contextcompass 2.15.0__py3-none-any.whl

contextcompass_cli/_package/examples/example_components/src_components.md

@@ -0,0 +1,169 @@
+# Example src_components (repo-grounded)
+
+## Metadata
+- Example type: high-fidelity C3/C2/C1 map
+- Objective: demonstrate complete component entries based on this repository
+- Last verified at: 2026-08-01T16:16:14Z
+
+## Scope
+Provide a concrete component-map example for ticket-first execution using real
+files from this package.
+
+## Indexing
+
+This document is authored. Its only generated companion is `src_components_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_components/src_components.md
+```
+
+That command indexes THIS example, and it works - run it and compare the
+output to the `src_components_index.md` beside it. When you write your own, the
+target becomes `context_compass/system_docs/src_components.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 H3 `### Component: <Name>`, 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
+- unresolved behavior stays UNKNOWN
+- promote claims only with evidence-backed references
+
+## Unknowns
+- UNKNOWN: future split of closure-sync responsibilities between docs policy and
+  scripted automation.
+
+## C3 Components Catalog
+### Component: Router/Role Resolver
+- Purpose: map the selected role to a deterministic role-chain readset.
+- Responsibilities: read `SKILLS.MD`, resolve role path, enforce parent-first
+  chain.
+- Inputs: the registry table in `SKILLS.MD`.
+- Outputs: ordered `SKILLS.MD` read chain.
+- Owned State: none. The registry table in `SKILLS.MD` is the state;
+  `config/context_compass_config.yaml` enumerates no roles.
+- Lifecycle/Cleanup: resolved once per agent per session; nothing persists
+  between sessions, so there is no state to clean up.
+- Concurrency/Threading: read-only resolution, safe under concurrent agents.
+  Role selection is per agent, so two agents resolving different roles in the
+  same repository do not contend.
+- Invariants/Guarantees: deterministic chain order and explicit path mapping.
+- Failure Modes: bad mapping path, stale references.
+- Observability: the resolved chain is stated in the onboarding attestation.
+- Extension Points: add a role by adding one registry row and the `SKILLS.MD`
+  it names; no resolver change is required.
+- Key Files (C1): `SKILLS.MD`, `config/context_compass_config.yaml`.
+
+### Component: Ticket Microcycle Coordinator
+- Purpose: enforce evidence-backed delivery cadence.
+- Responsibilities: keep note updates, transition logic, and validation records
+  coherent.
+- Inputs: active ticket content + findings.
+- Outputs: append-only notes and status transitions.
+- Owned State: ticket `## Notes` and transition records.
+- Lifecycle/Cleanup: spans one ticket, from route to closure; on closure the
+  ticket moves to its `completed/` lane rather than being deleted.
+- Concurrency/Threading: single-writer per ticket. Two agents on one ticket is
+  a coordination failure, not a supported mode.
+- Invariants/Guarantees: meaningful findings are captured before deeper actions.
+- Failure Modes: undocumented decisions and speculative transitions.
+- Observability: note timestamps and transition records in the ticket itself.
+- Extension Points: the microcycle phases are named in `workflow.md`; a lane
+  with extra phases extends that list rather than forking the coordinator.
+- Key Files (C1): `tickets/*`, `templates/task_template.md`, `agent_onboarding/default/general/skills/workflow.md`.
+
+### Component: Artifact Link Coordinator
+- Purpose: maintain traceable artifact-to-ticket relationships.
+- Responsibilities: keep artifact paths, status, and disposition synchronized.
+- Inputs: story/task artifact links and closure decisions.
+- Outputs: active/cleared rows in artifact board.
+- Owned State: `artifact_board.md` rows.
+- Lifecycle/Cleanup: a row lives from artifact creation to disposition at
+  ticket closure; cleared rows stay as history.
+- Concurrency/Threading: append-oriented board writes; concurrent edits to the
+  same row require ticket-level coordination.
+- Invariants/Guarantees: active artifact always has ticket ownership and
+  disposition.
+- Failure Modes: orphaned artifact rows, missing disposition.
+- Observability: the active/cleared split on the board is the status surface.
+- Extension Points: new artifact classes add a disposition rule; the row shape
+  stays fixed.
+- Key Files (C1): `artifact_board.md`, `examples/example_completed/*`.
+
+## C2 Subcomponents Catalog
+- Router/Role Resolver
+  - profile selector
+  - role path resolver
+  - chain-order reader
+
+- Ticket Microcycle Coordinator
+  - note appender
+  - transition recorder
+  - validation reporter
+
+- Artifact Link Coordinator
+  - artifact path linker
+  - disposition tracker
+
+## Method-Level Call Flows (C1)
+- `resolve_profile() -> resolve_role_path() -> read_inherited_skills()`
+- `investigate() -> append_note(FACT/UNKNOWN) -> plan() -> implement() -> validate() -> append_note(result)`
+- `link_artifact() -> record_disposition() -> verify_link_on_close()`
+
+## C1 Code Map (Core)
+- path: `SKILLS.MD`
+  start_line: 1
+  end_line: 108
+  loc: 108
+  verified_at: 2026-08-01T16:16:14Z
+- path: `templates/task_template.md`
+  start_line: 1
+  end_line: 111
+  loc: 111
+  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
+- path: `examples/eng_task_flow.md`
+  start_line: 1
+  end_line: 31
+  loc: 31
+  verified_at: 2026-08-01T16:16:14Z
+
+## Diagrams
+```text
+Profile Config -> Skills Resolver -> Active Ticket -> Notes/Transitions -> Closure
+```
+
+```mermaid
+flowchart LR
+  P[Profile Config] --> S[Skills Resolver]
+  S --> T[Active Ticket]
+  T --> N[Notes + Transitions]
+  N --> C[Closure Sync]
+```
+
+## Information Sources
+- `SKILLS.MD`
+- `config/context_compass_config.yaml`
+- `templates/task_template.md`
+- `tickets/tasks/README.md`
+- `agent_onboarding/default/general/skills/workflow.md`
+- `artifact_board.md`
+
+## Context / Handoff Summary
+This example demonstrates expected component-map depth with explicit ownership,
+invariants, and file-backed call flow claims.
+
+
+

