contextcompass 2.15.0__py3-none-any.whl

contextcompass_cli/_package/examples/artifact_workflow.md

@@ -0,0 +1,20 @@
+# Example: artifact workflow (repo-based)
+
+Scenario
+- A docs release-readiness pass requires a retained rationale artifact.
+
+Flow
+1. Create artifact
+- `examples/example_completed/2026-02-19_context_compass_release_overview_artifact.md`
+
+2. Link artifact in ticket chain
+- Epic, story, and task all include the same artifact path.
+
+3. Capture rationale
+- Add `DECISION`, `EVIDENCE`, and `NEXT` note fields in linked tickets.
+
+4. Apply disposition
+- Keep as `retain_as_reference` unless a later docs policy changes it.
+
+Expected outcome
+- Any reader can reconstruct why the artifact exists and how it supports ticket closure.

contextcompass_cli/_package/examples/continuity_fact_checker_task_flow.md

@@ -0,0 +1,23 @@
+# Example: continuity_fact_checker task flow
+
+Scenario
+- Verify timeline and canon continuity before proofing.
+
+Workflow
+1. Intake
+- gather story bible, chapter map, and current manuscript.
+
+2. Continuity scan
+- detect contradictions in timeline, facts, and constraints.
+
+3. Severity assignment
+- classify conflicts and attach evidence.
+
+4. Resolution handoff
+- publish recommended fixes and responsible role.
+
+Expected outputs
+- `continuity_matrix.md`
+- `timeline_validation.md`
+- `canon_conflict_report.md`
+- `resolution_recommendations.md`

contextcompass_cli/_package/examples/design_task_flow.md

@@ -0,0 +1,35 @@
+# Example: design_engineer task flow (repo-based)
+
+Scenario
+- Story: raise release-readiness doc quality so users can execute this workflow
+  from this repository without hidden assumptions.
+
+Entry gate
+- Confirm design-first scope and clear boundaries before implementation edits.
+
+Design workflow
+1. Problem framing
+- Define failures: shallow examples, stale slugs, unclear chain.
+
+2. Current-state evidence
+- Review templates, current examples, and system docs.
+
+3. Option set
+- Option A: patch only links.
+- Option B: rewrite as full repo-based chain.
+
+4. Tradeoff analysis
+- Option A is faster but weak.
+- Option B is durable and reusable for release hardening.
+
+5. Proposed design
+- Pick Option B.
+- Define epic/story/task/artifact naming and acceptance gates.
+
+6. Ticketization
+- One story, one implementation task, retained overview artifact.
+
+Expected outputs
+- design rationale in ticket notes and ADR
+- artifact: `examples/example_completed/2026-02-19_context_compass_release_overview_artifact.md`
+- explicit approval checkpoint before final closure

contextcompass_cli/_package/examples/developmental_editor_task_flow.md

@@ -0,0 +1,22 @@
+# Example: developmental_editor task flow
+
+Scenario
+- Evaluate a full manuscript draft for structure, pacing, and coherence.
+
+Workflow
+1. Intake
+- load architecture pack and manuscript.
+
+2. Structural diagnosis
+- identify plot holes, pacing failures, and character-arc breaks.
+
+3. Rewrite plan
+- prioritize defects with sequencing and dependencies.
+
+4. Handoff
+- provide actionable rewrite packet to draft writer.
+
+Expected outputs
+- `developmental_report.md`
+- `priority_defect_matrix.md`
+- `rewrite_plan.md`

contextcompass_cli/_package/examples/draft_writer_task_flow.md

@@ -0,0 +1,23 @@
+# Example: draft_writer task flow
+
+Scenario
+- Produce manuscript draft from approved architecture + research constraints.
+
+Workflow
+1. Intake
+- confirm required dependencies are complete.
+
+2. Draft pass
+- write chapter-complete v1 with deviation log.
+
+3. Revision pass
+- address developmental defects and publish v2.
+
+4. Gate
+- unresolved high-severity defects are escalated.
+
+Expected outputs
+- `manuscript_draft_v1.md`
+- `deviation_log.md`
+- `manuscript_draft_v2.md`
+- `rewrite_resolution_log.md`

contextcompass_cli/_package/examples/eng_task_flow.md

