contextcompass 2.15.0__py3-none-any.whl

contextcompass_cli/_package/examples/researcher_task_flow.md

@@ -0,0 +1,23 @@
+# Example: researcher task flow
+
+Scenario
+- Validate historical/legal details for a courtroom thriller arc.
+
+Workflow
+1. Intake
+- define research questions and confidence requirements.
+
+2. Evidence collection
+- gather sources and contradictions.
+
+3. Constraint synthesis
+- convert findings into writing-safe constraints.
+
+4. Handoff
+- publish confidence map and unresolved unknowns.
+
+Expected outputs
+- `research_questions.md`
+- `source_log.md`
+- `confidence_map.md`
+- `plausibility_constraints.md`

contextcompass_cli/_package/examples/security_review_flow.md

@@ -0,0 +1,24 @@
+# Example: security_engineer review flow
+
+Scenario
+- Review a change touching onboarding and automation guidance.
+
+Workflow
+1. Scope trust boundaries
+- identify where user input can influence commands.
+
+2. Threat review
+- misuse of elevated commands
+- accidental secret leakage in artifacts
+
+3. Mitigation checks
+- ensure escalation requires explicit approval
+- ensure docs ban secret logging
+
+4. Residual risk report
+- list accepted and unaccepted risks
+
+Expected outputs
+- threat summary
+- mitigation checklist
+- residual risk decisions

contextcompass_cli/_package/examples/story_designer_task_flow.md

@@ -0,0 +1,23 @@
+# Example: story_designer task flow
+
+Scenario
+- Build architecture for a mystery novel with dual timelines.
+
+Workflow
+1. Intake
+- lock premise, POV constraints, and audience profile.
+
+2. Architecture pass
+- produce story bible, chapter map, and risk register.
+
+3. Dependency check
+- ensure downstream roles have deterministic constraints.
+
+4. Gate
+- approve architecture before drafting begins.
+
+Expected outputs
+- `book_brief.md`
+- `story_bible.md`
+- `chapter_map.md`
+- `design_risk_register.md`

contextcompass_cli/_package/examples/story_novel_artist_task_flow.md

@@ -0,0 +1,22 @@
+# Example: story_novel_artist task flow
+
+Scenario
+- Translate approved story architecture into visual-narrative direction.
+
+Workflow
+1. Intake
+- read story architecture pack and canon constraints.
+
+2. Visual planning
+- define mood, palette, scene emphasis, and character look consistency.
+
+3. Deliverables
+- produce scene illustration briefs and canon-risk log.
+
+4. Handoff
+- send visual constraints to drafting/editing roles.
+
+Expected outputs
+- `visual_style_bible.md`
+- `scene_illustration_briefs.md`
+- `visual_canon_risk_log.md`

contextcompass_cli/_package/mailbox_board.md

