@getarbiter/cli 0.5.0

package/dist/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+import{createRequire}from"node:module";import{Command}from"commander";import{runInit}from"./commands/init.js";import{resolvePresetOption}from"./wizard/presets.js";import{runUpdate}from"./commands/update.js";import{runDiff}from"./commands/diff.js";import{runObsidian}from"./commands/obsidian.js";import{runConfigure}from"./commands/configure.js";import{runSettings}from"./commands/settings.js";import{runMethodStatus}from"./commands/method.js";import{runWorktreeOpen,runWorktreeClose,runWorktreeList,runWorktreeRelink}from"./commands/worktree.js";import{runWorktreePrune}from"./commands/worktree-prune.js";import{runGateExec}from"./commands/gate-exec.js";import{runVerify,runVerifyEvidence}from"./commands/verify.js";import{formatProvenance}from"./evidence/provenance.js";import{runGoldAudit}from"./commands/gold-audit.js";import{runDocSet}from"./commands/doc-set.js";import{runDocSetPlanApply}from"./generators/doc-set.js";import{runVerifyPlan}from"./commands/verify-plan.js";import{loadConfig}from"./utils/config.js";import{loadPlugin}from"./utils/plugin-loader.js";import{runPluginAdd,runPluginList}from"./commands/plugin.js";import{runDoctorRepairState,runDoctorHealth,runDoctorRecoverLock,runDoctorClean,runDoctorProveGates,runDoctorToolPins,runDoctorFailOpenCensus}from"./commands/doctor.js";import{jsonOutput}from"./utils/json-output.js";import{runUpgradeLevel}from"./commands/upgrade-level.js";import{runTaskAdvance,runTaskRecover,runTaskResume,runTaskInit,runTaskGet,HandoffRequiredError}from"./commands/task.js";import{runTaskShip,buildShipStepLines,shipStepFor}from"./commands/task-ship.js";import{runCrossModelReview,runShipCrossModelReview}from"./commands/cross-model-review.js";import{buildShipOverrides,resolveShipProfile}from"./commands/ship-profile.js";import{detectExternalModel}from"./detectors/external-model.js";import{runTaskRecordRed}from"./commands/task-record-red.js";import{runTaskRecordTechDebt}from"./commands/task-record-tech-debt.js";import{runTaskNote}from"./commands/task-note.js";import{runTaskMark}from"./commands/task-mark.js";import{isTddPhase,readUnifiedState}from"./commands/task-state.js";import{runVerifyTdd}from"./commands/verify-tdd.js";import{normTier}from"./commands/ship-tier.js";import{splitTrainIds}from"./commands/ship-train.js";import{runGraphBuild,runVerifyGraph}from"./commands/graph.js";import{runReviewDiff,renderMarkdown}from"./commands/review-diff.js";import{confirmChannelDowngrade}from"./utils/confirm-downgrade.js";import{appendEvidenceLine,evidenceLogTarget}from"./utils/evidence-log.js";import{getBoolFlag}from"./config/env-registry.js";import{AUTH_PROVIDERS,OBSERVABILITY_PROVIDERS,DEPLOY_TARGETS,isDeployTarget}from"./config/schema.js";import{runCli}from"./utils/run-cli.js";import{ArbiterError,UserFacingError,FatalError,ConfigError,RecoverableError}from"./utils/errors.js";import{SnapshotChecksumError}from"./state/envelope.js";import{registerCleanupHandlers}from"./utils/fs.js";import{runExplain}from"./commands/explain.js";import{getRunId,formatRunIdFooter}from"./utils/run-id.js";import{parseExperimentalArgv}from"./experimental/index.js";import{applyDeprecatedFlagFilter}from"./internal/deprecate.js";import{CLI_DEPRECATED_FLAGS}from"./internal/cli-deprecation-registry.js";import{warnExperimental}from"./internal/experimental-warn.js";import{setRootLogger,getLogger}from"./utils/logger.js";import{resolveFromProcess}from"./utils/logger-config.js";import{startReplay,rotateReplayLogs}from"./utils/replay.js";import{startProfiler}from"./utils/profiler.js";registerCleanupHandlers(),getRunId();function printCliError(msg){process.stderr.write(`  Error: ${msg}${formatRunIdFooter()}
+`)}function refuseUnsupportedArc42Flags(opts){opts.arc42&&(opts.manifest===void 0&&opts.docProfile===void 0||(process.stderr.write(`arbiter doc-set: --manifest/--doc-profile are not supported with --arc42 \u2014 the arc42 engine reads standards/gold-doc-set.yml directly. Re-run without them.
+`),process.exit(2)))}function printDocSetPlanApplyReport(result,applied){const mode=applied?"apply":"plan",tier=result.tierColumn??"n/a (no manifest \u2014 SKIP)";process.stdout.write(`doc-set skeletons [tier: ${tier}] (${mode}):
+`);for(const s of result.scaffolded){const verb=s.action==="created"?applied?"+ created":"+ would-scaffold":s.action==="replaced"||s.action==="backed-up-and-replaced"?applied?"~ replaced (banner upgrade)":"~ would-upgrade (banner)":". skipped (withheld \u2014 hand-edited)";process.stdout.write(`    ${verb}  ${s.path}  [${s.template}]
+`)}for(const p of result.unbound)process.stdout.write(`    ? unbound (no skeleton bound \u2014 engine --generate banner only): ${p}
+`);applied&&result.scaffolded.length===0&&result.unbound.length>0&&process.stdout.write("    Remedy: run `node scripts/check-doc-set.mjs --generate` to create banner stubs for unbound rows.\n"),result.scaffolded.length===0&&result.unbound.length===0&&process.stdout.write(`    (nothing to scaffold \u2014 all applicable rows present)
+`)}const _rawArgv=process.argv.slice(2),_noEvidenceIdx=_rawArgv.indexOf("--no-evidence"),_noEvidence=_noEvidenceIdx!==-1||getBoolFlag("ARBITER_NO_EVIDENCE");_noEvidenceIdx!==-1&&process.argv.splice(2+_noEvidenceIdx,1);const _verboseIdx=process.argv.indexOf("--verbose"),_verbose=_verboseIdx!==-1;_verbose&&process.argv.splice(_verboseIdx,1);try{const{remaining,flags}=parseExperimentalArgv(process.argv);if(process.argv.length=0,process.argv.push(...remaining),Object.keys(flags).length>0){process.env.ARBITER_EXPERIMENTAL=JSON.stringify(flags);for(const name of Object.keys(flags))warnExperimental(name)}}catch(err){process.stderr.write(`arbiter: ${err instanceof Error?err.message:String(err)}
+`),process.exit(1)}{const result=applyDeprecatedFlagFilter(process.argv,CLI_DEPRECATED_FLAGS);result.exitCode!==void 0&&(process.stderr.write(`${result.errorMessage??"Removed flag used."}
+`),process.exit(result.exitCode)),process.argv.length=0,process.argv.push(...result.remaining)}function consumeFlag(name){const idx=process.argv.indexOf(name);return idx===-1?!1:(process.argv.splice(idx,1),!0)}function consumeFlagValue(name){const idx=process.argv.indexOf(name);if(idx===-1){const eqMatch=process.argv.find(a=>a.startsWith(`${name}=`));return eqMatch!==void 0?(process.argv.splice(process.argv.indexOf(eqMatch),1),eqMatch.slice(name.length+1)):void 0}const value=process.argv[idx+1];return process.argv.splice(idx,2),value}const _debugFlag=consumeFlag("--debug"),_profileFlag=consumeFlag("--profile"),_noReplayFlag=consumeFlag("--no-replay"),_logLevelFlag=consumeFlagValue("--log-level"),_logFormatFlag=consumeFlagValue("--log-format"),_channelFlag=consumeFlagValue("--channel"),_jsonRequested=process.argv.includes("--json");_channelFlag!==void 0&&!["latest","beta","canary"].includes(_channelFlag)&&(process.stderr.write(`[arbiter] error: --channel "${_channelFlag}" is not a valid channel.
+  Valid values: latest, beta, canary
+`),process.exit(1));const _resolvedLogger=resolveFromProcess([..._logLevelFlag!==void 0?["--log-level",_logLevelFlag]:[],..._logFormatFlag!==void 0?["--log-format",_logFormatFlag]:[]],process.env),_effectiveLevel=_debugFlag?"debug":_resolvedLogger.level,_runId=getRunId();setRootLogger({level:_effectiveLevel,format:_resolvedLogger.format,runId:_runId});let _replayHandle=null;if(!_noReplayFlag)try{rotateReplayLogs({capN:10}),_replayHandle=startReplay({runId:_runId,argv:process.argv.slice(1),env:process.env,cwd:process.cwd()})}catch(err){process.stderr.write(`[warn] replay capture failed: ${String(err)}
+`)}let _profilerHandle=null;async function _startProfileIfRequested(){if(_profileFlag)try{_profilerHandle=await startProfiler({runId:_runId})}catch(err){getLogger().warn("profiler.start_failed",void 0,String(err))}}function resolveHeadSha(){try{return runCli("git",["rev-parse","--short","HEAD"]).stdout.trim()}catch{return"unknown"}}const _headSha=_noEvidence?"":resolveHeadSha(),_startMs=Date.now();function parseCmdArgs(){const tokens=process.argv.slice(2);if(tokens.length===0)return{cmd:"",args:[]};const nested=new Set(["worktree","wt","task","plugin","work","kit"]),first=tokens[0]??"";if(nested.has(first)&&tokens.length>=2){const sub=tokens[1]??"";if(!sub.startsWith("-"))return{cmd:`${first} ${sub}`,args:tokens.slice(2)}}return{cmd:first,args:tokens.slice(1)}}function validateInitFlags(opts){const VALID_ARCHETYPES=["backend-web-db","cli","library","data-pipeline","frontend-spa","embedded"];if(opts.archetype!==void 0&&!VALID_ARCHETYPES.includes(opts.archetype))throw ArbiterError.fromKey("E_INVALID_ARCHETYPE","errors.E_INVALID_ARCHETYPE",{field:"archetype",value:opts.archetype,valid:VALID_ARCHETYPES.join(", ")},{hint:"Run `arbiter init --help` for the list of valid archetypes."});if(opts.authProvider!==void 0&&!AUTH_PROVIDERS.has(opts.authProvider))throw ArbiterError.fromKey("E_INVALID_ARCHETYPE","errors.E_INVALID_ARCHETYPE",{field:"auth-provider",value:opts.authProvider,valid:[...AUTH_PROVIDERS].join(", ")},{hint:"Run `arbiter init --help` for the list of valid auth providers."});if(opts.observabilityProvider!==void 0&&!OBSERVABILITY_PROVIDERS.has(opts.observabilityProvider))throw ArbiterError.fromKey("E_INVALID_ARCHETYPE","errors.E_INVALID_ARCHETYPE",{field:"observability-provider",value:opts.observabilityProvider,valid:[...OBSERVABILITY_PROVIDERS].join(", ")},{hint:"Run `arbiter init --help` for the list of valid observability providers."});if(opts.deployTarget!==void 0&&!isDeployTarget(opts.deployTarget))throw ArbiterError.fromKey("E_INVALID_ARCHETYPE","errors.E_INVALID_ARCHETYPE",{field:"deploy-target",value:opts.deployTarget,valid:[...DEPLOY_TARGETS].join(", ")},{hint:"Run `arbiter init --help` for the list of valid deploy targets."})}const _parsedCmd=parseCmdArgs();let _evidenceLogged=!1;process.on("exit",code=>{if(_replayHandle!==null)try{_replayHandle.close(code)}catch{}if(_evidenceLogged||_noEvidence)return;_evidenceLogged=!0;const _evidenceDir=evidenceLogTarget(process.cwd(),_parsedCmd.cmd);if(_evidenceDir!==null)try{appendEvidenceLine({ts:new Date().toISOString(),cmd:_parsedCmd.cmd,args:_parsedCmd.args,exit:code,durationMs:Date.now()-_startMs,headSha:_headSha},{dir:_evidenceDir})}catch{process.stderr.write(`[arbiter] warning: evidence log write failed on exit \u2014 log entry lost
+`)}});const program=new Command;function readPackageVersion(){try{return createRequire(import.meta.url)("../package.json").version}catch{return"unknown"}}const packageVersion=readPackageVersion();program.name("arbiter").description("AI development governance framework").version(packageVersion),program.helpCommand(!1),program.addHelpText("after","\nRun `arbiter help --all` for experimental commands.");function externalModelAccessForShip(root,overrides){const config=resolveShipProfile(root,{...Object.keys(overrides).length>0?{overrides}:{}}).crossModelReview;if(!(config===void 0||!config.enabled||!config.diffEgressConsent))return detectExternalModel("codex")}function runConfiguredShipReview(root,result,tier,access){const config=result.profile.crossModelReview;if(result.advanced||result.phase!=="refactor"||!config?.enabled)return null;const taskId=readUnifiedState(root)?.taskId;if(taskId===void 0)throw new Error("crossModelReview is enabled but the active ship task id is missing");return runShipCrossModelReview({dir:root,taskId,tier:result.tier??normTier(tier),phase:result.phase,vertical:result.step.verticals.includes("security")?"security":"bugs",cfg:config,collaborationMode:result.profile.collaborationMode,...access!==void 0?{access}:{}})}function shipOutputAfterConfiguredReview(root,result,tier,access){return runConfiguredShipReview(root,result,tier,access)?.status==="degraded"?{...result,step:shipStepFor(result.phase,result.tier,result.profile)}:result}program.option("--log-level <level>","Log level: error|warn|info|debug|trace (default: info)").option("--log-format <format>","Log format: text|json (default: text)").option("--debug","Enable debug-level logging (implies --log-level=debug)").option("--no-replay","Disable replay log capture for this invocation").option("--profile","Capture a V8 CPU profile to ~/.arbiter/profiles/<runId>.cpuprofile").option("--channel <name>","Channel for this invocation: latest|beta|canary \u2014 gates downgrade warnings and shown in `doctor health` (default: arbiter.json channel or latest)"),program.command("note").description("Capture an out-of-scope finding to the per-agent JSONL spool (#1401)").argument("[note]","Finding text (or use --note)").option("--note <text>","Finding text (alternative to the positional argument)").option("--kind <kind>","Finding class: dup|smell|risk|debt|note (default: note)").option("--severity <sev>","Severity band: low|med|high|info (default: info)").option("--file <path>","Repo-relative file the finding concerns").option("--line <n>","Line number the finding was seen at (excluded from the fingerprint)").option("--dir <path>","Project root (default: cwd)").action((positional,opts)=>{const text=(positional??opts.note??"").trim(),logger=getLogger();if(text.length===0){process.stderr.write(`arbiter note: a finding text is required (positional or --note)
+`),process.exitCode=1;return}const noteOpts={note:text};opts.kind!==void 0&&(noteOpts.kind=opts.kind),opts.severity!==void 0&&(noteOpts.severity=opts.severity),opts.file!==void 0&&(noteOpts.file=opts.file),opts.dir!==void 0&&(noteOpts.dir=opts.dir);const parsedLine=opts.line!==void 0?Number.parseInt(opts.line,10):NaN;Number.isInteger(parsedLine)&&(noteOpts.line=parsedLine);const result=runTaskNote(noteOpts);result.ok?(logger.info("note.captured",{spool:result.spoolPath,fingerprint:result.fingerprint}),process.stdout.write(`noted \u2192 ${result.spoolPath}
+`)):(process.stderr.write(`arbiter note: ${result.reason}
+`),process.exitCode=1)}),program.command("init").description("Initialize AI governance in a project").option("-y, --yes","Skip wizard \u2014 use auto-detected defaults",!1).option("--tools <tools>","Comma-separated list of AI tools (claude,codex)").option("--level <level>","Governance level: L1, L2, L3, or L4","L2").option("--tier <tier>","Progressive-adoption tier: bootstrap (gentlest Day-1: L1 + brownfield) | L1 | L2 | L3 | L4. Overrides --level.").option("--language <lang>","Override detected language (typescript|java|kotlin|rust|python|go|multi)").option("--archetype <archetype>","Override detected archetype (backend-web-db|cli|library|data-pipeline|frontend-spa|embedded)").option("--dir <dir>","Target directory (default: current directory)").option("--dry-run","Preview what would be generated without writing files",!1).option("--brownfield","Auto-capture debt baseline after generation (locks current state as day-0 baseline)",!1).option("--no-verify","Skip toolchain compatibility probes after generation").option("--accept-beta-tools","Allow generation of L3 features backed by beta-maturity tools (audit trail written to arbiter.json)",!1).option("--backend <backend>","Decomposition backend: github or markdown (overrides gh auth detection)").option("--json","Emit machine-readable JSON output (requires --yes)",!1).option("--quiet","Suppress informational banners (e.g. telemetry notice)",!1).option("--force","Override adverse git state check (detached HEAD, rebase, etc.)",!1).option("--preset <preset>","Apply a meta-preset: industrial-grade (governance + compliance + observability + auth bundle) | solo-homelab (compliance off, governance \u2264 L2, mutation off, no prod runbooks)").option("--auth-provider <provider>","Override auth provider (used with --preset or standalone)").option("--observability-provider <provider>","Override observability provider (used with --preset or standalone)").option("--deploy-target <target>","Deploy target: ghcr | azure-container-app | aws-ecs | gcp-cloud-run | none (non-interactive complement to the wizard)").option("--github","Activate GitHub API calls and set permitGitHub:true in stored config",!1).option("--solo","Set collaborationMode=trunk-solo (direct-merge, full local gate \u2261 CI, CI as verification mirror). Shorthand for ADR-051 trunk-solo mode.",!1).option("--recipe <path>","Path or https:// URL to a recipe JSON file for pre-configured init").option("--recipe-sha256 <hash>","Expected SHA-256 hex digest of the recipe file").action(async opts=>{validateInitFlags(opts);const backend=opts.backend==="github"||opts.backend==="markdown"?opts.backend:void 0,preset=resolvePresetOption(opts.preset);await runInit({yes:opts.yes,tools:opts.tools,level:opts.level,...opts.tier!==void 0?{tier:opts.tier}:{},dir:opts.dir,dryRun:opts.dryRun,brownfield:opts.brownfield,noVerify:!opts.verify,acceptBetaTools:opts.acceptBetaTools,github:opts.github,...opts.solo?{solo:!0}:{},...backend!==void 0?{backend}:{},json:opts.json,quiet:opts.quiet,force:opts.force,...preset!==void 0?{preset}:{},...opts.authProvider!==void 0?{authProvider:opts.authProvider}:{},...opts.observabilityProvider!==void 0?{observabilityProvider:opts.observabilityProvider}:{},...opts.recipe!==void 0?{recipe:opts.recipe}:{},...opts.recipeSha256!==void 0?{recipeSha256:opts.recipeSha256}:{},...opts.language!==void 0?{language:opts.language}:{},...opts.archetype!==void 0?{archetype:opts.archetype}:{},...opts.deployTarget!==void 0?{deployTarget:opts.deployTarget}:{}})}),program.command("update").description("Re-generate governance files using stored config (arbiter.json)").option("--dir <dir>","Target directory (default: current directory)").option("--github","Activate live GitHub API calls (opt-in; ARBITER_GITHUB=1 also activates)",!1).option("--json","Emit machine-readable JSON output",!1).option("--force","Override adverse git state check (detached HEAD, rebase, etc.)",!1).option("--adopt","Force-adopt ALL currently-withheld files (not just safety-class), recording a reversible local-override for each. Safety-class files adopt by default already.",!1).option("--no-adopt-safety","Opt OUT of the default-on safety-class adoption (.claude/hooks/*.mjs). Leaves a user-modified safety hook frozen even if the shipped template fixed it \u2014 dangerous.").option("--adopt-gate-spine","Opt IN to force-adopting the gate spine (scripts/check-all.mjs, scripts/lib/*.mjs) over a user-modified copy. DESTRUCTIVE: checks wired into that file by the project are replaced by the template render \u2014 preview with --adopt-plan first (#2119).",!1).option("--adopt-governance","Opt IN to force-adopting governance files (AGENTS.md, .claude/settings.json) over a user-modified copy. DESTRUCTIVE: the template render is not a superset of governed consumer content \u2014 preview with --adopt-plan first (#2141).",!1).option("--no-adopt-gate-spine","DEPRECATED (#2453, removed in 0.8.0): no-op \u2014 withholding a customized gate spine is already the default since #2119. See docs/DEPRECATIONS.md.").option("--no-adopt-governance","DEPRECATED (#2453, removed in 0.8.0): no-op \u2014 withholding a diverged governance file is already the default since #2141. See docs/DEPRECATIONS.md.",(_value,previous)=>previous).option("--adopt-plan","Two-phase preview: print what --adopt/the default safety adoption WOULD change (file list + line diff), without writing anything.",!1).option("--only <globs>","Restrict this run to the managed files matching these globs (comma-separated, repeatable), matched against manifest keys. Every other managed file is skipped and keeps its manifest entry. .arbiterignore wins on conflict (#2353).",(value,previous)=>[...previous,...value.split(",").map(g=>g.trim()).filter(g=>g.length>0)],[]).option("--refresh-derived","Force-refresh the codex-track derived file set (.agents/rules/*, .claude/hooks/* when codex-only, .codex/codex-adapter.mjs) even though these are skipIfExists by default. Combine with --adopt-plan to preview first. A file marked arbiter:preserve is never overwritten (#1983).",!1).action(async opts=>{if(_channelFlag!==void 0){const config=loadConfig(opts.dir??".");await confirmChannelDowngrade(_channelFlag,config?.channel)}await runUpdate({dir:opts.dir,github:opts.github,json:opts.json,force:opts.force,adopt:opts.adopt,noAdoptSafety:!opts.adoptSafety,adoptGateSpine:opts.adoptGateSpine,adoptGovernance:opts.adoptGovernance,adoptPlan:opts.adoptPlan,refreshDerived:opts.refreshDerived,only:opts.only})}),program.command("configure").description("Modify arbiter.json configuration (interactive on TTY, or use --set)").option("--dir <dir>","Target directory (default: current directory)").option("--set <path=value>","Set a config path to a value (repeatable)",(v,acc)=>[...acc,v],[]).option("--json","Emit machine-readable JSON output",!1).action(opts=>{(async()=>{if(opts.set.length===0&&!opts.json&&process.stdin.isTTY){const{runInteractiveConfigure}=await import("./commands/configure-interactive.js");return runInteractiveConfigure(opts.dir)}return runConfigure({dir:opts.dir,sets:opts.set,json:opts.json})})().catch(err=>{const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)})}),program.command("settings",{hidden:!0}).description("List every settable arbiter.json path with its current value (#1121)").option("--dir <dir>","Target directory (default: current directory)").option("--json","Emit machine-readable JSON output",!1).action(opts=>{try{runSettings({...opts.dir!==void 0?{dir:opts.dir}:{},json:opts.json})}catch(err){const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)}});const method=program.command("method",{hidden:!0}).description("Methodology lens: per-feature Config+Emit wiring status over `configure` (#2039)").option("--dir <dir>","Target directory (default: current directory)").option("--json","Emit machine-readable JSON output",!1).action(opts=>{(async()=>{if(!opts.json&&process.stdin.isTTY){const{runInteractiveMethod}=await import("./commands/method-interactive.js");return runInteractiveMethod(opts.dir)}runMethodStatus({...opts.dir!==void 0?{dir:opts.dir}:{},json:opts.json})})().catch(err=>{const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)})});method.command("status").description("Read-only per-feature methodology report (Config + Emit facets)").option("--dir <dir>","Target directory (default: current directory)").option("--json","Emit machine-readable JSON output",!1).action((_opts,cmd)=>{const merged=cmd.optsWithGlobals();try{runMethodStatus({...merged.dir!==void 0?{dir:merged.dir}:{},json:merged.json})}catch(err){const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)}}),program.command("diff").description("Show what arbiter update would change (dry run)").option("--dir <dir>","Target directory (default: current directory)").option("--json","Emit machine-readable JSON output",!1).option("--withheld","Show only template fixes withheld from user-modified files (#1344)",!1).option("--governance","Audit Iron Laws (AGENTS.md) and the permission deny list (.claude/settings.json) for staleness vs the current template; fail-closed (#2040)",!1).action(opts=>{runDiff({dir:opts.dir,json:opts.json,withheld:opts.withheld,governance:opts.governance})}),program.command("obsidian").description("Sync/validate the Obsidian vault via the repo-owned wiki scripts (#1979)").option("--repo <dir>","Target repo directory (default: current directory)").option("--vault-path <dir>","Vault directory relative to the repo root","wiki").option("--sync","Regenerate the vault then re-validate (fail-closed)",!1).option("--validate-only","Validate the existing vault without writing",!1).option("--write","Reserved for a future writer; v1 is read-only (ADR-001)",!1).option("--dry-run","Report only \u2014 writes nothing (default)",!1).option("--json","Emit machine-readable JSON output",!1).action(opts=>{const result=runObsidian({...opts.repo!==void 0?{dir:opts.repo}:{},vaultPath:opts.vaultPath,sync:opts.sync,validateOnly:opts.validateOnly,write:opts.write,dryRun:opts.dryRun,json:opts.json});opts.json?jsonOutput("obsidian",result.status,{...result}):result.reason?process.stdout.write(`obsidian: ${result.reason}
+`):process.stdout.write(`obsidian: ${result.mode} \u2014 ${result.status} (vault: ${result.vaultDir})
+`),process.exit(result.exitCode)});const plugin=program.command("plugin").description("Manage third-party arbiter plugins (arbiter.json `plugins[]`)");plugin.command("add <package>").description("Resolve, install, validate, and register a plugin (local path or npm package)").option("--dir <dir>","Target directory (default: current directory)").option("--no-install","Skip the package-manager install step (local paths never install)").option("--json","Emit machine-readable JSON output",!1).action((pkg,opts)=>{runPluginAdd({dir:opts.dir,pkg,install:opts.install,json:opts.json}).catch(err=>{const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)})}),plugin.command("list").description("List configured plugins with load status").option("--dir <dir>","Target directory (default: current directory)").option("--json","Emit machine-readable JSON output",!1).action(opts=>{runPluginList({dir:opts.dir,json:opts.json}).catch(err=>{const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)})});const worktree=program.command("worktree").alias("wt").description("Manage git worktrees for parallel task development");worktree.command("open <task-id> [slug]").description("Create a sibling worktree with a task branch and symlinked local files").option("--base <branch>","Base branch to branch from","main").option("--sibling [slug]","Place worktree at <repo>.worktrees/<slug> (sibling layout)").option("--with-build-links","Also materialize buildLinks from config",!1).option("--json","Emit machine-readable JSON output",!1).action((taskId,slug,opts)=>{runWorktreeOpen({taskId,...slug!==void 0?{slug}:{},base:opts.base,...opts.sibling!==void 0?{sibling:opts.sibling===!0?"":opts.sibling}:{},withBuildLinks:opts.withBuildLinks,json:opts.json}).catch(err=>{const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)})}),worktree.command("close <task-id>").description("Tear down a task worktree after its branch is merged").option("--force","Close even if branch is unmerged or hook fails",!1).option("--keep-branch","Do not delete the task branch after closing",!1).option("--no-fetch","Skip git fetch before the merge check",!1).option("--harvest","Copy modified/untracked files back to main repo before closing",!1).option("--harvest-all","Harvest all files and skip merge check (implies --force for cleanup)",!1).option("--json","Emit machine-readable JSON output",!1).action((taskId,opts)=>{runWorktreeClose({taskId,force:opts.force,keepBranch:opts.keepBranch,noFetch:!opts.fetch,harvest:opts.harvest,harvestAll:opts.harvestAll,json:opts.json})}),worktree.command("list").description("List open task worktrees").option("--json","Emit machine-readable JSON output",!1).action(opts=>{runWorktreeList({json:opts.json})}),worktree.command("relink <task-id>").description("Re-materialize configured links for an existing task worktree").option("--with-build-links","Also materialize buildLinks from config",!1).option("--json","Emit machine-readable JSON output",!1).action((taskId,opts)=>{try{runWorktreeRelink({taskId,withBuildLinks:opts.withBuildLinks,json:opts.json})}catch(err){const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)}}),worktree.command("prune").description("Reap zombie worktrees (#1873, ADR-103): clean trees that are merged or inactive beyond --stale hours. Dry-run by default; dirty trees are never touched (INV-96); inactive-unmerged candidates keep their branch.").option("--stale <hours>","Inactivity threshold in hours for unmerged worktrees",v=>{const n=parseInt(v,10);if(isNaN(n)||n<=0)throw new Error("--stale must be a positive integer (hours)");return n}).option("--execute","Close the candidates (default: dry-run report)",!1).option("--no-fetch","Skip git fetch before the merge check",!1).option("--json","Emit machine-readable JSON output",!1).action(opts=>{try{runWorktreePrune({...opts.stale!==void 0?{staleHours:opts.stale}:{},execute:opts.execute,noFetch:!opts.fetch,json:opts.json})}catch(err){const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)}}),program.command("gate-exec <cmd...>").description("Run a command under the per-repo gate mutex (#1873, ADR-103): every worktree of the same repo converges on ONE flock(1) lock, the wait is kernel-side (blocking), and flock closes the lock fd before the command and its descendants run. Usage: arbiter gate-exec [--key K] -- <cmd> [args...]. Exit code: passthrough of the command; 2 on gate-exec errors (e.g. flock missing \u2014 fail-closed).").option("--key <key>","Explicit mutex key (overrides per-repo derivation)").option("--dir <dir>","Target directory (default: current directory)").action(async(cmdArgs,opts)=>{try{const code=await runGateExec({cmdArgs,...opts.key!==void 0?{key:opts.key}:{},...opts.dir!==void 0?{dir:opts.dir}:{}});process.exit(code)}catch(err){const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(2)}});const review=program.command("review").description("Semantic diff between graph snapshots (#262)"),graph=program.command("graph",{hidden:!0}).description("Manage the provenance graph (#259)");graph.command("build").description("Build the provenance graph from invariants and write .arbiter/graph.json").option("--dir <dir>","Target directory (default: current directory)").option("--output <path>","Override output path (default: <dir>/.arbiter/graph.json)").option("--format <fmt>","Output format: json | dot | mermaid (default: json)","json").option("--json","Emit machine-readable JSON output",!1).action(opts=>{const buildOpts={};opts.dir!==void 0&&(buildOpts.dir=opts.dir),opts.output!==void 0&&(buildOpts.output=opts.output),buildOpts.format=opts.format;const result=runGraphBuild(buildOpts);opts.json?jsonOutput("graph build",result.status,{exitCode:result.exitCode,path:result.path,nodes:result.nodes,edges:result.edges},result.reason!==void 0?[result.reason]:void 0):result.status==="ok"?process.stdout.write(`graph build: wrote ${result.path} (${result.nodes} nodes, ${result.edges} edges)
+`):process.stderr.write(`graph build: FAIL \u2014 ${result.reason??"unknown error"}
+`),process.exit(result.exitCode)}),program.command("gold-audit [repo]").description("Deterministic gold-LEVEL band + missing-items report (#1414, wraps the engine)").option("--stack <stack>","Per-stack registry selector (standards/gold-registry.<stack>.yml)").option("--class <class>","Brownfield class for the level band: gold|light|medium|heavy").option("--check","No-regress gate: bootstrap missing baseline (exit 0), fail on regress",!1).option("--require-baseline","With --check, a missing baseline is a HARD FAIL (#1419)",!1).option("--json","Emit machine-readable JSON output",!1).option("--cockpit","Render the rich TTY-gated goldness console (#1475)",!1).option("--ascii","Force pure-ASCII cockpit output (no unicode glyphs/ANSI)",!1).action((repo,opts)=>{const cls=opts.class==="gold"||opts.class==="light"||opts.class==="medium"||opts.class==="heavy"?opts.class:void 0;opts.class!==void 0&&cls===void 0&&(printCliError(`invalid --class "${opts.class}". Valid: gold, light, medium, heavy.`),process.exit(1));const result=runGoldAudit({...repo!==void 0?{repo}:{},...opts.stack!==void 0?{stack:opts.stack}:{},...cls!==void 0?{class:cls}:{},check:opts.check,requireBaseline:opts.requireBaseline,json:opts.json,cockpit:opts.cockpit,ascii:opts.ascii});process.exit(result.exitCode)}),review.command("cross-model").description("Run the configured Codex review seat against a diff from stdin (#2357)").requiredOption("--task <id>","Task issue id, for example #2357").requiredOption("--prompt <text>","Review prompt; the code diff is read from stdin").option("--tier <tier>","Ship tier (XS|S|Standard; default: Standard)").option("--phase <phase>","Task phase (default: refactor)").option("--vertical <vertical>","Review vertical (default: bugs)").option("--dir <dir>","Target directory (default: current directory)").action(opts=>{const result=runCrossModelReview({taskId:opts.task,prompt:opts.prompt,...opts.tier!==void 0?{tier:opts.tier}:{},...opts.phase!==void 0?{phase:opts.phase}:{},...opts.vertical!==void 0?{vertical:opts.vertical}:{},...opts.dir!==void 0?{dir:opts.dir}:{}});process.stdout.write(`${JSON.stringify(result)}
+`)}),program.command("doc-set [repo]",{hidden:!0}).description("Deterministic gold doc-set presence audit (H1, gold-doc-capability: wraps scripts/check-doc-set.mjs). Required-set is tier-parameterized by collaborationMode (solo/small/enterprise) \u2014 see standards/gold-doc-set.yml `tiers{}`.").option("--strict","Exit 1 if any mandatory doc is missing (default: advisory, exit 0)",!1).option("--check","Run the default advisory presence audit (backward-compat alias for the no-flag default; emitted governed-repo runners pass it)",!1).option("--json","Emit the audit as JSON",!1).option("--generate","Scaffold stub files for missing mandatory+recommended .md docs",!1).option("--refresh-stubs","(with --generate) re-render a doc in place only if it is byte-equal to the stub template",!1).option("--manifest <path>","Manifest path override (default standards/gold-doc-set.yml)").option("--doc-profile <path>","Overlay profile path override (default standards/doc-profile)").option("--plan","T3: dry-run the skeleton generator \u2014 report would-scaffold/unbound, write nothing",!1).option("--apply","T3: scaffold real per-doc-type skeletons for missing bound rows (skipIfExists; never overwrites a hand-edited doc; upgrades a byte-equal banner stub)",!1).option("--freshness","T4: run the per-doc freshness audit (scripts/check-doc-freshness.mjs) instead of presence",!1).option("--arc42","INV-144: run the arc42 slot-completeness audit (scripts/check-arc42-slots.mjs) instead of presence \u2014 every slot the tier's arc42 skeleton provides must be present and filled",!1).option("--update-baseline","(with --arc42) re-record the hollow-slot ratchet; refused when a counter rose",!1).action((repo,opts)=>{if(refuseUnsupportedArc42Flags(opts),opts.plan||opts.apply){const result2=runDocSetPlanApply({...repo!==void 0?{repo}:{},apply:opts.apply,...opts.manifest!==void 0?{manifest:opts.manifest}:{},...opts.docProfile!==void 0?{profile:opts.docProfile}:{}});printDocSetPlanApplyReport(result2,opts.apply),process.exit(opts.apply&&result2.scaffolded.length===0&&result2.unbound.length>0?1:0)}const result=runDocSet({...repo!==void 0?{repo}:{},strict:opts.strict,json:opts.json,generate:opts.generate,refreshStubs:opts.refreshStubs,freshness:opts.freshness,arc42:opts.arc42,updateBaseline:opts.updateBaseline,...opts.manifest!==void 0?{manifest:opts.manifest}:{},...opts.docProfile!==void 0?{profile:opts.docProfile}:{}});process.exit(result.exitCode)});function printProvenanceLines(provenance){if(provenance!==void 0)for(const line of formatProvenance(provenance))process.stdout.write(`${line}
+`)}const verify=program.command("validate").alias("verify").description("Probe toolchain compatibility for the detected stack").option("--json","Emit JSON report",!1).option("--dir <dir>","Target directory (default: current directory)").action(opts=>{runVerify({json:opts.json,dir:opts.dir})});verify.command("evidence").description("Verify the .evidence/SUMMARY.json snapshot (SHA + freshness window).").option("--json","Emit machine-readable JSON output",!1).option("--dir <dir>","Target directory (default: current directory)").action((opts,cmd)=>{const json=!!cmd.optsWithGlobals().json,result=runVerifyEvidence({dir:opts.dir});if(json)jsonOutput("verify evidence",result.status,{exitCode:result.exitCode,...result.skipped!==void 0?{skipped:result.skipped}:{},...result.reason!==void 0?{reason:result.reason}:{},...result.provenance!==void 0?{provenance:result.provenance}:{}},result.status==="error"&&result.reason!==void 0?[result.reason]:void 0);else{const label=result.status==="ok"?"OK":result.status.toUpperCase(),tail=result.reason?` \u2014 ${result.reason}`:"";process.stdout.write(`verify evidence: ${label}${tail}
+`),printProvenanceLines(result.provenance)}process.exit(result.exitCode)}),verify.command("plan <file>").description("Validate a PLAN.json against invariant rules and write REVIEW.json (#253)").option("--dir <dir>","Project root (default: current directory)").option("--reviewer <name>","Reviewer name in REVIEW.json").option("--fail-on-warn","Treat WARN violations as REJECTED",!1).option("--json","Emit machine-readable JSON output",!1).action(async(file,opts,cmd)=>{const json=!!cmd.optsWithGlobals().json,{resolve}=await import("node:path"),dir=resolve(opts.dir??"."),stored=loadConfig(dir),pluginNames=stored!=null&&Array.isArray(stored.plugins)?stored.plugins:[],extraRules=[];for(const pkg of pluginNames)try{const plugin2=await loadPlugin(pkg,dir);Array.isArray(plugin2.verifyPlanRules)&&extraRules.push(...plugin2.verifyPlanRules)}catch(err){process.stderr.write(`[arbiter] verify plan: plugin "${pkg}" failed to load \u2014 its rules will not run: ${err instanceof Error?err.message:String(err)}
+`)}const result=runVerifyPlan({file,dir,...opts.reviewer!==void 0?{reviewer:opts.reviewer}:{},failOnWarn:opts.failOnWarn,json,extraRules});process.exit(result.exitCode)}),verify.command("graph").description("Verify the provenance graph (#259) \u2014 fails on orphan invariants (no enforces / no implements)").option("--dir <dir>","Target directory (default: current directory)").option("--input <path>","Override graph snapshot path (default: <dir>/.arbiter/graph.json)").option("--json","Emit machine-readable JSON output",!1).action((opts,cmd)=>{const commandOpts=cmd.optsWithGlobals(),json=!!commandOpts.json,verifyOpts={};commandOpts.dir!==void 0&&(verifyOpts.dir=commandOpts.dir),opts.input!==void 0&&(verifyOpts.input=opts.input);const result=runVerifyGraph(verifyOpts);if(json)jsonOutput("verify graph",result.status,{exitCode:result.exitCode,path:result.path,totalInv:result.totalInv,orphans:result.orphans},result.reason!==void 0?[result.reason]:void 0);else if(result.status==="ok")process.stdout.write(`verify graph: OK (${result.totalInv} invariant(s) checked, 0 orphan)
+`);else{process.stderr.write(`verify graph: FAIL \u2014 ${result.reason??"unknown error"}
+`);for(const orphan of result.orphans)process.stderr.write(`  orphan: ${orphan.id} \u2014 ${orphan.reason}
+`)}process.exit(result.exitCode)}),verify.command("tdd <task-id>").description("Verify TDD red-phase evidence for a task \u2014 replayable audit (#553)").option("--dir <dir>","Target directory / repo root (default: current directory)").option("--json","Emit machine-readable JSON output",!1).action((taskId,opts,cmd)=>{const json=!!cmd.optsWithGlobals().json,result=runVerifyTdd({taskId,json,...opts.dir!==void 0?{dir:opts.dir}:{}});json?jsonOutput("verify tdd",result.status==="PASS"?"ok":"error",{exitCode:result.exitCode,taskId:result.taskId,checks:result.checks??[]},result.reason!==void 0?[result.reason]:void 0):result.status==="PASS"?process.stdout.write(`verify tdd: PASS (${result.checks?.length??0} checks)
+`):result.status==="DEGRADED"?process.stderr.write(`verify tdd: DEGRADED \u2014 ${result.reason??"unknown"}
+`):process.stderr.write(`verify tdd: FAIL \u2014 ${result.reason??"unknown"}
+`),process.exit(result.exitCode)}),program.command("upgrade-level",{hidden:!0}).description("Upgrade governance level with a grace period for new gates").option("--target <level>","Target level (L2 or L3)").option("--extend","Extend an existing active grace period by --days (default: 30)",!1).option("--days <n>","Grace period length in days (default: 30)").option("--dir <dir>","Target directory (default: current directory)").option("--interactive","Guided level selection on a TTY (#1168)",!1).option("--json","Emit machine-readable JSON output",!1).action(opts=>{if(opts.interactive&&!opts.json&&process.stdin.isTTY){import("./commands/upgrade-level-interactive.js").then(({runInteractiveUpgradeLevel})=>runInteractiveUpgradeLevel({...opts.dir!==void 0?{dir:opts.dir}:{}})).catch(err=>{process.stderr.write(`  Error: ${err instanceof Error?err.message:String(err)}
+`),process.exit(1)});return}const upgradeOpts={extend:opts.extend,json:opts.json};if(opts.target&&(opts.target!=="L2"&&opts.target!=="L3"&&(printCliError(`invalid --target "${opts.target}". Valid values: L2, L3.`),getLogger().error("invalid_target",{value:opts.target??null}),process.exit(1)),upgradeOpts.target=opts.target),opts.days!==void 0){const parsedDays=Number.parseInt(opts.days,10);(!Number.isInteger(parsedDays)||parsedDays<1)&&(printCliError(`invalid --days "${opts.days}". Must be a positive integer (>= 1).`),getLogger().error("invalid_days",{value:opts.days}),process.exit(1)),upgradeOpts.days=parsedDays}opts.dir!==void 0&&(upgradeOpts.dir=opts.dir),runUpgradeLevel(upgradeOpts).catch(err=>{const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)})});function runDoctorHealthAction(_opts,cmd){const opts=cmd.optsWithGlobals();if(opts.proveGates){const result=runDoctorProveGates({json:opts.json});result.exitCode!==0&&process.exit(result.exitCode);return}if(opts.interactive&&!opts.json&&process.stdin.isTTY){import("./commands/doctor-interactive.js").then(({runInteractiveDoctor})=>runInteractiveDoctor({...opts.dir!==void 0?{dir:opts.dir}:{}})).catch(err=>{process.stderr.write(`  Error: ${err instanceof Error?err.message:String(err)}
+`),process.exit(1)});return}runDoctorHealth({...opts.dir!==void 0?{dir:opts.dir}:{},json:opts.json,repair:opts.repair,..._channelFlag!==void 0?{channelFlag:_channelFlag}:{}}).then(result=>{result.exitCode!==0&&process.exit(result.exitCode)}).catch(err=>{const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)})}const doctor=program.command("doctor").description("Diagnose and repair arbiter state").option("--dir <dir>","Target directory (default: current directory)").option("--json","Emit machine-readable JSON output",!1).option("--repair","Auto-release stale .arbiter/.lock files detected by the health check (#824)",!1).option("--interactive","Guided health check with one-key repair on a TTY (#1168)",!1).option("--prove-gates","Run negative proofs for every tier-1 conformance gate; report any gate that does not bite (#1817, A5)",!1).action(runDoctorHealthAction);doctor.command("health").description("Run arbiter health checks").option("--dir <dir>","Target directory (default: current directory)").option("--json","Emit machine-readable JSON output",!1).option("--repair","Auto-release stale .arbiter/.lock files detected by the health check (#824)",!1).option("--interactive","Guided health check with one-key repair on a TTY (#1168)",!1).option("--prove-gates","Run negative proofs for every tier-1 conformance gate; report any gate that does not bite (#1817, A5)",!1).action(runDoctorHealthAction),doctor.command("repair-state").description("Re-derive .arbiter-generated.json from arbiter.json (snapshot corruption recovery)").option("--dir <dir>","Target directory (default: current directory)").option("--json","Emit machine-readable JSON output",!1).action((_opts,cmd)=>{const opts=cmd.optsWithGlobals();runDoctorRepairState({...opts.dir!==void 0?{dir:opts.dir}:{},json:opts.json}).then(result=>{result.exitCode!==0&&process.exit(result.exitCode)}).catch(err=>{const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)})}),doctor.command("recover-lock").description("Force-release a stale .arbiter/.lock file left by a crashed process").option("--dir <dir>","Target directory (default: current directory)").option("--force","Release a live or unconfirmed lock deliberately",!1).option("--json","Emit machine-readable JSON output",!1).action((_opts,cmd)=>{const opts=cmd.optsWithGlobals();runDoctorRecoverLock({...opts.dir!==void 0?{dir:opts.dir}:{},force:opts.force,json:opts.json}).catch(err=>{const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)})}),doctor.command("clean").description("Remove arbiter backup files (*.arbiter-backup, .arbiter-generated.json.bak.*)").option("--dir <dir>","Target directory (default: current directory)").option("--dry-run","List files without deleting",!1).option("--json","Emit machine-readable JSON output",!1).action((_opts,cmd)=>{const opts=cmd.optsWithGlobals();try{runDoctorClean({...opts.dir!==void 0?{dir:opts.dir}:{},dryRun:opts.dryRun,json:opts.json})}catch(err){const msg=err instanceof Error?err.message:String(err);process.stderr.write(`  Error: ${msg}
+`),process.exit(1)}}),doctor.command("tool-pins").description("Compare local tool versions against CI workflow pins (see `check-ci-tool-parity.mjs` for CI-internal manifest parity \u2014 a different, non-overlapping check)").option("--dir <dir>","Target directory (default: current directory)").option("--json","Emit machine-readable JSON output",!1).action((_opts,cmd)=>{const opts=cmd.optsWithGlobals(),result=runDoctorToolPins({...opts.dir!==void 0?{dir:opts.dir}:{},json:opts.json});result.exitCode!==0&&process.exit(result.exitCode)}),doctor.command("fail-open-census").description("Census `command -v X || <fail-open>` and positive `if command -v X; then ... fi` gate-script presence-gates (see `check-fail-closed-audit.mjs` for a different pattern class \u2014 `|| true` / swallowed catch \u2014 self-scoped to arbiter's own repo)").option("--dir <dir>","Target directory (default: current directory)").option("--json","Emit machine-readable JSON output",!1).option("--allowlist <path>","Override allowlist path (default: .arbiter/fail-open-allowlist.json)").action((_opts,cmd)=>{const opts=cmd.optsWithGlobals(),result=runDoctorFailOpenCensus({...opts.dir!==void 0?{dir:opts.dir}:{},json:opts.json,...opts.allowlist!==void 0?{allowlistPath:opts.allowlist}:{}});result.exitCode!==0&&process.exit(result.exitCode)});const task=program.command("task").description("Manage task lifecycle state");task.command("resume").description("Print recovery instructions for the current task phase").option("--dir <dir>","Target directory (default: current directory)").action(opts=>{runTaskResume({...opts.dir!==void 0?{dir:opts.dir}:{}})});function advanceLandingFlags(opts){return opts.pr===!1?{noPr:!0}:typeof opts.pr=="number"?{pr:opts.pr}:{}}task.command("advance").description("Advance (or reverse) the task lifecycle phase").requiredOption("--to <phase>","Target phase (preflight|plan|red-team-review|red|green|refactor|verification|close|complete|red-team-rework)").option("--reverse","Allow backward phase transitions",!1).option("--dir <dir>","Target directory (default: current directory)").option("--skip-plan-review","Bypass the plan-review gate (writes audit record + WARNING)",!1).option("--post-clear","Signal post-/clear re-entry (equivalent to ARBITER_POST_CLEAR=1)",!1).option("--no-pr","Complete without a merged PR \u2014 this repo lands by direct push (logged)").option("--pr <n>","Verify this PR number when the branch carries more than one",v=>{const n=parseInt(v,10);if(isNaN(n)||n<=0)throw new Error("--pr must be a positive integer");return n}).action(opts=>{try{runTaskAdvance({to:opts.to,reverse:opts.reverse,skipPlanReview:opts.skipPlanReview,postClear:opts.postClear,...advanceLandingFlags(opts),...opts.dir!==void 0?{dir:opts.dir}:{}})}catch(err){throw err instanceof HandoffRequiredError&&(process.stderr.write(err.message+`
+`),process.exit(78)),err}}),task.command("recover").description("Print 3-layer recovery context for the current task (#694)").option("--dir <dir>","Target directory (default: current directory)").option("--task <id>","Task id (default: the active task)").action(opts=>{runTaskRecover({...opts.dir!==void 0?{dir:opts.dir}:{},...opts.task!==void 0?{taskId:opts.task}:{}})}),task.command("record-red").description("Record TDD red-phase evidence: run a failing test and capture evidence (#551)").requiredOption("--test-path <path>","Repo-relative path to the failing test file").option("--dir <dir>","Target directory / repo root (default: current directory)").option("--task <id>","Task id; use for a declared secondary issue on a train (#2336)").option("--test-command <cmd>","Override the test runner binary (e.g. go, pytest, npx). Overrides language-based auto-selection. The command is passed verbatim to the runner (no shell interpolation).").option("--test-arg <arg>","Argument to the test command (repeatable). Combined with --test-command in the order given.",(val,acc)=>acc.concat(val),[]).option("--timeout-ms <ms>","Test-run timeout in ms (default 60000, clamped to 1..600000)").option("--force","Skip the dirty-__tests__ and test-path-in-HEAD refusals (#1988)",!1).action(opts=>{const testCmd=opts.testCommand!==void 0?[opts.testCommand,...opts.testArg??[]]:void 0,timeoutMs=opts.timeoutMs!==void 0?Number.parseInt(opts.timeoutMs,10):void 0,result=runTaskRecordRed({testPath:opts.testPath,...opts.dir!==void 0?{dir:opts.dir}:{},...opts.task!==void 0?{taskId:opts.task}:{},...testCmd!==void 0?{testCmd}:{},...timeoutMs!==void 0?{timeoutMs}:{},force:opts.force});result.ok?process.stdout.write(`record-red: OK (framework=${result.framework})
+evidence: ${result.evidencePath}
+`):(process.stderr.write(`record-red: FAIL \u2014 ${result.reason}
+`),process.exit(1))}),task.command("record-tech-debt").description("File a tech-debt GitHub issue and persist evidence (#702)").requiredOption("--description <text>","Short description of the tech-debt finding").option("--triggered-by <task-id>","Task ID that triggered this debt filing (default: the active task)").option("--dir <dir>","Target directory / repo root (default: current directory)").action(opts=>{const result=runTaskRecordTechDebt({description:opts.description,...opts.triggeredBy!==void 0?{triggeredBy:opts.triggeredBy}:{},...opts.dir!==void 0?{dir:opts.dir}:{}});result.ok?process.stdout.write(`record-tech-debt: OK (issue #${result.issueNumber})
+`):(process.stderr.write(`record-tech-debt: FAIL \u2014 ${result.reason}
+`),process.exit(1))}),task.command("init [ids...]").description("Initialise / update the unified task document (#1206)").option("--id <id>","Task id, e.g. #1206").option("--tier <tier>","Task tier (XS|S|Standard)").option("--plan <path>","Repo-relative path to the plan file").option("--chain <id>","Other issue id batched into this task worktree/gate/PR (repeatable, #2102)",(v,acc)=>[...acc,v],[]).option("--dir <dir>","Target directory (default: current directory)").action((ids,opts)=>{const train=splitTrainIds(ids,opts.id,opts.chain);runTaskInit({...train.taskId!==void 0?{id:train.taskId}:{},...opts.tier!==void 0?{tier:opts.tier}:{},...opts.plan!==void 0?{plan:opts.plan}:{},...train.chainIds.length>0?{chainIds:train.chainIds}:{},...opts.dir!==void 0?{dir:opts.dir}:{}})}),task.command("get").description("Print a single task-state field for shell consumers (#1206)").requiredOption("--field <field>","phase|taskId|tier|plan|tddPhase|lastAction|nextAction").option("--dir <dir>","Target directory (default: current directory)").action(opts=>{runTaskGet({field:opts.field,...opts.dir!==void 0?{dir:opts.dir}:{}})}),program.command("mark",{hidden:!0}).description("Pinpoint: snapshot the step-cursor so a mid-task /clear resumes exactly (#1206)").option("--next <action>","The exact next sub-step to resume on").option("--last <action>","The sub-step just completed").option("--tdd <phase>","TDD sub-phase (RED|GREEN|REFACTOR)").option("--task <id>","Set/override the active task id").option("--digest <line>","One-line progress digest for log.md").option("--dir <dir>","Target directory (default: current directory)").action(opts=>{let tddPhase;if(opts.tdd!==void 0){const upper=opts.tdd.toUpperCase();isTddPhase(upper)||(process.stderr.write(`Invalid --tdd value "${opts.tdd}". Valid: RED, GREEN, REFACTOR
+`),process.exit(2)),tddPhase=upper}runTaskMark({...opts.next!==void 0?{next:opts.next}:{},...opts.last!==void 0?{last:opts.last}:{},...tddPhase!==void 0?{tddPhase}:{},...opts.task!==void 0?{taskId:opts.task}:{},...opts.digest!==void 0?{digest:opts.digest}:{},...opts.dir!==void 0?{dir:opts.dir}:{}})});function shipReviewFlags(opts){return{...opts.reviewRound?{reviewRound:!0}:{},...opts.forceReview?{forceReview:!0}:{}}}program.command("ship [ids...]").description("Orchestrate an issue \u2192 reviewed, merged PR over the existing engine (#1206)").option("--tier <tier>","Task tier (XS|S|Standard)").option("--autonomy <level>","Per-run autonomy override (L0|L1|L2|L3) \u2014 beats arbiter.json automation.autonomy (#1291)",v=>{if(!["L0","L1","L2","L3"].includes(v))throw new Error("--autonomy must be one of L0|L1|L2|L3");return v}).option("--set <path=value>","Per-run override of an overridable config path (repeatable, ADR-094). Gated by OVERRIDABLE_PATHS; persists to the session layer so it survives /clear. e.g. --set automation.autonomy=L3",(v,acc)=>[...acc,v],[]).option("--advance","Advance to the next phase (runs that phase gate; fails if red)",!1).option("--skip-plan-review","Bypass the plan-review gate on advance",!1).option("--post-clear","Signal post-/clear re-entry on advance",!1).option("--units <n>","Implementation unit count from the plan \u2014 drives the size-driven clear decision",v=>{const n=parseInt(v,10);if(isNaN(n)||n<=0)throw new Error("--units must be a positive integer");return n}).option("--chain <id>","Other issue id batched into this ship worktree/gate/PR (repeatable, #2102)",(v,acc)=>[...acc,v],[]).option("--chain-add <id>","Append an issue to the open train, or refuse if it must seal first (repeatable, #2331)",(v,acc)=>[...acc,v],[]).option("--seal","Seal the open train now \u2014 land it before starting another (#2331)",!1).option("--no-pr","Complete without a merged PR \u2014 this repo lands by direct push (logged)").option("--pr <n>","Verify this PR number when the branch carries more than one",v=>{const n=parseInt(v,10);if(isNaN(n)||n<=0)throw new Error("--pr must be a positive integer");return n}).option("--review-round","Record another code-review round on this task (entering refactor records the first)",!1).option("--force-review","Take a review round past ship.review.maxRounds, and record that it was forced",!1).option("--dir <dir>","Target directory (default: current directory)").action((ids,opts)=>{try{const shipRoot=opts.dir??process.cwd(),overrides=buildShipOverrides(shipRoot,{sets:opts.set,...opts.autonomy!==void 0?{autonomy:opts.autonomy}:{}}),externalModelAccess=externalModelAccessForShip(shipRoot,overrides),train=splitTrainIds(ids,void 0,opts.chain),result=runTaskShip({...Object.keys(overrides).length>0?{overrides}:{},...train.taskId!==void 0?{taskId:train.taskId}:{},...opts.tier!==void 0?{tier:opts.tier}:{},...train.chainIds.length>0?{chainIds:train.chainIds}:{},...opts.chainAdd.length>0?{chainAddIds:opts.chainAdd}:{},...opts.seal?{seal:!0}:{},...shipReviewFlags(opts),advance:opts.advance,advanceOpts:{skipPlanReview:opts.skipPlanReview,postClear:opts.postClear,...opts.units!==void 0?{units:opts.units}:{},...advanceLandingFlags(opts)},...opts.dir!==void 0?{dir:opts.dir}:{},...externalModelAccess!==void 0?{externalModelAccess}:{}}),outputResult=shipOutputAfterConfiguredReview(shipRoot,result,opts.tier,externalModelAccess),lines=buildShipStepLines(outputResult);process.stdout.write(lines.join(`
+`)+`
+`)}catch(err){throw err instanceof HandoffRequiredError&&(process.stderr.write(err.message+`
+`),process.exit(78)),err}});function exitReviewDiffFailure(json,exitCode,data,message){json?jsonOutput("review diff","error",data,[message]):process.stderr.write(message+`
+`),process.exit(exitCode)}review.command("diff").description("Semantic diff between two graph snapshots (#262)").option("--base <path>","Base graph snapshot path (default: reads from stdin or .arbiter/graph-base.json)").option("--head <path>","Head graph snapshot path (default: .arbiter/graph.json)").option("--dir <dir>","Target directory (default: current directory)").option("--json","Emit machine-readable JSON output",!1).option("--post-pr <number>","Post result as GitHub PR comment").action(async opts=>{const{existsSync:efs}=await import("node:fs"),{resolve:res,join:pjoin}=await import("node:path"),{loadGraphSnapshot:loadGraph}=await import("./graph/load.js"),dir=res(opts.dir??"."),headPath=opts.head!==void 0?res(opts.head):pjoin(dir,".arbiter","graph.json"),basePath=opts.base!==void 0?res(opts.base):pjoin(dir,".arbiter","graph-base.json");if(!efs(headPath)){const message=`review diff: FAIL \u2014 head graph not found at ${headPath}`;exitReviewDiffFailure(opts.json,2,{headPath},message)}efs(basePath)||process.stderr.write(`review diff: WARN \u2014 base graph not found at ${basePath}, using empty base
+`);const headOutcome=loadGraph(headPath);if(!headOutcome.ok){const message=`review diff: FAIL \u2014 ${headOutcome.reason}`;exitReviewDiffFailure(opts.json,2,{headPath},message)}let base={nodes:[],edges:[]};if(efs(basePath)){const baseOutcome=loadGraph(basePath);if(!baseOutcome.ok){const message=`review diff: FAIL \u2014 ${baseOutcome.reason}`;exitReviewDiffFailure(opts.json,2,{basePath},message)}base=baseOutcome.snapshot}const result=runReviewDiff({base,head:headOutcome.snapshot});if(opts.json?jsonOutput("review diff",result.status,{exitCode:result.exitCode,recommendation:result.recommendation,risk_delta:result.risk_delta,changes:result.changes,summary:result.summary},result.reason!==void 0?[result.reason]:void 0):process.stdout.write(renderMarkdown(result)+`
+`),opts.postPr!==void 0){const{runCli:rc}=await import("./utils/run-cli.js"),markdown=renderMarkdown(result);try{rc("gh",["pr","comment",opts.postPr,"--body",markdown])}catch(err){process.stderr.write(`review diff: failed to post PR comment: ${err instanceof Error?err.message:String(err)}
+`)}}process.exit(result.exitCode)}),program.command("explain [code]").description("Show detailed explanation for an error code, INV-NN invariant, or CANON-NN rule").option("--format <format>","Output format: text (default) or json").option("--list","List all known codes grouped by category").option("--handoff <topic>","Scaffold HANDOFF-<TOPIC>.md from the executable-handoff template (#1817 A7)").option("--out <dir>","Target directory for --handoff (default: cwd)").action((code,opts)=>{const result=runExplain(code??"",opts);result.output&&process.stdout.write(result.output),result.error&&process.stderr.write(result.error),result.exitCode!==0&&process.exit(result.exitCode)}),program.command("help [command]",{hidden:!0}).description("Display help for a command").option("--all","Also list experimental (hidden) commands",!1).action((commandName,opts)=>{if(opts.all){const helpRenderer=program.createHelp(),visibleNames=new Set(helpRenderer.visibleCommands(program).map(c=>c.name())),hidden=program.commands.filter(c=>!visibleNames.has(c.name())&&c.name()!=="help");process.stdout.write(program.helpInformation()),process.stdout.write(`
+Experimental commands:
+`);const width=Math.max(...hidden.map(c=>c.name().length));for(const cmd of hidden.slice().sort((a,b)=>a.name().localeCompare(b.name())))process.stdout.write(`  ${cmd.name().padEnd(width+2)}${cmd.summary()||cmd.description()}
+`);return}if(commandName){const sub=program.commands.find(c=>c.name()===commandName||c.aliases().includes(commandName));sub&&sub.help(),process.stderr.write(`error: unknown command '${commandName}'
+`),process.exit(1)}program.help()});function _writeArbiterError(err,prefix="Error"){if(_jsonRequested){jsonOutput("arbiter","error",{},[err.message],{code:err.code,...err instanceof FatalError?{errorClass:"fatal"}:err instanceof ConfigError?{errorClass:"config"}:err instanceof RecoverableError?{errorClass:"recoverable"}:{}});return}process.stderr.write(`
+${prefix} [${err.code}]: ${err.message}
+`),err.hint&&process.stderr.write(`  Hint: ${err.hint}
+`),err.docUrl&&process.stderr.write(`  Docs: ${err.docUrl}
+`),process.stderr.write(`
+Run \`arbiter explain ${err.code}\` for more detail.
+`),_verbose&&err.stack&&process.stderr.write(`
+${err.stack}
+`)}function _writeStackIfVerbose(err){_verbose&&err.stack&&process.stderr.write(`
+${err.stack}
+`)}function _handleTopLevelError(err){err instanceof FatalError?(!_jsonRequested&&err.recoverableContext?.length&&process.stderr.write(`
+  Recoverable errors before fatal:
+${err.recoverableContext.map(w=>`    - ${w}`).join(`
+`)}
+`),_writeArbiterError(err,"Fatal error"),process.exit(2)):err instanceof ConfigError?(_writeArbiterError(err,"Config error"),process.exit(78)):err instanceof RecoverableError?(_writeArbiterError(err),process.exit(1)):err instanceof SnapshotChecksumError?(process.stderr.write(`
+Checksum error: ${err.message}
+`),process.stderr.write("  The .arbiter-generated.json snapshot is corrupt. Delete it and re-run `arbiter update`.\n"),_writeStackIfVerbose(err),process.exit(2)):err instanceof ArbiterError?_writeArbiterError(err):err instanceof UserFacingError?(process.stderr.write(`Error: ${err.message}
+`),_writeStackIfVerbose(err)):err instanceof Error?(process.stderr.write(`Unexpected error: ${err.message}
+`),_verbose&&process.stderr.write(`${err.stack??""}
+`)):process.stderr.write(`Unexpected error: ${String(err)}
+`),process.exit(1)}async function _main(){await _startProfileIfRequested();try{await program.parseAsync()}finally{if(_profilerHandle!==null)try{const path=await _profilerHandle.stop();getLogger().info("profiler.written",{path})}catch(err){getLogger().warn("profiler.stop_failed",void 0,String(err))}}}_main().catch(_handleTopLevelError);

