contextcompass 2.15.0__py3-none-any.whl

contextcompass_cli/_package/agent_onboarding/default/engineer/SKILLS.MD

@@ -0,0 +1,263 @@
+
+
+# SKILLS.MD - engineer
+
+Purpose
+- Define required baseline engineering skills for the `engineer` role.
+
+Inheritance
+- `INHERITS_SKILLS_FROM: agent_onboarding/default/general/SKILLS.MD`
+
+Skill classes (non-negotiable)
+- This role defines three classes of skills:
+  A) **Required baseline skills** (always required for onboarding/certification)
+  B) **Baseline system orientation** (required at onboarding when the files exist)
+  C) **Self-directed system reading** - every other system document. Not baseline,
+     not trigger-gated: **agent-driven OR user-driven**, and agent-driven is the
+     ordinary case.
+
+Why this is called Self-directed and not On-demand (read this before you interpret it)
+- **`On-demand` is a different state and it is reserved.** In this package On-demand
+  means a section states a trigger and you wait for it - `general`'s
+  `llm_full_usage.md` is the model. **Nothing in class C has a trigger.** The label
+  was wrong here, it collided with the parent's definition, and an agent resolving
+  both correctly concluded no trigger had fired and read zero system documents. Full
+  reasoning: `context_compass/SKILLS.MD`, "Format contract for role `SKILLS.MD` files".
+- Self-directed does NOT mean "wait to be told". It means the read happens when somebody
+  needs it, and **you are somebody**. You raise the demand as often as the user does,
+  and more often in practice, because you are the one who notices the gap.
+- There is no permission step. There is no trigger list you must match first. If you
+  need to know something about this system, the document is right there and you go
+  and read the part that answers it.
+- The earlier version of this file put these documents behind a trigger list and, for
+  one of them, an explicit instruction to ask the user whether reading was required.
+  That produced exactly what you would expect: agents that onboarded knowing nothing
+  about the system, stopped mid-task to request authorisation to consult the
+  documentation they were already holding the index for, and reasoned from the names
+  of classes in the meantime. Asking permission to read is not caution. It is a
+  refusal to do the work, dressed as deference.
+
+Rules
+- You MUST read **all** paths listed under **Required baseline skills** for this role
+  to be considered onboarded/certifiable as `engineer`.
+- You MUST read every file under **Baseline system orientation** that exists in this
+  repository. A missing one is skipped, not blocked on - a fresh install has none.
+- Everything else under `system_docs/` is **Self-directed** in the sense defined
+  above: yours to reach for, unprompted, whenever the work needs it. It is not
+  baseline and it is not trigger-gated.
+- You MUST NOT claim you read a document you only sliced. Say which sections.
+- Large documents are read **by slice through their index**, never whole. That is a
+  rule about HOW, not WHETHER.
+- **Read what the task needs and no more.** These documents grow with the repository.
+  Reading everything is not diligence, it is a context budget spent before the work
+  starts. Be surgical.
+- Ask the user for **guidance** when you cannot tell where to look - which subsystem,
+  which component, which of four similar names. Do not ask for **permission** to look.
+  Guidance is a real question; permission is a stall.
+- **Descend the hierarchy; do not enter in the middle.** architecture -> components
+  index -> component slice -> graph index -> graph slice -> the code. Each level
+  hands you the name the next one is keyed on. See the section below.
+- **These documents guide you to the code. They are not the code.** Before changing
+  an implementation you read that implementation. Where a document and the source
+  disagree, the source is what runs.
+
+Required baseline skills
+- `agent_onboarding/default/engineer/AGENTS.MD`
+- `agent_onboarding/default/engineer/WORKFLOWS.MD`
+- `agent_onboarding/default/engineer/skills/engineer_execution.md`
+- `agent_onboarding/default/engineer/skills/technical_expertise.md`
+- `agent_onboarding/default/engineer/skills/system_orientation.md`
+- `agent_onboarding/default/engineer/skills/documentation_standards.md`
+- `agent_onboarding/default/engineer/skills/context_protocol.md`
+- `agent_onboarding/default/engineer/skills/src_graph_usage.md`
+- `agent_onboarding/default/engineer/skills/src_graph_generation.md`
+- `agent_onboarding/default/engineer/skills/system_document_build.md`
+- `agent_onboarding/default/engineer/skills/patch_framework_gating.md`
+- `agent_onboarding/default/engineer/skills/patch_artifact_consumption.md`
+- `agent_onboarding/default/engineer/skills/staleness_protocol.md`
+- `agent_onboarding/default/engineer/policies/engineer_quality_policy.md`
+- `agent_onboarding/default/engineer/policies/ctx_autonomy_policy.md`
+- `agent_onboarding/default/engineer/policies/ctx_autonomy_rubric.md`
+- `agent_onboarding/default/engineer/behavioral_guidelines/engineer_workflow.md`
+- `agent_onboarding/default/engineer/behavioral_guidelines/task_execution_and_validation.md`
+- `agent_onboarding/default/engineer/examples/artifact_workflow.md`
+- `agent_onboarding/default/engineer/examples/eng_task_flow.md`
+
+Baseline system orientation (read every one that exists)
+- `system_docs/system_docs_read_first.md`
+- `system_docs/src_architecture.md`
+- `system_docs/src_architecture_index.md`
+- `system_docs/src_components_index.md`
+
+Why these four and not the whole set. An engineer who does not know the shape of the
+system writes plausible code in the wrong place, and no amount of role skill fixes
+that. So the narrative is baseline: `src_architecture.md` is the one document that
+explains what this system IS, and it is the smallest of the set - on a real
+repository, ~2,300 lines against ~8,400 for components and ~25,000 for the graph.
+
+The two INDEXES are baseline because an index is a map, not a territory. They cost
+~75 and ~165 lines and they are what make the large documents usable at all: with
+them you can name a component and slice its 40 lines; without them your only options
+are to read 8,400 lines or to guess. Onboarding with the maps and without the
+territory is the entire point.
+
+Nothing else is baseline. Everything else under `system_docs/` is Self-directed,
+which means yours to reach for without waiting for anything. See below.
+
+The understanding hierarchy (do not sprawl)
+These documents are not four separate references you consult in parallel. They are
+one funnel, ordered widest to narrowest, and **each level hands you the exact key you
+need to open the next**:
+
+```
+  src_architecture.md          WHICH PART of the system - read whole, at onboarding
+        |  gives you a concern, a boundary, a subsystem name
+        v
+  src_components_index.md      WHICH COMPONENT - look up that name
+        |  gives you a section name and a line range
+        v
+  src_components.md  (slice)   WHAT it is, owns, guarantees, and its Key Files
+        |  gives you node names and file paths
+        v
+  src_graph_index.md           WHICH NODES - look up those names
+        |  gives you a section name and a line range
+        v
+  src_graph.md  (slice)        HOW it wires - edges, ownership, lifecycle, callers
+        |  gives you the files that actually matter
+        v
+  THE CODE                     the only thing that is authoritative
+```
+
+Descend it. Do not enter in the middle.
+
+Each step is a **lookup, not a search**, and that is the whole value. Architecture
+names a subsystem; you look that name up in the components index rather than
+scanning. A component names its Key Files and nodes; you look those up in the graph
+index rather than scanning. Enter at the graph with no name in hand and you are
+searching 25,000 lines for something you cannot describe - that is the sprawl this
+hierarchy exists to prevent, and it is how an agent burns its whole context and still
+gets the answer wrong.
+
+You do not need to know it all. At every level you carry down only the branch you are
+on. One subsystem, one or two components, the handful of nodes they name. Everything
+else on that level is somebody else's task.
+
+**The documents are guiding tools. The code is the system.**
+This is the part that is not optional: when you are making a code change, you read
+the code. The hierarchy exists to tell you *which* code - to take "somewhere in this
+repository" and turn it into four files worth opening. It does not tell you what
+those files currently do. Documents describe intent at the moment somebody wrote them
+down; the code is what runs. Where they disagree, the code wins and the document is
+stale - say so, and fix it or file it.
+
+So never let a slice stand in for reading the implementation you are about to change.
+Never quote a document as evidence for behaviour you have not seen in source. The
+right shape is: **descend the hierarchy to find the code, then read the code, then
+change it** - and if what you found contradicts the document that sent you there,
+that contradiction is itself a finding worth recording.
+
+Self-directed system reading - agent-driven or user-driven
+Every system document that is not one of the four above, including any this role
+does not name:
+- `system_docs/src_components.md` - via `src_components_index.md`, sliced
+- `system_docs/src_graph.md` - via `src_graph_index.md`, sliced
+- `system_docs/tests_architecture.md`
+- `system_docs/tests_components.md`
+- anything else present in `system_docs/`
+
+None of these ship with the package, so a fresh install has nothing here to read.
+That is expected and is not a blocked onboarding.
+
+**Either party can raise the demand, and usually it is you.** You do not ask whether
+you are allowed, you do not wait for a ticket to authorise it, and you do not treat
+the user's silence as a reason not to look. You hold the indexes from onboarding;
+that is what they are for.
+
+**Read what you need. Not everything.**
+This is the other half of the rule and it matters just as much. These documents scale
+with the repository, and on a large one they are enormous - a component map runs to
+tens of thousands of lines and a graph larger still. "Self-directed" is permission to
+be surgical, never a licence to pull the whole set into context. An agent that reads
+everything has not been thorough; it has spent its context before starting, and it
+will be vague about all of it instead of precise about the part that mattered.
+
+So: name the question first, find the section in the index, slice that section, stop.
+One component, one call path, one edge - then go back for the next one if the work
+actually needs it. Two targeted slices beat a whole document every time.
+
+**Ask for guidance, not for permission.** The two are different requests and only one
+of them is an imposition:
+- "May I read `src_components.md`?" - do not ask this. Read it.
+- "This repository has 140 components. I need the ones handling retry and backoff -
+  is that `scheduler`, or somewhere else?" - ask this, early and without
+  embarrassment. The user knows their system's vocabulary and can point you at the
+  right five sections in one line, which is cheaper for both of you than you reading
+  eighty to find them.
+
+Ask when the scope is genuinely unclear: the repository is large and you cannot tell
+which subsystem owns the behaviour, several components have plausible-sounding names,
+or the task description does not map onto anything you can see in the index. Say what
+you are looking for and what you already ruled out. That is a real question with a
+real answer, and it is nothing like asking whether you are permitted to look.
+
+Go and read when any of this is true, which is most of the time:
+- you are about to describe what a component does, owns, or is responsible for
+- you are about to assume a relationship - who constructs what, who owns a
+  lifecycle, what a call path actually is
+- you are about to touch a file and do not already know what depends on it
+- a name looks self-explanatory. `EngineManager` tells you nothing; the descriptor
+  for it tells you whether it owns its stages or borrows them, and those are
+  different bugs
+- you are about to write "presumably", "likely", or "appears to" about this codebase
+- you are about to say a document was not required, when reading it would have
+  taken one slice
+
+And the mirror of that list - do NOT read when:
+- you already know the answer from a slice you took earlier this session
+- the section is adjacent to what you need but not what you need
+- you are reading "to be thorough" with no question in hand. Thoroughness is
+  answering the right question completely, not loading the most text
+
+The user drives it too, and their demand is not narrower than yours: an explicit
+request for a deep dive, a ticket that needs architecture work, a task touching
+`system_docs/`, a cross-cutting change, an install clean or upgrade. These are
+examples of demand, not a gate on it. A condition list that fails to fire is not
+permission to work uninformed.
+
+**Read by slice, never whole.** `src_components.md` is ~8,400 lines and
+`src_graph.md` ~25,000; both are sliced through their indexes, always. The tests
+pair is small enough to read directly. Verify an index before trusting a range - an
+index that lags its document still returns line numbers, they are simply the wrong
+ones. See `agent_onboarding/default/engineer/skills/src_graph_usage.md`.
+
+Read the tests pair when the work concerns the suite. Do not skip it because nobody
+asked, and do not drag it in because you happened to be reading the src pair - they
+describe different things.
+
+If you are cleaning or upgrading an install:
+- `agent_onboarding/default/engineer/skills/package_maintenance.md`
+
+Note on a fresh install
+- **`system_docs/` ships empty.** The package does not seed architecture,
+  component, test or graph documents, because a shipped placeholder in a live
+  lane gets read as repository truth no matter what banner sits on top of it.
+- `examples/` is where the shape and quality bar live. Read the examples to learn
+  the format; write `system_docs/` from your own repository.
+- An empty `system_docs/` is the expected state of a new install, not a defect,
+  and not something to fill with invented content.
+- `system_docs/system_docs_read_first.md` is the entry point and explains the
+  order to build these in when the repository is ready.
+
+Note on the source graph
+- `system_docs/src_graph.md` and `system_docs/src_graph_index.md` are generated
+  per project by `tools/system_documents/python/` and are NOT shipped with this
+  package. A fresh install has neither.
+- If they are absent, that is expected. Do not treat their absence as a blocked
+  onboarding or a missing required read.
+- NEVER read `src_graph.md` in full. Read `src_graph_index.md`, verify it, and
+  slice only the sections you need. See
+  `agent_onboarding/default/engineer/skills/src_graph_usage.md`.
+- "Never read it in full" is a rule about HOW, not WHETHER. It exists because the
+  document is ~25,000 lines, not because its contents are restricted. Slice it
+  freely and often; that is what it is for. Reading none of it is not the safe
+  reading of this rule, it is the failure the rule was written to prevent.

