@ahmed-g-gad/apothem 0.1.1

package/src/apothem/skills/incident-runbook/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: "incident-runbook"
+version: "0.1.0"
+updated: "2026-06-09"
+description: "Author and execute operational incident runbooks — matched when the operator asks to 'write a runbook', define an 'on-call procedure', author 'incident response steps', document a 'recovery procedure', 'document recovery steps for a failing service', or capture the response sequence for a failing or compromised service. Produces a runbook in the canonical five-stage shape — Trigger → Diagnosis → Action → Verification → Rollback — where every Action step carries an explicit, paired rollback path and every irreversible Action sits behind a no-default confirmation gate. On execution, advances Diagnosis → Action → Verification in order, confirming each live-infrastructure Action through the structured-inquiry channel and STOPping at the first Verification failure to surface its rollback. Serves the developer and security cohorts. NOT for provisioning monitoring/alerting/dashboards, paging on-call rotations or opening incident channels, writing post-mortems or retrospectives, or batch-executing destructive remediation unattended. User-invocable directly."
+archetype: "runbook-template"
+userInvocable: true
+argument-hint: "[--service NAME]"
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+## Purpose
+
+Author and execute operational runbooks for a named service. Every runbook follows the canonical five-stage structure — **Trigger · Diagnosis · Action · Verification · Rollback** — and every Action carries an explicit rollback path the on-call operator can execute under pressure.
+
+The product is a document an operator reaches for at 3 a.m. and trusts without hesitation: each step is concrete (names the exact command), ordered (the sequence is the procedure), and reversible (every Action has a tested inverse, or is named irreversible behind a confirmation gate).
+
+## Detection Signal
+
+Triggers when the operator asks to "write a runbook", define an "on-call procedure", author "incident response steps", document a "recovery procedure", or capture the response sequence for a failing or compromised service. Any phrasing that asks for the ordered operational steps an on-call engineer follows during an incident matches.
+
+## Non-Goals
+
+This skill carries a deliberately narrow surface. It is NOT:
+
+- **Not a monitoring or alerting configurator.** The runbook names the trigger the operator observes; it does not provision dashboards, alert rules, or telemetry pipelines.
+- **Not an incident-management platform.** It authors the procedure document; it does not page on-call rotations, open incident channels, or track timelines in a tracker.
+- **Not a post-mortem writer.** The runbook is the forward-acting recovery procedure, not the retrospective. Post-incident analysis lands in a separate document.
+- **Not a remediation auto-runner.** When executing a runbook, the skill performs each Action against live infrastructure only after the operator confirms via the structured-inquiry channel; it never batch-executes destructive steps unattended.
+
+## Workflow — Authoring
+
+1. **Discover the service surface.** Walk the host's ratified source-of-truth files per `rules/host-discovery.md` to identify the named service (from `--service NAME` or inquiry), its deployment topology, health-check endpoints, log locations, and existing runbook conventions. Record each discovery with provenance.
+2. **Author the Trigger stage.** State the observable condition that opens the incident — the alert name, the error-rate threshold, the failed health check, the security signal. The Trigger is a falsifiable observation, never a feeling.
+3. **Author the Diagnosis stage.** Enumerate the ordered diagnostic steps that localize the root cause: the log queries to run, the metrics to read, the dependency checks to perform. Each step names the command and the expected signal that confirms or rules out a cause.
+4. **Author the Action stage.** Enumerate the ordered remediation steps. Each Action step names the exact command or operation, the expected post-condition, and a one-line precondition that must hold before it runs.
+5. **Author the Rollback stage — paired to every Action.** For each Action step, author the inverse operation that returns the service to its pre-Action state. An Action whose rollback cannot be executed because the operation is irreversible is named explicitly as irreversible, and that Action carries a `no-default: user decision required` confirmation gate per `rules/interactive-questions.md` §6. **Action–Rollback parity is the central invariant: no Action ships without a paired Rollback or an explicit irreversibility declaration.**
+6. **Author the Verification stage.** State the ordered checks that confirm recovery: the health endpoint returns healthy, the error rate falls below threshold, the security signal clears. Each check names the command and the pass condition.
+7. **Emit the runbook file.** Write the runbook to its host-natural location, route the new file through `scripts/inject-header.py`, and confirm every Action step has a paired Rollback step (or a declared irreversibility gate) before the file is considered complete.
+
+## Workflow — Execution
+
+When the operator asks to run an authored runbook, advance **Diagnosis → Action → Verification** in order:
+
+- Run the Diagnosis steps and report which causes are confirmed or ruled out.
+- For each Action step, confirm via the structured-inquiry channel before executing against live infrastructure; never batch live Actions.
+- STOP at the first Verification failure and surface the paired Rollback path for the failed Action — do not advance past a failed verification.
+
+## Return Contract
+
+Maximum response: 800 tokens for authoring; unlimited when executing a runbook against live infrastructure. Structure:
+
+- **Summary** — one sentence naming the service and the runbook's incident scope.
+- **Stages emitted** — the Trigger / Diagnosis / Action / Verification / Rollback sections with their step counts.
+- **Action–Rollback parity** — confirmation that every Action step carries a paired Rollback step, with any irreversible Actions named.
+- **Surfaced gaps** — discovery gaps, missing endpoints, or unverifiable rollback paths (empty when none).
+- **File path** — the canonical location the runbook was written to.
+
+## Foundational Stanzas
+
+The four standing surfaces every operator inherits.
+
+### Refusal & Escalation
+
+REFUSE any request that asks the skill to act outside its mission — provisioning monitoring, paging rotations, writing post-mortems, or batch-executing destructive remediation unattended. Refusal is explicit: name what was refused, name the mission boundary crossed, and surface an escalation option through the structured-inquiry channel per `rules/interactive-questions.md` (canonical channel; three-segment option annotation; free-form prose as primary input is forbidden). When an Action step has no executable Rollback and the operator has not confirmed the irreversibility gate, STOP — do not emit a runbook with an unguarded irreversible Action.
+
+### Output Surface
+
+The skill emits one runbook document per invocation at the host's ratified runbook location, discovered per `rules/host-discovery.md`. Planning artifacts go to `<project-root>/.apothem/plans/{suite}/`; NEVER write a plan-suite artifact to any global-ecosystem location. Runbook prose carries natural domain language per `rules/operational-mandates.md` CM-7 — zero plan-internal references.
+
+### File-Authoring Contract
+
+Every NEW file the skill creates routes through `scripts/inject-header.py` so the canonical `SPDX-License-Identifier: MIT` header is injected in the comment family matching the filetype; the injector is idempotent and detects the variant from the byte-exact fixture at `src/apothem/schemas/authorship-header.txt`. The exempt classes are enumerated at `src/apothem/schemas/header-exceptions.txt`. Edits to existing runbooks preserve any existing header.
+
+### Structured Inquiry on Ambiguity
+
+When the skill reaches a decision in any of the seven authoritative-data categories per `rules/host-discovery.md` and the host is silent — the service name, the deployment target, the health endpoint, the log location, the rollback mechanism — it routes 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. Every Action step that deletes, restarts, scales down, or revokes against live infrastructure routes through the per-file destructive-op floor per `rules/interactive-questions.md` §6 — one invocation per operation, every option's `default-pointer:` carrying the verbatim `no-default: user decision required` marker.
+
+## Recommended Next Step
+
+**Invoke the `incident-runbook` skill via the Skill tool** with `--service NAME` to author the runbook for a named service, then execute its Verification stage against a staging deployment to confirm every step is orderable before the runbook reaches on-call.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every authored runbook's Trigger / Diagnosis / Action / Verification / Rollback structure. ● The Action–Rollback parity invariant at every emitted runbook. ● Every live-infrastructure Action step's destructive-op confirmation gate.
+- **Satisfies →** ● The developer and security cohorts' need for tested, reversible operational procedures. ● `CLAUDE.md` Source Layout row "incident-runbook" (skills/ class).
+- **Established by ↑** ● `CLAUDE.md` Source Layout (skills/ folder-with-`SKILL.md` class). ● `CLAUDE.md` Ambiguity Handling (structured inquiry over fabrication).
+- **Gated by ←** ● The harness's Write / Edit / Bash tool surface. ● The host's discovered runbook conventions per `rules/host-discovery.md`.
+- **Cross-bound with ↔** ↔ `rules/interactive-questions.md` (structured-inquiry channel; per-file destructive-op floor for live Actions). ↔ `rules/host-discovery.md` (service-surface discovery). ↔ `scripts/inject-header.py` (authorship-header injection). ↔ `src/apothem/schemas/header-exceptions.txt` (header-exempt classes). ↔ `skills/plan-suite/SKILL.md` + `skills/ecosystem-audit/SKILL.md` (sibling skills under the same registry section).