package/dist/commands/adopt-policy.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: Apache-2.0
+import{createHash}from"node:crypto";import{join}from"node:path";import{ensureDir,writeFileTranslated}from"../utils/fs.js";import{isGateSpineKey,isGovernanceClassKey,isSafetyClassKey}from"../generators/safety-class.js";import{isDerivedTrackKey}from"../generators/derived-class.js";function sha256(content){return createHash("sha256").update(content).digest("hex")}export function buildAdoptPredicate(options){const adoptAll=options.adopt===!0,adoptSafety=options.noAdoptSafety!==!0,adoptGateSpine=options.adoptGateSpine===!0,adoptGovernance=options.adoptGovernance===!0,refreshDerived=options.refreshDerived===!0,informative=(key,provenanceKnown)=>provenanceKnown&&(adoptGateSpine&&isGateSpineKey(key)||adoptGovernance&&isGovernanceClassKey(key)||refreshDerived&&isDerivedTrackKey(key));return(key,provenanceKnown)=>adoptAll||adoptSafety&&isSafetyClassKey(key)||informative(key,provenanceKnown)}function localOverrideSlug(key){return key.replace(/^\.+/,"").replace(/[/\\]+/g,"__")}function localOverrideReason(key){return isDerivedTrackKey(key)?"update --refresh-derived: codex-track derived file force-refreshed to the current template render (skipIfExists bypassed for this known set only)":isGovernanceClassKey(key)?"update --adopt-governance: governance file force-adopted over locally-modified content \u2014 AGENTS.md carries the Iron Laws and .claude/settings.json the ARBITER_* deny list; this now happens only under explicit --adopt-governance (#2056, #2120, #2141; mark the file `arbiter:preserve` to freeze it)":isGateSpineKey(key)?"update: gate-spine file force-adopted over user-modified content \u2014 the gate entrypoint and its libs are the delivery vector for every later fix (#2109, reversed by #2119: this now happens only under explicit --adopt-gate-spine)":"update --adopt: template fix force-adopted over user-modified content (safety-class files adopt by default; see --no-adopt-safety)"}export function recordLocalOverride(targetDir,record,now=()=>new Date){const dir=join(targetDir,".arbiter","evidence","local-overrides");ensureDir(dir);const envelope={path:record.key,adoptedAt:now().toISOString(),reason:localOverrideReason(record.key),priorContent:record.priorContent,priorContentSha256:sha256(record.priorContent),newContent:record.newContent,newContentSha256:sha256(record.newContent)},file=join(dir,`${localOverrideSlug(record.key)}.json`);return writeFileTranslated(file,JSON.stringify(envelope,null,2)+`
+`),file}

