contextcompass 2.15.0__py3-none-any.whl

contextcompass_cli/_package/examples/example_graph_details/src/example/storage/store.py

@@ -0,0 +1,20 @@
+"""Record storage."""
+from threading import RLock
+from example.core.resource import Resource
+
+
+class Store(Resource):
+    """Holds records for the duration of a run."""
+
+    def __init__(self) -> None:
+        self._lock = RLock()
+        self._records: dict[str, bytes] = {}
+
+    def acquire(self) -> None: ...
+    def release(self) -> None: ...
+    def put(self, key: str, value: bytes) -> None: ...
+    def get(self, key: str) -> bytes: ...
+    def keys(self) -> list[str]: ...
+
+
+Storage = Store

contextcompass_cli/_package/examples/example_graph_details/src_graph.md

@@ -0,0 +1,192 @@
+# src_graph
+
+Assembled system graph. One section per source file. Each section opens
+with an HTML comment reading BEGIN FILE followed by the source path, and
+closes with the matching END FILE comment. Exact line ranges are in
+`src_graph_index.md`; prefer the index over scanning for delimiters.
+
+Generated by `tools/system_documents/python/assemble_graph.py`.
+Do not hand-edit: edit the per-file descriptors and reassemble.
+
+<!-- BEGIN FILE: src/example/__init__.py -->
+
+## src/example/__init__.py
+
+- source_sha256: `932911b90c4ce4e130ec615078a8e4b6c41ffffc3cbe6aadd068e3d4a079feb1`
+- nodes: 1
+
+### Nodes
+
+#### `example` (module)
+
+- id: `example`
+- defined at: `src/example/__init__.py:1`
+- **UNSEMANTIC** - mechanical scaffold only, not yet authored
+
+<!-- END FILE: src/example/__init__.py -->
+
+<!-- BEGIN FILE: src/example/core/interfaces.py -->
+
+## src/example/core/interfaces.py
+
+- source_sha256: `5120f2b7d872f45c099574c2917dfba83742e06f0e83f1743180bc027ff95051`
+- nodes: 2
+
+### Nodes
+
+#### `interfaces` (module)
+
+- id: `example.core.interfaces`
+- defined at: `src/example/core/interfaces.py:1`
+- **UNSEMANTIC** - mechanical scaffold only, not yet authored
+
+#### `IResource` (interface)
+
+- id: `example.core.interfaces.IResource`
+- defined at: `src/example/core/interfaces.py:5`
+- markers: `Protocol`
+- role: Structural mirror of the Resource ABC's public surface.
+- public methods: `acquire`, `is_open`, `release`
+
+<!-- END FILE: src/example/core/interfaces.py -->
+
+<!-- BEGIN FILE: src/example/core/resource.py -->
+
+## src/example/core/resource.py
+
+- source_sha256: `7973dcbcd22a09b055173bbaa14895072d4ee0ecc7027b66f0db01e9c5a89e21`
+- nodes: 2
+
+### Nodes
+
+#### `resource` (module)
+
+- id: `example.core.resource`
+- defined at: `src/example/core/resource.py:1`
+- **UNSEMANTIC** - mechanical scaffold only, not yet authored
+
+#### `Resource` (abstract)
+
+- id: `example.core.resource.Resource`
+- defined at: `src/example/core/resource.py:5`
+- markers: `ABC`
+- role: Acquire/release contract every owned resource inherits.
+- responsibilities: `defines the lifecycle surface`
+- phases: `runtime`
+- public methods: `acquire`, `is_open`, `release`
+
+<!-- END FILE: src/example/core/resource.py -->
+
+<!-- BEGIN FILE: src/example/pipeline/pipeline.py -->
+
+## src/example/pipeline/pipeline.py
+
+- source_sha256: `fe7cb898b9e4e3b9f0916449f7bdbbdb9facad1de1f9162f4f5f4b8d27c13fe9`
+- nodes: 2
+
+### Nodes
+
+#### `pipeline` (module)
+
+- id: `example.pipeline.pipeline`
+- defined at: `src/example/pipeline/pipeline.py:1`
+- **UNSEMANTIC** - mechanical scaffold only, not yet authored
+
+#### `Pipeline` (class)
+
+- id: `example.pipeline.pipeline.Pipeline`
+- defined at: `src/example/pipeline/pipeline.py:8`
+- extends: `Resource`
+- role: Execution scope for a run: owns its stages, borrows the store.
+- responsibilities: `owns the stage list for one run`, `sequences stage execution`, `releases stages on close`
+- owns_state: `_stages`, `_lock`
+- phases: `init`, `runtime`, `cleanup`
+- public methods: `acquire`, `add_stage`, `release`, `run`, `stage_names`
+
+### Edges out
+
+| from | relation | to | cardinality | phase | origin |
+| --- | --- | --- | --- | --- | --- |
+| `example.pipeline.pipeline.Pipeline` | specializes | `example.core.resource.Resource` | - | - | derived |
+| `example.pipeline.pipeline.Pipeline` | owns_lifecycle_of | `example.pipeline.stage.Stage` | one_to_many | init,runtime,cleanup | authored |
+| `example.pipeline.pipeline.Pipeline` | borrows | `example.storage.store.Store` | many_to_one | runtime | authored |
+
+- `example.pipeline.pipeline.Pipeline` -> `example.pipeline.stage.Stage`: Pipeline constructs its stages in __init__ and is the only object that can release them, so the stage list dies with the run.
+- `example.pipeline.pipeline.Pipeline` -> `example.storage.store.Store`: The store is passed in and outlives the pipeline. Releasing the pipeline must not close it - several pipelines share one store.
+
+### Edge candidates (2, unconfirmed)
+
+Instantiation guesses from the AST. Over-generated roughly 8x against the reference graph; confirm or drop before relying on them.
+
+- `example.pipeline.pipeline.Pipeline` creates `RLock`
+- `example.pipeline.pipeline.Pipeline` creates `Stage`
+
+<!-- END FILE: src/example/pipeline/pipeline.py -->
+
+<!-- BEGIN FILE: src/example/pipeline/stage.py -->
+
+## src/example/pipeline/stage.py
+
+- source_sha256: `ee53cbf3da28df104f91d4f62798046acbeb85dfe33678ae03d97dfc837b48df`
+- nodes: 2
+
+### Nodes
+
+#### `stage` (module)
+
+- id: `example.pipeline.stage`
+- defined at: `src/example/pipeline/stage.py:1`
+- **UNSEMANTIC** - mechanical scaffold only, not yet authored
+
+#### `Stage` (class)
+
+- id: `example.pipeline.stage.Stage`
+- defined at: `src/example/pipeline/stage.py:4`
+- public methods: `describe`, `run`
+- **UNSEMANTIC** - mechanical scaffold only, not yet authored
+
+<!-- END FILE: src/example/pipeline/stage.py -->
+
+<!-- BEGIN FILE: src/example/storage/store.py -->
+
+## src/example/storage/store.py
+
+- source_sha256: `33f8c86c22704cf1aba64ca8fbddae2c9e8dddc3541b4ad296da55ea53040049`
+- nodes: 2
+
+### Nodes
+
+#### `store` (module)
+
+- id: `example.storage.store`
+- defined at: `src/example/storage/store.py:1`
+- **UNSEMANTIC** - mechanical scaffold only, not yet authored
+
+#### `Store` (class)
+
+- id: `example.storage.store.Store`
+- defined at: `src/example/storage/store.py:6`
+- extends: `Resource`
+- role: Record storage held for the duration of a run.
+- owns_state: `_records`, `_lock`
+- phases: `runtime`
+- public methods: `acquire`, `get`, `keys`, `put`, `release`
+
+### Edges out
+
+| from | relation | to | cardinality | phase | origin |
+| --- | --- | --- | --- | --- | --- |
+| `example.storage.store.Store` | specializes | `example.core.resource.Resource` | - | - | derived |
+
+### Edge candidates (1, unconfirmed)
+
+Instantiation guesses from the AST. Over-generated roughly 8x against the reference graph; confirm or drop before relying on them.
+
+- `example.storage.store.Store` creates `RLock`
+
+### Published aliases
+
+- `Storage` = `Store` (line 20)
+
+<!-- END FILE: src/example/storage/store.py -->
+

