instar 1.3.1196 → 1.3.1197

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

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1196",
+  "packageVersion": "1.3.1197",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

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

@@ -1,5 +1,5 @@
 {
-  "sha256": "245d913df7c5e45424a2491bef4d7ea849d2cce4e224a0ab1943fa31195ec96d",
+  "sha256": "a4dfe2bf7d36670a4e46e566bb3eed53479031f12f38a5450f4c2badd1754192",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1196"
+  "packageVersion": "1.3.1197"
 }

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

@@ -2,5 +2,5 @@
   "sha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
   "articleCount": 90,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1196"
+  "packageVersion": "1.3.1197"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1196",
+  "version": "1.3.1197",
   "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/standards-coverage.mjs

@@ -604,10 +604,22 @@ function validateRootSelfWiring() {
     return exactKeys(config, ['branches']) &&
       Array.isArray(config.branches) && config.branches.length === 1 && config.branches[0] === 'main';
   };
-  if (!exactKeys(workflow.on, ['push', 'pull_request', 'workflow_dispatch']) ||
+  // `pull_request_review` added 2026-08-22 and pinned, not merely permitted.
+  // The direction guard accepts the operator's approval as proof, but CI fired
+  // on push — before any approval could exist — so approving left the check
+  // red and finished, with nothing to re-run it. `dismissed` is pinned beside
+  // `submitted` because withdrawing an approval must re-run the guard and turn
+  // the check red again: a gate that only re-evaluates toward passing is not a
+  // gate. Pinning the types means neither can be dropped silently.
+  const reviewTrigger = workflow.on?.pull_request_review;
+  const reviewTriggerWired = exactKeys(reviewTrigger, ['types']) &&
+    Array.isArray(reviewTrigger.types) && reviewTrigger.types.length === 2 &&
+    reviewTrigger.types.includes('submitted') && reviewTrigger.types.includes('dismissed');
+  if (!exactKeys(workflow.on, ['push', 'pull_request', 'pull_request_review', 'workflow_dispatch']) ||
     !(workflow.on.workflow_dispatch === null || exactKeys(workflow.on.workflow_dispatch, [])) ||
+    !reviewTriggerWired ||
     !eventTargetsMain('push') || !eventTargetsMain('pull_request')) {
-    errors.push('The Root self-wiring requires top-level push and pull_request CI triggers targeting main');
+    errors.push('The Root self-wiring requires top-level push, pull_request and pull_request_review (submitted+dismissed) CI triggers targeting main');
   }
   const job = workflow.jobs?.['standards-coverage'];
   const steps = Array.isArray(job?.steps) ? job.steps : [];
@@ -666,31 +678,47 @@ function validateRootSelfWiring() {
   // protected-base step's is, so a behaviour edit here is a DECLARED edit.
   const expectedReviewRun = [
     'set -u',
-    'if [ "$EVENT_NAME" != "pull_request" ]; then',
-    "  associated=$(gh api \"repos/${GITHUB_REPOSITORY}/commits/${PUSH_SHA}/pulls\" 2>/dev/null || echo '[]')",
-    "  match=$(SHA=\"$PUSH_SHA\" jq -c '[.[] | select(.merge_commit_sha == env.SHA)] | if length == 1 then .[0] else empty end' <<< \"${associated:-[]}\" 2>/dev/null || echo '')",
+    'assoc_failed=0',
+    'if [ "$EVENT_NAME" != "pull_request" ] && [ "$EVENT_NAME" != "pull_request_review" ]; then',
+    '  if associated=$(gh api "repos/${GITHUB_REPOSITORY}/commits/${PUSH_SHA}/pulls" 2>/dev/null); then',
+    `    match=$(SHA="$PUSH_SHA" jq -c '[.[] | select(.merge_commit_sha == env.SHA)] | if length == 1 then .[0] else empty end' <<< "\${associated:-[]}" 2>/dev/null || echo '')`,
+    '  else',
+    "    associated='[]'",
+    "    match=''",
+    '    assoc_failed=1',
+    '  fi',
     "  PR=''",
     "  HEAD_SHA=''",
     "  PR_AUTHOR=''",
     '  if [ -n "$match" ]; then',
-    "    PR=$(jq -r '.number // empty' <<< \"$match\" 2>/dev/null || echo '')",
-    "    HEAD_SHA=$(jq -r '.head.sha // empty' <<< \"$match\" 2>/dev/null || echo '')",
-    "    PR_AUTHOR=$(jq -r '.user.login // empty' <<< \"$match\" 2>/dev/null || echo '')",
+    `    PR=$(jq -r '.number // empty' <<< "$match" 2>/dev/null || echo '')`,
+    `    HEAD_SHA=$(jq -r '.head.sha // empty' <<< "$match" 2>/dev/null || echo '')`,
+    `    PR_AUTHOR=$(jq -r '.user.login // empty' <<< "$match" 2>/dev/null || echo '')`,
     '  fi',
-    "  echo \"path-b: event=${EVENT_NAME} associated=$(jq -r 'length' <<< \"${associated:-[]}\" 2>/dev/null || echo unreadable) matched-pr=${PR:-none}\"",
+    `  echo "path-b: event=\${EVENT_NAME} associated=$(jq -r 'length' <<< "\${associated:-[]}" 2>/dev/null || echo unreadable) matched-pr=\${PR:-none} assoc-failed=\${assoc_failed}"`,
     'fi',
-    "reviews='[]'",
-    'if [ -n "$PR" ]; then',
-    "  reviews=$(gh api \"repos/${GITHUB_REPOSITORY}/pulls/${PR}/reviews?per_page=100\" 2>/dev/null || echo '[]')",
+    'echo "path-b: head-sha=${HEAD_SHA:-none} owner=${OWNER_LOGIN:-none}/${OWNER_TYPE:-none}"',
+    'if [ "$assoc_failed" = "1" ]; then',
+    `  printf '%s' '{"fetchError":"the commit-to-pull-request association call failed"}' > "$OUT"`,
+    'elif [ -z "$PR" ]; then',
+    '  jq -n --arg headSha "$HEAD_SHA" \\',
+    '        --arg ownerLogin "$OWNER_LOGIN" \\',
+    '        --arg ownerType "$OWNER_TYPE" \\',
+    '        --arg prAuthorLogin "$PR_AUTHOR" \\',
+    "     '{reviews:[], headSha:$headSha, ownerLogin:$ownerLogin, ownerType:$ownerType, prAuthorLogin:$prAuthorLogin}' \\",
+    `     > "$OUT" || printf '%s' '{"fetchError":"jq could not build the review context"}' > "$OUT"`,
+    'elif reviews=$(gh api "repos/${GITHUB_REPOSITORY}/pulls/${PR}/reviews?per_page=100" 2>/dev/null); then',
+    `  echo "path-b: reviews=$(jq -r 'length' <<< "$reviews" 2>/dev/null || echo unreadable)"`,
+    '  jq -n --argjson reviews "$reviews" \\',
+    '        --arg headSha "$HEAD_SHA" \\',
+    '        --arg ownerLogin "$OWNER_LOGIN" \\',
+    '        --arg ownerType "$OWNER_TYPE" \\',
+    '        --arg prAuthorLogin "$PR_AUTHOR" \\',
+    "     '{reviews:$reviews, headSha:$headSha, ownerLogin:$ownerLogin, ownerType:$ownerType, prAuthorLogin:$prAuthorLogin}' \\",
+    `     > "$OUT" || printf '%s' '{"fetchError":"jq could not build the review context"}' > "$OUT"`,
+    'else',
+    `  printf '%s' '{"fetchError":"the reviews API call failed"}' > "$OUT"`,
     'fi',
-    "echo \"path-b: reviews=$(jq -r 'length' <<< \"${reviews:-[]}\" 2>/dev/null || echo unreadable) head-sha=${HEAD_SHA:-none} owner=${OWNER_LOGIN:-none}/${OWNER_TYPE:-none}\"",
-    'jq -n --argjson reviews "${reviews:-[]}" \\',
-    '      --arg headSha "$HEAD_SHA" \\',
-    '      --arg ownerLogin "$OWNER_LOGIN" \\',
-    '      --arg ownerType "$OWNER_TYPE" \\',
-    '      --arg prAuthorLogin "$PR_AUTHOR" \\',
-    "   '{reviews:$reviews, headSha:$headSha, ownerLogin:$ownerLogin, ownerType:$ownerType, prAuthorLogin:$prAuthorLogin}' \\",
-    "   > \"$OUT\" || echo '{}' > \"$OUT\"",
     '',
   ].join('\n');
   const expectedBaseSha = "${{ github.event.pull_request.base.sha || github.event.before || format('{0}^', github.sha) }}";

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-24T02:13:09.489Z",
-  "instarVersion": "1.3.1196",
+  "generatedAt": "2026-08-24T02:50:42.124Z",
+  "instarVersion": "1.3.1197",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

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

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1196",
+  "packageVersion": "1.3.1197",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

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

@@ -1,5 +1,5 @@
 {
-  "sha256": "245d913df7c5e45424a2491bef4d7ea849d2cce4e224a0ab1943fa31195ec96d",
+  "sha256": "a4dfe2bf7d36670a4e46e566bb3eed53479031f12f38a5450f4c2badd1754192",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1196"
+  "packageVersion": "1.3.1197"
 }

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

@@ -2,5 +2,5 @@
   "sha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
   "articleCount": 90,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1196"
+  "packageVersion": "1.3.1197"
 }

package/upgrades/1.3.1197.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`.github/workflows/ci.yml` gains a `pull_request_review` trigger (`submitted`, `dismissed`), and The Root's self-wiring contract in `scripts/standards-coverage.mjs` pins it.
+
+The constitutional direction guard accepts the operator's approving review as proof that a registry change was authorised. CI fired on `push`, before any approval could exist, so the guard ran, correctly found none, and failed — and approving afterwards changed nothing, because the check had already finished. Approval had no event to re-run it.
+
+The trigger alone is not the fix. A `pull_request_review` event is a THIRD event shape, and the evidence step plus the three `AUDIT_CHANGE_*` expressions each assumed exactly two. The step branched on `!= "pull_request"`, so a review event took the PUSH path, where the pull request is found by matching `github.sha` against `merge_commit_sha` — and on a review event `github.sha` is the merge ref, which matches nothing. Left alone, the trigger fires, the job runs, no pull request resolves, an empty context is written and the guard refuses: approving would have turned the check red *reliably* rather than leaving it stale. The event is handled explicitly in all four places and the branch test is pinned as a fourth regression route.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+Observed live on PR #1960: approved at 22:03 with the standards check red and finished; a manual re-run of the same job then passed with no other change. That difference was the defect.
+
+`scripts/standards-coverage.mjs --check` passes against the branch worktree, so the pinned literal matches the workflow rather than a description of it. `dismissed` is pinned alongside `submitted` so withdrawing an approval re-runs the guard and turns the check red again — a gate that re-evaluates only toward passing is not a gate. Ratchet suite 38/38, including the negative controls asserting that a workflow missing the required triggers FAILS; their fixtures and expected error text moved with the contract.
+
+## Known Limits
+
+A review EDITED in place does not re-trigger (`pull_request_review` fires on submit/dismiss). The guard binds to the head sha, so the exposure is an edited review body rather than a state change, and any new push re-runs everything via `synchronize`.
+
+More broadly: this closes the gap for the review path only. Any other check whose inputs are not repository content has the same shape, and nothing enumerates those.

package/upgrades/ci-rerun-on-review.eli16.md

@@ -0,0 +1,31 @@
+# Making an approval actually do something — Plain-English Overview
+
+## The problem in one breath
+
+Tonight the operator approved a rulebook change and nothing happened. The check that was supposed to notice his approval had already run — minutes earlier, before he tapped — and finished red. Nothing told it to look again. It only didn't leave him stuck because someone was watching and pushed the button by hand.
+
+## What already exists
+
+The automated checks run when code changes. That has always been enough, because until today every input they cared about was code.
+
+## What this adds
+
+The checks now also run when someone approves a change, or withdraws an approval. That's it — one line saying "an approval is also a reason to look again."
+
+## The new pieces
+
+Nothing new is built. An existing set of checks gains one more reason to run.
+
+## The safeguards
+
+**Withdrawing counts too, and that's the important half.** If the operator approves and then changes his mind, the check runs again and goes back to red. A check that only re-runs when the news is good isn't a check — it would let a change of mind be quietly ignored while a stale green sat on the screen.
+
+**The new trigger is pinned in place.** There's a guard that records the exact shape of the automated checks, so this can't be quietly removed later. If it were, the symptom would be an operator approving into silence again — the same bug, returning without a trace. Now its absence breaks the build instead.
+
+## What ships when
+
+Immediately, and it needs nothing from the operator. It's the missing half of the approval path that shipped an hour ago.
+
+## What you actually need to decide
+
+Nothing. This is a defect found on first real use, fixed in the direction of your time rather than mine.

package/upgrades/side-effects/ci-rerun-on-review.md

@@ -0,0 +1,84 @@
+# Side-Effects Review — CI re-runs when a review is submitted or dismissed
+
+**Version / slug:** `ci-rerun-on-review`
+**Date:** `2026-08-22`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — one workflow trigger and its pinned contract`
+
+## Summary of the change
+
+`.github/workflows/ci.yml` gains a `pull_request_review` trigger (`submitted`, `dismissed`), and `scripts/standards-coverage.mjs` pins that trigger in The Root's self-wiring contract.
+
+**Found in production, on the first real use of the feature it completes.** The direction guard now accepts the operator's approving review as proof that a constitutional change was authorised. But CI fired on `push`, minutes before any approval could exist, so the guard ran, correctly found no approval, and failed. The operator then approved — and nothing happened. The check was already finished and red, with no event to re-run it. It only did not strand him because someone was watching and re-ran the job by hand.
+
+An approval flow whose result depends on a human remembering to re-run the job is not a flow.
+
+## Decision-point inventory
+
+- CI trigger set — **modify** — adds the event that makes an approval re-evaluate the guard.
+- The Root self-wiring contract in `standards-coverage.mjs` — **modify** — pins the new trigger and its two types.
+
+No agent-runtime decision point is touched.
+
+## 1. Over-block
+
+`dismissed` is included deliberately and is the only arm that can newly turn a check RED. That is the point: withdrawing an approval must re-run the guard and fail it again. **A gate that re-evaluates only in the direction of passing is not a gate** — it would let an operator's change of mind be silently ignored while the stale green sat there. This is over-blocking in the correct direction and is the whole reason `dismissed` is pinned rather than merely allowed.
+
+## 2. Under-block
+
+`pull_request_review` fires for `submitted`/`dismissed`, so a review EDITED in place (rare) does not re-trigger. Named rather than papered over: the guard binds to the head sha, so the practical exposure is an edited review body — not a state change — which cannot flip approval either way. A `synchronize` on any new push already re-runs everything.
+
+## 3. Level-of-abstraction fit
+
+One trigger on the workflow that already runs the check. No new job, no polling, no bot. The alternative — a scheduled job re-running checks — would be strictly worse: slower, noisier, and it would not know what it was waiting for.
+
+## 4. Signal vs authority compliance
+
+Unchanged. This alters WHEN the check runs, never what it decides. The guard's authority and the ruleset's authority are untouched.
+
+## 4b. Judgment-point check
+
+None added. A workflow trigger is a deterministic event subscription.
+
+## 5. Interactions
+
+- **The direction guard's path B** is the feature this completes; without it, path B is only usable by someone manually re-running jobs.
+- **The self-wiring contract** pins the trigger so it cannot be dropped silently. Dropping it would not fail any test otherwise, and the symptom would be an operator approving into a void — exactly the failure being fixed.
+- **CI cost:** one extra run per review event on open PRs. Reviews are rare here (the operator is asked only for constitutional changes), so this is not a meaningful load.
+- **The event SHAPE, found on rebase (2026-08-23) and the reason this branch is not a two-line change.** Adding a trigger gives the workflow a THIRD event shape, and three places assumed exactly two. The evidence step branched on `!= "pull_request"`, so a review event fell into the push branch, where the pull request is resolved by matching `github.sha` against `merge_commit_sha` — on a review event `github.sha` is the merge REF and matches nothing. The step would have resolved no pull request, written an empty context, and refused. The trigger added to make an approval count would have reliably rejected it, while every assertion about the trigger's presence stayed green: the event fires, the job runs, the check goes red. `AUDIT_CHANGE_KIND` / `_BASE_SHA` / `_HEAD_SHA` had the same two-shape assumption and would have handed the decision audit an EMPTY change kind — an unscoped run reporting clean. Both are fixed here and the first is pinned as a fourth regression route. This is the producer/consumer split in its exact shape: the trigger is the producer, and firing it is not the same fact as the checks handling it.
+
+## 6. External surfaces
+
+None. No route, no message, no notification.
+
+## 6b. Operator-surface quality
+
+This IS an operator-surface fix. Before: approve, and the red check stays red with no explanation. After: approve, and the check re-runs and goes green on its own.
+
+## 7. Multi-machine posture
+
+`unified` — trivially. A CI trigger; no state, no per-machine behaviour.
+
+## 8. Rollback cost
+
+The trigger, the event-shape handling in the evidence step and the three `AUDIT_CHANGE_*` expressions, plus their pinned counterparts in the contract. Reverting restores today's behaviour, in which an operator's approval requires a manual re-run to take effect — which is why the revert should not happen quietly. Reverting the event-shape handling ALONE is worse than reverting the whole change: the trigger would still fire and the check would then fail on every approval.
+
+## Conclusion
+
+Ship. It closes a gap found on the first real use of the approval path, in the direction of the operator's time rather than the agent's.
+
+## Second-pass review
+
+Ran, and it found something. Rebasing onto `main` after #1970 landed put this branch's trigger next to that change's push-path resolution for the first time, and the two together produced a third event shape neither had handled. See §5. The design question worth a second look — whether `dismissed` belongs — is answered under §1 and is the load-bearing half.
+
+## Evidence pointers
+
+- Observed live: PR #1960, approved at 22:03, standards check still red and finished; a manual re-run of the same job then passed with no other change. That difference is the bug.
+- `tests/unit/standards-coverage-ratchet.test.ts` 38/38, including the negative controls that assert a workflow missing the required triggers FAILS, whose fixtures and expected error text moved with the contract.
+- **Correction, on rebase.** An earlier version of this document cited moving the suite's population literals 88/89/89 → 89/89/89 as evidence. Those literals are GONE — #1970 removed them on `main`, because `protectedBase` is measured against the merge base and therefore depends on WHERE the test runs, so no literal can satisfy both the branch and the merged state. The rebase takes `main`'s removal. The claim is withdrawn rather than restated.
+- The fourth regression route (`pull_request_review` folded back into the push branch) is asserted in the same suite and fails the check when applied, alongside the three routes #1970 pinned.
+- `scripts/standards-coverage.mjs --check` run against this worktree: PASSED, so the pinned literal matches the workflow as it now stands rather than as it was described.
+
+## Class-Closure Declaration (display-only mirror)
+
+The class is "a check whose input can change without the check re-running." Closed for the review path specifically. NOT closed generally: any other check whose inputs are not repository content has the same shape, and nothing enumerates those. Named, not claimed.