package/dist/commands/configure-interactive.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: Apache-2.0
+import{resolve}from"node:path";import{intro,outro,select,multiselect,confirm,text,isCancel,cancel,note}from"@clack/prompts";import{loadConfig}from"../utils/config.js";import{t}from"../i18n/index.js";import{runConfigure}from"./configure.js";import{SUPPORTED_AI_TOOLS}from"../wizard/types.js";function diffStr(path,oldVal,newVal){return oldVal===newVal?[]:[`${path}=${newVal}`]}function diffBool(path,oldVal,newVal){return oldVal===newVal?[]:[`${path}=${String(newVal)}`]}function diffArr(path,oldArr,newArr){const a=[...oldArr].sort().join(","),b=[...newArr].sort().join(",");return a===b?[]:[`${path}=${newArr.join(",")}`]}function axisDefaults(config){return{archetype:config.archetype??"backend-web-db",architectureStyle:config.architectureStyle??"none",isMultiTenant:config.isMultiTenant??!1,hasDatabase:config.hasDatabase??!1,hasPublicApi:config.hasPublicApi??!1,contractType:config.contractType??"none"}}async function promptAxisGroup(config){note(t("cli.configure.interactive.axis_header"));const d=axisDefaults(config),archetype=await select({message:"Project archetype",options:[{value:"backend-web-db",label:"backend-web-db"},{value:"cli",label:"cli"},{value:"library",label:"library"},{value:"data-pipeline",label:"data-pipeline"},{value:"frontend-spa",label:"frontend-spa"},{value:"embedded",label:"embedded"}],initialValue:d.archetype});if(isCancel(archetype))return null;const architectureStyle=await select({message:"Architecture style",options:[{value:"hexagonal",label:"hexagonal"},{value:"layered",label:"layered"},{value:"modular-monolith",label:"modular-monolith"},{value:"none",label:"none"}],initialValue:d.architectureStyle});if(isCancel(architectureStyle))return null;const isMultiTenant=await confirm({message:"Multi-tenant deployment?",initialValue:d.isMultiTenant});if(isCancel(isMultiTenant))return null;const hasDatabase=await confirm({message:"Database connected?",initialValue:d.hasDatabase});if(isCancel(hasDatabase))return null;const hasPublicApi=await confirm({message:"Public API exposed?",initialValue:d.hasPublicApi});if(isCancel(hasPublicApi))return null;const contractType=await select({message:"Contract testing strategy",options:[{value:"rest-owned",label:"rest-owned"},{value:"rest-public",label:"rest-public"},{value:"graphql",label:"graphql"},{value:"grpc",label:"grpc"},{value:"message-queue",label:"message-queue"},{value:"none",label:"none"}],initialValue:d.contractType});if(isCancel(contractType))return null;const governanceLevel=await select({message:"Governance level",options:[{value:"L1",label:"L1",hint:"minimal"},{value:"L2",label:"L2",hint:"standard"},{value:"L3",label:"L3",hint:"strict"},{value:"L4",label:"L4",hint:"maximum"}],initialValue:config.governanceLevel});return isCancel(governanceLevel)?null:[...diffStr("archetype",config.archetype,archetype),...diffStr("architectureStyle",config.architectureStyle,architectureStyle),...diffBool("isMultiTenant",config.isMultiTenant,isMultiTenant),...diffBool("hasDatabase",config.hasDatabase,hasDatabase),...diffBool("hasPublicApi",config.hasPublicApi,hasPublicApi),...diffStr("contractType",config.contractType,contractType),...diffStr("governanceLevel",config.governanceLevel,governanceLevel)]}async function promptFeaturesGroup(config){note(t("cli.configure.interactive.features_header"));const f=config.features,fields=[["features.contractTesting",f.contractTesting],["features.mutationTesting",f.mutationTesting],["features.securityScanning",f.securityScanning],["features.evidenceHarness",f.evidenceHarness],["features.acceptanceAnchor",f.acceptanceAnchor??!1],["features.debtGates",f.debtGates],["features.suppressions",f.suppressions],["features.soloDevMode",f.soloDevMode??!1]],assignments=[];for(const[path,oldVal]of fields){const label=path.replace("features.",""),val=await confirm({message:`Enable ${label}?`,initialValue:oldVal});if(isCancel(val))return null;assignments.push(...diffBool(path,oldVal,val))}return assignments}async function promptThresholdsGroup(config){note(t("cli.configure.interactive.thresholds_header"));const th=config.thresholds,numericFields=[["thresholds.lineCoverage",th.lineCoverage,"Line coverage threshold (%)"],["thresholds.branchCoverage",th.branchCoverage,"Branch coverage threshold (%)"],["thresholds.mutationScore",th.mutationScore,"Mutation score threshold (%)"],["thresholds.cyclomaticComplexity",th.cyclomaticComplexity,"Max cyclomatic complexity"],["thresholds.methodLength",th.methodLength,"Max method length (lines)"],["thresholds.maxParams",th.maxParams,"Max parameters per function"]],assignments=[];for(const[path,oldVal,message]of numericFields){const val=await text({message,initialValue:String(oldVal),validate:v=>v===void 0||!/^\d+$/.test(v.trim())?t("cli.configure.interactive.invalid_number"):void 0});if(isCancel(val))return null;const trimmed=val.trim();trimmed!==String(oldVal)&&assignments.push(`${path}=${trimmed}`)}return assignments}async function promptCollaborationGroup(config){note(t("cli.configure.interactive.collaboration_header"));const collaborationMode=await select({message:"Collaboration mode",options:[{value:"trunk-solo",label:"trunk-solo",hint:"one author, direct push"},{value:"peer-review",label:"peer-review",hint:"shared trust, mandatory PR"},{value:"gated-review",label:"gated-review",hint:"CODEOWNERS, merge queue"}],initialValue:config.collaborationMode??"peer-review"});if(isCancel(collaborationMode))return null;const branchingStrategy=await select({message:"Branching strategy",options:[{value:"trunk-direct",label:"trunk-direct"},{value:"github-flow",label:"github-flow"},{value:"github-flow-with-develop",label:"github-flow-with-develop"}],initialValue:config.branchingStrategy??"trunk-direct"});if(isCancel(branchingStrategy))return null;const soloMergeMode=await select({message:"Solo merge method",options:[{value:"direct",label:"direct",hint:"push directly to main"},{value:"pr-ff",label:"pr-ff",hint:"PR with fast-forward merge"}],initialValue:config.solo?.mergeMode??"direct"});return isCancel(soloMergeMode)?null:[...diffStr("collaborationMode",config.collaborationMode,collaborationMode),...diffStr("branchingStrategy",config.branchingStrategy,branchingStrategy),...diffStr("solo.mergeMode",config.solo?.mergeMode,soloMergeMode)]}async function promptAccessGroup(config){note(t("cli.configure.interactive.access_header"));const tools=await multiselect({message:"Active AI tools",options:SUPPORTED_AI_TOOLS.map(v=>({value:v,label:v})),initialValues:[...config.tools],required:!0});if(isCancel(tools))return null;const permitGitHub=await confirm({message:"Permit GitHub integration?",initialValue:config.permitGitHub??!1});return isCancel(permitGitHub)?null:[...diffArr("tools",config.tools,tools),...diffBool("permitGitHub",config.permitGitHub,permitGitHub)]}async function promptAutomationGroup(config){note(t("cli.configure.interactive.automation_header"));const autonomy=await select({message:"Ship autonomy level",options:[{value:"L0",label:"L0",hint:"ask at each ship step (default)"},{value:"L1",label:"L1",hint:"auto-advance + auto-merge on green"},{value:"L2",label:"L2",hint:"+ autonomous fix-on-red attempt"},{value:"L3",label:"L3",hint:"full auto: wave/batch + fix push + sub-agents"}],initialValue:config.automation?.autonomy??"L0"});return isCancel(autonomy)?null:diffStr("automation.autonomy",config.automation?.autonomy,autonomy)}export async function runInteractiveConfigure(dir){const targetDir=resolve(dir??process.cwd()),stored=loadConfig(targetDir);if(!stored){process.stderr.write(`${t("cli.configure.interactive.no_config")}
+`),process.exit(1);return}intro(t("cli.configure.interactive.intro"));const groups=[c=>promptAxisGroup(c),c=>promptFeaturesGroup(c),c=>promptThresholdsGroup(c),c=>promptCollaborationGroup(c),c=>promptAccessGroup(c),c=>promptAutomationGroup(c)],allAssignments=[];for(const group of groups){const result=await group(stored);if(result===null){cancel(t("cli.configure.no_changes"));return}allAssignments.push(...result)}const saveit=await confirm({message:t("cli.configure.interactive.save_confirm"),initialValue:!0});if(isCancel(saveit)||!saveit){cancel(t("cli.configure.no_changes"));return}if(allAssignments.length===0){outro(t("cli.configure.no_changes"));return}await runConfigure({dir:targetDir,sets:allAssignments})}

