@rungs/cli 0.1.0

package/modules/gates/gates/structural.toml

@@ -0,0 +1,127 @@
+# Gate table for the `gates` module — the repo-agnostic structural set.
+#
+# Nothing here knows what a document *means*. Anything that does belongs to the module that owns
+# that document (ADR-0003's declared/command boundary).
+
+# ── gates-links-resolve · gates-paths-exist ───────────────────────────────────
+
+[link_integrity]
+scan       = ["**/*.md", ".ai/**/*.toml"]
+# `modules/**` is a rungs module source tree, not repo content: a fragment's
+# links are relative to the file it merges *into*, not to where it is authored,
+# so checking them where they sit reports every one as broken. Costs a consumer
+# repo nothing — it has no `modules/` — and was found by running this against
+# the rungs repo itself.
+exclude    = ["node_modules/**", "**/archive/**", ".git/**", "modules/*/fragments/**", "modules/*/files/**"]
+check      = ["relative_markdown_links", "backticked_paths"]
+# Backticked paths are checked only when they look like paths — containing a `/` or a known
+# extension — because prose is full of `identifiers` that are not files. Under-detection is the
+# correct bias: a missed stale path is a nuisance, a false refusal on every code span is a gate
+# people delete.
+path_hint  = ["/", ".md", ".ts", ".cs", ".mjs", ".toml", ".json", ".ps1"]
+exempt     = "path-ok:"       # ignored unless it states a reason
+
+[link_integrity.notes]
+external = "not fetched — a gate that needs the network is a gate that fails on a plane"
+
+# ── gates-frontmatter-valid · gates-rules-declare-enforcement ─────────────────
+
+[[frontmatter_schema]]
+id       = "rules"
+scan     = [".ai/rules/**/*.md"]
+exclude  = [".ai/rules/README.md"]
+required = ["description", "enforcement"]
+optional = ["paths"]
+enum     = { enforcement = ["gated", "review-only"] }
+message  = """
+Every rule declares whether something enforces it. `review-only` is a legitimate answer and is
+what most rules honestly are; the failure this catches is the silent third category, where a rule
+reads as mandatory and nothing checks it.
+"""
+
+# The skill frontmatter schema lived here and moved to the `skills` module, for the same reason
+# `ids-unique` and `generated-current` did: knowing what a SKILL.md may contain is knowledge about
+# skills, not a repo-agnostic structural fact. What `gates` contributes is the `frontmatter-schema`
+# engine that both tables run on.
+
+# ── gates-self-tests-both-directions ──────────────────────────────────────────
+#
+# The meta-gate.
+
+[gate_meta]
+require_self_tests = true
+require_directions = ["pass", "fail"]
+applies_to         = "declared"    # a command gate is the repo's own; we do not audit its tests
+message            = """
+Declared gate `{id}` has no self-test expecting `{missing}`. A gate whose rules are all currently
+satisfied is indistinguishable from a gate that matches nothing, and the fail case is the half
+that proves it can still fire.
+"""
+
+# ── self-tests ────────────────────────────────────────────────────────────────
+
+[[self_test]]
+gate   = "gates-links-resolve"
+expect = "fail"
+input  = "See [the plan](./does-not-exist.md)."
+
+[[self_test]]
+gate   = "gates-links-resolve"
+expect = "pass"
+input  = "See [this table](./structural.toml)."
+
+[[self_test]]
+gate   = "gates-paths-exist"
+expect = "pass"
+input  = "The `Result<T>` type wraps it."          # a code span that is not a path
+
+[[self_test]]
+gate   = "gates-rules-declare-enforcement"
+expect = "fail"
+fixture = { file = ".ai/rules/x.md", frontmatter = { description = "d", paths = ["**"] } }
+
+[[self_test]]
+gate   = "gates-rules-declare-enforcement"
+expect = "pass"
+fixture = { file = ".ai/rules/x.md", frontmatter = { description = "d", enforcement = "review-only" } }
+
+[[self_test]]
+gate   = "gates-frontmatter-valid"
+expect = "fail"
+fixture = { file = ".claude/skills/x/SKILL.md", frontmatter = { name = "x", description = "d", "argument-hint" = "y" } }
+
+[[self_test]]
+gate   = "gates-self-tests-both-directions"
+expect = "fail"
+fixture = { gate = "example", self_tests = ["pass"] }
+
+[[self_test]]
+gate   = "gates-self-tests-both-directions"
+expect = "pass"
+fixture = { gate = "example", self_tests = ["pass", "fail"] }
+
+# `gates-paths-exist` and `gates-frontmatter-valid` share the tables above with
+# their siblings, but the meta-gate keys self-tests by gate id — so a shared
+# table still needs a pass and a fail per gate. That is correct: two gates
+# running the same engine can still be scoped differently, and only their own
+# fixtures prove each one fires.
+
+[[self_test]]
+gate   = "gates-paths-exist"
+expect = "fail"
+input  = "The mapper lives in [`src/gone.ts`](src/gone.ts)."
+
+[[self_test]]
+gate   = "gates-paths-exist"
+expect = "pass"
+input  = "The mapper lives in [`structural.toml`](./structural.toml)."
+
+[[self_test]]
+gate    = "gates-frontmatter-valid"
+expect  = "pass"
+fixture = { file = ".claude/skills/x/SKILL.md", frontmatter = { name = "x", description = "d" } }
+
+[[self_test]]
+gate    = "gates-frontmatter-valid"
+expect  = "fail"
+fixture = { file = ".claude/skills/x/SKILL.md", frontmatter = { description = "d" } }

