@getarbiter/cli 0.5.0

package/dist/templates/schemas/milestone.schema.json.ejs

@@ -0,0 +1,164 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "milestone.schema.json",
+  "title": "Milestone set",
+  "description": "Contract for the fenced JSON block in docs/MILESTONES.md, the milestone SSOT. GitHub milestones are a projection of this file, never the other way round. Enforced by scripts/check-milestones.mjs (INV-146, #2480).",
+  "type": "object",
+  "required": ["milestones"],
+  "additionalProperties": false,
+  "properties": {
+    "milestones": {
+      "type": "array",
+      "description": "Live and upcoming milestones only. The migration is forward-only: closed pre-MS work stays in MILESTONES.md, which is an archive. Exit-criteria evidence is never reconstructed after the fact to satisfy the gate.",
+      "items": { "$ref": "#/definitions/milestone" }
+    },
+    "epics": {
+      "type": "array",
+      "description": "The epic index. An epic lives as a GitHub issue; this is the committed side of it, because the gate is offline by contract (INV-13) and cannot ask GitHub what it says. Sharing the milestone SSOT is deliberate: an epic that targets no milestone, and a milestone claiming an epic that does not exist, are the same defect seen from two sides, and only a reader holding both can see either.",
+      "items": { "$ref": "#/definitions/epic" }
+    }
+  },
+  "definitions": {
+    "milestone": {
+      "type": "object",
+      "required": ["id", "title", "goal", "exit_criteria", "horizon", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^MS-[0-9]{2}$",
+          "description": "Registered in docs/internal/SYSTEM/ID-REGISTRY.md. NOT the bare `M` prefix, which is methodology measures M1-M16."
+        },
+        "title": { "type": "string", "minLength": 8 },
+        "goal": {
+          "type": "object",
+          "description": "GSN Goal. A milestone states a claim about the world, not a list of tasks — the tasks are `members`.",
+          "required": ["claim", "strategy"],
+          "additionalProperties": false,
+          "properties": {
+            "claim": {
+              "type": "string",
+              "minLength": 16,
+              "description": "What is true once this milestone is verified."
+            },
+            "strategy": {
+              "type": "string",
+              "minLength": 16,
+              "description": "How the exit criteria are argued to establish the claim. GSN Strategy."
+            },
+            "context": { "type": "string" },
+            "assumptions": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "exit_criteria": {
+          "type": "array",
+          "minItems": 1,
+          "description": "GSN Solutions. What would have to be shown for the claim to hold.",
+          "items": {
+            "type": "object",
+            "required": ["id", "description"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string", "pattern": "^EC-[0-9]{2}$" },
+              "description": { "type": "string", "minLength": 8 },
+              "evidence_ref": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Resolvable pointer to the artifact that discharges this criterion: a gate name, a path under .arbiter/evidence/, or an INV id. Required by the gate before `status: done` — its absence is what makes `done` fail-closed."
+              }
+            }
+          }
+        },
+        "members": {
+          "type": "object",
+          "description": "What rolls up into this milestone. An epic that targets no milestone is the defect the shared gate exists to surface.",
+          "additionalProperties": false,
+          "properties": {
+            "epics": {
+              "type": "array",
+              "items": { "type": "string", "pattern": "^EP-[0-9]{2}$" }
+            },
+            "issues": {
+              "type": "array",
+              "items": { "type": "integer", "minimum": 1 }
+            },
+            "label": {
+              "type": "string",
+              "description": "GitHub label used to reconcile the projection."
+            }
+          }
+        },
+        "depends_on": {
+          "type": "array",
+          "description": "Must form a DAG across the set; the gate rejects a cycle.",
+          "items": { "type": "string", "pattern": "^MS-[0-9]{2}$" }
+        },
+        "horizon": {
+          "enum": ["now", "next", "later"],
+          "description": "Now/Next/Later. Granularity decays with distance — see the allOf rules below."
+        },
+        "due": {
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+          "description": "Required for `now`, optional for `next`, forbidden for `later`. A date on a `later` milestone is false precision, so the schema refuses it rather than trusting a convention."
+        },
+        "estimate_days": { "type": "number", "exclusiveMinimum": 0 },
+        "status": {
+          "enum": ["planned", "active", "done", "verified"],
+          "description": "`done` requires every exit criterion to carry an evidence_ref (gate-enforced, fail-closed). `verified` additionally requires those refs to resolve."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "horizon": { "const": "now" } },
+            "required": ["horizon"]
+          },
+          "then": {
+            "required": ["due", "estimate_days"],
+            "description": "A milestone claimed to be in flight has a date and a size, or it is not really `now`."
+          }
+        },
+        {
+          "if": {
+            "properties": { "horizon": { "const": "later" } },
+            "required": ["horizon"]
+          },
+          "then": { "not": { "required": ["due"] } }
+        }
+      ]
+    },
+    "epic": {
+      "type": "object",
+      "description": "A decomposable unit of work targeting exactly one milestone.",
+      "required": ["id", "title", "issue", "targets", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^EP-[0-9]{2}$",
+          "description": "Registered in docs/internal/SYSTEM/ID-REGISTRY.md."
+        },
+        "title": { "type": "string", "minLength": 8 },
+        "issue": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "The GitHub issue this epic IS. One issue may back at most one epic, and may not also appear in a milestone's members.issues — the same work claimed twice is a claim the join cannot reconcile."
+        },
+        "targets": {
+          "type": "string",
+          "pattern": "^MS-[0-9]{2}$",
+          "description": "Exactly one milestone. The targeted milestone must list this epic in members.epics; the gate checks both directions, because a one-sided link is how an epic silently detaches from the plan."
+        },
+        "status": {
+          "enum": ["open", "decomposed", "drained", "abandoned"],
+          "description": "`abandoned` is not a euphemism for `drained` and the ladder does not treat it as one: work can stop because it shipped or because it was dropped, and a roadmap that cannot say which has lost the only distinction that matters when reading it later. Both are terminal and both demand an evidence_ref. This rung exists because the first three epics recorded here were all closed — one completed, two not-planned — while the file called them open (#2480, wave 8)."
+        },
+        "evidence_ref": {
+          "type": "string",
+          "description": "Required by the gate for a terminal status (`drained`, `abandoned`) — the same fail-closed discipline a milestone's exit criteria carry, for the same reason: status is a claim, not evidence. A `github:` ref is accepted unresolved because this gate never reaches the network."
+        }
+      }
+    }
+  }
+}

