yadflow 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,27 +1,15 @@
-# [2.0.0](https://github.com/abdelrahmannasr/yadflow/compare/v1.4.0...v2.0.0) (2026-06-12)
-
-
-* feat!: rename sdlc-* skills to yad-* and the CLI to yad; feature the report ([ea05f17](https://github.com/abdelrahmannasr/yadflow/commit/ea05f17085f992343fc9d1f25bde24c87815be1a))
+# [2.1.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.0.1...v2.1.0) (2026-06-13)
 
 
 ### Bug Fixes
 
-* rewrite the root .gitlab-ci.yml include when migrating gitlab fragments ([75eeb3a](https://github.com/abdelrahmannasr/yadflow/commit/75eeb3acf4f2c77b43af4577fe5d1d3cc4285258))
+* address CodeRabbit review on the hardening PR ([7dbe9e3](https://github.com/abdelrahmannasr/yadflow/commit/7dbe9e358e731d69ecead6ecac9faa8377c37023))
+* drop useless backtick escapes in a single-quoted doctor hint (lint) ([c0cf1a2](https://github.com/abdelrahmannasr/yadflow/commit/c0cf1a26c15fccc91df15013d6bac83892f2af25))
 
 
 ### Features
 
-* migrate pre-2.0 sdlc-* installs in place via yad update ([f85433f](https://github.com/abdelrahmannasr/yadflow/commit/f85433ff8fb4f54ce0c455abb2d72974f82fd507))
-
-
-### BREAKING CHANGES
-
-* the installed command is now `yad` (was `sdlc`) and the
-skills are invoked as /yad-* (were /sdlc-*). Repos wired before this release
-keep their old sdlc-* workflow files and markers; re-run `yad check --fix`
-to install the renamed ones.
-
-Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+* yad doctor + structured YAD-* error codes with recovery hints ([94f9e9f](https://github.com/abdelrahmannasr/yadflow/commit/94f9e9f6ff6d6d3c83ed29f1cfcc97e32678615c))
 
 # [1.1.0](https://github.com/abdelrahmannasr/sdlc-workflow/compare/v1.0.3...v1.1.0) (2026-06-09)
 

package/README.md

@@ -3,6 +3,8 @@
 [![npm version](https://img.shields.io/npm/v/yadflow?logo=npm)](https://www.npmjs.com/package/yadflow)
 [![CI](https://github.com/abdelrahmannasr/yadflow/actions/workflows/ci.yml/badge.svg)](https://github.com/abdelrahmannasr/yadflow/actions/workflows/ci.yml)
 [![provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://docs.npmjs.com/generating-provenance-statements)
+[![node](https://img.shields.io/node/v/yadflow?logo=node.js)](https://github.com/abdelrahmannasr/yadflow/blob/main/package.json)
+[![security policy](https://img.shields.io/badge/security-policy-brightgreen)](https://github.com/abdelrahmannasr/yadflow/blob/main/SECURITY.md)
 [![report](https://img.shields.io/badge/docs-Yadflow%20report-2471a3)](https://abdelrahmannasr.github.io/yadflow/)
 
 > 📖 **Start here: the [Yadflow Terminology & Workflow Structure Report](https://abdelrahmannasr.github.io/yadflow/)** —
@@ -26,67 +28,8 @@ is human-gated and runs once per epic in the product hub; the **build half** run
 per code repo; **automation** is opt-in and earned. `yad-status` reads it all; `yad-hub-bridge`
 mirrors front-half reviews to real PR/MRs.
 
-```mermaid
-flowchart TD
-    classDef gated fill:#fdebd0,stroke:#ca6f1e,color:#000
-    classDef earns fill:#d6eaf8,stroke:#2471a3,color:#000
-    classDef locked fill:#eaecee,stroke:#566573,color:#000,stroke-dasharray:5 3
-    classDef artifact fill:#fcf3cf,stroke:#b7950b,color:#000
-    classDef sentinel fill:#d5f5e3,stroke:#1e8449,color:#000
-
-    subgraph SETUP["0 · One-time setup (per project)"]
-      direction TB
-      inst["install.sh<br/>copy yad-* skills into IDE dirs"]
-      wire["wire each repo:<br/>yad-checks · yad-pr-template · yad-review-comments"]
-      conn["yad-connect-repos<br/>repos.json + cached code-map"]
-      phub["optional: hub on a platform<br/>detect-hub · roster"]
-      inst --> wire --> conn --> phub
-    end
-
-    subgraph FRONT["A · Front half — product hub · human-gated · once per epic"]
-      direction TB
-      an["yad-analysis<br/>optional → analysis.md"]:::artifact
-      ep["yad-epic<br/>epic.md · assigns EP-&lt;slug&gt;"]:::artifact
-      ar["yad-architecture<br/>architecture.md + locked contract.md"]:::artifact
-      ui["yad-ui<br/>ui-design.md + DESIGN.md"]:::artifact
-      st["yad-stories<br/>repo-tagged stories/EP-&lt;slug&gt;-S0N.md"]:::artifact
-      gAn{{"gate · analysis"}}:::gated
-      gEp{{"gate · epic<br/>base: owner + reviewer"}}:::gated
-      gAr{{"gate · architecture<br/>escalated: + repo domain owners"}}:::gated
-      gUi{{"gate · UI · base"}}:::gated
-      gSt{{"gate · stories<br/>per-repo domain owners"}}:::gated
-      rfb(["currentStep: ready-for-build"]):::sentinel
-      an --> gAn --> ep --> gEp --> ar --> gAr --> ui --> gUi --> st --> gSt --> rfb
-    end
-
-    subgraph BUILD["B · Build half — per story, per code repo"]
-      direction TB
-      sp["yad-spec<br/>Spec Kit ceremony → specs/&lt;story&gt;/"]
-      im["yad-implement<br/>1 task = 1 branch = 1 commit"]:::earns
-      ck["yad-checks<br/>spec-link · contract-check · build/test/lint"]:::earns
-      prm["open PR/MR + yad-pr-template route"]
-      shp["yad-ship<br/>AI review (advisory)"]
-      eng{{"engineer review<br/>human · never automated"}}:::locked
-      merged(["merge → build-log.json"]):::sentinel
-      sp --> im --> ck --> prm --> shp --> eng --> merged
-    end
-
-    subgraph AUTO["C · Automation — earned & reversible"]
-      direction TB
-      run["yad-run<br/>reads automation dial + trust-log.json"]:::earns
-      kill["kill switch → everything human_approve"]
-      run --- kill
-    end
-
-    phub --> an
-    rfb --> sp
-    run -. drives earned back steps .-> im
-    bridge["yad-hub-bridge<br/>review PR/MR ↔ file ledger"]:::gated
-    bridge -. syncs approvals .-> gEp
-    status["yad-status<br/>read-only view over all of it"]
-    status -. observes .-> FRONT
-    status -. observes .-> BUILD
-```
+<!-- Source: docs/diagrams/sdlc-overview.mmd — edit the .mmd and run `npm run diagrams` to regenerate -->
+![Yadflow SDLC overview — setup, human-gated front half, per-story build half, earned automation](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/sdlc-overview.svg)
 
 **Legend.** <span>🟨</span> **artifact** = an author step writes a file and stops; <span>🟧</span>
 **gate** = a human review that must pass (`open → comment → approve → advance`); <span>🟦</span>
@@ -129,12 +72,18 @@ The module ships a zero-dependency CLI, published to npm as
 [`yadflow`](https://www.npmjs.com/package/yadflow). Run it
 with `npx` from your **product hub** repo — no clone needed.
 
+> **Platform support.** Linux and macOS are first-class — the test suite, the bash check gates, and
+> the end-to-end harness all run on both in CI. The CLI shells out to `git` (and the bash gate
+> scripts), so on **Windows use [WSL](https://learn.microsoft.com/windows/wsl/)**; native PowerShell
+> is not yet supported. Requires **Node.js ≥ 18**.
+
 | Command | What it does |
 |---------|--------------|
 | `npx yadflow setup` | Guided first-run wizard (the steps below). |
 | `npx yadflow check` | Read-only report: what is **missing** / **outdated** (drifted) / **stale** (code-context) / **legacy** (pre-2.0 `sdlc-*` names) vs the bundled manifest. |
 | `npx yadflow check --fix` | Reconcile: fill what is missing **and** update what changed — touches nothing already correct. |
 | `npx yadflow update` | Apply drift only (alias for `check --fix --scope=changed`). Also migrates a pre-2.0 install in place: `sdlc-*` skill copies and marker-owned `sdlc-*.yml` CI files are replaced by their `yad-*` names (a same-named file *you* authored is never touched). |
+| `npx yadflow doctor [--json]` | Environment + state health: tools on PATH and platform auth, config files parse and point at real repos, every epic ledger loads. Exit 1 on any failure; `--json` for CI and bug reports. |
 | `yad gate open <epic> <artifact>` | Open the front-half **review PR/MR** for an artifact and mark the step `in_review`. |
 | `yad gate sync <epic> [artifact]` | Pull the PR/MR's reviews + comment threads into the file ledger; **auto-advance** the step when approvals are satisfied, all threads are resolved, and the PR is merged. |
 | `yad gate comments <epic> [artifact]` | Fetch the unresolved review comments to address (then reply on the PR; reviewers resolve their threads). |
@@ -202,6 +151,25 @@ provenance). See [`RELEASING.md`](RELEASING.md).
 > ships the `CHANGELOG.md` in the tarball, and cuts a GitHub release. No manual `npm publish`. See
 > [`RELEASING.md`](RELEASING.md).
 
+### Troubleshooting (`yad doctor` + error codes)
+
+When something is off, run `yad doctor` first — it checks the environment (git, gh/glab auth, node
+version), the project state (`.sdlc/*.json` parse and point at real repos), and every epic ledger,
+with a fix-it hint per finding. Failures carry stable, greppable codes, also printed by any failing
+`yad` command:
+
+| Code | Meaning | Fix |
+|------|---------|-----|
+| `YAD-ENV-001` | git is not installed or not on PATH | install git — every yad command needs it |
+| `YAD-ENV-002` | platform CLI (gh/glab) missing or not authenticated | install it and authenticate — `gh auth login` (GitHub) or `glab auth login` (GitLab); the gate degrades to file-only without it |
+| `YAD-ENV-003` | Node.js older than the supported range | install Node >= 18 |
+| `YAD-STATE-001` | a ledger/config JSON file exists but does not parse | fix the file or restore from git — never delete a ledger blindly |
+| `YAD-STATE-002` | a ledger/config file parses but has the wrong shape | fix the file or restore from git (the message names the field) |
+| `YAD-STATE-003` | a registered repo path is missing or not a git repo | fix the path in `.sdlc/repos.json` or re-connect the repo |
+| `YAD-CFG-001` | `hub.json` names an unknown platform | expected `github`, `gitlab`, or `null` — fix it or re-run `yad setup` |
+
+Filing a bug? Attach `yad doctor --json` — it contains no secrets (names, paths, and check results only).
+
 ## Agent skills (all 17)
 
 The CLI **installs and wires** the module; the skills below are the **agents you invoke by name** in your
@@ -413,16 +381,8 @@ accumulate, and the step moves forward only when the rule is met. **File-only**
 `advance`; **PR-driven** (hub on a platform) ends when the approved, fully-resolved review PR is
 **merged**:
 
-```mermaid
-flowchart LR
-    a["author writes<br/>artifact"] --> o["open<br/>raise review PR/MR"]
-    o --> c["comment<br/>reviewers leave notes"]
-    c -->|owner addresses,<br/>edits in place| c
-    c --> ap["approve<br/>+ resolve threads"]
-    ap --> adv{"rule met,<br/>threads resolved,<br/>merged?"}
-    adv -->|no — names who's missing| o
-    adv -->|yes| nxt(["next step"])
-```
+<!-- Source: docs/diagrams/review-loop.mmd — edit the .mmd and run `npm run diagrams` to regenerate -->
+![Review gate loop — author, open, comment, approve, advance](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/review-loop.svg)
 
 **File-only** — invoke **`yad-review-gate`** with `open` (present the artifact; reviewers comment in
 `reviews/<artifact>--<date>--comments.md`), `approve` (name + role → `.sdlc/approvals.json`), and

package/bin/yad.mjs

@@ -9,6 +9,7 @@ import { isValidEpicId } from '../cli/epic-state.mjs';
 import { runCommit } from '../cli/commit.mjs';
 import { runOpenPr } from '../cli/openpr.mjs';
 import { runRepo } from '../cli/repo.mjs';
+import { runDoctor } from '../cli/doctor.mjs';
 
 const HELP = `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
 
@@ -18,6 +19,8 @@ ${c.bold('Setup & maintenance')}
   yad check --fix      Reconcile: fill what is missing, update what changed
   yad update           Apply drift only (alias for: check --fix --scope=changed);
                        also migrates pre-2.0 sdlc-* installs to the yad-* names
+  yad doctor [--json]  Environment + state health: tools/auth, config files,
+                       repo paths, epic ledgers (exit 1 on any failure)
 
 ${c.bold('Review gate (front half)')}
   yad gate open <epic> <artifact>      Open the review PR/MR; mark the step in_review
@@ -62,6 +65,7 @@ function parseArgs(argv) {
     else if (a === '--contract-change') o.contractChange = true;
     else if (a === '--no-push') o.noPush = true;
     else if (a === '--dry-run') o.dryRun = true;
+    else if (a === '--json') o.json = true;
     else if (a === '-h' || a === '--help') o.help = true;
     else if (a === '-v' || a === '--version') o.version = true;
     else if (a.startsWith('--scope=')) o.scope = a.slice('--scope='.length);
@@ -96,6 +100,9 @@ async function main() {
     case 'update':
       await reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, today });
       break;
+    case 'doctor':
+      await runDoctor(o.dir, { json: o.json });
+      break;
     case 'gate': {
       const [, action, epic, artifact] = o._;
       // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).
@@ -130,7 +137,10 @@ async function main() {
 
 main()
   .catch((err) => {
-    log(c.red(`\nyad failed: ${err?.message || err}`));
+    const code = err?.code && /^YAD-/.test(err.code) ? ` [${err.code}]` : '';
+    log(c.red(`\nyad failed${code}: ${err?.message || err}`));
+    if (err?.hint) log(c.yellow(`  → ${err.hint}`));
+    if (code) log(c.dim('  (see README "Troubleshooting" for this code, or run `yad doctor`)'));
     process.exitCode = 1;
   })
   .finally(closePrompts);

package/cli/doctor.mjs

@@ -0,0 +1,146 @@
+// `yad doctor` — environment + state health, the complement of `yad check` (file drift).
+// Three sections: environment (tools on PATH, auth), project state (config files parse and
+// point at real repos), epics (each ledger loads). Pure reporting: exit 1 on any FAIL,
+// 0 with warnings. `--json` emits the checks for CI / bug reports.
+import path from 'node:path';
+import fs from 'node:fs';
+import { c, log, ok, info, warn, fail, hand, run, has, exists, readJSON, readJSONStrict } from './lib.mjs';
+import { VERSION, PROJECT_FILES } from './manifest.mjs';
+import { loadLedger, epicRoot } from './epic-state.mjs';
+import { gitHead } from './setup.mjs';
+import { cliFor } from './platform.mjs';
+
+const MIN_NODE = 18;
+
+// Each check: { id, section, status: 'ok'|'warn'|'fail', message, hint? }
+function check(checks, id, section, status, message, hint = '') {
+  checks.push({ id, section, status, message, ...(hint ? { hint } : {}) });
+}
+
+export function envChecks(checks) {
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major >= MIN_NODE) check(checks, 'node', 'environment', 'ok', `node ${process.versions.node}`);
+  else check(checks, 'node', 'environment', 'fail', `node ${process.versions.node} is below the supported range [YAD-ENV-003]`, `install Node.js >= ${MIN_NODE}`);
+
+  if (has('git')) check(checks, 'git', 'environment', 'ok', 'git present');
+  else check(checks, 'git', 'environment', 'fail', 'git not found on PATH [YAD-ENV-001]', 'install git — every yad command needs it');
+
+  for (const tool of ['npx', 'bash']) {
+    if (has(tool)) check(checks, tool, 'environment', 'ok', `${tool} present`);
+    else check(checks, tool, 'environment', 'warn', `${tool} not found on PATH`, tool === 'npx' ? 'repomix packing will be skipped' : 'the check gates are bash scripts');
+  }
+}
+
+export function projectChecks(checks, root) {
+  const hubPath = path.join(root, PROJECT_FILES.hubConfig);
+  const regPath = path.join(root, PROJECT_FILES.reposRegistry);
+  const verPath = path.join(root, PROJECT_FILES.version);
+  if (!exists(hubPath) && !exists(regPath) && !exists(verPath)) {
+    check(checks, 'project', 'project', 'warn', 'no yad project here (.sdlc/ not initialised)', 'run `yad setup` to start one — environment checks above still apply');
+    return null;
+  }
+
+  // version stamp
+  const ver = readJSON(verPath, null);
+  if (!ver) check(checks, 'cli-version', 'project', 'warn', `${PROJECT_FILES.version} missing or unreadable`, 'run `yad check --fix`');
+  else if (ver.version !== VERSION) check(checks, 'cli-version', 'project', 'warn', `project stamped v${ver.version}, CLI is v${VERSION}`, 'run `yad update` to reconcile');
+  else check(checks, 'cli-version', 'project', 'ok', `version stamp matches (v${VERSION})`);
+
+  // hub.json: parse + shape
+  let hub = null;
+  if (!exists(hubPath)) {
+    check(checks, 'hub', 'project', 'warn', `${PROJECT_FILES.hubConfig} absent — file-only gate`, 'run `yad setup` to configure a platform + roster');
+  } else {
+    let hubBroken = false;
+    try {
+      hub = readJSONStrict(hubPath, null);
+    } catch (e) {
+      hubBroken = true;
+      check(checks, 'hub', 'project', 'fail', `${PROJECT_FILES.hubConfig} does not parse [${e.code || 'YAD-STATE-001'}]`, e.hint || 'fix the JSON or restore it from git');
+    }
+    if (hubBroken) { /* reported above */ }
+    else if (typeof hub !== 'object' || Array.isArray(hub) || hub === null) check(checks, 'hub', 'project', 'fail', `${PROJECT_FILES.hubConfig} has the wrong shape [YAD-STATE-002]`, 'expected a JSON object');
+    else if (![null, undefined, 'github', 'gitlab'].includes(hub.platform)) check(checks, 'hub', 'project', 'fail', `${PROJECT_FILES.hubConfig}: unknown platform '${hub.platform}' [YAD-CFG-001]`, 'expected github, gitlab, or null');
+    // Mirror gate.mjs's roster shape check so doctor never reports "ok" on a hub the gate would reject.
+    else if (hub.roster !== undefined && !Array.isArray(hub.roster)) check(checks, 'hub', 'project', 'fail', `${PROJECT_FILES.hubConfig}: \`roster\` must be an array [YAD-STATE-002]`, 'fix the file or re-run `yad setup`');
+    else {
+      check(checks, 'hub', 'project', 'ok', `hub: ${hub.platform || 'file-only'}, ${(hub.roster || []).length} reviewer(s)`);
+      // platform CLI + auth (best-effort; auth probing is the user's own session)
+      const cli = cliFor(hub.platform);
+      if (cli) {
+        if (!has(cli)) check(checks, 'platform-cli', 'project', 'warn', `${cli} not found on PATH [YAD-ENV-002]`, `install ${cli} — the gate degrades to file-only without it`);
+        else if (!run(cli, ['auth', 'status']).ok) check(checks, 'platform-cli', 'project', 'warn', `${cli} present but not authenticated [YAD-ENV-002]`, `run \`${cli} auth login\``);
+        else check(checks, 'platform-cli', 'project', 'ok', `${cli} present and authenticated`);
+      }
+    }
+  }
+
+  // repos.json: parse + every entry is a live git repo; staleness vs syncedHead
+  let registry = { repos: [] };
+  let regBroken = false;
+  try {
+    registry = readJSONStrict(regPath, { repos: [] });
+  } catch (e) {
+    regBroken = true;
+    check(checks, 'repos', 'project', 'fail', `${PROJECT_FILES.reposRegistry} does not parse [${e.code || 'YAD-STATE-001'}]`, e.hint || 'fix the JSON or restore it from git');
+  }
+  if (regBroken) { /* reported above */ }
+  else if (!Array.isArray(registry?.repos)) check(checks, 'repos', 'project', 'fail', `${PROJECT_FILES.reposRegistry} has the wrong shape [YAD-STATE-002]`, 'expected a `repos` array');
+  else {
+    for (const repo of registry.repos) {
+      // A missing/empty path must NOT fall back to the project root (which is itself a git repo and
+      // would read as "healthy") — an entry with no path is malformed.
+      if (!repo.path) { check(checks, `repo:${repo.name || '(unnamed)'}`, 'project', 'fail', `${repo.name || '(unnamed)'}: no \`path\` in repos.json [YAD-STATE-003]`, 're-connect the repo (`yad setup`)'); continue; }
+      const repoRoot = path.resolve(root, repo.path);
+      if (!exists(repoRoot)) { check(checks, `repo:${repo.name}`, 'project', 'fail', `${repo.name}: path ${repo.path} does not exist [YAD-STATE-003]`, 'fix the path in repos.json or re-connect the repo'); continue; }
+      const head = gitHead(repoRoot);
+      if (!head) { check(checks, `repo:${repo.name}`, 'project', 'fail', `${repo.name}: ${repo.path} is not a git repository (or has no commits) [YAD-STATE-003]`, 'init/clone the repo, then re-connect it'); continue; }
+      if (repo.syncedHead && head !== repo.syncedHead) check(checks, `repo:${repo.name}`, 'project', 'warn', `${repo.name}: code-context is stale (HEAD moved since last pack)`, 'run `yad repo refresh ' + repo.name + '`');
+      else check(checks, `repo:${repo.name}`, 'project', 'ok', `${repo.name}: git repo, context fresh`);
+    }
+    if (!registry.repos.length) check(checks, 'repos', 'project', 'warn', 'no code repos registered', 'run `yad setup` to connect one');
+  }
+  return { hub, registry };
+}
+
+export function epicChecks(checks, root) {
+  const epicsDir = path.join(root, 'epics');
+  if (!exists(epicsDir)) return;
+  for (const e of fs.readdirSync(epicsDir).sort()) {
+    if (!fs.statSync(path.join(epicsDir, e)).isDirectory()) continue;
+    try {
+      const ledger = loadLedger(epicRoot(root, e));
+      if (!ledger.state) check(checks, `epic:${e}`, 'epics', 'warn', `${e}: no state.json — epic not seeded`, 'author it via yad-epic, or remove the directory');
+      else check(checks, `epic:${e}`, 'epics', 'ok', `${e}: currentStep ${ledger.state.currentStep}`);
+    } catch (err) {
+      check(checks, `epic:${e}`, 'epics', 'fail', `${e}: ${err.message} [${err.code || 'YAD-STATE-001'}]`, err.hint || 'fix the file or restore it from git');
+    }
+  }
+}
+
+export async function runDoctor(root, { json = false } = {}) {
+  const checks = [];
+  envChecks(checks);
+  projectChecks(checks, root);
+  epicChecks(checks, root);
+
+  const failed = checks.filter((x) => x.status === 'fail');
+  const warned = checks.filter((x) => x.status === 'warn');
+  if (json) {
+    log(JSON.stringify({ version: VERSION, ok: failed.length === 0, checks }, null, 2));
+  } else {
+    log(c.bold(`\nyad doctor  ${c.dim('v' + VERSION)}`));
+    let section = '';
+    for (const x of checks) {
+      if (x.section !== section) { section = x.section; log(`\n  ${c.bold(section)}`); }
+      ({ ok, warn, fail })[x.status](x.message);
+      if (x.hint && x.status !== 'ok') hand(x.hint);
+    }
+    log('');
+    if (failed.length) fail(`${failed.length} problem(s) found`);
+    else if (warned.length) info(`healthy with ${warned.length} warning(s)`);
+    else ok('all clear');
+  }
+  if (failed.length) process.exitCode = 1;
+  return { ok: failed.length === 0, failed: failed.length, warned: warned.length, checks };
+}

package/cli/epic-state.mjs

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import { readJSONStrict, writeJSON, fileSha } from './lib.mjs';
+import { err } from './errors.mjs';
 import { epicFiles } from './manifest.mjs';
 
 const RISK_ESCALATORS = ['contract', 'auth', 'payments'];
@@ -98,7 +99,7 @@ export function artifactHash(epicDir, artifact) {
 
 // Shape checks for the ledger files. Fail fast with the exact file named — a wrong-shape ledger
 // silently treated as a default would be rewritten by the next sync, destroying the real data.
-const badShape = (file, what) => new Error(`${file}: ${what} — fix the file or restore it from git`);
+const badShape = (file, what) => err('YAD-STATE-002', `${file}: ${what}`, 'fix the file or restore it from git');
 function requireArray(v, file) {
   if (!Array.isArray(v)) throw badShape(file, 'expected a JSON array');
   return v;

package/cli/errors.mjs

@@ -0,0 +1,25 @@
+// Structured error codes for the `yad` CLI. A YadError carries a stable code (greppable,
+// documented in README "Troubleshooting") and a one-line recovery hint that the top-level
+// catch in bin/yad.mjs prints after the message. Plain Errors still work everywhere; codes
+// are reserved for the failures users actually hit and need to act on.
+export class YadError extends Error {
+  constructor(code, message, hint = '') {
+    super(message);
+    this.name = 'YadError';
+    this.code = code;
+    this.hint = hint;
+  }
+}
+
+// The catalog — single source for doctor, the top-level catch, and the README table.
+export const CODES = {
+  'YAD-ENV-001': 'git is not installed or not on PATH',
+  'YAD-ENV-002': 'the platform CLI (gh/glab) is missing or not authenticated',
+  'YAD-ENV-003': 'Node.js is older than the supported range (>=18)',
+  'YAD-STATE-001': 'a ledger/config JSON file exists but does not parse',
+  'YAD-STATE-002': 'a ledger/config JSON file parses but has the wrong shape',
+  'YAD-STATE-003': 'a registered repo path is missing or not a git repository',
+  'YAD-CFG-001': 'hub.json names an unknown platform (expected github, gitlab, or null)',
+};
+
+export const err = (code, message, hint) => new YadError(code, message, hint);

package/cli/gate.mjs

@@ -14,6 +14,7 @@ import {
   artifactPaths, upsertHubPr,
 } from './epic-state.mjs';
 import { readPr, mapApprovers, createPr } from './platform.mjs';
+import { err } from './errors.mjs';
 
 // ---- tiny frontmatter reader (key: value, and `repos: [a, b]`) ----------------------------------
 function frontmatter(file) {
@@ -64,18 +65,23 @@ function warnUnlockedContract(epicDir, artifact) {
 function loadHub(root) {
   const hubFile = path.join(root, PROJECT_FILES.hubConfig);
   const regFile = path.join(root, PROJECT_FILES.reposRegistry);
+  // Distinguish an ABSENT hub.json (null default → fine, file-only gate) from one that exists but
+  // holds literal `null` (malformed — must not silently downgrade to file-only).
   const hub = readJSONStrict(hubFile, null);
+  if (hub === null && fs.existsSync(hubFile)) {
+    throw err('YAD-STATE-002', `${hubFile}: contains \`null\` — expected a config object`, 'fix the file or re-run `yad setup`');
+  }
   if (hub !== null) {
-    if (typeof hub !== 'object' || Array.isArray(hub)) throw new Error(`${hubFile}: expected a JSON object`);
+    if (typeof hub !== 'object' || Array.isArray(hub)) throw err('YAD-STATE-002', `${hubFile}: expected a JSON object`, 'fix the file or re-run `yad setup`');
     if (![null, undefined, 'github', 'gitlab'].includes(hub.platform)) {
-      throw new Error(`${hubFile}: unknown platform '${hub.platform}' — expected github, gitlab, or null`);
+      throw err('YAD-CFG-001', `${hubFile}: unknown platform '${hub.platform}'`, 'expected github, gitlab, or null — fix the file or re-run `yad setup`');
     }
     if (hub.roster !== undefined && !Array.isArray(hub.roster)) {
-      throw new Error(`${hubFile}: expected \`roster\` to be an array`);
+      throw err('YAD-STATE-002', `${hubFile}: expected \`roster\` to be an array`, 'fix the file or re-run `yad setup`');
     }
   }
   const registry = readJSONStrict(regFile, { repos: [] });
-  if (!Array.isArray(registry?.repos)) throw new Error(`${regFile}: expected a \`repos\` array`);
+  if (!Array.isArray(registry?.repos)) throw err('YAD-STATE-002', `${regFile}: expected a \`repos\` array`, 'fix the file or re-run `yad setup`');
   return { hub, repos: registry.repos };
 }
 
@@ -131,7 +137,7 @@ function writeComments(epicDir, base, today, blocking) {
 // Upsert machine-readable participation records into the comments ledger (the counterpart to the
 // markdown side file) so the ledger — not just reviews/*.md — reflects platform thread state. One
 // record per (step, commenter, round); `round` is the count of prior synced rounds for the step.
-function recordComments(comments, { artifact, stepId, today, roster, repos, blocking }) {
+function recordComments(comments, { artifact, stepId, today, roster, blocking }) {
   if (!blocking.length) return comments;
   const byName = (login) => (roster.find((r) => r.login === login)?.name) || login || 'reviewer';
   const roleOf = (login) => (roster.find((r) => r.login === login)?.role) || 'reviewer';
@@ -386,8 +392,8 @@ export async function gateStatus(root, { epic } = {}) {
   }
 }
 
-export async function gateOpen(root, { epic, artifact, today } = {}) {
-  const { hub, repos } = loadHub(root);
+export async function gateOpen(root, { epic, artifact } = {}) {
+  const { hub } = loadHub(root);
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
   if (!ledger.state) { fail(`no epic state at ${epicDir}`); process.exitCode = 1; return; }

package/cli/lib.mjs

@@ -1,5 +1,6 @@
 // Shared helpers for the `yad` CLI. Node >=18 built-ins only — no dependencies.
 import { createHash } from 'node:crypto';
+import { err } from './errors.mjs';
 import { spawnSync } from 'node:child_process';
 import * as readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
@@ -108,7 +109,7 @@ export function readJSONStrict(p, def = null) {
   try {
     return JSON.parse(fs.readFileSync(p, 'utf8'));
   } catch (e) {
-    throw new Error(`corrupt JSON in ${p}: ${e.message} — fix or delete the file`);
+    throw err('YAD-STATE-001', `corrupt JSON in ${p}: ${e.message}`, 'fix the file or restore it from git — never delete a ledger blindly');
   }
 }
 // Atomic: serialize first, write a sibling tmp file (same dir = same filesystem),

package/cli/reconcile.mjs

@@ -3,7 +3,7 @@
 // manifest: missing setup, drifted files, stale code-context.
 import path from 'node:path';
 import {
-  c, log, ok, info, warn, hand, fail, readJSON, writeJSON, exists,
+  c, log, ok, info, warn, hand, readJSON, writeJSON, exists,
 } from './lib.mjs';
 import { VERSION, PROJECT_FILES } from './manifest.mjs';
 import {

package/cli/setup.mjs

@@ -3,9 +3,9 @@ import path from 'node:path';
 import fs from 'node:fs';
 import {
   c, log, step, ok, info, warn, hand, fail, ask, askYesNo, run, has,
-  exists, asset, copyFile, readJSON, writeJSON,
+  exists, readJSON, writeJSON,
 } from './lib.mjs';
-import { VERSION, IDE_FOLDER_TARGETS, IDE_OPENCODE_DIR, PROJECT_FILES } from './manifest.mjs';
+import { VERSION, IDE_FOLDER_TARGETS, PROJECT_FILES } from './manifest.mjs';
 import { moduleActions, repoActions, hubActions, authorsActions } from './plan.mjs';
 
 const ALL_IDES = [...IDE_FOLDER_TARGETS, '.opencode'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, repo). A BMAD module + 17 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",
@@ -20,6 +20,7 @@
     "bin/",
     "cli/",
     "!cli/test.mjs",
+    "!cli/test-checks.mjs",
     "skills/",
     "docs/index.html",
     "README.md",
@@ -35,7 +36,11 @@
   },
   "scripts": {
     "yad": "node bin/yad.mjs",
-    "test": "node --test cli/test.mjs",
+    "lint": "eslint cli bin",
+    "test": "node --test cli/test.mjs cli/test-checks.mjs",
+    "test:e2e": "bash test/e2e/run.sh",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-exclude='cli/test*.mjs' --test-coverage-lines=70 --test-coverage-branches=70 cli/test.mjs cli/test-checks.mjs",
+    "diagrams": "npx -y @mermaid-js/mermaid-cli -i docs/diagrams/sdlc-overview.mmd -o docs/diagrams/sdlc-overview.svg -b transparent && npx -y @mermaid-js/mermaid-cli -i docs/diagrams/review-loop.mmd -o docs/diagrams/review-loop.svg -b transparent",
     "prepublishOnly": "npm test"
   },
   "keywords": [
@@ -48,7 +53,9 @@
     "spec-driven-development"
   ],
   "devDependencies": {
+    "@eslint/js": "^9.39.4",
     "@semantic-release/changelog": "^6.0.3",
+    "eslint": "^9.39.4",
     "semantic-release": "^25.0.3"
   }
 }