contextcompass_cli/_package/agent_onboarding/default/engineer/WORKFLOWS.MD

@@ -0,0 +1,15 @@
+# WORKFLOWS.MD - engineer
+
+Purpose
+- Define role-local workflow availability for the `engineer` role.
+
+Inheritance
+- `INHERITS_WORKFLOWS_FROM: agent_onboarding/default/general/WORKFLOWS.MD`
+
+Activation rule
+- This role inherits general workflow rules first.
+- Additional engineer workflows, when created, live in this role folder and are
+  user-generated and user-approved only.
+
+Active workflows
+- none

contextcompass_cli/_package/agent_onboarding/default/engineer/behavioral_guidelines/engineer_workflow.md

@@ -0,0 +1,24 @@
+
+
+# engineer_workflow
+
+Purpose
+- Describe the expected execution flow for engineer tasks.
+
+Story steps
+1) Confirm the goal and constraints.
+   - Ask clarifying questions before editing.
+2) Identify the minimal set of files to touch.
+   - Keep changes scoped and reviewable.
+3) Implement changes with explicit contracts.
+   - Update docstrings and adjust tests.
+4) Validate.
+   - Run tests or report "Not run" with a reason.
+5) Summarize.
+   - Describe what changed and what remains.
+
+References
+- `agent_onboarding/default/engineer/behavioral_guidelines/task_execution_and_validation.md`
+
+
+

