@getarbiter/cli 0.5.0

package/dist/templates/scripts/capacity-probe.mjs.ejs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// scripts/capacity-probe.mjs (#2098) — combined local+remote saturation advisory.
+//
+// Root cause fixed: self-hosted CI runners share the exact same host as
+// local gate execution — a load spike was once misdiagnosed as "5 concurrent
+// local gates" when GH Actions runner contention was an equal contributor.
+// No single signal combines local-queue-depth + remote-runner-busy; this does.
+//
+// Usage: capacity-probe <owner/repo>
+// Prints one line, exit 0 (OK) or 1 (SATURATED).
+import { execFileSync } from 'node:child_process'
+import { cpus, loadavg } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { countLockWaiters } from './lib/waiter-count.mjs'
+import { gateLockPathFor } from './lib/gate-mutex.mjs'
+
+// ── local load — Node stdlib covers this, no /proc parsing or `nproc` shell-out needed ──
+
+export function localLoad() {
+  return { load1: loadavg()[0], nproc: cpus().length }
+}
+
+// ── gate-queue depth ──
+//
+// #2427 extracted the key derivation this file used to carry as a documented
+// duplicate: it now lives in scripts/lib/gate-mutex.mjs, the ONE .mjs-side copy
+// of the gate mutex's lock-path derivation, which the pre-push hook and the gate
+// itself also use. Re-exported here so this script's own consumers keep their
+// import path.
+export { gateLockPathFor }
+
+export function gateQueueDepth(dir = process.cwd()) {
+  try {
+    return countLockWaiters(gateLockPathFor(dir))
+    // FAIL-OPEN-INTENT: advisory signal — no repo/lock here just means zero queue depth.
+  } catch {
+    return 0
+  }
+}
+
+// ── remote (gh) — advisory only, never throws: unreachable/unauthenticated
+// `gh` degrades to a zero signal rather than crashing the probe ──
+
+function ghNumber(args) {
+  try {
+    const out = execFileSync('gh', args, { encoding: 'utf-8', timeout: 10_000 })
+    const n = Number(out.trim())
+    return Number.isFinite(n) ? n : 0
+    // FAIL-OPEN-INTENT: advisory signal — unreachable/unauthenticated gh degrades to zero.
+  } catch {
+    return 0
+  }
+}
+
+export function remoteSignal(ownerRepo) {
+  const runnersBusy = ghNumber([
+    'api',
+    `repos/${ownerRepo}/actions/runners`,
+    '--jq',
+    '[.runners[]|select(.busy)]|length',
+  ])
+  const runnersTotal = ghNumber([
+    'api',
+    `repos/${ownerRepo}/actions/runners`,
+    '--jq',
+    '.runners|length',
+  ])
+  const queuedRuns = ghNumber([
+    'run',
+    'list',
+    '-R',
+    ownerRepo,
+    '--status',
+    'queued',
+    '--json',
+    'databaseId',
+    '--jq',
+    'length',
+  ])
+  return { runnersBusy, runnersTotal, queuedRuns }
+}
+
+// ── verdict — pure, unit-testable without touching gh/os/fs ──
+
+/**
+ * SATURATED iff (all runners busy AND a run is queued) OR (load > 1.5x nproc)
+ * OR (gate-queue depth >= 3).
+ * ponytail: thresholds are a first cut (no data behind 1.5x / 3 yet) — tune
+ * via flags if they misfire in practice, not preemptively configurable.
+ * @param {{load1:number, nproc:number, gateQueueDepth:number, runnersBusy:number, runnersTotal:number, queuedRuns:number}} signals
+ */
+export function computeVerdict(signals) {
+  const {
+    load1,
+    nproc,
+    gateQueueDepth: queueDepth,
+    runnersBusy,
+    runnersTotal,
+    queuedRuns,
+  } = signals
+  const remoteSaturated = runnersTotal > 0 && runnersBusy >= runnersTotal && queuedRuns > 0
+  const loadSaturated = load1 > 1.5 * nproc
+  const queueSaturated = queueDepth >= 3
+  return {
+    saturated: remoteSaturated || loadSaturated || queueSaturated,
+    remoteSaturated,
+    loadSaturated,
+    queueSaturated,
+  }
+}
+
+async function main() {
+  const [ownerRepo] = process.argv.slice(2)
+  if (!ownerRepo) {
+    process.stderr.write('usage: capacity-probe <owner/repo>\n')
+    process.exit(2)
+  }
+
+  const { load1, nproc } = localLoad()
+  const queueDepth = gateQueueDepth()
+  const { runnersBusy, runnersTotal, queuedRuns } = remoteSignal(ownerRepo)
+  const verdict = computeVerdict({
+    load1,
+    nproc,
+    gateQueueDepth: queueDepth,
+    runnersBusy,
+    runnersTotal,
+    queuedRuns,
+  })
+
+  process.stdout.write(
+    `capacity-probe: ${verdict.saturated ? 'SATURATED' : 'OK'} ` +
+      `load=${load1.toFixed(2)}/${nproc} queue=${queueDepth} runners=${runnersBusy}/${runnersTotal} busy queued=${queuedRuns}\n`,
+  )
+  process.exit(verdict.saturated ? 1 : 0)
+}
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url)
+if (isMain) {
+  try {
+    await main()
+  } catch (e) {
+    process.stderr.write(`capacity-probe: unexpected error: ${e.stack ?? e}\n`)
+    process.exit(1)
+  }
+}

