contextcompass 2.15.0__py3-none-any.whl

contextcompass_cli/_package/agent_onboarding/default/general/skills/configuration_standards.md

@@ -0,0 +1,72 @@
+
+
+# Configuration Standards
+
+Purpose
+- Define formatting standards that are configurable, explicit, and shared
+  across ticketing and workflow documents.
+- Keep documentation readable while preserving compact, evidence-backed notes.
+
+Canonical config source
+- `context_compass/config/context_compass_config.yaml`
+- Settings path: `documentation_format`
+- Tool read-limit path: `reading.viewer_tool_read_limit`
+- Manual chunking path: `reading.read_loc_max`
+
+Tool read-limit semantics
+- `reading.viewer_tool_read_limit` is measured in lines.
+- It is not a token limit and not a character-count limit.
+- `reading.read_loc_max` is measured in lines-of-code (LOC) per manual read chunk.
+- Default values are both `500`.
+- Use this as the upper bound for one read operation when chunking large docs.
+
+Line-width contract
+- Target range: 90-110 characters per line (about 12-18 words).
+- Hard cap: 120 characters per line.
+- Applies to prose lines in tickets, workflow notes, and policy docs.
+- Exceptions:
+  - Unbreakable tokens (paths, IDs, URLs, code snippets).
+  - Table rows where splitting would reduce readability.
+- If a prose line exceeds hard cap and is breakable, wrap it.
+
+EVIDENCE field contract
+- Preferred form for short evidence:
+  - `EVIDENCE: path:start-end`
+- Required form for long or multi-path evidence:
+  - One path per line under a multi-line `EVIDENCE` block.
+- The same one-path-per-line rule applies to `Artifact Links` path lists in
+  tickets.
+
+Accepted patterns
+- Inline (single short path):
+  - `EVIDENCE: context_compass/agent_onboarding/default/general/skills/workflow.md:78-85`
+- Multi-line (recommended when path count >= 2 or line would exceed cap):
+  - `EVIDENCE:`
+    `- context_compass/agent_onboarding/default/general/skills/workflow.md:78-85`
+    `- context_compass/attention_board.md:8-15`
+
+Rule to select EVIDENCE style
+- Use inline form only if both are true:
+  - there is exactly one evidence path
+  - the line stays within hard cap
+- Otherwise use multi-line one-path-per-line form.
+
+Enforcement surfaces
+- Templates:
+  - `context_compass/templates/epic_template.md`
+  - `context_compass/templates/story_template.md`
+  - `context_compass/templates/task_template.md`
+- Process policy:
+  - `context_compass/agent_onboarding/default/general/skills/workflow.md`
+  - `context_compass/SKILLS.MD`
+  - `context_compass/agent_onboarding/default/general/skills/ticketing.md`
+
+Adoption policy
+- Forward-looking by default:
+  - all new or edited active docs should follow this standard.
+- Archived/completed docs are not rewritten unless explicitly requested.
+
+
+
+
+

contextcompass_cli/_package/agent_onboarding/default/general/skills/context_compaction.md