package/dist/commands/configure.js

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+import{resolve,join,relative}from"node:path";import{existsSync}from"node:fs";import{loadConfig,saveConfig}from"../utils/config.js";import{validateConfig,VALID_COLLABORATION_MODES,VALID_SOLO_MERGE_MODES,VALID_BRANCHING_STRATEGIES,AUTONOMY_LEVELS,VALID_GATE_LEVELS,DEFAULT_CROSS_MODEL_REVIEW}from"../config/schema.js";import{acquireLock}from"../utils/file-lock.js";import{jsonOutput}from"../utils/json-output.js";import{deriveAxisDefaults}from"../detectors/axis.js";import{ArbiterError}from"../utils/errors.js";import{SUPPORTED_AI_TOOLS}from"../wizard/types.js";import{t}from"../i18n/index.js";import{ensureDir,readFileTranslated,writeFile}from"../utils/fs.js";import{resolveMaxParallelWorktrees}from"../config/collaboration-mode-defaults.js";export const ALLOWED_PATHS=new Set(["features.contractTesting","features.mutationTesting","features.securityScanning","features.evidenceHarness","features.acceptanceAnchor","features.debtGates","features.suppressions","features.soloDevMode","features.codeownersNotify","features.taxonomy25d","features.perfTesting","features.riskRegister","features.operationsHandbook","features.iso27001Mapping","features.nis2Mapping","features.gdprMapping","collaborationMode","solo.mergeMode","branchingStrategy","thresholds.lineCoverage","thresholds.branchCoverage","thresholds.mutationScore","thresholds.cyclomaticComplexity","thresholds.methodLength","thresholds.maxParams","governanceLevel","permitGitHub","tools","archetype","architectureStyle","isMultiTenant","hasDatabase","hasPublicApi","contractType","automation.autonomy","automation.maxParallelWorktrees","automation.defaultGateLevel","crossModelReview.enabled","crossModelReview.diffEgressConsent","crossModelReview.providers","crossModelReview.slots.codeReview","crossModelReview.slots.redTeamReview","crossModelReview.timeoutMs","crossModelReview.onUnavailable"]),OVERRIDABLE_PATHS=new Set(["automation.autonomy","automation.defaultGateLevel","crossModelReview.enabled"]);export function assertOverridablePath(path){if(!OVERRIDABLE_PATHS.has(path))throw ArbiterError.fromKey("E_UNKNOWN_PATH","errors.E_UNKNOWN_PATH",{path},{hint:`Per-run --set is limited to: ${[...OVERRIDABLE_PATHS].join(", ")}. Persistent settings change via \`arbiter configure\`.`})}const VALID_TOOLS=new Set(SUPPORTED_AI_TOOLS),VALID_ARCHETYPES=new Set(["backend-web-db","cli","library","data-pipeline","frontend-spa","embedded"]),VALID_ARCHITECTURE_STYLES=new Set(["hexagonal","layered","modular-monolith","none"]),VALID_CONTRACT_TYPES=new Set(["rest-owned","rest-public","graphql","grpc","message-queue","none"]),CROSS_MODEL_BOOLEAN_PATHS=new Set(["crossModelReview.enabled","crossModelReview.diffEgressConsent"]),CROSS_MODEL_SLOT_PATHS=new Set(["crossModelReview.slots.codeReview","crossModelReview.slots.redTeamReview"]);function parseAxisValue(path,raw){if(path==="archetype"){if(!VALID_ARCHETYPES.has(raw))throw ArbiterError.fromKey("E_INVALID_ARCHETYPE","errors.E_INVALID_ARCHETYPE",{field:"archetype",value:raw,valid:[...VALID_ARCHETYPES].join(", ")},{hint:"Run `arbiter configure --help` for a list of valid archetypes."});return raw}if(path==="architectureStyle"){if(!VALID_ARCHITECTURE_STYLES.has(raw))throw ArbiterError.fromKey("E_INVALID_ARCHETYPE","errors.E_INVALID_ARCHETYPE",{field:"architectureStyle",value:raw,valid:[...VALID_ARCHITECTURE_STYLES].join(", ")},{hint:"Run `arbiter configure --help` for valid architectureStyle values."});return raw}if(path==="contractType"){if(!VALID_CONTRACT_TYPES.has(raw))throw ArbiterError.fromKey("E_INVALID_ARCHETYPE","errors.E_INVALID_ARCHETYPE",{field:"contractType",value:raw,valid:[...VALID_CONTRACT_TYPES].join(", ")},{hint:"Run `arbiter configure --help` for valid contractType values."});return raw}if(raw==="true")return!0;if(raw==="false")return!1;throw ArbiterError.fromKey("E_INVALID_BOOL","errors.E_INVALID_BOOL",{path,value:raw},{hint:"Use `true` or `false` (lowercase)."})}function parseCrossModelBoolean(path,raw){if(raw==="true")return!0;if(raw==="false")return!1;throw ArbiterError.fromKey("E_INVALID_BOOL","errors.E_INVALID_BOOL",{path,value:raw},{hint:"Use `true` or `false` (lowercase)."})}function parseCrossModelProviders(raw){const providers=raw.split(",").map(provider=>provider.trim());if(providers.length===1&&providers[0]==="codex")return providers;throw ArbiterError.fromKey("E_INVALID_TOOL","errors.E_INVALID_TOOL",{noun:"provider",tool:JSON.stringify(raw),valid:"codex"},{hint:"The only supported cross-model provider is codex."})}function parseCrossModelNumber(path,raw){const value=Number(raw),minimum=CROSS_MODEL_SLOT_PATHS.has(path)?0:1;if(!Number.isInteger(value)||value<minimum)throw ArbiterError.fromKey("E_INVALID_NUMBER","errors.E_INVALID_NUMBER",{path,value:raw},{hint:`Provide an integer >= ${minimum}.`});return value}function parseCrossModelPolicy(path,raw){if(raw==="degrade"||raw==="fail")return raw;throw ArbiterError.fromKey("E_INVALID_ARCHETYPE","errors.E_INVALID_ARCHETYPE",{field:path,value:raw,valid:"degrade, fail"},{hint:"Use `degrade` or `fail`."})}function parseCrossModelValue(path,raw){return CROSS_MODEL_BOOLEAN_PATHS.has(path)?parseCrossModelBoolean(path,raw):path==="crossModelReview.providers"?parseCrossModelProviders(raw):CROSS_MODEL_SLOT_PATHS.has(path)||path==="crossModelReview.timeoutMs"?parseCrossModelNumber(path,raw):path==="crossModelReview.onUnavailable"?parseCrossModelPolicy(path,raw):raw}function parseFeatureValue(path,raw){if(!path.startsWith("features."))return null;if(raw==="true")return!0;if(raw==="false")return!1;throw ArbiterError.fromKey("E_INVALID_BOOL","errors.E_INVALID_BOOL",{path:"features.*",value:raw},{hint:"Use `true` or `false` (lowercase). Example: `arbiter configure --set features.debtGates=true`."})}const AXIS_PATHS=new Set(["archetype","architectureStyle","isMultiTenant","hasDatabase","hasPublicApi","contractType"]);export function parseValue(path,raw){const featureValue=parseFeatureValue(path,raw);if(featureValue!==null)return featureValue;if(path.startsWith("thresholds.")){const n=Number(raw);if(!Number.isFinite(n))throw ArbiterError.fromKey("E_INVALID_NUMBER","errors.E_INVALID_NUMBER",{path,value:raw},{hint:`Provide a numeric value. Example: \`arbiter configure --set ${path}=80\`.`});return n}if(path==="permitGitHub"){if(raw==="true")return!0;if(raw==="false")return!1;throw ArbiterError.fromKey("E_INVALID_BOOL","errors.E_INVALID_BOOL",{path:"permitGitHub",value:raw},{hint:"Use `true` or `false` (lowercase)."})}if(path==="tools"){const toolList=raw.split(",").map(tool=>tool.trim());for(const tool of toolList)if(!VALID_TOOLS.has(tool))throw ArbiterError.fromKey("E_INVALID_TOOL","errors.E_INVALID_TOOL",{noun:"tool",tool:`"${tool}"`,valid:[...VALID_TOOLS].join(", ")},{hint:`Valid tools: ${[...VALID_TOOLS].join(", ")}.`});return toolList}return path.startsWith("crossModelReview.")?parseCrossModelValue(path,raw):AXIS_PATHS.has(path)?parseAxisValue(path,raw):AUTOMATION_SCALAR_PATHS.has(path)?parseAutomationScalar(path,raw):new Set(["collaborationMode","solo.mergeMode","branchingStrategy","automation.autonomy","automation.defaultGateLevel"]).has(path)?parseEnumPathValue(path,raw):raw}const AUTOMATION_SCALAR_PATHS=new Set(["automation.maxParallelWorktrees"]);function parseAutomationScalar(path,raw){const n=Number(raw);if(!Number.isInteger(n)||n<1)throw ArbiterError.fromKey("E_INVALID_NUMBER","errors.E_INVALID_NUMBER",{path,value:raw},{hint:"Provide a positive integer (\u22651). Example: `--set automation.maxParallelWorktrees=3`."});return n}function parseEnumPathValue(path,raw){const spec={collaborationMode:{valid:VALID_COLLABORATION_MODES,hint:"Valid values: trunk-solo, peer-review, gated-review. Example: `arbiter configure --set collaborationMode=peer-review`."},"solo.mergeMode":{valid:VALID_SOLO_MERGE_MODES,hint:"Valid values: direct, pr-ff. Example: `arbiter configure --set solo.mergeMode=pr-ff`."},branchingStrategy:{valid:VALID_BRANCHING_STRATEGIES,hint:"Valid values: trunk-direct, github-flow, github-flow-with-develop."},"automation.autonomy":{valid:new Set(AUTONOMY_LEVELS),hint:"Valid values: L0, L1, L2, L3. L0 = ask each ship step (default). Per-run override: `arbiter ship --autonomy Lx`."},"automation.defaultGateLevel":{valid:new Set(VALID_GATE_LEVELS),hint:"Valid values: L1, L2. The gate level `arbiter verify` runs by default. Per-run override: `arbiter ship --set automation.defaultGateLevel=L2`."}}[path];if(spec!==void 0&&!spec.valid.has(raw))throw ArbiterError.fromKey("E_INVALID_ARCHETYPE","errors.E_INVALID_ARCHETYPE",{field:path,value:raw,valid:[...spec.valid].join(", ")},{hint:spec.hint});return raw}function cascadeAxisDefaults(config,archetype){const defaults=deriveAxisDefaults(config,archetype);return{...config,architectureStyle:config.architectureStyle??defaults.architectureStyle,isMultiTenant:config.isMultiTenant??defaults.isMultiTenant,hasDatabase:config.hasDatabase??defaults.hasDatabase,hasPublicApi:config.hasPublicApi??defaults.hasPublicApi,contractType:config.contractType??defaults.contractType}}function applyAssignment(config,assignment){const eqIdx=assignment.indexOf("=");if(eqIdx<0)throw ArbiterError.fromKey("E_INVALID_FORMAT","errors.E_INVALID_FORMAT",{assignment},{hint:"Example: `arbiter configure --set tools=claude,codex`."});const path=assignment.slice(0,eqIdx),rawValue=assignment.slice(eqIdx+1);if(!ALLOWED_PATHS.has(path))throw ArbiterError.fromKey("E_UNKNOWN_PATH","errors.E_UNKNOWN_PATH",{path},{hint:"Run `arbiter configure --help` to see valid paths."});const value=parseValue(path,rawValue);return{config:applySet(config,path,value),archetypeTouched:path==="archetype"}}function applyTopLevel(config,key,value){return{...config,[key]:value}}function applyNested(config,top,key,value){const parent=config[top]??(top==="crossModelReview"?structuredClone(DEFAULT_CROSS_MODEL_REVIEW):{});return{...config,[top]:{...parent,[key]:value}}}function applyDeep(config,top,middle,leaf,value){const root=config,fallback=top==="crossModelReview"?{...structuredClone(DEFAULT_CROSS_MODEL_REVIEW)}:{},parent=root[top]??fallback,nested=parent[middle]??{};return{...config,[top]:{...parent,[middle]:{...nested,[leaf]:value}}}}function applySet(config,path,value){const parts=path.split("."),[top,middle,leaf]=parts;if(parts.length===1&&top!==void 0)return applyTopLevel(config,top,value);if(parts.length===2&&top!==void 0&&middle!==void 0)return applyNested(config,top,middle,value);if(parts.length===3&&top!==void 0&&middle!==void 0&&leaf!==void 0)return applyDeep(config,top,middle,leaf,value);throw ArbiterError.fromKey("E_UNSUPPORTED_PATH_DEPTH","errors.E_UNSUPPORTED_PATH_DEPTH",{path},{hint:"Run `arbiter configure --help` to see valid paths."})}function syncDrainMaxParallel(targetDir,config){const drainPath=join(targetDir,".claude","commands","drain.md");if(!existsSync(drainPath))return null;const cap=resolveMaxParallelWorktrees({automation:config.automation,collaborationMode:config.collaborationMode,enableSoloDevMode:config.features.soloDevMode}),before=readFileTranslated(drainPath,"utf8"),after=before.replace(/^(\| `--max-parallel N` \|) [^|\r\n]+(\| Max worktree agents;.*)$/m,`$1 ${cap}       $2`);return after===before?null:writeFile(drainPath,after).withheld?{drainPath,cap}:null}export async function runConfigure(options){if(options.sets.length===0){if(options.json){jsonOutput("configure","error",{},["--set is required (non-interactive usage)"]),process.exit(1);return}process.stderr.write(`${t("cli.configure.usage_hint")}
+`),process.exit(2)}const targetDir=resolve(options.dir??process.cwd()),stored=loadConfig(targetDir);if(!stored){if(options.json){jsonOutput("configure","error",{},["No arbiter.json found. Run `arbiter init` first."]),process.exit(1);return}throw ArbiterError.fromKey("E_CONFIG_NOT_FOUND","errors.E_CONFIG_NOT_FOUND",{},{hint:"Run `arbiter init` to initialize governance in this directory.",docUrl:"https://arbiter.dev/reference/cli#init"})}let config=stored,archetypeTouched=!1;for(const assignment of options.sets){const next=applyAssignment(config,assignment);config=next.config,next.archetypeTouched&&(archetypeTouched=!0)}archetypeTouched&&config.archetype!==void 0&&(config=cascadeAxisDefaults(config,config.archetype));const result=validateConfig(config);if(!result.ok)throw ArbiterError.fromKey("E_CONFIG_INVALID","errors.E_CONFIGURE_CONFIG_INVALID",{errors:result.errors.join("; ")},{hint:"Fix the errors above, or delete arbiter.json and re-run `arbiter init`."});ensureDir(join(targetDir,".arbiter"));const lock=await acquireLock(join(targetDir,".arbiter",".lock"));let drainWithheld;try{await saveConfig(targetDir,result.config),drainWithheld=syncDrainMaxParallel(targetDir,result.config)}finally{await lock.release()}const drainWarning=drainWithheld?t("cli.configure.drain_sync_withheld",{path:relative(targetDir,drainWithheld.drainPath),cap:drainWithheld.cap}):null;if(options.json){jsonOutput("configure","ok",{updated:options.sets},void 0,drainWarning?{warnings:[drainWarning]}:void 0);return}process.stdout.write(`${t("cli.configure.updated",{keys:options.sets.join(", ")})}
+`),drainWarning&&process.stderr.write(`${drainWarning}
+`)}