@@ -0,0 +1,31 @@
+# Example: engineer task flow (repo-based)
+
+Scenario
+- Active ticket: `examples/example_tasks/2026-02-19_context_compass_release_readiness_pack_task.md`
+- Goal: build a complete release-readiness example chain using this repository
+  as the working context.
+
+Entry gate
+- Scope is bounded to `examples/` and `system_docs/` docs surfaces.
+- Story linkage exists:
+  `examples/example_stories/2026-02-19_context_compass_release_readiness_examples_story.md`.
+
+Ticket microcycle
+1. Investigate
+- Read templates and current example/system docs.
+
+2. Document
+- Record `FACT` and `UNKNOWN` findings with file evidence.
+
+3. Plan
+- Define file names, scope boundaries, and acceptance gates.
+
+4. Implement
+- Create/update epic/story/task/artifact and flow docs.
+
+5. Validate
+- Run grep checks for stale slugs and path quality.
+
+Exit gate
+- Task acceptance criteria are satisfied.
+- Story and epic links are coherent.

contextcompass_cli/_package/examples/example_architecture/src_architecture.md

@@ -0,0 +1,136 @@
+# Example src_architecture (repo-grounded)
+
+## Metadata
+- Example type: high-fidelity architecture example
+- Objective: show what a strong architecture document looks like when based on
+  real repository files
+- Last verified at: 2026-08-01T16:16:14Z
+
+## Scope and Intent
+This example demonstrates a credible C4 architecture narrative for Context
+Compass using this repo's actual entrypoints, routing files, ticket lanes, and
+board state files.
+
+## Indexing
+
+This document is authored. Its only generated companion is `src_architecture_index.md`,
+rebuilt in the same pass as any edit:
+
+```bash
+python context_compass/tools/system_documents/index_document.py \
+    --doc context_compass/examples/example_architecture/src_architecture.md
+```
+
+That command indexes THIS example, and it works - run it and compare the
+output to the `src_architecture_index.md` beside it. When you write your own, the
+target becomes `context_compass/system_docs/src_architecture.md`, which does not exist
+until you create it: the package ships `system_docs/` empty.
+
+Format rules the index depends on, demonstrated throughout this example:
+- exactly one H1 (the document title)
+- the navigable unit is H2 `## <Concern>`, at consistent depth
+- section names unique and stable - index rows are selected by name
+- container headings organise, but are never the read target: a heading wrapping
+  only other headings indexes as a range covering all of them
+
+Spec: `agent_onboarding/default/engineer/skills/system_document_build.md`
+
+## DO NOT ASSUME / Unknowns Gate
+- Keep unresolved claims marked UNKNOWN.
+- Promote to FACT only with file evidence.
+
+## Unknowns
+- UNKNOWN: whether automated path/reference scanning will be part of the default
+  release checklist.
+- UNKNOWN: whether artifact retention defaults should differ by lane.
+
+## System Context (C4)
+Context Compass turns volatile chat context into durable, file-backed execution
+state through policy bootstrap, role routing, and ticket-first notes.
+
+## System Boundary and External Interfaces
+- Entrypoints: `AGENTS.MD`
+- Router/config: `SKILLS.MD`, `config/context_compass_config.yaml`
+- Work memory: `attention_board.md`, `tickets/`
+- Artifact memory: `artifact_board.md`, `artifacts/`
+
+## Architecture Summary (C4)
+- bootstrap/guardrails
+- role-chain routing
+- ticket microcycle execution
+- closure and compaction continuity
+
+## Entrypoints and Runtime Guardrails
+- mandatory onboarding/certification before work
+- parent-first role-chain reads
+- explicit re-onboarding after compaction/handoff
+
+## Boot and Configuration Sequence
+1. Read runtime entrypoint.
+2. Read execution contract and compaction policy.
+3. Read config + top-level skills map.
+4. Resolve and read role chain.
+5. Route to active ticket.
+6. Execute microcycle and document findings.
+
+## Data Flows and Sequences
+- request -> routing -> ticket loop -> validation -> closure sync
+- compaction -> re-onboarding -> recertify -> resume
+
+## Operational Invariants
+- ticket notes are canonical in-flight memory
+- UNKNOWN never becomes FACT without evidence
+- sample assets stay in `examples/` lanes
+
+## Failure Modes and Error Paths
+- broken references
+- stale attention-board pointer
+- missing artifact disposition
+
+## C1 Code Map (Core Only)
+- path: `SKILLS.MD`
+  start_line: 1
+  end_line: 108
+  loc: 108
+  verified_at: 2026-08-01T16:16:14Z
+- path: `config/context_compass_config.yaml`
+  start_line: 1
+  end_line: 101
+  loc: 101
+  verified_at: 2026-08-01T16:16:14Z
+- path: `attention_board.md`
+  start_line: 1
+  end_line: 57
+  loc: 57
+  verified_at: 2026-08-01T16:16:14Z
+- path: `artifact_board.md`
+  start_line: 1
+  end_line: 54
+  loc: 54
+  verified_at: 2026-08-01T16:16:14Z
+
+## Diagrams
+```text
+Entrypoint -> Config/Skills -> Role Chain -> Ticket Loop -> Closure/Compaction
+```
+
+```mermaid
+flowchart LR
+  E[Entrypoint] --> R[Config + Skills]
+  R --> C[Role Chain]
+  C --> T[Ticket Loop]
+  T --> H[Closure + Compaction Recovery]
+```
+
+## Information Sources
+- `AGENTS.MD`
+
+- `SKILLS.MD`
+- `config/context_compass_config.yaml`
+- `agent_onboarding/default/general/skills/workflow.md`
+
+## Context / Handoff Summary
+This example shows the expected depth standard: concrete boundaries, explicit
+invariants, and repo-backed references.
+
+