package/modules/gates/module.toml

@@ -0,0 +1,143 @@
+[module]
+name    = "gates"
+version = "1.0.0"
+rung    = 1
+summary = "The gate runner, the registry every other module registers into, the run ledger, and the generic structural gate set."
+
+[requires]
+modules = ["instructions"]
+
+[conflicts]
+modules = []
+
+# ── parameters ────────────────────────────────────────────────────────────────
+
+[params.tiers]
+description = "Ordered gate tiers. The first is the one meant to run constantly."
+default     = ["fast", "full"]
+
+[params.ledger]
+description = """
+Record exit status and wall-clock per gate per run to a gitignored ledger (ADR-0005). Off means
+`doctor` cannot answer which gates never fire, and declared durations stay hand-typed.
+"""
+default     = true
+
+[params.fast_budget_ms]
+description = """
+Wall-clock the fast tier is expected to stay inside. Compared against the ledger's observed
+values, not against typed per-gate numbers — that comparison is the reason the ledger exists.
+"""
+default     = 30000
+
+# ── gates ─────────────────────────────────────────────────────────────────────
+#
+# Only genuinely repo-agnostic checks live here. Anything needing to know what a
+# document means belongs to the module that owns that document.
+
+[[gates]]
+id     = "gates-links-resolve"
+kind   = "declared"
+engine = "link-integrity"
+table  = "gates/structural.toml"
+tier   = "fast"
+why    = "A relative link that stopped resolving is the cheapest possible signal that a document moved and its citers did not."
+
+[[gates]]
+id     = "gates-paths-exist"
+kind   = "declared"
+engine = "link-integrity"
+table  = "gates/structural.toml"
+tier   = "fast"
+why    = "Instruction files name paths. hexguard's seven instruction files describe workspace registration and CI wiring across 105 packages, and nothing detected a moved path."
+
+[[gates]]
+id     = "gates-frontmatter-valid"
+kind   = "declared"
+engine = "frontmatter-schema"
+table  = "gates/structural.toml"
+tier   = "fast"
+why    = "A skill with malformed frontmatter does not fail; it silently never loads."
+
+[[gates]]
+id     = "gates-rules-declare-enforcement"
+kind   = "declared"
+engine = "frontmatter-schema"
+table  = "gates/structural.toml"
+tier   = "fast"
+why    = """
+Every rule declares `gated` or `review-only`, and a rule claiming MANDATORY with no gate behind it
+is reported. This is failure mode F1 made detectable: all four source repos wrote rules they could
+not check, and all four decayed — including inside the file that states the rule.
+"""
+
+[[gates]]
+id     = "gates-self-tests-both-directions"
+kind   = "declared"
+engine = "gate-meta"
+table  = "gates/structural.toml"
+tier   = "fast"
+why    = """
+The meta-gate. Every declared gate must carry at least one self-test expecting `fail` and one
+expecting `pass`, because a gate whose rules are currently satisfied is indistinguishable from a
+gate that matches nothing.
+"""
+
+# ── skills ────────────────────────────────────────────────────────────────────
+
+[skills.harden-rule]
+# No extensions. Escalating a broken rule is exactly the kind of thing a model
+# should be able to reach for on its own, mid-task, without being asked.
+
+# ── detection (ADR-0004) ──────────────────────────────────────────────────────
+#
+# Deliberately narrow. A repo with a folder of validation scripts has gates; it
+# does not have *this* registry, and conflating the two would let `add` believe
+# it owns scripts it has never read.
+
+[detect]
+paths   = [".ai/gates.toml"]
+markers = ["rungs:begin gates"]
+
+# Existing validators. Not a paradigm difference — a repo that has these has the
+# thing this module wraps, and they adopt cleanly as `command` gates. `add`
+# proposes registering them; it never rewrites one.
+[[detect.adopt_as]]
+kind  = "command"
+paths = [
+  ".github/scripts/check-*.mjs",
+  ".github/scripts/validate-*.mjs",
+  "scripts/validate-*.ps1",
+  "scripts/check-*.sh",
+]
+note  = """
+Registering an existing validator gives it the runner, the ledger and attribution without changing
+a line of it. This is the axiom-mesh case (8 PowerShell validators, no root package.json) and the
+rift-forge case (82 registry entries, no ledger) in one mechanism.
+"""
+
+# ── provenance (required, validated) ──────────────────────────────────────────
+
+[provenance]
+sources  = ["rift-forge", "axiom-mesh"]
+patterns = [
+  "structural-gates",
+  "gate-self-test",
+  "read-the-negation",
+  "reasoned-exemption",
+  "computed-claims",
+  "generate-derivable",
+  "enforcement-declaration",
+  "ageing-signal",
+  "tool-level-hook",
+  "instruction-hardening",
+]
+incident = """
+rift-forge's verify.mjs carries 82 gates each with a hand-typed `ms` duration measured on a single
+date, supporting a "~30s" fast-tier budget stated in an authority document. The fast tier's 73
+typed values sum to 38.4s serial; it runs concurrently, so the claim is plausible and unverifiable
+from the repo. The runner produces the true duration of all 82 on every run and discards it — the
+computed-claims failure inside the runner that enforces the other gates. Separately, its CI was red
+for 11 of 15 runs on two permanently-broken jobs, kept survivable by attribution, which is also
+what removed the pressure to fix them.
+"""

