contextcompass 2.15.0__py3-none-any.whl

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

@@ -0,0 +1,111 @@
+
+
+# llm_full_usage
+
+## Purpose
+- Read `llm_full.md` - the whole package concatenated into one file - without
+  loading a million characters to answer a question about three of them.
+- Establish that the index is the entry point and the document is not.
+
+## What these two files are
+
+`llm_full.md` is every shipped package file end to end. `llm_full_index.md`
+records the line range each file occupies, plus a staleness proof.
+
+They live at the REPOSITORY root, not inside `context_compass/`. They are a view
+of the package, not part of it, which is why the package can be installed
+without them.
+
+Generated together by one pass:
+
+```bash
+python context_compass/tools/build_llm_full.py \
+    --root context_compass --out llm_full.md
+```
+
+The index is a **byproduct of that pass**, not a re-parse. The ranges were
+recorded by the loop that emitted the lines, so index and document cannot
+disagree. Contrast `index_document.py`, which re-walks an authored document's
+headings and therefore has to be guarded by a hash.
+
+## The rule
+
+**Read the index. Slice what you need. Never read the document whole.**
+
+`llm_full.md` is ~27,000 lines and ~1.1 MB. Reading it to find one skill is not
+thoroughness, it is a context-window fire. The index is ~450 lines and tells you
+exactly where everything is.
+
+## How to read one file
+
+```bash
+# 1. find it in the index
+rg 'AGENTS.MD' llm_full_index.md
+#    | 11-402 | `context_compass/AGENTS.MD` | 392 | 15204 |
+
+# 2. read exactly those lines
+sed -n '11,402p' llm_full.md
+```
+
+Or let the tool do both, which verifies the index first:
+
+```bash
+python context_compass/tools/build_llm_full.py \
+    --root context_compass --out llm_full.md --slice context_compass/AGENTS.MD
+```
+
+**Give it enough path to be unambiguous.** `--slice` matches on substring, and
+bare `AGENTS.MD` matches 19 files - the root entrypoint plus one per role. When
+several match it lists them with their ranges and refuses rather than guessing,
+so an ambiguous query costs you a round trip, never the wrong file:
+
+```
+3 files match 'SKILLS.MD' - narrow it:
+  19-26   context_compass/SKILLS.MD
+  28-32   context_compass/agent_onboarding/default/engineer/SKILLS.MD
+  40-44   context_compass/agent_onboarding/user_defined/myrole/SKILLS.MD
+```
+
+That listing is usable directly - take the range you wanted and `sed` it.
+
+## Verify before you trust a range
+
+```bash
+python context_compass/tools/build_llm_full.py \
+    --root context_compass --out llm_full.md --check
+```
+
+A line-offset index is more fragile than the text it indexes. Insert one line
+near the top and every range below it is wrong - while still parsing, still
+returning content, and returning the WRONG content confidently. The index
+carries `line_count`, `line_ending` and `content_sha256` for exactly this
+reason, and `--slice` recomputes them before returning anything.
+
+**On mismatch: STOP.** Regenerate, or read the real file under
+`context_compass/`. Do not eyeball an offset. Say which you did.
+
+## When to use this at all
+
+Use `llm_full.md` when the relationships between files are the point: reviewing
+a change to the onboarding contract, working out why two policies disagree,
+handing the whole system to a model that cannot browse a filesystem.
+
+Do NOT use it as a substitute for reading the real file. If you are working
+inside a repository that has `context_compass/`, read the file directly - it is
+authoritative, it is what agents actually load, and it cannot be stale. This
+document is a snapshot, and a snapshot is stale the moment the package changes.
+
+## Anti-patterns (reject)
+
+- Reading `llm_full.md` whole because "it is only one file".
+- Slicing a range without recomputing the staleness proof.
+- Quoting `llm_full.md` as evidence when the real file is on disk. Cite
+  `context_compass/<path>:<start>-<end>`, not a range into a generated view.
+- Hand-editing either file. Both are derived; edit the package and regenerate.
+- Treating a stale index as "close enough" and adjusting the offset by eye.
+
+## References
+- `agent_onboarding/default/engineer/skills/src_graph_usage.md` - the same
+  index-then-slice discipline, applied to the source graph
+- `agent_onboarding/default/engineer/skills/system_document_build.md` - the
+  index format specification

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