contextcompass_cli/_package/examples/example_components/src_components_index.md

@@ -0,0 +1,44 @@
+# src_components_index
+
+Line ranges into `src_components.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_components.md` |
+| index_version | 1.1.0 |
+| generated_at | 2026-08-01T23:32:17Z |
+| line_count | 169 |
+| line_ending | lf |
+| content_sha256 | `518dd137c426620f9244c8ada040f4adf4bbf5092276ba840af872b517d448ec` |
+| sections | 15 |
+
+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-7 | 2 | Metadata |
+| 8-11 | 2 | Scope |
+| 12-35 | 2 | Indexing |
+| 36-39 | 2 | DO NOT ASSUME / Unknowns Gate |
+| 40-43 | 2 | Unknowns |
+| 44-100 | 2 | C3 Components Catalog |
+| 45-64 | 3 | C3 Components Catalog > Component: Router/Role Resolver |
+| 65-82 | 3 | C3 Components Catalog > Component: Ticket Microcycle Coordinator |
+| 83-100 | 3 | C3 Components Catalog > Component: Artifact Link Coordinator |
+| 101-115 | 2 | C2 Subcomponents Catalog |
+| 116-120 | 2 | Method-Level Call Flows (C1) |
+| 121-142 | 2 | C1 Code Map (Core) |
+| 143-155 | 2 | Diagrams |
+| 156-163 | 2 | Information Sources |
+| 164-169 | 2 | Context / Handoff Summary |

contextcompass_cli/_package/examples/example_components/tests_components.md