package/modules/gates/skills/harden-rule/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: harden-rule
+description: >-
+  Turn a mistake into a rule that cannot be made again, by picking the cheapest rung that actually
+  holds: a sentence at the point of use, a line in a skill, a path-scoped rule, or a gate or hook.
+  Use after getting something wrong that an instruction could have prevented, after the same
+  mistake happens twice, when a rule that already exists was broken anyway, or when asked to
+  "write that down", "make sure this doesn't happen again", or "add a check for this". Also use to
+  decide whether a rule is worth a gate at all. Recording the observation without changing the
+  instruction is /record-finding; this skill changes the instruction.
+---
+
+# Harden a rule
+
+**A mistake an instruction could have prevented is a defect in the instruction.** Repairing it
+belongs in the same change as repairing the mistake — nobody will ask, because a reviewer reads the
+fix, not the counterfactual in which you had been told the right thing first.
+
+Run this unprompted. It is not a request; it is part of finishing.
+
+## 1. Name the shape, not the incident
+
+Write the rule as something the *next* agent can recognise before making the mistake, not as a
+description of what you did. The trigger has to be mechanical: you should not need to notice you
+were careless, only to notice a shape.
+
+Weak: *"be careful when editing the dataset."*
+Strong: *"reconcile a generated artifact by regenerating it, never by merging text."*
+
+If you cannot state the shape, you have a finding, not a rule. Stop here and record it.
+
+## 2. Check whether the rule already exists
+
+Search the entry document, the rules, and the skills for it.
+
+**If it already existed and was broken anyway, skip to rung 3 or 4.** Do not restate it, do not
+bold it, do not add an emphasis marker. A louder sentence in a file that was already read changes
+nothing, and the restatement is itself evidence that prose has been tried.
+
+## 3. Pick the cheapest rung that holds
+
+| Rung | Use when | Cost |
+| --- | --- | --- |
+| **1 — a sentence at the point of use** | First occurrence, and the rule is local to one place | Minutes |
+| **2 — a line in the relevant skill** | The mistake happens *during* a procedure that already has a skill | Minutes |
+| **3 — a path-scoped rule** in `.ai/rules/` | It applies to a surface rather than a task, and would be noise in the always-on document | An hour |
+| **4 — a gate or a hook** | **The rule has already been broken after being written down**, or the check is mechanical and cheap | Half a day, plus maintenance |
+
+Rung 1 goes **where the mistake is made** — not in a preamble, not in a summary section. The rule
+has to be in front of the person about to break it.
+
+## 4. If it is rung 4, build it properly
+
+Add the gate to the owning module's table, or as a `command` gate in `.ai/gates.toml`. Then, before
+you call it done:
+
+- **Self-tests, both directions.** One expecting `fail`, one expecting `pass`. A gate whose rules
+  are all currently satisfied is indistinguishable from a gate that matches nothing.
+- **Read the negation before the token.** If the gate refuses a phrase, check a preceding-context
+  window for a negation cue first — otherwise it refuses the sentence that documents the fix, and a
+  guard that refuses its own fix is one people disable.
+- **An exemption must carry a reason.** `<marker>: <why>`, ignored when the reason is missing.
+- **Recompute rather than compare.** If the gate checks a number, derive the number. A probe
+  encoding a guess is confidently wrong, which is worse than a typed value nobody trusts.
+- **Pin what it does not cover**, in its own message. Green must never read as "verified".
+
+## 5. Write down where it is now true
+
+A rule usually lives in more than one place: the authority document that explains *why*, the
+always-on document that every session reads, and the skills that execute it.
+
+**Fix the authority first, then the citers.** A citer corrected against a stale authority is a
+second wrong statement, and the next reader cannot tell which one won.
+
+**A citation is not propagation.** "See §3" ages into a false claim the moment §3 changes, and it
+reads as verified precisely because it names a source.
+
+## 6. Say what you did
+
+In the same change: what went wrong, which rung you chose, and why the cheaper rungs were not
+enough. That last part is what stops the next person re-litigating it — and if the honest answer is
+"prose had already failed twice", write that.

