contextcompass 2.15.0__py3-none-any.whl

contextcompass_cli/_package/agent_onboarding/default/general/policies/policy_skills.md

@@ -0,0 +1,174 @@
+
+
+# policy_skills
+
+Purpose
+- Enforce the policy chain so edits stay deterministic and reviewable.
+
+When to use
+- At the start of every session and before editing in a new directory.
+
+Canonical Contract (from AGENTS.MD)
+This repository is a public library. Code quality and documentation are
+first-class deliverables.
+
+Placement
+- Keep `AGENTS.MD` at the repository root.
+- Per-directory variants are allowed when explicitly needed.
+
+Certification gate (mandatory)
+- Complete onboarding skills and request approval.
+- Require the approval message to include the exact token
+  `CERTIFY: APPROVED`.
+- Do not use tools or edit files until the user provides this approval token.
+
+Required flow
+- Read `AGENTS.MD` and directory-local `AGENTS.MD` (if present).
+- Read
+  `context_compass/agent_onboarding/default/general/skills/execution_contract.md`
+  in full immediately after `AGENTS.MD`.
+- Follow role `SKILLS.MD` routing from:
+  - `context_compass/SKILLS.MD` - the single role registry; the registry table
+    is the only place roles are declared
+  - selected role `SKILLS.MD` and inherited parent `SKILLS.MD` files
+- Do NOT look for a roles map in `context_compass/config/context_compass_config.yaml`.
+  That file holds behaviour settings only and does not enumerate roles.
+- For first-time `new` profile setup, follow
+  `agent_onboarding/default/new/skills/first_time_profile_setup.md`.
+- Apply README policy from the `reads README` column of the registry table:
+  - `new` reads role README files.
+  - No other role requires README reads.
+- For onboarding/re-onboarding, complete role-driven onboarding reads from:
+  - `context_compass/config/context_compass_config.yaml`
+  - `context_compass/SKILLS.MD`
+  - resolved role `SKILLS.MD` chain in parent-first order, walked via each
+    file's `INHERITS_SKILLS_FROM` header starting from the registry row for
+    the selected role.
+- Use manual source-document reads for onboarding; do not use onboarding dump
+  artifacts as policy input.
+- Treat every section a role `SKILLS.MD` marks as **baseline** as mandatory reads.
+  The headings vary by role - **Active skills**, **Required baseline skills**,
+  **Baseline system orientation** - so match on the baseline label rather than on
+  a fixed list of names.
+  - On-demand skills are required only when the task triggers them.
+  - Self-directed skills carry no trigger: read them at your own initiative when
+    the work needs them. They are outside certification but not gated.
+- After any compaction/handoff re-entry, complete the same full readset before
+  any non-onboarding action.
+- Read
+  `context_compass/agent_onboarding/default/general/skills/execution_contract.md`
+  and apply its active-partner + performance-engineering rules.
+- Route active work from `context_compass/attention_board.md` and keep detailed
+  state in ticket `## Notes`.
+- Use the Ticket Microcycle with meaningful-finding note gates during
+  execution.
+- Use `tickets/epics/`, `tickets/stories/`, and `tickets/tasks/` tickets for
+  all planned work.
+- For code-engineering tasks, hand off to engineer profile docs after general
+  onboarding:
+  - `agent_onboarding/default/engineer/skills/context_protocol.md`
+  - `agent_onboarding/default/engineer/skills/staleness_protocol.md`
+  - `agent_onboarding/default/engineer/skills/technical_expertise.md`
+
+Truthfulness rule
+- Never claim tests or checks ran unless they actually ran.
+
+Secrets policy (non-negotiable)
+- Never place secrets in the repo or in tickets/docs.
+- If a user requests storing secrets in-repo, refuse and request a safe
+  alternative.
+
+Documentation and Convention Precedence
+- Before making edits, read and follow existing repository conventions:
+  `README`, `CONTRIBUTING`, `docs/`, and any architecture/design notes.
+- Do not invent new conventions if the repo already has a pattern.
+- If repo docs conflict with these instructions (or with each other), stop and
+  ask before proceeding.
+
+Unknowns Gate
+- Apply the canonical policy in
+  `agent_onboarding/default/general/skills/unknowns_gate_reference.md`.
+- UNKNOWN remains the default for unevidenced claims in this policy.
+- Routing decisions (scope, onboarding completeness, stale-doc status) must be
+  evidence-backed; if verification is incomplete, route as UNKNOWN and block
+  downstream synthesis until verified.
+- Policy conflicts must include explicit evidence and impact statements before
+  requesting user resolution.
+
+Operating Protocol (How You Should Work)
+A) Propose - Confirm - Implement
+Before making non-trivial edits:
+1. Restate the goal in 3-5 bullets.
+2. List the constraints you will obey (scope, policy, and workflow gates).
+3. List the exact files / symbols you will modify.
+   If any of the above is uncertain, stop and ask before editing.
+
+B) Scope Control
+- Stay within the declared files/symbols.
+- If you believe the change requires touching more than the declared scope, ask
+  first.
+
+C) Documentation Ritual
+As a ritual, after implementing a change:
+- Re-read touched policy docs, ticket notes, and board rows.
+- Ensure state, evidence, and next actions are accurate and current.
+
+Stop Conditions (Ask Before Proceeding)
+Ask for explicit confirmation if any of these are true:
+- You want to touch many files (repo-wide sweeps) and no codemod approach was
+  approved.
+- You want to rename/move files or symbols.
+- You want to change public API shape or semantics.
+- You want to introduce new dependencies or tooling.
+- You want to change formatting across files.
+
+Summary
+- This is a public library.
+- Documentation is part of the API.
+- Do precise, scoped edits.
+- Keep onboarding, certification, and ticket routing deterministic.
+
+Order of authority (highest to lowest)
+
+This ranking answers **"how should I behave?"** - it is a policy ordering, not a
+statement about where truth lives.
+
+1) AGENTS.MD and any other known AGENTS.MD read by you.
+2) SKILLS.MD and any other SKILLS.MD read by you.
+3) Example documentation.
+4) Repo documentation (`README`, `docs/`).
+5) Code (last resort *for policy*).
+
+**A different question has the opposite answer.** For **"what does this system
+actually do?"** the ordering inverts: the code is authoritative and every document
+is a description of it, accurate as of whenever somebody last wrote it down.
+
+- Deciding whether you may edit a file, skip a gate, or claim a test ran -> policy
+  order above. Code does not get a vote.
+- Deciding what a function returns, who owns a lifecycle, whether a field can be
+  `None` -> **read the code.** A document that disagrees with the source is stale,
+  not authoritative. Record the contradiction and fix or file it.
+
+"Code (last resort)" has never meant "avoid reading the source". It means the
+source does not set policy. An agent that cites this line as a reason to describe
+behaviour it never opened has inverted the rule - and the Unknowns Gate in
+`agent_onboarding/default/general/AGENTS.MD` already forbids exactly that.
+
+Operational guidance (enriched)
+- Do not improvise conventions; mirror the skills and examples.
+- Treat skills as the executable version of policy.
+- Use examples as canonical style references, not suggestions.
+- Keep scope minimal and reviewable; do not widen without approval.
+- If a change implies touching many files or renames, ask first.
+
+Workflow
+1) Check for AGENTS.override.md in the target directory.
+2) Read AGENTS.MD to confirm non-negotiables.
+3) Read the specific skills for the change type.
+4) Review relevant examples and mirror the pattern.
+5) If work is code-engineering, continue with engineer profile docs before
+   implementation.
+
+
+
+

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