@@ -0,0 +1,85 @@
+# Mailbox Protocol
+
+Canonical board: `context_compass/mailbox_board.md`.
+Alert surface: `## Message Alerts` section at the top of
+`context_compass/attention_board.md`.
+
+## Why this exists
+
+Targeted agent-to-agent communication previously routed through
+`attention_board.md` attention details (board bloat, no addressee
+semantics) or through the user manually ferrying data between agents.
+The mailbox gives addressed, consume-on-read delivery while keeping
+`attention_board.md` routing/broadcast-only and keeping tickets as the
+single durable history.
+
+## Check-in (mandatory, onboarding-time)
+
+- During onboarding AND re-onboarding, open `mailbox_board.md` and add or
+  update your row in `## Checked-In Agents`:
+  `| <agent_name> | <owner> | <checked_in_at> | <last_checked> | active |`
+- `checked_in_at` is set when you first check in for the session;
+  `last_checked` updates EVERY time you read the message section.
+- Timestamps are ISO-8601 UTC, same as all boards.
+- When your session ends deliberately (final closure of your last lane),
+  set `status` to `departed`. Stale `active` rows older than a day may be
+  marked `stale` by any agent during their own check-in.
+
+## When checking is required (keep it cheap)
+
+- If you are the ONLY agent in `## Checked-In Agents` with status
+  `active`, the mailbox imposes no further duty. Do not poll it.
+- If MULTIPLE agents are active, read your messages:
+  - at onboarding / re-onboarding (after check-in),
+  - at every lane open, lane switch, and lane closure,
+  - periodically between substantial work units (a board glance when you
+    already touch `attention_board.md` is sufficient cadence),
+  - whenever `attention_board.md` `## Message Alerts` names you.
+
+## Sending a message
+
+1. Append a structured entry to `## Messages` in `mailbox_board.md`:
+   - `TO:` recipient agent_name (one recipient per message; send two
+     messages for two recipients)
+   - `FROM:` your agent_name
+   - `DATETIME:` ISO-8601 UTC
+   - `TYPE:` `HANDOFF` (work/finding transfer), `NOTICE` (FYI a lane
+     needs), `QUESTION` (needs a reply), `ACK` (reply/receipt)
+   - `CLAIM:` one to five lines, specific and actionable
+   - `EVIDENCE:` `path:start-end` or ticket path (required for
+     HANDOFF/NOTICE; tickets/source stay the canonical content)
+   - `ACK_REQUESTED:` true|false
+2. Add one alert line to `attention_board.md` under `## Message Alerts`:
+   `- NEW MESSAGE for <agent_name> (from <agent_name>, <DATETIME>)`
+3. Keep messages pointer-heavy. Never paste secrets, large code blocks,
+   or content that belongs in a ticket note.
+
+## Receiving a message
+
+1. For each message addressed to you, copy anything actionable into your
+   active (or a new) ticket's `## Notes` first - durable history lives in
+   tickets, never in the mailbox.
+2. DELETE the message from `## Messages`. Consumption is deletion; a
+   read message must not linger.
+3. Clear your alert line(s) from `attention_board.md` `## Message Alerts`
+   in the same working pass.
+4. If `ACK_REQUESTED: true`, send a `TYPE: ACK` message back (with its
+   own alert line).
+5. Update your `last_checked` timestamp.
+
+## Concurrency discipline
+
+- Both boards are shared files: on a write-conflict, re-read the current
+  content and retry your edit against it. Never resolve a race by
+  overwriting another agent's concurrent change.
+- Legal writes are: appending messages, maintaining YOUR check-in row,
+  and deleting messages addressed TO YOU. Never delete or edit another
+  agent's messages or check-in row (stale-marking excepted).
+
+## Boundary with attention_board.md
+
+- Broadcast facts every lane must see (API/key-map changes, repo-wide
+  regressions) remain `attention_board.md` attention details.
+- Point-to-point content (handoffs, questions, acks, FYIs for one agent)
+  belongs here. If you are about to write an attention detail naming a
+  single agent, it is a mailbox message.

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