contextcompass_cli/_package/examples/example_graph_details/src_graph_index.md

@@ -0,0 +1,32 @@
+# src_graph_index
+
+Line ranges into `src_graph.md`. Emitted by the same pass that wrote the
+document, so the ranges cannot have drifted from it.
+
+Line numbers are 1-based and inclusive on both ends.
+
+## Staleness proof
+
+| field | value |
+| --- | --- |
+| document | `src_graph.md` |
+| index_version | 1.0.0 |
+| generated_at | 2026-08-02T09:31:52Z |
+| line_count | 192 |
+| line_ending | lf |
+| content_sha256 | `a655ccfaee86bb59aa26613ab714da5ea770572e5b098a85f296e84d9e9a6366` |
+| sections | 6 |
+
+Recompute `line_count` and `content_sha256` before slicing. On any
+mismatch the document was hand-edited: STOP, do not slice, reassemble.
+
+## Sections
+
+| lines | source | nodes | edges |
+| --- | --- | --- | --- |
+| 11-26 | `src/example/__init__.py` | 1 | 0 |
+| 28-51 | `src/example/core/interfaces.py` | 2 | 0 |
+| 53-78 | `src/example/core/resource.py` | 2 | 0 |
+| 80-124 | `src/example/pipeline/pipeline.py` | 2 | 3 |
+| 126-148 | `src/example/pipeline/stage.py` | 2 | 0 |
+| 150-191 | `src/example/storage/store.py` | 2 | 1 |

