yadflow 3.18.1 → 4.0.0-next.1

package/cli/ship.mjs

@@ -1,4 +1,4 @@
-// `yad ship` — commit the staged atomic change AND open its task PR/MR, in one step (build half).
+// `yad ship` — commit the staged atomic change AND open its task PR/MR, in one step (Build).
 // A thin orchestration over the two existing engines: `yad commit` then `yad open-pr`. It holds no
 // commit/PR logic of its own — it reuses runCommit/runOpenPr so the conventions stay in one place.
 // The PR step runs ONLY when the commit actually lands: a failed commit, a tripped atomic guard, or a
@@ -17,14 +17,14 @@ export async function runShip(root, opts = {}) {
     contractChange: opts.contractChange, dryRun: opts.dryRun, force: opts.force,
   });
 
-  if (opts.dryRun) { info('dry run — not committed, PR/MR not opened'); return committed; }
+  if (opts.dryRun) { info('dry run — not committed, PR/MR not opened'); return { ...committed, pr: null }; }
 
   // runCommit signals failure by setting process.exitCode (not by throwing) — honour it and abort the
   // PR step so we never open a PR for a branch whose commit did not land.
-  if (process.exitCode) { info('commit did not land — skipping open-pr'); return committed; }
+  if (process.exitCode) { info('commit did not land — skipping open-pr'); return committed && { ...committed, pr: null }; }
 
-  // Step 2 — open the task PR/MR from the committed template (pushes the branch, auto-assigns the
-  // repo-scoped roster). Pass ONLY an explicit --title: when omitted, runOpenPr derives the title
+  // Step 2 — open the task PR/MR from the committed template (pushes the branch, assigns the committer,
+  // requests no reviewers — E62). Pass ONLY an explicit --title: when omitted, runOpenPr derives the title
   // from the committed subject (the full `<type>: …` form), which the pr-title gate expects — passing
   // the bare --message here would override that with a type-less title and fail the gate.
   const opened = await runOpenPr(root, {
@@ -33,5 +33,6 @@ export async function runShip(root, opts = {}) {
     risk: opts.risk, contractChange: opts.contractChange,
   });
 
-  return { ...committed, ...opened };
+  // The commit's keys, and the PR open-pr opened (or null when it opened none).
+  return { ...committed, pr: opened ?? null };
 }

package/cli/skill.mjs