@@ -0,0 +1,96 @@
+# Example tests_components
+
+## Metadata
+- Example only; demonstrates tests component mapping format.
+
+## Scope
+Map key test-validation components for workflow integrity.
+
+## Indexing
+
+This document is authored. Its only generated companion is `tests_components_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_components/tests_components.md
+```
+
+That command indexes THIS example, and it works - run it and compare the
+output to the `tests_components_index.md` beside it. When you write your own, the
+target becomes `context_compass/system_docs/tests_components.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 H3 `### Component: <Name>`, 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 assumptions as UNKNOWN.
+
+## Unknowns
+- UNKNOWN: final CI matrix for multi-runtime validation.
+
+## C3 Components Catalog
+### Component: Reference Integrity Scanner
+- Purpose: detect broken internal references.
+- Responsibilities: scan docs and resolve paths.
+- Inputs: markdown/yaml files.
+- Outputs: missing reference findings.
+- Owned State: scan report.
+- Lifecycle/Cleanup: run on release hardening.
+- Concurrency/Threading: serial scan pass.
+- Invariants/Guarantees: findings include file references.
+- Failure Modes: false negatives from incomplete patterns. A pattern narrower
+  than the file set it claims to cover reports a clean sweep over a subset,
+  which is worse than reporting nothing.
+- Observability: ticket validation notes.
+- Extension Points: new reference shapes extend the resolver's match set; the
+  finding format stays fixed so downstream triage does not change.
+- Key Files (C1): `tickets/*/README.md`, `templates/*.md`.
+
+## C2 Subcomponents Catalog
+- path resolver
+- missing-target reporter
+- severity triage layer
+
+## Method-Level Call Flows (C1)
+- `scan_files -> resolve_targets -> emit_findings`
+- `triage_findings -> gate_release`
+
+## C1 Code Map (Core)
+- path: `examples/example_graph_details/src/example/core/resource.py`
+  start_line: 1
+  end_line: 15
+  loc: 15
+  verified_at: 2026-08-01T16:16:14Z
+- path: `examples/example_graph_details/src/example/storage/store.py`
+  start_line: 1
+  end_line: 20
+  loc: 20
+  verified_at: 2026-08-01T16:16:14Z
+
+## Diagrams
+```text
+Docs -> Scanner -> Findings -> Release Gate
+```
+
+```mermaid
+flowchart LR
+  D[Docs] --> S[Scanner]
+  S --> F[Findings]
+  F --> G[Release Gate]
+```
+
+## Information Sources
+- `templates/*.md`
+- `tickets/*/README.md`
+- `agent_onboarding/default/qa_engineer/skills/*`
+
+## Context / Handoff Summary
+Use this structure when mapping real test components.

contextcompass_cli/_package/examples/example_components/tests_components_index.md

@@ -0,0 +1,42 @@
+# tests_components_index
+
+Line ranges into `tests_components.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_components.md` |
+| index_version | 1.1.0 |
+| generated_at | 2026-08-02T10:58:15Z |
+| line_count | 96 |
+| line_ending | lf |
+| content_sha256 | `d505f573cd2b96f8df2169ab8640297c2f7f0c64fb4898e4f2aeebec14c4b634` |
+| sections | 13 |
+
+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-5 | 2 | Metadata |
+| 6-8 | 2 | Scope |
+| 9-32 | 2 | Indexing |
+| 33-35 | 2 | DO NOT ASSUME / Unknowns Gate |
+| 36-38 | 2 | Unknowns |
+| 39-56 | 2 | C3 Components Catalog |
+| 40-56 | 3 | C3 Components Catalog > Component: Reference Integrity Scanner |
+| 57-61 | 2 | C2 Subcomponents Catalog |
+| 62-65 | 2 | Method-Level Call Flows (C1) |
+| 66-77 | 2 | C1 Code Map (Core) |
+| 78-89 | 2 | Diagrams |
+| 90-94 | 2 | Information Sources |
+| 95-96 | 2 | Context / Handoff Summary |

contextcompass_cli/_package/examples/example_epics/2026-02-19_context_compass_release_readiness_example_pack_epic.md