package/dist/templates/schemas/rtm-verdict.schema.json.ejs

@@ -0,0 +1,52 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "rtm-verdict.schema.json",
+  "title": "RTM verification verdict",
+  "description": "Contract for .arbiter/evidence/rtm/<REQ-NNN>.json — the evidence a FEATURE_MATRIX row must carry before it may claim `Verified`. Enforced by scripts/check-feature-matrix.mjs (INV-112, #2480). `Verified` was previously a word someone typed; this makes it a claim with a transcript behind it, the same fail-closed posture INV-146 applies to milestone `done`.",
+  "type": "object",
+  "required": [
+    "feature_id",
+    "verdict",
+    "justification",
+    "command",
+    "transcript_digest",
+    "recorded_at"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "feature_id": {
+      "type": "string",
+      "pattern": "^REQ-[0-9]{3}$",
+      "description": "Must equal the row this envelope stands under. A mismatch means the evidence was copied from another requirement, which is how a green row ends up proving something else."
+    },
+    "verdict": {
+      "enum": ["PROVEN", "FAILING", "STALE", "UNRESOLVED", "UNCOVERED"],
+      "description": "The vocabulary forma's traceability lens already renders. Only PROVEN admits a `Verified` row; the other four are recordable states, not failures to hide — a requirement known to be FAILING is better governance than one silently left at Partial."
+    },
+    "justification": {
+      "type": "string",
+      "minLength": 24,
+      "description": "Why the cited evidence establishes the claim. A verdict with no argument is an opinion with a schema around it, so the length floor is deliberate: it is not satisfied by 'works'."
+    },
+    "command": {
+      "type": "string",
+      "minLength": 3,
+      "description": "The command actually executed to produce the transcript. PROVEN means something was RUN, not that someone read the code and was satisfied."
+    },
+    "transcript_digest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "sha256 of the executed command's output. The digest is not re-verifiable offline by design — its job is to make the claim falsifiable and attributable, not to re-run CI inside a lint gate."
+    },
+    "citations": {
+      "type": "array",
+      "description": "Where the proof lives, in axis 1's pinned-span grammar (`path#Lx-Ly@<12 hex>`) so a citation that drifts is reported OUTDATED by the same mechanism rather than a second one.",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "recorded_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the verdict was taken. A verdict has an age, and an old PROVEN over code that has since moved is what the citation pins exist to expose."
+    }
+  }
+}