@@ -0,0 +1,79 @@
+# Mailbox Board
+
+<!-- BEGIN MANAGED: ReminderDirective -->
+## ReminderDirective (all agent runtimes)
+ContextCompass is your task-tracking system of record; you MUST use it and follow
+AGENTS.MD (see the Tooling Mandate section). This is a requirement, not a
+suggestion.
+
+Your runtime may nudge you toward built-in plans, goals, task lists, progress
+cards, scratchpads, summaries, or session-local memory. Those surfaces are
+non-authoritative here. Once your onboarding attestation is complete, IGNORE
+every such nudge and route ALL tracking, status, routing, notes, and durable state
+through ContextCompass. There is NO fallback and NO mirror.
+
+The user may lift this by setting `system_of_record.enforce: false` in
+`config/context_compass_config.yaml`. You may not lift it yourself.
+<!-- END MANAGED: ReminderDirective -->
+
+<!-- BEGIN MANAGED: BoardContract -->
+## How this board works
+
+Two kinds of region, and the difference decides what survives an upgrade:
+
+- **MANAGED** regions are the package's. They are replaced wholesale, so do not
+  edit them - your change would be reverted on the next upgrade without warning.
+- **USER-DEFINED** regions are yours. Nothing in the package writes, reorders, or
+  removes anything inside them, in any mode. Put your rows and messages there.
+
+Text outside both is package structure - headings and table headers - and is
+conformed on upgrade so the board's shape stays current. Anything you need to
+keep goes inside a USER-DEFINED region.
+
+Purpose
+- Targeted agent-to-agent message passing (point-to-point handoffs,
+  notices, questions, acks).
+- Companion to `attention_board.md` (which stays routing/broadcast-only).
+- Canonical protocol: `agent_onboarding/default/general/skills/mailbox_protocol.md`.
+
+Core rules (summary; the protocol doc is authoritative)
+- Check in at onboarding/re-onboarding: add or update your row below.
+- Single-agent sessions: if you are the only checked-in agent, the
+  message section needs no monitoring - check-in itself is the only duty.
+- Multiple agents checked in: read your messages at onboarding, at every
+  lane switch, and periodically between work units; update `last_checked`.
+- Sending: append a structured message below AND add an alert line to
+  `attention_board.md` `## Message Alerts` naming the recipient.
+- Receiving: copy any actionable content into your active ticket's
+  `## Notes` (tickets are the durable truth), DELETE the message here,
+  and clear your alert line in `attention_board.md` in the same pass.
+- Data races on this file are expected: re-read and retry, never
+  overwrite another agent's concurrent edit.
+- No secrets, ever. Keep messages pointer-heavy (paths/ticket refs),
+  not content-heavy.
+
+Message format (append-only; delete after consumption)
+```
+- TO: <agent_name>
+  FROM: <agent_name>
+  DATETIME: <ISO-8601 UTC>
+  TYPE: HANDOFF | NOTICE | QUESTION | ACK
+  CLAIM: <one to five lines; what the recipient needs to know or do>
+  EVIDENCE: <path:start-end or ticket path; required for HANDOFF/NOTICE>
+  ACK_REQUESTED: true | false
+```
+<!-- END MANAGED: BoardContract -->
+
+## Checked-In Agents
+| agent_name | owner | checked_in_at | last_checked | status |
+| --- | --- | --- | --- | --- |
+<!-- BEGIN USER-DEFINED: checked_in -->
+<!-- END USER-DEFINED: checked_in -->
+
+## Messages
+<!-- BEGIN USER-DEFINED: messages -->
+<!-- END USER-DEFINED: messages -->
+
+## Notes
+<!-- BEGIN USER-DEFINED: notes -->
+<!-- END USER-DEFINED: notes -->

contextcompass_cli/_package/special_instructions/README.md

@@ -0,0 +1,16 @@
+# Special Instructions
+
+Purpose
+- Users can place project-specific instruction documents in this folder.
+- Agents must read and follow every Markdown document in `context_compass/special_instructions/`.
+
+Rules
+- Use relative repo paths only.
+- Keep project-specific instructions here instead of embedding them directly in `AGENTS.MD` when possible.
+
+Registration
+- Documents here are picked up by a directory sweep, not by a named entry in a
+  `SKILLS.MD` readset. Adding a file here is enough; nothing needs to be
+  registered, and an unreferenced file in this folder is not an orphan.
+- That is deliberate: project instructions are the user's to add, and requiring
+  a registry edit would make the package own something it should not.

contextcompass_cli/_package/system_docs/patches/active/README.md