package/src/apothem/skills/multi-source-research/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: "multi-source-research"
+version: "0.1.0"
+updated: "2026-06-09"
+description: "Multi-source research harness — matched when the operator asks to 'research X deeply', 'investigate', 'find sources on', 'gather evidence about', 'fact-check', or any phrasing that demands a fanned-out, cross-verified, cited report rather than a single answer recalled from memory. Runs a five-step pipeline: decompose the question into testable sub-questions, fan out parallel source-discovery queries through a Research Team agent dispatch, fetch and extract claims per source, adversarially verify each claim against two or more independent sources, and synthesize a cited report where every claim carries its sources, a HIGH/MEDIUM/LOW confidence level, and an open-questions list. A single-source claim never closes at HIGH; an unverifiable claim is reported at LOW with the gap named, never papered over with an invented citation. User-invocable directly. NOT a single-answer lookup, a code generator, a plan-suite generator, a documentation generator, or a single-source summarizer."
+archetype: "research-template"
+userInvocable: true
+argument-hint: "[research question]"
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch, Agent"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+## Purpose
+
+Answer a research question with a cited, cross-verified report rather than a single recalled answer. The skill decomposes the question into sub-questions, discovers sources in parallel, extracts claims per source, verifies each claim against two or more *independent* sources, and synthesizes the findings into a report where every claim carries its sources and a confidence level.
+
+The load-bearing discipline is **adversarial verification**: a claim is not closed until independent evidence confirms it, contradictions are surfaced rather than silently resolved, and the absence of corroboration is reported as low confidence — never hidden behind an invented citation.
+
+## Detection Signal
+
+Triggers when the operator asks to "research X deeply", "investigate", "find sources on", "gather evidence about", "fact-check", or any phrasing that demands a fanned-out, cross-verified, cited report — never a single answer recalled from memory. The signal is the demand for *sourced, multi-source evidence* over a single-shot reply.
+
+## Non-Goals
+
+This skill carries a deliberately narrow surface. It is NOT:
+
+- **Not a single-answer lookup.** A one-shot recalled answer is a different surface; this skill exists when the answer must be sourced and cross-verified.
+- **Not a code generator.** The skill emits a research report, never codebase artifacts. Code emission is the host's `/plan-execute` surface.
+- **Not a plan-suite generator.** Phase decomposition and plan structure belong to the `/plan` pipeline stages; this skill consumes no plan template and writes no plan-suite artifact.
+- **Not a documentation generator.** The report is working research evidence, not user-facing documentation. User-facing docs land at the host's documentation surfaces per `rules/host-discovery.md`.
+- **Not a single-source summarizer.** A claim resting on one source is reported at the lowest confidence with the dependency named; one source never closes a claim.
+
+## Workflow
+
+1. **Decompose the question.** Split the research question into testable sub-questions, each answerable by sourced evidence. Record the sub-question set before any search. When the question is underspecified (scope, region, timeframe, or definition ambiguous), STOP and surface the clarifying choices through the structured-inquiry channel before fanning out — fanning out against an ambiguous question wastes the fan-out budget.
+2. **Fan out parallel source-discovery queries.** Dispatch one `WebSearch` per sub-question through parallel Agent fan-out per `rules/agent-orchestration.md` — a Research Team, full-parallel, structured-summary return contract. Each agent returns candidate source URLs with relevance notes.
+3. **Fetch and extract per source.** `WebFetch` each candidate source; extract the specific claims it asserts, each bound to its source URL and the quoted or paraphrased passage that carries it. When a required source is paywalled, login-gated, purchase-only, or otherwise inaccessible after the `WebFetch` attempt, do NOT silently substitute a lower-trust accessible source — STOP and request the full source content from the operator through the structured-inquiry channel per `rules/source-accessibility.md` (trust outranks reachability); a claim left resting on an unreachable trusted source is reported at LOW confidence with the gap named, never papered over. Record the source-trust decision (which source, its trust tier, whether the trusted source was reachable, why a substitute was used) in the disclosure ledger per `rules/disclosure-ledger.md`.
+4. **Adversarially verify each claim against two or more independent sources.** For every extracted claim, seek at least two independent sources that confirm or contradict it. Sources sharing a single upstream origin do not count as independent. Contradictions are surfaced, never silently resolved in favor of one side.
+5. **Synthesize a cited report with confidence levels.** Assemble the verified claims into a report. Each claim carries its sources, a confidence level from the closed three-tier scale below, and an open-questions list naming what the evidence did not settle.
+
+**Confidence scale (closed, three-tier):**
+
+- **HIGH** — confirmed by two or more independent sources.
+- **MEDIUM** — one strong source plus weak corroboration.
+- **LOW** — single source, or contested across sources.
+
+## Return Contract
+
+A cited research report with four required elements:
+
+- **Claims** — each stated definitively, with the sub-question it answers.
+- **Sources** — per claim, the independent source URLs and the passages that carry the claim.
+- **Confidence** — per claim, HIGH / MEDIUM / LOW per the Step 5 scale, with the reason.
+- **Open questions** — what the evidence did not settle, and which sub-question remains unanswered.
+
+A claim without sources, or a single-source claim presented as HIGH confidence, is non-conformant.
+
+## Foundational Stanzas
+
+The four standing surfaces every invocation inherits.
+
+### Refusal & Escalation
+
+REFUSE any request that asks the skill to act outside its research mission — code generation, plan-suite authoring, documentation production, or asserting an unsourced answer as fact. 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; free-form prose as primary input is forbidden). When a research question is underspecified, STOP and surface the clarifying choices through the same channel before fanning out.
+
+### Output Surface
+
+The skill's primary output is the cited research report (markdown), written to STDOUT for direct invocation. When the operator requests a durable artifact, the report lands at the host's research-evidence location per `rules/host-discovery.md` — never at a global-ecosystem location, never inside a downstream project's `.apothem/plans/` from this skill's context. Intermediate source dumps and extraction scratch are session-local and released after synthesis.
+
+### File-Authoring Contract
+
+When the skill emits a NEW file, the file routes through `scripts/inject-header.py` so the canonical `SPDX-License-Identifier` `MIT` header per `src/apothem/schemas/authorship-header.txt` is injected at the head; the injector is idempotent and detects the filetype variant automatically. Exempt classes — LICENSE, JSON configuration files, lockfiles, generated assets, vendored trees, ephemera, `.keep` markers, binary files — are enumerated at `src/apothem/schemas/header-exceptions.txt`.
+
+### 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 host is silent, it routes 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, and NEVER fabricate a source — an unverifiable claim is reported at LOW confidence with the gap named, never papered over with an invented citation.
+
+## Recommended Next Step
+
+**Invoke the skill with the research question as its argument** to decompose, fan out, verify, and synthesize. When the question is underspecified, answer the surfaced clarifying choices first so the fan-out targets a well-scoped question.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every multi-source research engagement's decompose → fan-out → fetch → verify → synthesize workflow. ● Every cited report's claim / source / confidence / open-question shape. ● Every parallel source-discovery fan-out via the Research Team pattern.
+- **Satisfies →** ● `CLAUDE.md` Source Layout row "multi-source-research" (skills/ class). ● The research cohort mission (fan-out, fetch, adversarially verify, synthesize a cited report).
+- **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 WebSearch / WebFetch / Agent tool surfaces (the skill fans out and fetches through them). ● The structured-inquiry channel for underspecified questions.
+- **Cross-bound with ↔** ↔ `rules/agent-orchestration.md` (the Research Team fan-out pattern Step 2 dispatches). ↔ `rules/interactive-questions.md` (the structured-inquiry channel for ambiguity). ↔ `skills/ecosystem-audit/SKILL.md` + `skills/plan-suite/SKILL.md` (sibling skills under the same registry section).