@@ -0,0 +1,28 @@
+
+
+# memory_management
+
+Purpose
+- Define how durable context is stored and maintained in this repo.
+
+Policy
+- Use `tickets/epics/`, `tickets/stories/`, and `tickets/tasks/` tickets as the primary durable memory.
+- Use `attention_board.md` as routing-only state to select the active ticket.
+- Store decisions, assumptions, and handoff context in ticket sections.
+- Maintain a `## Notes` section in active tickets for in-flight findings with
+  `path:start_line-end_line` evidence pointers (`start=end` if single-line).
+- Use UNKNOWN as the default claim state and promote to FACT only when evidence is attached.
+- Avoid separate memory stores or ad-hoc JSON logs.
+
+Safety rules
+- Never store secrets in tickets or docs.
+- Prefer concise, evidence-based notes over speculative memory.
+
+References
+- `context_compass/SKILLS.MD`
+- `agent_onboarding/default/general/skills/workflow.md`
+- `agent_onboarding/default/general/skills/active_documentation.md`
+
+
+
+

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

@@ -0,0 +1,40 @@
+
+
+# mrp_policy
+
+Purpose
+- Enforce MRP (Most Reasonable Product) as the default strategy.
+
+MRP (Most Reasonable Product)
+- Definition: the smallest product that is still coherent, trustworthy, and
+  durable enough that shipping it does not create a trap.
+- Framing: build it like there is no patch coming, no second chance, and no
+  acceptable excuse to ship the core wrong.
+- Quality bar: the core experience, boundaries, lifecycle, operability, and
+  failure behavior must be right enough that the system can grow without a
+  foundational rewrite.
+- Ship rule: if the core would need to be reworked immediately after release to
+  become trustworthy, it is not MRP yet.
+- Practical analogy: treat the build like `Super Mario World`, not a
+  patch-it-later live-service product. If the core has to be right the first
+  time, MRP is the standard.
+- Non-goal: MRP is not perfectionism. It does not mean infinite polish. It
+  means the foundational system must be right, coherent, and safe to build on.
+
+MVP (Minimum Viable Product) - Disallowed
+- MVP is optimized for speed to validate demand, not robustness.
+- MVP is disallowed in this repo.
+
+MLP (Most Lovable Product) - UI Only
+- MLP focuses on delight, polish, and adoption.
+- Allowed only for UI/UX tasks and only after the MRP core is solid.
+
+Decision heuristic
+- If uncertainty is about foundation reliability, choose MRP.
+- If the choice is between shipping faster and getting the core right, choose
+  getting the core right.
+- If the product would become technical debt the moment it ships, it is not
+  MRP.
+- If success depends on love/retention/referrals, apply MLP after MRP.
+- Default to MRP when in doubt.
+

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

