@gluecharm-lab/easyspecs-cli 0.0.28 → 0.1.1

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. 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`**. |
+| `--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. Factory / pipeline failures include **`factoryFailures`** (per failed phase), **`failurePhase`**, and **`validationExitId`** (legacy alias of **`failureExitId`**). See [error-code.md](./error-code.md) — OS exit **`5`** is **not** used (**SRS-70**). |
 | `--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

@@ -24,21 +24,21 @@ Quick usage:
 easyspecs-cli help
 ```
 
-### Factory validation reporting (**SRS-57**)
+### Factory failure reporting (**SRS-57** / **SRS-70**)
 
-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:
+When `**easyspecs-cli analysis`** exits **non-zero** with factory failures, human stderr prints a short banner and **one bullet per failed factory phase** (readable label, `**failureExitId**`, normative `**title**`, optional `**detail**`). **OS exit `5` is never used** — each phase maps to a dedicated code (**50–58**), **59** when multiple distinct phases fail in one run, or **49** when unattributed. `**--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)`. |
+| `**factoryFailures**`  | Array of `**{ factory, phase, exitCode, failureExitId, title, validationExitId?, detail?, validationSubcode? }**` — `**failureExitId**` is the canonical `**major.minor**` id (**SRS-58**); `**major**` matches **`process.exit`** (**SRS-70**). See `[error-code.md](./error-code.md)`. |
 | `**failurePhase**`     | Last failed phase in macro order (alias for scripts).                                                                                                                                                                                         |
-| `**validationExitId**` | Matching `**5.x**` for `**failurePhase**`.                                                                                                                                                                                                    |
+| `**validationExitId**` | Legacy alias: same string as `**failureExitId**` when present.                                                                                                                                                                              |
 | `**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)`).                                                  |
