instar 1.3.1021 → 1.3.1022

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1021",
+  "version": "1.3.1022",
   "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:26:52.565Z",
+  "instarVersion": "1.3.1022",
   "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/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-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.