yadflow 3.18.1 → 4.0.0-next.1

package/cli/next.mjs

@@ -1,50 +1,76 @@
 // `yad next` — the unified next-step driver. Read-only: it never writes state or acts. It reads the
 // file ledger and prints the ONE concrete, copy-pasteable next action (and a one-line why), so a user
 // never has to remember which of the 38 skills / gate commands comes next. "Guide, don't act" — the
-// front half still never auto-advances. Once an epic is `ready-for-build`, it reads each story's
+// Shape still never auto-advances. Once an epic is `ready-for-build`, it reads each story's
 // build-state and prints the next BUILD sub-step per repo (spec → tasks → implement → checks → engineer-review)
-// plus the remaining chain — so the build half is guided too, not just hinted at.
+// plus the remaining chain — so Build is guided too, not just hinted at.
 //
 //   yad next                  general orientation across the whole project
 //   yad next <epic>           the single next action for one epic
 //   yad next <epic> --check <step>   exit 0 if <step> is runnable now, else 1 (the precondition guard)
 //   yad next --all            every active epic's next action at once
 //   yad next [<epic>] --json  the same answer as an action object, for an agent or CI
-import fs from 'node:fs';
 import path from 'node:path';
-import { c, log, ok, info, warn, hand, fail, readJSON, exists } from './lib.mjs';
-import { PROJECT_FILES, VERSION } from './manifest.mjs';
-import { epicRoot, loadLedger, nextAction, preconditionsMet, isValidEpicId, epicLineage, kindNoun, DISCOVERY_EPIC } from './epic-state.mjs';
+import { c, log, ok, info, warn, hand, fail, readJSON, exists, emitJSON } from './lib.mjs';
+import { PROJECT_FILES, isVerifiedLedger, productConfigPath, stepAdvance } from './manifest.mjs';
+import { printTeamHint, soloTeamHint } from './people.mjs';
+import { dedupeConsecutive, epicIds, isGateStep, killSwitchOn, loadAutomation, epicRel, epicRoot, loadLedger, loadSkillBindings, stepSkills, nextAction, preconditionsMet, isValidEpicId, epicLineage, typeNoun, phaseOf, stepPhase, profileSteps, lifecycleProfile, PHASES, PRODUCT_DONE, PRODUCT_EPICS } from './epic-state.mjs';
 
 // Is solo mode on? Persisted in hub.json by setup (Phase C/D); default false. Read defensively so a
 // missing/old hub.json never breaks the driver.
+const soloOf = (hub) => !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
 function isSolo(root) {
-  const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig), null);
-  return !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
+  return soloOf(readJSON(productConfigPath(root), null));
 }
-// The setup profile recorded by `yad setup` (codebase / repo_layout / team_size), or null.
-const profileOf = (root) => readJSON(path.join(root, PROJECT_FILES.hubConfig), null)?.profile || null;
-// Has `yad setup` run here? True once the version stamp or hub config exists.
-const isSetUp = (root) => exists(path.join(root, PROJECT_FILES.version)) || exists(path.join(root, PROJECT_FILES.hubConfig));
+// Has `yad setup` run here? True once the version stamp or Product config exists.
+const isSetUp = (root) => exists(path.join(root, PROJECT_FILES.version)) || exists(productConfigPath(root));
 
-// Every epic that has a state ledger, in directory order.
+// Every epic that has a state ledger, the Foundation included, in id order.
 function listEpics(root) {
-  const dir = path.join(root, 'epics');
-  if (!exists(dir)) return [];
-  return fs.readdirSync(dir, { withFileTypes: true })
-    .filter((e) => e.isDirectory() && isValidEpicId(e.name))
-    .map((e) => e.name)
-    .filter((id) => exists(path.join(dir, id, '.sdlc', 'state.json')))
-    .sort();
+  return epicIds(root).filter((id) => exists(path.join(epicRoot(root, id), '.sdlc', 'state.json')));
 }
 
-// The action object for ONE epic, with its lineage kind attached. The single shape both surfaces
+// The action object for ONE epic, with its work-item type attached. The single shape both surfaces
 // consume — `printAction` renders it, `--json` emits it verbatim — so the prose and the machine
 // answer can never drift apart.