@@ -0,0 +1,135 @@
+# package_upgrade
+
+Purpose
+- Take an existing `context_compass/` folder and bring it up to a newer version
+  of the package without destroying the project's work.
+- Give you enough of the algorithm to reimplement it if Python is unavailable.
+
+This is the general-audience skill. `engineer/skills/package_maintenance.md`
+covers cleanup, release preparation, and the manifest generator in more depth.
+
+## The shape of the operation
+
+```bash
+python context_compass/tools/update_context_compass.py \
+    --install path/to/your-repo/context_compass \
+    --new     path/to/new/context_compass \
+    --check
+```
+
+- `--install` is **yours**. It is modified in place.
+- `--new` is **read-only**. Nothing is ever written to it, so ten repositories
+  can point at the same downloaded copy.
+- `--check` prints the plan and writes nothing. Run it first, every time.
+- `--apply` performs it.
+
+The direction is one-way. It never pushes your changes back upstream. If you
+improved a default role locally and want it in the package, that is a manual
+copy.
+
+## What decides each file
+
+`MANIFEST.md` in your install records the sha256 of every file **as it shipped**.
+Three hashes, four outcomes:
+
+| current vs shipped | new vs shipped | verdict |
+| --- | --- | --- |
+| same | changed | replace - the package moved, you did not |
+| same | same | skip - already current |
+| changed | same | **keep yours** - you moved, the package did not |
+| changed | changed | **conflict** - reported, not touched |
+
+One hash tells you a file changed. It cannot tell you WHO changed it, and that
+is the only question that decides whether overwriting is safe. Conflicts are
+never merged automatically; a merge is a guess and a wrong guess destroys work
+silently. Resolve by hand, or pass `--force-conflicts` to take the package
+version and lose the local edit knowingly.
+
+## What is never touched
+
+| lane | why |
+| --- | --- |
+| `system_docs/` | your architecture, component and test maps |
+| `tickets/` | your work |
+| `artifacts/` | your findings |
+| `context_management/` | your context board |
+| `special_instructions/` | your project rules |
+| `agent_onboarding/user_defined/` | your role overlays |
+
+An upgrade that rewrites someone's architecture map is not an upgrade.
+
+Two lanes get partial handling:
+
+- **the boards** carry a package-owned block between `<!-- BEGIN MANAGED: ... -->`
+  and `<!-- END MANAGED: ... -->`. Only that block is swapped; your routing rows
+  below it survive.
+- **`config/context_compass_config.yaml`** is merged key by key. New top-level
+  keys arrive with package defaults and their comments; a value you already set
+  is never overwritten; keys dropped upstream are reported, not deleted.
+
+## First upgrade of an older install
+
+An install predating the manifest has no shipped hashes, so a local edit and an
+upstream change are indistinguishable. The tool does not guess: it reports
+**every** differing file as a conflict, still skips identical files, and still
+adds new ones. Review, then `--force-conflicts` if you want the package version.
+Either way it writes the manifest, so this happens exactly once.
+
+## If Python is not available
+
+The tools are stdlib-only Python, but nothing about the algorithm requires
+Python. Reimplement it in PowerShell, bash, or whatever the environment has.
+**Do not skip the three-hash rule to make the port easier** - a port that
+compares only current-vs-new will silently overwrite local edits, which is worse
+than no tool.
+
+What a port must do:
+
+1. **Parse `MANIFEST.md`.** Rows under `## Files` are
+   `| path | class | sha256 |`. Read both manifests: the install's (shipped) and
+   the new version's (incoming).
+2. **Skip by class.** `RESET` and `INSTANCE` are never touched. `CONFIG` is
+   merged, never replaced. `LIVE` gets only its `MANAGED` block swapped.
+3. **For every `PACKAGE` file**, hash the install's copy and apply the table
+   above. Report conflicts; do not resolve them.
+4. **Copy new files** the install does not have.
+5. **Report files dropped upstream** that are still present locally. Do not
+   delete them - the package no longer ships it, which is not the same as the
+   project not wanting it.
+6. **Write the new manifest** into the install, last.
+
+Minimum viable shell version, in outline:
+
+```bash
+# sha256 of a file, portable enough
+sha() { sha256sum "$1" 2>/dev/null | cut -d' ' -f1 || shasum -a 256 "$1" | cut -d' ' -f1; }
+
+# read "path class sha" triples out of a manifest
+rows() { grep '^| `' "$1" | tr -d '`' | awk -F'|' '{print $2, $3, $4}'; }
+```
+
+```powershell
+function Get-Sha { param($p) (Get-FileHash -Algorithm SHA256 $p).Hash.ToLower() }
+```
+
+Then implement the table. It is a dozen lines of branching, not a project.
+
+**Verify the port before trusting it** by constructing the four cases
+deliberately: a file only the package changed, a file only you changed, a file
+both changed, and an identical file. If your port does not keep the second and
+refuse the third, it is not finished.
+
+## Anti-patterns
+
+- Running `--apply` without reading a `--check` plan first.
+- Comparing current against new only, with no shipped hash. That is the
+  single-hash trap: it cannot see the difference between your edit and an
+  upstream change, so it either clobbers you or never updates.
+- Auto-resolving conflicts by taking the newer file.
+- Upgrading `--new` by accident. It is the source, not the target.
+- Forgetting the release step: a package published without running
+  `tools/package_manifest.py` has no manifest, and nothing can upgrade from it.
+
+References
+- `agent_onboarding/default/engineer/skills/package_maintenance.md`
+- `agent_onboarding/default/general/skills/configuration_standards.md`

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