package/modules/instructions/files/.ai/rules/README.md

@@ -0,0 +1,53 @@
+# Path-scoped rules
+
+**These files are the source. The copies under `.claude/rules/`, `.github/instructions/` and
+`.cursor/rules/` are generated — do not edit those.** Run `rungs render` after changing anything
+here; `rungs check` refuses a stale rendering.
+
+A rule here loads only when an agent touches a matching file, so it costs nothing until it is
+relevant. That is what keeps [`../../AGENTS.md`](../../AGENTS.md) inside its line budget.
+
+## When something belongs here
+
+| Content | Goes |
+| --- | --- |
+| A fact every session needs | `AGENTS.md` |
+| A rule for one part of the tree | **here** |
+| A multi-step procedure with a beginning and an end | a skill |
+
+If you are adding a section to `AGENTS.md` that begins "when working on X…", it belongs here.
+
+## Format
+
+```markdown
+---
+description: >-
+  What this covers and when it applies. One or two sentences — some harnesses use this to decide
+  whether to load the rule at all, so lead with the trigger.
+paths:
+  - "src/api/**/*.ts"
+  - "tests/api/**"
+enforcement: gated        # gated | review-only
+---
+
+# API rules
+
+- Concrete, checkable statements. "Use 2-space indentation", not "format properly".
+```
+
+- **`paths`** — globs. Omit for a rule that should load every session, but prefer `AGENTS.md` for
+  that; a rule with no paths is a rule with no reason to be here.
+- **`enforcement`** — required. `gated` means a gate enforces it; `review-only` means nothing does.
+  There is no silent third category, because a silent third category is what every repo this
+  content came from actually had.
+
+## What does not survive rendering
+
+Not every harness can express every field, and the render report names each loss:
+
+| Field | Claude | Copilot | Cursor | AGENTS.md-only |
+| --- | --- | --- | --- | --- |
+| `paths` | ✅ | ✅ `applyTo` | ✅ `globs` | directory-level, or a routing line |
+| `description` | dropped | ✅ | ✅ | — |
+
+Read `.ai/render-report.md` after a render to see what your harness set actually received.

package/modules/instructions/files/AGENTS.md