package/dist/commands/cross-model-review.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: Apache-2.0
+import{join,resolve}from"node:path";import{detectExternalModel}from"../detectors/external-model.js";import{assertSafeArbiterEvidenceRoot,invokeExternalReview}from"../integrations/external-review.js";import{resolveShipProfile}from"./ship-profile.js";import{normTier}from"./ship-tier.js";import{existsSync,lstatSync,readFileSync}from"node:fs";import{readFileContained,toFsError,writeFileContained}from"../utils/fs.js";import{runCli}from"../utils/run-cli.js";import{currentBranch,headSha}from"../evidence/git-checks.js";const SHIP_CROSS_MODEL_PROMPT="Review this change for bugs, type safety, security, data integrity, and silent failures.";function runCrossModelReview(options){const repoRoot=resolve(options.dir??process.cwd()),tier=normTier(options.tier),profile=resolveShipProfile(repoRoot),cfg=profile.crossModelReview;if(!cfg?.enabled)throw new Error("crossModelReview.enabled must be true to run an external review");if(!cfg.diffEgressConsent)throw new Error("crossModelReview.diffEgressConsent must be true to send the diff");const result=invokeExternalReview({repoRoot,taskId:options.taskId,prompt:options.prompt,diff:options.diff??readStdin(),cfg,access:detectExternalModel("codex"),tier,phase:options.phase??"refactor",vertical:options.vertical??"bugs"});return existsSync(repoRoot)&&writeExternalReviewSidecar(repoRoot,options.taskId,result,tier,profile.collaborationMode),result}function isRecord(value){return typeof value=="object"&&value!==null&&!Array.isArray(value)}function assertSafeSidecarFile(path){try{const stat=lstatSync(path);if(stat.isSymbolicLink())throw new Error(`${path} must not be a symbolic link`);if(!stat.isFile())throw new Error(`${path} must be a regular file`)}catch(error){if(error.code==="ENOENT")return;throw toFsError(error,path)}}function readSidecar(repoRoot){const relativePath=join(".arbiter","agents-dispatched.json"),path=join(repoRoot,".arbiter","agents-dispatched.json");try{if(assertSafeArbiterEvidenceRoot(repoRoot),assertSafeSidecarFile(path),!existsSync(path))return null;const parsed=JSON.parse(readFileContained(repoRoot,relativePath));if(!isRecord(parsed))throw new Error(`${path} must contain a JSON object`);return parsed}catch(error){if(error.code==="ENOENT")return null;throw new Error(`cannot read dispatch sidecar ${path}: ${String(error)}`,{cause:error})}}function isCurrentSidecar(existing,branch,sha,taskId){return existing!==null&&existing.branch===branch&&existing.sha===sha&&existing.taskId===taskId}function hasCurrentFulfilledReview(repoRoot,taskId){if(!existsSync(join(repoRoot,".git")))return!1;const branch=currentBranch(repoRoot),sha=headSha(repoRoot);if(branch==="unknown"||sha==="unknown")return!1;const sidecar=readSidecar(repoRoot);if(!(isCurrentSidecar(sidecar,branch,sha,taskId)&&Array.isArray(sidecar.agents)&&sidecar.agents.includes("codex-reviewer")))return!1;try{return runCli("node",[join(repoRoot,"scripts","check-cross-model-review.mjs"),"--require-fulfilled"],{cwd:repoRoot,timeoutMs:5e3,retries:0}).exitCode===0}catch{return!1}}function readSidecarAgents(existing){if(existing.agents===void 0)return null;if(!Array.isArray(existing.agents)||!existing.agents.every(agent=>typeof agent=="string"))throw new Error("existing dispatch sidecar has invalid agent names");const agents=[...existing.agents];if(new Set(agents).size!==agents.length)throw new Error("existing dispatch sidecar has duplicate agents");if(existing.count!==void 0&&(typeof existing.count!="number"||!Number.isInteger(existing.count)||existing.count<0||existing.count>agents.length))throw new Error("existing dispatch sidecar has an invalid count");return agents}function freshReviewPanel(context){return context.collaborationMode!=="trunk-solo"&&context.tier==="Standard"?{count:2,agents:["anthropic-reviewer","codex-reviewer"]}:{count:1,agents:["codex-reviewer"]}}function completeReviewPanel(agents,panelSize){if(panelSize!==2||agents.length!==1)return agents;const first=agents[0]??"anthropic-reviewer";return[first==="codex-reviewer"?"anthropic-reviewer":first,"codex-reviewer"]}function sidecarAgents(existing,branch,sha,taskId,context){const fresh=freshReviewPanel(context);if(!isCurrentSidecar(existing,branch,sha,taskId))return fresh;const agents=readSidecarAgents(existing);if(agents===null||agents.length===0)return fresh;const completed=completeReviewPanel(agents,fresh.count);return completed!==agents?{count:completed.length,agents:completed}:(agents.includes("codex-reviewer")||(agents[agents.length-1]="codex-reviewer"),{count:agents.length,agents})}function writeExternalReviewSidecar(repoRoot,taskId,result,tier="Standard",collaborationMode="peer-review"){if(result.status!=="fulfilled"||!result.recorded||result.envelope===void 0)return;assertSafeArbiterEvidenceRoot(repoRoot);const sidecarPath=join(repoRoot,".arbiter","agents-dispatched.json");assertSafeSidecarFile(sidecarPath);const branch=currentBranch(repoRoot),sha=headSha(repoRoot);if(branch==="unknown"||sha==="unknown")throw new Error("cannot bind dispatch sidecar to Git HEAD");const panel=sidecarAgents(readSidecar(repoRoot),branch,sha,taskId,{tier,collaborationMode});writeFileContained(repoRoot,join(".arbiter","agents-dispatched.json"),`${JSON.stringify({...panel,taskId,branch,sha},null,2)}
+`)}function assertReviewTreeClean(repoRoot){const unreviewed=runCli("git",["status","--porcelain=v1","--untracked-files=all"],{cwd:repoRoot,timeoutMs:15e3}).stdout.split(/\r?\n/).filter(line=>line.length>2).map(line=>line.slice(3)).filter(path=>path.length>0&&!path.startsWith(".arbiter/"));if(unreviewed.length>0)throw new Error(`working tree has uncommitted changes; commit before external review (${unreviewed.join(", ")})`)}function runShipCrossModelReview(options){const repoRoot=resolve(options.dir);let diff="",access=options.cfg.diffEgressConsent?options.access:void 0,preflightError,preflightDegradation;if(options.cfg.diffEgressConsent)try{if(assertReviewTreeClean(repoRoot),options.cfg.enabled&&hasCurrentFulfilledReview(repoRoot,options.taskId))return{provider:"codex",status:"fulfilled",diffBytes:0,diffTruncated:!1,degradationReasons:[],recorded:!0};diff=runCli("git",["diff","--binary","origin/main...HEAD"],{cwd:repoRoot,timeoutMs:15e3}).stdout}catch(error){access=void 0,preflightError=error,preflightDegradation="invocation-failed"}const result=invokeExternalReview({repoRoot,taskId:options.taskId,prompt:SHIP_CROSS_MODEL_PROMPT,diff,cfg:options.cfg,...access!==void 0?{access}:{},...preflightDegradation!==void 0?{preflightDegradation,preflightError}:{},tier:options.tier,phase:options.phase,vertical:options.vertical});return existsSync(repoRoot)&&writeExternalReviewSidecar(repoRoot,options.taskId,result,options.tier,options.collaborationMode??"peer-review"),result}export{runCrossModelReview,runShipCrossModelReview,writeExternalReviewSidecar};function readStdin(){try{return readFileSync(0,"utf8")}catch(error){throw toFsError(error,"stdin")}}