@@ -0,0 +1,180 @@
+// `yad skill` — which skill runs which step (E6).
+//
+// The engine ships a default for every step (the `skill` column of the step catalogue in
+// epic-state.mjs). A project that wants a different one records it in `.sdlc/skills.json`, and every
+// surface that names a skill — `yad next`, `yad epic new` — reads the project's answer first.
+//
+//   yad skill list [--json]                 every step, its bound skill(s), and where that came from
+//   yad skill bind <step> <skill> [<skill>…]  bind one step; several skills run in the order given
+//   yad skill unbind <step>                 drop the binding and fall back to the engine's default
+//
+// WHY A COMMAND AND NOT JUST A FILE. The file stays hand-editable — it is read by
+// `loadSkillBindings`, and `yad doctor` reports a line that binds nothing rather than correcting it.
+// But a file the engine never writes is a file with no `schemaVersion` in it, and `yad doctor` would
+// then tell the user to migrate the config file it had just asked them to write. Writing it through
+// `writeJSON` stamps the shape like every other engine-written file, and gives the cost warning a
+// place to appear at the moment somebody opts into a chain.
+import path from 'node:path';
+import { c, exists, fail, hand, info, log, ok, readJSONStrict, warn, writeJSON, emitJSON } from './lib.mjs';
+import { loadSkillBindings, stepDef, stepSkills, STEPS } from './epic-state.mjs';
+import { PROJECT_FILES, SCHEMA_VERSION } from './manifest.mjs';
+
+const bail = (message, hint) => { fail(message); if (hint) hand(hint); process.exitCode = 1; };
+
+// Every step the engine actually runs a skill for — the ones worth binding. Shape review gates are
+// driven by `yad gate` and are deliberately not listed: offering to bind one would promise something
+// that never runs.
+const bindableSteps = () => STEPS.filter((s) => s.skill).map((s) => s.id);
+
+const skillsFile = (root) => path.join(root, PROJECT_FILES.skillsConfig);
+
+// Read the file as it is on disk, so a write preserves keys this release does not know about (E50 and
+// E51 add some). `normalizeBindings` is for READING a binding; this is for editing the document.
+//
+// STRICT, unlike the resolver. `loadSkillBindings` treats a broken file as an empty one because
+// `yad next` must still answer; this is a read-modify-write, and doing the same here would rebuild
+// the document from nothing and delete every binding the file held — silently, with a green tick, on
+// the file the docs tell people to hand-edit. Returns null when the bytes do not parse; the caller
+// refuses rather than writing.
+// Returns `{ doc }`, or `{ error }` naming which of the two failures it is. The two are reported with
+// different codes by `yad doctor` on the same bytes, and saying "does not parse" about a file that
+// parses perfectly and is simply a JSON array sends the reader looking for a missing comma.
+const readRaw = (root) => {
+  const file = skillsFile(root);
+  if (!exists(file)) return { doc: {} };
+  let raw;
+  try { raw = readJSONStrict(file, null); } catch { return { error: 'does not parse [YAD-STATE-001]' }; }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { error: 'has the wrong shape [YAD-STATE-002]' };
+  return { doc: raw };
+};
+
+// An existing document plus this edit, ready to write.
+//
+// `schemaVersion` is set OUTRIGHT rather than carried through. `readJSON` back-stamps an unstamped
+// file as shape 1 (rule 1: a file with no version IS shape 1), and `writeJSON` then preserves what it
+// was handed — so writing the document back unchanged would stamp a hand-authored file as shape 1 and
+// `yad doctor` would immediately report it as behind. This command is the file's engine writer; like
+// `writeState`, its write IS the file's migration.
+const withSteps = (raw, steps) => ({ ...raw, schemaVersion: SCHEMA_VERSION, steps });
+
+const brokenFile = (error) => bail(`${PROJECT_FILES.skillsConfig} ${error}`,
+  'fix the file (or restore it from git) first — writing over it would delete every binding it holds');
+
+// A step id has the shape every catalogue id has. An id this release does not KNOW is allowed through
+// with a warning (the file wins, rule 3), so this is not an allowlist — it is a shape guard, and the
+// one thing it has to stop is `__proto__`: assigning that key to the document sets the object's
+// prototype instead of adding a line, `JSON.stringify` then drops it, and the command would report a
+// binding it did not write. `yad epic new` guards its slug the same way.
+const STEP_ID = /^[a-z][a-z0-9-]*$/;
+
+// One row per step the engine can run a skill for: what runs it now, and whether that is the project's
+// choice or the engine's. `source` is the field worth having — "yad-stories" alone never says whether
+// someone chose it.
+// `written` is the set of step ids the FILE mentions, whether or not the value was usable. It is what
+// separates "this project left the step alone" from "this project wrote a line here and the line does
+// nothing" — the second is invisible otherwise, which is the failure `yad skill list` exists to end.
+export function skillRows(root, bindings = loadSkillBindings(root), written = null) {
+  return bindableSteps().map((id) => {
+    const bound = Object.hasOwn(bindings.steps, id) ? bindings.steps[id] : null;
+    return {
+      step: id,
+      phase: stepDef(id).phase,
+      skills: stepSkills(id, bindings),
+      source: bound?.length ? 'project' : (written?.has(id) ? 'ignored' : 'engine'),
+      default: stepDef(id).skill,
+    };
+  });
+}
+
+export function runSkillList(root, { json = false } = {}) {
+  const bindings = loadSkillBindings(root);
+  const { doc, error } = readRaw(root);
+  const written = new Set(error ? [] : Object.keys(doc.steps && typeof doc.steps === 'object' ? doc.steps : {}));
+  const rows = skillRows(root, bindings, written);
+  // Bindings on ids the catalogue does not know are listed too, and marked. They are the ones a person
+  // most needs to see: `yad next` never looks them up, so without this line they are invisible.
+  const extra = [...written]
+    .filter((id) => !stepDef(id))
+    .map((step) => ({
+      step, phase: null,
+      skills: stepSkills(step, bindings),
+      source: Object.hasOwn(bindings.steps, step) ? 'project' : 'ignored',
+      default: null,
+    }));
+
+  if (json) return emitJSON({ ok: true, file: PROJECT_FILES.skillsConfig, steps: [...rows, ...extra] });
+
+  if (error) warn(`${PROJECT_FILES.skillsConfig} ${error} — showing the engine's defaults`);
+  log(`\n  ${c.bold('step')}                 ${c.bold('skill(s)')}`);
+  for (const r of [...rows, ...extra]) {
+    const mark = r.source === 'project' ? c.cyan('•') : (r.source === 'ignored' ? c.red('!') : ' ');
+    const notes = [];
+    if (r.phase === null) notes.push('not a step this yadflow runs');
+    if (r.source === 'ignored') notes.push('the file has a line for this step that names no skill');
+    const note = notes.length ? c.dim(`   (${notes.join('; ')})`) : '';
+    log(`  ${mark} ${r.step.padEnd(18)} ${r.skills.join(c.dim(' → ')) || c.dim('(none)')}${note}`);
+  }
+  const all = [...rows, ...extra];
+  const chosen = all.filter((r) => r.source === 'project').length;
+  const ignored = all.filter((r) => r.source === 'ignored').length;
+  info(chosen
+    ? `${c.cyan('•')} = bound by this project in ${PROJECT_FILES.skillsConfig}; the rest are the engine's defaults`
+    : `every step is on the engine's default — bind one with \`yad skill bind <step> <skill>\``);
+  if (ignored) info(`${c.red('!')} = a line in that file that binds nothing — \`yad doctor\` says which`);
+}
+
+export function runSkillBind(root, { step, skills = [] } = {}) {
+  const names = skills.map((s) => String(s || '').trim()).filter(Boolean);
+  if (!step || !names.length) {
+    return bail('usage: yad skill bind <step> <skill> [<skill> …]',
+      `bindable steps: ${bindableSteps().join(' · ')}`);
+  }
+  if (!STEP_ID.test(step)) {
+    return bail(`\`${step}\` is not a step id`, 'a step id is lower-case letters, digits and dashes — for example `architecture` or `ui-design`');
+  }
+  const def = stepDef(step);
+  // A review gate is refused rather than warned about: nothing would ever invoke the binding, so
+  // writing it would record a decision that silently never happens.
+  if (def && !def.skill) {
+    return bail(`\`${step}\` is a review gate — no skill runs it`,
+      `it is driven by \`yad gate open\` / \`yad gate sync\`. Bind the step it reviews instead${def.reviews ? `: \`${def.reviews}\`` : ''}`);
+  }
+  // An UNKNOWN id is allowed through with a warning, not refused. The file wins for this whole major
+  // (rule 3), and a project may legitimately hold a step from a newer release than the CLI in hand.
+  const { doc, error } = readRaw(root);
+  if (error) return brokenFile(error);
+  const steps = doc.steps && typeof doc.steps === 'object' && !Array.isArray(doc.steps) ? { ...doc.steps } : {};
+  steps[step] = names.length === 1 ? names[0] : names;
+  writeJSON(skillsFile(root), withSteps(doc, steps));
+
+  ok(`${step} → ${names.join(' → ')}`);
+  if (!def) {
+    info(`\`${step}\` is not a step this yadflow runs — the binding is recorded but nothing will invoke it`);
+  }
+  // Closed decision 7: extra skills are a chain, never a panel, and every extra one costs another run.
+  if (names.length > 1) {
+    info(`${names.length} skills run for this step, one after another — each one costs tokens`);
+    info('they chain: each sees what the one before it produced, and the last output is the artifact');
+  }
+  hand(`written to ${PROJECT_FILES.skillsConfig} — \`yad next\` names it from now on (undo with \`yad skill unbind ${step}\`)`);
+  return { step, skills: names, known: !!def, file: PROJECT_FILES.skillsConfig };
+}
+
+export function runSkillUnbind(root, { step } = {}) {
+  if (!step) return bail('usage: yad skill unbind <step>');
+  const { doc, error } = readRaw(root);
+  if (error) return brokenFile(error);
+  const steps = doc.steps && typeof doc.steps === 'object' && !Array.isArray(doc.steps) ? { ...doc.steps } : {};
+  if (!(step in steps)) {
+    return bail(`${step} is not bound in ${PROJECT_FILES.skillsConfig}`, 'see `yad skill list` for what is bound');
+  }
+  delete steps[step];
+  // The file is left behind, holding an empty `steps`, rather than deleted. Deleting a file the user
+  // may have hand-authored — with comments-by-convention, or keys a later release reads — to undo one
+  // line would throw away more than was asked for.
+  writeJSON(skillsFile(root), withSteps(doc, steps));
+  // What runs it now: the engine's default, or nothing at all if this engine does not know the step.
+  const fallback = stepSkills(step, null);
+  ok(`${step} unbound${fallback.length ? ` — back to the engine's default (${fallback.join(' → ')})` : ' — this yadflow runs no skill for it'}`);
+  return { step, skills: fallback, file: PROJECT_FILES.skillsConfig };
+}

package/cli/skip.mjs

@@ -1,45 +1,226 @@
-// `yad skip <epic> <step> --reason "<why>"` (and `--undo`) — mark an OPTIONAL front step N/A for one
-// epic. Today only `ui-design` is skippable: an epic with no user-facing surface (backend/API, data,
-// infra) does not need a UI-design artifact + review gate. The skip stays VISIBLE and auditable — the
-// step is pre-marked `done` with a recorded reason (and actor/date), short-circuited at the gate — and
-// is reversible with `--undo` until the stories review opens. All state logic is the pure
-// `skipStep`/`unskipStep` in epic-state.mjs; this is the thin file-load/save + attribution wrapper.
-import { ok, info, hand, fail, run, writeJSON } from './lib.mjs';
-import { epicRoot, loadLedger, skipStep, unskipStep } from './epic-state.mjs';
-import { loadHub } from './gate.mjs';
-import { resolveCommitterLogin } from './platform.mjs';
-
-// Best-effort auditable actor for `skippedBy`: the roster login for the local git identity, else the
-// raw git user.name, else null. A malformed/absent hub degrades to the raw name — attribution is a
-// nicety on the audit trail, never a gate, so it must not block the skip.
-function skipActor(root) {
-  let roster = [];
-  try { roster = loadHub(root)?.hub?.roster || []; } catch { /* no hub / malformed — attribute by raw git name */ }
-  return resolveCommitterLogin(root, roster)
-    || (run('git', ['config', 'user.name'], { cwd: root }).stdout || '').trim()
-    || null;
+// `yad skip <epic> <step> --reason "<why>"` / `yad unskip <epic> <step>` (E35, E36) and
+// `yad defer <epic> <step> --reason "<why>"` / `yad undefer <epic> <step>` (E37) — set an OPTIONAL Shape
+// step aside for one epic, or put it back. A skip says the step does not apply; a deferral says it does,
+// later. `yad skip … --undo` and `yad defer … --undo` are the same as the undo verbs. `yad defer --debt`
+// (E41) marks the deferral owed back, and `yad undefer` re-opens a deferral even after later work finished.
+// Which steps qualify is a fact about the epic's ROUTE, read from the lifecycle profile it is on (E35,
+// `optionalStepsFor`), not a list this engine keeps: on `classic` and `analysis-first` that is
+// `ui-design` and its gate. E40's short lanes mark NOTHING optional — they drop the steps they do not
+// need from the chain instead — so both verbs are refused outright on one, and `notOptional` says which
+// of the two reasons applies rather than reporting every empty answer as a broken chain.
+// The too-late checks name no step (E36): a route that marks another step optional gets the same verbs
+// with the same guards, measured against whatever steps follow the pair on that route.
+// Putting a step back asks no route at all: restoring a step to the chain can never let a gate pass, and
+// `yad unskip` is the remedy `yad doctor`'s `skip:not-optional` recommends on an epic whose route forbids
+// the skip. Either way the step stays VISIBLE and auditable — marked with a recorded reason (and
+// actor/date), short-circuited at the gate. All state logic is the pure `skipStep` / `unskipStep` /
+// `deferStep` / `undeferStep` in epic-state.mjs; this is the thin file-load/save + attribution wrapper.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ok, info, hand, fail, readJSON, readJSONStrict, warn, writeJSON } from './lib.mjs';
+import { epicRel, epicRoot, epicStories, loadLedger, skipLane, skipStep, unskipLane, unskipStep, deferStep, undeferStep, unblockStep, writeState, isReopenedStep, stepStatus } from './epic-state.mjs';
+import { epicFiles, isVerifiedLedger, productConfigPath } from './manifest.mjs';
+import { refreshIndexAfterWrite } from './product-index.mjs';
+import { readShips } from './ledger.mjs';
+import { loadProduct } from './gate.mjs';
+import { seededSlugs } from './hook.mjs';
+import { actorName } from './platform.mjs';
+
+// Best-effort auditable actor for a record's `by` — who WROTE the record: the platform login the CLI
+// reports (`actorName`), else the raw git user.name, else null. A malformed/absent Product has no
+// platform to ask and degrades to the raw name — attribution is a nicety on the audit trail, never a
+// gate, so it must not block the verb.
+export function recordActor(root) {
+  let platform = null;
+  try { platform = loadProduct(root)?.hub?.platform || null; } catch { /* no Product / malformed — attribute by raw git name */ }
+  return actorName(root, platform);
+}
+
+// The `--json` answer (E1) of every verb here: the step as the file now holds it.
+function stepAnswer(state, epic, step) {
+  const s = (Array.isArray(state.steps) ? state.steps : []).find((x) => x?.id === step) || null;
+  return { epic, step, state: s ? stepStatus(s) : null, debt: s?.debt === true, record: s?.record ?? null, currentStep: state.currentStep ?? null };
+}
+
+// What differs between the two verbs, as a person reads it.
+const VERBS = {
+  skip: {
+    set: skipStep, restore: unskipStep, undo: 'unskip', done: 'marked N/A', undone: 'un-skipped', state: 'skipped',
+    gate: 'its review gate is short-circuited',
+    reasonNote: '--reason is not used when un-skipping: the skip record is removed with the skip',
+  },
+  defer: {
+    set: deferStep, restore: undeferStep, undo: 'undefer', done: 'deferred', undone: 'un-deferred', state: 'deferred',
+    gate: 'the chain continues past it; its review is still owed',
+    reasonNote: '--reason is not used when un-deferring: the record is removed with the deferral',
+  },
+};
+
+// On a verified Product, an epic's `state.json` is CI's alone once it is on the default branch (rule 9):
+// `ledger-guard` rejects every other commit that changes it, and `gate ci` has no step for a skip, a
+// deferral or an unblock. A write here could never land, and the ledger on this machine would drift from
+// the one CI keeps — so these verbs refuse, before anything is written. The question is the one the
+// `ledger-guard` hook asks (`seededSlugs`, cli/hook.mjs), so the hook and the verb never disagree:
+//   - an epic whose ledger is NOT on the base yet still writes. Its seed rides the first review PR (#162):
+//     the epic review on `classic`, the analysis review on `analysis-first`. A skip or deferral written
+//     then is one way once that PR merges, so the verb says so.
+//   - a base that cannot be read is unknown, and allowed with a warning, as the hook allows it. The CI gate
+//     is the one that fails closed.
+// `hub.json` is read leniently, as the hook reads it. A broken `hub.json` or `repos.json` must not stop
+// these verbs on a local ledger (`yad doctor` reports both), and the hook and the verb must give the same
+// answer on the same file.
+function ciOwnsLedger(root, { epic, command, undoCommand = null, runner }) {
+  const hub = readJSON(productConfigPath(root), null);
+  if (!isVerifiedLedger(hub)) return false;
+  const seeded = seededSlugs(root, hub, runner);
+  if (seeded === null) {
+    warn(`this Product's ledger is verified, and origin could not be read — cannot tell whether CI already owns ${epicRel(epic)}/.sdlc/state.json. If the epic's first review PR has merged, ledger-guard will reject this change`);
+    return false;
+  }
+  if (!seeded.has(epic.toLowerCase())) {
+    if (undoCommand) {
+      info(`on this verified Product ${epicRel(epic)}/.sdlc/state.json is yours to write only until the epic's first review PR merges; after that \`${undoCommand}\` is refused until CI has a step for it (checked against origin as last fetched — run \`git fetch origin\` if that PR may have merged)`);
+    }
+    return false;
+  }
+  fail(`\`${command}\` is refused: ${epicRel(epic)}/.sdlc/state.json is on the default branch, and on a verified Product only CI writes it — nothing is written`);
+  hand(`ledger-guard rejects any commit to it that CI did not make, and CI has no step for \`${command}\` yet. An epic's ledger is still yours to write while the epic is new, before its first review PR merges`);
+  process.exitCode = 1;
+  return true;
 }
 
-export async function runSkip(root, { epic, step, reason, undo = false, today } = {}) {
+async function runSetAside(root, verb, { epic, step, reason, debt = false, undo = false, today, runner } = {}) {
+  const V = VERBS[verb];
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
   if (!ledger.state) { fail(`no epic state at ${epicDir} — seed the epic first with yad-epic`); process.exitCode = 1; return; }
-  if (!step) { fail('usage: yad skip <epic> <step> --reason "<why>"   (or: yad skip <epic> <step> --undo)'); process.exitCode = 1; return; }
+  if (!step) {
+    fail(undo ? `usage: yad ${V.undo} <epic> <step>` : `usage: yad ${verb} <epic> <step> --reason "<why>"   (undo it with: yad ${V.undo} <epic> <step>)`);
+    process.exitCode = 1;
+    return;
+  }
+  if (ciOwnsLedger(root, { epic, command: `yad ${undo ? V.undo : verb}`, undoCommand: undo ? null : `yad ${V.undo} ${epic} ${step}`, runner })) return;
 
   // Guard violations throw a YadError (YAD-STATE-004) with a hint — the top-level catch in bin/yad.mjs
   // renders those. Here we only handle the happy path + the two plain-arg checks above.
   if (undo) {
-    unskipStep(ledger.state, step);
-    writeJSON(ledger.files.state, ledger.state);
-    ok(`${step} un-skipped — back in the chain`);
+    V.restore(ledger.state, step);
+    // Putting a step back deletes its record, so a reason given here would be recorded nowhere. Say so
+    // rather than accept it in silence.
+    if (reason != null && reason !== true) info(V.reasonNote);
+    // The same for `--debt`: putting a step back is how a debt is PAID, so the flag means nothing here (E41).
+    if (debt === true) info('--debt is not used when putting a step back: a debt is set with `yad defer --debt`, and putting the step back starts paying it');
+    writeState(ledger.files.state, ledger.state);
+    refreshIndexAfterWrite(root, readJSON(productConfigPath(root), null)); // E19: the default branch of a local Product only
+    // A deferral put back after later work finished RE-OPENS beside that work (E41), and `currentStep`
+    // stays where the chain is — so "back in the chain" and a currentStep line would both mislead.
+    const answer = { ...stepAnswer(ledger.state, epic, step), changed: true, reopened: isReopenedStep(ledger.state, step) };
+    if (answer.reopened) {
+      ok(`${step} ${V.undone} — re-opened beside the work already finished after it, which stays done`);
+      hand(`currentStep stays ${ledger.state.currentStep}; see the re-opened lane with: yad next ${epic}`);
+      return answer;
+    }
+    ok(`${step} ${V.undone} — back in the chain`);
     hand(`currentStep is now ${ledger.state.currentStep}`);
+    return answer;
+  }
+
+  const by = recordActor(root);
+  // A repeat on a step already set aside this way changes nothing but, with `--debt`, the flag — and keeps
+  // the ORIGINAL record. Printing this run's actor, date and reason would misstate who set it aside and why.
+  const steps = Array.isArray(ledger.state.steps) ? ledger.state.steps : [];
+  const before = steps.find((s) => s?.id === step);
+  const already = stepStatus(before) === V.state;
+  const owedBefore = before?.debt === true;
+  V.set(ledger.state, step, { reason, by, at: today, debt: debt === true });
+  writeState(ledger.files.state, ledger.state);
+  refreshIndexAfterWrite(root, readJSON(productConfigPath(root), null)); // E19, as above
+  const after = ledger.state.steps.find((s) => s?.id === step);
+  const owed = after?.debt === true;
+  if (already) {
+    const r = after?.record || {};
+    ok(`${step} was already ${V.done}${r.by ? ` by ${r.by}` : ''}${r.date ? ` on ${r.date}` : ''}${owed && !owedBefore ? ' — now marked as debt' : ' — nothing changed'}`);
+    if (r.reason) info(`reason: ${r.reason}`);
+    return { ...stepAnswer(ledger.state, epic, step), changed: owed && !owedBefore };
+  }
+  ok(`${step} ${V.done}${owed ? ' as debt' : ''}${by ? ` by ${by}` : ''}${today ? ` on ${today}` : ''}`);
+  info(`reason: ${String(reason).trim()}`);
+  hand(`${V.gate}; currentStep is now ${ledger.state.currentStep}  (reverse with \`yad ${V.undo} ${epic} ${step}\`)`);
+  return { ...stepAnswer(ledger.state, epic, step), changed: true };
+}
+
+// `yad skip <epic> <story> --repo <name> --reason "<why>"` / `yad unskip <epic> <story> --repo <name>`
+// (E39) — set a whole Build LANE aside: this story needs no change in this repo. The rules are the pure
+// `skipLane` / `unskipLane` in epic-state.mjs; this reads the story and the ships, and writes
+// `build-state/<story>.json`, which `yad checkpoint --push` commits. There is no lane deferral: a lane that
+// is owed later is simply not driven yet.
+export async function runLaneSkip(root, { epic, story, repo, reason, undo = false, today } = {}) {
+  const epicDir = epicRoot(root, epic);
+  const ledger = loadLedger(epicDir);
+  if (!ledger.state) { fail(`no epic state at ${epicDir} — seed the epic first with yad-epic`); process.exitCode = 1; return; }
+  if (!repo || repo === true) {
+    fail(`usage: yad ${undo ? 'unskip' : 'skip'} ${epic} ${story} --repo <name>${undo ? '' : ' --reason "<why>"'}`);
+    process.exitCode = 1;
     return;
   }
+  const file = path.join(epicFiles(epicDir).buildStateDir, `${story}.json`);
+  const current = readJSONStrict(file, null);
+
+  // Putting a lane back asks nothing but that it was skipped — not even that the story file still exists,
+  // so a story renamed or removed after the skip can still have its skip undone (E39 review).
+  if (undo) {
+    const { buildState, empty } = unskipLane(current, { story, repo });
+    if (empty) fs.rmSync(file);
+    else writeJSON(file, buildState);
+    if (reason != null && reason !== true) info('--reason is not used when un-skipping: the skip record is removed with the skip');
+    ok(`${story} / ${repo} un-skipped — the lane is owed again`);
+    hand(`yad-run adds the lane the next time ${story} is driven in ${repo}; commit this with \`yad checkpoint --push\``);
+    return { epic, story, repo, skipped: false, changed: true, record: null, file: path.relative(root, file) };
+  }
 
-  const by = skipActor(root);
-  skipStep(ledger.state, step, { reason, by, at: today });
-  writeJSON(ledger.files.state, ledger.state);
-  ok(`${step} marked N/A${by ? ` by ${by}` : ''}${today ? ` on ${today}` : ''}`);
+  const entry = epicStories(epicDir).find((st) => st.id === story);
+  if (!entry) { fail(`no story ${story} under ${epicRel(epic)}/stories/`); process.exitCode = 1; return; }
+  // An EARNED stories review only: `done` here, or `satisfied` (reviewed in the parent epic) — the rule E36
+  // gives for "Build can run". `isPassed` would also accept a hand-typed `skipped` or `deferred` review, and
+  // a lane skip over stories nobody approved is what this refusal exists to stop (E39 review).
+  const storiesReview = ledger.state.steps.find((st) => st?.id === 'stories-review');
+  const shippedRepos = readShips(epicDir).filter((sh) => sh.story === story).map((sh) => sh.repo);
+  const by = recordActor(root);
+  const { buildState, already } = skipLane(current, {
+    story, repo, reason, by, date: today, declared: entry.repos, shippedRepos, storiesPassed: ['done', 'satisfied'].includes(stepStatus(storiesReview)),
+  });
+  if (already) {
+    const r = current.repos[repo].record || {};
+    ok(`${story} / ${repo} was already skipped${r.by ? ` by ${r.by}` : ''}${r.date ? ` on ${r.date}` : ''} — nothing changed`);
+    if (r.reason) info(`reason: ${r.reason}`);
+    return { epic, story, repo, skipped: true, changed: false, record: current.repos[repo].record ?? null, file: path.relative(root, file) };
+  }
+  writeJSON(file, buildState);
+  ok(`${story} / ${repo} lane skipped — N/A${by ? ` by ${by}` : ''}${today ? ` on ${today}` : ''}`);
   info(`reason: ${String(reason).trim()}`);
-  hand(`its review gate is short-circuited; currentStep is now ${ledger.state.currentStep}  (reverse with \`yad skip ${epic} ${step} --undo\`)`);
+  hand(`the feature can ship without it; commit this with \`yad checkpoint --push\`  (reverse with \`yad unskip ${epic} ${story} --repo ${repo}\`)`);
+  return { epic, story, repo, skipped: true, changed: true, record: buildState.repos?.[repo]?.record ?? null, file: path.relative(root, file) };
+}
+
+export const runSkip = (root, opts) => runSetAside(root, 'skip', opts);
+export const runDefer = (root, opts) => runSetAside(root, 'defer', opts);
+
+// `yad unblock <epic> <step>` (E37) — clear a recorded blocker once the wait is over. The state logic is
+// the pure `unblockStep`; `build-state/<story>.json` belongs to the skills and is never touched here.
+export async function runUnblock(root, { epic, step, runner } = {}) {
+  const epicDir = epicRoot(root, epic);
+  const ledger = loadLedger(epicDir);
+  if (!ledger.state) { fail(`no epic state at ${epicDir} — seed the epic first with yad-epic`); process.exitCode = 1; return; }
+  if (!step) { fail('usage: yad unblock <epic> <step>'); process.exitCode = 1; return; }
+  if (ciOwnsLedger(root, { epic, command: 'yad unblock', runner })) return;
+  // Read the reason BEFORE the write removes it, so the line can say what was cleared.
+  const steps = Array.isArray(ledger.state.steps) ? ledger.state.steps : [];
+  const was = steps.find((s) => s?.id === step)?.record?.reason || null;
+  unblockStep(ledger.state, step);
+  writeState(ledger.files.state, ledger.state);
+  refreshIndexAfterWrite(root, readJSON(productConfigPath(root), null)); // E19, as above
+  ok(`${step} unblocked — now ${ledger.state.steps.find((s) => s?.id === step).status}`);
+  if (was) info(`cleared: ${was}`);
+  hand(`see what to do now: yad next ${epic}`);
+  return { ...stepAnswer(ledger.state, epic, step), changed: true, cleared: was };
 }

package/cli/thread.mjs

@@ -4,10 +4,10 @@
 // this only DISCOVERS, exactly as yad-docs-sync flags and the build gates block. Node built-ins only.
 import path from 'node:path';
 import fs from 'node:fs';
-import { c, log, ok, info, warn, hand, readJSON, exists } from './lib.mjs';
+import { c, log, ok, info, warn, hand, readJSON, exists, emitJSON, refuse } from './lib.mjs';
 import { readShips } from './ledger.mjs';
 import {
-  epicRoot, isValidEpicId, epicLineage, readFrontmatter, isStubEpic, kindNoun,
+  epicRoot, isValidEpicId, epicLineage, readFrontmatter, isStubEpic, typeNoun, currentPhase, isProductLevel,
   resolveThread, threadEpics, resolveCurrentArtifacts, resolveCurrentStories, THREAD_ARTIFACT_BASES,
 } from './epic-state.mjs';
 
@@ -24,7 +24,7 @@ export const loadBuildLog = (root, epic) => ({ epic, ships: readShips(epicRoot(r
 
 // An epic is SEALED once every authored story is `shipped` (config.yaml change.seal_on). A sealed epic
 // refuses new behaviour (epic-open.sh) — a further change must open a new threaded change-epic, which is
-// what keeps the front artifacts from going stale. An epic with no stories is NOT sealed (nothing built).
+// what keeps the Shape artifacts from going stale. An epic with no stories is NOT sealed (nothing built).
 export function sealedEpic(root, epic) {
   const dir = path.join(epicRoot(root, epic), 'stories');
   if (!exists(dir)) return false;
@@ -54,8 +54,18 @@ export function threadSummary(root, threadOrEpic) {
     const state = readJSON(path.join(epicRoot(root, id), '.sdlc', 'state.json'), null);
     const change = loadChange(root, id);
     return {
-      id, kind: lin.kind, parent: lin.parent, inherits: lin.inherits,
+      // `type` is the word from shape 5 on; `kind` is the same value under the name this key has
+      // always had. Both are emitted for one major so a script reading either keeps working.
+      id, type: lin.type, kind: lin.type, parent: lin.parent, inherits: lin.inherits,
+      // The free grouping tag from epic.md (E31), null when unset. This is the only machine-readable
+      // surface that carries it: `yad next --json` is frozen by the golden test and cannot gain a key.
+      theme: lin.theme,
       currentStep: state?.currentStep || 'unseeded',
+      // Which of the six phases this epic is in — the same answer `yad next` prints, from the same
+      // function. Null is a real answer, not a gap: a stub and any step id this release does not
+      // recognise have no phase, and neither is guessed at. (The product level never reaches here —
+      // a thread is built from epics with an `epic.md` — but the same predicate is asked anyway.)
+      phase: currentPhase(state?.currentStep, { product: isProductLevel(state) }),
       sealed: sealedEpic(root, id),
       stub: isStubEpic(root, id),
       depth: change?.depth || null,
@@ -73,16 +83,18 @@ export function threadSummary(root, threadOrEpic) {
   };
 }
 
-// Colour a node's kind noun for the tree render. The noun words live in one place (`kindNoun`); this
-// only layers the per-kind colour on top, so the two never drift. Unknown kind → uncoloured noun.
-const KIND_COLOR = { feature: c.green, change: c.cyan, defect: c.yellow, hotfix: c.red };
-const kindTag = (kind) => (KIND_COLOR[kind] || ((s) => s))(kindNoun(kind));
+// Colour a node's type noun for the tree render. The noun words live in one place (`typeNoun`); this
+// only layers the per-type colour on top, so the two never drift. Unknown type → uncoloured noun.
+const TYPE_COLOR = {
+  feature: c.green, change: c.cyan, defect: c.yellow, hotfix: c.red, chore: c.dim,
+};
+const typeTag = (t) => (TYPE_COLOR[t] || ((s) => s))(typeNoun(t));
 
 export async function runThread(root, { epic, json = false } = {}) {
   if (!epic) {
     // List every distinct thread root in the project.
     const dir = path.join(root, 'epics');
-    if (!exists(dir)) { log(c.red('no epics/ directory')); process.exitCode = 1; return; }
+    if (!exists(dir)) return refuse('no epics/ directory', null, { json });
     const roots = new Set();
     for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
       if (e.isDirectory() && isValidEpicId(e.name) && exists(path.join(dir, e.name, 'epic.md'))) {
@@ -90,27 +102,37 @@ export async function runThread(root, { epic, json = false } = {}) {
       }
     }
     log(c.bold('\nFeature threads'));
+    // The --json answer (E1): one line per thread, as the list prints it.
+    const threads = [];
     for (const r of [...roots].sort()) {
       const s = threadSummary(root, r);
+      threads.push({ thread: r, theme: s.nodes[0]?.theme ?? null, epics: s.nodes.length, stub: !!s.nodes[0]?.stub, openDebt: s.openDebt.length });
       const debt = s.openDebt.length ? c.red(`  ⚠ ${s.openDebt.length} open reconcile-debt`) : '';
       const stub = s.nodes[0]?.stub ? c.yellow('  [stub · backfill pending]') : '';
-      log(`  ${c.bold(r)}  ${c.dim(`${s.nodes.length} epic(s)`)}${stub}${debt}`);
+      // The genesis epic's grouping theme (E31). This list is where a person looks to see which
+      // threads belong together, so it is the one place the tag earns its keep most.
+      const theme = s.nodes[0]?.theme ? c.dim(` #${s.nodes[0].theme}`) : '';
+      log(`  ${c.bold(r)}${theme}  ${c.dim(`${s.nodes.length} epic(s)`)}${stub}${debt}`);
     }
     log(c.dim('\n  yad thread <epic>   show one thread in full'));
-    return;
+    if (json) return emitJSON({ threads });
+    return { threads };
   }
-  if (!isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic}`)); process.exitCode = 1; return; }
+  if (!isValidEpicId(epic)) return refuse(`invalid epic id: ${epic}`, null, { json });
   const s = threadSummary(root, epic);
-  if (json) { log(JSON.stringify(s, null, 2)); return; }
+  if (json) { emitJSON(s); return; }
 
   log(c.bold(`\nThread ${s.thread}`) + c.dim('  (genesis → tip)'));
   if (s.broken) log(c.red(`  ✗ broken lineage: ${s.broken}`));
   for (const n of s.nodes) {
-    const tag = kindTag(n.kind);
+    const tag = typeTag(n.type);
     const seal = n.sealed ? c.dim(' [sealed]') : '';
     const stub = n.stub ? c.yellow(' [stub · backfill pending]') : '';
     const dep = n.depth ? c.dim(` ${n.depth}`) : '';
-    log(`  • ${c.bold(n.id)}  ${tag}${dep}  ${c.dim('@ ' + n.currentStep)}${seal}${stub}`);
+    // The grouping theme prints only when there is one. An epic with no theme is normal, and an
+    // empty `theme: —` on every line would be noise on a surface people read top to bottom.
+    const theme = n.theme ? c.dim(` #${n.theme}`) : '';
+    log(`  • ${c.bold(n.id)}  ${tag}${dep}${theme}  ${c.dim('@ ' + n.currentStep)}${seal}${stub}`);
     if (n.parent) log(c.dim(`      parent: ${n.parent}   inherits: [${n.inherits.join(', ') || '—'}]`));
     if (n.defect) log(c.dim(`      defect: ${n.defect.severity || '?'} · escaped@${n.defect.escape_stage || '?'} · ${n.defect.root_cause || ''}`));
     if (n.brokenThread) log(c.red(`      ✗ ${n.brokenThread}`));
@@ -150,16 +172,18 @@ function threadRoots(root) {
 
 export async function runReconcile(root, { action = 'check', thread = null } = {}) {
   const roots = thread ? [resolveThread(root, thread).rootId] : threadRoots(root);
-  if (!roots.length) { info('no feature threads found (no epics with epic.md yet)'); return; }
+  if (!roots.length) { info('no feature threads found (no epics with epic.md yet)'); return { action, flags: 0, threads: [] }; }
 
   log(c.bold(`\nChange reconcile  ${c.dim(action)}`));
   let flags = 0;
+  const threads = [];   // the --json answer (E1)
   for (const r of roots) {
     const s = threadSummary(root, r);
     const issues = [];
     if (s.broken) issues.push(`broken lineage: ${s.broken}`);
     for (const n of s.nodes) if (n.brokenThread) issues.push(`${n.id}: ${n.brokenThread}`);
     for (const d of s.openDebt) issues.push(`open reconcile debt on ${d.epicId} — next change blocked until paid`);
+    threads.push({ thread: r, clean: !issues.length, issues });
     if (!issues.length) { ok(`${r} — clean`); continue; }
     flags += issues.length;
     warn(`${r}`);
@@ -168,7 +192,7 @@ export async function runReconcile(root, { action = 'check', thread = null } = {
 
   if (action === 'refresh') {
     log('');
-    info('refresh is advisory: open a reconcile change-epic with `yad-change` (kind: change) threaded to');
+    info('refresh is advisory: open a reconcile change-epic with `yad-change` (type change) threaded to');
     info('the affected feature, then pay any open debt (update artifacts + add a regression test).');
     info('for shipped brownfield code with NO epic at all, anchor it first with `yad-stub`, then thread');
     info('the change/defect off that stub (and run `yad-backfill` to make the anchor real).');
@@ -182,4 +206,5 @@ export async function runReconcile(root, { action = 'check', thread = null } = {
   log('');
   if (flags) { warn(`${flags} item(s) need attention — reconcile is advisory; the gates block at merge`); }
   else { ok('all threads reconciled — no drift, no open debt'); }
+  return { action, flags, threads };
 }