@ahmed-g-gad/apothem 0.1.1

package/src/apothem/rules/production-ready-prs.md

@@ -0,0 +1,83 @@
+---
+name: "production-ready-prs"
+description: "Every change the agent makes in a host project is delivered in production-ready form — tests + docs + CHANGELOG entry + conformant commit message + CI green in the same change-set. The seven visibility surfaces (what-is-this / how-to-install / is-it-alive / is-it-safe / how-to-contribute / can-I-trust / what-changed) are honored; gaps surface as findings rather than silently entrenched."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Production-Ready Discipline on Host-Project Artifacts
+
+## What this rule enforces
+
+This rule binds **M15 — Production-Ready Discipline on Host-Project Artifacts**. Every change the agent makes in a host project **MUST** ship in **production-ready form** in one change-set: tests, docs, CHANGELOG entry, conformant commit message, CI green, supply-chain posture preserved, release-engineering invariants preserved. Where the host is not yet production-ready (missing LICENSE / CONTRIBUTING / CHANGELOG / CI / tests / examples), the agent **MUST NOT** silently entrench the gap — it surfaces the gap as an inquiry per §5 and proceeds under the user's choice.
+
+## Pre-conditions
+
+Applies to software-project work (a versioned project with a build / package / release surface) whenever a change affects a user-facing surface (public API, CLI, configuration, documentation, behavior, build / package / release); a non-software session — plain chat, cowork, research, or writing with no code, build, or release artifact — is outside its scope. Trivial-scope edits per the trivial-vs-non-trivial threshold are exempt from the full discipline; the commit-message-conformity and CI-green sub-clauses still bind.
+
+## Required behavior
+
+### 1. The Same-Change-Set Discipline
+
+A code change **MUST** ship **all** of the following in **one** change-set:
+
+| Element | Ships when |
+|---|---|
+| **Tests** | Code touched or new public surface introduced |
+| **Documentation** | Any user-facing surface touched |
+| **CHANGELOG entry** | User-facing change, per host format (Keep-a-Changelog `[Unreleased]` baseline) |
+| **Conformant commit message** | Every commit, per the host's ratified convention |
+| **CI green** | Change-set passes the host's full CI gate |
+| **CODEOWNERS reviewers** | Host has CODEOWNERS and the change touches owned paths |
+| **License header** | Host policy requires headers on new source files |
+| **Migration guide** | The change is breaking |
+| **Deprecation notice** | The change deprecates surface |
+| **Example** | A new feature is introduced — runnable and CI-tested |
+
+Deferred follow-ups ("I'll add tests / docs / CHANGELOG later") are forbidden: they never land, and production-readiness is violated at the merge boundary.
+
+### 2. The Seven Visibility Surfaces (Companion Sub-Rule Anchor)
+
+The seven visibility surfaces — what-is-this, how-to-install, is-it-alive, is-it-safe, how-to-contribute, can-I-trust, what-changed-and-when — are kept current on every change; gaps route to §5. (Companion Sub-Rule Anchor) See `rules/production-ready-prs-surfaces.md` §1.
+
+### 3. Supply-Chain Posture Preservation (Companion Sub-Rule Anchor)
+
+Every change preserves supply-chain posture: no unpinned dependency, no secret literal, no permission escalation, no unpinned GitHub Actions, no unsigned release artifact where signing is ratified. (Companion Sub-Rule Anchor) See `rules/production-ready-prs-surfaces.md` §2.
+
+### 4. Release-Engineering Invariants (Companion Sub-Rule Anchor)
+
+Versioning honored, tag-to-version consistency, tag signing where ratified. (Companion Sub-Rule Anchor) See `rules/production-ready-prs-surfaces.md` §3.
+
+### 5. Gap-Surfacing Discipline
+
+When the host is missing a production-ready surface (LICENSE, CONTRIBUTING, CHANGELOG, CI, tests, examples), the agent **MUST NOT** silently install it — it surfaces the gap as an inquiry per `rules/authority-inquiry.md` with options annotated per `rules/option-annotation.md`. Silent installation of long-lived ratifications is forbidden per the required-category inquiries at `rules/authority-inquiry.md` §10.
+
+### 6. Commit-Message Discipline (Companion Sub-Rule Anchor)
+
+Every commit message honors the host's ratified convention discovered per `rules/host-discovery.md`, and the **human-only authorship** invariant binds every git surface — the agent never attributes itself or the underlying model / harness / vendor to any commit, trailer, branch, tag, or PR field. (Companion Sub-Rule Anchor) See `rules/production-ready-prs-surfaces.md` §4.
+
+### 7. CI-Green Discipline (Companion Sub-Rule Anchor)
+
+The change-set is CI-green before the change is considered complete: lint / format / type-check / test pass, coverage holds, security scans clean, build succeeds, docs build clean. CI failures are diagnosed and fixed in the same change-set, never deferred or marked flaky without root-cause. (Companion Sub-Rule Anchor) See `rules/production-ready-prs-surfaces.md` §5.
+
+### 8. Modern Project Surface (Companion Sub-Rule Anchor)
+
+Every host project — and apothem itself, by self-application — ships a modern project surface: paired multi-OS install scripts (`scripts/installer/install.sh` + `install.ps1`), an update / auto-update path (read-only by default), paired uninstall scripts (timestamped-backup default, unsafe-target refusal), a logo asset at `assets/logo.svg`, a modern centered README header, and an `## Install` section with one-shot / manual / verify sub-paths. (Companion Sub-Rule Anchor) See `rules/production-ready-prs-surfaces.md` §6 for the full §6.1–§6.7 specification.
+
+## Disclosure surface
+
+Outcomes are recorded in the disclosure ledger per `rules/disclosure-ledger.md` using the canonical `[Production-Ready — …]` / `[Visibility-Gap — …]` / `[Supply-Chain — …]` / `[Release-Engineering — …]` / `[Modern-Surface — …]` marker shapes. (Companion Sub-Rule Anchor) See `rules/production-ready-prs-surfaces.md` §1–§6.
+
+## Failure tells
+
+Same-change-set violations: "I'll add tests in a follow-up"; a breaking change with no migration guide; an `[Unreleased]` CHANGELOG lagging the codebase; a CI failure marked flaky without diagnosis; lint findings persisting into the merge. The visibility / supply-chain / release-engineering / modern-surface failure tells are enumerated alongside the moved sections. (Companion Sub-Rule Anchor) See `rules/production-ready-prs-surfaces.md` §1–§6.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every change the agent makes in a host project (the same-change-set discipline is the production-readiness floor). ● Every CHANGELOG entry, every commit message, every CI invocation across the host. ● The seven visibility surfaces' continuous maintenance across the host's lifecycle. ● The `production-ready-pr-grep` mechanical matcher at `conformity/production_ready_pr_grep.py` — operationalizes the §1 same-change-set discipline. ● The `secret-leak-grep` and `unpinned-action-grep` mechanical matchers at `conformity/` — operationalize the §3 supply-chain posture preservation.
+- **Satisfies →** ● the fifteen-mandate registry row **M15 — Production-Ready**. ● the Pre-Emission Gate row 15 (M15 production-ready check).
+- **Established by ↑** ● the fifteen-mandate registry (ratifies M15). ● the Pre-Emission Gate row 15. ● Keep-a-Changelog convention (the upstream changelog standard this rule projects). ● Conventional Commits specification (the upstream commit-message convention this rule honors per host-discovery).
+- **Gated by ←** ● The trivial-vs-non-trivial threshold (trivial-scope edits run an abbreviated check covering commit-conformity and CI-green only). ● `CLAUDE.md` always-loaded preamble.
+- **Cross-bound with ↔** ↔ `rules/production-ready-prs-surfaces.md` (path-filtered companion sub-rule carrying the §2 visibility surfaces, §3 supply-chain catalog, §4 release-engineering invariants, §6 commit-message discipline detail, §7 CI-green catalog, and §8 modern-project-surface specification). ↔ `rules/agile-sprints.md` (M11 — the DoD's `production-ready` criterion delegates here; the same-change-set discipline IS the DoD's production-ready clause materialized). ↔ `rules/disclosure-ledger.md` (M2 — production-ready outcomes recorded in the ledger). ↔ `rules/authority-inquiry.md` (M5 — visibility-gap inquiries route through the canonical channel; long-lived ratifications like LICENSE / CHANGELOG-format / CI-platform never silently installed). ↔ `rules/option-annotation.md` (M7 — every visibility-gap inquiry's option set carries the Recommended marker plus concrete-driver rationale). ↔ `rules/code-craft-python.md` + `rules/code-craft-shell.md` + `rules/code-craft-markdown.md` (M13 — code-craft sub-elements feed into the same-change-set tests / docs requirements). ↔ `rules/systemic-participation.md` (M14 — new components introduced via change-sets honor both the four-relations declaration and the production-ready discipline). ↔ `rules/host-discovery.md` (M1 — commit-message convention, action-pinning policy, release-signing requirement all discovered). ↔ `rules/sota-elevation.md` (production-ready is the floor; SOTA lifts the ceiling). ↔ `rules/i18n-discipline.md` (M15 — ≥80% review completion gate). ↔ `rules/freshness-facade.md` (M15 — the current-version-only release facade this rule's release-engineering discipline upholds). ↔ `rules/living-docs.md` (M15 — the production-ready same-change-set discipline this documentation analogue projects onto the docs surface).