@@ -0,0 +1,105 @@
+
+
+# reactive_documentation
+
+Purpose
+- Keep compaction-proof breadcrumbs while work is in flight.
+- Capture broad findings quickly without losing source truth.
+- Preserve momentum by recording only what must be re-read later.
+
+When to use
+- Any investigation, debugging pass, architecture revalidation, or broad repo trace.
+- Immediately after discovering a core claim that could be lost after compaction.
+
+Core stance
+- Do not dump raw transcript sludge as durable memory.
+- Do not over-structure notes into heavy ceremony.
+- Use targeted, broad claims plus exact evidence pointers.
+- Start from UNKNOWN and promote to FACT only with evidence.
+
+Canonical storage
+- Tickets are first-class memory:
+  - `Notes` for in-flight findings captured during execution.
+  - `Decision Log` for accepted facts and decisions.
+  - `Unknowns` for unresolved or blocked claims.
+  - `Context / Handoff Summary` for current state and next actions.
+- `attention_board.md` is routing-only state, not detailed finding storage.
+- Avoid creating side memory stores unless explicitly requested.
+
+Reactive capture protocol (mandatory)
+1) Classify claim type:
+   - `FACT`: verified directly in source.
+   - `UNKNOWN`: not yet verified or ambiguous.
+   - `HYPOTHESIS`: explicit idea/opinion awaiting evidence.
+   - `DECISION`: explicit direction and rationale.
+   - `DECISION_REQUEST`: explicit Architect decision required before proceeding.
+   - `PLAN`: concrete next implementation slice.
+   - `STRATEGY_DISCUSSION`: structured options analysis needed before implementation.
+   - `ASSUMPTION_CHALLENGE`: explicit challenge to an assumption with evidence.
+   - `CONFLICT`: evidence-backed contradiction between direction and mission outcomes.
+   - `TRADEOFF`: multiple viable options with meaningful pros/cons.
+   - `BLOCKER`: hard stop requiring external unblock action.
+   - `ALIGNMENT_CHECK`: explicit scope/intent confirmation checkpoint.
+   - `MEASURE`: validation/profiling result.
+   - `RISK`: risk that needs mitigation follow-up.
+   - `RAISE`: immediate generic escalation when a serious issue is detected and precise type is not yet clear.
+2) Record one broad claim line:
+   - 1-2 sentences, general and scannable.
+3) Attach evidence pointers:
+   - `path/to/file.py:start_line-end_line` (preferred), plus symbol when useful.
+4) Mark re-read priority:
+   - `REQUIRED`: must reopen on next session.
+   - `HELPFUL`: context only.
+5) Add compaction usefulness score:
+   - `SCORE_0_TO_10` (must meet
+     `workflow.ticket_microcycle.minimum_note_score`).
+6) Record one concrete next action:
+   - single step that moves verification or implementation forward.
+
+Entry template
+- `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`: <broad finding>
+- `EVIDENCE`:
+  - <path:start_line-end_line>
+  - <path:start_line-end_line>
+- `REREAD`: REQUIRED | HELPFUL
+- `SCORE_0_TO_10`: <0-10>
+- `NEXT`: <single concrete step>
+- Detailed collaboration semantics for each `TYPE` are defined in:
+  `context_compass/agent_onboarding/default/general/skills/execution_contract.md`.
+- `RAISE` notes must be recategorized to a concrete type within one microcycle.
+
+Quality bar
+- Prefer targeted claims over narrative replay.
+- Every durable claim needs `file:start_line-end_line` evidence.
+- No evidence means mark it `UNKNOWN`.
+- Keep entries append-only when possible.
+
+Anti-patterns
+- Long logs with no evidence.
+- Broad assertions with no file pointers.
+- Rewriting history instead of adding incremental updates.
+- Treating speculative reasoning as fact.
+- Implementing directly from UNKNOWN/HYPOTHESIS without evidence-backed promotion.
+
+Re-entry checklist
+- Open active ticket handoff summary first.
+- Re-open entries marked `REREAD: REQUIRED`.
+- Resume from the most recent `NEXT` action.
+
+References
+- `agent_onboarding/default/general/skills/memory_management.md`
+- `agent_onboarding/default/general/skills/active_documentation.md`
+- `agent_onboarding/default/general/skills/compaction_requirements.md`
+- `agent_onboarding/default/general/skills/workflow.md`
+- `context_compass/SKILLS.MD`
+
+
+
+
+
+

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