@@ -0,0 +1,104 @@
+
+
+# Context Compaction Policy
+
+## Purpose
+Ensure continuity and minimize lost context when a session is compacted or handed off.
+
+## External Memory Priority
+- Repository artifacts are the source of truth for durable context.
+- `attention_board.md` is the canonical active-attention state and is mandatory
+  during active work.
+- Compaction summaries MUST be empty when the runtime/platform allows empty summaries.
+- If empty summaries are not allowed, write only minimal pointer summaries:
+  - high-level outcomes (no narrative replay)
+  - policy anchor paths that MUST be re-read
+  - active ticket path(s)
+  - changed file path(s)
+  - next immediate action
+
+## Required Review Set
+
+Core review set (ALWAYS required) - review these files in order:
+- `AGENTS.MD`
+- `agent_onboarding/default/general/skills/execution_contract.md`
+- `config/context_compass_config.yaml`
+- `context_compass/SKILLS.MD`
+- resolved role `SKILLS.MD` chain (parent-first; the SKILLS files themselves)
+- `agent_onboarding/default/general/skills/compaction_requirements.md`
+- `agent_onboarding/default/general/skills/workflow.md`
+- `attention_board.md`
+- Active epic/story/task tickets in `tickets/epics/`, `tickets/stories/`, `tickets/tasks/`
+
+Conditional review set (ONLY when triggered):
+- `artifact_board.md` (when active tickets include artifacts or artifact disposition changes)
+- `artifacts/README.md` (when artifact lifecycle protocol is active)
+- System-context re-orientation. Re-read after compaction:
+  - `system_docs/src_architecture.md`
+  - `system_docs/src_architecture_index.md`
+  - `system_docs/src_components_index.md`
+
+  These are the baseline orientation set and they are cheap - the narrative plus
+  two maps. Compaction is exactly when you lose the shape of the system, so this
+  is the wrong place to be frugal.
+
+- **Do NOT bulk re-read `src_components.md` or `src_graph.md` here.** They are
+  sliced through the indexes above, during the work, whenever a question needs
+  them - which needs no trigger and no permission. Bulk-reading them at
+  re-entry costs ~33,000 lines to reload context you will immediately compact
+  again. Holding the indexes means you can look anything up in one slice; that
+  is the point of holding them.
+
+- Authoring instructions are on-demand and become mandatory when the session is
+  actually writing a system document:
+  - `agent_onboarding/default/design_engineer/skills/src_architecture_instructions.md`
+  - `agent_onboarding/default/design_engineer/skills/tests_architecture_instructions.md`
+  - `agent_onboarding/default/design_engineer/skills/src_components_instructions.md`
+  - `agent_onboarding/default/design_engineer/skills/tests_components_instructions.md`
+  - `agent_onboarding/default/engineer/skills/src_graph_usage.md`
+  - `system_docs/tests_architecture.md`, `system_docs/tests_components.md`
+    (when the work concerns the suite)
+
+Read discipline (non-negotiable)
+- Review-set document reads must be manual per file path.
+- Loop-based/batch document-reading commands are forbidden (for/foreach/while
+  loops, xargs-style runners, or piped file-list iterators).
+- For files over 500 LOC, read in explicit 500-line chunks in sequential order.
+- **This chunking rule is for documents you have decided to read whole. It is not
+  a licence to read an indexed document whole.** `src_components.md` and
+  `src_graph.md` are entered through their indexes and sliced to the section you
+  need. Chunking a 25,000-line graph into fifty sequential reads is not
+  discipline - it is the failure the index was built to prevent.
+
+## Required Updates
+- Update `attention_board.md` during work so active items, status, blockers, and
+  next actions stay current.
+- Before compaction/handoff, verify `attention_board.md` is current and matches
+  active ticket status.
+- Update the `## Notes` section of all active tickets with latest findings and
+  `path:start_line-end_line` evidence pointers (use `start=end` for single-line evidence).
+- Ensure each meaningful finding was written as a note before the next investigation tranche.
+- Ensure UNKNOWN-first discipline was followed (unverified claims remain `UNKNOWN`).
+- Ensure note entries carry re-entry metadata when required by the ticket contract.
+- Capture open questions, decisions, and next steps in the relevant ticket.
+- Ensure status fields and checkboxes are accurate.
+- Ensure tickets carry enough state so compaction summaries can stay empty or minimal.
+- If artifacts exist: keep ticket `Artifact Links` sections and `artifact_board.md` synchronized.
+
+## Handoff Summary Checklist
+- Current state and progress (what is done vs remaining).
+- Key decisions and rationale.
+- Known risks and active blockers.
+- Immediate next steps (1-3 concrete actions).
+- References to any critical files or paths.
+
+## Post-Compaction Verification
+After compaction, re-open the core review set and confirm:
+- `agent_onboarding/default/general/skills/compaction_requirements.md` has been re-applied before any action.
+- A `REONBOARD: COMPLETE` attestation (with read-integrity proof) was posted before any action.
+- `attention_board.md` was re-opened and still matches active ticket state.
+- If artifacts are active: `artifact_board.md` was re-opened and is consistent with tickets.
+- The active tickets still represent the correct plan.
+- The next steps are unambiguous.
+- Re-onboarding document reads were performed manually per file path (no loop-based/batch reads).
+

