@ahmed-g-gad/apothem 0.1.1

package/src/apothem/templates/agents-md-template.md

@@ -0,0 +1,80 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Agent-Facing Folder Guidance Template
+
+Per the root-only convention at
+[`../rules/agents-md-convention.md`](../rules/agents-md-convention.md), the
+repository carries a **single agent-facing canon** at the root `AGENTS.md`, and
+per-folder operating guidance lives in each folder's `README.md` — which serves
+both the human reader and the agent reader. **The convention does NOT require a
+separate per-folder `AGENTS.md` companion beside each `README.md`:** the folder
+`README.md` is the agent-facing surface, so authoring a standalone
+`<folder>/AGENTS.md` is optional, not expected.
+
+Use this template in one of two ways:
+
+- **Preferred — author a folder README's agent-facing section.** Adapt the
+  fenced skeleton below into a section of the folder's `README.md` (a heading
+  such as `## For agents` followed by the same body) so one file orients both
+  readers.
+- **Rare — author a standalone companion.** Where a folder genuinely needs a
+  standalone agent companion beyond its README, copy the skeleton into
+  `<folder>/AGENTS.md`, keep the frontmatter and the single-line SPDX license
+  header, replace every `<PLACEHOLDER>`, and delete the guidance comments.
+
+## What to fill, and what to leave out
+
+- **Fill** the folder's purpose, the load-bearing artifacts an agent touches,
+  the local conventions an agent MUST respect, the safe-operation guidance,
+  and the upstream/downstream edges.
+- **Leave out** volatile inventory counts (e.g., "12 files"); they go stale.
+  Describe the operating contract, which is stable.
+- **Stay agnostic.** Privilege no single harness, model, or tool; pre-set no
+  model or effort preference. A folder describing one harness adapter names it
+  by its catalog slug, never by a privileging brand phrase.
+- **Stay canon-coherent.** Extend the root `AGENTS.md` canon; contradict none
+  of its shared claims (plans locality, authorship headers, ambiguity
+  handling, naming, release freshness, human-only authorship, plain-language).
+
+## Skeleton
+
+```markdown
+---
+name: <FolderName>
+version: <semver, e.g. 0.1.0>
+updated: <YYYY-MM-DD>
+description: Agent-facing operating guide for the <folder/path> folder.
+scope: folder
+portability: repo-local
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# <folder/path> — Agent Guide
+
+> **Role.** <One sentence: what this folder is for and what depends on it.>
+
+## What lives here
+
+<The load-bearing artifacts an agent touches and how they are organized —
+the artifact CLASSES and their roles, not a file-by-file count. One short
+paragraph or a compact list.>
+
+## Conventions an agent must respect
+
+<The concrete invariants for acting in this folder. Examples to adapt:
+file-header form, frontmatter contract, naming scheme, where this folder's
+artifacts register (an index/README/registry), gate requirements that run on
+a change here, and any mutation guard.>
+
+## Operating in this folder
+
+<How to add, modify, or remove an artifact here safely, and which checks
+verify the change. State the command(s) that validate a change to this
+folder (lint, type-check, the relevant conformity matcher, tests).>
+
+## Relationships
+
+- **Consumes:** <upstream folders/artifacts this folder depends on.>
+- **Produces:** <downstream consumers of this folder's artifacts.>
+```

package/src/apothem/templates/consideration-log.md

@@ -0,0 +1,39 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Consideration Log Template
+
+The Consideration Log is the deliverable of Discipline D1 (Meticulous Consideration) inside `src/apothem/commands/plan-spec.md`. Every transformation choice the Forge makes traces back to one row in this log; an empty / skeletal / sham log fires the D1 ◇ Gate at P0 severity and blocks emission.
+
+## Purpose
+
+Capture every consideration item surfaced during the prose-to-spec transformation — the directives, intentions, rationales, adjacent-domain scans, second-order consequences, and contradictions that the double-read + triple-extract pass produced. The log is the primary evidence that Discipline D1 (double-read · triple-extract · adjacent-domain scan · second-order-consequence enumeration · contradiction surfacing · persona/register/voice inference) executed in full.
+
+## Schema
+
+| Column | Type | Required | Content |
+| ------ | ---- | -------- | ------- |
+| `item-id` | string | Yes | Stable identifier of the form `CL-NNN` (zero-padded three-digit ordinal). Used as the join key from the Potency Map (paired potent form), the Preservation Audit (preservation verdict per level), and any inline `[Expertise amendment — axis: X — rationale: ...]` markers in the emitted spec. |
+| `source` | string | Yes | The verbatim prose excerpt that produced this consideration. Includes the source-file reference (`path:line` or `path:lines a-b`). Verbatim-quoted; no paraphrase. |
+| `classification` | enum | Yes | One of `preserved-verbatim` (clause woven into the spec at an analogous locus without rewriting) · `amended-with-rationale` (clause woven with a documented amendment) · `added-with-rationale` (no source clause; the consideration extends the prose with a rationale traceable to an adjacent-domain scan or second-order-consequence enumeration). |
+| `disposition` | string | Yes | The transformation choice: where the consideration lands in the spec (section anchor) and how it manifests (e.g., as a requirement, a constraint, a Sprint Goal element, an annotation marker). |
+
+## Sample row
+
+```markdown
+| item-id | source | classification | disposition |
+|---------|--------|----------------|-------------|
+| CL-001  | "Reliability above all" — `notes/migration.md:14` | preserved-verbatim | Becomes the Sprint Goal's load-bearing clause at `_spec/spec.md` §2.1; paired in Potency Map row PM-001 with the SLO `99.95% read availability over a 28-day rolling window`. |
+| CL-014  | "Probably should think about caching" — `notes/migration.md:62` | amended-with-rationale | Tension surfaced via the structured-inquiry channel at G3; operator selected `Add caching as a deferred capability` over `Add caching as a sprint commitment`; lands at `_spec/spec.md` §3.4 with the deferral rationale captured. |
+| CL-027  | (no source — adjacent-domain scan) | added-with-rationale | Adjacent-domain scan on `database` surfaced the connection-pool-exhaustion failure mode the prose did not name; lands at `_spec/spec.md` §5.2 Failure Modes; rationale points to the Postgres `max_connections` operational pattern. |
+```
+
+## Gate semantics
+
+The D1 ◇ Gate fires at G0 (Consideration-Log-Complete standing). An empty log, a log carrying fewer rows than there are distinctive prose phrases, or a log whose `classification` is uniformly `preserved-verbatim` (signal that no thought was applied beyond mechanical transcription) all fail the gate. P0 severity; blocks emission.
+
+## Cross-references
+
+- Discipline D1 Meticulous Consideration definition: `src/apothem/commands/plan-spec.md` §Workflow Phase 2.
+- Pairing into the Potency Map: `src/apothem/templates/potency-map.md`.
+- Preservation Audit's verdict per row: `src/apothem/templates/preservation-audit.md` (the Preservation Audit's `clause-id` shares the namespace with this log's `item-id` for traceability).
+- Question-Resolution Audit's row when a consideration surfaced via the structured-inquiry channel: `src/apothem/templates/question-resolution-audit.md`.