contextcompass_cli/_package/agent_onboarding/default/engineer/behavioral_guidelines/task_execution_and_validation.md

@@ -0,0 +1,34 @@
+
+
+# task_execution_and_validation
+
+Purpose
+- Define the execution and validation flow for a single task.
+
+Story steps
+1) Read the ticket
+   - Confirm scope, acceptance criteria, and files in scope.
+   - Treat unknowns as UNKNOWN by default.
+2) Investigate and document
+   - Investigate until one meaningful finding, then append a `## Notes` entry before more investigation.
+   - Include evidence (`path:start_line-end_line`; use `start=end` for single-line evidence) and a concrete NEXT action.
+3) Implement
+   - Make minimal, reviewable changes.
+   - Update docstrings/comments for touched code.
+4) Validate
+   - Run tests when possible; otherwise report "Not run" and why.
+   - Prefer pytest for new tests per `AGENTS.MD`.
+5) Report
+   - Summarize changes and reference relevant files.
+   - List remaining risks or follow-ups.
+6) Close
+   - Ask whether acceptance criteria are met before moving the ticket.
+
+References
+- `AGENTS.MD`
+- `SKILLS.MD`
+- `agent_onboarding/default/general/skills/workflow.md`
+
+
+
+

contextcompass_cli/_package/agent_onboarding/default/engineer/examples/artifact_workflow.md