contextcompass_cli/_package/examples/example_architecture/src_architecture_index.md

@@ -0,0 +1,46 @@
+# src_architecture_index
+
+Line ranges into `src_architecture.md`. Derived: regenerated by re-walking the
+document, never hand-edited. Hand-editing a range is how an index starts
+lying.
+
+Line numbers are 1-based and inclusive on both ends.
+
+## Staleness proof
+
+| field | value |
+| --- | --- |
+| document | `src_architecture.md` |
+| index_version | 1.1.0 |
+| generated_at | 2026-08-01T23:32:34Z |
+| line_count | 136 |
+| line_ending | lf |
+| content_sha256 | `8f426d7c9265847850d4bc3f0650617a387469165ebd9c47465615c21a288deb` |
+| sections | 17 |
+
+Recompute all three of `line_count`, `line_ending`, and `content_sha256`
+before slicing. On any mismatch: STOP, do not slice, do not eyeball an
+offset. Regenerate this index or read the document directly, and say
+which you did.
+
+## Sections
+
+| lines | lvl | name |
+| --- | --- | --- |
+| 3-8 | 2 | Metadata |
+| 9-13 | 2 | Scope and Intent |
+| 14-37 | 2 | Indexing |
+| 38-41 | 2 | DO NOT ASSUME / Unknowns Gate |
+| 42-46 | 2 | Unknowns |
+| 47-50 | 2 | System Context (C4) |
+| 51-56 | 2 | System Boundary and External Interfaces |
+| 57-62 | 2 | Architecture Summary (C4) |
+| 63-67 | 2 | Entrypoints and Runtime Guardrails |
+| 68-75 | 2 | Boot and Configuration Sequence |
+| 76-79 | 2 | Data Flows and Sequences |
+| 80-84 | 2 | Operational Invariants |
+| 85-89 | 2 | Failure Modes and Error Paths |
+| 90-111 | 2 | C1 Code Map (Core Only) |
+| 112-124 | 2 | Diagrams |
+| 125-131 | 2 | Information Sources |
+| 132-136 | 2 | Context / Handoff Summary |

contextcompass_cli/_package/examples/example_architecture/tests_architecture.md

