instar 1.3.1183 → 1.3.1185

package/dist/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1183",
+  "packageVersion": "1.3.1185",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/dist/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "8105f34456934b67af19b7dffdb0b1bda68f1019301745cf73d6596155928f5a",
+  "sha256": "3eb1bd07851f19c2b7daa4f5bcf5b38a58e611750b8edfbe5f4836b7ee919418",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1183"
+  "packageVersion": "1.3.1185"
 }

package/dist/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1183"
+  "packageVersion": "1.3.1185"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1183",
+  "version": "1.3.1185",
   "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/decision-audit-presence-check.mjs

@@ -26,6 +26,7 @@
  */
 
 import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 
 // Keep in sync with inScope() in scripts/instar-dev-precommit.js — the gate
 // this check detects bypasses OF. (A drift here only weakens detection, never
@@ -40,18 +41,43 @@ export function isInScopeFile(file) {
   return false;
 }
 
-function isGateEvidence(change) {
-  // Post-#827 per-entry file (added per gate evaluation)…
-  if (/^\.instar\/instar-dev-decisions\/.+\.json$/.test(change.file)) return true;
-  // …or the pre-#827 legacy JSONL append (transition grace for in-flight PRs).
-  if (change.file === '.instar/instar-dev-decisions.jsonl') return true;
-  return false;
+function isPerEntryDecisionFile(change) {
+  return /^\.instar\/instar-dev-decisions\/.+\.json$/.test(change.file);
+}
+
+function isLegacyDecisionFile(change) {
+  return change.file === '.instar/instar-dev-decisions.jsonl';
+}
+
+function recordScopeFiles(record) {
+  const files = record?.scope?.files;
+  return Array.isArray(files) ? files.filter((file) => typeof file === 'string') : [];
+}
+
+function coverageFiles(records) {
+  const covered = new Set();
+  for (const record of Array.isArray(records) ? records : []) {
+    for (const file of recordScopeFiles(record)) covered.add(file);
+  }
+  return covered;
+}
+
+function readDecisionAuditRecords(changes) {
+  const records = [];
+  for (const change of changes.filter(isPerEntryDecisionFile)) {
+    try {
+      records.push(JSON.parse(readFileSync(change.file, 'utf8')));
+    } catch {
+      records.push({});
+    }
+  }
+  return records;
 }
 
 /**
  * Pure evaluation — exported for unit tests.
- * @param {{ changes: Array<{status: string, file: string}>, title?: string, authorType?: string }} input
- * @returns {{ ok: boolean, exempt?: string, reason?: string, inScopeFiles?: string[] }}
+ * @param {{ changes: Array<{status: string, file: string}>, records?: unknown[], title?: string, authorType?: string }} input
+ * @returns {{ ok: boolean, exempt?: string, reason?: string, inScopeFiles?: string[], uncoveredFiles?: string[] }}
  */
 export function evaluateDecisionAuditPresence(input) {
   const title = String(input?.title ?? '');
@@ -64,21 +90,39 @@ export function evaluateDecisionAuditPresence(input) {
     return { ok: true, reason: 'no in-scope changes — local gate not required' };
   }
 
-  const hasEvidence = changes.some(isGateEvidence);
-  if (hasEvidence) {
-    return { ok: true, reason: 'gate evidence present', inScopeFiles };
+  if (changes.some(isLegacyDecisionFile)) {
+    return { ok: true, reason: 'legacy decision-audit evidence present', inScopeFiles };
+  }
+
+  const recordChanges = changes.filter(isPerEntryDecisionFile);
+  if (recordChanges.length === 0) {
+    return {
+      ok: false,
+      inScopeFiles,
+      reason:
+        `This PR changes ${inScopeFiles.length} in-scope file(s) but carries NO decision-audit record — ` +
+        `the local instar-dev pre-commit gate did not run for these commits. The usual cause is a build ` +
+        `worktree without the husky shim (created with raw 'git worktree add' instead of 'instar worktree ` +
+        `create'). Fix: in the worktree run 'npm run prepare' (wires .husky/_), then re-commit so the gate ` +
+        `evaluates the change and its audit entry (.instar/instar-dev-decisions/<ts>-<slug>.json) rides the ` +
+        `commit. See tasks #81/#80 and PRs #827/#829.`,
+    };
+  }
+
+  const covered = coverageFiles(input?.records);
+  const uncoveredFiles = inScopeFiles.filter((file) => !covered.has(file));
+  if (uncoveredFiles.length === 0) {
+    return { ok: true, reason: 'decision-audit scope covers in-scope changes', inScopeFiles };
   }
 
   return {
     ok: false,
     inScopeFiles,
+    uncoveredFiles,
     reason:
-      `This PR changes ${inScopeFiles.length} in-scope file(s) but carries NO decision-audit record — ` +
-      `the local instar-dev pre-commit gate did not run for these commits. The usual cause is a build ` +
-      `worktree without the husky shim (created with raw 'git worktree add' instead of 'instar worktree ` +
-      `create'). Fix: in the worktree run 'npm run prepare' (wires .husky/_), then re-commit so the gate ` +
-      `evaluates the change and its audit entry (.instar/instar-dev-decisions/<ts>-<slug>.json) rides the ` +
-      `commit. See tasks #81/#80 and PRs #827/#829.`,
+      `This PR changes ${inScopeFiles.length} in-scope file(s), but its decision-audit record scope ` +
+      `does not cover ${uncoveredFiles.length} in-scope file(s). Re-run the local instar-dev ` +
+      `pre-commit gate for this change so the decision-audit record declares the changed path(s).`,
   };
 }
 
@@ -114,8 +158,10 @@ if (invokedDirectly) {
     console.error(`decision-audit gate: git diff failed — ${err instanceof Error ? err.message : String(err)}`);
     process.exit(2);
   }
+  const changes = parseNameStatus(diffOut);
   const res = evaluateDecisionAuditPresence({
-    changes: parseNameStatus(diffOut),
+    changes,
+    records: readDecisionAuditRecords(changes),
     title: process.env.PR_TITLE,
     authorType: process.env.PR_AUTHOR_TYPE,
   });
@@ -126,7 +172,7 @@ if (invokedDirectly) {
   console.error('decision-audit gate: FAIL');
   console.error(res.reason);
   console.error('');
-  console.error('In-scope files without gate evidence:');
-  for (const f of res.inScopeFiles ?? []) console.error(`  - ${f}`);
+  console.error('In-scope files lacking decision-audit coverage:');
+  for (const f of res.uncoveredFiles ?? res.inScopeFiles ?? []) console.error(`  - ${f}`);
   process.exit(1);
 }

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-21T09:06:56.394Z",
-  "instarVersion": "1.3.1183",
+  "generatedAt": "2026-08-21T16:44:51.648Z",
+  "instarVersion": "1.3.1185",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1183",
+  "packageVersion": "1.3.1185",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "8105f34456934b67af19b7dffdb0b1bda68f1019301745cf73d6596155928f5a",
+  "sha256": "3eb1bd07851f19c2b7daa4f5bcf5b38a58e611750b8edfbe5f4836b7ee919418",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1183"
+  "packageVersion": "1.3.1185"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1183"
+  "packageVersion": "1.3.1185"
 }

package/upgrades/{1.3.1183.md → 1.3.1184.md}

@@ -5,6 +5,34 @@
 
 ## What Changed
 
+The PR-boundary decision-audit gate now verifies that the audit record a pull request carries
+actually **covers** the in-scope files that pull request changed, instead of only verifying that
+some audit record was present.
+
+Previously `evaluateDecisionAuditPresence()` asked one question — did any decision-audit record
+change in this PR? — so an unrelated or stale-scoped record satisfied the gate while covering none
+of the changed files. The gate reported "covered" while covering nothing.
+
+The evaluator now accepts caller-supplied decision records, unions their readable `scope.files`, and
+requires every in-scope changed path to appear in that union. The pure function still performs no
+filesystem I/O; the CLI reads the per-entry JSON records and passes the parsed content in. A record
+whose `scope.files` is absent, malformed, or unreadable contributes no coverage — the check fails
+closed. Directory strings do not cover their descendants.
+
+Unchanged: the bot-author, release-cut and no-in-scope-changes exemptions, and the legacy
+`.instar/instar-dev-decisions.jsonl` transition allowance, which still short-circuits to a pass.
+
+The failure output now names the specific uncovered files and the remedy (re-run the local gate so
+the record declares those paths) rather than listing every in-scope file.
+
+This is a CI-only gate script. There is no runtime surface, no route, no message, and no
+agent-visible or user-visible behaviour change.
+
+**Verdict is review-grade, not proven.** The five-property signature runner that would let a guard
+be called fixed does not exist yet — `scratchpad/phaseB/B0.1-THE-BAR.md` is marked
+`DRAFT-FOR-LANES` and its B0.2 implementation was never built — so nothing here is described as
+fixing, verifying or proving the guard effective.
+
 A machine that receives an inbound Telegram message for a conversation it does **not** own no longer
 claims that message in its own exactly-once ingress ledger. It still relays the message to the owning
 machine exactly as before.
@@ -48,6 +76,18 @@ bookkeeping row is written.
 
 ## Evidence
 
+- `npx vitest run tests/unit/decision-audit-presence-check.test.ts` — 14/14 passing, covering both
+  sides of the boundary: covering scope passes, stale scope fails, malformed scope fails closed,
+  directory strings do not cover descendants, multiple records union, and each existing exemption
+  still exempts.
+- Side-effects review: `upgrades/side-effects/w22-decision-audit-scope-coverage.md`, including an
+  independent second-pass review that concurred and separately confirmed the diff introduces no new
+  schema, config, protocol surface or plumbing.
+- Plain-English overview: `docs/specs/w22-decision-audit-scope-coverage.eli16.md`.
+- The gap was identified by the Window-22 guard survey (`.instar/w22/branch-b-guard-ground-truth.md`),
+  which located this guard as one of four that prove less than they claim and rated this
+  identification the highest-confidence of the four.
+
 - Mechanism established from the code: `src/core/SessionRouter.ts` documents that an inbound for a
   topic owned by another live machine is forwarded to that machine over the mesh — so the non-owner
   is the relay, which is why the claim (and not the delivery) is what needed to change.

package/upgrades/1.3.1185.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A new manually-started maintenance job was added to this repository's own
+pipeline: it marks ONE already-published version of the package deprecated,
+with a plain-English pointer to the version people should use instead.
+
+It exists because a release race can leave an ORPHAN on the registry — a
+version that was published, but whose release commit and tag never landed in
+history. Cleaning one up requires a publish-capable credential, and that
+credential lives only inside this repository's pipeline. This job is the one
+place it can be used for that purpose, and its capability is exactly one write.
+
+The job is started by hand only. It never checks out the repository, so no
+repository code runs beside the credential. It can deprecate; it cannot publish
+and it cannot unpublish. The version and the message are supplied when it is
+started, so nothing about the target is baked into the file. A range or a tag
+is refused before the credential is touched, because those would deprecate many
+versions in a single call, and the current recommended version is refused so
+that what everyone installs can never be hit by a typo. Afterwards the result
+is read back from the registry — the command exiting cleanly is not accepted as
+proof on its own.
+
+## What to Tell Your User
+
+Nothing. This is repository maintenance for the people who publish this
+package; it changes no behaviour on any installed agent and adds no capability
+an agent can reach.
+
+## Summary of New Capabilities
+
+None for agents or users. One maintenance job for maintainers of this
+repository.

package/upgrades/side-effects/w22-decision-audit-scope-coverage.md

@@ -0,0 +1,150 @@
+# Side-Effects Review — decision-audit gate: scope coverage, not mere presence
+
+**Change:** `scripts/decision-audit-presence-check.mjs` (+ its unit test)
+**Tier:** 1 (declared). See "Tier declaration" at the bottom — the gate's advisory signal said 2.
+**Branch:** `w22-b-audit-scope-coverage` · **Base:** `7d4076a53` (JKHeadley/main, v1.3.1182)
+
+## Summary of the change
+
+The decision-audit presence gate ran on every PR and asked one question: did *some* decision-audit
+record change in this PR? It never asked whether that record's declared scope covered the in-scope
+files the PR actually touched. Any unrelated or stale-scoped record satisfied it. The gate reported
+"covered" while covering nothing — a known false positive, and the exact shape the Window-22 guard
+survey was chartered to find.
+
+The evaluator now accepts caller-supplied decision records, unions their readable `scope.files`, and
+requires every in-scope changed path to be covered by that union. The pure function does no
+filesystem I/O; the CLI reads the per-entry JSON records and passes parsed content in.
+
+## Decision-point inventory
+
+One decision point, already existing: pass/fail of the `decision-audit-gate` CI check on a PR. This
+change does not create a decision point; it corrects the predicate of one that already blocks.
+
+## 1. Over-block
+
+**What it now rejects that it did not before:** a PR that carries a decision-audit record whose
+`scope.files` does not list every in-scope changed path. In practice this is a PR where the gate ran
+for *some* of the commits but not the one that touched the extra file, or where files were added
+after the last gate run.
+
+This is the intended new rejection, but it is a genuine behaviour change for authors: previously the
+presence of any record was enough. The failure message names the uncovered paths and tells the
+author to re-run the local gate so the record declares them. Cost of a false block is "re-run the
+gate and re-commit" — recoverable, local, no data loss.
+
+**Deliberate non-tightening:** directory strings do *not* count as covering their descendants. That
+choice makes the gate stricter than a permissive reading. It is recorded here because it is the one
+place a reasonable reviewer might want the opposite; the writer emits concrete staged file paths, so
+descendant-coverage would only matter for hand-written records.
+
+## 2. Under-block
+
+Still missed, explicitly:
+
+- A record whose `scope.files` lists the right paths but whose *content* is boilerplate. Coverage is
+  a structural claim, not a quality claim; nothing here reads the reasoning.
+- A PR that changes an in-scope file, reverts it in a later commit, and carries a record scoped to
+  the intermediate state. The union is computed over declared paths, not over diff history.
+- Files outside the in-scope predicate (`isInScopeFile`) are unaffected — this change does not widen
+  what counts as in-scope, and should not be read as doing so.
+- Bot-authored and release-cut PRs remain exempt, unchanged.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. The check runs at the PR boundary, which is where the bypass it detects becomes
+visible; the local pre-commit gate is the layer that *produces* the record, and it already does its
+job. Pushing coverage down into the pre-commit writer would not help — the failure mode is commits
+that never reached the writer at all.
+
+No smarter gate exists that this should feed instead. The verdict is a set-membership fact, not a
+judgment, so there is no authority for it to inform.
+
+## 4. Signal vs authority compliance
+
+`docs/signal-vs-authority.md` applies to **judgment** decisions — blocking on what a message *means*
+or what an agent's *intent* appears to be. This is not one. "Do the record's declared paths cover the
+diff's paths?" is set membership over enumerable inputs, with no context required to separate the
+legitimate case from the illegitimate one. It sits in the document's own excluded category:
+structural validation at a boundary.
+
+The change also moves the check in the *safe* direction relative to the principle: the check already
+held blocking authority with a brittle predicate; this narrows a false-positive **pass**. It does not
+add brittle authority, and it does not add a new blocker.
+
+**Fails closed** on an absent, malformed, or unreadable `scope.files` — that record contributes no
+coverage. Justified by the same document: a guard whose false-pass is cheap to exploit and whose
+false-block costs a re-run should fail closed.
+
+## 5. Interactions
+
+- **Legacy JSONL transition path** (`.instar/instar-dev-decisions.jsonl`) is checked *before* the
+  coverage logic and still short-circuits to pass. In-flight PRs on the old format are unaffected.
+- **The "no record at all" branch** is preserved verbatim, including its long remediation message.
+  Only the new "record present but scope does not cover" branch is added.
+- **The local pre-commit gate** is the producer of these records; nothing in this change alters what
+  it writes.
+- No double-fire: the gate runs once per PR in one workflow.
+- **Self-referential note:** this PR changes an in-scope file, so it must itself carry a record whose
+  scope covers `scripts/decision-audit-presence-check.mjs`. The change is therefore exercised against
+  itself at merge time.
+
+## 6. External surfaces
+
+CI-visible only. The check's failure output changes (it now prints "In-scope files lacking
+decision-audit coverage" and lists uncovered paths rather than all in-scope paths). No route, no
+message, no agent-visible behaviour, no user-visible surface. No timing or runtime-state dependence.
+
+## 6b. Operator-surface quality
+
+The failure message names the specific uncovered files and the concrete remedy (re-run the local
+gate so the record declares the path). It does not require the reader to know the internals of the
+record format. No operator action is required by this change itself.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local by design, and correctly so:** this runs in GitHub Actions against a PR, not on any
+agent machine. There is no per-machine state, no replication path, and nothing to strand on a topic
+transfer. The decision records it reads are repository content, identical on every checkout.
+
+## 8. Rollback cost
+
+Single-file revert of `scripts/decision-audit-presence-check.mjs` (plus its test). No migration, no
+persisted state, no agent repair. A PR blocked by the new predicate is unblocked by reverting or by
+adding a covering record. Worst realistic case: a burst of PRs fail the gate until authors re-run
+the local gate — visible immediately, recoverable in minutes.
+
+## Conclusion
+
+Bounded correction of an existing gate's predicate, in the direction of fewer false passes, with a
+recoverable false-block cost. No new decision point, no new authority, no runtime surface.
+
+**Verdict is REVIEW-GRADE, not proven.** The five-property signature test that would let a guard be
+called *fixed* does not exist — `scratchpad/phaseB/B0.1-THE-BAR.md` is marked `DRAFT-FOR-LANES` and
+its B0.2 runner was never built. Nothing in this change may be described as fixing, verifying, or
+proving the guard is effective.
+
+## Tier declaration (recorded because the signal disagreed)
+
+The gate's advisory printed `suggestedTier=2 (size=2, riskFloor=1, 86 LOC across 1 file(s))` — the
+**risk** floor is 1; **size** raised the suggestion to 2, and the size is mostly added tests.
+Observer-1 ruling ten (2026-08-21, topic 29723) declared this change tier 1, reasoning on the record:
+the higher tier exists to force design convergence before code, and that convergence exists for this
+change in the Window-22 causal map, the charter, and rulings eight through ten — mechanism proven,
+predicted after-state stated, falsification condition stated. The ruling is void if the diff carries
+new plumbing, a schema, config, or a protocol surface; it does not (one script, one test file).
+
+This paragraph exists so the disagreement between the signal and the declaration is auditable rather
+than suppressed.
+
+## Evidence pointers
+
+- 14/14 targeted tests pass: `npx vitest run tests/unit/decision-audit-presence-check.test.ts`
+- Guard survey that identified the gap: `.instar/w22/branch-b-guard-ground-truth.md`
+- Findings ledger entry 36: view `6e25dfa2-f374-409b-9e85-57aa210adfe0`
+
+## Second-pass review
+
+Concur with the review. I checked the artifact, docs/signal-vs-authority.md, and the actual git diff for the worktree: the diff is limited to scripts/decision-audit-presence-check.mjs and its unit test, and it changes the existing PR gate from per-entry record presence to exact in-scope-path coverage by the union of parsed scope.files. The over-block section is honest: absent, malformed, unreadable, different-file, and directory-only scopes now contribute no coverage and can reject the PR, while legacy JSONL still passes before coverage logic. The signal-vs-authority argument is sound because this is structural boundary validation over enumerable changed paths and declared record paths, not a judgment about message meaning or intent. I found no unmentioned behavioral surface in the diff and no new schema, config, protocol surface, or tier-voiding plumbing beyond local parsing/passing of the already-existing decision-record content.
+
+Independent reviewer, 2026-08-21T01:10:23-07:00