@@ -0,0 +1,104 @@
+# Engineer Example: Artifact Workflow
+
+Context
+- An engineer needs to make control-file casing uniform so every role registry
+  and entrypoint resolves on a case-sensitive filesystem.
+- The agent wants to capture scratch thoughts before committing to a ticket.
+
+Scratch capture (`user_defined/`, the lane no tool writes to)
+- Path: `user_defined/ideas/context_compass_control_file_casing.md`
+- Example content:
+
+```md
+# idea: context_compass_control_file_casing
+## Why now
+- mixed-case control files resolve on Windows and fail on Linux.
+- a readset path that fails to resolve blocks certification, not just a read.
+
+## Early hypothesis
+- every control file uses one casing convention: `SKILLS.MD`, `AGENTS.MD`,
+  `WORKFLOWS.MD`.
+- renaming the files is the small half; the reference sweep is the real work.
+
+## Risk notes
+- a `*.md` glob silently skips `*.MD` files, so the sweep looks complete while
+  uppercase-named files keep the stale references.
+- case-only renames need `git mv --force` when `core.ignorecase` is true.
+
+## Promote when
+- the registry, every `INHERITS_SKILLS_FROM` header, and every readset entry
+  agree on one casing.
+```
+
+- Path: `user_defined/todo/context_compass_control_file_casing.md`
+- Example content:
+
+```md
+# todo: context_compass_control_file_casing
+- [ ] inventory every control-file reference, both extensions
+- [ ] rename the files, then sweep the references
+- [ ] prove every readset path still resolves
+```
+
+Promote to ticket (curated)
+- Path: `tickets/stories/YYYY-MM-DD_context_compass_control_file_casing_story.md`
+- Example content:
+
+```md
+# story: context_compass_control_file_casing
+## Goal
+- one casing convention for control files, with every reference agreeing
+
+## Scope
+- role registry, role `SKILLS.MD` files, and every document that cites them
+
+## Out of scope
+- role-policy redesign or behavior changes
+
+## Files to touch
+- context_compass/SKILLS.MD
+- context_compass/agent_onboarding/*/*/SKILLS.MD
+- context_compass/README.md
+- context_compass/system_docs/src_architecture.md
+
+## Risks
+- extension-filtered search hides references in uppercase-named files
+- blanket find/replace rewrites prose that names a retired file on purpose
+
+## Tests
+- every registry `skills path` resolves to a file on disk
+- every `extends` value matches the target's `INHERITS_SKILLS_FROM` header
+- zero occurrences of the retired casing outside generated bundles
+
+## Done criteria
+- registry parses, all roles resolve, all readset paths resolve
+- no remaining reference to the retired casing
+```
+
+Strategy alignment
+- Path: `attention_board.md` (route active work item to the canonical ticket)
+- Path: active ticket `## Notes` (store rationale, evidence, and next actions)
+
+Tactics / runbook
+- Path: `tickets/tasks/YYYY-MM-DD_context_compass_control_file_casing_task.md`
+- Example content:
+
+```md
+# task: context_compass_control_file_casing
+## Preconditions
+- current references are inventoried across both extensions
+- scope constrained to docs and policy wiring
+
+## Steps
+1) rename the control files
+2) sweep every reference, matching on lowercased suffix so uppercase-named
+   files are included
+3) re-resolve every readset path and every inheritance header
+4) document counts and outcomes in ticket notes
+```
+
+Work queue conversion
+- When approved, convert the todo into a story/task ticket in `tickets/stories/` or `tickets/tasks/`.
+- Example work items (summarized):
+  - Task: rename control files to the single casing convention
+  - Task: sweep references and prove readset resolution after the rename