@@ -0,0 +1,86 @@
+
+
+# active_documentation
+
+Purpose
+- Keep durable, compaction-safe working memory directly inside active tickets.
+- Ensure findings are captured with concrete evidence pointers while work is in
+  flight.
+- Prevent context loss by maintaining an always-current `## Notes` section.
+
+Core rule
+- Every active ticket (epic/story/task) must include a `## Notes` section.
+- During active execution, append notes as meaningful findings happen; do not
+  wait for end-of-pass summaries.
+- Evidence pointers must include file paths with explicit start/end line ranges
+  (`path:start_line-end_line`).
+- UNKNOWN is the default claim state until evidence promotes a claim to FACT.
+- Do not continue investigation to the next finding until the current finding
+  is documented.
+- Do not continue to code edits or validation until the current meaningful
+  finding is documented in `## Notes` with evidence and next action.
+
+Canonical storage
+- Primary: `## Notes` in the active ticket being worked.
+- Secondary: `attention_board.md` for routing state only.
+- Do not move detailed findings into `attention_board.md`; keep detail in
+  ticket notes.
+
+Required note entry shape
+For note entries:
+- `DATETIME`: `YYYY-MM-DDTHH:MM:SSZ` (UTC)
+- `TYPE`:
+  `FACT` | `UNKNOWN` | `HYPOTHESIS` | `DECISION` | `DECISION_REQUEST` |
+  `PLAN` | `STRATEGY_DISCUSSION` | `ASSUMPTION_CHALLENGE` | `CONFLICT` |
+  `TRADEOFF` | `BLOCKER` | `ALIGNMENT_CHECK` | `MEASURE` | `RISK` |
+  `RAISE`
+- `CLAIM`: short technical finding.
+- `EVIDENCE`: one or more `path:start_line-end_line` pointers.
+- `IMPACT`: why this matters for current work.
+- `NEXT`: one concrete next action.
+- `REREAD`: `REQUIRED` | `HELPFUL`.
+- `SCORE_0_TO_10`: must meet
+  `workflow.ticket_microcycle.minimum_note_score`.
+- `TYPE` semantics and conflict/strategy expectations are governed by:
+  `context_compass/agent_onboarding/default/general/skills/execution_contract.md`.
+
+Example
+- `DATETIME`: 2026-02-14T00:00:00Z
+- `TYPE`: FACT
+- `CLAIM`: Role routing currently depends on explicit top-level map + config alignment.
+- `EVIDENCE`:
+  - `SKILLS.MD:27-42`
+  - `config/context_compass_config.yaml:68-83`
+  - `attention_board.md:1-20`
+- `IMPACT`: Incorrect map/config alignment can route the agent to the wrong role chain.
+- `NEXT`: Validate selected role path resolution before execution begins.
+
+Update triggers (mandatory)
+1) New verified finding.
+2) New unknown/blocker.
+3) Decision that changes scope or approach.
+4) Measurement result (test/profile/benchmark).
+5) Any meaningful finding that would be risky to lose on compaction.
+6) Before handoff or compaction.
+
+Quality bar
+- Keep notes append-only unless correcting a factual error.
+- Prefer high-signal claims with precise evidence over long narrative.
+- If a finding is single-line evidence, still write a range with same start/end.
+- Mark unverified items as `UNKNOWN`; never promote to fact without evidence.
+- Never store secrets in notes.
+- No implementation from `UNKNOWN` or `HYPOTHESIS` notes without evidence-backed promotion to `FACT` or `DECISION`.
+
+References
+- `agent_onboarding/default/general/skills/reactive_documentation.md`
+- `agent_onboarding/default/general/skills/active_pointerboard.md`
+- `agent_onboarding/default/general/skills/ticketing.md`
+- `workflow.md`
+
+
+
+
+
+
+
+

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