@@ -0,0 +1,148 @@
+# Example tests_architecture (repo-grounded)
+
+## Metadata
+- Example type: high-fidelity tests architecture example
+- Objective: show what a strong tests architecture document looks like when
+  based on real repository files
+- Last verified at: 2026-08-01T16:16:14Z
+
+## Scope and Intent
+This example demonstrates the test-side mirror of `src_architecture.md`. It uses
+this repository's actual testing skills, QA role docs, and ticket lanes rather
+than invented surfaces.
+
+The two documents are a matched pair. `src_architecture.md` describes how the
+runtime is structured; this one describes how that structure is verified. They
+share a section contract so a reader who knows one can navigate the other
+without relearning anything.
+
+## Indexing
+
+This document is authored. Its only generated companion is `tests_architecture_index.md`,
+rebuilt in the same pass as any edit:
+
+```bash
+python context_compass/tools/system_documents/index_document.py \
+    --doc context_compass/examples/example_architecture/tests_architecture.md
+```
+
+That command indexes THIS example, and it works - run it and compare the
+output to the `tests_architecture_index.md` beside it. When you write your own, the
+target becomes `context_compass/system_docs/tests_architecture.md`, which does not exist
+until you create it: the package ships `system_docs/` empty.
+
+Format rules the index depends on, demonstrated throughout this example:
+- exactly one H1 (the document title)
+- the navigable unit is H2 `## <Concern>`, at consistent depth
+- section names unique and stable - index rows are selected by name
+- container headings organise, but are never the read target: a heading wrapping
+  only other headings indexes as a range covering all of them
+
+Spec: `agent_onboarding/default/engineer/skills/system_document_build.md`
+
+## DO NOT ASSUME / Unknowns Gate
+- Keep unresolved test claims marked UNKNOWN.
+- A test that has never run is not evidence. Promote to FACT only when the run
+  produced output you read.
+
+## Unknowns
+- UNKNOWN: whether contract checks over policy documents should run in CI or
+  stay a release-hardening step.
+- UNKNOWN: the boundary between component and integration suites for
+  documentation-shaped systems.
+
+## System Context (C4)
+Testing here validates a document-backed system, so most surfaces are
+structural rather than behavioural: references resolve, section contracts hold,
+role chains are reachable, and evidence ranges match the files they cite.
+
+## System Boundary and External Interfaces
+- Test posture and strategy: `agent_onboarding/default/qa_engineer/skills/`
+- Document contracts under test: `agent_onboarding/default/design_engineer/skills/`
+- Evidence lanes: `tickets/`, active ticket `## Notes`
+- Index tooling: `tools/system_documents/index_document.py`
+
+## Architecture Summary (C4)
+- reference-integrity checks over the routing graph
+- section-contract checks over system documents
+- index staleness checks against the documents they describe
+- evidence-quality checks on cited line ranges
+
+## Entrypoints and Runtime Guardrails
+- a check that cannot fail is not a check
+- findings carry `path:start_line-end_line`, never a bare assertion
+- a stale index is a hard stop, not a rounding error
+
+## Boot and Configuration Sequence
+1. Resolve the role chain to know which documents are in scope.
+2. Recompute each index's staleness proof before slicing anything.
+3. Run reference resolution over the resolved readset.
+4. Compare section contracts against the spec.
+5. Record findings in the active ticket with file evidence.
+
+## Data Flows and Sequences
+- authoring change -> index rebuild -> checks -> evidence in ticket notes
+- compaction -> re-onboard -> re-verify stale assumptions -> resume
+
+## Operational Invariants
+- every readset path resolves, or onboarding is blocked
+- every index matches `line_count`, `line_ending`, and `content_sha256`
+- every cited range is measured, never estimated
+
+## Failure Modes and Error Paths
+- a checker whose pattern is too narrow reports a clean sweep over a subset
+- an index regenerated before the document is edited, so the proof passes and
+  the ranges lie
+- ranges copied forward from an earlier revision without remeasuring
+
+## C1 Code Map (Core Only)
+- path: `agent_onboarding/default/qa_engineer/skills/test_case_design.md`
+  start_line: 1
+  end_line: 27
+  loc: 27
+  verified_at: 2026-08-01T16:16:14Z
+- path: `agent_onboarding/default/qa_engineer/skills/test_automation_practices.md`
+  start_line: 1
+  end_line: 30
+  loc: 30
+  verified_at: 2026-08-01T16:16:14Z
+- path: `agent_onboarding/default/qa_engineer/skills/test_strategy_and_planning.md`
+  start_line: 1
+  end_line: 31
+  loc: 31
+  verified_at: 2026-08-01T16:16:14Z
+- path: `agent_onboarding/default/qa_engineer/skills/regression_and_release_quality.md`
+  start_line: 1
+  end_line: 28
+  loc: 28
+  verified_at: 2026-08-01T16:16:14Z
+- path: `tickets/tasks/README.md`
+  start_line: 1
+  end_line: 67
+  loc: 67
+  verified_at: 2026-08-01T16:16:14Z
+
+## Diagrams
+```text
+Docs Change -> Index Rebuild -> Checks -> Evidence -> Ticket Notes
+```
+
+```mermaid
+flowchart LR
+  D[Docs Change] --> I[Index Rebuild]
+  I --> C[Reference + Contract Checks]
+  C --> E[Evidence with Line Ranges]
+  E --> N[Ticket Notes]
+```
+
+## Information Sources
+- `agent_onboarding/default/qa_engineer/skills/test_case_design.md`
+- `agent_onboarding/default/qa_engineer/skills/test_strategy_and_planning.md`
+- `tickets/tasks/README.md`
+- `agent_onboarding/default/engineer/skills/system_document_build.md`
+
+## Context / Handoff Summary
+This example shows the expected depth standard for the test-side map: concrete
+surfaces, explicit unknowns, and measured line ranges. It pairs with
+`examples/example_architecture/src_architecture.md`; read them together to see how the
+runtime map and its verification map stay structurally aligned.

