contextcompass 2.15.0__py3-none-any.whl

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

@@ -0,0 +1,57 @@
+
+
+# ticket_closure_attention_sync
+
+Purpose
+- Enforce deterministic synchronization between ticket closure and `attention_board.md`.
+- Prevent stale routing rows and historical note buildup on the pointer board.
+
+When to use
+- Any time a ticket is moved to `tickets/epics/completed/`, `tickets/stories/completed/`, or `tickets/tasks/completed/`.
+- Any time a ticket status changes to done/review/blocked and the board row should change.
+
+Deterministic closure sync protocol (mandatory)
+1) Identify the closed ticket path (`old_ticket`) and completion datetime (`YYYY-MM-DDTHH:MM:SSZ`).
+2) Open `context_compass/attention_board.md`.
+3) In `## Active Items`:
+   - If a row points to `old_ticket` and no immediate successor ticket exists, remove the row.
+   - If a successor ticket exists, replace the row `ticket`, `status`, `mode`, `next`, `outcome`, `exit_signal`, and `updated_at` values.
+4) In `## Active Attention Details`:
+   - Remove entries whose `NEXT` or `EVIDENCE` are only about `old_ticket` and no longer route active work.
+   - Keep the section focused on current active rows only.
+   - Ensure the active row still has a matching `SWITCH_TRIGGER` and `RESUME_HIERARCHY`.
+5) In `## Recently Closed Anchors`:
+   - Add one compact anchor row for `old_ticket` with status `done` and `next=none`.
+   - Keep at most 12 anchor rows; remove oldest rows first when adding a new one.
+6) Verify board invariants before saving.
+7) If the closed ticket has artifacts:
+   - apply artifact disposition (`delete_on_close`, `retain_as_reference`, or
+     `promote_to_documentation`),
+   - update `context_compass/artifact_board.md` active/cleared rows.
+
+Board invariants (must hold)
+- `## Active Items` rows must only reference non-completed tickets.
+- Every active row must map to one canonical ticket path.
+- `next` text must be one concrete action.
+- `outcome` and `exit_signal` must be concrete and non-empty for active rows.
+- `## Active Attention Details` must only contain active-routing details.
+- Active routing details must include `SWITCH_TRIGGER` and `RESUME_HIERARCHY`.
+- Board must remain compact; durable narrative belongs in ticket `## Notes`.
+
+Verification commands
+- `rg -n "context_compass/(epics|stories|tasks)/completed/" context_compass/attention_board.md`
+- `rg -n "## Active Items|## Active Attention Details|## Recently Closed Anchors" context_compass/attention_board.md`
+
+Anti-patterns
+- Leaving closed ticket rows in `## Active Items`.
+- Keeping deep historical narratives in board detail section.
+- Using board detail section as a duplicate of ticket notes.
+
+References
+- `context_compass/agent_onboarding/default/general/skills/workflow.md`
+- `context_compass/agent_onboarding/default/general/skills/ticketing.md`
+- `context_compass/agent_onboarding/default/general/skills/active_pointerboard.md`
+
+
+
+

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

@@ -0,0 +1,44 @@
+
+
+# ticket_microcycle
+
+Purpose
+- Define a compact, repeatable execution loop that survives context loss.
+
+Strict mode loop
+1. `Investigate`
+2. `Document` (immediate notes entry)
+   - If `CONTEXT_MANAGEMENT_REQUIRED: true`, update the linked context
+     artifact when the finding changes the reread pack or active topics.
+3. `Strategy/Plan`
+4. `Document` (decision/plan note)
+   - If `CONTEXT_MANAGEMENT_REQUIRED: true`, update the linked context
+     artifact when the decision changes the required context or topic focus.
+5. `Implement`
+6. `Document` (implementation note)
+   - If `CONTEXT_MANAGEMENT_REQUIRED: true`, update the linked context
+     artifact when implementation changes what must be reread for safe
+     continuation.
+7. `Validate`
+8. `Document` (measure/result note)
+   - If `CONTEXT_MANAGEMENT_REQUIRED: true`, update the linked context
+     artifact when validation changes the active context or next reread set.
+
+Relaxed mode loop
+- Use when strict mode is disabled by config.
+- Still required:
+  - Document each meaningful finding.
+  - Document before implementation starts.
+  - Document after validation.
+  - If `CONTEXT_MANAGEMENT_REQUIRED: true`, keep the linked context artifact
+    synchronized with those findings.
+- Unknown-first evidence rules remain unchanged.
+
+Config source
+- `config/context_compass_config.yaml`
+- Keys:
+  - `workflow.ticket_microcycle.enabled`
+  - `workflow.ticket_microcycle.mode`
+  - `workflow.ticket_microcycle.require_note_before_continue`
+  - `workflow.ticket_microcycle.minimum_note_score`
+

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