-const actionFor = (root, id) => ({
-  ...nextAction(loadLedger(epicRoot(root, id)), { epic: id }),
-  lineageKind: epicLineage(root, id).kind,
-});
+//
+// The key stays `lineageKind` even though the word is now `type`, and there is no `lineageType`
+// beside it. `yad next --json` is deep-equalled by the golden test (cli/test-golden.mjs), which
+// rule 6 says never changes — and a deep-equal breaks on an ADDED key just as hard as a renamed
+// one. The value is the same either way; only the label is old.
+//
+// The lineage may be passed in. `epicLineage` opens and parses `epic.md`, and every printed surface
+// needs the grouping theme off the SAME read — without this the file would be parsed twice per epic
+// on every `yad next`. The default keeps the `--json` path a one-liner, where the theme is not wanted.
+// `bindings` is passed in for the same reason `lin` is: every loop below renders many epics, and the
+// project's skill bindings are ONE file for all of them. The default keeps the single-epic callers a
+// one-liner; a loop reads the file once and hands the same object to every row.
+const actionFor = (root, id, lin = epicLineage(root, id), bindings = loadSkillBindings(root)) => {
+  const ledger = loadLedger(epicRoot(root, id));
+  return {
+    ...nextAction(ledger, { epic: id, bindings }),
+    lineageKind: lin.type,
+    // Which ROUTE this epic RECORDED, carried so `phaseLine` can mark a phase that route never enters
+    // (E40). The recorded key ONLY — never matched from the chain, which is the one place in this file
+    // that deliberately asks less than `epicProfileId` does.
+    //
+    // A chain is allowed to be short without its route being short: every hand-written and pre-shape-6
+    // ledger is a truncated `classic`, and matching would read `[epic, epic-review]` as the chore lane
+    // and grey out two phases the epic is going to walk. Matching is the right fallback where the
+    // answer only has to be the best available one — what a step may skip, what `yad doctor` reports.
+    // Here it would be a visible claim about an epic's future, made from a guess, and it would flip
+    // the moment the next gate write stamped `classic` on the same file. An epic that never says
+    // which route it is on simply gets the line it got before the short lanes existed.
+    route: lifecycleProfile(ledger?.state?.profile) ? ledger.state.profile : null,
+  };
+};
+
+// One `epic.md` read, both things that come out of it: the action to print and the tag to print
+// beside it. Every printed path in this file goes through here.
+const rowFor = (root, id, bindings = loadSkillBindings(root)) => {
+  const lin = epicLineage(root, id);
+  return { action: actionFor(root, id, lin, bindings), theme: lin.theme };
+};
 
 // EP-checkout-S03 → S03 (the compact lane label for the roll-up). Falls back to the full id.
 const shortStory = (s) => (s && s.match(/S\d+$/i)?.[0]) || s || '(story)';
@@ -52,114 +78,330 @@ const shortStory = (s) => (s && s.match(/S\d+$/i)?.[0]) || s || '(story)';
 // Every per-repo lane across the build, flattened with its story id attached.
 const buildLanes = (builds = []) => builds.flatMap((b) => b.repos.map((r) => ({ ...r, story: b.story })));
 
-// The dial note for a build lane: a machine_advance lane is driven by yad-run; everything else stops
+// The dial note for a build lane: an `advance: auto` lane is driven by yad-run; everything else stops
 // for a human (the locked engineer-review always does).
