@ahmed-g-gad/apothem 0.1.1

package/src/apothem/skills/secret-rotation/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: "secret-rotation"
+version: "0.1.0"
+updated: "2026-06-22"
+description: "Safe secret-rotation template — matched when the user says 'rotate a secret', 'a key leaked', 'a token leaked', 'a credential is exposed', 'revoke and re-issue this key', 'an API key was committed', or any phrasing that asks to safely retire and replace an exposed credential. Treats a leaked credential as compromised the moment it touched a tracked file and enforces the revoke-before-re-issue ordering invariant: detects the coarse exposure surface, revokes the compromised credential at its issuer FIRST, re-issues a least-privilege replacement, rewires configuration through env-var or secret-manager indirection (never plaintext), and verifies no plaintext residue remains in the working tree or version-control history. NOT a full secret-scanner (routes the broad sweep to the host's scanner), NOT an issuer client, NOT a history-rewrite engine. User-invocable directly."
+archetype: "security-template"
+userInvocable: true
+argument-hint: "[--scope PATH]"
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+## Purpose
+
+Drive the safe rotation of an exposed secret end to end: detect the exposure surface, revoke the compromised credential at its issuer, re-issue a replacement, rewire configuration through indirection, and verify no plaintext residue remains.
+
+The skill treats a leaked credential as **already compromised the moment it touched a tracked file**. This drives the one non-negotiable ordering invariant of the whole procedure: **revoke before re-issue.** A replacement minted before the leaked key is revoked leaves both keys live — doubling the attack surface instead of closing it. Every step downstream of detection assumes the leaked key is in an adversary's hands.
+
+## Detection Signal
+
+The user asks to retire and replace a compromised credential. Trigger phrases: "rotate a secret", "a key leaked", "a token leaked", "a credential is exposed", "an API key was committed", "revoke and re-issue this key".
+
+## Non-Goals
+
+The skill carries a deliberately narrow surface. It is NOT:
+
+- **Not a full secret-scanner replacement.** Detection is coarse — high-entropy strings, known key prefixes, and the host's ratified secret patterns. Exhaustive scanning is `gitleaks` / `trufflehog` territory under `conformity/secret_leak_grep.py` and the host's CI; this skill routes the broad sweep there and acts on the confirmed exposure.
+- **Not an issuer client.** The skill names the revocation and re-issue steps the operator performs at the credential's issuer (cloud console, registry, identity provider); it does not hold issuer credentials or call issuer APIs on the operator's behalf.
+- **Not a history-rewrite engine.** History rewriting (`git filter-repo`, BFG) is surfaced as an operator decision under the per-file destructive-op floor, never executed silently.
+
+## Workflow
+
+Five ordered steps. The order is the safety contract — step 2 (revoke) MUST precede step 3 (re-issue); the procedure NEVER mints a replacement while the leaked key is still live.
+
+1. **Detect the exposure surface.** Glob the scope (`--scope PATH`, default project root) and Grep for the host's ratified secret patterns, known key prefixes, and high-entropy literals. Enumerate **every** file and line where the credential appears. Run `git log -p -S '<fragment>'` to find the historical commits that introduced or carried the secret. **Criterion:** the full surface — working tree AND history — is reported; the skill never acts on a partial enumeration, because a missed occurrence is a credential still leaking after rotation "completes".
+
+2. **Revoke the compromised credential at its issuer — FIRST.** Direct the operator to revoke the leaked credential at its issuer (cloud console, registry, identity provider) before any other action. A live leaked key is an open door; revocation closes it before a replacement exists. **Criterion:** revocation is confirmed by the operator. The skill does NOT advance to step 3 on an unconfirmed revocation — STOP and re-confirm.
+
+3. **Re-issue a replacement.** Direct the operator to mint a new credential at the same issuer with the **minimum scope** the workload requires (least-privilege, not a copy of the old grant). Capture the new value only into the step-4 indirection surface — **never echo it to STDOUT, never write it to a tracked file, never paste it into a report.** **Criterion:** a replacement exists and its value is held only behind indirection.
+
+4. **Rewire configuration through indirection.** Replace every plaintext occurrence from step 1 with an env-var reference or a secret-manager lookup discovered per `rules/host-discovery.md` (the host's ratified `.env` convention, vault path, or cloud secret-manager). The replacement reads the value at runtime; the tracked source carries only the **reference**. **Criterion:** zero plaintext secrets remain in tracked config — every site reads through indirection.
+
+5. **Verify no plaintext residue remains.** Re-run the step-1 sweep over the working tree and confirm **zero** plaintext hits. Re-run `git log -p -S '<fragment>'`; when the secret persists in history, surface the history-rewrite decision under the per-file destructive-op floor (one structured-inquiry invocation per affected ref, every option's `default-pointer:` carrying the verbatim `no-default: user decision required` marker). Confirm the new credential resolves through indirection and the workload reaches a working run. **Criterion:** working-tree sweep is clean, history disposition is decided (rewritten or operator-accepted-with-rationale), and the workload runs green on the replacement.
+
+## Return Contract
+
+Maximum response: 800 tokens. Structure:
+
+- **Summary:** one sentence stating the credential rotated and its disposition.
+- **Exposure surface:** every file / line / historical commit where the secret appeared.
+- **Actions taken:** revocation confirmation, re-issue confirmation, indirection rewiring per file.
+- **Residue verification:** working-tree and history sweep results; pending history-rewrite decisions.
+- **Surfaced gaps:** out-of-axis concerns (deeper scan, related credentials) per M6. Empty: `none`.
+
+## Foundational Stanzas
+
+The four standing surfaces every operator inherits, adapted to this skill's user-invocable security role so the destructive-op floor is preserved across the rotation surface.
+
+### Refusal & Escalation
+
+REFUSE any request that asks the skill to act outside its mission — exhaustive secret-scanning, holding issuer credentials, silent history rewriting, rotating a credential the operator has not confirmed exposed. Refusal is explicit: name what was refused, name the mission boundary crossed, and surface escalation through the structured-inquiry channel per `rules/interactive-questions.md` (canonical channel; three-segment option annotation; never free-form prose as primary input). When revocation cannot be confirmed, STOP before re-issue — a replacement minted beside a live leaked key doubles the exposure.
+
+### Output Surface
+
+The rotation report writes to STDOUT. NEVER write a captured secret value to a tracked file, a report, or STDOUT. Configuration edits land at the host's ratified paths per `rules/host-discovery.md`; indirection references replace plaintext in place. Audit-internal scratch lands under `.audit/` (gitignored-class per the canonical `.gitignore` snippet); NEVER write rotation working state to a global location.
+
+### File-Authoring Contract
+
+When the skill emits a NEW file (rare; the rotation path edits existing config in place), the file routes through `scripts/inject-header.py` so the canonical single-line SPDX license header is injected at the head; the injector is idempotent and detects the filetype variant automatically from the byte-exact fixture at `src/apothem/schemas/authorship-header.txt`. Exempt classes (LICENSE, JSON configuration files, lockfiles, generated assets, `.env` files, `.audit/` ephemera, binary files) are enumerated at `src/apothem/schemas/header-exceptions.txt`. Edits to existing config preserve any existing header.
+
+### Structured Inquiry on Ambiguity
+
+When the rotation reaches a decision in any of the seven authoritative-data categories per `rules/host-discovery.md` and `rules/authority-inquiry.md` — identity (credential owner), scope direction (which secret, which environment), preference (secret-manager choice), security (rotation cadence, allowed egress), naming of public surfaces, infrastructure endpoints (issuer, vault path), version pins — and the host is silent, route the resolution through the structured-inquiry channel with the three-segment option annotation per `rules/interactive-questions.md` §3 (rationale / recommendation / default-pointer). NEVER fabricate authoritative data. The replacement landing in production-ready form — config rewired, no plaintext residue, workload green — satisfies the same-change-set discipline per `rules/production-ready-prs.md`. **Per-file destructive-op floor.** Every history-rewriting step (`git filter-repo`, BFG, force-update of a ref) and every delete / overwrite-without-retention of an exposed file routes through the structured-inquiry channel on a per-file (per-ref) basis per `rules/interactive-questions.md` §6 — one invocation per ref, every time, no `multiSelect` batching, every option's `default-pointer:` carries the verbatim `no-default: user decision required` marker.
+
+## Recommended Next Step
+
+**Run `python -m apothem.conformity.gate --all .`** to run the host's mechanical conformity corpus — which includes the secret-leak matcher — and confirm zero plaintext-secret residue after rotation. (To scope the secret-leak matcher to a single touched file, use `--check secret-leak-grep <path>`; the bare `--check secret-leak-grep .` directory form is not a runnable invocation.)
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every exposed-credential rotation the operator invokes. ● Every plaintext-to-indirection config rewiring under the host's ratified secret surface. ◐ The per-ref history-rewrite decision under the destructive-op floor.
+- **Satisfies →** ● `CLAUDE.md` Source Layout row "secret-rotation" (skills/ class). ● `rules/production-ready-prs.md` supply-chain-posture preservation (no secret literal in tracked source).
+- **Established by ↑** ● `CLAUDE.md` Source Layout (skills/ folder-with-`SKILL.md` convention). ● `CLAUDE.md` Ambiguity Handling (structured inquiry over fabrication).
+- **Gated by ←** ● The harness's tool surface (Read / Write / Edit / Glob / Grep / Bash). ● Operator confirmation of revocation before re-issue.
+- **Cross-bound with ↔** ↔ `rules/host-discovery.md` (secret-manager and `.env` convention discovery). ↔ `rules/interactive-questions.md` (per-ref destructive-op floor on history rewrites). ↔ `rules/production-ready-prs.md` (supply-chain posture). ↔ `conformity/secret_leak_grep.py` (the mechanical sweep this skill routes to). ↔ `skills/ecosystem-audit/SKILL.md` (sibling skill under the same registry section).

package/src/apothem/skills/source-synthesis/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: "source-synthesis"
+version: "0.1.0"
+updated: "2026-06-22"
+description: "Reconcile a fixed set of provided sources into one cited synthesis — matched when the user says 'synthesize these sources', 'combine these documents', 'reconcile these', 'what do these say together', 'merge these notes into one', or any phrasing that hands over N specific documents and asks for a single consolidated reading. Extracts the claim set per source with citation anchors, reconciles agreements and contradictions across sources, and produces a cited synthesis that separates consensus from contested ground while flagging coverage gaps. User-invocable directly via `--sources`; never gathers or discovers sources of its own (that is the `multi-source-research` surface), never adjudicates which source is correct against ground truth (a contradiction is reported as contested, not resolved by fiat), and never synthesizes fewer than two sources (a lone source is summarized, not synthesized)."
+archetype: "research-template"
+userInvocable: true
+argument-hint: "[--sources GLOB_OR_PATHS]"
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Glob, Grep"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+## Purpose
+
+Reconcile a **fixed set of operator-provided sources** into one cited synthesis. The skill reads each named source, extracts its claim set with per-claim citation anchors, cross-references the claims to surface agreement and contradiction, and emits a single synthesis that separates what the sources **agree on** from what they **contest** — with every synthesized claim attributed to the source(s) that assert it.
+
+The discipline that distinguishes synthesis from summary: synthesis is **relational**. It does not merely report what each source says; it places each claim in relation to the others — consensus, contradiction, or solitary assertion — so the reader sees not just the content but its evidentiary weight. Per-claim attribution is non-negotiable: an unattributed synthesized claim is indistinguishable from a fabrication.
+
+## Detection Signal
+
+The user provides specific documents and asks for a consolidated reading. Trigger phrases: "synthesize these sources", "combine these documents", "reconcile these", "what do these say together", "merge these notes into one". The defining marker: the source set is **given, not requested** — the user names the inputs and asks for the union, never for new material.
+
+## Non-Goals
+
+The skill carries a deliberately narrow surface. It is NOT:
+
+- **Not source discovery.** The skill consumes the sources the operator provides via `--sources`. It does NOT search for additional documents, follow citations to new material, or fetch external references. Discovery of sources to synthesize is the `multi-source-research` surface; this skill begins where the source set is already fixed.
+- **Not a fact-checker.** The skill reconciles what the sources say against each other; it does NOT adjudicate which source is correct against ground truth. A contradiction is reported as contested, not resolved by fiat. External verification is out of scope.
+- **Not a summarizer of a single document.** Synthesis requires two or more sources to reconcile. A lone source is summarized, not synthesized; that request routes elsewhere.
+- **Not a content generator.** Every synthesized claim traces to a source claim. The skill introduces no assertion the sources do not support; unsupported ground is flagged as a gap, never filled.
+
+## Workflow
+
+Five ordered steps. Each step's output exists and is checkable before the next runs — the **Criterion** gates the advance.
+
+1. **Resolve the source set.** Expand `--sources` (glob or explicit paths) to a concrete file list and read each source. **Criterion:** the resolved list holds **two or more** sources and every path read successfully. A missing or unreadable source STOPs the workflow and surfaces the gap; a resolved set of fewer than two routes to single-source summary, not synthesis (per Non-Goals).
+
+2. **Extract the claim set per source.** For each source, enumerate its distinct claims and attach a **citation anchor** to each — source path plus the locating heading, line range, or quoted span — so a reader can verify the claim at its origin. **Criterion:** every source has a claim list, and every claim carries an anchor that resolves back to its source.
+
+3. **Reconcile across sources.** Cross-reference the per-source claim sets. Cluster claims by **subject**; within each cluster, assign exactly one relation:
+   - **Agreement** — two or more sources assert the same claim.
+   - **Contradiction** — sources assert mutually incompatible claims about the same subject.
+   - **Singleton** — one source only asserts the claim.
+
+   **Criterion:** every claim lands in exactly one subject cluster with exactly one assigned relation — no claim is unclassified, none double-counted.
+
+4. **Produce the cited synthesis.** Emit the consolidated reading with consensus and contested ground **visibly separated**: a **Consensus** section (agreed claims, citing every asserting source) and a **Contested** section (each contradiction, citing each side's source and conflicting anchors). **Criterion:** no synthesized claim lacks attribution; consensus and contested ground are structurally distinct, never blended into a single narrative that hides which ground is settled.
+
+5. **Flag gaps.** Name the subjects the source set leaves uncovered, the singleton claims (unconfirmed by a second source), and the contradictions left unresolved. **Criterion:** a Gaps section exists — even when its content is the single word "none" — so the reader always knows the boundary of what the sources can settle.
+
+## Return Contract
+
+A cited synthesis with four labeled sections, in order:
+
+- **Consensus** — claims asserted by two or more sources, each citing every agreeing source.
+- **Contested** — contradictions across sources, each side attributed to its source with the conflicting anchors.
+- **Singletons** — claims a single source asserts, marked **unconfirmed**.
+- **Gaps** — subjects the source set leaves uncovered plus contradictions left unresolved (`none` when empty).
+
+**Per-claim source attribution is mandatory.** A synthesized claim with no source anchor is a contract failure — it is the failure mode this skill exists to prevent, because an unattributed claim cannot be distinguished from invented material.
+
+## Foundational Stanzas
+
+### Refusal & Escalation
+
+REFUSE any request that pushes the skill past its mission — discovering new sources, fact-checking against external ground truth, summarizing a single document, or generating claims the sources do not support. Refusal is explicit: name what was refused, name the mission boundary the request crossed, and route the operator to the correct surface via the structured-inquiry channel per `rules/interactive-questions.md` (canonical channel; three-segment option annotation; never free-form prose as primary input). When `--sources` resolves to fewer than two sources, REFUSE the synthesis and surface the single-source-summary boundary instead.
+
+### Output Surface
+
+The synthesis writes to STDOUT for direct invocation. When the operator requests a durable artifact, it lands at the operator-named path under the host project per `rules/host-discovery.md`; per `rules/operational-mandates.md` CM-7, the artifact carries natural domain language with zero plan-internal references. NEVER write to a global-ecosystem location and NEVER fabricate a source path the operator did not provide.
+
+### File-Authoring Contract
+
+When the skill emits a NEW file, it routes through `scripts/inject-header.py` so the canonical authorship header is injected at the head; the injector is idempotent and detects the filetype variant from the byte-exact fixture at `src/apothem/schemas/authorship-header.txt`. Exempt classes are enumerated at `src/apothem/schemas/header-exceptions.txt`. Edits to existing files preserve any present header.
+
+### Structured Inquiry on Ambiguity
+
+When the skill reaches a decision in any of the seven authoritative-data categories per `rules/authority-inquiry.md` — identity, scope direction, preference, security, naming of public surfaces, infrastructure endpoints, version pins — and the input is silent, route the resolution through the structured-inquiry channel with the three-segment option annotation per `rules/interactive-questions.md` §3 (rationale / recommendation / default-pointer). Free-form prose questions as primary input are forbidden. NEVER fabricate authoritative data. Clean-room discipline per `rules/clean-room-generation.md` governs the synthesis prose: it is re-derived from the extracted claim sets, never paraphrased from a single source's framing.
+
+## Recommended Next Step
+
+**Run the skill against the resolved source set** with `--sources` naming the documents to reconcile; review the Contested and Gaps sections first, since they name the claims the source set cannot settle on its own.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every per-source claim extraction with citation anchors. ● Every cross-source reconciliation pass separating consensus from contested ground. ● The Gaps surface naming uncovered subjects and unresolved contradictions.
+- **Satisfies →** ● `CLAUDE.md` Source Layout row "source-synthesis" (skills/ class). ● The research cohort's provided-source reconciliation surface.
+- **Established by ↑** ● `CLAUDE.md` Source Layout (skills/ class declaration with the folder-with-`SKILL.md` convention). ● `CLAUDE.md` Ambiguity Handling (structured inquiry over fabrication).
+- **Gated by ←** ● The harness's Read tool surface. ● The presence of two or more resolvable sources in `--sources` (a single source routes to summary, not synthesis).
+- **Cross-bound with ↔** ↔ `rules/clean-room-generation.md` (the synthesis is re-derived, not paraphrased). ↔ `rules/interactive-questions.md` (the structured-inquiry channel on ambiguity). ↔ `skills/plan-suite/SKILL.md` + `skills/ecosystem-audit/SKILL.md` (sibling skills under the same registry section).

package/src/apothem/skills/surgical-guard/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: "surgical-guard"
+version: "0.1.0"
+updated: "2026-06-14"
+description: "Surgical-edit + reactive-guard skill — matched when the operator asks to 'edit surgically', 'make a minimal diff', 'guard this change', 'review the diff for quality', 'don't rewrite the whole file', or otherwise needs a precise, anchor-bounded mutation plus a post-edit quality pass before it lands. Stage 1 is a minimal-diff editing discipline: mutate through a managed-block or anchor-bounded edit (e.g. swap only the sentinel-delimited region, preserving the surrounding bytes and the authorship banner) — never a blunt whole-file overwrite where a scoped edit suffices. Stage 2 is a reactive, diff-based quality guard that reviews only the change's diff and loads only the rule references the diff's context matches (progressive disclosure), catching the systematic failure modes of generated changes: clean-code (swallowed errors, hardcoded success returns, hallucinated APIs, premature abstraction, silent contract changes), test (mock-boundary violations, duplicate bodies, hollow assertions, missing coverage of the changed behavior), docs (hallucinated symbols, broken samples, docs-vs-code drift). Not for: green-field file creation with no existing content to preserve (below the surgical threshold — routes to ordinary authoring); domain-framework linting with vendor-specific rule packs (out of scope — only the generalized clean-code/test/docs guard pattern is carried); producing the change's content via debugging or TDD (routes to dev-toolkit — this skill governs how the change lands and whether it passes). Harness-agnostic; deterministic output. Feeds the harness-directive surgical-manipulation mandate."
+archetype: "guard-template"
+userInvocable: true
+argument-hint: "[change target] [--guard clean-code|test|docs|all]"
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash, TodoWrite"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+## Purpose
+
+Land a change as a **precise, minimal, scoped mutation**, then **guard it reactively** before it is accepted. Two stages, one contract:
+
+1. **Surgical edit** — mutate through a managed block (sentinel-delimited region swapped, boundaries preserved) or an anchor-bounded edit, touching only the lines the change requires. Everything outside the anchor stays byte-for-byte identical, including the authorship banner. A blunt whole-file overwrite where a scoped edit suffices is refused.
+2. **Reactive guard** — a diff-based post-edit review that loads only the rule references the change's context matches (progressive disclosure) and catches the systematic failure modes of generated changes — swallowed errors, hollow tests, docs-vs-code drift — before the change is accepted.
+
+The pairing is the skill's robustness: the change is **both** surgically minimal **and** quality-attested. This skill supplies the surgical-manipulation discipline the harness directives mandate.
+
+## Detection Signal
+
+The operator asks to edit surgically, make a minimal diff, or not rewrite a whole file; asks to guard or review a change for quality; or hands off a mutation that should land scoped and attested rather than sweeping.
+
+**Falsifiable counter-signal.** A green-field file creation with no existing content to preserve is below the surgical threshold — it routes to ordinary authoring, not this skill.
+
+## Non-Goals
+
+A deliberately narrow surface. The skill is NOT:
+
+- **A whole-file rewriter.** Where a scoped, anchor-bounded edit satisfies the change, a blunt whole-file overwrite is refused — minimality is the contract.
+- **A domain-framework linter.** The source guard set carried framework-specific rule packs (a particular CMS / e-commerce platform); apothem generalizes the *guard pattern* (clean-code / test / docs) and does **not** carry those domain-specific packs — they are out of scope.
+- **A writing-time constraint engine.** The guard is a **reactive** post-edit diff pass, not a constraint that bloats every edit as it is written — the change is made, then guarded.
+- **The engineering-loop owner.** Producing the change's *content* (debugging, TDD, slicing) routes to `skills/dev-toolkit/SKILL.md`; this skill governs *how the change lands* (minimal diff) and *whether it passes* (the guard).
+
+## Foundational Stanzas
+
+The four standing surfaces every operator inherits per the canonical project voice at `AGENTS.md` plus the active harness mirror.
+
+### Refusal & Escalation
+
+REFUSE a whole-file overwrite where an anchor-bounded edit suffices — name the minimal alternative and apply it. REFUSE accepting a change the guard flags (swallowed error, hollow assertion, docs drift) without surfacing the finding — name it, never silently pass. REFUSE any request beyond surgical editing + reactive guarding; surface an escalation option through the structured-inquiry channel per `rules/interactive-questions.md`.
+
+### Output Surface
+
+Changes land at their domain-natural host locations per `rules/host-discovery.md` as minimal diffs; the guard report lands beside the change or in the working trace. Per `rules/operational-mandates.md` CM-7, the change and its commit carry natural domain language — zero process-internal scaffolding.
+
+### File-Authoring Contract
+
+Edits preserve any existing authorship banner — the surgical discipline never strips a header (corner case B of the header-inject-guard hook at `hooks/messages/pretooluse-{write,edit}-header-guard.md`). New files route through `scripts/inject-header.{sh,py}`; exempt classes at `src/apothem/schemas/header-exceptions.txt`.
+
+### Structured Inquiry on Ambiguity
+
+When the change's anchor / scope, the managed-block boundary, or a guard finding's disposition is ambiguous, route the resolution through the structured-inquiry channel with the three-segment option annotation per `rules/interactive-questions.md` §3 (rationale / recommendation / default-pointer). Every destructive operation (deletion, move, non-retaining overwrite) routes per-file through the §6 canonical destructive-op option sets — one invocation per file, every option's `default-pointer:` carrying the verbatim `no-default: user decision required`.
+
+## Conformity Posture
+
+**Discover-don't-assume preamble (M1).** Discover the host's managed-block / anchor convention (sentinel markers, comment-delimited regions) and its diff + review tooling per `rules/host-discovery.md`. The surgical anchor scheme is the host's, discovered — never imposed.
+
+**Minimal-diff attestation.** The change's diff is attested against the golden corpus (the host's green-gate baseline): a surgical edit that leaves the gates green is the minimal-diff golden-corpus contract this skill establishes and that the surgical-manipulation harness directive depends on.
+
+## Procedure
+
+Four numbered, independently-verifiable steps. The change's *content* is supplied upstream; this procedure governs *how it lands and whether it passes*.
+
+### 1. Locate the Anchor
+
+Locate the precise mutation site — a managed-block sentinel region, an anchor-bounded span, or the smallest contiguous range the change requires. Read only that range plus a tight buffer (locate-before-read per `rules/large-file-reading.md`). The anchor is the scope contract: the edit touches it and nothing else.
+
+### 2. Mutate Surgically
+
+Apply the change as a minimal diff at the anchor — a managed-block replacement (sentinel-delimited content swapped, boundaries preserved) or an anchor-bounded edit. Preserve everything outside the anchor byte-for-byte, including the authorship banner. No whole-file overwrite where a scoped edit suffices.
+
+### 3. Reactive Guard (diff-based, progressive-disclosure)
+
+Review the change's **diff** — not the whole file — against the guard set selected by `--guard` (default `all`), loading only the rule references the diff's context matches:
+
+- **clean-code guard** — swallowed / catch-all errors, hardcoded success returns, hallucinated APIs, premature abstraction, silent contract changes.
+- **test guard** — mock-boundary violations, duplicate test bodies, hollow assertions, missing coverage of the changed behavior.
+- **docs guard** — hallucinated symbols, broken samples, docs-vs-code drift introduced by the change.
+
+Each finding is surfaced with its offending diff locus. An accepted change carries no surviving guard finding — or each finding is explicitly dispositioned by the operator through the structured-inquiry channel.
+
+### 4. Attest & Self-Check
+
+Attest the minimal-diff golden-corpus contract: the change is scoped, the gates are green, the guard is clear. Run the fifteen-bar pre-emission gate per `rules/pre-emission-gate.md`. Emit the change, the guard report, and the single recommended next move.
+
+## Arguments
+
+- `[change target]` — the change to land, in natural language (the behavior to mutate, the anchor it touches).
+- `--guard clean-code|test|docs|all` — the reactive guard set (default: `all`).
+
+## Return Contract
+
+The skill returns:
+
+- **Minimal diff** — scoped to the anchor; everything outside it byte-identical.
+- **Guard report** — per-guard findings with diff loci, or a clean attestation.
+- **Minimal-diff golden-corpus attestation** — scope + green gates.
+- **Fifteen-bar gate attestation** per `rules/pre-emission-gate.md`.
+- A single `## Recommended Next Step`.
+
+Deterministic per `rules/determinism.md`: the same change target + anchor yields the same minimal diff.
+
+## Recommended Next Step
+
+**Invoke the `surgical-guard` skill via the Skill tool** with `<change> --guard all` — apply the change as a managed-block / anchor-bounded minimal diff, then review the guard report and disposition any finding before accepting. Route the change's *content* (the debugging / TDD that produced it) through the `dev-toolkit` skill, and keep this skill for *how the change lands and whether it passes*.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every surgical (minimal-diff, anchor-bounded) mutation across the host. ● The reactive diff-based quality guard on every guarded change. ● **The surgical-manipulation discipline the harness directives weave in** (this skill is its mechanism).
+- **Satisfies →** ● `CLAUDE.md` Source Layout row "surgical-guard" (skills/ class). ● The elevation dimension **robustness** (minimal-diff editing + reactive diff-based guard with progressive-disclosure rule loading).
+- **Established by ↑** ● `CLAUDE.md` Source Layout (skills/ folder-with-`SKILL.md` class). ● `CLAUDE.md` Ambiguity Handling (structured inquiry over fabrication). ● `rules/own-voice-reimplementation.md` (zero-verbatim; `reference-token-grep` = 0). ● `rules/agnostic-posture.md` (17-harness agnostic floor).
+- **Gated by ←** ● The host's discovered managed-block / anchor convention + diff tooling. ● The minimal-diff contract (no whole-file overwrite where a scoped edit suffices). ● The host's structured-inquiry + Edit + Write + Bash tool surface; the per-file destructive-op floor.
+- **Cross-bound with ↔** ↔ `skills/dev-toolkit/SKILL.md` (produces the change's content; this skill governs how it lands + whether it passes). ↔ `rules/own-voice-reimplementation.md` + `rules/agnostic-posture.md` (own-voice + agnostic floors). ↔ `rules/interactive-questions.md` (§6 destructive-op floor). ↔ `skills/diagram-authoring/SKILL.md` + `skills/document-authoring/SKILL.md` (sibling own-voice authoring skills).

package/src/apothem/skills/test-authoring/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: "test-authoring"
+version: "0.1.0"
+updated: "2026-06-09"
+description: "Behavior-first test authoring with strict Arrange-Act-Assert discipline — matched when the developer asks to 'write tests', 'add coverage', 'add a test for', 'test this function', 'cover this module', 'write a failing test', 'increase coverage', or any phrasing requesting new test cases that assert observable behavior against a unit under test. Discovers the unit's behavior contract (input domains, return shapes, side effects, raised exception types, edge boundaries — empty/null/zero/max/Unicode/off-by-one), writes failing AAA assertions before the implementation satisfies them, partitions coverage across the happy path, the edge boundaries, and the failure modes (with a regression test pinning any named bug), and reports residual coverage gaps for operator triage. Authors tests only — never edits, writes, or repairs the implementation under test, never executes the suite, never computes a coverage percentage, never edits coverage config, and never mocks the unit under test itself (mocks only at owned boundaries: adapters, injected ports). A request to fix a failing test by editing the implementation, scaffold a project, or run an existing suite is NOT a match."
+archetype: "authoring-template"
+userInvocable: true
+argument-hint: "[--focus PATH] [--framework NAME]"
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+## Purpose
+
+Author behavior-first test cases for a named unit under test. Every emitted test asserts one observable behavior contract — an input-to-output mapping, a side effect, a raised exception, or an edge boundary — under a strict Arrange-Act-Assert shape. The skill writes the tests; it never touches the implementation those tests exercise.
+
+## Detection Signal
+
+The developer asks to "write tests", "add coverage", "add a test for", "test this function", "cover this module", "write a failing test", or "increase coverage" — any phrasing that requests new test cases asserting observable behavior against a unit under test.
+
+**Falsifiable counter-signal.** A request to fix a failing test by editing the implementation, scaffold a project, or run an existing suite is NOT a match — those route to the implementation, project-setup, and test-execution surfaces respectively.
+
+## Non-Goals
+
+A deliberately narrow surface. The skill is NOT:
+
+- **An implementation generator.** It authors tests against the unit's behavior contract; it never writes, edits, or repairs the production code the tests exercise. Implementation lands through the host's normal codegen surface, governed by `rules/host-discovery.md`.
+- **A green-bar chaser.** A test that passes before the implementation exists asserts nothing. The skill writes assertions that fail against the absent or current behavior first; the contract is satisfied by implementation outside this skill.
+- **A test runner.** It authors test files; it does not execute the suite, compute a coverage percentage, or gate on a threshold. Execution is the host's `pytest` / `vitest` / `go test` surface and the consuming command's responsibility.
+- **A mock-everything tool.** Tests assert behavior, not implementation detail. The skill mocks only at owned boundaries (adapters, injected ports) and never mocks the unit under test itself.
+- **A coverage-config editor.** Threshold configuration, CI wiring, and coverage-tool selection are operator decisions surfaced as findings, never silently installed.
+
+## Workflow
+
+Five numbered, independently-verifiable steps. Test authoring only — no implementation edits.
+
+1. **Resolve the unit and the framework.** Discover the host's ratified test framework, test-directory layout, fixture conventions, and naming idioms by walking the host's source-of-truth files per `rules/host-discovery.md` (e.g., `pyproject.toml [tool.pytest.ini_options]`, sibling `test_*.py`, `*.test.ts`, `*_test.go`). `--focus PATH` names the unit; `--framework NAME` overrides the discovered framework when the host runs more than one.
+2. **Extract the behavior contract.** Read the unit under test and enumerate its observable contract — every input domain, every return shape, every side effect, every raised exception type, every edge boundary (empty, null, zero, max, Unicode, boundary off-by-one). Record each contract item as a distinct row; one row becomes one test.
+3. **Write failing AAA assertions first.** For each contract row, author one test in strict Arrange-Act-Assert form: the **Arrange** block builds the fixture and inputs, the **Act** block invokes the unit once, the **Assert** block checks exactly one observable outcome. The assertion fails against absent or current behavior before the implementation satisfies it. One behavioral claim per test; behavior-descriptive names (`test_<unit>_<condition>_<expected>`).
+4. **Cover happy, edge, and failure paths.** Partition the contract into the **happy path** (valid in-domain inputs), the **edge boundaries** (empty, null, zero, max, Unicode), and the **failure modes** (invalid inputs, missing dependencies, raised exceptions asserted with the framework's exception-matcher). Every partition carries at least one covering test; a bug-fix request adds a regression test pinning the prior defect.
+5. **Report residual coverage gaps.** Name every contract row left uncovered and why (data not yet discoverable, behavior under-specified, boundary requires host input). Uncovered rows surface as findings for operator triage, never silently dropped.
+
+## Return Contract
+
+Output is the set of authored test files plus a coverage-map summary (markdown). Maximum response: 800 tokens. Structure:
+
+- **Tests authored:** bulleted list — file path, test name, contract row, partition (happy / edge / failure).
+- **Coverage map:** contract rows covered vs. residual, with each residual row's triage reason.
+- **Gaps:** behavior contracts the host has not yet specified (if applicable).
+
+**Token-budget override.** The invoker may request a higher budget for exhaustive enumeration; honor it. Prefer raising the budget over truncating the coverage map.
+
+## Foundational Stanzas
+
+The four standing surfaces, adapted to this skill's user-invocable test-authoring role.
+
+### Refusal & Escalation
+
+REFUSE any request that asks the skill to act outside its mission — editing the implementation under test, scaffolding a project, running the suite, computing coverage percentages, or mutating coverage configuration. Refusal is explicit: name what was refused, name the mission boundary crossed, and route the developer to the correct surface through the structured-inquiry channel per `rules/interactive-questions.md` (canonical channel; three-segment option annotation; never free-form prose as primary input). When the unit under test cannot be located or its behavior contract is unreadable, STOP and surface the recovery options — never invent a contract from training-time memory.
+
+### Output Surface
+
+The skill emits test files at the host's ratified test location, discovered per `rules/host-discovery.md` (mirror-the-source layout where the host uses one; sibling-of-source where it does not). NEVER write a test outside the host's test tree, NEVER write to a global location, and NEVER edit the implementation under test. Per `rules/operational-mandates.md` CM-7, authored tests carry zero plan-internal references — natural domain language only.
+
+### File-Authoring Contract
+
+Every NEW test file routes through `scripts/inject-header.py` so the canonical `SPDX-License-Identifier: MIT` header is injected at the head in the comment family matching the filetype; the injector is idempotent and resolves the variant from the byte-exact fixture at `src/apothem/schemas/authorship-header.txt`. Exempt classes are enumerated at `src/apothem/schemas/header-exceptions.txt`. The header-inject-guard hook at `hooks/messages/pretooluse-{write,edit}-header-guard.md` enforces the contract at every Write / Edit invocation.
+
+### Structured Inquiry on Ambiguity
+
+When the skill reaches a decision in any of the seven authoritative-data categories per `rules/authority-inquiry.md` — identity, scope direction (which unit, which subtree), preference (test framework, fixture style, mocking library, coverage tool), security (test-fixture credentials), naming of public surfaces (test-file naming), infrastructure endpoints (integration-test targets), version pins — and the host is silent, route the resolution through the structured-inquiry channel with the three-segment annotation per `rules/interactive-questions.md` §3 (rationale / recommendation / default-pointer). NEVER fabricate authoritative data. Every overwrite of an existing test file routes through the per-file destructive-op floor per `rules/interactive-questions.md` §6 — one invocation per file, no `multiSelect` batching, every option's `default-pointer:` carrying the verbatim `no-default: user decision required` marker.
+
+## Recommended Next Step
+
+**Run the host's test command against the authored files** (e.g., `python -m pytest <focus-path>`) to confirm every new assertion fails before the implementation lands, then hand the failing suite to the implementation surface.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every behavior-first test file authored at the host's ratified test location. ● The AAA-shaped assertion discipline at every emitted test. ● The coverage-map summary that surfaces residual gaps for operator triage.
+- **Satisfies →** ● `CLAUDE.md` Source Layout row "test-authoring" (skills/ class). ● The behavior-first test-authoring mission with strict Arrange-Act-Assert discipline.
+- **Established by ↑** ● `CLAUDE.md` Source Layout (skills/ folder-with-`SKILL.md` class). ● `rules/code-craft-python.md` §3 Testing Directives (AAA shape, behavior-descriptive names, one assertion per test). ● `rules/ten-dimension-check-dimensions.md` dimension 10 (examples / tests / docstrings).
+- **Gated by ←** ● The harness's Write / Edit / Read / Glob / Grep / Bash tool surface. ● The presence of a locatable unit under test and a discoverable test framework per `rules/host-discovery.md`.
+- **Cross-bound with ↔** ↔ `rules/code-craft-python.md` (test-craft discipline for Python units). ↔ `rules/host-discovery.md` (framework and layout discovery). ↔ `rules/interactive-questions.md` (structured-inquiry channel for ambiguity and destructive-op floor). ↔ `rules/clean-room-generation.md` §4.2 (test-behavioral derivation). ↔ `skills/ecosystem-audit/SKILL.md` + `skills/plan-suite/SKILL.md` (sibling skills under the same registry section).

package/src/apothem/skills/vuln-triage/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: "vuln-triage"
+version: "0.1.0"
+updated: "2026-06-09"
+description: "Vulnerability and security-advisory triage — matched when the user references a 'CVE', cites a 'security advisory' (GHSA, OSV, vendor bulletin), asks to 'triage this vuln', or asks 'is this vulnerable'. Targets one named advisory per invocation: severity-classifies it with a CVSS-style band (critical 9.0–10.0 / high 7.0–8.9 / medium 4.0–6.9 / low 0.1–3.9 / none 0.0) plus the justifying vector string, maps it to the affected surface in the host tree against the resolved lockfile, determines reachability and exploitability (reachable / unreachable / conditional + applicable attack vector), routes remediation from the closed set {patch, upgrade, mitigate, accept} (or not-applicable when no affected surface exists), and records a seven-field triage record with cited rationale. The output drives the operator's remediation decision; the skill does NOT apply the remediation, construct or run exploit payloads, scan the repository, re-publish CVSS scores, or re-solve the dependency graph. The 'accept' route is a security ratification — when the host has not ratified an accepted-risk threshold, it blocks on inquiry."
+archetype: "security-template"
+userInvocable: true
+argument-hint: "[--advisory ID] [--focus PATH]"
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+## Purpose
+
+Triage one vulnerability or security advisory against the host tree. The skill severity-classifies the advisory with a named scheme, locates the affected surface in the host, determines whether the affected code is reachable and exploitable, selects a remediation route, and records the disposition with cited rationale as a structured triage record. The output drives the operator's remediation decision; the skill does not apply the remediation itself.
+
+## Detection Signal
+
+The user references a `CVE` identifier, cites a `security advisory` (GHSA, OSV, vendor bulletin), asks to `triage this vuln`, or asks `is this vulnerable`. Any single phrasing that names a concrete advisory or asks whether the host carries a known vulnerability matches.
+
+**Falsifiable counter-signal.** A request for a repository-wide scan, an exploit proof-of-concept, or the application of a fix is NOT a match — those route to the host's scanner CI, a penetration-test surface, and the remediation change-set respectively.
+
+## Non-Goals
+
+A deliberately narrow surface. The skill is NOT:
+
+- **A full vulnerability scanner.** It triages one named advisory per invocation against a known surface. Repository-wide scanning is `pip-audit` / `gitleaks` / `trivy` / `osv-scanner` territory under the host's CI; the skill consumes a scanner's output, it does not replace it.
+- **A remediation executor.** It selects a remediation route and records it; it does not apply the patch, bump the dependency, or edit the vulnerable code. Remediation lands as a separate operator-driven change-set governed by `rules/production-ready-prs.md`.
+- **A penetration tester.** Exploitability is assessed by reachability analysis and advisory metadata, not by constructing or executing an exploit. No proof-of-concept payload is authored or run.
+- **A CVSS authority.** It applies a CVSS-style classification to rank the advisory against the host's actual exposure; it does not publish or amend the upstream CVSS base score.
+- **A dependency-graph resolver.** Transitive-dependency math is the package manager's job; the skill reads the resolved lockfile, it does not re-solve the graph.
+
+## Workflow
+
+Five numbered steps. Step 2 may short-circuit the workflow to step 5 when no affected surface exists (`not-applicable`).
+
+1. **Classify severity using a named scheme.** Read the advisory metadata (CVSS vector, affected version range, attack vector, attack complexity, privileges required, user interaction). Assign a CVSS-style band — `critical` (9.0–10.0) / `high` (7.0–8.9) / `medium` (4.0–6.9) / `low` (0.1–3.9) / `none` (0.0) — and record the vector string that justifies it.
+2. **Map the advisory to the affected surface in the host tree.** Use Glob and Grep to locate the affected package, module, or call site under `--focus PATH` (default: host root). Read the host's resolved manifest or lockfile (`pyproject.toml`, `uv.lock`, `package-lock.json`, the host's ratified equivalent per `rules/host-discovery.md`) and confirm the installed version falls inside the advisory's affected range. When no affected surface exists, the disposition is `not-applicable` and the workflow terminates at step 5.
+3. **Determine exploitability and reachability.** Grep for call sites that reach the vulnerable function, configuration, or code path. Record whether the path is reachable (`reachable` / `unreachable` / `conditional`), whether the attack vector applies to the host's deployment (network-exposed, local-only, build-time-only), and whether a precondition (specific config, untrusted-input flow) is required.
+4. **Route remediation.** Select exactly one route from the closed set `{patch, upgrade, mitigate, accept}` — `patch` (apply the upstream fix or backport), `upgrade` (bump to a fixed version), `mitigate` (configuration change, input validation, or network restriction that removes reachability), `accept` (document and accept the residual risk when unreachable or out of scope). The selection cites the severity band from step 1 and the reachability verdict from step 3.
+5. **Record the disposition with rationale.** Emit the triage record per the Return Contract. The rationale cites the advisory ID, the affected-surface path, the reachability verdict, and the concrete driver for the chosen route. The record is the disposition's authoritative source.
+
+## Return Contract
+
+The skill emits one triage record per invocation. The record carries seven fields, every field populated:
+
+| Field | Content |
+|-------|---------|
+| `id` | The advisory identifier (CVE / GHSA / OSV / vendor-bulletin ID) |
+| `severity` | The CVSS-style band from step 1 plus the vector string |
+| `affected-surface` | The host path mapped in step 2 (package + module + installed version), or `none` |
+| `exploitability` | The reachability verdict from step 3 (`reachable` / `unreachable` / `conditional`) plus the applicable attack vector |
+| `disposition` | The remediation route from step 4 (`patch` / `upgrade` / `mitigate` / `accept`), or `not-applicable` |
+| `rationale` | The cited justification linking severity + reachability + route |
+| `date` | ISO-8601 triage date |
+
+A record with any field unpopulated is non-conformant. The record writes to STDOUT for direct invocation; when the host maintains a security-advisory ledger, the record appends to it at the host's ratified path.
+
+## Foundational Stanzas
+
+The four standing surfaces every operator inherits, adapted to this skill's single-advisory triage role.
+
+### Refusal & Escalation
+
+REFUSE any request that asks the skill to act outside its triage mission — applying remediation edits, constructing or running exploit payloads, repository-wide scanning, re-publishing CVSS scores. Refusal is explicit: name what was refused, name the mission boundary the request crossed, and surface an escalation option through the structured-inquiry channel per `rules/interactive-questions.md` (canonical channel; three-segment option annotation; never free-form prose as primary input). When the advisory cannot be resolved to host state — the advisory ID is malformed, the affected package is absent, or the lockfile is unreadable — the skill STOPs and surfaces the recovery options; it never guesses a severity or fabricates an affected surface.
+
+### Output Surface
+
+The skill emits one triage record (the Return Contract). The record writes to STDOUT for direct invocation; when the host maintains a security-advisory ledger or `SECURITY.md` tracking surface, the record appends there at the host's ratified path per `rules/host-discovery.md`. NEVER write the record to a global-ecosystem location, and NEVER edit the vulnerable code as part of triage. Remediation artifacts a downstream change-set emits land at their domain-natural host locations per `rules/host-discovery.md`; per `rules/operational-mandates.md` CM-7, those artifacts carry natural domain language and zero plan-internal references.
+
+### File-Authoring Contract
+
+When the skill emits a NEW file — a fresh security-advisory ledger where the host has none — the file routes through `scripts/inject-header.py` so the canonical authorship-header banner is injected at the head; the injector is idempotent and detects the filetype variant automatically from the byte-exact fixture at `src/apothem/schemas/authorship-header.txt`. The exempt classes (LICENSE, JSON configuration files, lockfiles, generated assets, vendored trees, `.audit/` ephemera, `<project-root>/.apothem/plans/` ephemera, `.keep` / `.gitkeep` markers, binary files) are enumerated at `src/apothem/schemas/header-exceptions.txt`. Triage records emitted to STDOUT are banner-exempt. Edits that append a record to an existing ledger preserve the ledger's existing banner.
+
+### Structured Inquiry on Ambiguity
+
+When triage reaches a decision in any of the seven authoritative-data categories per `rules/host-discovery.md` and `rules/interactive-questions.md` — identity, scope direction (which subtree to triage), preference (which severity scheme when the host ratifies one over CVSS), security posture (accepted-risk threshold, deployment exposure model), naming of public surfaces, infrastructure endpoints, version pins (the fixed-version target for an `upgrade` route) — and the host is silent, route the resolution through the structured-inquiry channel with the three-segment option annotation per `rules/interactive-questions.md` §3 (rationale / recommendation / default-pointer). Free-form prose questions as primary input are forbidden. NEVER fabricate authoritative data — a severity band, an affected version range, or an accepted-risk disposition is discovered or inquired, never invented. The `accept` route is a security ratification; when the host has not ratified an accepted-risk threshold, the route blocks on inquiry.
+
+## Recommended Next Step
+
+**Run the host's remediation change-set for the chosen route** — apply the `patch` / `upgrade` / `mitigate` action recorded in the triage record under `rules/production-ready-prs.md`, shipping the fix with its test, CHANGELOG entry, and CI-green attestation in one change-set. When the disposition is `accept`, record the operator-ratified accepted-risk entry in the host's `SECURITY.md` instead.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every single-advisory triage record's seven-field shape (the Return Contract is the disposition's authoritative surface). ● Every remediation route selection against the closed `{patch, upgrade, mitigate, accept}` set. ● Every downstream remediation change-set the triage record routes to. ◐ The host's security-advisory ledger append where one exists.
+- **Satisfies →** ● `CLAUDE.md` Source Layout row "vuln-triage" (skills/ class). ● The security-cohort triage mission (severity-classify and route remediation for vulnerabilities and advisories).
+- **Established by ↑** ● `CLAUDE.md` Source Layout (skills/ class declaration with the folder-with-`SKILL.md` convention). ● `CLAUDE.md` Ambiguity Handling (structured inquiry over fabrication).
+- **Gated by ←** ● The harness's Read / Glob / Grep / Bash surface (the skill maps the advisory to host state by discovery). ● The presence of a resolvable advisory ID and a readable host manifest (the skill STOPs and surfaces recovery when either is absent).
+- **Cross-bound with ↔** ↔ `rules/host-discovery.md` (M1 — affected surface and manifest discovered, never assumed). ↔ `rules/interactive-questions.md` (the structured-inquiry channel for accepted-risk and version-pin decisions). ↔ `rules/production-ready-prs.md` (M15 — the remediation change-set the Recommended Next Step routes to). ↔ `rules/disclosure-ledger.md` (M2 — triage dispositions recorded as findings). ↔ `skills/ecosystem-audit/SKILL.md` (sibling skill under the same registry section).