package/dist/commands/diff.js

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+import{resolve,relative,join}from"node:path";import{existsSync}from"node:fs";import{loadConfig}from"../utils/config.js";import{slugifyProjectName}from"./init.js";import{buildAdoptPredicate}from"./update.js";import{buildSelectionPredicate,loadIgnorePatterns}from"../config/arbiter-ignore.js";import{resolveProjectName}from"../config/resolve-project-name.js";import{resolveProjectConfig,gitHubPermitted}from"../config/resolve-project-config.js";import{detectInstalledSkills}from"../integrations/skill-detector.js";import{buildRegistry,runGeneratorsFromRegistry}from"../generators/registry.js";import{jsonOutput,statusToExitCode}from"../utils/json-output.js";import{t}from"../i18n/index.js";import{beginGenerationSession,endGenerationSession,readFileTranslated}from"../utils/fs.js";import{loadGeneratedManifest}from"../state/generated-manifest.js";import{renderAgentsMd}from"../generators/agents-md.js";import{buildRenderContext as buildClaudeRenderContext,parseExistingSettings}from"../generators/claude.js";import{renderTemplate}from"../utils/render.js";const IRON_LAWS_HEADING=/^## Iron Laws[ \t]*$/m;function extractIronLawsBlock(content){const match=IRON_LAWS_HEADING.exec(content);if(!match)return null;const rest=content.slice(match.index),nextHeader=rest.indexOf(`
+## `,1);return(nextHeader===-1?rest:rest.slice(0,nextHeader)).trim()}function normalizeWhitespace(s){return s.replace(/\s+/g," ").trim()}export function checkGovernanceSections(config,targetDir){const results=[],agentsPath=join(targetDir,"AGENTS.md"),currentIronLaws=extractIronLawsBlock(renderAgentsMd(config));if(!existsSync(agentsPath))results.push({file:"AGENTS.md",section:"Iron Laws",stale:!0,detail:"file missing"});else{const materializedIronLaws=extractIronLawsBlock(readFileTranslated(agentsPath,"utf-8")),stale=materializedIronLaws===null||normalizeWhitespace(materializedIronLaws)!==normalizeWhitespace(currentIronLaws??"");results.push({file:"AGENTS.md",section:"Iron Laws",stale,detail:materializedIronLaws===null?"section missing":"content differs from current template"})}const settingsPath=join(targetDir,".claude","settings.json"),currentDeny=JSON.parse(renderTemplate("claude/settings.json.ejs",buildClaudeRenderContext(config))).permissions.deny;if(!existsSync(settingsPath))results.push({file:".claude/settings.json",section:"deny list",stale:!0,detail:"file missing"});else{let materializedDeny=[],malformed=!1;try{const deny=parseExistingSettings(settingsPath).permissions?.deny;Array.isArray(deny)?materializedDeny=deny:malformed=!0}catch(err){const msg=err instanceof Error?err.message:String(err);process.stderr.write(`[diff] .claude/settings.json: ${msg}
+`),malformed=!0}if(malformed)return results.push({file:".claude/settings.json",section:"deny list",stale:!0,detail:"malformed settings.json"}),results;const missing=currentDeny.filter(d=>!materializedDeny.includes(d));results.push({file:".claude/settings.json",section:"deny list",stale:missing.length>0,detail:missing.length>0?`missing entries: ${missing.join(", ")}`:""})}return results}function actionToStatus(action){return action==="created"?"new":action==="skipped"?"unchanged":"changed"}function buildRemoteSideEffects(permitGitHub,githubOwner,githubRepo){if(!permitGitHub||!githubOwner||!githubRepo)return[];const target=`${githubOwner}/${githubRepo}`;return[{op:"provision-labels",target},{op:"apply-branch-protection",target},{op:"create-project-board",target}]}function buildDiffFiles(results,targetDir){return results.map(r=>{const rel=relative(targetDir,r.path),status=r.excluded==="ignored"?"ignored":r.withheld===!0&&r.adopted!==!0?"withheld":actionToStatus(r.action);return{key:rel,status,action:r.action,path:rel}})}function printFileLine(f){f.status==="new"?process.stdout.write(`${t("cli.diff.new_file",{key:f.key})}
+`):f.status==="changed"?process.stdout.write(`${t("cli.diff.changed_file",{key:f.key})}
+`):f.status==="ignored"?process.stdout.write(`${t("cli.diff.ignored_file",{key:f.key})}
+`):process.stdout.write(`${t("cli.diff.unchanged_file",{key:f.key})}
+`)}function printWithheldSection(withheld){if(withheld.length!==0){process.stdout.write(`${t("cli.diff.withheld_header",{count:withheld.length})}
+`);for(const f of withheld)process.stdout.write(`${t("cli.diff.withheld_file",{key:f.key})}
+`);process.stdout.write(`${t("cli.diff.withheld_hint")}
+`)}}function printHuman(files,remote,hasChanges,withheldOnly){const withheld=files.filter(f=>f.status==="withheld");if(withheldOnly){printWithheldSection(withheld);return}for(const f of files)f.status!=="withheld"&&printFileLine(f);if(remote.length>0){process.stdout.write(`${t("cli.diff.remote_header")}
+`);for(const r of remote)process.stdout.write(`${t("cli.diff.remote_effect",{op:r.op,target:r.target})}
+`)}printWithheldSection(withheld),hasChanges?process.stdout.write(`${t("cli.diff.run_update")}
+`):withheld.length===0&&process.stdout.write(`${t("cli.diff.up_to_date")}
+`)}function printGovernanceReport(config,targetDir,json){const sections=checkGovernanceSections(config,targetDir),stale=sections.filter(s=>s.stale);if(json){jsonOutput("diff",stale.length>0?"warning":"ok",{sections}),stale.length>0&&process.exit(statusToExitCode("warning"));return}for(const s of sections)s.stale&&process.stdout.write(`${t("cli.diff.governance_stale_section",{file:s.file,section:s.section,detail:s.detail})}
+`);stale.length>0&&(process.stdout.write(`${t("cli.diff.governance_stale_footer")}
+`),process.exit(1)),process.stdout.write(`${t("cli.diff.governance_up_to_date")}
+`)}export function runDiff(options){const targetDir=resolve(options.dir??process.cwd());options.json||process.stdout.write(`${t("cli.diff.banner")}
+`);const stored=loadConfig(targetDir);if(!stored){options.json?jsonOutput("diff","error",{},["No arbiter.json found. Run `arbiter init` first."]):process.stdout.write(`${t("cli.diff.no_config")}
+`),process.exit(statusToExitCode("error"));return}const projectName=slugifyProjectName(resolveProjectName(targetDir,stored)),{config}=resolveProjectConfig(targetDir,projectName,stored);if(options.governance){printGovernanceReport(config,targetDir,options.json===!0);return}const claudeHome=process.env.HOME?`${process.env.HOME}/.claude`:"",installedSkills=detectInstalledSkills({targetDir,claudeHome}),specs=buildRegistry(config,installedSkills),prevManifest=loadGeneratedManifest(targetDir);beginGenerationSession({targetDir,prevHashes:prevManifest,onWithheld:()=>{},adoptPredicate:buildAdoptPredicate({}),selectPredicate:buildSelectionPredicate({patterns:loadIgnorePatterns(targetDir),only:[]})});let results;try{results=runGeneratorsFromRegistry(specs,[],{dryRun:!0})}finally{endGenerationSession()}const allFiles=buildDiffFiles(results,targetDir),withheldCount=allFiles.filter(f=>f.status==="withheld").length,files=options.withheld?allFiles.filter(f=>f.status==="withheld"):allFiles,remoteSideEffect=buildRemoteSideEffects(gitHubPermitted(stored),config.githubOwner,config.githubRepo),hasChanges=allFiles.some(f=>f.status!=="unchanged"&&f.status!=="withheld"&&f.status!=="ignored");if(options.json){const status=hasChanges||withheldCount>0?"warning":"ok";jsonOutput("diff",status,{hasChanges,files,remoteSideEffect,withheldCount});const code=statusToExitCode(status);code!==0&&process.exit(code);return}printHuman(files,remoteSideEffect,hasChanges,options.withheld===!0)}

package/dist/commands/doc-set.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: Apache-2.0
+import{fileURLToPath}from"node:url";import{resolve}from"node:path";import{runCli,CliError}from"../utils/run-cli.js";import{jsonOutput}from"../utils/json-output.js";function packageRoot(){return resolve(fileURLToPath(import.meta.url),"../../..")}function buildEngineArgs(opts){const args=[];return opts.json&&args.push("--json"),opts.arc42?opts.updateBaseline?[...args,"--update-baseline"]:args:(opts.manifest&&args.push("--manifest",opts.manifest),opts.profile&&args.push("--profile",opts.profile),opts.freshness||(opts.strict&&args.push("--strict"),opts.generate&&args.push("--generate"),opts.refreshStubs&&args.push("--refresh-stubs")),args)}function engineFor(opts){return opts.arc42?"scripts/check-arc42-slots.mjs":opts.freshness?"scripts/check-doc-freshness.mjs":"scripts/check-doc-set.mjs"}function runEngine(script,args,repo){try{const r=runCli("node",[script,...args],{cwd:repo});return{stdout:r.stdout,stderr:r.stderr,exitCode:0}}catch(err){return err instanceof CliError?{stdout:err.stdout,stderr:err.stderr,exitCode:err.exitCode>=0?err.exitCode:2}:{stdout:"",stderr:`doc-set: engine failed \u2014 ${err instanceof Error?err.message:String(err)}
+`,exitCode:2}}}function parsePayload(stdout,jsonRequested){if(!jsonRequested)return null;const text=stdout.trim();if(!text.startsWith("{"))return null;try{return JSON.parse(text)}catch{return null}}export function runDocSet(opts={}){const repo=opts.repo?resolve(opts.repo):process.cwd(),script=resolve(packageRoot(),engineFor(opts)),{stdout,stderr,exitCode}=runEngine(script,buildEngineArgs(opts),repo),payload=parsePayload(stdout,!!opts.json);return opts.quiet||(opts.json?jsonOutput("doc-set",exitCode===0?"ok":exitCode===1?"warning":"error",payload===null?{}:{...payload}):stdout&&process.stdout.write(stdout),stderr&&process.stderr.write(stderr)),{exitCode,payload}}

package/dist/commands/doctor/clean.js

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: Apache-2.0
+import{realpathSync}from"node:fs";import{resolve}from"node:path";import{walkDir}from"../../utils/walk-dir.js";import{jsonOutput}from"../../utils/json-output.js";import{unlinkTranslated}from"../../utils/fs.js";const CLEAN_SKIP_DIRS=new Set(["node_modules",".git","dist"]);function isBackupFile(name){return name.endsWith(".arbiter-backup")||/^\.arbiter-generated\.json\.bak\./.test(name)}function collectBackups(dir,out){out.push(...walkDir(dir,{skipDirs:CLEAN_SKIP_DIRS,filter:name=>isBackupFile(name),errorMode:"fs-soft"}))}export function runDoctorClean(opts={}){const rawDir=resolve(opts.dir??".");let targetDir;try{targetDir=realpathSync(rawDir)}catch{targetDir=rawDir}const found=[];collectBackups(targetDir,found);const deleted=[];if(!opts.dryRun)for(const f of found)try{unlinkTranslated(f),deleted.push(f)}catch{}return opts.json&&jsonOutput("doctor clean","ok",{found,deleted}),{found,deleted}}

package/dist/commands/doctor/fail-open-census.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+import{existsSync,readdirSync,statSync}from"node:fs";import{join,relative,resolve}from"node:path";import{jsonOutput}from"../../utils/json-output.js";import{readFileTranslated}from"../../utils/fs.js";const SCAN_SUBDIRS=["scripts",".githooks"],SKIP_DIR_NAMES=new Set(["node_modules",".git","data"]);function listScanFiles(dir){const out=[];for(const sub of SCAN_SUBDIRS)walk(join(dir,sub),out);return out}function walk(current,out){let entries;try{entries=readdirSync(current)}catch{return}for(const entry of entries){const full=join(current,entry);let stat;try{stat=statSync(full)}catch{continue}if(stat.isDirectory()){if(SKIP_DIR_NAMES.has(entry))continue;walk(full,out)}else stat.isFile()&&out.push(full)}}function lineOf(text,index){return text.slice(0,index).split(`
+`).length}const BRACE_FORM_RE=/command\s+-v\s+(\S+)[^\n]*\|\|\s*\{[^}]*\b(?:return|exit)\s+0\b/g,BARE_FORM_RE=/command\s+-v\s+(\S+)[^\n]*\|\|\s*exit\s+0\b/g,IF_GUARD_RE=/if\s*!\s*command\s+-v\s+(\S+)/g,POSITIVE_IF_GUARD_RE=/(?<!el)\bif\s+command\s+-v\s+(\S+)/g;function findMatchingFi(lines,startLine){let depth=1;for(let i=startLine;i<lines.length;i++){const line=lines[i]??"";if(/\bif\b(?!\s*!\s*command)/.test(line)&&/;\s*then\s*$|then\s*$/.test(line)&&depth++,/(?:^|[;\s])fi(?:[;\s]|$)/.test(line)&&(depth--,depth===0))return i}return lines.length-1}function findGuardFindings(text,file,re,isFailOpen){const lines=text.split(`
+`),findings=[];for(const m of text.matchAll(re)){const tool=m[1];if(!tool)continue;const startLine=lineOf(text,m.index),blockStartIdx=startLine,fiIdx=findMatchingFi(lines,blockStartIdx);isFailOpen(lines.slice(blockStartIdx,fiIdx+1))&&findings.push({file,line:startLine,tool})}return findings}function hasZeroExit(blockLines){return/\b(?:return|exit)\s+0\b/.test(blockLines.join(`
+`))}function hasNoBlockingElse(blockLines){let depth=1,elseIdx=-1;for(let i=1;i<blockLines.length;i++){const line=blockLines[i]??"";/\bif\b(?!\s*!\s*command)/.test(line)&&/;\s*then\s*$|then\s*$/.test(line)&&depth++,/^\s*else\b/.test(line)&&depth===1&&(elseIdx=i),/(?:^|[;\s])fi(?:[;\s]|$)/.test(line)&&depth--}if(elseIdx===-1)return!0;const elseLines=blockLines.slice(elseIdx);elseLines[0]=elseLines[0]?.replace(/^\s*else\b/,"")??"";const last=elseLines.length-1;elseLines[last]=elseLines[last]?.replace(/(?:^|;)\s*fi(?:[;\s]|$).*$/,"")??"";const elseBody=elseLines.join(`
+`).trim();return elseBody===""?!0:elseBody.split(/[;\n]/).every(command=>/^(?:#.*|(?:echo|printf)\b.*|:\s*(?:#.*)?)$/.test(command.trim()))}function scanFileText(text,file){const joined=text.replace(/\\\n/g," "),findings=[];for(const m of joined.matchAll(BRACE_FORM_RE)){const tool=m[1];tool&&findings.push({file,line:lineOf(joined,m.index),tool})}for(const m of joined.matchAll(BARE_FORM_RE)){const tool=m[1];tool&&findings.push({file,line:lineOf(joined,m.index),tool})}return findings.push(...findGuardFindings(joined,file,IF_GUARD_RE,hasZeroExit)),findings.push(...findGuardFindings(joined,file,POSITIVE_IF_GUARD_RE,hasNoBlockingElse)),findings}function loadAllowlist(path){if(!existsSync(path))return{entries:[],malformed:!1};const entries=JSON.parse(readFileTranslated(path,"utf-8")).entries??[],malformed=entries.some(e=>!e.reason||e.reason.trim()==="");return{entries,malformed}}function applyAllowlist(findings,allowlist){return findings.map(f=>{const match=allowlist.find(e=>e.file===f.file&&e.line===f.line&&e.reason);return match?.reason?{...f,allowlisted:match.reason}:f})}function emitTextOutput(findings){if(process.stdout.write(`
+`),findings.length===0){process.stdout.write(`  no fail-open patterns found
+
+`);return}for(const f of findings){const suffix=f.allowlisted?`  (allowlisted: ${f.allowlisted})`:"";process.stdout.write(`  ${f.file}:${f.line}  command -v ${f.tool}${suffix}
+`)}process.stdout.write(`
+`)}export function runDoctorFailOpenCensus(opts={}){const dir=resolve(opts.dir??"."),allowlistPath=opts.allowlistPath??join(dir,".arbiter","fail-open-allowlist.json"),{entries,malformed}=loadAllowlist(allowlistPath);if(malformed)return opts.json?jsonOutput("doctor fail-open-census","error",{findings:[]},["Allowlist entry missing a reason \u2014 every entry must justify its suppression."],{errorClass:"config"}):process.stderr.write(`  Error: allowlist entry missing a reason (${relative(dir,allowlistPath)})
+`),{exitCode:2,findings:[]};const rawFindings=listScanFiles(dir).flatMap(path=>scanFileText(readFileTranslated(path,"utf-8"),relative(dir,path))).sort((a,b)=>a.file===b.file?a.line-b.line:a.file.localeCompare(b.file)),findings=applyAllowlist(rawFindings,entries),exitCode=findings.filter(f=>!f.allowlisted).length>0?1:0;return opts.json?jsonOutput("doctor fail-open-census",exitCode===0?"ok":"error",{findings}):emitTextOutput(findings),{exitCode,findings}}

package/dist/commands/doctor/health.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+import{existsSync,readdirSync}from"node:fs";import{join,resolve}from"node:path";import os from"node:os";import{jsonOutput}from"../../utils/json-output.js";import{loadConfig}from"../../utils/config.js";import{runCli}from"../../utils/run-cli.js";import{forceReleaseLock,isLockStale,readLockInfo}from"../../utils/file-lock.js";import{ArbiterError}from"../../utils/errors.js";import{resolveChannel}from"../../utils/channel.js";import{detectLanguage}from"../../detectors/language.js";import{detectExternalModel}from"../../detectors/external-model.js";import{runProbes}from"../../compatibility/probe.js";import{isArbiterSelf}from"../ship-profile.js";import{diagnoseCompanions}from"../../integrations/companions.js";import{checkScaffoldWiring}from"../../detectors/scaffold-wiring.js";import{isValidPhase}from"../task-state.js";import{validateCollaborationCoherence,validateOverlayCoherence,validateAutonomyCoherence,validateProfileCoherence,validateLanguageArchetypeCoherence,validateTrunkSoloParityCoherence}from"../wizard/coherence.js";import{resolveCollaborationMode}from"../../config/collaboration-mode-defaults.js";import{deriveGateKey,gateLockPath}from"../gate-exec.js";import{readFileTranslated}from"../../utils/fs.js";function readRawCoherenceConfig(dir){try{return JSON.parse(readFileTranslated(join(dir,"arbiter.json"),"utf8"))}catch{return null}}function checkNodeVersion(){const nodeVer=process.versions.node,nodeMajor=parseInt(nodeVer.split(".")[0]??"0",10),check={id:"node-version",label:"Node.js version >= 22",status:nodeMajor>=22?"PASS":"FAIL",detail:`found ${nodeVer}`};return nodeMajor<22&&(check.hint="Upgrade to Node.js >= 22. See https://nodejs.org/en/download."),check}function checkGitAvailable(dir){let gitOk=!1;try{gitOk=runCli("git",["--version"],{cwd:dir,timeoutMs:3e3}).exitCode===0}catch{}const check={id:"git-available",label:"git installed",status:gitOk?"PASS":"FAIL",detail:gitOk?"git found in PATH":"git not found in PATH"};return gitOk||(check.hint="Install git from https://git-scm.com."),[check,gitOk]}function checkArbiterProject(dir,gitOk,claudeHome){const out=[];if(!existsSync(join(dir,"arbiter.json")))return out;const agentsPresent=existsSync(join(dir,"AGENTS.md")),agentsCheck={id:"agents-md",label:"AGENTS.md present",status:agentsPresent?"PASS":"WARN",detail:agentsPresent?"found":"not found"};if(agentsPresent||(agentsCheck.hint="Run `arbiter init` to generate AGENTS.md."),out.push(agentsCheck),out.push({id:"integrations",label:"Skill integrations discoverable",status:"PASS",detail:"advisory \u2014 review the detected and recommended skills in your configured integrations.",hint:"Review your configured integrations and installed skills."}),out.push(checkExternalModelHealth()),gitOk){let hooksPath="";try{hooksPath=runCli("git",["config","core.hooksPath"],{cwd:dir,timeoutMs:3e3}).stdout.trim()}catch{}const hooksCheck={id:"hooks-path",label:"git hooks path configured",status:hooksPath.length>0?"PASS":"WARN",detail:hooksPath.length>0?`core.hooksPath = ${hooksPath}`:"core.hooksPath not set"};hooksPath.length===0&&(hooksCheck.hint="Run `git config core.hooksPath .githooks` to enable hooks."),out.push(hooksCheck)}return out.push(checkGateScript(dir)),out.push(checkGateToolchain(dir)),out.push(checkGateMutex(dir)),out.push(checkScaffoldWiringHealth(dir)),out.push(...checkLockfiles(dir)),out.push(checkCollaborationCoherence(dir)),out.push(checkLanguageArchetypeCoherence(dir)),out.push(checkOverlayCoherence(dir)),out.push(checkAutonomyCoherence(dir)),out.push(checkProfileCoherence(dir)),out.push(checkTrunkSoloParityWiring(dir)),out.push(checkCompanionHealth(dir,claudeHome)),out.push(checkBypassCeremony(dir)),out}function checkExternalModelHealth(){const access=detectExternalModel("codex"),version=access.version?`codex ${access.version}`:"codex";return access.available?access.authenticated?{id:"external-model-codex",label:"External Codex reviewer",status:"PASS",detail:`${version}: authenticated`}:{id:"external-model-codex",label:"External Codex reviewer",status:"WARN",detail:`${version}: not authenticated`,hint:"Authenticate the Codex CLI before enabling cross-model review."}:{id:"external-model-codex",label:"External Codex reviewer",status:"WARN",detail:`${version}: ${access.error??"unavailable"}`,hint:"Install the Codex CLI to enable the optional cross-model review slot."}}function checkCompanionHealth(dir,claudeHome){const base={id:"companions",label:"Companions",status:"PASS"};if(isArbiterSelf(dir))return{...base,detail:"companions never activate on arbiter-self (its own complexity is load-bearing)"};const cfg=readRawCoherenceConfig(dir),rows=diagnoseCompanions({claudeHome:claudeHome??join(os.homedir(),".claude"),language:detectLanguage(dir),...cfg?.companions?{overrides:cfg.companions}:{}});if(rows.length===0)return{...base,detail:"no known companions in the registry"};const detail=rows.map(r=>r.installed?r.disabledByConfig?`${r.label}: detected, disabled by config`:`${r.label}: detected, mode=${r.mode} (${r.modeSource})`:`${r.label}: not installed`).join("; ");return{...base,detail}}function checkGateScript(dir){const present=existsSync(join(dir,"scripts","check-all.mjs")),check={id:"gate-script",label:"gate script (scripts/check-all.mjs) present",status:present?"PASS":"WARN",detail:present?"found":"scripts/check-all.mjs not found"};return present||(check.hint="Run `arbiter init` (or `arbiter update`) to (re)generate the gate."),check}function checkGateToolchain(dir){const check={id:"gate-toolchain",label:"gate toolchain installed (tools check-all.mjs invokes)",status:"PASS",detail:"all required gate tools resolve"};let report;try{report=runProbes(dir)}catch(err){return check.status="WARN",check.detail=`could not probe gate toolchain: ${err instanceof Error?err.message:String(err)}`,check}const failed=report.probes.filter(p=>p.status==="failed").map(p=>p.tool),missing=report.probes.filter(p=>p.status==="skipped"&&p.reason==="toolchain-missing").map(p=>p.tool);if(failed.length===0&&missing.length===0)return check.detail=`all gate tools resolve for ${report.stack}`,check;check.status=failed.length>0?"FAIL":"WARN";const parts=[];return missing.length>0&&parts.push(`not installed: ${missing.join(", ")}`),failed.length>0&&parts.push(`broken/incompatible: ${failed.join(", ")}`),check.detail=`gate would error on first run \u2014 ${parts.join("; ")}`,check.hint="Install the gate toolchain (e.g. `npm install` for the declared devDependencies) before running `node scripts/check-all.mjs L1`.",check}function checkGateMutex(dir){const id="gate-mutex",label="gate-exec mutex";let lockPath;try{lockPath=gateLockPath(deriveGateKey(dir))}catch(err){return{id,label,status:"WARN",detail:`could not derive gate mutex path: ${err instanceof Error?err.message:String(err)}`}}try{runCli("flock",["--version"],{cwd:dir,timeoutMs:3e3})}catch{return{id,label,status:"WARN",detail:`mutex ${lockPath}; flock(1) is unavailable, so holder/waiter count cannot be inspected`,hint:"Install util-linux flock to inspect the gate mutex."}}const helperPath=resolve(dir,"scripts","lib","waiter-count.mjs");if(!existsSync(helperPath))return{id,label,status:"WARN",detail:`mutex ${lockPath}; waiter-count helper is missing at ${helperPath}`,hint:"Run `arbiter update` to restore scripts/lib/waiter-count.mjs."};try{const{stdout}=runCli("node",[helperPath,lockPath],{cwd:dir,timeoutMs:5e3}),count=Number(stdout.trim());return!Number.isInteger(count)||count<0?{id,label,status:"WARN",detail:`mutex ${lockPath}; waiter-count helper returned invalid output: ${JSON.stringify(stdout.trim())}`,hint:"Run `arbiter update` to restore scripts/lib/waiter-count.mjs."}:count>2?{id,label,status:"WARN",detail:`mutex ${lockPath}; ${count} supervisor/holder/waiter process(es) currently have the lock open`,hint:"Inspect the process groups; do not kill only flock while its gated command is running."}:{id,label,status:"PASS",detail:`mutex ${lockPath}; ${count} supervisor/holder/waiter process(es) currently have the lock open (a normal gate-exec uses two: Node holder + detached supervisor)`}}catch{return{id,label,status:"WARN",detail:`mutex ${lockPath}; waiter-count helper could not be run`,hint:"Run `arbiter update` to restore scripts/lib/waiter-count.mjs."}}}function checkScaffoldWiringHealth(dir){const{unwired}=checkScaffoldWiring(dir);if(unwired.length===0)return{id:"scaffold-wiring",label:"gate scripts referenced by check-all.mjs/run.sh/Makefile",status:"PASS",detail:"every scripts/check-*.mjs is referenced or declared optional"};const names=unwired.map(u=>u.path).join(", ");return{id:"scaffold-wiring",label:"gate scripts referenced by check-all.mjs/run.sh/Makefile",status:"WARN",detail:`${unwired.length} script(s) not referenced by check-all.mjs, run.sh, or Makefile: ${names}`,hint:"Wire each into check-all.mjs (or run.sh/Makefile) if it should run, or remove it if dead."}}function checkProfileCoherence(dir){const check={id:"profile-coherence",label:"automation profile (worktrees / gate-level) coherence",status:"PASS",detail:"coherent"},cfg=readRawCoherenceConfig(dir);if(cfg===null)return check.status="WARN",check.detail="could not read arbiter.json for profile-coherence check",check;if(cfg.governanceLevel===void 0)return check.status="WARN",check.detail="governanceLevel missing from arbiter.json \u2014 cannot check profile coherence",check.hint="Run `arbiter update` to repair the governanceLevel field.",check;const mode=resolveCollaborationMode(cfg),r=validateProfileCoherence(cfg.automation?.maxParallelWorktrees,cfg.automation?.defaultGateLevel,mode,cfg.governanceLevel);return r.severity==="OK"?(check.detail=`${mode} @ ${cfg.governanceLevel} \u2014 profile prefs coherent`,check):(check.status=r.severity==="CRITICAL"?"FAIL":"WARN",check.detail=r.message,r.remediation!==void 0&&(check.hint=r.remediation),check)}function checkCollaborationCoherence(dir){const check={id:"collab-coherence",label:"collaborationMode \xD7 governanceLevel coherence",status:"PASS",detail:"coherent"},cfg=readRawCoherenceConfig(dir);if(cfg===null)return check.status="WARN",check.detail="could not read arbiter.json for coherence check",check;if(cfg.collaborationMode===void 0||cfg.governanceLevel===void 0)return check.status="WARN",check.detail="collaborationMode or governanceLevel missing from arbiter.json",check.hint="Run `arbiter update` to migrate the collaborationMode axis.",check;const r=validateCollaborationCoherence(cfg.collaborationMode,cfg.governanceLevel);return r.severity==="OK"?(check.detail=`${cfg.collaborationMode} @ ${cfg.governanceLevel} \u2014 coherent`,check):(check.status=r.severity==="CRITICAL"?"FAIL":"WARN",check.detail=r.message,r.remediation!==void 0&&(check.hint=r.remediation),check)}function hasLocalCiParityCheck(dir){return existsSync(join(dir,"scripts","check-local-ci-parity.mjs"))}function hasPushGatingWired(dir){return existsSync(join(dir,".githooks","pre-push"))}function checkTrunkSoloParityWiring(dir){const check={id:"trunk-solo-parity-wiring",label:"trunk-solo local-ci-parity + push-gating",status:"PASS",detail:"not applicable (collaborationMode is not trunk-solo)"},cfg=readRawCoherenceConfig(dir);if(cfg===null)return check.detail="could not read arbiter.json for trunk-solo-parity-wiring check",check;const mode=resolveCollaborationMode(cfg),hasParityCheck=hasLocalCiParityCheck(dir),hasPushGating=hasPushGatingWired(dir),r=validateTrunkSoloParityCoherence(mode,{hasParityCheck,hasPushGating});return r.severity==="OK"?(mode!=="trunk-solo"||(check.detail="local-ci-parity check + push-gating both wired \u2014 coherent",hasWorkflowFiles(dir)&&(check.detail+=". CI workflow files present \u2014 verify `node scripts/check-local-ci-parity.mjs` is green.")),check):(check.status="FAIL",check.detail=r.message,r.remediation!==void 0&&(check.hint=r.remediation),check)}function checkLanguageArchetypeCoherence(dir){const check={id:"language-archetype-coherence",label:"language \xD7 archetype coherence",status:"PASS",detail:"coherent"},cfg=readRawCoherenceConfig(dir);if(cfg===null)return check.status="WARN",check.detail="could not read arbiter.json for language-archetype check",check;if(cfg.language===void 0||cfg.archetype===void 0)return check.detail="language or archetype absent \u2014 nothing to check",check;const r=validateLanguageArchetypeCoherence(cfg.language,cfg.archetype);return r.severity==="OK"?(check.detail=`${cfg.language} \xD7 ${cfg.archetype} \u2014 coherent`,check):(check.status="WARN",check.detail=r.message,check.hint="Pick an archetype that matches the language, or switch language.",check)}function checkOverlayCoherence(dir){const check={id:"overlay-coherence",label:"industryOverlay \xD7 governanceLevel coherence",status:"PASS",detail:"coherent"},cfg=readRawCoherenceConfig(dir);if(cfg===null)return check.status="WARN",check.detail="could not read arbiter.json for overlay-coherence check",check;const overlay=cfg.industryOverlay??"none";if(overlay==="none")return check.detail="no industry overlay configured \u2014 nothing to check",check;if(cfg.governanceLevel===void 0)return check.status="WARN",check.detail=`industryOverlay='${overlay}' set but governanceLevel missing from arbiter.json`,check.hint="Run `arbiter update` to repair the governanceLevel field.",check;const r=validateOverlayCoherence(overlay,cfg.governanceLevel);return r.severity==="OK"?(check.detail=`${overlay} @ ${cfg.governanceLevel} \u2014 coherent`,check):(check.status="WARN",check.detail=r.message,check.hint="Raise governanceLevel or change industryOverlay so the overlay's controls are gate-backed.",check)}function hasWorkflowFiles(dir){try{return readdirSync(join(dir,".github","workflows")).some(f=>f.endsWith(".yml")||f.endsWith(".yaml"))}catch{return!1}}function checkAutonomyCoherence(dir){const check={id:"autonomy-coherence",label:"automation.autonomy \xD7 governanceLevel \xD7 CI coherence",status:"PASS",detail:"coherent"},cfg=readRawCoherenceConfig(dir);if(cfg===null)return check.status="WARN",check.detail="could not read arbiter.json for autonomy-coherence check",check;const autonomy=cfg.automation?.autonomy;if(autonomy===void 0)return check.detail="no automation block configured \u2014 autonomy defaults to L0 (ask-each-step)",check;const hasCi=hasWorkflowFiles(dir);if(cfg.governanceLevel===void 0)return check.status="WARN",check.detail="automation.autonomy set but governanceLevel missing from arbiter.json \u2014 cannot check autonomy coherence",check.hint="Run `arbiter update` to repair the governanceLevel field.",check;const r=validateAutonomyCoherence(autonomy,cfg.governanceLevel,hasCi);return r.severity!=="OK"?(check.status=r.severity==="CRITICAL"?"FAIL":"WARN",check.detail=r.message,r.remediation!==void 0&&(check.hint=r.remediation),check):!hasCi&&cfg.useGitHub===!0?(check.status="WARN",check.detail="useGitHub is true but .github/workflows/ contains no workflow files \u2014 CI config drift (the autonomy check trusts the filesystem, not the flag)",check.hint="Add a workflow under .github/workflows/ or set useGitHub to false.",check):(check.detail=`autonomy ${autonomy} @ ${cfg.governanceLevel} (CI: ${hasCi?"yes":"no"}) \u2014 coherent`,check)}const LOCK_CHECK_ID="arbiter-lock",DOCTOR_LOCK_STALE_AGE_MS=6*36e5;export const MANAGED_LOCKS=[{rel:join(".arbiter",".lock"),id:LOCK_CHECK_ID},{rel:join(".arbiter","kit.lock"),id:"arbiter-kit-lock"}];function checkLockHealth(dir,rel,id){const lockPath=join(dir,rel);if(!existsSync(lockPath))return{id,label:`${rel} not present`,status:"PASS",detail:"no leftover lock file"};const info=readLockInfo(lockPath);if(info===null)return{id,label:`${rel} unreadable`,status:"WARN",detail:"lock file exists but contents are not valid JSON",hint:"Run `arbiter doctor recover-lock` to remove it."};const ageMs=Date.now()-new Date(info.startedAt).getTime(),ageH=Math.round(ageMs/36e5),sameHost=info.hostname===os.hostname();return isLockStale(info,DOCTOR_LOCK_STALE_AGE_MS)?{id,label:`${rel} stale`,status:"WARN",detail:`pid ${info.pid}, age ${ageH}h, cmd: ${info.cmd}`,hint:"Run `arbiter doctor recover-lock` to clean up."}:{id,label:`${rel} active`,status:"PASS",detail:`pid ${info.pid}, age ${ageH}h${sameHost?"":" (other host)"}`}}function checkLockfiles(dir){return MANAGED_LOCKS.map(({rel,id})=>checkLockHealth(dir,rel,id))}function checkGatePassLog(dir){const logPath=join(dir,".arbiter","gate-pass.jsonl");if(!existsSync(logPath))return{id:"gate-pass-log",label:"gate-pass log",status:"PASS",detail:"not created yet \u2014 run the gate to start logging"};const lines=readFileTranslated(logPath,"utf-8").split(`
+`).filter(l=>l.trim()),parsed=[],parseErrors=[];for(let i=0;i<lines.length;i++){const line=lines[i]??"";try{const entry=JSON.parse(line);parsed.push(`${(entry.sha??"unknown").slice(0,7)} @ ${entry.signedAt??"?"} [${entry.level??"?"}]`)}catch(err){parseErrors.push(`line ${i+1}: ${err instanceof Error?err.message:String(err)}`)}}if(parseErrors.length>0)return{id:"gate-pass-log",label:"gate-pass log",status:"WARN",detail:`${lines.length} entries, ${parseErrors.length} unparseable: ${parseErrors.slice(0,3).join("; ")}`,hint:"Inspect .arbiter/gate-pass.jsonl for corrupt lines."};const recent=parsed.slice(-5);return{id:"gate-pass-log",label:"gate-pass log",status:"PASS",detail:`${lines.length} entries; last ${recent.length}: ${recent.join(", ")}`}}function bypassCeremonyWarn(detail){return{id:"bypass-ceremony",label:"bypass ceremony budget",status:"WARN",detail}}function runBypassCeremonyScript(dir,scriptPath){let result;try{result=runCli("node",[scriptPath,"--json","--root",dir],{cwd:dir,timeoutMs:15e3})}catch(err){return bypassCeremonyWarn(`could not run bypass-ceremony check: ${err instanceof Error?err.message:String(err)}`)}try{return{result,parsed:JSON.parse(result.stdout)}}catch{return bypassCeremonyWarn("bypass-ceremony check produced unparseable output")}}function toBypassCeremonyCheck(result,parsed){const channels=parsed.channels??[],ledgerViolations=parsed.ledgerViolations??[],rateViolations=parsed.rateViolations??[],channelSummary=channels.length>0?channels.map(c=>`${c.env}: ${c.count}/${c.ceiling}`).join(", "):"no bypass-log channels in the trailing 30 days";return result.exitCode!==0||ledgerViolations.length>0||rateViolations.length>0?{id:"bypass-ceremony",label:"bypass ceremony budget",status:"FAIL",detail:[...rateViolations,...ledgerViolations].slice(0,3).join("; ")||`channels: ${channelSummary}`,hint:"Run `node scripts/check-bypass-ceremony.mjs` for the full report."}:{id:"bypass-ceremony",label:"bypass ceremony budget",status:"PASS",detail:`channels: ${channelSummary}`}}function checkBypassCeremony(dir){const scriptPath=join(dir,"scripts","check-bypass-ceremony.mjs");if(!existsSync(scriptPath))return isArbiterSelf(dir)?bypassCeremonyWarn("scripts/check-bypass-ceremony.mjs not found"):{id:"bypass-ceremony",label:"bypass ceremony budget",status:"PASS",detail:"not configured for this project"};const outcome=runBypassCeremonyScript(dir,scriptPath);return"id"in outcome?outcome:toBypassCeremonyCheck(outcome.result,outcome.parsed)}function checkChannelSetting(dir,channelFlag){try{const config=loadConfig(dir),resolved=resolveChannel({...channelFlag!==void 0&&{flag:channelFlag},...config?.channel!==void 0&&{config:config.channel}});return{id:"release-channel",label:"release channel",status:"PASS",detail:`${resolved.value} (${resolved.source})`}}catch(err){return{id:"release-channel",label:"release channel",status:"FAIL",detail:err instanceof Error?err.message:String(err),hint:"Fix or delete arbiter.json and re-run `arbiter init`."}}}function emitHealthOutput(checks,pass,warn,fail){process.stdout.write(`
+`);for(const check of checks){const icon=check.status==="PASS"?"[PASS]":check.status==="WARN"?"[WARN]":"[FAIL]";process.stdout.write(`  ${icon}  ${check.label}  \u2014 ${check.detail}
+`),check.hint&&process.stdout.write(`         hint: ${check.hint}
+`)}process.stdout.write(`
+  ${pass} passed, ${warn} warnings, ${fail} failed
+
+`)}function checkTaskDocument(dir){const statusPath=join(dir,".claude",".task","status.json"),id="task-document",label="unified task document";if(!existsSync(statusPath))return{id,label,status:"PASS",detail:"no active task (.claude/.task/ absent)"};try{const state=JSON.parse(readFileTranslated(statusPath,"utf-8"));return typeof state.phase!="string"||!isValidPhase(state.phase)?{id,label,status:"WARN",detail:`.claude/.task/status.json has an invalid phase: ${JSON.stringify(state.phase)}`,hint:"Re-run `arbiter task init` / `arbiter task advance` to repair task state."}:{id,label,status:"PASS",detail:`active task ${state.taskId||"(unset)"} at phase=${state.phase}`}}catch(err){return{id,label,status:"WARN",detail:`.claude/.task/status.json is not valid JSON \u2014 ${err instanceof Error?err.message:String(err)}`,hint:"Delete .claude/.task/ and re-initialise with `arbiter task init`."}}}export async function runDoctorHealth(opts={}){const dir=resolve(opts.dir??"."),[gitCheck,gitOk]=checkGitAvailable(dir),checks=[checkNodeVersion(),gitCheck,...checkArbiterProject(dir,gitOk,opts.claudeHome),checkChannelSetting(dir,opts.channelFlag),checkTaskDocument(dir),checkGatePassLog(dir)];let repaired;opts.repair&&(repaired=await repairStaleLockInChecks(dir,checks));const pass=checks.filter(c=>c.status==="PASS").length,warn=checks.filter(c=>c.status==="WARN").length,fail=checks.filter(c=>c.status==="FAIL").length;return opts.json?jsonOutput("doctor health",fail>0?"error":"ok",{checks,pass,warn,fail,...repaired?{repaired}:{}}):(emitHealthOutput(checks,pass,warn,fail),repaired&&process.stdout.write(`  repaired: released stale lock pid ${repaired.pid}
+
+`)),{exitCode:fail>0?1:0,checks,pass,warn,fail,...repaired?{repaired}:{}}}async function repairStaleLockInChecks(dir,checks){let firstRepaired;for(const{rel,id}of MANAGED_LOCKS){const lockCheck=checks.find(c=>c.id===id);if(!lockCheck||lockCheck.status!=="WARN")continue;const lockPath=join(dir,rel),info=readLockInfo(lockPath);if(info){try{await forceReleaseLock(lockPath,info.pid,dir)}catch(err){lockCheck.hint=err instanceof ArbiterError?`auto-repair failed: ${err.message}`:`auto-repair failed: ${err instanceof Error?err.message:String(err)}`;continue}lockCheck.status="PASS",lockCheck.label=`${rel} released (auto-repaired)`,lockCheck.detail=`released stale lock pid ${info.pid}`,delete lockCheck.hint,firstRepaired??={lockPath,pid:info.pid}}}return firstRepaired}

package/dist/commands/doctor/prove-gates.js

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+import{jsonOutput}from"../../utils/json-output.js";import{runGateProofs}from"../../conformance/gate-proofs.js";function emitProveGatesOutput(results){process.stdout.write(`
+arbiter doctor --prove-gates \u2014 negative proof per tier-1 gate
+
+`);for(const r of results){const label=r.bites?"[BITES]":"[NO-BITE]";process.stdout.write(`  ${label} ${r.id} \u2014 ${r.title}
+`),process.stdout.write(`           violation: ${r.violation}
+`),process.stdout.write(`           verdict: ${r.verdict}${r.detail?` (${r.detail})`:""}
+`)}process.stdout.write(`
+`)}export function runDoctorProveGates(opts={}){const results=runGateProofs(),bitingCount=results.filter(r=>r.bites).length,notBitingCount=results.length-bitingCount,exitCode=notBitingCount>0?1:0;return opts.json?jsonOutput("doctor --prove-gates",exitCode===0?"ok":"error",{results,bitingCount,notBitingCount}):(emitProveGatesOutput(results),notBitingCount>0?process.stdout.write(`${notBitingCount} of ${results.length} gate(s) did NOT bite on their negative fixture.
+
+`):process.stdout.write(`All ${results.length} tier-1 gates bite on their negative fixture.
+
+`)),{exitCode,results,bitingCount,notBitingCount}}

package/dist/commands/doctor/recover-lock.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+import{existsSync}from"node:fs";import{join,resolve}from"node:path";import os from"node:os";import{jsonOutput}from"../../utils/json-output.js";import{t}from"../../i18n/index.js";import{inspectLock,forceReleaseLock,isLockStale}from"../../utils/file-lock.js";import{UserFacingError}from"../../utils/errors.js";import{MANAGED_LOCKS}from"./health.js";const RECOVER_LOCK_STALE_AGE_MS=6*36e5;function formatRefusalHolders(refusals){return refusals.map(({rel,pid,cmd,age})=>`${rel} (pid ${pid}, cmd: ${cmd}, age: ${age}s)`).join("; ")}function emitRefusedRecovery(opts,refusalMessage,summary,refusals){opts.json&&jsonOutput("doctor recover-lock","error",{found:!0,released:summary.released,...summary.firstInfo?{info:summary.firstInfo}:{},...summary.corrupt?{corrupt:!0}:{},refused:refusals},[refusalMessage])}function emitRecoveryResult(opts,targetDir,result){opts.json?jsonOutput("doctor recover-lock","ok",{found:result.found,released:result.released,...result.info?{info:result.info}:{},...result.corrupt?{corrupt:!0}:{}}):result.found||process.stdout.write(`  No lock file found in ${join(targetDir,".arbiter")}
+`)}async function recoverManagedLock(lockPath,rel,targetDir,opts){if(!existsSync(lockPath))return{found:!1,released:!1};const info=await inspectLock(lockPath);if(!info)return opts.json||process.stdout.write(`  Lock found (${rel}): CORRUPT / unreadable; removing it.
+`),await forceReleaseLock(lockPath,0,targetDir,{allowUnreadable:!0}),opts.json||process.stdout.write(`  Corrupt lock released.
+`),{found:!0,released:!0,corrupt:!0};if(!opts.json){const age=Math.round((Date.now()-new Date(info.startedAt).getTime())/1e3),onThisHost=info.hostname===os.hostname()?"yes":"no";process.stdout.write(`  Lock found (${rel}):
+`),process.stdout.write(`    pid:       ${info.pid}
+`),process.stdout.write(`    hostname:  ${info.hostname}
+`),process.stdout.write(`    cmd:       ${info.cmd}
+`),process.stdout.write(`    age:       ${age}s
+`),process.stdout.write(`    this host: ${onThisHost}
+`)}if(!opts.force&&!isLockStale(info,RECOVER_LOCK_STALE_AGE_MS)){const age=Math.round((Date.now()-new Date(info.startedAt).getTime())/1e3);return{found:!0,released:!1,info,refusal:{rel,pid:info.pid,cmd:info.cmd,age}}}return await forceReleaseLock(lockPath,info.pid,targetDir),opts.json||process.stdout.write(`  Lock released.
+`),{found:!0,released:!0,info}}export async function runDoctorRecoverLock(opts={}){const targetDir=resolve(opts.dir??".");let firstInfo,released=!1,corrupt=!1;const refusals=[];for(const{rel}of MANAGED_LOCKS){const lockPath=join(targetDir,rel),result2=await recoverManagedLock(lockPath,rel,targetDir,opts);released||=result2.released,corrupt||=result2.corrupt===!0,firstInfo??=result2.info,result2.refusal&&refusals.push(result2.refusal)}if(refusals.length>0){const holders=formatRefusalHolders(refusals),refusalMessage=t("cli.doctor.recover_lock.refused",{holders});throw emitRefusedRecovery(opts,refusalMessage,{released,firstInfo,corrupt},refusals),new UserFacingError(t("cli.doctor.recover_lock.refused",{holders}))}if(!firstInfo&&!corrupt){const result2={found:!1,released:!1};return emitRecoveryResult(opts,targetDir,result2),result2}const result={found:!0,released,...firstInfo?{info:firstInfo}:{},...corrupt?{corrupt:!0}:{}};return emitRecoveryResult(opts,targetDir,result),result}

package/dist/commands/doctor/repair-state.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+import{existsSync}from"node:fs";import{ensureDir}from"../../utils/fs.js";import{join,resolve}from"node:path";import{acquireLock}from"../../utils/file-lock.js";import{jsonOutput}from"../../utils/json-output.js";import{loadConfig,writeSnapshot}from"../../utils/config.js";const REPAIR_STATE_CMD="doctor repair-state";export async function runDoctorRepairState(opts={}){const dir=resolve(opts.dir??"."),configPath=join(dir,"arbiter.json"),snapshotPath=join(dir,".arbiter-generated.json");if(!existsSync(configPath)){const msg=`arbiter.json not found at ${configPath} \u2014 cannot repair snapshot without source-of-truth config. Run \`arbiter init\` first.`;return opts.json?jsonOutput(REPAIR_STATE_CMD,"error",{dir,configPath},[msg]):process.stderr.write(`Error: ${msg}
+`),{exitCode:2,repaired:!1,snapshotPath}}const config=loadConfig(dir);if(config===null){const msg=`failed to load ${configPath}`;return opts.json?jsonOutput(REPAIR_STATE_CMD,"error",{dir,configPath},[msg]):process.stderr.write(`Error: ${msg}
+`),{exitCode:2,repaired:!1,snapshotPath}}ensureDir(join(dir,".arbiter"));const lock=await acquireLock(join(dir,".arbiter",".lock"));try{writeSnapshot(dir,config)}finally{await lock.release()}const manifestWarning="generated-manifest (.arbiter-generated-manifest.json) is NOT re-derivable from config; if you suspect template-fix drift, re-run `arbiter update` to refresh it.";return opts.json?jsonOutput(REPAIR_STATE_CMD,"ok",{snapshotPath,repaired:!0},void 0,{warnings:[manifestWarning]}):(process.stdout.write(`doctor: snapshot re-derived from arbiter.json \u2192 ${snapshotPath}
+`),process.stderr.write(`doctor: warning \u2014 ${manifestWarning}
+`)),{exitCode:0,repaired:!0,snapshotPath}}