@@ -0,0 +1,25 @@
+# Active Patch Lane
+
+Purpose
+- Hold temporary patch artifacts for the current implementation lane.
+- Keep patch docs separate from canonical `system_docs/src_*` docs until merge.
+
+Usage
+1) Copy `_template_patch_id/` to a new patch folder:
+   - `system_docs/patches/active/<patch_id>/`
+2) Fill in:
+   - `architecture_patch.md`
+   - `component_patch_<component>.md` (one per changed component)
+   - `code_description_patch_<component>.md` (conditional)
+3) Link artifacts in active ticket `Artifact Links`.
+4) Validate artifacts manually:
+   - verify required patch files exist for the patch id,
+   - verify artifact links are present in active ticket `Artifact Links`,
+   - verify patch contracts and ticket notes are consistent.
+5) On closure:
+   - merge durable deltas into canonical docs,
+   - remove temporary patch folder unless explicit retention is approved.
+
+Notes
+- Patch artifacts are temporary by default.
+- Ticket state remains the canonical execution tracker.

contextcompass_cli/_package/system_docs/patches/active/_template_patch_id/architecture_patch.md

@@ -0,0 +1,53 @@
+# architecture_patch
+
+## Metadata
+- Patch ID: <patch_id>
+- Status: draft
+- Owner: <owner>
+- Created: <YYYY-MM-DDTHH:MM:SSZ>
+- Updated: <YYYY-MM-DDTHH:MM:SSZ>
+
+## Patch Scope and Non-Goals
+- Objective:
+- Non-goals:
+
+## Changed-Components Matrix
+| component | change_type | rationale | depends_on |
+|---|---|---|---|
+| <component_name> | modify/add/remove | <why> | <component_or_none> |
+
+## Interface and Boundary Deltas
+- Boundary delta 1:
+- Interface delta 1:
+
+## Cross-Component Invariants
+- Invariant 1:
+- Invariant 2:
+
+## Migration and Rollout Order
+1. Step 1
+2. Step 2
+3. Step 3
+
+## Rollback Strategy
+- Rollback trigger:
+- Rollback steps:
+- Post-rollback verification:
+
+## Validation Expectations and Evidence Plan
+- Validation item 1:
+- Evidence source 1:
+
+## Ticket Coverage Map
+- Epic:
+- Story:
+- Tasks:
+
+## Unknowns and Decision Requests
+- UNKNOWN:
+- DECISION_REQUEST:
+
+## Context / Handoff Summary
+- What changed:
+- What remains:
+- Next entrypoint:

contextcompass_cli/_package/system_docs/patches/active/_template_patch_id/code_description_patch_TEMPLATE_COMPONENT.md

@@ -0,0 +1,39 @@
+# code_description_patch_TEMPLATE_COMPONENT
+
+## Metadata
+- Patch ID: <patch_id>
+- Component: <component_name>
+- Status: draft
+- Owner: <owner>
+- Created: <YYYY-MM-DDTHH:MM:SSZ>
+- Updated: <YYYY-MM-DDTHH:MM:SSZ>
+
+## Trigger Justification
+- Why this artifact is required for this component:
+
+## Control-Flow Description (Pseudocode Level)
+1. Step 1
+2. Step 2
+3. Step 3
+
+## Edge/Error and Rollback Semantics
+- Edge case 1:
+- Error behavior 1:
+- Rollback behavior:
+
+## Invariants and Idempotency Expectations
+- Invariant 1:
+- Idempotency condition 1:
+
+## Explicit Non-Goals
+- Non-goal 1:
+- Non-goal 2:
+
+## Validation Focus Points
+- Validation item 1:
+- Validation item 2:
+
+## Context / Handoff Summary
+- What changed:
+- Remaining unknowns:
+- Next entrypoint:

contextcompass_cli/_package/system_docs/patches/active/_template_patch_id/component_patch_TEMPLATE_COMPONENT.md

