instar 1.3.1021 → 1.3.1023

package/dist/commands/devCiFailures.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"devCiFailures.d.ts","sourceRoot":"","sources":["../../src/commands/devCiFailures.ts"],"names":[],"mappings":"AAiBA,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAKD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,YAAY,EAAE,GAAG,MAAM,EAAE,CAczE;AAqBD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqElF"}
+{"version":3,"file":"devCiFailures.d.ts","sourceRoot":"","sources":["../../src/commands/devCiFailures.ts"],"names":[],"mappings":"AAiBA,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAKD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,YAAY,EAAE,GAAG,MAAM,EAAE,CAczE;AA2CD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqElF"}

package/dist/commands/devCiFailures.js

@@ -43,6 +43,28 @@ export function extractFailureLines(annotations) {
     }
     return lines;
 }
+/**
+ * RULE 3.1 rationale — criticality x frequency x stability x fallback.
+ *
+ * CRITICALITY: lowest band. This reads a PR's failed check-runs and their
+ *   annotations to print what broke. It is a DIAGNOSTIC, never a gate — the
+ *   command returns 0 even when it finds failures. A wrong answer costs a
+ *   contributor one confusing terminal read, never a merge decision.
+ * FREQUENCY: once per `instar dev:ci-failures <pr>` invocation, run by hand
+ *   against a red PR. No loop, no polling, no retry amplification.
+ * STABILITY: `gh --json` / the check-run annotations endpoint is GitHub's
+ *   documented machine-readable contract, requested with explicit fields —
+ *   not prose scraped from stdout. An upstream shape change surfaces as a `gh`
+ *   error or a parse failure, not as a silently reshaped object. Deterministic
+ *   parsing is acceptable here without a canary.
+ * FALLBACK: loud on every path, which is why this detector needs no partial
+ *   caveat. A non-zero `gh` exit rejects with the captured stderr; empty or
+ *   malformed stdout throws inside JSON.parse and rejects as "gh returned
+ *   non-JSON" (note there is no `|| \'null\'` default here, so empty output
+ *   cannot degrade into a successful-looking empty result); and every caller
+ *   catches, writes the reason via out.error, and returns exit 1. There is no
+ *   path on which a failed read renders as a clean one.
+ */
 function defaultDeps() {
     return {
         ghJson: (args) => new Promise((resolve, reject) => {

package/dist/commands/devCiFailures.js.map

@@ -1 +1 @@
-{"version":3,"file":"devCiFailures.js","sourceRoot":"","sources":["../../src/commands/devCiFailures.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"devCiFailures.js","sourceRoot":"","sources":["../../src/commands/devCiFailures.ts"],"names":[],"mappings":"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"}

package/dist/commands/devClaimCheck.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"devClaimCheck.d.ts","sourceRoot":"","sources":["../../src/commands/devClaimCheck.ts"],"names":[],"mappings":"AA4BA,mDAAmD;AACnD,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,6DAA6D;IAC7D,SAAS,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAOD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,EAAE,CAe5G;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAC5C,QAAQ,EAAE,MAAM,EAAE,GACjB,SAAS,EAAE,CAUb;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAuBrF;AAoBD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkErF"}
+{"version":3,"file":"devClaimCheck.d.ts","sourceRoot":"","sources":["../../src/commands/devClaimCheck.ts"],"names":[],"mappings":"AA4BA,mDAAmD;AACnD,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,6DAA6D;IAC7D,SAAS,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAOD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,EAAE,CAe5G;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAC5C,QAAQ,EAAE,MAAM,EAAE,GACjB,SAAS,EAAE,CAUb;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAuBrF;AA2CD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkErF"}

package/dist/commands/devClaimCheck.js

@@ -99,6 +99,29 @@ export function readSpecHeads(specsDir) {
     }
     return out;
 }
+/**
+ * RULE 3.1 rationale — criticality x frequency x stability x fallback.
+ *
+ * CRITICALITY: lowest band. This detector answers "is another PR or approved spec already
+ *   claiming these files?" before a build starts. It is ADVISORY — it never gates, blocks,
+ *   or decides. A wrong answer costs a duplicated build (the 2026-06-05 collision this
+ *   command exists to prevent), never a wrong verdict on someone else's change.
+ * FREQUENCY: once per `instar dev:claim-check` invocation, at build start. Not a hot path,
+ *   no loop, no retry amplification.
+ * STABILITY: the highest available for an external read. `gh --json <fields>` is GitHub
+ *   CLI's documented machine-readable contract, not prose scraped from stdout, and the
+ *   fields are requested explicitly — so an upstream format change surfaces as a `gh`
+ *   error rather than as a silently reshaped object. Deterministic parsing is therefore
+ *   acceptable here without a canary or an LLM check.
+ * FALLBACK: asymmetric, and the asymmetry is the reason this rationale is worth reading.
+ *   A THROWN error (gh missing, auth, network, malformed JSON) degrades LOUDLY — the
+ *   caller records `ghDegraded` and reports spec-scan-only, so the user knows the PR half
+ *   of the check did not run. But EMPTY stdout parses to `null`, which the caller's
+ *   `?? []` renders as "zero PRs claim these files" with no degradation flag: a check that
+ *   could not run becomes indistinguishable from one that ran clean. That path is narrow
+ *   (`gh pr list --json` emits `[]` on success, not empty) but real, and it is tracked
+ *   separately rather than papered over here.
+ */
 function defaultGhJson(args) {
     return new Promise((resolve, reject) => {
         execFile('gh', args, { maxBuffer: 32 * 1024 * 1024, timeout: 30_000 }, (err, stdout) => {

package/dist/commands/devClaimCheck.js.map

@@ -1 +1 @@
-{"version":3,"file":"devClaimCheck.js","sourceRoot":"","sources":["../../src/commands/devClaimCheck.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"devClaimCheck.js","sourceRoot":"","sources":["../../src/commands/devClaimCheck.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1021",
+  "version": "1.3.1023",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/check-rule3-coverage.cjs

@@ -149,9 +149,22 @@ function readRegistry() {
 }
 
 function isInRegistry(filepath, registryContent) {
-  // Strip src/ prefix; the registry uses paths relative to src/.
-  const stripped = filepath.replace(/^src\//, '');
-  return registryContent.includes(stripped);
+  // The registry's Location column is SECTION-relative, not uniformly relative
+  // to src/. Most sections write paths relative to src/, but the provider
+  // substrate section ("Provider substrate (`src/providers/`)") writes them
+  // relative to src/providers/ — 21 of its 23 rows, measured on main.
+  //
+  // Stripping only `src/` therefore looked for `providers/adapters/X.ts` while
+  // the row said `adapters/X.ts`, so no provider file could ever match. A file
+  // listed in three registry rows was still refused for a "missing registry
+  // entry", which told the author to add a row that already existed.
+  if (registryContent.includes(filepath.replace(/^src\//, ''))) return true;
+  // Only widen for genuine provider paths, so no other file gains a match it
+  // would not otherwise have had.
+  if (filepath.startsWith('src/providers/')) {
+    return registryContent.includes(filepath.replace(/^src\/providers\//, ''));
+  }
+  return false;
 }
 
 function hasMatchingCanary(stagedFiles, filepath) {

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-28T02:53:15.912Z",
-  "instarVersion": "1.3.1021",
+  "generatedAt": "2026-07-28T09:37:06.269Z",
+  "instarVersion": "1.3.1023",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.1022.md

@@ -0,0 +1,42 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The Rule 3 pre-commit gate's registry lookup could never match a file under `src/providers/`.
+
+`isInRegistry()` stripped only `src/`, so it searched the state-detector registry for
+`providers/adapters/foo/Bar.ts` — while the registry's provider section writes its Location column
+relative to `src/providers/`, i.e. `adapters/foo/Bar.ts`. 21 of that section's 23 rows use that
+form. The strings never met.
+
+A registered file was therefore still refused, with a message instructing the author to add a
+registry entry that already existed — in one case, one that appears in three separate rows.
+
+The lookup now also tries the `src/providers/`-relative form, guarded by
+`filepath.startsWith('src/providers/')` so no other file gains a match it did not already have.
+
+## What to Tell Your User
+
+Nothing. This is a contributor-facing pre-commit script — not shipped, not executed at runtime, no
+user-visible behaviour.
+
+## Summary of New Capabilities
+
+None. A registry entry still does not exempt a file on its own: `inRegistry && (hasRationale ||
+hasCanary)` is unchanged. This only stops the gate from ignoring a registry row that genuinely
+exists.
+
+## Evidence
+
+- Red → green, observed rather than predicted: the provider case failed and the `src/`-relative
+  control passed before the fix (1 failed / 23 passed); 24/24 after. The control is what isolates
+  the cause to the path form.
+- **Why the branch had no coverage:** `tests/unit/scripts/check-rule3-coverage.test.ts` copied the
+  script into its tmp repo but executed the *original*. Since the script resolves its registry from
+  `__dirname/../specs/`, it read the real repo's registry while reading staged files from the tmp
+  repo — so every registry fixture a test wrote was silently ignored. Fixed by running the copy;
+  all 22 pre-existing tests pass unchanged under the corrected harness.
+- Side-effects review: `upgrades/side-effects/rule3-registry-lookup-provider-paths.md`.

package/upgrades/1.3.1023.md

@@ -0,0 +1,74 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`src/commands/devClaimCheck.ts` reads GitHub by running `gh` and parsing its `--json` output —
+textbook state detection under Rule 3 — but it entered `main` via #813 (2026-06-05) carrying
+neither of the two things Rule 3 requires: an in-file Rule 3.1 rationale and a state-detector
+registry row. Both are added here.
+
+It survived because the pre-commit Rule 3 gate evaluates **staged** files only, so a file that
+entered `main` without tripping the gate at its own commit time is never re-examined.
+
+That is not a cosmetic gap. A merge stages everything, so anyone merging `main` into an older
+branch is judged as the author of all of `main` and hits this refusal for a violation absent
+from their own diff — a hard blocker on locally refreshing older open PRs. It blocked exactly
+that work on 2026-07-28 and is the reason this was found at all.
+
+The registry row is deliberately **🟡 Partial rather than 🔵 Exempt**, unlike the neighbouring
+`gh --json` reads that are exempt on "versioned structured contract" reasoning. The difference
+is the fallback. A thrown error (gh missing, auth, network) degrades loudly — the caller sets
+`ghDegraded` and reports spec-scan-only. But empty stdout parses to `null`, and the caller's
+`?? []` renders that as "zero PRs claim these files" with no degradation flag: a check that
+could not run reading identically to one that ran clean. Narrow (`gh pr list --json` emits `[]`
+on success, not empty) and advisory-only, so the blast radius is a false all-clear on a
+pre-build hint — but it is named in both the rationale and the registry rather than papered
+over, and the row flips to Exempt once that path degrades as loudly as the throw path.
+
+Fixing the silent-empty path is a behaviour change and is tracked separately, not bundled into
+a comment-only commit.
+
+## What to Tell Your User
+
+Nothing. No user-visible change, no new command, no behaviour difference in any conversation.
+This is a documentation and registry fix to a contributor-facing CLI helper.
+
+## Summary of New Capabilities
+
+None. `instar dev:claim-check` behaves exactly as before — same flags, same output, same exit
+codes. The only functional effect is that `main` stops failing its own Rule 3 gate, which
+unblocks locally merging `main` into older branches.
+
+## Evidence
+
+- The violation was confirmed on `main`, not inferred: `grep -c "RULE 3"
+  src/commands/devClaimCheck.ts` on `origin/main` returns 0, and the file is absent from the
+  diff of the branch that hit the refusal.
+- The refusal is reproducible, and so is the fix: the same staged change was **blocked** by the
+  Rule 3 gate before the rationale comment, blocked again for the missing registry row after it,
+  and **passed** once both halves were present. Each verdict was observed, not predicted.
+- Comment-and-registry only — no statement, signature, export, or type is modified, so `tsc`
+  emits identical JS.
+- Side-effects review: `upgrades/side-effects/rule3-rationale-devclaimcheck.md`.
+- ELI16: `upgrades/rule3-rationale-devclaimcheck.eli16.md`.
+
+## Correction after opening: this was TWO files, not one
+
+The first version of this change covered only `devClaimCheck.ts` and claimed that unblocked merging
+`main` into an older branch. **That claim was false**, and an A/B test caught it: branching from a
+pre-#813 `main` commit and staging a merge of current `main` flagged **two** files —
+`devCiFailures.ts` as well. Fixing one of two blockers unblocks nothing.
+
+`devCiFailures.ts` now carries its own rationale and registry row. It is marked **🔵 Exempt** rather
+than Partial, because unlike its sibling every failure path is loud: a non-zero `gh` exit rejects
+with captured stderr, and its `JSON.parse(stdout)` carries no `|| 'null'` default, so empty output
+throws rather than degrading into a successful-looking empty result.
+
+**How the check nearly fooled me.** My first A/B run reported the fixed side PASSING — but the merge
+had failed (a ref I had not fetched), so nothing was staged and the checker exited 0 over an empty
+file list. A vacuous pass is indistinguishable from a real one unless you assert the check had input.
+The re-run prints staged counts: 7,499 files / 905 `src/*.ts` on the failing side, and refuses to
+read 0 staged files as a pass.

package/upgrades/rule3-rationale-devclaimcheck.eli16.md

@@ -0,0 +1,55 @@
+# ELI16 — the missing rationale that was blocking old pull requests
+
+There is a rule in this repo (Rule 3.1) that says: if your code looks at some outside system
+to figure out what state it's in, you have to write a short paragraph explaining *why it's OK*
+to detect it that way. Four questions: how much damage does a wrong answer do, how often does
+this run, how likely is the outside thing to change shape on you, and what happens when it
+fails.
+
+A pre-commit check enforces that rule. But it only inspects the files you are committing
+*right now*. So a file that slipped into `main` without ever tripping the check is never
+looked at again.
+
+That's what happened to `src/commands/devClaimCheck.ts`. It arrived in June, it reads GitHub
+by running `gh` and parsing the JSON that comes back — textbook state detection — and it has
+no rationale at all.
+
+**Why that stopped being merely untidy.** Merging `main` into an older branch stages *every
+file in main*. Git then treats you as the author of all of it, so the check inspects the whole
+thing, finds this file, and refuses your commit — for a violation you did not write and cannot
+see in your own diff. Anyone trying to bring an old pull request up to date walks into it. It
+blocked me last night.
+
+**The change is one comment.** It adds the rationale that should have been there in June.
+
+The one part worth reading is the "what happens when it fails" answer, because it is not
+flattering. If `gh` genuinely breaks — missing, not logged in, no network — the tool says so
+out loud and tells you it only managed to scan the specs. Good. But if `gh` returns *nothing
+at all*, that empty result quietly becomes "zero pull requests claim these files", with no
+warning. A check that could not run ends up looking exactly like a check that ran and found
+everything clear.
+
+That path is narrow, and this change does not fix it. It writes it down instead of leaving it
+unmentioned, and it is tracked separately. A rationale that only lists reassuring facts is
+worth very little — the point of the rule is to surface the part someone should worry about.
+
+No behaviour changes. Nothing runs differently.
+
+
+## Correction after opening: this was TWO files, not one
+
+The first version of this change covered only `devClaimCheck.ts` and claimed that unblocked merging
+`main` into an older branch. **That claim was false**, and an A/B test caught it: branching from a
+pre-#813 `main` commit and staging a merge of current `main` flagged **two** files —
+`devCiFailures.ts` as well. Fixing one of two blockers unblocks nothing.
+
+`devCiFailures.ts` now carries its own rationale and registry row. It is marked **🔵 Exempt** rather
+than Partial, because unlike its sibling every failure path is loud: a non-zero `gh` exit rejects
+with captured stderr, and its `JSON.parse(stdout)` carries no `|| 'null'` default, so empty output
+throws rather than degrading into a successful-looking empty result.
+
+**How the check nearly fooled me.** My first A/B run reported the fixed side PASSING — but the merge
+had failed (a ref I had not fetched), so nothing was staged and the checker exited 0 over an empty
+file list. A vacuous pass is indistinguishable from a real one unless you assert the check had input.
+The re-run prints staged counts: 7,499 files / 905 `src/*.ts` on the failing side, and refuses to
+read 0 staged files as a pass.

package/upgrades/rule3-registry-lookup-provider-paths.eli16.md

@@ -0,0 +1,36 @@
+# ELI16 — the gate told authors to add a registry row that was already there
+
+There is a registry listing every place Instar reads state from something it doesn't control.
+A pre-commit gate uses it: if your file is in the registry *and* carries a rationale comment,
+the gate lets it through.
+
+For files under `src/providers/`, that lookup could never succeed.
+
+**Why.** The gate turned `src/providers/adapters/foo/Bar.ts` into
+`providers/adapters/foo/Bar.ts` and searched the registry for that string. But the registry's
+provider section writes its paths relative to `src/providers/`, so the row actually says
+`adapters/foo/Bar.ts`. The two never matched — 21 of the 23 provider rows are written that way.
+
+The result: a file listed in the registry — one of them appears in **three** rows — was still
+refused, with a message telling the author to add a registry entry. Adding the row again would
+not have helped. That is the worst kind of gate message: it is confidently wrong about what
+would fix it.
+
+**Why nobody noticed.** The test file for this gate builds a throwaway repo, copies the script
+into it, writes a registry fixture — and then runs the *original* script instead of the copy.
+The script finds its registry relative to its own folder, so it read the real repo's registry
+while reading the staged files from the throwaway one. Every registry fixture a test wrote was
+quietly ignored, so this whole branch had no working test coverage. That is fixed here too, by
+running the copy.
+
+**How I know the fix works rather than believing it.** I wrote two tests: the provider case, and
+a control using the ordinary path form that should already have worked. Before the fix the
+provider one failed and the control passed. After, both pass, and the 22 tests that were already
+there still pass.
+
+Worth saying: the control failed on my first attempt too, which meant my explanation was wrong.
+Chasing that disagreement is what turned up the harness defect. A control test that fails is
+telling you something.
+
+**Scope.** A registry entry still does not exempt a file on its own — a rationale or a canary is
+still required. This only stops the gate from ignoring a registry row that genuinely exists.

package/upgrades/side-effects/rule3-rationale-devclaimcheck.md

@@ -0,0 +1,73 @@
+# Side-effects review — Rule 3.1 rationale for `devClaimCheck`'s gh detector
+
+**Change:** one doc-comment added above `defaultGhJson` in `src/commands/devClaimCheck.ts`.
+23 lines, comment-only. No statement, expression, signature, export, or type is modified.
+
+## What the change can affect
+
+| Surface | Effect | Why |
+|---|---|---|
+| Runtime behaviour | **None** | A block comment. `tsc` emits identical JS; no code path is reachable through it. |
+| Public API / CLI | **None** | `dev:claim-check` flags, output, and exit codes are untouched. |
+| Tests | **None expected** | No test asserts on this file's source text. |
+| The Rule 3 pre-commit gate | **Intended change** | This file stops being a violation. Verified: the gate refused this exact commit before the comment and accepted it after. |
+| Other repos / migration | **None** | Not an agent-installed file, no config default, no template, no hook. Migration Parity does not apply. |
+| Multi-machine posture | **N/A** | No state surface introduced. |
+
+## The risk worth naming
+
+The change is safe. The thing it *documents* is not, and I want that visible rather than
+buried in a comment.
+
+`JSON.parse(stdout || 'null')` resolves `null` on empty stdout. The caller's
+`(await ghJson(...)) as ClaimPr[] ?? []` turns that into an empty array, and an empty array is
+indistinguishable from "no open PR claims these files". Meanwhile a *thrown* error is handled
+properly — it sets `ghDegraded` and the tool reports spec-scan-only.
+
+So the loud path is loud and the quiet path is silently clean. That is the failure shape the
+constitution calls out directly: a check that cannot run must not be indistinguishable from
+one that ran clean.
+
+**Not fixed here, deliberately.** Fixing it means changing behaviour (treating empty stdout as
+a degradation), which deserves its own review and its own tests. Bundling it into a
+comment-only change would hide a behaviour change inside a documentation commit. It is filed
+separately.
+
+**Reachability:** narrow. `gh pr list --json` emits `[]` on success, not empty output. It
+would take a `gh` build that exits 0 while writing nothing, or truncated output. Low
+likelihood, and the consequence is a false all-clear on an advisory tool — not a wrong gate
+verdict.
+
+## Rollback
+
+`git revert`. Nothing depends on it; reverting restores the pre-existing violation and with it
+the merge blocker.
+
+## What I verified rather than assumed
+
+- The file is `main`'s, not the PR's — it arrived via #813 (`144ff6122`, 2026-06-05) and is
+  absent from the branch diff.
+- `main`'s copy carries zero `RULE 3` markers (`grep -c` → 0).
+- The refusal is real and reproducible: the same staged commit was blocked before the comment
+  and passed the Rule 3 check after it.
+- The fallback asymmetry is read from the code, not inferred — `catch` at the call site sets
+  `ghDegraded`; the `?? []` at lines 197/201 absorbs `null` with no flag.
+
+
+## Correction after opening: this was TWO files, not one
+
+The first version of this change covered only `devClaimCheck.ts` and claimed that unblocked merging
+`main` into an older branch. **That claim was false**, and an A/B test caught it: branching from a
+pre-#813 `main` commit and staging a merge of current `main` flagged **two** files —
+`devCiFailures.ts` as well. Fixing one of two blockers unblocks nothing.
+
+`devCiFailures.ts` now carries its own rationale and registry row. It is marked **🔵 Exempt** rather
+than Partial, because unlike its sibling every failure path is loud: a non-zero `gh` exit rejects
+with captured stderr, and its `JSON.parse(stdout)` carries no `|| 'null'` default, so empty output
+throws rather than degrading into a successful-looking empty result.
+
+**How the check nearly fooled me.** My first A/B run reported the fixed side PASSING — but the merge
+had failed (a ref I had not fetched), so nothing was staged and the checker exited 0 over an empty
+file list. A vacuous pass is indistinguishable from a real one unless you assert the check had input.
+The re-run prints staged counts: 7,499 files / 905 `src/*.ts` on the failing side, and refuses to
+read 0 staged files as a pass.

package/upgrades/side-effects/rule3-registry-lookup-provider-paths.md

@@ -0,0 +1,57 @@
+# Side-effects review — Rule 3 gate registry lookup (provider paths)
+
+**Change:** `isInRegistry()` in `scripts/check-rule3-coverage.cjs` gains a second, narrowly-scoped
+path form; `tests/unit/scripts/check-rule3-coverage.test.ts` runs the copied script instead of the
+original and gains 2 tests + a registry-fixture helper.
+
+## Direction of effect — the only question that matters for a gate
+
+This makes the gate **strictly more permissive**, so the risk to weigh is a false ACCEPT, never a
+false refusal.
+
+| Surface | Effect |
+|---|---|
+| Non-provider files | **None.** The widened form is behind `filepath.startsWith('src/providers/')`, so no other file can gain a match it did not already have. |
+| Provider files, registered, with rationale | Now correctly accepted (was refused). **This is the fix.** |
+| Provider files, registered, no rationale/canary | Still refused — `inRegistry && (hasRationale \|\| hasCanary)` is unchanged. |
+| Provider files, unregistered | Still refused. Containment against a row that does not exist still fails. |
+| Runtime / shipped product | **None.** A pre-commit script; not in `src/`, not bundled, not executed by the server. |
+
+## The false-accept surface, stated plainly
+
+Containment is a substring test, so a short row path could in principle match an unintended file.
+That property is **pre-existing** and unchanged in kind — this only adds a second candidate string
+for paths already under `src/providers/`. A file would need to be under `src/providers/` *and* have
+its `src/providers/`-relative path appear verbatim in the registry, which is precisely the
+condition the fix exists to honour.
+
+I considered resolving each row against its section heading instead, which would remove the
+guesswork entirely. It is the better long-term shape and a larger change; it is not done here.
+
+## Test-harness change — read this as a coverage change, not a cosmetic one
+
+`runCheck` now executes the copy inside the tmp repo. The script resolves the registry from
+`__dirname/../specs/`, so running the original read the **real** repo's registry while reading
+staged files from the tmp repo.
+
+Consequence: every registry fixture written by a test was silently ignored, and the
+"already in the registry" branch had **no reachable coverage at all**. `beforeEach` had always
+copied the script in — the copy was simply never run.
+
+All 22 pre-existing tests pass unchanged under the corrected harness, which is the evidence that
+this repaired coverage rather than altering what those tests assert.
+
+## Verification
+
+- **Red → green, observed:** before the fix, the provider test failed and the `src/`-relative
+  control passed (1 failed / 23 passed). After, 24/24.
+- The control is the load-bearing part: it fails if the cause is anything other than the provider
+  path form.
+- **A correction this produced:** on my first attempt the control failed *too*, which meant my
+  explanation was wrong — a registry entry alone never exempted anything. Following that
+  disagreement is what surfaced the harness defect. The earlier claim that 26 files on `main` were
+  affected is withdrawn: all 26 lack a rationale and would be refused regardless.
+
+## Rollback
+
+`git revert`. Restores the unreachable lookup; no state, no migration, no config.