@@ -0,0 +1,130 @@
+# Epic: Context Compass Release Readiness Example Pack
+
+## Metadata
+- Epic ID: EPIC-2026-02-19-context-compass-release-readiness-example-pack
+- Status: review
+- Owner: context_compass_maintainer
+- Priority: p1
+- Created: 2026-02-19T00:00:00Z
+- Updated: 2026-02-19T03:10:00Z
+- Target Window: 2026-Q1
+- Related Program/Initiative: public-library-release-hardening
+
+## Problem / Opportunity
+Top-level examples were shallow and referenced an unrelated legacy narrative.
+Users could not follow a complete epic -> story -> task flow grounded in this
+repository.
+
+## MRP Alignment (Most Reasonable Product)
+The durable core is a repo-local example set that demonstrates real usage:
+entrypoints and routing, template-complete tickets, artifact lifecycle, and
+compaction-safe handoff notes.
+
+## Ticket Contract
+- ENTRY_GATE: `SKILLS.MD` and `AGENTS.MD` are present and readable.
+- EXECUTION_BOUNDARY: docs/examples only.
+- DEPENDENCIES: `templates/*_template.md`, `tickets/*/README.md`, `agent_onboarding/default/general/skills/workflow.md`.
+- EXIT_GATE: complete example epic/story/task exists under `examples/example_*`; flow docs and system docs are aligned.
+- FAILURE_ESCALATION: raise `DECISION_REQUEST` for ambiguity and `BLOCKER` for unresolved references.
+
+## Goals (Outcomes)
+- Build one complete, high-quality epic/story/task chain based on this repo.
+- Publish a rich overview for users copying `context_compass/`.
+- Ensure top-level example flows reference only real example assets.
+
+## Non-Goals (Explicit Exclusions)
+- No runtime code changes.
+- No policy semantics redesign.
+
+## Scope Boundaries
+- In scope:
+  - `examples/example_epics/`, `examples/example_stories/`, `examples/example_tasks/`, `examples/example_completed/`
+  - `examples/eng_task_flow.md`, `examples/design_task_flow.md`, `examples/artifact_workflow.md`, `examples/adr_example.md`, `examples/repo_overview.md`
+  - `system_docs/src_architecture.md`, `system_docs/src_components.md`
+- Out of scope:
+  - CI/release scripting changes
+  - role-policy refactors
+
+## State Transition Event
+- from_state: in_progress
+- to_state: review
+- transition_reason: story and task are complete; awaiting user acceptance.
+
+## Success Metrics
+- Full example chain exists and links correctly.
+- Legacy sample slugs removed from top-level examples.
+- Architecture/components docs use clean, copy-safe paths.
+
+## Milestones (Track Progress)
+- [x] Replace weak sample narrative with repo-based chain.
+- [x] Upgrade architecture/components docs with concrete repo grounding.
+- [x] Publish rich overview and flow alignment.
+
+## Stories (Required to Complete)
+- [x] Story: STORY-2026-02-19-context-compass-release-readiness-examples - create complete example chain and align docs.
+
+## Tasks (Cross-Cutting or Epic-Level)
+- [x] Task: Complete story STORY-2026-02-19-context-compass-release-readiness-examples
+- [x] Task: Verify top-level example references and lane isolation.
+- [x] Task: Verify Ticket Microcycle enforcement across linked ticket docs.
+
+## Acceptance Criteria (Epic Done)
+- Example epic/story/task/artifact are present in `examples/example_*` lanes.
+- Rich overview exists in `examples/repo_overview.md`.
+- Top-level flow docs and system docs are coherent and evidence-ready.
+
+## Risks / Mitigations
+- Risk: docs drift and links break.
+  - Mitigation: run release grep checks for stale slugs and bad path patterns.
+
+## Applicable Anti-Patterns
+- [x] No epic-state transition without story-level evidence.
+- [x] No closure while required stories are incomplete or unaccepted.
+- [x] No program claims without source evidence from story/task notes.
+
+## Validation / Test Approach
+- `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`
+
+## 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-19T02:40:00Z
+  TYPE: FACT
+  CLAIM: top-level examples were not repository-grounded and lacked full ticket-chain depth.
+  EVIDENCE:
+  - `examples/eng_task_flow.md:1-30`
+  - `examples/adr_example.md:1-20`
+  IMPACT: poor onboarding and weak handoff reliability.
+  NEXT: replace with complete repo-based examples.
+  REREAD: REQUIRED
+  SCORE_0_TO_10: 9
+- DATETIME: 2026-02-19T03:10:00Z
+  TYPE: FACT
+  CLAIM: new example chain and rich overview are in place and linked.
+  EVIDENCE:
+  - `examples/example_stories/2026-02-19_context_compass_release_readiness_examples_story.md:1-170`
+  - `examples/example_tasks/2026-02-19_context_compass_release_readiness_pack_task.md:1-200`
+  - `examples/repo_overview.md:1-130`
+  IMPACT: public users can follow a complete, repo-native workflow.
+  NEXT: request user acceptance and close.
+  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
+This epic now anchors a full repo-based example workflow under `examples/`.
+Story and task are complete; only user acceptance remains for closure.
+
+
+

