@momentiq/dark-factory-cli 1.0.0 → 2.0.0

package/dist/cli.js

@@ -34,7 +34,7 @@
 // subcommands accept their own flags directly (see `cmdAudit` and
 // `cmdAdmitPr` below).
 import { spawnSync } from "node:child_process";
-import { accessSync, appendFileSync, constants as fsConstants, existsSync, readFileSync, } from "node:fs";
+import { accessSync, appendFileSync, constants as fsConstants, existsSync, readFileSync, realpathSync, } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runValidateCycleDoc } from "./cycle-doc-validator/index.js";
@@ -52,12 +52,13 @@ import { AdapterRegistry, collectRequiredEnvVars, } from "./adapters/critic.js";
 // path). Phase B-PUBLISH-pkg (cycle 331.1, alpha.5): see
 // https://github.com/momentiq-ai/dark-factory/pull/<this-pr>.
 import { loadAgentReviewConfig } from "./policy/config.js";
-import { buildCriticReport } from "./report.js";
+import { buildCriticReport, buildZeroEvidenceDiagnostic } from "./report.js";
 import { runReview, runCommitGate } from "./runner.js";
+import { buildDefaultSelfConsistencyProbe, } from "./self-consistency.js";
 import { resolveArtifactDir, telemetryPath } from "./paths.js";
 // Phase F-LOCAL — hook-facing subcommand support.
 import { loadDopplerBootstrapEnv, DEFAULT_BOOTSTRAP_ALLOWLIST, } from "./doppler-bootstrap.js";
-import { runDoctor } from "./doctor.js";
+import { classifyDoctorState, detectCloudEnv, runDoctor, } from "./doctor.js";
 import { resolveProfile } from "./policy/profile.js";
 import { commitsForPushUpdate, parsePrePushUpdates, resolveCommit, commitParent, changedFiles, } from "./git.js";
 import { runQualityGates } from "./evidence/quality-gates.js";
@@ -69,10 +70,21 @@ import { summarizeGate } from "./policy/gate.js";
 // stderr-only diagnostics) is structurally distinct from the other
 // subcommands. See docs/roadmap/cycles/cycle5-mcp-server.md.
 import { cmdMcp } from "./mcp/cli.js";
+// DFP #192 — `df skills install/list` subcommand. The skills module is the
+// install engine (consumer-config-driven template rendering); cmdSkills
+// in commands/skills.ts is the CLI wrapper around it.
+import { cmdSkills } from "./commands/skills.js";
 // Cycle 11 Phase 11.1 — `df flow` namespace surfacing the PR Flow
 // Assessor's records from momentiq-ai/df-assessments. See
 // docs/roadmap/cycles/cycle11-flow-assessor-surfacing-and-tools.md.
 import { cmdFlow } from "./commands/flow/index.js";
+import { cmdShow } from "./commands/show.js";
+import { cmdStatus } from "./commands/status.js";
+// Cycle 13 (dark-factory-platform#149) — `df findings --range` surfaces
+// the per-commit iteration-receipt artifacts that the new (default)
+// final-commit-only `df gate-push` semantic leaves un-gated. See
+// src/commands/findings.ts for the rationale.
+import { cmdFindings } from "./commands/findings.js";
 // Cycle 12 Phase 12.2 — agent handoff protocol (v2 — Issue-anchored, native-
 // baton). The four cmd* functions below wrap the verb orchestrators exported
 // from src/handoff/index.ts and route to them at the bottom of main(). v1