-function dialNote(r) {
-  if (r.locked) return c.dim('human merge gate');
-  return r.automation === 'machine_advance'
-    ? c.dim('machine_advance — yad-run auto-drives')
-    : c.dim('human_approve');
+//
+// This is the sentence a person LEARNS the vocabulary from, so it says the new words even though the
+// `--json` key beside it still says `automation` (see buildNextForRepo). Different audiences: the key
+// is read by scripts and is frozen by the golden test; this line is read by people.
+//
+// The kill switch (E34) holds an `auto` lane at human, and the line says so: a lane that reads `auto` while
+// nothing drives it would send a person to wait for a run that is never coming.
+//
+// The gate test is the engine's (`isGateStep`), not `locked` alone: since E34 a `locked` Build author step is
+// not held at human, so calling it "a human merge gate" would say the opposite of what runs.
+function dialNote(r, automation = null) {
+  if (isGateStep({ id: r.step, locked: r.locked })) return c.dim('human merge gate');
+  if (stepAdvance(r) !== 'auto') return c.dim('advance: human');
+  // A broken file holds every step at human too, and `yad unkill` cannot fix a file it cannot read.
+  if (automation?.error) return c.dim(`advance: auto — held at human: .sdlc/automation.json ${automation.error} (yad doctor)`);
+  return killSwitchOn(automation)
+    ? c.dim('advance: auto — held at human by the kill switch (yad unkill)')
+    : c.dim('advance: auto — yad-run auto-drives');
+}
+
+// ---- how a step's skills read on a line (E6) -----------------------------------------------------
+//
+// A step's skill is no longer one string the engine chose: `.sdlc/skills.json` can bind a different
+// one, or several. The resolver puts the first in `skill` and, ONLY when there is more than one, the
+// whole chain in `skills` — so everything here reads `skills` when it is there and falls back to the
+// single field, and a project that binds nothing prints exactly what it printed before.
+const skillList = (a) => a?.skills || (a?.skill ? [a.skill] : []);
+
+// "the yad-architecture skill", or for a bound chain "the shape-it skill, then yad-stories". Closed
+// decision 7: several skills on one step are a CHAIN, not a panel — they run in the order given, each
+// seeing what the one before it produced, and the last output is the artifact.
+function skillPhrase(a, fallback = null) {
+  const ids = skillList(a);
+  if (!ids.length) return `the ${c.bold(fallback || '(no skill)')} skill`;
+  const [first, ...rest] = ids;
+  const then = rest.length ? `, then ${rest.map((s) => c.bold(s)).join(', then ')}` : '';
+  return `the ${c.bold(first)} skill${then}`;
 }
 
+// The cost warning decision 7 asks for. Extra skills are opt-in, and each one is another model run —
+// said here, where the chain is actually about to be invoked, rather than in a document nobody reopens
+// after binding. Null for the normal one-skill step, so the common case gains no noise.
+const costNote = (a) => {
+  const n = skillList(a).length;
+  return n > 1 ? `${n} skills run for this step, one after another — each one costs tokens` : null;
+};
+
 // The detailed per-story/per-repo build lanes for `printAction`. Each open lane is a 2-line block:
 // a header naming the active step + dial, then the actionable `▸` skill line with the remaining chain.
-function printBuildLanes(builds) {
+function printBuildLanes(builds, automation = null) {
   for (const lane of buildLanes(builds)) {
     const where = `${c.cyan(lane.story || '(story)')} / ${c.bold(lane.repo)}`;
     if (lane.shipped) { log(`    ${where} ${c.green('— shipped ✓')}`); continue; }
+    // A lane skipped whole (E39): nothing to drive, and the reason is the point of the record.
+    if (lane.status === 'skipped') { log(`    ${where} ${c.dim(`— skipped (N/A)${lane.record?.reason ? `: ${lane.record.reason}` : ''}`)}`); continue; }
     // No resolvable next skill (an empty/half-seeded build-state file): show it as not-started, no ▸.
     if (!lane.skill) { log(`    ${where} ${c.dim('— not started yet (no build steps recorded)')}`); continue; }
-    log(`    ${where} ${c.dim('—')} ${c.bold(lane.step)}  (${dialNote(lane)})`);
-    const rest = (lane.chain || []).slice(1);
+    log(`    ${where} ${c.dim('—')} ${c.bold(lane.step)}  (${dialNote(lane, automation)})`);
+    // `chain` is every skill still to run in this lane, the active step's own included — so drop this
+    // step's own off the front, or a bound chain would print its second skill again as if it came
+    // later. Folded through the SAME helper the chain was built with: `chain` collapses consecutive
+    // duplicates, so a step bound to one skill twice has two entries here and one there, and slicing
+    // by the raw count would swallow the next step's skill.
+    const rest = (lane.chain || []).slice(dedupeConsecutive(skillList(lane)).length);
     const then = rest.length ? `   ${c.dim(`then → ${rest.join(' → ')}`)}` : '';
-    hand(`invoke the ${c.bold(lane.skill)} skill${then}`);
+    hand(`invoke ${skillPhrase(lane)}${then}`);
+    const note = costNote(lane);
+    if (note) info(c.dim(note));
   }
 }
 
 // A short, copy-pasteable line for one action — the `▸` line a user can act on directly.
-function actionLine(a, { solo } = {}) {
+//
+// `bindings` arrives here as well as on the action object, because two of these lines name a skill
+// the RESOLVER never put on the action: the `discovery-done` hand-off to the epic step, and the Build
+// fallback printed when no story has a build-state yet. Both are the engine naming a step's skill in
+// prose, so both must name the project's choice — otherwise `yad next` and `yad skill list` disagree
+// about the same project.
+function actionLine(a, { solo, bindings = null, verified = false } = {}) {
+  const runs = (stepId, fallback) => stepSkills(stepId, bindings)[0] || fallback;
   switch (a.kind) {
     case 'new':
-      return `invoke the ${c.bold(a.skill)} skill ${c.dim('(author the epic)')}`;
+      return `invoke ${skillPhrase(a)} ${c.dim('(author the epic)')}`;
     case 'author':
-      return `invoke the ${c.bold(a.skill || ('yad-' + a.step))} skill ${c.dim(`(author ${a.artifact})`)}`;
+      return `invoke ${skillPhrase(a, `yad-${a.step}`)} ${c.dim(`(author ${a.artifact})`)}`;
     case 'review-open':
     case 'review-sync':
       return `${c.bold(a.command)}${solo ? c.dim('   (solo: no approval needed — just merge your own PR)') : ''}`;
     case 'build': {
-      // In the build half: compact the lanes to "N lane(s) in build — next: <skill> @ <story>/<repo>".
+      // In Build: compact the lanes to "N lane(s) in build — next: <skill> @ <story>/<repo>".
       if (a.builds?.length) {
-        const open = buildLanes(a.builds).filter((r) => !r.shipped);
-        if (!open.length) return c.dim('build half — every lane shipped');
-        // Headline the first lane with a resolvable next skill; if none, the half is started but unspecced.
-        const first = open.find((r) => r.skill);
-        if (!first) return c.dim(`${open.length} lane(s) in build — not specced yet`);
-        return `${c.dim(`${open.length} lane(s) in build — next:`)} ${c.bold(first.skill)} ${c.dim(`@ ${shortStory(first.story)}/${first.repo}`)}`;
+        const all = buildLanes(a.builds);
+        const open = all.filter((r) => !r.shipped && r.status !== 'skipped');
+        if (open.length) {
+          // Headline the first lane with a resolvable next skill; if none, the half is started but unspecced.
+          const first = open.find((r) => r.skill);
+          if (!first) return c.dim(`${open.length} lane(s) in build — not specced yet`);
+          return `${c.dim(`${open.length} lane(s) in build — next:`)} ${c.bold(first.skill)} ${c.dim(`@ ${shortStory(first.story)}/${first.repo}`)}`;
+        }
+        if (all.some((r) => r.shipped)) return c.dim(all.some((r) => r.status === 'skipped') ? 'Build — every lane shipped or skipped' : 'Build — every lane shipped');
+        // Every recorded lane is SKIPPED and none shipped (E39 review): a skip written before Build began
+        // creates the build-state file on its own. Build has not started, so fall through to the yad-run hint.
       }
-      return `${c.bold('yad-run')} ${c.dim('(or per story: yad-spec → yad-implement → yad ship → yad-engineer-review)')}`;
+      return `${c.bold('yad-run')} ${c.dim(`(or per story: ${runs('spec', 'yad-spec')} → ${runs('implement', 'yad-implement')} → yad ship → ${runs('engineer-review', 'yad-engineer-review')})`)}`;
     }
+    case 'foundation-done':
     case 'discovery-done':
-      return `invoke the ${c.bold('yad-epic')} skill ${c.dim('(seed a feature epic from roadmap.md)')}`;
+      return `invoke the ${c.bold(runs('epic', 'yad-epic'))} skill ${c.dim('(seed the next feature from roadmap.md — `yad foundation status` shows which are started)')}`;
     case 'backfill-pending':
       return `invoke the ${c.bold('yad-backfill')} skill ${c.dim('(document the code, then `yad-backfill promote` — or thread bugs now with yad-change)')}`;
     case 'backfill-done':
       return `invoke the ${c.bold('yad-change')} skill ${c.dim('(documented anchor — evolve it by threading a change/defect off it)')}`;
+    // A blocked step (E38) has no command to run, and that is the point: the thing in the way is not in
+    // this tool. The line says who recorded the block and when, and how to clear it once the wait is
+    // over (E37); the reason itself is on the line above. It used to print `by` as "waiting on", but
+    // `by` is who WROTE the record, on every record — the `yad-run` skill writes the login the run ran as —
+    // so it named the wrong party.
+    case 'blocked': {
+      const who = a.record?.by ? ` — recorded by ${a.record.by}${a.record.date ? ` on ${a.record.date}` : ''}` : '';
+      // On a verified Product the verb refuses once the ledger is on the default branch, and CI has no step
+      // for it yet: naming it there would send the reader to a refusal (E34 review).
+      const clear = verified
+        ? 'on a verified Product only CI can clear it once the epic\'s ledger is on the default branch, and CI has no step for that yet (yad unblock refuses)'
+        : `clear it with yad unblock ${a.epicId} ${a.step} once resolved`;
+      return c.dim(`blocked${who} — ${clear}`);
+    }
     default:
       return c.dim('nothing to do');
   }
 }
 
 // Full, friendly printout for a single epic.
-function printAction(a, { solo } = {}) {
-  // Prefix the id with the kind noun (Defect / Change request / Hotfix / Epic) so a glance says what
-  // kind of work this is. The discovery front-zero is not a feature epic — leave it un-prefixed.
-  const noun = a.lineageKind && a.epicId !== DISCOVERY_EPIC ? `${kindNoun(a.lineageKind)} ` : '';
-  log(`\n  ${c.bold(`${noun}${a.epicId || '(epic)'}`)} ${c.dim(`— ${a.why}`)}`);
-  // In the build half with live lanes, print each story/repo's next sub-step + remaining chain instead
+//
+// The grouping theme arrives as an argument rather than as another field on the action object:
+// `printAction` renders `a` and `--json` emits the SAME `a` verbatim, and that JSON is deep-equalled
+// by the golden test, which an added key breaks (see actionFor). It comes from `rowFor`, off the same
+// `epic.md` read the action's own `lineageKind` came from.
+function printAction(a, { solo, theme: tag = null, bindings = null, automation = null, verified = false } = {}) {
+  // Prefix the id with the type noun (Defect / Change request / Hotfix / Chore / Epic) so a glance
+  // says what kind of work this is. The product level is not a feature — leave it un-prefixed.
+  const noun = a.lineageKind && !PRODUCT_EPICS.includes(a.epicId) ? `${typeNoun(a.lineageKind)} ` : '';
+  // The free grouping tag, printed only when the epic has one — most do not, and an empty marker on
+  // every line would cost more attention than it pays back.
+  const theme = tag ? ` ${c.dim(`#${tag}`)}` : '';
+  log(`\n  ${c.bold(`${noun}${a.epicId || '(epic)'}`)}${theme} ${c.dim(`— ${a.why}`)}`);
+  // In Build with live lanes, print each story/repo's next sub-step + remaining chain instead
   // of the single static hint; otherwise the one actionable line.
-  if (a.kind === 'build' && a.builds?.length) printBuildLanes(a.builds);
-  else hand(actionLine(a, { solo }));
-  if (a.kind === 'review-sync') info(c.dim(`unresolved comments? ${c.bold(`yad gate comments ${a.epicId} ${a.artifact}`)}`));
-  if (a.parallel) hand(`parallel track: invoke the ${c.bold(a.parallel.skill)} skill ${c.dim(`(author ${a.parallel.artifact})`)}`);
+  if (a.kind === 'build' && a.builds?.length) {
+    printBuildLanes(a.builds, automation);
+    // Every lane printed is a skip and nothing has started (E39 review): the lanes alone name no command,
+    // so the one actionable line is printed too.
+    const lanes = buildLanes(a.builds);
+    if (lanes.length && lanes.every((r) => r.status === 'skipped')) hand(actionLine(a, { solo, bindings, verified }));
+  } else {
+    hand(actionLine(a, { solo, bindings, verified }));
+    const note = costNote(a);
+    if (note) info(c.dim(note));
+    // A Shape author step the team set to `auto` (E34). Recorded, not acted on: say so, or the line reads
+    // as a promise that something will run.
+    if (a.kind === 'author' && automation?.steps?.[a.step] === 'auto') {
+      info(c.dim(killSwitchOn(automation)
+        ? 'advance: auto — held at human by the kill switch (yad unkill)'
+        : 'advance: auto — recorded; nothing drives a Shape step on its own yet'));
+    }
+  }
+  // Not `c.dim(... c.bold(...) ...)`: `paint` closes with a full reset, so a bold word inside a dim
+  // string ends the dim and everything after it reads bright. Painted per segment instead.
+  if (a.kind === 'review-sync') info(`${c.dim('unresolved comments?')} ${c.bold(`yad gate comments ${a.epicId} ${a.artifact}`)}`);
+  if (a.parallel) {
+    hand(`parallel track: invoke ${skillPhrase(a.parallel)} ${c.dim(`(author ${a.parallel.artifact})`)}`);
+    const note = costNote(a.parallel);
+    if (note) info(c.dim(note));
+  }
+  // A step re-opened behind finished work (E41) is a lane of its own beside the chain, like the
+  // test-cases track above: it gets its own line, with the same words a chain step would get.
+  for (const lane of a.reopened || []) hand(`re-opened lane: ${actionLine({ ...lane, epicId: a.epicId }, { solo, bindings, verified })}`);
+  // DEBT is reminded on every run until it is paid (E41). The line says what is owed and the one command
+  // that starts paying it — or, once that has started, what finishes it.
+  for (const d of a.debt || []) warn(debtLine(a.epicId, d, verified));
+  phaseLine(a);
+}
+
+// One reminder line for a step owed as debt (E41).
+function debtLine(epicId, d, verified = false) {
+  const author = d.step.replace(/-review$/, '');
+  if (d.status === 'deferred') {
+    const r = d.record || {};
+    const when = [r.by ? `by ${r.by}` : '', r.date ? `on ${r.date}` : ''].filter(Boolean).join(' ');
+    return `owed (debt): ${author} — deferred${when ? ` ${when}` : ''}${r.reason ? `: ${r.reason}` : ''} — pay it back with yad undefer ${epicId} ${author}${verified ? ' (on a verified Product it is refused once the epic\'s ledger is on the default branch, until CI has a step for it)' : ''}`;
+  }
+  // Put back, but waiting behind an earlier step that has not passed: say so, rather than "being paid
+  // back" about a step nobody can work on yet.
+  if (d.status === 'todo') return `owed (debt): ${author} — back in the chain, waiting for an earlier step; the debt clears when ${author}-review passes`;
+  return `owed (debt): ${author} — being paid back (${d.step} is ${d.status}); the debt clears when ${author}-review passes`;
+}
+
+// Where this epic sits in the lifecycle: the six phases, with the current one marked.
+//
+// `phaseOf` is given the same two facts every renderer needs — the epic's current step and whether it
+// is the product level — so `yad next` and `yad thread` cannot answer this differently. It returns
+// null for a stub and for any step id this release does not recognise, and this line then stays away
+// entirely: a wrong phase is worse than no phase.
+//
+// The two unbuilt phases are shown, greyed, rather than hidden. Someone reading this needs to see
+// that the lifecycle does not stop at merge; a list that ended at Build would say it does.
+//
+// THE PRODUCT LEVEL GETS ITS OWN LINE (E75), not the six-phase strip. The Foundation runs once per
+// product and never walks Design, Plan or Build, so printing those six with nothing marked would claim
+// a journey it does not take — which is why this line used to be absent for `EP-discovery` altogether.
+// It now has a phase of its own, on a ladder of its own, and says so in words.
+function phaseLine(a) {
+  const here = phaseOf(a.step, { product: PRODUCT_EPICS.includes(a.epicId) });
+  if (!here) return;
+  if (here.level === 'product') {
+    info(`${c.dim('phase:')} ${c.bold(here.name)} ${c.dim('— the Product level, once per product, before any feature epic')}`);
+    return;
+  }
+  // A phase this epic's ROUTE never enters is marked, not hidden (E40). A `chore` epic has no
+  // architecture or UI-design step, so it never sees Design — and printing Design exactly as a
+  // `classic` epic prints it makes a lane that will never go there look like one that has already
+  // been. Marked rather than dropped for the same reason the two unbuilt phases are: a person reading
+  // this needs the whole shape, with their own position in it, not an edited version of the lifecycle.
+  // Build is never marked: it is where every feature route ends up, and the Build steps live per story
+  // in `build-state/` rather than in this chain, so their absence here means nothing.
+  const onRoute = a.route ? profileSteps(a.route) : null;
+  const covered = onRoute?.length
+    ? new Set(PHASES.filter((p) => p.id === 'build'
+        || onRoute.some((id) => stepPhase(id) === p.id)).map((p) => p.id))
+    : null;
+  const rendered = PHASES.map((p) => {
+    if (p.id === here.id) return c.bold(p.name);
+    if (!p.built) return c.dim(`${p.name} (planned)`);
+    if (covered && !covered.has(p.id)) return c.dim(`${p.name} (not on this route)`);
+    return c.dim(p.name);
+  });
+  // Coloured PER SEGMENT, never nested: `paint` closes with a full reset (\x1b[0m), so a bold word
+  // inside a dim string ends the dim for everything after it and the rest of the line reads bright.
+  // The current phase is named in WORDS as well as marked in bold, because bold is not always there:
+  // `useColor` is off whenever output is not a terminal or NO_COLOR is set, which is every pipe, every
+  // log file and every CI job. Without this the line would list six phases and give no way to tell
+  // which one you are in — the one thing it exists to say. The part is added only when it is a
+  // different word; "now: Build (Build part)" tells nobody anything.
+  const part = here.name === here.part ? '' : ` (${here.part} part)`;
+  info(`${c.dim('phase:')} ${rendered.join(c.dim(' · '))} ${c.dim(`— now: ${here.name}${part}`)}`);
 }
 
 // `yad next` with no epic: orient across the whole project, always ending on ONE thing to do.
-function generalNext(root, { all } = {}) {
+function generalNext(root, { all, headCount = null } = {}) {
   if (!isSetUp(root)) {
     log(`\n  ${c.bold('Project not set up yet.')}`);
     hand(`run ${c.bold('yad setup')} ${c.dim('(then come back to `yad next`)')}`);
     return;
   }
-  const solo = isSolo(root);
-  const brownfield = profileOf(root)?.codebase === 'brownfield';
-  // The project front-zero (EP-discovery / "epic zero") is not a feature epic — split it out so it is
-  // surfaced on its own line and never mixed into the feature-epic roll-up.
+  // The Product config, read ONCE for this view.
+  const hub = readJSON(productConfigPath(root), null);
+  const solo = soloOf(hub);
+  // E74: in solo mode, suggest `yad mode team` when the count shows more than one person may work here.
+  // Printed first, so it is not lost under a long list of epics. An unknown count is not said here —
+  // `yad doctor` and `yad mode` say it (the user's choice, 2026-09-22). `headCount` is for tests.
+  printTeamHint(soloTeamHint(root, hub, { solo, headCount }));
+  // `profile` here is the SETUP profile `yad setup` records (codebase / repo_layout / team_size), not the
+  // lifecycle profile an epic walks (`LIFECYCLE_PROFILES`, E5): two things share the word.
+  const brownfield = hub?.profile?.codebase === 'brownfield';
+  // The PRODUCT level (the Foundation, or a ledger still in its old `discovery` spelling) is not a
+  // feature epic — split it out so it is surfaced on its own line and never mixed into the roll-up.
   const allEpics = listEpics(root);
-  const hasDiscovery = allEpics.includes(DISCOVERY_EPIC);
-  const featureEpics = allEpics.filter((id) => id !== DISCOVERY_EPIC);
-  const discoveryAction = hasDiscovery ? actionFor(root, DISCOVERY_EPIC) : null;
-  const discoveryOpen = !!discoveryAction && discoveryAction.kind !== 'discovery-done';
+  // One read of `.sdlc/skills.json` for the whole roll-up, not one per epic.
+  const bindings = loadSkillBindings(root);
+  const automation = loadAutomation(root);
+  const verified = isVerifiedLedger(hub);
+  // The Foundation wins when both exist. Two product levels is a fault `yad doctor` fails on; until it
+  // is fixed the new spelling is the one worth acting on, and the old one is named so it is not lost.
+  const productIds = PRODUCT_EPICS.filter((id) => allEpics.includes(id));
+  const productId = productIds[0] || null;
+  const featureEpics = allEpics.filter((id) => !PRODUCT_EPICS.includes(id));
+  const productRow = productId ? rowFor(root, productId, bindings) : null;
+  const productOpen = !!productRow && !PRODUCT_DONE.includes(productRow.action.kind);
+  if (productIds.length > 1) {
+    warn(`two product levels: ${productIds.map((id) => epicRel(id)).join(' and ')} — ${productId} is the one used`);
+    hand(`run ${c.bold('yad doctor')} ${c.dim('(a product has one Foundation; `yad migrate` converts the old one when it can)')}`);
+  }
 
   if (!featureEpics.length) {
-    if (discoveryOpen) { printAction(discoveryAction, { solo }); return; }
+    if (productOpen) { printAction(productRow.action, { solo, bindings, automation, verified, ...productRow }); return; }
     log(`\n  ${c.bold('Set up — no feature epics yet.')}`);
     if (brownfield) hand(`capture what already exists first: invoke the ${c.bold('yad-backfill')} skill`);
-    if (!hasDiscovery) hand(`frame the whole project (market, feasibility, roadmap): invoke the ${c.bold('yad-discovery')} skill ${c.dim('(optional front-zero)')}`);
-    hand(`start your first epic: invoke the ${c.bold('yad-epic')} skill${hasDiscovery ? c.dim(' (it reads the approved roadmap.md)') : ''}`);
+    // Both name a STEP's skill, so both ask the project. `yad-backfill` above does not: waking a
+    // brownfield anchor is the engine's own promote verb, not a step on any chain.
+    if (!productId) hand(`frame the whole product first (purpose, scope, MVP, roadmap, stack): run ${c.bold('yad foundation new')}, then invoke the ${c.bold(stepSkills('foundation', bindings)[0] || 'yad-discovery')} skill ${c.dim('(optional)')}`);
+    hand(`start your first epic: invoke the ${c.bold(stepSkills('epic', bindings)[0] || 'yad-epic')} skill${productId ? c.dim(' (it reads the approved roadmap.md)') : ''}`);
     return;
   }
 
-  const actions = featureEpics.map((id) => actionFor(root, id));
-  if (discoveryOpen) printAction(discoveryAction, { solo });   // an unfinished discovery comes first
+  const rows = featureEpics.map((id) => rowFor(root, id, bindings));
+  if (productOpen) {
+    printAction(productRow.action, { solo, bindings, automation, verified, ...productRow });   // an unfinished Foundation comes first
+    // REPORTED, NOT ENFORCED (E75). The roadmap puts one approval on the Foundation "before feature
+    // work begins", and the decision for this release is to say so rather than to block on it: a
+    // project that began its epics first — every project older than this release — must keep working
+    // (rule 5), and a hard stop here would be the first thing that ever refused to show an epic.
+    info(c.dim(`${productId} has not passed its gate — ${featureEpics.length} feature epic(s) are going ahead of it (reported, not enforced)`));
+  }
 
   if (featureEpics.length === 1 || all) {
-    for (const a of actions) printAction(a, { solo });
+    for (const r of rows) printAction(r.action, { solo, bindings, automation, verified, ...r });
     return;
   }
   // Several epics — list each with a one-liner, then point at the per-epic / --all views.
   log(`\n  ${c.bold(`${featureEpics.length} epics`)} ${c.dim('— next action each:')}`);
-  for (const a of actions) log(`    ${c.cyan(`${kindNoun(a.lineageKind)} ${a.epicId}`)}  ${actionLine(a, { solo })}`);
-  info(c.dim(`detail: ${c.bold('yad next <epic>')}  •  all at once: ${c.bold('yad next --all')}`));
+  // The grouping theme rides this list too. This is the ONE `yad next` view that shows several epics
+  // side by side, so it is where seeing which of them belong together is worth most — and leaving it
+  // off would have meant bare `yad next`, the command people run by default, never showed the tag.
+  for (const { action: a, theme: tag } of rows) {
+    const theme = tag ? ` ${c.dim(`#${tag}`)}` : '';
+    // Debt is reminded here too (E41): the roll-up is the view people run most, and a reminder that only
+    // appears once you already look at the one epic is not a reminder.
+    const owed = a.debt?.length ? `  ${c.yellow(`· ${a.debt.length} owed as debt`)}` : '';
+    log(`    ${c.cyan(`${typeNoun(a.lineageKind)} ${a.epicId}`)}${theme}  ${actionLine(a, { solo, verified })}${owed}`);
+  }
+  // Painted per segment, not dim-wrapping a bold: `paint` closes with a full reset, so the nested
+  // form loses the dim from the first bold word to the end of the line.
+  info(`${c.dim('detail:')} ${c.bold('yad next <epic>')}  ${c.dim('•  all at once:')} ${c.bold('yad next --all')}`);
 }
 
 // `yad next <epic> --check <step>`: the precondition guard. Exit 0 if runnable now, 1 otherwise.
@@ -178,20 +420,30 @@ function checkPrecondition(root, epic, stepId) {
 // ---- machine-readable output (`--json`) --------------------------------------------------------
 // `nextAction` already computes exactly what a caller needs; until now the ANSI prose renderer was
 // its only consumer, so anything driving yadflow had to regex coloured English. This emits the SAME
-// objects, unrendered. One envelope for every route, so a caller never has to branch on the shape:
+// objects, unrendered, inside E1's envelope (`jsonVersion`, `version`, `command`, `ok`, `warnings`).
+// One shape for every route, so a caller never has to branch on it:
 //
-//   { version, ok: true,  actions: [ <action>, … ] }        next / next <epic>
-//   { version, ok,        check: { epic, step, ok, reason } } next <epic> --check <step>
-//   { version, ok: true,  setUp: false, actions: [] }        the project has no `yad setup` yet
-//   { version, ok: false, error }                            bad epic id / no state.json
+//   { …, ok: true,  actions: [ <action>, … ] }         next / next <epic>
+//   { …, ok,        check: { epic, step, ok, reason } } next <epic> --check <step>
+//   { …, ok: true,  setUp: false, actions: [] }        the project has no `yad setup` yet
+//   { …, ok: false, error, code, hint }                bad epic id / no state.json
 //
 // Exit codes are unchanged from the prose path — only the rendering differs.
-const emitJSON = (payload) => log(JSON.stringify({ version: VERSION, ...payload }, null, 2));
+// `route` is a RENDERING input, not part of the answer: `phaseLine` uses it to mark a phase this
+// epic's route never enters, and a script reading `yad next --json` gets the route from `state.json`'s
+// own `profile` key, which is the record. Stripped here rather than
+// threaded past the JSON path, because one strip is easier to keep right than three call sites — and
+// `--json` is a machine contract, so a field added by accident is a field somebody starts depending on.
+const forJSON = (a) => Object.fromEntries(Object.entries(a).filter(([k]) => k !== 'route'));
+const answer = (payload) => emitJSON({
+  ...payload,
+  ...(payload.actions ? { actions: payload.actions.map(forJSON) } : {}),
+});
 
 // A JSON error still leaves stdout parseable: a caller that pipes us into a parser gets an object
 // explaining the failure, never half a document or a bare ANSI line.
 function jsonError(message) {
-  emitJSON({ ok: false, error: message });
+  answer({ ok: false, error: message });
   process.exitCode = 1;
 }
 
@@ -200,26 +452,27 @@ function jsonError(message) {
 function jsonNext(root, { epic, check }) {
   if (epic && check) {
     const res = preconditionsMet(loadLedger(epicRoot(root, epic)).state, check);
-    emitJSON({ ok: !!res.ok, check: { epic, step: check, ok: !!res.ok, ...(res.reason ? { reason: res.reason } : {}) } });
+    answer({ ok: !!res.ok, check: { epic, step: check, ok: !!res.ok, ...(res.reason ? { reason: res.reason } : {}) } });
     if (!res.ok) process.exitCode = 1;
     return;
   }
   if (epic) {
     if (!exists(path.join(epicRoot(root, epic), '.sdlc', 'state.json'))) {
-      return jsonError(`no epic state at epics/${epic}/.sdlc/state.json`);
+      return jsonError(`no epic state at ${epicRel(epic)}/.sdlc/state.json`);
     }
-    return emitJSON({ ok: true, actions: [actionFor(root, epic)] });
+    return answer({ ok: true, actions: [actionFor(root, epic)] });
   }
-  if (!isSetUp(root)) return emitJSON({ ok: true, setUp: false, actions: [] });
-  // Every epic that HAS a ledger, discovery included — its `kind` already says whether it is open
+  if (!isSetUp(root)) return answer({ ok: true, setUp: false, actions: [] });
+  // Every epic that HAS a ledger, discovery included — its ACTION kind already says whether it is open
   // (`discovery-*`) or finished, so filtering it out would hide a fact rather than clarify one.
   // `--all` is implied: an array always carries everything, so there is nothing left to expand.
-  return emitJSON({ ok: true, actions: listEpics(root).map((id) => actionFor(root, id)) });
+  const bindings = loadSkillBindings(root);
+  return answer({ ok: true, actions: listEpics(root).map((id) => actionFor(root, id, undefined, bindings)) });
 }
 
 // Entry point for the `next` command: route to the precondition check, a single epic's action, or the
 // project-wide general view. Validates the epic id first.
-export async function runNext(root, { epic, check, all, json } = {}) {
+export async function runNext(root, { epic, check, all, json, headCount = null } = {}) {
   if (epic && !isValidEpicId(epic)) {
     const message = `invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`;
     if (json) return jsonError(message);
@@ -229,7 +482,7 @@ export async function runNext(root, { epic, check, all, json } = {}) {
   }
   if (json) return jsonNext(root, { epic, check });
   if (epic && check) return checkPrecondition(root, epic, check);
-  if (!epic) return generalNext(root, { all });
+  if (!epic) return generalNext(root, { all, headCount });
 
   const epicDir = epicRoot(root, epic);
   if (!exists(path.join(epicDir, '.sdlc', 'state.json'))) {
@@ -238,5 +491,11 @@ export async function runNext(root, { epic, check, all, json } = {}) {
     process.exitCode = 1;
     return;
   }
-  printAction(actionFor(root, epic), { solo: isSolo(root) });
+  // One read, two readers: the resolver puts the bound skill on the action, and the renderer names it
+  // in the two prose lines no action carries.
+  const bindings = loadSkillBindings(root);
+  const automation = loadAutomation(root);
+  const verified = isVerifiedLedger(readJSON(productConfigPath(root), null));
+  const row = rowFor(root, epic, bindings);
+  printAction(row.action, { solo: isSolo(root), bindings, automation, verified, ...row });
 }