package/src/apothem/templates/expertise-gap-log.md

@@ -0,0 +1,56 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Expertise-Gap Log Template
+
+The Expertise-Gap Log is the deliverable of Discipline D4 (Extensive Expertise) inside `src/apothem/commands/plan-spec.md`. Every transformation in the prose-to-spec run records which of the seven axs of breadth applied, which were not applicable (with rationale), and which surfaced an expertise-envelope limit needing routing.
+
+## Purpose
+
+Realize the operational form of D4: every transformation explicitly attests its expertise posture. Inline `**[Expertise amendment — axis: X — rationale: ...]**` markers in the emitted spec point back to rows in this log. Under-applied axs raise the D4 ◇ Gate at `**P1**` severity and block emission until either the axis applies (with a recorded amendment) or the row records `not-applicable-with-rationale` or `expertise-envelope-limited` with a downstream routing target.
+
+## The seven axs (canonical)
+
+| Axis | Scope |
+| ---- | ----- |
+| Domain | Direct subject-matter expertise on what the prose is about (e.g., database internals, payment systems, ML training). |
+| Adjacent-domain | Expertise on neighboring domains whose patterns, failure modes, or vocabularies inform the prose's domain by analogy. |
+| Meta-engineering | The discipline-of-engineering itself: SOLID, clean architecture, dependency direction, testability, reversibility. |
+| Operational | Runtime behavior: deployment, observability, on-call rotations, incident response, runbooks. |
+| Process | The work-process surface: sprint cadence, code review, RFC writing, change management, retrospection. |
+| Scholarly-technical-literature | Citations to peer-reviewed papers, RFCs, industry case studies, formal specifications. |
+| Second-order-systems-thinking | Implications a step removed: what the prose's requirements imply for downstream artifacts the prose does not name. |
+
+## Schema
+
+| Column | Type | Required | Content |
+| ------ | ---- | -------- | ------- |
+| `axis` | enum | Yes | One of the seven canonical axs above. |
+| `disposition` | enum | Yes | `applied` (axis amended the spec; one or more inline amendment markers point here) · `not-applicable-with-rationale` (axis is genuinely orthogonal to the prose's domain; rationale captures why) · `expertise-envelope-limited` (axis would apply but the Forge's expertise envelope is insufficient; routing target captures where the gap closes). |
+| `attestation-locus` | string | Conditional | Section anchor in `_spec/spec.md` where the inline amendment marker lands; required when `disposition: applied`. Multiple loci are admissible — list them comma-separated when the axis amends more than one section. |
+| `rationale` | string | Conditional | One-sentence justification; required when `disposition: not-applicable-with-rationale` or `expertise-envelope-limited`. For `expertise-envelope-limited`, the rationale also names the expertise-gap closure target (operator clarification, downstream specialist consultation, or deferred routing). |
+| `routing-target` | string | Conditional | When `disposition: expertise-envelope-limited`, names the downstream surface that closes the gap — e.g., `<USER-CONFIRM:kind=...>` placeholder, expert-consultation deferral, downstream-command consumption. |
+
+## Sample row
+
+```markdown
+| axis | disposition | attestation-locus | rationale | routing-target |
+|------|-------------|-------------------|-----------|----------------|
+| Domain | applied | §2.1 Sprint Goal, §3.4 SLOs | — | — |
+| Adjacent-domain | applied | §3.5 Failure modes (analog: Postgres connection-pool exhaustion) | — | — |
+| Meta-engineering | applied | §4.2 Reversibility paths (closed-set enumeration), §5.1 Composition root | — | — |
+| Operational | applied | §3.4 SLO measurement window, §6.1 Runbook pointer | — | — |
+| Process | applied | §7 Sprint cadence | — | — |
+| Scholarly-technical-literature | not-applicable-with-rationale | — | The prose covers an internal migration with no peer-reviewed scholarship to cite; informal industry references already inline at §3.5 are sufficient. | — |
+| Second-order-systems-thinking | applied | §5.2 Downstream consequences (table) | — | — |
+```
+
+## Gate semantics
+
+The D4 ◇ Gate fires at G4 (Pre-emission). All seven axs appear in the log. Any axis with `disposition: applied` carries a non-empty `attestation-locus`; any with `not-applicable-with-rationale` or `expertise-envelope-limited` carries a non-empty `rationale`. A row with `applied` but missing `attestation-locus`, or with `not-applicable-with-rationale` but missing `rationale`, is a gate failure (`**P1**` block).
+
+When more than two axs carry `disposition: not-applicable-with-rationale`, the gate fires a soft warning: the prose may be narrowly scoped, OR the Forge may have under-applied breadth. The warning surfaces in the emitted spec's preamble and routes to the operator's review on next iteration.
+
+## Cross-references
+
+- Discipline D4 Extensive Expertise definition: `src/apothem/commands/plan-spec.md` §Workflow Phase 5.
+- Inline amendment markers: appear in the emitted `_spec/spec.md` as `**[Expertise amendment — axis: X — rationale: ...]**` annotations whose `axis` field joins to a row in this log.

