instar 1.3.481 → 1.3.483

package/skills/spec-converge/scripts/write-convergence-tag.mjs

@@ -46,6 +46,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { checkEli16Overview } from '../../../scripts/eli16-overview-check.mjs';
 
 function parseArgs() {
@@ -56,6 +57,11 @@ function parseArgs() {
     report: null,
     crossModelReview: null,
     crossModelReason: null,
+    // Decision-Completeness counts (Autonomy Principle 2, Piece 2). Optional —
+    // when provided, the spec earns `single-run-completable: true` + the counts.
+    frontloadedDecisions: null,
+    cheapTags: null,
+    contestedCleared: null,
   };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -64,6 +70,9 @@ function parseArgs() {
     else if (a === '--report') out.report = args[++i];
     else if (a === '--cross-model-review') out.crossModelReview = args[++i];
     else if (a === '--cross-model-reason') out.crossModelReason = args[++i];
+    else if (a === '--frontloaded-decisions') out.frontloadedDecisions = parseInt(args[++i], 10);
+    else if (a === '--cheap-tags') out.cheapTags = parseInt(args[++i], 10);
+    else if (a === '--contested-cleared') out.contestedCleared = parseInt(args[++i], 10);
     else {
       console.error(`Unknown arg: ${a}`);
       process.exit(1);
@@ -72,22 +81,79 @@ function parseArgs() {
   if (!out.spec || !out.report || !Number.isFinite(out.iterations)) {
     console.error(
       'Usage: write-convergence-tag.mjs --spec PATH --iterations N --report PATH ' +
-        '[--cross-model-review VALUE] [--cross-model-reason REASON]',
+        '[--cross-model-review VALUE] [--cross-model-reason REASON] ' +
+        '[--frontloaded-decisions N --cheap-tags N --contested-cleared N]',
     );
     process.exit(1);
   }
   return out;
 }
 
+/**
+ * Decision-Completeness convergence criterion 2 (Autonomy Principle 2):
+ * a spec CANNOT converge while an unresolved user-decision remains in
+ * `## Open questions`. Returns the list of unresolved entry lines (empty = ok).
+ *
+ * Resolution markers that do NOT count as unresolved:
+ *   - a none-marker line: `*(none)*`, `(none)`, `None`, `None.`, `N/A`
+ *   - blockquote commentary (`> …`) explaining the section
+ *   - blank lines / horizontal rules
+ * Anything else with content (e.g. a `- **Q1:** …` bullet or a paragraph posing
+ * a question) is an unresolved entry.
+ */
+export function findOpenQuestions(specBody) {
+  // \b…[^\n]*$ (not \s*$) so heading variants like "## Open questions (round 2)"
+  // or "## Open Questions & Decisions" are still recognized — a variant heading
+  // must not make the section invisible to the gate (reviewer finding, PR 2).
+  const m = specBody.match(/^##\s+Open questions\b[^\n]*$/im);
+  if (!m) return []; // no section → nothing parked on the user
+  const start = m.index + m[0].length;
+  const restAfter = specBody.slice(start);
+  const nextHeading = restAfter.search(/^##\s+/m);
+  const section = nextHeading === -1 ? restAfter : restAfter.slice(0, nextHeading);
+  const NONE_RE = /^\s*[*_]*\(?\s*(none|n\/a)\s*\.?\)?[*_]*\s*$/i;
+  return section
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0)
+    .filter((l) => !l.startsWith('>')) // blockquote commentary
+    .filter((l) => !/^-{3,}$/.test(l)) // horizontal rule
+    .filter((l) => !NONE_RE.test(l));
+}
+
+// ─── main (guarded so the module is importable for tests) ────────────────
+// fileURLToPath (not URL.pathname) so %-encoded paths (spaces) compare correctly,
+// and realpathSync so a symlinked invocation still matches — a mismatch here
+// would otherwise silently exit 0 having done NOTHING (fail-loud lesson).
+const IS_MAIN = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    return (
+      fs.realpathSync(path.resolve(process.argv[1])) ===
+      fs.realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    // @silent-fallback-ok — an unresolvable argv path simply isn't this module.
+    return false;
+  }
+})();
+if (IS_MAIN) {
+  main();
+}
+
+function main() {
 const {
   spec: specArg,
   iterations,
   report: reportArg,
   crossModelReview,
   crossModelReason,
+  frontloadedDecisions,
+  cheapTags,
+  contestedCleared,
 } = parseArgs();
 
-const ROOT = path.resolve(new URL('../../..', import.meta.url).pathname);
+const ROOT = path.resolve(fileURLToPath(new URL('../../..', import.meta.url)));
 const specPath = path.resolve(ROOT, specArg);
 const reportPath = path.resolve(ROOT, reportArg);
 
@@ -130,6 +196,21 @@ if (!_eli16Result.ok) {
   process.exit(1);
 }
 
+// ─── Open-questions gate (Decision-Completeness, Autonomy Principle 2) ────
+// Convergence criterion 2: a spec CANNOT converge while an unresolved
+// user-decision remains in `## Open questions`. Structural — prose can't skip it.
+const openQuestions = findOpenQuestions(content);
+if (openQuestions.length > 0) {
+  console.error(
+    `Spec ${specArg} still has ${openQuestions.length} unresolved entr${openQuestions.length === 1 ? 'y' : 'ies'} in ## Open questions:\n` +
+      openQuestions.map((q) => `  • ${q.slice(0, 120)}`).join('\n') +
+      `\n\nA spec cannot converge while a user-decision is still open (Autonomy Principle 2).\n` +
+      `Resolve each into ## Frontloaded Decisions (or a contested-and-surviving\n` +
+      `cheap-to-change-after tag), leave the section reading "*(none)*", then re-run.`,
+  );
+  process.exit(1);
+}
+
 // Parse YAML frontmatter manually (no dependency).
 // Expect: /^---\n<body>\n---\n<rest>/
 const FM_RE = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
@@ -143,8 +224,9 @@ if (!match) {
 }
 const [, fmBody, rest] = match;
 
-// Strip any existing managed lines (review-* chain + cross-model-review chain)
-// so re-runs are idempotent — the field is rewritten, never duplicated.
+// Strip any existing managed lines (review-* chain + cross-model-review chain +
+// the single-run-completable chain) so re-runs are idempotent — the field is
+// rewritten, never duplicated.
 const preservedLines = fmBody
   .split('\n')
   .filter(
@@ -154,7 +236,11 @@ const preservedLines = fmBody
       !/^\s*review-completed-at\s*:/.test(l) &&
       !/^\s*review-report\s*:/.test(l) &&
       !/^\s*cross-model-review\s*:/.test(l) &&
-      !/^\s*cross-model-review-reason\s*:/.test(l),
+      !/^\s*cross-model-review-reason\s*:/.test(l) &&
+      !/^\s*single-run-completable\s*:/.test(l) &&
+      !/^\s*frontloaded-decisions\s*:/.test(l) &&
+      !/^\s*cheap-to-change-tags\s*:/.test(l) &&
+      !/^\s*contested-then-cleared\s*:/.test(l),
   )
   .join('\n')
   .trim();
@@ -186,6 +272,25 @@ if (crossModelReview) {
   }
 }
 
+// Decision-Completeness evidence (Autonomy Principle 2). The tag is EARNED:
+// it is only written here, after the open-questions gate above passed, and it
+// carries the reviewer's final-round counts so a downstream reader sees WHAT
+// was frontloaded, not just that a boolean is true.
+if (
+  Number.isFinite(frontloadedDecisions) ||
+  Number.isFinite(cheapTags) ||
+  Number.isFinite(contestedCleared)
+) {
+  newFmLines.push('single-run-completable: true');
+  if (Number.isFinite(frontloadedDecisions)) {
+    newFmLines.push(`frontloaded-decisions: ${frontloadedDecisions}`);
+  }
+  if (Number.isFinite(cheapTags)) newFmLines.push(`cheap-to-change-tags: ${cheapTags}`);
+  if (Number.isFinite(contestedCleared)) {
+    newFmLines.push(`contested-then-cleared: ${contestedCleared}`);
+  }
+}
+
 const newFm = newFmLines.join('\n');
 
 const newContent = `---\n${newFm}\n---\n${rest}`;
@@ -197,3 +302,4 @@ console.log(
     `  review-iterations=${iterations}\n` +
     `  review-report=${reportRel}`,
 );
+}

package/skills/spec-converge/templates/reviewer-decision-completeness.md

@@ -0,0 +1,83 @@
+# Reviewer Prompt — Decision Completeness Perspective
+
+You are the decision-completeness reviewer for an instar spec under convergence review.
+
+Read these in order:
+
+1. The spec file at {SPEC_PATH}
+2. Any architectural doc the spec references.
+
+Your DECISION-COMPLETENESS perspective (Autonomy Principle 2 — "frontload all user
+decisions into the spec so the agent completes it in a SINGLE autonomous run"): your
+ONLY job is to find every point where the building agent would have to **stop
+mid-run and ask the user**, and force each one to be settled NOW, in the spec —
+because agents build at 100–1000x behind dark/dry-run/read-only phases, a decision is
+cheaper to change *after* a completed run than to stop-and-wait mid-run for.
+
+Enumerate every mid-run stop-and-ask point. Each MUST be one of:
+
+1. **Frontloaded** — pulled into the spec's `## Frontloaded Decisions` section as a
+   concrete decision (made by the author, attributable, reversible-or-not stated). A
+   decision the user must make belongs in `## Open questions` — and the spec CANNOT
+   converge while any remain (the convergence criterion enforces this; your job is to
+   FIND the buried ones that never made it into either section).
+
+2. **Cheap-to-change-after** — explicitly tagged as a default safe to pick now and
+   change post-run, *because* the work ships behind a named dark / dry-run /
+   read-only phase.
+
+**CONTEST every cheap-to-change-after tag.** Do not merely check that a phase is
+named — independently assert reversibility. A closed NON-CHEAP taxonomy overrides any
+tag: anything touching
+
+- **durable external side-effects** (sent messages, published pages, external-system
+  writes, deleted data),
+- **money** (spend, billing, subscriptions),
+- **identity** (keys, principals, operator binding, trust levels), or
+- **a published / user-visible interface** (API contracts others consume, dashboards
+  users rely on, on-disk formats other tools read)
+
+is NEVER cheap-to-change-after, regardless of a "ships dark" label — the dark phase
+ends, and what happened during it does not un-happen. A contested tag you reject is a
+**MATERIAL finding that blocks convergence** — same authority as any other material
+issue.
+
+Specifically check:
+
+1. **Buried decisions** — sentences like "the implementer can decide", "TBD", "we
+   could either X or Y", "depending on user preference", "ask the user when" anywhere
+   in the body. Each is an un-frontloaded decision hiding outside `## Open questions`.
+
+2. **Unstated defaults** — config values, thresholds, naming, storage choices the
+   spec leaves open. Each needs a concrete default (frontloaded) or a contested-and-
+   surviving cheap tag.
+
+3. **Conditional scope** — "if X turns out to be true, then…" branches whose
+   resolution requires a human answer mid-build. Force the branch to be decided now
+   or restructured so either outcome is buildable without asking.
+
+4. **Approval points** — any step where the spec says to pause for sign-off mid-run
+   (deploy gates, "confirm with the user before…"). Distinguish a genuine
+   operator-only authority (legitimate — but then the spec must scope the single run
+   to END before it, with the gate as the run boundary) from ceremony (a material
+   finding: remove it or convert it to a post-run review).
+
+5. **Cheap-tag audit** — for every existing cheap-to-change-after tag: does the named
+   dark/dry-run/read-only phase actually exist in the spec's rollout plan? Does the
+   tagged decision hit the non-cheap taxonomy above? Reject violators.
+
+6. **Open-questions hygiene** — does `## Open questions` exist, and is every entry a
+   genuine user decision (not a design question the author should answer)? An
+   author-answerable question parked on the user is a deferral, not a decision.
+
+Produce a SHORT report (under 400 words):
+
+- **Verdict: CLEAN, MINOR ISSUES, or SERIOUS ISSUES**
+- Counts: `frontloaded-decisions: N`, `cheap-tags: N`, `contested-then-cleared: N`,
+  `contested-rejected: N`, `open-user-decisions: N`
+- Specific findings with spec-section references and concrete resolutions (which
+  section the decision must move to, what default you recommend, which cheap tag you
+  reject and why).
+
+Be rigorous. A spec converges only when an agent could complete it in ONE autonomous
+run without a single mid-run "what do you want me to do?"

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-10T22:30:23.798Z",
-  "instarVersion": "1.3.481",
+  "generatedAt": "2026-06-10T23:23:57.878Z",
+  "instarVersion": "1.3.483",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {
@@ -1522,7 +1522,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "7eed149592b598b2ffbea3da927113b4888579d2b53aadda2dcdf091e0457f59",
+      "contentHash": "781f517503b3cf19fa679f1acd223e87cbbeeab44fb16336ab22f2fa5137e005",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {

package/upgrades/1.3.482.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Conforms the Blocker Ledger (PR #1055) to the developmentAgent dark-feature gate standard (PR #1056) — the two merged from divergent branch points within minutes, so the new `lint-dev-agent-dark-gate` never saw #1055's hardcoded `monitoring.blockerLedger.enabled: false` default, leaving main latently lint-red. Fix: ConfigDefaults omits `enabled`, `AgentServer` resolves it via `resolveDevAgentGate` (LIVE on a development agent for dogfooding, DARK on the fleet → `/blockers` routes 503), the config type makes `enabled` optional, and the feature is registered in `DEV_GATED_FEATURES` with its safety justification (signal-only, no egress, no destructive action; one bounded fail-closed B17 settle check). Fleet behavior is unchanged; existing agents that already received the explicit `enabled: false` default keep it (applyDefaults adds only missing keys — no surprise activation).
+
+## What to Tell Your User
+
+- **Development agents only:** "My Blocker Ledger is now live on me (the dev agent) for dogfooding — when I hit something that feels like a wall, it's logged and worked through a pipeline instead of becoming an excuse. Fleet agents are unaffected; it stays off for them until it matures."
+- **Fleet agents:** None — no behavior change (the ledger stays dark until explicitly enabled).
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Blocker Ledger live-on-dev (dogfood) | Automatic on agents with `developmentAgent: true` — no config edit needed; explicit `monitoring.blockerLedger.enabled: true/false` still wins |
+
+## Evidence
+
+- `node scripts/lint-dev-agent-dark-gate.js`: clean (was failing with `[C: unclassified dark default]` at `src/config/ConfigDefaults.ts:257`).
+- `tests/unit/devGatedFeatures-wiring.test.ts`: green with the new `blockerLedger` registry entry — proves live-on-dev / dark-on-fleet resolution against real ConfigDefaults.
+- Blocker Ledger unit (35) + integration (7) + e2e (4): green, unchanged.
+- `npx tsc --noEmit`: exit 0.

package/upgrades/1.3.483.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Implements Piece 2 of `docs/specs/AUTONOMY-PRINCIPLES-ENFORCEMENT-SPEC.md` (Autonomy Principle 2 — frontload all user decisions so a spec completes in ONE autonomous run). Three parts, all in the agent-private spec-converge skill (no runtime `src/` surface):
+
+1. **New internal reviewer** (`reviewer-decision-completeness.md`, 6th of six): enumerates every mid-run stop-and-ask-the-user point; each must be frontloaded into `## Frontloaded Decisions` or tagged cheap-to-change-after behind a named dark/dry-run/read-only phase. The reviewer CONTESTS every cheap tag against a closed non-cheap taxonomy (durable external side-effects, money, identity, published/user-visible interface — never cheap); a rejected tag is a material finding that blocks convergence. Applies to ALL specs (D7), no per-spec override (D11).
+2. **New convergence criterion** (Phase 3): a spec cannot converge while `## Open questions` contains an unresolved user-decision.
+3. **Structural enforcement + earned evidence** (`write-convergence-tag.mjs`): the tag writer refuses to stamp `review-convergence` while open questions remain, and writes `single-run-completable: true` plus the reviewer's counts (`frontloaded-decisions`, `cheap-to-change-tags`, `contested-then-cleared`) — the tag carries its evidence, earned not minted. Pre-existing converged specs are unaffected (the gate fires at stamp time only).
+
+The spec's migration decision is resolved and recorded: spec-converge stays **agent-private** (matching `/instar-dev`'s not-user-facing status) — deliberately NOT promoted to the fleet builtin skill set, so no fleet migration surface exists.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- `tests/unit/write-convergence-tag-decision-completeness.test.ts`: 15 new tests — none-marker variants, section scoping, refuse-on-live-question (tag NOT written), stamp-on-resolved, earned counts, no-counts → no minted tag, idempotent re-runs.
+- `tests/unit/write-convergence-tag-crossmodel.test.ts`: 16 existing tests green (no regression from the import-safe main-guard restructure).
+- Live functional run: refused a spec with `- **Q1:** should we do A or B?` (exit 1 + remediation message); stamped `single-run-completable: true` + counts once the section read `*(none)*`.

package/upgrades/side-effects/blocker-ledger-dev-gate.md

@@ -0,0 +1,61 @@
+# Side-Effects Review — Blocker Ledger dev-gate registration (PR-1055 follow-up fix)
+
+**Version / slug:** `blocker-ledger-dev-gate`
+**Date:** `2026-06-10`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (4-file conformance fix to an enforced standard; no new decision logic)`
+
+## Summary of the change
+
+Registers the Blocker Ledger (merged in PR #1055) under the **developmentAgent dark-feature gate standard** enforced by `lint-dev-agent-dark-gate` (PR #1056). The two PRs merged within minutes of each other from divergent branch points, so PR #1055's hardcoded `monitoring.blockerLedger.enabled: false` default never met the new lint in CI — leaving main latently red (the next branch off main fails `npm run lint`). This fix conforms the feature to the standard: ConfigDefaults **omits** `enabled` (`blockerLedger: {}`), `AgentServer` resolves it via `resolveDevAgentGate(...)` (LIVE on a development agent for dogfooding, DARK on the fleet → routes 503), the config type makes `enabled` optional, and the feature is registered in `DEV_GATED_FEATURES` with the required safety justification (signal-only, no egress, no destructive action; one bounded fail-closed ≤200-token B17 check on the rare settle).
+
+Files: `src/config/ConfigDefaults.ts`, `src/server/AgentServer.ts`, `src/core/types.ts`, `src/core/devGatedFeatures.ts`.
+
+## Decision-point inventory
+
+- `AgentServer` BlockerLedger construction condition — **modify** — from a literal `enabled === true` check to `resolveDevAgentGate(enabled, config)`. The gate's semantics: explicit `true`/`false` wins; absent → live on dev agents, dark on fleet. No other decision point touched.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. (Fleet behavior is unchanged: absent flag still resolves false on non-dev agents → routes 503 exactly as before.)
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. The one behavior change is intended: development agents now run the ledger live without a config edit (the dogfood-on-dev standard).
+
+## 3. Level-of-abstraction fit
+
+Correct layer: this moves the feature onto the EXISTING gate primitive (`resolveDevAgentGate`) + registry (`DEV_GATED_FEATURES`) rather than a parallel mechanism. The wiring test (`devGatedFeatures-wiring.test.ts`) auto-covers the new entry with real ConfigDefaults.
+
+## 4. Signal vs authority compliance
+
+- [x] No — this change has no block/allow surface.
+
+The gate resolution is configuration mechanics, not a judgment decision. The ledger's own signal-only posture (PR #1055 artifact) is unchanged.
+
+## 5. Interactions
+
+- **Shadowing/double-fire/races:** none — same single construction site, same null-→503 path.
+- **Migration interplay:** `applyDefaults` adds only MISSING keys; an existing agent that already received `blockerLedger: { enabled: false }` from PR #1055's default keeps that explicit false (fleet-safe; dev agents that want live can clear it or set true). New installs get the empty object → gate decides. No surprise activation on the fleet.
+
+## 6. External surfaces
+
+None beyond the intended one: a development agent's `/blockers` routes go live (local Bearer-auth API + dashboard tab). Zero egress; no fleet-visible change.
+
+## 7. Rollback cost
+
+Trivial: revert restores the literal `enabled: false` default. No persistent state created by the gate itself.
+
+## Conclusion
+
+A 4-file conformance fix that repairs the PR #1055 × #1056 merge race (latent red main) and lands the feature on the correct dev-gate standard — which also supersedes the manual dogfood config flip on the dev agent. Verified: `lint-dev-agent-dark-gate` clean, `tsc` clean, dev-gate wiring test green (proves live-on-dev/dark-on-fleet with real defaults), Blocker Ledger unit (35) + integration (7) + e2e (4) all green. Clear to ship.
+
+---
+
+## Evidence pointers
+
+- `node scripts/lint-dev-agent-dark-gate.js` → clean (was: `[C: unclassified dark default]` on ConfigDefaults.ts:257).
+- `tests/unit/devGatedFeatures-wiring.test.ts` → green including the new `blockerLedger` entry.
+- `tests/unit/BlockerLedger.test.ts` (28) + `tests/unit/blockerSettleAuthority.test.ts` (7) + `tests/integration/blocker-ledger-routes.test.ts` (7) + `tests/e2e/blocker-ledger-lifecycle.test.ts` (4) → green.

package/upgrades/side-effects/decision-completeness-gate.md

@@ -0,0 +1,85 @@
+# Side-Effects Review — Decision-Completeness Gate in spec-converge (Autonomy Principles Enforcement, Piece 2)
+
+**Version / slug:** `decision-completeness-gate`
+**Date:** `2026-06-10`
+**Author:** `echo`
+**Second-pass reviewer:** `independent reviewer subagent — concern raised, all items resolved (see below)`
+
+## Summary of the change
+
+Implements Piece 2 of `docs/specs/AUTONOMY-PRINCIPLES-ENFORCEMENT-SPEC.md`: makes single-run-completability **provable** in spec-converge. Three parts:
+
+1. **New internal reviewer** (`templates/reviewer-decision-completeness.md`, 6th of six): enumerates every mid-run stop-and-ask-the-user point; each must be **frontloaded** into `## Frontloaded Decisions` or tagged **cheap-to-change-after** behind a named dark/dry-run/read-only phase. The reviewer **CONTESTS every cheap tag** against a closed non-cheap taxonomy (durable external side-effects, money, identity, published/user-visible interface — NEVER cheap); a rejected tag is a material finding that blocks convergence.
+2. **New convergence criterion** (SKILL.md Phase 3): a spec cannot converge while `## Open questions` contains an unresolved user-decision — additive to "no material new issues."
+3. **Structural enforcement + earned evidence** (`write-convergence-tag.mjs`): the tag writer now REFUSES to stamp `review-convergence` while open questions remain (criterion 2 cannot be skipped by prose), and writes `single-run-completable: true` + the reviewer's counts (`frontloaded-decisions`, `cheap-to-change-tags`, `contested-then-cleared`) so the tag carries its evidence — earned, not minted. The script gained an import-safe main guard so the parser (`findOpenQuestions`) is unit-testable.
+
+Files: `skills/spec-converge/SKILL.md`, `skills/spec-converge/templates/reviewer-decision-completeness.md` (new), `skills/spec-converge/scripts/write-convergence-tag.mjs`, `tests/unit/write-convergence-tag-decision-completeness.test.ts` (new, 15 tests).
+
+## Decision-point inventory
+
+- `write-convergence-tag.mjs` open-questions gate — **add** — a deterministic, commit-time text validator: refuses the convergence stamp while `## Open questions` has unresolved entries. (Hard-invariant class, see §4.)
+- Convergence criterion 2 (SKILL.md) — **add** — prose criterion backed by the structural gate above.
+- Decision-Completeness reviewer — **add** — produces findings (signals) folded into the round; blocking authority remains the convergence process itself.
+- `single-run-completable` frontmatter — **add** — disclosure only; does NOT change /instar-dev's `review-convergence` + `approved` enforcement.
+
+---
+
+## 1. Over-block
+
+The open-questions gate could refuse a spec whose `## Open questions` section contains commentary that *looks* unresolved. Mitigated: blockquote lines (`>`), none-markers (`*(none)*`, `(none)`, `None`, `None.`, `N/A`, emphasis variants), blank lines, and horizontal rules are all recognized as resolved; only contentful entries refuse. Unit-tested per variant. Residual: a spec author writing prose commentary as plain (non-blockquote) text under Open questions gets refused — acceptable, the error message names the fix and the convention (blockquote commentary) is already what existing specs use (this very spec's Piece-1 sibling used `> Per Principle 2…` + `*(none)*`, which passes).
+
+## 2. Under-block
+
+Two honest gaps, both by design: (a) the gate validates the SECTION, not the whole document — a user-decision buried in prose outside `## Open questions` is the REVIEWER's job to find (LLM judgment), not the deterministic gate's; (b) an author could delete the question instead of resolving it — but the Decision-Completeness reviewer re-reads the full spec every round and the deleted-but-unresolved decision resurfaces as a finding (the same "rewriting the spec to hide findings" anti-pattern the skill already documents and catches).
+
+## 3. Level-of-abstraction fit
+
+Correct: the deterministic part (is the section empty?) is a cheap structural validator at the tag-writer boundary — the same layer as the existing ELI16-presence check it sits beside. The judgment part (is this REALLY cheap-to-change-after? is that REALLY the user's decision?) lives in the LLM reviewer. Neither re-implements the other.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md
+
+- [x] No — the new blocking surface is **hard-invariant validation at a tool boundary**, not a judgment gate.
+
+The open-questions gate is the "structural validators at the boundary of the system" case the principle explicitly allows (like "this field must be a number"): it checks section emptiness against an enumerable marker set — zero judgment, deterministic, with a clear remediation message. The *judgment* calls (contesting cheap tags, finding buried decisions) are the reviewer's — and the reviewer produces findings (signals) that block only through the existing convergence process, exactly like the other five reviewers. No brittle check gained judgment authority.
+
+## 5. Interactions
+
+- **Shadowing:** the gate runs after the ELI16 check inside the same script — ordering is irrelevant (both must pass; neither consumes the other's input).
+- **Existing callers:** `write-convergence-tag.mjs` is invoked only by the spec-converge skill flow. Its existing tests (`write-convergence-tag-crossmodel.test.ts`, 5 tests) pass unchanged — the new args are optional and the main-guard restructure preserves CLI behavior (IS_MAIN hardened with realpath + fileURLToPath after second-pass review so a symlinked or %-encoded invocation cannot silently no-op).
+- **Pre-existing converged specs:** unaffected — the gate fires at stamp time only; already-stamped specs are never re-validated. Specs converged before this ships simply lack `single-run-completable` (honest, documented in SKILL.md).
+- **Idempotency:** re-runs strip and rewrite the new fields exactly like the review-* chain (tested).
+
+## 6. External surfaces
+
+None at runtime. This is skill-content + a repo script + tests: no `src/` change, no API, no fleet migration surface (spec-converge is **agent-private** — deliberately NOT in the builtin skill set, matching `/instar-dev`'s explicit not-user-facing status; the spec's "promote vs declare agent-private" decision is resolved as **agent-private**, recorded here). Future instar-dev specs converge under the stricter criteria — that is the intended effect.
+
+## 7. Rollback cost
+
+Trivial: revert the commit. No persistent state, no migration, no user-visible runtime surface. Specs stamped in the interim keep their earned fields (harmless disclosure).
+
+## Conclusion
+
+Piece 2 lands the spec's design with the criterion enforced structurally (Structure > Willpower) rather than as prose: the tag writer is now the chokepoint that makes "a spec cannot converge with open user-decisions" unskippable, and the `single-run-completable` tag carries its evidence counts. The one new blocking surface is hard-invariant validation, explicitly inside the principle's allowed class. Verified by 15 new unit tests + the 16 existing cross-model tag tests + live functional runs (refuses on a live question; stamps with counts once resolved). Clear to ship as PR 3-of-3's sibling (PR 2).
+
+---
+
+## Second-pass review
+
+**Reviewer:** independent reviewer subagent (adversarial audit of artifact + code + tests, ran the suites).
+**Independent read of the artifact: concern raised → all resolved this pass.**
+
+- MUST-FIX (resolved): the IS_MAIN guard could silently exit 0 (doing nothing) when invoked via a symlink or a %-encodable path — safe direction (tag never written without the checks) but a fail-loud violation. Fixed: realpathSync + fileURLToPath comparison; the pre-existing `ROOT` URL-pathname decode bug rode the same fix.
+- MUST-FIX (resolved): this artifact overstated the existing cross-model test count (claimed 16; vitest counts 5). Corrected above.
+- NICE-TO-HAVE (applied): heading-variant false-pass (`## Open questions (round 2)` was invisible to the gate) — regex loosened to `\b[^\n]*$`.
+- NICE-TO-HAVE (applied): SKILL.md now scopes the "earned" claim honestly (the structural guarantee is the open-questions invariant; the counts are caller-supplied disclosure on the same trust model as `--cross-model-review`) and names the blockquote-commentary convention's limit with its reviewer backstop.
+- Confirmed clean: signal-vs-authority compliance (deterministic hard-invariant validation; all judgment in the LLM reviewer), taxonomy fidelity to the spec, and test honesty (refuse → exit 1 AND tag absent; idempotency).
+
+---
+
+## Evidence pointers
+
+- `tests/unit/write-convergence-tag-decision-completeness.test.ts` — 15 tests: parser none-marker variants, section-scoping, refuse-on-live-question (and tag NOT written), stamp-on-resolved, earned counts, no-counts → no minted tag, idempotent re-runs.
+- `tests/unit/write-convergence-tag-crossmodel.test.ts` — 16 existing tests green (no regression from the main-guard restructure).
+- Live functional run: refused `- **Q1:** should we do A or B?` with exit 1 + remediation message; stamped `single-run-completable: true` + counts on the `*(none)*` variant.