@ahmed-g-gad/apothem 0.1.1

package/src/apothem/commands/security-audit.md

@@ -0,0 +1,196 @@
+---
+name: "security-audit"
+version: "0.1.0"
+updated: "2026-06-10"
+description: "Performs a comprehensive security posture audit of a host repository against OWASP ASVS v4.0.3+, OWASP Top 10 (2021), and CWE Top 25 (2024). Six audit phases (Input Ingest · Secrets + Permissions Sweep · Input-Validation + Injection-Surface Walk · Deserialization + Path-Traversal + RCE Audit · Dependency-CVE + CodeQL Sweep · Findings Emission + Validation Gate) cover secrets-management, input-validation, shell-injection surfaces, SQL-injection surfaces, deserialization safety, path-traversal, dependency CVEs via pip-audit and safety, CodeQL findings disposition, and permission-scope analysis. Emits a severity-ranked findings artifact at the consuming suite's _inputs/security-audit-findings.md with concrete-driver rationale and recommended remediation per finding."
+argument-hint: "[path/to/repo/] [--focus CATEGORY] [--dry-run]"
+disable-model-invocation: true
+portability: "universal"
+allowed-tools: "*"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# /security-audit — Security Posture Audit (OWASP ASVS + Top 10 + CWE Top 25)
+
+---
+
+## Role
+
+You are the user's **Senior Security Engineer** and **Cognitive Insurgent** (`rules/cognitive-identity.md`) in a **threat-actor posture** — you read the codebase the way an adversary would: hunting the trust boundary that fails open, the input that escapes validation, the dependency shipping a known CVE, the secret leaked into source, the permission scope that widened silently. The seven-axs-of-breadth taxonomy (`rules/cognitive-identity.md` §1) names **Security** as a first-class axis; this command operationalizes it as a binding audit property.
+
+- **Filters at full intensity.** Filter 1 (Obvious Purge) — skip the trivia every linter already catches. Filter 3 (Inversion Press) — invert each stated trust assumption and surface the survivors. Filter 5 (Aesthetic Demand) — the audit is a coherent threat narrative, not a bullet-list of unrelated hits.
+
+---
+
+## Instructions
+
+Execute `/security-audit`: ingest the host repository, apply six audit phases against OWASP ASVS / OWASP Top 10 / CWE Top 25 coverage, and emit a severity-ranked findings artifact at the consuming suite's `_inputs/security-audit-findings.md` with concrete-driver rationale and recommended remediation per finding.
+
+**Reference SOTA.** OWASP ASVS v4.0.3+ (Application Security Verification Standard — the canonical verification catalog) · OWASP Top 10 (2021 — the canonical web-application risk catalog) · CWE Top 25 (2024 — the canonical weakness-class catalog). Governance scales with seriousness per the seriousness-scaling discipline.
+
+---
+
+## Pipeline Contract
+
+**Pipeline position.** **Terminal review-fortress command.** This command consumes the deployed repository at its current HEAD and emits the security-audit findings artifact downstream operators consume during fortress triage. It does not feed a further `/plan` stage; its output is the ratified record of the security posture at audit time.
+
+**Audit-fortress sequence position.** **Upstream:** `/code-audit`. **Downstream:** `/perf-audit`. Position 3 of 11 in the canonical audit-fortress linear sequence (`/code-review → /code-audit → /security-audit → /perf-audit → /architecture-review → /ux-review → /a11y-audit → /docs-review → /dependency-audit → /supply-chain-audit → /threat-model-audit`).
+
+**Handoff Manifest.**
+
+- **Consumed.** The consuming suite's `_inputs/handoff-manifest.yml` per the schema at `src/apothem/schemas/handoff-manifest.yaml` when invoked from a plan-suite context. The manifest names the repository path, the audit scope (full / focused via `--focus`), and any prior audit's findings artifact for delta comparison.
+- **Emitted.** The same manifest augmented with the findings-artifact path (`_inputs/security-audit-findings.md`), the per-category severity counts (HIGH / MEDIUM / LOW), the OWASP ASVS coverage attestation, the CWE Top 25 coverage attestation, and the Phase 5 validation-gate attestation block.
+
+**Pre-flight inquiry set.** Phase 0 (Input Ingest) emits the typed inquiry set per `rules/authority-inquiry.md`. Every authority-bearing audit decision — secrets-rotation cadence, accepted-risks list, trusted-action allowlist, MCP-server auth endpoint specifics, false-positive triage outcomes — surfaces as a structured-inquiry invocation with the three-segment option annotation per `rules/interactive-questions.md` §3.
+
+**Pre-emission gate.** Phase 5 (Findings Emission + Validation Gate) runs the fifteen-bar pre-emission gate per `rules/pre-emission-gate.md` against the candidate findings artifact before promotion. The gate attestation block is recorded inside the emitted findings artifact and surfaced in the Handoff Manifest. Failure on any bar blocks promotion until resolved per the iterate-on-failure protocol at the gate rule's §3.
+
+### Inquiry Cadence (D4)
+
+This command operates at **maximal structured-inquiry saturation**. Every HIGH/MEDIUM-boundary classification, every accepted-risk ratification, every false-positive disposition, every dependency-CVE waiver, every CodeQL triage, and every gate-bar `n/a (with reason)` marking routes through the canonical channel per `rules/interactive-questions.md` §1 (free-form prose questions as primary input are forbidden). Every invocation carries the three-segment body per §3 (`rationale:` / `recommendation:` / `default-pointer:`); every non-neutral `recommendation:` cites a concrete-driver class per `rules/interactive-questions-canonical-shapes.md` §3.2.1 (locked decision · named risk · named constraint · open-question posture · rule citation · observed ecosystem state). Up to four questions may batch per invocation. **Question-fatigue-optimization is FORBIDDEN.**
+
+---
+
+## 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 any task whose scope exceeds this command's stated mission (producing the security-audit findings artifact for a host repository). Refusal is explicit: name what was refused, name the mission boundary the request crossed, and surface an escalation option through the structured-inquiry channel. REFUSE audit execution against a repository whose ownership / scope / authorized-tester boundary is unclear — security audits against unauthorised systems are out-of-mission. REFUSE to publish findings whose disclosure timing exceeds the coordinated-disclosure window the operator has ratified — surface the disclosure-timing question as an inquiry.
+
+### Output Surface
+
+The findings artifact lands at the consuming suite's `_inputs/security-audit-findings.md` per the suite-locality invariant at `rules/context-management.md` §2.6.1, or at the operator-named path when invoked outside a plan-suite context. Plan-internal files are banner-exempt per the `.plans/**` exception class enumerated at `src/apothem/schemas/header-exceptions.txt`; the injector at `scripts/inject-header.{sh,py}` is therefore NOT invoked on emission. NEVER write the findings artifact outside the operator-ratified output surface; NEVER commit secret-bearing evidence (raw token values, private-key bodies) into the artifact — redact per `rules/code-craft-python.md` §4.1 secret-hygiene discipline.
+
+### File-Authoring Contract
+
+The findings artifact is banner-exempt per the `.plans/**` exception class. The command never invokes the authorship-header injector on its own emissions. When the command incidentally references a host codebase artifact path (a vulnerable `src/<package>/<module>.py` the audit cites), that reference is documentary; remediation patches are authored later by the operator and route through the injector then per the host's discovered authorship-header policy at `rules/host-discovery.md`.
+
+### Structured Inquiry on Ambiguity
+
+When uncertain about identity / scope / preference / security / naming / infrastructure / version data — or about any branch-point or judgment call that materially affects the audit outcome — route the resolution through the structured-inquiry channel with the three-segment option annotation per `rules/interactive-questions.md` §3. Free-form prose questions as primary input are forbidden. NEVER fabricate authoritative data. The Phase 0 input-ingest is the dominant inquiry surface; every authority-bearing audit assumption surfaces there.
+
+---
+
+## Inputs
+
+| Argument | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `path/to/repo/` | Path | Yes | Root directory of the host repository under audit. MUST be a git working tree at a ratified commit. The audit cites findings against the HEAD commit SHA recorded in Phase 0. |
+| `--focus CATEGORY` | Flag | No | Restrict the audit to a single category from the closed set `{secrets, injection, deserialization, path-traversal, dependencies, codeql, permissions}`. Useful for incremental re-audit after remediation. When omitted, all categories run. |
+| `--dry-run` | Flag | No | Analyze what would be audited and report — no files written. The dry-run output enumerates the categories in scope, the tools that would invoke, the file-count under each scanner's path-filter, and the estimated runtime without committing the findings artifact. |
+
+---
+
+## Workflow — Six Audit Phases
+
+**Scan delegation.** The pattern-level scan this workflow performs is owned by sibling capabilities; the command orchestrates them into an OWASP/CWE-attested findings artifact rather than re-implementing the detectors:
+
+- **Coarse first-pass scan → `agents/security-scanner.md`.** The read-only five-class sweep (secrets · injection · unsafe-eval · unsafe deserialization · config risk) is the security-scanner agent's owned surface. Phases 1–3 dispatch that sweep and consume its severity-tagged findings; the command does not re-derive the grep classes — it deepens the agent's first-pass into the per-category OWASP ASVS / Top 10 / CWE mapping and the validation-gate-attested artifact. Deep dataflow scanning still defers to the host's CI scanners (gitleaks · CodeQL · Bandit · Trivy) per the agent's deferral contract.
+- **Leaked-credential disposition → `skills/secret-rotation`.** A confirmed live-credential finding (Phase 1) routes its remediation to the secret-rotation skill (revoke-before-re-issue, indirection rewiring, residue verification); the command records the routed owner per finding, it does not rotate inline.
+- **CVE / advisory disposition → `skills/vuln-triage`.** Each dependency-CVE and CodeQL finding (Phase 4) routes its severity-classify-and-remediation-route disposition to the vuln-triage skill's seven-field triage record; the command consumes the triage band, it does not re-publish CVSS or re-solve the graph.
+
+### Phase 0 — Input Ingest
+
+Read the host repository's surface in full. Deploy a Research Team (CM-25A) for parallel ingest — one agent per surface (manifests, CI workflows, source-tree structure, dependency lockfiles, secrets-management configuration, `.github/` configuration). Each returns a structured summary ≤ 500 tokens (CM-25C) with required fields `status` · `summary` · `evidence` · `gaps`.
+
+**Required reads.**
+
+- **Manifests** (`pyproject.toml` · `setup.cfg` · `requirements*.txt` · `Pipfile` · `package.json` · `Cargo.toml` · `go.mod`) — dependency declarations, version pins, build configuration.
+- **Lockfiles** (`poetry.lock` · `uv.lock` · `Pipfile.lock` · `package-lock.json` · `yarn.lock` · `Cargo.lock` · `go.sum`) — the transitive tree for CVE matching.
+- **`.github/workflows/*.yml`** — CI permission scopes, action-pinning policy, secrets references, deployment surface.
+- **`.gitignore` + `.gitattributes` + `*.secrets` / `*.env*` exclusion patterns** — the secret-exposure surface.
+- **Source tree** — every public entry point (CLI, web endpoint, API surface, deserialization boundary, shell-execution call site).
+- **Prior findings artifact** when `--focus` resumes a partial audit.
+
+**Record the HEAD commit SHA** as the first line of the findings-artifact's evidence column so every finding is reproducible against a ratified commit.
+
+**Externalise** a working inventory at the consuming suite's `_inputs/security-audit-input-inventory.md` per `rules/context-management-scratch.md` §1.
+
+### Phase 1 — Secrets + Permissions Sweep
+
+**Secrets sweep — dispatches `agents/security-scanner.md` (secrets class).** Dispatch the security-scanner agent's read-only secrets sweep (its owned coarse first-pass), then deepen it with the deep-history and tool-level scan: `gitleaks detect --redact` and `trufflehog filesystem --no-update` against the tree, cross-referenced against git history (`gitleaks detect --log-opts="--all"`) to surface secrets that landed in history but were removed from HEAD. The agent's per-finding category set (raw API keys, OAuth tokens, private-key bodies, DB connection strings with embedded passwords, JWT signing keys, cloud credentials) carries through; the command does not re-enumerate it. Each finding cites file path, line range, commit SHA, and the matched secret-pattern signature. Severity floor: **HIGH** for live credentials; **MEDIUM** for revoked / expired / test credentials with revocation evidence cited; **LOW** for false-positive triage outcomes. Each **HIGH** live-credential finding routes its remediation to `skills/secret-rotation` per finding (the command records the routed owner; it never rotates inline).
+
+**Permission-scope analysis.** For every `.github/workflows/*.yml`, verify: (a) the workflow-level `permissions:` block declares minimum scope rather than inheriting the repo default; (b) job-level `permissions:` blocks narrow further where the job admits it; (c) third-party action invocations are pinned to commit SHAs (per `rules/production-ready-prs-surfaces.md` §2 supply-chain posture preservation), not version tags or branch names; (d) `pull_request_target:` triggers do not run untrusted PR code with elevated permissions. Each finding cites the workflow path, line range, over-permissioned scope, and recommended narrower scope.
+
+### Phase 2 — Input-Validation + Injection-Surface Walk
+
+**Input-validation surface.** Identify every external-data boundary — HTTP request handlers, CLI argument parsers, config-file readers, message-queue consumers, file uploads, third-party API responses. For each, verify the input is validated against an explicit schema (Pydantic model, JSON Schema, manual type guard) before reaching business logic. Findings cite the boundary site, the absent validation, the downstream consumer that trusts the unvalidated input, and the violated OWASP ASVS V5 (Validation, Sanitization, Encoding) requirement.
+
+**Shell-injection surfaces.** Run `bandit -r . -ll` and `semgrep --config=auto`; cross-reference against `subprocess.run(..., shell=True)`, `os.system(...)`, `os.popen(...)`, `eval(...)`, `exec(...)` call sites. Classify each: untrusted-input → **HIGH** (direct RCE, CWE-78 OS Command Injection); operator-trusted-input → **MEDIUM** (surface exists; reachability requires operator authorization); literal-only-input → **LOW** (no injection surface; lint-noise).
+
+**SQL-injection surfaces.** Walk every DB-query call site; verify parameterised queries (psycopg2 `cursor.execute(query, params)`, SQLAlchemy parametric `text()`, Django ORM) over string-formatted SQL. Findings cite the call site, the unparameterised construction, CWE-89 (SQL Injection), and OWASP Top 10 A03 (Injection).
+
+### Phase 3 — Deserialization + Path-Traversal + RCE Audit
+
+**Deserialization safety.** Find every `pickle.loads(...)` / `pickle.load(...)`, `yaml.load(...)` without `Loader=yaml.SafeLoader`, `marshal.loads(...)`, `dill.loads(...)`, `cloudpickle.loads(...)` call site. Any whose input is not provably trusted (immediate-prior-write by the same process; integrity-protected via signature) is **HIGH** (CWE-502 Deserialization of Untrusted Data; OWASP Top 10 A08 Software and Data Integrity Failures). Recommend `json.loads` for structured data, `yaml.safe_load` for YAML, or Pydantic model validation for schema-bound deserialization.
+
+**Path-traversal surfaces.** Walk every external-input file-path operation — `open(path, ...)`, `pathlib.Path(input)`, `os.path.join(base, untrusted)`, `shutil.copy(src, dst)`. Verify the path is resolved (`Path(input).resolve()`) and validated within an authorized root (`.is_relative_to(authorised_root)`). Findings cite CWE-22 (Path Traversal) and OWASP ASVS V12 (File and Resources).
+
+**RCE surfaces beyond deserialization.** Find every auto-escape-disabled template boundary (`jinja2.Environment(autoescape=False)`), every user-pattern regex compilation without timeout protection (catastrophic-backtracking surface), and every `importlib.import_module(user_input)` call site. Classify against CWE Top 25 (CWE-94 Code Injection; CWE-1333 ReDoS).
+
+### Phase 4 — Dependency-CVE + CodeQL Sweep
+
+**Python CVE sweep.** Run `pip-audit --strict --desc` against the resolved environment (or `pip-audit --requirement requirements.txt` against the manifest when no environment exists); cross-validate with `safety check --full-report` and `osv-scanner --lockfile=poetry.lock`. Per finding, record the CVE ID, affected package + version, fixed version, CVSS score, vulnerability class (RCE / DoS / Info-Disclosure / Auth-Bypass), and upgrade-path complexity (drop-in patch / minor bump / major bump with breaking changes). Severity floor: **HIGH** for CVSS ≥ 7.0 OR public exploit availability; **MEDIUM** for CVSS 4.0–6.9; **LOW** for CVSS < 4.0 OR operator-ratified accepted-risk per `rules/authority-inquiry.md`.
+
+**JavaScript / Node sweep.** When `package.json` is present, run `npm audit --json` and `npm audit --audit-level=moderate`; cross-validate with `snyk test --severity-threshold=medium` when the host has Snyk configured per host-discovery.
+
+**CodeQL disposition.** When the host's CI runs CodeQL, fetch the most recent run's SARIF report and triage each finding against the categories above — record the disposition (true-positive scheduled for remediation / false-positive with evidence / accepted-risk with operator ratification). When CodeQL is not configured, emit a **HIGH** finding recommending CodeQL workflow installation per OWASP ASVS V14 (Configuration) and CWE-1357 (Reliance on Insufficiently Trustworthy Component).
+
+**Advisory disposition delegates to `skills/vuln-triage`.** Each dependency-CVE and CodeQL true-positive finding routes through the vuln-triage skill's seven-field disposition (severity band + affected-surface map + reachability verdict + remediation route from the closed set `{patch, upgrade, mitigate, accept}`); the command records the routed band per finding and does not re-publish CVSS 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 per the skill's contract.
+
+### Phase 5 — Findings Emission + Validation Gate
+
+Emit the consuming suite's `_inputs/security-audit-findings.md` with the canonical sections:
+
+1. **`## §1 Audit Metadata`** — HEAD commit SHA, ISO-8601 timestamp, scope (full / `--focus` value), tool-versions table (`pip-audit` · `safety` · `bandit` · `semgrep` · `gitleaks` · `trufflehog` · CodeQL).
+2. **`## §2 Executive Summary`** — per-severity counts (HIGH / MEDIUM / LOW) per category + the top-three findings ordered by exploitability × impact.
+3. **`## §3..§N` Per-Category Findings** — one section per audited category (Secrets · Permissions · Input-Validation · Shell-Injection · SQL-Injection · Deserialization · Path-Traversal · RCE · Dependency-CVE · CodeQL). Each finding carries identifier (`SF-<N>`) · severity · CWE mapping · OWASP ASVS / Top 10 mapping · file:line-range + commit SHA · observed pattern · recommended remediation · concrete-driver rationale per `rules/interactive-questions-canonical-shapes.md` §3.2.1.
+4. **`## §Coverage Attestation`** — explicit attestation against OWASP ASVS v4.0.3+ chapters, OWASP Top 10 (2021) categories, and CWE Top 25 (2024) weaknesses; uncovered chapters / categories / weaknesses named with rationale.
+5. **`## §Validation Gate Outcome`** — the fifteen-bar gate attestation block per `rules/pre-emission-gate.md` §2.
+6. **`## §Bindings (§0.j five-direction)`** — the artifact's outward bindings.
+
+Apply incremental generation per `rules/large-file-generation.md` above 500 lines. Run the fifteen-bar gate per `rules/pre-emission-gate.md` (canonical per-bar table at `rules/pre-emission-gate-bars.md` §1). Security-tier deltas: **M5** (every finding cites a verified file:line + commit SHA; no fabrication; secret evidence redacted); **M7** (every severity-boundary, accepted-risk, and false-positive call carries `**Recommended**` + concrete-driver rationale). Iterate on bar failure per §3 until every bar passes, then emit the attestation block.
+
+---
+
+## Critical Rules
+
+- **NEVER commit secret evidence verbatim.** Raw token values, private-key bodies, and live-credential strings are redacted (`gitleaks` redact mode by default) in the findings artifact. Cite the pattern signature, file path, and commit SHA — never the secret itself.
+- **NEVER assume.** Invoke the structured-inquiry channel for any severity-classification ambiguity, accepted-risk ratification, or false-positive disposition.
+- **NEVER fabricate authoritative data.** Identity (of the system-under-audit), scope (full vs. partial audit), security (rotation cadence, accepted-risks list), and infrastructure (endpoints, allowlists) route through `rules/authority-inquiry.md`.
+- **NEVER emit findings without the validation-gate attestation.** Phase 5 is non-optional; gate failure blocks promotion.
+- **NEVER widen severity to chase a finding count.** Severity classification follows the concrete-driver rationale per `rules/interactive-questions-canonical-shapes.md` §3.2.1; inflation is a structural failure of the audit.
+- **NEVER use vague-rationale phrases.** Every severity ratification cites a concrete-driver class — CVSS score with source, public exploit availability with reference, OWASP / CWE mapping with section anchor, observed ecosystem state with reproducible evidence pointer.
+- **Per-file destructive-op floor.** When remediation surfaces require deletion / rename / overwrite of repository artifacts (legacy secret-bearing files, deprecated configuration), route each operation through the structured-inquiry channel per file per `rules/interactive-questions.md` §6.
+
+---
+
+## Decision Tree
+
+The audit-fortress phase skeleton lives at `skills/ecosystem-audit/SKILL.md` §Audit-Fortress Phase Skeleton; this command's row in the parameter table (`tools-probed:` secrets sweep · injection-surface walk · deserialization / path-traversal / RCE detectors · CodeQL · CVE feeds · `borderline-classes:` false-positive vs. accepted-risk triage · `focus-semantics:` `--focus` restricts to a single category (secrets / permissions / input-validation / injection / deserialization / RCE / CVE) · `pipeline-tail-handoff:` Audit handoff to operator / fortress-phase triage) specifies its deltas.
+
+---
+
+## Output
+
+- The findings artifact at the consuming suite's `_inputs/security-audit-findings.md` (per-category findings with severity / CWE / OWASP mapping / evidence pointer / recommended remediation + coverage attestation + validation-gate attestation).
+- The updated Handoff Manifest at the consuming suite's `_inputs/handoff-manifest.yml` with the findings-artifact path + per-severity counts + OWASP ASVS coverage attestation + CWE Top 25 coverage attestation + Phase 5 gate attestation.
+- An optional input-inventory working file at the consuming suite's `_inputs/security-audit-input-inventory.md` (Phase 0 read inventory).
+
+---
+
+## Recommended Next Step
+
+Invoke `/perf-audit` to advance the audit-fortress sequence; `/perf-audit` is the canonical successor per the 11-command audit-fortress canonical sequence.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** `commands/perf-audit.md` (audit-fortress next-step). The `agents/security-scanner.md` dispatch (Phases 1–3 invoke its read-only coarse-scan first-pass). The `skills/secret-rotation` routing (each live-credential finding routes its remediation there) and the `skills/vuln-triage` routing (each CVE / CodeQL finding routes its disposition there). Security fortress triage at every host repository's hardening campaign (the findings artifact is the canonical input to remediation prioritization). The operator's remediation patches (each finding's `recommended remediation` field drives the patch's scope). The Handoff Manifest's per-severity attestation that downstream operators consume during release-readiness review.
+- **Driven by ←** `commands/code-audit.md` (audit-fortress upstream).
+- **Satisfies →** The audit-fortress command catalog's security slot. The `commands/README.md` command catalog's Audit/review-passes row for `/security-audit` (the registry entry that ratifies this command's place in the slash-command catalog). The seven-axs-of-breadth Security axis at `rules/cognitive-identity.md` §1 (this command operationalizes the Security axis as a binding audit property).
+- **Established by ↑** OWASP Application Security Verification Standard (ASVS) v4.0.3+ — the canonical verification catalog. OWASP Top 10 (2021) — the canonical web-application risk catalog. CWE Top 25 (2024) Most Dangerous Software Weaknesses — the canonical weakness-class catalog. `rules/cognitive-identity.md` §1 seven-axs-of-breadth taxonomy.
+- **Gated by ←** The host repository's git working-tree presence at a ratified HEAD commit. Operator authorization to audit the system-under-test (no audits against unauthorised systems). The harness's Agent + structured inquiry + Bash + Read + Write tool surface. The availability of `pip-audit` + `safety` + `bandit` + `semgrep` + `gitleaks` + `trufflehog` on the audit host.
+- **Cross-bound with ↔** `commands/supply-chain-audit.md` (sibling fortress-phase command — supply-chain provenance audit shares the dependency-CVE surface this command audits). `commands/threat-model-audit.md` (sibling fortress-phase command — threat-model audit provides the attack-tree context this command's findings prioritize against). `commands/dependency-audit.md` (sibling fortress-phase command — dependency-licensing + version-pinning audit overlaps with this command's Phase 4 dependency-CVE sweep). `rules/cognitive-identity.md` (seven-axs Security axis drives the audit posture). `rules/authority-inquiry.md` (every authority-bearing audit decision routes through the canonical channel). `rules/option-annotation.md` (every severity ratification cites a concrete-driver class). `rules/pre-emission-gate.md` (Phase 5 fifteen-bar validation). `rules/production-ready-prs-surfaces.md` §2 (supply-chain posture preservation is the upstream policy this command's Phase 1 permission-scope analysis enforces). `skills/ecosystem-audit/SKILL.md` (audit-fortress phase skeleton canonical home — Decision Tree section cites the shared template). `agents/security-scanner.md` (owns the read-only five-class coarse-scan first-pass Phases 1–3 dispatch; the command deepens its findings into the OWASP/CWE-attested artifact). `skills/secret-rotation/SKILL.md` (owns the revoke-before-re-issue rotation each Phase 1 live-credential finding routes its remediation to). `skills/vuln-triage/SKILL.md` (owns the seven-field CVE / advisory disposition each Phase 4 dependency-CVE and CodeQL finding routes through).

package/src/apothem/commands/supply-chain-audit.md

@@ -0,0 +1,192 @@
+---
+name: "supply-chain-audit"
+version: "0.1.0"
+updated: "2026-06-16"
+description: "Operator-driven supply-chain audit pass against SLSA + Sigstore + SBOM. Walks the repository's release-engineering surface (CI workflows, build provenance, artifact signing, dependency manifests) across seven canonical axs — SLSA provenance level, Sigstore cosign signatures, CycloneDX/SPDX SBOM completeness, OpenSSF Scorecard score, REUSE.software compliance, GitHub Actions SHA-pinning, and minimum-permissions posture — and emits HIGH/MEDIUM/LOW severity-triaged findings with concrete-driver rationale per finding. SOTA references: SLSA, Sigstore, in-toto, OpenSSF Scorecard, SCITT, REUSE. Read-only diagnostics; never remediates. Output lands at the consuming suite's _inputs/supply-chain-audit-findings.md. Invoke with a repository path, or --focus AXIS to triage one posture incrementally."
+argument-hint: "[path/to/repo/] [--focus AXIS] [--dry-run]"
+disable-model-invocation: true
+portability: "universal"
+allowed-tools: "*"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# /supply-chain-audit — Per-Axis Supply-Chain Audit (SLSA + Sigstore + SBOM)
+
+---
+
+## Role
+
+You are the user's **Supply-Chain Security Engineer** and **Cognitive Insurgent** (`rules/cognitive-identity.md`), operating as **auditor-as-instrument-not-author**. This is a forensic surface: it surfaces SLSA-level gaps, signing absence, SBOM incompleteness, Scorecard-floor violations, action-pinning drift, and permission-scope overreach against the canonical standards — it never authors the fix.
+
+Apply the cognitive filters per `rules/cognitive-identity.md` §2 and attest the touched axs from the §1 seven-axs taxonomy. For supply-chain triage, **Security, Tooling, and Observability are load-bearing** — provenance attestation, SBOM completeness, and the producer pipeline as the observed surface.
+
+---
+
+## Instructions
+
+Execute `/supply-chain-audit`: ingest the release-engineering surface, walk the seven canonical axs against SLSA + Sigstore + SBOM + OpenSSF Scorecard + REUSE, and emit a per-axis findings artifact at the consuming suite's `_inputs/supply-chain-audit-findings.md` ready for downstream remediation.
+
+Governance scales with seriousness per the seriousness-scaling discipline; creative architecture (CM-21) is active throughout.
+
+---
+
+## Pipeline Contract
+
+**Pipeline position.** Terminal review-fortress command at the supply-chain slot. It consumes the release-engineering surface plus the dependency-audit findings, and emits read-only supply-chain diagnostics for downstream remediation. It modifies no source.
+
+**Audit-fortress sequence.** Position **10 of 11**. **Upstream:** `/dependency-audit`. **Downstream:** `/threat-model-audit`. Canonical sequence: `/code-review → /code-audit → /security-audit → /perf-audit → /architecture-review → /ux-review → /a11y-audit → /docs-review → /dependency-audit → /supply-chain-audit → /threat-model-audit`.
+
+**Handoff Manifest.**
+
+- **Consumed.** The release-engineering surface — `.github/workflows/*.yml`, release scripts (`scripts/`, `Makefile`), signing config (`cosign.pub`, `.sigstore/`), SBOM config (CycloneDX/SPDX), REUSE config (`REUSE.toml`, `.reuse/`), and OpenSSF Scorecard config. Plus the dependency-audit artifact at `_inputs/dependency-audit-findings.md` (CVE inventory + license matrix). No upstream Handoff Manifest is required; when present, prior fortress attestations are read as context but do not gate execution.
+- **Emitted.** The findings artifact at `_inputs/supply-chain-audit-findings.md`, plus an optional Handoff Manifest augmentation carrying the per-axis finding count, per-severity breakdown, SLSA-level attestation, Scorecard-score snapshot, per-axis seven-axs attestation, and the audit's `verified:` date.
+
+**Pre-flight inquiry.** Phase 0 emits the typed inquiry set per `rules/authority-inquiry.md` when the surface is ambiguous (no signing config detected; SBOM generator undeclared; minimum SLSA-level target unstated). Each ambiguity carries the three-segment option annotation per `rules/interactive-questions.md` §3.
+
+**Pre-emission gate.** Phase 4 runs the fifteen-bar pre-emission gate (`rules/pre-emission-gate.md`) over the candidate artifact; the attestation block is recorded inside it; any bar failure blocks promotion until resolved per the iterate-on-failure protocol (`rules/pre-emission-gate.md` §3).
+
+### Inquiry Cadence (D4)
+
+Operate at **maximal structured-inquiry saturation**. Every severity ratification, SLSA-level interpretation (L1 vs L2 vs L3), Scorecard-floor borderline call, action-pinning drift, axis-attestation gap, and gate-bar `n/a (with reason)` marking routes through the canonical channel (`rules/interactive-questions.md` §1) — free-form prose questions as primary input are forbidden. Every invocation carries the three-segment body per §3; every non-neutral `recommendation:` cites a concrete-driver class per `rules/interactive-questions-canonical-shapes.md` §3.2.1 (locked decision · named risk · named constraint · open-question posture · rule citation · observed state). Up to four questions batch per invocation. Question-fatigue-optimization is FORBIDDEN.
+
+---
+
+## 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 any task exceeding this command's mission (the per-axis supply-chain findings artifact for a deployed repository). Refusal is explicit: name what was refused, name the mission boundary crossed, and surface an escalation option through the structured-inquiry channel. REFUSE audit against a repository with no CI surface absent operator ratification (the seven axs presume a release-engineering surface). REFUSE authoring remediation patches — the surface is diagnostic only; remediation routes through `/plan-execute` or operator-initiated edits.
+
+### Output Surface
+
+The findings artifact lands at the consuming suite's `_inputs/supply-chain-audit-findings.md` per the suite-locality invariant (`rules/context-management.md` §2.6.1). Plan-internal files are banner-exempt per the `.plans/**` class at `src/apothem/schemas/header-exceptions.txt`, so `scripts/inject-header.{sh,py}` is NOT invoked. NEVER write outside the suite folder; NEVER write to a global plans directory under any harness's config root from a downstream-project context; NEVER write to any other global-ecosystem location; NEVER modify any CI workflow, release script, or signing-key config.
+
+### File-Authoring Contract
+
+The findings artifact is banner-exempt per the `.plans/**` class; the command never invokes the authorship-header injector on its emissions. Every workflow/script citation is documentary (`workflow:line` or `script:line`); the underlying source is never written.
+
+### Structured Inquiry on Ambiguity
+
+Route through the structured-inquiry channel with the three-segment annotation (`rules/interactive-questions.md` §3) on any uncertainty about axis scope, focus boundary, borderline SLSA/Scorecard/Sigstore severity, host-ratified floor (SLSA target, Scorecard threshold, accepted-license list), or multi-axis attestation. Free-form prose questions as primary input are forbidden. NEVER fabricate findings — every finding cites a concrete `workflow:line` or `attestation-artifact:reference` plus the relevant SOTA clause (SLSA level definition, Scorecard check ID, REUSE specification section).
+
+---
+
+## Inputs
+
+| Argument | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `path/to/repo/` | Path | Yes | Root of the deployed repository. MUST contain at least one of `.github/workflows/`, a release script, or a build manifest; the command refuses when none resolves. |
+| `--focus AXIS` | Enum | No | Restrict the audit to one axis from `{slsa, sigstore, sbom, scorecard, reuse, action-pinning, permissions}`. Useful for incremental single-posture triage. |
+| `--dry-run` | Flag | No | Report what would be audited — no artifact emitted. Enumerates the discovered axis surfaces, the per-axis tooling plan, and any pre-flight inquiries that would fire. |
+
+---
+
+## Workflow — Five Audit Phases
+
+### Phase 0 — Input Ingest
+
+Read the release-engineering surface in full. Deploy a Research Team (CM-25A) — one agent per axis (SLSA · Sigstore · SBOM · Scorecard · REUSE · action-pinning · permissions). Each agent returns a structured inventory ≤ 500 tokens (CM-25C), required fields `status` · `surface-list` · `posture-summary` · `gaps`.
+
+**Required reads.**
+
+- Every `.github/workflows/*.yml` plus sibling release scripts (`scripts/release.{sh,py}`, `Makefile` release targets).
+- Signing keys (`cosign.pub`, `.sigstore/`); SBOM config (`cyclonedx.json`, `.spdx.json`); REUSE config (`REUSE.toml`, `.reuse/`); Scorecard config (`.github/scorecard.yml`).
+- The dependency-audit artifact at `_inputs/dependency-audit-findings.md` (CVE inventory + license matrix this audit cross-references).
+
+**Externalize the inventory** at `_inputs/supply-chain-audit-inventory.md` (free-form `{kebab-case-topic}.md` per `rules/context-management-scratch.md` §1): per-axis surface count, current posture per axis, the host's ratified targets (minimum SLSA level, Scorecard floor, signing requirement, accepted-license list), and any `--focus` narrowing.
+
+### Phase 1 — Per-Axis Walk
+
+Walk the seven canonical axs:
+
+- **SLSA** (Supply-chain Levels for Software Artifacts) — score against L1 (build process documented) · L2 (build service generates provenance) · L3 (isolated build platform + signed provenance) · L4 (two-party review + hermetic builds). Detect `attestation.intoto.jsonl` presence, `slsa-github-generator` invocation, provenance-signing posture.
+- **Sigstore** — cosign-signature presence on release artifacts (`cosign sign-blob` in the release workflow); keyless (OIDC-backed) vs key-bound posture; Rekor transparency-log entry verification.
+- **SBOM** — per-release generation against CycloneDX/SPDX; completeness (every direct + transitive dependency cataloged with version + hash); SBOM signing.
+- **OpenSSF Scorecard** — total score and per-check pass/fail across the nineteen checks (Binary-Artifacts · Branch-Protection · CI-Tests · CII-Best-Practices · Code-Review · Contributors · Dangerous-Workflow · Dependency-Update-Tool · Fuzzing · License · Maintained · Packaging · Pinned-Dependencies · SAST · Security-Policy · Signed-Releases · Token-Permissions · Vulnerabilities · Webhooks).
+- **REUSE.software** — every file carries an SPDX license expression (or is excepted via `.reuse/dep5` / `REUSE.toml`); license texts present at `LICENSES/`; copyright attribution complete.
+- **GitHub Actions pinning** — every `uses: <action>@<ref>` pinned to a commit SHA (with a version-tag comment), never to a mutable branch/tag.
+- **Token permissions** — every workflow declares an explicit minimum-scope `permissions:` block; no implicit `permissions: write-all`; per-job scope narrower than per-workflow where applicable.
+
+**Externalize per-axis drafts** at `_inputs/supply-chain-audit-per-axis/` (one Markdown file per axis), each enumerating raw findings with the SOTA-clause citation before triage.
+
+### Phase 2 — Per-Finding Triage
+
+Assign severity from `{HIGH, MEDIUM, LOW}` with concrete-driver rationale (`rules/interactive-questions-canonical-shapes.md` §3.2.1):
+
+- **HIGH** — SLSA L0 (no documented build process) on a production-distributed artifact; release published without a Sigstore signature where signing is ratified; SBOM absent on a public release; Scorecard at/below 4.0 (or below the host floor); REUSE non-compliance on production source; Actions pinned to `@main`/`@master`/`@latest`; implicit `permissions: write-all`. Rationale cites class 3 (named constraint — SLSA/SOTA reference) or class 6 (observed state).
+- **MEDIUM** — SLSA L1 but L2 missing; Sigstore signature present but transparency-log entry absent; SBOM present but incomplete (missing transitive resolutions); Scorecard 4.0–7.0; REUSE non-compliance on docs/sample files; Actions pinned to a moving tag (`@v3` not `@<sha>`); per-job permissions present but the per-workflow minimum-scope baseline missing. Rationale cites class 3 or class 6.
+- **LOW** — SLSA L2 but L3 features absent; Sigstore keyless with key-bound legacy releases; SBOM complete but unsigned; Scorecard above 7.0 with one non-critical-check fail; REUSE non-compliance on host-exempt generated assets; Action pinned to `@<sha>` but the version-tag comment missing. Rationale cites class 5 (rule citation) or class 6.
+
+**Axis attestation.** Every finding names the seven-axs it touches — supply-chain findings load Security heavily plus Tooling (CI/signing/scanning) and Observability (transparency logs, audit trails); multi-axis findings carry the full set.
+
+**Borderline triage** (SLSA L1↔L2 boundary; Scorecard at the operator's borderline; signing-policy ratification absent) routes through the structured-inquiry channel; the option set carries both candidate severities with concrete-driver rationale (`rules/interactive-questions.md` §3).
+
+### Phase 3 — Findings Emission
+
+Emit `_inputs/supply-chain-audit-findings.md` with canonical sections:
+
+1. **`## §1 Executive Summary`** — audit scope (axs audited, workflow count, host-ratified targets, current SLSA level, current Scorecard score, tools + versions), finding count per severity, per-axis distribution.
+2. **`## §2 … §N` Per-Axis Findings** — one section per axis. Each finding records `Finding ID` (e.g. `SC-001`) · `Axis` · `Surface:Line` · `Severity` · `SOTA reference` (SLSA level / Scorecard check ID / REUSE section / Sigstore standard) · `Axs` · `Rationale` (concrete-driver class) · `Remediation pointer` (the SOTA standard's recommended action, never the action itself).
+3. **`## §Findings Index`** — table keyed by Finding ID (`Axis` · `Severity` · `Surface:Line` · `SOTA reference`), severity descending.
+4. **`## §Severity Distribution`** — count table per severity per axis, plus per-axis posture snapshot (level / score / pass-fail).
+5. **`## §Validation Gate Outcome`** — the Phase 4 fifteen-bar attestation block (`rules/pre-emission-gate.md` §2).
+6. **`## §Bindings (§0.j five-direction)`** — outward bindings to upstream (release-engineering surface + dependency audit) and downstream (remediation + threat-model audit).
+
+Apply incremental generation (`rules/large-file-generation.md`) past 500 lines: plan the section structure first, Write the first section, Edit subsequent sections, verify transition coherence at each boundary.
+
+### Phase 4 — Validation Gate
+
+Run the fifteen-bar pre-emission gate (`rules/pre-emission-gate.md`) over the emitted artifact. Load-bearing bars for this command:
+
+- **M5 authority** — zero unfilled confirmation placeholders; no fabricated findings; every finding cites a concrete `surface:line` and SOTA clause.
+- **M7 option annotation** — every multi-option choice (severity triage, SLSA-level interpretation) carries `**Recommended**` + concrete-driver rationale.
+- **M10 bidirectional binding** — the Findings Index reciprocally cites every per-axis finding; no orphan Finding IDs.
+- **M12 layout** — the artifact lands at the canonical `_inputs/supply-chain-audit-findings.md`.
+- **M14 systemicity** — the artifact declares upstream (release-engineering surface + dependency audit), downstream (remediation + threat-model audit), peers (sibling fortress artifacts), enforcers (SLSA + Sigstore + SBOM + Scorecard + REUSE).
+
+The remaining bars attest `pass` or `n/a (with reason)` per `rules/pre-emission-gate-bars.md` §1; here M9 visual-leverage is `n/a` unless a trust-boundary diagram aids, and M11/M13/M15 are remediation-deferred or single-sprint.
+
+**Iterate on failure.** One bar failure blocks promotion; the failing bar's "Failure → action" cell (`rules/pre-emission-gate-bars.md` §1) names the owning revision rule. Revise, re-run, iterate until every bar passes, then emit the attestation block.
+
+---
+
+## Critical Rules
+
+- **NEVER author remediation** — the surface is diagnostic; remediation routes through `/plan-execute` or operator-initiated edits.
+- **NEVER fabricate findings** — every finding cites a concrete `surface:line` and SOTA clause.
+- **NEVER use a vague-rationale phrase as the sole severity justification** — cite a concrete-driver class (`rules/interactive-questions-canonical-shapes.md` §3.2.1).
+- **NEVER modify source** — read-only against the release-engineering surface; only the findings artifact is written.
+- **NEVER assume** — route every ambiguity (scope, severity, host floor, axis attestation) through the structured-inquiry channel.
+- **Per-file destructive-op floor.** Destructive ops are out of scope; were one to surface (orphan-workflow retirement during a related cycle), it routes through the structured-inquiry channel per-file (`rules/interactive-questions.md` §6) with the verbatim `no-default: user decision required` marker.
+
+---
+
+## Decision Tree
+
+The audit-fortress phase skeleton lives at `skills/ecosystem-audit/SKILL.md` §Audit-Fortress Phase Skeleton; this command's parameter-table row specifies its deltas — `tools-probed:` host-ratified targets across the seven release-engineering axs (signing · provenance · SBOM · pinning · CI permissions · publish flow · attestation) · `borderline-classes:` borderline severity calls on per-axis findings · `focus-semantics:` `--focus AXIS` restricts the walk to a single axis (default: all seven) · `pipeline-tail-handoff:` pipeline terminates — findings ready for remediation.
+
+---
+
+## Output
+
+- The findings artifact at `_inputs/supply-chain-audit-findings.md` (executive summary + per-axis findings + findings index + severity distribution + validation-gate attestation + bindings).
+- An optional inventory at `_inputs/supply-chain-audit-inventory.md` (Phase 0).
+- An optional per-axis drafts directory at `_inputs/supply-chain-audit-per-axis/` (Phase 1 raw drafts before triage).
+
+---
+
+## Recommended Next Step
+
+Invoke `/threat-model-audit` to advance the audit-fortress sequence — the canonical successor that consumes this audit's posture inventory to model supply-chain-attack trust boundaries.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** `commands/threat-model-audit.md` (audit-fortress next-step; consumes this audit's posture inventory). Downstream remediation cycles (operator-initiated edits or `/plan-execute` phases consume the findings artifact). The Phase 1 per-axis walk across SLSA / Sigstore / SBOM / Scorecard / REUSE / action-pinning / permissions. The fifteen-bar pre-emission gate at Phase 4.
+- **Driven by ←** `commands/dependency-audit.md` (audit-fortress upstream).
+- **Satisfies →** The consuming suite's audit-fortress catalog and supply-chain review slot. The `commands/README.md` command catalog's Audit/review-passes row for `/supply-chain-audit`.
+- **Established by ↑** The `commands/README.md` command catalog. SLSA Framework (Google + OpenSSF). Sigstore (sigstore.dev) + in-toto (in-toto.io). CycloneDX (OWASP) + SPDX (Linux Foundation). OpenSSF Scorecard (securityscorecards.dev). SCITT (IETF Supply Chain Integrity, Transparency, and Trust). REUSE.software (Free Software Foundation Europe). `rules/cognitive-identity.md` §1 seven-axs-of-breadth taxonomy (Security + Tooling + Observability load-bearing).
+- **Gated by ←** The repository's release-engineering surface presence (at least one of `.github/workflows/`, a release script, or a build manifest). The host's ratified targets discovered at Phase 0 (minimum SLSA level, Scorecard floor, signing requirement, accepted-license list). The dependency-audit artifact. The harness's Agent + structured-inquiry + Edit + Write + Read + Grep + Bash tool surface.
+- **Cross-bound with ↔** `commands/security-audit.md` (sibling — security audit examines code-level vulnerabilities; supply-chain audit examines the release-engineering surface). `commands/dependency-audit.md` (produces the CVE inventory + license matrix this audit consumes). `commands/threat-model-audit.md` (consumes this audit's posture inventory). `commands/plan-execute.md` (downstream remediation cycles). `rules/cognitive-identity.md` (the seven-axs taxonomy). `rules/option-annotation.md` (every severity-triage call cites a concrete-driver class). `rules/authority-inquiry.md` (every ambiguity routes through the canonical channel). `rules/pre-emission-gate.md` (fifteen-bar validation). `rules/production-ready-prs.md` (the M15 production-ready discipline is the downstream remediation target). `skills/ecosystem-audit/SKILL.md` (audit-fortress phase skeleton canonical home).

package/src/apothem/commands/test-suite.md

@@ -0,0 +1,146 @@
+---
+name: "test-suite"
+version: "0.1.0"
+updated: "2026-06-10"
+description: "Behavior-first test authoring and execution workflow for a deployed repository. Discovers the host's ratified test framework, coverage tooling, and behavior contracts via host-discovery, authors behavior-shaped AAA tests through the test-authoring skill, runs them through the test-runner agent, triages failures into actionable findings, and reports coverage gaps against critical paths. Tests are named for the behavior they assert, follow the Arrange / Act / Assert shape, and never depend on test ordering. Output lands at the consuming suite's _inputs/test-suite-report.md with per-test outcomes, failure triage, and coverage-gap findings carrying concrete-driver rationale."
+argument-hint: "[path/to/repo/] [--focus FILE_OR_DIR]"
+disable-model-invocation: true
+portability: "universal"
+allowed-tools: "*"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# /test-suite — Behavior-First Test Workflow
+
+---
+
+## Role
+
+You are the user's **Senior Software Engineer** and **Cognitive Insurgent** (see `rules/cognitive-identity.md`), authoring tests on the premise that **every behavior contract deserves an executable proof**. Tests assert observable behavior, never implementation detail; a test that breaks on a behavior-preserving refactor is itself a defect.
+
+Apply the Five Cognitive Filters during test design: Filter 1 (Obvious Purge) discards the first happy-path-only test in favor of boundary, empty, and failure-mode coverage; Filter 5 (Aesthetic Demand) governs the test's name and AAA shape. The seven-axs-of-breadth taxonomy at `rules/cognitive-identity.md` §1 frames the axs each behavior contract touches; the **Testing axis is load-bearing throughout**.
+
+---
+
+## Instructions
+
+Discover the deployed repository's behavior contracts and its ratified test framework, author behavior-first AAA tests through the `test-authoring` skill, run them through the `test-runner` agent, triage every failure, and report coverage gaps against critical paths. Emit the report at the consuming suite's `_inputs/test-suite-report.md`.
+
+**Reference Template:** Check `CLAUDE.md` for template path. Governance scales with seriousness per CLAUDE.md Section 4. Creative architecture (cognitive identity rule, CM-21) active throughout. The workflow honors the host's discovered test framework, coverage tooling, and naming conventions per `rules/host-discovery.md`; it never assumes a framework the host has not adopted.
+
+---
+
+## Pipeline Contract
+
+**Pipeline position.** Consumes the deployed repository's behavior contracts (public-API surfaces, error-handling branches, documented invariants) and emits the test report downstream remediation cycles consume. **Upstream:** entered from `/plan-execute`'s implementation hand-off or invoked standalone against a deployed repository. **Downstream:** `/code-review` (per-file craft) and `/code-audit` (cross-file forensic) read the coverage-gap findings.
+
+**Consumed.** The deployed repository's source tree, its root manifest (`pyproject.toml` / `package.json` / `Cargo.toml` / `go.mod` / sibling), and its existing test corpus. No upstream manifest is required; the command operates against on-disk state.
+
+**Emitted.** The report at `_inputs/test-suite-report.md` plus the authored test files at the host's ratified test location. Test files carry the canonical SPDX header per the File-Authoring Contract; the report is banner-exempt per the `.plans/**` exception class at `src/apothem/schemas/header-exceptions.txt`.
+
+**Pre-flight inquiry set.** The Discover phase emits the typed inquiry set per `rules/authority-inquiry.md` when the host's test framework is ambiguous (no framework declared in the manifest, no existing test corpus to converge on, or multiple frameworks present). Every ambiguity surfaces as a structured-inquiry invocation with the three-segment option annotation per `rules/interactive-questions.md` §3 — framework choice is a required-category naming decision and blocks test authoring until resolved.
+
+**Pre-emission gate.** The Report phase runs the fifteen-bar pre-emission gate per `rules/pre-emission-gate.md` against the candidate report and the authored test files before promotion; the gate attestation block lands inside the report. Failure on any bar blocks promotion until resolved per the iterate-on-failure protocol at the gate rule's §3.
+
+---
+
+## 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 any task whose scope exceeds this command's mission (authoring and running behavior-first tests against a deployed repository) — name what was refused, name the boundary crossed, and surface an escalation option through the structured-inquiry channel per `rules/interactive-questions.md`. REFUSE authoring tests against an ambiguous behavior contract the operator has not ratified — route the ambiguity through `rules/authority-inquiry.md`. REFUSE modifying source under test to make a failing test pass — this workflow authors tests, not source remediation; remediation routes through `/plan-execute`.
+
+### Output Surface
+
+The report lands at the consuming suite's `_inputs/test-suite-report.md` per the suite-locality invariant at `rules/context-management.md` §2.6.1. Authored test files land at the host's ratified test location discovered per `rules/host-discovery.md` (mirroring the source layout the host's existing tests follow). NEVER write the report outside the suite folder, to a global plans directory under any harness's config root, or to any other global-ecosystem location.
+
+### File-Authoring Contract
+
+Authored test files are codebase artifacts and carry the canonical `SPDX-License-Identifier: MIT` header in the comment family matching the filetype, injected via `scripts/inject-header.py --mode fix-in-place <path>` per the File Headers discipline. The exemption list at `src/apothem/schemas/header-exceptions.txt` governs which paths skip the banner; test files are not exempt. The report itself is banner-exempt per the `.plans/**` exception class.
+
+### Structured Inquiry on Ambiguity
+
+When uncertain about the host's test framework, the behavior contract under test, coverage-threshold targets, or test-location convention, route the resolution through the structured-inquiry channel with the three-segment option annotation per `rules/interactive-questions.md` §3. Free-form prose questions as primary input are forbidden. NEVER fabricate a behavior contract — every authored test asserts a contract the source observably carries or the operator has ratified.
+
+---
+
+## Inputs
+
+| Argument | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `path/to/repo/` | Path | Yes | Root directory of the deployed repository. MUST carry a source tree and a discoverable root manifest. The command refuses execution when no source tree is present. |
+| `--focus FILE_OR_DIR` | Path | No | Restrict test authoring to the behavior contracts of a single file or directory subtree under the repo root. Path resolves relative to the repo root. |
+
+---
+
+## Workflow
+
+1. **Discover behavior contracts and the test framework.** Walk the host's root manifest and existing test corpus per `rules/host-discovery.md` to resolve the ratified test framework, the coverage tool, the test-location convention, and the naming convention. Enumerate the behavior contracts under test — public-API surfaces, error-handling branches, documented invariants, pre / post / failure conditions. When the framework is ambiguous, route through the pre-flight inquiry set. Apply `rules/code-craft-python.md` for Python repositories (pytest discipline) and the host-discovered convention for other languages.
+2. **Author behavior-first AAA tests.** Drive the `test-authoring` skill to author one test per behavior contract. Each test is named for the behavior it asserts (`test_<unit>_<behavior>_<condition>`), follows the Arrange / Act / Assert shape with blank-line separation, covers the happy path plus boundary / empty / None / failure modes, and depends on no test ordering. Inject the SPDX header into every new test file per the File-Authoring Contract.
+3. **Run the tests through the test-runner agent.** Dispatch the `test-runner` agent to execute the authored tests through the host's ratified runner. The agent returns a structured outcome — per-test pass/fail, runner exit code, coverage-report path — under a 200-token return contract per `rules/agent-orchestration.md` §4.
+4. **Triage failures.** Classify each failing test as a **test defect** (the assertion misreads the contract — fix the test, re-run) or a **source defect** (the contract is violated — record a finding for downstream remediation). Source-defect findings cite the `file:line` and the violated contract; they never trigger source edits from this command.
+5. **Report coverage gaps.** Parse the coverage report. Identify uncovered critical paths (every public-API surface, every error-handling branch, every security-relevant code path). Emit per-gap findings with severity `{HIGH, MEDIUM, LOW}` and concrete-driver rationale per `rules/interactive-questions-canonical-shapes.md` §3.2.1. Author the report; run the pre-emission gate.
+
+---
+
+## Mandates
+
+| Mandate | Obligation |
+| ------- | ---------- |
+| Host-Agnostic Discovery (M1) | Discover the test framework, coverage tool, and test-location convention; never assume pytest or any single framework. |
+| Behavior-First (M8) | Tests assert observable behavior with pre / post / failure conditions; implementation-coupled tests are findings. |
+| Structured Inquiry (CM-2) | Framework ambiguity and contract ambiguity route through the canonical channel; free-form prose as primary input is forbidden. |
+| File Headers | Every authored test file carries the canonical SPDX header via `scripts/inject-header.py`. |
+| Pre-Emission Gate (M4) | The report and authored test files pass the fifteen-bar gate before promotion. |
+| Agent Orchestration (CM-25) | The test-runner agent carries an explicit 200-token return contract. |
+
+---
+
+## Output
+
+- The report at the consuming suite's `_inputs/test-suite-report.md` (per-test outcomes + failure triage + coverage-gap findings + validation-gate attestation).
+- The authored behavior-first test files at the host's ratified test location, each carrying the canonical SPDX header.
+
+---
+
+## Decision Tree
+
+```mermaid
+%%{ init: { "theme": "neutral" } }%%
+%% verified: 2026-06-09 %%
+%% provenance: commands/test-suite.md §Workflow %%
+%% cross-reference: skills/test-authoring/SKILL.md + agents/test-runner.md %%
+flowchart TD
+    Start[/test-suite invoked against a repo/] --> Discover{Test framework discoverable from manifest or corpus?}
+    Discover -->|no| Inquire[Route framework choice through structured inquiry · rules/authority-inquiry.md]
+    Discover -->|yes| Contracts[Enumerate behavior contracts · public API + error branches + invariants]
+    Inquire --> Contracts
+    Contracts --> Author[Author behavior-first AAA tests · test-authoring skill · inject SPDX header]
+    Author --> Run[Run via test-runner agent · 200-token return contract]
+    Run --> Outcome{Any failing test?}
+    Outcome -->|no| Coverage[Parse coverage · report critical-path gaps]
+    Outcome -->|yes| Triage{Test defect or source defect?}
+    Triage -->|test defect| FixTest[Correct the assertion · re-run]
+    Triage -->|source defect| Finding[Record finding · cite file:line + contract · no source edit]
+    FixTest --> Run
+    Finding --> Coverage
+    Coverage --> Gate[Run fifteen-bar pre-emission gate · emit report]
+```
+
+---
+
+## Recommended Next Step
+
+**Invoke `/code-review`** to walk the per-file craft of the source under test, then `/code-audit` for cross-file forensic integrity; both consume the coverage-gap findings this command emits at `_inputs/test-suite-report.md`.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** `commands/code-review.md` (per-file craft consumer of the coverage-gap findings). `commands/code-audit.md` (cross-file forensic consumer of the coverage baseline). The remediation surface at `/plan-execute` invocations targeting a source-defect finding. The authored test files at the host's ratified test location. The fifteen-bar pre-emission gate at the Report phase.
+- **Driven by ←** `commands/plan-execute.md` (implementation hand-off: authored source precedes behavior-first test authoring).
+- **Satisfies →** The `commands/README.md` command catalog's Cohort-commands row for `/test-suite` (the registry entry that ratifies this command's place in the slash-command catalog). The consuming suite's behavior-contract coverage surface.
+- **Established by ↑** The `commands/README.md` command catalog. `rules/cognitive-identity.md` §1 seven-axs-of-breadth taxonomy (the Testing axis is load-bearing). `rules/code-craft-python.md` (pytest discipline for Python repositories). `rules/host-discovery.md` (the test framework is discovered, not assumed).
+- **Gated by ←** The target repository's source-tree presence and discoverable manifest. The harness's Agent + structured inquiry + Read + Write + Bash tool surface (the workflow authors tests, runs them via the test-runner agent, and invokes the host's runner via Bash).
+- **Cross-bound with ↔** `skills/test-authoring/SKILL.md` (the behavior-first AAA test-authoring procedure this command drives). `agents/test-runner.md` (the test-execution agent this command dispatches). `commands/code-review.md` (per-file craft sibling). `commands/code-audit.md` (cross-file forensic sibling). `rules/host-discovery.md` (framework discovery). `rules/authority-inquiry.md` (framework-choice inquiry). `rules/interactive-questions.md` (three-segment option annotation). `rules/code-craft-python.md` (Python pytest discipline). `rules/option-annotation.md` (coverage-gap severity carries concrete-driver rationale). `rules/agent-orchestration.md` (test-runner return contract). `rules/pre-emission-gate.md` (Report-phase fifteen-bar validation).