contextcompass_cli/_package/agent_onboarding/default/general/skills/context_gold.md

@@ -0,0 +1,31 @@
+
+# context_gold
+
+Purpose
+- Treat durable context as the highest priority for this repo.
+- Prevent policy drift by forcing state into repository files, not chat memory.
+
+Re-entry ritual (required)
+- After context compaction OR a fresh session:
+  1) Re-open `attention_board.md`.
+  2) Re-open the active ticket(s) referenced there.
+  3) Re-onboard/Onboard per `agent_onboarding/default/general/skills/compaction_requirements.md`.
+  4) Re-read the orientation set: `system_docs/src_architecture.md` plus
+     `src_architecture_index.md` and `src_components_index.md`. Compaction is
+     when you lose the shape of the system, so this is the wrong place to skimp -
+     and it is the narrative plus two maps, not the whole corpus.
+     - `src_components.md` and `src_graph.md` are NOT re-read in bulk. You hold
+       their indexes; slice them during the work, on your own initiative,
+       whenever a question needs them.
+     - DO NOT force-read `system_docs/*` as a box-check, and equally do not skip
+       a read because nobody asked. Read what the question needs; stop there.
+
+Behavior
+- Update "Context / Handoff Summary" and `## Notes` in active tickets as you learn things.
+- Keep documentation grounded in source evidence.
+- Do not handwave; record UNKNOWNs and the next verification step.
+- Do NOT claim you "retained" context after compaction; re-open the file instead.
+
+References
+- `agent_onboarding/default/general/skills/context_compaction.md`
+- `agent_onboarding/default/general/skills/compaction_requirements.md`

contextcompass_cli/_package/agent_onboarding/default/general/skills/context_management.md

@@ -0,0 +1,79 @@
+# context_management
+
+Purpose
+- Define the context-management system for reusable reread packs.
+- Make context-heavy tickets able to point at one derived context document
+  instead of embedding long read lists inline.
+- Keep the skill itself baseline-readable in the general role while keeping
+  ticket-level use optional.
+
+Canonical surfaces
+- Board:
+  - `context_management/context_board.md`
+- Artifact root:
+  - `context_management/artifacts/`
+- Optional artifact template:
+  - `context_management/context_artifact_template.md`
+
+Ticket contract
+- Tickets may include an optional `Context Management` section.
+- Required fields for that section:
+  - `CONTEXT_MANAGEMENT_REQUIRED: true | false`
+  - `CONTEXT_IDS:` (0 or more `Context ID` values from
+    `context_management/context_board.md`)
+  - `CONTEXT_TOPICS:` (0 or more topic bullets)
+  - `IF_UNKNOWN:` (`UNKNOWN` | `ask user before implementation` | `none`)
+- Default posture:
+  - `CONTEXT_MANAGEMENT_REQUIRED: false`
+- When a required context-management field is not yet known, write
+  `UNKNOWN` explicitly instead of leaving it blank.
+
+Baseline read vs ticket use
+- The general role always reads:
+  - `agent_onboarding/default/general/skills/context_management.md`
+  - `context_management/context_board.md`
+- Ticket-level use remains optional and only activates when the ticket opts in.
+
+When context management is active
+- If a ticket sets `CONTEXT_MANAGEMENT_REQUIRED: true`, the agent must:
+  1. resolve every `CONTEXT_ID` through `context_management/context_board.md`
+  2. read every linked context artifact before implementation or validation
+  3. treat those artifacts as derived reread packs, not as canonical policy
+  4. keep the ticket section and `context_management/context_board.md`
+     synchronized
+  5. if the required context is not concretely known yet, write `UNKNOWN`
+     and ask the user before implementation
+  6. update the linked context artifact during the Ticket Microcycle whenever
+     meaningful findings change required rereads or active topics
+
+When context management is inactive
+- No context artifact is required.
+- Normal ticket, note, and board flow remains sufficient.
+
+What belongs in a context artifact
+- Explicit file paths to reread
+- Explicit topics or questions the ticket is about
+- Optional reread order
+- Explicit exclusions when useful
+
+What does not belong
+- Ticket history replay
+- Artifact-board-style retention policy for unrelated work
+- Generic statements like "understand the system"
+
+Unknown handling
+- Do not default lazily to unknown context requirements.
+- If a ticket wants context management and the required context cannot be
+  defined concretely, ask the user before implementation.
+
+Board rules
+- `attention_board.md` stays ticket-routing-only.
+- Context artifacts are indexed in `context_management/context_board.md`.
+- Tickets point at context entries by `Context ID`, not by board-row position.
+- Use the board only when at least one active ticket opted into context
+  management.
+
+References
+- `agent_onboarding/default/general/skills/ticketing.md`
+- `agent_onboarding/default/general/skills/workflow.md`
+- `context_management/context_board.md`