contextcompass_cli/_package/examples/example_stories/2026-02-19_context_compass_release_readiness_examples_story.md

@@ -0,0 +1,120 @@
+# Story: Build Repo-Based Release Readiness Workflow Examples
+
+## Metadata
+- Story ID: STORY-2026-02-19-context-compass-release-readiness-examples
+- Epic: EPIC-2026-02-19-context-compass-release-readiness-example-pack
+- Status: done
+- Owner: context_compass_maintainer
+- Priority: p1
+- Created: 2026-02-19T01:20:00Z
+- Updated: 2026-02-19T03:10:00Z
+
+## User Narrative
+As a maintainer preparing this package for public use, I want a realistic,
+end-to-end example chain built from this repository so users can copy
+`context_compass/` and understand actual workflow execution.
+
+## Value / MRP Alignment
+This story replaces placeholder examples with a durable, evidence-backed,
+repo-grounded pattern that can survive compaction and handoff.
+
+## Ticket Contract
+- ENTRY_GATE: epic scope and templates reviewed.
+- EXECUTION_BOUNDARY: docs/examples only.
+- DEPENDENCIES: `TASK-2026-02-19-context-compass-release-readiness-pack`, `templates/story_template.md`, `templates/task_template.md`, `tickets/stories/README.md`, `tickets/tasks/README.md`.
+- EXIT_GATE: task done; flow docs updated; example links resolve.
+- FAILURE_ESCALATION: `DECISION_REQUEST` for format ambiguity, `BLOCKER` for unresolved references.
+
+## Requirements (Functional)
+- Create complete story/task examples with correct IDs and links.
+- Add an example artifact and rich overview.
+- Align top-level flow docs to new example assets.
+
+## Requirements (Non-Functional)
+- Compaction-safe clarity and evidence-backed claims.
+- Copy-safe repository paths for users importing `context_compass/`.
+
+## Scope Boundaries
+- In scope:
+  - `examples/example_stories/`
+  - `examples/example_tasks/`
+  - `examples/example_completed/`
+  - `examples/repo_overview.md`
+  - `examples/eng_task_flow.md`, `examples/design_task_flow.md`, `examples/artifact_workflow.md`, `examples/adr_example.md`
+- Out of scope:
+  - policy behavior changes
+  - external codebase modifications
+
+## State Transition Event
+- from_state: in_progress
+- to_state: done
+- transition_reason: linked task complete and acceptance criteria satisfied with evidence.
+
+## Tasks (Implementation Checklist)
+- [x] Task: TASK-2026-02-19-context-compass-release-readiness-pack - create repo-grounded chain and update flow docs.
+- [x] Enforce Ticket Microcycle across all linked tasks.
+- [x] Require meaningful-finding note updates during discovery/implementation.
+
+## Acceptance Criteria
+- Story and task files are template-complete and cross-linked.
+- Artifact exists and is linked in story/task/epic.
+- Flow docs point to new example paths only.
+- Rich overview exists in `examples/repo_overview.md`.
+
+## Validation / Test Plan
+- `rg -n "context_compass_release_readiness|repo_overview" examples`
+- `rg -n "context_compass_release_readiness" examples`
+- verify all linked example files exist.
+
+## UX / API / Data Notes
+- UX focus is onboarding/document clarity.
+- No API or data model changes.
+
+## Risks / Mitigations
+- Risk: mixed old/new references.
+  - Mitigation: grep for legacy slugs before closure.
+
+## Applicable Anti-Patterns
+- [x] No story-state transition without linked task-state evidence.
+- [x] No closure while required tasks remain active or un-routed.
+- [x] No cross-task synthesis claims without ticket-note evidence pointers.
+
+## Artifact Links (Optional)
+- ARTIFACTS_REQUIRED: true
+- ARTIFACT_PATHS:
+  - `examples/example_completed/2026-02-19_context_compass_release_overview_artifact.md`
+- DISPOSITION: retain_as_reference
+- CLEANUP_TRIGGER: next major docs refresh.
+
+## Notes
+- DATETIME: 2026-02-19T02:45:00Z
+  TYPE: FACT
+  CLAIM: no complete story existed in `examples/example_stories/` and the task example lacked template depth.
+  EVIDENCE:
+  - `examples/example_stories/.gitkeep:1-1`
+  - `examples/example_tasks/2026-02-19_context_compass_release_readiness_pack_task.md:1-40`
+  IMPACT: no end-to-end story-level onboarding reference.
+  NEXT: create full story/task pair and link artifact.
+  REREAD: REQUIRED
+  SCORE_0_TO_10: 9
+- DATETIME: 2026-02-19T03:10:00Z
+  TYPE: FACT
+  CLAIM: story deliverables and linked examples were completed.
+  EVIDENCE:
+  - `examples/example_stories/2026-02-19_context_compass_release_readiness_examples_story.md:1-140`
+  - `examples/example_tasks/2026-02-19_context_compass_release_readiness_pack_task.md:1-170`
+  - `examples/repo_overview.md:1-130`
+  IMPACT: repo now contains a complete sample workflow chain.
+  NEXT: await user acceptance.
+  REREAD: HELPFUL
+  SCORE_0_TO_10: 9
+
+## Closure Confirmation
+- [x] Work walkthrough shared with user
+- [ ] Acceptance criteria confirmed by user
+- [x] Applicable anti-pattern checks are clear or escalated with evidence.
+
+## Context / Handoff Summary
+Story is complete and linked to a finished task, artifact, and overview.
+Pending final user acceptance for closure.
+