@@ -106,58 +118,79 @@ function printHelp(meta) {
         "  df --version              Print version and exit",
         "  df --help                 Print this help and exit",
         "",
-        "Subcommands (Phase C — services #5/#7/#9):",
-        "  df validate-cycle-doc       Validate a PR's Cycle:/Issue:/ProjectItem: trailers",
-        "  df audit-branch-protection  Detect drift between spec.yaml and live GH ruleset",
-        "  df sync-trackers            Reconcile GitHub tracker issues with cycle docs",
-        "  df attribute-pr             Write PR's Cycle: trailer into project board's Cycle Ref field",
+        "Local critic workflow:",
+        "  df review                   Run the local critic against a commit",
+        "                              (subscription auth — Cursor / Codex /",
+        "                              Claude logins, NOT pay-per-token keys).",
+        "  df gate-push                Pre-push gate — block a push when HEAD's",
+        "                              critic verdict has unresolved blockers.",
+        "                              Default since Cycle 13 (dark-factory-",
+        "                              platform#149): gates the HEAD commit",
+        "                              only; intermediate commits are iteration",
+        "                              receipts (see `df findings --range`).",
+        "                              Legacy per-commit gating via",
+        "                              `--full-range` / `DF_GATE_FULL_RANGE=1`.",
+        "  df show                     Render the per-commit review artifact",
+        "                              (with --json for the structured form).",
+        "  df status                   Terse verdict + per-critic status for",
+        "                              a commit (with --json for shell pipes).",
+        "  df findings --range BASE..HEAD",
+        "                              Audit-inspect per-commit findings for the",
+        "                              iteration-receipt artifacts the default",
+        "                              final-commit-only `df gate-push` leaves",
+        "                              un-gated (Cycle 13). NOT a gate.",
+        "  df gates                    Run configured quality gates and",
+        "                              triggered verification routes.",
+        "  df stats                    Pretty-print critic call stats + bypass",
+        "                              audit (alias for `df audit stats`).",
+        "  df doctor                   Verify env: node, hooks, artifact dir,",
+        "                              per-adapter auth.",
         "",
-        "Subcommands (Phase D — services #6/#8):",
-        "  df audit stats              Summarize the _runs.ndjson audit trail (service #8)",
-        "  df admit-pr                 Classify a PR as plan vs code (service #6)",
+        "CI / reusable-workflow gates:",
+        "  df status-check             Sentinel aggregator (pr-status-check).",
+        "                              Exits 0 — merge queue is the real",
+        "                              aggregator.",
+        "  df critic                   Real Critic Orchestrator wiring (agent-",
+        "                              critic gate). Loads .agent-review/",
+        "                              config.json, runs configured vendor",
+        "                              adapters via runReview, writes aggregate",
+        "                              verdict to .git/agent-reviews/<sha>.",
+        "                              Degrades-and-passes on any error.",
         "",
-        "Subcommands (Phase F — reusable-workflow gates, dogfood-wired):",
-        "  df status-check             Sentinel aggregator (PR Status Check gate).",
-        "                              Exits 0 — merge queue is the real aggregator.",
-        "  df critic                   Real Critic Orchestrator wiring (agent-critic",
-        "                              gate). Loads .agent-review/config.json, runs",
-        "                              the 4 vendor adapters via runReview, writes",
-        "                              aggregate verdict to .git/agent-reviews/<sha>.",
-        "                              Degrades-and-passes on any error (exit 0).",
+        "Cycle-doc + project services:",
+        "  df validate-cycle-doc       Validate a PR's Cycle:/Issue:/",
+        "                              ProjectItem: trailers.",
+        "  df audit-branch-protection  Detect drift between spec.yaml and the",
+        "                              live GitHub ruleset.",
+        "  df sync-trackers            Reconcile GitHub tracker issues with",
+        "                              cycle docs.",
+        "  df attribute-pr             Write PR's Cycle: trailer into the",
+        "                              project board's Cycle Ref field.",
+        "  df audit stats              Summarize the _runs.ndjson audit trail.",
+        "  df admit-pr                 Classify a PR as plan vs code.",
         "",
-        "Subcommands (Phase F-LOCAL — hook-facing CLI, subscription cost model):",
-        "  df review                   Background-friendly local critic invocation",
-        "                              for .husky/post-commit. Honors profile auth",
-        "                              (chatgpt/composer/subscription) so Cursor +",
-        "                              Codex + Claude SUBSCRIPTIONS are consumed,",
-        "                              NOT pay-per-token API keys.",
-        "  df gate-push                Read pre-push stdin + gate every commit in",
-        "                              the pushed range. CI mode: --commit SHA --ci.",
-        "                              Honors AGENT_REVIEW_BYPASS for emergencies.",
-        "  df doctor                   Verify env: node, hooks, hookPath, artifact",
-        "                              dir, Doppler bootstrap, per-adapter auth.",
-        "  df gates                    Run configured `requiredQualityGates` and",
-        "                              triggered verification routes. No LLM calls.",
-        "  df stats                    Pretty-print critic call stats + bypass audit.",
-        "                              Alias for `df audit stats`. No LLM calls.",
-        "",
-        "Subcommands (Phase G — agentic MCP surface, cycle5):",
+        "Agentic surface (MCP server):",
         "  df mcp                      Start the local stdio Model Context Protocol",
         "                              server. Exposes the CLI surface to any MCP-",
-        "                              speaking agent (Claude Code, Cursor, Codex,",
-        "                              Gemini) as a structured tool + resource +",
-        "                              prompt catalog. Run `df mcp --help` for the",
+        "                              speaking agent as a structured tool + resource",
+        "                              + prompt catalog. Run `df mcp --help` for the",
         "                              .mcp.json wiring snippet.",
         "",
-        "Subcommands (Cycle 11 — PR Flow Assessor surfacing):",
-        "  df flow                     Surface the PR Flow Assessor's records",
-        "                              from momentiq-ai/df-assessments. Six",
-        "                              sub-subcommands: show / agent / patterns /",
-        "                              cost / trends / rollup. Each carries",
-        "                              --json. Run `df flow --help` for the list,",
-        "                              `df flow <sub> --help` for per-sub flags.",
+        "Bundled skills (consumer-shape):",
+        "  df skills install <name>    Render + install a bundled skill into",
+        "                              .claude/skills/<name>/, driven by the consumer's",
+        "                              darkfactory.yaml. --all installs every skill",
+        "                              flagged enabled: true.",
+        "  df skills list              List bundled skill names + summaries.",
+        "",
+        "PR Flow Assessor surfacing:",
+        "  df flow                     Surface the PR Flow Assessor's records.",
+        "                              Six sub-subcommands: show / agent /",
+        "                              patterns / cost / trends / rollup.",
+        "                              Each carries --json. Run `df flow",
+        "                              --help` for the list.",
         "",
-        "Subcommands (Cycle 12 — agent handoff protocol, v2 Issue-anchored):",
+        "Agent handoff protocol (v2 Issue-anchored):",
         "  df handoff [issue]          Put a work-stream on the handoff stack:",
         "    [--link <ref>]...           upsert the marker-bounded rehydration",
         "    [--unlink <ref>]...         note (read from stdin) as the dedicated",
@@ -168,7 +201,7 @@ function printHelp(meta) {
         "  df handoffs                 List the stack of handed-off Issues (open,",
         "                              labeled `handoff`, unassigned).",
         "  df accept <issue>           Claim a handoff Issue (assign you), rehydrate,",
-        "                              then close it (Commitment 10).",
+        "                              then close it.",
         "  df rehydrate [issue]        Read-only catch-up on a handoff Issue's note —",
         "                              derives LIVE state first, changes no ownership.",
         "                              No-arg: 2-tier (open+@me → closed+@me ≤7d).",
@@ -177,42 +210,25 @@ function printHelp(meta) {
         "  The local hook path (review/gate-push) consumes Cursor / Codex / Claude",
         "  SUBSCRIPTIONS via the developer's existing CLI logins. Vendor API keys",
         "  (CURSOR_API_KEY / CODEX_API_KEY / GEMINI_API_KEY / XAI_API_KEY) are the",
-        "  CI cold-path fallback only. Profile `auth` pins (e.g. `chatgpt` on the",
-        "  codex critic) enforce subscription-only with no env-presence fallback",
-        "  (cycle 322.7 issue #2103).",
+        "  CI cold-path fallback only.",
         "",
-        "Each Phase C subcommand passes its remaining argv through to the bundled",
-        "Python script verbatim; run `df <subcommand> --help` for full flags.",
-        "Phase D subcommands parse flags directly — see `df audit --help` and",
-        "`df admit-pr --help`. Phase F's `df critic` accepts --ref/--config/--cwd",
-        "(see `df critic --help`); status-check accepts no flags. Both subcommands",
-        "exit 0 even on failure so the reusable workflows do not block the merge",
-        "queue on a single vendor flake — vendor errors register in the artifact",
-        "as `status=error` and the configured min-complete-quorum policy decides",
-        "the aggregate verdict.",
+        "Each subcommand carries its own `--help` for full flag documentation.",
+        "Critic and status-check exit 0 even on failure so the reusable workflows",
+        "do not block the merge queue on a single vendor flake — vendor errors",
+        "register in the artifact as `status=error` and the configured aggregation",
+        "policy (min-complete-quorum, block-if-any) decides the aggregate verdict.",
         "",
         "System requirements:",
         "  Node.js >=20",
         "  python3 (>=3.11)",
-        "  gh CLI (authenticated) for service #5/#7/#9 GitHub API calls",
+        "  gh CLI (authenticated) for project/cycle-doc GitHub API calls",
         "  git on PATH",
         "",
         "Library usage today:",
         "  import { runReview, evaluateCommitGate, buildReviewPacket }",
         `    from \"${name}\";`,
         "",
-        "Status: 0.1.0-alpha.6 — Phase F-LOCAL ports sage3c's hook-facing CLI",
-        "        subcommands (review/gate-push/doctor/gates/stats) so consumer",
-        "        repos can wire .husky hooks to the subscription-auth local",
-        "        critic path. Also: Phase B-PUBLISH-pkg fixes CLI loadability",
-        "        under `npm install --ignore-scripts` for all non-`df critic`",
-        "        subcommands. Phase F wires the real Critic Orchestrator and",
-        "        dogfoods dark-factory on its own PRs. Reusable workflows from",
-        "        Phase E now invoke real critic logic. The substrate validates",
-        "        itself end-to-end. Pure-TS port of #5/#7/#9 tracked as Phase",
-        "        C-PORT follow-up.",
-        "",
-        "Docs:   https://github.com/momentiq-ai/dark-factory",
+        `Version: ${version}. Docs: https://github.com/momentiq-ai/dark-factory`,
         "",
     ].join("\n"));
 }
