@gluecharm-lab/easyspecs-cli 0.0.16 → 0.0.18

package/README.md

@@ -5,7 +5,7 @@ Headless **EasySpecs** command-line tool: same orchestration ideas as the **Easy
 ## The three factory-level commands
 
 1. **`easyspecs-cli analysis` — create new context**  
-   Runs the full **Generate Context** factory end to end (synthesis until stable, coverage, remediation, reporting, link mapping, index assembly). Use this when you need a fresh or full rebuild of **`.gluecharm/context`** from the repo. Optional **`--upload`** pushes resulting context to EasySpecs after **`auth login`** and **`config set-project-id`**. **`--synthesis-only`** stops after synthesis; **`--force-new-context-analysis`** overrides skip-when-already-analyzed behavior when the factory would otherwise exit early.
+   Runs the full **Generate Context** factory end to end (synthesis until stable, coverage, remediation, reporting, link mapping, index assembly). Use this when you need a fresh or full rebuild of **`.gluecharm/context`** from the repo. Optional **`--upload`** pushes resulting context to EasySpecs after **`auth login`** and **`config set-project-id`**. **`--synthesis-only`** stops after synthesis; **`--force-new-context-analysis`** overrides skip-when-already-analyzed behavior when the factory would otherwise exit early. If **`git worktree add`** fails because a temp analysis checkout folder was removed but Git still lists it, the CLI runs **`git worktree prune`** in your repository and retries **`git worktree add`** once (same behaviour wherever the CLI creates that temp worktree).
 
 2. **`easyspecs-cli update context` — update context from code churn**  
    Incremental refresh from a **git delta** since the stored baseline (**`easyspecs.factory.updateContext.lastRunAt`**) or, when that is absent, inferred from workspace context mtimes: materialises **`changes-since-date.md`**, runs **scoped** remediation when commits and touched paths warrant it, then optional promotion and **`--upload`**. Use this day to day after **`analysis`** when the codebase moved but specs did not restart from zero.
@@ -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**. |
@@ -258,7 +258,7 @@ Every command the CLI accepts, with command-specific tokens. Global flags above
 | `run synthesis` | — | Context artefact pipeline pass; **`requireOpenCode`** applies. **`--promote` / `--no-promote`** affect promotion after success. |
 | `run synthesis resume-missing` | **`--worktree <path>`** (optional) | Parallel missing-artefact remediation pool on an existing checkout (from **`--worktree`** or last snapshot). **`requireOpenCode`**. |
 | `run synthesis resume-synthesis` | **`--worktree <path>`** (optional) | Same implementation as **`resume-missing`** (alias command path). |