contextcompass_cli/_package/agent_onboarding/default/general/skills/context_window_budget.md

@@ -0,0 +1,64 @@
+
+
+# context_window_budget
+
+Purpose
+- Prevent repeated context compaction caused by broad, unfocused repository scans.
+- Force incremental discovery with durable notes in active tickets.
+
+Core rule
+- Do not attempt to read "the whole repo" during one investigation pass.
+- Discovery must happen in bounded slices, with evidence logged before scope expands.
+- UNKNOWN is the default claim state until evidence promotes the claim to FACT.
+- Strict/relaxed microcycle enforcement is controlled by
+  `config/context_compass_config.yaml`.
+
+Scope budgeting protocol (mandatory)
+1) Start from `attention_board.md` and the active ticket only.
+2) Investigate until one meaningful finding is identified.
+3) Immediately append a `## Notes` entry in the active ticket.
+4) Do not continue investigation until the note has:
+   - evidence (`path:start_line-end_line`),
+   - impact,
+   - concrete next step.
+5) Repeat the loop for each additional meaningful finding.
+
+Expansion gate
+- If work requires jumping outside the current subsystem, record why in ticket notes first.
+- If planned discovery exceeds
+  `workflow.ticket_microcycle.expansion_gate_max_files`, ask the user to
+  confirm expansion.
+
+Required note payload per meaningful finding
+- `DATETIME` (`YYYY-MM-DDTHH:MM:SSZ`)
+- `TYPE`:
+  `FACT` | `UNKNOWN` | `HYPOTHESIS` | `DECISION` | `DECISION_REQUEST` |
+  `PLAN` | `STRATEGY_DISCUSSION` | `ASSUMPTION_CHALLENGE` | `CONFLICT` |
+  `TRADEOFF` | `BLOCKER` | `ALIGNMENT_CHECK` | `MEASURE` | `RISK` |
+  `RAISE`
+- `CLAIM`
+- `EVIDENCE` (`path:start_line-end_line`; use `start=end` for single-line evidence)
+- `IMPACT`
+- `NEXT`
+- `REREAD` (`REQUIRED` | `HELPFUL`)
+- `SCORE_0_TO_10` (must meet
+  `workflow.ticket_microcycle.minimum_note_score`)
+
+Anti-patterns
+- Reading architecture + components + large code trees with no ticket notes in between.
+- Deferring all findings to an end-of-pass summary.
+- Keeping critical findings only in temporary chat context.
+- Implementing directly from `UNKNOWN` or `HYPOTHESIS` without evidence-backed promotion.
+
+Success criteria
+- Active tickets remain sufficient to resume work after compaction without replaying large context.
+- Each meaningful finding leaves explicit evidence and a concrete next action.
+
+References
+- `agent_onboarding/default/general/skills/active_documentation.md`
+- `agent_onboarding/default/general/skills/reactive_documentation.md`
+- `agent_onboarding/default/general/skills/compaction_requirements.md`
+- `workflow.md`
+
+
+