@@ -220,11 +236,9 @@ function printVersion(meta) {
     process.stdout.write(`${meta.version ?? "unknown"}\n`);
 }
 function notImplemented(sub) {
-    process.stderr.write(`df: subcommand "${sub}" is not implemented in this alpha build.\n` +
-        `    Phase B/C/D ship services as library + Python-wrapped subcommands;\n` +
-        `    Phase E added reusable workflow stubs (status-check, critic);\n` +
-        `    Phase F upgraded both to real implementations;\n` +
-        `    "${sub}" lands in Phase G or later (see \`df --help\`).\n`);
+    process.stderr.write(`df: subcommand "${sub}" is not implemented in this build.\n` +
+        `    Run \`df --help\` for the list of available subcommands.\n` +
+        `    Track / request at: https://github.com/momentiq-ai/dark-factory/issues\n`);
     return 2;
 }
 async function runPhaseCSubcommand(sub, rest) {
@@ -264,7 +278,7 @@ const PHASE_D_SUBCOMMANDS = new Set(["audit", "admit-pr"]);
 //
 //   - `status-check` stays thin: a sentinel aggregator. The merge queue's
 //     ALLGREEN rule already does the real cross-check aggregation; this
-//     subcommand exists for the `PR Status Check` ruleset context.
+//     subcommand exists for the `pr-status-check` ruleset context.
 //
 //   - `critic` is now wired to the real Critic Orchestrator (Phase B
 //     extraction). It loads `.agent-review/config.json`, instantiates
@@ -308,10 +322,27 @@ const CYCLE12_SUBCOMMANDS = new Set([
 // not at the top level, so the surface stays grouped (`df flow --help` is
 // authoritative) and we don't pollute the top-level `df` namespace.
 const CYCLE11_SUBCOMMANDS = new Set(["flow"]);
+// `df show` / `df status` / `df findings` — CLI artifact-inspection
+// subcommands. `show` + `status` mirror the df_show_run / df_findings MCP
+// tools per-commit (cycle 5); `findings --range <base>..<head>` (Cycle
+// 13, dark-factory-platform#149) walks the iteration-receipt artifacts
+// the new default final-commit-only `df gate-push` semantic leaves
+// un-gated. All three share the loader + mappers in
+// src/lib/show-status-core.ts so the CLI's `--json` output stays
+// byte-equivalent with the MCP tool's structuredContent envelope (cycle 5
+// spec requirement). Registered here so the early --help interception
+// forwards each `df <cmd> --help` to its per-subcommand help printer.
+const SHOW_STATUS_SUBCOMMANDS = new Set(["show", "status", "findings"]);
+// `df skills` — bundled-skill installer (Cycle: DFP #192). The namespace
+// fans out into `install/list` sub-subcommands handled inside cmdSkills;
+// registered here so the early --help interception above forwards
+// `df skills --help` to cmdSkills' own help printer instead of the
+// top-level printHelp.
+const SKILLS_SUBCOMMANDS = new Set(["skills"]);
 function cmdStatusCheck(_rest) {
-    // PR Status Check is a sentinel aggregator. As cycle 331.1 Phase E
+    // pr-status-check is a sentinel aggregator. As cycle 331.1 Phase E
     // documents in `.github/workflows/pr-status-check.yml`, this gate is
-    // present specifically to satisfy the `PR Status Check` ruleset context
+    // present specifically to satisfy the `pr-status-check` ruleset context
     // — its passage means "the workflow itself reached this step", which
     // is the contract every other status check separately enforces. There
     // is no useful aggregation work to do here that the merge queue's
@@ -351,6 +382,12 @@ const ADAPTER_LOADERS = [
     { id: "codex-sdk", modulePath: "./adapters/codex-sdk.js", className: "CodexSdkAdapter" },
     { id: "gemini-sdk", modulePath: "./adapters/gemini-sdk.js", className: "GeminiSdkAdapter" },
     { id: "grok-direct-sdk", modulePath: "./adapters/grok-direct-sdk.js", className: "GrokDirectSdkAdapter" },
+    // Consumer dark-factory-platform#107 — deterministic schema-lint adapter.
+    // No vendor SDK, no env vars, no network; pure ajv-backed validation of
+    // schema-annotated code blocks in changed markdown / config files.
+    // Loads alongside the LLM adapters so the local profile can include it
+    // without any additional toolchain.
+    { id: "static-schema-lint", modulePath: "./adapters/static-schema-lint.js", className: "StaticSchemaLintAdapter" },
 ];
 async function buildDefaultAdapterRegistry() {
     // Each adapter reads its API key from the corresponding env var by
@@ -403,6 +440,31 @@ function appendStepSummary(markdown) {
         // best-effort — never let a summary-write failure change the gate outcome.
     }
 }
+/**
+ * Cursor finding (cli.ts:560) — resolve the production
+ * self-consistency probe so the policy `unilateralVetoRules.requireCorroborationFor`
+ * actually demotes findings on the default OSS CLI path. Returns the
+ * probe callable when (a) the loaded policy lists `self_inconsistent`
+ * AND (b) `buildDefaultSelfConsistencyProbe()` returns a non-null
+ * factory (i.e. the env has a `GEMINI_API_KEY`). Otherwise returns
+ * undefined, which makes the runner skip the probe pass entirely
+ * (byte-identical pre-#112 behavior).
+ *
+ * Operators who want a non-Gemini probe (or the hosted worker's
+ * proprietary calibrated probe) replace the callable by importing
+ * `runReview` directly with their own `selfConsistencyProbe`.
+ */
+export function resolveProductionSelfConsistencyProbe(loaded) {
+    const flags = loaded.config.aggregation.unilateralVetoRules?.requireCorroborationFor ?? [];
+    if (!flags.includes("self_inconsistent"))
+        return undefined;
+    const probe = buildDefaultSelfConsistencyProbe();
+    if (probe === null) {
+        process.stderr.write("[critic] self-consistency probe disabled — GEMINI_API_KEY unset; policy `unilateralVetoRules.requireCorroborationFor: [self_inconsistent]` is configured but probe-flagged findings will not be demoted on this run.\n");
+        return undefined;
+    }
+    return probe;
+}
 async function cmdCritic(rest) {
     if (rest.includes("--help") || rest.includes("-h")) {
         process.stdout.write([
@@ -443,11 +505,13 @@ async function cmdCritic(rest) {
         // audit trail on its own PRs.
         const artifactDir = await resolveArtifactDir(loaded);
         const sink = new FileTelemetrySink(telemetryPath(artifactDir));
+        const selfConsistencyProbe = resolveProductionSelfConsistencyProbe(loaded);
         const outcome = await runReview({
             loaded,
             registry,
             ref: opts.ref,
             telemetry: sink,
+            ...(selfConsistencyProbe !== undefined ? { selfConsistencyProbe } : {}),
         });
         // sage3c#2213 — surface per-critic errors + a loud degradation
         // warning. `buildCriticReport` is pure; it turns the artifact's
@@ -631,13 +695,28 @@ async function cmdReview(rest) {
     const ref = flags["commit"] ?? "HEAD";
     const foreground = flags["foreground"] === true || flags["foreground"] === "true";
     try {
+        const selfConsistencyProbe = resolveProductionSelfConsistencyProbe(loaded);
         const outcome = await runReview({
             loaded,
             registry,
             ref,
             telemetry: sink,
             profileName,
+            ...(selfConsistencyProbe !== undefined ? { selfConsistencyProbe } : {}),
         });
+        // Issue #51 — loud post-completion diagnostic for zero-evidence
+        // reviews. When every critic errored (no completed verdicts), the
+        // gate will silently block at push time and operators reach for
+        // AGENT_REVIEW_BYPASS as the workaround. Surface the failure here
+        // so the operator sees it at commit time, with a specific
+        // remediation per critic and a pointer to the artifact JSON for
+        // deeper triage. The helper is pure (no I/O); the only side effect
+        // is the stderr write below.
+        const configHasProfiles = hasProfileEntry(loaded.config, profileName);
+        const diagnostic = buildZeroEvidenceDiagnostic(outcome.artifact, outcome.paths.jsonPath, { configHasProfiles });
+        if (diagnostic.isZeroEvidence) {
+            process.stderr.write(diagnostic.stderr);
+        }
         if (foreground) {
             process.stdout.write(`df review: ${outcome.artifact.gateVerdict ?? "complete"} for ${outcome.artifact.commit.slice(0, 12)}\n`);
             process.stdout.write(`  json: ${outcome.paths.jsonPath}\n`);
@@ -650,20 +729,108 @@ async function cmdReview(rest) {
         return 1;
     }
 }
+// Issue #51 — the post-completion diagnostic needs to know whether
+// the loaded config has the requested profile so it can prepend a
+// "add 'profiles' to .agent-review/config.json" remediation when the
+// seed config is the broken sage-blueprint shape (`profiles: {}`).
+// Returns `true` when both a profiles map exists AND the requested
+// name is present; `false` otherwise. (Back-compat configs with no
+// profiles map AT ALL also return `false`, which is the correct
+// signal — the diagnostic surfaces the seed remediation in both
+// cases.)
+function hasProfileEntry(config, profileName) {
+    if (!config.profiles)
+        return false;
+    return config.profiles[profileName] !== undefined;
+}
 // ----- df gate-push -----
+//
+// Cycle 13 (dark-factory-platform#149) — semantic flip:
+//
+//   DEFAULT MODE: final-commit-only. The HEAD (last) commit of each
+//     push update is the only one whose verdict decides the gate. The
+//     intermediate commits' per-SHA artifacts still exist on disk
+//     (`.git/agent-reviews/<sha>.json`) as iteration receipts and stay
+//     visible via `df findings --range <base>..<head>`, but they do
+//     NOT influence the push outcome. This matches the documented
+//     find-fix-new-commit pattern: commit B fixes commit A's blockers,
+//     B's verdict is what gates the push.
+//
+//     Soundness caveat: each per-SHA artifact reviews `parent..commit`
+//     only, NOT `base..tip`. HEAD's APPROVED verdict therefore proves
+//     the LAST incremental change is safe; it does NOT prove the
+//     cumulative `base..tip` diff is safe. The banner + help text
+//     surface this so operators can choose `--full-range` (or rely on
+//     the CI cold-path agent-critic workflow that reviews the full PR
+//     diff) when cumulative soundness matters more than termination of
+//     the find-fix loop.
+//
+//   LEGACY MODE: full-range — gate every commit in the push update,
+//     block on any single commit's blockers. Opt-in via `--full-range`
+//     OR `DF_GATE_FULL_RANGE=1`. Use cases: forensic replay, per-commit
+//     audit (each commit is independently reviewed in a deploy log),
+//     cumulative-state evidence requirements.
+//
+//   The legacy mode was the implicit default before Cycle 13. It
+//   makes the find-fix-new-commit pattern non-terminating in practice
+//   (any iteration round produces stale intermediate `CHANGES_REQUESTED`
+//   verdicts that block the push and force a squash, which spawns a
+//   fresh full-diff review that surfaces new findings — see
+//   consumer-side dark-factory-platform#149 for the full failure mode).
+//
+// The mode banner — `GATE MODE: final-commit-only (HEAD=<sha>)` or
+// `GATE MODE: full-range (N commits)` — prints once per push update so
+// operators see which semantic is active without needing to remember
+// the env-var / flag state.
+//
+// `--commit SHA --ci` mode is a single-commit replay path (CI cold-
+// path); the legacy/default split does not apply to it (one commit
+// only).
+function isFullRangeRequested(flags) {
+    if (flags["full-range"] === true || flags["full-range"] === "true") {
+        return true;
+    }
+    const env = process.env["DF_GATE_FULL_RANGE"];
+    if (env !== undefined && env !== "" && env !== "0" && env.toLowerCase() !== "false") {
+        return true;
+    }
+    return false;
+}
 async function cmdGatePush(rest) {
     if (rest.includes("--help") || rest.includes("-h")) {
         process.stdout.write([
-            "df gate-push — block a push when prior commits have unresolved blockers.",
+            "df gate-push — gate a push on the local-critic verdict.",
             "",
             "Usage:",
-            "  df gate-push [--profile NAME]                          # local pre-push",
-            "  df gate-push --commit SHA --ci [--profile NAME]        # CI replay",
+            "  df gate-push [--profile NAME]                              # local pre-push",
+            "  df gate-push --full-range [--profile NAME]                 # legacy: gate every commit",
+            "  df gate-push --commit SHA --ci [--profile NAME]            # CI replay (single commit)",
+            "",
+            "Designed for .husky/pre-push. Reads git's pre-push protocol on stdin.",
+            "",
+            "Default mode (Cycle 13 — dark-factory-platform#149):",
+            "  Gates ONLY the HEAD (final) commit of each push update. Intermediate",
+            "  commits' per-SHA artifacts at .git/agent-reviews/<sha>.json are still",
+            "  written (iteration audit), but they DO NOT influence the gate.",
+            "  Inspect them with: `df findings --range <base>..HEAD`.",
+            "",
+            "Legacy mode — opt in via `--full-range` OR `DF_GATE_FULL_RANGE=1`:",
+            "  Gates EVERY commit in the push range; any single commit's blocker",
+            "  blocks the push. Use for forensic replay or per-commit deploy-log",
+            "  audit. Note: this was the implicit default before Cycle 13 and is",
+            "  what produced the find-fix-new-commit termination failure.",
             "",
-            "Designed for .husky/pre-push. Reads git's pre-push protocol on stdin",
-            "and gates each commit in the pushed range against the per-SHA artifact",
-            "written by `df review`. Exit 1 if any commit has unresolved BLOCKER",
-            "findings under the configured aggregation policy.",
+            "Soundness caveat (default mode):",
+            "  Each per-SHA artifact reviews `parent..commit` only, NOT `base..tip`.",
+            "  HEAD's APPROVED verdict therefore proves the LAST incremental change",
+            "  is safe; it does NOT prove the cumulative `base..tip` diff is safe.",
+            "  For cumulative-state evidence either pass `--full-range` (or set",
+            "  `DF_GATE_FULL_RANGE=1`) for per-commit gating, or rely on the CI",
+            "  cold-path agent-critic workflow (which reviews the full PR diff).",
+            "",
+            "Exit code:",
+            "  1 if the gating verdict (HEAD-only or full-range, per mode) blocks.",
+            "  0 otherwise.",
             "",
             "Bypass:",
             "  AGENT_REVIEW_BYPASS=\"<reason>\" git push   # logged to _runs.ndjson",
@@ -702,6 +869,7 @@ async function cmdGatePush(rest) {
         process.stdout.write(`-- ${sha.slice(0, 12)}\n${summarizeGate(result)}\n`);
         return result.blocked ? 1 : 0;
     }
+    const fullRange = isFullRangeRequested(flags);
     const stdin = await readStdinUtf8FromTtyOrStream();
     const updates = parsePrePushUpdates(stdin);
     if (updates.length === 0) {
@@ -715,18 +883,45 @@ async function cmdGatePush(rest) {
         const commits = await commitsForPushUpdate(update);
         if (commits.length === 0)
             continue;
-        process.stdout.write(`df gate-push: gating ${commits.length} commit(s) on ${update.localRef} -> ${update.remoteRef}\n`);
-        for (const sha of commits) {
-            const result = await runCommitGate({
-                loaded,
-                commit: sha,
-                telemetry: sink,
-                profileName,
-            });
-            process.stdout.write(`-- ${sha.slice(0, 12)}\n${summarizeGate(result)}\n`);
-            if (result.blocked)
-                blockedAny = true;
+        if (fullRange) {
+            // Legacy mode — gate every commit in the range. Pre-Cycle-13
+            // behavior, kept for forensic replay and per-commit audit
+            // contexts (e.g. production-deploy push where each commit is
+            // independently reviewed in the deploy log).
+            process.stdout.write(`GATE MODE: full-range (${commits.length} commits) — ${update.localRef} -> ${update.remoteRef}\n`);
+            for (const sha of commits) {
+                const result = await runCommitGate({
+                    loaded,
+                    commit: sha,
+                    telemetry: sink,
+                    profileName,
+                });
+                process.stdout.write(`-- ${sha.slice(0, 12)}\n${summarizeGate(result)}\n`);
+                if (result.blocked)
+                    blockedAny = true;
+            }
+            continue;
         }
+        // Default mode (Cycle 13) — final-commit-only. The last commit in
+        // the range (`commitsForPushUpdate` returns the rev-list reverse,
+        // so HEAD is the last element) is the only one whose verdict
+        // gates the push. Intermediate commits' artifacts are iteration
+        // receipts; inspect them with `df findings --range`.
+        const headSha = commits[commits.length - 1] ?? "";
+        process.stdout.write(`GATE MODE: final-commit-only (HEAD=${headSha.slice(0, 12)}) — ${update.localRef} -> ${update.remoteRef}\n`);
+        if (commits.length > 1) {
+            process.stdout.write(`  intermediate commits (${commits.length - 1}) are iteration receipts; inspect with: df findings --range ${update.remoteRef === "" ? "<base>" : `${update.remoteSha.slice(0, 12)}..${headSha.slice(0, 12)}`}\n`);
+            process.stdout.write(`  soundness caveat: HEAD's verdict covers parent..HEAD only, NOT base..HEAD; use --full-range (or the CI agent-critic on the full PR diff) when cumulative-state evidence is required.\n`);
+        }
+        const result = await runCommitGate({
+            loaded,
+            commit: headSha,
+            telemetry: sink,
+            profileName,
+        });
+        process.stdout.write(`-- ${headSha.slice(0, 12)}\n${summarizeGate(result)}\n`);
+        if (result.blocked)
+            blockedAny = true;
     }
     return blockedAny ? 1 : 0;
 }
@@ -737,11 +932,18 @@ async function cmdDoctor(rest) {
             "df doctor — verify the environment for hook-facing critic invocation.",
             "",
             "Usage:",
-            "  df doctor [--profile NAME]",
+            "  df doctor [--profile NAME] [--json]",
             "",
             "Checks: node version, hooks dir, hook executable, core.hooksPath,",
-            "artifact dir, doppler bootstrap, per-adapter doctor() (subscription",
-            "auth lives here).",
+            "artifact dir, doppler bootstrap, cloud-env detection, per-adapter",
+            "doctor() (subscription auth lives here; skipped in cloud envs).",
+            "",
+            "Flags:",
+            "  --json                           Emit a machine-readable JSON",
+            "                                   report on stdout instead of the",
+            "                                   human-readable INFO/OK/FAIL lines",
+            "                                   (for consumer-side pre-push hooks",
+            "                                   that fail-fast on auth_pending).",
             "",
             "Environment:",
             "  AGENT_REVIEW_PROFILE=<name>      Profile to validate (default: local)",
@@ -749,6 +951,12 @@ async function cmdDoctor(rest) {
             "  DF_DOCTOR_SKIP_HOOKS=1           Skip git-core-hookspath check",
             "  DF_DOCTOR_SKIP_DOPPLER=1         Skip doppler-cli-on-path check",
             "",
+            "Cloud-env markers (any-of triggers subscription-auth skip):",
+            "  CODESPACES=true                  GitHub Codespaces",
+            "  REMOTE_CONTAINERS=true           VS Code Dev Containers",
+            "  CLAUDE_CODE_SANDBOX=true         Claude Code web sandbox",
+            "  DEVCONTAINER=true                generic devcontainer images",
+            "",
         ].join("\n"));
         return 0;
     }
@@ -770,15 +978,55 @@ async function cmdDoctor(rest) {
         bootstrap,
         profileName,
     });
-    let allOk = true;
+    // Issue #51 — surface the 3-state triage classification FIRST, before
+    // the per-check INFO/OK/FAIL block. The headline tells the operator
+    // whether they're in config_missing / auth_pending / ok before they
+    // have to parse per-critic noise.
+    const triage = classifyDoctorState({
+        config: loaded.config,
+        profileName,
+        perCriticChecks: checks,
+    });
+    const cloudEnv = detectCloudEnv();
+    const allOk = checks.every((c) => c.passed || c.optional);
+    // --json — machine-readable output for consumer-side pre-push hooks
+    // (DFP issue #56). Shape is stable and documented in
+    // packages/schemas/src/index.ts (DoctorReport). Exit code semantics
+    // are the same as the human path: 0 = all required checks passed,
+    // 1 = at least one required check failed.
+    if (flags["json"]) {
+        const report = {
+            version: 1,
+            schema: "df-doctor-report-v1",
+            triage: { state: triage.state, line: triage.line },
+            cloudEnv: {
+                detected: cloudEnv.detected,
+                markers: cloudEnv.markers,
+            },
+            // `profile` is part of the stable field set; `JSON.stringify`
+            // omits `undefined`, so we default explicitly here even though
+            // `resolveProfile` already returns `"local"` on the no-flag /
+            // no-env path. Belt-and-braces — keeps the contract intact if the
+            // resolver signature ever loosens.
+            profile: profileName || "local",
+            ok: allOk,
+            checks,
+        };
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        return allOk ? 0 : 1;
+    }
+    process.stdout.write(`${triage.line}\n`);
     for (const c of checks) {
-        const label = c.passed ? "OK" : c.optional ? "INFO" : "FAIL";
+        const label = c.passed ? (c.optional ? "INFO" : "OK") : c.optional ? "INFO" : "FAIL";
         process.stdout.write(`[${label}] ${c.name}: ${c.detail}\n`);
         if (!c.passed && c.remediation) {
             process.stdout.write(`       fix: ${c.remediation}\n`);
         }
-        if (!c.passed && !c.optional)
-            allOk = false;
+        else if (c.passed && c.optional && c.remediation) {
+            // INFO-with-remediation surfaces the cloud-env bypass hint loudly
+            // even though the check itself "passed" (it's informational).
+            process.stdout.write(`       note: ${c.remediation}\n`);
+        }
     }
     return allOk ? 0 : 1;
 }
@@ -1468,7 +1716,9 @@ async function main(argv) {
             !PHASE_F_LOCAL_SUBCOMMANDS.has(sub0) &&
             !PHASE_G_SUBCOMMANDS.has(sub0) &&
             !CYCLE12_SUBCOMMANDS.has(sub0) &&
-            !CYCLE11_SUBCOMMANDS.has(sub0)) {
+            !CYCLE11_SUBCOMMANDS.has(sub0) &&
+            !SHOW_STATUS_SUBCOMMANDS.has(sub0) &&
+            !SKILLS_SUBCOMMANDS.has(sub0)) {
             printHelp(meta);
             return 0;
         }
@@ -1539,12 +1789,63 @@ async function main(argv) {
             parseFlags,
         });
     }
+    // `df show` / `df status` — CLI mirrors of the df_show_run / df_findings
+    // MCP tools. See src/lib/show-status-core.ts for the shared backend.
+    if (sub === "show") {
+        return await cmdShow(rest, {
+            stdout: (s) => process.stdout.write(s),
+            stderr: (s) => process.stderr.write(s),
+        });
+    }
+    if (sub === "status") {
+        return await cmdStatus(rest, {
+            stdout: (s) => process.stdout.write(s),
+            stderr: (s) => process.stderr.write(s),
+        });
+    }
+    // Cycle 13 (dark-factory-platform#149) — `df findings --range` audit
+    // surface for the iteration-receipt artifacts the new default
+    // final-commit-only `df gate-push` semantic intentionally leaves
+    // un-gated. NOT a gate; opt-in inspection only.
+    if (sub === "findings") {
+        return await cmdFindings(rest, {
+            stdout: (s) => process.stdout.write(s),
+            stderr: (s) => process.stderr.write(s),
+        });
+    }
+    // DFP #192 — bundled-skill installer surface. The subcommand fans out
+    // into `install/list` inside cmdSkills, mirroring the `df flow` pattern.
+    if (sub === "skills") {
+        return await cmdSkills(rest);
+    }
     return notImplemented(sub);
 }
-main(process.argv).then((code) => {
-    process.exitCode = code;
-}, (err) => {
-    process.stderr.write(`df: fatal: ${err.message}\n`);
-    process.exitCode = 1;
-});
+// Only run main() when this module is the program entry point.
+// Tests and other modules can `import` cli.ts to reuse helpers
+// (e.g. `resolveProductionSelfConsistencyProbe`) without triggering
+// `main(process.argv)` as a side-effect of the import. The realpath
+// dance handles symlinked installs (npm bin shims often symlink
+// `dist/cli.js` into `node_modules/.bin/df`). Same posture as
+// sage-cli (see commit f0f945e). Cursor finding (cli.ts:560) tests
+// reach `resolveProductionSelfConsistencyProbe` by importing this
+// module; without the guard they'd trigger the help path on import.
+function isInvokedAsMain() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isInvokedAsMain()) {
+    main(process.argv).then((code) => {
+        process.exitCode = code;
+    }, (err) => {
+        process.stderr.write(`df: fatal: ${err.message}\n`);
+        process.exitCode = 1;
+    });
+}
 //# sourceMappingURL=cli.js.map