contextcompass_cli/_package/examples/example_tasks/2026-02-19_context_compass_release_readiness_pack_task.md

@@ -0,0 +1,147 @@
+# Task: Build Repo-Based Release Readiness Example Pack
+
+## Metadata
+- Task ID: TASK-2026-02-19-context-compass-release-readiness-pack
+- Story: STORY-2026-02-19-context-compass-release-readiness-examples
+- Status: done
+- Owner: context_compass_maintainer
+- Priority: p1
+- Created: 2026-02-19T01:40:00Z
+- Updated: 2026-02-19T03:12:00Z
+
+## Objective
+Build a complete, template-quality example workflow using this repository as the
+actual context: epic/story/task/artifact chain, aligned flow docs, rich overview,
+and upgraded architecture/component docs.
+
+## Ticket Contract
+- ENTRY_GATE: story linkage confirmed and template contracts reviewed.
+- EXECUTION_BOUNDARY: `examples/` and `system_docs/` only.
+- DEPENDENCIES: `templates/task_template.md`, `templates/story_template.md`, `templates/epic_template.md`, `tickets/tasks/README.md`, `agent_onboarding/default/general/skills/workflow.md`.
+- EXIT_GATE: deliverables exist, legacy slugs removed from top-level flows, validation recorded.
+- FAILURE_ESCALATION: `DECISION_REQUEST` for contract ambiguity; `BLOCKER` for unresolved path integrity.
+
+## Scope Boundaries
+- In scope:
+  - create/update example epic/story/task/artifact files
+  - update top-level flow docs and ADR
+  - add `examples/repo_overview.md`
+  - improve `system_docs/src_architecture.md` and `system_docs/src_components.md`
+- Out of scope:
+  - runtime code changes
+  - onboarding policy redesign
+
+## State Transition Event
+- from_state: in_progress
+- to_state: done
+- transition_reason: all deliverables complete and validation checks pass.
+
+## Steps / Checklist
+- [x] Inventory current example docs and identify quality gaps.
+- [x] Replace weak task narrative with full template-quality task + story chain.
+- [x] Add/refresh epic to link story/task and artifact.
+- [x] Publish repo-based overview artifact.
+- [x] Rewrite top-level flow docs to new example references.
+- [x] Upgrade architecture/components docs with clean path text.
+- [x] Run Ticket Microcycle during execution:
+      `Investigate -> Document -> Strategy/Plan -> Document -> Implement ->
+      Document -> Validate -> Document`.
+- [x] Document each meaningful finding immediately in `## Notes` before further investigation.
+
+## Deliverables
+- `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/example_completed/2026-02-19_context_compass_release_overview_artifact.md`
+- `examples/repo_overview.md`
+- updated flow docs and system docs.
+
+## Files / Paths Impacted
+- `examples/eng_task_flow.md`
+- `examples/design_task_flow.md`
+- `examples/artifact_workflow.md`
+- `examples/adr_example.md`
+- `examples/repo_overview.md`
+- `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/example_completed/2026-02-19_context_compass_release_overview_artifact.md`
+- `system_docs/src_architecture.md`
+- `system_docs/src_components.md`
+- `examples/example_architecture/src_architecture.md`
+- `examples/example_components/src_components.md`
+
+## Validation
+- Completed.
+- Commands used:
+  - `rg -n "context_compass_release_readiness|repo_overview" examples`
+  - `rg -n "context_compass/AGENTS.MD" examples`
+  - `rg -n "\x07|\x08|\x09|\x0d" system_docs examples/example_architecture examples/example_components`
+
+## Risks / Rollback Notes
+- Risk: broad docs edits can introduce link drift.
+  - Rollback: restore previous example files and reapply in smaller scoped patches.
+
+## Applicable Anti-Patterns
+- [x] No status transition without evidence-backed transition reason.
+- [x] No implementation/validation from `UNKNOWN` or `HYPOTHESIS`.
+- [x] No closure without acceptance confirmation and board-sync completion.
+
+## Done Checklist
+- [x] Steps complete and checked off
+- [x] Deliverables produced and linked
+- [x] Documentation updated (if needed)
+- [x] Validation status recorded
+- [x] Unknown-first discipline followed (`UNKNOWN` promoted to `FACT` only with evidence)
+- [x] Notes quality maintained (`SCORE_0_TO_10` >=
+      `workflow.ticket_microcycle.minimum_note_score`)
+- [x] Applicable anti-pattern checks are clear or escalated with evidence.
+- [ ] Acceptance criteria reviewed with user and confirmed
+- [ ] Board sync completed for successor routing or closure anchor update.
+
+## Artifact Links (Optional)
+- ARTIFACTS_REQUIRED: true
+- ARTIFACT_PATHS:
+  - `examples/example_completed/2026-02-19_context_compass_release_overview_artifact.md`
+- DISPOSITION: retain_as_reference
+- CLEANUP_TRIGGER: next docs refresh cycle.
+
+## Notes
+- DATETIME: 2026-02-19T01:55:00Z
+  TYPE: FACT
+  CLAIM: prior task example was too minimal to satisfy ticket template depth.
+  EVIDENCE:
+  - `examples/example_tasks/2026-02-19_context_compass_release_readiness_pack_task.md:1-40`
+  - `templates/task_template.md:1-103`
+  IMPACT: users lacked a credible task-level reference.
+  NEXT: replace with full task + story chain.
+  REREAD: REQUIRED
+  SCORE_0_TO_10: 9
+- DATETIME: 2026-02-19T02:25:00Z
+  TYPE: FACT
+  CLAIM: top-level flow docs were still tied to old slugs and weak narrative.
+  EVIDENCE:
+  - `examples/eng_task_flow.md:1-30`
+  - `examples/artifact_workflow.md:1-25`
+  - `examples/adr_example.md:1-20`
+  IMPACT: inconsistent onboarding path.
+  NEXT: rewrite to repo-based files.
+  REREAD: REQUIRED
+  SCORE_0_TO_10: 9
+- DATETIME: 2026-02-19T03:12:00Z
+  TYPE: FACT
+  CLAIM: task deliverables were created and references aligned.
+  EVIDENCE:
+  - `examples/repo_overview.md:1-130`
+  - `system_docs/src_architecture.md:1-200`
+  - `system_docs/src_components.md:1-200`
+  IMPACT: package now has a usable release-readiness workflow example.
+  NEXT: request user acceptance and close.
+  REREAD: HELPFUL
+  SCORE_0_TO_10: 9
+
+## Context / Handoff Summary
+Task is complete with full example chain and repo overview. Re-run the listed
+validation commands during future release-hardening passes.
+
+

