instar 1.3.1031 → 1.3.1032

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1031",
+  "version": "1.3.1032",
   "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

@@ -212,12 +212,32 @@ function isInRegistry(filepath, registryContent) {
 
 function hasMatchingCanary(stagedFiles, filepath) {
   // A matching canary is any file in the same adapter's canary/ directory,
-  // or a file named *Canary*.ts adjacent to the source file.
+  // or a file named *Canary*.ts ADJACENT to the source file.
+  //
+  // "Adjacent" used to be unimplemented: the second clause tested
+  // `/canary/i.test(path.basename(f))` against every staged file without ever
+  // referencing `filepath`. That made it a property of the COMMIT, not a
+  // relationship — stage one canary-named file anywhere and every other file in
+  // the change was credited with having a canary. src/ carries 11 such files, so
+  // any broad commit touching one satisfied the canary half of Rule 3 wholesale.
+  //
+  // It failed in the QUIET direction (weakening the gate rather than blocking
+  // wrongly), which is why nothing ever complained about it.
+  // TWO canary/ locations, because sources sit at two depths. A source one
+  // level below the adapter root (adapters/X/observability/foo.ts) has its
+  // canary at adapters/X/canary/; a source AT the adapter root
+  // (adapters/X/foo.ts) has it at adapters/X/canary/ too — but that is
+  // `<dir>/canary`, not `<parent>/canary`. The original computed only the
+  // parent form, so the directory clause silently missed the second layout and
+  // the global fallback above was covering for it. Removing the fallback
+  // without fixing this would have turned a too-weak check into a wrong one.
   const dir = path.dirname(filepath);
   const adapterRoot = dir.split('/').slice(0, -1).join('/');
-  const canaryDir = path.join(adapterRoot, 'canary');
+  const canaryDirs = [path.join(dir, 'canary'), path.join(adapterRoot, 'canary')];
   return stagedFiles.some(
-    (f) => f.startsWith(canaryDir + '/') || /canary/i.test(path.basename(f)),
+    (f) =>
+      canaryDirs.some((cd) => f.startsWith(cd + '/')) ||
+      (path.dirname(f) === dir && /canary/i.test(path.basename(f))),
   );
 }
 

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-28T13:03:59.365Z",
-  "instarVersion": "1.3.1031",
+  "generatedAt": "2026-07-28T13:11:52.917Z",
+  "instarVersion": "1.3.1032",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.1032.md

@@ -0,0 +1,36 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The Rule 3 gate's canary check credited a file if **any** staged file had a canary-ish basename — it
+never referenced the file under test, so it was a property of the commit rather than a relationship.
+`src/` holds 11 canary-named files, so any broad commit touching one satisfied the canary half of Rule 3
+for everything else in the change. It failed in the permissive direction, which is why it went unnoticed.
+
+Underneath it, the canary-directory probe computed `<parent-of-dir>/canary` only, missing a source that
+sits directly in an adapter root. The permissive fallback was masking that — so removing the fallback
+alone would have turned a too-weak check into a wrong one.
+
+Both fixed: the fallback now requires the canary to be in the file's own directory, and the probe covers
+both layouts.
+
+## What to Tell Your User
+
+Nothing — a contributor-facing pre-commit script.
+
+## Summary of New Capabilities
+
+None. The gate is stricter: it stops granting canary credit that was never earned. A file carrying a
+Rule 3.1 rationale is unaffected.
+
+## Evidence
+
+- Red → green: the new unrelated-canary test fails without the change (1 failed / 26 passed), passes with
+  it (27/27).
+- The **second** bug was found because an existing test failed when I tightened the first. I assumed the
+  test was wrong; it was describing a real directory layout the probe could not see.
+- Held deliberately until #1701 landed — tightening this earlier would have surfaced main's latent Rule 3
+  violations on every merge. Verified `mergeHeadIfMerging` is on `main` before proceeding.

package/upgrades/rule3-canary-adjacency.eli16.md

@@ -0,0 +1,26 @@
+# ELI16 — one file with the right name let a whole commit off the hook
+
+Rule 3 says code that reads outside state must ship with either a written justification or a "canary" —
+a small file that proves the reading still works. The check looked for a canary next to your file.
+
+Except it didn't check "next to". It asked: *is any file in this commit called something-canary?* If
+yes, **every** file in the commit was treated as having one. There are eleven canary-named files in the
+source tree, so any broad change touching one of them satisfied that half of the rule for everything
+else it contained.
+
+It failed silently in the permissive direction — it let things through rather than blocking them — so
+nobody ever hit it and complained.
+
+**A second bug was hiding underneath.** The check *did* have a proper "look in the canary folder next to
+this file" rule, but it looked one directory too high. It worked for files nested inside an adapter and
+missed files sitting directly in one. The sloppy catch-all was quietly covering for it — so removing
+the catch-all on its own would have turned a too-weak check into a plainly wrong one.
+
+I only found that because an existing test failed when I tightened the first rule. I had assumed the
+test was wrong. It wasn't; it was describing a real folder layout the check couldn't see.
+
+**Both are fixed:** the catch-all now requires the canary to actually be beside the file, and the folder
+rule checks both layouts.
+
+The check is now stricter than it was yesterday. That's the point — it was passing things it should
+have refused.

package/upgrades/side-effects/rule3-canary-adjacency.md

@@ -0,0 +1,45 @@
+# Side-effects review — Rule 3 canary adjacency
+
+**Change:** `hasMatchingCanary` in `scripts/check-rule3-coverage.cjs` — the basename fallback is scoped
+to the file's own directory, and the canary-directory probe now covers both layouts. One new test.
+
+## Direction of effect
+
+**Stricter**, so the risk to weigh is a false REFUSAL blocking legitimate work.
+
+| situation | before | after |
+|---|---|---|
+| canary in `<dir>/canary/` | **missed** (only `<parent>/canary` was computed) | matched |
+| canary in `<parent>/canary/` | matched | matched |
+| canary-named file **beside** the source | matched | matched |
+| canary-named file **anywhere else in the commit** | matched ❌ | **not matched** — the fix |
+| no canary, but a rationale comment | passes | passes (unchanged) |
+
+Rule 3 is satisfied by `inRegistry && (rationale || canary)` **or** `rationale && canary`, so a file
+with a rationale is unaffected either way. This only removes credit that was never earned.
+
+## The interaction that made this worth care
+
+Removing the global fallback alone would have **broken** the check: the directory probe computed
+`<parent-of-dir>/canary`, which misses a source sitting directly in an adapter root. The fallback was
+masking it. An existing test caught this immediately — I had assumed the test was wrong, and it was
+describing a real layout.
+
+## Sequencing — why now and not earlier
+
+Filed as ACT-1472 and deliberately held: making this stricter **before** #1701 (judge the author's
+contribution, not the merge index) would have surfaced all of main's latent Rule 3 violations on every
+merge. #1701 is now on `main` (verified: `mergeHeadIfMerging` present), so a merge evaluates only the
+committer's own files and this cannot cascade.
+
+## Blast radius
+
+Pre-commit script only — not in `src/`, not shipped, not executed at runtime. `git revert` restores
+both the permissive fallback and the layout blind spot.
+
+## Verification
+
+- Red → green: the new unrelated-canary test fails without the change (1 failed / 26 passed) and passes
+  with it (27/27).
+- The pre-existing "canary staged alongside" test passes, which is what demonstrates the layout fix —
+  it was the failure that revealed the second bug.