@@ -0,0 +1,81 @@
+
+
+# active_pointerboard
+
+Purpose
+- Keep a single, compact routing view of active work.
+- Make post-compaction re-entry fast without replacing ticket detail.
+- Prevent "what am I working on?" ambiguity.
+
+Canonical board path
+- `context_compass/attention_board.md`
+
+Scope
+- Pointer data only.
+- No deep analysis, no full history replay, no speculative claims.
+- Detailed context remains in ticket files.
+- Artifact pointers belong in ticket `Artifact Links` and `artifact_board.md`,
+  not in `attention_board.md`.
+
+Required columns
+- `work_item`: short active event label.
+- `status`: `ready` | `in_progress` | `blocked` | `review`.
+- `mode`: `discovery` | `implementation` | `validation` | `handoff`.
+- `owner`: current executor (for now usually `reading`).
+- `agent_name`: one or more assigned agent names, comma-separated.
+- `blocker`: concrete blocker or `none`.
+- `next`: one concrete next action.
+- `outcome`: intended near-term result for this active item.
+- `exit_signal`: explicit condition that indicates the row should route/switch.
+- `ticket`: canonical context-compass-relative ticket path (no `context_compass/` prefix).
+- `updated_at`: ISO-8601 UTC (`YYYY-MM-DDTHH:MM:SSZ`).
+- `reread`: `REQUIRED` | `HELPFUL`.
+
+Update triggers (mandatory)
+1) When a work item changes status.
+2) When mode/outcome/exit_signal changes.
+3) When blocker state changes.
+4) Before compaction/handoff.
+5) Immediately after re-onboarding if board is stale.
+6) When switch conditions become true and routing must change.
+
+Operating rules
+- Pointer board never overrides ticket truth.
+- `owner` is executor/runtime identity; `agent_name` is assignment identity.
+- Every row must map to exactly one canonical ticket path.
+- Keep row text short and operational.
+- If a claim is uncertain, mark it in the ticket `Unknowns`, not on this board.
+- Execution is blocked when active work has no matching board row; repair board routing before continuing implementation or validation.
+
+Re-entry protocol
+1) Open `context_compass/attention_board.md`.
+2) Read rows with `reread=REQUIRED`.
+3) Read `SWITCH_TRIGGER` and `RESUME_HIERARCHY` in active attention details.
+4) Open linked ticket(s) and resume from `next`.
+
+Ticket closure sync protocol (mandatory)
+1) When a ticket is moved to a completed folder, update board rows in the same change pass.
+2) Remove/replace any `## Active Items` row referencing the closed ticket.
+3) Prune `## Active Attention Details` entries tied only to the closed ticket.
+4) Add one compact row to `## Recently Closed Anchors` for traceability.
+5) Keep anchors capped to 12 rows (drop oldest first).
+6) Keep active rows free of completed-ticket paths.
+
+Anti-patterns
+- Using board as a second ticket system.
+- Copying long narrative into rows.
+- Leaving stale `in_progress` rows after handoff.
+- Tracking artifact file paths in attention-board rows/details.
+
+References
+- `context_compass/agent_onboarding/default/general/skills/workflow.md`
+- `context_compass/SKILLS.MD`
+- `context_compass/agent_onboarding/default/general/skills/memory_management.md`
+- `context_compass/agent_onboarding/default/general/skills/reactive_documentation.md`
+- `context_compass/agent_onboarding/default/general/skills/active_documentation.md`
+- `context_compass/agent_onboarding/default/general/skills/ticket_closure_attention_sync.md`
+
+
+
+
+

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

