@gluecharm-lab/easyspecs-cli 0.0.17 → 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.
@@ -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

@@ -137,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. |
@@ -153,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
@@ -161,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`**.