@ahmed-g-gad/apothem 0.1.1

package/src/apothem/rules/interactive-questions-detail.md

@@ -0,0 +1,41 @@
+---
+name: "interactive-questions-detail"
+description: "Path-filtered companion to interactive-questions.md carrying the authoring-discipline procedure and the anti-pattern catalog; demand-loaded on path match when a surface authors structured-inquiry invocations."
+pathFilter: "**/commands/**/*.md, **/rules/**/*.md, **/skills/**/*.md, **/agents/**/*.md, **/hooks/**/*.md"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Interactive-Questions Authoring Detail & Anti-Patterns (Companion Sub-Rule)
+
+## Purpose
+
+Carry the demand-load detail for the always-on parent `rules/interactive-questions.md`: the authoring-discipline procedure and the anti-pattern catalog. Loads on path match when a surface authors structured-inquiry invocations, so the detail pays its context cost only where questions are written.
+
+## Authoring Discipline
+
+Author every invocation in five ordered steps:
+
+1. **Write the question first.** One sentence ending in `?`, naming the decision — not the implementation. The question fixes the decision space before any option is drafted.
+2. **Derive options from the decision space.** Each option is a distinct, reachable outcome of the question. Two-to-four options (the choice-overload bound); the implicit `Other` covers the long tail. Labels are 1–5 words.
+3. **Annotate each option** with the three-segment body per `rules/interactive-questions.md` §3: `rationale:` (observable consequence) · `recommendation:` (taxonomy value) · `default-pointer:` (named default OR `no-default: user decision required`).
+4. **Cite a concrete driver** on every non-neutral `recommendation:` value (`recommended` / `discouraged` / `destructive-no-default`) — one of the six driver classes; never a vague-rationale phrase. Downgrade to `acceptable` when no driver supports the claim.
+5. **Review before emission** for the four invariants: driver presence (§4), destructive-op no-default floor (§6), label↔body `(Recommended)` consistency (§3 bidirectional bind), and the two-to-four cardinality bound.
+
+## Anti-Patterns
+
+- **DON'T** issue a raw "Please confirm…" / "Which of…" / imperative-plus-`?` as primary input — **BECAUSE** it bypasses the schema and the annotation that biases-check the choice.
+- **DON'T** batch destructive files into one invocation — **BECAUSE** per-file confirmation is the floor; one irreversible decision per invocation.
+- **DON'T** mark a non-neutral recommendation without a concrete-driver why-clause — **BECAUSE** an un-driven nudge biases the operator invisibly.
+- **DON'T** name a default on a destructive question — **BECAUSE** it makes the irreversible action the easy path; destructive ops are universally `no-default`.
+- **DON'T** put `(Recommended)` on more than one option in a single-select question, or on a non-`recommended` body — **BECAUSE** the label↔body bind is bidirectional and a stray postfix corrupts the signal.
+- **DON'T** fall back to prose silently when structured inquiry is available — **BECAUSE** the degradation MUST be logged with the conversation marker and a ledger row.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** The authoring review every structured-inquiry invocation passes before emission; the anti-pattern checks the parent §8 sweep matchers operationalize.
+- **Satisfies →** The demand-load detail tier for the parent `interactive-questions.md` authoring discipline and anti-pattern catalog.
+- **Established by ↑** `rules/interactive-questions.md` (the always-on parent this companion carries detail for, per the parent / companion-sub-rule pattern).
+- **Gated by ←** The `pathFilter` glob (demand-loads only when a question-authoring surface is touched).
+- **Cross-bound with ↔** `rules/interactive-questions.md` (parent — §9 Authoring Discipline and the Anti-Patterns catalog were moved here under the companion-sub-rule pattern); `rules/interactive-questions-canonical-shapes.md` and `rules/interactive-questions-sweep-matchers.md` (sibling companions carrying the schema worked-examples and the H1–H7 matcher catalog).

package/src/apothem/rules/interactive-questions-sweep-matchers.md