package/dist/commands/doctor/tool-pin-extract.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+function toSemVer(major,minor,patch){return{major:Number(major),minor:Number(minor),patch:patch?Number(patch):0}}export function compareSemVer(a,b){return a.major-b.major||a.minor-b.minor||a.patch-b.patch}function lineOf(text,index){return text.slice(0,index).split(`
+`).length}const TRUTHY_RE=/continue-on-error:\s*['"]?(\$\{\{\s*true\s*\}\}|true|on|yes|y)\b/i;function buildBlockingLineMap(workflowText){const lines=workflowText.split(`
+`),jobsIdx=lines.findIndex(l=>/^jobs:\s*$/.test(l));if(jobsIdx===-1)return()=>!0;const jobStarts=[];for(let i=jobsIdx+1;i<lines.length;i++)/^ {2}[\w-]+:\s*$/.test(lines[i]??"")&&jobStarts.push(i);const advisoryRanges=jobStarts.map((start,idx)=>({start,end:jobStarts[idx+1]??lines.length})).filter(({start,end})=>lines.slice(start,end).some(l=>TRUTHY_RE.test(l))).map(({start,end})=>({start,end}));return lineNo=>{const idx=lineNo-1;return!advisoryRanges.some(r=>idx>=r.start&&idx<r.end)}}const DOWNLOAD_URL_RE=/https:\/\/github\.com\/[\w.-]+\/([\w.-]+)\/releases\/download\/v?(\d+)\.(\d+)(?:\.(\d+))?\//g,ENV_PIN_RE=/^\s*([A-Z][A-Z0-9_]*)_VERSION\s*:\s*['"]?(\d+)\.(\d+)(?:\.(\d+))?/gm,ACTION_TAG_RE=/uses:\s*[\w.-]+\/([\w.-]+?)(?:-action)?@v?(\d+)\.(\d+)(?:\.(\d+))?/g;function extractDownloadUrlPins(text,file,isBlocking){const pins=[];for(const m of text.matchAll(DOWNLOAD_URL_RE)){const[,repo,major,minor,patch]=m;if(!repo||!major||!minor)continue;const line=lineOf(text,m.index);pins.push({tool:repo,version:toSemVer(major,minor,patch),file,line,blocking:isBlocking(line)})}return pins}function extractEnvPins(text,file,isBlocking){const pins=[];for(const m of text.matchAll(ENV_PIN_RE)){const[,prefix,major,minor,patch]=m;if(!prefix||!major||!minor)continue;const line=lineOf(text,m.index);pins.push({tool:prefix.toLowerCase(),version:toSemVer(major,minor,patch),file,line,blocking:isBlocking(line)})}return pins}function extractActionTagPins(text,file,isBlocking){const pins=[];for(const m of text.matchAll(ACTION_TAG_RE)){const[,repo,major,minor,patch]=m;if(!repo||!major||!minor)continue;const line=lineOf(text,m.index);pins.push({tool:repo,version:toSemVer(major,minor,patch),file,line,blocking:isBlocking(line)})}return pins}export function extractToolPins(workflowText,file){const isBlocking=buildBlockingLineMap(workflowText);return[...extractDownloadUrlPins(workflowText,file,isBlocking),...extractEnvPins(workflowText,file,isBlocking),...extractActionTagPins(workflowText,file,isBlocking)]}

package/dist/commands/doctor/tool-pins.js

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+import{readdirSync}from"node:fs";import{join,resolve}from"node:path";import{jsonOutput}from"../../utils/json-output.js";import{runCli,CliError}from"../../utils/run-cli.js";import{extractToolPins,compareSemVer}from"./tool-pin-extract.js";import{readFileTranslated}from"../../utils/fs.js";function formatVersion(v){return`${v.major}.${v.minor}.${v.patch}`}function parseSemVerFromVersionOutput(output){const m=/(\d+)\.(\d+)(?:\.(\d+))?/.exec(output);if(!m)return;const[,major,minor,patch]=m;if(!(!major||!minor))return{major:Number(major),minor:Number(minor),patch:patch?Number(patch):0}}function getLocalToolVersion(tool,override){if(override&&Object.prototype.hasOwnProperty.call(override,tool)){const raw=override[tool];return raw?parseSemVerFromVersionOutput(raw)??"unparseable":void 0}try{const result=runCli(tool,["--version"],{timeoutMs:5e3}),combined=`${result.stdout}
+${result.stderr}`;return parseSemVerFromVersionOutput(combined)??"unparseable"}catch(err){if(err instanceof CliError){if(err.notFound)return;const combined=`${err.stdout}
+${err.stderr}`;return parseSemVerFromVersionOutput(combined)??"unparseable"}return}}function listWorkflowFiles(dir){const wfDir=join(dir,".github","workflows");let entries;try{entries=readdirSync(wfDir)}catch{return[]}return entries.filter(f=>f.endsWith(".yml")||f.endsWith(".yaml")).map(f=>join(wfDir,f))}function dedupePins(pins){const byTool=new Map;for(const pin of pins){const existing=byTool.get(pin.tool);if(!existing){byTool.set(pin.tool,pin);continue}const merged={...compareSemVer(pin.version,existing.version)>0?pin:existing,blocking:existing.blocking||pin.blocking};byTool.set(pin.tool,merged)}return[...byTool.values()]}function buildCheck(pin,override){const id=`tool-pin-${pin.tool}`,label=`${pin.tool} version matches CI pin`,pinDetail=`pin ${formatVersion(pin.version)} (${pin.file}:${pin.line})`,local=getLocalToolVersion(pin.tool,override);if(local===void 0)return{id,label,status:pin.blocking?"FAIL":"WARN",detail:`${pin.tool} not found locally \u2014 ${pinDetail}`};if(local==="unparseable")return{id,label,status:"WARN",detail:`${pin.tool} local version output unparseable \u2014 ${pinDetail}`};const cmp=compareSemVer(local,pin.version),localDetail=`local ${formatVersion(local)}`;return cmp<0?{id,label,status:"FAIL",detail:`${pin.tool} ${localDetail} < ${pinDetail}`}:{id,label,status:"PASS",detail:`${pin.tool} ${localDetail} >= ${pinDetail}`}}function emitTextOutput(checks,pass,warn,fail){process.stdout.write(`
+`);for(const check of checks){const icon=check.status==="PASS"?"[PASS]":check.status==="WARN"?"[WARN]":"[FAIL]";process.stdout.write(`  ${icon}  ${check.label}  \u2014 ${check.detail}
+`)}process.stdout.write(`
+  ${pass} passed, ${warn} warnings, ${fail} failed
+
+`)}export function runDoctorToolPins(opts={}){const dir=resolve(opts.dir??"."),allPins=listWorkflowFiles(dir).flatMap(path=>{const text=readFileTranslated(path,"utf-8"),rel=path.slice(dir.length+1);return extractToolPins(text,rel)}),checks=dedupePins(allPins).map(pin=>buildCheck(pin,opts.localVersionOverride)),pass=checks.filter(c=>c.status==="PASS").length,warn=checks.filter(c=>c.status==="WARN").length,fail=checks.filter(c=>c.status==="FAIL").length,exitCode=fail>0?1:0;return opts.json?jsonOutput("doctor tool-pins",fail>0?"error":"ok",{checks,pass,warn,fail}):emitTextOutput(checks,pass,warn,fail),{exitCode,checks,pass,warn,fail}}

package/dist/commands/doctor-interactive.js

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: Apache-2.0
+import{intro,outro,confirm,isCancel,cancel}from"@clack/prompts";import{runDoctorHealth}from"./doctor.js";export async function runInteractiveDoctor(opts={}){const dir=opts.dir;intro("arbiter doctor");const first=await runDoctorHealth({...dir!==void 0?{dir}:{},json:!1,repair:!1});if(!first.checks.some(c=>c.status==="FAIL"&&/lock/i.test(`${c.label} ${c.detail}`))){outro(first.exitCode===0?"Healthy \u2014 nothing to repair.":"No auto-fixable issues found."),first.exitCode!==0&&(process.exitCode=first.exitCode);return}const doRepair=await confirm({message:"Fixable issue detected. Attempt repair now?"});if(isCancel(doRepair)){cancel("Cancelled.");return}if(!doRepair){outro("Skipped repair."),first.exitCode!==0&&(process.exitCode=first.exitCode);return}const repaired=await runDoctorHealth({...dir!==void 0?{dir}:{},json:!1,repair:!0});outro(repaired.exitCode===0?"Repaired \u2014 project healthy.":"Repair ran; some issues remain."),repaired.exitCode!==0&&(process.exitCode=repaired.exitCode)}

package/dist/commands/doctor.js

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: Apache-2.0
+export{runDoctorHealth}from"./doctor/health.js";export{runDoctorRepairState}from"./doctor/repair-state.js";export{runDoctorRecoverLock}from"./doctor/recover-lock.js";export{runDoctorClean}from"./doctor/clean.js";export{runDoctorProveGates}from"./doctor/prove-gates.js";export{runDoctorToolPins}from"./doctor/tool-pins.js";export{runDoctorFailOpenCensus}from"./doctor/fail-open-census.js";