package/dist/templates/schemas/source-record.schema.json.ejs

@@ -0,0 +1,91 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "source-record.schema.json",
+  "title": "SOTA source registry",
+  "description": "Contract for the SOURCES_START/END block in docs/SOURCES.md. A source is admitted as evidence only when its quotations can be checked against a committed excerpt — a URL in a document proves nothing, because the page can change or can never have said it. Enforced by scripts/check-sources.mjs (INV-147, #2480).",
+  "type": "object",
+  "required": ["sources"],
+  "additionalProperties": false,
+  "properties": {
+    "sources": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/source" }
+    }
+  },
+  "definitions": {
+    "source": {
+      "type": "object",
+      "required": [
+        "id",
+        "title",
+        "url",
+        "kind",
+        "retrieved_at",
+        "excerpt_path",
+        "content_hash",
+        "citations",
+        "selected_by_user",
+        "application_status"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^SRC-[0-9]{3}$",
+          "description": "SRC-NNN, three digits. The scheme is registered in arbiter's docs/internal/SYSTEM/ID-REGISTRY.md; a governed project inherits the shape, not the registry."
+        },
+        "title": { "type": "string", "minLength": 4 },
+        "url": {
+          "type": "string",
+          "minLength": 8,
+          "description": "Recorded provenance, never dereferenced by the tier-1 gate. A gate that fails when a website is down fails for a reason unrelated to the claim it guards."
+        },
+        "kind": {
+          "enum": ["paper", "standard", "spec", "docs", "tool", "book"]
+        },
+        "retrieved_at": {
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+          "description": "When the excerpt was taken. A source has an age, and the web moves under citations."
+        },
+        "excerpt_path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Repository-contained, citation-length excerpt tracked by Git. A newly added excerpt staged for its first commit is accepted so the pre-commit check remains usable. Short by design: enough to check the quotations this project makes, never a reproduction of the source."
+        },
+        "content_hash": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "sha256 of the excerpt file. Without it, a substring check would still pass on an excerpt edited after the fact — the evidence could drift away from what was actually read."
+        },
+        "citations": {
+          "type": "array",
+          "minItems": 1,
+          "description": "A source nobody quotes is a bookmark, not evidence. Each quoted_text must appear verbatim in the excerpt.",
+          "items": {
+            "type": "object",
+            "required": ["quoted_text"],
+            "additionalProperties": false,
+            "properties": {
+              "quoted_text": { "type": "string", "minLength": 8 },
+              "note": { "type": "string" }
+            }
+          }
+        },
+        "selected_by_user": {
+          "type": "boolean",
+          "description": "Whether a human chose this source from a shortlist. An agent-selected source is a candidate; adoption is a human act, and the field records which happened rather than blurring the two."
+        },
+        "informs": {
+          "type": "array",
+          "description": "The ADR / INV ids this source bears on. Empty means cited but not yet applied to any decision — visible rather than implied.",
+          "items": { "type": "string" }
+        },
+        "application_status": {
+          "enum": ["candidate", "selected", "cited", "applied-certified"],
+          "description": "The ladder. `applied-certified` is the only rung claiming the source demonstrably shaped the architecture, and tier 3 (graph reachability) is what will admit it — tier 1 records the claim but does not adjudicate it."
+        }
+      }
+    }
+  }
+}

package/dist/templates/schemas/tabletop-evidence.schema.json.ejs