-| `analysis` | **`--synthesis-only`**, **`--upload`**, **`--skip-upload`**, **`--force-new-context-analysis`** (any order among argv tokens after **`analysis`**) | Full **Generate Context** factory unless **`--synthesis-only`** — **create new context** trajectory. **`--upload`** runs backend sync after the factory (needs **`auth login`** + **`easyspecs.easyspecsProjectId`**). Without **`--upload`**, backend sync is skipped. **`--skip-upload`** appears in **`easyspecs-cli help`**; omit **`--upload`** to skip upload. If **`easyspecs.factory.cloudContextAnalyzed`** is **`true`** (legacy **`easyspecs.analysis.cloudContextAnalyzed`**) and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** early with **`analysisSkipped`** (machine JSON fields). |
+| `analysis` | **`--synthesis-only`**, **`--upload`**, **`--skip-upload`**, **`--force-new-context-analysis`** (any order among argv tokens after **`analysis`**) | Full **Generate Context** factory unless **`--synthesis-only`** — **create new context** trajectory. **`--upload`** runs backend sync after the factory (needs **`auth login`** + **`easyspecs.easyspecsProjectId`**). Without **`--upload`**, backend sync is skipped. **`--skip-upload`** appears in **`easyspecs-cli help`**; omit **`--upload`** to skip upload. If **`easyspecs.factory.cloudContextAnalyzed`** is **`true`** (legacy **`easyspecs.analysis.cloudContextAnalyzed`**) and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** early with **`analysisSkipped`** (machine JSON fields). Stale temp-worktree registration (*missing but already registered worktree*): **`git worktree prune`** in the repo root, then one retry of **`git worktree add`**. |
 | `update context` | **`--upload`** (optional; any order in tail) | **Update context** trajectory: git window after baseline → worktree → **`changes-since-date.md`** → optional remediation → **`--promote` / `--no-promote`** → optional **`--upload`** (mtime-scoped files) → **`easyspecs.factory.updateContext.lastRunAt`**. Seed context should exist on **HEAD** in the checkout (the factory may copy from workspace when the worktree lacks context). |
 | `diagnose reference-coverage` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | Reference coverage gate; optional percent limit via **`easyspecs.diagnose.zeroReference.maxPercentNonReferenced`**. |
 | `diagnose coordination-duplicates` | same | Duplicate/orphan reporting; **`easyspecs.diagnose.coordinationDuplicates.strict`**. |

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. |
@@ -119,7 +137,7 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
 | `auth status` | — | Reads session file. |
 | `run synthesis` | — | Single SRS-9 context pass (same as extension **Run Analysis**). **`requireOpenCode`** → executable + credentials unless skip flag. Uses **`merged.pipelineOpenCode`** from **`config.json`**. **`--promote` / `--no-promote`** controls promotion after success. |
 | `run synthesis resume-missing`, `run synthesis resume-synthesis` | Optional **`--worktree <path>`** | Same implementation: resolves checkout via `--worktree` or stored snapshot ([`resolveAdHocCheckoutRoot`](../../src/cli/main.ts)). OpenCode + **`merged.pipelineOpenCode`**. |
-| `analysis` | Optional tokens anywhere in argv: **`--synthesis-only`**, **`--upload`**, **`--force-new-context-analysis`** | **SRS-32** full **Factory** loop: synthesis convergence (until no missing artefacts), coverage, zero-ref, report, **link mapping**, index assembly, optional backend sync. Factory timing from **`merged.factory`** (internal merge shape in [`cliSettings.ts`](../../src/cli/cliSettings.ts)) + **`--ci`** defaults. **`--upload`** requires prior **`auth login`** session. Debug: **`easyspecs.factory.debug`** (legacy **`easyspecs.macro.debug`**). OpenCode options from **`merged.pipelineOpenCode`**. **SRS-46:** if **`easyspecs.factory.cloudContextAnalyzed`** is **`true`** (legacy **`easyspecs.analysis.cloudContextAnalyzed`**) and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** without running the Factory or **`--upload`** (machine fields: **`analysisSkipped`**, **`skipReason`**, **`cloudContextAnalyzedAt`**). |
+| `analysis` | Optional tokens anywhere in argv: **`--synthesis-only`**, **`--upload`**, **`--force-new-context-analysis`** | **SRS-32** full **Factory** loop: synthesis convergence (until no missing artefacts), coverage, zero-ref, report, **link mapping**, index assembly, optional backend sync. Factory timing from **`merged.factory`** (internal merge shape in [`cliSettings.ts`](../../src/cli/cliSettings.ts)) + **`--ci`** defaults. **`--upload`** requires prior **`auth login`** session. Debug: **`easyspecs.factory.debug`** (legacy **`easyspecs.macro.debug`**). OpenCode options from **`merged.pipelineOpenCode`**. **SRS-46:** if **`easyspecs.factory.cloudContextAnalyzed`** is **`true`** (legacy **`easyspecs.analysis.cloudContextAnalyzed`**) and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** without running the Factory or **`--upload`** (machine fields: **`analysisSkipped`**, **`skipReason`**, **`cloudContextAnalyzedAt`**). **SRS-59:** if **`git worktree add`** fails with Git’s *missing but already registered worktree* (temp checkout folder gone but still registered), the CLI runs **`git worktree prune`** in the repo root and retries **`worktree add`** once — see **§ Analysis git checkout** below. |
 | `update context` | Optional **`--upload`** (anywhere in tail, same pattern as **`analysis --upload`**) | **SRS-55:** incremental context refresh — baseline **`easyspecs.factory.updateContext.lastRunAt`** **or** max workspace **`.gluecharm/context`** mtime → git commits after baseline → analysis worktree → seed check (optional copy from workspace if **HEAD** worktree lacks context) → **`changes-since-date.md`** → optional scoped zero-reference remediation → **`--promote` / `--no-promote`** (global) → optional **`--upload`** (files touched this run via mtime gate) → persist **`lastRunAt`**. **`--upload`** requires **`auth`** + **`easyspecs.easyspecsProjectId`**. |
 | `diagnose reference-coverage` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | Gate when **`easyspecs.diagnose.zeroReference.maxPercentNonReferenced`** is a finite number (not **`null`**): failure when metric exceeds it. |
 | `diagnose coordination-duplicates` | Same **`--root`** / **`--worktree`** | **`easyspecs.diagnose.coordinationDuplicates.strict`**: when **`true`** (default), duplicate/orphan issues fail the exit code. |
