instar 1.3.1023 → 1.3.1024

package/package.json

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

@@ -113,7 +113,50 @@ const STATE_DETECTION_PATTERNS = [
 const RULE3_EXEMPT_COMMENT_RE = /RULE\s*3\s*:\s*EXEMPT/i;
 const RULE3_RATIONALE_COMMENT_RE = /RULE\s*3\.1\s*RATIONALE/i;
 
+/**
+ * The incoming ref, if a merge is in progress. `MERGE_HEAD` exists only between
+ * `git merge` starting and the merge commit being written — exactly the window
+ * this hook runs in.
+ */
+function mergeHeadIfMerging() {
+  try {
+    const out = execSync('git rev-parse -q --verify MERGE_HEAD', {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.trim() || null;
+  } catch {
+    return null; // not a merge — `rev-parse -q --verify` exits non-zero
+  }
+}
+
 function getStagedFiles() {
+  // During a MERGE the index holds every file that differs between the branch
+  // base and the incoming ref — i.e. effectively all of the incoming branch.
+  // Judging that as the committer's work makes anyone merging `main` into an
+  // older branch the author of all of `main`, so they are refused for
+  // pre-existing violations that are absent from their own diff and that they
+  // did not write. That refusal names a file they cannot see, so the natural
+  // responses are to edit someone else's code or reach for --no-verify.
+  //
+  // A committer's real contribution to a merge is what differs from the
+  // INCOMING ref: a file taken verbatim from MERGE_HEAD was not authored here.
+  // A conflict resolution DOES differ from MERGE_HEAD, so genuinely authored
+  // content is still evaluated — see the merge-semantics tests, which assert
+  // both directions.
+  const mergeHead = mergeHeadIfMerging();
+  if (mergeHead) {
+    try {
+      const out = execSync(
+        `git diff --cached --name-only --diff-filter=ACMR ${mergeHead}`,
+        { encoding: 'utf-8' },
+      );
+      return out.split('\n').filter((l) => l.trim().length > 0);
+    } catch {
+      // Fall through to the full staged list — the STRICTER reading, so a
+      // failure here can only over-report, never silently let code past.
+    }
+  }
   try {
     const out = execSync('git diff --cached --name-only --diff-filter=ACMR', {
       encoding: 'utf-8',

package/src/data/builtin-manifest.json

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

package/upgrades/1.3.1024.md

@@ -0,0 +1,42 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The Rule 3 pre-commit gate judged **everything a merge stages** as the committer's work.
+
+An ordinary commit's index is the author's change. A merge's index is every file that differs between
+the branch base and the incoming ref — so merging `main` into an older branch made the committer the
+author of all of `main`, and they were refused for pre-existing violations absent from their own diff.
+Measured on a branch based at 2026-06-01: 905 staged `src/*.ts`, refused on two files the merger never
+touched.
+
+While a merge is in progress the gate now diffs against `MERGE_HEAD`. A file taken verbatim from the
+incoming ref was not authored by the committer; a conflict resolution was, and is still evaluated.
+Outside a merge nothing changes. If the comparison fails, the gate falls back to the full index — the
+stricter reading, so a failure can only over-report.
+
+## What to Tell Your User
+
+Nothing. A contributor-facing pre-commit script — not shipped, not executed at runtime, no
+user-visible behaviour.
+
+## Summary of New Capabilities
+
+None. This narrows *who* a rule is enforced against, not what the rule requires. It removes a class of
+refusal that named a file the author could not see — the response to which was to edit someone else's
+code or skip the check.
+
+## Evidence
+
+- Red → green with a control: the verbatim-from-incoming test failed while the author-resolved control
+  passed (1 failed / 25 passed); 26/26 after. The control is what distinguishes scoping the gate from
+  weakening it — content matching neither parent is still judged.
+- The verbatim test asserts the offending file **is staged** before expecting a pass, so the pass
+  cannot come from an empty file list.
+- All 24 pre-existing tests pass unchanged.
+- Harness bug fixed en route: the new tests hardcoded `master` while `init.defaultBranch` is `main`
+  here; the branch name is now read from the repo rather than assumed.
+- Side-effects review: `upgrades/side-effects/rule3-gate-judges-author-contribution.md`.

package/upgrades/rule3-gate-judges-author-contribution.eli16.md

@@ -0,0 +1,34 @@
+# ELI16 — you were being judged as the author of everything you merged
+
+A pre-commit check looks at "the files you are committing" to decide whether new code that reads
+outside systems ships with its required justification. It gets that list from the git index.
+
+For an ordinary edit, the index *is* your change. **For a merge it is not.** Merging `main` into an
+older branch stages every file that differs between your branch and `main` — hundreds or thousands of
+them. The check then treats all of it as yours.
+
+So you get refused for a rule broken by a file you have never opened, which does not appear in your
+diff, in code somebody else wrote months ago. Measured on a branch based at 1 June: the merge stages
+905 TypeScript files and the check refuses on two of them, neither touched by the merger.
+
+That refusal is worse than annoying. It names a file you cannot see, so the two natural responses are
+to go and edit someone else's code, or to reach for the flag that skips the check. Neither is what
+anyone wanted.
+
+**The fix.** While a merge is in progress git records the incoming side as `MERGE_HEAD`. Your actual
+contribution to a merge is whatever differs from *that* — a file taken verbatim from the incoming
+branch was not written by you. So during a merge the check now compares against the incoming ref
+instead of the whole index.
+
+**It does not go soft.** If you resolve a conflict, your resolution matches neither parent, so it is
+still yours and still checked. There is a test for exactly that, and it fails if the fix is too
+permissive. Outside a merge nothing changes at all — same list, same behaviour, and the 24 existing
+tests pass untouched.
+
+If the comparison itself fails for any reason, the check falls back to the old full list. That is the
+stricter reading, so a failure can only ever over-report — it can never quietly let something past.
+
+**Why this is the right layer.** A sweep finds 26 files on `main` that would trip this rule. Which of
+them bites you depends on how old your branch is, because only files changed since your branch point
+get staged. Adding justifications one file at a time is chasing a moving target; making the check
+judge your own work fixes every version of the problem at once.

package/upgrades/side-effects/rule3-gate-judges-author-contribution.md

@@ -0,0 +1,53 @@
+# Side-effects review — Rule 3 gate judges the author's contribution
+
+**Change:** `getStagedFiles()` in `scripts/check-rule3-coverage.cjs` diffs against `MERGE_HEAD` while
+a merge is in progress; a new `mergeHeadIfMerging()` helper detects that state. Two merge-semantics
+tests added.
+
+## Direction of effect — the only question that matters for a gate
+
+More permissive **during a merge only**, so the risk to weigh is a false ACCEPT.
+
+| situation | before | after |
+|---|---|---|
+| Ordinary commit (no merge) | full index | **identical** — `MERGE_HEAD` absent, original path taken |
+| Merge: file verbatim from incoming ref | judged as yours ❌ | not judged ✅ **(the fix)** |
+| Merge: file you resolved / authored | judged | **still judged** — differs from `MERGE_HEAD` |
+| Merge: unrelated file you also staged | judged | **still judged** — differs from `MERGE_HEAD` |
+| `git diff` against `MERGE_HEAD` fails | n/a | falls back to the full index — the **stricter** reading |
+
+The load-bearing claim is row 3, and it is asserted by a test that fails if the fix is too permissive.
+It is the reason this is scoping rather than weakening: content that exists on neither parent is
+authored content, and it is still evaluated.
+
+## What could go wrong, honestly
+
+**A file the author deliberately reverts to the incoming version.** If you resolve a conflict by
+taking the incoming side wholesale, that file no longer differs from `MERGE_HEAD` and is not judged.
+That is correct by the definition used here — you contributed no content — but it does mean a merge
+cannot be used to *re-introduce* an incoming violation under your name. Since the incoming ref already
+contains it, the rule was already not being enforced there; this changes who is asked to fix it, not
+whether it exists.
+
+**Octopus merges** (>1 `MERGE_HEAD`) — `rev-parse --verify MERGE_HEAD` returns the first only. Rare in
+this repo and it degrades toward the stricter side.
+
+**Not addressed:** the 26 latent violators on `main` remain. This stops them landing on whoever merges
+next; it does not add their missing justifications.
+
+## Blast radius
+
+Pre-commit script only. Not in `src/`, not bundled, not executed at runtime, no state, no migration,
+no config. `git revert` restores the previous behaviour exactly.
+
+## Verification
+
+- **Red → green with a control**: before the fix the verbatim-from-incoming test failed while the
+  author-resolved control passed (1 failed / 25 passed) — the control is what proves the fix targets
+  the right thing rather than disabling the check. 26/26 after.
+- The verbatim test asserts the file **is staged** before expecting a pass, so a pass cannot come from
+  an empty file list.
+- All 24 pre-existing tests pass unchanged.
+- A harness bug found and fixed en route: the tests hardcoded `master`, but `init.defaultBranch` is
+  `main` here. The branch name is now read from the repo, so the tests do not depend on the author's
+  git config.