contextcompass_cli/_package/examples/line_copy_editor_task_flow.md

@@ -0,0 +1,23 @@
+# Example: line_copy_editor task flow
+
+Scenario
+- Perform line-level polish after structural approval.
+
+Workflow
+1. Intake
+- confirm manuscript is structurally stable.
+
+2. Edit pass
+- improve clarity, rhythm, and consistency without structural rewrites.
+
+3. Logging
+- track style decisions and recurring issues.
+
+4. Handoff
+- return revised manuscript plus edit log.
+
+Expected outputs
+- `line_edit_sheet.md`
+- `style_sheet.md`
+- `consistency_log.md`
+- `manuscript_line_v1.md`

contextcompass_cli/_package/examples/platform_task_flow.md

@@ -0,0 +1,26 @@
+# Example: platform_engineer task flow
+
+Scenario
+- Add a CI stage that runs architecture reference checks before merge.
+
+Workflow
+1. Intake
+- Identify pipelines, environments, and rollback path.
+
+2. Plan
+- Add lightweight check stage after unit tests.
+
+3. Implement
+- Update pipeline config and required scripts.
+
+4. Validate
+- Run pipeline in dry-run branch.
+- Confirm failure behavior when refs break.
+
+5. Handoff
+- Document operational risk and rollback command.
+
+Expected outputs
+- pipeline config diff
+- release note entry
+- operational runbook update

