Merged
Conversation
All insights from plan/BT_INTEGRATION.md have been distributed: - plan/IMPLEMENTATION_NOTES.md: Populated with BT design decisions, rationale, translation strategy (simulation → prototype), actor isolation model, CaseActor architecture, concurrency model, open questions for Phase BT-2+, and resolved risk notes. - specs/behavior-tree-integration.md: Updated source reference from BT_INTEGRATION.md to ADR-0008; updated Related section to point to IMPLEMENTATION_NOTES.md instead of BT_INTEGRATION.md. - specs/README.md: Updated BT status from 'planned' to 'Phase BT-1 complete'; replaced BT_INTEGRATION.md reference with IMPLEMENTATION_NOTES.md. - specs/project-documentation.md: Replaced BT_INTEGRATION.md plan entry with archived status note documenting where insights moved. - plan/IMPLEMENTATION_PLAN.md: Updated two references from BT_INTEGRATION.md to appropriate current files. - plan/PRIORITIES.md: Updated to reflect Phase BT-1 complete and point to current planning documents. - plan/BT_INTEGRATION.md: Removed (insights distributed). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Expand cvd_bt.md with a full decomposition map of the behavior_logic section. The new Section Overview includes: - A Mermaid flowchart showing every sub-tree page and how it relates to the four top-level CVD BT tasks (A–D) - Narrative summaries for each major branch (Discover Vulnerability, Receive Messages, Report Management, Embargo Management) with links and brief descriptions of each sub-tree's role and the state transitions it drives Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Move sub-tree link lists directly into the (B), (C), (D) top-level bullet descriptions, eliminating the duplicate ### subsections - Remove the now-redundant standalone Do Work paragraph (covered under the expanded (C) bullet) - Fix the Section Overview Mermaid diagram by replacing markdown link syntax in node labels with plain text (links in Mermaid node labels are not rendered by the site renderer) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…and prioritize related activities
…clarity on project priorities and specifications
…ate README - Rewrite specs/agentic-readiness.md to proper spec format per meta-specifications.md style guide: add AR- requirement IDs, PROD_ONLY tags, remove duplicate requirements (cross-referenced instead), remove TODO list. Retains unique agentic concerns: OpenAPI discoverability, stable error_code, next_allowed_actions, CLI interface, job pattern, pagination, bulk ops, request correlation. - Fix HP prefix collision: handler-protocol.md and http-protocol.md both used HP-XX-XXX IDs, violating global uniqueness per meta-spec. Rename all IDs in http-protocol.md from HP- to HTTP-. Update cross-references in inbox-endpoint.md, message-validation.md, error-handling.md, and AGENTS.md. - Fix duplicate HP-07-001 in http-protocol.md: the FastAPI response serialization section re-used the HP-07-001 ID already assigned to rate limiting. Renumbered to HTTP-08-001 and improved the requirement to be more atomic (state what, not just how). - Remove advisory 'Consider: Merge...' note from observability.md. - Update specs/README.md: add missing files (agentic-readiness.md, outbox.md, prototype-shortcuts.md, project-documentation.md), add note clarifying HP- is Handler Protocol / HTTP- is http-protocol.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Update gap analysis summary to reflect Phase BT-1 complete status - Expand Phase BT-2 with specific prioritize_report BT tasks and decision guide for which handlers benefit from BT refactoring - Add Phase BT-3: initialize_case + manage_case demo (create_case BT, add_report_to_case, close_case handlers + demo script) - Add Phase BT-4: invite_actor + initialize_participant + manage_participants demo (invitation handlers, participant handlers, demo script) - Add Phase BT-5: establish_embargo + manage_embargo demo (embargo handlers, negotiation handlers, demo script) - Add Phase BT-6: status_updates + acknowledge demo (note/status handlers) - Add Phase BT-7: lower-priority suggest_actor + transfer_ownership demos - Update IMPLEMENTATION_NOTES.md with Phase BT-2+ strategy, BT handler complexity analysis table, embargo/case BT structure notes, demo script architecture pattern, and engage_case/defer_case semantic check guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Implements case prioritization for the receive-side of RmEngageCase (Join(VulnerabilityCase)) and RmDeferCase (Ignore(VulnerabilityCase)). Key design insight: RM is participant-specific. Each CaseParticipant carries its own RM state in participant_status[].rm_state. ReportStatus in the flat status layer is only used for reports not yet associated with a case. Changes: - enums.py: Add ENGAGE_CASE and DEFER_CASE to MessageSemantics - activity_patterns.py: Add EngageCase (Join) and DeferCase (Ignore) patterns - semantic_map.py: Register new patterns - semantic_handler_map.py: Register new handlers - behaviors/report/policy.py: Add PrioritizationPolicy and AlwaysPrioritizePolicy (hook point for future SSVC integration per PROTO-05-001) - behaviors/report/nodes.py: Add CheckParticipantExists, TransitionParticipantRMtoAccepted, TransitionParticipantRMtoDeferred, EvaluateCasePriority (stub for outgoing-direction decisions) - behaviors/report/prioritize_tree.py: New file with create_engage_case_tree and create_defer_case_tree factories - api/v2/backend/handlers.py: Add engage_case and defer_case handlers - specs/prototype-shortcuts.md: Add PROTO-05-001 documenting SSVC deferral and ReportStatus vs CaseParticipant.participant_status distinction - test/behaviors/report/test_prioritize_tree.py: 11 tests (structure, success, failure, participant isolation) - plan/: Update IMPLEMENTATION_PLAN.md and IMPLEMENTATION_NOTES.md Full test suite: 472 passed, 2 xfailed (pre-existing) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace ambiguous 'uv run pytest -q' with the canonical one-shot command: uv run pytest --tb=short 2>&1 | tail -5 Key rules added: - Run full test suite ONCE per validation cycle; read tail -5 directly - Do NOT re-run pytest to grep for counts - Ordered workflow: black → pytest → git add -A && git commit Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ctions
The default .markdownlint-cli2.yaml ignores AGENTS.md and specs/**. Local
config discovery means --config alone cannot bypass the ignores block.
Fix: add strict.markdownlint-cli2.yaml (same rules, no ignores) and run
markdownlint from /tmp to avoid local config discovery:
cd /tmp && markdownlint-cli2 \
--config /path/to/strict.markdownlint-cli2.yaml \
/path/to/AGENTS.md "/path/to/specs/**/*.md" --fix
Updated AGENTS.md:
- Miscellaneous tips: replace broken command with correct two-command pattern
- Markdown formatting section: cross-reference to Miscellaneous tips
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- AGENTS.md: add Protocol Activity Model section explaining that activities are state-change notifications, not commands; include inReplyTo guidance for response activities - specs/handler-protocol.md: add HP-00 Protocol Semantics section with requirements for state update obligations (HP-00-001, HP-00-002) - specs/behavior-tree-integration.md: update status to reflect Phase BT-2.1 completion (engage_case/defer_case handlers) Rationale: Critical conceptual model from IMPLEMENTATION_NOTES.md was not captured in AGENTS.md or specs. Agents implementing handlers need to understand that inbound activities are assertions about sender state, not commands. BT spec status updated to reflect current implementation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Create notes/ directory with README.md for durable, version-controlled
design insights (replacing reliance on ephemeral IMPLEMENTATION_NOTES.md)
- Add notes/bt-integration.md: BT design decisions, simulation-to-prototype
strategy, per-handler BT value table, concurrency model, performance
baseline, and open architecture questions
- Add notes/activitystreams-semantics.md: activity-as-notification model,
inReplyTo conventions, rehydration guidance
- Update AGENTS.md:
- Clarify that plan/IMPLEMENTATION_NOTES.md is ephemeral; direct agents
to notes/ for durable insights
- Update Last Updated date to 2026-02-20
- Add expected xfails note (2 deprecated _old_handlers tests)
- Add prioritize_tree.py to Key Files Map
- Add specs/idempotency.md to Key Specifications
- Add Health Check Readiness Gap pitfall (/health/ready gap vs OB-05-002)
- Point BT and ActivityStreams references to notes/ files
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…d and LEARN_prompt.md
…s and design insights guidelines
…s and lessons learned
…tes/specs/AGENTS - notes/bt-integration.md: add EvaluateCasePriority outgoing-only section (receive-side trees record sender state; policy eval is outgoing only) - specs/behavior-tree-integration.md: update BT-06-001 with decision criteria and notes cross-reference; update Implementation section for BT-2.1 (engage_case/defer_case trees, updated test counts); redirect Related section from ephemeral IMPLEMENTATION_NOTES to durable notes/bt-integration.md - AGENTS.md: add EvaluateCasePriority outgoing-only tip in BT guidance section Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… is where, how it relates to the current implementation, etc.
…guidance - AGENTS.md: remove all references to ephemeral plan/IMPLEMENTATION_NOTES.md; durable context now lives in notes/ and is self-contained in each pitfall - AGENTS.md: replace flat 17-line Key Specifications list with a concise categorized pointer to specs/README.md (reduces redundancy) - AGENTS.md: remove redundant 'Running demo server' section (already in quickstart); remove duplicate Key Specifications list from Specification Usage Guidance - AGENTS.md: fix hardcoded absolute path in markdownlint tip to use $(git rev-parse --show-toplevel) - AGENTS.md: add Vocabulary Examples and Case States entries to Key Files Map - notes/activitystreams-semantics.md: add section on vocab_examples.py as canonical implementation reference for activity structures and semantics - notes/README.md: update topics column for activitystreams-semantics.md - specs/dispatch-routing.md: fix implementation paths (vultron/api/v2/backend/behavior_dispatcher.py -> vultron/behavior_dispatcher.py; same for semantic_handler_map.py) - specs/README.md: update status summary to reflect BT-2.1 completion; remove reference to ephemeral IMPLEMENTATION_NOTES.md - specs/agentic-readiness.md: tag AR-08 CLI requirements as PROD_ONLY (these are Priority 1000 / not yet implemented) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…referenced from AGENTS.md Future agents updating AGENTS.md should pull durable content from notes/, not from plan/IMPLEMENTATION_NOTES.md which is periodically wiped. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… model, codebase structure, and documentation strategy
…n to case-state-model.md Squashed commits: [3dac8a4] docs: add participant-specific vs. participant-agnostic states section to case-state-model.md [af9afbb] docs: expand IMPLEMENTATION_NOTES.md with details on participant-specific and participant-agnostic states
… PROD_ONLY tag usage
…ation notes - agentic-readiness.md: Remove AR-07-001 (duplicate of http-protocol HTTP-05-001); move AR-03-002 (Retry-After) to http-protocol.md; add PROD_ONLY to AR-02-001, AR-02-003, AR-04-001, AR-04-002, AR-06-001; align error_code -> error field references to match EH-05-001; rename section 'Stable Error Codes' -> 'Stable Error Types'; trim verbose verification section - http-protocol.md: Add HTTP-07-004 (Retry-After for transient errors, moved from agentic-readiness); trim code blocks from verification section; update Consolidates header to include agentic-readiness.md - handler-protocol.md: Remove Implementation Notes code blocks (implementation guidance belongs in AGENTS.md, not specs) - testability.md: Remove 'Test Data Quality Examples' code blocks (already in AGENTS.md under 'Test Data Quality') - structured-logging.md: Remove 'Implementation Example' section with JSON/Python code (implementation guidance, not specification) - README.md: Update consolidation note to include agentic-readiness.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…incorporate new insights
Adds a 'Technical debt (housekeeping)' section with prioritized maintenance tasks derived from specs/notes/plan. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- AGENTS.md: add acknowledge_demo, manage_case_demo, initialize_participant_demo to Key Files Map - manage_case.md: replace outdated RmReEngageCase/as:Undo tip with correct guidance (re-engage via RmEngageCase/as:Join) - notes/activitystreams-semantics.md: add permanent section documenting re-engagement design decision - IMPLEMENTATION_PLAN.md: update status summary (38 handlers, 10 demos); remove resolved BT-8 phase; refresh gap analysis - IMPLEMENTATION_HISTORY.md: add Phase BT-8 and DEMO-3.1-3.9 completion entries - IMPLEMENTATION_NOTES.md: remove promoted insights; update demo script gap summary Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Implements the manage_embargo workflow demo covering: - Activate-and-terminate path: propose → accept → activate → remove - Reject-and-repropose path: propose → reject → repropose → accept → activate Adds: - vultron/scripts/manage_embargo_demo.py - test/scripts/test_manage_embargo_demo.py - manage-embargo-demo service in docker/docker-compose.yml - manage-embargo-demo target in docker/Dockerfile Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…field
DEMO-3.13: Create vultron/scripts/manage_participants_demo.py
- Full invite→accept→create_participant→add_to_case→create_status→
add_status→remove_participant cycle
- Reject path demonstrating invitation refusal
DEMO-3.14: Add test/scripts/test_manage_participants_demo.py
DEMO-3.15: Add manage-participants-demo Dockerfile target and
docker-compose.yml service
Fix: RemoveParticipantFromCase.origin → target to align with the
REMOVE_CASE_PARTICIPANT_FROM_CASE activity pattern (which matches on
target_=VULNERABILITY_CASE) and the existing handler implementation.
Update handler docstring and corresponding handler tests accordingly.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
ahouseholder
added
content/semantic
Contributor
There was a problem hiding this comment.
Pull request overview
This PR completes the implementation of individual demo scripts corresponding to the ActivityPub workflow documentation, finalizing the behavior tree integration phase. The changes include new demo services, documentation updates for workflow clarity, and improvements to configuration and data models.
Changes:
- Added 10+ new demo services (initialize-case, establish-embargo, invite-actor, status-updates, suggest-actor, transfer-ownership, acknowledge, manage-case, initialize-participant, manage-embargo, manage-participants) with corresponding Dockerfile targets and docker-compose configurations
- Enhanced documentation diagrams and workflow descriptions to clarify ActivityStreams semantics (Accept/Reject of Offers/Invites, re-engagement patterns)
- Expanded behavior tree and case management logic with new enums, nodes, trees, and policy classes for case prioritization and creation
- Updated specs and configuration files to improve consistency and structure
Reviewed changes
Copilot reviewed 99 out of 108 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
vultron/enums.py |
Added UPDATE_CASE, ENGAGE_CASE, DEFER_CASE message semantics |
vultron/behaviors/report/prioritize_tree.py |
New BT trees for engage_case and defer_case workflows |
vultron/behaviors/report/policy.py |
Added PrioritizationPolicy and AlwaysPrioritizePolicy classes |
vultron/behaviors/report/nodes.py |
Added case prioritization nodes (CheckParticipantExists, TransitionParticipantRMtoAccepted/Deferred, EvaluateCasePriority) |
vultron/behaviors/case/nodes.py |
New case management BT nodes for create_case workflow |
vultron/behaviors/case/create_tree.py |
BT composition for create_case workflow |
vultron/behaviors/case/__init__.py |
Package initialization for case behavior trees |
vultron/as_vocab/objects/vulnerability_case.py |
Added notes field and current_status property; fixed set_embargo to use current_status |
vultron/as_vocab/objects/case_status.py |
Removed actor field from ParticipantStatus; changed to attributed_to |
vultron/as_vocab/objects/case_participant.py |
Replaced actor field with attributed_to throughout |
vultron/as_vocab/activities/embargo.py |
Fixed EmAcceptEmbargo/EmRejectEmbargo to reference EmProposeEmbargo as object |
vultron/as_vocab/activities/case_participant.py |
Added set_name validator to CreateParticipant for clearer activity names |
vultron/as_vocab/activities/case.py |
Fixed Accept/RejectCaseOwnershipTransfer and RmAcceptInviteToCase to reference Offer/Invite as object |
vultron/as_vocab/activities/actor.py |
Fixed AcceptActorRecommendation/RejectActorRecommendation to reference RecommendActor offer as object |
vultron/activity_patterns.py |
Updated embargo and case patterns; added UpdateCase, EngageCase, DeferCase patterns |
test/scripts/test_*.py |
New test files for all demo scripts |
test/behaviors/case/test_create_tree.py |
Tests for create_case BT |
test/as_vocab/test_vulnerability_case.py |
Tests for VulnerabilityCase including set_embargo fix |
test/as_vocab/test_vocab_examples.py |
Updated tests to reflect attributed_to changes and Accept/Reject object field corrections |
test/as_vocab/test_actvitities/test_actor.py |
Updated tests for Accept/RejectActorRecommendation |
test/as_vocab/test_actvitities/test_activities.py |
New tests for CreateParticipant name generation |
test/api/test_reporting_workflow.py |
Removed deprecated mock-based tests; updated to use handlers directly |
test/AGENTS.md |
New test-specific agent guidance (ONE RUN RULE for pytest) |
strict.markdownlint-cli2.yaml |
New strict config for linting excluded files |
specs/*.md |
Multiple spec updates for consistency, clarity, and new requirements |
prompts/*.md |
Updated prompt templates for agent workflows |
plan/*.md |
Updated planning documents (PRIORITIES, IMPLEMENTATION_NOTES, IMPLEMENTATION_HISTORY, IDEATION) |
notes/*.md |
New durable design insights (domain-model-separation, documentation-strategy, codebase-structure, activitystreams-semantics, README) |
docs/topics/behavior_logic/cvd_bt.md |
Expanded with sub-behavior breakdown and mermaid diagram |
docs/howto/activitypub/activities/*.md |
Clarified workflow diagrams (transfer_ownership, suggest_actor, manage_case, invite_actor) |
docker/docker-compose.yml |
Added 10+ new demo service definitions |
docker/README.md |
Updated to describe new demo services |
docker/Dockerfile |
Added 10+ new demo targets |
.markdownlint-cli2.yaml |
Re-enabled linting for plan/ and prompts/ directories |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Contributor
|
@ahouseholder I've opened a new pull request, #304, to work on those changes. Once the pull request is ready, I'll request review from you. |
…o api-bt-demo-2 # Conflicts: # .markdownlint-cli2.yaml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR finishes out the individual demo scripts that correspond to the Activities (workflows) listed in the Vultron documentation site.
Future work not addressed here:
Create(Note)activities for thisCopilot Summary
This pull request introduces several new demo services and updates documentation to reflect these additions, while also making improvements to documentation and configuration. The main focus is on expanding the suite of demo workflows available in the Docker Compose setup, clarifying workflow descriptions, and improving ActivityPub activity diagrams and documentation structure.
Demo Services Expansion:
initialize-case-demo,establish-embargo-demo,invite-actor-demo, etc.), each corresponding to a specific workflow and backed by a dedicated Dockerfile target and script. This allows for more granular demonstration and testing of individual workflows. [1] [2]docker/README.mdto describe the new demo services, clarify how to run them, and explain the workflow each demo represents.Documentation Improvements:
object=Invite/object=Offerrather than referencing the case directly. This aligns the diagrams with protocol semantics. [1] [2] [3] [4]RmEngageCaseactivity is used for re-engagement rather than introducing a new activity.notes/README.mdto establish a durable location for design insights and implementation notes, distinguishing it from the ephemeralplan/IMPLEMENTATION_NOTES.md.Configuration Adjustments:
.markdownlint-cli2.yamlto remove theplan/**andprompts/**directories from the ignore list to re-enable linting for these folders.