@@ -0,0 +1,104 @@
+# AGENTS.md — {{project_name}}
+
+Canonical agent policy for this repository. Read in full before making changes.
+
+This is the **always-on** document: facts every session needs. Anything that applies to one part of
+the tree belongs in [`.ai/rules/`](.ai/rules/README.md) instead, and anything that is a multi-step
+procedure belongs in a skill. Both load only when relevant, and this file has a line budget that
+`rungs check` enforces.
+
+## What this is
+
+<!-- One paragraph: what the project does, for whom, and the one property that must not break. -->
+
+## Repo map
+
+<!-- rungs:begin repo-map -->
+<!-- Generated. Run `rungs render` after moving directories. -->
+<!-- rungs:end repo-map -->
+
+## Validation matrix
+
+**Run the narrowest validation that covers what you touched**, then the standard gates. Running
+everything is slow enough to get skipped; running the wrong subset proves nothing.
+
+| Change surface | Run |
+| --- | --- |
+| *(fill in per surface)* | |
+| anything | `rungs check` |
+
+## Task loop
+
+1. **Start from the narrowest concrete anchor** — a file, a symbol, a failing test, a route.
+2. Read the scoped rule for that surface before editing broadly.
+3. Make the smallest change that proves or disproves the current hypothesis.
+4. Run the narrowest validation above.
+5. Update docs when public behaviour or developer workflow changed.
+
+Choosing the anchor **before** reading instructions is the point: which instructions apply is then a
+consequence of scope rather than a guess.
+
+## Non-negotiables
+
+### When you get something wrong, harden the instruction — without being asked
+
+**A mistake an instruction could have prevented is a defect in the instruction**, and repairing it
+is part of repairing the mistake. Do it in the same change, unprompted: a reviewer reads the fix,
+not the counterfactual in which you had been told the right thing first, so the repair that does not
+happen here does not happen at all.
+
+Pick the cheapest rung that actually holds:
+
+1. **A sentence at the point of use** — where the mistake is made, not in a preamble.
+2. **A line in the relevant skill**, where an agent meets the rule during execution.
+3. **A path-scoped rule**, when it applies to a surface rather than a task.
+4. **A gate or a hook**, when the rule has already been broken *after* being written down.
+
+**If the rule already existed and you broke it anyway, do not restate it — make it mechanical.** A
+louder sentence in a file you have already read changes nothing. `/harden-rule` walks the ladder.
+
+### Editing files from the shell
+
+**Never pipe a multi-line edit through `node -e "…"`, `python -c "…"`, or a shell-expanded
+heredoc.** Write the script to a file and run it. Inside a double-quoted shell string backticks are
+command substitution, so a `node -e` that writes documentation deletes the backticked words and
+leaves grammatical text behind — and exits 0.
+
+**Chain with `&&`, never `;`**, when a later step consumes an earlier one. A failed producer
+followed by `;` yields an empty variable, and an empty variable written into a file is not a crash;
+it is a wrong value that passes review.
+
+### Claims and numbers
+
+- **A number a machine can compute is never typed by a human.** If it can be derived, generate it
+  and gate it.
+- **A control that cannot fail loudly is not a control.** Filtering a command's output through
+  `| tail` or `| grep` reports *that* command's exit status, not the one you care about.
+- **Check the artifact, not the bookkeeping about it.** A status field, a board row, or a triage is
+  a claim about the work; the branch, the test, and the file are the work.
+
+<!--
+Optional — uncomment if you want it. Not shipped active because it is a preference, not a universal:
+
+### Communication style
+
+- Never tell me what I want to hear; prioritise truth over comfort.
+- Contradict me when you disagree, and challenge assumptions.
+- Be direct and concise. Skip validation and praise.
+- If there is a better approach, recommend it even if I did not ask.
+-->
+
+## Conventions
+
+<!-- Positive and negative both. A prohibition should state the evidence that would reverse it,
+     e.g. "no dedicated X package until two real consumers prove a stable API". -->
+
+- Commit messages: conventional prefixes (`feat:`, `fix:`, `docs:`, `chore:`…).
+
+## Routing
+
+| If you need… | Go to |
+| --- | --- |
+| Rules for one part of the tree | [`.ai/rules/`](.ai/rules/README.md) |
+| A multi-step procedure | the skills in this repo — invoke by name |
+| Why a decision was made | *(add when `adr` is installed)* |

package/modules/instructions/files/CLAUDE.md

@@ -0,0 +1,11 @@
+@AGENTS.md
+
+<!--
+  Generated by `rungs`. Claude Code does not read AGENTS.md, so this file imports it — one source,
+  no second copy to drift (ADR-0001). The import is used rather than a symlink because a symlink
+  requires Administrator or Developer Mode on Windows.
+
+  Add Claude-specific content below this comment. It is yours; `rungs upgrade` will not touch it.
+-->
+
+## Claude Code

package/modules/instructions/gates/core.toml