@@ -0,0 +1,25 @@
+
+
+# repo_topology
+
+Purpose
+- Define the standard repo layout for this project.
+- Keep onboarding/certification focused on documentation and ticket routing.
+
+Repository layout
+- Repo root is the project root (this checkout).
+- Primary code lives under `src/` and tests under `tests/`.
+- Planning and onboarding live under `agent_onboarding/`, `tickets/epics/`,
+  `tickets/stories/`, `tickets/tasks/`, and `templates/`.
+- Completed items live in matching completed folders.
+
+Collaboration note
+- Certification in this repo is token-based (`CERTIFY: APPROVED`).
+- Code-management workflows are user-directed and out of onboarding policy
+  scope.
+
+References
+- `README.md`
+- `AGENTS.MD`
+
+

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

@@ -0,0 +1,41 @@
+# role_local_workflows
+
+Purpose
+- Define how workflows are stored and governed in Context Compass.
+
+Rules
+- Workflows are first-class role artifacts.
+- Actual workflow definitions live inside roles, not in a top-level registry.
+- Canonical role-local paths are:
+  - `<role_root>/WORKFLOWS.MD`
+  - `<role_root>/workflows/`
+- Templates may live at the top level under `templates/`.
+- Workflows are user-generated and user-approved only.
+- Agents may suggest or scaffold workflows when explicitly asked.
+- Agents must not silently create, modify, or adopt a new workflow at their
+  own discretion.
+- Workflow inheritance is parent-first by role chain, mirroring the skill
+  model conceptually.
+- Role-local workflow manifests should stay lightweight:
+  - purpose
+  - inheritance
+  - activation rule
+  - active workflow paths or `none`
+  - optional on-demand workflow paths or `none`
+- Active workflows are baseline-readable for that role.
+- On-demand workflows are discoverable but should not be read until:
+  - the user explicitly asks to use them, or
+  - the current task explicitly triggers them.
+- A role may mix:
+  - active starter workflows
+  - on-demand scaffolding workflows
+  in the same manifest, as long as the distinction is explicit.
+
+Non-goals
+- This does not create a top-level workflow registry.
+- This does not require every role to define active workflows immediately.
+
+References
+- `PROFILE_CLASS_CREATION_GUIDE.md`
+- `templates/workflow_simple_template.md`
+- `templates/workflow_advanced_template.md`

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