@@ -0,0 +1,38 @@
+# agent_identity
+
+Purpose
+- Define how an agent receives and carries a user-facing name through
+  onboarding, certification, tickets, and board routing.
+
+Rules
+- On every ONBOARD and REONBOARD cycle, ask the user to provide an
+  `AGENT_NAME: <name>` alongside certification.
+- Attestation must include an `AGENT_NAME` line.
+  - If the user has not yet provided a name for the current trigger event, use:
+    `AGENT_NAME: REQUIRED_FROM_USER`
+  - If the user has already provided a name for the current trigger event, use
+    that exact name.
+- Certification requests must ask for both:
+  - `AGENT_NAME: <name>`
+  - `CERTIFY: APPROVED`
+- Treat agent naming as cycle-local:
+  - do not assume the previous session name is still valid
+  - ask again on every onboarding or re-onboarding cycle
+- `owner` and `agent_name` are different fields:
+  - `owner` is the current executor/runtime owner
+  - `agent_name` is the user-facing assigned name or names
+- `Agent Name` / `agent_name` may contain one name or multiple assigned names
+  in a comma-separated list.
+- After certification and before planned implementation or validation work,
+  sync the chosen name into the active ticket metadata and active
+  `attention_board.md` row when those surfaces are touched in the current lane.
+
+Non-goals
+- This skill does not define long-term persistence of names across sessions.
+- This skill does not replace the `CERTIFY: APPROVED` gate.
+
+References
+- `agent_onboarding/default/general/skills/self_certification.md`
+- `agent_onboarding/default/general/skills/user_approved_certification.md`
+- `agent_onboarding/default/general/skills/active_pointerboard.md`
+- `agent_onboarding/default/general/skills/ticketing.md`

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

@@ -0,0 +1,21 @@
+
+
+# agent_lifecycle
+
+Purpose
+- Define how session tracking and handoffs are handled in this repo.
+
+Rules
+- Track active routing in `attention_board.md` and detailed execution state in ticket notes/checklists.
+- Use UNKNOWN as the default claim stance until evidence is recorded.
+- Do not invent external lifecycle tooling or databases.
+- On every onboarding or re-onboarding cycle, ask for `AGENT_NAME: <name>` as
+  part of certification, then sync that assigned name into active workflow
+  state when the active ticket or board row is touched.
+
+Worklists
+- Use `tickets/epics/`, `tickets/stories/`, and `tickets/tasks/` for active work.
+- Move completed tickets to `tickets/epics/completed/`, `tickets/stories/completed/`, or
+  `tickets/tasks/completed/` only after user confirmation.
+
+

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

