yadflow 3.18.1 → 4.0.0-next.1

package/cli/doctor.mjs

@@ -5,22 +5,29 @@
 // `--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, DESIGN_TOOLS, TESTING_TOOLS, LEARNING_TOOLS, HOOK_SETTINGS, HOOK_TOOL_MATCHER, isBridgeHub } from './manifest.mjs';
-import { mergeHookSettings, hookMatcherFires, ideTargetsFor } from './plan.mjs';
+import { c, log, ok, info, warn, fail, hand, run, has, exists, isPlainObject, readJSON, readJSONStrict, emitJSON } from './lib.mjs';
+import { VERSION, BACKUP_SUFFIX, MIRRORED_FILES, PROJECT_FILES, MODULE_CONFIG, epicFiles, DESIGN_TOOLS, TESTING_TOOLS, LEARNING_TOOLS, HOOK_ADAPTERS, isVerifiedLedger , productConfigPath, ADVANCE_FROM_AUTOMATION, DRIVER_FROM_ASSISTANCE } from './manifest.mjs';
+import { mergeHookSettings, hookMatcherFires, ideTargetsFor, safeIdeTargetStateFor, hookScriptReady, miswiredGuardCommand } from './plan.mjs';
 import { planMigration } from './migrate.mjs';
-import { loadLedger, epicRoot, isValidEpicId, epicLineage, resolveThread, stateInvariants, contractSurfaceHash, artifactHash } from './epic-state.mjs';
+import { ADVANCE_VALUES, isGateStep, killSwitchOn, loadAutomation, stepDef as catalogueStep, loadLedger, owedSteps, epicIds, epicRel, epicRoot, FOUNDATION_DIR, FOUNDATION_EPIC, DISCOVERY_EPIC, staleFoundationGuards, unwrittenSections, artifactBase, artifactAgrees, epicStories, laneStarted, isValidEpicId, epicLineage, isGenesisType, readFrontmatter, resolveThread, stateInvariants, contractSurfaceHash, acceptedHashes, isStaleHash, workItemType, WORK_ITEM_TYPES, themeOf, themeKey, stepPhase, stepDef, matchLifecycleProfile, lifecycleProfile, LIFECYCLE_PROFILES, SENTINELS, normalizeBindings, optionalStepsFor, isSkippableStep, recordedRouteDisagrees, isPassed, stepStatus, claimsSkipped, STEP_STATES, isStepRecord, RECORDED_STEP_STATES } from './epic-state.mjs';
 import { loadDebt } from './thread.mjs';
+import { readShips } from './ledger.mjs';
 import { gitHead, insideWorkspace } from './setup.mjs';
-import { cliFor, validateLogin, hostFromGitUrl } from './platform.mjs';
+import { cliFor, hostFromGitUrl, ambiguousLegacyNames } from './platform.mjs';
+import { legacyLogins, stampLegacyLogins } from './gate.mjs';
+import { checkRepo } from './riskmap-command.mjs';
+import { checkCodeowners, codeownersFindings } from './codeowners-command.mjs';
+import { RISK_MAP_FILE } from './riskmap.mjs';
+import { readProtection, protectionLine, protectionJSON, hideAddresses } from './protection.mjs';
+import { soloTeamHint, TEAM_CMD } from './people.mjs';
+import { indexFreshness, INDEX_FILE } from './product-index.mjs';
+import { productGit, resolveDefaultBranch } from './hubcommit.mjs';
 
 const MIN_NODE = 18;
 
 // Solo mode (a lone developer): approval waived, merge + resolved threads still gate. Persisted in
 // hub.json. Mirrors gate.mjs / next.mjs.
 const isSolo = (hub) => !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
-// owner/repo slug from a git url (https or ssh), for the branch-protection probe.
-const repoSlug = (url) => ((url || '').match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/) || [])[1] || null;
 // Is an already-resolved path nested under the project root? Repo paths are contained to the WORKSPACE
 // (the root's parent, see setup.insideWorkspace), so a registered sibling resolves outside the root —
 // which is what distinguishes "absent because it lives elsewhere" from "absent because it is broken".
@@ -55,11 +62,12 @@ export function envChecks(checks) {
   }
 }
 