contextcompass_cli/_package/examples/example_graph_details/README.md

@@ -0,0 +1,131 @@
+# example_graph_details
+
+Shape reference for the generated source graph.
+
+The graph is **derived from source code**, not authored. Two files are produced
+by `tools/system_documents/python/`, and neither ships in `system_docs/` - a
+fresh install has neither, and that is expected:
+
+- `system_docs/src_graph.md` - one section per source file
+- `system_docs/src_graph_index.md` - line ranges into it, plus staleness proof
+
+## This example is reproducible
+
+`src/example/` here is a real six-file Python package, and `src_graph.md` /
+`src_graph_index.md` are the unmodified output of running the real pipeline over
+it. Nothing was hand-written, trimmed, or annotated afterwards.
+
+```bash
+cd context_compass/examples/example_graph_details
+python ../../tools/system_documents/python/extract_graph.py --src src --out /tmp/desc
+python ../../tools/system_documents/python/assemble_graph.py --descriptors /tmp/desc --out /tmp/out
+```
+
+The result matches what ships here, except for the authored fields - those are
+tier 3 and were added to the descriptors by hand, which is exactly the documented
+workflow. That is the point of the example: it shows both what the extractor
+recovers and what a human has to supply.
+
+Because the output is unmodified, **the index actually proves the document**.
+Recompute `line_count` and `content_sha256` over `src_graph.md` and they match
+the staleness proof, and every range lands on its own `BEGIN FILE` / `END FILE`
+delimiter. An example you can verify is worth more than one you have to trust.
+
+## What a section looks like
+
+Each source file gets one section, delimited by HTML comments naming the file.
+Line ranges for every section live in the index; read the index and slice, never
+scan the document for delimiters.
+
+The `BEGIN FILE` / `END FILE` comments are the section boundaries. They do not
+render, and the index's ranges are measured against them - a section written
+without them is not addressable.
+
+See `src_graph.md` lines 80-124 for the richest section: a class with derived
+and authored edges, authored semantics, and unconfirmed candidates side by side.
+
+## What is derived and what is authored
+
+This distinction is the whole contract. Measured against a hand-authored graph
+of 535 nodes and 997 edges:
+
+| field | origin | recovery |
+|---|---|---|
+| `id`, `label`, `kind`, `file`, `lineno`, `bases`, `public_methods` | derived | 94% |
+| `specializes`, `implements` | derived | 94%, targets resolved 99% |
+| `creates` | **candidate only** | 57%, over-generated ~8x |
+| `role`, `responsibilities`, `owns_state`, `phases` | authored | not derivable |
+| `owns_lifecycle_of`, `uses`, `borrows` | authored | **not derivable** |
+
+`owns_lifecycle_of`, `uses`, and `borrows` are syntactically identical - each is
+"A holds a reference to B". Which one it is, is a design fact that appears
+nowhere in the source text. That is 68% of all edges, and it is why the graph has
+an authored layer at all.
+
+You can see it in this example. `Pipeline` holds a `Stage` list and a `Store`
+reference. The AST shows both as attributes; only a human knows the pipeline owns
+its stages and borrows the store. The extractor emitted neither edge.
+
+And because the claim is authored, the reason is shown next to it:
+
+```
+| `..Pipeline` | owns_lifecycle_of | `..Stage` | one_to_many | init,runtime,cleanup | authored |
+| `..Pipeline` | borrows           | `..Store` | many_to_one | runtime             | authored |
+
+- `..Pipeline` -> `..Stage`: Pipeline constructs its stages in __init__ and is the
+  only object that can release them, so the stage list dies with the run.
+- `..Pipeline` -> `..Store`: The store is passed in and outlives the pipeline.
+  Releasing the pipeline must not close it - several pipelines share one store.
+```
+
+Derived rows carry `-` in the authored columns. That is not missing data: it is
+the graph saying nobody has authored that relationship's semantics yet.
+
+`why` sits beneath the table rather than in it, so the table stays scannable. On
+this example the whole authored layer costs 3 lines out of 192, and you never pay
+it on a read you did not ask for - you slice one section, not the document.
+
+A node marked **UNSEMANTIC** carries mechanical scaffold and no meaning yet. Its
+structure is trustworthy; do not infer its purpose from its name.
+
+## Two index shapes, do not confuse them
+
+`src_graph.md` is GENERATED, so its index is emitted by `assemble_graph.py` in
+the same pass - keyed by **source path**. Authored documents get their index from
+`index_document.py` by walking headings - keyed by **heading breadcrumb**.
+
+Running `index_document.py` against `src_graph.md` produces a heading-shaped
+index of `## src/...` and `### Nodes` sections. It parses, but it is the wrong
+artifact: it indexes the rendering rather than the files, and every section named
+`Nodes` collides. The tool will warn about the collision.
+
+## Index shape
+
+```markdown
+| lines | source | nodes | edges |
+| --- | --- | --- | --- |
+| 11-26 | `src/example/__init__.py` | 1 | 0 |
+| 80-124 | `src/example/pipeline/pipeline.py` | 2 | 3 |
+```
+
+The `edges` count covers derived and authored edges together, matching what that
+section's `Edges out` table renders. Candidates are not counted - they are
+guesses, not edges.
+
+Every row is keyed by a name - here the source path. No index in this system uses
+a bare number as identity: a row keyed by a number tells a reader nothing about
+whether to read it.
+
+## Files here
+
+- `src/example/` - a six-file Python package, the input
+- `src_graph.md` - unmodified assembler output over that package
+- `src_graph_index.md` - unmodified index from the same pass
+- this README
+
+## References
+
+- `agent_onboarding/default/engineer/skills/src_graph_generation.md` - building
+- `agent_onboarding/default/engineer/skills/src_graph_usage.md` - reading
+- `agent_onboarding/default/engineer/skills/system_document_build.md` -
+  the authored documents and their indexes