@@ -135,6 +153,10 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
 | `ace learn` | Optional **`--worktree <path>`** | **`requireOpenCode`**; worktree chosen if `--worktree` points at checkout with **`.opencode/schemas/ace`**, else **`repoRoot`** ([`main.ts`](../../src/cli/main.ts)). **`merged.pipelineOpenCode`** for spawn argv/timeout. |
 | `ace auto-learn` | Optional **`--worktree <path>`** | **`requireOpenCode`**; checkout = `--worktree` if valid git dir, else **`repoRoot`**. **`merged.pipelineOpenCode.maxConcurrentOpenCodeAgents`** caps parallelism. |
 
+### Analysis git checkout (**SRS-59**)
+
+The Factory creates a **detached** analysis checkout under **`$TMPDIR/easyspecs-analysis/easyspecs-NNN`** ([`worktreeManager.ts`](../../src/analysis/worktreeManager.ts)). If the OS removes that folder (or it is deleted) **without** **`git worktree remove`**, Git may still list the path and **`git worktree add`** fails with *missing but already registered worktree*. **SRS-59:** **`easyspecs-cli`** detects that failure class, runs **`git worktree prune`** with **`cwd`** = the repository root (from **`--cwd`** / current directory), then retries **`git worktree add`** **once** at the same allocated path ([`gitWorktreeStaleRecovery.ts`](../../src/analysis/gitWorktreeStaleRecovery.ts)). Stderr may include **`[worktree] git worktree prune — cleared stale registration for <folder> (<absolute path>)`** before the retry. Manual troubleshooting: [`.gluecharm/docs/srs/USER-MANUAL-SRS-59.md`](../../.gluecharm/docs/srs/USER-MANUAL-SRS-59.md).
+
 ---
 
 ## Notes
@@ -143,3 +165,4 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
 - **`download context`** / **`upload`** / **`analysis --upload`** / **`update context --upload`** require a prior **`auth login`** session (**`--email`** / **`--password`**, or **`--ci`** with **`easyspecs.auth.ciLogin`** in **`config.json`**).
 - Unknown commands print help and exit with a usage error.
 - Git subprocesses may set **`GIT_TERMINAL_PROMPT=0`** on the child environment ([`runCoveragePipeline`](../../src/pipelines/coverage/coveragePipeline.ts)).
+- Any command path that **creates** the analysis git worktree (**`analysis`**, **`run synthesis`**, **`update context`**, **`context drift`** without **`--dry-run`**, etc.) benefits from **SRS-59** stale-registration recovery in **`createAnalysisWorktree`**, not only **`analysis`**.