contextcompass_cli/_package/examples/example_architecture/tests_architecture_index.md

@@ -0,0 +1,46 @@
+# tests_architecture_index
+
+Line ranges into `tests_architecture.md`. Derived: regenerated by re-walking the
+document, never hand-edited. Hand-editing a range is how an index starts
+lying.
+
+Line numbers are 1-based and inclusive on both ends.
+
+## Staleness proof
+
+| field | value |
+| --- | --- |
+| document | `tests_architecture.md` |
+| index_version | 1.1.0 |
+| generated_at | 2026-08-02T09:36:24Z |
+| line_count | 148 |
+| line_ending | lf |
+| content_sha256 | `a7bf8047ab6894b1d9a509f15b0ea4b42fbaa02f73789f72c0c3459051d9c9cf` |
+| sections | 17 |
+
+Recompute all three of `line_count`, `line_ending`, and `content_sha256`
+before slicing. On any mismatch: STOP, do not slice, do not eyeball an
+offset. Regenerate this index or read the document directly, and say
+which you did.
+
+## Sections
+
+| lines | lvl | name |
+| --- | --- | --- |
+| 3-8 | 2 | Metadata |
+| 9-18 | 2 | Scope and Intent |
+| 19-42 | 2 | Indexing |
+| 43-47 | 2 | DO NOT ASSUME / Unknowns Gate |
+| 48-53 | 2 | Unknowns |
+| 54-58 | 2 | System Context (C4) |
+| 59-64 | 2 | System Boundary and External Interfaces |
+| 65-70 | 2 | Architecture Summary (C4) |
+| 71-75 | 2 | Entrypoints and Runtime Guardrails |
+| 76-82 | 2 | Boot and Configuration Sequence |
+| 83-86 | 2 | Data Flows and Sequences |
+| 87-91 | 2 | Operational Invariants |
+| 92-97 | 2 | Failure Modes and Error Paths |
+| 98-124 | 2 | C1 Code Map (Core Only) |
+| 125-137 | 2 | Diagrams |
+| 138-143 | 2 | Information Sources |
+| 144-148 | 2 | Context / Handoff Summary |

contextcompass_cli/_package/examples/example_completed/2026-02-19_context_compass_release_overview_artifact.md

@@ -0,0 +1,33 @@
+# Context Compass Release Readiness Overview Artifact
+
+## Purpose
+Provide durable rationale for making this repository itself the primary example
+scenario in public-facing workflow documentation.
+
+## Summary of Changes
+- Replaced weak, unrelated top-level sample narrative.
+- Added complete epic/story/task chain in `examples/example_*`.
+- Added rich repository overview and linked it to the chain.
+- Upgraded architecture and components docs with repo-grounded detail.
+
+## Decisions
+- Keep examples isolated in `examples/` lanes.
+- Keep references copy-safe for `context_compass/AGENTS.MD`.
+- Retain this artifact for future release-hardening checks.
+
+## Evidence
+- `examples/example_epics/2026-02-19_context_compass_release_readiness_example_pack_epic.md`
+- `examples/example_stories/2026-02-19_context_compass_release_readiness_examples_story.md`
+- `examples/example_tasks/2026-02-19_context_compass_release_readiness_pack_task.md`
+- `examples/repo_overview.md`
+- `system_docs/src_architecture.md`
+- `system_docs/src_components.md`
+
+## Validation Snapshot
+- legacy sample slugs removed from top-level example docs
+- flow docs align with new example chain
+- architecture/component docs use readable, clean paths
+
+## Disposition
+- retain_as_reference
+