contextcompass_cli/_package/examples/example_graph_details/src/example/__init__.py

@@ -0,0 +1,4 @@
+"""Example package root."""
+from example.pipeline.pipeline import Pipeline
+
+__all__ = ["Pipeline"]

contextcompass_cli/_package/examples/example_graph_details/src/example/core/interfaces.py

@@ -0,0 +1,10 @@
+"""Structural mirrors of the core contracts."""
+from typing import Protocol
+
+
+class IResource(Protocol):
+    """Structural mirror of Resource's public surface."""
+
+    def acquire(self) -> None: ...
+    def release(self) -> None: ...
+    def is_open(self) -> bool: ...

contextcompass_cli/_package/examples/example_graph_details/src/example/core/resource.py

@@ -0,0 +1,15 @@
+"""Base resource contract."""
+from abc import ABC, abstractmethod
+
+
+class Resource(ABC):
+    """Anything with an acquire/release lifecycle."""
+
+    @abstractmethod
+    def acquire(self) -> None: ...
+
+    @abstractmethod
+    def release(self) -> None: ...
+
+    def is_open(self) -> bool:
+        return False

contextcompass_cli/_package/examples/example_graph_details/src/example/pipeline/pipeline.py

@@ -0,0 +1,20 @@
+"""Pipeline execution scope."""
+from threading import RLock
+from example.core.resource import Resource
+from example.pipeline.stage import Stage
+from example.storage.store import Store
+
+
+class Pipeline(Resource):
+    """Execution scope that owns its stages and borrows a store."""
+
+    def __init__(self, store: Store) -> None:
+        self._lock = RLock()
+        self._stages: list[Stage] = [Stage("load"), Stage("validate")]
+        self._store = store
+
+    def acquire(self) -> None: ...
+    def release(self) -> None: ...
+    def add_stage(self, stage: Stage) -> None: ...
+    def run(self, payload: bytes) -> bytes: ...
+    def stage_names(self) -> list[str]: ...

contextcompass_cli/_package/examples/example_graph_details/src/example/pipeline/stage.py

@@ -0,0 +1,11 @@
+"""A single unit of work in a pipeline."""
+
+
+class Stage:
+    """One transformation step."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def run(self, payload: bytes) -> bytes: ...
+    def describe(self) -> str: ...