package/src/apothem/rules/propagation.md

@@ -0,0 +1,63 @@
+---
+name: "propagation"
+description: "Every mutation of any artifact propagates, in the SAME change-set, to every dependent reference across the whole repository's reference graph — code, tests, docs, root files, `.github`, CHANGELOG, harness-rendered templates, the harness registry, plugin manifests, and cross-rule bindings. A mutation (add / edit / remove / rename / move / split / merge / deprecate) that lands without its reference updates is an orphan / half-edge finding. Unifies the docs-tier (living-docs) and component-tier (systemic-participation) propagation disciplines to the full reference graph; the existing drift gates are its mechanical arm."
+pathFilter: "**/*.py, **/*.md, **/*.mdx, **/*.json, **/*.yaml, **/*.yml, **/*.toml, **/*.sh, **/*.ps1, **/*.ts, **/*.js, **/*.mjs, **/*.css, **/*.mdc, **/*.txt"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Propagation — Same-Change-Set Sync to the Full Reference Graph
+
+## What this rule enforces
+
+Every mutation of any artifact MUST propagate, **in the same change-set**, to **every reference** across the repository's reference graph. A mutation is not done when the artifact changes — it is done when every dependent surface that references it is updated alongside it. This rule is the unifying generalization of the two existing propagation disciplines — `rules/living-docs.md` (docs tier) and `rules/systemic-participation.md` (component tier) — extended to the **full** reference graph, with the existing drift gates as its mechanical arm.
+
+## Pre-conditions
+
+Applies whenever an artifact other surfaces reference is mutated. Trivial-scope single-line edits with no downstream reference are exempt; the obligation applies the moment a mutation changes a name, path, signature, count, public surface, or any value another surface depends on.
+
+## Required behavior
+
+### 1. Every mutation class triggers propagation
+
+The triggering mutation classes are the closed set **{add, create, edit, modify, remove, delete, rename, move, split, merge, deprecate}**. Each, applied to a referenced artifact, triggers the same-change-set propagation obligation: a rename propagates to every citation of the old name; a removal propagates to (and removes) every reference to the removed artifact; an addition propagates to every index / registry / catalog that should list it.
+
+### 2. The full reference graph
+
+Every mutation propagates to the union below. The **component tier** (Code, Tests, Examples, READMEs, `.github`) is owned by `rules/systemic-participation.md` and the **docs tier** (documentation + source-generated reference pages) by `rules/living-docs.md` — this rule cites those owners for their per-surface obligations rather than restating them, and adds the surfaces neither sibling covers (AI-memory canon, CHANGELOG, harness-rendered templates / registry / plugin manifests, website catalog, cross-rule bindings):
+
+- **Code** — dependent imports, call-sites, type references.
+- **Tests** — tests exercising or snapshotting the mutated surface (incl. behavior-diff golden fixtures).
+- **Docs** — documentation pages; source-generated reference pages regenerated per `rules/living-docs.md`.
+- **Examples · READMEs · root files** — example scaffolds, per-folder READMEs, root-level singletons.
+- **`.github`** — workflows, issue / PR templates that reference the surface.
+- **AI-memory surfaces** — `CLAUDE.md` / `AGENTS.md` / `.github/copilot-instructions.md` canon + memory indexes.
+- **CHANGELOG** — a user-facing change records an entry.
+- **Harness-rendered templates · harness registry · plugin manifests** — the per-harness templates, `harness_registry.py`, and `.claude-plugin/plugin.json` (regenerated from its generator when commands / agents change).
+- **Website catalog** — the docs-site catalog entry for the surface.
+- **Cross-rule bindings** — reciprocal `## Bindings` back-pointers per `rules/bidirectional-binding.md`.
+
+### 3. Mechanically attestable — the drift-gate arm
+
+A mutation landing without its reference updates is an orphan / half-edge finding. The mechanical arm is the existing gate set; this rule binds, not duplicates, them:
+
+- `conformity/orphan_output_grep.py` — orphan outputs (no consumer / no index / no provenance).
+- `conformity/binding_reciprocity_grep.py` — half-edge cross-rule bindings.
+- `.github/workflows/docs-drift.yml` + source-generated reference-page regeneration (`site/scripts/update-reference-inventory.mjs`) — docs drift.
+- The plugin-manifest generator consistency test (`build_plugin_manifest` vs. the committed manifest) — manifest drift.
+- The behavior-diff regression wall — install-output drift.
+
+A new propagation surface the existing gates do not cover surfaces as a gap per `rules/persistent-conventions-vigilance.md` §4 (a candidate new matcher) — never a silent omission.
+
+## Failure tells
+
+A renamed symbol whose old name still appears at a call-site. A new command added without regenerating `.claude-plugin/plugin.json`. A removed artifact whose docs page / catalog entry / registry row survives. A user-facing change with no CHANGELOG entry. A new public surface absent from the reference pages. A cross-rule citation with no reciprocal back-pointer. A mutated surface whose behavior-diff golden fixture was not regenerated.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every mutation's same-change-set reference-graph update across the repo. The regeneration of generated artifacts (plugin manifest, reference pages, behavior-diff fixtures) when their source mutates. The CHANGELOG entry on every user-facing change.
+- **Driven by ←** The WS-C propagation/sync mandate; the operator directive that every amendment propagate to every reference across the whole repo/project.
+- **Satisfies →** The MAXIMAL reference-graph integrity end-state (no orphan, no half-edge, no stale reference); the CM-8 keystone (once propagation is mechanically attestable, every workstream's same-change-set obligation is enforced rather than manual).
+- **Established by ↑** `rules/living-docs.md` (the docs-tier propagation this rule generalizes); `rules/systemic-participation.md` (the component-tier propagation this rule generalizes); `rules/bidirectional-binding.md` (the reciprocity surface).
+- **Cross-bound with ↔** `rules/living-docs.md` (docs tier) · `rules/systemic-participation.md` (component tier) · `rules/bidirectional-binding.md` (binding reciprocity) · `rules/canonical-layout.md` (orphan prevention) · `rules/dynamism.md` (version/badge propagation) · `conformity/orphan_output_grep.py` + `conformity/binding_reciprocity_grep.py` + `.github/workflows/docs-drift.yml` (the mechanical drift-gate arm).

package/src/apothem/rules/recommend-next-step.md

@@ -0,0 +1,106 @@
+---
+name: "recommend-next-step"
+description: "Every command, skill, and phase artifact closes with a Recommended Next Step block — canonical heading, named action, optional rationale — so terminal output never leaves the operator without a definitive forward move. Hedged or absent next-step blocks are structural failures; the mechanical matcher operationalises the check at the pre-emission gate."
+pathFilter: "**/commands/**/*.md, **/skills/**/SKILL.md, **/phases/**/PHASE.md"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Recommended Next Step — Definitive Forward Move on Every Terminal Surface
+
+## What this rule enforces
+
+Every command file, skill entry-point, and phase artifact MUST close its terminal section with a **Recommended Next Step** block naming a definitive forward move the operator can take next — not a hedged suggestion, not a list of possibilities without a recommendation, not a silent end-of-document. Terminal sections that omit the block or carry it in a non-conformant shape are structural failures.
+
+## Pre-conditions
+
+Applies to every artifact under the path-filter — `commands/**/*.md`, `skills/**/SKILL.md`, `phases/**/PHASE.md`. The block lives at the artifact's **tail** (the final section before any closing `## Bindings`, appendix, or metadata footer). Trivial-scope edits that do not modify the terminal section are exempt from re-authoring the block but inherit the existing block's conformance.
+
+## Required behaviour
+
+### 1. Canonical Heading
+
+The block opens with one of two ratified headings:
+
+- `## Recommended Next Step` — **preferred**; single-action terminal surfaces (one canonical forward move).
+- `## Next Steps` — acceptable when the surface genuinely admits a small ordered set of forward moves (two or three; **never more than four** — beyond four routes through the option-annotation surface per `rules/option-annotation.md`).
+
+Heading-level drift (`###` / `####`), alternate phrasings (`## What's Next`, `## Follow-Up`, `## Suggested Actions`), and missing headings are non-conformant.
+
+### 2. Named Action
+
+The block body MUST name a **definitive action** that is:
+
+- **Imperative-verb-led.** "Run `apothem verify`", "Author the suite specification", "Invoke `/plan-execute` to advance the next phase". Never a hedged participle ("you might consider running …") nor a question ("should you run X?").
+- **Referenced by identifier.** Commands cite their slash-name (`/plan-spec`); scripts cite their path (`scripts/dev/audit.py`); files cite their canonical location.
+- **Definitive per `rules/definitiveness.md`.** Hedging vocabulary (maybe, might, could, should probably, usually, typically) is forbidden in the action statement. The block is a binding next-move declaration, not a probabilistic forecast.
+
+### 3. Optional Rationale Clause
+
+The block MAY carry a one-sentence rationale clause naming why this action is the canonical next step. The rationale cites a concrete driver per `rules/option-annotation.md` §2 — observed state of the artifact set, a rule citation, a named prerequisite gate. A rationale clause without a concrete driver is non-conformant; omit the rationale rather than fill it with platitude.
+
+### 4. Multi-Action Form (`## Next Steps`)
+
+When the surface admits multiple forward moves, the block uses an ordered list and marks exactly one entry as **Recommended** per `rules/option-annotation.md`:
+
+```markdown
+## Next Steps
+
+1. **Run `apothem verify`** — **Recommended**. Confirms the install reached the canonical end state before further changes land.
+2. Inspect `apothem doctor` output — when verify fails, doctor surfaces the failing precondition.
+3. Re-run the install with `--force` — only when the verify failure traces to a partial install.
+```
+
+A multi-action block without a Recommended marker falls back to the option-annotation rule's zero-recommended fallback (the rationale section names the underdetermined dimensions and routes the choice via inquiry per `rules/authority-inquiry.md`).
+
+### 5. Terminal Placement
+
+The block MUST be the **last substantive section** of the artifact. It precedes only:
+
+- `## Bindings (§0.j five-direction)` (when present per `rules/bidirectional-binding.md`);
+- closing metadata / appendix / disclosure footers.
+
+It MUST NOT precede further substantive sections. A `## Recommended Next Step` followed by `## Implementation Details` is a placement violation — the block has been displaced from its terminal role.
+
+### 6. Per-Surface Materialisation
+
+| Surface | Block role |
+|---|---|
+| `commands/**/*.md` | Names the next command to invoke, the next file to read, or the next operator decision after the command completes. Ties the command into the pipeline shape declared by `rules/canonical-layout.md` M12. |
+| `skills/**/SKILL.md` | Names the canonical follow-up after the skill's procedure completes — the verification step, the index-update step, or the next skill in the chain. |
+| `phases/**/PHASE.md` | Names the next phase per the suite's progress tracker (`PROGRESS.md` Resumption Contract). Phase rollup REPORTs follow the same discipline at their tail. |
+
+## Mechanical enforcement
+
+The matcher `conformity/recommend_next_step_grep.py` operationalises the check. For every artifact under the path-filter it verifies:
+
+- presence of `## Recommended Next Step` or `## Next Steps`;
+- heading placement at the artifact's terminal section per §5;
+- absence of hedging vocabulary inside the block body per `rules/definitiveness.md`;
+- multi-action form carries exactly one `**Recommended**` marker per §4.
+
+Findings surface at the pre-emission gate per `rules/pre-emission-gate.md` — HIGH-severity on a missing block, MEDIUM-severity on shape drift.
+
+## Disclosure surface
+
+Block emission is recorded in the disclosure ledger per `rules/disclosure-ledger.md`:
+
+- `[Next-Step — emitted: <artifact-path>; heading: <Recommended Next Step | Next Steps>; action: <imperative-summary>]` for new blocks.
+- `[Next-Step — refreshed: <artifact-path>; reason: <pipeline-shape-change | action-target-renamed | downstream-surface-retired>]` for updates.
+
+## Failure tells
+
+An artifact ending mid-section with no block. A block headed `## Conclusion` / `## Wrap-Up` / `## What's Next` (heading drift). A block body opening with "You might want to …" / "Consider …" / "It's usually a good idea to …" (hedging — M8 violation). A `## Next Steps` list of seven items with no Recommended marker (cardinality drift; route through `rules/option-annotation.md` instead). A block placed mid-artifact with substantive sections following it (placement violation). A `## Recommended Next Step` whose action names no identifier — "run the next thing" (action under-specified). A rationale clause that says "this is generally the safer path" with no concrete driver (vague-rationale forbid list per `rules/option-annotation.md`).
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every terminal section of every `commands/**/*.md`, `skills/**/SKILL.md`, and `phases/**/PHASE.md` under the path-filter. ● The mechanical matcher at `conformity/recommend_next_step_grep.py`. ● Every pipeline-transition surface where one command's terminal block names the next command's invocation. ◐ The Resumption Contract's "next action" field at `PROGRESS.md` for phase artifacts.
+- **Satisfies →** ● `CLAUDE.md` operating principle "every terminal surface emits a definitive next move". ● `rules/canonical-layout.md` M12 reporting-surface discipline (the terminal block IS the reporting surface's forward-move declaration). ● `rules/definitiveness.md` M8 (the next-move declaration meets the definitiveness floor).
+- **Established by ↑** ● The pre-emission gate at `rules/pre-emission-gate.md` (the M3 ten-dimension check's dimension 6 structurality enforces terminal-section completeness). ● `rules/canonical-layout.md` (phase / sub-phase reporting tier where the block lives).
+- **Gated by ←** ● The path-filter (the three glob patterns) — this rule activates only on terminal-emission-surface touches. ● The trivial-scope threshold (edits not touching the terminal section inherit the existing block's conformance).
+- **Cross-bound with ↔** ↔ `rules/definitiveness.md` (M8 — the named action carries no hedging vocabulary; the next-move declaration is binding, not probabilistic). ↔ `rules/canonical-layout.md` (M12 — the block is the reporting tier's forward-move surface). ↔ `rules/option-annotation.md` (M7 — multi-action `## Next Steps` blocks carry the Recommended marker plus concrete-driver rationale). ↔ `conformity/recommend_next_step_grep.py` (the mechanical matcher operationalising the check at the pre-emission gate). ↔ `rules/pre-emission-gate.md` (M4 — block presence is a gated bar at terminal-surface emission). ↔ `rules/disclosure-ledger.md` (M2 — block emissions and refreshes recorded in the ledger). ↔ `rules/determinism.md` (the terminal next-move block is rendered deterministically — same artifact state yields the same forward-move declaration). ↔ `rules/own-voice-reimplementation.md` (the terminal forward-move discipline this rule defines is the tail discipline own-voice reimplementations honor). ↔ `rules/session-closure.md` (the terminal Recommended Next Step this rule owns is element (a) of the three-element session close; session-closure binds it as one of three closure elements for every session, not only path-filtered terminal artifacts). ↔ `rules/living-docs.md` (the living-docs tail honours the terminal forward-move discipline).
+
+## Recommended Next Step
+
+**Run `python scripts/inject-header.py --mode fix-in-place src/apothem/rules/recommend-next-step.md`** to install the canonical single-line SPDX license header per the project's File Headers discipline before the artifact lands at its emission gate.

package/src/apothem/rules/refactoring-discipline.md

@@ -0,0 +1,76 @@
+---
+name: "refactoring-discipline"
+description: "Agent-driven refactoring is test-gated, one-at-a-time, plan-first, and continuous: a behavior-preserving refactor holds a GREEN test baseline before the first edit and after (the before-and-after contract); addresses exactly one concern in an isolated workspace; proceeds only from a reviewed plan after maximal context-gathering; and runs continuously as the codebase drifts rather than deferred to a crisis. Demand-loaded on refactor-class source edits; the detection signals and full procedure live in the body."
+pathFilter: "**/*.py, **/*.ts, **/*.tsx, **/*.js, **/*.jsx, **/*.mjs, **/*.go, **/*.rs, **/*.java, **/*.kt, **/*.rb, **/*.c, **/*.cpp, **/*.h, **/*.swift, **/*.sh, **/*.ps1"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Refactoring Discipline — Test-Gated, One-at-a-Time, Plan-First, Continuous
+
+## What this rule enforces
+
+Agent-driven refactoring MUST be **behavior-preserving, test-gated, isolated to one concern, planned before executed, and continuous**. Five obligations bind: a refactor MUST NOT begin without a **green test baseline** and MUST NOT complete until that same baseline is green again (the before-and-after behavior-preservation contract); it addresses **exactly one concern at a time** in an isolated workspace; execution proceeds only from a **reviewed plan** produced after gathering maximal context; the re-derivation is **clean-room and quality-elevating**, never cosmetic; and refactoring is a **continuous** response to drift, not a deferred crisis. This rule governs refactoring's *workflow and cadence*; the *generation method* (behavioral extraction → clean-room re-derivation → quality elevation → regression gate) is owned by `rules/clean-room-generation.md` §3, and *single-symbol extraction* by the `refactor-extract` skill.
+
+## Pre-conditions
+
+Applies whenever a refactor — a behavior-preserving structural change to existing code — is undertaken in a host project. It does NOT apply to feature work that changes observable behavior (a feature change under its own contracts), nor to pure-formatting normalization (a carve-out auto-decision per `rules/authority-inquiry.md`). The moment a change is framed as "refactor", "clean up", "restructure", "extract", "split", or "consolidate" while preserving behavior, the rule applies.
+
+## Required behavior
+
+### 1. Detection — when to refactor
+
+Refactoring is triggered by observable drift signals, not a fixed schedule. Any one signal is sufficient:
+
+- The agent has become **slower** at implementing changes in the surface.
+- The agent **introduces more defects** per change than when the surface was clean.
+- Bugs appear in **code the change did not touch** — hidden coupling the structure no longer expresses.
+- The agent **can no longer follow instructions precisely** in the surface — the structure obscures intent.
+- The surface has **drifted from its clean state** — accreted responsibilities, leaked abstractions, primitive obsession, duplicated logic.
+
+Each signal is **falsifiable** — an observable the agent confirms before committing. Refactor **early**, at the first sustained signal, not after the surface is unworkable.
+
+### 2. One refactor at a time — isolation
+
+Each refactor addresses **exactly one concern** in an **isolated workspace** (a dedicated git worktree per `rules/agent-orchestration.md` §5.1, or an equivalent isolated branch). Two refactors MUST NOT run concurrently against the same surface — entangled diffs make regression attribution impossible (when behavior breaks, neither refactor reverts or blames cleanly). Refactoring alongside feature work is permitted; two simultaneous *refactors* are not. A multi-concern restructure is decomposed into a sequence of single-concern refactors, each independently test-gated.
+
+### 3. Plan-first — context, then plan, then execute
+
+Before the first edit the agent MUST: (a) **traverse the relevant surface** for a full picture; (b) gather **maximal context** — what to refactor, **why**, and reference exemplars of the target structure where its optimal shape is uncertain; (c) produce a **reviewed refactoring plan** naming the concern, affected files, target structure, and behavior-preservation strategy. Execution proceeds only once the plan is accepted. Editing first and structuring as you go is non-conformant — the plan is the contract the regression gate verifies against.
+
+### 4. Test safety net — green before AND green after
+
+A behavior-preserving refactor carries a test baseline green before the first edit and green again after the last:
+
+- **Before.** Establish a passing test (or behavioral-assertion) baseline capturing the surface's observable contracts. Where none exists, author the assertions per the `test-authoring` skill *before* the refactor begins. A refactor that cannot demonstrate green-before is not ready to start — the baseline is the only proof behavior was preserved.
+- **After.** The **same** baseline passes on completion, with no new defects. A contract that no longer holds blocks the refactor until repaired — the formal behavior-preservation gate per `rules/clean-room-generation.md` §3.5.
+
+The before-and-after gate is non-negotiable: it distinguishes a refactor (behavior preserved, proven) from an undisciplined rewrite (behavior changed, unproven).
+
+### 5. Clean-room, quality-elevating execution
+
+The refactor re-derives the affected unit **clean-room** from its extracted behavioral specification per `rules/clean-room-generation.md` §3 — never a cosmetic edit of the original text — and **elevates quality against a named deficiency** (the leaky abstraction, god function, primitive obsession, or duplication it exists to remove). A change that rephrases without elevating a named deficiency is not a refactor; it is churn.
+
+### 6. Continuous cadence
+
+Refactoring is **continuous maintenance**, a natural part of a codebase's evolution — not a one-time event to eliminate. The agent periodically checks the surfaces it works in for the §1 drift signals and refactors at the first sustained one. Deferring until the surface is unworkable converts cheap continuous maintenance into an expensive crisis rewrite.
+
+## Disclosure surface
+
+Every refactor is recorded in the disclosure ledger per `rules/disclosure-ledger.md`:
+
+- `[Refactor — concern: <single concern>; trigger: <§1 signal>; baseline: green-before/green-after; deficiency-elevated: <named>]` for every completed refactor.
+- `[Refactor — deferred: <concern>; reason: <out-of-scope | sequenced-after-current>; tracking: <where>]` when a surfaced refactor concern is sequenced for later, not executed now (one-at-a-time isolation).
+
+## Failure tells
+
+Two refactors running concurrently against the same surface. A refactor begun with no green test baseline (no proof of the starting contract). A refactor presented as complete without re-running the baseline green (behavior preservation unproven). A "refactor" that rephrases the original without elevating a named deficiency (churn, not refactor). Editing first and planning as you go (no reviewed plan). A refactor deferred until the surface is unworkable, then attempted as one large rewrite (crisis refactoring — the cadence failure). A behavior-changing edit presented as a refactor (a feature change in disguise — routes back to the user as a finding).
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every behavior-preserving refactor's before-and-after test gate; the one-concern-at-a-time isolation invariant on every refactoring workspace; the plan-first sequence on every refactor; the continuous-cadence drift check on every surface the agent works in.
+- **Driven by ←** The §1 drift detection signals (agent slowdown, defect rate, untouched-code bugs, instruction-following degradation, structural drift) that trigger a refactor.
+- **Satisfies →** The behavior-preservation contract for agent-driven refactoring (green-before / green-after); the one-at-a-time isolation floor; the continuous-maintenance cadence.
+- **Established by ↑** `rules/clean-room-generation.md` §3 (the re-writing protocol this discipline gates); the host's ratified test command (the safety net's mechanism).
+- **Cross-bound with ↔** `rules/clean-room-generation.md` (§3 Re-Writing Protocol — behavioral extraction, clean-room barrier, quality elevation, regression gate; this rule gates *when and how* that protocol runs for a refactor). `rules/surgical-manipulation.md` (minimal, anchor-bounded mutation — a refactor's edits are surgical). `rules/agent-orchestration.md` (§5.1 worktree isolation — the isolated workspace for one-at-a-time refactoring). `rules/code-craft-python.md` + sibling per-language code-craft rules (the quality bar the §5 deficiency-elevation targets). `skills/refactor-extract/SKILL.md` (the single-symbol extraction operationalization of this discipline). `skills/test-authoring/SKILL.md` (the §4 safety-net author when no tests exist).

package/src/apothem/rules/session-closure.md

@@ -0,0 +1,44 @@
+---
+name: "session-closure"
+description: "Every session — ad-hoc conversational sessions included, not only plan phases — ends with a formal, verifiable close: a terminal Recommended Next Step, a done/deferred ledger, and a verification attestation. A session that trails off mid-thread, claims done without a checked outcome, or buries deferred work silently is a structural failure. Harness-agnostic; the close is rules text every harness honors."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Session Closure — Every Session Ends With a Formal, Verifiable Close
+
+## Purpose
+
+A session is not finished when the last edit lands; it is finished when it is **closed**. Every session — an ad-hoc conversational exchange as much as a plan phase or a multi-step mission — MUST end with a formal, verifiable close. The operator never inherits a trailing-off thread, an unstated "done", or work that was silently dropped. The close is the session's airtight terminal contract.
+
+## Obligations
+
+### 1. The Three Closure Elements
+
+Every closing turn MUST carry all three, in order:
+
+- **(a) Recommended Next Step.** A terminal, imperative-verb-led, identifier-referenced forward move per `rules/recommend-next-step.md` — the single best action for the session's end state, never a hedge, a question, or a silent stop. On commands / skills / phase artifacts this is the canonical `## Recommended Next Step` block; in conversational prose it is one definitive named action.
+- **(b) Done / Deferred ledger.** An explicit two-column account: what was **completed** this session, and what was **deferred** — each deferral naming a tracking location per the `[Deferral — …]` marker at `rules/disclosure-ledger.md`. Adjacent work touched-but-not-finished is deferred-with-tracking, never elided. Silent over-completion ("said done, left a gap") and silent over-reach are both non-conformant.
+- **(c) Verification attestation.** A statement of **what machine-checkable condition was checked and its outcome** — a gate, test, build, or read a third party reproduces, with pass / fail / n-a-with-reason. Self-assessment ("looks correct") is not a verdict; the attestation cites the objective check behind the completed column. A "done" resting on self-assessment, or on nothing checked, is non-conformant.
+
+### 2. Universality and Scaling
+
+The close binds **every** session, not only plan-suite work. The phase-exit and Stop-hook externalization at `rules/context-management.md` §2.5 / §3 is the plan-suite materialization; this rule extends it to ad-hoc sessions the hook does not reach. Closure **depth** scales to session weight — a trivial exchange emits one line per element, a multi-step mission a full ledger and multi-gate attestation. Depth flexes; **presence does not**. A session emitting zero elements has not closed — it has trailed off.
+
+### 3. Single Canonical Close — No Repetition
+
+The three elements are emitted **once**, as one close — never duplicated in the turn, never re-printed unchanged across turns; on a Stop-condition / goal / loop re-engagement, report only the **delta**. Element (a) IS the terminal `## Recommended Next Step` block, not a second copy; the Stop-hook externalization is file-side, not re-narrated.
+
+## Failure tells
+
+A reply ending mid-thought with no forward move. A "done" resting on self-assessment or no check at all. Deferred work mentioned in passing with no tracking location, or not mentioned. A completed-claim an unchecked gate contradicts. A plan phase that runs the Stop-hook externalization while an ad-hoc session beside it closes on none of the three elements. A close listing next steps but no done/deferred ledger, or a ledger but no attestation. The same close re-printed unchanged across turns.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** ● Every session's terminal turn (the three-element close is the closing-turn floor). ● Every ad-hoc conversational exchange's formal close, extending the plan-suite Stop-hook externalization to sessions the hook does not reach. ● The done/deferred ledger every close emits. ● The verification attestation every "done" claim carries.
+- **Satisfies →** ● The airtight-session-close end state (no trailing-off thread, no unverified "done", no silently-dropped work). ● The advisory-posture invariant that every interaction closes with the single best next action.
+- **Established by ↑** ● The operator mandate that any session — ad-hoc included — ends with a formal, verifiable close. ● `rules/recommend-next-step.md` (the terminal forward-move element). ● `rules/context-management.md` §2.5 (the phase-exit externalization this rule generalizes to ad-hoc sessions).
+- **Gated by ←** ● `CLAUDE.md` always-loaded preamble. ● The §3 scaling clause (a trivial session scales the close down, never away).
+- **Cross-bound with ↔** ↔ `rules/recommend-next-step.md` (element (a) — the terminal Recommended Next Step the close opens with; this rule binds it as one of three closure elements for every session, not only path-filtered terminal artifacts). ↔ `rules/context-management.md` (element (b)+(c) — the Stop-hook / §2.5 phase-exit externalization is the plan-suite materialization of this close; this rule extends it to ad-hoc sessions). ↔ `rules/disclosure-ledger.md` (M2 — the done/deferred ledger's deferral entries use the `[Deferral — …]` marker; the completed column is the change's disclosure surface). ↔ `rules/pre-emission-gate.md` (M4 — the verification attestation element mirrors the gate's per-bar attestation at the session scale; a close's "checked" column is the session-level analog of the gate's bar attestation).

package/src/apothem/rules/sota-elevation-exemplars.md

@@ -0,0 +1,76 @@
+---
+name: "sota-elevation-exemplars"
+description: "Path-filtered companion to `sota-elevation.md` carrying the eight-surface SOTA evaluation lens, the named-exemplar catalogue (cpython / shadcn-ui / Bun / Fumadocs / vite / vitest), per-surface exemplar walks, the upper-bound calibration binding, the Filter-5 aesthetic-demand binding, the gap-surfacing protocol, the disclosure markers, and the failure tells; demand-loaded on README / docs / `.github/` / `site/` touches."
+pathFilter: "**/README.md, **/docs/**, **/.github/**, **/site/**"
+alwaysApply: false
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: SOTA Elevation — Exemplar Catalogue & Eight-Surface Walks (Companion Sub-Rule)
+
+## Purpose
+
+Carry the operational detail the parent rule `rules/sota-elevation.md` anchors: the eight SOTA evaluation surfaces, the named-exemplar catalogue, the per-surface exemplar walks, the upper-bound calibration, the Filter-5 binding, the gap-surfacing protocol, the disclosure markers, and the failure tells. Path-filtered to OSS-distribution user-facing surfaces (README, docs site, CI workflows, site/ scaffold); the parent's always-on payload stays lean while this companion preserves full exemplar fidelity at the demand-load surface.
+
+## Obligations
+
+### 1. The Eight SOTA Evaluation Surfaces
+
+Every user-facing change MUST be audited across all eight surfaces. A change that lands one surface while leaving the others below SOTA is partial-SOTA, not SOTA:
+
+| # | Surface | What "SOTA" means here |
+|---|---|---|
+| 1 | **README modernization** | Centered logo + tagline + badge row + nav strip + Quick-start; depth matching cpython / shadcn-ui / Bun headers. Cites `rules/production-ready-prs-surfaces.md` §6.5. |
+| 2 | **Visibility surfaces** | All seven per `rules/production-ready-prs-surfaces.md` §1 present, current, badge-rendered. |
+| 3 | **Supply-chain producer-pipeline** | Actions pinned to commit-SHA, minimum permissions, ratified release signing, SBOM where applicable, OIDC trust where the registry supports it. |
+| 4 | **CI/CD modernization** | Generic SOTA workflow naming (cpython / django / react / vue pattern); matrix-tested; cache-keyed; concurrency-grouped; reusable workflow composition. |
+| 5 | **Test rigor** | Coverage gate; parametrized; behavior-named; AAA-shaped; cross-platform matrix where the product targets cross-platform. |
+| 6 | **Packaging / type-safety** | Modern manifest schema; `py.typed` marker or equivalent; strict type-check on public API; dynamic version rendering. |
+| 7 | **Observability** | Structured logging (`logging.getLogger(__name__)` / structlog / pino equivalents); deliberate log levels; no `print()` for operational output. |
+| 8 | **Docs SOTA** | Documentation tooling at current SOTA (Fumadocs / VitePress / Docusaurus); folded sidebar; landing distinct from docs; OG cards; mobile-first responsive. |
+
+### 2. Named-Exemplar Catalogue
+
+Every SOTA citation names a **currently-shipping** exemplar as concrete-driver class 6 per `rules/interactive-questions-canonical-shapes.md` §3.2.1. Vague "industry standard" / "best practice" appeals without a named source are non-conformant per `rules/interactive-questions-canonical-shapes.md` §3.2.2.
+
+| Exemplar | Anchors surface(s) | What to copy |
+|---|---|---|
+| **cpython** | 1, 4 | CONTRIBUTING shape; release-engineering rigor; workflow naming (`tests.yml`, `build.yml`); dev-guide depth |
+| **shadcn-ui** | 1, 8 | README header centered pattern; dark-mode-first aesthetic; copy-paste-component documentation; landing-page polish |
+| **Bun** | 1, 8 | performance-first landing; folded sidebar; marketing-quality OG cards; bold typography |
+| **Fumadocs** | 8 | Docs-site IA; MDX-rich pages; Next.js App Router; dedicated landing distinct from docs root; localized routing |
+| **vite** | 8 | VitePress sibling-class clean IA; minimal nav; fast TTFB |
+| **vitest** | 5, 8 | Behavior-named tests; clean docs/test parity; fast-feedback CLI surface |
+
+### 3. Upper-Bound Calibration
+
+When the operator's directive carries `MAXIMAL` (or "best possible", "world-class", "no expense spared", "ALL diversified dimensions"), the calibration ladder at `rules/expertise-posture-elements.md` §2 escalates to the **architectural-rework** rung. Every surface in §1 is inspected; no surface is skipped under time pressure. Mid-tier "production-ready" is the floor `rules/production-ready-prs.md` enforces; SOTA-elevation lifts the ceiling.
+
+### 4. Filter-5 Aesthetic-Demand Binding
+
+SOTA elevation is the outward projection of cognitive-identity Filter 5 (aesthetic demand) per `rules/cognitive-identity-techniques.md` §1. A surface that passes every mechanical bar but lacks conceptual elegance, texture, soul — the "feels inevitable once seen" property — has not yet reached SOTA. Filter 5 is the gate beyond mechanical conformity.
+
+### 5. Gap-Surfacing Protocol
+
+When the host's current state falls short of SOTA on any of the eight surfaces, the gap MUST be surfaced as a finding per `rules/authority-inquiry.md` with options annotated per `rules/option-annotation.md` — never silently entrenched, never deferred without a tracking record. The recommended-option rationale MUST cite a concrete exemplar from §2.
+
+### 6. Disclosure Markers
+
+Outcomes recorded in the disclosure ledger per `rules/disclosure-ledger.md`:
+
+- `[SOTA — elevated: <surface>; exemplar: <project>; from: <prior-state>; to: <new-state>]` for every SOTA-lift.
+- `[SOTA — gap-surfaced: <surface>; current-state: <description>; exemplar-target: <project>; tracking: <inquiry-id | task>]` for every gap.
+- `[SOTA — floor-honored: <surface>]` for surfaces already at SOTA where the change preserves the elevation.
+
+### 7. Failure Tells
+
+A README rewrite that adopts a single SOTA element (e.g., a logo) without the surrounding header pattern (partial-SOTA). A "SOTA" citation that names no exemplar. A workflow renamed to a generic name without the surrounding security-and-permissions polish (surface 4 partial). Docs migrated to a SOTA framework but left at the default theme (surface 8 partial). `MAXIMAL` directive answered with mid-tier "production-ready" output (calibration miss). A gap on any of the eight surfaces entrenched silently instead of surfaced. Aesthetic dismissal ("it's fine") on a surface where Filter 5 has not yet been applied.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every OSS-distribution user-facing surface emission under the path-filter; the eight-surface audit at every README / docs / `.github/` / `site/` touch; the named-exemplar citation requirement at every `[SOTA — …]` marker; the architectural-rework rung escalation on `MAXIMAL` directives.
+- **Satisfies →** `rules/sota-elevation.md` companion anchors (the parent rule's pointers to this companion's eight-surface table, exemplar catalogue, calibration binding, Filter-5 binding, gap-surfacing protocol, disclosure markers, and failure tells).
+- **Established by ↑** `rules/sota-elevation.md` (parent-rule anchor). Exemplar attestation, SOTA-elevation meta-mandate, and README + workflow SOTA directives.
+- **Gated by ←** The path-filter (`**/README.md`, `**/docs/**`, `**/.github/**`, `**/site/**`) — this rule demand-loads only on OSS-distribution user-facing surface touches. `rules/sota-elevation.md` always-on baseline (parent rule must be live for this companion's anchors to surface coherently).
+- **Cross-bound with ↔** `rules/sota-elevation.md` (parent rule; companion anchors bind here). `rules/production-ready-prs-surfaces.md` (§6.5 modern-README escalation cites the parent; this companion's surface 1 + surface 2 materialise the SOTA tier above the production-ready floor). `rules/cognitive-identity-techniques.md` §1 (Filter 5 aesthetic-demand binding at §4). `rules/expertise-posture-elements.md` §2 (calibration ladder at §3). `rules/interactive-questions-canonical-shapes.md` §3.2.1 (concrete-driver class 6 citation requirement) + §3.2.2 (vague-rationale forbid list). `rules/persistent-conventions-vigilance.md` §4 (gap-detection surface). `rules/disclosure-ledger.md` (M2 — disclosure markers at §6).

package/src/apothem/rules/sota-elevation.md

@@ -0,0 +1,52 @@
+---
+name: "sota-elevation"
+description: "SOTA elevation as default posture for OSS distribution projects — every user-facing surface targets the upper bound of contemporary best-practice, calibrated against named exemplar projects (cpython, shadcn-ui, Bun, Fumadocs, vite, vitest) and audited across the eight SOTA evaluation surfaces."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: SOTA Elevation — Default Posture for OSS Distribution Projects
+
+## What this rule enforces
+
+For every OSS distribution project apothem touches, the default posture is **State-Of-The-Art elevation**: every user-facing surface targets the **upper bound** of contemporary best-practice, not the median. "Good enough" is non-conformant when MAXIMAL is reachable. The operator's `MAXIMAL` descriptor in a directive signals escalation to the upper-bound interpretation; absent it, SOTA remains the floor, not a ceiling-on-request. The discipline calibrates against **named, currently-shipping OSS exemplars** — never folklore or "industry standard" appeals without a concrete source.
+
+## Pre-conditions
+
+Applies whenever the artifact under change belongs to an **OSS distribution project** — one that publishes to a public registry (PyPI, npm, crates.io, Maven Central) or maintains a public documentation site, README, or release surface. It does not apply to internal dev-tool harnesses or private artifacts; the CM-7 codebase-vs-process-tooling distinction governs that split. Trivial-scope edits per the trivial-vs-non-trivial threshold still honor the SOTA floor on the surfaces they touch.
+
+## Required behaviour
+
+### 1. Eight SOTA Evaluation Surfaces (Companion Sub-Rule Anchor)
+
+Every user-facing change MUST be audited across eight surfaces: (1) README modernization, (2) visibility surfaces, (3) supply-chain producer-pipeline, (4) CI/CD modernization, (5) test rigor, (6) packaging / type-safety, (7) observability, (8) docs SOTA. A change landing one surface without the others is partial-SOTA, not SOTA. Full per-surface specification at `rules/sota-elevation-exemplars.md` §1.
+
+### 2. Named-Exemplar Discipline (Companion Sub-Rule Anchor)
+
+Every SOTA citation MUST name a **currently-shipping** exemplar project as concrete-driver class 6 per `rules/interactive-questions-canonical-shapes.md` §3.2.1. Canonical exemplars: **cpython** (workflow naming, release rigor), **shadcn-ui** (README header, dark-mode aesthetic), **Bun** (performance-first landing, OG cards), **Fumadocs** (docs IA, dedicated landing), **vite** (clean IA), **vitest** (behavior-named tests). Citations like "industry standard" without naming a specific project are non-conformant per `rules/interactive-questions-canonical-shapes.md` §3.2.2. Full per-exemplar walks at `rules/sota-elevation-exemplars.md` §2.
+
+### 3. Upper-Bound Calibration & Filter-5 Binding (Companion Sub-Rule Anchor)
+
+A `MAXIMAL` directive (or synonyms) escalates the calibration ladder at `rules/expertise-posture-elements.md` §2 to the architectural-rework rung. Production-ready is the floor `rules/production-ready-prs.md` enforces; SOTA-elevation lifts the ceiling. SOTA is the outward projection of cognitive-identity Filter 5 (aesthetic demand) per `rules/cognitive-identity-techniques.md` §1 — passing every mechanical bar without conceptual elegance is not yet SOTA. Full bindings at `rules/sota-elevation-exemplars.md` §§3–4.
+
+### 4. Gap-Surfacing
+
+When the host's current state falls short of SOTA on any of the eight surfaces, the gap MUST be surfaced as a finding per `rules/authority-inquiry.md` with options annotated per `rules/option-annotation.md` — never silently entrenched. The recommended-option rationale cites a concrete exemplar from §2.
+
+## Disclosure surface (Companion Sub-Rule Anchor)
+
+Outcomes recorded per `rules/disclosure-ledger.md` using `[SOTA — elevated: …]`, `[SOTA — gap-surfaced: …]`, `[SOTA — floor-honored: …]` markers. Full schemas at `rules/sota-elevation-exemplars.md` §6.
+
+## Failure tells (Companion Sub-Rule Anchor)
+
+Partial-SOTA emissions, exemplar-less citations, `MAXIMAL` directives answered with mid-tier output, silently-entrenched gaps, aesthetic dismissal where Filter 5 has not been applied. Full enumeration at `rules/sota-elevation-exemplars.md` §7.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every OSS-distribution-project change's pre-emission SOTA audit across the eight surfaces. The README-modernization escalation cited at `rules/production-ready-prs-surfaces.md` §6.5. Every `MAXIMAL` directive's calibration-ladder escalation to the architectural-rework rung. Every concrete-exemplar citation in `[SOTA — …]` ledger markers.
+- **Satisfies →** The rule inventory, SOTA-elevation meta-mandate, comprehensive SOTA polish mandate, and the operator's MAXIMAL-standard directive.
+- **Established by ↑** The operator's README MAXIMAL SOTA and workflow generic-SOTA naming directives. The adjacent-domain axis citing cpython / shadcn / Bun / Fumadocs / vite / vitest exemplars. The scholarly-technical-literature axis and SOTA gap declaration.
+- **Gated by ←** the trivial-vs-non-trivial threshold (trivial-scope edits honor the SOTA floor on surfaces touched; full eight-surface audit applies to meaningful-scope changes). The OSS-distribution-project pre-condition (internal dev-tools are out of scope).
+- **Cross-bound with ↔** `rules/sota-elevation-exemplars.md` (path-filtered companion sub-rule carrying the eight-surface table, named-exemplar catalogue, calibration binding, Filter-5 binding, gap-surfacing protocol, disclosure markers, and failure tells). `rules/production-ready-prs.md` + `rules/production-ready-prs-surfaces.md` (production-ready is the floor; SOTA lifts the ceiling). `rules/cognitive-identity.md` (Filter 5 aesthetic-demand binding). `rules/expertise-posture.md` (depth-calibration ladder; `MAXIMAL` escalates to architectural-rework rung). `rules/persistent-conventions-vigilance.md` (CM-22 — SOTA-gap detection feeds the §4 ecosystem-gap-detection surface). `rules/option-annotation.md` (every recommended-option rationale cites a concrete-exemplar concrete-driver class 6). `rules/authoritative-referencing.md` (§2 named-exemplar discipline — the authoritative-referencing standing mandate consolidates this no-"industry-standard" citation bar by reference).

package/src/apothem/rules/source-accessibility.md

@@ -0,0 +1,58 @@
+---
+name: "source-accessibility"
+description: "Source trust outranks source accessibility — reach a trusted but inaccessible source via browser then operator interview; never prefer an untrusted-but-free source over a trusted-but-inaccessible one; record the source-trust decision in the ledger."
+pathFilter: ""
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Rule: Source Accessibility — Trust Outranks Reachability
+
+## Purpose
+
+Govern source selection when the authoritative source for a claim, convention, API contract, or version pin is hard to reach. Convenience MUST NOT silently demote authority: a paywalled specification, a login-gated vendor doc, or an offline standard stays the source of record even when a free, open, lower-trust page is one click away. This rule fixes the ranking and the escalation path so the agent reaches the trusted source instead of the reachable one.
+
+## Obligations
+
+### 1. Trust outranks accessibility
+
+When candidate sources conflict on trust and on reachability, the higher-trust source wins regardless of how much harder it is to reach. The agent MUST NOT prefer an untrusted-but-accessible source — an SEO blog, a forum answer, a model's own recollection, a mirror of unknown fidelity — over a trusted-but-inaccessible one: the vendor's official doc, the ratified standard, the primary specification, the maintainer's own statement.
+
+### 2. Escalate to reach the trusted source
+
+A trusted source that is not immediately readable MUST be reached through an ordered escalation, not abandoned:
+
+1. Retrieve it directly through the host's browser / fetch capability — declared per-harness in `capabilities.yml` `web_fetch` (the backing dimension per `rules/agent-capability-discipline-matrix.md` §1A). A `no` / `discovery-pending` cell means no capability to invoke; escalate to step 2.
+2. Where that capability is absent, or the source sits behind credentials the agent does not hold, interview the operator for the content or for access per `rules/authority-inquiry.md`.
+
+The agent settles for a lower-trust substitute only after both steps are exhausted, and MUST disclose the substitution.
+
+### 3. Record the source-trust decision
+
+Every source-selection decision of meaningful scope MUST record, in the change ledger per `rules/disclosure-ledger.md`: which source was used, its trust tier, whether the first-choice trusted source was reachable, and — when a substitute was used — why the trusted source was not reachable. A claim resting on a lower-trust source carries that provenance with it.
+
+## Seriousness Scaling
+
+| Level | Source discipline |
+| ----- | ----------------- |
+| EXPLORING | Prefer the trusted source; substitution disclosure optional. |
+| PERSONAL_USE | Reach the trusted source via browser; disclose substitutions. |
+| SHARED | Full escalation (browser then operator interview) before any substitution; every source-trust decision recorded. |
+| PUBLIC_LAUNCH | No lower-trust substitute on a public-surface claim without recorded exhaustion of the escalation and an explicit operator-confirmed fallback. |
+
+## Enforcement
+
+Always-on at every seriousness level, scaling per the table above. Source selection is a discrete behavior that precedes any claim the artifact rests on; the ranking and escalation apply before the claim is committed.
+
+## Failure tells
+
+A free low-trust page cited where the vendor's gated doc is the real source of record; "it was not accessible" offered as justification with no browser attempt and no operator interview logged; a version pin or a security claim resting on a forum post; a substituted source used with no ledger record of the trust downgrade.
+
+## Bindings (§0.j five-direction)
+
+- **Drives →** Every source-selection decision behind a claim, a convention adoption, an API-contract reading, or a version pin across every ecosystem surface; the provenance each lower-trust-sourced claim must carry.
+- **Satisfies →** The standing-mandate end-state that authority, not convenience, decides which source a claim rests on.
+- **Established by ↑** The operator's standing-mandate set (the inaccessible-source mandate — trust outranks reachability).
+- **Gated by ←** The host's browser / fetch capability surface — declared per-harness in `capabilities.yml` `web_fetch` per `rules/agent-capability-discipline-matrix.md` §1A — and the operator-interview channel (the two reachability paths the escalation depends on).
+- **Cross-bound with ↔** `rules/authority-inquiry.md` (M5 — the operator-interview channel this rule escalates to when a trusted source is credential-gated is owned there); `rules/ten-dimension-check.md` (dimension 9 Scholarly / technical referencing — source-trust selection is the upstream behavior that referencing dimension verifies); `rules/disclosure-ledger.md` (M2 — the source-trust decision is recorded as a ledger entry); `rules/authoritative-referencing.md` (the trust-outranks-accessibility ranking decides WHICH source that referencing mandate cites).