package/dist/templates/scripts/capture-debt-baseline.mjs.ejs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// capture-debt-baseline.mjs — generated by arbiter
+// Captures tech debt metrics into scripts/debt-baseline.json (schema v2).
+// Run from project root: node scripts/capture-debt-baseline.mjs [--update]
+// --update: one-way ratchet — only tighten metrics, never loosen.
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { collectMetrics, countTodos, getCommit, assertKeyParity } from './debt-lib.mjs'
+
+const updateMode = process.argv.includes('--update')
+const cwd = process.cwd()
+const BASELINE_FILE = resolve(cwd, 'scripts/debt-baseline.json')
+
+// ─── Collect current metrics ──────────────────────────────────────────────────
+// Capture is an explicit human-invoked operation: a collector that RAN but
+// failed must abort the capture, or the baseline is born without that ratchet
+// metric (greenfield) — fail-closed (#1286).
+const collectionErrors = []
+const collected = collectMetrics(cwd, collectionErrors)
+collected.todoCount = { value: countTodos(cwd), unit: 'count', direction: 'lower-is-better' }
+
+// ─── Load prior baseline (if --update mode) ───────────────────────────────────
+// Keys in existing.metrics that are absent from `collected` (e.g. tools not
+// installed on the current machine) MUST survive, otherwise --update silently
+// drops metrics when any capture tool is unavailable.
+let existing = { metrics: {} }
+if (updateMode && existsSync(BASELINE_FILE)) {
+  try {
+    const parsed = JSON.parse(readFileSync(BASELINE_FILE, 'utf-8'))
+    existing = { metrics: parsed.metrics ?? {} }
+  } catch (err) {
+    throw new Error(`Malformed baseline at ${BASELINE_FILE}: ${err.message}`)
+  }
+}
+
+// ─── Build baseline object (seeded from prior, ratcheted by collected) ───────
+const baseline = {
+  version: 2,
+  capturedAt: new Date().toISOString(),
+  commit: getCommit(cwd),
+  archetype: '<%= archetype %>',
+  metrics: { ...existing.metrics },
+}
+
+// One-way ratchet: for each currently-collected metric, keep the tighter value.
+// For metrics present only in `existing` (tool unavailable this run), the
+// spread above has already preserved them verbatim.
+for (const [key, current] of Object.entries(collected)) {
+  const prev = existing.metrics[key]
+  // No prior value, or direction changed between runs — overwrite with current.
+  if (!prev || prev.direction !== current.direction) {
+    baseline.metrics[key] = current
+    continue
+  }
+  // Strict comparison: on a tie, keep `prev` so sub-fields like `items`
+  // (populated by archunitFailingRules on machines with test results) are
+  // not silently overwritten when the current run produces an empty list.
+  if (current.direction === 'higher-is-better') {
+    baseline.metrics[key] = current.value > prev.value ? current : prev
+  } else if (current.direction === 'lower-is-better') {
+    baseline.metrics[key] = current.value < prev.value ? current : prev
+  } else {
+    // Unknown direction — overwrite (no ratchet applicable).
+    baseline.metrics[key] = current
+  }
+}
+
+// ─── Collection-error guard (#1286) ──────────────────────────────────────────
+if (collectionErrors.length > 0) {
+  for (const e of collectionErrors) {
+    process.stderr.write(`[arbiter] collection FAILURE for ${e.metric}: ${e.reason}\n`)
+  }
+  process.stderr.write(
+    '[arbiter] refusing to write baseline with failed collectors (fail-closed)\n',
+  )
+  process.exit(1)
+}
+
+// ─── Key-drop guard (#1286) ──────────────────────────────────────────────────
+// A recapture (any mode) must never silently delete a metric the prior
+// baseline tracked — e.g. a jscpd hiccup would otherwise remove
+// duplicationPercentage and permanently disable the duplication ratchet.
+if (existsSync(BASELINE_FILE)) {
+  try {
+    const prior = JSON.parse(readFileSync(BASELINE_FILE, 'utf-8'))
+    assertKeyParity(prior.metrics ?? {}, baseline.metrics)
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      throw new Error(`Malformed baseline at ${BASELINE_FILE}: ${err.message}`)
+    }
+    throw err
+  }
+}
+
+// ─── Write baseline ───────────────────────────────────────────────────────────
+writeFileSync(BASELINE_FILE, JSON.stringify(baseline, null, 2) + '\n', 'utf-8')
+process.stdout.write(`[arbiter] Debt baseline captured → ${BASELINE_FILE}
+`)
+process.stdout.write(String(JSON.stringify(baseline.metrics, null, 2)) + '\n')