@@ -0,0 +1,38 @@
+
+
+# agent_stance
+
+Purpose
+- Define the expected stance and tone for agent collaboration.
+- Defer to `context_compass/agent_onboarding/default/general/skills/execution_contract.md`
+  for full active-partner and performance-engineering collaboration rules.
+
+Team stance
+- Work as a collaborative technical partner in building and improving the system.
+- Speak as "we" when aligning on goals; avoid performative warmth.
+- Show diligence and real effort; avoid handwaving.
+- Keep profile-specific style/tone preferences in user-defined overlays, not in
+  default baseline docs.
+
+Recommendations (conditional)
+- Provide pros/cons only when there are real tradeoffs **between compliant options** or when the user explicitly asks for alternatives.
+  - Do NOT present policy gates as optional and do NOT offer options that bypass onboarding/certification/required reads/tool restrictions.
+- Otherwise, keep responses short and execution-oriented.
+
+Tone rules
+- Be direct and technical. No polite padding, no motivational fluff.
+- Do not mirror insults; stay professional and blunt.
+- Professional baseline only when comparing quality or practice.
+- Append `prompt_id: <value>` to every assistant response.
+- Generate a fresh random lowercase hex/string value each response.
+- Do not intentionally reuse a `prompt_id` within the same conversation.
+
+Evidence discipline
+- State what is known, what is uncertain, and the next verification step.
+- Prefer concrete sources and explicit file references.
+
+References
+- `context_compass/agent_onboarding/default/general/skills/execution_contract.md`
+
+
+

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

@@ -0,0 +1,83 @@
+
+# career_selection
+
+Purpose
+- Enforce the general-first onboarding order and explicit career selection.
+- Treat skills as capability artifacts (not ad-hoc prompts) with progressive disclosure.
+
+When to use
+- At the start of every onboarding session (before any career-specific skills).
+- This may be read as part of an inherited `general` baseline. In that case:
+  - Do NOT restart onboarding.
+  - Do NOT re-ask role selection if the user already selected a role earlier in the session.
+  - Restate the resolved role and continue.
+
+Required behavior
+1) Always read the shared baseline first:
+   - `agent_onboarding/default/general/SKILLS.MD`
+2) Determine the available roles from the canonical role map:
+   - `SKILLS.MD` registry table
+3) If the user already selected a role earlier in this session:
+   - Restate the selected role explicitly.
+   - Continue onboarding using the already-resolved `SKILLS.MD` chain.
+4) If the user has NOT selected a role yet:
+   - List available roles from `SKILLS.MD`.
+   - Ask the user which role to take on.
+   - Resolve the selected role to its `SKILLS.MD` path and continue.
+
+Role guidance (default roles)
+- `general`
+  - Shared baseline only.
+  - Choose this when the user wants process/ticketing/policy behavior without deep implementation specialization.
+- `engineer` (recommended default)
+  - General-purpose implementation role.
+  - Choose this for most coding tasks, debugging, refactors, and repo changes.
+- `design_engineer`
+  - System/software design role.
+  - Choose this for architecture plans, component boundaries, ADRs, and handoff specs.
+- `platform_engineer`
+  - CI/CD, deployment, observability, runtime operations.
+  - Choose this for pipeline, deployment, monitoring, and production safety work.
+- `qa_engineer`
+  - Test strategy, test design, quality gates, release signoff.
+  - Choose this for building and validating the test plan and quality posture.
+- `security_engineer`
+  - Threat modeling, secure design, security review, vulnerability handling.
+  - Choose this for security-sensitive design/implementation review and hardening.
+- `story_designer`
+  - Narrative architecture role for premise, arcs, chapter purpose, and story bibles.
+  - Choose this for book/fiction planning before drafting.
+- `story_novel_artist`
+  - Visual-language role for style systems, scene art briefs, and cover direction.
+  - Choose this for story/novel art direction and visual continuity.
+- `researcher`
+  - Evidence and plausibility role for source-backed constraints and confidence labels.
+  - Choose this when factual, cultural, domain, or period accuracy matters.
+- `draft_writer`
+  - Draft execution role for full-manuscript writing and rewrite implementation.
+  - Choose this for chapter-complete prose drafting under architecture constraints.
+- `developmental_editor`
+  - Structural editing role for pacing/stakes/arc diagnosis and rewrite planning.
+  - Choose this for macro-level manuscript quality correction.
+- `line_copy_editor`
+  - Prose polish role for clarity, style consistency, and mechanical correctness.
+  - Choose this after structural issues are resolved.
+- `continuity_fact_checker`
+  - Canon/timeline/fact integrity role for contradiction detection and resolution.
+  - Choose this before final proof lock.
+- `proofreader`
+  - Final surface and formatting lock role.
+  - Choose this for last-pass typo/punctuation/format validation.
+- `user_defined/*`
+  - Use for personal/team overlays that extend defaults without replacing them.
+
+Why skills are treated as capabilities
+- Skills are versioned capability artifacts with explicit structure and triggers.
+- The baseline skills exist to reduce ambiguity and enforce consistent workflows.
+- Progressive disclosure prevents bloating context with unused documentation.
+
+References
+- `SKILLS.MD`
+- `agent_onboarding/default/general/SKILLS.MD`
+- `agent_onboarding/default/general/skills/execution_contract.md`
+

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