package/src/apothem/templates/master-index-template.md

@@ -0,0 +1,93 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# MASTER-INDEX — `[SUITE_NAME]`
+
+> **Purpose.** Suite-root index for **medium+ tier** plan suites (≥50 phases or ≥100 spec sections / constraints per `src/apothem/rules/canonical-layout.md` §7 Three-Tier Scalability). The index is the queryable surface a fresh session, a `/plan-review` cycle, or a sub-suite-federation parent reads to navigate the suite without scanning every PHASE.md or spec section linearly.
+>
+> **When required.** Mandatory at medium and large tier; absent at small tier (in-line refs in `PLAN-NOTES.md` substitute). A small-tier suite that grows past the 50-phase or 100-spec boundary materializes this index in the same change-set per the §7.5 tier-transition rule.
+>
+> **Authoring cadence.** Initial authorship at the medium-tier transition; per-phase write-back appends a row to §2 on phase completion; spec-section evolution edits §1; decision ratification appends a row to §4. The index is always current with the suite — staleness is a structural failure on the orphan-output axis.
+
+---
+
+## 1. Spec-Section Anchor Table
+
+> **Schema.** Every section of `_spec/spec.md` (and any sibling specifications under `_spec/supporting/`) emits one row. The `Stable ID` column carries the `R-NNNN` zero-padded sequential per the §7.2 stable-ID convention (cross-references survive section renames). The `Phase coverage` column lists every `P-NN` mapped to the requirement.
+
+| Stable ID | Spec section | Title / one-line summary | Phase coverage | Notes |
+|---|---|---|---|---|
+| `R-0001` | `_spec/spec.md §1` | Mission statement | `P-01`, `P-20` | — |
+| `R-0002` | `_spec/spec.md §2.1` | Token-usage optimization directive | `P-04` | Ratified at Q-014 |
+| `R-NNNN` | `_spec/spec.md §M.N` | `[one-line summary]` | `P-NN`, `P-NN` | `[notes]` |
+
+---
+
+## 2. Phase Anchor Table
+
+> **Schema.** Every phase folder under `phases/` emits one row. Sub-phases (`phases/NN-topic/NNL-subtopic/`) emit additional rows nested via the `Stable ID` (`P-NN.L`). The `Spec coverage` column lists every `R-NNNN` the phase satisfies.
+
+| Stable ID | Phase folder | Title / scope | Spec coverage | Status |
+|---|---|---|---|---|
+| `P-01` | `phases/01-kebab-topic/` | `[scope summary]` | `R-0001`, `R-0007` | ✅ Complete |
+| `P-02` | `phases/02-kebab-topic/` | `[scope summary]` | `R-0003` | ⏳ Pending |
+| `P-NN` | `phases/NN-kebab-topic/` | `[scope summary]` | `R-NNNN`, `R-NNNN` | `[status]` |
+| `P-NN.A` | `phases/NN-topic/NNA-subtopic/` | `[sub-phase scope]` | `R-NNNN` | `[status]` |
+
+---
+
+## 3. Constraint Anchor Table
+
+> **Schema.** Every named constraint (architectural invariant, security floor, regulatory boundary, performance budget, compliance clause) emits one row. Constraints sit alongside requirements; the table separates them so binding analysis can audit each class independently.
+
+| Stable ID | Constraint name | Source citation | Affected phases | Notes |
+|---|---|---|---|---|
+| `C-01` | `[constraint name]` | `_spec/spec.md §M.N` or `src/apothem/rules/<rule>.md §X` | `P-NN`, `P-NN` | `[mitigation / verification surface]` |
+
+---
+
+## 4. Decision Anchor Table
+
+> **Schema.** Every numbered decision (D-1, D-2, …) the suite ratifies emits one row. Decisions are the resolved-structured inquiry surface plus any agent-driven architectural decisions recorded with operator approval. Cross-references in PLAN-NOTES.md and PHASE.md files cite the `Stable ID` so renames preserve the link.
+
+| Stable ID | Decision title | Resolution | Source | Affected phases |
+|---|---|---|---|---|
+| `D-1` | `[decision name]` | `[one-sentence resolution]` | Q-NNN in `PLAN-NOTES.md` Wave N | `P-NN`, `P-NN` |
+
+---
+
+## 5. Cross-Suite Federation (Large Tier Only)
+
+> **Schema.** Large-tier suites decompose into multiple child suites with parent-child relationship per `src/apothem/rules/canonical-layout.md` §7.1 Decomposition. The parent's MASTER-INDEX.md carries this section listing every child suite plus its own MASTER-INDEX.md path. Child suites omit this section (they are small or medium per §7.1).
+
+| Child suite | Path | Tier | Phase count | Spec count | MASTER-INDEX path | Last rollup |
+|---|---|---|---|---|---|---|
+| `[child-suite-name]` | `<project-root>/.apothem/plans/[child-suite]/` | `medium` | NN | NNN | `[child-suite]/MASTER-INDEX.md` | `[ISO-8601 date]` |
+
+**Federation invariants:**
+
+- Every `R-NNNN` requirement in the parent index resolves to at least one child suite's phase coverage.
+- Every cross-child reference uses the parent's stable ID space (no child-local IDs leak into parent navigation).
+- Child suite tier transitions (small ↔ medium) propagate to this section in the same change-set.
+
+---
+
+## 6. Validation Cadence
+
+> **Schema.** The medium and large tiers run `/plan-review` incrementally rather than full-suite-each-pass. This section records the rolling validation state — which phase groups have been audited in the current cycle, which spec sections have been re-validated, when the next sampled-rollup is due.
+
+| Audit class | Last cycle | Coverage this cycle | Next due |
+|---|---|---|---|
+| Per-phase verification | `[ISO-8601 date]` | `P-NN..P-NN` | `[ISO-8601 date]` |
+| Phase-rollup verification (groups of 5-20) | `[ISO-8601 date]` | `[group ID]` | `[ISO-8601 date]` |
+| Spec-section sampled audit | `[ISO-8601 date]` | `R-NNNN..R-NNNN` | `[ISO-8601 date]` |
+| Suite-rollup (large only) | `[ISO-8601 date]` | full | `[ISO-8601 date]` |
+
+---
+
+## 7. Bindings (§0.j five-direction)
+
+- **Drives →** Every fresh-session navigation of this suite (the index is the first read after PROGRESS.md per `src/apothem/rules/context-management.md` §6 Blind Bootstrap at medium+ tier); every `/plan-review` cycle's audit-coverage decision (the §6 cadence table records what was last audited and what is due); every cross-suite federation parent's child-suite enumeration at large tier.
+- **Satisfies →** `src/apothem/rules/canonical-layout.md` §7 Three-Tier Scalability (medium+ tier indexing requirement); the §7.2 drift-prevention `MASTER-INDEX.md` mechanism; the §7.5 tier-transition emission contract.
+- **Established by ↑** `_spec/spec.md` §8 (D7 source — Q-011 three-tier ratification); the medium-tier transition decision recorded in PLAN-NOTES.md when the suite crosses the 50-phase or 100-spec boundary.
+- **Gated by ←** Tier classification (small-tier suites omit this index); operator's borderline-tier structured inquiry resolution per §7.3 of the canonical-layout companion when phase count sits within ±10% of a boundary.
+- **Cross-bound with ↔** `src/apothem/templates/trace-matrix-template.md` (sibling drift-prevention surface; the trace matrix's row × column shape and this index's anchor tables together close the bidirectional traceability invariant); `PROGRESS.md` (per-phase status mirrors the §2 Phase Anchor Table's Status column); `_spec/spec.md` (every §1 row maps back to a spec section); `PLAN-NOTES.md` (every §4 row maps back to a Q-NNN resolution); every `phases/NN-kebab-topic/PHASE.md` (every §2 row resolves to a PHASE.md file).

package/src/apothem/templates/potency-map.md

@@ -0,0 +1,53 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Potency Map Template
+
+The Potency Map is the deliverable of Discipline D2 (EXTREME Potency) inside `src/apothem/commands/plan-spec.md`. Every preserved prose element pairs with its potent operational form here; missing pairings raise a `**P1**` block at emission.
+
+## Purpose
+
+Realize the spec's organizing principle: **potency alone is inert archiving; potency is the ceiling, preservation is the floor**. The Forge does not merely retain the user's prose — it pairs every retained element with the operational shape that lets the spec actively drive downstream commands. The Potency Map is the audit surface where each pairing is recorded.
+
+## Pairing dictionary (canonical)
+
+| Preserved prose class | Paired potent operational form |
+| --------------------- | ------------------------------ |
+| Reliability requirement | Service Level Objective (SLO) with measurable threshold + measurement window |
+| Flow / sequence | Mermaid `flowchart` (control flow) · `sequenceDiagram` (interaction) · `stateDiagram-v2` (state machine) |
+| Decision / choice | Annotated structured inquiry option set with the three-segment body (rationale / recommendation / default-pointer) |
+| Ordered execution | Sprint apparatus with Sprint Goal · DoR · DoD · Sprint Review · Retrospective · Velocity Log entry |
+| Cross-reference | Canonical bidirectional binding (Drives → · Satisfies → · Established by ↑ · Gated by ← · Cross-bound with ↔) |
+| Definitive statement | Airtight input-class coverage (closed-set enumeration with explicit-N/A attestation on residue) |
+| Authoritative datum | Inquiry surfacing with `<USER-CONFIRM:kind=...>` placeholder until operator-supplied |
+
+The dictionary is open-extensible: when a prose element does not match any of the seven canonical pair-classes above, the row records the bespoke pairing with a one-sentence rationale.
+
+## Schema
+
+| Column | Type | Required | Content |
+| ------ | ---- | -------- | ------- |
+| `pair-id` | string | Yes | Stable identifier of the form `PM-NNN`. |
+| `preserved-element` | string | Yes | Verbatim prose excerpt + source reference (`path:line` or `path:lines a-b`). |
+| `paired-potent-form` | string | Yes | The operational shape paired to the element. Names the class from the dictionary above (or describes the bespoke pairing) and embeds the concrete artifact (the SLO threshold, the Mermaid block name, the option-set label, etc.). |
+| `pairing-anchor` | string | Yes | The section anchor in `_spec/spec.md` where the paired potent form lands (e.g., `§3.4 SLOs`, `§4.2 Sprint apparatus`). |
+| `transformation-effect` | string | Yes | One sentence describing what the pairing enables downstream — what the operational form lets a downstream command (`/plan-generate`, `/plan-execute`) do that the unpaired prose alone could not. |
+
+## Sample row
+
+```markdown
+| pair-id | preserved-element | paired-potent-form | pairing-anchor | transformation-effect |
+|---------|-------------------|--------------------|----------------|----------------------|
+| PM-001  | "Reliability above all" — `notes/migration.md:14` | SLO: 99.95% read availability over a 28-day rolling window; measurement via the existing latency dashboard's 5xx-rate panel | `§3.4 Service Level Objectives` | Downstream `/plan-execute` can author a quality gate that fails when the rolling 28-day 5xx rate exceeds the SLO budget. |
+| PM-002  | "We probably need to retry transient failures" — `notes/migration.md:31` | Decision option set: Add retry-with-backoff (Recommended) · Add at-least-once delivery · Defer | `§4.1 Reliability options` | The annotated option set lets the operator make the retry-strategy decision via the structured-inquiry channel at G3 with the three-segment body rather than a silent default. |
+| PM-008  | "Migration must be reversible" — `notes/migration.md:48` | Definitive statement: airtight closed-set enumeration of the four reversibility paths (down-migration · feature-flag rollback · blue-green swap · point-in-time-restore); residue explicitly N/A-with-rationale | `§5.1 Reversibility paths` | Downstream `/plan-review` can verify every migration step in the plan suite traces back to one of the four reversibility paths. |
+```
+
+## Gate semantics
+
+A row missing its `paired-potent-form` raises a `**P1**` block at emission. A row whose `paired-potent-form` is the empty string, the string `none`, or the string `TODO` is treated identically. Every preserved-element from the Consideration Log (rows classified `preserved-verbatim` or `amended-with-rationale`) must have a corresponding Potency Map row; missing rows raise the `**P1**` block.
+
+## Cross-references
+
+- Discipline D2 EXTREME Potency definition: `src/apothem/commands/plan-spec.md` §Workflow Phase 3.
+- Source consideration item: `src/apothem/templates/consideration-log.md` (row's `item-id` is the upstream join key).
+- Preservation Audit's verdict for the same clause: `src/apothem/templates/preservation-audit.md`.

package/src/apothem/templates/preservation-audit.md

@@ -0,0 +1,60 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Preservation Audit Template
+
+The Preservation Audit is the deliverable of Discipline D3 (STRICT Preservation) inside `src/apothem/commands/plan-spec.md`. It records the per-clause verdicts at all three preservation levels — Level 1 syntactic · Level 2 semantic · Level 3 tonal — that gate emission of the spec.
+
+## Purpose
+
+Realize the spec's load-bearing principle: **preservation is strict weaving; every prose clause is woven into scaffolding at its structural locus; transformation is additive, not rewriting**. The Preservation Audit is the per-clause record proving this principle held: every distinctive prose phrase verbatim-present (Level 1), every requirement / constraint / directive operationally HONORED (Level 2), every tonal choice preserved at the analogous locus (Level 3).
+
+## The three levels
+
+- **Level 1 — Syntactic.** Every distinctive phrase verbatim, grep-matchable. Reproducible matcher: `rg --no-heading -nF '<phrase>' {suite}/_spec/spec.md`. A single grep-miss is a Level-1 failure (`**P1**` block).
+- **Level 2 — Semantic.** Every requirement / constraint / directive / implicit assumption is HONORED in operational scaffolding (not merely quoted). Quotation without operational enforcement is a Level-2 failure (`**P1**` block).
+- **Level 3 — Tonal.** Bold / italic / ALL-CAPS / repeated intensifiers / slash-alternations / paired adjectives / rhetorical repetition are preserved at the analogous locus. Flattening is a Level-3 failure (`**P2**` escalating to `**P1**` when interpretive weight is materially affected).
+
+## Schema
+
+| Column | Type | Required | Content |
+| ------ | ---- | -------- | ------- |
+| `clause-id` | string | Yes | Stable identifier shared with the Consideration Log's `item-id` namespace (e.g., `CL-001` becomes `clause-id: CL-001` here). |
+| `source-locus` | string | Yes | Path + line reference for the source prose. |
+| `target-locus` | string | Yes | Section anchor in `_spec/spec.md` where the clause is woven. |
+| `l1-verdict` | enum | Yes | `pass` (verbatim grep-match holds) · `fail` (grep-miss; the verbatim phrase is absent at the target locus). |
+| `l1-matcher` | string | Conditional | The `rg` invocation used; required when `l1-verdict: pass` so the verdict is reproducible. |
+| `l2-verdict` | enum | Yes | `pass` (the requirement / constraint / directive is operationally enforced via SLO / option set / sprint apparatus / etc.) · `fail` (the source clause is quoted without operational enforcement). |
+| `l2-enforcement-anchor` | string | Conditional | The Potency Map row (`PM-NNN`) or the section in `_spec/spec.md` where the operational enforcement lives; required when `l2-verdict: pass`. |
+| `l3-verdict` | enum | Yes | `pass` (tonal choice preserved at the analogous locus) · `partial` (`**P2**` — tonal choice partially preserved with no material effect on interpretive weight) · `fail` (`**P1**` — tonal choice flattened with material effect on interpretive weight). |
+| `l3-tonal-marker` | string | Conditional | The specific tonal marker preserved (e.g., `ALL-CAPS PERSISTENTLY`, `bold "must never"`, `paired adjective "airtight + strict"`); required when `l3-verdict: pass` or `partial`. |
+| `notes` | string | No | Free-form remediation notes when any verdict is `fail` or `partial`. |
+
+## Sample row
+
+```markdown
+| clause-id | source-locus | target-locus | l1-verdict | l1-matcher | l2-verdict | l2-enforcement-anchor | l3-verdict | l3-tonal-marker | notes |
+|-----------|--------------|--------------|------------|------------|------------|-----------------------|------------|-----------------|-------|
+| CL-001    | notes/migration.md:14 | §3.4 SLOs | pass | rg --no-heading -nF '"Reliability above all"' _spec/spec.md | pass | PM-001 (SLO 99.95%/28-day) | pass | bold "above all" preserved at §3.4 lead | — |
+| CL-014    | notes/migration.md:62 | §3.4 Reliability options | pass | rg --no-heading -nF '"Probably should think about caching"' _spec/spec.md | pass | PM-002 (decision option set) | pass | hedging "probably" preserved as deferral signal | Surfaced via the structured-inquiry channel at G3; selection captured in Question-Resolution Audit row QR-007. |
+| CL-022    | notes/migration.md:72 | §5.1 Reversibility paths | pass | rg --no-heading -nF '"Migration must be reversible"' _spec/spec.md | pass | PM-008 (definitive closed-set) | pass | imperative "must be" preserved verbatim | — |
+```
+
+## Per-level summary
+
+The Preservation Audit emits a header summary above the per-row table:
+
+```markdown
+| Level | Pass | Partial | Fail | Total |
+|-------|------|---------|------|-------|
+| 1     | 124  | 0       | 0    | 124   |
+| 2     | 47   | 0       | 0    | 47    |
+| 3     | 12   | 0       | 0    | 12    |
+```
+
+The summary is the inspection surface for the four-discipline operational invariant condition (i) + (ii) + (iii). Any non-zero `Fail` count blocks emission until the offending rows resolve.
+
+## Cross-references
+
+- Discipline D3 STRICT Preservation definition: `src/apothem/commands/plan-spec.md` §Workflow Phase 4.
+- Source consideration item: `src/apothem/templates/consideration-log.md` (`item-id` ↔ `clause-id`).
+- Operational enforcement target: `src/apothem/templates/potency-map.md` (`PM-NNN` referenced in `l2-enforcement-anchor`).

package/src/apothem/templates/question-resolution-audit.md

@@ -0,0 +1,52 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Question-Resolution Audit Template
+
+The Question-Resolution Audit is the deliverable of Discipline D5 (Question-Resolution Audit) inside `src/apothem/commands/plan-spec.md` Phase 6. Every structured-inquiry invocation across the six mandatory gate points G0–G5 lands one row here; silent-defaulted rows are forbidden by the D8 anti-pattern set.
+
+## Purpose
+
+Realize the operational audit surface for the canonical-channel obligation of `src/apothem/rules/interactive-questions.md`. Every questionable identified by the ten D1 trigger categories produces a row; every row corresponds to an actual structured inquiry call; every P0/P1-severity row resolves at its gate or carries a `<USER-CONFIRM:kind=...; defer-reason=...; defer-timestamp=...; deferred-by-command=plan-spec/>` placeholder routed downstream via the Handoff Manifest. The audit is the proof that no question was suppressed, no default was silent, no fabrication occurred.
+
+## Schema
+
+| Column | Type | Required | Content |
+| ------ | ---- | -------- | ------- |
+| `question-id` | string | Yes | Stable identifier of the form `QR-NNN`. |
+| `trigger-category` | enum | Yes | One of the ten D1 trigger categories: `authority-datum-absent` · `requirement-ambiguity` · `constraint-under-specification` · `ordering-indeterminacy` · `contradiction` · `option-set-decision` · `implicit-assumption` · `expertise-envelope-limit` · `scope-boundary` · `consequence-acceptance`. |
+| `source` | string | Yes | Verbatim prose excerpt + source reference (`path:line` or `path:lines a-b`). For category `expertise-envelope-limit` rows, the source may be the Expertise-Gap Log row that surfaced the limit. |
+| `question` | string | Yes | The question text emitted via the structured-inquiry channel. One sentence, ending in `?`. |
+| `options` | string | Yes | Pipe-delimited list of option labels presented in the invocation. Implicit `Other` (free-text) is not enumerated; only the canned options. |
+| `selection` | string | Yes | The label the operator selected. When the operator provided free-text via the implicit `Other` channel, the value is the literal `Other: <free-text>` form. |
+| `gate` | enum | Yes | Which gate fired: `G0` (Consideration-Log-Complete standing) · `G1` (Pre-structural-drafting) · `G2` (Mid-drafting on-discovery) · `G3` (Pre-amendment) · `G4` (Pre-emission) · `G5` (Handoff). |
+| `severity` | enum | Yes | `P0` (skipping G1/G2/G5 OR D4 Deferral discipline missing one of its five conditions; blocks emission) · `P1` (skipping G3/G4 OR a question that materially affects the spec; blocks emission until resolved) · `P2` (questions whose resolution does not block emission but improves spec quality). |
+| `resolution-status` | enum | Yes | `resolved-at-gate-X` (substituting the actual gate that resolved it) · `deferred-with-placeholder` (operator chose to defer; the `<USER-CONFIRM:...>` placeholder is installed and the routing target captured below). |
+| `consequence` | string | Yes | One sentence describing what selection of the operator's chosen option entails for the spec — what scaffolding lands, what is excluded, what becomes a dependency for downstream consumption. |
+| `deferral-routing` | string | Conditional | When `resolution-status: deferred-with-placeholder`, names the downstream routing target via the Handoff Manifest's `placeholders` field; required only on deferred rows. |
+
+## Sample row
+
+```markdown
+| question-id | trigger-category | source | question | options | selection | gate | severity | resolution-status | consequence | deferral-routing |
+|-------------|------------------|--------|----------|---------|-----------|------|----------|-------------------|-------------|------------------|
+| QR-001 | option-set-decision | notes/migration.md:31 "We probably need to retry transient failures" | Should the migration use retry-with-backoff or at-least-once delivery? | Retry-with-backoff (Recommended) | At-least-once delivery | Defer | Retry-with-backoff (Recommended) | G3 | P1 | resolved-at-gate-G3 | Spec §3.4 lands the retry-with-backoff option set; at-least-once delivery and deferral are excluded. The retry-config parameters become an authority-datum-absent question routed to G3 (closed in QR-002). | — |
+| QR-007 | authority-datum-absent | notes/migration.md:48 "rollback strategy" | Which reversibility paths apply to this migration? | Down-migration | Feature-flag rollback | Blue-green swap | Point-in-time-restore | Down-migration · Feature-flag rollback · Point-in-time-restore | G2 | P1 | resolved-at-gate-G2 | Spec §5.1 lists three of the four canonical reversibility paths as in-scope; blue-green swap is explicitly out-of-scope with rationale. | — |
+| QR-014 | implicit-assumption | notes/migration.md:55 "We assume the dump tool is fast enough" | Is the dump tool's throughput verified for the migration window? | Verified by recent benchmark | Verified by ops-team experience | Defer with placeholder | Defer with placeholder | G4 | P0 | deferred-with-placeholder | Spec §6.2 carries `<USER-CONFIRM:kind=ops-verification; defer-reason=ops-team-availability-pending; defer-timestamp=2026-04-27T15:00:00Z; deferred-by-command=plan-spec/>`; downstream `/plan-generate` consumes the placeholder per the Handoff Manifest's `placeholders` field. | downstream-command:/plan-generate |
+```
+
+## Invariants
+
+The audit is checked at G4 (Pre-emission). Required invariants:
+
+- Every row corresponds to an actual structured inquiry call (no fictional rows).
+- Every `D1`-identified questionable produces exactly one row (no merging, no skipping).
+- No row carries `selection: silent-default` or empty selection (the D8 anti-pattern set forbids these forms).
+- Every `severity: P0` and `severity: P1` row carries either `resolution-status: resolved-at-gate-X` or `resolution-status: deferred-with-placeholder` with non-empty `deferral-routing`.
+- The Handoff Manifest's `p0-unresolved` and `p1-unresolved` fields equal the count of P0 / P1 rows whose `resolution-status` is `deferred-with-placeholder` and whose `deferral-routing` does not name a placeholder-resolution target. The four-discipline operational invariant requires both fields to read `0` at G5 (Handoff).
+
+## Cross-references
+
+- Discipline D5 Question-Resolution Audit definition: `src/apothem/commands/plan-spec.md` Phase 6 — Question-Resolution Sweep (Ten Disciplines D1–D10).
+- Canonical channel obligation: `src/apothem/rules/interactive-questions.md`.
+- Handoff Manifest target: `src/apothem/schemas/handoff-manifest.yaml`.
+- Trigger-category D1 enumeration source: `src/apothem/commands/plan-spec.md` §Workflow Phase 6 D1.

package/src/apothem/templates/trace-matrix-template.md

@@ -0,0 +1,77 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# TRACE-MATRIX — `[SUITE_NAME]`
+
+> **Purpose.** Bidirectional traceability surface mapping every spec requirement to the phase(s) that satisfy it, and every phase to the requirement(s) it covers. Closes the **all-tier** drift-prevention invariant per `src/apothem/rules/canonical-layout.md` §7.2: at small tier a narrative trace table inside `PLAN-NOTES.md` substitutes for this formal file; at medium and large tier the formal matrix is materialized at the suite root.
+>
+> **Stable-ID convention** (medium+ tier per §7.2). Every prose directive line in `_spec/spec.md` becomes `R-NNNN` (zero-padded sequential within the suite). Every phase number becomes `P-NN` (matching `phases/NN-kebab-topic/`). Sub-phases use `P-NN.L` (matching `phases/NN-topic/NNL-subtopic/`). The matrix's row × column cells record presence / absence of mapping with the cell legend at §1.
+>
+> **Update cadence.** Each `/plan-generate` cycle assigns IDs to new requirements + phases and writes the initial matrix. Each `/plan-review` cycle re-audits the matrix and flags `✗` cells (uncovered requirements) or orphan rows (requirements with no phase coverage). Each `/plan-execute` cycle does NOT modify the matrix — execution consumes IDs but does not assign them.
+
+---
+
+## 1. Cell Legend
+
+| Cell | Meaning |
+|---|---|
+| `✓` | Covered — the phase satisfies the requirement (verified by the phase's own verification section). |
+| `◐` | Partially covered — the phase satisfies part of the requirement; the remainder maps to another phase row. |
+| `✗` | Uncovered — the phase claims to address the requirement but verification has not yet confirmed it. Findings flagged at `/plan-review`. |
+| `N/A` | Not applicable — the phase is intentionally outside this requirement's scope; the row × column intersection is empty by design. |
+| `—` | Vacuous — no relationship; the phase neither addresses nor excludes the requirement. (The default cell value when the matrix is initialized; cells transition to `✓` / `◐` / `✗` / `N/A` as coverage is declared.) |
+
+---
+
+## 2. Matrix — Requirements × Phases
+
+> **Schema.** Rows are requirements (`R-NNNN`); columns are phases (`P-NN` and `P-NN.L`). The `Source` column anchors the row to a spec section. The `Verification surface` column names where the row's coverage is verified (a phase REPORT.md, a CI gate, an external audit).
+
+| `R-ID` | Source | `P-01` | `P-02` | `P-03` | … | `P-NN` | Verification surface |
+|---|---|---|---|---|---|---|---|
+| `R-0001` | `_spec/spec.md §1` | `✓` | `—` | `—` | … | `✓` | `phases/01-.../REPORT.md` + `phases/NN-.../REPORT.md` |
+| `R-0002` | `_spec/spec.md §2.1` | `—` | `—` | `—` | … | `—` | `phases/04-.../REPORT.md` (verification cell pending Phase 04 execution) |
+| `R-NNNN` | `_spec/spec.md §M.N` | `[cell]` | `[cell]` | `[cell]` | … | `[cell]` | `[verification surface]` |
+
+> **Wide-matrix tactic.** When phase count exceeds ~30, render the matrix as a flat list rather than a wide table — each `R-NNNN` row collapses to one line (`R-NNNN: covered by P-NN, P-NN; partial at P-NN; uncovered at P-NN`). Wide tables become unreadable past ~30 columns. The flat-list form preserves every cell value but trades two-dimensional readability for vertical scrollability.
+
+---
+
+## 3. Phase Coverage Summary (Inverse)
+
+> **Schema.** The inverse projection — every phase enumerates the requirements it covers. This table is derived from §2 (no new information) but accelerates phase-side audit ("what does Phase NN actually deliver?"). Both projections must agree; disagreement is a structural failure on the bidirectional-binding axis.
+
+| `P-ID` | Phase folder | Requirements covered | Partial coverage | Uncovered claims |
+|---|---|---|---|---|
+| `P-01` | `phases/01-kebab-topic/` | `R-0001`, `R-0007` | — | — |
+| `P-NN` | `phases/NN-kebab-topic/` | `R-NNNN`, `R-NNNN` | `R-NNNN` | `R-NNNN` |
+
+---
+
+## 4. Orphan & Drift Audit
+
+> **Schema.** Two classes of drift the matrix surfaces:
+>
+> 1. **Orphan requirement** — an `R-NNNN` row whose every cell is `—` or `N/A` (no phase claims coverage). The requirement is unaddressed; either (a) a new phase must be authored, (b) the requirement must be retired with explicit deferral logged in `PLAN-NOTES.md`, or (c) the requirement maps to an existing phase and the matrix is stale.
+> 2. **Orphan phase** — a `P-NN` column whose every cell is `—` or `N/A` (the phase covers no requirement). The phase has no spec source; either (a) the spec is missing a requirement the phase implicitly addresses (author it and add the row), or (b) the phase's scope is unjustified and should be re-scoped.
+
+| Drift class | ID | Description | Action |
+|---|---|---|---|
+| Orphan requirement | `R-NNNN` | `[one-sentence summary of what is unaddressed]` | `[author phase / retire with deferral / amend matrix]` |
+| Orphan phase | `P-NN` | `[one-sentence summary of unsourced scope]` | `[author requirement / re-scope / retire]` |
+| Stale partial coverage | `R-NNNN × P-NN` | `[one-sentence summary of why the cell stayed `◐` past its expected resolution]` | `[upgrade to ✓ via verification, downgrade to ✗ pending re-audit, or mark `N/A` with rationale]` |
+
+---
+
+## 5. Small-Tier Substitution
+
+At small tier (per `src/apothem/rules/canonical-layout.md` §7.1), the formal matrix file is replaced by a narrative trace table inside the plan suite's notes file. The narrative form preserves the bidirectional invariant — every requirement names the phase(s) that satisfy it; every phase names the requirement(s) it covers — without the per-cell two-dimensional grid. A small-tier suite that grows past the 50-phase or 100-spec boundary materializes this formal matrix in the same change-set as the medium-tier transition (per §7.5 of the canonical-layout companion).
+
+---
+
+## 6. Bindings (§0.j five-direction)
+
+- **Drives →** Every `/plan-review` cycle's drift audit (the §4 orphan tables produce review findings); every medium-to-large tier transition's matrix-decomposition step (the matrix splits along the sub-suite federation seam at large tier per `MASTER-INDEX.md` §5); every fresh-session understanding of "what spec coverage looks like" without re-reading every PHASE.md.
+- **Satisfies →** `src/apothem/rules/canonical-layout.md` §7.2 drift-prevention trace-matrix mechanism (all-tier obligation); the §7.5 tier-transition emission contract for the small→medium boundary.
+- **Established by ↑** `_spec/spec.md` §8 (D7 source — Q-011 three-tier ratification); `_spec/spec.md` §8.4 drift-prevention table (the trace-matrix row of which this template is the materialization).
+- **Gated by ←** Tier classification (small-tier suites substitute the §5 narrative form); the assignment of stable IDs (`R-NNNN`, `P-NN`) at `/plan-generate` time gates this template's authorability — without IDs the matrix has no row / column keys.
+- **Cross-bound with ↔** `src/apothem/templates/master-index-template.md` (sibling drift-prevention surface — its §1 spec-section anchor table and §2 phase anchor table together provide the row / column legends this matrix consumes); `PLAN-NOTES.md` (small-tier substitute lives there per §5; deferred-orphan rationales recorded there); every `phases/NN-kebab-topic/REPORT.md` (the verification-surface column resolves to a REPORT.md path); `_spec/spec.md` (the Source column anchors every row to a spec section).