@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "tabletop-evidence.schema.json",
+  "title": "Tabletop evidence",
+  "description": "Frontmatter and findings-table contract for a file under .arbiter/evidence/tabletop/. Enforced by scripts/check-tabletop-evidence.mjs (#2429).",
+  "type": "object",
+  "required": ["scenario", "sha", "date", "persona", "steps", "findings"],
+  "properties": {
+    "scenario": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Catalogue slug from docs/internal/METHOD/TABLETOP-SCENARIOS.md, or a slugified free-text use case."
+    },
+    "sha": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{7,40}$",
+      "description": "Commit the tabletop was walked against — findings are only readable against a pinned tree."
+    },
+    "date": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "persona": {
+      "type": "string",
+      "minLength": 8,
+      "description": "Who the agent narrated the journey as."
+    },
+    "steps": { "type": "integer", "minimum": 1 },
+    "findings": {
+      "type": "object",
+      "required": ["blocker", "major", "minor"],
+      "description": "Per-severity counts; must equal the findings-table row counts.",
+      "properties": {
+        "blocker": { "type": "integer", "minimum": 0 },
+        "major": { "type": "integer", "minimum": 0 },
+        "minor": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "x-findings-table": {
+    "description": "The findings table's shape. Kept here so the gate, the skill and the reader share one source of truth.",
+    "columns": [
+      "step",
+      "doc claim (path:line)",
+      "observed",
+      "severity",
+      "class",
+      "proposed permanent check",
+      "owner"
+    ],
+    "severity": ["blocker", "major", "minor"],
+    "class": ["phantom-command", "doc-drift", "missing-gate", "ux", "bug"],
+    "ownerRequiredFor": ["blocker", "major"],
+    "ownerPattern": "^(#[0-9]+|https://\\S+|fixed:[0-9a-f]{7,40})$"
+  }
+}

package/dist/templates/schemas/use-case.schema.json.ejs

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "use-case.schema.json",
+  "title": "Use-case set",
+  "description": "Contract for docs/USE_CASES.md, the use-case SSOT. A use case is what an ACTOR wants to accomplish, and the features that accomplishing it requires. Enforced by scripts/check-use-cases.mjs (UC-NN, #2480 wave 8). Shape taken from a real product's matrix rather than invented: the fields are those a shipped use-case matrix already carried, which is also what forma's traceability lens renders.",
+  "type": "object",
+  "required": ["useCases"],
+  "additionalProperties": false,
+  "properties": {
+    "useCases": {
+      "type": "array",
+      "description": "Every use case the product claims. An empty list is legitimate and distinct from an absent file: the first means nothing is claimed, the second means nothing is codified.",
+      "items": { "$ref": "#/definitions/useCase" }
+    }
+  },
+  "definitions": {
+    "useCase": {
+      "type": "object",
+      "required": ["id", "actor", "goal", "featureIds"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^UC-[0-9]{2,3}$",
+          "description": "Registered in the ID registry."
+        },
+        "actor": {
+          "type": "string",
+          "minLength": 2,
+          "description": "WHO wants this. A use case with no actor is a feature description wearing a use case's name — the actor is what makes it a claim about someone's world rather than about the code."
+        },
+        "goal": {
+          "type": "string",
+          "minLength": 8,
+          "description": "What the actor accomplishes, in their terms. Not the mechanism."
+        },
+        "featureIds": {
+          "type": "array",
+          "minItems": 1,
+          "description": "The features this use case requires, which the gate resolves against the feature matrix. `minItems: 1` is the load-bearing constraint: a use case demanding no feature is a promise with nothing behind it, and it is precisely what an unmaintained matrix accumulates.",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "journeyIds": {
+          "type": "array",
+          "description": "Optional journeys this use case belongs to. Not resolved — journeys are a product-side vocabulary this contract does not own, and validating a reference into a namespace it cannot see would be a false red.",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "prdRef": {
+          "type": "string",
+          "description": "Optional upward anchor to the requirement's origin, e.g. `PRD §3`. Format-only, never dereferenced — the same treatment FEATURE_MATRIX's source_ref gives a non-canonical anchor, and for the same reason: a gate that reaches outside its own tree fails when the network does, not when the document is wrong."
+        },
+        "status": {
+          "enum": ["proposed", "drafted", "linked", "exercised"],
+          "description": "The ladder. `linked` means every featureId resolves; `exercised` additionally means a tabletop scenario walks it. Both are gate-checked, so neither can be claimed by typing it."
+        }
+      }
+    }
+  }
+}

package/dist/templates/scripts/apply-branch-protection.mjs.ejs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// apply-branch-protection.mjs — idempotent GitHub branch protection apply
+// Generated by arbiter — run once after repo creation: node scripts/apply-branch-protection.mjs
+// Requires: gh CLI authenticated with admin access to the repository
+<%
+const _requireCodeOwners = isL3Plus;
+const _isSolo = typeof collaborationMode !== 'undefined' && collaborationMode === 'trunk-solo';
+const _contexts = _isSolo
+  ? ['CI Required']
+  : ['CI Required', 'Human Approval Required (INV-74)'];
+%>
+import { spawnSync } from 'node:child_process'
+import {
+  EXACT_SHA_BRANCH_SETTINGS,
+  EXACT_SHA_REPO_SETTINGS,
+} from './lib/exact-sha-policy.mjs'
+
+function gh(...args) {
+  const result = spawnSync('gh', args, { encoding: 'utf8' })
+  if (result.status !== 0) {
+    console.error(`ERROR: gh ${args[0]} failed — ${result.stderr.trim()}`)
+    process.exit(1)
+  }
+  return result.stdout.trim()
+}
+
+function ghApi(endpoint, method, body) {
+  const input = JSON.stringify(body)
+  const result = spawnSync('gh', ['api', '--method', method, endpoint, '--input', '-'], {
+    input,
+    encoding: 'utf8',
+  })
+  if (result.status !== 0) {
+    console.error(`ERROR: gh api ${method} ${endpoint} failed — ${result.stderr?.trim() ?? ''}`)
+    process.exit(1)
+  }
+}
+
+const repo = gh('repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner')
+
+console.log(`Applying branch protection to ${repo} main branch...`)
+
+const payload = JSON.stringify({
+  required_status_checks: {
+    strict: true,
+    contexts: <%- JSON.stringify(_contexts) %>,
+  },
+  enforce_admins: false,
+<% if (_isSolo) { %>
+  required_pull_request_reviews: null,
+<% } else { %>
+  required_pull_request_reviews: {
+    required_approving_review_count: 1,
+    dismiss_stale_reviews: true,
+    require_code_owner_reviews: <%= _requireCodeOwners %>,
+  },
+<% } %>
+  restrictions: null,
+  ...EXACT_SHA_BRANCH_SETTINGS,
+})
+
+ghApi(`repos/${repo}/branches/main/protection`, 'PUT', JSON.parse(payload))
+
+// INV-101: canonical executable policy shared with pr-merge-watch.
+const repoSettings = JSON.stringify(EXACT_SHA_REPO_SETTINGS)
+
+ghApi(`repos/${repo}`, 'PATCH', JSON.parse(repoSettings))
+
+console.log('Branch protection and merge settings applied.')
+console.log('  Merge method: exact-SHA CAS (squash=false, rebase=false, force=false)')

package/dist/templates/scripts/audit-toolchain.mjs.ejs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// scripts/audit-toolchain.mjs
+// Toolchain audit for <%= projectName %> — generated by arbiter.
+// DO NOT EDIT by hand — re-run `arbiter update` to regenerate.
+//
+// Checks that required CI workflow files, gate scripts, and build toolchain
+// are present and functional. Reports pass/fail per check.
+//
+// Exit codes:
+//   0 — all checks pass
+//   1 — one or more checks failed
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const repoRoot = resolve(__dirname, '..')
+
+const GREEN = '\x1b[32m'
+const RED = '\x1b[31m'
+const RESET = '\x1b[0m'
+
+let passed = 0
+let failed = 0
+
+function pass(label) {
+  process.stdout.write(`  ${GREEN}PASS${RESET}  ${label}\n`)
+  passed++
+}
+
+function fail(label, detail) {
+  process.stdout.write(`  ${RED}FAIL${RESET}  ${label}${detail ? ` — ${detail}` : ''}\n`)
+  failed++
+}
+
+function checkExists(label, relPath) {
+  const abs = resolve(repoRoot, relPath)
+  if (existsSync(abs)) {
+    pass(label)
+  } else {
+    fail(label, `missing: ${relPath}`)
+  }
+}
+
+// ─── 1. Required CI workflow files ───────────────────────────────────────────
+// #1835: only the two workflows unconditional whenever GitHub is on are asserted
+// here. 05-release.yml (skipped for pipelineStyle 'starter') and a nightly
+// workflow (06-nightly.yml full vs 06-nightly-lite.yml for trunk-solo, L3+ only)
+// depend on a style/collaborationMode/governanceLevel derivation this generic
+// audit does not replicate — asserting them caused false FAILs for real configs.
+<% if (useGitHub) { %>
+process.stdout.write('\n=== Check: CI workflow files ===\n')
+
+const REQUIRED_WORKFLOWS = [
+  '.github/workflows/01-pr-fast.yml',
+  '.github/workflows/02-pr-extended.yml',
+]
+
+for (const wf of REQUIRED_WORKFLOWS) {
+  checkExists(`workflow ${wf}`, wf)
+}
+<% } %>
+
+// ─── 2. Required gate scripts ─────────────────────────────────────────────────
+
+process.stdout.write('\n=== Check: Gate scripts ===\n')
+
+const REQUIRED_SCRIPTS = [
+  'scripts/check-all.mjs',
+  'scripts/check-drift.mjs',
+<% if (governanceLevel !== 'L1') { %>
+  'scripts/check-docs.mjs',
+<% } %>
+  'scripts/check-doc-links.mjs',
+]
+
+for (const s of REQUIRED_SCRIPTS) {
+  checkExists(`script ${s}`, s)
+}
+
+// ─── 3. CLI buildability ──────────────────────────────────────────────────────
+
+process.stdout.write('\n=== Check: CLI buildability ===\n')
+
+const pkgPath = resolve(repoRoot, 'package.json')
+if (!existsSync(pkgPath)) {
+  fail('package.json exists', 'not found')
+} else {
+  pass('package.json exists')
+
+  let pkg
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+  } catch {
+    pkg = null
+  }
+
+  if (pkg && pkg.scripts && pkg.scripts.build) {
+    pass('build script defined in package.json')
+  } else {
+    fail('build script defined in package.json', 'scripts.build missing')
+  }
+}
+
+// ─── Result ───────────────────────────────────────────────────────────────────
+
+process.stdout.write('\n' + '─'.repeat(52) + '\n')
+process.stdout.write(`Passed: ${passed}  Failed: ${failed}\n`)
+process.stdout.write('─'.repeat(52) + '\n\n')
+
+process.exit(failed > 0 ? 1 : 0)