@@ -0,0 +1,46 @@
+
+
+# security_and_secrets
+
+Purpose
+- Enforce a strict no-secrets-in-repo policy.
+- Provide safe alternatives for secret handling during agent work.
+- Define refusal conditions when a user requests unsafe storage.
+
+Non-negotiable rules
+- Never store secrets anywhere in the repo, including `agent_onboarding/`, `tickets/epics/`,
+  `tickets/stories/`, `tickets/tasks/`, `tickets/epics/completed/`, `tickets/stories/completed/`,
+  `tickets/tasks/completed/`, `artifacts/`, `user_defined/`, and `system_docs/`.
+- The list above is illustrative, not exhaustive. **No path in this repository is a
+  permitted location for a secret**, including one this list does not name.
+- Never write secrets into tickets, docs, or logs.
+- Never commit secrets, even temporarily, even in test data.
+- If a user requests storing secrets in-repo, refuse and ask for a safe alternative.
+
+What counts as a secret
+- Credentials (API keys, tokens, passwords, cookies).
+- Private keys, certificates, or access URLs with embedded credentials.
+- Internal endpoints that include authentication material.
+- Any value the user labels as secret/confidential.
+
+Approved alternatives
+- Environment variables injected at runtime.
+- OS keychain or secret manager (1Password, Keychain, Vault, etc.).
+- CI/CD secret store or runtime injected config.
+- Runtime-only prompts (no persistence, no logging).
+
+Refusal protocol (required)
+- State that storing secrets in-repo is not allowed.
+- Provide at least one safe alternative and ask for confirmation.
+- Do not proceed with any write that would persist the secret.
+
+Logging and output hygiene
+- Do not print secrets to stdout/stderr.
+- If a secret appears in input, do not echo it back.
+- Mask or omit secrets in examples and documentation.
+
+References
+- `AGENTS.MD`
+
+
+

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

@@ -0,0 +1,49 @@
+
+
+# self_certification
+
+Purpose
+- Ensure onboarding is complete before any tool usage or edits.
+
+Required flow
+- Read routing authority 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`
+- Complete role-driven onboarding reads from:
+  - `context_compass/config/context_compass_config.yaml`
+  - `context_compass/SKILLS.MD`
+  - the resolved role `SKILLS.MD` chain.
+- For a given trigger event, complete the readset once; do not duplicate-read
+  the same onboarding set before certification unless a new
+  compaction/handoff/session-reset event occurs.
+- Manual source-document reading from the readset is required; onboarding dump
+  files are non-compliant.
+- Performative onboarding is forbidden: marker-only reread logs do not satisfy
+  the read requirement.
+- If the user challenges onboarding truthfulness (e.g., "you didn't read that", "you're lying",
+  "performative compliance"):
+  - Treat certification as NOT granted (or revoked) and STOP.
+  - Re-onboard/re-onboard as required, then re-request `CERTIFY: APPROVED`.
+  - Do not debate, rationalize, or offer bypass options.
+- Before requesting certification, provide concise **read-integrity proof**:
+  - concrete rule callouts from reread docs, AND
+  - a one-line "what this changes in my behavior" per callout.
+  - Tool logs/dumps are not proof.
+- Before requesting certification, include `AGENT_NAME` in the attestation:
+  - use the provided name if the user already gave one in the current trigger event
+  - otherwise use `AGENT_NAME: REQUIRED_FROM_USER`
+- For ONBOARD/REONBOARD attestations, keep declarations concise with
+  `ROLE_SKILLS_READ`, `AGENT_NAME`, and `NO_ACTION_TAKEN_YET: true`.
+- Summarize that onboarding is complete and request approval.
+- Require the approval message to include:
+  - `AGENT_NAME: <name>`
+  - the exact token `CERTIFY: APPROVED`.
+- Do not use tools or edit files until the user provides that token.
+
+Certification record
+- Track certification in the session narrative and update `attention_board.md`
+  routing when certification state affects execution.
+
+