package/src/apothem/skills/plan-suite/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: "plan-suite"
+version: "0.1.0"
+updated: "2026-06-10"
+description: "Master Plan Suite template container — matched when the work is structured plan generation from authored prose, phase-by-phase decomposition of a complex multi-step engagement, plan-suite refinement, forensic plan review, closed-loop plan audit/remediation, architectural design, phase execution against quality gates, read-only progress reporting, or decision-preserving amendment; consumed by the /plan pipeline stages (spec, generate, review, design, audit, execute, status, amend). Houses master_template.md — the canonical specification defining plan-suite structure, the mandate catalog (TM-1–28), the core-principle catalog (CP-1–27), and the Technical Co-Founder Framework. Not directly user-invocable: the /plan stages resolve the template by path, cold-load it on a context-empty invocation, and refuse to regenerate it from memory if it is missing. Not a codegen tool, not a research pipeline, not a documentation generator, not a registry, and not stateful across sessions."
+archetype: "workflow-template"
+userInvocable: false
+disable-model-invocation: true
+allowed-tools: "Read"
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+## Purpose
+
+> **Structural Note:** This skill is a *template container*, not a procedural skill. It deliberately omits the standard SKILL.md Procedure / Detection-Signal structure because it houses a reference template rather than encoding a reusable technique. The `/plan` pipeline stages invoke it by reading its template file directly — not by following a procedure. The deviation from standard skill structure is intentional.
+
+Houses the Master Plan Suite Template — the canonical specification referenced by all `/plan` pipeline commands (`/plan-spec`, `/plan-generate`, `/plan-review`, `/plan-design`, `/plan-audit`, `/plan-execute`, `/plan-status`, `/plan-amend`).
+
+## Contents
+
+- `master_template.md` — the full template defining plan-suite structure, the mandate catalog (TM-1–28), the core-principle catalog (CP-1–27), and the Technical Co-Founder Framework.
+
+## Auto-Load Contract
+
+When any `/plan-<stage>` command is invoked **cold** — without its predecessor stages' context explicitly loaded into the session — the consuming stage MUST resolve this skill before executing, so the full pipeline context loads uniformly and no stage assumes manually-preloaded state.
+
+**Cold-invocation trigger.** A `/plan-<stage>` invocation is cold when the session carries none of: a resolved `_spec/spec.md`, a loaded plan suite (PREAMBLE.md / MASTER-PLAN.md / PROGRESS.md), or a prior `/plan-<stage>` turn in the same session. On a cold invocation the stage reads this skill first; on a warm invocation (predecessor context already loaded) the read is a no-op refresh.
+
+**Deterministic full-pipeline load order.** Resolving this skill surfaces the pipeline in one fixed order — the same cold invocation always yields the same load:
+
+1. `/plan-spec` — prose → `_spec/spec.md` (+ Handoff Manifest)
+2. `/plan-generate` — `_spec/spec.md` → Master Plan Suite
+3. `/plan-review` — forensic audit + scorecards
+4. `/plan-design` — architecture artifact (architecture-bearing suites only)
+5. `/plan-audit` — closed-loop remediation to a zero-finding gate
+6. `/plan-execute` — phase execution against quality gates
+7. `/plan-status` — read-only progress report
+8. `/plan-amend` — amend an existing suite, re-deriving only affected artifacts
+
+Each stage's template anchor (its Step-0 consumption point in the Invoking Surfaces table below) resolves against this skill's `master_template.md` by path. A cold stage that cannot resolve this skill STOPs per the Resolution & Recovery clause instead of proceeding on assumed context.
+
+## Non-Goals
+
+This skill is a template container with a deliberately narrow surface. It is NOT:
+
+- **Not a one-shot codegen tool.** The template defines plan structure; it does not generate code, scaffold projects, or emit codebase artifacts directly. Codebase emission is the consuming `/plan-execute` stage's responsibility, governed by the host's discovered conventions.
+- **Not a research synthesis pipeline.** The template consumes authored prose at `_spec/spec.md`; it does not gather, summarize, or triangulate external sources. Prose elicitation and refinement is the upstream `/plan-spec` stage's responsibility.
+- **Not a documentation generator.** Plan-suite artifacts (PREAMBLE.md, MASTER-PLAN.md, PROGRESS.md, PLAN-NOTES.md, per-phase PHASE.md / REPORT.md) are working documents driving execution; they are not user-facing documentation. User-facing docs land at `site/content/docs/`, `README.md`, and the host's documentation surfaces.
+- **Not a registry.** The template path is declared in the `/plan` pipeline and resolved path-based — no auto-discovery, no fallback registry, no plug-in-style extension.
+- **Not stateful across sessions.** The skill carries no runtime state; each `/plan` stage invocation re-reads the template afresh, and durable plan-suite state lives in the per-suite folder under `<project-root>/.apothem/plans/{suite}/`.
+
+## Invoking Surfaces
+
+The eight `/plan` pipeline stages consume this skill's template by direct path resolution:
+
+| Command | Consumption point | What the command reads |
+|---------|-------------------|------------------------|
+| `/plan-spec` | Step 0 (template anchor) | TM-1 / TM-7 / TM-10 / TM-11 mandates governing prose elicitation |
+| `/plan-generate` | Step 0 (template anchor) | Full TM-N / CP-N catalog + plan-suite skeleton (PREAMBLE / MASTER-PLAN / PROGRESS / PLAN-NOTES / per-phase PHASE.md) |
+| `/plan-review` | Step 0 (template anchor) | TM-N / CP-N IDs for forensic-audit cross-references; scorecard rubric |
+| `/plan-design` | Step 0 (template anchor) | Architecture-bearing TM-N / CP-N mandates governing the six-phase architectural-design transformation (sits between `/plan-review` and `/plan-execute`) |
+| `/plan-audit` | Step 0 (template anchor) | TM-19 orchestration, zero-finding gate, `_outputs/`, and `*-maintenance` routing |
+| `/plan-execute` | Step 0 (template anchor) | Verification-section + Phase Output Registry + Resumption Contract conventions |
+| `/plan-status` | Step 0 (template anchor) | Phase Tracker + Phase Output Registry shape (read-only) |
+| `/plan-amend` | Step 0 (template anchor) | TM-N / CP-N IDs governing decision-preserving amendment + the plan-suite artifact set it re-derives |
+
+No agent invokes the skill directly; the `/plan` pipeline commands are the canonical consumption surface.
+
+## Foundational Stanzas
+
+The four standing surfaces per the canonical project voice at `AGENTS.md` plus the active harness mirror, adapted to this skill's passive template-container role so consuming `/plan` pipeline stages inherit a coherent posture on template resolution.
+
+### Refusal & Escalation
+
+REFUSE any consumer request that asks the skill to act outside its template-container mission — generation, edits, research, codegen, fixes. Refusal is explicit: name what was refused, name the mission boundary crossed, and route the consumer back to the appropriate `/plan` stage via the structured-inquiry channel per `rules/interactive-questions.md` (canonical channel; three-segment option annotation; free-form prose as primary input is forbidden). When the template file is missing, malformed, or unreachable, the skill STOPs and surfaces the recovery options in the Resolution & Recovery section below — it does NOT regenerate the template from training-time memory or scaffold a partial replacement.
+
+### Output Surface
+
+The skill emits **no artifacts of its own**; it is a passive template read by consuming commands. Plan-suite artifacts that the consumers emit while resolving this template land at `<project-root>/.apothem/plans/{suite}/` per the suite-locality invariant at `rules/context-management.md` §2.6.1 — gitignored per the canonical `.gitignore` snippet, lifecycle draft → in-progress → converged → abandoned / superseded. NEVER write a plan-suite artifact outside the suite folder, NEVER write to `<project-root>/.apothem/plans/` from a downstream-project context, and NEVER write to any global-ecosystem location. The downstream-project lightweight plan-write surface is `/plan-spec --quick` per D3 — a single `<YYYY-MM-DD>--<kebab-slug>.md` file at the resolved project's `.apothem/plans/` directory. Codebase artifacts that consuming commands emit during plan execution go to their domain-natural locations under the host project per `rules/host-discovery.md`; per `rules/operational-mandates.md` CM-7, codebase artifacts contain ZERO plan-internal references — natural domain language only.
+
+### File-Authoring Contract
+
+The skill is `allowed-tools: "Read"` — it authors no files directly. The contract applies to consuming `/plan` pipeline stages: every NEW codebase file the consumer creates routes through `scripts/inject-header.{sh,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`. Plan-suite artifacts (PREAMBLE.md, MASTER-PLAN.md, PROGRESS.md, PLAN-NOTES.md, per-phase PHASE.md / REPORT.md) are banner-exempt under the `.apothem/plans/**` exception class. The header-inject-guard hook at `hooks/messages/pretooluse-{write,edit}-header-guard.md` enforces the contract at every Write / Edit invocation made by the consuming command.
+
+### Structured Inquiry on Ambiguity
+
+When a consuming `/plan` stage reaches a decision in any of the seven authoritative-data categories per `rules/authority-inquiry.md` — identity (suite owner, contributors), scope direction (which subtree, which target), preference (CI provider, branch strategy, formatter, linter, test framework), security (deny rules, secret rotation, allowed shells, allowed network egress), naming of public surfaces (suite name, phase identifiers), infrastructure endpoints, version pins (template version, downstream-tooling pins) — and the host is silent, the consumer routes 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. Required-category inquiries (identity, scope direction, security posture, naming of public surfaces) block emission until answered; optional inquiries fall back to the recommended option and record the fallback in PLAN-NOTES.md as a finding. **Per-file destructive-op floor.** Every delete / rename / move / overwrite-without-retention / revert-uncommitted operation the consumer performs against an existing plan-suite artifact routes through the structured-inquiry channel on a per-file basis per `rules/interactive-questions.md` §6 — one invocation per file, every time, no `multiSelect` batching across files, every option's `default-pointer:` carrying the verbatim `no-default: user decision required` marker.
+
+## Conformity Posture
+
+The three-element conformity discipline applies to **consumers** of this template — every `/plan` stage invocation that resolves the template inherits the obligations below — and is reproduced here so consumers reach the discipline at the same surface they reach the template.
+
+**Discover-don't-assume preamble (M1).** Before any `/plan` stage invocation populates a plan-suite artifact from this template, the consuming command walks the host's ratified source-of-truth files for the host's planning conventions per `rules/host-discovery.md` — phase-folder naming, sub-phase-folder naming, report-filename convention, frontmatter requirements on per-phase artifacts, host-discovered TM-N / CP-N analogs. Honor discoveries; never silently install a planning convention where the host has its own.
+
+**Authority inquiry surface (M5).** Per the Structured Inquiry on Ambiguity stanza above; this anchor binds the M5 discipline to the seven-category inquiry catalog at `rules/authority-inquiry.md` §10.
+
+**Pre-emission self-check (M4).** Every plan-suite artifact emitted from this template — `PREAMBLE.md`, `MASTER-PLAN.md`, `PROGRESS.md`, `PLAN-NOTES.md`, every `phases/NN-topic/PHASE.md`, every `phases/NN-topic/REPORT.md` — passes the fifteen-bar pre-emission gate per `rules/pre-emission-gate.md` before the consuming `/plan` stage considers the artifact complete. The gate's attestation lands in the artifact's working trace (specifically, the corresponding REPORT.md's "Pre-Emission Gate Attestation" section per the established reporting convention). Mechanical-fraction bars run via the per-bar matchers at `conformity/*-grep.py`; reasoned bars are evaluated inline by the consuming command.
+
+## Resolution & Recovery
+
+Not directly invocable. The `/plan` pipeline stages resolve this template via the path declared in `CLAUDE.md` Source Layout (currently `skills/plan-suite/master_template.md`). Resolution is path-based, not registry-based — there is no fallback registry and no auto-discovery; the path must match exactly.
+
+**Fallback handling.** If the template file is missing, malformed (corrupted YAML/markdown that prevents parsing of the TM-N / CP-N sections), or unreachable: STOP and inform the user. Do NOT regenerate the template from training-time memory or scaffold a partial replacement — `/plan` pipeline stages depend on the canonical TM-N / CP-N IDs, and any divergence silently corrupts every cross-reference downstream. Recovery options surfaced via the structured-inquiry channel: (a) re-clone or re-install the apothem ecosystem from version control (Recommended); (b) restore the template file from a backup; (c) point commands at a known-good template via an explicit override path.
+
+**Version compatibility.** Commands declare `Requires template v0.1.0+`. Bump the template's version field when changes alter TM-N / CP-N semantics; consumers refuse to operate against an older major version than they expect.
+
+## Recommended Next Step
+
+Invoke `/plan-generate` to consume this skill's `master_template.md` and materialize a plan suite from the authored prose at `_spec/spec.md`. `/plan-generate` is the canonical downstream consumer that reads the full TM-N / CP-N catalog and the plan-suite skeleton from this template.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every `/plan` stage's resolution of the master template at `skills/plan-suite/master_template.md`. ● Every TM-N / CP-N cross-reference resolution across the eight `/plan` pipeline stages. ● Every plan-suite emission's structural conformity (the template is the canonical schema). ◐ The version-compatibility gate (`Requires template v0.1.0+`).
+- **Satisfies →** ● `CLAUDE.md` Source Layout row "plan-suite". ● `CLAUDE.md` Project Purpose (the eight `/plan` pipeline stages consume this skill's template).
+- **Established by ↑** ● `CLAUDE.md` Source Layout. ● `CLAUDE.md` Project Purpose (the path declaration `skills/plan-suite/master_template.md`). ● `CLAUDE.md` Source Layout (skills/ class declaration with the folder-with-`SKILL.md` convention).
+- **Gated by ←** ● The harness's Read tool surface (commands resolve the template by reading the canonical path). ● The presence of the template file at the canonical path (path-based resolution per the Resolution & Recovery clause).
+- **Cross-bound with ↔** ↔ `commands/plan-spec.md` + `commands/plan-generate.md` + `commands/plan-review.md` + `commands/plan-audit.md` + `commands/plan-design.md` + `commands/plan-execute.md` + `commands/plan-status.md` + `commands/plan-amend.md` (the eight consumer commands). ↔ `skills/ecosystem-audit/SKILL.md` (sibling skill under the same registry section).