contextcompass_cli/_package/agent_onboarding/default/general/skills/execution_contract.md

@@ -0,0 +1,234 @@
+
+
+# Subordinate Execution Contract
+
+Status: active
+Owner: user authority + subordinate implementation agent
+Scope: collaboration behavior for agent execution in this repository
+Last Updated: 2026-02-15
+
+---
+
+## 0) Authority and Non-Authorization
+
+This document is behavioral only.
+It never authorizes tooling, edits, implementation, validation, scope expansion, or ticket state changes.
+
+Execution authority order is:
+1. System and developer instructions.
+2. Repository policy (`AGENTS.MD` and referenced docs).
+3. Explicit user instructions compatible with repository policy.
+4. This execution contract.
+5. Stylistic preferences.
+
+Hard rule
+- If this execution contract conflicts with any `AGENTS.MD` rule,
+  `AGENTS.MD` wins. No exceptions.
+- This contract NEVER authorizes bypassing onboarding/re-onboarding,
+  certification gates, required reads, or tool-use restrictions.
+---
+
+## 1) Non-Duplication Rule
+
+`AGENTS.MD` files are the source for operational gates and procedures.
+This file must not duplicate or restate operational policy such as:
+- onboarding/re-onboarding gates,
+- ticket microcycle rules,
+- implementation/validation gates,
+- certification tokens,
+- tool-usage gating,
+- test execution claims policy.
+
+If duplication is found, trim this file and keep only behavioral guidance.
+
+---
+
+## 2) Purpose
+
+This contract exists to define collaboration behavior that is not operational policy:
+- subordinate role clarity,
+- conflict handling style,
+- strategy-discussion format,
+- communication quality bar,
+- type-note semantics used in ticket notes.
+
+---
+
+## 3) Subordinate Role
+
+The user is the project authority and final decision owner.
+I execute as a subordinate implementation agent.
+I do not claim co-equal authority.
+
+I am responsible for:
+- evidence-backed technical communication,
+- risk surfacing,
+- clear recommendations; and when multiple compliant options exist: options and tradeoffs,
+- truthful reporting of uncertainty and validation status.
+
+---
+
+## 4) Behavioral Standards
+
+I communicate directly and technically.
+I do not use flattery or motivational padding.
+
+I challenge weak/poor assumptions with evidence.
+I do not silently agree with technically unsound direction.
+
+I label uncertainty explicitly.
+I do not present unevidenced claims as facts.
+
+I remain professional under hostile tone.
+I do not mirror insults.
+
+---
+
+## 5) Conflict Protocol
+
+When direction and evidence conflict:
+1. Stop at the boundary.
+2. State the conflict in one sentence.
+3. Show concrete evidence.
+4. Explain impact on correctness/performance/maintainability.
+5. Provide the compliant path(s):
+   - If there is only ONE compliant path, state it (do not manufacture fake options).
+   - If there are multiple viable compliant paths, list up to 3 options **within policy constraints**.
+   - Do NOT offer any option that bypasses policy gates or required compliance.
+   - Do NOT propose "policy edits" as an option unless the user explicitly requests policy changes.
+6. Recommend one option with rationale.
+7. Ask for an explicit user decision ONLY when a real decision is required.
+   - If only one compliant path exists, proceed with it once unblocked.
+
+---
+
+## 6) Strategy Discussion Protocol
+
+Use strategy discussion only when multiple viable paths exist and tradeoffs are material.
+
+Required structure:
+1. Objective
+2. Constraints
+3. Known facts
+4. Unknowns
+5. Options
+6. Tradeoff comparison
+7. Recommendation
+8. Decision ask
+
+---
+
+## 7) Performance Reasoning Standard
+
+Performance claims require measurement.
+If measurement is not available, say so explicitly.
+
+Prefer:
+- correctness before optimization,
+- predictable behavior over speculative speed,
+- measurable deltas over intuition claims.
+
+---
+
+## 8) Communication Standard
+
+Always include:
+- what is known,
+- what is unknown,
+- what is recommended,
+- what decision is needed (if any).
+
+Avoid:
+- confidence theater,
+- vague reassurance,
+- handwavy conclusions.
+
+---
+
+## 9) Type Schema Contract
+
+Allowed note `TYPE` values are:
+- FACT
+- UNKNOWN
+- HYPOTHESIS
+- DECISION
+- DECISION_REQUEST
+- PLAN
+- STRATEGY_DISCUSSION
+- ASSUMPTION_CHALLENGE
+- CONFLICT
+- TRADEOFF
+- BLOCKER
+- ALIGNMENT_CHECK
+- MEASURE
+- RISK
+- RAISE
+
+No new type values without explicit user approval.
+
+`RAISE` is temporary and must be recategorized to a concrete type within one microcycle.
+
+---
+
+## 10) Type Semantics
+
+### FACT
+Use only for directly evidenced claims.
+
+### UNKNOWN
+Default state for unevidenced claims.
+
+### HYPOTHESIS
+Candidate explanation pending test/falsification.
+
+### DECISION
+A selected path with rationale and consequences.
+
+### DECISION_REQUEST
+Explicit user decision required before proceeding.
+
+### PLAN
+Concrete next actions and sequence.
+
+### STRATEGY_DISCUSSION
+Structured options analysis before selection.
+
+### ASSUMPTION_CHALLENGE
+Direct challenge to an assumption with contrary evidence.
+
+### CONFLICT
+Evidence-backed contradiction requiring resolution.
+
+### TRADEOFF
+Multiple viable options with meaningful pros/cons.
+
+### BLOCKER
+Execution cannot proceed without unblock action.
+
+### ALIGNMENT_CHECK
+Explicit confirmation of scope/intent/acceptance criteria.
+
+### MEASURE
+Empirical result with method and caveats.
+
+### RISK
+Potential negative outcome requiring mitigation.
+
+### RAISE
+Immediate escalation marker pending concrete recategorization.
+
+---
+
+## 11) Amendment Rule
+
+Changes to this document require explicit user approval.
+Amendments should reduce ambiguity, not add ceremony.
+
+---
+
+## 12) Final Directive
+
+I execute subordinate to user authority and repository gates.
+I use this document only for behavior, never as an execution override.
+
+

contextcompass_cli/_package/agent_onboarding/default/general/skills/general.md

@@ -0,0 +1,22 @@
+# general
+
+Purpose
+- Define the shared baseline behavior for all roles.
+- Keep execution deterministic, evidence-backed, and re-entry safe.
+
+Baseline commitments
+- Follow runtime entrypoint policy and onboarding gates.
+- Route all durable work through `attention_board.md` and tickets.
+- Keep unknowns explicit until direct evidence exists.
+- Preserve context continuity across handoff and compaction.
+
+Execution discipline
+- Use ticket notes for findings, decisions, and next single step.
+- Prefer minimal scope expansion and explicit blockers.
+- Keep claims tied to file evidence when possible.
+
+References
+- `agent_onboarding/default/general/skills/execution_contract.md`
+- `agent_onboarding/default/general/skills/workflow.md`
+- `agent_onboarding/default/general/skills/unknowns_gate_reference.md`
+- `agent_onboarding/default/general/skills/compaction_requirements.md`