yadflow 4.0.0-next.3 → 4.0.0

package/cli/manifest.mjs

@@ -44,7 +44,7 @@ export const SKILLS = [
   'yad-implement',
   'yad-checks',
   'yad-pr-template',
-  'yad-hub-bridge',
+  'yad-product-bridge',
   'yad-commit',
   'yad-open-pr',
   'yad-ship',
@@ -63,8 +63,11 @@ export const SKILLS = [
   'yad-stub',
 ];
 
-// Pre-2.0 skill names (the sdlc-* -> yad-* rename). `check`/`update` migrate any install
-// still carrying an old name: remove the old copy, install the renamed one.
+// Old skill names. `check`/`update` migrate any install still carrying one: remove the old copy,
+// install the renamed one. A value is one old name or a list of them — a skill renamed twice keeps
+// every name it shipped under, since an install can skip releases. Read through `legacySkillPairs`.
+//   sdlc-* -> yad-*          the 2.0 rename.
+//   yad-hub-bridge           the 4.0 hub -> Product rename (E123).
 export const LEGACY_SKILLS = {
   'yad-analysis': 'sdlc-author-analysis',
   'yad-epic': 'sdlc-author-epic',
@@ -76,7 +79,7 @@ export const LEGACY_SKILLS = {
   'yad-implement': 'sdlc-implement',
   'yad-checks': 'sdlc-checks',
   'yad-pr-template': 'sdlc-pr-template',
-  'yad-hub-bridge': 'sdlc-hub-bridge',
+  'yad-product-bridge': ['sdlc-hub-bridge', 'yad-hub-bridge'],
   // Step E ("ship") was renamed to yad-engineer-review (the yad-ship name now belongs to the new
   // commit+open-PR combined skill). Pre-2.0 installs carry sdlc-ship → migrate it to yad-engineer-review.
   // A 2.x install carrying yad-ship-as-Step-E is simply overwritten with the new combined content on
@@ -87,6 +90,9 @@ export const LEGACY_SKILLS = {
   'yad-review-gate': 'sdlc-review-gate',
   'yad-status': 'sdlc-status',
 };
+// Every (current name, old name) pair in LEGACY_SKILLS, one pair per old name.
+export const legacySkillPairs = () => Object.entries(LEGACY_SKILLS)
+  .flatMap(([skill, old]) => (Array.isArray(old) ? old : [old]).map((o) => [skill, o]));
 
 // Skills removed in a later release that must be PURGED from existing installs. Unlike
 // LEGACY_SKILLS (a rename: drop old name, install new), these have no replacement — a rerun of
@@ -96,22 +102,28 @@ export const LEGACY_SKILLS = {
 //   yad-review-comments — removed in 2.x (was sdlc-review-comments pre-2.0).
 export const REMOVED_SKILLS = ['yad-review-comments', 'sdlc-review-comments'];
 
-// Pre-2.0 wired-file dests replaced by renamed ones (old dest -> new dest, per platform).
-// An old file is removed ONLY when its first line carries the old ownership marker —
-// a same-named file the user authored themselves is never touched.
+// Wired-file dests replaced by renamed ones (old dest -> { to: new dest, marker }, per platform).
+// An old file is removed ONLY when its first line starts with that entry's ownership marker — a
+// same-named file the user authored themselves is never touched. Each entry carries its own marker
+// because each rename happened under a different one: the pre-2.0 files start `# sdlc-managed`, the
+// hub -> Product ones (E123) `# yad-managed: yad-checks` (GitHub) or `# yad-managed-include: yad-checks`
+// (GitLab). A marker is not proof nobody edited the file: `legacyFileActions` (cli/plan.mjs) also
+// asks the provenance record, as every other managed file does.
 export const LEGACY_MARKER = '# sdlc-managed';
 export const LEGACY_REPO_FILES = {
-  github: { '.github/workflows/sdlc-checks.yml': '.github/workflows/yad-checks.yml' },
-  gitlab: { '.gitlab/ci/sdlc-checks.yml': '.gitlab/ci/yad-checks.yml' },
+  github: { '.github/workflows/sdlc-checks.yml': { to: '.github/workflows/yad-checks.yml', marker: LEGACY_MARKER } },
+  gitlab: { '.gitlab/ci/sdlc-checks.yml': { to: '.gitlab/ci/yad-checks.yml', marker: LEGACY_MARKER } },
 };
 export const LEGACY_PRODUCT_FILES = {
   github: {
-    '.github/workflows/sdlc-gate-sync.yml': '.github/workflows/yad-gate-sync.yml',
-    '.github/workflows/sdlc-verified-commits.yml': '.github/workflows/yad-verified-commits.yml',
+    '.github/workflows/sdlc-gate-sync.yml': { to: '.github/workflows/yad-gate-sync.yml', marker: LEGACY_MARKER },
+    '.github/workflows/sdlc-verified-commits.yml': { to: '.github/workflows/yad-verified-commits.yml', marker: LEGACY_MARKER },
+    '.github/workflows/yad-hub-checks.yml': { to: '.github/workflows/yad-product-checks.yml', marker: '# yad-managed: yad-checks' },
   },
   gitlab: {
-    '.gitlab/ci/sdlc-gate-sync.yml': '.gitlab/ci/yad-gate-sync.yml',
-    '.gitlab/ci/sdlc-verified-commits.yml': '.gitlab/ci/yad-verified-commits.yml',
+    '.gitlab/ci/sdlc-gate-sync.yml': { to: '.gitlab/ci/yad-gate-sync.yml', marker: LEGACY_MARKER },
+    '.gitlab/ci/sdlc-verified-commits.yml': { to: '.gitlab/ci/yad-verified-commits.yml', marker: LEGACY_MARKER },
+    '.gitlab/ci/yad-hub-checks.yml': { to: '.gitlab/ci/yad-product-checks.yml', marker: '# yad-managed-include: yad-checks' },
   },
 };
 
@@ -254,7 +266,7 @@ export const PROJECT_FILES = {
   // The product's own settings. `product.json` is the name from shape 3 onward; `hub.json` is what
   // it was called before, and it is NOT dead — see MIRRORED_FILES below.
   productConfig: '.sdlc/product.json',
-  hubConfig: '.sdlc/hub.json',
+  productConfigLegacy: '.sdlc/hub.json',
   designConfig: '.sdlc/design.json',
   testingConfig: '.sdlc/testing.json',
   learningConfig: '.sdlc/learning.json',
@@ -274,60 +286,74 @@ export const PROJECT_FILES = {
 
 // ---- files that changed NAME in shape 3 --------------------------------------------------------
 //
-// `hub` became `Product`, so `.sdlc/hub.json` became `.sdlc/product.json`. A field rename is easy;
-// a FILE rename is not, because a file is opened by name from outside this codebase:
+// `hub` became `Product`, so `.sdlc/hub.json` became `.sdlc/product.json` (and each epic's
+// `hub-prs.json` became `product-prs.json`). A field rename is easy; a FILE rename is not, because a
+// file is opened by name from outside this codebase:
 //
-//   - `templates/checks/ledger-guard.sh` is committed inside the USER's repo and opens
-//     `.sdlc/hub.json` by that literal path. It is refreshed by `yad update`, which is a separate act
-//     from `yad migrate` with no ordering between them.
-//   - So a project WILL exist that has been migrated but not updated. Its guard would open a path
-//     that no longer exists, read no platform, conclude the ledger is local, and stop rejecting human
+//   - the check gates (`templates/checks/*.sh`, `checks/verified-commits.sh`) are committed inside
+//     the USER's repo, and the ones installed before E122 open `.sdlc/hub.json` by that literal
+//     path. They are refreshed by `yad update`, which is a separate act from `yad migrate`.
+//   - So a project WILL exist whose gates are older than its CLI. If only the new name existed, such
+//     a `ledger-guard` would read no platform, conclude the ledger is local, and stop rejecting human
 //     commits to it — the audit trail disarmed by an upgrade.
 //
-// Hence: for one whole major version BOTH files exist, and the OLD name is the one that is READ.
-// `product.json` is written on every save so that it is there, correct, and ready — but nothing
-// depends on it yet. `productConfigPath` picks the old name whenever it exists and falls back to the
-// new one, so a project holding either name alone still works.
+// Hence BOTH names are written on every save (`writeMirrored`, cli/lib.mjs) until v5, and the gates
+// installed from this release on read the new name first.
 //
-// Reading the new name first is the tempting version and it is wrong: the moment two names exist and
-// the new one wins, everything that writes the old one — the guard above, a script someone wrote,
-// a person editing the file they know — is silently ignored.
+// The ladder (E122, 2026-09-28). It was three majors — add, switch, delete — and is now two, because
+// 4.0.0 reached `@next` only and no ordinary user lived with the add-only stage:
+//   v3           the new name appeared beside the old one; the OLD one was read
+//   v4 (this)    the NEW name is read; the old one is still written, for the gates above;
+//                `yad doctor` says v5 deletes it
+//   v5           the old name is deleted (a shape of its own, with a `MIGRATIONS` step)
 //
-// The ladder is add, then switch, then remove:
-//   this major   the new name appears and is maintained; the old one is still read
-//   next major   the new name becomes the one read, and `yad doctor` warns about the old
-//   after that   the old name is deleted
-//
-// This costs a duplicated file on disk for two releases. That is the price of not silently disarming
-// a safety gate in somebody else's repository, and it is worth paying.
+// Two copies that DISAGREE are never settled by picking one. Whichever name won, somebody's edit —
+// a person editing the name they know, a script, an older gate's world view — would be silently
+// ignored. So every command refuses (`mirrorDrift`, checked once in bin/yad.mjs and again in
+// `loadLedger`), names both files, and points at `yad migrate`, which asks which copy wins.
 export const MIRRORED_FILES = [
-  { canonical: PROJECT_FILES.productConfig, legacy: PROJECT_FILES.hubConfig },
+  { canonical: PROJECT_FILES.productConfig, legacy: PROJECT_FILES.productConfigLegacy },
 ];
 
-// Which of the two names to READ.
-//
-// The OLD name wins while it exists, and that is deliberate. Renaming a file across an ecosystem
-// takes three releases, not one:
-//
-//   this major   the new name appears and is written on every save. The OLD name is still the one
-//                that counts, so everything that already reads it keeps working — the ledger-guard
-//                committed in the user's repo, a script somebody wrote, a person editing the file
-//                they know. Nothing can be silently ignored, because the file everyone knows is
-//                still authoritative.
-//   next major   the new name becomes authoritative and `yad doctor` warns about the old one.
-//   the one after that   the old name is deleted.
-//
-// Reading the NEW name first this early looks tidier and is a trap: the moment two names exist and
-// the new one wins, anyone who edits the old one — including our own fixtures, which is how this was
-// found — has their change silently ignored. `yad doctor` reports the two copies drifting apart, so
-// a project that gets into that state is told, rather than left to wonder.
-export const productConfigPath = (root) => {
-  const legacy = path.join(root, PROJECT_FILES.hubConfig);
-  return existsSync(legacy) ? legacy : path.join(root, PROJECT_FILES.productConfig);
+// Which of the two names to READ: the new one when it exists, the old one otherwise, and the new one
+// again when neither does (so "absent" is reported under the name people should use). A project
+// holding either name alone still works. Pure on purpose — it is a probe used by every directory
+// walk that asks "is this a Product?", so it must never throw; the refusal lives in `mirrorDrift`.
+export const preferring = (canonical, legacy) => (existsSync(canonical) || !existsSync(legacy) ? canonical : legacy);
+
+export const productConfigPath = (root) =>
+  preferring(path.join(root, PROJECT_FILES.productConfig), path.join(root, PROJECT_FILES.productConfigLegacy));
+
+// Where a person edits the Product settings, for a hint (E122): the file that is READ, and — only when
+// both names exist — the command that copies the edit over the other one. Naming product.json on a
+// Product that has only hub.json would have a person create a one-key product.json, and `--keep product`
+// would then copy it over every other setting.
+export const settingsEditHint = (root) => {
+  const rel = path.relative(root, productConfigPath(root)).split(path.sep).join('/');
+  const both = existsSync(path.join(root, PROJECT_FILES.productConfig)) && existsSync(path.join(root, PROJECT_FILES.productConfigLegacy));
+  return both ? `${rel}, then \`yad migrate --apply --keep product\`` : rel;
+};
+// The same, where no Product root is at hand.
+export const SETTINGS_EDIT_HINT = '.sdlc/product.json (.sdlc/hub.json on a Product that has only that name), then `yad migrate --apply --keep product` if both exist';
+
+// Both names present and saying different things. Byte for byte, like `yad doctor` and the gates
+// (`cmp -s`): the engine writes both from one string, so any difference at all came from outside it.
+// A copy that cannot be read counts as different — it is not the same file.
+export const mirrorDrift = (canonical, legacy) => {
+  if (!existsSync(canonical) || !existsSync(legacy)) return false;
+  try { return !readFileSync(canonical).equals(readFileSync(legacy)); } catch { return true; }
 };
 
-// Same rule for a renamed file inside an epic's ledger.
-export const preferring = (canonical, legacy) => (existsSync(legacy) ? legacy : canonical);
+// The drifted pairs under a Product root, project-relative: the settings file and every epic's PR
+// ledger. Empty when nothing disagrees. `epicDirs` is passed in (manifest.mjs lists no folders).
+export const productDrift = (root, epicDirs = []) => {
+  const pairs = [...MIRRORED_FILES];
+  for (const e of epicDirs) {
+    const f = epicFiles(e);
+    pairs.push({ canonical: f.productPrs, legacy: f.productPrsLegacy });
+  }
+  return pairs.filter(({ canonical, legacy }) => mirrorDrift(path.join(root, canonical), path.join(root, legacy)));
+};
 
 // Who writes the ledger. Two values, and the switch lives in `.sdlc/hub.json`:
 //
@@ -349,10 +375,10 @@ export const preferring = (canonical, legacy) => (existsSync(legacy) ? legacy :
 // SAME order in bash because the check gates are standalone by design; that copy is the only one,
 // its header says so, and cli/test-checks.mjs runs a table of hub.json variants through both and
 // asserts they agree on every row. Three keys is three ways for two readers to drift.
-export const isVerifiedLedger = (hub) => {
-  if (!hub?.platform) return false;
-  if (typeof hub.ledger === 'string') return hub.ledger === 'verified';
-  return hub.bridge_enabled === true || hub.bridge === true;
+export const isVerifiedLedger = (productConfig) => {
+  if (!productConfig?.platform) return false;
+  if (typeof productConfig.ledger === 'string') return productConfig.ledger === 'verified';
+  return productConfig.bridge_enabled === true || productConfig.bridge === true;
 };
 
 // ---- the two dials (E28) ------------------------------------------------------------------------
@@ -362,7 +388,8 @@ export const isVerifiedLedger = (hub) => {
 //   assistance: none | review | heavy         ->  driver:  human | pair  | agent
 //   automation: human_approve | machine_advance  ->  advance: human | auto
 //
-// Same rule as `.sdlc/hub.json` above: BOTH are written, and the OLD one wins while it exists.
+// BOTH spellings are written, and the OLD one wins while it exists. (Not the rule the renamed files
+// follow since E122 — those read the new name first. The dials keep old-first until their own switch.)
 // The old name is what the 29 skills that hand-write `state.json` still emit, and what an older CLI
 // still reads. A step whose dials disagree is a project mid-upgrade, not a decision — `yad doctor`
 // reports it and `yad migrate` closes it.
@@ -397,14 +424,19 @@ export const AI_COAUTHORS = {
 };
 // Atomic-commit guard: warn/refuse above this many staged files (build plan: ≤3 where possible).
 export const ATOMIC_FILE_LIMIT = 3;
-// Trailer order is fixed: Task -> Contract-Change -> Co-Authored-By (config.yaml build comment).
+// Trailer order is fixed: Task -> Contract-Change -> Ledger-Override -> Co-Authored-By (config.yaml build
+// comment; Ledger-Override is E49's `yad commit --manual --reason`).
 export const TASK_TRAILER = 'Task';
 export const CONTRACT_CHANGE_TRAILER = 'Contract-Change';
+// E49: `yad commit --manual --reason` records why a person committed past the ledger hook. The CI
+// `ledger-guard` check quotes it and still fails the commit — anyone can type a trailer.
+export const LEDGER_OVERRIDE_TRAILER = 'Ledger-Override';
 export const COAUTHOR_TRAILER = 'Co-Authored-By';
-// A Task trailer id must be a real <story>-T<NN>. Mirrors the spec-link gate contract
-// (checks/spec-link.sh: `.+-T[0-9]+$`) so an explicit --task that would fail CI is
-// rejected locally at commit time instead of after a push + history rewrite.
-export const TASK_ID_RE = /.+-T\d+$/;
+// A Task trailer id must be a real <story>-T<NN>, the story an `EP-<slug>-S<n>` with a lowercase slug.
+// Mirrors the spec-link gate contract (checks/spec-link.sh: `-T[0-9]+$`, then STORY_RE on the story, E117)
+// so an explicit --task that would fail CI is rejected locally at commit time instead of after a push +
+// history rewrite.
+export const TASK_ID_RE = /^EP-[a-z0-9-]+-S\d+-T\d+$/;
 
 // Per-epic ledger files under epics/<epic>/.sdlc/ (the file source of truth the gate reads/writes).
 export const epicFiles = (epicRoot) => ({
@@ -412,11 +444,11 @@ export const epicFiles = (epicRoot) => ({
   approvals: `${epicRoot}/.sdlc/approvals.json`,
   comments: `${epicRoot}/.sdlc/comments.json`,
   // The record of review PR/MRs opened on the product. `product-prs.json` is the name from shape 3
-  // onward; `hub-prs.json` is what it was called before and is written alongside it for one major —
-  // both `templates/checks/ledger-guard.sh` and `cli/hook.mjs` name it literally, and the guard in a
-  // user's repo only learns the new name when they run `yad update`. See MIRRORED_FILES.
+  // onward and the one read from v4; `hub-prs.json` is what it was called before and is still written
+  // beside it until v5 — `templates/checks/ledger-guard.sh` guards both names, and a guard in a user's
+  // repo only learns anything new when they run `yad update`. See MIRRORED_FILES.
   productPrs: `${epicRoot}/.sdlc/product-prs.json`,
-  hubPrs: `${epicRoot}/.sdlc/hub-prs.json`,
+  productPrsLegacy: `${epicRoot}/.sdlc/hub-prs.json`,
   contractLock: `${epicRoot}/.sdlc/contract-lock.json`,
   // The two append-only Build ledgers use shard-then-fold storage (cli/ledger.mjs): writers add
   // one loose shard per entry under the *Dir path (conflict-free concurrent writes); `yad tidy up`
@@ -443,6 +475,8 @@ export const REPO_WIRING = {
     { src: 'skills/yad-checks/templates/checks/lineage-check.sh', dest: 'checks/lineage-check.sh', exec: true },
     { src: 'skills/yad-checks/templates/checks/epic-open.sh', dest: 'checks/epic-open.sh', exec: true },
     { src: 'skills/yad-checks/templates/checks/reconcile-debt-check.sh', dest: 'checks/reconcile-debt-check.sh', exec: true },
+    // E120. Checks the Product out in CI where .sdlc/product-link.json says, before the four gates above read it.
+    { src: 'skills/yad-checks/templates/checks/product-checkout.sh', dest: 'checks/product-checkout.sh', exec: true },
     { src: 'skills/yad-checks/templates/checks/verified-commits.sh', dest: 'checks/verified-commits.sh', exec: true },
     { src: 'skills/yad-checks/templates/checks/commit-message.sh', dest: 'checks/commit-message.sh', exec: true },
     // E65. The CHECK is ours and wired; the map it reads (`.sdlc/risk-map`) is the team's and never is.
@@ -471,6 +505,13 @@ export const REPO_WIRING = {
 // else is a local edit, reported as `modified` and left alone (#164). Committed, so the record
 // travels with the repo instead of living in one person's clone.
 export const MANAGED_LEDGER = '.sdlc/managed.json';
+// E120. Where a connected code repo's Product lives, as a fact of the repo — `git_url`, `path` (from the
+// repo root: where CI checks the Product out) and `default_branch`. Written by `yad check --fix` /
+// `yad update` (the Product knows both sides), merged on its own, and read from the BASE by the four
+// Product-reading gates and checks/product-checkout.sh. NOT `.sdlc/product.json`: that is the Product's
+// own settings file, and a code repo holding one would be taken for a Product.
+export const PRODUCT_LINK = '.sdlc/product-link.json';
+export const PRODUCT_LINK_DEFAULT_PATH = '.yad/product';
 // Suffix for the copy written beside a managed file before its content is replaced without that
 // proof — the local edit is always recoverable from the working tree, not only from git history.
 export const BACKUP_SUFFIX = '.yad-orig';
@@ -481,31 +522,33 @@ export const wiringFor = (platform) => [
 ];
 
 // Product wiring: CI installed on the PRODUCT itself (dest is the project root — the Product IS the
-// root). Installed only when hub.json has a platform and the ledger is verified. Carries the
-// event-driven gate sync (approvals/change requests/the merge trigger `yad gate ci`) and the
-// verified-commits gate (no commit without a platform-Verified signature reaches merge on the Product).
+// root). Installed only when the Product settings (product.json, or hub.json until v5) name a
+// platform and the ledger is verified. Carries the merge-time gate sync (a review PR's merge, and a
+// 15-minute schedule that catches a merge the event missed, run `yad gate ci --merged`; nothing fires
+// on an approval) and the verified-commits gate (no commit without a platform-Verified signature
+// reaches merge on the Product).
 export const PRODUCT_WIRING = {
   common: [
     { src: 'skills/yad-checks/templates/checks/verified-commits.sh', dest: 'checks/verified-commits.sh', exec: true },
     // The ledger is CI-owned: block non-bot commits to gate-state files on the Product review PRs.
     { src: 'skills/yad-checks/templates/checks/ledger-guard.sh', dest: 'checks/ledger-guard.sh', exec: true },
-    // Pattern gates run on the Product too (profile: hub) — commit subject + PR title + PR body.
+    // Pattern gates run on the Product too (profile: product) — commit subject + PR title + PR body.
     { src: 'skills/yad-checks/templates/checks/commit-message.sh', dest: 'checks/commit-message.sh', exec: true },
     { src: 'skills/yad-pr-template/templates/checks/pr-title.sh', dest: 'checks/pr-title.sh', exec: true },
     { src: 'skills/yad-pr-template/templates/checks/pr-template.sh', dest: 'checks/pr-template.sh', exec: true },
   ],
   github: [
-    { src: 'skills/yad-hub-bridge/templates/github/yad-gate-sync.yml', dest: '.github/workflows/yad-gate-sync.yml' },
+    { src: 'skills/yad-product-bridge/templates/github/yad-gate-sync.yml', dest: '.github/workflows/yad-gate-sync.yml' },
     { src: 'skills/yad-checks/templates/github/yad-verified-commits.yml', dest: '.github/workflows/yad-verified-commits.yml' },
-    { src: 'skills/yad-checks/templates/github/yad-hub-checks.yml', dest: '.github/workflows/yad-hub-checks.yml' },
+    { src: 'skills/yad-checks/templates/github/yad-product-checks.yml', dest: '.github/workflows/yad-product-checks.yml' },
     // Integrity gate for the Product's own direct-to-default pushes (`yad update --push`; the machine-
     // state `yad checkpoint`/`gate ci` commits carry [skip ci] and are intentionally not re-checked).
     { src: 'skills/yad-checks/templates/github/yad-update-guard.yml', dest: '.github/workflows/yad-update-guard.yml' },
   ],
   gitlab: [
-    { src: 'skills/yad-hub-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml', dest: '.gitlab/ci/yad-gate-sync.yml' },
+    { src: 'skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml', dest: '.gitlab/ci/yad-gate-sync.yml' },
     { src: 'skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml', dest: '.gitlab/ci/yad-verified-commits.yml' },
-    { src: 'skills/yad-checks/templates/gitlab/yad-hub-checks.gitlab-ci.yml', dest: '.gitlab/ci/yad-hub-checks.yml' },
+    { src: 'skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml', dest: '.gitlab/ci/yad-product-checks.yml' },
     { src: 'skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml', dest: '.gitlab/ci/yad-update-guard.yml' },
   ],
 };
@@ -513,10 +556,26 @@ export const PRODUCT_WIRING = {
 // Harness hooks: the LOCAL half of the ledger rule, installed on the Product beside the CI gates and
 // active under the same verified-ledger predicate (#171). Kept out of `PRODUCT_WIRING` because a hook is not a
 // CI gate — it is advisory, fails open, and its adapter (below) is per-harness, not per-platform.
+//
+// Node scripts, not shell scripts (E113): one file runs on Windows, macOS and Linux, and a harness entry
+// runs it as `node <file>`, so no execute bit is needed — Windows cannot keep one on disk.
+// The branch-protection setup guide (E48), linked from `yad doctor`'s `protection` section. A URL, not a
+// path: the reader is in their own repo, where `docs/` is not yadflow's.
+export const PROTECTION_GUIDE_URL = 'https://github.com/abdelrahmannasr/yadflow/blob/main/docs/branch-protection.md';
+// The hub -> Product hand-change guide (E124), linked from `yad migrate`'s last line while `.sdlc/hub.json` is on
+// disk. A URL for the same reason.
+export const PRODUCT_RENAME_GUIDE_URL = 'https://github.com/abdelrahmannasr/yadflow/blob/main/docs/migrations/hub-to-product.md';
+
 export const HOOK_WIRING = [
-  { src: 'skills/yad-checks/templates/hooks/ledger-guard.sh', dest: 'hooks/ledger-guard.sh', exec: true },
+  { src: 'skills/yad-checks/templates/hooks/ledger-guard.mjs', dest: 'hooks/ledger-guard.mjs' },
 ];
 
+// The shell scripts every hook was before E113. `yad check --fix` rewrites an entry that still names one
+// (each adapter's `legacyCommands`) and then deletes the script — but only a copy the provenance record
+// proves yad wrote and nobody edited. An edited or unrecorded copy is the team's, and may be what their
+// own hand-wired hook runs, so it is left where it is.
+export const LEGACY_HOOK_SCRIPTS = Object.freeze(['hooks/ledger-guard.sh', 'hooks/ledger-guard-cursor.sh', 'hooks/yad-capture.sh']);
+
 // Per-harness adapter config: which IDE target gets a hook entry written, where, and in what shape.
 //
 // A harness qualifies for an entry here ONLY if it can run a command BEFORE a file is written and
@@ -526,10 +585,10 @@ export const HOOK_WIRING = [
 // Cursor — so "no entry here" means "not wired", never "checked and found wanting":
 //
 //   .claude   Claude Code — `PreToolUse` in `.claude/settings.json`, reading the EXIT CODE, so the
-//             entry points straight at the shared `hooks/ledger-guard.sh`.
+//             entry points straight at the shared `hooks/ledger-guard.mjs`.
 //   .cursor   Cursor — `preToolUse` in `.cursor/hooks.json`, a PERMISSION hook that reads a JSON
 //             verdict on STDOUT and treats an empty answer as a refusal. The shared script prints
-//             nothing when it allows, so this entry points at `hooks/ledger-guard-cursor.sh`
+//             nothing when it allows, so this entry points at `hooks/ledger-guard-cursor.mjs`
 //             instead (the `wiring` below), which speaks that protocol.
 //
 // Cursor's `afterFileEdit` is deliberately NOT used: it fires once the edit is already on disk, so it
@@ -554,7 +613,9 @@ export const HOOK_WIRING = [
 // guard that is off while every report says it is on.
 const CLAUDE_PROJECT_DIR_ENV = 'CLAUDE_PROJECT_DIR';
 const CURSOR_PROJECT_DIR_ENV = 'CURSOR_PROJECT_DIR';
-const guardCommand = (envVar) => `"$${envVar}/hooks/ledger-guard.sh"`;
+// `node` then the script: the harness runs the command through a shell (Git Bash on Windows for Claude
+// Code), and `node` is on PATH wherever yadflow runs at all.
+const guardCommand = (envVar) => `node "$${envVar}/hooks/ledger-guard.mjs"`;
 
 export const HOOK_ADAPTERS = Object.freeze({
   '.claude': Object.freeze({
@@ -581,7 +642,10 @@ export const HOOK_ADAPTERS = Object.freeze({
     // is ours to normalise; anything else is the team's, even if it names a similar path. Never widen
     // this to a substring test — a team keeping its own wrapper at `.claude/hooks/ledger-guard.sh`
     // would have their hook silently rewritten to ours.
-    legacyCommands: Object.freeze(['$CLAUDE_PROJECT_DIR/hooks/ledger-guard.sh']), // 3.16.x, pre-quoting
+    legacyCommands: Object.freeze([
+      '$CLAUDE_PROJECT_DIR/hooks/ledger-guard.sh',   // 3.16.x, pre-quoting
+      '"$CLAUDE_PROJECT_DIR/hooks/ledger-guard.sh"', // the bash script, before E113
+    ]),
   }),
   '.cursor': Object.freeze({
     target: '.cursor',
@@ -600,36 +664,38 @@ export const HOOK_ADAPTERS = Object.freeze({
     // Cursor's `preToolUse` is a PERMISSION hook: it answers in JSON on stdout, and empty stdout is
     // invalid JSON, which BLOCKS. So the plain guard cannot be wired here — it prints nothing when it
     // allows, which would have blocked every file write in a verified project. This wrapper, installed
-    // with the adapter below, always prints a permission answer. It takes no arguments on purpose:
-    // Cursor holds one command STRING and does not document whether it is split by a shell.
+    // with the adapter below, always prints a permission answer. The script itself takes no arguments:
+    // the entry stays a program and one path, the one form Cursor's own docs show.
     wiring: Object.freeze([
-      Object.freeze({ src: 'skills/yad-checks/templates/hooks/ledger-guard-cursor.sh', dest: 'hooks/ledger-guard-cursor.sh', exec: true }),
+      Object.freeze({ src: 'skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs', dest: 'hooks/ledger-guard-cursor.mjs' }),
     ]),
     // RELATIVE, and deliberately not `$CURSOR_PROJECT_DIR/…` — the opposite of the Claude entry above,
     // for a documented reason. Cursor's docs say a project hook RUNS FROM THE PROJECT ROOT, which is
     // the directory holding the `.cursor/hooks.json` this entry lives in, and the same directory
-    // holding `hooks/ledger-guard.sh`. So the relative path always resolves, whatever the harness's
+    // holding `hooks/ledger-guard.mjs`. So the relative path always resolves, whatever the harness's
     // notion of cwd elsewhere.
     //
-    // What they do NOT say is whether the command runs through a shell. That is exactly why there is
-    // no variable and no quotes here: `$CURSOR_PROJECT_DIR` never expanded would be a command not
-    // found, and quotes taken literally by a non-shell exec would be part of the filename. An
-    // unquoted relative path with no variable and no space is the one spelling that works either way
-    // — which matters, because every one of those failures is silent, fails OPEN, and leaves
-    // `yad doctor` truthfully reporting the entry as wired while nothing is ever refused.
+    // What they do NOT say is WHICH shell runs the command — on Windows it is PowerShell. That is why
+    // there is no variable and no quotes here: `$CURSOR_PROJECT_DIR` is not an environment variable to
+    // PowerShell, and a command that begins with a quoted path is not a command to it either. Every one
+    // of those failures is silent, fails OPEN, and leaves `yad doctor` truthfully reporting the entry
+    // as wired while nothing is ever refused.
+    //
+    // E113: `node` and a relative script. Cursor's docs call the command a "shell string" and show
+    // `python3 .cursor/hooks/x.py`, so a program and one argument is a documented form — and on Windows
+    // it is the one that runs at all: PowerShell cannot run a `.sh` file.
     projectDirEnv: CURSOR_PROJECT_DIR_ENV,
-    command: 'hooks/ledger-guard-cursor.sh',
+    command: 'node hooks/ledger-guard-cursor.mjs',
     // This harness answers with a JSON verdict and treats an empty or off-schema answer as a REFUSAL.
     // `yad doctor` uses the flag to catch a hand-wired command that would fail closed — see
     // `miswiredGuardCommand`. An adapter without it reads the exit code, where a silent command is
     // simply a guard that never fires.
     requiresJsonVerdict: true,
-    // Nothing shipped before this release, so there is no past spelling of ours to normalise.
-    legacyCommands: Object.freeze([]),
+    legacyCommands: Object.freeze(['hooks/ledger-guard-cursor.sh']), // the bash script, before E113
   }),
 });
 
-// Background capture (E43): the POST-edit half. After an agent writes a file, `hooks/yad-capture.sh` runs
+// Background capture (E43): the POST-edit half. After an agent writes a file, `hooks/yad-capture.mjs` runs
 // `yad capture --hook`, which snapshots every changed artifact onto the person's private
 // `yad/wip/<name>/<epic>` branches. Unlike the guard it is wired in BOTH ledger modes — capture is about
 // never losing a draft, which matters whoever owns the ledger — and on any Product whose config does not
@@ -637,7 +703,7 @@ export const HOOK_ADAPTERS = Object.freeze({
 // check serve both; `observe: true` marks a hook that only watches (it cannot refuse), so its entry carries
 // no `failClosed`, and a null `matcher` is an event that takes none (Cursor's `afterFileEdit`).
 export const CAPTURE_WIRING = [
-  { src: 'skills/yad-checks/templates/hooks/yad-capture.sh', dest: 'hooks/yad-capture.sh', exec: true },
+  { src: 'skills/yad-checks/templates/hooks/yad-capture.mjs', dest: 'hooks/yad-capture.mjs' },
 ];
 export const CAPTURE_ADAPTERS = Object.freeze({
   '.claude': Object.freeze({
@@ -651,10 +717,11 @@ export const CAPTURE_ADAPTERS = Object.freeze({
     matcher: 'Edit|Write|MultiEdit|NotebookEdit',
     projectDirEnv: CLAUDE_PROJECT_DIR_ENV,
     // Quoted and anchored on the project root, for the reason the guard's entry is (see above).
-    command: `"$${CLAUDE_PROJECT_DIR_ENV}/hooks/yad-capture.sh"`,
+    // `--format claude` is said here, not guessed by the script: Cursor sets `CLAUDE_PROJECT_DIR` too.
+    command: `node "$${CLAUDE_PROJECT_DIR_ENV}/hooks/yad-capture.mjs" --format claude`,
     observe: true,
     wiring: Object.freeze([]),
-    legacyCommands: Object.freeze([]),
+    legacyCommands: Object.freeze([`"$${CLAUDE_PROJECT_DIR_ENV}/hooks/yad-capture.sh"`]), // before E113
   }),
   '.cursor': Object.freeze({
     target: '.cursor',
@@ -668,10 +735,10 @@ export const CAPTURE_ADAPTERS = Object.freeze({
     matcher: null,
     projectDirEnv: CURSOR_PROJECT_DIR_ENV,
     // Relative and unquoted, for the reason the guard's Cursor entry is (see above).
-    command: 'hooks/yad-capture.sh',
+    command: 'node hooks/yad-capture.mjs',
     observe: true,
     wiring: Object.freeze([]),
-    legacyCommands: Object.freeze([]),
+    legacyCommands: Object.freeze(['hooks/yad-capture.sh']), // before E113
   }),
 });