@@ -0,0 +1,184 @@
+---
+name: "interactive-questions-sweep-matchers"
+description: "Path-filtered companion rule carrying the canonical-channel sweep matcher specifications (H1–H7); demand-loaded when the parent `interactive-questions.md` rule's §8 anchor surfaces."
+pathFilter: "**/commands/**/*.md, **/rules/**/*.md, **/skills/**/*.md, **/agents/**/*.md, **/hooks/**/*.md, **/CLAUDE.md, **/settings.json"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Interactive-Questions Sweep Matchers (Companion Sub-Rule)
+
+## Purpose
+
+Specify the executable matcher catalog for the canonical-channel compliance gate declared at the parent rule's `rules/interactive-questions.md` §8 anchor. This companion is path-filtered: it loads when the assistant edits any of the governed-core surfaces the matchers sweep, keeping the parent's always-on payload lean while preserving full matcher fidelity at the demand-load surface. The parent rule remains the canonical home for the canonical-channel obligation, the three-segment option-annotation schema, the recommendation taxonomy, the harness fallback, the per-file destructive-op confirmation, and the default-pointer convention; this companion carries the H1–H7 sweep matcher catalog.
+
+## Obligations
+
+### 1. Heuristic Catalog (H1–H7)
+
+The compliance gate sweeps for two heuristic classes: conversational-form heuristics (H1–H3), which detect raw conversational prompts that bypass the canonical channel; and annotation-compliance heuristics (H4–H7), which detect structured-inquiry invocation payloads that violate the option-annotation schema.
+
+- **H1 — Imperative + question mark.** A sentence opens with an imperative verb ("Confirm", "Approve", "Choose", "Select", "Pick", "Decide") and ends with `?`. Exemption: the phrase appears inside a code fence, a blockquote marked as preserved conversation, or a raw-notes context explicitly tagged as the parent rule's §1 exception 1 material.
+- **H2 — "Please confirm" / "Please approve" / "Please choose".** The literal phrase appears as a primary input prompt. Same exemption as H1.
+- **H3 — "Which of the following".** The phrase opens a primary input prompt without an immediately preceding structured-inquiry invocation. Same exemption as H1.
+- **H4 — Option without three-segment body.** A structured-inquiry invocation has any option whose `description` lacks any of the three canonical segments (`rationale:`, `recommendation:`, `default-pointer:`).
+- **H5 — Non-neutral recommendation without concrete driver.** A `recommendation:` body value is `recommended`, `discouraged`, or `destructive-no-default`, and the same body segment carries no concrete-driver why-clause of the form admissible by `rules/interactive-questions-canonical-shapes.md` §3.2.1.
+- **H6 — Label–body mismatch and cardinality.** An option's label carries the `(Recommended)` postfix but its body `recommendation:` value is not exactly `recommended`; an option's body value is exactly `recommended` and its own label does not carry the postfix; or a `multiSelect: false` question carries more than one recommended option. `multiSelect: true` questions may carry multiple recommended options when each label/body pair matches.
+- **H7 — Destructive op without `no-default` floor.** A `recommendation:` body value is `destructive-no-default` and the same option's `default-pointer:` is not the `no-default: user decision required` form; or a question has at least one option marked `destructive-no-default` and another option in the same question carries a named default.
+
+Every heuristic hit is a gate finding at severity HIGH unless the artifact is outside the interactive-surface catalog's compliance scope (fallback-permitted harnesses recording a compliant fallback use, raw-notes preservation contexts per §3). The H6 sweep is bidirectional — it checks both label→body and body→label.
+
+### 2. Sweep Scope
+
+The zero-match sweep runs across the ecosystem's governed-core tree:
+
+- `commands/` — all `.md` files
+- `rules/` — all `.md` files
+- `skills/` — recursive, all `.md` / `.py` / `.sh` / `.ps1` / `.json` files
+- `agents/` — all flat `<name>.md` entry points
+- `hooks/` — recursive, all `.py` / `.sh` / `.ps1` / `.md` / `.json` files
+- `settings.json` in the harness config root — root-level hook-configuration file
+- `CLAUDE.md` — root-level ecosystem-config file
+
+The sweep does not recurse into `<project-root>/.apothem/plans/` (plan-suite internal artifacts are exempt from the gate) or `<harness-root>/projects/` (per-project memory outside ecosystem authorship).
+
+### 3. Exclusion Zones
+
+Hits inside the following contexts are exempt from the zero-match verdict:
+
+- **Raw-notes contexts** per the parent rule's §1 exception 1 — quoted conversational material preserved for audit fidelity. Preservation is explicit: the artifact declares itself as a preservation artifact (frontmatter `purpose: preserved-conversation` marker, or an enclosing `<raw-notes>…</raw-notes>` fence, or a blockquote whose preceding paragraph labels the block as preserved conversation).
+- **Parent rule's own §1, §5, §6, and §Anti-Patterns bodies** — the parent rule specifies the patterns it regulates; the self-referential citations are definitional. The §1 Scope statement, the §5.2 fallback-shape worked example, the §6.4–§6.7 canonical option-set subsections, and the §Anti-Patterns first bullet may quote the forbidden phrases verbatim for definitional purposes.
+- **This companion rule's own §1 H1–H7 catalog body** — the catalog specifies the patterns it regulates; its self-referential citations of the H1, H2, H3 trigger phrases are definitional and exempt.
+- **Migration-ledger paths** — `ecosystem-remediation-ledger.md` and every per-sub-phase `ledger-fragment.md` under `.apothem/plans/*/phases/*/` may quote forbidden phrases as "before-state" evidence of a migration.
+- **Code fences and blockquotes tagged as preserved conversation** — inline preservation anchors inside otherwise-non-exempt files.
+
+### 4. Sweep Invocation Specification — H1–H3 (Conversational-Form)
+
+The sweep uses ripgrep with the following per-heuristic invocations. Each invocation returns a hit count; the gate passes when every count equals the number of hits inside exclusion zones.
+
+| Heuristic | Pattern (ripgrep regex) | Case | Exclusion-zone count |
+|-----------|-------------------------|------|----------------------|
+| H1 | `^(Confirm\|Approve\|Choose\|Select\|Pick\|Decide\|Specify\|Indicate)\b.*\?$` | literal | 0 active hits; 1 definitional reference at this companion's §1 H1 (inside quote marks, exempt) |
+| H2 | `Please (confirm\|approve\|choose\|select)` | case-insensitive | 0 active hits; definitional references at the parent rule's §1, this companion's §1 H2, and the parent rule's §Anti-Patterns |
+| H3 | `Which of (the following\|these)` | case-insensitive | 0 active hits; definitional references at the parent rule's §1 and this companion's §1 H3 |
+
+Reproducible invocation from the ecosystem root (identical in POSIX bash and PowerShell 7+ since ripgrep is cross-platform):
+
+```sh
+rg --no-heading -nP '^(Confirm|Approve|Choose|Select|Pick|Decide|Specify|Indicate)\b.*\?$' \
+  commands/ rules/ skills/ agents/ hooks/ settings.json CLAUDE.md
+
+rg --no-heading -ni 'Please (confirm|approve|choose|select)' \
+  commands/ rules/ skills/ agents/ hooks/ settings.json CLAUDE.md
+
+rg --no-heading -ni 'Which of (the following|these)' \
+  commands/ rules/ skills/ agents/ hooks/ settings.json CLAUDE.md
+```
+
+### 5. Gate Admission — Interactive-Channel Compliance
+
+The interactive-channel compliance gate is a named member of the airtightness composite alongside the numeric gates (5–19) and the other two named gates (Portability Gate, Kerning Gate). The gate's pass predicate is:
+
+- For every conversational-form heuristic H1–H3: total hit count equals the documented exclusion-zone count. Equivalently, every conversational-question pattern that appears in the ecosystem is inside a declared exclusion zone (§3).
+- For every annotation-compliance heuristic H4–H7: zero hits. The annotation sweep has no exclusion zone — every structured-inquiry invocation in the ecosystem must satisfy the annotation schema (parent rule's §3 three-segment body, §4 recommendation taxonomy, §6.2 default-floor on destructive ops, §3 bidirectional label-postfix rule).
+
+Gate failures at HIGH severity block the composite's pass verdict. The gate's downstream enforcement arm is the semantic blind re-audit in the diagnostic phase, which re-executes §4's sweep specifications and verifies the exclusion-zone count matches the documented values. A drift (e.g., the H2 exclusion count rises without a corresponding definitional-use change recorded in the remediation ledger) is itself a gate finding.
+
+### 6. H4–H7 Machine Matchers — Annotation-Compliance Heuristics
+
+H4–H7 sweep the structured-inquiry invocation payloads themselves rather than free-form prose. Each heuristic's matcher semantics are specified below.
+
+#### 6.1 H4 — Body-Segment Omission
+
+**Pass predicate:** every option's `description` field contains all three body-segment markers `rationale:`, `recommendation:`, and `default-pointer:` in that order, separated by newlines or period-space per the parent rule's §3.
+
+**Matcher:** for each structured-inquiry invocation, walk every option; for each option, test that its `description` string contains all three segment-marker tokens (case-sensitive literal match). Absence of any one token = HIGH-severity hit.
+
+**Normative source:** parent rule's §3 Three-Segment Option Annotation.
+
+#### 6.2 H5 — Non-Neutral Recommendation Without Concrete Driver
+
+**Pass predicate:** every option whose body `recommendation:` value is one of `{recommended, discouraged, destructive-no-default}` carries a why-clause that cites at least one admissible driver class per `rules/interactive-questions-canonical-shapes.md` §3.2.1 AND does not match any phrase on `rules/interactive-questions-canonical-shapes.md` §3.2.2 forbid list.
+
+**Matcher:** for each option, extract the body `recommendation:` value. If the value is `acceptable`, skip (neutral; no driver required). Otherwise, extract the why-clause (text after the `—` em-dash separator on the `recommendation:` segment line, up to the next newline). Test:
+
+- **Admissibility test** — the why-clause contains at least one token from the six driver-class signature set: (1) a decision identifier of shape `D-\d+` or equivalent; (2) a risk identifier of shape `R-\d+`; (3) a constraint identifier of shape `C-\d+`; (4) an open-question identifier of shape `OQ-\d+`; (5) a rule-file path of shape `rules/*.md §X.Y.Z`; (6) an observed-state citation pattern — a measured metric + source, a file path + line range, a gate-result citation. At least one signature token must match.
+- **Forbid-list test** — the why-clause does NOT contain any literal phrase from `rules/interactive-questions-canonical-shapes.md` §3.2.2 vague-rationale forbid list (case-insensitive). A match on the forbid list is a HIGH-severity hit even when an admissible token is also present (the forbid phrase must be removed or the recommendation downgraded to `acceptable`).
+
+**Normative source:** `rules/interactive-questions-canonical-shapes.md` §3.2.1 Driver Taxonomy + §3.2.2 Vague-Rationale Forbid List.
+
+#### 6.3 H6 — Label-Postfix ↔ Body-Value Bidirectional Consistency
+
+**Pass predicate:** for every option, the bidirectional bind holds — `label` ends with ` (Recommended)` IFF body `recommendation:` value is exactly `recommended`. Additionally, `multiSelect: false` invocations have zero or one recommended option; `multiSelect: true` invocations may have one or more recommended options.
+
+**Matcher:** for each option, extract the `(label, description)` coupled pair. Compute two booleans:
+
+- `label_has_postfix` — the `label` string ends with the exact suffix ` (Recommended)` (one leading space, literal past-participle wrapped in parentheses, no trailing whitespace or punctuation).
+- `body_is_recommended` — the body `recommendation:` value is exactly the string `recommended`.
+
+Three failure modes (all HIGH-severity):
+
+- **Missing postfix (body→label direction):** `body_is_recommended = true` AND `label_has_postfix = false`.
+- **Spurious postfix (label→body direction):** `label_has_postfix = true` AND `body_is_recommended = false`.
+- **Single-select multi-postfix:** invocation `multiSelect = false` AND more than one option has `body_is_recommended = true`.
+
+Options with body values `acceptable`, `discouraged`, or `destructive-no-default` MUST carry no label postfix — absence is the normal state, not a finding. Multiple recommended options are compliant only on non-exclusive `multiSelect: true` invocations.
+
+**Normative source:** parent rule's §3.1 Label Postfix Convention.
+
+#### 6.4 H7 — Destructive-Op Missing No-Default Floor
+
+**Pass predicate:** every option in a destructive-op invocation carries the verbatim string `no-default: user decision required` on its `default-pointer:` segment.
+
+**Matcher:** for each structured-inquiry invocation, determine whether it is a destructive-op invocation by two signals:
+
+1. **Op-type signal:** the invocation's option set matches one of the parent rule's §6.4–§6.7 canonical option-set templates (delete/rename/move/revert-uncommitted) by label-set intersection — the canonical set labels are `{Retire, Keep, Defer, Explain-first}` (§6.4), `{Rename-as-proposed, Keep-current, Propose-alternative, Defer}` (§6.5), `{Move-as-proposed, Keep-current, Propose-alternative, Defer}` (§6.6), `{Discard, Keep, Stash-for-later, Defer}` (§6.7).
+2. **Taxonomy-value signal:** any option carries body `recommendation: destructive-no-default` (per the parent rule's §4.1 this is the destructive-irreversible taxonomy value).
+
+An invocation satisfying either signal is a destructive-op invocation. For every option in such an invocation, test that the `default-pointer:` segment contains the verbatim string `no-default: user decision required`. Failure = HIGH-severity hit.
+
+Two sub-conditions of H7:
+
+- **Missing no-default marker** — the destructive-op invocation's option has a named-default pointer instead of the verbatim no-default marker.
+- **Contradictory pointer mix** — the invocation has at least one option marked `destructive-no-default` and another option carries a named-default pointer (the parent rule's §6.2 consistency rule is violated).
+
+**Normative source:** parent rule's §6.2 Default Floor + §6.8 Invocation-Shape Invariants + §7.3 Destructive-Op Invariant.
+
+### 7. Payload Inspection Procedure
+
+The H4–H7 matchers operate on structured-inquiry invocation payloads extracted from two source surfaces:
+
+- **Native invocations** — call sites where the tool is invoked with a `questions` array. Extraction uses static pattern matching on the tool-invocation syntax (e.g., in command `.md` specifications that describe an invocation inline with `question: … / header: … / options: [ label / description / multiSelect ]` block form, or in the skill-template `{…}` block form). The matcher walks the `questions` array, then each question's `options` array, then each option's `label` and `description` pair.
+- **Fallback prose mirrors** (per the parent rule's §5.2) — the fallback prose shape is a faithful mirror of the tool's schema. Extraction uses the fallback-form parser: the closing instruction `Reply with the label of your choice.` (or the multi-select variant) delimits the option list; each bullet `- <label>: <three-segment body>` is parsed into `(label, description)`.
+
+For H6 (label-postfix ↔ body-value), the matcher treats `label` and `description` as a coupled pair — extracting the trailing parenthetical from `label` and the `recommendation:` segment from `description` together so both booleans in §6.3's pass predicate can be computed from a single option's payload.
+
+For H7 (destructive-op no-default), the matcher first classifies the invocation as destructive using the §6.4 op-type and taxonomy-value signals, then walks every option's `default-pointer:` segment.
+
+Exemption: the §3 exclusion zones apply equally to H4–H7. Invocation payloads inside the canonical-shapes companion's body (e.g., its §2.1, §2.2, §5.2, §3.2.4 worked examples) are definitional uses; the companion specifies the patterns it regulates, and its own worked examples are the normative source. The rule self-citation exemption covers these; the companion's §3.2.4 "Before" anti-example is specifically designed as a non-compliant example demonstrating the pattern to avoid and is covered by the rule-self-citation exemption.
+
+### 8. Sweep Invocation Specification — H4–H7
+
+Each H4–H7 heuristic has a reproducible sweep invocation. Because H4–H7 operate on structured payloads rather than line-oriented prose, the invocations use an AST-walk or JSON-path parser where the source format supports it; for Markdown source artifacts, the invocations combine ripgrep with structural context (`--multiline` and `--no-heading` flags).
+
+| Heuristic | Incantation sketch (Markdown source — the tooling sub-phase materializes a full script) |
+|-----------|------------------------------------------------------------------------------------------|
+| H4 | `rg --multiline --no-heading -U 'structured inquiry[\s\S]*?options:[\s\S]*?(?:label:.*?(?!.*rationale:).*?(?!.*recommendation:).*?(?!.*default-pointer:))' <scope>` — matches any option block missing any of the three body-segment markers |
+| H5 | Two-pass: (pass 1) `rg -nP 'recommendation:\s+(recommended\|discouraged\|destructive-no-default)\b([^\n]*)' <scope>` to enumerate non-neutral recommendations; (pass 2) for each match, verify the tail `[^\n]*` contains at least one driver-class signature token (D-/R-/C-/OQ-/rule-path/observed-state pattern) AND does not contain any forbid-list phrase |
+| H6 | Two linked passes plus a cardinality pass: (a) `rg -nP '^\s+label:\s+.+(?<! \(Recommended\))$' <scope>` enumerating labels NOT ending with the canonical postfix, paired with their option's body `recommendation:` segment — hit when the body value is `recommended` (missing-postfix direction); (b) `rg -nP '^\s+label:\s+.+ \(Recommended\)$' <scope>` enumerating labels ending with the canonical postfix, paired with their option's body `recommendation:` segment — hit when the body value is not `recommended` (spurious-postfix direction); a label ending with the lowercase ` (recommended)` variant is itself a non-canonical-case hit; (c) count recommended options per invocation and hit when `multiSelect: false` has more than one |
+| H7 | Two-step: (step 1) classify invocation as destructive by (a) label-set intersection with the parent rule's §6.4–§6.7 canonical sets OR (b) any option carrying `recommendation: destructive-no-default`; (step 2) for every option in a destructive invocation, verify `default-pointer:` segment contains the verbatim literal `no-default: user decision required` — hit on any option where the verbatim string is absent |
+
+The annotation-compliance-sweep tooling materializes these sketches into a single runnable sweep script (POSIX bash + PowerShell 7+ equivalents) honoring the §4 cross-platform convention. The sweep script's executable matcher implementations are the authoritative realization of these specifications.
+
+## 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/interactive-questions.md` §8. The parent rule carries the canonical-channel obligation, the option-annotation schema, the recommendation taxonomy, the harness fallback, the per-file destructive-op confirmation, and the default-pointer convention; this companion carries the H1–H7 sweep matcher catalog. Together they constitute the canonical specification for user-input surface discipline and interactive-channel compliance heuristics.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● The H1–H7 heuristic sweep across the governed-core surface classes (commands, rules, skills, agents, hooks, `settings.json`, `CLAUDE.md`). ● The interactive-channel compliance gate's pass/fail verdict (§5 Gate Admission). ● The `scripts/dev/validate_ecosystem.py --check option-annotation` subcommand (the H4–H7 annotation-compliance matchers operationalize here). ◐ The semantic blind re-audit in the diagnostic phase (the gate's downstream-enforcement arm).
+- **Satisfies →** ● CM-2 extension (rule-delegated companion sub-rule). ● the rules registry row "Interactive Questions Sweep Matchers". ● `rules/interactive-questions.md` §8 anchor (the parent rule's pointer to this companion's full executable matcher catalog).
+- **Established by ↑** ● `rules/interactive-questions.md` §8 (parent-rule anchor). ● CM-2 extension. ● Option Annotation Discipline (the mandate the H4–H7 matchers enforce).
+- **Gated by ←** ● The path-filter (the eight glob patterns) — this rule demand-loads only on governed-core surface touches. ● `rules/interactive-questions.md` always-on baseline (parent rule must be live for the §8 anchor to surface).
+- **Cross-bound with ↔** ↔ `rules/interactive-questions.md` (parent rule; §8 anchor binds this companion). ↔ `scripts/dev/validate_ecosystem.py` (the `--check option-annotation` subcommand operationalizes the H4–H7 matchers; this rule specifies the matchers' executable semantics). ↔ `rules/operational-mandates.md` (CM-2 zero-assumptions's structured-inquiry surface delegates to the parent rule, which delegates the matcher catalog here).

package/src/apothem/rules/interactive-questions.md

@@ -0,0 +1,89 @@
+---
+name: "interactive-questions"
+description: "Canonical discipline for soliciting user input — the harness-neutral structured-inquiry channel is the sanctioned abstraction; every invocation carries a structured option annotation; destructive operations and ambiguity resolution route through this rule; a prose fallback shape covers harnesses that lack a native tool."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Interactive Questions
+
+## Purpose
+
+Govern every act of soliciting user input. One abstraction, one schema, one fallback.
+
+## Obligations
+
+### 1. Canonical Channel
+
+The structured-inquiry channel is the **sole** sanctioned abstraction. Every surface **MUST** route through its native tool or documented fallback; free-form conversational prompts as primary input are retired. Three narrow exceptions: raw-notes preservation (quote, never reissue); fallback-prose per §5; harness-emitted dialogs outside this rule's scope.
+
+### 2. Structured-Inquiry Shape (Companion Sub-Rule Anchor)
+
+Every invocation carries `question` (one sentence ending `?`), `header` (≤12 chars), `options` (2–4, auto-implicit `Other`), `multiSelect`. Each option carries `label` (1–5 words) and `description` (three-segment body per §3).
+
+(Companion Sub-Rule Anchor) See `rules/interactive-questions-canonical-shapes.md` §1 for worked examples.
+
+### 3. Three-Segment Option Annotation (Companion Sub-Rule Anchor)
+
+Every `description` carries three fixed-order segments: **rationale:** (observable consequence) · **recommendation:** (taxonomy value per §4; driver why-clause when non-neutral) · **default-pointer:** (named default OR `no-default: user decision required`). The label ` (Recommended)` postfix bidirectionally binds the body value `recommended`: single-select carries at most one recommended option; `multiSelect: true` MAY mark several.
+
+(Companion Sub-Rule Anchor) See `rules/interactive-questions-canonical-shapes.md` §2 for the full schema, label-postfix specification, and failure modes.
+
+### 4. Recommendation Taxonomy (Companion Sub-Rule Anchor)
+
+Closed taxonomy `{recommended, acceptable, discouraged, destructive-no-default}`. Non-neutral values **MUST** cite a concrete driver; vague phrases are forbidden as sole justification — downgrade to `acceptable`.
+
+(Companion Sub-Rule Anchor) See `rules/interactive-questions-canonical-shapes.md` §3 for the driver taxonomy, forbid list, downgrade path, and extension protocol.
+
+### 5. Harness Fallback (Companion Sub-Rule Anchor)
+
+When the harness exposes neither direct nor deferred structured inquiry, the prose fallback fires: a prose prompt mirroring the schema, the conversation marker `[FALLBACK — structured-inquiry channel unavailable]`, and a ledger row in `ecosystem-remediation-ledger.md`. Outside this context, free-form prose as primary input is forbidden.
+
+(Companion Sub-Rule Anchor) See `rules/interactive-questions-canonical-shapes.md` §4 for the activation predicate, prose-shape example, and ledger schema.
+
+### 6. Per-File Destructive-Op Confirmation (Companion Sub-Rule Anchor)
+
+Every destructive op (delete, rename, move, overwrite, revert-uncommitted) **MUST** route through the channel per file — never batched. Every option carries `default-pointer: no-default: user decision required`; `multiSelect: true` is non-compliant; ` (Recommended)` **MUST NOT** mark a destructive option.
+
+(Companion Sub-Rule Anchor) See `rules/interactive-questions-canonical-shapes.md` §5 for the canonical option-sets (Delete / Rename / Move / Revert) and invariants.
+
+### 7. Default-Pointer Convention (Companion Sub-Rule Anchor)
+
+Two forms: **named-default** (`<label> — <rationale>`, identical across options) or **no-default** (the verbatim `no-default: user decision required`). Destructive ops universally use no-default per §6.
+
+(Companion Sub-Rule Anchor) See `rules/interactive-questions-canonical-shapes.md` §6 for worked examples.
+
+### 8. Pattern-Detection Heuristics (Companion Sub-Rule Anchor)
+
+The interactive-channel gate sweeps for conversational-prompt patterns and annotation compliance. The H1–H7 matcher catalog lives at `rules/interactive-questions-sweep-matchers.md`; its §3 exempts this rule's §1, §5, §6, Anti-Patterns as definitional. HIGH findings block the airtightness composite. The runtime PreToolUse `AskUserQuestion` validator additionally checks `(Recommended)`-marker well-formedness on the LIVE tool payload at call time (advisory by default; the strict opt-in blocks), closing the previously documented-but-unenforced call-time gap; see `rules/interactive-questions-canonical-shapes.md` §2.1.
+
+### 9. Authoring Discipline (Companion Sub-Rule Anchor)
+
+Write the question first; derive options; annotate; review. (Companion Sub-Rule Anchor) See `rules/interactive-questions-detail.md` §Authoring Discipline for the full five-step procedure.
+
+## Seriousness Scaling
+
+| Level | Discipline |
+| ----- | ---------- |
+| EXPLORING | Channel active; annotation encouraged; driver advisory |
+| PERSONAL_USE | Channel + annotation + driver + per-file destructive confirmation mandatory |
+| SHARED | Full; sweep on every change; ledger tagging mandatory |
+| PUBLIC_LAUNCH | Zero tolerance; heuristic hits block; sweep is a numbered airtightness gate |
+
+## Anti-Patterns (Companion Sub-Rule Anchor)
+
+Six anti-patterns: schema-bypassing raw prompts, destructive batching, driver-less recommendation, destructive named-default, `(Recommended)` signal violation, silent fallback. (Companion Sub-Rule Anchor) See `rules/interactive-questions-detail.md` §Anti-Patterns for full bodies.
+
+## Enforcement
+
+Always-on. Implements CM-2 extension. Detail-tier at `rules/interactive-questions-canonical-shapes.md`; matchers at `rules/interactive-questions-sweep-matchers.md`.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every structured-inquiry invocation across the ecosystem (every command, rule, skill, agent, hook surface that solicits user input routes through the canonical channel). ● The three-segment option-annotation schema (every option's `description` carries `rationale:`, `recommendation:`, `default-pointer:`). ● The per-file destructive-op confirmation floor (§6 — every delete / rename / move / overwrite / revert routes through the structured-inquiry channel per-file). ● The fallback prose shape (§5 — the sole permitted free-form-looking prompt outside the canonical channel). ◐ The `(Recommended)` label postfix bidirectional bind with body `recommendation: recommended`.
+- **Satisfies →** ● CM-2 extension (the structured-inquiry surface CM-2 delegates to). ● the rules registry row "Interactive Questions". ● Option Annotation Discipline (the mandate this rule's annotation schema enforces).
+- **Established by ↑** ● CM-2 (Zero Assumptions — this rule is the structured-inquiry extension). ● Option Annotation Discipline. ● Authority Hygiene (per-file destructive-op confirmation operationalizes the no-silent-substitution invariant).
+- **Gated by ←** ● `CLAUDE.md` always-loaded preamble. ● `rules/operational-mandates.md` (CM-2 inline definition delegates the structured-inquiry surface here).
+- **Cross-bound with ↔** ↔ `rules/interactive-questions-canonical-shapes.md` (companion sub-rule carrying §2–§7 worked examples, schema bodies, taxonomy details, canonical option-set templates). ↔ `rules/interactive-questions-sweep-matchers.md` (companion sub-rule carrying the §8 H1–H7 matcher catalog). ↔ `rules/operational-mandates.md` (CM-2 inline anchor delegates here). ↔ `commands/plan-execute.md` + `commands/plan-generate.md` + `commands/plan-spec.md` + `commands/plan-review.md` (every plan-pipeline command's structured-inquiry invocations). ↔ `scripts/dev/validate_ecosystem.py` (the `--check option-annotation` subcommand operationalizes the H4–H7 matchers). ↔ `rules/agent-capability-discipline.md` (§6 destructive-op canonical option sets govern agent-capability invocations). ↔ `rules/agnostic-posture.md` (preference selection routes through the end user under the host-agnostic posture rather than being silently picked). ↔ `rules/interactive-questions-detail.md` (companion sub-rule carrying the §9 authoring-discipline procedure and the anti-pattern catalog moved out of the always-on body).

package/src/apothem/rules/large-file-generation.md

@@ -0,0 +1,112 @@
+---
+name: "large-file-generation"
+description: "Large file generation via incremental appends — assess size (Small <200 / Medium 200–500 / Large 500–1500 / Massive >1500 lines), then for Large+ plan sections first and append via Write-then-Edit so documents are never silently truncated or abandoned."
+pathFilter: "**/.apothem/plans/**, **/.plans/**, **/*.md, **/docs/**"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Large File Generation via Incremental Appends
+
+## Purpose
+
+Generate large files completely via systematic incremental appends when content exceeds practical single-output thresholds — never truncated, never silently abandoned.
+
+## Obligations
+
+### 1. Pre-Generation Assessment
+
+Assess expected size before generating, and route by band:
+
+| Band | Size | Handling |
+|---|---|---|
+| **Small** | < 200 lines / < 2000 tokens | Single `Write`. No special handling. |
+| **Medium** | 200–500 lines / 2000–5000 tokens | Single `Write`, monitored for truncation. On cut-off, switch to incremental mode. |
+| **Large** | 500–1500 lines / 5000–15000 tokens | Plan incremental generation from the start; divide into logical sections. |
+| **Massive** | > 1500 lines / > 15000 tokens | MANDATORY incremental generation with explicit section planning, progress tracking, and inter-section coherence verification. |
+
+### 2. Incremental Generation Protocol
+
+**2.1 — Section planning.** Before writing any content, plan the complete document structure: list every section with an estimated line count; identify cross-reference points between sections; establish the voice, tone, heading hierarchy, and formatting convention that persists across all appends; externalize the plan to a scratch note (or state it explicitly) before beginning.
+
+**2.2 — First write.** Use `Write` for the first section, establishing the document header / metadata / preamble, the table of contents or structural outline (where applicable), and the first logical section in full.
+
+**2.3 — Subsequent appends.** For each subsequent section, use `Edit` to append after the last line of existing content: match the final lines as `old_string`, replace with those same lines plus the new section as `new_string`. Maintain identical formatting conventions (heading levels, list styles, code-block styles). Open each append with a brief coherence check (does this flow from the prior section?). Preserve every cross-reference established earlier. NEVER re-generate already-written content — append only.
+
+**2.4 — Transition integrity.** At each section boundary, verify: the prior section's last paragraph and the new section's first paragraph read as one continuous document; numbering sequences (lists, figures, tables, sections) stay continuous; every forward reference from an earlier section is satisfied by the new content.
+
+### 3. Coherence Guarantees
+
+Every incrementally generated document satisfies four coherences:
+
+- **Structural** — consistent heading hierarchy; no orphan sections, no duplicate section numbers.
+- **Narrative** — reads as a single authored work, not a patchwork of fragments.
+- **Reference** — every internal cross-reference (sections, figures, tables, code blocks) resolves correctly.
+- **Format** — Markdown formatting, indentation, list styles, code-block languages, and emphasis patterns are uniform end to end.
+
+### 4. Completion Verification
+
+After the final append: read the complete file to verify end-to-end coherence (for files too large to read in one pass, read in overlapping segments with a 50-line overlap to verify transition zones); confirm the document has a proper ending, not an abrupt stop; confirm the section count matches the §2.1 plan.
+
+### 5. Failure Recovery
+
+If generation is interrupted (context pressure, error, tool failure): log the interruption point (which section, what remains); on resumption, read the last 50 lines of the existing file to re-establish context; continue from the exact interruption point — never restart or duplicate; after recovery, run the §2.4 transition-integrity check at the recovery boundary.
+
+## Seriousness Scaling
+
+| Level | Large File Generation Behavior |
+| ----- | ------------------------------ |
+| EXPLORING | Size assessment before generation. Basic incremental mode for large files. Section plans optional |
+| PERSONAL_USE | Size assessment + incremental mode for medium+ files. Section plan recommended for large files |
+| SHARED | Full protocol: mandatory section plan for large+ files. Coherence verification (§3) after every incremental generation. Transition-integrity checks at every append |
+| PUBLIC_LAUNCH | Full protocol + completion verification (§4). Section plans externalized before generation. Overlapping-read verification for massive files. Coherence failures block completion |
+
+## Decision Tree
+
+```mermaid
+%%{ init: { "theme": "neutral" } }%%
+%% verified: 2026-04-27 %%
+%% provenance: rules/large-file-generation.md §1 (pre-generation assessment) %%
+%% cross-reference: rules/large-file-generation.md §2 (incremental generation protocol) %%
+flowchart TD
+    Start[File generation request] --> Size{Estimated size}
+    Size -->|< 200 lines / Small| Single[Single Write call · no special handling]
+    Size -->|200-500 / Medium| MidWrite[Single Write · monitor for truncation]
+    Size -->|500-1500 / Large| Plan[Plan complete document structure first]
+    Size -->|> 1500 / Massive| MassivePlan[Mandatory section plan · explicit progress tracking]
+    MidWrite --> Trunc{Output truncated?}
+    Trunc -->|yes| SwitchInc[Switch to incremental mode]
+    Trunc -->|no| Done[Single-shot success]
+    Plan --> First[Write first section · header + outline + first body]
+    MassivePlan --> First
+    SwitchInc --> First
+    First --> Append[Append next section via Edit · match tail of prior content]
+    Append --> Trans[Transition integrity check · numbering · cross-refs · format coherence]
+    Trans --> More{More sections in plan?}
+    More -->|yes| Append
+    More -->|no| Verify[Read full file end-to-end · verify coherence]
+    Verify --> Inter{Interrupted mid-generation?}
+    Inter -->|yes| Recover[Re-read last 50 lines · resume from interruption point]
+    Recover --> Append
+    Inter -->|no| Done
+```
+
+## Anti-Patterns
+
+- **DON'T** generate a 1000+ line file in a single Write call — **BECAUSE** it risks silent truncation with no recovery path.
+- **DON'T** re-generate earlier sections when appending later ones — **BECAUSE** it wastes tokens, risks inconsistency, and drifts from the original content.
+- **DON'T** skip the section plan — **BECAUSE** unplanned incremental generation produces documents lacking structural coherence with inconsistent depth across sections.
+- **DON'T** append without reading the tail of existing content — **BECAUSE** transition zones become jarring and numbering breaks.
+
+## Enforcement
+
+Path-filtered (`**/.apothem/plans/**`, `**/.plans/**`, `**/*.md`, `**/docs/**`), scaling per the table above. Implements CM-23. Canonical specification for large file generation via incremental appends.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every large file emission across plan suites and docs (§1 Pre-Generation Assessment routes by size band; §2 Incremental Generation Protocol governs the writes). ● Every Phase Report emission exceeding the medium-band threshold (§2.3 subsequent-appends operationalizes the CM-23B incremental protocol). ● Every CHANGELOG / docs-site / massive-spec authoring session above the 1500-line threshold. ◐ Compaction triggers at the 500-line emission threshold (cross-bound with CM-19 in `rules/context-management.md` §3).
+- **Satisfies →** ● CM-23 (Large File Generation — rule-delegated mandate). ● the rules registry row "Large File Generation".
+- **Established by ↑** ● CM-23. ● the artifact directories (.apothem/plans/, .plans/, docs/, *.md class declarations).
+- **Gated by ←** ● The path-filter (`**/.apothem/plans/**`, `**/.plans/**`, `**/*.md`, `**/docs/**`) — this rule activates only on matching artifact touches. ● `rules/clean-room-generation.md` §2 Writing Protocol baseline (every artifact passes through the Writing Protocol before size-driven branching).
+- **Cross-bound with ↔** ↔ `rules/context-management.md` (CM-19 compaction discipline triggers at the 500-line emission threshold per §3 of that rule). ↔ `rules/clean-room-generation.md` (§2 Writing Protocol governs *what* to write; this rule governs *how* to safely write it when the size exceeds the single-write band). ↔ `commands/plan-execute.md` Step 7 (Phase Report emission cites CM-23A pre-generation size assessment). ↔ `rules/token-efficiency-rewrite.md` (CM-23 write-side incremental-append budget protocol; token-efficiency-rewrite complements at the read-side / always-on rewrite tier). ↔ `rules/large-file-reading.md` (sibling read-side rule with matching size-bands and segmentation logic).

package/src/apothem/rules/large-file-reading.md

@@ -0,0 +1,59 @@
+---
+name: "large-file-reading"
+description: "Large file reading via targeted segments — Grep to locate, Glob for traversal, Read with offset/limit; never load a full file when a segment suffices. Read-side analogue of large-file-generation."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Large File Reading via Targeted Segments
+
+## Obligations
+
+### 1. Pre-Read Assessment
+
+Assess size before reading:
+
+- **Small** (< 200): full-read MAY proceed.
+- **Medium** (200–500): segment reads SHOULD be preferred for scoped tasks.
+- **Large** (500–1500): locate first; read only cited ranges.
+- **Massive** (> 1500): structure first; full-read forbidden unless every section is load-bearing AND recorded per §4.
+
+### 2. Locate-Before-Read Protocol
+
+When the task names an identifier, heading, or symbol: `Grep -n` first, `Read` the cited range with a tight buffer, re-`Grep` before any escalation. A named target MUST NOT trigger a full-read.
+
+### 3. Structural Traversal Protocol
+
+`Glob` for sibling discovery; `Grep` for headings, signatures, frontmatter fields. Descend into a body only when the mapped structure shows it is needed.
+
+### 4. Segmentation Discipline
+
+Right-size each `offset` / `limit`, track multi-segment coverage, and record every Large+ full-read exception in the disclosure ledger per `rules/disclosure-ledger.md` (path, band, driver).
+
+## Seriousness Scaling
+
+| Level | Large File Reading Behavior |
+| ----- | --------------------------- |
+| EXPLORING | Size awareness; segment-based reads encouraged on Large+ files |
+| PERSONAL_USE | Pre-read assessment + locate-before-read on Medium+ files |
+| SHARED+ | Segment-only on Large+ files; full-read exceptions require disclosure-ledger rationale |
+
+## Anti-Patterns
+
+- **DON'T** full-read when `Grep` plus a segment answers the question.
+- **DON'T** skip locate-before-read for a named target.
+- **DON'T** re-read overlapping ranges without tracking.
+
+## Enforcement
+
+Always-on at every seriousness level, scaling per the table above. Canonical specification for size-aware file reading.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every file-consultation surface across the ecosystem (every `Read` invocation against a non-trivial-size file routes through the pre-read assessment at §1 and the locate-before-read protocol at §2). The `Grep` / `Glob` first-pass discipline at every search-before-implement step per CM-4. The segmentation discipline at §4 on every multi-segment file consult.
+- **Satisfies →** Project `CLAUDE.md` reading-discipline obligations; the read-side half of the context-budget invariant declared at `rules/context-management.md` §7.
+- **Established by ↑** `rules/large-file-generation.md` (sibling write-side rule — same essence, applied to writing). `rules/context-management.md` §7 Context Budget Discipline (this rule operationalizes the read-side of §7.2 Demand Loading).
+- **Gated by ←** The size-band thresholds at §1 (small files bypass the protocol). The trivial-vs-non-trivial threshold inherited from the project's CLAUDE.md scope.
+- **Cross-bound with ↔** ↔ `rules/large-file-generation.md` (sibling; write-side analogue with matching size-bands and segmentation logic). ↔ `rules/context-management.md` (CM-12 lean-context discipline; this rule's segmentation is one of the primary read-side levers preserving context budget). ↔ `rules/token-budget-discipline.md` (read-side analogue of the always-on body-size ceiling; both rules optimize the same gradient on different surfaces). ↔ `rules/clean-room-generation.md` (CM-4 Search Before Implement uses `Grep` / `Glob` first; this rule canonicalizes the locate-before-read shape that CM-4 search relies on). ↔ `rules/tool-use-discipline.md` (locate-before-read is the observe-step discipline at the file tier of that rule's observe → decide → act loop).

package/src/apothem/rules/living-docs.md

@@ -0,0 +1,85 @@
+---
+name: "living-docs"
+description: "Every change to a documented public surface — a CLI command or flag, a harness adapter, a profile field, an installer flag or environment variable, a configuration key, or any surface with a page under site/content/docs/ — MUST update its documentation page in the same change-set; source-generated reference pages are kept current by re-running the reference-inventory generator and committing the regenerated pages."
+pathFilter: "**/site/content/docs/**, **/src/apothem/cli/**, **/src/apothem/harnesses/**, **/src/apothem/schemas/profile.schema.json, **/scripts/installer/**"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Living Documentation — Same-Change-Set Docs for Every Documented Public Surface
+
+## What this rule enforces
+
+Documentation is part of the change, not a follow-up. When a behavior change touches a **documented public surface**, the page describing that surface **MUST** be updated in the **same change-set** as the behavior change. This is the documentation analogue of the production-ready same-change-set discipline at `rules/production-ready-prs.md`: just as a code change ships its tests, CHANGELOG entry, and conformant commit together, a public-surface change ships its docs update together. A documented surface that drifts ahead of its page — even transiently across a commit boundary — is non-conformant. Apothem self-applies this rule: its own docs tree under `site/content/docs/` is kept current under the same binding it ships to host projects.
+
+## Pre-conditions
+
+The rule applies whenever a change touches a documented public surface:
+
+| Surface | Source of truth | Documented at |
+|---|---|---|
+| **CLI command / flag** | `src/apothem/cli/` | `site/content/docs/reference/cli.mdx` |
+| **Harness adapter** | `src/apothem/harnesses/<name>/` | the harness-registry reference + the harness's how-to page |
+| **Profile field** | `src/apothem/schemas/profile.schema.json` | the profile-fields reference |
+| **Installer flag / env var** | `scripts/installer/` | the install how-to |
+| **Configuration key / any other** | — | its page under `site/content/docs/` |
+
+The rule does NOT apply to internal-only surfaces with no public docs page (private helpers, test fixtures, conformity matchers) — they carry no living-docs obligation. Trivial-scope edits per the host's threshold that do not alter a documented surface's behavior, signature, or default are exempt.
+
+## Required behavior
+
+### 1. Same-Change-Set Docs Update
+
+A change to a documented public surface **MUST** update the corresponding page in the same change-set. Deferring the docs update to a later commit or PR is forbidden — the follow-up never lands, and the page is stale at the merge boundary. The update covers every observable shift the change introduces: a renamed flag updates the flag's documented name; a new profile field documents its type, default, and meaning; a removed adapter removes its registry row and how-to page.
+
+### 2. Source-Generated Reference Pages
+
+Three reference surfaces are **source-generated** — derived mechanically from the source of truth, never hand-maintained:
+
+- **CLI reference** (`reference/cli.md`) — generated from the Click command tree.
+- **Harness-registry reference** — generated from the registered `apothem.harnesses` entry points.
+- **Profile-fields reference** — generated from `profile.schema.json`.
+
+A change touching any of these source surfaces **MUST** regenerate the affected pages by re-running `node site/scripts/update-reference-inventory.mjs` and committing the regenerated pages in the same change-set. The generator output is authoritative; hand-edits to a source-generated page are overwritten on the next regeneration and **MUST NOT** be relied upon.
+
+### 3. Hand-Authored How-To Pages
+
+Hand-authored pages (how-to guides, conceptual pages, tutorials) describing a changed surface **MUST** be updated by hand in the same change-set. Adding a CLI flag that changes a documented workflow updates both the regenerated `reference/cli.md` **and** the relevant how-to page that walks the workflow.
+
+### 4. Worked Example — Adding a CLI Flag
+
+A developer adds a `--dry-run` flag to `apothem install` in `src/apothem/cli/`. The living-docs binding requires the same PR to:
+
+1. **Regenerate `reference/cli.md`** — run `node site/scripts/update-reference-inventory.mjs`; the regenerated page now lists `--dry-run` with its help text under `apothem install`. Commit the regenerated page.
+2. **Update the relevant how-to** — the install how-to under `site/content/docs/` that walks `apothem install` gains a sentence on `--dry-run` (when to use it, what it previews). Edit by hand.
+
+Both land in the same change-set as the flag. Ship the flag without the docs update and CI's docs-reference-sync / stale-doc drift gate (§Mechanical enforcement) fails: it re-runs the generator in a clean tree and diffs the result against the committed pages; a non-empty diff means the committed `reference/cli.md` is stale, and the gate blocks the merge until the regenerated page is committed.
+
+## Mechanical enforcement
+
+The **docs-reference-sync / stale-doc drift gate** enforces this rule in CI. It runs `node site/scripts/update-reference-inventory.mjs` in a clean checkout and diffs the regenerated source-generated pages against the committed pages. A non-empty diff means a documented source surface changed without its reference page being regenerated; the gate fails and names the stale page. This is the docs analogue of the production-ready CI-green discipline: a stale source-generated reference page blocks the merge the way a failing test does. Hand-authored how-to drift is a reasoned review check, not mechanically diffable — reviewers confirm a surface change carries its how-to update.
+
+## Disclosure surface
+
+Every living-docs outcome is recorded in the disclosure ledger per `rules/disclosure-ledger.md`:
+
+- `[Living-Docs — surface: <cli | harness | profile-field | installer | config-key>; page: <docs-path>; update: regenerated | hand-edited]` for every same-change-set docs update.
+- `[Living-Docs — regenerated: reference/cli.md | harness-registry | profile-fields; generator: update-reference-inventory.mjs]` for every source-generated page refresh.
+- `[Living-Docs — deferred: docs update out-of-scope because <reason>; tracking: <where>]` only when the surface change genuinely carries no documented public effect; the deferral names why the page needs no update.
+
+## Failure tells
+
+A PR adding a CLI flag with no change to `reference/cli.md`. A new harness adapter merged without a registry-reference regeneration or a how-to page. A renamed profile field whose documented name still shows the old identifier. An installer env var added to `scripts/installer/` with no mention in the install how-to. A hand-edit to a source-generated reference page (overwritten on the next regeneration). A "docs update coming in a follow-up PR" note on a surface-changing diff. A green local build with a CI docs-reference-sync drift-gate failure (the committed reference page is stale against the source of truth).
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** The same-change-set docs update on every documented-public-surface change under this rule's `pathFilter`. The regeneration of source-generated reference pages via `node site/scripts/update-reference-inventory.mjs`. The CI docs-reference-sync / stale-doc drift gate that diffs regenerated pages against committed pages.
+- **Satisfies →** The living-documentation mandate (documented surfaces never drift ahead of their pages). The documentation analogue of the production-ready same-change-set discipline.
+- **Established by ↑** The production-ready same-change-set discipline at `rules/production-ready-prs.md` (this rule projects that discipline onto the documentation surface). The source-generated reference-inventory generator at `site/scripts/update-reference-inventory.mjs`.
+- **Gated by ←** The `pathFilter` (documented public source surfaces + the docs tree only; internal-only surfaces are exempt). The trivial-scope threshold (edits that do not alter a documented surface's behavior, signature, or default are exempt). The CI docs-reference-sync drift gate's clean-tree diff baseline.
+- **Cross-bound with ↔** `rules/production-ready-prs.md` (the production-ready same-change-set discipline this rule is the documentation analogue of). `rules/systemic-participation.md` (a documented surface and its page are reciprocal participants; the page is the surface's downstream consumer). `rules/recommend-next-step.md` (terminal-surface forward-move discipline this rule's tail honors). `rules/propagation.md` (the full reference-graph propagation mandate this docs-tier rule is one participant of).
+
+## Recommended Next Step
+
+**Run `node site/scripts/update-reference-inventory.mjs`** after any change to a CLI command, harness adapter, or profile field, then commit the regenerated reference pages alongside the source change so the CI docs-reference-sync drift gate stays green, per `rules/recommend-next-step.md`.