@@ -0,0 +1,48 @@
+# component_patch_TEMPLATE_COMPONENT
+
+## Metadata
+- Patch ID: <patch_id>
+- Component: <component_name>
+- Status: draft
+- Owner: <owner>
+- Created: <YYYY-MM-DDTHH:MM:SSZ>
+- Updated: <YYYY-MM-DDTHH:MM:SSZ>
+
+## Component Purpose and Boundary
+- Current boundary:
+- Target boundary:
+
+## Before/After Behavior Summary
+- Before:
+- After:
+
+## Interface Deltas
+- Inputs:
+- Outputs:
+- Error semantics:
+
+## State and Lifecycle Deltas
+- Owned state changes:
+- Lifecycle/cleanup changes:
+
+## Failure Mode Deltas
+- New failure mode:
+- Removed failure mode:
+- Changed failure mode:
+
+## Dependency and Ordering Constraints
+1. Constraint 1
+2. Constraint 2
+
+## Validation Expectations
+- Test/validation item 1:
+- Evidence target 1:
+
+## Unknowns and Open Decisions
+- UNKNOWN:
+- DECISION_REQUEST:
+
+## Context / Handoff Summary
+- What changed:
+- Remaining risks:
+- Next entrypoint:

contextcompass_cli/_package/system_docs/system_docs_read_first.md

@@ -0,0 +1,107 @@
+# System Docs Read First
+
+## Purpose
+This note explains how to approach `system_docs/` in a fresh Context Compass
+install.
+
+Context Compass ships example context maps and example workflows. It does not
+assume that your repository already has a real architecture map, component
+map, test map, or graph-details map.
+
+## Default Truth
+- `examples/` contains reference examples that show the expected shape and
+  depth of documentation. That is where the quality bar lives.
+- **`system_docs/` ships EMPTY.** No architecture, component, test or graph
+  document is seeded. A placeholder sitting in a live lane gets read as
+  repository truth no matter what banner is on it, so the package does not put
+  one there.
+- Everything in this directory is yours. Nothing here is replaced on upgrade.
+- Missing repo-specific context maps are not a defect in a fresh install.
+- Users should be encouraged to build context maps for their own repository as
+  real structure emerges.
+
+## Read Order
+The four context maps are two mirrored pairs: a source map and its test map at
+each of the architecture and component levels. Read each pair together - the
+test map uses the same section contract as its source map, so reading them apart
+hides the thing that makes them useful.
+
+**These are the EXAMPLE documents, and reading them whole is correct.** They are
+small and you are reading them to learn a shape. Do not carry that habit across to
+the live documents in this directory: once your repository has real maps, only
+`src_architecture.md` and the two indexes are read whole, and `src_components.md`
+and `src_graph.md` are entered through their indexes and sliced. That split is
+defined in `agent_onboarding/default/engineer/SKILLS.MD`, and it is the difference
+between a 200-line orientation and a 33,000-line one.
+
+1. `examples/example_architecture/src_architecture.md`
+   Read this to see what a strong repo-specific architecture map should look
+   like.
+2. `examples/example_architecture/tests_architecture.md`
+   Read this to see the test-side mirror of the architecture map.
+3. `examples/example_components/src_components.md`
+   Read this to see what a strong repo-specific component map should look like.
+4. `examples/example_components/tests_components.md`
+   Read this to see the test-side mirror of the component map.
+5. `agent_onboarding/default/engineer/skills/src_graph_usage.md`
+   Read this if graph-details workflow is needed.
+6. `examples/example_graph_details/src_graph.md`
+   Read this to see the readable graph format.
+7. `examples/example_epics/2026-02-19_context_compass_release_readiness_example_pack_epic.md`
+   Read this for example ticket structure.
+8. `examples/example_stories/2026-02-19_context_compass_release_readiness_examples_story.md`
+   Read this for example story structure.
+9. `examples/example_tasks/2026-02-19_context_compass_release_readiness_pack_task.md`
+   Read this for example task structure.
+10. `examples/example_completed/2026-02-19_context_compass_release_overview_artifact.md`
+    Read this for example completed-output structure.
+
+## What To Do In A New Library
+If the library is new and there is little or no repo-specific context yet:
+
+- do not pretend a real architecture map already exists
+- do not invent fake runtime truth just to fill `system_docs/`
+- use the example docs as templates and quality bars
+- create repo-specific context maps only when there is enough real structure to
+  document
+
+## Recommended First Context Maps
+When the repository is ready, build these in order:
+
+1. `system_docs/src_architecture.md` **and `src_architecture_index.md`**
+   Create this when the system boundary, entrypoints, and major flows are
+   understood.
+2. `system_docs/src_components.md` **and `src_components_index.md`**
+   Create this when concrete modules, ownership seams, and responsibilities are
+   understood.
+3. `system_docs/tests_architecture.md` and `tests_architecture_index.md`
+   Create this when the test model and validation layers are real enough to map.
+4. `system_docs/tests_components.md` and `tests_components_index.md`
+   Create this when test surfaces, helpers, and fixtures need explicit
+   ownership mapping.
+5. `system_docs/src_graph_index.md` and `system_docs/src_graph.md`
+   Create these only if graph-details workflow is actually needed for the repo.
+
+**Every authored document gets its index in the same pass.** An index is not an
+optional extra you add later when the document gets big - it is how the document
+is meant to be entered, and roles read it as baseline orientation.
+`src_architecture_index.md` and `src_components_index.md` in particular are what
+let an agent onboard holding the maps without loading the territory: an
+architecture narrative plus two indexes is a few thousand lines, while the
+documents they point into run to tens of thousands.
+
+An authored document shipped without its index is half-built. Regenerate the
+index every time you edit the document - an index that lags still returns line
+numbers, they are simply the wrong ones.
+
+## Live Execution Note
+- `attention_board.md` and `tickets/` are live coordination surfaces.
+- In a fresh install they may be sparse, empty, or starter-only.
+- Historical examples belong in `examples/`, not in live `tickets/*/completed/`
+  lanes.
+
+## Use
+- Start here when `system_docs/` has little or no repo-specific content.
+- Treat `examples/` as the model pack.
+- Encourage the user to build real context maps rather than relying on empty
+  placeholders.