package/dist/templates/scripts/check-acceptance.mjs.ejs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// check-acceptance.mjs — INV-138 acceptance-criteria anchor gate.
+//
+// "Green" certifies mechanics; this gate anchors INTENT. During implementation phases
+// the active task's plan MUST freeze the issue's acceptance criteria (explicit AC-N ids)
+// plus non-goals; at verification/close the reviewer-written ac-fit artifact
+// (.arbiter/evidence/ac-fit/<task>.json) MUST exist with every criterion PASS and a
+// cited evidence line — the mechanical form of "unproven criterion = REJECT".
+//
+// Flag-gated (inert by default for targets): env ARBITER_ACCEPTANCE_ANCHOR=1/0 overrides
+// arbiter.json features.acceptanceAnchor. Vacuous exit 0 with no active task, so main,
+// CI on merged trees, and fresh clones stay green.
+//
+// Usage:
+//   node scripts/check-acceptance.mjs                 # gate mode (active task state)
+//   node scripts/check-acceptance.mjs --plan <path>   # direct plan validation (wave integrate)
+//     [--ac-fit <path>]                               # validate a specific ac-fit artifact
+//
+// Exit codes (INV-53): 0 PASS/SKIP · 1 FAIL (anchor or fit missing/invalid) · 2 ERROR
+//
+// CATALOG: enforces the acceptance-criteria anchor (INV-138) — implementation-phase plans must freeze explicit AC-N criteria + non-goals, and verification/close requires an all-PASS per-criterion ac-fit evidence artifact.
+// CATALOG: rejected fold-in into check-phase-doc-consistency.mjs because that gate validates the SHAPE of .claude/.task/status.json (single-doc split-brain), while this one validates the CONTENT CONTRACT between the anchored plan, the issue's acceptance criteria, and reviewer fit evidence — a different SSOT axis with a feature-flag lifecycle.
+// CATALOG: rejected fold-in into check-evidence-bundle.mjs because evidence bundles are per-task artifact BUNDLES under .evidence/ with their own JSON schema file, whereas ac-fit is a single per-criterion verdict artifact coupled to plan parsing (scripts/lib/acceptance-criteria.mjs) that bundle validation knows nothing about.
+import { existsSync, lstatSync } from 'node:fs'
+import { join } from 'node:path'
+import { parsePlanAnchor, validateAcFit } from './lib/acceptance-criteria.mjs'
+import { isMainModule, readRegularFileSync } from './lib/run-helpers.mjs'
+
+const PRE_PHASES = new Set(['preflight', 'plan', 'red-team-review', 'red-team-rework', 'complete'])
+const IMPL_PHASES = new Set(['red', 'green', 'refactor'])
+const LATE_PHASES = new Set(['verification', 'close'])
+
+export function flagEnabled(root, env = process.env) {
+  const override = env.ARBITER_ACCEPTANCE_ANCHOR
+  if (override === '1' || override === 'true') return true
+  if (override === '0' || override === 'false') return false
+  try {
+    const cfg = JSON.parse(readRegularFileSync(join(root, 'arbiter.json'), 'utf-8'))
+    return cfg?.features?.acceptanceAnchor === true
+    // FAIL-OPEN-INTENT: unreadable/absent arbiter.json means an ungoverned tree — the flag-gated feature stays inert by design (mirrors guard-done-evidence.mjs).
+  } catch {
+    return false // inert when no readable arbiter.json (ungoverned tree)
+  }
+}
+
+export function sanitizeTaskId(taskId) {
+  return String(taskId ?? 'unknown').replace(/[^A-Za-z0-9._-]/g, '')
+}
+
+function fail(msg) {
+  process.stderr.write(`FAIL check-acceptance: ${msg}\n`)
+}
+
+/** Validate one plan body's anchor; returns { ok, criteriaIds, errors }. */
+export function checkPlanAnchor(planBody) {
+  const anchor = parsePlanAnchor(planBody)
+  const errors = []
+  if (anchor === null) {
+    errors.push(
+      'plan lacks the frozen anchor: add "## Acceptance Criteria" (verbatim from the issue, explicit AC-N ids) and "## Non-Goals"',
+    )
+    return { ok: false, criteriaIds: [], errors }
+  }
+  if (anchor.criteria.length === 0) {
+    errors.push('plan "## Acceptance Criteria" has no `- [ ] AC-N: …` checkbox')
+  } else if (anchor.criteria.some((c) => !c.explicit)) {
+    errors.push('plan acceptance criteria need explicit stable `AC-N:` ids')
+  } else {
+    // Duplicate ids collapse distinct criteria into one fit verdict (fail-open) —
+    // wave plans must namespace per issue: AC-<issue>.<n> (e.g. AC-123.1).
+    const ids = anchor.criteria.map((c) => c.id)
+    const dupes = [...new Set(ids.filter((id, i) => ids.indexOf(id) !== i))]
+    if (dupes.length > 0)
+      errors.push(
+        `duplicate criterion id(s) in the anchor: ${dupes.join(', ')} — namespace wave criteria as AC-<issue>.<n>`,
+      )
+  }
+  if (anchor.nonGoals.length === 0) errors.push('plan lacks a non-empty "## Non-Goals" section')
+  return {
+    ok: errors.length === 0,
+    criteriaIds: anchor.criteria.map((c) => c.id),
+    errors,
+  }
+}
+
+function readPlan(root, planRef) {
+  const withoutFragment = planRef.split('#')[0]
+  const abs = withoutFragment.startsWith('/') ? withoutFragment : join(root, withoutFragment)
+  if (!existsSync(abs)) return { error: `anchored plan file not found: ${withoutFragment}` }
+  try {
+    return { body: readRegularFileSync(abs, 'utf-8') }
+    // FAIL-OPEN-INTENT: the error object is returned and every caller surfaces it via fail() + exit 2 — fail-closed at the call site, not here.
+  } catch (err) {
+    return {
+      error: `anchored plan unreadable: ${err instanceof Error ? err.message : String(err)}`,
+    }
+  }
+}
+
+// ── direct --plan mode (wave integrate: no per-task status.json in the main tree) ──
+function runPlanMode(root, args, planIdx) {
+  const planArg = args[planIdx + 1]
+  if (!planArg) {
+    fail('--plan requires a path')
+    return 2
+  }
+  const plan = readPlan(root, planArg)
+  if (plan.error) {
+    fail(plan.error)
+    return 2
+  }
+  const result = checkPlanAnchor(plan.body)
+  for (const e of result.errors) fail(e)
+  if (!result.ok) return 1
+  const fitExit = checkExplicitFitArg(root, args, result.criteriaIds)
+  if (fitExit !== 0) return fitExit
+  console.log('OK check-acceptance (--plan mode)')
+  return 0
+}
+
+// --ac-fit <path>: validate a named artifact against the plan's criteria (all-PASS).
+function checkExplicitFitArg(root, args, criteriaIds) {
+  const fitIdx = args.indexOf('--ac-fit')
+  if (fitIdx === -1) return 0
+  const fitArg = args[fitIdx + 1]
+  const fitAbs = fitArg && (fitArg.startsWith('/') ? fitArg : join(root, fitArg))
+  if (!fitAbs || !existsSync(fitAbs)) {
+    fail(`--ac-fit artifact not found: ${fitArg}`)
+    return 2
+  }
+  const errors = validateFitFile(fitAbs, criteriaIds, true)
+  if (errors.length > 0) {
+    for (const e of errors) fail(e)
+    return 1
+  }
+  return 0
+}
+
+// Read record-shaped state from status.json; return { exit } when the gate should
+// stop early (vacuous SKIP or fail-closed ERROR).
+function loadTaskState(root) {
+  const statusPath = join(root, '.claude', '.task', 'status.json')
+  try {
+    lstatSync(statusPath)
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err
+    console.log('SKIP check-acceptance: no active task')
+    return { exit: 0 }
+  }
+  let state
+  try {
+    state = JSON.parse(readRegularFileSync(statusPath, 'utf-8'))
+    if (state === null || typeof state !== 'object' || Array.isArray(state)) {
+      throw new Error('task state must be an object')
+    }
+    // FAIL-OPEN-INTENT: malformed state is surfaced via fail() + exit 2 in this catch — the audit heuristic cannot see the returned {exit:2}.
+  } catch {
+    fail(
+      'malformed .claude/.task/status.json — fix or reset it (rm -rf .claude/.task). ' +
+        'Escape hatch: ARBITER_ACCEPTANCE_ANCHOR=0',
+    )
+    return { exit: 2 }
+  }
+  return { state }
+}
+
+function resolveTaskPhase(root) {
+  const loaded = loadTaskState(root)
+  if (loaded.exit !== undefined) return loaded
+  const { state } = loaded
+  // Mirror task-state.ts normalizePhase: absent/empty phase is a legal fresh state
+  // (preflight), 'implementation' is the legacy alias for red.
+  let phase = typeof state.phase === 'string' && state.phase !== '' ? state.phase : 'preflight'
+  if (phase === 'implementation') phase = 'red'
+  if (PRE_PHASES.has(phase)) {
+    console.log(`SKIP check-acceptance: phase ${phase} precedes the anchor contract`)
+    return { exit: 0 }
+  }
+  if (!IMPL_PHASES.has(phase) && !LATE_PHASES.has(phase)) {
+    fail(
+      `unrecognized task phase "${phase}" — reset stale state (rm -rf .claude/.task) or fix status.json. ` +
+        'Escape hatch: ARBITER_ACCEPTANCE_ANCHOR=0',
+    )
+    return { exit: 2 }
+  }
+  return { state, phase }
+}
+
+// Resolve the anchored plan for gate mode; { exit } on fail-closed ERROR / anchor FAIL.
+function resolveGatePlan(root, state, phase) {
+  const planField = state === null || typeof state !== 'object' ? undefined : state.plan
+  const planRef = typeof planField === 'string' && planField !== 'unknown' ? planField : null
+  if (!planRef) {
+    fail(
+      `phase ${phase} requires an anchored plan (arbiter task init --plan <path>). ` +
+        'Escape hatch: ARBITER_ACCEPTANCE_ANCHOR=0',
+    )
+    return { exit: 2 }
+  }
+  const plan = readPlan(root, planRef)
+  if (plan.error) {
+    fail(
+      `${plan.error} — reset stale state (rm -rf .claude/.task) or restore the plan. Escape hatch: ARBITER_ACCEPTANCE_ANCHOR=0`,
+    )
+    return { exit: 2 }
+  }
+  const result = checkPlanAnchor(plan.body)
+  if (!result.ok) {
+    for (const e of result.errors) fail(e)
+    return { exit: 1 }
+  }
+  return { planRef, criteriaIds: result.criteriaIds }
+}
+
+// Per-task ac-fit contract: validate when present; REQUIRED (all-PASS) at late phases,
+// except for wave workers — a task anchored to `wave-N.md#group` never produces a
+// per-worker ac-fit; the wave's fit enforcement runs at integrate time
+// (`--plan … --ac-fit wave-N.json` in the main tree, see wave-drain Phase 4).
+function checkTaskFit(root, state, phase, planRef, criteriaIds) {
+  const fitPath = join(
+    root,
+    '.arbiter',
+    'evidence',
+    'ac-fit',
+    `${sanitizeTaskId(state.taskId)}.json`,
+  )
+  const isWaveWorker = planRef.includes('#')
+  const late = LATE_PHASES.has(phase)
+  if (existsSync(fitPath)) {
+    const errors = validateFitFile(fitPath, criteriaIds, late, state.taskId)
+    if (errors.length > 0) {
+      for (const e of errors) fail(e)
+      return 1
+    }
+    return 0
+  }
+  if (late && !isWaveWorker) {
+    fail(
+      `phase ${phase} requires the ac-fit evidence artifact at ${fitPath} ` +
+        '(reviewer: per-criterion verdicts with cited diff/test lines — see /ship Adversarial Verifier; ' +
+        `note the sanitized filename: taskId "#42" → 42.json)`,
+    )
+    return 1
+  }
+  return 0
+}
+
+// ── gate mode: driven by the active task state ──
+function runGateMode(root) {
+  const resolved = resolveTaskPhase(root)
+  if (resolved.exit !== undefined) return resolved.exit
+  const { state, phase } = resolved
+
+  const planResolved = resolveGatePlan(root, state, phase)
+  if (planResolved.exit !== undefined) return planResolved.exit
+  const { planRef, criteriaIds } = planResolved
+
+  const fitExit = checkTaskFit(root, state, phase, planRef, criteriaIds)
+  if (fitExit !== 0) return fitExit
+
+  console.log(`OK check-acceptance (phase ${phase}, ${criteriaIds.length} criteria)`)
+  return 0
+}
+
+function main() {
+  const root = process.cwd()
+  const args = process.argv.slice(2)
+
+  if (!flagEnabled(root)) {
+    console.log('SKIP check-acceptance: features.acceptanceAnchor is off')
+    return 0
+  }
+
+  const planIdx = args.indexOf('--plan')
+  if (planIdx !== -1) return runPlanMode(root, args, planIdx)
+  return runGateMode(root)
+}
+
+function validateFitFile(absPath, criteriaIds, requireAllPass, expectedTaskId) {
+  let json
+  try {
+    json = JSON.parse(readRegularFileSync(absPath, 'utf-8'))
+    // FAIL-OPEN-INTENT: the parse error is surfaced as a returned error string; both callers print it and exit 1 — fail-closed at the call site.
+  } catch {
+    return [`ac-fit artifact is not valid JSON: ${absPath}`]
+  }
+  return validateAcFit(json, criteriaIds, { requireAllPass, expectedTaskId })
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    process.exit(main())
+  } catch (err) {
+    console.error(`ERROR check-acceptance: ${err instanceof Error ? err.message : String(err)}`)
+    process.exit(2)
+  }
+}