-export function projectChecks(checks, root) {
-  const hubPath = path.join(root, PROJECT_FILES.hubConfig);
+// `headCount` is a count of people the caller already read (E74); the CLI passes none, a test passes one.
+export function projectChecks(checks, root, { headCount = null } = {}) {
+  const productPath = productConfigPath(root);
   const regPath = path.join(root, PROJECT_FILES.reposRegistry);
   const verPath = path.join(root, PROJECT_FILES.version);
-  if (!exists(hubPath) && !exists(regPath) && !exists(verPath)) {
+  if (!exists(productPath) && !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;
   }
@@ -67,7 +75,7 @@ export function projectChecks(checks, root) {
   // 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`');
-  // The stamp is not only cosmetic: in bridge mode the wired gate-sync job resolves the yadflow it
+  // The stamp is not only cosmetic: in verified mode the wired gate-sync job resolves the yadflow it
   // RUNS from it — unless hub.json pins `gate_sync_version`, a YAD_VERSION variable overrides, or the
   // stamp is not an exact release of the current major (then the job skips it and floats). So a stale
   // stamp can mean CI is running an old gate; say so, or the warning reads as bookkeeping.
@@ -76,12 +84,12 @@ export function projectChecks(checks, root) {
 
   // 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');
+  if (!exists(productPath)) {
+    check(checks, 'hub', 'project', 'warn', `${PROJECT_FILES.hubConfig} absent — local gate`, 'run `yad setup` to configure a platform');
   } else {
     let hubBroken = false;
     try {
-      hub = readJSONStrict(hubPath, null);
+      hub = readJSONStrict(productPath, 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');
@@ -89,90 +97,172 @@ export function projectChecks(checks, root) {
     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)`);
-      if (isSolo(hub)) check(checks, 'solo', 'project', 'ok', 'mode: solo — approval waived; the PR merge + resolved threads gate the step');
+      check(checks, 'hub', 'project', 'ok', `hub: ${hub.platform || 'local'}`);
+      // E62 removed the roster. A list an older release wrote is kept on disk and decides nothing — its
+      // name → login pairs only let the first sync recognise older approvals (`legacyLogins`) — so say so
+      // — a team that still edits it would otherwise believe it decides something. An empty list (what a
+      // solo setup used to write) says nothing about people and is left quiet.
+      const r = hub.roster;
+      const listed = Array.isArray(r) ? r.length > 0 : (r && typeof r === 'object' ? Object.keys(r).length > 0 : !!r);
+      if (listed) {
+        // When it can go (E64): once every older record it can place names the login. Counted with the same
+        // stamp the gate writes, so this says exactly what the next gate write would still change.
+        let waiting = 0;
+        let unplaced = 0;
+        const waitingIn = [];
+        const aliases = legacyLogins(hub);
+        const clashed = ambiguousLegacyNames(hub);
+        for (const e of epicIds(root)) {
+          try {
+            const led = loadLedger(epicRoot(root, e));
+            const st = stampLegacyLogins({ approvals: led.approvals, comments: led.comments }, { aliases, clashed });
+            if (st.stamped) { waiting += st.stamped; waitingIn.push(e); }
+            unplaced += st.unplaced;
+          } catch { /* an unreadable ledger is reported by its own check */ }
+        }
+        const when = !hub.platform
+          ? 'nothing reads it on a Product with no platform — delete the `roster` key'
+          : waiting
+            ? `keep it for now: ${waiting} older approval/comment record(s) in ${waitingIn.join(', ')} still name people by roster name. The next gate write records their logins — ${isVerifiedLedger(hub) ? 'CI\'s run on the next merged review' : '`yad gate sync <epic>`'} — then delete the \`roster\` key`
+            : unplaced
+              ? `every older record it can place names its login now; ${unplaced} it cannot place (a name two logins share, or records that disagree about which review they are) are matched by submission time or given again on a new review — delete the \`roster\` key once those reviews are closed`
+              : 'no older record needs it any more — delete the `roster` key';
+        check(checks, 'people:roster-unused', 'project', 'warn',
+          `${PROJECT_FILES.hubConfig} has a \`roster\` that no longer decides who approves — a gate needs one approval (not the author's own) from anyone with access`,
+          when);
+        // Those pairs are exact only when the roster is: a name two logins share cannot say which person an
+        // older record means. Named here, because on an open review that approval may then have to be given
+        // again. (A name equal to ANOTHER entry's login is exact — a record under a name was written from
+        // that entry, and an unlisted login was written `unverified` — so it is not warned about.) The hint
+        // does NOT say "rename it": renaming one entry hands every older record under the name to whoever
+        // keeps it, which can put someone's approval of old content on a person who never gave it.
+        const unclear = [...ambiguousLegacyNames(hub).keys()];
+        if (unclear.length) {
+          check(checks, 'people:roster-ambiguous', 'project', 'warn',
+            `${PROJECT_FILES.hubConfig} roster name(s) ${unclear.join(', ')} are given to more than one login — an older approval under that name cannot be recognised by name`,
+            'leave the roster as it is: an older approval under that name is matched only when its submission time says whose it is, and otherwise may need to be given again on a new PR. Renaming an entry hands those records to whoever keeps the name — only do it if you know whose approval each one was');
+        }
+      }
+      if (isSolo(hub)) {
+        check(checks, 'solo', 'project', 'ok', 'mode: solo — approval waived; the PR merge + resolved threads gate the step');
+        // E74: suggest team mode when the count shows more than one person may work here. Counted ONLY
+        // in solo mode, because the count walks the git history of every connected repo; team mode
+        // pays nothing. A suggestion, never a switch — so a warning, never a failure. An unknown count
+        // is a warning too (the user's choice, 2026-09-22): doctor is where a count that cannot be read
+        // is fixed, and a ✓ beside "could not be counted" would read as healthy.
+        const hint = soloTeamHint(root, hub, { solo: true, headCount });
+        if (hint.line && hint.known) {
+          check(checks, 'mode:suggest-team', 'project', 'warn', hint.line,
+            `run \`${TEAM_CMD}\` if more than one person works here; if it is only you (for example two accounts, two spellings of your name, a robot committing or auto-approving, or your own approval on a local ledger), leave solo mode on`);
+        } else if (hint.line) {
+          check(checks, 'mode:suggest-team', 'project', 'warn', hint.line,
+            'the reason in brackets names what could not be read — clone the missing repo, unshallow it, or fix the file — then run `yad doctor` again');
+        }
+      }
+      // E10 writes `mode: solo|team` beside `solo`, and `solo` is still the one read. A hand edit can leave
+      // the two saying different things; name that, and say which one the gates follow. Silent on a file
+      // with no `mode`, which is every Product set up before E10 (the frozen golden one included).
+      if (hub.mode !== undefined) {
+        const acting = isSolo(hub) ? 'solo' : 'team';
+        if (hub.mode !== acting) {
+          check(checks, 'mode:disagree', 'project', 'warn',
+            `${PROJECT_FILES.hubConfig} says mode: ${JSON.stringify(hub.mode)}, but solo mode is ${acting === 'solo' ? 'on' : 'off'} — the old \`solo\` flag is the one the gates read`,
+            ['solo', 'team'].includes(hub.mode)
+              ? `\`yad mode ${acting}\` keeps what the gates do now; \`yad mode ${hub.mode === 'solo' ? 'solo --reason "<why>"' : 'team'}\` makes the gates follow \`mode\``
+              : `\`yad mode ${acting}\` writes a mode the gates recognise`);
+        }
+      }
       // platform CLI + auth (best-effort; auth probing is the user's own session)
       const cli = cliFor(hub.platform);
       if (cli) {
         // git_url is required whenever a platform is set — doctor needs it to scope the auth probe
-        // and the bridge/PR flow needs it to open PRs. Warn on its absence directly (not on the
+        // and the verified ledger/PR flow needs it to open PRs. Warn on its absence directly (not on the
         // resolved host), so it fires even when an origin remote can substitute: the field itself
         // is required regardless.
         if (!hostFromGitUrl(hub.git_url)) {
           check(checks, 'hub-git-url', 'project', 'warn',
             `${PROJECT_FILES.hubConfig} sets platform '${hub.platform}' but has no git_url [YAD-CFG-005]`,
-            'add git_url to hub.json (or re-run `yad setup`) — auth/PR checks need the hub host');
+            'add git_url to hub.json (or re-run `yad setup`) — auth/PR checks need the Product host');
         }
-        // Scope the auth probe to the hub's own host (derived from git_url, falling back to the
+        // Scope the auth probe to the Product's own host (derived from git_url, falling back to the
         // origin remote). `${cli} auth status` without --hostname exits non-zero when ANY configured
         // instance fails, so an unrelated stale login (e.g. a dead gitlab.com token) would falsely
-        // flag a working self-hosted hub — so we SKIP the probe entirely when no host resolves
+        // flag a working self-hosted Product — so we SKIP the probe entirely when no host resolves
         // rather than run the flaky unscoped form.
         const host = hostFromGitUrl(hub.git_url)
           || hostFromGitUrl(run('git', ['remote', 'get-url', 'origin'], { cwd: root }).stdout);
-        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`);
+        if (!has(cli)) check(checks, 'platform-cli', 'project', 'warn', `${cli} not found on PATH [YAD-ENV-002]`, `install ${cli} — the gate degrades to local without it`);
         else if (!host) check(checks, 'platform-cli', 'project', 'warn', 'auth check skipped — hub host unknown (no git_url / origin)', 'add git_url to hub.json so the auth probe can target the right host');
         else if (!run(cli, ['auth', 'status', '--hostname', host]).ok) check(checks, 'platform-cli', 'project', 'warn', `${cli} present but not authenticated for ${host} [YAD-ENV-002]`, `run \`${cli} auth login --hostname ${host}\``);
         else {
           check(checks, 'platform-cli', 'project', 'ok', `${cli} present and authenticated`);
-          // Re-validate each roster login against the hub (warn-only). Skips when a login is already
-          // flagged unverified by setup; reports any that no longer resolve.
-          const bad = [];
-          for (const e of hub.roster || []) {
-            const v = validateLogin(hub.platform, e.login);
-            if (v.checked && !v.exists) bad.push(e.login);
-          }
-          if (bad.length) check(checks, 'roster', 'project', 'warn', `roster login(s) not found on ${hub.platform}: ${bad.join(', ')}`, 'fix the login or re-run `yad setup` (they cannot satisfy a gate)');
-          else check(checks, 'roster', 'project', 'ok', `roster: ${(hub.roster || []).length} member(s) validated on ${hub.platform}`);
           // GitLab API reachability: the gate reads MR state via `glab api …` (approvals, discussions).
           // A present+authenticated glab whose token lacks api scope would still break readPrGitLab, so
           // probe a cheap api call (warn-only) to surface it before a sync silently holds the gate.
           if (hub.platform === 'gitlab') {
-            // Scope the probe to the hub's own host (like the auth check above) so a multi-instance
+            // Scope the probe to the Product's own host (like the auth check above) so a multi-instance
             // setup doesn't hit the wrong GitLab. `host` is guaranteed truthy here (we skip the whole
             // auth branch when it cannot be resolved), so the probe is always host-scoped.
             if (!run('glab', ['api', 'version', '--hostname', host]).ok) {
               check(checks, 'gitlab-api', 'project', 'warn', `glab is authenticated but \`glab api\` failed for ${host} [YAD-ENV-002]`, 'ensure the token has `api` scope — the gate reads MR approvals/discussions via the API');
             }
           }
-          // Solo + GitHub: a branch that "requires approvals" would block the solo dev's own merge
-          // (they can't approve their own PR). Best-effort probe; a 404 (no protection) is fine.
-          if (isSolo(hub) && hub.platform === 'github') {
-            const slug = repoSlug(hub.git_url) || repoSlug(run('git', ['remote', 'get-url', 'origin'], { cwd: root }).stdout);
-            const br = hub.default_branch || 'main';
-            if (slug) {
-              const probe = run('gh', ['api', `repos/${slug}/branches/${br}/protection/required_pull_request_reviews`, '--jq', '.required_approving_review_count']);
-              if (probe.ok && Number(probe.stdout) > 0) {
-                check(checks, 'solo-branch-protection', 'project', 'warn', `solo mode but ${br} requires ${probe.stdout} approval(s) — you cannot approve your own PR, so the merge will be blocked`, `relax "Require approvals" in ${slug} branch protection for ${br}`);
-              }
-            }
-          }
+          // Solo mode's "a required approval blocks your own merge" warning moved to the `protection`
+          // section (E70), which reads rulesets as well as classic protection, asks the Product's own host,
+          // and says "not known" when a call fails instead of staying quiet.
         }
       }
     }
   }
 
-  // The harness ledger guard (#171). Only meaningful in bridge mode: there the ledger is CI-owned and
+  // The harness ledger guard (#171). Only meaningful in verified mode: there the ledger is CI-owned and
   // an agent's hand-edit is always rejected later by `ledger-guard`, so the local hook that refuses it
-  // up front should be installed. Without the bridge the ledger is locally owned and the hand-edit the
+  // up front should be installed. With a local ledger nothing guards it, and the hand-edit the
   // authoring skills describe is correct — nothing to report, so the check is silent rather than `ok`.
-  const hubForHooks = readJSON(hubPath, null);
-  if (isBridgeHub(hubForHooks)) {
+  const hubForHooks = readJSON(productPath, null);
+  if (isVerifiedLedger(hubForHooks)) {
     const unwired = [];
     const broken = [];
-    if (!exists(path.join(root, 'hooks', 'ledger-guard.sh'))) unwired.push('hooks/ledger-guard.sh');
+    // PRESENT AND EXECUTABLE. A script at mode 644 has the right bytes and cannot run: the harness
+    // entry pointing at it fails, fails OPEN, and every ledger edit is permitted while this check and
+    // `yad check` both call the guard healthy. Reachable from a zip download, `cp` without `-p`, or a
+    // restrictive umask, with nobody having done anything unusual.
+    if (!hookScriptReady(root, 'hooks/ledger-guard.sh')) unwired.push('hooks/ledger-guard.sh');
     // The SAME target list `hookActions` wires — the persisted `ideTargets`, not "does the directory
     // exist". Keyed on the directory, a project whose targets are `['.agents']` but which also has a
     // stray `.claude/` would be told to run `yad check --fix` forever, while that command builds no
     // action for `.claude` and correctly reports "already up to date". Never name a remedy that
     // cannot reach the thing being reported.
     const unreadable = [];
-    for (const ide of ideTargetsFor(root)) {
-      const relDest = HOOK_SETTINGS[ide];
-      if (!relDest) continue;
+    // Targets with no pre-edit hook protocol at all. Collected rather than skipped: a project whose
+    // only target is `.agents` had this whole section report `ok` — "agent ledger guard wired" — while
+    // nothing local guarded anything, because the loop found no adapter and said nothing. Silence
+    // about an unguarded target reads as a guarded one (E11).
+    const noProtocol = [];
+    // Targets whose directory is unsafe (a symlink, or a file). `hookActions` filters these through
+    // `safeIdeTargetsFor` and THROWS on them, so reporting one as "not wired — run `yad check --fix`"
+    // names a remedy that aborts instead of fixing it. The rule ten lines above is the same one:
+    // never name a remedy that cannot reach the thing being reported.
+    const unsafeTargets = [];
+    const miswired = [];
+    // Read ONCE, like the settings files below — the block's own rule, and two reads can disagree.
+    const targets = ideTargetsFor(root);
+    const safe = new Set(safeIdeTargetStateFor(root, targets).targets);
+    for (const ide of targets) {
+      if (!safe.has(ide)) { unsafeTargets.push(ide); continue; }
+      const adapter = HOOK_ADAPTERS[ide];
+      if (!adapter) { noProtocol.push(ide); continue; }
+      // The SCRIPT THE ENTRY POINTS AT, which is not always the shared one. `.cursor`'s entry names
+      // `hooks/ledger-guard-cursor.sh`, and only the shared `hooks/ledger-guard.sh` was checked above
+      // — so a project whose wrapper was deleted, gitignored or lost in a partial checkout had
+      // `yad check` calling it `new` while `yad doctor` printed a green "guard wired". The two
+      // commands disagreeing about one project is the worst version of this: whichever the human
+      // believes, Cursor is invoking a command that does not exist on every single file write.
+      for (const w of adapter.wiring) {
+        if (!hookScriptReady(root, w.dest)) unwired.push(w.dest);
+      }
+      const relDest = adapter.settings;
       const settingsPath = path.join(root, relDest);
       // A file that exists but does not parse is its OWN report. `readJSON` returns null for both
       // "absent" and "broken", and null merges as "not wired" — which would send the human to
@@ -187,24 +277,59 @@ export function projectChecks(checks, root) {
         if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { unreadable.push(relDest); continue; }
         settings = parsed;
       }
-      if (mergeHookSettings(settings).changed) { unwired.push(relDest); continue; }
+      // BEFORE the merge check, which `continue`s: a miswired command reads as "ours is absent", so
+      // the scan would never run on the very file that needs it.
+      for (const entry of settings?.hooks?.[adapter.event] || []) {
+        const why = miswiredGuardCommand(entry, adapter);
+        if (why) miswired.push(`${relDest}: ${why}`);
+      }
+      if (mergeHookSettings(settings, adapter).changed) { unwired.push(relDest); continue; }
       // Present is not the same as armed. The entry's matcher is the team's to narrow (the merge
       // deliberately leaves it alone), but one that no longer selects any file-editing tool means
       // nothing is intercepted — and reporting that as `ok` is how a disarmed guard passes for
       // healthy until a ledger edit fails in CI.
-      if (!hookMatcherFires(settings)) broken.push(relDest);
+      if (!hookMatcherFires(settings, adapter)) broken.push(`${relDest} (expected \`${adapter.matcher}\`)`);
     }
-    if (unreadable.length) {
-      check(checks, 'hooks', 'project', 'warn', `agent ledger guard cannot be wired — ${unreadable.join(', ')} does not parse [YAD-STATE-001]`,
+    // One clause, appended to whichever verdict below is reached, so the unguarded targets are named
+    // on the healthy path too — which is the path they are most likely to be read on.
+    const alsoUnguarded = noProtocol.length
+      ? ` — no pre-edit hook protocol on ${noProtocol.join(', ')}, so an agent using ${noProtocol.length > 1 ? 'those directories are' : 'that directory is'} guarded by CI only`
+      : '';
+    // NOTHING local guards this Product. Every target it has is one no harness can hook, so the
+    // script is installed and attached to no event anywhere. Naming that while reporting `ok` was a
+    // half-fix: `status` is the only machine-readable signal, the release check filters on `fail`,
+    // and a dashboard reading `--json` saw green on a verified project with no local guard at all.
+    // It is a warn, not a fail, because it is a real and reasonable setup — CI still fails closed.
+    const nothingWired = noProtocol.length > 0 && noProtocol.length === targets.length;
+    if (unsafeTargets.length) {
+      check(checks, 'hooks', 'project', 'warn', `agent ledger guard cannot be wired — ${unsafeTargets.join(', ')} is not a usable directory${alsoUnguarded}`,
+        'the target is a symbolic link or a file; `yad check --fix` refuses to write through it, so make it a real directory or drop it from `ideTargets` in `.sdlc/cli-version.json`');
+    } else if (unreadable.length) {
+      check(checks, 'hooks', 'project', 'warn', `agent ledger guard cannot be wired — ${unreadable.join(', ')} does not parse [YAD-STATE-001]${alsoUnguarded}`,
         'fix the JSON by hand, then run `yad check --fix` — yad never rewrites a settings file it cannot parse, so nothing else can clear this');
+    } else if (miswired.length) {
+      // BEFORE `unwired`, though a miswired command also reads as "ours is absent". It is the more
+      // specific fact and by far the more damaging one, and the `unwired` remedy is wrong here: a
+      // `yad check --fix` would add our entry BESIDE theirs, leaving the one that refuses everything
+      // still in place, while the report said the guard was simply missing.
+      check(checks, 'hooks', 'project', 'warn', `agent ledger guard wired with a command that will refuse every write: ${miswired.join('; ')}`,
+        'this harness answers with a JSON verdict and reads an empty answer as a deny; replace that command with `hooks/ledger-guard-cursor.sh`, which `yad check --fix` installs, or have your own wrapper run `yad hook ledger-guard --format cursor` and pass its stdout through');
     } else if (unwired.length) {
-      check(checks, 'hooks', 'project', 'warn', `agent ledger guard not wired: ${unwired.join(', ')}`,
+      check(checks, 'hooks', 'project', 'warn', `agent ledger guard not wired: ${unwired.join(', ')}${alsoUnguarded}`,
         'run `yad check --fix` — until then an agent can hand-edit the CI-owned ledger and only find out when the review PR/MR fails');
     } else if (broken.length) {
-      check(checks, 'hooks', 'project', 'warn', `agent ledger guard installed but its matcher no longer selects file edits: ${broken.join(', ')}`,
-        `restore the matcher to \`${HOOK_TOOL_MATCHER}\` — as it stands the hook is wired but never fires`);
+      check(checks, 'hooks', 'project', 'warn', `agent ledger guard installed but its matcher no longer selects file edits: ${broken.join(', ')}${alsoUnguarded}`,
+        'restore the matcher named beside each file — as it stands the hook is wired but never fires');
+    } else if (nothingWired) {
+      check(checks, 'hooks', 'project', 'warn', `agent ledger guard installed but attached to nothing: no target (${noProtocol.join(', ')}) has a pre-edit hook protocol, so nothing local guards the ledger`,
+        'add a target whose agent can refuse a write before it lands (`.claude` or `.cursor`) if you want the local half; otherwise CI is the only guard, and it only speaks at merge time');
     } else {
-      check(checks, 'hooks', 'project', 'ok', 'agent ledger guard wired (hooks/ledger-guard.sh)');
+      // Name every script that is actually wired, not just the shared one — on a `.cursor` project the
+      // file Cursor invokes is the wrapper, and a health line that never mentions it is a health line
+      // about something else.
+      const wiredScripts = ['hooks/ledger-guard.sh',
+        ...targets.flatMap((ide) => (HOOK_ADAPTERS[ide]?.wiring || []).map((w) => w.dest))];
+      check(checks, 'hooks', 'project', 'ok', `agent ledger guard wired (${[...new Set(wiredScripts)].join(', ')})${alsoUnguarded}`);
     }
   }
 
@@ -225,7 +350,7 @@ export function projectChecks(checks, root) {
     else if (!DESIGN_TOOLS.includes(design.tool)) check(checks, 'design', 'project', 'fail', `${PROJECT_FILES.designConfig}: unknown or missing design tool '${design.tool}' [YAD-CFG-002]`, `expected one of ${DESIGN_TOOLS.join(', ')}, or none`);
     else if (design.source && design.source !== 'unavailable') check(checks, 'design', 'project', 'ok', `design: ${design.tool} (${design.source})`);
     else if (design.source === 'unavailable') check(checks, 'design', 'project', 'warn', `design: ${design.tool} MCP unavailable — yad-ui runs markdown-only`, 'connect the MCP, then run `yad-connect-design` (action: refresh)');
-    else check(checks, 'design', 'project', 'warn', `design: ${design.tool} recorded but the MCP is not confirmed`, 'run `yad-connect-design` in Claude Code to detect the MCP');
+    else check(checks, 'design', 'project', 'warn', `design: ${design.tool} recorded but the MCP is not confirmed`, 'run `yad-connect-design` in your AI agent to detect the MCP');
   }
 
   // testing.json: parse + shape + tool + MCP confirmation (absent is the normal artifacts-only default —
@@ -245,7 +370,7 @@ export function projectChecks(checks, root) {
     else if (!TESTING_TOOLS.includes(testing.tool)) check(checks, 'testing', 'project', 'fail', `${PROJECT_FILES.testingConfig}: unknown or missing testing tool '${testing.tool}' [YAD-CFG-003]`, `expected one of ${TESTING_TOOLS.join(', ')}, or none`);
     else if (testing.source && testing.source !== 'unavailable') check(checks, 'testing', 'project', 'ok', `testing: ${testing.tool} (${testing.source})`);
     else if (testing.source === 'unavailable') check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} MCP unavailable — yad-test-cases runs artifacts-only`, 'connect the MCP, then run `yad-connect-testing` (action: refresh)');
-    else check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} recorded but the MCP is not confirmed`, 'run `yad-connect-testing` in Claude Code to detect the MCP');
+    else check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} recorded but the MCP is not confirmed`, 'run `yad-connect-testing` in your AI agent to detect the MCP');
   }
 
   // learning.json: parse + shape + tool + CLI confirmation (absent is the normal harness-native default —
@@ -266,10 +391,16 @@ export function projectChecks(checks, root) {
     else if (!LEARNING_TOOLS.includes(learning.tool)) check(checks, 'learning', 'project', 'fail', `${PROJECT_FILES.learningConfig}: unknown or missing learning tool '${learning.tool}' [YAD-CFG-004]`, `expected one of ${LEARNING_TOOLS.join(', ')}, or none`);
     else if (learning.source === 'deeptutor-cli') check(checks, 'learning', 'project', 'ok', `learning: ${learning.tool} (${learning.source})`);
     else if (learning.source === 'harness-native') check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool} CLI unavailable — yad-learn tutors harness-native`, 'install the deeptutor CLI, then run `yad-connect-learning` (action: refresh)');
-    else if (learning.source == null) check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool} recorded but the CLI is not confirmed`, 'run `yad-connect-learning` in Claude Code to detect the CLI');
+    else if (learning.source == null) check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool} recorded but the CLI is not confirmed`, 'run `yad-connect-learning` in your AI agent to detect the CLI');
     else check(checks, 'learning', 'project', 'fail', `${PROJECT_FILES.learningConfig}: unknown source '${learning.source}' [YAD-STATE-002]`, 'expected deeptutor-cli, harness-native, or null');
   }
 
+  // skills.json: which skill runs which step, when the project does not want the engine's default.
+  // Called from HERE rather than from `collectDoctor` beside the other E6 code so its findings land
+  // inside the `project` block. The renderer prints a header every time the section CHANGES, so a
+  // `project` check added after the `shape` section prints the word "project" a second time.
+  skillBindingChecks(checks, root);
+
   // repos.json: parse + every entry is a live git repo; staleness vs syncedHead
   let registry = { repos: [] };
   let regBroken = false;
@@ -287,13 +418,13 @@ export function projectChecks(checks, root) {
       // 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);
-      // A registered repo may be a SIBLING of the hub (`../backend`, the standard multi-repo layout).
-      // Such a checkout is legitimately absent wherever only the hub is checked out — hub CI, a fresh
+      // A registered repo may be a SIBLING of the Product (`../backend`, the standard multi-repo layout).
+      // Such a checkout is legitimately absent wherever only the Product is checked out — Product CI, a fresh
       // clone — so its absence is a warn, not corruption. A missing path INSIDE the project root is
       // still a hard fail: nothing but damage explains it.
       if (!exists(repoRoot)) {
         if (underProjectRoot(root, repoRoot) || !isRegistrableSibling(root, repo.path)) 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');
-        else check(checks, `repo:${repo.name}`, 'project', 'warn', `${repo.name}: ${repo.path} is not present in this checkout (sibling repo, outside the hub)`, 'expected when only the hub is checked out; clone it alongside the hub to work on it here');
+        else check(checks, `repo:${repo.name}`, 'project', 'warn', `${repo.name}: ${repo.path} is not present in this checkout (sibling repo, outside the Product)`, 'expected when only the Product is checked out; clone it alongside the Product to work on it here');
         continue;
       }
       const head = gitHead(repoRoot);
@@ -303,6 +434,40 @@ export function projectChecks(checks, root) {
       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');
+    // Per-repo owners went with the roster (E62). Named only where a repo actually lists someone: every
+    // repo an older setup connected carries an EMPTY `domain_owner`, which says nothing.
+    const owned = registry.repos.filter((r) => (Array.isArray(r.domain_owners) && r.domain_owners.length) || (typeof r.domain_owner === 'string' && r.domain_owner));
+    if (owned.length) {
+      check(checks, 'people:domain-owners-unused', 'project', 'warn',
+        `${PROJECT_FILES.reposRegistry} names domain owners that nothing reads any more: ${owned.map((r) => r.name).join(', ')}`,
+        'delete `domain_owner` / `domain_owners` when convenient; request reviewers on the PR itself');
+    }
+    // The verified-commits author allowlist went with the roster too (E62): the gate checks signatures
+    // only, and write access decides who can author. Name what an older release left — the free-form
+    // list in hub.json and every generated file — so nobody maintains a list that no longer protects.
+    const allowFiles = [
+      { where: 'the Product', file: path.join(root, '.sdlc', 'verified-authors') },
+      ...registry.repos.filter((r) => r.path).map((r) => ({ where: r.name, file: path.join(path.resolve(root, r.path), '.sdlc', 'verified-authors') })),
+    ].filter((x) => exists(x.file)).map((x) => x.where);
+    const listedAuthors = hub && typeof hub === 'object' && Array.isArray(hub.verified_authors) && hub.verified_authors.length > 0;
+    if (allowFiles.length || listedAuthors) {
+      const what = [listedAuthors ? `\`verified_authors\` in ${PROJECT_FILES.hubConfig}` : null, allowFiles.length ? `.sdlc/verified-authors in ${allowFiles.join(', ')}` : null].filter(Boolean).join(' and ');
+      check(checks, 'people:verified-authors-unused', 'project', 'warn',
+        `${what} — the verified-commits gate no longer reads an author list; it checks signatures only`,
+        'delete them when convenient; write access to the repo decides who can author a commit');
+    }
+    // A wired `verified-commits.sh` from before E62 still ENFORCES the author list. On a verified ledger
+    // `yad check --fix` refreshes it; on a local ledger the Product's CI files are not managed, so an older
+    // copy stays and keeps failing commits from unlisted authors (E62 upgrade simulation). Named, not fixed.
+    const oldGates = [
+      { where: 'the Product', file: path.join(root, 'checks', 'verified-commits.sh') },
+      ...registry.repos.filter((r) => r.path).map((r) => ({ where: r.name, file: path.join(path.resolve(root, r.path), 'checks', 'verified-commits.sh') })),
+    ].filter((x) => exists(x.file) && /SDLC_VERIFIED_AUTHORS|ALLOWLIST=/.test(fs.readFileSync(x.file, 'utf8'))).map((x) => x.where);
+    if (oldGates.length) {
+      check(checks, 'people:allowlist-gate-stale', 'project', 'warn',
+        `checks/verified-commits.sh in ${oldGates.join(', ')} is an older copy that still enforces the author list`,
+        'run `yad check --fix` (it refreshes the gate on a verified ledger and on code repos); on a local-ledger Product, copy skills/yad-checks/templates/checks/verified-commits.sh over it');
+    }
   }
 
   ciTagsChecks(checks, root, hub, registry);
@@ -322,7 +487,7 @@ export function ciTagsChecks(checks, root, hub, registry) {
     } catch { return false; } // absent fragment is not this check's concern
   };
   const fragments = [];
-  if (hub?.platform === 'gitlab' && (hub.bridge_enabled === true || hub.bridge === true)) {
+  if (hub?.platform === 'gitlab' && isVerifiedLedger(hub)) {
     fragments.push(
       { scope: 'hub', file: '.gitlab/ci/yad-gate-sync.yml', path: path.join(root, '.gitlab/ci/yad-gate-sync.yml') },
       { scope: 'hub', file: '.gitlab/ci/yad-verified-commits.yml', path: path.join(root, '.gitlab/ci/yad-verified-commits.yml') },
@@ -372,27 +537,27 @@ function contractLockCheck(checks, root, epic, ledger) {
   const short = (h) => `${h.slice(0, 19)}…`;
 
   if (lock.inheritedFrom || lock.ref) {
-    // The ref is repo-controlled text, so keep it inside this hub's epics/ — a lock file must not be
+    // The ref is repo-controlled text, so keep it inside this Product's epics/ — a lock file must not be
     // able to point the check at arbitrary JSON elsewhere on disk.
     const epicsDir = path.join(root, 'epics');
     const refPath = path.resolve(path.join(epicDir, '.sdlc'), lock.ref || `../../${lock.inheritedFrom}/.sdlc/contract-lock.json`);
     if (refPath !== epicsDir && !refPath.startsWith(epicsDir + path.sep)) {
       check(checks, id, 'epics', 'fail',
         `${epic}: pointer-lock ref '${lock.ref}' resolves outside epics/`,
-        'a pointer-lock must reference another epic in this hub — fix `ref` (yad-change writes ../../EP-<parent>/.sdlc/contract-lock.json)');
+        'a pointer-lock must reference another epic in this Product — fix `ref` (`yad epic new --parent` writes ../../EP-<owner>/.sdlc/contract-lock.json, where the owner is the epic along the parent\'s line that holds the contract)');
       return;
     }
     const parent = readJSON(refPath, null);
     if (!parent || typeof parent.hash !== 'string') {
       check(checks, id, 'epics', 'fail',
         `${epic}: pointer-lock references ${lock.inheritedFrom || lock.ref}, whose contract-lock.json is missing or has no hash`,
-        're-thread the change-epic (yad-change) so it points at a real parent lock');
+        're-seed the change-epic (`yad epic new --parent`) so it points at the real lock of the epic that owns the contract');
       return;
     }
     if (parent.hash !== stored) {
       check(checks, id, 'epics', 'fail',
         `${epic}: pointer-lock pins ${short(stored)} but ${lock.inheritedFrom || 'its parent'} now locks ${short(parent.hash)}`,
-        'the inherited surface was re-locked upstream — re-copy the parent hash, or re-author architecture in this epic');
+        'the inherited surface was re-locked upstream — re-copy the owner\'s hash, or re-author architecture in this epic');
       return;
     }
     // A pointer-lock epic has no contract.md by construction (the surface physically cannot drift).
@@ -433,9 +598,14 @@ function contractLockCheck(checks, root, epic, ledger) {
 // Two findings on a review step that is already `done`, both about the approval record behind it.
 //
 //   FAIL — it holds NO qualifying approval at all (outside solo mode). This is the state the gate
-//   exists to prevent: the step advanced without the record that justifies it. `gatePredicate` counts
-//   exactly the same thing (`status === 'approved'`, with `inherited`/`skipped` steps short-circuited
-//   before it), so a step doctor reports here is one the gate itself would refuse today.
+//   exists to prevent: the step advanced without the record that justifies it. It reads approvals the
+//   way `gatePredicate` does (`status === 'approved'`, with `inherited`/`skipped` steps short-circuited
+//   before it), so a step reported here is one the gate itself would refuse today. It is deliberately
+//   deliberately the WEAKER question: it asks whether any qualifying approval RECORD exists, not whether
+//   enough distinct people approved for the step's reported count (`gateRuleFor`, E7 — which holds no
+//   gate and so has nothing to audit against). Zero approvals is the one state that was never legitimate
+//   under any rule, and re-auditing a step that already passed against a number that arrived afterwards
+//   would flood a healthy project with findings nobody can act on.
 //
 //   WARN — it holds approvals, but none still bind to the artifact as it stands. The gate is
 //   deliberately one-way — nothing pulls a chain backward once work is built on it — so the only way
@@ -446,7 +616,10 @@ function contractLockCheck(checks, root, epic, ledger) {
 function staleGateCheck(checks, root, epic, ledger, { solo = false } = {}) {
   const epicDir = epicRoot(root, epic);
   for (const s of ledger.state.steps) {
-    if (s.type !== 'review+approve' || s.status !== 'done' || s.inherited || s.skipped) continue;
+    // `stepStatus(s) === 'done'` is the whole of the old three-part condition (E38): a step that
+    // passed AND was authored here. An inherited step reads `satisfied` and a skipped one `skipped`,
+    // so both drop out by name instead of by a flag check beside the status.
+    if (s.type !== 'review+approve' || stepStatus(s) !== 'done') continue;
     const forStep = ledger.approvals.filter((a) => a.step === s.id && a.status === 'approved');
     // Checked BEFORE the artifact hash below: "done holding no approval" is a claim about the ledger,
     // not about content, so it must not depend on there being something to hash. Gating it behind the
@@ -462,9 +635,9 @@ function staleGateCheck(checks, root, epic, ledger, { solo = false } = {}) {
         'the step advanced without the record the gate exists to keep — re-open the review (a fresh PR/MR) and re-approve, or run `yad gate sync` if the approvals are on the PR but never reached the ledger');
       continue;
     }
-    const cur = artifactHash(epicDir, s.artifact);
-    if (!cur) continue; // nothing to bind to (no locked surface / incomplete set) — not a staleness claim
-    const live = forStep.filter((a) => !a.artifactHash || a.artifactHash === cur);
+    const accepted = acceptedHashes(epicDir, s.artifact);
+    if (!accepted.length) continue; // nothing to bind to (no locked surface / incomplete set) — not a staleness claim
+    const live = forStep.filter((a) => !isStaleHash(a.artifactHash, accepted));
     if (live.length) continue;
     check(checks, `epic:${epic}:${s.id}:stale`, 'epics', 'warn',
       `${epic}: ${s.id} is done, but all ${forStep.length} approval(s) are bound to an older ${s.artifact}`,
@@ -472,16 +645,32 @@ function staleGateCheck(checks, root, epic, ledger, { solo = false } = {}) {
   }
 }
 
+// Every walker goes through `epicIds`, which lists only VALID ids — so a folder under `epics/` whose name
+// is not one (`EP-Foo`, with a capital, which macOS happily creates) is read by nothing, and nothing
+// said so. Name it (rule 6). Two kinds are meant to be skipped and are not named: a `*.yad-orig` backup,
+// which `yad migrate` makes, and a dot-folder.
+export function strayEpicDirChecks(checks, root) {
+  const dir = path.join(root, 'epics');
+  if (!exists(dir)) return;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!e.isDirectory() || e.name.startsWith('.') || e.name.endsWith(BACKUP_SUFFIX) || isValidEpicId(e.name)) continue;
+    check(checks, `epic-dir:${e.name}`, 'epics', 'warn',
+      `epics/${e.name}/ is not a valid epic id, so no command reads it`,
+      'rename it to `EP-<slug>` — lowercase letters, digits and dashes — or remove it if it is not an epic');
+  }
+}
+
 export function epicChecks(checks, root) {
-  const epicsDir = path.join(root, 'epics');
-  if (!exists(epicsDir)) return;
+  strayEpicDirChecks(checks, root);
   // Read once for the whole sweep: whether approval is waived is a project fact, not a per-epic one.
-  const solo = isSolo(readJSON(path.join(root, PROJECT_FILES.hubConfig), null));
-  for (const e of fs.readdirSync(epicsDir).sort()) {
-    if (!fs.statSync(path.join(epicsDir, e)).isDirectory()) continue;
+  const solo = isSolo(readJSON(productConfigPath(root), null));
+  // `epicIds` — every VALID epic id plus the Foundation (E75). The old listing took any directory under
+  // `epics/`, so a folder that is not an epic got an "epic not seeded" warning it could never satisfy.
+  for (const e of epicIds(root)) {
     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');
+      if (!ledger.state) check(checks, `epic:${e}`, 'epics', 'warn', `${e}: no state.json — epic not seeded`,
+        e === FOUNDATION_EPIC ? `seed it with \`yad foundation new\`, or remove ${FOUNDATION_DIR}/.sdlc/` : 'author it via yad-epic, or remove the directory');
       else {
         check(checks, `epic:${e}`, 'epics', 'ok', `${e}: currentStep ${ledger.state.currentStep}`);
         // Chain consistency: a passed review gate whose author step was never closed. currentStep alone
@@ -496,8 +685,8 @@ export function epicChecks(checks, root) {
         // review — so an OPEN (non-done) review PR recorded here means it was opened under an older
         // model. Merge/close it under the version that opened it before relying on the CI flow.
         const openPr = (ledger.hubPrs || []).find((p) => {
-          const st = (ledger.state.steps.find((s) => s.id === p.step) || {}).status;
-          return st && st !== 'done';
+          const step = ledger.state.steps.find((s) => s.id === p.step);
+          return !!step && !isPassed(step);
         });
         if (openPr) check(checks, `epic:${e}:migration`, 'epics', 'warn',
           `${e}: an open review PR (${openPr.artifact}${openPr.number ? ` #${openPr.number}` : ''}) is recorded on the default branch`,
@@ -511,6 +700,105 @@ export function epicChecks(checks, root) {
   }
 }
 
+// ---- the Foundation is guarded only once the wired checks know its folder (E75) ------------------
+// On a VERIFIED Product, CI is the only writer of the ledger, and what enforces that is
+// `checks/ledger-guard.sh` — committed in the user's own repo and refreshed by `yad update`, which is a
+// separate act from upgrading the CLI or running `yad migrate`. A copy from before E75 guards `epics/`
+// only. So a Product that has a Foundation and has not refreshed its checks has a ledger nobody
+// guards: a human can hand-edit `foundation/.sdlc/approvals.json` and the review PR goes green. The
+// two PR gates have the same gap for a Foundation section riding a non-review branch.
+//
+// Rule 6 says the engine never goes quiet about what is unprotected, so this is a WARNING that names
+// the consequence and the one command that fixes it. It never fires without a Foundation — there is
+// nothing to guard — nor on a local ledger, where humans write the ledger by design.
+//
+// Detected by the ARM that does the guarding, not by the folder name anywhere in the text: a comment
+// that merely mentions `foundation/` must not make an outdated script read as current. The wired copy
+// is byte-for-byte a template, so each template's arm is a fixed string.
+//
+// The same section reports the three ways a product can have the WRONG number of product levels:
+//   foundation:two     a Foundation AND an old `epics/EP-discovery/` ledger — fail. Two product levels
+//                      is a bug by the roadmap's own words, and only a person knows which is real.
+//   foundation:stray   an `epics/EP-foundation/` folder — fail. That id's folder is `foundation/`; this
+//                      one is never read, so anything written into it is silently lost.
+//   foundation:legacy  the old spelling alone. On a local ledger that is a warning with the command
+//                      that converts it. On a verified one there is nothing to run — CI owns the
+//                      ledger — so it is reported as fine, because a warning nobody can clear teaches
+//                      people to stop reading warnings.
+export function foundationChecks(checks, root) {
+  const hub = readJSON(productConfigPath(root), null);
+  const hasFoundation = exists(path.join(epicRoot(root, FOUNDATION_EPIC), '.sdlc', 'state.json'));
+  const hasLegacy = exists(path.join(epicRoot(root, DISCOVERY_EPIC), '.sdlc', 'state.json'));
+  if (hasFoundation && hasLegacy) {
+    check(checks, 'foundation:two', 'project', 'fail',
+      `two product levels: ${FOUNDATION_DIR}/ and epics/${DISCOVERY_EPIC}/ — a product has one Foundation`,
+      `decide which one is real. \`yad next\` uses ${FOUNDATION_DIR}/; to keep the old one instead, move ${FOUNDATION_DIR}/ aside and run \`yad migrate --apply\``);
+  } else if (hasLegacy) {
+    if (isVerifiedLedger(hub)) {
+      // CI moves it (cli/gate.mjs `convertProductLevel`), but only once the committed checks know the
+      // Foundation — so the stale case is the one with something for a person to do.
+      const stale = staleFoundationGuards(root);
+      if (stale.length) {
+        check(checks, 'foundation:legacy', 'project', 'warn',
+          `the product level is in its old spelling (epics/${DISCOVERY_EPIC}/), and CI will not move it: ${stale.join(', ')} ${stale.length === 1 ? 'predates' : 'predate'} the Foundation`,
+          `run \`yad update\` and commit the refreshed checks — the next gate run on the default branch then moves it to ${FOUNDATION_DIR}/`);
+      } else {
+        check(checks, 'foundation:legacy', 'project', 'ok',
+          `the product level is in its old spelling (epics/${DISCOVERY_EPIC}/) — read as the Foundation; CI moves it to ${FOUNDATION_DIR}/ at its next gate run on the default branch`);
+      }
+    } else {
+      check(checks, 'foundation:legacy', 'project', 'warn',
+        `the product level is in its old spelling (epics/${DISCOVERY_EPIC}/)`,
+        `run \`yad migrate\` to preview, then \`yad migrate --apply\` — it moves to ${FOUNDATION_DIR}/ with its files and approvals kept (docs/migrations/shape-8.md)`);
+    }
+  }
+  if (exists(path.join(root, 'epics', FOUNDATION_EPIC))) {
+    check(checks, 'foundation:stray', 'project', 'fail',
+      `epics/${FOUNDATION_EPIC}/ exists, but that id's folder is ${FOUNDATION_DIR}/ — nothing ever reads this one`,
+      `move anything real into ${FOUNDATION_DIR}/, then delete epics/${FOUNDATION_EPIC}/`);
+  }
+  foundationGuardChecks(checks, root, hub);
+  if (hasFoundation) foundationSectionChecks(checks, root);
+}
+
+// A Foundation whose review has OPENED or PASSED while a section is still only its template (E76).
+// While it is being authored an empty section is simply work not done yet, so nothing is said then;
+// once reviewers are looking at it, or have approved it, an empty section is part of what they approved.
+// A warning: the fix — write the section, re-open the review — is a person's decision.
+//
+// Only a review bound to `foundation/`. A Foundation converted from the old spelling keeps
+// `artifact: "discovery/"` and its six old files (shape 8), and those were never templates of this kind.
+// A ledger that does not load is left to the epic checks, which already report it.
+export function foundationSectionChecks(checks, root) {
+  const dir = epicRoot(root, FOUNDATION_EPIC);
+  let state;
+  try { state = loadLedger(dir).state; } catch { return; }
+  if (!state) return;                                        // no state.json — no Foundation to read
+  const review = state.steps.find((s) => s.id === 'foundation-review');
+  // `validateState` does not require `artifact`, and `artifactBase` throws without one: a hand-edited
+  // step missing it is `catalogueChecks`' finding to report, so this check must not crash doctor first.
+  if (!review || typeof review.artifact !== 'string' || artifactBase(review.artifact) !== 'foundation') return;
+  const status = stepStatus(review);
+  if (status !== 'in_review' && status !== 'done') return;
+  const empty = unwrittenSections(dir);
+  if (!empty.length) return;
+  check(checks, 'foundation:unwritten', 'project', 'warn',
+    `${FOUNDATION_EPIC}: ${empty.join(', ')} ${empty.length === 1 ? 'holds nothing but its' : 'hold nothing but their'} template, and its review has ${status === 'done' ? 'passed' : 'opened'}`,
+    status === 'done'
+      ? 'write the section, then re-open the review (a fresh PR/MR) — the approval on record approved an empty section'
+      : 'write the section before the review is approved — the yad-discovery skill says what each section needs');
+}
+
+function foundationGuardChecks(checks, root, hub) {
+  if (!exists(path.join(root, FOUNDATION_DIR, '.sdlc'))) return;
+  if (!isVerifiedLedger(hub)) return;
+  const stale = staleFoundationGuards(root);
+  if (!stale.length) return;
+  check(checks, 'foundation:guard', 'project', 'warn',
+    `the wired checks predate the Foundation: ${stale.join(', ')} ${stale.length === 1 ? 'does' : 'do'} not know \`${FOUNDATION_DIR}/\``,
+    `run \`yad update\` and commit the refreshed checks — until then CI does not stop a hand-edit of ${FOUNDATION_DIR}/.sdlc/ or a Foundation change on a non-review branch`);
+}
+
 // ---- file shape (schemaVersion) -------------------------------------------------------------
 // What shape this project's files are in, against the shape this engine writes. The stamp itself is
 // silent by design (cli/lib.mjs), and `yad migrate` only speaks when you run it — so without this
@@ -527,6 +815,7 @@ export function epicChecks(checks, root) {
 //         so the fix is to upgrade the CLI, not to touch the file
 const scopeOf = (rel) => {
   const parts = rel.split(path.sep);
+  if (parts[0] === FOUNDATION_DIR && parts.length > 1) return FOUNDATION_EPIC;   // E75
   return parts[0] === 'epics' && parts.length > 1 ? parts[1] : null;
 };
 
@@ -544,7 +833,7 @@ function shapeCheckFor(checks, id, label, rows, engine) {
   const readable = rows.filter((r) => r.from !== null);
   if (!readable.length) return;
   const ahead = readable.filter((r) => r.action === 'ahead');
-  // A file behind the engine on a VERIFIED hub is real drift, but `yad migrate` deliberately refuses
+  // A file behind the engine on a VERIFIED Product is real drift, but `yad migrate` deliberately refuses
   // to touch it — CI is its only writer. Pointing at migrate there would send someone to a command
   // that changes nothing while the warning never clears, so those are counted and named separately.
   const behind = readable.filter((r) => r.from < engine && r.action !== 'ci-owned');
@@ -588,8 +877,916 @@ function shapeCheckFor(checks, id, label, rows, engine) {
 // engine is on shape 1 nothing can be BEHIND it, so the warn branch — the one this section exists for —
 // is unreachable from a real project until the first real shape change lands. Tests supply a plan that
 // reaches it, which is how the drift report is proven before there is any drift to report.
+// A file that lives under two names must say the same thing under both. The engine writes them
+// together, so they only drift when something outside the engine touched one — a person editing the
+// name they happen to know, a script, a half-finished merge. The older name is the authoritative one
+// this major, so a silent drift means the OTHER copy is being ignored, which is the kind of thing
+// people lose an afternoon to. Say it out loud instead.
+export function mirrorChecks(checks, root) {
+  const pairs = [...MIRRORED_FILES.map(({ canonical, legacy }) => ({ canonical, legacy }))];
+  // The per-epic PR ledger is renamed the same way, so it drifts the same way. It is not in
+  // MIRRORED_FILES because that list is project-relative and this one exists once per epic.
+  // `epicIds` reads with `withFileTypes`, so a dangling symlink is simply not a directory — it cannot
+  // throw here and take the whole health check down, which is what the old `statSync` guard was for.
+  for (const e of epicIds(root)) {
+    const f = epicFiles(epicRel(e));
+    pairs.push({ canonical: f.productPrs, legacy: f.hubPrs });
+  }
+  for (const { canonical, legacy } of pairs) {
+    const a = path.join(root, canonical);
+    const b = path.join(root, legacy);
+    // Only the settings file reaches this branch in practice: the per-epic PR ledgers are top-level
+    // arrays, which carry no shape at all, so `shape >= 3` is never true for them. They can be
+    // reported as DRIFTED (below) but never as half-made, and that is correct — their new name
+    // appears when a gate command next writes them, not when the project migrates.
+    //
+    // One side missing is NORMAL before `yad migrate` — an un-migrated project has only the old name.
+    // It is not normal once the file says shape 3, because from then on every save writes both. And
+    // `writeMirrored` cannot repair it on its own: when the authoritative copy already matches, it
+    // correctly does nothing, so a half-made pair stays half-made and silent.
+    if (exists(a) !== exists(b)) {
+      const present = exists(a) ? a : b;
+      let shape;
+      try { shape = JSON.parse(fs.readFileSync(present, 'utf8'))?.schemaVersion ?? 1; } catch { continue; }
+      if (typeof shape === 'number' && shape >= 3) {
+        check(
+          checks, `mirror:${canonical}`, 'shape', 'warn',
+          `${exists(a) ? legacy : canonical} is missing — it should exist beside ${path.relative(root, present)} on shape ${shape}`,
+          'run `yad migrate --apply` — a missing partner counts as a change, so it writes the pair back into step',
+        );
+      }
+      continue;
+    }
+    if (!exists(a)) continue;
+    let same;
+    try { same = fs.readFileSync(a, 'utf8') === fs.readFileSync(b, 'utf8'); } catch { continue; }
+    if (same) continue;
+    check(
+      checks, `mirror:${canonical}`, 'shape', 'warn',
+      `${canonical} and ${legacy} do not match — ${legacy} is the one being read`,
+      'they are two names for one file while the rename settles. Copy the one you meant to keep over the other, then re-run the command that writes it',
+    );
+  }
+}
+
+// The two dials are one setting under two spellings, exactly like the mirrored file names, so they
+// drift the same way and are reported the same way. Two things can go wrong, and they need different
+// answers:
+//
+//   DISAGREE  a step says `assistance: heavy` and `driver: human`. Somebody edited one spelling, or a
+//             tool wrote one and a person wrote the other. The OLD name is the one that counts, and
+//             `yad migrate` will not fix it — the step already has the new key, so the step is
+//             skipped as done. Only a person can say which was meant.
+//   A REVIEW STEP CLAIMING AUTO  `advance: auto` on a step a human must sign off. The rule that never
+//             bends, and worth failing over rather than warning: it is the one dial value that can
+//             let work past a person.
+//
+// Scoped to the per-step dials only. `trust-log.json` records what a dial WAS on a past run and is
+// not a live setting, so a mismatch there is history, not drift.
+export function dialChecks(checks, root) {
+  const disagree = [];
+  const reviewAuto = [];
+  const newOnly = [];
+  const shapeStateAuto = [];
+  const lockedAuto = [];
+
+  const inspect = (rel, where, steps) => {
+    if (!Array.isArray(steps)) return;
+    for (const s of steps) {
+      if (!isPlainObject(s)) continue;
+      const at = `${rel}${where ? ` (${where})` : ''} step \`${s.id || '?'}\``;
+      if (typeof s.assistance === 'string' && typeof s.driver === 'string'
+          && DRIVER_FROM_ASSISTANCE[s.assistance] !== s.driver) {
+        disagree.push(`${at}: \`assistance: ${s.assistance}\` but \`driver: ${s.driver}\``);
+      }
+      if (typeof s.automation === 'string' && typeof s.advance === 'string'
+          && ADVANCE_FROM_AUTOMATION[s.automation] !== s.advance) {
+        disagree.push(`${at}: \`automation: ${s.automation}\` but \`advance: ${s.advance}\``);
+      }
+      // A step holding ONLY the new name is the half-made pair, and it is silent from every other
+      // direction: this CLI reads it fine, `yad migrate` only ever adds new-from-old so it can never
+      // repair it, and an OLDER CLI finds no dial at all and falls back to `human_approve` — turning
+      // a lane earned to auto back into a manual one with nothing to say why. That is the exact
+      // failure the two-name window exists to prevent, so doctor has to be the one that sees it.
+      if (typeof s.driver === 'string' && typeof s.assistance !== 'string') {
+        newOnly.push(`${at}: \`driver\` with no \`assistance\``);
+      }
+      if (typeof s.advance === 'string' && typeof s.automation !== 'string') {
+        newOnly.push(`${at}: \`advance\` with no \`automation\``);
+      }
+      const isReview = isGateStep(s);
+      const saysAuto = s.advance === 'auto' || s.automation === 'machine_advance';
+      if (isReview && saysAuto) {
+        reviewAuto.push(at);
+      }
+      // Two `auto`s E34 changed the meaning of (neither is a failure — nothing breaks, but the file says
+      // something that does not happen, or no longer holds). `where` is empty for state.json, a repo for
+      // build-state.
+      const def = catalogueStep(s.id);
+      if (!isReview && saysAuto && def?.kind === 'author') {
+        if (def.phase !== 'build' && !where) shapeStateAuto.push(at);
+        else if (def.phase === 'build' && s.locked === true) lockedAuto.push(at);
+      }
+    }
+  };
+
+  for (const e of epicIds(root)) {
+    const f = epicFiles(epicRel(e));
+    const state = readJSON(path.join(root, f.state), null);
+    if (state) inspect(f.state, '', state.steps);
+    const bsDir = path.join(root, f.buildStateDir);
+    if (!exists(bsDir)) continue;
+    let names;
+    try { names = fs.readdirSync(bsDir).filter((n) => n.endsWith('.json')).sort(); } catch { continue; }
+    for (const n of names) {
+      const bs = readJSON(path.join(bsDir, n), null);
+      if (!bs || typeof bs.repos !== 'object' || bs.repos === null) continue;
+      for (const [repo, r] of Object.entries(bs.repos)) inspect(`${f.buildStateDir}/${n}`, repo, r?.steps);
+    }
+  }
+
+  if (reviewAuto.length) {
+    check(
+      checks, 'dials:review-auto', 'shape', 'fail',
+      `a review step is set to advance on its own: ${reviewAuto.slice(0, 3).join('; ')}${reviewAuto.length > 3 ? ` (+${reviewAuto.length - 3} more)` : ''}`,
+      'a review gate can never be `auto` — set it back to `advance: human` (`automation: human_approve`). `yad migrate` never writes this value; something else did',
+    );
+  }
+  if (newOnly.length) {
+    check(
+      checks, 'dials:new-only', 'shape', 'warn',
+      `${newOnly.length} step(s) carry only the new dial name: ${newOnly.slice(0, 2).join('; ')}${newOnly.length > 2 ? ` (+${newOnly.length - 2} more)` : ''}`,
+      'add the older name beside it (`driver` needs `assistance`, `advance` needs `automation`) — an older yadflow reads only the old one and would see no dial at all. `yad migrate` cannot repair this: it only ever adds the new name from the old',
+    );
+  }
+  if (shapeStateAuto.length) {
+    check(
+      checks, 'dials:shape-auto-unread', 'shape', 'warn',
+      `${shapeStateAuto.length} Shape author step(s) say auto in state.json, where nothing reads a Shape dial: ${shapeStateAuto.slice(0, 2).join('; ')}${shapeStateAuto.length > 2 ? ` (+${shapeStateAuto.length - 2} more)` : ''}`,
+      'a Shape author step\'s dial is read from .sdlc/automation.json (E34) — set it with `yad dial <step> --to auto`',
+    );
+  }
+  if (lockedAuto.length) {
+    check(
+      checks, 'dials:locked-auto', 'shape', 'warn',
+      `${lockedAuto.length} Build step(s) are locked and set to auto, and \`locked\` no longer holds a Build author step at human (E34): ${lockedAuto.slice(0, 2).join('; ')}${lockedAuto.length > 2 ? ` (+${lockedAuto.length - 2} more)` : ''}`,
+      'if it should wait for a person: `yad dial <epic> <story> --repo <name> <step> --to human`',
+    );
+  }
+  if (disagree.length) {
+    check(
+      checks, 'dials:disagree', 'shape', 'warn',
+      `${disagree.length} step(s) carry two different dial values: ${disagree.slice(0, 2).join('; ')}${disagree.length > 2 ? ` (+${disagree.length - 2} more)` : ''}`,
+      'the OLD name (`assistance`/`automation`) is the one being read. Set both to the value you meant — `yad migrate` skips a step that already has the new key, so it cannot decide this for you',
+    );
+  }
+}
+
+// The advance dial and the kill switch (E34). Silent on a project that never touched either, so a project
+// with no `.sdlc/automation.json` — the frozen golden one included — reads exactly as before.
+export function automationChecks(checks, root) {
+  const rel = PROJECT_FILES.automationConfig;
+  const a = loadAutomation(root);
+  if (a.error) {
+    check(checks, 'automation', 'project', 'fail',
+      `${rel} ${a.error} — every step is held at advance: human until it is fixed`,
+      'fix the JSON, or delete the file to go back to the defaults (kill switch off, every Shape step human)');
+  } else {
+    if (a.kill?.on) {
+      const who = [a.kill.by ? `by ${a.kill.by}` : '', a.kill.date ? `on ${a.kill.date}` : ''].filter(Boolean).join(' ');
+      check(checks, 'automation:kill', 'project', 'warn',
+        `the kill switch is ON${who ? ` (${who})` : ''}${a.kill.reason ? `: ${a.kill.reason}` : ''} — every step is held at advance: human`,
+        'turn it off with `yad unkill` once the reason is gone');
+    }
+    const gates = [];
+    const build = [];
+    const unknown = [];
+    for (const [id, v] of Object.entries(a.steps)) {
+      const def = catalogueStep(id);
+      if (!ADVANCE_VALUES.includes(v)) unknown.push(`${id}: ${JSON.stringify(v)} is not human or auto`);
+      else if (!def) unknown.push(`${id}: not a step this release knows`);
+      else if (def.kind === 'review' && v === 'auto') gates.push(id);
+      else if (def.phase === 'build') build.push(id);
+    }
+    if (gates.length) {
+      check(checks, 'automation:gate', 'project', 'fail',
+        `${rel} sets a review gate to auto: ${gates.join(', ')}`,
+        'a gate is never auto (rule 1), and nothing honours this line — remove it');
+    }
+    if (build.length) {
+      check(checks, 'automation:build-step', 'project', 'warn',
+        `${rel} lists Build step(s) nothing reads here: ${build.join(', ')}`,
+        'a Build step\'s dial is set per lane — `yad dial <epic> <story> --repo <name> <step> --to auto`');
+    }
+    if (unknown.length) {
+      check(checks, 'automation:unknown', 'project', 'warn',
+        `${rel}: ${unknown.slice(0, 3).join('; ')}${unknown.length > 3 ? ` (+${unknown.length - 3} more)` : ''}`,
+        'only `auto` on a Shape author step is read; everything else is ignored');
+    }
+  }
+  // The switch's OLD home. Before E34 it was `kill_switch: true` in the module config `yad update` installs.
+  // Nothing reads that key now, so a team that set it by hand has a kill switch that silently turned OFF —
+  // the one change this row must never make quietly.
+  const legacy = path.join(root, '_bmad', 'sdlc', 'config.yaml');
+  let text = '';
+  try {
+    if (exists(legacy)) text = fs.readFileSync(legacy, 'utf8');
+  } catch { /* an unreadable module config has nothing to say about the switch */ }
+  // Every spelling YAML reads as true, and the old skill (a model reading the file) would have honoured.
+  if (/^\s*kill_switch:\s*(?:true|yes|on)\b/im.test(text) && !killSwitchOn(a)) {
+    check(checks, 'automation:legacy-kill', 'project', 'fail',
+      '_bmad/sdlc/config.yaml says `kill_switch: true`, and nothing reads that key any more — the kill switch is OFF',
+      'turn it on where it is read: `yad kill --reason "<why>"`. Then set that line back to false, or delete _bmad/sdlc/ (see `module:legacy-bmad`)');
+  }
+}
+
+// The module's OLD install folder (E3). Until E3, `yad setup` copied the module config into `_bmad/sdlc/`,
+// because yadflow was packaged as a BMAD module. Nothing reads that folder now, and nothing deletes it:
+// `automation:legacy-kill` above reads a `kill_switch` line in it, and a delete run before the doctor
+// would hide that the switch is off. So the folder is named here, and the team removes it. `_bmad/` on its
+// own is BMAD's install and none of ours; only the `sdlc/` folder inside it was written by yadflow.
+export function legacyModuleChecks(checks, root) {
+  if (!exists(path.join(root, '_bmad', 'sdlc'))) return;
+  const installed = exists(path.join(root, MODULE_CONFIG));
+  check(checks, 'module:legacy-bmad', 'project', 'warn',
+    `_bmad/sdlc/ is left over from before E3, and nothing reads it — the module config is ${MODULE_CONFIG} now`,
+    `${installed ? '' : `run \`yad check --fix\` to install ${MODULE_CONFIG}, then `}copy any value you changed in _bmad/sdlc/config.yaml into ${MODULE_CONFIG}, then delete _bmad/sdlc/. If \`automation:legacy-kill\` shows, clear it first — it reads that folder`);
+}
+
+// The work-item type, mid-rename. Shape 5 writes `type:` beside `kind:` in `epic.md` and copies the
+// value into `state.json`; `kind:` is still the name that is READ. Four things can go wrong while two
+// names are alive, and only one of them is a failure:
+//
+//   A GATE THAT CANNOT SEE THE TYPE   `type:` alone, with no `kind:`, on a change/defect/hotfix.
+//             `templates/checks/lineage-check.sh` runs inside the user's repository and is refreshed
+//             by `yad update`, which is a separate act from `yad migrate` with no ordering between
+//             them — so a repo that migrated but did not update has a copy that reads only `kind:`.
+//             It finds none, defaults to `feature`, decides the epic is a parent-free genesis, and
+//             stops asking it for its parent. A lineage gate silently disarmed by an upgrade is worth
+//             failing over; everything else here is drift a person can take their time with.
+//   ONLY THE NEW NAME, on a genesis type. The same half-made pair with nothing at stake — `feature`
+//             is what an older reader defaults to anyway.
+//   TWO DIFFERENT VALUES   `kind:` and `type:` disagree. The OLD one is being read, and `yad migrate`
+//             skips an epic that already has the new key, so only a person can say which was meant.
+//   A LEDGER THAT DISAGREES WITH THE EPIC   `state.json` records a `type` that is not what `epic.md`
+//             says. The epic.md value is the one the engine reads, so this is a stale copy.
+//   A TYPE NOBODY DEFINED   a value outside the five. It reads as a non-genesis type, so the lineage
+//             gate gets stricter rather than looser — a warning, not a failure.
+//
+// `state.json`'s own top-level `kind` is NOT looked at here. That is the `stub` / `foundation` / `discovery`
+// lifecycle marker, a different axis, and a stub legitimately carries both at once.
+export function typeChecks(checks, root) {
+  const epicsDir = path.join(root, 'epics');
+  if (!exists(epicsDir)) return;
+  const gateBlind = [];
+  const newOnly = [];
+  const disagree = [];
+  const ledger = [];
+  const unknown = [];
+
+  for (const e of fs.readdirSync(epicsDir).sort()) {
+    if (!isValidEpicId(e)) continue;
+    const md = path.join(epicsDir, e, 'epic.md');
+    if (!exists(md)) continue; // no epic.md — EP-discovery, not a work item on the ladder
+    const fm = readFrontmatter(md);
+    const hasOld = typeof fm.kind === 'string' && fm.kind;
+    const hasNew = typeof fm.type === 'string' && fm.type;
+    const resolved = workItemType(fm);
+
+    if (hasNew && !hasOld) {
+      if (isGenesisType(fm.type)) newOnly.push(`${e}: \`type: ${fm.type}\` with no \`kind:\``);
+      else gateBlind.push(`${e}: \`type: ${fm.type}\` with no \`kind:\``);
+    }
+    if (hasOld && hasNew && fm.kind !== fm.type) {
+      disagree.push(`${e}: \`kind: ${fm.kind}\` but \`type: ${fm.type}\``);
+    }
+    if (!WORK_ITEM_TYPES.includes(resolved)) unknown.push(`${e}: \`${resolved}\``);
+
+    const state = readJSON(path.join(epicsDir, e, '.sdlc', 'state.json'), null);
+    if (isPlainObject(state) && typeof state.type === 'string' && state.type !== resolved) {
+      ledger.push(`${e}: epic.md says \`${resolved}\`, state.json says \`${state.type}\``);
+    }
+  }
+
+  const some = (list, n) => `${list.slice(0, n).join('; ')}${list.length > n ? ` (+${list.length - n} more)` : ''}`;
+  if (gateBlind.length) {
+    check(
+      checks, 'type:gate-blind', 'shape', 'fail',
+      `${gateBlind.length} epic(s) record a type only the newest yadflow can see: ${some(gateBlind, 3)}`,
+      'add `kind:` beside `type:` in epic.md. `lineage-check.sh` inside your repo reads `kind:` and, finding none, treats the epic as a parent-free genesis — so it stops requiring the `parent:` a change/defect/hotfix must have. Run `yad update` to refresh the check gates too',
+    );
+  }
+  if (newOnly.length) {
+    check(
+      checks, 'type:new-only', 'shape', 'warn',
+      `${newOnly.length} epic(s) carry only the new name: ${some(newOnly, 2)}`,
+      'add `kind:` beside `type:` — it is still the name every other reader uses. Nothing can do it for you: `yad migrate` never writes `epic.md` at all',
+    );
+  }
+  if (disagree.length) {
+    check(
+      checks, 'type:disagree', 'shape', 'warn',
+      `${disagree.length} epic(s) name two different types: ${some(disagree, 2)}`,
+      'the OLD name (`kind:`) is the one being read. Set both to the type you meant',
+    );
+  }
+  if (ledger.length) {
+    check(
+      checks, 'type:ledger', 'shape', 'warn',
+      `${ledger.length} epic ledger(s) disagree with their epic.md: ${some(ledger, 2)}`,
+      'epic.md is where the type is authored and is what the engine reads. Correct `type` in `.sdlc/state.json`, or fix epic.md if the ledger was right',
+    );
+  }
+  if (unknown.length) {
+    check(
+      checks, 'type:unknown', 'shape', 'warn',
+      `${unknown.length} epic(s) use a type nobody defined: ${some(unknown, 3)}`,
+      `a work item is one of ${WORK_ITEM_TYPES.join(' · ')}. An unrecognised value reads as a non-genesis type, so the lineage gate will demand a \`parent:\` for it`,
+    );
+  }
+}
+
+// The grouping theme (E31) — a free tag on `epic.md` that puts several epics under one heading. It is
+// deliberately unvalidated: there is no list of allowed themes, and having none is normal. So there is
+// nothing here to check about a SINGLE epic. Both reports below are about the tag failing at the one
+// job it has, which is putting epics together.
+//
+// Reported in the `shape` section beside the type and phase checks: those three are the engine's own
+// vocabulary, and the golden test freezes the `epics` and `threads` sections against exactly this kind
+// of addition (rule 6).
+export function themeChecks(checks, root) {
+  const epicsDir = path.join(root, 'epics');
+  if (!exists(epicsDir)) return;
+  const spellings = new Map();   // folded key -> the distinct spellings seen, in first-seen order
+  const unreadable = [];
+  const commented = [];
+
+  for (const e of fs.readdirSync(epicsDir).sort()) {
+    if (!isValidEpicId(e)) continue;
+    const md = path.join(epicsDir, e, 'epic.md');
+    if (!exists(md)) continue;   // no epic.md — EP-discovery, not a work item on the ladder
+    const fm = readFrontmatter(md);
+    // `readFrontmatter` turns `theme: [a, b]` into an array, and a theme is ONE tag. Left alone the
+    // value would simply read as absent, so the epic would drop out of every grouping in silence.
+    // An EMPTY list is not this — `theme: []` plainly says "no theme", and so does a blank `theme:`,
+    // which is what the skill templates ship.
+    if (Array.isArray(fm.theme)) {
+      if (fm.theme.length) unreadable.push(`${e}: \`theme: [${fm.theme.join(', ')}]\``);
+      continue;
+    }
+    const t = themeOf(fm);
+    if (!t) continue;
+    // A `#` inside the tag is almost always the comment trap: neither `readFrontmatter` nor the check
+    // gates' `fm_val` strips a trailing `# …`, so it lands in the value. The tag IS read — it is not
+    // unreadable — but it now includes the note, so it groups only with epics carrying that exact
+    // text. Reported on its own rather than as a spelling variant, which would be true of
+    // `#checkout-revamp` beside `checkout-revamp` while naming the wrong problem.
+    if (t.includes('#')) { commented.push(`${e}: \`theme: ${t}\``); continue; }
+    const key = themeKey(t);
+    // Nothing left after the fold — a tag of pure punctuation or symbols, like `🎯`. Nothing is wrong
+    // with it: it reads, and two epics carrying it group by being the same string. It is only left OUT
+    // of the variant report, which has nothing to compare. Keeping it IN would be the bug: every such
+    // tag folds to the same empty key, so `🎯` and `···` would be reported as one theme spelled two
+    // ways — which is exactly backwards.
+    if (!key) continue;
+    const seen = spellings.get(key) || [];
+    if (!seen.includes(t)) seen.push(t);
+    spellings.set(key, seen);
+  }
+
+  const variants = [...spellings.values()].filter((v) => v.length > 1);
+  const some = (list, n) => `${list.slice(0, n).join('; ')}${list.length > n ? ` (+${list.length - n} more)` : ''}`;
+  if (variants.length) {
+    check(
+      checks, 'theme:variants', 'shape', 'warn',
+      `${variants.length} grouping theme(s) are spelled more than one way: ${some(variants.map((v) => v.map((x) => `\`${x}\``).join(' / ')), 2)}`,
+      'these are one theme typed differently, and they group as two. Pick one spelling and use it in every `epic.md` that belongs to the group',
+    );
+  }
+  if (unreadable.length) {
+    check(
+      checks, 'theme:unreadable', 'shape', 'warn',
+      `${unreadable.length} epic(s) have a \`theme:\` nothing can read: ${some(unreadable, 3)}`,
+      'a theme is ONE free tag — a word or short phrase, in any language. A list is read as no theme at all, so the epic drops out of every grouping',
+    );
+  }
+  if (commented.length) {
+    check(
+      checks, 'theme:commented', 'shape', 'warn',
+      `${commented.length} epic(s) have a \`#\` inside the theme itself: ${some(commented, 3)}`,
+      'these frontmatter readers keep the whole rest of the line, so a `#` and everything after it becomes part of the tag — the epic then groups only with epics carrying that exact text. Write the tag bare. `yad next` and `yad thread` print a `#` in front of it, but that is decoration on the screen, not part of the value',
+    );
+  }
+}
+
+// A project's chain against the step catalogue (E4). `phaseChecks` below asks whether a step id is
+// KNOWN; this asks whether a known step is set up the way the catalogue says it is.
+//
+// IT REPORTS AND CHANGES NOTHING, and when the two disagree THE FILE WINS for this whole major
+// (rule 3). `yad epic new` seeds from the catalogue and three of the five authoring skills now call
+// it, so a fresh epic on those routes cannot disagree with it by accident — but `yad-discovery` and
+// `yad-change` still write their own, a chain may legitimately leave a step out (not every epic has a
+// `ui-design`), and a project may hold a chain from a newer yadflow. So a mismatch is a warning about a file somebody should look at, never
+// a rewrite — the same discipline as `workItemType`.
+//
+// Nothing here reports a step that is ABSENT from a chain. Skipping `ui-design` on an epic with no
+// screens is a normal thing to do, and a check that nagged about it would train people to ignore the
+// section that also carries the two below, which are real breakage.
+export function catalogueChecks(checks, root) {
+  const wrongArtifact = [];
+  const noArtifact = [];
+  const wrongKind = [];
+  const orphanGate = [];
+  const offRoute = [];
+
+  for (const e of epicIds(root)) {
+    const state = readJSON(path.join(epicRoot(root, e), '.sdlc', 'state.json'), null);
+    if (!isPlainObject(state) || !Array.isArray(state.steps)) continue;
+    const present = new Set(state.steps.map((s) => s?.id).filter((x) => typeof x === 'string'));
+
+    // Which lifecycle profile is this epic walking? Worked out from the CHAIN, not from the `profile`
+    // key shape 6 records — the key says which route the epic was started on, and this is about the
+    // steps as they stand. (`profileChecks` below is what compares the two.) A chain matching NO
+    // profile carries a step no route has, or has them out of order, and `yad next` walks a chain in
+    // array order: the step it names next is then whatever happens to sit there, not the step that
+    // comes next in any route.
+    if (state.steps.length && !matchLifecycleProfile(state.steps)) {
+      const known = state.steps.filter((x) => stepDef(x?.id));
+      // Only reported when every step is one the catalogue knows. An id from a newer release is
+      // `phase:unknown`'s business, and a chain full of them would otherwise be reported twice.
+      if (known.length === state.steps.length) {
+        offRoute.push(`${e}: \`${state.steps.map((x) => x.id).join(' → ')}\``);
+      }
+    }
+
+    for (const step of state.steps) {
+      const def = step && typeof step.id === 'string' ? stepDef(step.id) : null;
+      if (!def) continue;   // unknown id — `phase:unknown` below is the check for that
+      // ONLY THE ARTIFACT COMPARISON skips a Build id, and only because there is nothing to compare:
+      // Build runs per story per code repo out of `build-state/`, so those catalogue rows carry no
+      // epic-level artifact. The two checks below still run on a Build id in an epic chain, which is
+      // right — `implement` written as a `review+approve` step is wrong wherever it appears.
+      //
+      // The artifact is what the gate HASHES. A chain naming a different one binds the approval to
+      // the wrong file, so the gate can pass while the artifact everybody reviewed sits unapproved.
+      //
+      // Compared through `artifactBase`, which is how every consumer reads this field
+      // (`findReviewStep`, `artifactHash`, `yad gate`). It maps `stories`, `stories/`, `stories.md`
+      // and `stories/EP-x-S01.md` all to one gate, so those spellings differ on paper and are the
+      // same artifact in fact. Comparing the raw strings would warn that a chain which gates, hashes
+      // and approves perfectly is bound to the wrong file — a false statement, and the kind that
+      // teaches people to stop reading warnings.
+      if (def.artifact && typeof step.artifact === 'string' && step.artifact
+          && !artifactAgrees(def, step.artifact)) {
+        wrongArtifact.push(`${e} \`${step.id}\`: \`${step.artifact}\`, catalogue says \`${def.artifact}\``);
+      }
+      // A Shape step with NO artifact at all is the one shape that crashes rather than misfires:
+      // `artifactBase(undefined)` throws, so `yad gate` on such a chain dies with an unhandled
+      // TypeError instead of a message. Reported here because this is where the catalogue knows the
+      // step should have named a file.
+      if (def.artifact && (step.artifact === undefined || step.artifact === null || step.artifact === '')) {
+        noArtifact.push(`${e} \`${step.id}\` (should be \`${def.artifact}\`)`);
+      }
+      // `type` in the file is `author` or `review+approve`; the catalogue calls the second one
+      // `review`. A step on the wrong side of that line is not driven by what drives it: an author
+      // step written as a gate is never closed by `yad gate`, and a gate written as an author step is
+      // handed to a skill that has no artifact to write.
+      const fileKind = step.type === 'review+approve' ? 'review' : step.type === 'author' ? 'author' : null;
+      if (fileKind && fileKind !== def.kind) {
+        wrongKind.push(`${e} \`${step.id}\`: \`${step.type}\`, catalogue says \`${def.kind}\``);
+      }
+      // A gate whose author step is not in the chain has nothing to review. Note what this does NOT
+      // do: it does not block the steps after it. `preconditionsMet` only requires the steps BEFORE
+      // one in the array to be done, and an absent step is in no such position — that is the
+      // different problem of an author step present and stranded (issue #131), which
+      // `stateInvariants` already reports.
+      if (def.reviews && !present.has(def.reviews)) {
+        orphanGate.push(`${e} \`${step.id}\` reviews \`${def.reviews}\`, which is not in the chain`);
+      }
+    }
+  }
+
+  const some = (list, n) => `${list.slice(0, n).join('; ')}${list.length > n ? ` (+${list.length - n} more)` : ''}`;
+  if (offRoute.length) {
+    const routes = LIFECYCLE_PROFILES.map((p) => `\`${p.id}\` (${p.title})`).join(' · ');
+    check(
+      checks, 'step:off-route', 'shape', 'warn',
+      `${offRoute.length} epic(s) walk a chain that matches no lifecycle profile: ${some(offRoute, 2)}`,
+      `a profile is the route an epic takes through the steps — ${routes}. Leaving a step OUT is fine; a step no route has, or two in the wrong order, is not: \`yad next\` reads the chain in the order it is written, so it will name whatever sits next rather than what comes next. In \`.sdlc/state.json\`, put the steps back in a route's order — and REMOVE any step no route has, which reordering cannot fix. A Build step (\`spec\`, \`tasks\`, \`implement\`, \`checks\`, \`engineer-review\`) is one of those: Build runs per story per repo out of \`build-state/\`, so it belongs in no epic chain`,
+    );
+  }
+  if (wrongArtifact.length) {
+    check(
+      checks, 'step:artifact', 'shape', 'warn',
+      `${wrongArtifact.length} step(s) name an artifact the catalogue does not: ${some(wrongArtifact, 3)}`,
+      'the artifact is the file the review gate hashes, so a wrong one binds the approval to the wrong file. Correct `artifact` in `.sdlc/state.json`, or leave it if this project deliberately runs a different chain — nothing is rewritten either way',
+    );
+  }
+  if (noArtifact.length) {
+    check(
+      checks, 'step:no-artifact', 'shape', 'warn',
+      `${noArtifact.length} step(s) name no artifact at all: ${some(noArtifact, 3)}`,
+      'the gate reads this field to know what to hash, and a missing one is not treated as "nothing" — `yad gate` stops with an unhandled error on this epic. Add `artifact` to the step in `.sdlc/state.json`',
+    );
+  }
+  if (wrongKind.length) {
+    check(
+      checks, 'step:kind', 'shape', 'warn',
+      `${wrongKind.length} step(s) are the wrong kind of step: ${some(wrongKind, 3)}`,
+      'an author step is run by a skill and a `review+approve` step by `yad gate`. On the wrong side of that line the step is never driven by the thing that drives it',
+    );
+  }
+  if (orphanGate.length) {
+    check(
+      checks, 'step:orphan-gate', 'shape', 'warn',
+      `${orphanGate.length} review gate(s) review a step that is not there: ${some(orphanGate, 3)}`,
+      'nothing in this chain tells anyone to write the artifact the gate reviews, and for a directory artifact the hash comes back empty, so the gate has nothing to bind an approval to. Add the author step, or drop the gate if this chain deliberately inherits that artifact from its parent epic',
+    );
+  }
+}
+
+// The lifecycle profile an epic RECORDS (E17, shape 6) against the chain it actually walks.
+//
+// Before shape 6 the route was only ever derived, so it could not be wrong — it was whatever the chain
+// said. Now `state.json` names it, and a name can go stale: someone edits the chain by hand, or copies
+// a ledger from another epic, and the file claims a route it is no longer on. That matters because the
+// name is what a seed and a renderer trust WITHOUT re-reading the chain.
+//
+// Reported, never corrected. The file wins for this whole major (rule 3) — an epic may carry a route
+// from a newer yadflow, and `yad migrate` deliberately never overwrites a `profile` somebody wrote.
+//
+// NO OVERLAP WITH `step:off-route`, on purpose. That check fires when a chain fits no route at all,
+// and it already tells the user their chain is broken and how. Re-reporting the same epic here as
+// "the recorded route disagrees" would name the same fault twice with two different remedies, so this
+// check speaks only when the chain fits a route CLEANLY and it is a different one from the record.
+export function profileChecks(checks, root) {
+  const unknown = [];
+  const disagree = [];
+
+  for (const e of epicIds(root)) {
+    const state = readJSON(path.join(epicRoot(root, e), '.sdlc', 'state.json'), null);
+    // No key at all is the normal state for a chain that matches no route: `stampProfile` declines to
+    // invent one, and `step:off-route` is what reports that chain. Nothing to say here.
+    if (!isPlainObject(state) || !('profile' in state)) continue;
+    const recorded = state.profile;
+    if (!lifecycleProfile(recorded)) {
+      unknown.push(`${e}: \`${recorded === null ? 'null' : String(recorded)}\``);
+      continue;
+    }
+    const matched = matchLifecycleProfile(state.steps);
+    if (matched && matched !== recorded) {
+      disagree.push(`${e}: records \`${recorded}\`, its chain is \`${matched}\``);
+    }
+  }
+
+  const some = (list, n) => `${list.slice(0, n).join('; ')}${list.length > n ? ` (+${list.length - n} more)` : ''}`;
+  if (unknown.length) {
+    check(
+      checks, 'profile:unknown', 'shape', 'warn',
+      `${unknown.length} epic(s) record a lifecycle profile nobody defined: ${some(unknown, 3)}`,
+      `a profile is one of ${LIFECYCLE_PROFILES.map((p) => p.id).join(' · ')}. An unrecognised value means nothing can say which route this epic is on, so every reader falls back to matching the chain — set \`profile\` in \`.sdlc/state.json\` to the route it walks, or delete the key and let it be derived`,
+    );
+  }
+  if (disagree.length) {
+    check(
+      checks, 'profile:disagree', 'shape', 'warn',
+      `${disagree.length} epic(s) record a route their chain is not on: ${some(disagree, 2)}`,
+      'the chain is what `yad next` walks step by step, and the recorded name is the label on top of it — so a stale label misleads whoever reads the record instead of the steps. It is not only cosmetic: the recorded name is what decides which steps this epic may SKIP (E35), deliberately, because a chain carrying a step from a newer release fits no route here and must not lose its optional steps for it. Correct `profile` in `.sdlc/state.json` to the route the chain shows',
+    );
+  }
+}
+
+// A step marked N/A ("skipped") that the epic's own route does NOT mark optional (E35).
+//
+// This could not be reported before, because the engine kept one list of skippable steps for the whole
+// project: a step optional on any route was skippable on every epic. Now the question is answered by
+// the route the epic is on, so the two can disagree — a chain edited by hand, a recorded route changed,
+// or a ledger copied from an epic on a different route.
+//
+// WHAT IT COSTS, stated the same way the hint states it. `gatePredicate` honours `skipped: true` only
+// for a step this epic's route marks optional, so a skip the route does not allow stops
+// short-circuiting. NOTHING BREAKS: the step is already `done`, so `yad gate sync` takes its
+// already-done branch, reports that the rule no longer holds and changes nothing — no step is
+// un-advanced, no review re-opens. What is lost is the justification: the gate stops treating the skip
+// as the reason the step passed, which is the whole point of recording a skip. This says so before the
+// next sync rather than after it.
+//
+// Reported, never corrected, like everything else here: clearing the flag would erase a recorded
+// decision, and re-marking the step `blocked` would undo work the team may have finished.
+export function skipChecks(checks, root) {
+  const some = (list, n) => `${list.slice(0, n).join('; ')}${list.length > n ? ` (+${list.length - n} more)` : ''}`;
+  const bad = [];
+
+  for (const e of epicIds(root)) {
+    const state = readJSON(path.join(epicRoot(root, e), '.sdlc', 'state.json'), null);
+    if (!isPlainObject(state) || !Array.isArray(state.steps)) continue;
+    // Silent on an epic `profile:disagree` already names. Both findings come from the same stale
+    // label, and that check's remedy — correct `profile` to the route the chain shows — clears this
+    // one too. Naming one fault twice with two remedies is what this file forbids itself elsewhere.
+    if (recordedRouteDisagrees(state)) continue;
+    const optional = optionalStepsFor(state);
+    // `claimsSkipped`, not the canonical state: this check exists to report a claim the route does not
+    // allow, so it has to see the claim before it can refuse it. A HALF-STAMPED one — `skipped: true`
+    // on a step that is not `done` — is the case most worth reporting, and reading the canonical state
+    // would let exactly that one through silently (E38).
+    // A `deferred` step (E37) needs the same route permission, because the chain walks past it with no
+    // approvals on its review — so the same finding covers it. It has no legacy flag, so its status word
+    // is the claim.
+    const skipped = new Set(state.steps.filter((x) => (claimsSkipped(x) || stepStatus(x) === 'deferred') && typeof x.id === 'string').map((x) => x.id));
+    for (const step of state.steps) {
+      if (!skipped.has(step.id)) continue;
+      if (isSkippableStep(step.id, optional)) continue;
+      // AUTHOR STEPS ONLY, when the pair is both marked. One `yad skip` stamps a step and its gate, so
+      // listing both reads as two faults for one action — and the remedy below takes the author step's
+      // id. A gate marked on its own is a different, real fault and is still reported.
+      if (step.id.endsWith('-review') && skipped.has(step.id.replace(/-review$/, ''))) continue;
+      bad.push(`${e}/${step.id}`);
+    }
+  }
+
+  if (bad.length) {
+    check(
+      checks, 'skip:not-optional', 'shape', 'warn',
+      `${bad.length} skipped or deferred step(s) their epic's route does not mark optional: ${some(bad, 3)}`,
+      'the gate fails closed on a skip the route does not allow, so it stops treating the skip as the reason the step passed. On a step already marked N/A in full nothing breaks: it reads as passed either way, and `yad gate sync` reports that the rule no longer holds and changes nothing — what is lost is the justification. A HALF-STAMPED one is different and is why this reads the claim rather than the state: `skipped: true` on a step that is not finished is a flag nothing honours, so the step is simply not done and the chain waits on it. Either the epic is on the wrong route (`step:off-route`), or the skip was written by hand — `yad unskip <epic> <step>` puts the step back in the chain (`yad undefer <epic> <step>` for a deferred one). It refuses, naming the step, once work has started past the step that follows the skipped pair, or that step is finished: the chain has been built on the skip by then, and putting it right is a decision about that later work, not a command',
+    );
+  }
+}
+
+// ---- the step-state model (E38) -----------------------------------------------------------------
+//
+// Two findings about a step's `status`, both REPORTED and never corrected — the same discipline as
+// every other check in this file. Correcting either one would mean this command deciding what
+// somebody's file meant, which is exactly what a project runs `yad doctor` to avoid.
+//
+// `step:unknown-status` — a status no word in STEP_STATES names, and no legacy spelling either.
+// This is NOT automatically a fault. A project may hold a step written by a NEWER yadflow, and for
+// this whole major the file wins (the same rule as the step catalogue and the work-item type). What
+// it costs is real and worth saying once: `stepStatus` fails closed on a word it cannot name, so
+// every reader treats the step as neither passed nor authored — the chain stops there, and
+// `yad next` will keep naming the step before it.
+//
+// `step:no-record` — a status that must say WHY and does not. Four of the eight states carry a
+// record: `skipped`, `deferred`, `satisfied` and `blocked`. A skip with no reason is the thing the
+// whole design refuses — "a recorded skip is not a hole in the audit trail, it IS the audit trail" —
+// so a recorded state with nothing recorded on it is a hole wearing the shape of a record.
+//
+// TWO DELIBERATE NARROWINGS, and each of them is what keeps this check honest rather than noisy:
+//
+//  1. It reads the `status` FIELD literally, not `stepStatus`. The legacy encodings carry their own
+//     provenance — a skipped step has `skipReason`/`skippedBy`/`skippedAt`, an inherited one has
+//     `inheritedFrom`/`boundHash` — and for this major those ARE the record. Asking a pre-shape-7
+//     project for a `record` it had no way to write would report every change-epic in the project,
+//     including the frozen one the golden test pins.
+//  2. A literal `blocked` is asked for a record only at shape 7 and above. Below it, `blocked` is the
+//     old spelling of "not started" and there is nothing to explain. At shape 7 the stamper has
+//     already rewritten those, so one that remains was hand-written — and it still READS as `todo`,
+//     which is the surprising half and what the hint leads with.
+
+// The shape in which `blocked` stopped meaning "not started". A FIXED historical number, not
+// `SCHEMA_VERSION`: that one moves with every future shape change, and this fact does not.
+const BLOCKED_CHANGED_MEANING_AT = 7;
+
+export function stepStateChecks(checks, root) {
+  const some = (list, n) => `${list.slice(0, n).join('; ')}${list.length > n ? ` (+${list.length - n} more)` : ''}`;
+  const unknown = [];
+  const noRecord = [];
+  const owed = [];
+
+  for (const e of epicIds(root)) {
+    const state = readJSON(path.join(epicRoot(root, e), '.sdlc', 'state.json'), null);
+    if (!isPlainObject(state) || !Array.isArray(state.steps)) continue;
+    // The shape as the FILE records it, by rule 1: no key means shape 1.
+    const shape = Number.isInteger(state.schemaVersion) ? state.schemaVersion : 1;
+    for (const d of owedSteps(state)) owed.push(`${e}/${d.id.replace(/-review$/, '')} (${stepStatus(d) ?? d.status})`);
+    for (const step of state.steps) {
+      if (!isPlainObject(step) || typeof step.id !== 'string') continue;
+      if (typeof step.status !== 'string') continue; // `validateState` is what reports a missing one
+      if (!stepStatus(step)) { unknown.push(`${e}/${step.id}: \`${step.status}\``); continue; }
+      if (!RECORDED_STEP_STATES.includes(step.status)) continue;
+      if (step.status === 'blocked' && shape < BLOCKED_CHANGED_MEANING_AT) continue;
+      if (!isStepRecord(step.record)) noRecord.push(`${e}/${step.id} (${step.status})`);
+    }
+  }
+
+  if (unknown.length) {
+    check(
+      checks, 'step:unknown-status', 'shape', 'warn',
+      `${unknown.length} step(s) carry a status this release does not know: ${some(unknown, 3)}`,
+      `the states this engine knows are ${STEP_STATES.map((x) => x.id).join(' · ')}. Nothing is rewritten: a chain may legitimately come from a newer yadflow, and the file wins. But an unnamed state fails closed — the step counts as neither passed nor authored, so the chain stops there and \`yad next\` keeps naming the step in front of it. Either upgrade the CLI to the release that wrote it, or correct the value in \`.sdlc/state.json\``,
+    );
+  }
+  // `step:debt` (E41) — a reminder, not a fault: the team chose to owe the work (`yad defer --debt`), and
+  // this repeats on every run until the step's review passes, which is what clears the flag.
+  if (owed.length) {
+    check(
+      checks, 'step:debt', 'shape', 'warn',
+      `${owed.length} step(s) still owed as debt: ${some(owed, 3)}`,
+      `a debt is a step deferred with \`--debt\`: owed back, and reminded until paid. \`yad undefer <epic> <step>\` starts paying it — after later work has finished, the step re-opens beside that work, which stays done — and the debt clears when the step's review passes${isVerifiedLedger(readJSON(productConfigPath(root), null)) ? '. On this verified Product `yad undefer` is refused once an epic\'s ledger is on the default branch: only CI writes `state.json` there, and CI has no step for it yet' : ''}`,
+    );
+  }
+  if (noRecord.length) {
+    check(
+      checks, 'step:no-record', 'shape', 'warn',
+      `${noRecord.length} step(s) hold a recorded state with nothing recorded: ${some(noRecord, 3)}`,
+      `${RECORDED_STEP_STATES.join(' · ')} each have to say WHY — a \`record\` of \`{ reason, by, date, link? }\` — because the reason is the audit trail the state exists to leave. A \`blocked\` with no record is the one that also changes meaning: every reader falls back to treating it as \`todo\` (not started), so the step does not read as waiting on anybody. Add the \`record\` in \`.sdlc/state.json\`, or move the step to the state that describes it`,
+    );
+  }
+}
+
+// `.sdlc/skills.json`: which skill runs which step, when the project does not want the engine's
+// default (E6). Absent is the normal case and says nothing — most projects run the shipped skills.
+//
+// REPORTS, NEVER CORRECTS, and never judges a skill NAME. The engine cannot know which skills a team
+// has installed — that is E50's job — and binding a skill this release has never heard of is the whole
+// point of the file. So the only things checked here are the ones the engine CAN know: does the file
+// parse, is a value usable, and is the step id one this engine runs at all.
+//
+// Three warnings, all of them "your line did nothing", which is the failure a config file makes easy
+// to miss. A typo in a step id is silent otherwise: the binding sits in the file, `yad next` never
+// looks it up, and the team concludes the feature does not work.
+export function skillBindingChecks(checks, root) {
+  const rel = PROJECT_FILES.skillsConfig;
+  const file = path.join(root, rel);
+  if (!exists(file)) return;
+
+  let raw;
+  try {
+    raw = readJSONStrict(file, null);
+  } catch (e) {
+    check(checks, 'skills', 'project', 'fail', `${rel} does not parse [${e.code || 'YAD-STATE-001'}]`,
+      e.hint || 'fix the JSON or restore it from git');
+    return;
+  }
+  if (!isPlainObject(raw)) {
+    check(checks, 'skills', 'project', 'fail', `${rel} has the wrong shape [YAD-STATE-002]`, 'expected a JSON object');
+    return;
+  }
+  // `steps` missing entirely is fine — a file holding only `schemaVersion` is what `yad skill unbind`
+  // leaves behind when the last binding goes, and it binds nothing, correctly.
+  if (raw.steps !== undefined && !isPlainObject(raw.steps)) {
+    check(checks, 'skills', 'project', 'fail', `${rel}: \`steps\` must be a JSON object [YAD-STATE-002]`,
+      'expected `"steps": { "<step-id>": "<skill>" }`');
+    return;
+  }
+
+  const bindings = normalizeBindings(raw);
+  const bound = Object.entries(bindings.steps);
+  // Dropped by `normalizeBindings` — a number, an empty string, an empty list. The line is in the file
+  // and does nothing, which is the one thing a person editing it would never guess.
+  const unusable = Object.keys(raw.steps || {})
+    .filter((id) => !Object.hasOwn(bindings.steps, id));
+  // A step id this engine does not run. The file still wins — a project may hold a step from a newer
+  // release — so this changes nothing and only says the binding is asleep.
+  const unknown = bound.map(([id]) => id).filter((id) => !stepDef(id));
+  // A step id the engine knows but runs no skill for: a Shape review gate, driven by `yad gate`.
+  const gates = bound.map(([id]) => id).filter((id) => stepDef(id) && !stepDef(id).skill);
+
+  if (unusable.length) {
+    check(checks, 'skills', 'project', 'warn',
+      `${rel}: ${unusable.length} binding(s) name no skill and are ignored — ${unusable.join(', ')} [YAD-CFG-006]`,
+      'each value must be a skill name or a non-empty list of them');
+  }
+  if (unknown.length) {
+    check(checks, 'skills:unknown-step', 'project', 'warn',
+      `${rel} binds ${unknown.length} step(s) this yadflow does not run: ${unknown.join(', ')}`,
+      'check the spelling against `yad skill list`, or upgrade yadflow if the step is from a newer release');
+  }
+  if (gates.length) {
+    check(checks, 'skills:review-step', 'project', 'warn',
+      `${rel} binds ${gates.join(', ')}, which no skill runs — review gates are driven by \`yad gate\``,
+      'bind the author step instead (for example `architecture`, not `architecture-review`)');
+  }
+  // Its OWN id, not `skills` again. A file with one good binding and one broken line fires both, and
+  // two checks sharing an id put a green tick under the complaint in prose — and, worse, let a `--json`
+  // consumer keying by id overwrite the warning with the tick.
+  if (bound.length) {
+    const chained = bound.filter(([, list]) => list.length > 1).length;
+    check(checks, 'skills:bound', 'project', 'ok',
+      `skills: ${bound.length} step(s) bound${chained ? `, ${chained} to more than one skill` : ''}`);
+  }
+}
+
+// A step this release does not recognise. Every step the engine can run has a row in the step
+// catalogue (E4), and that row is what gives it both a phase and a skill. So an id no phase claims is
+// an id with no row at all: one `yad next` cannot guide, `yad gate` has no artifact rule for, and no
+// renderer can place in the lifecycle. It is reported rather than ignored, and only warned about rather than failed: a project
+// may legitimately hold a step from a newer yadflow than the one being run, and a hand-written
+// `state.json` is allowed to be ahead of the tool reading it.
+//
+// THREE PLACES A STEP ID CAN APPEAR, and all three are read:
+//   * `state.json` `steps[]` — the Shape chain;
+//   * `state.json` `currentStep` — the field `yad thread --json` derives its `phase` from, and the one
+//     nothing else validates. A typo there does not break `yad next`, which falls back to the first
+//     step that is not done, so it would otherwise sit in a project unreported;
+//   * `build-state/<story>.json` `repos.<name>.steps[]` — the Build half. Without these, five of the
+//     twelve known step ids have no reader on this path at all.
+// The four `currentStep` sentinels are markers rather than steps and are skipped by name.
+export function phaseChecks(checks, root) {
+  const unplaced = [];
+  // One report per unknown id per epic. `currentStep` usually names a step that is also in `steps[]`,
+  // so a single typo would otherwise be listed twice and push a genuinely different one out of the
+  // three the message has room for.
+  let seen = new Set();
+  const consider = (where, id) => {
+    if (typeof id !== 'string' || !id || SENTINELS.includes(id) || seen.has(id)) return;
+    if (stepPhase(id)) return;
+    seen.add(id);
+    unplaced.push(`${where}: \`${id}\``);
+  };
+  const considerSteps = (where, steps) => {
+    if (!Array.isArray(steps)) return;
+    for (const s of steps) if (isPlainObject(s)) consider(where, s.id);
+  };
+  for (const e of epicIds(root)) {
+    seen = new Set();
+    const state = readJSON(path.join(epicRoot(root, e), '.sdlc', 'state.json'), null);
+    if (isPlainObject(state)) {
+      considerSteps(e, state.steps);
+      consider(`${e} (currentStep)`, state.currentStep);
+    }
+    const bsDir = path.join(epicRoot(root, e), '.sdlc', 'build-state');
+    if (!exists(bsDir)) continue;
+    let names;
+    try { names = fs.readdirSync(bsDir).filter((n) => n.endsWith('.json')).sort(); } catch { continue; }
+    for (const n of names) {
+      const bs = readJSON(path.join(bsDir, n), null);
+      if (!isPlainObject(bs) || !isPlainObject(bs.repos)) continue;
+      for (const [repo, r] of Object.entries(bs.repos)) considerSteps(`${e}/${n} (${repo})`, r?.steps);
+    }
+  }
+  if (unplaced.length) {
+    check(
+      checks, 'phase:unknown', 'shape', 'warn',
+      `${unplaced.length} step(s) belong to no phase: ${unplaced.slice(0, 3).join('; ')}${unplaced.length > 3 ? ` (+${unplaced.length - 3} more)` : ''}`,
+      'this yadflow does not recognise that step id, so it cannot say which phase it is in, which skill runs it, or what `yad next` should tell you to do. Check the spelling, or upgrade if the step comes from a newer release',
+    );
+  }
+}
+
+// ---- Build lanes set aside (E39) ----------------------------------------------------------------
+// A Build lane — one story in one repo, in `build-state/<story>.json` — may be SKIPPED WHOLE with
+// `yad skip <epic> <story> --repo <name>`, and nothing smaller: no single Build step may be set aside (the
+// user's E39 decision). The file is written by skills and by hand as well, so it is read for four faults:
+//   lane:<epic>:<story>:<repo>:contradiction   fail — skipped, yet work started in it or a ship is
+//                                              recorded. Two records say opposite things.
+//   …:no-record                                warn — skipped with no reason: a hole, not an audit trail.
+//   …:undeclared                               warn — skipped for a repo the story does not declare, so
+//                                              it owes no lane there and the skip means nothing.
+//   …:step-set-aside                           warn — one Build step `skipped` or `deferred` inside a lane.
+//                                              `buildNextForRepo` walks past a passed step, so this would
+//                                              read as done work nobody did.
+export function laneChecks(checks, root) {
+  for (const e of epicIds(root)) {
+    const epicDir = epicRoot(root, e);
+    const bsDir = path.join(epicDir, '.sdlc', 'build-state');
+    if (!exists(bsDir)) continue;
+    let names;
+    try { names = fs.readdirSync(bsDir).filter((n) => n.endsWith('.json')).sort(); } catch { continue; }
+    const stories = new Map(epicStories(epicDir).map((st) => [st.id, st]));
+    let ships = [];
+    try { ships = readShips(epicDir); } catch { /* an unreadable build-log is reported by the epic checks */ }
+    for (const n of names) {
+      const bs = readJSON(path.join(bsDir, n), null);
+      if (!isPlainObject(bs) || !isPlainObject(bs.repos)) continue;
+      const storyId = typeof bs.story === 'string' && bs.story ? bs.story : n.replace(/\.json$/, '');
+      for (const [repo, lane] of Object.entries(bs.repos)) {
+        if (!isPlainObject(lane)) continue;
+        const where = `${e}: ${storyId} / ${repo}`;
+        const id = (kind) => `lane:${e}:${storyId}:${repo}:${kind}`;
+        const steps = Array.isArray(lane.steps) ? lane.steps.filter(isPlainObject) : [];
+        if (lane.status === 'skipped') {
+          const shipped = ships.some((sh) => sh.story === storyId && sh.repo === repo);
+          const started = laneStarted(lane);   // an unknown status word counts as started (E39 review)
+          if (shipped || started) {
+            check(checks, id('contradiction'), 'epics', 'fail',
+              `${where} is skipped, but ${shipped ? 'a ship is recorded for it' : 'work has started in it'}`,
+              `decide which is true: if the lane is owed, put it back with \`yad unskip ${e} ${storyId} --repo ${repo}\`; if it really needs no change, remove the work from build-state/${n}`);
+          }
+          if (!isStepRecord(lane.record)) {
+            check(checks, id('no-record'), 'epics', 'warn', `${where} is skipped with no recorded reason`,
+              `a skip is an audit trail only with its record — put it back with \`yad unskip ${e} ${storyId} --repo ${repo}\`, then skip it again with --reason`);
+          }
+          const story = stories.get(storyId);
+          if (story && !story.repos.includes(repo)) {
+            check(checks, id('undeclared'), 'epics', 'warn', `${where} is skipped, but ${storyId} does not declare ${repo}`,
+              `the story owes no lane there, so the skip means nothing — remove the \`${repo}\` entry from build-state/${n}`);
+          }
+          continue;
+        }
+        const aside = steps.filter((st) => ['skipped', 'deferred'].includes(stepStatus(st)));
+        if (aside.length) {
+          check(checks, id('step-set-aside'), 'epics', 'warn',
+            `${where}: ${aside.map((st) => `${st.id} is ${stepStatus(st)}`).join(', ')} — no single Build step may be set aside`,
+            `a Build lane is skipped whole or not at all: \`yad skip ${e} ${storyId} --repo ${repo} --reason "<why>"\` when the story needs no change in ${repo}; otherwise set the step back to todo`);
+        }
+      }
+    }
+  }
+}
+
 export function shapeChecks(checks, root, { plan: injected = null } = {}) {
-  if (!injected && !exists(path.join(root, PROJECT_FILES.hubConfig)) && !exists(path.join(root, PROJECT_FILES.version))) return;
+  if (!injected && !exists(productConfigPath(root)) && !exists(path.join(root, PROJECT_FILES.version))) return;
   let plan = injected;
   if (!plan) {
     try {
@@ -616,6 +1813,120 @@ export function shapeChecks(checks, root, { plan: injected = null } = {}) {
   }
 }
 
+// The risk map of each connected code repo (E65): one line per directory giving it a level, no names.
+// Advisory like the PR check — a stale map warns and never fails doctor. Doctor prints no approver count:
+// the count (E66) is a fact about one change, read by the PR check, `checks/risk-route.sh` and `yad open-pr`,
+// and doctor has no change in front of it. A repo that is not on disk, or not a git repo, is the repos
+// check's to report, not this one's.
+export function riskMapChecks(checks, root) {
+  const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+  const repos = Array.isArray(registry?.repos) ? registry.repos : [];
+  for (const repo of repos) {
+    if (!repo || typeof repo.name !== 'string' || typeof repo.path !== 'string' || !repo.path) continue;
+    const repoRoot = path.resolve(root, repo.path);
+    if (!exists(repoRoot) || !gitHead(repoRoot)) continue;
+    const r = checkRepo(repoRoot);
+    if (!r.git) continue;
+    const id = `risk-map:${repo.name}`;
+    if (!r.map) {
+      check(checks, id, 'risk-map', 'ok', `${repo.name}: no ${RISK_MAP_FILE} yet — no directory has a risk level (\`yad risk-map draft ${repo.name}\` starts one)`);
+      continue;
+    }
+    if (!r.findings.length) { check(checks, id, 'risk-map', 'ok', `${repo.name}: every directory has a confirmed level`); continue; }
+    const groups = [];
+    for (const f of r.findings) {
+      let g = groups.find((x) => x.code === f.code);
+      if (!g) { g = { code: f.code, targets: [] }; groups.push(g); }
+      if (f.target) g.targets.push(f.target);
+    }
+    const said = groups.map((g) => {
+      const shown = g.targets.slice(0, 3).join(', ') + (g.targets.length > 3 ? ` +${g.targets.length - 3} more` : '');
+      return `${g.code}${shown ? ` (${shown})` : ''}`;
+    }).join('; ');
+    check(checks, id, 'risk-map', 'warn', `${repo.name}: ${RISK_MAP_FILE} is out of date — ${said}`,
+      `\`yad risk-map check ${repo.name}\` lists each one; fix the map in ${repo.name} through a PR (advisory — it blocks nothing)`,
+      { findings: r.findings });
+  }
+}
+
+// E69 — a stale CODEOWNERS, per connected repo on disk. FACTS only (a line that matches no file, a file
+// the platform never reads or will not load, a line yad cannot read): the "owner seems inactive" hint is
+// a guess, and it prints only in `yad codeowners check`, never here. Advisory — a warning, never a
+// failure: CODEOWNERS is a hint (Part 3). No file at all is a note; a repo with no review rules at all is
+// E70's to warn about. A repo not on disk, or not a git repo, is the repos check's to report.
+export function codeownersChecks(checks, root) {
+  const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+  const repos = Array.isArray(registry?.repos) ? registry.repos : [];
+  for (const repo of repos) {
+    if (!repo || typeof repo.name !== 'string' || typeof repo.path !== 'string' || !repo.path) continue;
+    const repoRoot = path.resolve(root, repo.path);
+    if (!exists(repoRoot) || !gitHead(repoRoot)) continue;
+    const r = checkCodeowners(repoRoot, { platform: repo.platform || null });
+    if (!r.git) continue;
+    const id = `codeowners:${repo.name}`;
+    const more = `\`yad codeowners check ${repo.name}\``;
+    if (r.unknown) { check(checks, id, 'codeowners', 'warn', `${repo.name}: CODEOWNERS could not be checked — ${r.unknown}`, more); continue; }
+    if (r.none) { check(checks, id, 'codeowners', 'ok', `${repo.name}: no CODEOWNERS — nothing to check`); continue; }
+    const findings = codeownersFindings(r);
+    if (!findings.length) { check(checks, id, 'codeowners', 'ok', `${repo.name}: every ${r.path} line yad can read matches a file`); continue; }
+    const lines = (code) => findings.filter((f) => f.code === code).map((f) => f.line);
+    const listed = (ns) => ns.slice(0, 3).join(', ') + (ns.length > 3 ? ` +${ns.length - 3} more` : '');
+    const said = [];
+    if (r.tooBig) said.push(`${r.path} is 3 MB or more, so GitHub does not load it`);
+    for (const p of r.ignored) said.push(`${p} is never read (${r.path} is read first)`);
+    const dead = lines('matches-nothing');
+    if (dead.length) said.push(`in ${r.path}, ${dead.length === 1 ? '1 line matches' : `${dead.length} lines match`} no file (line${dead.length === 1 ? '' : 's'} ${listed(dead)})`);
+    const unread = lines('not-read');
+    if (unread.length) said.push(`in ${r.path}, ${unread.length === 1 ? '1 line' : `${unread.length} lines`} yad could not read (line${unread.length === 1 ? '' : 's'} ${listed(unread)})`);
+    check(checks, id, 'codeowners', 'warn', `${repo.name}: CODEOWNERS may be out of date — ${said.join('; ')}`,
+      `${more} lists each one; fix it in ${repo.name} through a PR (advisory — CODEOWNERS is a hint, and yad never enforces it)`,
+      { findings });
+  }
+}
+
+// E70 — what the platform holds on the Product hub's branch and on each connected repo's: branch
+// protection, and whether a rule requires an approval before a merge (cli/protection.mjs). Never quiet
+// (rule 6): every repo gets a line, and a read that failed says "not known" and why — never "fine", never
+// "unprotected". Advisory, like E69: a warning at most, never a failure — the platform holds a merge, not
+// yad. Solo mode prints the facts as `ok` (the user's decision, 2026-09-22), except a required approval,
+// which blocks the solo developer's own merge. The branch is the one yad's files name (`default_branch`),
+// the branch gates merge into; with none, the platform's own default is read and the line says so.
+export function protectionChecks(checks, root, { runner, env } = {}) {
+  const productPath = productConfigPath(root);
+  const hub = readJSON(productPath, null);
+  const solo = isSolo(hub);
+  // One login check per host for this run, and never longer: a login can change between runs.
+  const opts = { ...(runner ? { runner } : {}), ...(env ? { env } : {}), authCache: new Map() };
+  const origin = (cwd) => run('git', ['remote', 'get-url', 'origin'], { cwd }).stdout || null;
+  const emit = (id, name, target) => {
+    const r = readProtection(target, opts);
+    const line = protectionLine(r, { name, solo });
+    check(checks, id, 'protection', line.status, line.message, line.hint || '', { protection: protectionJSON(r), alwaysHint: true });
+  };
+  if (isPlainObject(hub)) {
+    // `protection` alone, never `protection:hub`: a connected repo may be named `hub`.
+    emit('protection', 'Product hub', {
+      platform: hub.platform || null,
+      gitUrl: hub.git_url || origin(root),
+      branch: typeof hub.default_branch === 'string' && hub.default_branch ? hub.default_branch : null,
+    });
+  }
+  const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+  const repos = Array.isArray(registry?.repos) ? registry.repos : [];
+  for (const [i, repo] of repos.entries()) {
+    if (!repo || typeof repo.name !== 'string' || !repo.name) continue;
+    const repoRoot = typeof repo.path === 'string' && repo.path ? path.resolve(root, repo.path) : null;
+    const onDisk = repoRoot && exists(repoRoot) && gitHead(repoRoot);
+    // A name with an `@` is hidden in the id too; its place in repos.json keeps the id one word. Nothing
+    // validates a repo's name, so a repo literally named `#1` could take the same id — it only labels a line.
+    emit(hideAddresses(repo.name) === repo.name ? `protection:${repo.name}` : `protection:#${i + 1}`, repo.name, {
+      platform: repo.platform || null,
+      gitUrl: (typeof repo.git_url === 'string' && repo.git_url) || (onDisk ? origin(repoRoot) : null),
+      branch: typeof repo.default_branch === 'string' && repo.default_branch ? repo.default_branch : null,
+    });
+  }
+}
+
 // Phase 6 — feature-thread integrity. A change-epic must thread to a real parent and its denormalized
 // `thread` cache must equal the computed root; an open hotfix reconcile-debt is a warn (the next change
 // on that thread is blocked at the gate until it is paid). Pure reporting, like the other sections.
@@ -626,13 +1937,15 @@ export function threadChecks(checks, root) {
     if (!fs.statSync(path.join(epicsDir, e)).isDirectory() || !isValidEpicId(e)) continue;
     if (!exists(path.join(epicsDir, e, 'epic.md'))) continue;
     const lin = epicLineage(root, e);
-    if (lin.kind === 'feature' && !lin.parent) continue; // genesis with no lineage — nothing to check
+    // A genesis type with no parent has no lineage to check. `chore` joins `feature` here from
+    // shape 5 on: upkeep often has no feature to hang off (see isGenesisType).
+    if (isGenesisType(lin.type) && !lin.parent) continue;
     const { broken } = resolveThread(root, e);
     if (broken) {
       check(checks, `thread:${e}`, 'threads', 'fail', `${e}: ${broken}`,
         'a change-epic must thread to a real parent; fix `parent:`/`thread:` in epic.md frontmatter');
     } else {
-      check(checks, `thread:${e}`, 'threads', 'ok', `${e}: ${lin.kind} threaded to ${lin.thread || lin.parent}`);
+      check(checks, `thread:${e}`, 'threads', 'ok', `${e}: ${lin.type} threaded to ${lin.thread || lin.parent}`);
     }
     for (const d of loadDebt(root, e)) {
       if (d.status === 'open') {
@@ -644,35 +1957,97 @@ export function threadChecks(checks, root) {
   }
 }
 
+// E19 — is the Product index (`.sdlc/index.json`) what its work items say today? Its OWN section: the
+// golden freezes `epics` and `threads`, and this is the one line that makes the index's correctness
+// visible, since nothing else in this release reads it. A warning, never a failure: the index is derived,
+// and nothing is lost while it is behind. The hint turns on who may write it — a person on a local
+// Product, CI alone on a verified one — so each of the four answers is said both ways.
+export function indexChecks(checks, root) {
+  if (!exists(productConfigPath(root))) return;
+  const fresh = indexFreshness(root);
+  if (fresh.state === 'none') return; // no work items and no index: nothing to be behind
+  const hubNow = readJSON(productConfigPath(root), null);
+  const verified = isVerifiedLedger(hubNow);
+  const hint = verified
+    ? 'CI rebuilds it when it records the next merged review; on a verified Product a local write could not be committed'
+    : 'run `yad index` on the default branch, then commit it';
+  if (fresh.state === 'current') {
+    check(checks, 'index', 'index', 'ok', `${INDEX_FILE} is current`);
+    return;
+  }
+  // Off the default branch a difference is EXPECTED: the index is written there only, so a branch that
+  // changes a work item always differs from it until the work merges. Saying "behind — run `yad index`"
+  // here would point at the one act the rule forbids (E19 review). An unreadable file is still a finding.
+  if (fresh.state !== 'unreadable' && exists(path.join(root, '.git'))) {
+    const git = productGit(root);
+    const head = git('rev-parse', '--abbrev-ref', 'HEAD');
+    const main = resolveDefaultBranch(git, hubNow);
+    if (head.ok && head.stdout && head.stdout !== main) {
+      check(checks, 'index', 'index', 'ok', `${INDEX_FILE} ${fresh.state === 'missing' ? 'is not built yet' : 'is not what this yadflow builds from the work items on this branch'} — expected on '${head.stdout}': it is written on '${main}' only, once this work merges`);
+      return;
+    }
+  }
+  const message = fresh.state === 'missing'
+    ? `${INDEX_FILE} has not been built yet`
+    : fresh.state === 'behind'
+      // The fact the read proved, and no cause: `yad epic new`, `yad skip`, a skill that still writes
+      // state.json by hand (E17b), a branch merged in, or a yadflow that builds a different summary
+      // (`INDEX_FORMAT`, E111 review) all do it — so it never says the work items changed.
+      ? `${INDEX_FILE} is behind: it is not what this yadflow builds from the work items on disk`
+      : `${INDEX_FILE} cannot be read — ${fresh.why}`;
+  check(checks, 'index', 'index', 'warn', message, hint);
+}
+
 // Run every check section and return the diagnostic object without printing. The shared core of
 // `runDoctor`, and the same shape `--json` prints. Checks carry names and paths, so anything that
 // leaves the machine must scrub them — `yad report` does NOT consume this; it builds its own
 // allowlisted subset (cli/report.mjs `sanitizeContext`).
-export function collectDoctor(root) {
+export function collectDoctor(root, { headCount = null } = {}) {
   const checks = [];
   envChecks(checks);
-  projectChecks(checks, root);
+  projectChecks(checks, root, { headCount });
+  riskMapChecks(checks, root);
+  codeownersChecks(checks, root);
+  protectionChecks(checks, root);
+  foundationChecks(checks, root);
   shapeChecks(checks, root);
+  indexChecks(checks, root);
+  mirrorChecks(checks, root);
+  dialChecks(checks, root);
+  automationChecks(checks, root);
+  legacyModuleChecks(checks, root);
+  typeChecks(checks, root);
+  themeChecks(checks, root);
+  catalogueChecks(checks, root);
+  profileChecks(checks, root);
+  skipChecks(checks, root);
+  stepStateChecks(checks, root);
+  phaseChecks(checks, root);
+  laneChecks(checks, root);
   epicChecks(checks, root);
   threadChecks(checks, root);
   const failed = checks.filter((x) => x.status === 'fail');
   return { version: VERSION, ok: failed.length === 0, checks };
 }
 
-export async function runDoctor(root, { json = false } = {}) {
-  const { checks } = collectDoctor(root);
+export async function runDoctor(root, { json = false, headCount = null } = {}) {
+  const { checks } = collectDoctor(root, { headCount });
 
   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));
+    // `alwaysHint` tells the printer below to show a hint on an `ok` line; it is not part of the shape a
+    // script reads, so it does not travel in `--json`.
+    emitJSON({ ok: failed.length === 0, checks: checks.map((c) => { const out = { ...c }; delete out.alwaysHint; return out; }) });
   } 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);
+      // A check may ask for its hint whatever its level (`alwaysHint`): an E70 `protection` line is `ok` in
+      // solo mode even when the platform could not be read, and its hint is the fix ("run `gh auth login` …").
+      if (x.hint && (x.status !== 'ok' || x.alwaysHint)) hand(x.hint);
     }
     log('');
     if (failed.length) fail(`${failed.length} problem(s) found`);