contextcompass_cli/_package/examples/proofreader_task_flow.md

@@ -0,0 +1,23 @@
+# Example: proofreader task flow
+
+Scenario
+- Final pre-release language pass.
+
+Workflow
+1. Intake
+- verify upstream editing passes are complete.
+
+2. Proof pass
+- fix grammar, punctuation, and formatting defects.
+
+3. Waiver capture
+- record any accepted residual issues.
+
+4. Release recommendation
+- issue final quality statement.
+
+Expected outputs
+- `proof_log.md`
+- `format_pass_log.md`
+- `final_issue_waivers.md`
+- `manuscript_final.md`

contextcompass_cli/_package/examples/qa_task_flow.md

@@ -0,0 +1,26 @@
+# Example: qa_engineer task flow
+
+Scenario
+- Validate release-readiness after doc and routing changes.
+
+Workflow
+1. Risk review
+- Identify critical paths: onboarding, role routing, references.
+
+2. Test strategy
+- contract checks: missing refs
+- workflow checks: ticket-note lifecycle
+- regression checks: adapter entrypoints
+
+3. Execute
+- Run reference scan and targeted smoke checks.
+
+4. Report
+- Findings ordered by severity with file references.
+
+5. Gate
+- Recommend `go` or `no-go` with residual risk list.
+
+Expected outputs
+- quality summary note
+- defect list or explicit no-findings statement