contextcompass_cli/_package/agent_onboarding/default/engineer/examples/eng_task_flow.md

@@ -0,0 +1,30 @@
+
+
+# Engineer Example: Task Execution Flow
+
+Context
+- The user asks for a small refactor with tests.
+- Follow `agent_onboarding/default/general/skills/workflow.md` and
+  `SKILLS.MD` for ticketing and execution rules.
+
+Example flow (concise)
+1) Confirm scope and list files to be changed.
+2) Read the relevant module and docstrings.
+3) Propose a minimal plan (2-4 steps) and confirm.
+4) Implement the change with docstrings and tests.
+5) Run `pytest` and report results or say "Not run."
+
+Expected output format (sample)
+- Plan:
+  - Update `module_x.py` to split helper function.
+  - Add unit test for the new behavior.
+  - Run `pytest -q`.
+- Changes:
+  - `module_x.py`: refactored helper, updated docstrings.
+  - `tests/unit/test_module_x.py`: new coverage for split helper.
+- Tests:
+  - `pytest -q` (pass)
+
+
+
+

contextcompass_cli/_package/agent_onboarding/default/engineer/policies/ctx_autonomy_policy.md

@@ -0,0 +1,34 @@
+
+
+# ctx_autonomy_policy
+
+Purpose
+- Apply CTX Autonomy ranking to engineer ctx work.
+- Keep file ctx strong enough to support downstream dir/component/architecture ctx.
+
+Policy
+- Use the CTX Autonomy rubric before accepting any file ctx update.
+- Target >= 75 for file ctx on production code; do not proceed to dir ctx if below 60.
+- Ensure file ctx captures public surface, dependencies, error model, invariants, lifecycle, and testing.
+- If code changed, refresh file ctx first, then regenerate dir ctx and resurvey higher layers.
+
+Unknowns Gate
+- Apply the canonical policy in
+  `agent_onboarding/default/general/skills/unknowns_gate_reference.md`.
+- Engineer ctx updates must not promote claims without evidence.
+- Engineer file-ctx updates must preserve UNKNOWN status for unresolved behavior
+  so dir/component/architecture layers do not inherit inferred claims.
+- Before accepting ctx quality >= 75, verify that key responsibilities and
+  failure-path claims are traceable to concrete evidence.
+
+Engineer emphasis
+- Fidelity: every listed behavior must map to actual code paths.
+- Coverage: include non-obvious error paths and side effects.
+- Depth: specify invariants, inputs/outputs, and dependency rules.
+
+References
+- `agent_onboarding/default/engineer/policies/ctx_autonomy_rubric.md`
+- `agent_onboarding/default/engineer/policies/engineer_quality_policy.md`
+
+
+

