@ahmed-g-gad/apothem 0.1.1

package/src/apothem/rules/surgical-manipulation.md

@@ -0,0 +1,48 @@
+---
+name: "surgical-manipulation"
+description: "Every mutation of an existing artifact is surgical — a precise, minimal, anchor-bounded or managed-block edit that touches only the span the change requires, never a blunt whole-file overwrite where a scoped edit suffices, and never a strip of a surrounding banner or unrelated content. The mutation produces a minimal diff attested against the host's green conformity baseline (the golden-corpus invariant). The surgical-edit + reactive-guard mechanism is the surgical-guard skill."
+pathFilter: "**/*.py, **/*.md, **/*.mdx, **/*.json, **/*.yaml, **/*.yml, **/*.toml, **/*.sh, **/*.ps1, **/*.ts, **/*.js, **/*.mjs, **/*.css, **/*.mdc"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Surgical Manipulation — Minimal, Anchor-Bounded Mutation
+
+## What this rule enforces
+
+Every mutation of an **existing** artifact MUST be **surgical**: a precise, minimal edit scoped to an anchor — a managed-block sentinel region, a contiguous span, or the smallest range the change requires. It MUST NOT be a blunt whole-file overwrite where a scoped edit suffices, and MUST NOT strip a surrounding authorship banner or unrelated content. The diff is minimal — only the lines the change requires move — and is attested against the host's green conformity baseline: the **minimal-diff golden-corpus invariant** (a surgical edit that leaves every gate green). The cohort mandates this discipline; its operating mechanism — surgical edit plus a reactive post-edit quality guard — is the `surgical-guard` skill.
+
+## Pre-conditions
+
+Applies whenever an existing artifact is mutated (an Edit, an in-place rewrite, a managed-block refresh). It does NOT apply to green-field file creation (no existing content to preserve) — that is authoring, governed by `rules/clean-room-generation.md`. Trivial-scope single-line edits inherit the discipline at the touch site (preserve surroundings) without further ceremony.
+
+## Required behavior
+
+### 1. Anchor before mutate
+
+Locate the precise mutation site first (locate-before-read): a sentinel-delimited managed block, an anchor-bounded span, or the smallest contiguous range the change needs. Read only that range plus a tight buffer. The anchor is the scope contract — the edit touches it and nothing outside it.
+
+### 2. Minimal diff
+
+Apply the change as the smallest diff that satisfies it. Everything outside the anchor MUST stay byte-for-byte unchanged — including the SPDX authorship banner, surrounding comments, and unrelated declarations. A whole-file overwrite where an anchor-bounded edit suffices is non-conformant; a managed-block refresh replaces only the sentinel-delimited content, never the boundaries.
+
+### 3. Golden-corpus attestation
+
+After the mutation, the host's conformity gate MUST be green and the diff minimal — the golden-corpus invariant. A mutation that turns a gate red, or sweeps far beyond its stated scope, fails the invariant and is reduced to its surgical minimum before acceptance.
+
+### 4. Reactive guard
+
+Non-trivial mutations MUST be reviewed reactively (a diff pass) for the systematic failure modes of generated changes — swallowed errors, hollow tests, docs-vs-code drift — via the `surgical-guard` skill before the change is accepted.
+
+## Failure tells
+
+A whole-file overwrite where a three-line anchor-bounded edit would suffice. A diff that strips or relocates the SPDX banner during an unrelated change. A managed-block edit that rewrites the sentinel boundaries instead of the enclosed content. A mutation that sweeps unrelated lines into its diff. A change accepted while a conformity gate it touched is red (golden-corpus breach).
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every mutation of an existing artifact across the host (anchor-bounded minimal diff). The minimal-diff golden-corpus attestation on every non-trivial change. The reactive post-edit guard pass.
+- **Driven by ←** The WS-E surgical-manipulation mandate; the harness installation discipline's managed-block (`sentinel_merge`) convention.
+- **Satisfies →** The MAXIMAL golden-corpus end-state (internally consistent, minimally-diffed, gate-conformant).
+- **Established by ↑** `skills/surgical-guard/SKILL.md` (the surgical-edit + reactive-guard mechanism this rule mandates); the harness-installation managed-block discipline.
+- **Cross-bound with ↔** `skills/surgical-guard/SKILL.md` (the mechanism). `rules/code-craft-python.md` + sibling code-craft rules (scoped, atomic refactoring is the per-language form of surgical mutation). `rules/interactive-questions.md` (§6 — destructive mutations route per-file through the canonical destructive-op floor). `rules/clean-room-generation.md` (governs green-field authoring; this rule governs mutation of existing artifacts). `rules/pre-emission-gate.md` (the golden-corpus attestation is verified at the gate). `rules/refactoring-discipline.md` (a refactor's edits are surgical, anchor-bounded mutations).

package/src/apothem/rules/systemic-participation-relations.md

@@ -0,0 +1,108 @@
+---
+name: "systemic-participation-relations"
+description: "Path-filtered companion rule carrying the operational detail of M14 systemic participation — the four systemic relations table, sibling-convention convergence detail, index/registry update table, the three orphan classes, the three silo classes, retirement discipline, and the cross-component reference graph invariant. Demand-loaded when the parent `systemic-participation.md` rule's anchors surface on host-project component touches."
+pathFilter: "**/src/**, **/lib/**, **/tests/**, **/docs/**, **/.github/**, **/migrations/**, **/__init__.py, **/CONTRIBUTING.md, **/CODEOWNERS"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Systemic-Participation Relations (Companion Sub-Rule)
+
+## Purpose
+
+Carry the operational detail of M14 systemic participation that the parent rule `rules/systemic-participation.md` anchors. The companion is path-filtered: it loads when the assistant edits any host-project component class (source modules, libraries, tests, documentation, CI workflows under `.github/`, migrations, package `__init__.py`, contribution surfaces). The parent rule retains the canonical directive paragraph, the pre-conditions, the disclosure surface, and the failure-tells catalog; this companion carries the seven sub-section bodies that operationalize the directive at the component-touch surface.
+
+## Obligations
+
+### 1. The Four Systemic Relations
+
+Every newly-introduced component declares four relations:
+
+| Relation | What it names | Why |
+|---|---|---|
+| **Upstream** | What triggers, depends on, or invokes this component | The reader can answer "what causes this to run / be loaded / be referenced?" |
+| **Downstream** | What consumes this component's output / behavior / surface | The reader can answer "what would break if this were removed?" |
+| **Peers** | Sibling components of the same kind (other tests, other docs, other workflows, other modules) | The reader can answer "what convention does this follow, and what conventions does it bind?" |
+| **Enforcers** | Host quality gates that govern this component (CI workflows, linters, type-checkers, security scans, code review owners) | The reader can answer "what gates pass / fail when this changes?" |
+
+The four relations MUST be declared in two places: inline in the artifact (header comment, frontmatter, or a dedicated `## Bindings` section per `rules/bidirectional-binding.md`) AND in the host's adjacent registry (the index file the host maintains for components of this kind).
+
+### 2. Sibling-Convention Convergence
+
+Every newly-introduced component **converges with its peers** on every observable convention:
+
+- **Naming.** The component's filename, identifier, header, ID, slug match the peers' naming convention (kebab-case / snake_case / PascalCase / camelCase / etc.).
+- **Layout.** The component's directory placement matches where the peers live. A new test under the host's tests directory; a new doc page under the host's docs directory; a new CI workflow under `.github/workflows/`.
+- **Frontmatter / header / preamble.** When peers carry a frontmatter contract or a header-comment shape, the new component carries the same contract / shape with the same field set (host-discovered required fields per `rules/host-discovery.md`).
+- **Internal idioms.** The component's body uses the same idioms its peers use — same fixture pattern in tests, same heading hierarchy in docs, same action-pinning policy in CI workflows, same import order in source files, same logging surface in scripts.
+
+**Sibling-convergence threshold.** When the host has at least three peer components of the same kind, the dominant observable convention is the ratified convention; new components honor it. When the host has fewer than three peers, the observable conventions are advisory; the new component adopts one and the choice is recorded in the disclosure ledger so future siblings converge on the same.
+
+### 3. Index / Registry Update — Same-Change Discipline
+
+Every newly-introduced component updates the host's adjacent registries **in the same change-set**:
+
+| Component class | Registry update |
+|---|---|
+| **Test file** | Picked up by the host's existing test discovery without configuration changes; if the host maintains an explicit test index (e.g., `tests/__init__.py`, `tests/index.json`, a `tox.ini` envlist), the new test is added |
+| **Documentation page** | Listed in the host's TOC / nav / sidebar / index page; cross-linked from contextually-related pages with reciprocal links per `rules/bidirectional-binding.md` |
+| **CI workflow** | If the host's `CONTRIBUTING.md` documents the CI section, the new workflow is mentioned; if the host has a workflow-index file, the new workflow is added |
+| **Source module** | Added to the host's `__init__.py` / module index / package manifest so it is importable through the public API surface |
+| **Configuration entry** | Documented in the configuration's reference page; default value declared; environment-variable mapping (where applicable) noted |
+| **Schema / migration** | Indexed in the host's migration directory; numbered or timestamped per the host's convention; downstream-consumer code that depends on the new schema updated in the same change-set |
+
+The same-change discipline forbids "I'll add the index entry in a follow-up": the follow-up never lands, the artifact persists as an orphan in the meantime, and orphans are structural failures.
+
+### 4. Orphan Prevention — The Three Orphan Classes
+
+An orphan is an artifact satisfying any one of the three conditions enumerated at `rules/canonical-layout.md` §3:
+
+- **No consumer.** Nothing in the host's reference graph reads / imports / executes / links / references the artifact.
+- **No index entry.** The artifact is not listed in the enclosing directory's index where the host maintains one.
+- **No producer attribution.** The artifact carries no provenance — no frontmatter `provenance:` field, no header comment naming the producer, no record in the producer's report.
+
+This rule extends the orphan-prevention discipline from `rules/canonical-layout.md` (which governs orphans within multi-step work session outputs) to **every** newly-introduced component in the host project (regardless of whether the component originated from multi-step work or a single-step touch).
+
+### 5. Silo Prevention — The Three Silo Classes
+
+A silo is a newly-introduced component satisfying any one of:
+
+- **Convention divergence.** The component's observable conventions (naming, layout, frontmatter, internal idioms) diverge from peer components of the same kind without explicit justification.
+- **Functional duplication.** The component performs a function the host already provides through an existing component, without explicit justification (e.g., a new utility function alongside an equivalent existing helper; a new test fixture alongside an equivalent existing fixture; a new doc page alongside an equivalent existing page).
+- **Scope drift.** The component bundles concerns that belong to multiple existing components, blurring the host's existing scope boundaries (e.g., a new module mixing domain logic and infrastructure concerns; a new doc page combining tutorial and reference material).
+
+Silo recovery: the silo is either (a) merged into the existing component it duplicates, (b) refactored to converge with peer conventions, or (c) split along the host's existing scope boundaries. Recovery happens in the same change-set as the silo's introduction; deferred recovery leaves the host's reference graph in a divergent state.
+
+### 6. Retirement Discipline — Symmetric to Introduction
+
+When apothem removes a component, the four relations are unwound:
+
+- **Upstream.** Triggers / dependencies that point at the removed component are updated or removed in the same change-set. A CI workflow's `runs-on` reference to a removed runner; a configuration entry's reference to a removed environment variable.
+- **Downstream.** Consumers that depend on the removed component are updated or removed in the same change-set. Code that imports the removed module; documentation pages that link to the removed page.
+- **Peers.** Sibling components that share registry entries with the removed component update their entries (e.g., a `__init__.py` that exported the removed module).
+- **Enforcers.** CI workflows / linters that referenced the removed component's path-filter or surface are updated. Removed-component-related warnings are deleted from the warning suppression list.
+
+The retirement is **complete** at the change-set boundary. A removed component whose downstream references persist is itself a finding (broken-reference orphan).
+
+### 7. Cross-Component Reference Graph
+
+The host's reference graph is the union of every component's four relations:
+
+- **Connectivity.** Every component is reachable from at least one entry point (the host's main entry, the host's documentation root, the host's CI configuration). Unreachable components are orphans.
+- **Acyclicity (where applicable).** Module dependency graphs that the host's language requires acyclic (Python, ES modules, Rust, Go) honor the constraint. Documentation cross-references may form cycles (forward + back-reference is a feature, not a violation).
+- **Density.** Sparse references (a component referenced from only one site) are inspected for whether the component is over-isolated or under-developed; dense references (a component referenced from many sites) are inspected for whether the component has become a god-object peer.
+
+The reference-graph state is the host's **systemic invariant**. Every change preserves the invariant or surfaces the invariant change as a finding.
+
+## Enforcement
+
+Path-filtered (the nine glob patterns in this rule's `pathFilter` field), always-on at every seriousness level when in scope. Demand-loaded companion to `rules/systemic-participation.md`. The parent rule carries the canonical M14 directive, pre-conditions, disclosure surface, and failure-tells catalog; this companion carries the seven operational sub-sections (four relations, sibling convergence, index/registry update, orphan classes, silo classes, retirement, reference graph).
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● The four-relations declaration at every newly-introduced host-project component (the §1 table is the operational floor). ● The sibling-convergence walk at §2. ● The index / registry update at §3 across every component class. ● The orphan-recovery and silo-recovery actions at §4 and §5. ● The retirement-discipline unwinding at §6. ● The reference-graph invariant preservation at §7.
+- **Satisfies →** ● the fifteen-mandate registry row **M14 — Ecosystem Systemicity** (operational detail tier). ● `rules/systemic-participation.md` companion-sub-rule anchors.
+- **Established by ↑** ● `rules/systemic-participation.md` (parent-rule anchor). ● the fifteen-mandate registry (ratifies M14). ● the Pre-Emission Gate row 14.
+- **Gated by ←** ● The path-filter (nine glob patterns covering host-project component classes) — this rule demand-loads only on component touches. ● `rules/systemic-participation.md` always-on baseline (parent rule must be live for the anchors to surface).
+- **Cross-bound with ↔** ↔ `rules/systemic-participation.md` (parent rule; companion-sub-rule anchors bind this companion). ↔ `rules/canonical-layout.md` (M12 — orphan-prevention discipline at §3 of that rule extends through this companion's §4 to all newly-introduced components). ↔ `rules/bidirectional-binding.md` (M10 — the four systemic relations populate the M10 five-direction binding section). ↔ `rules/host-discovery.md` (M1 — sibling-convergence walks the host-discovery surface). ↔ `rules/code-craft-conventions.md` (universal-delegation stub's sibling-convergence enforcement at §2 binds here for code-language artifacts). ↔ `rules/disclosure-ledger.md` (M2 — systemic-participation outcomes recorded in the ledger).

package/src/apothem/rules/systemic-participation.md

@@ -0,0 +1,70 @@
+---
+name: "systemic-participation"
+description: "Every artifact apothem introduces into a host project joins the host as a systemic participant — declares its upstream / downstream / peers / enforcers; honors sibling conventions; lands at the host's canonical layout; updates the host's index registries in the same change. Silos (self-contained artifacts diverging from sibling conventions) and orphans (artifacts with no consumer / no index entry / no producer attribution) are structural failures, not aesthetic preferences."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Ecosystem Systemicity in the Host Project — No Orphans, No Silos
+
+## What this rule enforces
+
+This rule binds **M14 — Ecosystem Systemicity in the Host Project**. Every artifact the agent produces in a host project — module, test fixture, CI workflow, documentation page, script, manifest, configuration entry, schema, migration, deployment artifact — MUST **join the host as a systemic participant**: it declares its **upstream** (what triggers it), **downstream** (what consumes it), **peers** (siblings of the same kind), and **enforcers** (the host quality gates that govern it). Introduction is **complete in the same change-set** — host registries / indexes / TOCs / linkbacks update, the sibling convention is honored, no parallel-but-divergent function is left for the reader to find. A **silo** (self-contained artifact diverging from sibling conventions or duplicating existing function) and an **orphan** (no consumer, no index entry, no place in the reference graph) are structural failures, not aesthetic preferences.
+
+## Pre-conditions
+
+Applies in a host project that maintains a reference graph (a software project with imports, indexes, and registries) whenever apothem introduces a new component, modifies an existing component's systemic relations (rename, relocation, scope change), or removes one (retirement is the symmetric inverse); a plain chat, cowork, research, or writing session with no such graph is outside its scope. Trivial-scope edits per the trivial-vs-non-trivial threshold (≤ 5 lines AND no public-API change AND no behavioral shift) are exempt; the moment a change introduces a component or alters its place in the host's reference graph, the rule applies.
+
+## Required behavior
+
+### 1. The Four Systemic Relations
+
+Every new component declares four relations — **upstream** (what triggers it), **downstream** (what consumes it), **peers** (siblings of its kind), **enforcers** (host gates governing it) — both inline in the artifact AND in the host's adjacent registry. (Companion Sub-Rule Anchor) See `rules/systemic-participation-relations.md` §1 for the full relations table.
+
+### 2. Sibling-Convention Convergence
+
+Every new component converges with its peers on naming, layout, frontmatter / header shape, and internal idioms. At three or more peers, the dominant observable convention is ratified; below that, the adopted choice is recorded in the disclosure ledger. (Companion Sub-Rule Anchor) See `rules/systemic-participation-relations.md` §2 for the convergence detail and threshold rule.
+
+### 3. Index / Registry Update — Same-Change Discipline
+
+Every new component updates the host's adjacent registries in the same change-set; a deferred index update leaves a transient orphan. (Companion Sub-Rule Anchor) See `rules/systemic-participation-relations.md` §3 for the per-class registry-update table (test file, documentation page, CI workflow, source module, configuration entry, schema / migration).
+
+### 4. Orphan Prevention — The Three Orphan Classes
+
+An orphan has no consumer, no index entry, or no producer attribution. This extends `rules/canonical-layout.md` §3 from multi-step work outputs to every new component. (Companion Sub-Rule Anchor) See `rules/systemic-participation-relations.md` §4 for the three-class catalog and the canonical-layout extension clause.
+
+### 5. Silo Prevention — The Three Silo Classes
+
+A silo exhibits convention divergence, functional duplication, or scope drift relative to host peers. Recovery (merge / refactor / split) lands in the same change-set as the introduction. (Companion Sub-Rule Anchor) See `rules/systemic-participation-relations.md` §5 for the three-class catalog and the recovery protocol.
+
+### 6. Retirement Discipline — Symmetric to Introduction
+
+When a component is removed, its upstream / downstream / peer / enforcer references are unwound in the same change-set; a persistent downstream reference is a broken-reference orphan. (Companion Sub-Rule Anchor) See `rules/systemic-participation-relations.md` §6 for the per-relation unwinding detail.
+
+### 7. Cross-Component Reference Graph
+
+The host's reference graph — the union of every component's four relations — carries connectivity, acyclicity-where-applicable, and density invariants. Every change preserves them or surfaces the change as a finding. (Companion Sub-Rule Anchor) See `rules/systemic-participation-relations.md` §7 for the three-invariant detail.
+
+## Disclosure surface
+
+Every systemic-participation declaration is recorded in the disclosure ledger per `rules/disclosure-ledger.md`:
+
+- `[Systemic — introduced: <component-path>; class: <test | doc | workflow | module | config | schema>; upstream: <list>; downstream: <list>; peers: <list>; enforcers: <list>; index-entry: added at <registry-path>]` for every new-component introduction.
+- `[Systemic — convergence: <component-path>; sibling-convention adopted: <convention>; sibling-source: <peer-files>]` for every sibling-convergence outcome.
+- `[Systemic — silo-recovery: <component-path>; resolution: <merge | refactor | split>; original-divergence: <description>]` for every silo recovery.
+- `[Systemic — orphan-recovery: <component-path>; resolution: <consumer-added | index-added | provenance-added | retired>]` for every orphan recovery.
+- `[Systemic — retired: <component-path>; class: <test | doc | workflow | module | config | schema>; downstream-cleanup: <list-of-updated-references>]` for every component retirement.
+
+## Failure tells
+
+Sibling-convention drift; orphan introduction (no consumer / no index entry / no producer attribution); functional-duplication and scope-drift silos; broken-reference orphans from incomplete retirement; unjustified convention divergence in the ledger. (Companion Sub-Rule Anchor) See `rules/systemic-participation-relations.md` §§4–6 for the per-class diagnostic catalog.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every newly-introduced component across every host project (the four-relations declaration is the systemic-participation floor). ● The orphan-prevention discipline's universal extension beyond multi-step work session outputs (this rule covers single-step touches; `rules/canonical-layout.md` covers multi-step work). ● Every component-retirement change-set (the symmetric retirement-discipline at §6 unwinds the four relations). ● The host's reference-graph invariant preservation across every change. ◐ The orphan-introduction-grep mechanical matcher at `conformity/orphan_output_grep.py` (operationalizes the §4 orphan-prevention discipline).
+- **Satisfies →** ● the fifteen-mandate registry row **M14 — Ecosystem Systemicity**. ● the Pre-Emission Gate row 14 (M14 systemicity check).
+- **Established by ↑** ● the fifteen-mandate registry (ratifies M14). ● the Pre-Emission Gate row 14. ● CM-22 Conventions Vigilance (the inward-axis analog M14 cross-maps to per the M↔CM cross-mapping declared at this rule's `Cross-bound with ↔` row).
+- **Gated by ←** ● The §8.1 trivial-vs-non-trivial threshold (trivial-scope edits skip the four-relations declaration). ● `CLAUDE.md` always-loaded preamble.
+- **Cross-bound with ↔** ↔ `rules/systemic-participation-relations.md` (path-filtered companion sub-rule carrying §1–§7 operational detail). ↔ `rules/persistent-conventions-vigilance.md` (CM-22 — the inward-axis analog M14 cross-maps to per `CLAUDE.md` PLAN-NOTES.md D1 cross-mapping table; CM-22 governs internal artifact lifecycle, M14 governs external systemic participation; both apply where both apply). ↔ `rules/canonical-layout.md` (M12 — orphan-prevention discipline at §3 of that rule extends here from multi-step work outputs to all newly-introduced components). ↔ `rules/bidirectional-binding.md` (M10 — the four systemic relations populate the M10 five-direction binding section). ↔ `rules/host-discovery.md` (M1 — sibling-convergence walks the host-discovery surface). ↔ `rules/code-craft-conventions.md` (universal-delegation stub's sibling-convergence enforcement at §2 binds here for code-language artifacts). ↔ `rules/disclosure-ledger.md` (M2 — systemic-participation outcomes are recorded in the ledger). ↔ `rules/harness-adapter-shape.md` (M14 sibling-convention convergence is the silo-prevention surface for harness adapters). ↔ `rules/agent-capability-discipline.md` (M14 — agent-capability matrix declares the four systemic relations across cohorts). ↔ `rules/living-docs.md` (M14 — a documented surface and its page are reciprocal participants; the page is the surface's downstream consumer). ↔ `rules/propagation.md` (the component-tier propagation this rule's M14 systemicity participates in).

package/src/apothem/rules/ten-dimension-check-dimensions.md

@@ -0,0 +1,52 @@
+---
+name: "ten-dimension-check-dimensions"
+description: "Path-filtered companion sub-rule carrying the verbatim per-dimension bodies (rigor / coherence / configurability / readability / orphanism / structurality / architecture / naming / scholarly referencing / examples-tests-docs) and per-dimension failure tells declared at the parent `ten-dimension-check.md` rule's anchor; demand-loaded on artifact-emission surfaces."
+pathFilter: "**/*.md, **/*.py, **/*.sh, **/*.ps1, **/CLAUDE.md, **/rules/**, **/commands/**, **/skills/**, **/agents/**, **/docs/**"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Ten-Dimension Check — Per-Dimension Bodies (Companion Sub-Rule)
+
+## Purpose
+
+Carry the verbatim per-dimension bodies and per-dimension failure tells the parent rule `rules/ten-dimension-check.md` anchors. Path-filtered: loads on any artifact-emission surface (Markdown, Python, shell, PowerShell under the rules / commands / skills / agents / docs trees and the root `CLAUDE.md`). The parent owns the M3 standing directive, the multiplicative-failure clause, the trivial-work abbreviated check, the self-check-at-emission paragraph, the cross-cutting failure tells, and the disclosure surface; this companion owns the ten per-dimension bodies below.
+
+## Obligations
+
+### The Ten Dimensions — Per-Dimension Bodies
+
+Every artifact MUST pass each of the ten dimensions individually before emission. The order is canonical; each carries one diagnostic failure tell.
+
+1. **Scientific rigor.** Claims are evidence-based; cause-effect statements are reproducible by inspection or experiment; folklore is excluded; falsifiability is stated where applicable. **Tell:** "this is faster" with no benchmark cited.
+
+2. **Consistency · Coherence · Integration · Validity.** No contradiction within the artifact or against its neighbors; every part belongs to one mental model; references resolve, data shapes align, schemas match, names exist, the artifact parses. **Tell:** a README that disagrees with the code it documents.
+
+3. **Configurability · Irredundancy · Consolidation.** Varying behavior is parameterized; values, rules, and patterns are not duplicated; downstream artifacts reference rather than copy; fragmentation is healed. **Tell:** the constant `60` repeated across three files.
+
+4. **Readability · Intuition · Cleanness.** Readable on first pass by a competent engineer new to the artifact; names telegraph purpose; surprising behavior is documented or removed; no trailing whitespace, mixed line endings, dead TODOs, or commented-out blocks. **Tell:** a function named `process_data` (intent-invisible).
+
+5. **Orphanism · Staleness.** No reference to a removed API, renamed identifier, deprecated tool, dead URL, or non-existent file; the artifact is itself reachable in the host's reference graph; verification dates are stamped where content is volatile. **Tell:** a reference to a file moved last sprint.
+
+6. **Structurality · Systemicity · Uniformity · Comprehensiveness.** The artifact has clear structure, behaves as part of a system rather than a heap, follows its peers' shape, and fully covers the surface it claims. **Tell:** a partial enumeration listing 3 of 5 cases without naming the omission.
+
+7. **Architecture.** Where the artifact is structural, layering is articulated, data and control flow are traceable, layer boundaries are respected, and violations are flagged. **Tell:** a domain function that imports an infrastructure adapter.
+
+8. **Naming conventions & uniformity.** One convention per scope, applied identically; identifier shapes match the host's idioms; names never lie about behavior; specificity is not baked into the names of generic things. **Tell:** mixed `camelCase` and `snake_case` in one Python module.
+
+9. **Scholarly / technical referencing.** Every reference — internal, external, symbolic, quoted — meets a scholarly bar: canonical permalinked form, access date where volatile, author or organization attribution, commit-pinned over branch-pointed, primary over secondary source, no phantom citation. **Tell:** "RFC 7234 says X" with no link, no section, no quote — and X is not in RFC 7234.
+
+10. **Examples · Tests · Docstrings · Documentation.** The artifact carries the minimum viable documentation surface for its kind: examples for invocables, tests or verification recipes for non-trivial logic, docstrings or header comments for scripts, README-equivalent coverage where the artifact is a directory or module. **Tell:** a public function with no docstring and no example.
+
+## Enforcement
+
+Path-filtered (the glob list in this rule's `pathFilter` field), always-on at every seriousness level when in scope. Demand-loaded companion to `rules/ten-dimension-check.md`: the parent owns the M3 standing directive, multiplicative-failure clause, trivial-work abbreviated check, self-check-at-emission paragraph, cross-cutting failure tells, and disclosure surface; this companion owns the ten per-dimension bodies and their failure tells.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every artifact-emission surface's per-dimension self-check (the ten verbatim per-dimension bodies enumerated above are the dimension-by-dimension specification the gate's bar 3 inspects). ● Every per-dimension failure-tell match at the pre-emission gate. ◐ The dimension-by-dimension marking on the gate attestation.
+- **Satisfies →** ● the fifteen-mandate registry row **M3 — Ten Quality Dimensions** (per-dimension specification surface). ● `rules/ten-dimension-check.md` anchor (parent rule's pointer to this companion's full per-dimension fidelity).
+- **Established by ↑** ● `rules/ten-dimension-check.md` (parent-rule anchor). ● the fifteen-mandate registry (ratifies M3). ● the Pre-Emission Gate row 3.
+- **Gated by ←** ● The path-filter (the glob list in this rule's frontmatter) — this rule demand-loads only on artifact-emission-surface touches. ● `rules/ten-dimension-check.md` always-on baseline (parent rule's anchor must be live for the companion to demand-load coherently).
+- **Cross-bound with ↔** ↔ `rules/ten-dimension-check.md` (parent rule; anchor binds this companion). ↔ `rules/pre-emission-gate.md` (M4 — bar 3 of the fifteen-bar gate inspects each of the ten verbatim per-dimension bodies enumerated here). ↔ `rules/code-craft-python.md` + `rules/code-craft-shell.md` + `rules/code-craft-markdown.md` + `rules/code-craft-conventions.md` (per-language code-craft rules apply dimensions 4, 7, 8, 10 with language-specific failure tells). ↔ `rules/disclosure-ledger.md` (M2 — deferred dimensions surface as deferrals per the parent rule's disclosure surface).

package/src/apothem/rules/ten-dimension-check.md

@@ -0,0 +1,59 @@
+---
+name: "ten-dimension-check"
+description: "Ten quality dimensions every host-project artifact passes before emission — rigor, coherence, configurability, readability, orphanism, structurality, architecture, naming, scholarly referencing, examples / tests / docs."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Ten Quality Dimensions
+
+## What this rule enforces
+
+This rule binds **M3 — The Ten Quality Dimensions Applied to Every Artifact**. Every artifact the ecosystem produces in a host project MUST be evaluated against ten quality dimensions, maximally meticulously, before emission. The check is a discrete pre-emission step (per `rules/pre-emission-gate.md`) recorded in the working trace — never implicit, never delegated downstream.
+
+Multiple-dimension failure is **multiplicative, not additive**: an artifact that is stale AND orphan AND inconsistently named AND undocumented is a candidate for retraction, not repair.
+
+## Pre-conditions
+
+Applies to every host-project artifact above the trivial threshold per the trivial-vs-non-trivial threshold. Trivial work runs an abbreviated check covering dimensions 4 (readability), 5 (orphanism / staleness), and 8 (naming) only.
+
+## Required behavior
+
+### The Ten Dimensions (Companion Sub-Rule Anchor)
+
+Every artifact MUST pass each dimension individually before emission. The ten dimensions, in canonical order:
+
+1. Scientific rigor.
+2. Consistency · Coherence · Integration · Validity.
+3. Configurability · Irredundancy · Consolidation.
+4. Readability · Intuition · Cleanness.
+5. Orphanism · Staleness.
+6. Structurality · Systemicity · Uniformity · Comprehensiveness.
+7. Architecture.
+8. Naming conventions & uniformity.
+9. Scholarly / technical referencing.
+10. Examples · Tests · Docstrings · Documentation.
+
+(Companion Sub-Rule Anchor) See `rules/ten-dimension-check-dimensions.md` §The Ten Dimensions — Per-Dimension Bodies for the verbatim per-dimension bodies and per-dimension failure tells. The companion demand-loads on artifact-emission surfaces (Markdown, Python, shell, PowerShell under the rules / commands / skills / agents / docs trees and the root `CLAUDE.md`).
+
+### Self-check at emission
+
+Before emitting / committing / handing off, the ten-bar self-check is recorded in the working trace as part of the fifteen-bar pre-emission gate attestation per `rules/pre-emission-gate.md`. Each dimension MUST be marked `pass` or `n/a (with reason)` — never silent, never aspirational.
+
+## Disclosure surface
+
+A failed dimension is either fixed before emission (the standard path) or, when the failure is structural and exceeds the change's scope, surfaced via `rules/disclosure-ledger.md` as a `[Deferral — out-of-scope: dimension N — <description>; tracking: <where>]` marker. A deferred dimension MUST NOT carry a `pass` marking — it carries an explicit `defer` marking with the deferral's tracking location.
+
+## Failure tells
+
+Per-dimension failure tells live at the companion. Cross-cutting tells: a `pass` marking while a checked condition demonstrably fails (an **M4** self-application breach); an attestation block missing the ten-dimension entries; a dimension marked `n/a` without a reason; a `pass` recorded without corresponding evidence in the working trace; an artifact compounding multiple failed dimensions (stale + orphan + mis-named + undocumented) emitted as repaired rather than retracted.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every artifact's pre-emission gate attestation per `rules/pre-emission-gate.md` (the ten-dimension entries are operationalized here as bar 3 of the fifteen-bar gate). Every code-craft surface check at `rules/code-craft-{python,shell,markdown,conventions}.md` (per-language code-craft rules apply dimensions 4, 7, 8, 10 with language-specific failure tells). Every doc-emission step at `skills/*/SKILL.md` and `commands/*.md`.
+- **Satisfies →** the fifteen-mandate registry row **M3 — Ten Quality Dimensions**. the Pre-Emission Gate row 3 (M3 ten-dimensions check).
+- **Established by ↑** the fifteen-mandate registry (ratifies M3). the Pre-Emission Gate (the gate row 3 anchors the dimension check).
+- **Gated by ←** The §8.1 trivial-vs-non-trivial threshold (trivial work runs the abbreviated check). `CLAUDE.md` always-loaded preamble.
+- **Cross-bound with ↔** `rules/ten-dimension-check-dimensions.md` (path-filtered companion sub-rule carrying the verbatim per-dimension bodies and per-dimension failure tells). `rules/pre-emission-gate.md` (M4 — the ten-dimension check is bar 3 of the fifteen-bar gate). `rules/disclosure-ledger.md` (M2 — deferred dimensions surface as deferrals). `rules/operational-mandates.md` §CM-5 Best Solution (the dimension check is the outward-projection form of CM-5's "expert-grade" requirement). `rules/code-craft-python.md` and sibling per-language code-craft rules (per-dimension materialization for code). `rules/etc-extension.md` (dimension 6 Comprehensiveness — the etc.-extension obligation is the upstream behavior this dimension verifies at emission). `rules/source-accessibility.md` (dimension 9 Scholarly / technical referencing — source-trust selection is the upstream behavior this dimension verifies). `rules/authoritative-referencing.md` (dimension 9 — the authoritative-referencing standing mandate outward-projects this referencing dimension).

package/src/apothem/rules/token-budget-discipline.md

@@ -0,0 +1,81 @@
+---
+name: "token-budget-discipline"
+description: "Caps every always-on rule body at 500 substantive tokens; over-budget bodies decompose into path-filtered companion sub-rules per the established demand-load pattern; mechanical matcher and PreToolUse hook enforce the budget at write time."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Token-Budget Discipline for Always-On Rules
+
+## Purpose
+
+Always-on rules load every session; body length multiplies every turn's cost. This rule caps each always-on body so the tier stays small and load-bearing — detail moves to the demand-load surface, where it costs only when relevant.
+
+## Obligations
+
+### 1. Ceiling and Warn Band
+
+- **MAX_SUBSTANTIVE_TOKENS = 500.** Hard ceiling per always-on body. An always-on body over 500 MUST NOT ship.
+- **WARN_BAND_THRESHOLD = 450.** Bodies at 450–500 pass but emit an advisory; the author SHOULD plan a companion before the ceiling triggers.
+
+### 2. Substantive-Token Counter
+
+A substantive token is a whitespace-separated token in the body after excluding three regions:
+
+1. YAML frontmatter (between the head `---` delimiters).
+2. The trailing `## Bindings (§0.j five-direction)` section through end of file.
+3. Every line containing `(Companion Sub-Rule Anchor)`.
+
+None of the three is a standing directive — frontmatter classifies, bindings point, pointer lines name surfaces — so none counts.
+
+### 3. Always-On Classification
+
+A rule is always-on **iff** frontmatter declares `alwaysApply: true` AND `pathFilter:` is empty. Path-filtered rules (`alwaysApply: false` OR non-empty `pathFilter`) demand-load on glob match and are exempt — their cost is paid only when the filter activates.
+
+### 4. Decomposition Pattern (Companion Sub-Rule Anchor)
+
+When an always-on body would exceed the ceiling, decompose along a natural path-filtered seam:
+
+- Author a sibling at `rules/<parent-name>-<aspect>.md` with `alwaysApply: false` and a `pathFilter:` matching the demand-load triggers.
+- Move detail (catalogs, sub-cases, exhaustive enumerations, executable specs, worked examples) to the companion.
+- Trim the parent to load-bearing anchors plus the `(Companion Sub-Rule Anchor)` pointer naming the companion path.
+- Cite the companion under the parent's `Cross-bound with ↔`.
+
+Precedents: `rules/context-management.md` ↔ `rules/context-management-scratch.md`; `rules/interactive-questions.md` ↔ `rules/interactive-questions-sweep-matchers.md`.
+
+### 5. Reading Discipline
+
+Mid-session, read only the needed segment: `Read` with `offset` / `limit`; `Grep` to locate first; `Glob` for traversal. NEVER full-read when a segment suffices.
+
+### 6. Mechanical Enforcement
+
+`conformity/always_on_budget_grep.py` measures every `rules/*.md`; PreToolUse Write/Edit hooks fire it on rule edits; the pre-emission gate FAILs on any always-on body over the ceiling.
+
+## Seriousness Scaling
+
+| Level | Enforcement |
+|-------|-------------|
+| EXPLORING | Advisory; warn-band notes only |
+| PERSONAL_USE | Hard ceiling enforced on rule edits; existing over-budget rules surface as findings |
+| SHARED | Hard ceiling enforced; over-budget edits blocked until decomposed |
+| PUBLIC_LAUNCH | Full enforcement; matcher exit-non-zero blocks emission per the pre-emission gate |
+
+## Anti-Patterns
+
+- **DON'T** add a paragraph to an always-on body for an edge case — **BECAUSE** the edge case belongs in a path-filtered companion that loads only when on the touch surface.
+- **DON'T** raise the ceiling to fit content — **BECAUSE** the ceiling is the discipline; raising it inverts the gradient.
+- **DON'T** count pointer lines toward the budget — **BECAUSE** the pointer is the demand-load handle, not a directive.
+
+## Enforcement
+
+Always-on at every seriousness level, scaling per the table above. Implements the D1 token-budget ratification. Canonical specification for always-on rule body sizing.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every always-on `rules/*.md` body's pre-emission size check; the mechanical matcher at `conformity/always_on_budget_grep.py`; the PreToolUse Write/Edit hook entries that fire the matcher on rule-file edits; every decomposition that splits an over-budget always-on rule into a path-filtered companion.
+- **Satisfies →** the rules registry row "Token Budget Discipline"; the D1 ratification at the upstream specification §2.3 sub-mandate "Always-on rule body budget"; the validation gate sub-mandate "PreToolUse hook fires on rule edits; gate FAILs if any always-on body > 500 tokens substantive".
+- **Established by ↑** The D1 / Q-014 operator ratification (aggressive token optimization with explicit budget enforcement); the demand-load companion-sub-rule pattern at `rules/context-management.md` ↔ `rules/context-management-scratch.md` (validated precedent).
+- **Gated by ←** `CLAUDE.md` always-loaded preamble; the PreToolUse Write/Edit hook entries that wire the matcher.
+- **Cross-bound with ↔** `rules/context-management.md` §7 Context Budget Discipline (the budget framework this rule tightens for the always-on tier); `rules/large-file-generation.md` (sibling write-side budget protocol; this rule extends to read-side / always-on-tier sizing); `rules/persistent-conventions-vigilance.md` §4 Ecosystem Gap Detection (the demand-load companion-sub-rule pattern is itself a gap-closure); `rules/performance-discipline.md` §1 per-class budgets (the budget methodology); `conformity/always_on_budget_grep.py` (the mechanical matcher); `rules/token-efficiency-rewrite.md` (sizing pair — this rule caps; that rule rewrites to fit the cap); `rules/large-file-reading.md` (read-side analogue of the always-on body-size ceiling; both rules optimize the same gradient on different surfaces).

package/src/apothem/rules/token-efficiency-rewrite-protocol.md

@@ -0,0 +1,79 @@
+---
+name: "token-efficiency-rewrite-protocol"
+description: "The full token-efficiency rewrite protocol the always-on parent rule references: the L1 prose-scaffolding elimination classes (filler / throat-clearing / restatement / hedge-padding / ceremonial-scaffolding / connective-bloat), the per-class compression heuristics, the extract-discard-re-derive-verify procedure, and worked before/after examples. Demand-loads when the assistant rewrites an authoring surface for token efficiency."
+pathFilter: "**/*.md, **/*.mdx, **/rules/**, **/skills/**, **/commands/**, **/agents/**, **/docs/**"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Token-Efficiency Rewrite Protocol (Companion Sub-Rule)
+
+## Purpose
+
+Carry the operational detail the parent `rules/token-efficiency-rewrite.md` references at its §2 anchor: the L1 prose-scaffolding elimination classes, the per-class compression heuristics, the extract → discard → re-derive → verify procedure, and worked before/after examples. The parent retains the always-on directive (the two preservation tiers, the anchor-preservation invariant, the semantic-regression gate, the same-change discipline, the when-not-to-rewrite carve-out); this companion carries the protocol bodies. Path-filtered: it loads when the assistant rewrites an authoring surface (Markdown / rules / skills / commands / agents / docs) for token efficiency.
+
+## Obligations
+
+### 1. The Rewrite Procedure — Extract, Discard, Re-Derive, Verify
+
+A token-efficiency rewrite proceeds in four ordered steps:
+
+1. **Extract L2 + L3.** Enumerate the artifact's L2 substantive semantic content (every claim, contract, directive, condition, threshold, citation, observable fact) and its L3 structural anchors (headings the ecosystem cites, rule names, mandate identifiers, `(Companion Sub-Rule Anchor)` pointers, cross-reference paths, binding-block reciprocals, frontmatter, the SPDX banner). L2 + L3 is the invariant surface.
+2. **Discard L1.** Everything outside L2 + L3 is L1 prose scaffolding — eligible for removal per the §2 classes.
+3. **Re-derive minimal prose.** Re-author the artifact carrying L2 verbatim in meaning and L3 byte-identical, L1 removed. The re-derivation is a fresh minimal surface, not a cosmetic edit of the original, per `rules/clean-room-generation.md` §3.3.
+4. **Verify regression.** Confirm every L2 directive / contract / condition / threshold / citation is preserved (the semantic-regression gate) and every L3 anchor appears byte-identical (the anchor-preservation invariant). A softened directive, a dropped condition, or a lost heading blocks the rewrite until repaired.
+
+### 2. The L1 Elimination Classes
+
+L1 prose scaffolding falls into six classes. Each is removable because its removal changes neither an L2 meaning nor an L3 anchor. (Token examples below are the rule's own subject matter — quoted, not authored, per the matcher self-citation exemption.)
+
+- **L1.1 Filler / meta-commentary.** Sentences about the document itself rather than its content (`In this section we discuss …`, `It is important to note that …`, `As mentioned earlier …`). The framed content is L2; the frame is L1.
+- **L1.2 Throat-clearing.** Opening sentences that delay substance (`Before diving in …`, `Let's begin by …`, `Without further ado …`). Replace with the substantive opening.
+- **L1.3 Restatement.** A sentence re-stating the prior one in different words. Compress the pair to one.
+- **L1.4 Hedge-padding.** Content-free qualifiers (`very`, `quite`, `somewhat`, `fairly`, `rather`, `kind of`). Delete the qualifier; the unqualified claim is stronger and shorter. (Distinct from the M8 binding-prescription hedging that is a definitiveness defect per `rules/definitiveness.md`; this is the no-information-padding subset.)
+- **L1.5 Ceremonial scaffolding.** Announcer phrases before a self-evident structure (`Here are the steps:`, `The following list enumerates …`, `Consider the following table:`). The list / table is L2; the announcement is L1.
+- **L1.6 Connective bloat.** Multi-word connectives with a one-word equivalent (`in order to` → `to`, `due to the fact that` → `because`, `at this point in time` → `now`, `in the event that` → `if`). Substitute the shorter form.
+
+### 3. Per-Class Compression Heuristics
+
+Each class resolves on one test: **does removing or compressing the span change an L2 meaning or an L3 anchor?** If no, remove or compress; if yes, the span is L2 / L3 and MUST be preserved.
+
+- **L1.1 / L1.2 / L1.5** — delete the span outright; the substance it framed stands alone.
+- **L1.3** — keep the clause with the more specific L2 content; delete its restatement.
+- **L1.4** — delete the qualifier word; leave the claim.
+- **L1.6** — substitute the one-word equivalent in place.
+
+The heuristic is conservative: when removal is uncertain (the span may carry an L2 nuance), the span is preserved. Token-efficiency never trades a directive's meaning for a shorter surface.
+
+### 4. Worked Examples
+
+**Example A — filler + connective bloat (L1.1 + L1.6).**
+
+- **Before:** "It is important to note that, in order to pass the gate, the artifact must carry a header." (18 words)
+- **After:** "To pass the gate, the artifact must carry a header." (10 words)
+- L2 preserved: the gate requires a header. L1 removed: the `It is important to note` frame; `in order to` → `to`.
+
+**Example B — throat-clearing + restatement (L1.2 + L1.3).**
+
+- **Before:** "Before we get into the specifics, let's establish the baseline. The baseline is the set of tests that pass before the change. In other words, the baseline is the pre-change passing tests." (32 words)
+- **After:** "The baseline is the set of tests that pass before the change." (12 words)
+- L2 preserved: the baseline definition. L1 removed: the throat-clearing opener and the `in other words` restatement.
+
+**Example C — L3 anchor preserved under compression.**
+
+- **Before:** "## Required behavior\n\nIt should be noted that the following section, namely the required-behavior section, mandates that every option carries a recommended marker."
+- **After:** "## Required behavior\n\nEvery option carries a recommended marker."
+- L3 preserved byte-identical: the `## Required behavior` heading (an anchor the ecosystem cites). L2 preserved: the option-marker mandate. L1 removed: the self-referential meta-commentary.
+
+## Enforcement
+
+Path-filtered (the seven glob patterns in this rule's `pathFilter` field — `**/*.md`, `**/*.mdx`, `**/rules/**`, `**/skills/**`, `**/commands/**`, `**/agents/**`, `**/docs/**`), demand-loaded companion to `rules/token-efficiency-rewrite.md`. The parent carries the always-on directive (two preservation tiers, anchor-preservation invariant, semantic-regression gate, same-change discipline, when-not-to-rewrite carve-out); this companion carries the four-step procedure, the six L1 elimination classes, the per-class compression heuristics, and the worked examples. The mechanical matcher at `conformity/token_efficiency_grep.py` operationalizes the L3 anchor-diff zero-drift check.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every token-efficiency rewrite's L1-elimination pass (the six §2 classes); the per-class compression decision (§3 heuristics); the four-step extract → discard → re-derive → verify procedure (§1).
+- **Driven by ←** `rules/token-efficiency-rewrite.md` §2 (the parent's anchor to this companion's full protocol).
+- **Satisfies →** The token-efficiency rewrite protocol's detail tier; the parent rule's promise that the full protocol, L1 elimination classes, and per-class compression heuristics live at the path-filtered companion.
+- **Established by ↑** `rules/token-efficiency-rewrite.md` (parent-rule anchor); `rules/clean-room-generation.md` §3 / §5 (the re-writing and prose disciplines this protocol specializes for token efficiency).
+- **Cross-bound with ↔** `rules/token-efficiency-rewrite.md` (parent rule; §2 anchor binds this companion). `rules/token-budget-discipline.md` (the always-on body sizing cap this rewrite fits content into). `rules/clean-room-generation.md` (§3 re-writing protocol + §5 prose discipline — L1 elimination is the token-efficiency projection of §5's sentence-level justification). `rules/definitiveness.md` (M8 — L1.4 hedge-padding is the no-information subset; binding-prescription hedging is the M8 defect). `rules/bidirectional-binding.md` (§2 — L3 anchor loss is a half-edge failure on the same axis). `conformity/token_efficiency_grep.py` (the mechanical matcher).

package/src/apothem/rules/token-efficiency-rewrite.md

@@ -0,0 +1,77 @@
+---
+name: "token-efficiency-rewrite"
+description: "Rewrite protocol for token-efficient content — re-derives prose to a minimal surface while preserving L2 substantive semantics and L3 structural / load-bearing anchors; pairs with token-budget-discipline (sizing) and clean-room-generation §3 (re-writing protocol)."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Token-Efficiency Rewrite Protocol
+
+## Purpose
+
+Token-efficiency is a rewrite discipline, not a one-shot compression. Where prose carries surplus tokens — filler, restatement, throat-clearing, paraphrase of the literal — the rewrite re-derives it to a minimal surface that preserves what matters and discards what does not. Operationalises the operator-ratified token-efficiency mandate alongside `rules/token-budget-discipline.md` (sizes the always-on tier) and `rules/clean-room-generation.md` §3 (the canonical re-writing protocol).
+
+## Obligations
+
+### 1. The Two Preservation Tiers
+
+Every rewrite preserves two tiers:
+
+- **L2 — Substantive semantic content.** Every claim, contract, directive, condition, threshold, citation, and observable fact the prose asserts. L2 is carried forward verbatim in **meaning**; expression MAY differ.
+- **L3 — Structural / load-bearing anchors.** Section headings the ecosystem cites; rule names; mandate identifiers (M-N / CM-N); `(Companion Sub-Rule Anchor)` pointer lines; cross-reference paths; binding-block reciprocal pointers; frontmatter; header.
+
+L2 + L3 are the invariant surface. Anything outside them is **L1 prose scaffolding** — eligible for compression.
+
+### 2. The Rewrite Discipline (Companion Sub-Rule Anchor)
+
+The rewrite proceeds: extract L2 + L3 → discard L1 → re-derive minimal prose carrying L2 verbatim and L3 byte-identical → verify regression. Full protocol with worked examples, L1 elimination classes, and per-class compression heuristics lives at the path-filtered companion. (Companion Sub-Rule Anchor) See `rules/token-efficiency-rewrite-protocol.md`.
+
+### 3. Anchor-Preservation Invariant
+
+Every L3 anchor in the pre-rewrite artifact MUST appear byte-identical in the post-rewrite artifact. A renamed heading, a deleted section anchor, a dropped `(Companion Sub-Rule Anchor)` pointer, a removed mandate-identifier — each is a structural failure on the same axis as a half-edge per `rules/bidirectional-binding.md` §2. The matcher `conformity/token_efficiency_grep.py` diffs L3 anchors pre / post and FAILs on any drift.
+
+### 4. Semantic-Regression Gate
+
+Every directive, contract, condition, and threshold from the pre-rewrite artifact MUST survive into the post-rewrite artifact. The rewrite MUST NOT soften a directive (`must` → `should`), remove a condition, drop a threshold, or elide a citation. The regression gate at `rules/clean-room-generation.md` §3.5 applies in full; this rule extends it to the token-efficiency class with explicit L2 enumeration.
+
+### 5. Same-Change Discipline
+
+A rewrite ships in one change-set: the rewritten prose AND the L3-anchor diff (mechanical zero-drift) AND the L2-preservation attestation (per `rules/pre-emission-gate.md`). Splitting rewrite from regression-verification across commits leaves the artifact in a non-conformant transient state.
+
+### 6. When Not to Rewrite
+
+The rewrite is **inapplicable** (a no-op; the artifact passes the gate as-is) to:
+
+- prose already minimal under the token-budget ceiling;
+- L1-rich prose authored for didactic purposes (tutorials, worked examples whose teaching value depends on the scaffold);
+- aspirational or quoted material whose source-fidelity invariant forbids re-derivation.
+
+## Seriousness Scaling
+
+| Level | Enforcement |
+|-------|-------------|
+| EXPLORING | Advisory; rewrites authored on explicit operator request |
+| PERSONAL_USE | Rewrite mandatory on over-budget always-on rules; L3 anchor-diff zero-drift verified |
+| SHARED | Full discipline; semantic-regression gate runs on every rewrite |
+| PUBLIC_LAUNCH | Full enforcement; matcher exit-non-zero blocks emission |
+
+## Anti-Patterns
+
+- **DON'T** drop a section heading the ecosystem cites — **BECAUSE** L3 anchors are reciprocal-binding surfaces; their loss orphans every back-pointer.
+- **DON'T** soften a `must` to a `should` to save a token — **BECAUSE** L2 directive strength is invariant under rewrite.
+- **DON'T** collapse a closed enumeration to "etc." — **BECAUSE** exhaustiveness is L2 per `rules/definitiveness.md` §2; the closure is the contract.
+- **DON'T** rewrite a tutorial's worked example to its bullet-form summary — **BECAUSE** the scaffold is the teaching surface, not L1 noise.
+
+## Enforcement
+
+Always-on at every seriousness level, scaling per the table above. Canonical specification for the token-efficiency rewrite protocol; pairs with `rules/token-budget-discipline.md` (sizing) and `rules/clean-room-generation.md` §3 (re-writing).
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every token-efficiency rewrite across `rules/`, `commands/`, `skills/`, `agents/`, `docs/`; the mechanical matcher at `conformity/token_efficiency_grep.py`; the L3 anchor-diff zero-drift verification at every rewrite emission; the L2-preservation attestation at every rewrite's gate row.
+- **Satisfies →** The token-efficiency rewrite directive; `CLAUDE.md` rules-registry row "Token-Efficiency Rewrite"; the ecosystem's always-on token-efficiency posture.
+- **Established by ↑** The operator-ratified token-efficiency mandate and the precedent re-writing protocol at `rules/clean-room-generation.md` §3.
+- **Gated by ←** `CLAUDE.md` always-loaded preamble; the PreToolUse Write/Edit hook entries that wire `conformity/token_efficiency_grep.py`.
+- **Cross-bound with ↔** `rules/clean-room-generation.md` §3 (re-writing protocol; this rule is the token-efficiency specialisation of §3 with L2 / L3 tiers made explicit); `rules/token-budget-discipline.md` (sizing pair — that rule caps; this rule rewrites to fit the cap); `rules/large-file-generation.md` (CM-23 write-side incremental-append budget protocol; this rule complements at the read-side / always-on rewrite tier); `rules/pre-emission-gate.md` (bar inspection of L3 anchor-diff zero-drift and L2-preservation attestation); `rules/bidirectional-binding.md` §2 (L3 anchor loss is a half-edge failure on the same axis); `rules/definitiveness.md` (M8 — closed-enumeration exhaustiveness is L2 invariant); `rules/token-efficiency-rewrite-protocol.md` (path-filtered companion carrying the full protocol, L1 elimination classes, worked examples); `conformity/token_efficiency_grep.py` (the mechanical matcher).