@@ -0,0 +1,175 @@
+
+
+# ticketing
+
+Purpose
+- Define the ticketing system used to plan, execute, and close work in this repo.
+
+Ticket types
+- Epic: big project or cross-cutting initiative with multiple stories.
+- Story: medium scope, user- or system-facing slice that can stand alone or live under an epic.
+- Task: small, single deliverable that can stand alone.
+
+Templates
+- `templates/epic_template.md`
+- `templates/story_template.md`
+- `templates/task_template.md`
+- `configuration_standards.md`
+- `artifact_board.md`
+- `context_management/context_board.md`
+
+Deep descriptive model (required)
+Each ticket must be specific, evidence-based, and durable. Avoid vague goals.
+
+Required elements
+- Agent Name metadata (one or more assigned names; comma-separated when multiple)
+- Problem / Opportunity
+- Context (why now, relationship to architecture)
+- MRP alignment
+- Ticket Contract (`ENTRY_GATE`, `EXECUTION_BOUNDARY`, `DEPENDENCIES`,
+  `EXIT_GATE`, `FAILURE_ESCALATION`)
+- Goals / Non-goals
+- Scope boundaries
+- Requirements (functional + non-functional)
+- Acceptance criteria (observable outcomes)
+- Risks / Mitigations
+- Validation plan (tests or verification)
+- Decision log
+- State Transition Event (`from_state`, `to_state`, `transition_reason`)
+- Applicable Anti-Patterns (lane-specific checklist only)
+- Noting Behavior (task/story/epic focus)
+- Artifact Links (Optional, required when artifacts exist)
+- Context Management (Optional, only when reusable reread packs are needed)
+- Notes (active findings with evidence pointers)
+- Context / Handoff summary
+
+Workflow rules
+1) Choose the smallest ticket type that fits the scope:
+   - Big project: epic -> stories -> tasks.
+   - Medium scope: story -> tasks.
+   - Small scope: task only.
+2) Keep links consistent (epic <-> story <-> task IDs) when using multiple levels.
+3) Track progress with checkboxes and status fields.
+4) Use the Ticket Microcycle while active:
+   - `Investigate -> Document -> Strategy/Plan -> Document -> Implement -> Document -> Validate -> Document`.
+5) For every meaningful finding, update `## Notes` immediately before any further investigation.
+6) Treat new claims as `UNKNOWN` by default; promote to `FACT` only with evidence.
+7) If investigation expands beyond the current subsystem or exceeds
+   `workflow.ticket_microcycle.expansion_gate_max_files`, add a `DECISION`
+   note and request user confirmation.
+8) Update Context / Handoff Summary as work changes.
+9) Before closing a ticket:
+   - Walk through what was delivered.
+   - Ask the user to confirm acceptance criteria.
+10) After confirmation:
+   - Add a completion summary + UTC datetime.
+   - Move the ticket to its matching completed folder (`tickets/epics/completed/`,
+     `tickets/stories/completed/`, or `tickets/tasks/completed/`).
+11) Immediately run deterministic closure sync for `attention_board.md`:
+   - Remove/replace active row(s) that point to the closed ticket.
+   - Prune stale attention details tied only to the closed ticket.
+   - Add one compact row under `Recently Closed Anchors`.
+   - Keep anchor rows capped (oldest removed first).
+12) If ticket artifacts exist, run artifact closure sync:
+   - Apply artifact disposition (`delete_on_close`, `retain_as_reference`, or
+     `promote_to_documentation`).
+   - Update `artifact_board.md` active/cleared entries.
+
+Mandatory execution gates
+- Active ticket gate:
+  - Do not implement or validate without an active ticket for the work.
+- Routing gate:
+  - Do not implement or validate unless `attention_board.md` has an active row
+    that points to the same active ticket.
+- Notes gate:
+  - Do not start another investigation/edit/validation tranche until the current
+    meaningful finding is appended to ticket `## Notes` with evidence pointers.
+- Repair gate:
+  - If any gate is broken or stale, stop and repair ticket/board/notes state
+    before continuing.
+- Artifact gate:
+  - When artifacts are present, ticket `Artifact Links (Optional)` and
+    `artifact_board.md` must stay synchronized.
+- Context-management gate:
+  - Context management is optional.
+  - When `CONTEXT_MANAGEMENT_REQUIRED: true`, ticket `Context Management` and
+    `context_management/context_board.md` must stay synchronized.
+  - Tickets should reference reusable context packs by `Context ID`.
+  - When `CONTEXT_MANAGEMENT_REQUIRED: true`, do not implement or validate
+    until linked context artifacts were actually read.
+  - When `CONTEXT_MANAGEMENT_REQUIRED: true`, keep the linked context artifact
+    updated during the Ticket Microcycle whenever meaningful findings change
+    the reread bundle or active topics.
+- Attention-board boundary gate:
+  - `attention_board.md` must remain ticket-routing-only (no artifact pointers).
+
+Notes format requirement
+- New note entries should include:
+  - `DATETIME` (ISO-8601 UTC: `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`:
+    - inline form for one short path (`path:start_line-end_line`)
+    - one path per line when path count >= 2 or line would exceed hard cap
+  - `IMPACT`
+  - `NEXT`
+  - `REREAD` (`REQUIRED` | `HELPFUL`)
+  - `SCORE_0_TO_10` (compaction usefulness score; improve entries below
+    `workflow.ticket_microcycle.minimum_note_score`)
+- Keep notes append-only except when correcting factual errors.
+- Deep semantic meaning and collaboration behavior for each `TYPE` are defined in:
+  `context_compass/agent_onboarding/default/general/skills/execution_contract.md`.
+
+Per-ticket noting behavior
+- Task notes: tactical findings, immediate impacts, and one-step continuation.
+- Story notes: cross-task synthesis, dependency movement, and gate transitions.
+- Epic notes: program direction, cross-story tradeoffs, and tranche order.
+
+Status discipline
+- Update Status and Updated fields on each state change (UTC DateTime: `YYYY-MM-DDTHH:MM:SSZ`).
+- Keep `Agent Name` current when ticket assignment changes.
+- Prefer: draft -> ready -> in_progress -> blocked/done.
+- If blocked, document the blocker and the unblock action.
+
+Ticket contract discipline
+- Every active ticket should contain `Ticket Contract`.
+- Every status transition should be documented via `State Transition Event`.
+- Keep anti-pattern checks local to the lane (`Applicable Anti-Patterns`);
+  do not duplicate a global anti-pattern catalog in each ticket.
+
+Config authority
+- Source thresholds from `config/context_compass_config.yaml` under
+  `workflow.ticket_microcycle`.
+- Values are authoritative in YAML.
+- Do not duplicate numeric defaults in policy docs.
+- Ticket contract gates are authoritative under `workflow.ticket_contract`.
+- Note behavior defaults are authoritative under `workflow.note_behavior`.
+- Artifact protocol is authoritative under `artifacts`.
+
+Formatting discipline
+- Follow `configuration_standards.md`.
+- Default prose target is 90-110 characters per line.
+- Hard cap is 120 characters per line.
+- `EVIDENCE` should use one path per line when multiple paths are present or
+  inline length would exceed hard cap.
+
+Validation reporting
+- Never claim tests ran unless they actually ran.
+- If not run, say "Not run" and explain why.
+
+Optional context-management section
+- Tickets may include:
+  - `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`
+- If a required context-management field is not known, write `UNKNOWN`
+  explicitly.
+

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

@@ -0,0 +1,52 @@
+
+
+# ticketing_skill_contract
+
+## Purpose
+This document defines how to create deep, descriptive structured tickets for epics, stories, and tasks in `tickets/epics/`, `tickets/stories/`, and `tickets/tasks/`.
+The goal is durable, high-context planning that survives compaction and handoffs.
+
+## Ticket Types (Use Templates)
+- Epic: big project or cross-cutting initiative with multiple stories.
+- Story: medium scope, user- or system-facing slice that can stand alone or live under an epic.
+- Task: small, single deliverable that can stand alone.
+
+Templates live in:
+- `templates/epic_template.md`
+- `templates/story_template.md`
+- `templates/task_template.md`
+
+## File Locations and Naming
+- Epics: `tickets/epics/`
+- Stories: `tickets/stories/`
+- Tasks: `tickets/tasks/`
+
+Naming convention (date-first, descriptive):
+- `YYYY-MM-DD_<slug>_epic.md`
+- `YYYY-MM-DD_<slug>_story.md`
+- `YYYY-MM-DD_<slug>_task.md`
+
+## Ticket Content Contract
+- Canonical ticket schema and execution-gate requirements live in
+  `agent_onboarding/default/general/skills/ticketing.md`.
+- Canonical lifecycle sequencing, microcycle order, and closure sync live in
+  `agent_onboarding/default/general/skills/workflow.md`.
+- Use templates as the executable contract; do not fork section schemas in this
+  skill.
+
+## Ticket Formatting Rules
+- Title line is required and outcome-focused.
+- Metadata is a short bullet list at the top.
+- Use short paragraphs and bullet lists for scanability.
+- Link epic <-> story <-> task by ID in metadata and checklists.
+- Apply formatting standards from
+  `agent_onboarding/default/general/skills/configuration_standards.md` and
+  config values in `config/context_compass_config.yaml`.
+
+## Context Compaction / Handoff
+- Canonical compaction/handoff process lives in
+  `agent_onboarding/default/general/skills/context_compaction.md` and
+  `agent_onboarding/default/general/skills/compaction_requirements.md`.
+- Keep ticket `Context / Handoff Summary` sections current before handoff.
+
+

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

@@ -0,0 +1,66 @@
+
+
+# unknowns_gate_reference
+
+Purpose
+- Provide one canonical onboarding source for UNKNOWN/FACT evidence discipline.
+
+Unknowns Gate (No Unverified Claims)
+- Any statement not supported by evidence is UNKNOWN.
+- UNKNOWN is the default claim state for new findings.
+- Evidence means at least one of:
+  - A specific source file reference (preferred: file + symbol/method/class name).
+  - A citation to an explicit, already-verified artifact (for example, an approved doc section).
+- If not evidenced => UNKNOWN.
+- UNKNOWN items must be labeled UNKNOWN (or added to an Unknowns section).
+- UNKNOWN items must be investigated by reading the relevant source(s).
+- If investigation cannot be completed (missing source access, ambiguity, or time),
+  the item must remain UNKNOWN and must not be promoted to FACT.
+- No reasonable assumptions.
+- Do not infer behavior from naming, patterns, conventions, or typical frameworks.
+- Only code/docs count as evidence.
+
+Operating workflow
+1) Start new claims as UNKNOWN.
+2) Identify evidence target (file + symbol).
+3) Capture reproducible evidence (`path:start_line-end_line` or verified-doc citation).
+4) Promote to FACT only when evidence directly supports the claim.
+5) If blocked, keep UNKNOWN and record the blocker.
+
+How to run step 2 and 3 cheaply
+- "Investigate" means **go and read it, yourself, now.** This gate creates an
+  obligation to look; it is not discharged by asking the user what the answer is,
+  and asking permission to consult documentation is not compliance with it.
+- Where system documents exist they make step 2 nearly free: the architecture
+  narrative names the subsystem, an index converts that name to a line range, and
+  a slice gives you the evidence with a citable `path:start-end`. Engineers:
+  `agent_onboarding/default/engineer/skills/context_protocol.md`.
+- **Evidence of intent is not evidence of behaviour.** A design document tells you
+  what somebody meant; only the source tells you what runs. For a claim about
+  current behaviour, cite the source. If a document contradicts it, the document
+  is stale - record that, it is a finding.
+- Read what the claim needs and stop. Loading whole documents with no claim in
+  hand is not evidence-gathering; it produces vague statements about a lot instead
+  of one evidenced statement about the thing that mattered.
+
+Evidence quality checklist
+- Specific: concrete symbols/sections, not broad file assumptions.
+- Sufficient: evidence directly supports the exact claim.
+- Current: evidence matches current repository state.
+- Traceable: another reader can reopen evidence quickly.
+
+Local override rule
+- Local docs may extend this policy for domain-specific enforcement.
+- Do not duplicate the full Unknowns Gate block unless a documented override is required.
+
+Disallowed shortcuts
+- Treating naming conventions as proof.
+- Promoting tentative conclusions to FACT without evidence.
+
+References
+- `context_compass/AGENTS.MD`
+- `context_compass/agent_onboarding/default/general/skills/execution_contract.md`
+
+
+
+

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

