@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/cli/index.js

@@ -0,0 +1,568 @@
+'use strict';
+// doflow CLI — argument parsing, the installer command table, and dispatch.
+//
+// bin/doflow.js is only a forwarder into main() here. This module owns: parseArgs (verbatim from
+// the pre-extraction monolith), the ONE table mapping the nine installer command names to their
+// handlers under commands/, and the runtime verbs' forwarding via ./runtime-commands — whose
+// implementations stay one-per-module in src/runtime/. Adding an installer command means a new
+// file in src/cli/commands/, an entry in COMMANDS, and an edit to test/guards/cli-boundary.test.js,
+// which ratchets this surface.
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+const {
+  handleCapabilitiesCommand, handleReadinessCommand, handleEvidenceCommand,
+  EVIDENCE_SCORE_FIELDS, scoreFieldRefusal,
+} = require('../runtime/cli.js');
+const { pkg } = require('./shared.js');
+const { VALID: VALID_TARGETS, DEFAULT_TARGETS } = require('../install/targets.js');
+const { dispatchRuntimeCommand } = require('./runtime-commands.js');
+const { usageError } = require('../runtime/cli-result.js');
+
+const cmdInstall = require('./commands/install.js');
+const cmdUpdate = require('./commands/update.js');
+const cmdReconcile = require('./commands/reconcile.js');
+const cmdRemove = require('./commands/remove.js');
+const cmdStatus = require('./commands/status.js');
+const cmdTools = require('./commands/tools.js');
+const cmdListBackups = require('./commands/list-backups.js');
+const cmdRollback = require('./commands/rollback.js');
+const cmdSelfUpdate = require('./commands/self-update.js');
+
+/** The installer command surface, written down once. The runtime verbs are dispatched separately
+ * (see ./runtime-commands) because their namespace is owned by the doflow-run verb table. */
+const COMMANDS                                  = {
+  install: cmdInstall,
+  update: cmdUpdate,
+  reconcile: cmdReconcile,
+  remove: cmdRemove,
+  status: cmdStatus,
+  tools: cmdTools,
+  'list-backups': cmdListBackups,
+  rollback: cmdRollback,
+  'self-update': cmdSelfUpdate,
+};
+
+/** "skip all backup protection" must be an explicit, deliberate choice, never a default combo. */
+function assertNoBackupRequiresForce(o     )       {
+  if (o.noBackup && !o.force) {
+    console.error('doflow: --no-backup skips all backup protection and requires --force');
+    process.exit(1);
+  }
+}
+
+function parseArgs(argv          )      {
+  const o      = { cmd: null, positional: [], targets: [], mcp: null, dryRun: false, force: false, adopt: false,
+    noBackup: false, prune: null, global: false, json: false, help: false, version: false,
+    tools: null, action: 'status', days: null, slug: null,
+    // Explicitly null, not absent. `handleReadinessCommand` declares defaults of `'feature'` and
+    // `'default'`, and a JavaScript default parameter fires on `undefined` — so an *absent* key
+    // silently reinstated exactly the identity defect readiness.ts fixed by failing closed.
+    taskClass: null, taskId: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '-h': case '--help': o.help = true; break;
+      case '-v': case '--version': o.version = true; break;
+      case '-n': case '--dry-run': o.dryRun = true; break;
+      case '-f': case '--force': o.force = true; break;
+      case '--adopt': o.adopt = true; break;
+      case '-g': case '--global': o.global = true; break;
+      case '--no-backup': o.noBackup = true; break;
+      case '--permissions': o.permissions = true; break;
+      case '--statusline': o.statusline = true; break;
+      case '--json': o.json = true; break;
+      case '--check': o.check = true; break;
+      // decision --action list: every decision by id, not just the live ones.
+      case '--all': o.all = true; break;
+      // lifecycle --action overview: the /do maintain view, with a larger list and a pending count.
+      case '--maintain': o.maintain = true; break;
+      // lifecycle --action release: record the previewed release instead of only previewing it.
+      case '--confirm': o.confirm = true; break;
+      // followup --action report: the report body comes from stdin instead of --file or --text.
+      case '--stdin': o.stdin = true; break;
+      // advise --action configure: these are deliberately presence-only switches.
+      case '--off': o.off = true; break;
+      case '--project': o.project = true; break;
+      // goal --action check: record the item as not met (evidence is still required, as the reason).
+      case '--unmet': o.unmet = true; break;
+      // goal --action link: move a feature that already serves another goal.
+      case '--replace': o.replace = true; break;
+      // readiness: the caller declares a decision is owed by the user. A flag rather than an
+      // inference, because nothing the runtime can see distinguishes "a decision is pending"
+      // from "nobody has looked yet", and guessing would be the gate answering unasked.
+      case '--user-decision-pending': o.userDecisionPending = true; break;
+      case '-t': case '--target': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.targets = val.split(',').map((s) => s.trim()).filter(Boolean); i++; break;
+      }
+      case '--mcp': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.mcp = val.split(',').map((s) => s.trim()).filter(Boolean); i++; break;
+      }
+      case '--tool': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.tools = val.split(',').map((s) => s.trim()).filter(Boolean); i++; break;
+      }
+      case '--action': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.action = val; o.actionGiven = true; i++; break;
+      }
+      case '--task-class': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.taskClass = val; i++; break;
+      }
+      case '--task-id': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.taskId = val; i++; break;
+      }
+      case '--stage': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.stage = val; i++; break;
+      }
+      case '--gate': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.gate = val; i++; break;
+      }
+      case '--node': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.node = val; i++; break;
+      }
+      case '--forced': o.forced = true; break;
+      case '--decision': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.decision = val; i++; break;
+      }
+      case '--note': {
+        const val = argv[i + 1];
+        if (val === undefined) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.note = val; i++; break;
+      }
+      case '--reason': {
+        const val = argv[i + 1];
+        if (val === undefined) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.reason = val; i++; break;
+      }
+      case '--query': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.query = val; i++; break;
+      }
+      case '-k': case '--top': {
+        const val = argv[i + 1];
+        const parsed = parseInt(val, 10);
+        if (!Number.isFinite(parsed) || parsed < 1) { console.error(`doflow: ${a} expects a positive number`); process.exit(2); }
+        o.top = parsed; i++; break;
+      }
+      case '--role': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a value`); process.exit(1); }
+        o.role = val; i++; break;
+      }
+      case '--days': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a number`); process.exit(2); }
+        const parsed = parseInt(val, 10);
+        // Run-ledger windows are calendar days; a zero or negative window is a typo, not "all
+        // history", and silently reading everything would answer a question nobody asked.
+        if (!Number.isFinite(parsed) || parsed < 1) { console.error(`doflow: ${a} expects a positive number of days, got '${val}'`); process.exit(2); }
+        o.days = parsed; i++; break;
+      }
+      case '--prune': {
+        const val = argv[i + 1];
+        if (val === undefined || val.startsWith('-')) { console.error(`doflow: ${a} requires a number`); process.exit(1); }
+        // Digits only: parseInt accepted `5abc` and `1.5`, and 0 is valid (keep every backup).
+        if (!/^[0-9]+$/.test(val) || Number(val) > Number.MAX_SAFE_INTEGER) { console.error(`doflow: ${a} requires a non-negative whole number, got '${val}'`); process.exit(2); }
+        o.prune = Number(val); i++; break;
+      }
+      default: {
+        // Value-taking arguments of the runtime verbs. Table-driven rather than fifteen more
+        // near-identical `case` blocks: the blocks above differ from one another only in the key
+        // they write, and copying that shape once per new verb is how one of them eventually gets
+        // its validation subtly wrong.
+        const runtime = parseRuntimeFlag(a, argv, i, o);
+        if (runtime !== null) { i = runtime; break; }
+        if (a.startsWith('-')) { console.error(`doflow: unknown flag '${a}'`); process.exit(1); }
+        else if (!o.cmd) o.cmd = a;
+        else o.positional.push(a);
+      }
+    }
+  }
+  return o;
+}
+
+/** Single-value arguments of the runtime verbs → the option key each one writes. */
+const RUNTIME_STRING_FLAGS = new Map([
+  // `scaffold`. The resolver's own ambiguous-feature error tells the caller to "re-run with
+  // --slug=<chosen>"; without this flag that hint would name an argument this CLI rejects.
+  ['--slug', 'slug'],
+  ['--rationale', 'rationale'],        // classify: why this class was proposed · decision --action add: why it was decided
+  ['--request', 'request'],            // classify: request text for an advisory second opinion
+  ['--request-file', 'requestFile'],   // classify: request text read from a file
+  // decision --action add. `--statement`, `--stage`, `--slug` and `--batch` above are shared.
+  ['--topic', 'topic'],                // the subject key a decision is live on
+  ['--channel', 'channel'],            // question | gate | prompt | default | resolution
+  ['--supersedes', 'supersedes'],      // comma-separated DEC-### ids this decision replaces
+  ['--refs', 'refs'],                  // comma-separated ids the decision touches, e.g. FR-001,IC-002
+  ['--source', 'source'],              // where the decision was stated, e.g. design/design-02-question.md#question-1
+  // followup and lifecycle (feature 046). `--statement`, `--stage`, `--slug`, `--batch`, `--reason`,
+  // `--channel`, `--state`, `--source`, `--intent`, `--task-class` and `--task-id` above are shared.
+  ['--ids', 'ids'],                    // followup: comma-separated FU-xxxxxx ids to take, settle or promote
+  ['--as', 'as'],                      // followup --action settle: kept | dismissed | fix | done
+  ['--evidence', 'evidence'],          // followup --action settle --as done: what shows it was done
+  ['--title', 'title'],                // followup --action promote: the new intent's title
+  ['--release', 'release'],            // followup --action add --source release: the release tag
+  ['--take', 'take'],                  // lifecycle --action init: comma-separated FU ids the feature takes
+  ['--goal', 'goal'],                  // lifecycle --action init: the goal the feature serves
+  ['--since', 'since'],                // lifecycle --action overview --maintain: ISO time the pass started
+  ['--file', 'file'],                  // followup --action report: the report body, read as text (at most 16 MiB)
+  ['--text', 'text'],                  // followup --action report: the report body inline (a value starting with - needs --text=...) · goal --action item: the checklist item
+  ['--tag', 'tag'],                    // lifecycle --action release: the version tag (`--version` is the CLI's own flag)
+  ['--fp', 'fp'],                      // failure --action settle: the 16 hex characters of an entry
+  ['--set', 'set'],                    // failure --action capture: on | off
+  ['--proposed-by', 'proposedBy'],     // classify: which worker proposed it
+  ['--calling-skill', 'callingSkill'],  // classify: which skill is asking, for the fit check
+  ['--intent', 'intent'],              // route: the information need being resolved
+  ['--query', 'query'],                // route: what the resolved provider would be asked
+  ['--statement', 'statement'],        // claim --action add
+  ['--claim-id', 'claimId'],           // claim --action link
+  ['--evidence-id', 'evidenceId'],     // claim --action link · evidence --action supersede
+  ['--relation', 'relation'],          // claim --action link: supports | contradicts
+  ['--role', 'role'],                  // claim --action add: the claim's relationship to the task, e.g. root-cause
+  ['--replaced-by', 'replacedBy'],     // claim --action supersede: the claim replacing this one ·
+                                        // evidence --action supersede: the evidence replacing this one
+  ['--kind', 'kind'],                  // evidence --action add: one of VALID_EVIDENCE_KINDS · advise --action ask
+  ['--server', 'server'],              // advise: MCP server for the mcp-need kind
+  ['--state-file', 'stateFile'],       // advise: request state from a UTF-8 file
+  ['--questions-file', 'questionsFile'], // advise: ad hoc question set JSON
+  ['--static', 'staticAnswer'],        // advise: explicit caller answer for comparison
+  ['--provenance', 'provenance'],      // evidence --action add: extracted | inferred | asserted
+  ['--provider', 'provider'],          // evidence --action add: source.provider
+  ['--capability', 'capability'],      // evidence --action add: source.capability
+  ['--locator', 'locator'],            // evidence --action add: 'path/file[:line]' or a URI
+  ['--content', 'content'],            // evidence --action add: the fact or the analysis itself
+  ['--establishes', 'establishes'],    // evidence --action add: requirement id(s) this item proves, comma-separated
+  ['--observed-command', 'observedCommand'], // evidence --action add: the command a test-result/runtime-observation ran
+  ['--batch', 'batchPath'],            // evidence --action add: a stage's batch file, or '-'
+  ['--verification-plan', 'verificationPlan'], // readiness: how success will be established
+  ['--mode', 'mode'],                  // readiness: execution mode, workflow (default) | standalone
+  ['--scope', 'scope'],                // readiness: the stated scope boundary; verify: the declared
+                                       // change scope, <path>[,<path>...], unioned with the plan's bound
+  ['--invariants', 'invariants'],      // readiness: the invariants a refactor must preserve
+  ['--objective', 'objective'],        // context-pack
+  ['--stage-id', 'stageId'],           // research-request: active feature stage
+  ['--question', 'question'],           // research-request: external question
+  ['--blocking', 'blocking'],           // research-request: true | false
+  ['--request-id', 'requestId'],       // research-request: request to resolve
+  ['--outcome', 'researchOutcome'],    // research-request: answered | unresolved
+  ['--gap', 'gap'],                     // research-request: unresolved reason
+  ['--stage', 'stage'],                // retrieval-plan: the stage id declaring the plan;
+                                       // outcome: the stage writing it, refused unless terminal
+  ['--state', 'state'],                // outcome: the terminal state being recorded
+  ['--result', 'result'],              // orchestrate complete-stage: the stage's own outcome, passed | failed (omit → unverified)
+  // outcome: the verdicts the run saw, stated by it and validated against the vocabulary the
+  // owning module exports. Recording an outcome never re-evaluates readiness and never re-runs
+  // verification, so these arrive as statements rather than as measurements taken here.
+  ['--readiness', 'readiness'],
+  ['--verification', 'verification'],
+  ['--risk', 'risk'],                  // verify: risk level selecting the required tiers
+  ['--pick-id', 'pickId'],             // advise --action outcome: retained pick to label
+  ['--actual', 'actual'],              // advise --action outcome: observed outcome
+  ['--model', 'model'],                // advise --action configure: installed decision-capable model
+  ['--endpoint', 'endpoint'],          // advise --action configure: loopback Ollama endpoint
+  ['--owner', 'owner'],                // brief-tools: the agent type the brief is for
+  ['--tier', 'tier'],                  // brief-tools: the task line's tier (light | standard | frontier)
+  ['--harness', 'harness'],            // brief-tools: the harness the brief is for
+  ['--heading-level', 'headingLevel'], // brief-tools: 2 (default) or 3
+  ['--tasks', 'tasks'],               // brief-tools: comma-separated plan task ids for tier advice
+  ['--plan-path', 'planPath'],         // verify: a feature plan.md whose doflow-verification
+                                       // block overrides manifest detection. Without this the
+                                       // override was implemented but unreachable (FR-011).
+  ['--verification-input', 'verificationInput'], // verify: manifest JSON file for explicit structuralChecks/requirements (IC-022)
+  ['--verification-phase', 'verificationPhase'], // verify: postimplementation (IC-022)
+  ['--baseline-ref', 'baselineRef'],             // verify: explicit ancestor commit or ref to measure change against (IC-022)
+  ['--error', 'errorMessage'],         // recover: the failure text to classify
+  ['--agent', 'agent'],                // recover: which agent produced the failure
+  ['--task', 'task'],                  // task-attempt: the plan task id, e.g. A.1
+  ['--token', 'token'],                // task-attempt finish|release: the fencing token claim returned
+]);
+
+/** Repeatable arguments — each occurrence appends rather than replaces. */
+const RUNTIME_LIST_FLAGS = new Map([
+  ['--mcp-outcome', 'mcpOutcome'],     // orchestrate handoff: <server>=<outcome>, one per MCP server the step names
+  ['--failed-check', 'failedChecks'],  // recover: check names outrank the error prose (see recovery.js)
+  // retrieval-plan: the intents a stage declares, or (on report) the ones it states it reached.
+  // Repeatable as well as comma-separated, because a plan assembled a need at a time should not
+  // have to be re-spelled as one string to be declared.
+  ['--need', 'need'],
+  ['--path', 'paths'],                 // leak-scan: the files to scan, one per occurrence
+  ['--exclude', 'exclude'],            // leak-scan: extra path segments to skip · lifecycle --action release: slugs left out
+  ['--feature', 'feature'],            // lifecycle --action release: a feature slug to add, one per occurrence
+  ['--item', 'item'],                  // goal --action add: a checklist item, one per occurrence · goal --action check: the one item id (C3)
+]);
+
+/** Non-negative integer arguments. */
+const RUNTIME_INT_FLAGS = new Map([
+  ['--iteration', 'iteration'],        // recover: retries already spent, bounding the retry budget
+  ['--observed-exit', 'observedExit'], // evidence --action add: exit status of the observed command (0 is meaningful)
+]);
+
+/**
+ * Reads one runtime-verb argument, in either `--flag value` or `--flag=value` spelling.
+ *
+ * Both spellings are accepted because the messages users copy from are not consistent about it:
+ * `do-paths.sh`'s own hint says `--slug=<chosen>` while the rest of this CLI is space-separated,
+ * and rejecting either would punish following the instructions.
+ *
+ * Returns the new loop index, or null when `arg` is not a runtime flag.
+ */
+function parseRuntimeFlag(arg        , argv          , i        , o     )                {
+  const eq = arg.indexOf('=');
+  const name = eq === -1 ? arg : arg.slice(0, eq);
+  // A score-shaped flag is refused by name rather than falling through to "unknown flag", which
+  // reads as "not built yet" and invites someone to build it. The name set and the reason both
+  // come from the evidence write boundary (src/runtime/cli.js), so argv and a --batch JSON file
+  // are refused by one rule with two enforcement points rather than two rules.
+  const camel = name.replace(/^--/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  if (EVIDENCE_SCORE_FIELDS.has(camel)) { console.error(`doflow: ${scoreFieldRefusal(name)}`); process.exit(2); }
+  const inline = eq === -1 ? null : arg.slice(eq + 1);
+  const key = RUNTIME_STRING_FLAGS.get(name) || RUNTIME_LIST_FLAGS.get(name) || RUNTIME_INT_FLAGS.get(name);
+  if (!key) return null;
+
+  let value      = inline;
+  let next = i;
+  if (value === null) {
+    value = argv[i + 1];
+    // A value that itself starts with `-` is far more likely the next flag than a deliberate
+    // argument, and consuming it would silently drop that flag.
+    // A bare `-` is the conventional name for stdin, not a flag, and the help advertises
+    // `--batch <file|->`. Rejecting it made the documented spelling exit 2 while only `--batch=-`
+    // worked — a help text endorsing a form the parser refuses.
+    const isStdin = value === '-';
+    if (value === undefined || (value.startsWith('-') && !isStdin)) { console.error(`doflow: ${name} requires a value`); process.exit(2); }
+    next = i + 1;
+  }
+  if (value === '') { console.error(`doflow: ${name} requires a value`); process.exit(2); }
+
+  if (RUNTIME_INT_FLAGS.has(name)) {
+    const parsed = parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) { console.error(`doflow: ${name} expects a non-negative integer, got '${value}'`); process.exit(2); }
+    o[key] = parsed;
+  } else if (RUNTIME_LIST_FLAGS.has(name)) {
+    // --exclude alone also accepts a comma-joined value (`--exclude bin,src,core`), not just the
+    // repeatable form (`--exclude bin --exclude src`) every other list flag uses — the two used to
+    // be parsed by two separate code paths (a dedicated switch case handling only the space
+    // spelling's comma-splitting, this generic path handling both spellings but never splitting),
+    // so `--exclude=bin,src` silently excluded nothing while `--exclude bin,src` worked. One path,
+    // both spellings, same behavior now.
+    const parts = name === '--exclude' ? value.split(',').map((s        ) => s.trim()).filter(Boolean) : [value];
+    (o[key] = o[key] || []).push(...parts);
+  } else if (name === '--evidence-id' && o.cmd === 'research-request') {
+    (o.evidenceIds = o.evidenceIds || []).push(value);
+  } else {
+    o[key] = value;
+  }
+  return next;
+}
+
+const HELP = `doflow — DoFlow config installer
+
+Usage: doflow <command> [path] [options]
+
+Commands:
+  install [path]       Install configs to target tools (use --dry-run to preview)
+  update               Incremental update of changed files only
+  reconcile            Converge observed state onto the doflow.lock pin (drift report + heal)
+  status               Show resolved context + installed state from manifest (--json for scripting)
+  rollback [id]        Restore from a backup (interactive pick if id omitted)
+  remove [path]        Remove only lifecycle-owned native resources
+  list-backups         List available backups
+  self-update          git pull + reinstall
+  tools                Inspect or manage registered external tools
+  capabilities         Show registered abstract capabilities and resolved providers
+  doctor               System health and capability smoke check diagnostics
+  readiness            Evaluate task readiness contract (--task-class, --task-id, both required)
+  evidence             Record a stage's evidence batch, or inspect what is recorded (--task-id)
+  claim                Record a claim, link evidence to it, or list them (--task-id, --action)
+  context-pack         Compile a task's evidence and claims into a context block (--task-id)
+  retrieval-plan       Declare a stage's information needs, then report every declared item
+  outcome              Record a task's terminal state with its basis, or show it (--task-id)
+  classify             Validate a proposed task class and return its workflow (--task-class)
+  workflow             Resolve a task class to its stages, gates and readiness templates
+  orchestrate          Start or resume a run: complete stages, decide gates (--action)
+  research-request     Open, list or resolve a feature-stage research question (--task-id)
+  task-attempt         Claim, finish, release or read the attempts on a plan's tasks (--action, --slug)
+  retrieve             BM25 search over the installed guidance tree (--query)
+  model-role           Resolve a model role to ranked provider candidates (--role)
+  advise               Route decision questions to the configured local model (--action)
+  brief-tools          Tier, tools and report-format block for a dispatch brief (--owner)
+  route                Resolve an information need to a healthy provider (--intent)
+  verify               Compile the verification contract and report against it (--task-id)
+  recover              Classify a verification failure and plan the bounded retry (--error)
+  trace                Trajectory of the current or most recent workflow (run ledger)
+  stats                Aggregate local run-ledger usage
+  indicators           Per-stage and per-gate timings from the orchestration record
+  discover             Missed capability opportunities in recorded runs
+  inventory            Shadowed copies, drift and unmanaged files across both install scopes
+  storage              Report stored data and retention bounds (--action report|prune|upkeep)
+  scaffold             Emit the reviewable code scaffold the active feature's artifacts imply
+  decision             Register, list or compact the active feature's decisions (--action init|add|list|compact)
+  followup             Record, list, take, settle, promote or report what a feature left unfinished (--action add|list|take|settle|promote|report)
+  lifecycle            Open follow-ups, feature tracking, releases and status for the project (--action overview|init|release|status|merged)
+  goal                 Add, check, link, list or close a goal and its checklist (--action add|item|check|link|list|done)
+  failure              List, settle or switch off the failures DoFlow captured on this machine (--action list|settle|capture)
+                       (a value beginning with '-' must be written --flag=value)
+  leak-scan            Report DoFlow-internal identifiers in shipped files (--path, repeatable)
+
+Scope (mutually exclusive — global wins if both given):
+  -g, --global         Install to each target's user-level directory under \$HOME (e.g. \$HOME/.claude),
+                       and the shared runtime to \$HOME/.doflow
+  [path]               Project-scoped install root (default: '.', i.e. cwd); e.g.
+                       'doflow install ../my-app' -> each target's project files, plus
+                       ../my-app/.doflow
+                       (rollback's one positional slot is the backup id instead — its scope is
+                       always -g or cwd, no custom project path)
+
+Options:
+  -t, --target <list>  Comma-separated: ${VALID_TARGETS.join(',')} (default: ${DEFAULT_TARGETS.join(',')})
+      --mcp <list>     Comma-separated MCP server names, or all or none, for every targeted
+                       harness that takes MCP servers (all but gemini). Default: none, or the
+                       selection a harness has recorded in doflow.lock, or the servers an
+                       installed harness already has; a real terminal prompts on install.
+                       Recorded per harness.
+  -n, --dry-run        Preview without writing
+  -f, --force          Skip confirmation prompts
+      --adopt          Record ownership of resources that exist with no ledger record, instead
+                       of refusing them. Not --force: a resource whose record disagrees with
+                       the file is still a conflict. For a tree installed before the neutral
+                       ledger existed, which nothing else can re-adopt
+      --no-backup      Skip backup (requires --force; ignored by rollback's safety snapshot)
+      --prune <N>      Keep the N newest backups after install or update (default 3; 0 keeps all)
+      --days <N>       Run-ledger window in calendar days (trace, stats, discover)
+      --slug <name>    Scaffold this feature instead of the branch-resolved active one
+
+Runtime verb arguments (accept --flag value or --flag=value):
+      --task-class     classify, workflow, readiness, context-pack, outcome --action record
+      --task-id        readiness, evidence, claim, context-pack, retrieval-plan, outcome, verify, advise
+      --action         claim: list|add|link|retract|supersede · evidence: list|add|supersede
+                       verify: report|contract · retrieval-plan: declare|report
+                       outcome: record|show · advise: ask|outcome|configure · tools: see above
+                       followup: add|list|take|settle|promote|report
+                       task-attempt: claim|finish|release|status
+                       lifecycle: overview|init|release|status|merged
+                       goal: add|item|check|link|list|done
+                       failure: list|settle|capture
+      --task, --token, --owner, --mode,
+      --result, --evidence-id, --reason     task-attempt (claim: --task --owner --mode manual|sequential|subagent;
+                                            finish: --task --token --result COMPLETED|BLOCKED|ABANDONED|INCONCLUSIVE
+                                            [--evidence-id]; release: --task --token --reason)
+      --rationale, --proposed-by, --calling-skill    classify
+      --request <text>, --request-file <file>  classify (mutually exclusive; optional second opinion)
+      --intent, --query, --check            route
+      --statement, --claim-id,
+      --evidence-id, --relation             claim
+      --kind, --provenance, --provider,
+      --capability, --locator, --content    evidence --action add (one item)
+      --batch <file|->                      evidence --action add (a stage's JSON batch)
+      --evidence-id, --replaced-by          evidence --action supersede (retire one item, point
+                                            forward to the item that replaces it)
+      --verification-plan, --scope,
+      --invariants,
+      --user-decision-pending               readiness: inputs the caller states rather than
+                                            evidence establishes; reported back as such
+      --objective                           context-pack
+      --need <intent[,intent]>,
+      --stage                               retrieval-plan (--need is repeatable), outcome
+      --mcp-outcome <server>=<outcome>      orchestrate --action handoff, repeatable: used | nothing-usable |
+                                            skipped:<reason> | unavailable (a server left out only warns)
+      --state <COMPLETED|BLOCKED|
+               ABANDONED|INCONCLUSIVE>,
+      --readiness, --verification           outcome --action record
+      --risk, --plan-path, --scope,
+      --verification-input,
+      --verification-phase,
+      --baseline-ref                     verify
+      --owner, --tier, --harness, --tasks <id,...>,
+      --heading-level 2|3                   brief-tools (--slug names the feature whose run gives the stage)
+      --kind, --state, --state-file,
+      --questions-file, --server,
+      --static                           advise --action ask
+      --pick-id, --actual                advise --action outcome
+      --model, --endpoint, --project,
+      --off                              advise --action configure
+      --path, --exclude (repeatable)        leak-scan
+      --ids, --as, --evidence, --title,
+      --release, --source, --channel        followup (add, list, take, settle, promote)
+      --file <path|->, --stdin, --text,
+      --feature                             followup --action report (the body comes from exactly one; - is stdin)
+      --take, --goal, --intent, --since,
+      --maintain                            lifecycle (overview, init)
+      --goal, --statement, --item (repeatable),
+      --text, --evidence, --unmet, --slug,
+      --replace, --reason, --channel        goal (add, item, check, link, list, done)
+      --tag, --confirm, --feature,
+      --exclude (repeatable), --reason      lifecycle (release, merged)
+      --fp, --as, --reason, --set, --all    failure (list, settle, capture)
+      --error, --failed-check,
+      --iteration, --agent                  recover
+      --json           Machine-readable output (status)
+
+External tools:
+      --tool <list>    Comma-separated: rtk,graphify (required outside an interactive terminal)
+      --action <name>  status (default), install, update, or uninstall
+                       --force is intentionally unavailable: every mutation is separately confirmed
+  -h, --help           Show help
+  -v, --version        Show version`;
+
+// The names a failure may be recorded under (IC-011): the installer table and the verbs HELP lists,
+// so a record can only ever carry a name from DoFlow's own tables and never an argument value.
+const COMMAND_NAMES = new Set([...Object.keys(COMMANDS), ...[...HELP.matchAll(/^  ([a-z][a-z-]*) {2,}\S/gm)].map((m) => m[1])]);
+
+/** `name` when it is one of DoFlow's own command names, else `unknown`. */
+function commandName(name     )         { return typeof name === 'string' && COMMAND_NAMES.has(name) ? name : 'unknown'; }
+
+/**
+ * Run one CLI invocation. Same behavior as the pre-extraction monolith's main(): --version and
+ * --help answer first, --no-backup-without-force is refused, then the command resolves either
+ * through the installer table above or through the runtime-verb dispatcher.
+ */
+async function main(argv          )               {
+  const o = parseArgs(argv);
+  if (o.version) { console.log(pkg.version); return; }
+  if (o.help || !o.cmd) { console.log(HELP); return; }
+  assertNoBackupRequiresForce(o);
+  if (o.cmd === 'classify' && o.request !== undefined && o.requestFile !== undefined) {
+    return usageError('classify', '--request and --request-file are mutually exclusive; provide only one.', o.json);
+  }
+  try {
+    const handler = COMMANDS[o.cmd];
+    if (handler) return handler(o);
+    return await dispatchRuntimeCommand(o);
+  } catch (error     ) {
+    // Recorded silently when it is a programming error (IC-016); the output and exit status below
+    // are the same whether or not anything was written.
+    // Required here, not at load, so a CLI whose failure modules cannot be loaded still runs as today.
+    try { require('../runtime/failure/capture.js').captureError(error, { command: commandName(o.cmd), exit: 1 }); } catch { /* best-effort */ }
+    // A lifecycle apply/remove can throw mid-mutation (fs error, TOCTOU ownership mismatch on a
+    // multi-harness run) — surface a clean, actionable message instead of a raw stack trace, and
+    // point at the recovery record applyLifecycle already wrote before rethrowing.
+    console.error(`[ERROR] ${error.message}`);
+    // Only the commands that actually mutate native resources can leave a partial application.
+    // Printing this after a rejected `readiness --task-id` or any other read-only query told the
+    // user to go inspect recovery records for a run that never wrote anything.
+    if (['install', 'update', 'remove', 'rollback', 'self-update', 'tools'].includes(o.cmd)) {
+      console.error('[ERROR] Some native resources may be partially applied — check .doflow/state/recovery/ (or ~/.doflow/state/recovery/ for -g) for the latest record before retrying.');
+    }
+    process.exit(1);
+  }
+}
+
+module.exports = { main, COMMANDS, commandName };