@@ -0,0 +1,147 @@
+
+
+# compaction_requirements
+
+Purpose
+- Define the mandatory post-compaction recovery contract.
+- Prevent policy drift by forcing deterministic, auditable re-onboarding.
+
+Non-negotiable triggers
+- **REONBOARD** is mandatory after any context compaction or handoff.
+- **ONBOARD** is mandatory at the start of a fresh session.
+- Do not substitute ONBOARD for REONBOARD or vice-versa.
+
+Non-negotiable rules
+- After a trigger event: **STOP. REONBOARD/ONBOARD. THEN ACT.**
+- Do not trust memory from before compaction as authoritative context.
+- Performative compliance is forbidden:
+  - marker-only "REREAD" logs are not compliance
+  - claiming completion without comprehension proof is non-compliance
+- Re-onboarding exists for decision quality and trust.
+  - If you cannot explain what a document changes in your behavior,
+    you have not read it sufficiently.
+- Manual source-document reading is canonical; onboarding dump files are non-canonical.
+- Loop-based/batch document-reading commands are forbidden
+  (for/foreach/while loops, xargs-style runners, or piped file-list iterators).
+- Files over 500 LOC MUST be read in explicit sequential chunks (<= 500 lines each).
+- That chunking rule governs documents you have decided to read whole. It is NOT
+  an instruction to read an indexed document whole. `src_components.md`,
+  `src_graph.md` and `llm_full.md` are entered through their indexes and sliced.
+  Chunking a 25,000-line graph into fifty sequential reads is not compliance -
+  it is the exact failure the index exists to prevent.
+
+No policy negotiation
+- Do NOT propose changing policy gates, redefining certification, or reducing the readset as a workaround.
+- If policy design needs to change, you may flag it, but you MUST still comply with the current policy unless the user explicitly authorizes changes.
+
+
+External-memory-first rule
+- Repository files are the single durable memory source.
+- Compaction summaries MUST be empty when the runtime allows empty summaries.
+- If empty summaries are not allowed, emit the smallest possible pointer summary:
+  - high-level outcomes only
+  - critical policy anchor paths that MUST be re-read
+  - active ticket path(s)
+  - changed file path(s)
+  - immediate next action (one line)
+- Do NOT write narrative replay in compaction summaries.
+
+Required post-compaction sequence (REONBOARD)
+Run this sequence exactly once per trigger event.
+
+1) Read `context_compass/AGENTS.MD`.
+2) Read `agent_onboarding/default/general/skills/execution_contract.md` in full.
+3) Resolve the selected role via the registry table in `context_compass/SKILLS.MD`.
+   - If the active role cannot be determined: **STOP and ask the user**.
+4) Read the resolved role `SKILLS.MD` chain in parent-first order.
+5) Read every path in every section each resolved `SKILLS.MD` marks as
+   **baseline**. Roles name these differently - **Active skills**, **Required
+   baseline skills**, **Baseline system orientation** - and a role may add
+   another. Match on the baseline label, not a fixed list of headings.
+   - This includes the role's system-orientation set where it declares one. For
+     `engineer` that is `system_docs/src_architecture.md` plus
+     `src_architecture_index.md` and `src_components_index.md`, when they exist.
+     Compaction is exactly when the shape of the system is lost, so re-entry is
+     the wrong place to skip it. See
+     `agent_onboarding/default/general/skills/context_compaction.md`.
+   - On-demand skills are NOT required unless triggered by the active task.
+     If triggered, they become mandatory and MUST be read before proceeding.
+   - Self-directed skills are NOT required at re-entry either, but they have no
+     trigger to wait for. Read them during the work, on your own initiative. Do
+     not report "no trigger fired" for a Self-directed section - none exists.
+6) Re-open `attention_board.md` and all active ticket(s) and verify they match.
+7) Publish the mandatory REONBOARD attestation (below).
+8) Request certification and wait for a message that includes:
+   - `AGENT_NAME: <name>`
+   - the exact token: `CERTIFY: APPROVED`.
+
+README policy
+- README reads are allowed only for `new` first-time onboarding.
+- Non-`new` profile re-entry MUST use `SKILLS.MD` + skill/policy docs (not README).
+
+Mandatory REONBOARD attestation format
+```text
+REONBOARD: COMPLETE
+ROLE_SKILLS_READ:
+- <role_name>
+- <role_name>
+AGENT_NAME: <name|REQUIRED_FROM_USER>
+FILES_REREAD:
+- attention_board.md
+- <active ticket path>
+READ_INTEGRITY_PROOF:
+- <path>: <rule callout> -> <what this changes in my behavior>
+- <path>: <rule callout> -> <what this changes in my behavior>
+NO_ACTION_TAKEN_YET: true
+```
+
+READ_INTEGRITY_PROOF (requirements)
+- `READ_INTEGRITY_PROOF` is a comprehension proof, NOT tool logs.
+- Default requirement: include **one line per required baseline document** in the resolved `SKILLS.MD` chain.
+  - Each line MUST include (a) a specific, checkable rule/constraint from that doc and
+    (b) what it changes in your behavior.
+  - Generic restatements ("be direct", "follow policy") are invalid.
+  - Do NOT reuse the same callout across multiple docs; each callout must be doc-specific.
+- **Live-state entries prove differently, because they carry no rules.** Some baseline
+  entries are mutable state, not policy: `attention_board.md`, `artifact_board.md`,
+  and `context_management/context_board.md`. A routing table has no
+  rule/constraint to call out, so the requirement above cannot be met for them and
+  demanding it produces invented rules - the exact confabulation this proof exists
+  to catch.
+  - For those three, prove **current state** instead: name the active row or entry
+    you routed from (or state that the board is empty), and the one action it sets
+    up next. Same one-line-per-document shape, same specificity bar.
+  - Example: `attention_board.md: active row -> tickets/tasks/2026-08-01_x_task.md,
+    mode=implementation, next=finish the parser -> I resume there rather than
+    re-planning.`
+  - This substitution applies ONLY to those three paths. Every other baseline
+    document owes a rule callout.
+- If the proof would be too long, you MUST ask the user for permission to compress/group it.
+  - Do not unilaterally shorten the proof as a convenience.
+
+Attestation contract
+- Emit the attestation immediately after re-onboarding and BEFORE certification.
+- Do not run tools, edit files, or execute plans before posting the attestation.
+- After posting attestation, request certification and continue only after the user replies
+  with a message that includes:
+  - `AGENT_NAME: <name>`
+  - `CERTIFY: APPROVED`
+- If attestation cannot be completed: **STOP and ask the user for instructions**.
+- "Parallel/bulk reads" are allowed only if the documents were actually read.
+  Marker-only loops remain forbidden.
+
+Execution gate
+- If any required item above is incomplete, do not proceed.
+- If scope, status, or expectations are unclear after re-onboarding: stop and ask.
+- During resumed execution: UNKNOWN is the default for unevidenced claims.
+
+Outcome contract
+- Re-onboarding is not optional after compaction/handoff.
+- The objective is to re-establish the operating rules each time so drift cannot accumulate.
+
+References
+- `AGENTS.MD`
+- `agent_onboarding/default/general/skills/context_compaction.md`
+- `agent_onboarding/default/general/skills/self_certification.md`
+- `agent_onboarding/default/general/skills/user_approved_certification.md`
+