@@ -0,0 +1,32 @@
+
+
+# user_approved_certification
+
+Purpose
+- Define the explicit approval step that unlocks tool usage and edits.
+
+Approval script
+- Ask the user to reply with a message that includes:
+  - `AGENT_NAME: <name>`
+  - the exact token `CERTIFY: APPROVED`.
+- Do not proceed with any tool use or file edits before approval.
+
+Rules
+- Only request approval after listing the skills read from:
+  - `context_compass/config/context_compass_config.yaml`
+  - `context_compass/SKILLS.MD`
+  - `context_compass/agent_onboarding/default/general/SKILLS.MD`
+  - selected role `SKILLS.MD` path from `context_compass/SKILLS.MD`
+- Before requesting approval, complete role-driven onboarding reads from:
+  - `context_compass/config/context_compass_config.yaml`
+  - `context_compass/SKILLS.MD`
+  - the resolved role `SKILLS.MD` chain
+  - include read-integrity proof in the ONBOARD/REONBOARD attestation
+  - include `AGENT_NAME` in the ONBOARD/REONBOARD attestation
+  (concrete rule callouts -> behavior implications; not tool logs).
+- Do not request approval based on onboarding dump artifacts; approval requires
+  source-document read completion.
+- After compaction/handoff/fresh-session re-entry, the same full-readset
+  requirement applies again before requesting approval.
+
+