contextcompass_cli/_package/examples/repo_overview.md

@@ -0,0 +1,63 @@
+# Rich Repository Overview (Context Compass)
+
+## What This Package Is
+`context_compass/` is a docs-first operating model for long-running AI work. It
+provides deterministic onboarding, role routing, ticket memory, and compaction
+recovery so execution can continue reliably across sessions.
+
+## Core Entry Points
+- `context_compass/AGENTS.MD`: agent startup contract.
+
+- `context_compass/SKILLS.MD`: top-level role map.
+
+## Folder Map
+- `config/context_compass_config.yaml`: profile + role routing config.
+- `agent_onboarding/`: role chains and policy/skill docs.
+- `tickets/`: operational epic/story/task lanes.
+- `artifact_board.md`: artifact association/disposition index.
+- `attention_board.md`: active-ticket routing index.
+- `templates/`: canonical ticket templates.
+- `system_docs/`: architecture and component maps.
+- `examples/`: runnable workflow examples.
+
+## End-to-End Example Chain
+- Epic:
+  `examples/example_epics/2026-02-19_context_compass_release_readiness_example_pack_epic.md`
+- Story:
+  `examples/example_stories/2026-02-19_context_compass_release_readiness_examples_story.md`
+- Task:
+  `examples/example_tasks/2026-02-19_context_compass_release_readiness_pack_task.md`
+- Artifact:
+  `examples/example_completed/2026-02-19_context_compass_release_overview_artifact.md`
+
+## How To Read This Repo Fast
+1. Start with `AGENTS.MD`.
+2. Read `SKILLS.MD` and resolve the role chain.
+3. Read `config/context_compass_config.yaml`.
+4. Read `system_docs/src_architecture.md` and `system_docs/src_components.md`.
+5. Follow the example epic/story/task chain above.
+
+## Public-Release Quality Bar
+- examples are repo-local and realistic
+- story/task examples are template-complete
+- flow docs point only to files that exist
+- architecture/component docs use clean copy-safe paths
+- no sample files leak into real `tickets/` or `artifacts/` lanes
+
+## Common Failure Patterns
+- referencing source-tree-prefixed paths instead of `context_compass/...` in copy-facing docs
+- using placeholder narratives unrelated to this package
+- marking tickets done without evidence and validation notes
+
+## Adoption Steps
+1. Copy `context_compass/` to repo root.
+2. Enter through `AGENTS.MD`.
+3. Select role from `SKILLS.MD`.
+4. Create tickets from templates.
+5. Use this example chain as the baseline quality model.
+
+## Context / Handoff Summary
+Treat this file plus the linked epic/story/task/artifact as the default public
+workflow reference for this package.
+
+