contextcompass_cli/_package/templates/epic_template.md

@@ -0,0 +1,149 @@
+
+
+# Epic: <short, outcome-focused title>
+
+## Metadata
+- Epic ID: EPIC-YYYY-MM-DD-<slug>
+- Status: draft | ready | in_progress | blocked | done
+- Owner:
+- Agent Name: <one or more assigned names, comma-separated>
+- Priority: p0 | p1 | p2 | p3
+- Created: YYYY-MM-DDTHH:MM:SSZ
+- Updated: YYYY-MM-DDTHH:MM:SSZ
+- Target Window: <e.g., 2026-Q1>
+- Related Program/Initiative:
+
+## Problem / Opportunity
+<Describe the problem or opportunity with concrete evidence and context.>
+
+## MRP Alignment (Most Reasonable Product)
+<Explain the holistic core being built and why this is the right long-term foundation.>
+
+## Ticket Contract
+- ENTRY_GATE: <program lane is routed and prerequisite story set is defined>
+- EXECUTION_BOUNDARY: <epic-level scope and explicit exclusions>
+- DEPENDENCIES: <required stories, policies, and architecture anchors>
+- EXIT_GATE: <all required stories accepted + board/closure sync complete>
+- FAILURE_ESCALATION: <when to raise DECISION_REQUEST/CONFLICT/BLOCKER>
+
+## Goals (Outcomes)
+- 
+
+## Non-Goals (Explicit Exclusions)
+- 
+
+## Scope Boundaries
+- In scope:
+- Out of scope:
+
+## State Transition Event
+- from_state: draft | ready | in_progress | blocked | review
+- to_state: ready | in_progress | blocked | review | done
+- transition_reason: <why this transition is valid now>
+
+## Success Metrics
+- 
+
+## Requirements (Functional + Non-Functional)
+- 
+
+## Constraints / Assumptions
+- 
+
+## Dependencies / External References
+- 
+
+## Milestones (Track Progress)
+- [ ] Milestone 1: <name> - <clear success criteria>
+- [ ] Milestone 2: <name> - <clear success criteria>
+
+## Stories (Required to Complete)
+- [ ] Story: <STORY-ID> - <short description>
+- [ ] Story: <STORY-ID> - <short description>
+
+## Tasks (Cross-Cutting or Epic-Level)
+- [ ] Task: Complete story <STORY-ID>
+- [ ] Task: Complete story <STORY-ID>
+- [ ] Task: <cross-cutting task>
+- [ ] Task: Verify Ticket Microcycle enforcement across active tickets/stories/tasks.
+
+## Acceptance Criteria (Epic Done)
+- 
+
+## Risks / Mitigations
+- 
+
+## Applicable Anti-Patterns
+- [ ] No epic-state transition without story-level evidence.
+- [ ] No closure while required stories are incomplete or unaccepted.
+- [ ] No program claims without source evidence from story/task notes.
+
+## Validation / Test Approach
+- 
+
+## Rollout / Adoption Plan
+- 
+
+## Open Questions
+- 
+
+## Decision Log
+- 
+
+## Artifact Links (Optional)
+- ARTIFACTS_REQUIRED: true | false
+- ARTIFACT_PATHS:
+  - <artifacts/YYYY-MM-DD_<slug>.<ext>>
+- DISPOSITION: delete_on_close | retain_as_reference | promote_to_documentation
+- CLEANUP_TRIGGER: <when artifact cleanup/retention decision is applied>
+
+## Context Management
+- CONTEXT_MANAGEMENT_REQUIRED: true | false
+- CONTEXT_IDS:
+  - CTX-YYYY-MM-DD-<slug> | UNKNOWN
+- CONTEXT_TOPICS:
+  - <topic or question> | UNKNOWN
+- IF_UNKNOWN: UNKNOWN | ask user before implementation | none
+
+## Notes
+- DATETIME: YYYY-MM-DDTHH:MM:SSZ
+  TYPE:
+    FACT | UNKNOWN | HYPOTHESIS | DECISION | DECISION_REQUEST | PLAN |
+    STRATEGY_DISCUSSION | ASSUMPTION_CHALLENGE | CONFLICT | TRADEOFF |
+    BLOCKER | ALIGNMENT_CHECK | MEASURE | RISK | RAISE
+  CLAIM: <short finding>
+  EVIDENCE:
+  - <path:start_line-end_line>
+  - <path:start_line-end_line>
+  IMPACT: <why this matters>
+  NEXT: <one concrete next action>
+  REREAD: REQUIRED | HELPFUL
+  SCORE_0_TO_10: <0-10 compaction usefulness>
+
+## Closure Confirmation
+- [ ] Work walkthrough shared with user
+- [ ] Acceptance criteria confirmed by user
+- [ ] Applicable anti-pattern checks are clear or escalated with evidence.
+
+## Noting Behavior
+- Note focus: program-level direction, cross-story tradeoffs, and tranche order.
+- Add notes when priorities, sequencing, or scope boundaries change.
+- Reference story/task evidence instead of duplicating tactical execution logs.
+- Keep notes append-only and preserve UNKNOWN-first promotion discipline.
+
+## Context / Handoff Summary
+<Succinct summary of current state, key decisions, and next steps for future context.>
+
+## Project-Specific Additions
+<!-- BEGIN USER-DEFINED: project_fields -->
+<!-- END USER-DEFINED: project_fields -->
+
+<!--
+Anything this project needs on every ticket of this kind goes in the region
+above: extra fields, a compliance checklist, a link to a local convention.
+
+The region is yours. An upgrade replaces every other line of this template with
+the new version's text and carries this region across untouched, so a local
+addition here is not a divergence you re-resolve on every upgrade - which is
+what editing the rest of the template would cost you.
+-->