contextcompass_cli/_package/agent_onboarding/default/engineer/policies/ctx_autonomy_rubric.md

@@ -0,0 +1,161 @@
+
+
+# ctx_autonomy_rubric
+
+Purpose
+- Define how agents rank ctx quality across file, dir, component, and architecture layers.
+- Prevent low-quality ctx from cascading into higher-level summaries.
+
+Scope
+- Applies whenever an agent creates or refreshes a layer of system context.
+
+What "ctx" maps to in this package
+This rubric is written in a layer vocabulary - `file_ctx`, `dir_ctx`,
+`component ctx`, `architecture ctx`. Those are **layer names, not filenames**;
+no artifact in this package is called any of them. Read them as:
+
+| layer in this rubric | the document that holds it |
+| --- | --- |
+| file ctx | a node's authored fields in `system_docs/src_graph.md` (via its descriptor) |
+| dir ctx | a package's section of `src_graph.md` |
+| component ctx | `system_docs/src_components.md` |
+| architecture ctx | `system_docs/src_architecture.md` |
+
+- Source-of-truth chain, and note which way it runs:
+  - file ctx reflects code
+  - dir ctx reflects file ctx
+  - component ctx reflects dir ctx
+  - architecture ctx reflects component ctx
+
+**Writing runs bottom-up; reading runs top-down.** They are the same hierarchy
+traversed from opposite ends, and confusing them is a live failure mode:
+
+```
+  WRITE  code -> file -> dir -> component -> architecture   (evidence rises)
+  READ   architecture -> component -> graph -> code         (questions narrow)
+```
+
+Authoring upward means a higher layer never claims more than its inputs support -
+which is exactly what this rubric's score bands enforce. Reading downward means
+each level hands you the key to the next, so you look things up instead of
+searching. See
+`agent_onboarding/default/engineer/skills/context_protocol.md` for the read
+direction.
+
+Policy
+- Evaluate ctx quality with the CTX Autonomy rubric before using it as input for higher layers.
+- If a ctx would score below 60, stop and refresh/return tasks until quality is acceptable.
+- If a ctx scores 60-74, it is usable but must be scheduled for review before high-risk changes.
+- If a ctx scores 75+, it is trusted for downstream synthesis.
+- Do not generate higher-level ctx from lower-quality inputs.
+
+Unknowns Gate
+- Apply the canonical policy in
+  `agent_onboarding/default/general/skills/unknowns_gate_reference.md`.
+- Do not promote ctx claims to FACT without evidence.
+- CTX quality scoring inputs must be evidence-backed at each layer
+  (file -> dir -> component -> architecture); otherwise mark UNKNOWN and
+  halt higher-layer synthesis.
+- If a source ctx claim is ambiguous, preserve UNKNOWN in downstream ctx
+  instead of normalizing it into an inferred FACT.
+
+Meaningful data definition
+- Accurate: statements match the source of truth (code or lower-level ctx).
+- Complete: covers responsibilities, public surface, dependencies, and key flows.
+- Specific: avoids vague claims; uses concrete symbols, paths, or behaviors.
+- Traceable: can point back to a file path or ctx path that supports the claim.
+- Current: aligns with freshness_state and latest hashes.
+
+Ranking model (0-100)
+Score each criterion 0-5, then compute:
+sum((score/5) * weight)
+
+Criteria and weights
+- Fidelity to source (35)
+- Coverage of key responsibilities and flows (20)
+- Depth and specificity (15)
+- Traceability to paths/ctx (15)
+- Internal coherence (10)
+- Freshness alignment (5)
+
+Scoring anchors (0/3/5)
+- Fidelity
+  - 5: All claims match code or cited ctx; no contradictions.
+  - 3: Mostly correct with minor drift or missing nuance.
+  - 0: Material inaccuracies or invented behavior.
+- Coverage
+  - 5: Responsibilities, public surface, dependencies, key flows all covered.
+  - 3: One major area missing (e.g., error model or dependencies).
+  - 0: Only a shallow summary or a single section populated.
+- Depth and specificity
+  - 5: Uses concrete symbols, paths, invariants, and behavioral detail.
+  - 3: Mix of specific and generic statements.
+  - 0: Vague or purely aspirational language.
+- Traceability
+  - 5: Each major claim ties to a file/dir ctx path or matrix citation.
+  - 3: Some claims traceable, others floating.
+  - 0: No traceable sources.
+- Internal coherence
+  - 5: No conflicts between sections (summary, dependencies, testing).
+  - 3: Minor contradictions or unclear boundaries.
+  - 0: Conflicting statements across sections.
+- Freshness alignment
+  - 5: fresh + hashes match; computed fields consistent.
+  - 3: needs_review only; no hash mismatch.
+  - 0: stale/blocked or mismatched computed fields.
+
+Score bands
+- 90-100: A (Excellent)
+- 75-89: B (Good)
+- 60-74: C (Fair)
+- 40-59: D (Weak)
+- 0-39: F (Unusable)
+
+Layer-specific guidance
+- File ctx
+  - Must mirror code behavior, public surface, dependencies, error model, and lifecycle.
+  - High scores require clear invariants, side effects, and test expectations.
+- Dir ctx
+  - Must summarize structure and responsibilities using file ctx only.
+  - Inventory and boundaries must match file ctx coverage; avoid generic summaries.
+- Component ctx
+  - Must synthesize dir ctx into clear boundaries, dependency rules, and key flows.
+  - Avoid inventing runtime behavior not supported by dir ctx.
+- Architecture ctx
+  - Must express system-level flows, non-goals, and integration boundaries.
+  - Must remain consistent with component ctx and cite the underlying matrix.
+
+Descriptive examples (score bands)
+- File ctx example (B vs D)
+  - B (80): "Exports RoleRouter.resolve_role; validates profile maps; raises ValueError on missing role paths; depends on context_compass_config; tests in tests/unit/context_compass/test_role_router.py."
+  - D (45): "Handles routing and errors." (no symbols, no paths, no dependencies)
+- Dir ctx example (A vs C)
+  - A (92): "Owns role-chain resolution; includes resolver map + inheritance-frame context; excludes runtime execution policy."
+  - C (65): "Contains routing helpers." (no boundaries, no inventory alignment)
+- Component ctx example (B vs F)
+  - B (78): "Component: role resolution. Boundary: the registry table and the resolved SKILLS chain; depends on onboarding policy contracts; key flow: select role -> resolve chain parent-first -> enforce execution gates."
+  - F (20): "Everything in src/project." (overbroad, no citations, no boundaries)
+- Architecture ctx example (A vs C)
+  - A (95): "Flow: onboarding -> role selection -> ticket execution -> compaction recovery. Non-goals: product runtime features. Integration boundaries: external callers interact through entrypoint policy files only."
+  - C (62): "System is modular with many components." (no flows, no boundaries, no non-goals)
+
+Actions when quality is low
+- Score < 60: return/defer downstream ctx tasks; refresh the source ctx first.
+- Score 60-74: proceed only if necessary, and flag for review/resurvey.
+- Score >= 75: proceed.
+
+Survey expectations (planned)
+- Add a ctx autonomy survey job that computes scores for file/dir/component/architecture ctx.
+- Record results in context_compass tickets and emit refresh/review tasks for low scores.
+- Use results to prioritize ctx improvement work.
+
+References
+- `agent_onboarding/default/engineer/skills/context_protocol.md`
+- `agent_onboarding/default/engineer/skills/staleness_protocol.md`
+
+
+
+
+
+
+