package/dist/templates/scripts/bg-run.sh.ejs

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# bg-run.sh (#2103) — launch a long-running command DETACHED (survives the caller's
+# session), recording {PID, exit code, log} for a coordinator-side pid-watch.sh.
+#
+# M16 terminal handoff — subagents never own waits: the WORKER's brief ends at
+# commit + launch + a structured handoff {SHA, worktree, PID, exit-file, log} with
+# an explicit END-TURN. All watches belong to the coordinator (pid-watch.sh, a
+# background until-loop on the exit file). This helper replaces the raw nohup
+# recipe (feedback_scoped_pid_wait): the detached process is invisible to harness
+# child-tracking BY DESIGN, so the launching agent MUST end its turn after this
+# returns — a foreground wait on this PID is exactly the parked-wait bug M16 bans.
+#
+# Usage: bg-run.sh <name> -- <command> [args...]
+# Env:   BG_DIR (default .arbiter/bg) — where <name>.pid/.exit/.log land.
+# Exit:  0 on successful DETACHED launch (the job keeps running after this returns).
+set -euo pipefail
+
+BG_DIR="${BG_DIR:-.arbiter/bg}"
+
+if [ "${1:-}" = "--self-test" ]; then
+  SELF_BG_DIR=$(mktemp -d)
+  BG_DIR="$SELF_BG_DIR" "$0" selftest -- sh -c 'sleep 1; exit 7' >/dev/null 2>&1
+  i=0
+  while [ ! -f "$SELF_BG_DIR/selftest.exit" ] && [ "$i" -lt 50 ]; do
+    sleep 0.1
+    i=$((i + 1))
+  done
+  rc=""
+  if [ -f "$SELF_BG_DIR/selftest.exit" ]; then
+    rc=$(cat "$SELF_BG_DIR/selftest.exit")
+  fi
+  if [ "$rc" != "7" ]; then
+    echo "bg-run.sh self-test FAILED: exit code not captured as 7 (got: ${rc:-none})" >&2
+    rm -rf "$SELF_BG_DIR"
+    exit 1
+  fi
+  rm -rf "$SELF_BG_DIR"
+  echo "bg-run.sh self-test OK (detached launch + exit-code capture)"
+  exit 0
+fi
+
+if [ "$#" -lt 3 ] || [ "$2" != "--" ]; then
+  echo "Usage: bg-run.sh <name> -- <command> [args...]" >&2
+  echo "       bg-run.sh --self-test" >&2
+  exit 2
+fi
+
+NAME="$1"
+shift 2
+mkdir -p "$BG_DIR"
+: >"$BG_DIR/$NAME.log"
+# setsid: own session, fully detached (survives the caller's session end).
+# nohup: ignore SIGHUP. The wrapper records the command's exit code into
+# <name>.exit when it finishes — the only signal pid-watch.sh ever reads.
+BG_EXIT="$BG_DIR/$NAME.exit" setsid nohup bash -c '"$@"; rc=$?; printf "%s" "$rc" > "$BG_EXIT"' \
+  bash "$@" >"$BG_DIR/$NAME.log" 2>&1 &
+echo $! >"$BG_DIR/$NAME.pid"
+
+echo "bg-run: launched $NAME (pid $(cat "$BG_DIR/$NAME.pid"), exit-file $BG_DIR/$NAME.exit, log $BG_DIR/$NAME.log)"