@@ -0,0 +1,114 @@
+# Gate table for the `instructions` module. Data only — no script enters the repo (ADR-0002).
+
+# ── instructions-core-size ────────────────────────────────────────────────────
+#
+# Counts what is actually loaded: HTML comments are stripped by at least one harness before
+# injection, so they do not count, and neither does frontmatter.
+
+[file_budget]
+file        = "AGENTS.md"
+max_lines   = {{core_budget}}
+ignore      = ["html_comments", "frontmatter"]
+warn_at     = 0.8
+message     = """
+AGENTS.md is over its {{core_budget}}-line budget. Move the most path-specific section into
+.ai/rules/ — that is what the budget is for. Merged module fragments count toward it, so a fragment
+that has grown past ~15 lines is usually the one to look at first.
+"""
+
+# ── instructions-render-current ───────────────────────────────────────────────
+
+[[render_freshness]]
+id      = "rules"
+sources = [".ai/rules/**/*.md"]
+exclude = [".ai/rules/README.md"]   # the scaffold doc is not a rule
+targets = [".claude/rules/**/*.md", ".github/instructions/**/*.instructions.md", ".cursor/rules/**/*.mdc"]
+command = "rungs render"
+# Targets are checked only for harnesses in the installed matrix; the rest are ignored rather
+# than reported missing.
+
+# ── instructions-repo-map-current ─────────────────────────────────────────────
+
+[[render_freshness]]
+id      = "repo-map"
+block   = { file = "AGENTS.md", marker = "repo-map" }
+derives = "directory-tree"
+depth   = 2
+command = "rungs render"
+
+# ── instructions-shell-backticks (hook: pre-tool-use) ─────────────────────────
+#
+# Refuses a command that would let the shell expand backticks inside a double-quoted string.
+# It permits every form the rule prescribes, and asserts BOTH directions below, because a guard
+# that also refuses its own fix is one people disable.
+
+[shell_safety]
+refuse = [
+  { pattern = "node\\s+-e\\s+\"[^\"]*`", why = "backtick inside a double-quoted -e string is command substitution" },
+  { pattern = "python\\s+-c\\s+\"[^\"]*`", why = "same trap, Python" },
+  { pattern = "<<\\s*EOF", why = "unquoted heredoc is shell-expanded; use <<'EOF'" },
+]
+permit = [
+  "script file invocation",
+  "single-quoted -e string",
+  "<<'EOF'",
+  "escaped backtick",
+]
+message = "Write the script to a file and run it. A file has no shell quoting layer, so backticks are just characters."
+
+# ── self-tests ────────────────────────────────────────────────────────────────
+#
+# Both directions, always. A gate whose rules are currently satisfied is indistinguishable from a
+# gate that matches nothing.
+
+[[self_test]]
+gate   = "instructions-shell-backticks"
+expect = "fail"
+input  = "node -e \"fs.writeFileSync('a.md', 'see `foo`')\""
+
+[[self_test]]
+gate   = "instructions-shell-backticks"
+expect = "pass"
+input  = "node scripts/edit.mjs"
+
+[[self_test]]
+gate   = "instructions-shell-backticks"
+expect = "pass"
+input  = "cat <<'EOF' > a.md"
+
+[[self_test]]
+gate   = "instructions-shell-backticks"
+expect = "fail"
+input  = "cat <<EOF > a.md"
+
+[[self_test]]
+gate   = "instructions-core-size"
+expect = "fail"
+fixture = { file = "AGENTS.md", lines = 9999 }
+
+[[self_test]]
+gate   = "instructions-core-size"
+expect = "pass"
+fixture = { file = "AGENTS.md", lines = 10 }
+
+# ── render-freshness self-tests ───────────────────────────────────────────────
+
+[[self_test]]
+gate    = "instructions-render-current"
+expect  = "fail"
+fixture = { sources = [".ai/rules/backend.md"], targets = [] }
+
+[[self_test]]
+gate    = "instructions-render-current"
+expect  = "pass"
+fixture = { sources = [".ai/rules/backend.md"], targets = [".claude/rules/backend.md"] }
+
+[[self_test]]
+gate    = "instructions-repo-map-current"
+expect  = "fail"
+fixture = { file = "AGENTS.md", blocks = [] }
+
+[[self_test]]
+gate    = "instructions-repo-map-current"
+expect  = "pass"
+fixture = { file = "AGENTS.md", blocks = ["repo-map"] }