+| `**error**`            | Orchestrator message; if several phases failed, a short appendix lists extra `**failureExitId`**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)`.
+**Phase → OS exit (generate_context):** **50** `create_analysis_worktree`, **51** `materialize_opencode_agents`, **52** `synthesis_convergence`, **53** `reference_coverage`, **54** `zero_reference_remediation_convergence`, **55** `reference_coverage_execution_report`, **56** `link_mapping_pipeline`, **57** `assemble_application_context_index`, **58** `backend_context_sync`, **49** unknown / unattributed. Full table: `[error-code.md](./error-code.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.
 
@@ -53,7 +53,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`. 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. |
+| `--json`                                             | On supported exits, prints one JSON summary line on stdout; suppresses some human-oriented stderr unless `--verbose`. On `**analysis**` factory failure, 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. **Exit codes:** **[SRS-70](../../.gluecharm/docs/srs/srs-70.md)** — OS **5** is not used; see `[error-code.md](./error-code.md)`. |
 | `--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.                                                                                                                                                                                                                                                                                 |
@@ -185,7 +185,7 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
 | `diagnose coverage-report`                                       | Same `**--root**` / `**--worktree**`                                                                                                                       | Uses repo/worktree paths only; no extra env in `main.ts`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `diagnose missing-artefacts`                                     | Same `**--root**` / `**--worktree**`                                                                                                                       | Reads artefact snapshot from workspace state; no OpenCode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `diagnose zero-reference`                                        | Optional `**--worktree <path>**` (no `--root` branch in this handler)                                                                                      | `**requireOpenCode**`; `**merged.pipelineOpenCode**` for pool concurrency/argv/timeout. Checkout from `**--worktree**` or snapshot (`[resolveAdHocCheckoutRoot](../../src/cli/main.ts)`). On full success, runs **SRS-51** markdown link graph on `**<checkout>/.gluecharm/context`** before exit (**non-zero** if link validation fails).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `context link-graph`                                             | `**--root workspace`** | `**--root worktree**`, optional `**--worktree <path>**`                                                                           | **SRS-51:** deterministic navigation sections in context markdown under `**<root>/.gluecharm/context`**. No OpenCode. `**--json**`: `**ok**`, `**contextDir**`, `**error**`, `**brokenLinks**`. Exit `**validation**` on broken relative links inside EasySpecs nav regions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `context link-graph`                                             | `**--root workspace`** | `**--root worktree**`, optional `**--worktree <path>**`                                                                           | **SRS-51:** deterministic navigation sections in context markdown under `**<root>/.gluecharm/context`**. No OpenCode. `**--json**`: `**ok**`, `**contextDir**`, `**error**`, `**brokenLinks**`. Exit **78** on broken relative links inside EasySpecs nav regions (**SRS-70**).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `context drift <referencePath>`                                  | `**--label <slug>**`, `**--index <path>**`, `**--dry-run**`. Optional `**--root**` / `**--worktree**` tail tokens are accepted and ignored for v1 routing. | **SRS-56:** analysis worktree → OpenCode drift agent → `**.gluecharm/context/drift/drift-<slug>-<date>.md`** + reference index patch → global `**--promote` / `--no-promote**`. Success stdout: drift report path.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `download context`                                               | Optional `**--force**`, `**--replace-from-cloud**`                                                                                                         | **SRS-49:** requires `**auth`** session. `**GET /api/content/application/:id**` → `**srs_discovery**` ids → `**POST /api/batch/content/srs_discovery/get**` → writes files under `**<repoRoot>/.gluecharm/context**`. `**--force**` overwrites existing paths; `**--replace-from-cloud**` deletes local context files first (preserves root `**easyspecs-upload-target.json**`). `**--json**` stdout: `**downloaded**`, `**skipped**`, `**failed**`, `**localRemoved**`. Exit `**upload**` when any row fails.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `upload context`                                                 | —                                                                                                                                                          | Requires `**auth**` session. Context dir: `**<repoRoot>/.gluecharm/context**`. Project id: `**easyspecs.easyspecsProjectId**` in `**config.json**` only. **SRS-46:** on full success, optional cloud status GET (see `**fetchContextAnalyzedInCloud`**); `**--json**` may add `**contextAnalyzedInCloud**` / `**contextAnalyzedInCloudAt**`; updates `**easyspecs.factory.cloudContext***` when fetch is enabled (legacy `**easyspecs.analysis.cloudContext***`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

package/dist/main.cjs

@@ -10640,17 +10640,53 @@ var fs62 = __toESM(require("node:fs"));
 var path59 = __toESM(require("node:path"));
 
 // src/cli/exitCodes.ts
+var OsExit = {
+  /** Unknown / unclassified factory failure */
+  factoryUnknown: 49,
+  /** Rollup: multiple failed generate_context phases with distinct OS codes in one run */
+  factoryMultiPhaseRollup: 59,
+  createAnalysisWorktree: 50,
+  materializeOpenCodeAgents: 51,
+  synthesisConvergence: 52,
+  referenceCoverage: 53,
+  zeroReferenceRemediation: 54,
+  referenceCoverageExecutionReport: 55,
+  linkMappingPipeline: 56,
+  assembleApplicationContextIndex: 57,
+  backendContextSync: 58,
+  driftEmptyBundle: 60,
+  driftUnresolvedReferenceRoot: 61,
+  driftManifestFailed: 62,
+  driftReportWriteFailed: 63,
+  driftIndexPatchFailed: 64,
+  diagnoseReferenceCoveragePipeline: 70,
+  diagnoseReferenceCoverageThreshold: 71,
+  diagnoseCoordinationDuplicatesPolicy: 72,
+  diagnoseCoordinationDuplicatesEngine: 73,
+  diagnoseCoverageReport: 74,
+  diagnoseZeroReferenceReadCoverage: 75,
+  diagnoseZeroReferenceLinkMapping: 76,
+  diagnoseZeroReferencePool: 77,
+  contextLinkGraph: 78,
+  resumeSynthesisIndex: 79,
+  runSynthesisPipeline: 80,
+  aceLearnTrace: 81,
+  aceAutoLearnPool: 82,
+  updateContextFactory: 83
+};
 var ExitCode = {
   ok: 0,
   usage: 2,
   misconfiguration: 3,
   opencode: 4,
-  validation: 5,
   auth: 6,
   upload: 7,
   cancelled: 8,
   internal: 99
 };
+function failureExitIdFromParts(exitCode, minor) {
+  return `${String(exitCode)}.${String(minor)}`;
+}
 function describeExitCode(code) {
   switch (code) {
     case ExitCode.ok:
@@ -10661,8 +10697,6 @@ function describeExitCode(code) {
       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:
@@ -10671,6 +10705,66 @@ function describeExitCode(code) {
       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.";
+    case OsExit.factoryUnknown:
+      return "Factory pipeline failed (phase could not be classified). See `error` and logs; retry with --verbose.";
+    case OsExit.factoryMultiPhaseRollup:
+      return "Multiple factory pipeline phases failed in one run. Inspect `factoryFailures` for each phase.";
+    case OsExit.createAnalysisWorktree:
+      return "Analysis Git worktree could not be prepared. Check disk space, permissions, and a valid Git checkout.";
+    case OsExit.materializeOpenCodeAgents:
+      return "OpenCode agent files could not be installed into the analysis worktree.";
+    case OsExit.synthesisConvergence:
+      return "Context synthesis did not finish successfully. Inspect OpenCode logs and workstation output.";
+    case OsExit.referenceCoverage:
+      return "Reference coverage could not be computed or written. Check coverage JSON and schema.";
+    case OsExit.zeroReferenceRemediation:
+      return "Zero-reference remediation did not complete. Inspect remediation logs and outputs.";
+    case OsExit.referenceCoverageExecutionReport:
+      return "Coverage execution report could not be generated. Ensure coverage inputs exist.";
+    case OsExit.linkMappingPipeline:
+      return "Context link graph could not be updated. Check coordination JSON and markdown.";
+    case OsExit.assembleApplicationContextIndex:
+      return "Application context index could not be assembled or failed schema validation.";
+    case OsExit.backendContextSync:
+      return "Upload or cloud sync after analysis did not succeed.";
+    case OsExit.driftEmptyBundle:
+      return "Context drift: reference bundle was empty or could not be read.";
+    case OsExit.driftUnresolvedReferenceRoot:
+      return "Context drift: reference root document could not be resolved.";
+    case OsExit.driftManifestFailed:
+      return "Context drift: comparison manifest could not be built.";
+    case OsExit.driftReportWriteFailed:
+      return "Context drift: report markdown could not be written.";
+    case OsExit.driftIndexPatchFailed:
+      return "Context drift: reference index could not be updated with the drift link.";
+    case OsExit.diagnoseReferenceCoveragePipeline:
+      return "diagnose reference-coverage: pipeline or write failed.";
+    case OsExit.diagnoseReferenceCoverageThreshold:
+      return "diagnose reference-coverage: percentNonReferenced exceeded the configured threshold.";
+    case OsExit.diagnoseCoordinationDuplicatesPolicy:
+      return "diagnose coordination-duplicates: strict mode reported duplicates or orphan markdown.";
+    case OsExit.diagnoseCoordinationDuplicatesEngine:
+      return "diagnose coordination-duplicates: scan or I/O failed.";
+    case OsExit.diagnoseCoverageReport:
+      return "diagnose coverage-report: report generation failed.";
+    case OsExit.diagnoseZeroReferenceReadCoverage:
+      return "diagnose zero-reference: could not read coverage / zero-reference inputs.";
+    case OsExit.diagnoseZeroReferenceLinkMapping:
+      return "diagnose zero-reference: link mapping after remediation failed.";
+    case OsExit.diagnoseZeroReferencePool:
+      return "diagnose zero-reference: remediation pool reported failures or cancellation.";
+    case OsExit.contextLinkGraph:
+      return "context link-graph: link mapping pipeline failed.";
+    case OsExit.resumeSynthesisIndex:
+      return "run synthesis resume-*: index assembly after remediation failed.";
+    case OsExit.runSynthesisPipeline:
+      return "run synthesis: pipeline did not complete successfully.";
+    case OsExit.aceLearnTrace:
+      return "ace learn: processing a trace failed.";
+    case OsExit.aceAutoLearnPool:
+      return "ace auto-learn: one or more learn runs failed.";
+    case OsExit.updateContextFactory:
+      return "update context: factory run did not succeed.";
     default:
       return `Non-zero exit (${String(code)}) \u2014 see stderr and any JSON \`error\` field for detail.`;
   }
@@ -21612,9 +21706,19 @@ var FACTORY_PIPELINE_EXIT_CONDITIONS = {
 function factoryFailureDisplayId(row2) {
   return row2.failureExitId;
 }
+function parseMajorFromFailureExitId(id) {
+  const m = /^(\d+)\.\d+$/.exec(id.trim());
+  if (!m) {
+    return void 0;
+  }
+  const n = Number(m[1]);
+  return Number.isFinite(n) ? n : void 0;
+}
 function normalizeFactoryFailureRow(r) {
-  const failureExitId = r.failureExitId ?? r.validationExitId ?? "5.0";
-  const exitCode = typeof r.exitCode === "number" ? r.exitCode : ExitCode.validation;
+  const failureExitId = r.failureExitId ?? r.validationExitId ?? failureExitIdFromParts(OsExit.factoryUnknown, 0);
+  const exitCodeFromField = typeof r.exitCode === "number" ? r.exitCode : void 0;
+  const exitCodeFromId = parseMajorFromFailureExitId(failureExitId);
+  const exitCode = exitCodeFromField ?? exitCodeFromId ?? OsExit.factoryUnknown;
   const factory = r.factory ?? "generate_context";
   const base = {
     factory,
@@ -21625,10 +21729,7 @@ function normalizeFactoryFailureRow(r) {
     ...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;
+  return { ...base, validationExitId: r.validationExitId ?? failureExitId };
 }
 var FACTORY_VALIDATION_PHASE_ORDER = [
   "create_analysis_worktree",
@@ -21644,29 +21745,29 @@ var FACTORY_VALIDATION_PHASE_ORDER = [
 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 PHASE_TO_OS_EXIT = {
+  unknown_factory_phase: OsExit.factoryUnknown,
+  create_analysis_worktree: OsExit.createAnalysisWorktree,
+  materialize_opencode_agents: OsExit.materializeOpenCodeAgents,
+  synthesis_convergence: OsExit.synthesisConvergence,
+  reference_coverage: OsExit.referenceCoverage,
+  zero_reference_remediation_convergence: OsExit.zeroReferenceRemediation,
+  reference_coverage_execution_report: OsExit.referenceCoverageExecutionReport,
+  link_mapping_pipeline: OsExit.linkMappingPipeline,
+  assemble_application_context_index: OsExit.assembleApplicationContextIndex,
+  backend_context_sync: OsExit.backendContextSync
 };
-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 TITLE_BY_PHASE = {
+  unknown_factory_phase: "EasySpecs stopped: the failing pipeline phase could not be identified. Retry with --verbose; report this outcome if it persists.",
+  create_analysis_worktree: "Could not prepare the analysis Git worktree (temporary checkout). Check disk space, repo permissions, and that the project is a valid Git checkout.",
+  materialize_opencode_agents: "Could not install OpenCode agent files into the analysis worktree. Check bundled extension assets and disk permissions under the worktree path.",
+  synthesis_convergence: "Context synthesis did not finish: required context files are still missing or invalid after retries. Inspect OpenCode errors and workstation logs for this phase.",
+  reference_coverage: "Reference coverage could not be computed or written. Check coverage-reference-validation.json prerequisites and disk/schema errors.",
+  zero_reference_remediation_convergence: "Zero-reference remediation did not complete successfully. Inspect remediation logs and zero-reference outputs for this checkout.",
+  reference_coverage_execution_report: "Reference coverage execution report could not be generated. Ensure coverage inputs exist from the coverage phase; see coverage-reference-validation.json.",
+  link_mapping_pipeline: "Context link graph (navigation links) could not be updated. Check coordination JSON and markdown under .gluecharm/context.",
+  assemble_application_context_index: "Application context index could not be assembled or failed schema validation. Inspect index-application-context.json and preceding context files.",
+  backend_context_sync: "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",
@@ -21700,11 +21801,11 @@ function inferValidationSubcode(phase, detail) {
   }
   return void 0;
 }
-function phaseToValidationExitId(phase) {
-  return PHASE_TO_EXIT_ID[phase] ?? "5.0";
+function phaseToSemanticOsExitForGenerateContext(phase) {
+  return PHASE_TO_OS_EXIT[phase] ?? OsExit.factoryUnknown;
 }
-function titleForValidationExitId(validationExitId) {
-  return EXIT_ID_TITLES[validationExitId] ?? EXIT_ID_TITLES["5.0"];
+function titleForGenerateContextPhase(phase) {
+  return TITLE_BY_PHASE[phase] ?? TITLE_BY_PHASE.unknown_factory_phase;
 }
 function readableLabelForFactoryPhase(phase) {
   return READABLE_PHASE_LABEL[phase] ?? phase;
@@ -21713,33 +21814,53 @@ function phaseIndex(key) {
   const i = FACTORY_VALIDATION_PHASE_ORDER.indexOf(key);
   return i >= 0 ? i : 999;
 }
+function finalizeFactoryFailuresForProcessExit(rows) {
+  if (rows.length === 0) {
+    return [];
+  }
+  const candidates = [...new Set(rows.map((r) => r.exitCode))];
+  const processExit = candidates.length > 1 ? OsExit.factoryMultiPhaseRollup : candidates[0] ?? OsExit.factoryUnknown;
+  return rows.map((r, i) => {
+    const minor = processExit === OsExit.factoryMultiPhaseRollup ? i : 0;
+    const fid = failureExitIdFromParts(processExit, minor);
+    return {
+      ...r,
+      exitCode: processExit,
+      failureExitId: fid,
+      validationExitId: fid
+    };
+  });
+}
 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 semantic = failed.map((p) => {
+    const os7 = phaseToSemanticOsExitForGenerateContext(p.key);
     const sub = inferValidationSubcode(p.key, p.detail);
+    const fid = failureExitIdFromParts(os7, 0);
     return {
       factory: "generate_context",
       phase: p.key,
-      exitCode: ExitCode.validation,
-      failureExitId: id,
-      validationExitId: id,
-      title: titleForValidationExitId(id),
+      exitCode: os7,
+      failureExitId: fid,
+      validationExitId: fid,
+      title: titleForGenerateContextPhase(p.key),
       detail: trimDetail(p.detail),
       ...sub !== void 0 ? { validationSubcode: sub } : {}
     };
   });
+  return finalizeFactoryFailuresForProcessExit(semantic);
 }
 function syntheticUnknownFactoryFailure(message) {
+  const fid = failureExitIdFromParts(OsExit.factoryUnknown, 0);
   return [
     {
       factory: "generate_context",
       phase: "unknown_factory_phase",
-      exitCode: ExitCode.validation,
-      failureExitId: "5.0",
-      validationExitId: "5.0",
-      title: titleForValidationExitId("5.0"),
+      exitCode: OsExit.factoryUnknown,
+      failureExitId: fid,
+      validationExitId: fid,
+      title: titleForGenerateContextPhase("unknown_factory_phase"),
       detail: trimDetail(message)
     }
   ];
@@ -21747,7 +21868,8 @@ function syntheticUnknownFactoryFailure(message) {
 function primaryFailureAliases(failures) {
   const last = failures[failures.length - 1];
   if (!last) {
-    return { failurePhase: "unknown_factory_phase", validationExitId: "5.0" };
+    const fid = failureExitIdFromParts(OsExit.factoryUnknown, 0);
+    return { failurePhase: "unknown_factory_phase", validationExitId: fid };
   }
   return {
     failurePhase: last.phase,
@@ -21767,7 +21889,7 @@ function exitMeaningFromFactoryFailures(failures) {
 function composeFactoryValidationError(orchestratorMessage, failures) {
   const m = orchestratorMessage?.trim() ?? "";
   if (failures.length <= 1) {
-    return m.length > 0 ? m : failures[0]?.title ?? "Validation failed.";
+    return m.length > 0 ? m : failures[0]?.title ?? "Factory pipeline failed.";
   }
   const extraIds = failures.slice(1).map((f) => factoryFailureDisplayId(f)).join(", ");
   let appendix = `(+${String(failures.length - 1)} additional phase failure(s): ${extraIds})`;
@@ -25373,9 +25495,6 @@ 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",
@@ -25391,20 +25510,20 @@ var DRIFT_META = {
   },
   EMPTY_BUNDLE: {
     phase: "resolve_reference_bundle",
-    exitCode: ExitCode.validation,
-    minor: 10,
+    exitCode: OsExit.driftEmptyBundle,
+    minor: 0,
     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,
+    exitCode: OsExit.driftUnresolvedReferenceRoot,
+    minor: 0,
     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,
+    exitCode: OsExit.driftManifestFailed,
+    minor: 0,
     title: "Comparison manifest could not be built for drift analysis."
   },
   AGENT_FAILED: {
@@ -25421,14 +25540,14 @@ var DRIFT_META = {
   },
   REPORT_WRITE_FAILED: {
     phase: "validate_and_render_report",
-    exitCode: ExitCode.validation,
-    minor: 13,
+    exitCode: OsExit.driftReportWriteFailed,
+    minor: 0,
     title: "Drift report markdown could not be written under the analysis worktree."
   },
   INDEX_PATCH_FAILED: {
     phase: "update_reference_index",
-    exitCode: ExitCode.validation,
-    minor: 14,
+    exitCode: OsExit.driftIndexPatchFailed,
+    minor: 0,
     title: "Reference root markdown could not be updated with the drift report link."
   },
   PROMOTE_FAILED: {
@@ -25484,10 +25603,7 @@ function contextDriftFactoryFailureRow(code, error) {
     title: meta.title,
     detail
   };
-  if (meta.exitCode === ExitCode.validation) {
-    return { ...base, validationExitId: failureExitId };
-  }
-  return base;
+  return { ...base, validationExitId: failureExitId };
 }
 
 // src/cli/factoryValidationStderr.ts
@@ -28395,7 +28511,7 @@ function formatCliStderrLine(line, useAnsi) {
 }
 
 // src/cli/main.ts
-var PKG_VERSION = "0.0.28";
+var PKG_VERSION = "0.1.1";
 function isNonEmptyFactoryFailureArray(x) {
   if (!Array.isArray(x) || x.length === 0) {
     return false;
@@ -28412,6 +28528,12 @@ function isNonEmptyFactoryFailureArray(x) {
   }
   return true;
 }
+function processExitFromNormalizedFactoryFailures(rows) {
+  return rows?.length ? rows[0].exitCode : OsExit.factoryUnknown;
+}
+function isContextDriftSrs70ValidationExit(code) {
+  return code >= OsExit.driftEmptyBundle && code <= OsExit.driftIndexPatchFailed;
+}
 function isEasyspecsConfigReadError(e) {
   return e instanceof EasyspecsConfigInvalidJsonError || e instanceof EasyspecsConfigSchemaError;
 }
@@ -29012,7 +29134,7 @@ async function main() {
         finish(ExitCode.cancelled, { ok: false, error: "Remediation cancelled.", analysisWorktreePath: analysisRoot });
       }
       if (!poolRes.indexOk) {
-        finish(ExitCode.validation, {
+        finish(OsExit.resumeSynthesisIndex, {
           ok: false,
           error: poolRes.indexError ?? "Index failed after remediation.",
           analysisWorktreePath: analysisRoot
@@ -29029,7 +29151,7 @@ async function main() {
         finish(ExitCode.cancelled, { ok: false, error: "Remediation cancelled.", analysisWorktreePath: analysisRoot });
       }
       if (!poolRes.indexOk) {
-        finish(ExitCode.validation, {
+        finish(OsExit.resumeSynthesisIndex, {
           ok: false,
           error: poolRes.indexError ?? "Index failed after remediation.",
           analysisWorktreePath: analysisRoot
@@ -29082,7 +29204,7 @@ async function main() {
             adHocCreatedAtIso: (/* @__PURE__ */ new Date()).toISOString()
           });
         }
-        finish(result.cancelled ? ExitCode.cancelled : ExitCode.validation, {
+        finish(result.cancelled ? ExitCode.cancelled : OsExit.runSynthesisPipeline, {
           ok: false,
           error: result.error ?? "run synthesis failed",
           cancelled: result.cancelled === true,
@@ -29110,14 +29232,14 @@ async function main() {
           const d = res.document;
           const maxPct = repoConfig.easyspecs?.diagnose?.zeroReference?.maxPercentNonReferenced;
           if (maxPct !== null && maxPct !== void 0 && Number.isFinite(maxPct) && d.metrics.percentNonReferenced > maxPct) {
-            finish(ExitCode.validation, {
+            finish(OsExit.diagnoseReferenceCoverageThreshold, {
               ok: false,
               error: `percentNonReferenced ${String(d.metrics.percentNonReferenced)} > ${String(maxPct)}`
             });
           }
           finish(ExitCode.ok, { ok: true, percentNonReferenced: d.metrics.percentNonReferenced });
         } else {
-          finish(ExitCode.validation, { ok: false, error: res.error ?? "coverage failed" });
+          finish(OsExit.diagnoseReferenceCoveragePipeline, { ok: false, error: res.error ?? "coverage failed" });
         }
       }
       if (sub === "coordination-duplicates") {
@@ -29131,7 +29253,7 @@ async function main() {
         if (res.ok) {
           const strict = repoConfig.easyspecs?.diagnose?.coordinationDuplicates?.strict !== false;
           const bad = strict && ((res.groupCount ?? 0) > 0 || (res.orphanMarkdownCount ?? 0) > 0);
-          finish(bad ? ExitCode.validation : ExitCode.ok, {
+          finish(bad ? OsExit.diagnoseCoordinationDuplicatesPolicy : ExitCode.ok, {
             ok: !bad,
             groupCount: res.groupCount,
             orphanMarkdownCount: res.orphanMarkdownCount,
@@ -29141,7 +29263,7 @@ async function main() {
             groupsByList: res.groupsByList
           });
         }
-        finish(ExitCode.validation, { ok: false, error: res.message ?? "duplicates failed" });
+        finish(OsExit.diagnoseCoordinationDuplicatesEngine, { ok: false, error: res.message ?? "duplicates failed" });
       }
       if (sub === "coverage-report") {
         const rootAbs = resolveAnalysisRoot(repoRoot, rootKind, worktree);
@@ -29153,7 +29275,7 @@ async function main() {
         if (rep.ok) {
           finish(ExitCode.ok, { ok: true, reportPath: rep.outputAbsolutePath });
         } else {
-          finish(ExitCode.validation, { ok: false, error: rep.error ?? "report failed" });
+          finish(OsExit.diagnoseCoverageReport, { ok: false, error: rep.error ?? "report failed" });
         }
       }
       if (sub === "missing-artefacts") {
@@ -29183,7 +29305,7 @@ async function main() {
         requireMinimalGluecharmLayoutAt(analysisRoot);
         const cov = readNonReferencedFilesFromRepositoryRoot(analysisRoot);
         if (!cov.ok) {
-          finish(ExitCode.validation, { ok: false, error: cov.error });
+          finish(OsExit.diagnoseZeroReferenceReadCoverage, { ok: false, error: cov.error });
         } else {
           const zrPaths = cov.paths;
           if (zrPaths.length === 0) {
@@ -29212,7 +29334,7 @@ async function main() {
             const ctxDir = path59.join(analysisRoot, ".gluecharm", "context");
             const lg = runLinkMappingPipeline(ctxDir, { log: (line) => logErr(flags, line) });
             if (!lg.ok) {
-              finish(ExitCode.validation, {
+              finish(OsExit.diagnoseZeroReferenceLinkMapping, {
                 ok: false,
                 completed: poolRes.completed,
                 failures: poolRes.failures,
@@ -29222,7 +29344,7 @@ async function main() {
               });
             }
           }
-          finish(bad ? ExitCode.validation : ExitCode.ok, {
+          finish(bad ? OsExit.diagnoseZeroReferencePool : ExitCode.ok, {
             ok: !bad,
             completed: poolRes.completed,
             failures: poolRes.failures,
@@ -29244,7 +29366,7 @@ async function main() {
         log: (line) => logErr(flags, line)
       });
       if (!res.ok) {
-        finish(ExitCode.validation, {
+        finish(OsExit.contextLinkGraph, {
           ok: false,
           contextDir: contextDir2,
           error: res.error,
@@ -29307,7 +29429,7 @@ async function main() {
           factoryFailures: [row2],
           error: composeFactoryValidationError(dres.error, [row2])
         };
-        if (driftExit === ExitCode.validation) {
+        if (isContextDriftSrs70ValidationExit(driftExit)) {
           Object.assign(envelope, primaryFailureAliases([row2]));
         }
         finish(driftExit, envelope);
@@ -29409,7 +29531,10 @@ async function main() {
         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);
+      finish(
+        res.ok ? ExitCode.ok : res.cancelled ? ExitCode.cancelled : processExitFromNormalizedFactoryFailures(res.factoryFailures),
+        analysisEnvelope
+      );
     }
     if (pos[0] === "update" && pos[1] === "context") {
       for (const a of pos.slice(2)) {
@@ -29437,7 +29562,7 @@ async function main() {
         log: (line) => logErr(flags, line)
       });
       const { exitOk, ...payload } = ures;
-      const code = exitOk ? ExitCode.ok : ures.code === "MISSING_BASELINE" ? ExitCode.usage : ExitCode.validation;
+      const code = exitOk ? ExitCode.ok : ures.code === "MISSING_BASELINE" ? ExitCode.usage : OsExit.updateContextFactory;
       finish(code, payload);
     }
     if (pos[0] === "download" && pos[1] === "context") {
@@ -29700,7 +29825,7 @@ async function main() {
           diagnosticLog: (line) => logErr(flags, line)
         });
         if (!res.ok) {
-          finish(ExitCode.validation, { ok: false, error: res.message });
+          finish(OsExit.aceLearnTrace, { ok: false, error: res.message });
         }
         okCount += 1;
       }
@@ -29726,7 +29851,7 @@ async function main() {
           diagnosticLog: (line) => logErr(flags, line)
         }
       });
-      finish(pool.failed ? ExitCode.validation : ExitCode.ok, {
+      finish(pool.failed ? OsExit.aceAutoLearnPool : ExitCode.ok, {
         ok: pool.failed === 0,
         completed: pool.completed,
         failed: pool.failed,