Update docs and planning

[ahouseholder]

This pull request primarily updates documentation to clarify system architecture, improve codebase organization, and strengthen conventions for error handling and API design. It also adds new sections on case state authority and behavior tree composability, and completes several module refactoring tasks. The changes enhance maintainability, accuracy, and future extensibility of both the docs and the codebase.

Error handling and validation conventions:

• Added a new requirement that Optional[str] fields must reject empty strings, enforced via Pydantic validators and reflected in JSON Schema (minLength: 1). Reference to specs/code-style.md CS-08-001.

Codebase and module organization:

• Completed refactoring of handler modules: vultron/api/v2/backend/handlers/ now contains topic-based submodules, with stable re-exports from __init__.py. See plan/IMPLEMENTATION_PLAN.md Phase TECHDEBT-1.
• Completed refactoring of vocabulary examples: vultron/as_vocab/examples/ now contains topic-based submodules, with direct imports and removal of compatibility shim. See plan/IMPLEMENTATION_PLAN.md TECHDEBT-5, TECHDEBT-6.
• Added a section proposing future API layer reorganization to clarify the distinction between ActivityPub, backend, and example layers, moving away from version-based naming.

Case state authority and update path:

• Documented the canonical update path for case state, emphasizing that the CaseActor is the authoritative source and all updates must be authenticated and broadcast from it. Cross-references implementation plan and specs.
• Clarified that CaseActor must apply its own trusted timestamp to all state-changing events, not rely on participant-supplied timestamps, to ensure auditability and single-source-of-truth.

Behavior tree architecture and automation boundaries:

• Added explanation of behavior tree composability, supporting modular workflows and triggerable behaviors.
• Expanded documentation on fix development, clarifying its out-of-scope status for Vultron, future automation potential, and design decisions for placeholder nodes and callback hooks. Also detailed preconditions for parallel do-work behaviors and implementation focus for triggerable behaviors.

Documentation conventions and bug fixes:

• Fixed root logger configuration side effect in app.py by moving it to the lifespan context manager, improving test isolation.
• Added docstring and markdown compatibility guidelines for documentation generation.

Other minor changes include typo corrections, navigation updates, and expanded cross-references for clarity and completeness.

[Copilot]

Pull request overview

This PR updates Vultron’s documentation/specs and planning artifacts to clarify architectural guidance (notably triggerable behaviors and case-management semantics), while also completing the vocab_examples shim removal by updating imports across the API and tests.

Changes:

• Remove the vultron/scripts/vocab_examples.py compatibility shim and migrate internal imports/tests to vultron.as_vocab.examples.
• Add/expand specifications and design notes (triggerable behaviors, case-management refinements, code-style rules, tech-stack tooling).
• Refresh planning documents and agent prompts to reflect current priorities, completed refactors, and task-sizing guidance.

Reviewed changes

Copilot reviewed 41 out of 41 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
vultron/semantic_map.py	Update example import path to the new as_vocab.examples location.
vultron/scripts/vocab_examples.py	Remove the deprecated compatibility shim module.
vultron/api/v2/routers/examples.py	Update router imports to use vultron.as_vocab.examples.
vultron/api/v2/routers/datalayer.py	Update example initialization import path during datalayer reset.
vultron/api/v1/routers/reports.py	Update imports to use vultron.as_vocab.examples.
vultron/api/v1/routers/participants.py	Update imports to use vultron.as_vocab.examples and topic submodules.
vultron/api/v1/routers/examples.py	Update imports to use vultron.as_vocab.examples.
vultron/api/v1/routers/embargoes.py	Update imports to use vultron.as_vocab.examples.
vultron/api/v1/routers/cases.py	Update imports to use vultron.as_vocab.examples.
vultron/api/v1/routers/actors.py	Update imports to use vultron.as_vocab.examples.
test/as_vocab/test_vocab_examples.py	Update test imports to the new vultron.as_vocab.examples.vocab_examples path.
specs/triggerable-behaviors.md	Add a formal spec for trigger endpoints, payload/response expectations, and BT integration.
specs/tech-stack.md	Add code-quality tooling guidance (Black enforcement, gradual pyright adoption).
specs/project-documentation.md	Add task sizing guidance and documentation/process refinements.
specs/object-ids.md	Update sources and rationale references for object ID requirements.
specs/meta-specifications.md	Clarify file naming conventions across notes/specs/docs.
specs/encryption.md	Update spec “Source” reference to the new encryption notes location.
specs/embargo-policy.md	Update “Source” and related references to newer notes/spec context.
specs/demo-cli.md	Update “Source” reference to priorities doc.
specs/code-style.md	Add CS-08-001 requirement: Optional string fields must reject empty strings.
specs/case-management.md	Expand/clarify trusted timestamps, domain object model, redacted views, embargo acceptance tracking.
specs/README.md	Update spec index and implementation-status summary to reflect new/updated specs.
prompts/PLAN_prompt.md	Add “meaningful chunks” sizing guidance for plan updates.
prompts/LEARN_EXTRA_prompt.md	Add a new prompt for documentation refinement workflows.
plan/PRIORITIES.md	Add priority-numbering guidance and additional roadmap items.
plan/IMPLEMENTATION_PLAN.md	Refresh gap analysis, completed work status, and add new TECHDEBT items tied to new specs.
plan/IMPLEMENTATION_NOTES.md	Mark captured items, add notes aligned with updated specs/planning.
plan/IDEAS.md	Mark pyright idea as captured in specs.
plan/BUGS.md	Update logging-noise status and note PyCharm runner limitation.
notes/triggerable-behaviors.md	Add detailed design notes for triggerable behaviors and endpoint contracts.
notes/encryption.md	Add encryption implementation notes (key discovery, decryption placement, strategies).
notes/domain-model-separation.md	Add per-actor datalayer isolation options and DI guidance.
notes/do-work-behaviors.md	Clarify automation boundaries for fix development and add BT precondition discussion.
notes/codebase-structure.md	Add API-layer architecture guidance and mark refactors as completed; add docstring/markdown guidance.
notes/case-state-model.md	Clarify trusted timestamp principle for CaseActor state changes.
notes/bt-integration.md	Update handler path reference; add BT composability and fuzzer-node context.
notes/bt-fuzzer-nodes.md	Add a comprehensive catalog of simulator fuzzer nodes as external dependency touchpoints.
notes/activitystreams-semantics.md	Add CaseActor authoritativeness and canonical case update path notes.
notes/README.md	Update notes index to include new topics/files.
mkdocs.yml	Fix navigation label typo (“Propose” embargo behavior).
AGENTS.md	Add guidance on optional-string non-emptiness; update vocabulary examples location references.

[ahouseholder]

@copilot open a new pull request to apply changes based on the comments in this thread

[Copilot]

@ahouseholder I've opened a new pull request, #314, to work on those changes. Once the pull request is ready, I'll request review from you.