@gluecharm-lab/easyspecs-cli 0.0.16 → 0.0.17

package/README.md

@@ -219,7 +219,7 @@ These appear **before** the subcommand (everything after the first non-flag toke
 | ---- | ------ |
 | `--cwd <dir>` | Repository root for git resolution and paths (default: current working directory). |
 | `--ci` | Non-interactive mode; affects merged settings (e.g. Factory outer-iteration default). **`EASYSPECS_CI` is not read** — use this flag. |
-| `--json` | On supported exits, one JSON summary line on stdout. |
+| `--json` | On supported exits, one JSON summary line on stdout. On **non-zero** exits, the line includes **`exitCode`** (number) and **`exitMeaning`** (one-line classification) alongside any command-specific fields. **`analysis`** validation failures also include **`factoryFailures`** (per failed factory phase), **`failurePhase`**, and **`validationExitId`**. |
 | `--verbose` | Extra stderr logging where implemented. |
 | `--api-base-url <url>` | System Manager API origin for this process (overrides `easyspecs.apiBaseUrl`). |
 | `--session-path <file>` | Session JSON path for **this process only** (overrides **`easyspecs.cliSessionPath`**); does not rewrite **`config.json`** unless you use **`auth login`** tail **`--session-path`** as documented under **Auth**. |

package/commands.md

@@ -1,5 +1,7 @@
 # EasySpecs CLI — commands, flags, and configuration
 
+**Error codes:** OS exit codes, structured **`failureExitId`** values, and JSON field semantics are catalogued in **[`error-code.md`](./error-code.md)** (maintained with CLI changes).
+
 Published package: **`@gluecharm-lab/easyspecs-cli`** (`easyspecs-cli`). Source of truth for routing and option registration: [`src/cli/cliProgram.ts`](../../src/cli/cliProgram.ts), command dispatch and business flow wiring: [`src/cli/main.ts`](../../src/cli/main.ts), merged settings: [`mergeEasyspecsCliSettings`](../../src/cli/cliSettings.ts), per-repo config: [`src/config/easyspecsConfigFile.ts`](../../src/config/easyspecsConfigFile.ts), CLI API URL resolution: [`src/easyspecsApiBaseUrlCli.ts`](../../src/easyspecsApiBaseUrlCli.ts). The VS Code extension resolves API URLs via [`src/apiBaseUrlResolve.ts`](../../src/apiBaseUrlResolve.ts); **`easyspecs-cli` does not use that chain** for System Manager origin (**SRS-43 R30 / R34**).
 
 ### Vocabulary (SRS-53)
@@ -20,6 +22,22 @@ Quick usage:
 easyspecs-cli help
 ```
 
+### Factory validation reporting (**SRS-57**)
+
+When **`easyspecs-cli analysis`** exits with **validation** (**`5`**), human stderr prints a short banner and **one bullet per failed factory phase** (readable label, **`validationExitId`** **`5.1`–`5.9`**, normative **`title`**, optional **`detail`**). **`--json`** adds:
+
+| JSON key | Meaning |
+| -------- | ------- |
+| **`factoryFailures`** | Array of **`{ factory, phase, exitCode, failureExitId, title, validationExitId? (when exit 5), detail?, validationSubcode? }`** — **`failureExitId`** is the canonical **`major.minor`** id (SRS-58); see [`error-code.md`](./error-code.md). |
+| **`failurePhase`** | Last failed phase in macro order (alias for scripts). |
+| **`validationExitId`** | Matching **`5.x`** for **`failurePhase`**. |
+| **`exitMeaning`** | First failure **`title`**, or that title plus “and *N* other pipeline phases failed”. |
+| **`error`** | Orchestrator message; if several phases failed, a short appendix lists extra **`validationExitId`**s (see [`factoryValidationFailures.ts`](../../src/factory/factoryValidationFailures.ts)). |
+
+**`validationExitId` → `phase` map:** **`5.1`** `create_analysis_worktree`, **`5.2`** `materialize_opencode_agents`, **`5.3`** `synthesis_convergence`, **`5.4`** `reference_coverage`, **`5.5`** `zero_reference_remediation_convergence`, **`5.6`** `reference_coverage_execution_report`, **`5.7`** `link_mapping_pipeline`, **`5.8`** `assemble_application_context_index`, **`5.9`** `backend_context_sync`, **`5.0`** unknown / unattributed. Normative **`title`** strings and readable labels: [`.gluecharm/docs/srs/srs-57.md`](../../.gluecharm/docs/srs/srs-57.md).
+
+**Optional `validationSubcode` (v1):** **`R5_MACRO_PING_PONG`** when synthesis **`detail`** notes **R5** unstable convergence; **`COVERAGE_PERCENT_THRESHOLD`** when reference-coverage **`detail`** matches the strict percent gate pattern.
+
 ---
 
 ## Global options
@@ -30,7 +48,7 @@ These flags may appear **before** the subcommand. Parsing and command registrati
 |------|--------|
 | `--cwd <dir>` | Repository root for git resolution and file paths (default: current working directory). |
 | `--ci` | Non-interactive mode; feeds into merged settings (e.g. Factory outer-iteration default when unlimited). **`EASYSPECS_CI` is not read** — use this flag in CI. |
-| `--json` | On supported exits, prints one JSON summary line on stdout; suppresses some human-oriented stderr unless `--verbose`. |
+| `--json` | On supported exits, prints one JSON summary line on stdout; suppresses some human-oriented stderr unless `--verbose`. On **`analysis`** validation (**exit code 5**), the JSON line includes **`factoryFailures`** (**SRS-57** — one object per **`failed`** factory phase) plus **`failurePhase`**, **`validationExitId`**, composed **`error`**, and **`exitMeaning`** tailored to the first failure. |
 | `--verbose` | Extra stderr logging where implemented. |
 | `--api-base-url <url>` | System Manager API origin for this process (overrides `easyspecs.apiBaseUrl` in config). |
 | `--environment production` \| `--environment staging` | Alias: **`--env`**. Overrides `easyspecs.deploymentEnvironment` for built-in URL selection when no explicit URL is set. |

package/dist/main.cjs

@@ -10651,6 +10651,30 @@ var ExitCode = {
   cancelled: 8,
   internal: 99
 };
+function describeExitCode(code) {
+  switch (code) {
+    case ExitCode.ok:
+      return "Success.";
+    case ExitCode.usage:
+      return "Invalid arguments, unknown command, or help was not applicable \u2014 see message above or run `easyspecs-cli help`.";
+    case ExitCode.misconfiguration:
+      return "Configuration or repo layout problem \u2014 fix `.easyspecs/config.json`, paths, or prerequisites, then retry.";
+    case ExitCode.opencode:
+      return "OpenCode (agent runner) failed \u2014 check `opencode` install, credentials, and stderr from the tool run.";
+    case ExitCode.validation:
+      return "Validation or factory pipeline did not succeed \u2014 see `error` above and logs for the failing phase (synthesis, coverage, remediation, index, etc.).";
+    case ExitCode.auth:
+      return "Authentication failed or session missing \u2014 run `easyspecs-cli auth login` or fix CI credentials in config.";
+    case ExitCode.upload:
+      return "Upload or cloud sync failed \u2014 check network, project id, and session; see `error` above.";
+    case ExitCode.cancelled:
+      return "Operation was cancelled (abort/stop).";
+    case ExitCode.internal:
+      return "Unexpected internal CLI error \u2014 retry; if it persists, report with full stderr and `--verbose` output.";
+    default:
+      return `Non-zero exit (${String(code)}) \u2014 see stderr and any JSON \`error\` field for detail.`;
+  }
+}
 
 // src/cli/jsonReporter.ts
 function printJsonLine(envelope) {
@@ -20779,6 +20803,180 @@ var FACTORY_PIPELINE_EXIT_CONDITIONS = {
   backend_context_sync: "Context upload finished with no failures (quiet SRS-13 path; or cancel)."
 };
 
+// src/factory/factoryValidationFailures.ts
+function factoryFailureDisplayId(row2) {
+  return row2.failureExitId;
+}
+function normalizeFactoryFailureRow(r) {
+  const failureExitId = r.failureExitId ?? r.validationExitId ?? "5.0";
+  const exitCode = typeof r.exitCode === "number" ? r.exitCode : ExitCode.validation;
+  const factory = r.factory ?? "generate_context";
+  const base = {
+    factory,
+    phase: r.phase,
+    exitCode,
+    failureExitId,
+    title: r.title,
+    ...typeof r.detail === "string" ? { detail: r.detail } : {},
+    ...typeof r.validationSubcode === "string" ? { validationSubcode: r.validationSubcode } : {}
+  };
+  if (exitCode === ExitCode.validation) {
+    return { ...base, validationExitId: r.validationExitId ?? failureExitId };
+  }
+  return base;
+}
+var FACTORY_VALIDATION_PHASE_ORDER = [
+  "create_analysis_worktree",
+  "materialize_opencode_agents",
+  "synthesis_convergence",
+  "reference_coverage",
+  "zero_reference_remediation_convergence",
+  "reference_coverage_execution_report",
+  "link_mapping_pipeline",
+  "assemble_application_context_index",
+  "backend_context_sync"
+];
+var DETAIL_MAX = 600;
+var ERROR_JOIN_MAX = 900;
+var ADDITIONAL_APPEND_MAX = 200;
+var PHASE_TO_EXIT_ID = {
+  unknown_factory_phase: "5.0",
+  create_analysis_worktree: "5.1",
+  materialize_opencode_agents: "5.2",
+  synthesis_convergence: "5.3",
+  reference_coverage: "5.4",
+  zero_reference_remediation_convergence: "5.5",
+  reference_coverage_execution_report: "5.6",
+  link_mapping_pipeline: "5.7",
+  assemble_application_context_index: "5.8",
+  backend_context_sync: "5.9"
+};
+var EXIT_ID_TITLES = {
+  "5.0": "EasySpecs stopped: the failing pipeline phase could not be identified. Retry with --verbose; report this outcome if it persists.",
+  "5.1": "Could not prepare the analysis Git worktree (temporary checkout). Check disk space, repo permissions, and that the project is a valid Git checkout.",
+  "5.2": "Could not install OpenCode agent files into the analysis worktree. Check bundled extension assets and disk permissions under the worktree path.",
+  "5.3": "Context synthesis did not finish: required context files are still missing or invalid after retries. Inspect OpenCode errors and workstation logs for this phase.",
+  "5.4": "Reference coverage could not be computed or written. Check coverage-reference-validation.json prerequisites and disk/schema errors.",
+  "5.5": "Zero-reference remediation did not complete successfully. Inspect remediation logs and zero-reference outputs for this checkout.",
+  "5.6": "Reference coverage execution report could not be generated. Ensure coverage inputs exist from the coverage phase; see coverage-reference-validation.json.",
+  "5.7": "Context link graph (navigation links) could not be updated. Check coordination JSON and markdown under .gluecharm/context.",
+  "5.8": "Application context index could not be assembled or failed schema validation. Inspect index-application-context.json and preceding context files.",
+  "5.9": "Upload / cloud sync after analysis did not succeed. Check auth, project id, network, and upload error details."
+};
+var READABLE_PHASE_LABEL = {
+  create_analysis_worktree: "Analysis worktree",
+  materialize_opencode_agents: "OpenCode agents",
+  synthesis_convergence: "Synthesis",
+  reference_coverage: "Reference coverage",
+  zero_reference_remediation_convergence: "Zero-reference remediation",
+  reference_coverage_execution_report: "Coverage report",
+  link_mapping_pipeline: "Link graph",
+  assemble_application_context_index: "Index assembly",
+  backend_context_sync: "Cloud sync",
+  unknown_factory_phase: "Unknown phase"
+};
+function trimDetail(s) {
+  if (!s) {
+    return void 0;
+  }
+  const t = s.trim();
+  if (!t) {
+    return void 0;
+  }
+  return t.length <= DETAIL_MAX ? t : `${t.slice(0, DETAIL_MAX)}\u2026`;
+}
+function inferValidationSubcode(phase, detail) {
+  const d = detail ?? "";
+  if (phase === "synthesis_convergence" && d.includes("Unstable convergence (R5)")) {
+    return "R5_MACRO_PING_PONG";
+  }
+  if (phase === "reference_coverage" && /percentNonReferenced\s+\d/.test(d) && d.includes(">")) {
+    return "COVERAGE_PERCENT_THRESHOLD";
+  }
+  return void 0;
+}
+function phaseToValidationExitId(phase) {
+  return PHASE_TO_EXIT_ID[phase] ?? "5.0";
+}
+function titleForValidationExitId(validationExitId) {
+  return EXIT_ID_TITLES[validationExitId] ?? EXIT_ID_TITLES["5.0"];
+}
+function readableLabelForFactoryPhase(phase) {
+  return READABLE_PHASE_LABEL[phase] ?? phase;
+}
+function phaseIndex(key) {
+  const i = FACTORY_VALIDATION_PHASE_ORDER.indexOf(key);
+  return i >= 0 ? i : 999;
+}
+function buildFactoryFailuresFromRows(phases) {
+  const failed = phases.filter((p) => p.status === "failed");
+  failed.sort((a, b) => phaseIndex(a.key) - phaseIndex(b.key));
+  return failed.map((p) => {
+    const id = phaseToValidationExitId(p.key);
+    const sub = inferValidationSubcode(p.key, p.detail);
+    return {
+      factory: "generate_context",
+      phase: p.key,
+      exitCode: ExitCode.validation,
+      failureExitId: id,
+      validationExitId: id,
+      title: titleForValidationExitId(id),
+      detail: trimDetail(p.detail),
+      ...sub !== void 0 ? { validationSubcode: sub } : {}
+    };
+  });
+}
+function syntheticUnknownFactoryFailure(message) {
+  return [
+    {
+      factory: "generate_context",
+      phase: "unknown_factory_phase",
+      exitCode: ExitCode.validation,
+      failureExitId: "5.0",
+      validationExitId: "5.0",
+      title: titleForValidationExitId("5.0"),
+      detail: trimDetail(message)
+    }
+  ];
+}
+function primaryFailureAliases(failures) {
+  const last = failures[failures.length - 1];
+  if (!last) {
+    return { failurePhase: "unknown_factory_phase", validationExitId: "5.0" };
+  }
+  return {
+    failurePhase: last.phase,
+    validationExitId: last.validationExitId ?? factoryFailureDisplayId(last)
+  };
+}
+function exitMeaningFromFactoryFailures(failures) {
+  const f0 = failures[0];
+  if (!f0) {
+    return "";
+  }
+  if (failures.length === 1) {
+    return f0.title;
+  }
+  return `${f0.title} (and ${String(failures.length - 1)} other pipeline phases failed)`;
+}
+function composeFactoryValidationError(orchestratorMessage, failures) {
+  const m = orchestratorMessage?.trim() ?? "";
+  if (failures.length <= 1) {
+    return m.length > 0 ? m : failures[0]?.title ?? "Validation failed.";
+  }
+  const extraIds = failures.slice(1).map((f) => factoryFailureDisplayId(f)).join(", ");
+  let appendix = `(+${String(failures.length - 1)} additional phase failure(s): ${extraIds})`;
+  if (appendix.length > ADDITIONAL_APPEND_MAX) {
+    appendix = appendix.slice(0, ADDITIONAL_APPEND_MAX).trimEnd() + "\u2026";
+  }
+  if (m.length > 0) {
+    const out = `${m} | ${appendix}`;
+    return out.length <= ERROR_JOIN_MAX ? out : `${m.slice(0, Math.max(0, ERROR_JOIN_MAX - appendix.length - 3))}\u2026 | ${appendix}`;
+  }
+  const joined = failures.map((f) => `[${factoryFailureDisplayId(f)}] ${f.title}`).join(" | ");
+  return joined.length <= ERROR_JOIN_MAX ? joined : `${joined.slice(0, ERROR_JOIN_MAX - 1)}\u2026`;
+}
+
 // src/factory/generateContextFactory.ts
 var FACTORY_PIPELINE_KEYS = [
   "create_analysis_worktree",
@@ -20886,7 +21084,11 @@ async function runGenerateContextFactory(deps) {
   };
   const fail = async (message) => {
     await post();
-    return { ok: false, message, totalElapsedMs: macroEnd() };
+    let ff = buildFactoryFailuresFromRows(phases);
+    if (ff.length === 0) {
+      ff = syntheticUnknownFactoryFailure(message);
+    }
+    return { ok: false, message, totalElapsedMs: macroEnd(), factoryFailures: ff };
   };
   const pipelineCtx = {
     signal: deps.signal,
@@ -24348,6 +24550,155 @@ function buildFactoryDepsHeadless(input) {
   };
 }
 
+// src/cli/failureExitRegistry.ts
+var DRIFT_FACTORY = "context_drift";
+function failureExitIdFromParts(exitCode, minor) {
+  return `${String(exitCode)}.${String(minor)}`;
+}
+var DRIFT_META = {
+  INVALID_REFERENCE_PATH: {
+    phase: "resolve_reference_bundle",
+    exitCode: ExitCode.misconfiguration,
+    minor: 1,
+    title: "Reference path is not valid under the repository root or does not exist. Check the path is relative to --cwd or exists on disk."
+  },
+  WORKTREE_PREP_FAILED: {
+    phase: "prepare_analysis_worktree",
+    exitCode: ExitCode.misconfiguration,
+    minor: 3,
+    title: "Analysis worktree could not be prepared for drift analysis. Check git, disk space, and permissions."
+  },
+  EMPTY_BUNDLE: {
+    phase: "resolve_reference_bundle",
+    exitCode: ExitCode.validation,
+    minor: 10,
+    title: "Reference bundle was empty or could not be read for drift analysis."
+  },
+  UNRESOLVED_REFERENCE_ROOT: {
+    phase: "resolve_reference_root",
+    exitCode: ExitCode.validation,
+    minor: 11,
+    title: "Reference root document could not be resolved. Use --index or ensure an index markdown exists."
+  },
+  MANIFEST_FAILED: {
+    phase: "build_comparison_manifest",
+    exitCode: ExitCode.validation,
+    minor: 12,
+    title: "Comparison manifest could not be built for drift analysis."
+  },
+  AGENT_FAILED: {
+    phase: "run_drift_analysis",
+    exitCode: ExitCode.opencode,
+    minor: 1,
+    title: "OpenCode drift comparison did not complete successfully. Check OpenCode logs and credentials."
+  },
+  INVALID_AGENT_PAYLOAD: {
+    phase: "validate_and_render_report",
+    exitCode: ExitCode.opencode,
+    minor: 2,
+    title: "Drift agent returned a payload that failed validation before the report could be written."
+  },
+  REPORT_WRITE_FAILED: {
+    phase: "validate_and_render_report",
+    exitCode: ExitCode.validation,
+    minor: 13,
+    title: "Drift report markdown could not be written under the analysis worktree."
+  },
+  INDEX_PATCH_FAILED: {
+    phase: "update_reference_index",
+    exitCode: ExitCode.validation,
+    minor: 14,
+    title: "Reference root markdown could not be updated with the drift report link."
+  },
+  PROMOTE_FAILED: {
+    phase: "promote_drift_artefacts",
+    exitCode: ExitCode.upload,
+    minor: 1,
+    title: "Promoting drift artefacts from the analysis worktree to the workspace failed."
+  }
+};
+var INDEX_PATH_ERROR_SUBSTRING = "--index";
+function invalidReferencePathMeta(error) {
+  const isIndex = (error ?? "").includes(INDEX_PATH_ERROR_SUBSTRING);
+  if (isIndex) {
+    return {
+      phase: "resolve_reference_root",
+      exitCode: ExitCode.misconfiguration,
+      minor: 2,
+      title: "Index path (--index) is not under the repository root or does not exist. Fix the path or omit --index."
+    };
+  }
+  return DRIFT_META.INVALID_REFERENCE_PATH;
+}
+function contextDriftExitCodeFor(code, error) {
+  if (code === "INVALID_REFERENCE_PATH") {
+    return invalidReferencePathMeta(error).exitCode;
+  }
+  return DRIFT_META[code].exitCode;
+}
+var DRIFT_PHASE_LABEL = {
+  parse_cli: "CLI",
+  prepare_analysis_worktree: "Analysis worktree",
+  resolve_reference_bundle: "Reference bundle",
+  resolve_reference_root: "Reference root",
+  build_comparison_manifest: "Comparison manifest",
+  run_drift_analysis: "Drift analysis",
+  validate_and_render_report: "Drift report",
+  update_reference_index: "Reference index",
+  promote_drift_artefacts: "Promotion",
+  finalize: "Finalize"
+};
+function readableLabelForDriftFactoryPhase(phase) {
+  return DRIFT_PHASE_LABEL[phase] ?? phase;
+}
+function contextDriftFactoryFailureRow(code, error) {
+  const meta = code === "INVALID_REFERENCE_PATH" ? invalidReferencePathMeta(error) : DRIFT_META[code];
+  const failureExitId = failureExitIdFromParts(meta.exitCode, meta.minor);
+  const detail = error.trim().length > 0 ? error.trim() : void 0;
+  const base = {
+    factory: DRIFT_FACTORY,
+    phase: meta.phase,
+    exitCode: meta.exitCode,
+    failureExitId,
+    title: meta.title,
+    detail
+  };
+  if (meta.exitCode === ExitCode.validation) {
+    return { ...base, validationExitId: failureExitId };
+  }
+  return base;
+}
+
+// src/cli/factoryValidationStderr.ts
+function readableLabelForAnyFactory(row2) {
+  return row2.factory === "context_drift" ? readableLabelForDriftFactoryPhase(row2.phase) : readableLabelForFactoryPhase(row2.phase);
+}
+function stderrLinesForFactoryFailures(failures, exitCode) {
+  const lines = [`=== Easyspecs factory failure (exit ${String(exitCode)})`];
+  for (const f of failures) {
+    const label = readableLabelForAnyFactory(f);
+    let bullet = `  \u2022 [${factoryFailureDisplayId(f)}] ${label} \u2014 ${f.title}`;
+    if (f.validationSubcode) {
+      bullet += ` (${f.validationSubcode})`;
+    }
+    lines.push(bullet);
+    if (f.detail) {
+      for (const part of f.detail.split(/\r?\n/)) {
+        if (part.length > 0) {
+          lines.push(`    ${part}`);
+        }
+      }
+    }
+  }
+  const n = failures.length;
+  if (n === 1 && failures[0]) {
+    lines.push(`Exit ${String(exitCode)} \u2014 ${failures[0].title}`);
+  } else {
+    lines.push(`Exit ${String(exitCode)} \u2014 ${String(n)} pipeline phase(s) failed.`);
+  }
+  return lines;
+}
+
 // src/factory/updateContext/runUpdateContextFactory.ts
 var fs49 = __toESM(require("node:fs"));
 var path48 = __toESM(require("node:path"));
@@ -27260,7 +27611,23 @@ function formatCliStderrLine(line, useAnsi) {
 }
 
 // src/cli/main.ts
-var PKG_VERSION = "0.0.14";
+var PKG_VERSION = "0.0.17";
+function isNonEmptyFactoryFailureArray(x) {
+  if (!Array.isArray(x) || x.length === 0) {
+    return false;
+  }
+  for (const item of x) {
+    if (typeof item !== "object" || item === null) {
+      return false;
+    }
+    const r = item;
+    const hasId = typeof r.failureExitId === "string" || typeof r.validationExitId === "string";
+    if (typeof r.phase !== "string" || typeof r.title !== "string" || !hasId) {
+      return false;
+    }
+  }
+  return true;
+}
 function isEasyspecsConfigReadError(e) {
   return e instanceof EasyspecsConfigInvalidJsonError || e instanceof EasyspecsConfigSchemaError;
 }
@@ -27279,6 +27646,20 @@ function logErr(flags, ...a) {
     console.error(...a);
   }
 }
+function logExitCodeSummary(code, flags) {
+  if (code === ExitCode.ok) {
+    return;
+  }
+  if (flags?.json === true) {
+    return;
+  }
+  const line = `Exit ${String(code)} \u2014 ${describeExitCode(code)}`;
+  if (flags) {
+    logErr(flags, line);
+  } else {
+    console.error(line);
+  }
+}
 function buildDoctorInspectPayload(merged, repoConfig) {
   return {
     merged: redactMergedCliSettingsForDump(merged),
@@ -27444,6 +27825,7 @@ async function main() {
     parsed = parseCliWithCommander(process.argv.slice(2));
   } catch (e) {
     console.error(e instanceof Error ? e.message : String(e));
+    logExitCodeSummary(ExitCode.usage);
     process.exit(ExitCode.usage);
   }
   const { flags, positionals } = parsed;
@@ -27465,6 +27847,7 @@ async function main() {
     const unknown = tail.filter((t) => t !== "--overwrite");
     if (unknown.length > 0) {
       logErr(flags, `Unknown arguments for config init: ${unknown.join(", ")}`);
+      logExitCodeSummary(ExitCode.usage, flags);
       process.exit(ExitCode.usage);
     }
     try {
@@ -27488,6 +27871,7 @@ async function main() {
     } catch (e) {
       if (isEasyspecsConfigReadError(e)) {
         console.error(e.message);
+        logExitCodeSummary(ExitCode.misconfiguration, flags);
         process.exit(ExitCode.misconfiguration);
       }
       throw e;
@@ -27499,6 +27883,7 @@ async function main() {
     const extra = rest.slice(1).filter((t) => t.length > 0);
     if (!id || extra.length > 0) {
       logErr(flags, "Usage: easyspecs-cli config set-project-id <easyspecsProjectId>");
+      logExitCodeSummary(ExitCode.usage, flags);
       process.exit(ExitCode.usage);
     }
     try {
@@ -27523,6 +27908,7 @@ async function main() {
     } catch (e) {
       if (isEasyspecsConfigReadError(e)) {
         console.error(e.message);
+        logExitCodeSummary(ExitCode.misconfiguration, flags);
         process.exit(ExitCode.misconfiguration);
       }
       throw e;
@@ -27534,6 +27920,7 @@ async function main() {
     const extra = rest.slice(1).filter((t) => t.length > 0);
     if (!url || extra.length > 0) {
       logErr(flags, "Usage: easyspecs-cli config set-git-remote <url>");
+      logExitCodeSummary(ExitCode.usage, flags);
       process.exit(ExitCode.usage);
     }
     try {
@@ -27558,6 +27945,7 @@ async function main() {
     } catch (e) {
       if (isEasyspecsConfigReadError(e)) {
         console.error(e.message);
+        logExitCodeSummary(ExitCode.misconfiguration, flags);
         process.exit(ExitCode.misconfiguration);
       }
       throw e;
@@ -27576,6 +27964,7 @@ async function main() {
   } catch (e) {
     if (isEasyspecsConfigReadError(e)) {
       console.error(e.message);
+      logExitCodeSummary(ExitCode.misconfiguration, flags);
       process.exit(ExitCode.misconfiguration);
     }
     throw e;
@@ -27594,12 +27983,29 @@ async function main() {
     repoRoot
   });
   const finish = (code, envelope) => {
+    const ffRaw = envelope.factoryFailures;
+    const factoryFailuresPack = isNonEmptyFactoryFailureArray(ffRaw) ? ffRaw.map(
+      (r) => normalizeFactoryFailureRow(
+        r
+      )
+    ) : void 0;
+    const exitMeaningComputed = code !== ExitCode.ok ? factoryFailuresPack !== void 0 && factoryFailuresPack.length > 0 ? exitMeaningFromFactoryFailures(factoryFailuresPack) : describeExitCode(code) : "";
     if (flags.json) {
       printJsonLine({
         command: cmd,
         durationMs: Date.now() - t0,
-        ...envelope
+        ...envelope,
+        ...factoryFailuresPack !== void 0 ? { factoryFailures: factoryFailuresPack } : {},
+        ...code !== ExitCode.ok ? { exitCode: code, exitMeaning: exitMeaningComputed } : {}
       });
+    } else if (code !== ExitCode.ok) {
+      if (factoryFailuresPack !== void 0 && factoryFailuresPack.length > 0) {
+        for (const ln of stderrLinesForFactoryFailures(factoryFailuresPack, code)) {
+          logErr(flags, ln);
+        }
+      } else {
+        logErr(flags, `Exit ${String(code)} \u2014 ${describeExitCode(code)}`);
+      }
     }
     process.exit(code);
     throw new Error("unreachable");
@@ -27620,6 +28026,7 @@ async function main() {
       } catch (e) {
         logErr(flags, e instanceof Error ? e.message : String(e));
         logErr(flags, "Usage: easyspecs-cli doctor [--readiness] [--inspect-config]");
+        logExitCodeSummary(ExitCode.usage, flags);
         process.exit(ExitCode.usage);
       }
       const agentsDir = resolveOpenCodeAgentsDir(repoRoot, repoConfig);
@@ -27684,6 +28091,7 @@ async function main() {
         sessionPathRaw = extracted.sessionPath;
       } catch (e) {
         logErr(flags, e instanceof Error ? e.message : String(e));
+        logExitCodeSummary(ExitCode.usage, flags);
         process.exit(ExitCode.usage);
       }
       const parsedCli = parseAuthLoginTail(tailForCreds);
@@ -27709,6 +28117,7 @@ async function main() {
           flags,
           "Non-interactive (--ci): set easyspecs.auth.ciLogin.email and easyspecs.auth.ciLogin.password in .easyspecs/config.json"
         );
+        logExitCodeSummary(ExitCode.usage, flags);
         process.exit(ExitCode.usage);
       }
       if (sessionPathRaw !== void 0) {
@@ -28043,12 +28452,29 @@ async function main() {
         signal: ctrl.signal,
         log: (line) => logErr(flags, line)
       });
-      const driftExit = dres.exitOk && dres.ok ? ExitCode.ok : dres.ok === false && (dres.code === "INVALID_REFERENCE_PATH" || dres.code === "UNRESOLVED_REFERENCE_ROOT") ? ExitCode.usage : ExitCode.validation;
-      if (dres.exitOk && dres.ok && dres.driftReportPath && !flags.json && !dres.dryRun) {
-        console.log(dres.driftReportPath);
+      if (dres.exitOk && dres.ok) {
+        if (dres.driftReportPath && !flags.json && !dres.dryRun) {
+          console.log(dres.driftReportPath);
+        }
+        const { exitOk: _driftOkA, ...driftPayload } = dres;
+        finish(ExitCode.ok, driftPayload);
+      }
+      if (dres.ok === false) {
+        const row2 = contextDriftFactoryFailureRow(dres.code, dres.error);
+        const driftExit = contextDriftExitCodeFor(dres.code, dres.error);
+        const { exitOk: _driftOkB, ...driftRest } = dres;
+        const envelope = {
+          ...driftRest,
+          ok: false,
+          factoryFailures: [row2],
+          error: composeFactoryValidationError(dres.error, [row2])
+        };
+        if (driftExit === ExitCode.validation) {
+          Object.assign(envelope, primaryFailureAliases([row2]));
+        }
+        finish(driftExit, envelope);
       }
-      const { exitOk: _driftExitOk, ...driftPayload } = dres;
-      finish(driftExit, driftPayload);
+      finish(ExitCode.internal, { ok: false, error: "Unexpected context drift result shape." });
     }
     if (pos[0] === "analysis") {
       const synthesisOnly = positionals.includes("--synthesis-only");
@@ -28152,12 +28578,18 @@ async function main() {
         runBackendSyncImpl
       });
       const res = await runGenerateContextFactory(deps);
-      finish(res.ok ? ExitCode.ok : res.cancelled ? ExitCode.cancelled : ExitCode.validation, {
+      const analysisEnvelope = {
         ok: res.ok,
-        error: res.message,
         cancelled: res.cancelled,
-        totalElapsedMs: res.totalElapsedMs
-      });
+        totalElapsedMs: res.totalElapsedMs,
+        error: res.message
+      };
+      if (!res.ok && !res.cancelled && res.factoryFailures && res.factoryFailures.length > 0) {
+        analysisEnvelope.factoryFailures = res.factoryFailures;
+        Object.assign(analysisEnvelope, primaryFailureAliases(res.factoryFailures));
+        analysisEnvelope.error = composeFactoryValidationError(res.message, res.factoryFailures);
+      }
+      finish(res.ok ? ExitCode.ok : res.cancelled ? ExitCode.cancelled : ExitCode.validation, analysisEnvelope);
     }
     if (pos[0] === "update" && pos[1] === "context") {
       for (const a of pos.slice(2)) {
@@ -28547,10 +28979,13 @@ async function main() {
           command: cmd,
           durationMs: Date.now() - t0,
           ok: false,
-          error: e.message
+          error: e.message,
+          exitCode: ExitCode.misconfiguration,
+          exitMeaning: describeExitCode(ExitCode.misconfiguration)
         });
       } else {
         console.error(e.message);
+        logExitCodeSummary(ExitCode.misconfiguration, flags);
       }
       process.exit(ExitCode.misconfiguration);
     }