@ahmed-g-gad/apothem 0.1.1

package/src/apothem/rules/context-management-scratch.md

@@ -0,0 +1,128 @@
+---
+name: "context-management-scratch"
+description: "Path-filtered companion rule carrying the plan-workflow directory convention (`_inputs/` working state, `_spec/` authored specifications, and `_outputs/` durable generated emissions) declared at the parent `context-management.md` rule's §2.6 anchor; demand-loaded on plan-workflow entry."
+pathFilter: "**/.apothem/plans/**/*.md, **/_inputs/**/*.md, **/_outputs/**/*.md, **/_spec/**/*.md"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Plan-Workflow Scratch Convention (Companion Sub-Rule)
+
+## Purpose
+
+Specify the file-naming, directory-placement, and lifecycle convention for the plan-workflow scratch, authored-specification, and durable-output artifacts that the parent rule's `rules/context-management.md` §2.6 anchor declares. This companion is path-filtered: it loads when the assistant edits any of the per-suite plan artifacts (any file under `<project-root>/.apothem/plans/**`, `_inputs/**`, `_outputs/**`, or `_spec/**`), keeping the parent rule's always-on payload lean while preserving full convention fidelity at the demand-load surface. The parent rule remains the canonical home for context-health monitoring, externalization, compaction, blind execution, and budget discipline; this companion carries the §2.6 + §2.6.1 plan-workflow directory convention.
+
+## Obligations
+
+### 1. Scratch File Conventions
+
+Working-scratch content lives exclusively in each plan suite's own `<project-root>/.apothem/plans/{suite}/_inputs/` directory — the sole scratch home, convergent with §2's suite-locality invariant. The sibling `{suite}/_spec/` holds the same suite's authored specification and is a principled sibling, not an alternative scratch home. Scratch is session-local working storage for multi-thread context that does not fit PROGRESS.md or PLAN-NOTES.md.
+
+**Naming.** Filenames inside each `_inputs/` directory follow one of two patterns — neither carries a suite-name prefix, since the enclosing `.apothem/plans/{suite}/_inputs/` path already encodes the suite:
+
+- **Canonical-purpose** `{purpose}.md`, where `{purpose}` is drawn from the closed vocabulary `{forge, notes, triage, draft, decisions, prose, requirements}` — exhaustive, scoped exclusively to `_inputs/` scratch (never `_spec/`, which uses the singleton `spec.md` per §2), extensible only by rule revision, never by ad-hoc naming.
+- **Free-form** `{kebab-case-topic}.md` for topic-scoped working notes outside that vocabulary.
+
+**Lifecycle.** Each file follows a creation → reference → graduation arc: written into `{suite}/_inputs/` at need, referenced within the active session, then resolved along exactly one of four terminal paths:
+
+1. **Promoted** intra-suite from `{suite}/_inputs/forge.md` to `{suite}/_spec/spec.md` once the content reaches specification quality (the §2 forge→spec lifecycle — the canonical arc for prose elicitation).
+2. **Distilled** into memory per `rules/auto-memory.md` when it captures long-lived knowledge worth preserving across sessions.
+3. **Captured** into PLAN-NOTES.md when it is a plan-relevant decision requiring durable record.
+4. **Deleted** at closure when session-complete and no graduation path applies.
+
+Cross-session persistence requires a reason documented inside the file itself; unexplained carry-over is a convention violation. Examples — canonical-purpose: `forge.md` in `.apothem/plans/agent-home-hardening/_inputs/` holds in-progress prose elicitation until it promotes to `.apothem/plans/agent-home-hardening/_spec/spec.md`. Free-form: `review-findings.md` in the same directory holds topic-scoped review triage until its findings distill to memory or graduate to PLAN-NOTES.md.
+
+### 2. Plan-Workflow Directories (`_spec/`, `_inputs/`, and `_outputs/`, per suite)
+
+The planning workflow writes three semantically distinct artifact classes, each with its own sibling directory **inside every plan-suite folder**. The underscore prefix signals ecosystem-internal state and sorts these folders before plan-product folders (`phases/`, etc.) within the suite. The distinction between the three classes is **semantic**, not merely organizational — correctly placing an artifact depends on whether it is a committed specification, working scratch, or durable generated output. All three directories are **suite-local**: each plan suite owns its own `_spec/`, `_inputs/`, and `_outputs/`, and no instance of any of these directories exists outside a suite folder.
+
+**Three artifact classes:**
+
+- **Authored specifications** — stable, committed prose that the planning workflow consumes as authoritative input. Home: `<project-root>/.apothem/plans/{suite}/_spec/`.
+- **Workflow scratch** — volatile, session-local working state produced during plan elicitation, review, and execution on that suite. Home: `<project-root>/.apothem/plans/{suite}/_inputs/`.
+- **Durable generated outputs** — bounded operator-facing reports, audit artifacts, rollups, metrics, exports, and phase-output mirrors emitted by writeful planning commands. Home: `<project-root>/.apothem/plans/{suite}/_outputs/`.
+
+**Directory specification — `<project-root>/.apothem/plans/{suite}/_spec/`:**
+
+- **Role:** Sole canonical home for the authored prose specification feeding its enclosing plan suite. Consumed by `/plan-spec` (during elicitation finalization) and `/plan-generate` (as authoritative input).
+- **Closed purpose set:** `{spec}` (singleton at the directory root). Per Q-016 the directory admits three optional structural subdirectories — `supporting/` (long-form supporting prose that the singleton `spec.md` cross-references but does not inline), `diagrams/` (Mermaid / image / SVG assets the spec embeds via relative path), `citations/` (sourced excerpts and reference snippets the spec quotes). The singleton `spec.md` remains the authoritative entry point; subdirectory contents are read by humans and `/plan-generate` only when the spec's prose explicitly cites them.
+- **Filename pattern:** `spec.md` at the directory root (singleton — the suite name is encoded by the enclosing folder path, not by the filename). Files inside `supporting/`, `diagrams/`, `citations/` use kebab-case topic names.
+- **Writers:** Humans and the `/plan-spec` workflow (during finalization).
+- **Readers:** `/plan-generate` reads `spec.md` as the authoritative input for plan-suite generation; humans read for audit and revision.
+- **Contract status:** Committed. A file in `{suite}/_spec/` is authoritative — downstream phases trace requirements back to it.
+- **Longevity:** Persistent across sessions until the enclosing suite is retired. Retirement is atomic with the suite — deleting the suite folder deletes the spec.
+
+**Directory specification — `<project-root>/.apothem/plans/{suite}/_inputs/`:**
+
+- **Role:** Sole canonical home for session-scratch produced during planning workflows on its enclosing suite. All multi-thread working context that does not fit PROGRESS.md or PLAN-NOTES.md lives here.
+- **Closed purpose set:** `{forge, notes, triage, draft, decisions, prose, requirements}` with per-purpose semantics:
+  - `forge` — draft-in-progress of a prose specification before promotion to `_spec/`.
+  - `notes` — free-form working notes accumulated during a phase or investigation.
+  - `triage` — cross-topic diagnostic surveys scoped to this suite.
+  - `draft` — draft work products (intermediate artifacts), NOT draft prose.
+  - `decisions` — in-flight decision capture before graduation to PLAN-NOTES.md.
+  - `prose` — free-form prose elicitation captured before forge consolidation; the lighter-weight sibling of `forge.md` for short-form drafts that have not yet earned the forge promotion arc.
+  - `requirements` — explicit operator-supplied requirements list captured during elicitation; pairs with `forge.md` when the forge content needs an authoritative requirements anchor distinct from the prose narrative.
+- **Filename pattern:** `{purpose}.md` (e.g., `forge.md`, `notes.md`, `decisions.md`) or `{kebab-case-topic}.md` (e.g., `review-findings.md`, `triage-phase-04.md`). No suite-name prefix — the enclosing folder path already encodes the suite.
+- **Writers:** Any planning-workflow actor scoped to the enclosing suite — humans, `/plan-spec`, `/plan-generate`, `/plan-review`, `/plan-audit`, `/plan-execute`, subagents.
+- **Readers:** Same set, as session context requires.
+- **Contract status:** Working state. Files in `{suite}/_inputs/` are volatile — downstream artifacts MUST NOT trace requirements back to them directly; content graduates (to `{suite}/_spec/spec.md`, PLAN-NOTES.md, or memory) or is deleted.
+- **Longevity:** Session-local unless explicitly promoted. Files persisting beyond their session require a documented reason in the suite's PROGRESS.md or PLAN-NOTES.md.
+
+**Directory specification — `<project-root>/.apothem/plans/{suite}/_outputs/`:**
+
+- **Role:** Sole canonical home for durable generated emissions that are too detailed for PROGRESS.md or PLAN-NOTES.md but remain part of the suite's audit trail. This includes audit reports, execution report mirrors, rollups, metrics, exports, and bounded operator-facing summaries.
+- **Closed purpose set:** `{report, audit, rollup, metrics, export}` as top-level file or directory purposes, plus free-form kebab-case topic names when a generated output has a precise domain subject. Free-form topics must cite their producer in frontmatter, header, or the phase report's Outputs emitted section.
+- **Filename pattern:** `{purpose}-{YYYY-MM-DD}.md`, `{kebab-case-topic}.md`, or `{phase-slug}/REPORT.md` for phase mirrors. No suite-name prefix — the enclosing folder path already encodes the suite.
+- **Writers:** Writeful planning workflows scoped to the enclosing suite — `/plan-audit`, `/plan-execute`, `/plan-review` when materializing durable review reports, `/plan-status` only when another orchestrator explicitly converts its prose output into a file, and subagents acting under those commands.
+- **Readers:** Humans, `/plan-status`, downstream `/plan-execute` phases, review/audit cycles, and any maintenance suite that consumes the output as evidence.
+- **Contract status:** Durable generated output. Files in `{suite}/_outputs/` are not authoritative requirements, but they are committed evidence of what the workflow emitted and verified.
+- **Longevity:** Persistent across sessions until the enclosing suite is retired. A stale output is superseded by a newer output and index/provenance entry; it is not silently overwritten unless the producer's contract says the path is a stable singleton.
+
+**Lifecycle — forge → spec promotion (always intra-suite):**
+
+```mermaid
+%%{ init: { "theme": "neutral" } }%%
+%% verified: 2026-04-27 %%
+%% provenance: rules/context-management-scratch.md §1 (scratch file conventions) %%
+%% cross-reference: rules/context-management.md §2.6 (parent rule anchor) %%
+flowchart LR
+    SESS["Session start<br/>(suite folder established first)"]
+    SESS --> FORGE_W["{suite}/_inputs/forge.md<br/>(prose elicitation begins here)"]
+    FORGE_W --> ITER["Iterative authoring<br/>(/plan-spec refinement passes)"]
+    ITER --> FORGE_R["{suite}/_inputs/forge.md<br/>(reaches specification quality)"]
+    FORGE_R --> PROM["Copy+rename promotion<br/>(forge retired)"]
+    PROM --> SPEC["{suite}/_spec/spec.md<br/>(authoritative spec · feeds /plan-generate)"]
+```
+
+No simultaneous authoritative copies — the forge file is **deleted** (or emptied) once the spec is promoted. The promotion act is the contract-status transition from working state to committed. Both sides of the transition are siblings in the same suite folder — promotion is always intra-suite, never cross-suite.
+
+**Pre-suite bootstrap:** `/plan-spec` MUST establish the enclosing suite folder (`<project-root>/.apothem/plans/{suite}/`) as its first action, before any forge write. Two sub-cases:
+
+- **Suite name known up front:** create `{suite}/_inputs/forge.md` directly.
+- **Suite name derived during elicitation:** collect a provisional kebab-case suite name at `/plan-spec` Step 1 (before any forge content is written). Refinement is permitted — renaming the suite folder is a single `mv`. No state ever exists outside a suite folder; there is no root-level bootstrap location.
+
+If a `/plan-spec` session is abandoned before promotion, the orphan suite folder (containing only `_inputs/forge.md`) is subject to the session-end retirement policy: either deleted, or marked with a longevity reason in a placeholder PLAN-NOTES.md.
+
+**Invariants:**
+
+- **Suite-locality:** Every `_spec/`, `_inputs/`, and `_outputs/` directory MUST be a direct child of a plan-suite folder (`<project-root>/.apothem/plans/{suite}/`). Root-level instances at `<project-root>/.apothem/plans/_spec/`, `<project-root>/.apothem/plans/_inputs/`, or `<project-root>/.apothem/plans/_outputs/`, or instances nested anywhere other than directly under a suite folder, are convention violations requiring migration.
+- **Disjoint purpose vocabularies:** `{spec}` (root singleton) plus `{supporting, diagrams, citations}` (optional subdirectory names) is exclusive to `_spec/`; `{forge, notes, triage, draft, decisions, prose, requirements}` is exclusive to `_inputs/`. Cross-contamination (e.g., a `spec.md` in `_inputs/` or a `forge.md` in `_spec/`) is a convention violation.
+- **Directional promotion:** Files graduate `{suite}/_inputs/ → {suite}/_spec/` within the same suite; never the reverse, never cross-suite. A spec that needs further elicitation is amended in place in `_spec/`, not demoted back to `_inputs/`.
+- **Authoritative-input asymmetry:** `/plan-generate` reads only `{suite}/_spec/spec.md` as spec input for its target suite. It never treats an `_inputs/` file as authoritative, and never consumes another suite's `_spec/`.
+- **Output non-authority:** `_outputs/` files are evidence and durable emissions, not requirement sources. Downstream work may consume them as verified-output evidence, but requirement traceability still resolves to `_spec/spec.md`, MASTER-PLAN.md, PHASE.md, and operator-ratified decisions.
+- **Single home per artifact class per suite:** For a given suite, exactly one `_spec/` folder, one `_inputs/` folder, and one `_outputs/` folder exist, all direct children of the suite folder. No other directory within the suite (e.g., `{suite}/phases/`, `{suite}/scratch/`) may host artifacts of these classes.
+- **Atomic retirement:** Deleting a plan suite is a single `rm -rf {suite}/` — removes specification, scratch, phases, and plan infrastructure atomically. No cross-directory cleanup is required. Cross-suite references to a retired suite's spec or scratch are the responsibility of the referring artifact and MUST be rewritten before retirement.
+
+## Enforcement
+
+Path-filtered (the four glob patterns in this rule's `pathFilter` field — `**/.apothem/plans/**/*.md`, `**/.plans/**/*.md`, `**/_inputs/**/*.md`, `**/_outputs/**/*.md`, `**/_spec/**/*.md`), always-on at every seriousness level when in scope. Demand-loaded companion to `rules/context-management.md` §2.6. The parent rule carries the proactive externalization protocol's other sub-clauses (§2.1 externalize-on-decide through §2.5 externalize-on-phase-exit), the compaction discipline, the long-conversation resilience protocol, the graceful-degradation policy, the blind-execution protocol, and the context-budget discipline; this companion carries the §2.6 plan-workflow directory convention.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every plan-workflow scratch file placement (the closed-purpose vocabulary `{forge, notes, triage, draft, decisions, prose, requirements}` for `_inputs/`; the singleton `spec.md` for `_spec/`; the generated-output purposes `{report, audit, rollup, metrics, export}` for `_outputs/`). ● The forge→spec promotion lifecycle (§2 — `{suite}/_inputs/forge.md` → `{suite}/_spec/spec.md`). ● The suite-locality invariant (every `_inputs/`, `_outputs/`, and `_spec/` is a direct child of a plan-suite folder). ◐ The PreToolUse Write/Edit hooks' real-time path-shape enforcement.
+- **Satisfies →** ● CM-12 / CM-24 (rule-delegated mandates; this companion is the path-filtered subset). ● the rules registry row "Context Management Scratch". ● `rules/context-management.md` §2.6 anchor (the parent rule's pointer to this companion's full specification).
+- **Established by ↑** ● `rules/context-management.md` §2.6 (parent-rule anchor). ● CM-12 + CM-24 inline definitions. ● the artifact directories (.apothem/plans/ + legacy .plans/ directory class).
+- **Gated by ←** ● The path-filter (`**/.apothem/plans/**/*.md`, `**/.plans/**/*.md`, `**/_inputs/**/*.md`, `**/_outputs/**/*.md`, `**/_spec/**/*.md`) — this rule demand-loads only on plan-workflow artifact touches. ● `rules/context-management.md` always-on baseline (parent rule's §2.6 anchor must be live for the companion to demand-load coherently).
+- **Cross-bound with ↔** ↔ `rules/context-management.md` (parent rule; §2.6 anchor binds this companion). ↔ `rules/context-management-budget.md` (sibling companion carrying the §7 Context Budget Discipline operational bodies — §7.1 budget awareness, §7.2 demand loading, §7.3 pressure signals, §7.4 per-task effort calibration / CM-12d). ↔ `commands/plan-spec.md` (Forge command's first action establishes the suite folder; §2 forge→spec promotion is operationalized at `/plan-spec` Step 1). ↔ `commands/plan-generate.md` (consumes `{suite}/_spec/spec.md` as authoritative input per the §2 authoritative-input-asymmetry invariant). ↔ `commands/plan-audit.md` + `commands/plan-execute.md` (write durable generated emissions under `{suite}/_outputs/`). ↔ `hooks/messages/pretooluse-write.md` + `hooks/messages/pretooluse-edit.md` (the hook contexts that enforce the path-shape invariants in real time).

package/src/apothem/rules/context-management.md

@@ -0,0 +1,85 @@
+---
+name: "context-management"
+description: "Systematic context management under the blind-execution invariant — every turn must be executable by a fresh session with zero prior history, so all state lives in durable files and active context is acceleration, not storage. Covers context-rot monitoring, proactive externalization, compaction discipline, opt-in continuous single-session execution, and context-budget calibration. Implements CM-12 / CM-14 / CM-18 / CM-19 / CM-24."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Context Management and Conversation-Independent Execution
+
+## Purpose
+
+Manage context systematically: mitigate context rot, preserve state across compaction and session boundaries, favor continuous single-session execution when the phase graph can advance, and guarantee every plan phase is executable in a fresh session with zero prior history. **Invariant: if every turn were the first turn of a new session, no information would be lost and no action would be incorrect.**
+
+## Obligations
+
+### 1. Context Health Monitoring
+
+Continuously monitor five signals: **token pressure** (latency, truncation, compression warnings), **recall degradation** (re-reading to recover earlier decisions), **repetition** (re-asking, re-discovering), **drift** (naming / convention inconsistencies, contradictions), **staleness** (outdated file-state references).
+
+### 2. Proactive Externalization Protocol (Companion Sub-Rule Anchor)
+
+Externalize critical state to durable files before it can decay; conversation history is never the sole record. (Companion Sub-Rule Anchor) See rules/context-management-protocol.md §1 for externalize-on-decide, on-accumulate, before-compact, on-complexity, and on-phase-exit sub-clauses.
+
+**2.6 — Scratch File Conventions and Plan-Workflow Directories (Companion Sub-Rule Anchor):** The plan-workflow directory convention — file-naming inside `<project-root>/.apothem/plans/{suite}/_inputs/`, the `_spec/` authored-spec surface, the `_outputs/` durable emission surface, the closed-purpose vocabularies, the forge→spec promotion lifecycle, the suite-locality invariant, and the directional-promotion rule — lives at the path-filtered companion rule [`rules/context-management-scratch.md`](./context-management-scratch.md), demand-loaded when the assistant edits any per-suite plan artifact under `<project-root>/.apothem/plans/**` (or the legacy `.plans/**`), `_inputs/**`, `_outputs/**`, or `_spec/**`.
+
+### 3. Compaction Discipline (CM-19) (Companion Sub-Rule Anchor)
+
+Compaction is the primary defense against context rot — trigger proactively per the cataloged boundaries; post-compaction restoration runs the Blind Bootstrap Sequence. A dispatch-routed `PostToolUse` hook makes the size-based triggers mechanical: it tracks per-session activity and surfaces a proactive-compaction advisory once a threshold crosses (advisory-only, never blocks, fail-open). (Companion Sub-Rule Anchor) See rules/context-management-protocol.md §2 for the full trigger catalog and the proactive-advisory hook.
+
+### 4. Long Conversation Resilience (Companion Sub-Rule Anchor)
+
+Long conversations apply periodic snapshots, progressive summarization, convention anchoring, regression detection, and concurrent-modification awareness. (Companion Sub-Rule Anchor) See rules/context-management-protocol.md §3.
+
+### 4A. Continuous Single-Session Execution (CM-16) (Companion Sub-Rule Anchor)
+
+Full-suite plan execution halts at each phase boundary by default; continuous advancement is opt-in per `agnostic-posture.md` (the operator sets the profile `enforcement.continuous_execution` flag, passes `--no-pause`, or requests it). Once opted in, the boundary sequence is: complete the phase, externalize the Phase Exit Protocol, compact, run the Blind Bootstrap Sequence, advance to the next unblocked phase. Execution still halts on explicit single-phase invocations, BLOCKED phases, final-suite completion, or unreconciled context-rot / regression signals after one externalize→compact→bootstrap recovery cycle. (Companion Sub-Rule Anchor) See rules/context-management-protocol.md §3.6.
+
+### 5. Graceful Degradation (Companion Sub-Rule Anchor)
+
+Under critical context pressure, externalize-then-complete-then-record-then-compact; silent quality degradation, unmarked partials, and undocumented state loss are forbidden. (Companion Sub-Rule Anchor) See rules/context-management-protocol.md §4.
+
+### 6. Blind Execution Protocol — Invariant (Companion Sub-Rule Anchor)
+
+Every phase must be executable by a fresh session with zero conversation history. **The Invariant:** all state lives in durable files; active context is ephemeral acceleration, not storage. (Companion Sub-Rule Anchor) See rules/context-management-protocol.md §5 for the Blind Bootstrap Sequence, Output Validation Gate, Convention Recovery, and State File Validation procedures.
+
+### 7. Context Budget Discipline (Companion Sub-Rule Anchor)
+
+Budget awareness, demand loading, pressure-signal thresholds (>3 large reads, >500 lines emitted, recall-degradation), and per-task effort calibration (CM-12d — operator-invoked per the agnostic posture, with the D3 stratified taxonomy supplying the recommended tier; per-phase calibration at `phases/NN-topic/PHASE.md`; single-phase scope; PROGRESS.md Resumption Contract recording). (Companion Sub-Rule Anchor) See rules/context-management-budget.md §7 for §7.1 / §7.2 / §7.3 / §7.4 operational bodies.
+
+### 8. Error Classification (CM-18) (Companion Sub-Rule Anchor)
+
+Six error classes (Parse / Resolution / Validation / Generation / External / State) structure recovery; escalate to user after 3 cumulative failures across any class. (Companion Sub-Rule Anchor) See rules/context-management-protocol.md §6 for the trigger / recovery-strategy table.
+
+## Seriousness Scaling
+
+| Level | Context Management Behavior |
+| ----- | --------------------------- |
+| EXPLORING | Basic externalize-on-decide; compact between phases (§3 detailed triggers from PERSONAL_USE+); Blind Bootstrap at session start; budget awareness (§7.1); no periodic snapshots |
+| PERSONAL_USE | Full externalization (§2); compact per §3; budget discipline (§7); periodic snapshots every 20 tool calls; Blind Bootstrap + Phase Exit Protocol active |
+| SHARED | Add long-conversation resilience (§4); Resumption-Contract convention anchoring; regression detection; graceful degradation (§5); full Blind Execution Protocol (§6) including Output Validation Gate; budget discipline enforced |
+| PUBLIC_LAUNCH | Aggressive compaction; snapshots every 15 tool calls; externalization failures block continuation; Output Validation Gate failures block execution (no override); budget discipline strictly enforced |
+
+## Anti-Patterns
+
+- **DON'T** rely on active context as sole record — **BECAUSE** it will be compressed or lost.
+- **DON'T** defer or batch externalization — **BECAUSE** "later" may be after compaction or session end.
+- **DON'T** ignore recall-degradation signals — **BECAUSE** continuing compounds the error.
+- **DON'T** hold more than 5 active threads without externalization — **BECAUSE** overflow is structural.
+- **DON'T** skip Phase Exit Protocol — **BECAUSE** it breaks the Blind Execution Invariant.
+- **DON'T** re-read full sources when Resumption Contract snapshots suffice — **BECAUSE** it inflates context.
+- **DON'T** redispatch a full-suite execution merely because a phase boundary was reached — **BECAUSE** continuous mode already externalizes, compacts, bootstraps, and proceeds.
+
+## Enforcement
+
+Always-on at every seriousness level, scaling per the table. Implements CM-12 / CM-14 / CM-18 / CM-19 / CM-24. CM-14 session-start (Blind Bootstrap) and session-end (Phase Exit) are owned here; session-end memory evaluation delegates to CM-26 and artifact evolution delegates to CM-22, coordinated by the Stop hook.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every session's bootstrap sequence (§6 Blind Execution Protocol — every fresh session reads PROGRESS.md, PLAN-NOTES.md, target phase file in deterministic order). ● Every phase exit (§2.5 Externalize-On-Phase-Exit writes Resumption Contract + Phase Output Registry to PROGRESS.md). ● Every compaction event (§3 Compaction Discipline triggers proactively per the nine enumerated triggers). ● Full-suite continuous execution (§4A) across phase boundaries when no blocker or explicit single-phase scope applies. ● The CM-19 compaction discipline (this rule's §3 is its canonical specification). ◐ The Stop hook's session-end protocol (the hook coordinates CM-26 + CM-22 evaluation handoffs declared at this rule's enforcement tail).
+- **Satisfies →** ● CM-12 / CM-14 / CM-18 / CM-19 / CM-24 (rule-delegated mandates). ● the rules registry row "Context Management". ● the hooks pipeline PreCompact / PostCompact / Stop / SessionStart events (this rule defines what those hooks coordinate).
+- **Established by ↑** ● CM-12 + CM-14 + CM-18 + CM-19 + CM-24 inline anchors. ● the artifact directories (memory directory class is part of the §6 Blind Bootstrap manifest). ● the hooks pipeline (the hooks this rule coordinates are registered there).
+- **Gated by ←** ● `CLAUDE.md` always-loaded preamble (this rule must be active for the Blind Bootstrap to fire). ● The harness's ability to run hooks (`hooks/dispatch.py` resolves the ecosystem root at session start).
+- **Cross-bound with ↔** ↔ `rules/context-management-protocol.md` (path-filtered companion sub-rule carrying the §2 / §3 / §4 / §5 / §6 / §8 procedural depth — externalization sub-clauses, compaction-trigger catalog, long-conversation resilience and continuous-execution procedures, graceful-degradation priorities, blind-execution full body, and error-classification table). ↔ `rules/context-management-scratch.md` (path-filtered companion sub-rule carrying the §2.6 plan-workflow scratch convention). ↔ `rules/context-management-budget.md` (path-filtered companion sub-rule carrying the §7 Context Budget Discipline operational bodies — §7.1 budget awareness, §7.2 demand loading, §7.3 pressure signals, §7.4 per-task effort calibration / CM-12d). ↔ `rules/auto-memory.md` (CM-26 owns the session-end memory evaluation that §2.5 delegates). ↔ `rules/persistent-conventions-vigilance.md` (CM-22 owns the artifact-evolution evaluation that §2.5 delegates). ↔ `rules/large-file-generation.md` (CM-23 large-file protocol triggers compaction at the 500-line emission threshold per §3). ↔ `rules/agent-orchestration.md` (post-multi-agent compaction trigger lives at §3; CM-25 agent orchestration is bidirectional). ↔ `hooks/messages/precompact.md` + `hooks/messages/postcompact.md` + `hooks/messages/stop.md` (the hook contexts the protocol's enforcement points emit). ↔ `rules/large-file-reading.md` (CM-12 lean-context discipline; large-file-reading segmentation is a primary read-side lever preserving context budget per §7.2 Demand Loading). ↔ `rules/agnostic-posture.md` (continuous single-session advancement is opt-in under the host-agnostic posture, not a default-on obligation). ↔ `rules/session-closure.md` (the §2.5 phase-exit / Stop-hook externalization is the plan-suite materialization of the formal session close; session-closure extends the same done/deferred + verification discipline to ad-hoc sessions the hook does not reach). ↔ `rules/tool-use-discipline.md` (the observe step of that rule's observe → decide → act loop preserves context budget per §7.2; §8 bounded-retry-with-retreat bounds the loop when the exit resists convergence).

package/src/apothem/rules/definitiveness-virtues.md

@@ -0,0 +1,67 @@
+---
+name: "definitiveness-virtues"
+description: "Path-filtered companion to `rules/definitiveness.md` carrying the operational depth of M8 — Definitiveness, Airtightness, and the Family of Rigorous-Systems Virtues. Demand-loaded when the assistant edits authoring surfaces (Markdown, rules, skills, agents, commands, docs) where prescriptive prose lands: the three hedge-resolution paths with worked examples, the seven-virtue floor, the definitive-form Right/Wrong examples, the airtightness checks, and the failure tells."
+pathFilter: "**/*.md, **/CLAUDE.md, **/rules/**, **/skills/**, **/agents/**, **/commands/**, **/docs/**"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Definitiveness — Virtues, Resolution Paths, and Failure Tells (Companion Sub-Rule)
+
+## Purpose
+
+Carry the operational depth of **M8 — Definitiveness, Airtightness, and the Family of Rigorous-Systems Virtues** — the three hedge-resolution paths with worked examples, the seven-virtue numbered list with full prose, the definitive-form Right/Wrong examples, the airtightness-checks-beyond-hedging bullet body, and the failure-tells full prose. This companion is path-filtered: it loads when the assistant edits authoring surfaces (Markdown, rules, skills, agents, commands, docs) where prescriptive prose lands, keeping the parent's always-on payload lean while preserving full fidelity at the demand-load surface. The parent rule remains the canonical home for the always-on directive, the closed hedging-vocabulary list (load-bearing for the mechanical matcher), and the one-line summary of the seven virtues.
+
+## Obligations
+
+### 1. Hedging-Vocabulary Resolution — The Three Paths
+
+The closed hedging-vocabulary list lives in the parent rule (load-bearing for the `conformity/hedging_grep.py` matcher). Each occurrence in prescriptive prose MUST resolve on exactly one of three paths:
+
+1. **Promote** to an unconditional form with the conditions named — "the build typically completes in 5 minutes" → "the build completes in 5 minutes when the cache is warm; up to 12 minutes on a cold start (criterion: `~/.cache/<host>` size below the threshold)".
+2. **Demote** to an explicit conditional with the branches enumerated — "users should probably commit small changes" → "when the change touches a single revertable unit, commit; when it touches multiple, split the commit per `rules/production-ready-prs.md`."
+3. **Remove** when the hedge concedes the prescription does not apply ("this is generally recommended" with no host-specific evidence) — drop the prescription; the option set is underdetermined and routes through the inquiry surface per `rules/authority-inquiry.md`.
+
+The mechanical hedging-grep at `conformity/hedging_grep.py` operationalizes detection at the pre-emission gate per `rules/pre-emission-gate.md` row 8.
+
+### 2. The Family of Rigorous-Systems Virtues — Seven-Virtue Floor
+
+Every emitted artifact passes the seven-virtue floor:
+
+1. **Completeness.** Every declared domain is fully covered. A partial enumeration that lists three of five cases names the omission as `(remaining cases: …)` rather than eliding it.
+2. **Closure.** Every `TBD` / `TODO` / `FIXME` / `XXX` / `we'll handle later` is closed in place or surfaced as an inquiry per `rules/authority-inquiry.md`. Open markers in emitted artifacts are non-conformant.
+3. **Strong non-contradiction.** No two clauses in the same artifact (or its declared neighbors) contradict each other. The pre-emission gate's M3 dimension 2 (consistency · coherence · integration · validity) at `rules/ten-dimension-check.md` enforces the cross-artifact case.
+4. **Determinism.** Same inputs produce the same outputs. Non-deterministic behavior is declared with the source of non-determinism named (random seed, timing-dependent ordering, external-state read).
+5. **Exhaustiveness of enumerations.** Every closed enumeration declares the closure with `{a, b, c}` set notation or an explicit "the four classes are X / Y / Z / W". Open enumerations declare the open-set nature with `{a, b, c, …}` and the discovery surface that admits new members.
+6. **Specificity over vagueness.** Numbers carry units; thresholds carry comparison operators; durations carry bounds. "Five minutes" is conformant; "around five minutes" is hedging unless the bound is named.
+7. **Pre / post / failure conditions on every contract.** Every function, schema, runbook step, CI job, and migration script declares its pre-conditions (what must hold before invocation), post-conditions (what holds after a successful return), and failure modes (what holds after a failure return — exception type, observable state, recovery path).
+
+### 3. Definitive Form — Right / Wrong Examples
+
+A generated rule that says "users should probably commit in small chunks" is non-conformant; the rule says "every commit covers one logical change (criterion: a single revertable unit; an indicator: `git revert <sha>` produces a coherent rollback)" or it does not say it. A generated test description that says "this test should usually pass within 5 seconds" is non-conformant; the description says "this test asserts completion within 5 seconds; if the assertion exceeds, the test fails — hard timeout, not a soft expectation". A generated configuration that says "the cache size is generally 100 MB" is non-conformant; the configuration declares `cache_size_mb: 100` and the comment names the condition under which the value changes.
+
+### 4. Airtightness Checks Beyond Hedging
+
+Hedging-vocabulary elimination is the surface signal; airtightness reaches deeper:
+
+- **No silent fallbacks.** A configuration default carries a comment naming the conditions under which it changes. A library's silent retry-on-error declares its retry budget, back-off, and failure surface.
+- **No precedence ties.** When two rules apply to the same surface, the precedence MUST be stated explicitly. The §6 inline-vs-rule-delegated mandate split at `CLAUDE.md` is the canonical pattern — the registry table names which mandate is inline and which is rule-delegated, with no ambiguity.
+- **No edge cases for later.** Edge-case handling is part of the contract, not a follow-up. A genuinely out-of-scope edge case carries an explicit `[Deferral — out-of-scope: <description>; tracking: <where>]` ledger entry per `rules/disclosure-ledger.md`.
+- **No literal-honoring loopholes.** When the literal text of a directive admits a reading that violates its intent, rewrite the directive to close the loophole. The intent is the contract; the literal text is the carrier.
+
+### 5. Failure Tells — Full Prose
+
+"It might be worth considering" / "this should usually work" / "you may want to" / "it's generally recommended" / "this is broadly compatible" — all in prescriptive contexts where definitiveness is possible. Open-ended exception clauses ("exceptions may apply"). Unstated assumptions surfacing as runtime errors. A rule body that uses "should" where "must" applies and the conditions are knowable. A function with no docstring declaring pre / post / failure. A test description that asserts probabilistic behavior without the probability named. A `TBD` left in a shipped artifact. A configuration default that lacks a comment naming the condition under which the default changes. A precedence tie where two rules apply to the same surface without a stated ordering. A literal-honoring loophole where the directive's intent is violated by an admissible reading of its text. **Simulated tools or fabricated output presented as real** — mock command output, an invented tool result, a hand-written transcript, or a fabricated tool interface offered as if it were a genuine invocation. The airtightness floor admits no fabricated evidence: run the real tool and report its actual output, or, when the tool is unavailable, surface the gap as an inquiry per `rules/authority-inquiry.md` and name what went unchecked — never stand in a plausible-looking invention for the result that was not produced.
+
+## Enforcement
+
+Path-filtered (the seven glob patterns in this rule's `pathFilter` field — `**/*.md`, `**/CLAUDE.md`, `**/rules/**`, `**/skills/**`, `**/agents/**`, `**/commands/**`, `**/docs/**`), always-on at every seriousness level when in scope. Demand-loaded companion to `rules/definitiveness.md`. The parent rule carries the always-on directive, the closed hedging-vocabulary list, and the one-line summary of the seven virtues; this companion carries the operational depth — three hedge-resolution paths with worked examples, the seven-virtue numbered list with prose, the definitive-form Right/Wrong examples, the airtightness-checks-beyond-hedging bullet body, and the failure-tells full prose.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every prescriptive-prose authoring surface under the path-filter (Markdown, CLAUDE.md, rules, skills, agents, commands, docs). The three-path hedge-resolution surface every hedging-grep finding routes through. The seven-virtue floor every emitted artifact passes at the pre-emission gate.
+- **Satisfies →** the fifteen-mandate registry row **M8 — Definitiveness, Airtightness** (operational-depth tier; always-on directive lives at the parent rule). `rules/definitiveness.md` parent-rule anchor (the parent's pointer to this companion's full specifications).
+- **Established by ↑** `rules/definitiveness.md` (parent-rule anchor — the parent's §"Required behavior" subsections cite this companion for full operational depth). the fifteen-mandate registry (ratifies M8). the Pre-Emission Gate row 8 (M8 mechanical bar).
+- **Gated by ←** The path-filter (the seven glob patterns) — this rule demand-loads only on authoring-surface touches. `rules/definitiveness.md` always-on baseline (parent rule must be live for this companion's pointers to surface coherently).
+- **Cross-bound with ↔** `rules/definitiveness.md` (parent rule; the always-on directive and closed hedging-vocabulary list live there). `rules/operational-mandates.md` §CM-10 Brutal Honesty (M8 ↔ CM-10 cross-mapping; the inward-axis analog). `rules/disclosure-ledger.md` (M2 — every hedge promotion / removal is recorded in the ledger). `rules/ten-dimension-check.md` (M3 — dimension 2 consistency / coherence + dimension 6 structurality enforce airtightness across artifacts; this rule enforces it within the artifact). `rules/pre-emission-gate.md` (M4 — bar 8 of the gate operationalizes the hedging-vocabulary scan and the pre / post / failure-condition presence check). `rules/authority-inquiry.md` (M5 — removed-prescription cases route to the inquiry surface).

package/src/apothem/rules/definitiveness.md

@@ -0,0 +1,58 @@
+---
+name: "definitiveness"
+description: "Every emitted statement is definitive and airtight — hedging vocabulary is eliminated where binding prescription is possible; every contract carries pre / post / failure conditions; every TBD / TODO / FIXME is closed in place or surfaced as an inquiry; the family of rigorous-systems virtues governs every artifact."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Definitiveness, Airtightness, and the Family of Rigorous-Systems Virtues
+
+## What this rule enforces
+
+Binds **M8 — Definitiveness, Airtightness, and the Family of Rigorous-Systems Virtues**. Every statement in every emitted host-project artifact — instruction, rule, description, contract, schema, matcher, directive, comment, runbook step — MUST be **definitive** (no hedging where binding prescription is possible; no "it depends" without dependencies enumerated; no unstated scope; no implicit defaults; no vague thresholds) and **airtight** (no gaps in declared domains; no loopholes where literal-honoring violates intent; no unstated assumptions; no precedence ties; no silent fallbacks in authoritative territory; no "edge cases we'll figure out later"). The broader family — completeness, closure, strong non-contradiction, determinism, exhaustiveness of enumerations, specificity over vagueness, pre / post / failure conditions on every contract — is the family of rigorous-systems virtues this rule enforces collectively.
+
+## Pre-conditions
+
+Applies to every host-project artifact emission, including trivial-scope work per the trivial-vs-non-trivial threshold — the airtightness floor does not relax with scope. A two-line comment, a five-line shell snippet, and a multi-thousand-line architectural specification carry the same definitiveness obligation.
+
+## Required behavior
+
+### Hedging vocabulary — eliminate or qualify
+
+Closed list, detected and eliminated when binding prescription is possible: **maybe, might, could, should probably, usually, generally, typically, mostly, often, perhaps, possibly, somewhat, fairly, roughly, broadly**. Each occurrence MUST resolve on one of three paths — **Promote** (unconditional with conditions named), **Demote** (explicit conditional with branches enumerated), or **Remove** (route to inquiry surface). The mechanical hedging-grep at `conformity/hedging_grep.py` operationalizes the detection at `rules/pre-emission-gate.md` row 8.
+
+(Companion Sub-Rule Anchor) See `rules/definitiveness-virtues.md` §1 for the three resolution paths with worked examples.
+
+### The family of rigorous-systems virtues
+
+Every emitted artifact passes a seven-virtue floor: **(1) Completeness**, **(2) Closure**, **(3) Strong non-contradiction**, **(4) Determinism**, **(5) Exhaustiveness of enumerations**, **(6) Specificity over vagueness**, **(7) Pre / post / failure conditions on every contract**.
+
+(Companion Sub-Rule Anchor) See `rules/definitiveness-virtues.md` §2 for the seven-virtue numbered list with full prose.
+
+### Definitive form — examples
+
+(Companion Sub-Rule Anchor) See `rules/definitiveness-virtues.md` §3 for Right/Wrong worked examples.
+
+### Airtightness checks beyond hedging
+
+Hedging elimination is the surface signal; airtightness reaches deeper into four checks: **no silent fallbacks**, **no precedence ties**, **no edge cases for later**, **no literal-honoring loopholes**. Intent is the contract; literal text is the carrier.
+
+(Companion Sub-Rule Anchor) See `rules/definitiveness-virtues.md` §4 for the four-check bullet body.
+
+## Disclosure surface
+
+Hedge promotions land as `[Refinement — improvement: definitiveness; from: <hedged>; to: <definitive>; rationale: <driver>]` in the ledger per `rules/disclosure-ledger.md`. Removed prescriptions land as `[Deferral — out-of-scope: prescription removed; tracking: <id>]`. Closed `TBD` / `TODO` / `FIXME` markers carry closure rationale inline.
+
+## Failure tells
+
+(Companion Sub-Rule Anchor) See `rules/definitiveness-virtues.md` §5 for the failure-tells full prose enumeration.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every emitted host-project artifact's pre-emission definiteness check (the seven-virtue floor and the hedging-vocabulary scan). The mechanical hedging-grep at `conformity/hedging_grep.py`. Every `commands/*.md` Step-N closing emission's prose pass. Every `rules/*.md` body shape (every ratified rule sibling honors the same definiteness floor on its own prescriptive prose). The closure clause at every `skills/*/SKILL.md` (every `TBD` / `TODO` / `FIXME` is closed in place or surfaced as an inquiry).
+- **Satisfies →** the fifteen-mandate registry row **M8 — Definitiveness, Airtightness**.
+- **Established by ↑** the fifteen-mandate registry (ratifies M8). `rules/operational-mandates.md` §CM-10 Brutal Honesty (the inward-axis analog M8 cross-maps to; brutal honesty's outward projection is the definiteness floor enforced here).
+- **Gated by ←** `CLAUDE.md` always-loaded preamble. The pre-emission gate at `rules/pre-emission-gate.md` row 8 (M8 mechanical bar; the hedging grep operationalizes this rule's vocabulary list).
+- **Cross-bound with ↔** `rules/definitiveness-virtues.md` (path-filtered companion sub-rule carrying the three hedge-resolution paths with worked examples, the seven-virtue numbered list with full prose, the definitive-form Right/Wrong examples, the airtightness-checks-beyond-hedging bullet body, and the failure-tells full prose). `rules/operational-mandates.md` §CM-10 Brutal Honesty (M8 ↔ CM-10 cross-mapping per PLAN-NOTES.md D1). `rules/disclosure-ledger.md` (M2 — every hedge promotion / removal is recorded in the ledger). `rules/ten-dimension-check.md` (M3 — dimension 2 consistency / coherence + dimension 6 structurality enforce airtightness across artifacts; this rule enforces it within the artifact). `rules/pre-emission-gate.md` (M4 — bar 8 of the gate operationalizes the hedging-vocabulary scan and the pre / post / failure-condition presence check). `rules/authority-inquiry.md` (M5 — removed-prescription cases route to the inquiry surface). `rules/recommend-next-step.md` (M8 — the named action carries no hedging vocabulary; the next-move declaration is binding). `rules/token-efficiency-rewrite.md` (M8 — closed-enumeration exhaustiveness is an L2 invariant of token-efficient rewrites). `rules/determinism.md` (the determinism virtue in M8's rigorous-systems family is the dedicated subject of that rule's byte-stable-output discipline).

package/src/apothem/rules/determinism.md

@@ -0,0 +1,81 @@
+---
+name: "determinism"
+description: "Every rendered option set carries the (Recommended) marker in its answer header, every terminal surface closes with a named next step, and every command, skill, output-style, and statusline surface holds a deterministic output shape — identical inputs produce identically-shaped output. The determinism harness proves the contract mechanically; the marker and next-step semantics are owned by their dedicated rules and this rule consolidates them under the determinism contract."
+pathFilter: "**/commands/**/*.md, **/skills/**/SKILL.md, **/rules/**/*.md, **/output-styles/**/*.md, **/statuslines/**/*.md"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Determinism & Advisory Next-Step
+
+## What this rule enforces
+
+The agent renders option sets and terminal surfaces with a strictly-expected output structure. Three invariants bind as **one** determinism contract:
+
+1. **Marker.** Every rendered option set carries the recommended option's `(Recommended)` marker in its answer header.
+2. **Next step.** Every terminal surface (command, skill, phase) closes with a definitive named next step.
+3. **Shape.** Identical inputs produce identically-shaped output; any non-determinism is declared and its source named.
+
+The harness `conformity/determinism_grep.py` is the executable proof. This rule **consolidates** the marker and next-step semantics owned by `rules/option-annotation.md` and `rules/recommend-next-step.md`; it does not duplicate them — it binds them into the composite contract and adds the output-shape-stability guarantee none of them carries alone.
+
+## Pre-conditions
+
+Applies whenever a command, skill, output-style, statusline, or option-rendering surface is authored or modified.
+
+## 1. The `(Recommended)`-in-header invariant
+
+Every rendered option set MUST carry the recommended option's marker in the answer header: the literal `(Recommended)` postfix at the end of the label, one leading space, bound bidirectionally to the option body's `recommended` value. The canonical placement, separator, case, and bidirectional bind are specified at `rules/interactive-questions-canonical-shapes.md` §2.1; the prose-and-document form uses the inline `**Recommended**` marker per `rules/option-annotation.md`. This rule binds that specification into the determinism contract — it does not restate it.
+
+**Label-only, multi-recommended.** The marker lives SOLELY in the option label. It MUST NOT appear in the accompanying narrative — neither the `rationale:` nor the `recommendation:` body segment carries the postfix string; the body carries verifiable concrete-driver evidence instead. The marker MAY appear on more than one option when the question is `multiSelect: true` (each independently-recommended option carries its own postfix); a `multiSelect: false` question carries the marker on at most one option. A marker string surfacing inside a body/narrative segment is a `narrative-marker-leak` finding at `conformity/option_annotation_grep.py`.
+
+**Concrete-driver requirement.** Every recommended marker MUST carry a rationale grounded in a named concrete-driver class per `rules/option-annotation.md` (locked decision, named risk, named constraint, open-question posture, rule citation, or observed state). A markerless option set where one option dominates, or a recommended marker with no concrete driver, is a defect.
+
+**Call-time enforcement.** Marker well-formedness is checked not only on committed surfaces but on the LIVE `AskUserQuestion` tool payload at call time by the runtime PreToolUse validator (`hooks/askuserquestion_validator.py`), advisory by default and blocking under the strict opt-in. The runtime check guarantees well-formedness (canonical case, placement, at-most-one-per-single-select, never on a destructive option); it cannot force a recommendation to exist — the native payload has no separate recommended field, so a missing marker surfaces only as a heuristic nudge. See `rules/interactive-questions-canonical-shapes.md` §2.1.1.
+
+## 2. The determinant-next-step convention
+
+Every terminal surface MUST close with a `## Recommended Next Step` (or multi-action `## Next Steps`) block naming a definitive, imperative-verb-led action referenced by identifier — never a hedge, never a question, never a silent end-of-document. The canonical block shape and per-surface-class materialization (command, skill, phase) are specified at `rules/recommend-next-step.md`. The matcher `conformity/recommend_next_step_grep.py` enforces presence across command and skill surfaces.
+
+## 3. The deterministic-output contract
+
+Identical inputs MUST produce identically-shaped output. The output-shape-stability contract binds every authored markdown surface — commands, skills, output-styles, statuslines — over its structural signature; the terminal-next-step floor (§2, §4) additionally binds command / skill / phase interaction surfaces, but not output-style and statusline *definition* surfaces (which are not terminal interaction surfaces). The structural signature held stable across runs spans seven dimensions:
+
+1. SPDX authorship-header presence;
+2. the frontmatter key set (where the surface carries frontmatter);
+3. the ordered H2 heading sequence;
+4. the recommended-marker count (`**Recommended**` and `(Recommended)` postfix);
+5. the fenced-code language multiset;
+6. the bindings-section presence;
+7. the terminal next-step form (singular, multi, or absent).
+
+Any non-determinism MUST be declared with its source named — e.g., a surface embedding a generation date marks the date as the non-deterministic element. Undeclared non-determinism — a signature that drifts between identical reads — is a defect. The harness `conformity/determinism_grep.py` computes the signature across repeated reads and asserts byte-stability; a structurally-incomplete surface fails the minimal output-shape floor (header, headings, terminal next-step).
+
+## 4. The advisory-posture invariant
+
+Every interaction MUST close with the single best next action for its current end state. A terminal surface emits exactly one recommended next action calibrated to where the surface ends; a surface ending without a recommended action is a defect. This is the advisory posture: the agent surfaces findings and a forward move, never a silent stop.
+
+## Mechanical enforcement
+
+- `conformity/determinism_grep.py` — composite output-shape signature stability plus the minimal-shape floor, across command and skill surfaces.
+- `conformity/option_annotation_grep.py` — the `(Recommended)` marker placement and bidirectional bind on rendered option sets.
+- `conformity/recommend_next_step_grep.py` — the terminal next-step block presence across command and skill surfaces.
+
+Findings surface at the pre-emission gate per `rules/pre-emission-gate.md`.
+
+## Disclosure surface
+
+- `[Determinism — signature-drift: <surface>; runs: <N>]` when a surface's structural signature is non-deterministic.
+- `[Determinism — incomplete-shape: <surface>; missing: <header | headings | next-step>]` when a surface fails the output-shape floor.
+
+## Failure tells
+
+An option set rendering no `(Recommended)` marker where one option dominates. A recommended marker with no concrete-driver rationale. A command or skill surface ending mid-section with no next-step block. A surface whose structural signature drifts between identical reads with no declared non-determinism source. A terminal surface that stops silently rather than naming the single best next action.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** every command and skill surface's output shape · the `(Recommended)` marker on every rendered option set · the terminal next-step block on every terminal surface · the mechanical harness `conformity/determinism_grep.py`.
+- **Driven by ←** the option-annotation and recommend-next-step conventions this rule consolidates · the pre-emission gate that consumes the harness verdict.
+- **Satisfies →** the strictly-expected-output-structure end state · the advisory posture (findings plus a forward move, never a silent stop).
+- **Established by ↑** `rules/option-annotation.md` · `rules/recommend-next-step.md` · `rules/definitiveness.md` (the determinism virtue).
+- **Cross-bound with ↔** `rules/option-annotation.md` · `rules/recommend-next-step.md` · `rules/interactive-questions-canonical-shapes.md` · `rules/definitiveness.md` · `rules/pre-emission-gate.md`.

package/src/apothem/rules/disclosure-ledger-markers.md

@@ -0,0 +1,58 @@
+---
+name: "disclosure-ledger-markers"
+description: "Path-filtered companion rule carrying the full marker-class enumeration, ledger-completeness detail, rationale-specificity detail, and failure-tells body declared at the parent `disclosure-ledger.md` rule's anchor; demand-loaded on disclosure-bearing artifact touches."
+pathFilter: "**/*.md, **/CLAUDE.md, **/rules/**, **/commands/**, **/skills/**, **/agents/**, **/docs/**, **/.github/**"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Disclosure-Ledger Markers (Companion Sub-Rule)
+
+## Purpose
+
+Specify the marker-class enumeration, ledger-completeness detail, rationale-specificity detail, and failure-tells body that the parent rule `rules/disclosure-ledger.md` anchors. This companion is path-filtered: it loads when the assistant edits any artifact that may carry a disclosure ledger (Markdown, rule, command, skill, agent, doc, or CI surface), keeping the parent's always-on payload lean while preserving full marker fidelity at the demand-load surface. The parent rule remains the canonical home for the M2 standing directive, the marker-class one-line list, the §2 ledger-placement paragraph, and the parent-side bindings; this companion carries the full marker-class bodies and the failure-catalog.
+
+## Obligations
+
+### 1. Marker-Class Enumeration (Full Bodies)
+
+Every disclosure ledger carries the following marker classes inline at the change's hand-off surface (commit message body, PR description, response prose, or the artifact's working-trace section):
+
+- `[Amendment — rationale: <cited rationale per ten-dimension-check.md dimension 9>]` — a deliberate change to the literal request because the literal would have left a known defect (idiom drift, security gap, correctness bug, performance trap). The rationale cites a primary source (RFC, vendor documentation, host-project sibling-file precedent, scholarly reference).
+- `[Extension — adjacent gap surfaced: <description>]` — a widening of the change's scope to address an adjacent gap revealed during execution. The extension is either folded into the change with explicit justification, or surfaced as a finding for the user's decision and deferred.
+- `[Refinement — improvement: <named property>]` — a structural / aesthetic / craft improvement applied alongside the request, with the improved property named (clarity, correctness, performance, maintainability, testability, security, expressiveness).
+- `[Deferral — out-of-scope: <description>; tracking: <where the deferral is tracked>]` — adjacent work intentionally left for a separate change, with the tracking location named (issue tracker entry, follow-up task, watch-item).
+- `[Discovery — source: <path>; value: <discovered>; honored]` — every host-discovered convention applied per `rules/host-discovery.md`.
+- `[Inquiry — id: <inquiry-id>; outcome: <user-choice|fallback-to-recommended>]` — every inquiry-resolved choice per `rules/authority-inquiry.md`.
+- `[Default — applied: <auto-decision>; class: <carve-out class>]` — every auto-decision applied per the carve-out catalog at `rules/authority-inquiry.md` (pure validity, pure rigor, universally-safe security, pure formatting normalization, internal reference repair).
+
+### 2. Ledger Completeness
+
+Every amendment, extension, refinement, deferral, and default the change carries MUST be enumerated. Non-conformant: a change that touches files the user did not name without comment; a change that elides edge cases the user did not specify but a senior engineer would have addressed, with no surfacing of the elision; a "fix" that papers over a deeper bug rather than naming the deeper bug for the user's decision.
+
+### 3. Rationale Specificity
+
+Rationales cite **specific** evidence — never platitudinous (`"this is widely adopted"`), never opinion-only (`"this is better"`), never an appeal to consensus without a named source. Rationale specificity matches the citation form at `rules/ten-dimension-check.md` dimension 9 (scholarly / technical referencing) and the concrete-driver classes at `rules/interactive-questions-canonical-shapes.md` §3.2.1.
+
+### 4. Operator Comprehension — The Ledger Is for Understanding, Not Bookkeeping
+
+A disclosure exists so the operator can **understand** the change, not merely record that it happened. The marker is a comprehension surface, not a receipt: it answers "what changed, why, and what should the operator look at to verify it" — never "a change occurred; details omitted". The proportionality rule: the disclosure's specificity scales with the change's surface area and risk. A one-line ledger entry standing behind a large or non-obvious diff leaves the operator unable to evaluate what they are accepting — the gap between what was changed and what the operator can comprehend from the ledger is **comprehension debt**, and it compounds the way unreviewed loop-generated output compounds.
+
+Closing comprehension debt is the disclosing party's obligation, not the operator's burden: a substantial change names its load-bearing decisions, the surfaces it touched, and the verification the operator can run to confirm it — enough that the operator forms an accurate mental model of the change from the ledger alone, without re-deriving it from the raw diff. A disclosure that records the *fact* of a change while leaving its *substance* opaque has recorded without disclosing.
+
+### 5. Failure Tells
+
+A diff that touches files the user did not name without comment. A response that elides edge cases the user did not specify but a senior engineer would have addressed, with no surfacing that the elision happened. A "fix" that papers over a deeper bug rather than naming the deeper bug. A commit message that says only "fix bug" with a 200-line diff. A PR that widens scope ("while I was here, I also …") with no `[Extension]` marker. A response that says "done" without listing what was done, what was amended, and what was deferred. An `[Amendment]` marker whose rationale is `"this is widely adopted"` without a named source. **Comprehension debt** — a large or non-obvious diff landed behind a one-line ledger entry the operator cannot evaluate without reconstructing the change from the raw diff themselves; the disclosure recorded that something happened without surfacing enough substance for the operator to understand what.
+
+## Enforcement
+
+Path-filtered (the eight glob patterns in this rule's `pathFilter` field), always-on at every seriousness level when in scope. Demand-loaded companion to `rules/disclosure-ledger.md`. The parent rule carries the M2 standing directive, the one-line marker-class list, the §2 ledger-placement paragraph, and the parent-side bindings; this companion carries the full marker-class bodies, the ledger-completeness detail, the rationale-specificity detail, and the failure-tells catalog.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every disclosure-ledger emission across every host-project artifact (the seven marker classes are the complete vocabulary). ● Every commit body, PR description, response prose, and phase rollup report's Disclosure Surface section. ● The completeness invariant at every change hand-off (§2 — every amendment / extension / refinement / deferral / default enumerated). ◐ The pre-emission gate's M2 row at `rules/pre-emission-gate.md`.
+- **Satisfies →** ● the fifteen-mandate registry row **M2 — Editorial Discipline** (companion-tier). ● `rules/disclosure-ledger.md` parent-rule anchor (the parent's pointer to this companion's full marker-class bodies and failure catalog).
+- **Established by ↑** ● `rules/disclosure-ledger.md` (parent-rule anchor). ● the fifteen-mandate registry (ratifies M2).
+- **Gated by ←** ● The path-filter (the eight glob patterns) — this rule demand-loads only on disclosure-bearing artifact touches. ● `rules/disclosure-ledger.md` always-on baseline (parent rule must be live for the anchor to surface).
+- **Cross-bound with ↔** ↔ `rules/disclosure-ledger.md` (parent rule; the anchor binds this companion). ↔ `rules/host-discovery.md` (M1 — `[Discovery — …]` markers). ↔ `rules/authority-inquiry.md` (M5 — `[Inquiry — …]` and `[Default — …]` markers). ↔ `rules/expertise-posture.md` (M6 — `[Amendment]` / `[Extension]` / `[Refinement]` markers driven by expertise). ↔ `rules/ten-dimension-check.md` (M3 — rationale citations meet dimension 9). ↔ `rules/pre-emission-gate.md` (M4 — `amendments-disclosed` array population).

package/src/apothem/rules/disclosure-ledger.md

@@ -0,0 +1,52 @@
+---
+name: "disclosure-ledger"
+description: "Disclosed amendments, never silent — every change of meaningful scope carries an explicit ledger of what was asked, what was amended, what was extended, and what was deferred, with cited rationale."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Disclosure Ledger — Disclosed Amendments, Never Silent
+
+## What this rule enforces
+
+This rule binds **M2 — Editorial Discipline**. When expertise reveals a better form than the literal request would produce — a stale idiom, a subtle bug, a missing edge case, a security gap, a maintainability regret, an adjacent gap the change implicates — the agent MUST proactively amend the work to address it, and MUST disclose every amendment. The disclosure carries a rationale at the scholarly / technical bar (cited reference, RFC, vendor docs, sibling-file precedent, named pattern). Two symmetric failures: **silent over-compliance** (did exactly what was asked, even though it was wrong) and **silent over-reach** (widened scope without saying).
+
+## Pre-conditions
+
+Applies to every change of meaningful scope per the trivial-vs-non-trivial threshold — above the trivial threshold (single-file edit ≤ 5 lines AND no public-API change AND no behavioral shift). The ledger MUST ship in the same change-set as the artifact it covers — never deferred to a later commit / PR / response.
+
+## Required behavior
+
+### 1. Ledger structure (Companion Sub-Rule Anchor)
+
+Every ledger carries seven marker classes inline at the change's hand-off surface: `[Amendment]`, `[Extension]`, `[Refinement]`, `[Deferral]`, `[Discovery]`, `[Inquiry]`, `[Default]`. Each class's placeholder shape, rationale-citation requirement, and carve-out enumeration live at the companion. (Companion Sub-Rule Anchor) See `rules/disclosure-ledger-markers.md` §1.
+
+### 2. Ledger placement
+
+The ledger lives at the change's hand-off boundary — the surface a reviewer encounters first: commit-message body for commits; PR description for PRs; closing summary section for multi-file responses; phase-level rollup report's Disclosure Surface section for multi-step work.
+
+### 3. Ledger completeness (Companion Sub-Rule Anchor)
+
+Every amendment, extension, refinement, deferral, and default the change carries MUST be enumerated; silent over-compliance and silent over-reach are both non-conformant. (Companion Sub-Rule Anchor) See `rules/disclosure-ledger-markers.md` §2.
+
+### 4. Rationale specificity (Companion Sub-Rule Anchor)
+
+Rationales MUST cite specific evidence at the scholarly / technical bar; platitudinous, opinion-only, or consensus-appeal phrasings without a named source are non-conformant. (Companion Sub-Rule Anchor) See `rules/disclosure-ledger-markers.md` §3.
+
+## Disclosure surface
+
+The ledger itself IS the disclosure surface. It MUST NOT be compressed under concision pressure (`output-styles/*.md` preserve disclosure markers per the fifteen-mandate registry row M2). When an output style flattens the ledger, the agent surfaces that flattening as an M2 non-conformity in its own pre-emission self-check per `rules/pre-emission-gate.md`.
+
+## Failure tells (Companion Sub-Rule Anchor)
+
+Undisclosed file touches, elided edge cases, paper-over fixes, vacuous commit messages, scope-widening PRs without `[Extension]` markers, vague-rationale `[Amendment]` markers. (Companion Sub-Rule Anchor) See `rules/disclosure-ledger-markers.md` §4.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every meaningful-scope change's hand-off surface (commit body, PR description, response prose, phase rollup report). The amendment-class disclosures every `agents/*.md` return format must carry per the fifteen-mandate registry row M2. The change-ledger preservation requirement at `output-styles/*.md`.
+- **Satisfies →** the fifteen-mandate registry row **M2 — Editorial Discipline**.
+- **Established by ↑** the fifteen-mandate registry (ratifies M2). The change's hand-off surface (commit message / PR / response).
+- **Gated by ←** The §8.1 trivial-vs-non-trivial threshold (trivial work is exempt from the ledger requirement). `CLAUDE.md` always-loaded preamble.
+- **Cross-bound with ↔** `rules/disclosure-ledger-markers.md` (path-filtered companion sub-rule carrying the §1 full marker-class enumeration, §3 ledger-completeness detail, §4 rationale-specificity detail, and the failure-tells catalog). `rules/host-discovery.md` (M1 — discoveries are recorded in the ledger as `[Discovery — …]` markers). `rules/expertise-posture.md` (M6 — expertise drives the amendments and refinements; the ledger discloses them). `rules/operational-mandates.md` §CM-10 Brutal Honesty (the ledger is the outward-projection form of CM-10's inward truth-telling discipline). `rules/ten-dimension-check.md` (M3 — rationale citations meet the scholarly / technical referencing dimension). `rules/pre-emission-gate.md` (M4 — disclosed amendments populate the `amendments-disclosed` array of the gate attestation). `rules/dynamism.md` (M2 — static-to-dynamic conversions and new-surface inquiry outcomes recorded in the ledger). `rules/plain-language.md` (M2 — plain-language interceptions recorded in the ledger). `rules/recommend-next-step.md` (M2 — block emissions and refreshes recorded in the ledger). `rules/harness-adapter-shape.md` (M2 — every discovery, pin refresh, and declared divergence recorded in the ledger). `rules/i18n-discipline.md` (M2 — per-locale outcomes recorded in the ledger). `rules/etc-extension.md` (M2 — every applied enumeration extension is recorded as an `[Extension]` marker). `rules/source-accessibility.md` (M2 — every source-trust decision is recorded as a ledger entry). `rules/authoritative-referencing.md` (M2 — every claim's source citation meets the rationale-citation bar recorded here). `rules/session-closure.md` (M2 — the formal session close's done/deferred ledger records its deferrals with the `[Deferral — …]` marker owned here, and the completed column is the change's disclosure surface).