yadflow 4.0.0-next.3 → 4.0.0

package/skills/yad-checks/templates/hooks/ledger-guard.mjs

@@ -0,0 +1,117 @@
+// ledger-guard HARNESS HOOK — the local half of the CI gate of the same name (#171).
+//
+// The gate ledger is CI-owned in verified mode: `checks/ledger-guard.sh` rejects any non-bot commit
+// that changes `epics/*/.sdlc/{state,approvals,comments,product-prs,hub-prs}.json` or `epics/*/reviews/*.md`,
+// and the same files for the Foundation in `foundation/.sdlc/` and `foundation/reviews/` (E75).
+// This hook says so at the moment an agent tries the edit, instead of twenty minutes later in a
+// failed pipeline, and names the command that owns the transition (`yad gate open`).
+//
+// This file is only the ADAPTER. It locates `yad` and hands the tool-call payload to
+// `yad hook ledger-guard`, which holds the decision. The contract it passes through:
+//
+//   stdin   the harness's tool-call payload as JSON (optional)
+//   exit 0  allow
+//   exit 2  deny, reason on stderr
+//
+// A NODE SCRIPT, NOT A SHELL SCRIPT (E113), so it runs the same on Windows, macOS and Linux. Node is
+// the one thing yadflow already needs. It imports nothing outside Node itself, because it runs from the
+// Product, where yadflow may not be installed at all.
+//
+// Wired by `yad check --fix` for every harness that can refuse a write BEFORE it lands:
+//   Claude Code  a `PreToolUse` hook in `.claude/settings.json`, pointing straight at THIS script
+//   Cursor       a `preToolUse` hook in `.cursor/hooks.json`, pointing at `ledger-guard-cursor.mjs`
+//
+// DO NOT WIRE THIS SCRIPT INTO CURSOR DIRECTLY, and check the same thing before wiring it into any
+// other harness by hand. Cursor's `preToolUse` is a PERMISSION hook: it wants a JSON verdict on
+// stdout, and treats an empty or off-schema answer as a refusal. This script prints NOTHING when it
+// allows — so wired there directly it would block every file write in the project, which is the
+// opposite of the fail-open stance below. `ledger-guard-cursor.mjs` exists to speak that protocol.
+//
+// A harness that reads the EXIT CODE can use this script as it stands: `node <product>/hooks/ledger-guard.mjs`.
+//
+// FAIL-OPEN: if no `yad` can be found, this ALLOWS and says why on stderr. A guardrail that blocked
+// every edit the moment an install went sideways would be worse than the problem. The CI gate fails
+// CLOSED and is what actually protects the ledger.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// ---- yad-resolve (the same block in every hooks/*.mjs; a test keeps the copies identical) ----------
+// The Product root is this script's grandparent — `<product>/hooks/<script>.mjs` — found from the
+// script's OWN location, never from the harness's working directory or its project-root variable
+// (whose form on Windows, `C:\…` or `/c/…`, no harness documents). `realpathSync` so a script reached
+// through a symbolic link still finds its own Product.
+const PRODUCT_ROOT = path.dirname(path.dirname(fs.realpathSync(fileURLToPath(import.meta.url))));
+const IS_WINDOWS = process.platform === 'win32';
+
+// A command found on PATH, or null. On Windows the npm launchers are `.cmd` files.
+function onPath(name) {
+  const exts = IS_WINDOWS ? ['.cmd', '.exe', ''] : [''];
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const full = path.join(dir, name + ext);
+      try { if (fs.statSync(full).isFile()) return full; } catch { /* not here */ }
+    }
+  }
+  return null;
+}
+
+// Windows cannot start a `.cmd` launcher without a shell (Node refuses since 18.20.2), so those run
+// through one, each word in double quotes. A Windows path cannot hold a `"`, so the quoting is whole.
+const quoteForCmd = (word) => `"${String(word).replace(/"/g, '')}"`;
+
+// How to run `yad`, cheapest and most specific first: an explicit override, then the copy installed in
+// this Product, then `yad` on PATH, then a network-free npx. `--no-install` matters — a hook runs on
+// every tool call and must never pause an agent to download a package. Returns
+// `{ file, args, shell }` or null.
+function resolveYad() {
+  // YAD_BIN is commonly an interpreter plus a script ("node /path/to/yad.mjs"). Split on spaces, with a
+  // double-quoted word kept whole — Node on Windows usually lives under `C:\Program Files\`.
+  const override = [...(process.env.YAD_BIN || '').matchAll(/"([^"]*)"|(\S+)/g)].map((m) => m[1] ?? m[2]).filter(Boolean);
+  if (override.length) {
+    const [file, ...args] = override;
+    return { file, args, shell: IS_WINDOWS && /\.(cmd|bat)$/i.test(file) };
+  }
+  const local = path.join(PRODUCT_ROOT, 'node_modules', 'yadflow', 'bin', 'yad.mjs');
+  if (fs.existsSync(local)) return { file: process.execPath, args: [local], shell: false };
+  const yad = onPath('yad');
+  if (yad) {
+    if (!IS_WINDOWS || !/\.(cmd|bat)$/i.test(yad)) return { file: yad, args: [], shell: false };
+    // An npm global install puts the package beside its launcher: run the script with this Node
+    // rather than through a shell whenever it is there.
+    const script = path.join(path.dirname(yad), 'node_modules', 'yadflow', 'bin', 'yad.mjs');
+    if (fs.existsSync(script)) return { file: process.execPath, args: [script], shell: false };
+    return { file: yad, args: [], shell: true };
+  }
+  const npx = onPath('npx');
+  if (npx) return { file: npx, args: ['--no-install', 'yadflow'], shell: IS_WINDOWS && /\.(cmd|bat)$/i.test(npx) };
+  return null;
+}
+
+// Run the resolved `yad` with `args` appended. `options` go to spawnSync.
+function runYad(yad, args, options) {
+  const all = [...yad.args, ...args];
+  if (yad.shell) return spawnSync([yad.file, ...all].map(quoteForCmd).join(' '), { ...options, shell: true, windowsHide: true });
+  return spawnSync(yad.file, all, { ...options, windowsHide: true });
+}
+// ---- end yad-resolve ---------------------------------------------------------------------------------
+
+const yad = resolveYad();
+if (!yad) {
+  process.stderr.write(`  • yad hook: no \`yad\` on PATH and none installed in ${PRODUCT_ROOT} — allowing (install yadflow to re-arm the ledger guard)\n`);
+  process.exit(0);
+}
+
+// Run it rather than hand the process over, so the exit code can be mapped. ONLY an explicit deny (2)
+// blocks: a `yad` that is present but cannot run — an `npx --no-install` with no yadflow to find, a
+// crash, a broken install — must not read as a refusal. Fail-open is the whole stance of this hook;
+// the CI gate is what fails closed. stdin, stdout and stderr are all the harness's own.
+const r = runYad(yad, ['hook', 'ledger-guard', ...process.argv.slice(2)], { stdio: 'inherit' });
+if (r.status === 2) process.exit(2);
+if (r.status !== 0) {
+  const why = r.error ? r.error.message : `exited ${r.status ?? r.signal}`;
+  process.stderr.write(`  • yad hook: \`yad hook ledger-guard\` ${why} — allowing (run \`yad doctor\` to check the install)\n`);
+}
+process.exit(0);

package/skills/yad-checks/templates/hooks/yad-capture.mjs

@@ -0,0 +1,117 @@
+// yad-capture HARNESS HOOK — background capture of Shape artifacts (E43).
+//
+// Runs AFTER an agent edits a file, and snapshots every changed artifact of the Product onto the
+// person's private `yad/wip/<name>/<epic>` branches — built with git plumbing, so the checkout, the
+// index and the current branch are never touched. The push runs in the background, at most once
+// every few minutes. The decision lives in `yad capture --hook`; this file only locates `yad`.
+//
+// Wired by `yad check --fix`, in BOTH ledger modes:
+//   Claude Code  a `PostToolUse` hook in `.claude/settings.json`:  node "$CLAUDE_PROJECT_DIR/hooks/yad-capture.mjs" --format claude
+//   Cursor       an `afterFileEdit` hook in `.cursor/hooks.json`:  node hooks/yad-capture.mjs
+// Any other harness: run `node <product>/hooks/yad-capture.mjs` (or `yad capture --hook`) after a file write.
+//
+// A NODE SCRIPT, NOT A SHELL SCRIPT (E113), so it runs the same on Windows, macOS and Linux.
+//
+// The contract: it ALWAYS exits 0 — a capture must never block or slow an agent. A problem is one line on
+// stderr. Stdout carries ONE thing, and only with `--format claude`: when a file this edit changed is also
+// being edited by someone else (E46 claims), a PostToolUse JSON note the agent reads. Otherwise it prints
+// nothing. The format is passed by the entry and never guessed from the environment: Cursor sets
+// `CLAUDE_PROJECT_DIR` too, as an alias. `YAD_CAPTURE=0`, or `"capture": false` in the Product config,
+// turns it off.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// ---- yad-resolve (the same block in every hooks/*.mjs; a test keeps the copies identical) ----------
+// The Product root is this script's grandparent — `<product>/hooks/<script>.mjs` — found from the
+// script's OWN location, never from the harness's working directory or its project-root variable
+// (whose form on Windows, `C:\…` or `/c/…`, no harness documents). `realpathSync` so a script reached
+// through a symbolic link still finds its own Product.
+const PRODUCT_ROOT = path.dirname(path.dirname(fs.realpathSync(fileURLToPath(import.meta.url))));
+const IS_WINDOWS = process.platform === 'win32';
+
+// A command found on PATH, or null. On Windows the npm launchers are `.cmd` files.
+function onPath(name) {
+  const exts = IS_WINDOWS ? ['.cmd', '.exe', ''] : [''];
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const full = path.join(dir, name + ext);
+      try { if (fs.statSync(full).isFile()) return full; } catch { /* not here */ }
+    }
+  }
+  return null;
+}
+
+// Windows cannot start a `.cmd` launcher without a shell (Node refuses since 18.20.2), so those run
+// through one, each word in double quotes. A Windows path cannot hold a `"`, so the quoting is whole.
+const quoteForCmd = (word) => `"${String(word).replace(/"/g, '')}"`;
+
+// How to run `yad`, cheapest and most specific first: an explicit override, then the copy installed in
+// this Product, then `yad` on PATH, then a network-free npx. `--no-install` matters — a hook runs on
+// every tool call and must never pause an agent to download a package. Returns
+// `{ file, args, shell }` or null.
+function resolveYad() {
+  // YAD_BIN is commonly an interpreter plus a script ("node /path/to/yad.mjs"). Split on spaces, with a
+  // double-quoted word kept whole — Node on Windows usually lives under `C:\Program Files\`.
+  const override = [...(process.env.YAD_BIN || '').matchAll(/"([^"]*)"|(\S+)/g)].map((m) => m[1] ?? m[2]).filter(Boolean);
+  if (override.length) {
+    const [file, ...args] = override;
+    return { file, args, shell: IS_WINDOWS && /\.(cmd|bat)$/i.test(file) };
+  }
+  const local = path.join(PRODUCT_ROOT, 'node_modules', 'yadflow', 'bin', 'yad.mjs');
+  if (fs.existsSync(local)) return { file: process.execPath, args: [local], shell: false };
+  const yad = onPath('yad');
+  if (yad) {
+    if (!IS_WINDOWS || !/\.(cmd|bat)$/i.test(yad)) return { file: yad, args: [], shell: false };
+    // An npm global install puts the package beside its launcher: run the script with this Node
+    // rather than through a shell whenever it is there.
+    const script = path.join(path.dirname(yad), 'node_modules', 'yadflow', 'bin', 'yad.mjs');
+    if (fs.existsSync(script)) return { file: process.execPath, args: [script], shell: false };
+    return { file: yad, args: [], shell: true };
+  }
+  const npx = onPath('npx');
+  if (npx) return { file: npx, args: ['--no-install', 'yadflow'], shell: IS_WINDOWS && /\.(cmd|bat)$/i.test(npx) };
+  return null;
+}
+
+// Run the resolved `yad` with `args` appended. `options` go to spawnSync.
+function runYad(yad, args, options) {
+  const all = [...yad.args, ...args];
+  if (yad.shell) return spawnSync([yad.file, ...all].map(quoteForCmd).join(' '), { ...options, shell: true, windowsHide: true });
+  return spawnSync(yad.file, all, { ...options, windowsHide: true });
+}
+// ---- end yad-resolve ---------------------------------------------------------------------------------
+
+// Drain the payload the harness sends on stdin, so it never sees a broken pipe — but never wait on it: not
+// at all from a terminal (someone ran this by hand), and at most a second on a pipe that never closes.
+function drainStdin() {
+  if (process.stdin.isTTY) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => { clearTimeout(timer); process.stdin.pause(); resolve(); };
+    const timer = setTimeout(done, 1000);
+    process.stdin.on('data', () => {});
+    process.stdin.on('end', done);
+    process.stdin.on('error', done);
+    process.stdin.resume();
+  });
+}
+
+async function main() {
+  await drainStdin();
+  if (process.env.YAD_CAPTURE === '0') return;
+  const yad = resolveYad();
+  if (!yad) {
+    process.stderr.write(`  • yad capture: no \`yad\` on PATH and none installed in ${PRODUCT_ROOT} — nothing captured\n`);
+    return;
+  }
+  // Only `--format claude` is passed through; anything else on the command line is not ours to forward.
+  const argv = process.argv.slice(2);
+  const i = argv.indexOf('--format');
+  const format = i >= 0 && argv[i + 1] === 'claude' ? ['--format', 'claude'] : [];
+  // stdin is closed for the child: the payload was drained above and capture reads none.
+  runYad(yad, ['capture', '--hook', ...format, '--dir', PRODUCT_ROOT], { stdio: ['ignore', 'inherit', 'inherit'] });
+}
+
+main().catch((e) => { process.stderr.write(`  • yad capture: ${e?.message || e}\n`); }).finally(() => process.exit(0));

package/skills/yad-commit/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: yad-commit
-description: 'Build helper of the gated SDLC. Commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer order (Task → Contract-Change, plus an OPTIONAL Co-Authored-By), and an atomic-file guard (≤3 files). By default the commit carries NO AI footer: the human git author owns it, and a Co-Authored-By trailer is added ONLY when --ai <id> is explicitly passed (claude|copilot|cursor|coderabbit; default none = human-only). The flag is the sole switch — never add the footer on the AI''s own initiative. Drives the zero-dependency `yad commit` CLI; never auto-advances. Use when the user says "commit this", "commit by convention", or "make an atomic commit".'
+description: 'Build helper of the gated SDLC. Commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer order (Task → Contract-Change → Ledger-Override, plus an OPTIONAL Co-Authored-By), and an atomic-file guard (≤3 files). By default the commit carries NO AI footer: the human git author owns it, and a Co-Authored-By trailer is added ONLY when --ai <id> is explicitly passed (claude|copilot|cursor|coderabbit; default none = human-only). The flag is the sole switch — never add the footer on the AI''s own initiative. Drives the zero-dependency `yad commit` CLI; never auto-advances. Use when the user says "commit this", "commit by convention", or "make an atomic commit".'
 ---
 
 # SDLC — Commit by Convention (Build helper)
 
 **Goal:** Turn ONE staged atomic change into a single commit that satisfies the project conventions
 (`CONTRIBUTING.md` / `config.yaml` `build`): a Conventional-Commits subject, the fixed trailer order
-`Task → Contract-Change → Co-Authored-By` (the footer **off by default** — added only via an explicit
-`--ai`), and the atomic-file guard. This is the standalone commit step — the same engine `yad-implement`
+`Task → Contract-Change → Ledger-Override → Co-Authored-By` (the override only with `--manual`; the footer
+**off by default** — added only via an explicit `--ai`), and the atomic-file guard. This is the standalone commit step — the same engine `yad-implement`
 and `yad-ship` use. It **never auto-advances**; it just commits.
 
 ## Conventions
@@ -20,8 +20,9 @@ and `yad-ship` use. It **never auto-advances**; it just commits.
 - **Subject** — `<type>: <lowercase imperative description, no trailing period>`; types are
   `feat|fix|docs|refactor|test|perf|build|ci|chore|revert`; proper nouns/acronyms keep their case.
 - **Task trailer** — required on a code repo (anchors the `spec-link` + `commit-message` gates). Given
-  with `--task` (a `<story>-T<NN>` id — an explicit value is validated against the `spec-link`
-  contract, so a malformed id like a bare `EP-x-S01` fails locally instead of after a push), else
+  with `--task` (a `<story>-T<NN>` id, the story an `EP-<slug>-S<n>` with a lowercase slug — an explicit
+  value is validated against the `spec-link` contract, so a malformed id like a bare `EP-x-S01` or an
+  `EP-Demo-S01-T01` fails locally instead of after a push), else
   derived from the branch (`feat/<story>-<task>-…`). Product commits are not
   task-scoped, so the trailer is optional there — a missing-Task warning is informational on the Product
   (`spec-link` is a code-repo gate) and only flags a real gate failure in a code repo.
@@ -40,6 +41,12 @@ and `yad-ship` use. It **never auto-advances**; it just commits.
   the `Co-Authored-By` trailer appears only when this flag names a tool).
 - `task`    — Task trailer (optional; derived from the branch when omitted).
 - `contractChange` — flag; mark the contract surface touched.
+- `manual` + `reason` — the ledger override (E49), for a PERSON only. On a verified Product a local
+  pre-commit hook refuses a commit that changes a CI-owned file (the gate ledger, the Product index).
+  `--manual --reason "<why>"` commits past that hook and records the reason as a `Ledger-Override:`
+  trailer. It is refused when nothing staged is a file that hook refuses. The `ledger-guard` check on
+  the pull request still fails the commit, and quotes the reason. A reason that starts with `-` is
+  passed as `--reason=-…`.
 
 ## On Activation
 
@@ -50,7 +57,7 @@ staged, split it into separate commits rather than passing `--force`.
 ### Step 2 — Commit by convention
 Run the CLI from the repo root:
 ```
-yad commit --type <type> -m "<subject>" [--ai <id>] [--task <id>] [--contract-change] [--dry-run]
+yad commit --type <type> -m "<subject>" [--ai <id>] [--task <id>] [--contract-change] [--manual --reason "<why>"] [--dry-run]
 ```
 Use `--dry-run` first to preview the exact message (subject + trailer block) without committing. The
 CLI validates the type, rejects a trailing period, and emits the trailers in the fixed order.
@@ -65,8 +72,12 @@ the architecture gate. To also open the PR/MR in the same step, use `yad-ship`.
 - **No AI footer by default.** A `Co-Authored-By` trailer is written ONLY when `--ai <id>` is explicitly
   passed; the default is a clean human-only commit. Never add it on your own initiative.
 - **The human author owns the commit.** The AI is at most a `Co-Authored-By` footer, never the author.
-- **Trailer order is fixed:** `Task → Contract-Change → Co-Authored-By` (the footer only when `--ai` is given).
+- **Trailer order is fixed:** `Task → Contract-Change → Ledger-Override → Co-Authored-By` (the override only
+  with `--manual`, the footer only when `--ai` is given).
 - **Never widen the contract here.** A contract touch is flagged (`--contract-change`), not hidden.
+- **Never pass `--manual` on your own initiative.** Committing past the ledger hook is a person's decision.
+  Pass it only when the user asked for it, with the reason they gave. `--manual` needs `--reason`, and the
+  reason must be one line.
 
 ## Reference
 - Branch/commit conventions + the file-boundary rule: `../yad-implement/references/implement-conventions.md`.

package/skills/yad-connect-design/SKILL.md

@@ -26,7 +26,7 @@ markdown-only exactly as before.
   shape as Impeccable's slash-commands, not Repomix's `npx`. The skill detects the MCP and degrades when
   it is absent; it never installs an MCP server.
 - Registry: `{project-root}/.sdlc/design.json` (project-wide, shared across all epics — NOT per-epic),
-  the sibling of `.sdlc/repos.json` and `.sdlc/hub.json`.
+  the sibling of `.sdlc/repos.json` and `.sdlc/product.json`.
 - Per-epic screen→frame links are written later by `yad-ui` (`epics/EP-<slug>/.sdlc/design-links.json`),
   not here.
 - Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.

package/skills/yad-connect-design/references/design-registry.md

@@ -47,7 +47,7 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
 ## Git tracking
 
 Commit the **registry** (`design.json`) — it is small, reviewable, and holds no secrets (references
-only). This mirrors how `repos.json` and `hub.json` are committed.
+only). This mirrors how `repos.json` and `product.json` are committed.
 
 ## Greenfield
 

package/skills/yad-connect-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-connect-docs
-description: 'Connects a docs/Pages publishing target to the Product so the interactive-docs steps can build and deploy the generated SPA — not just commit its source. Registers the target into the project-wide .sdlc/docs.json (GitHub Pages / GitLab Pages / build-only), auto-detecting the platform from .sdlc/hub.json and resolving the Vite base path, with local-user auth and no stored tokens. Detects whether gh/glab is present and degrades to build-only when absent. Run at setup or any time the publish target changes. Reusable, idempotent, refreshable. Use when the user says "connect docs", "connect Pages", "refresh the docs connection", or "list the docs connection".'
+description: 'Connects a docs/Pages publishing target to the Product so the interactive-docs steps can build and deploy the generated SPA — not just commit its source. Registers the target into the project-wide .sdlc/docs.json (GitHub Pages / GitLab Pages / build-only), auto-detecting the platform from .sdlc/product.json and resolving the Vite base path, with local-user auth and no stored tokens. Detects whether gh/glab is present and degrades to build-only when absent. Run at setup or any time the publish target changes. Reusable, idempotent, refreshable. Use when the user says "connect docs", "connect Pages", "refresh the docs connection", or "list the docs connection".'
 ---
 
 # SDLC — Connect a Docs/Pages Target (make the docs steps publishable)
@@ -26,7 +26,7 @@ at a local `dist/` — build-only, no publish, exactly as before.
   never installed by this skill, never given a token. Absent ⇒ degrade to build-only (`source:
   "unavailable"`).
 - Registry: `{project-root}/.sdlc/docs.json` (project-wide, shared across all epics + the overview —
-  NOT per-epic), the sibling of `.sdlc/hub.json`, `.sdlc/repos.json`, and `.sdlc/design.json`.
+  NOT per-epic), the sibling of `.sdlc/product.json`, `.sdlc/repos.json`, and `.sdlc/design.json`.
 - Per-epic / overview build manifests (`docs-build.json`) are written later by `yad-docs` /
   `yad-docs-overview`, not here. This skill describes the *connection*; it does not build.
 - Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.
@@ -34,17 +34,21 @@ at a local `dist/` — build-only, no publish, exactly as before.
 ## Inputs
 
 - `action` — `connect` (default) | `refresh` | `list` | `disconnect`.
-- `target` — `github-pages` | `gitlab-pages` | `none`. Default **auto-detected** from `.sdlc/hub.json`
+- `target` — `github-pages` | `gitlab-pages` | `none`. Default **auto-detected** from `.sdlc/product.json`
   `platform` (github → `github-pages`, gitlab → `gitlab-pages`, null/no Product → `none`).
-- `scope` — `hub` (default) | `<repo-name>` | `dedicated`. Where the Pages site is published from (the
-  Product repo, one connected code repo, or a dedicated docs repo).
+- `scope` — `product` (default) | `<repo-name>` | `dedicated`. Where the Pages site is published from (the
+  Product repo, one connected code repo, or a dedicated docs repo). `hub` is the old name for `product`:
+  a `docs.json` written before 4.0 says `"scope": "hub"`, and it means the same thing — read it as
+  `product`, and write `product` the next time you write the file. A connected code repo that is itself named
+  `product` is recorded by its registry `path` (for example `repos/product`), never its name, so it is not read
+  as the Product.
 - `public` — `true` (default) | `false`. Whether the published site is public.
 - `base_path` — optional explicit override of the Vite `base` (otherwise resolved, Step 2).
 
 ## On Activation
 
 ### Step 1 — Resolve the target + detect the platform (the publish adapter)
-Determine the `target`. If not given, read `{project-root}/.sdlc/hub.json` `platform` and map it the same
+Determine the `target`. If not given, read `{project-root}/.sdlc/product.json` (`.sdlc/hub.json` on an older Product that has only that name) `platform` and map it the same
 way the Product bridge maps repos: `github` → `github-pages`, `gitlab` → `gitlab-pages`, `null`/no Product →
 `none` (deliberate build-only). Reject a `target` value outside the three providers (fall back to the
 detected default with a warning, the way `registerRepo` falls back on an unknown platform).
@@ -61,8 +65,9 @@ tokens**; everything in the registry is a plain reference. Do **not** install a
 
 ### Step 2 — Decide the publish scope + resolve the base path
 Resolve `scope` → `publishRepo`:
-- `hub` (default) → publish from the Product repo (read its name from `hub.json` `git_url`).
-- `<repo-name>` → publish from that connected code repo (must exist in `.sdlc/repos.json`).
+- `product` (default; `hub` in an older `docs.json`) → publish from the Product repo (read its name from `product.json` `git_url`).
+- `<repo-name>` → publish from that connected code repo (must exist in `.sdlc/repos.json`). A value with a `/` in
+  it is that repo's registry `path` (the form a repo named `product` is recorded in).
 - `dedicated` → a dedicated docs repo the user names (recorded as `publishRepo`).
 
 Resolve `basePath` (the Vite `base`) per the table in `references/docs-registry.md`:
@@ -78,8 +83,8 @@ Upsert into `{project-root}/.sdlc/docs.json` (create the file + parent `.sdlc/`
 ```json
 {
   "target": "github-pages",
-  "scope": "hub",
-  "publishRepo": "<repo or hub name>",
+  "scope": "product",
+  "publishRepo": "<repo or Product name>",
   "basePath": "/<repo>/",
   "public": true,
   "auth": "user",
@@ -89,7 +94,7 @@ Upsert into `{project-root}/.sdlc/docs.json` (create the file + parent `.sdlc/`
 }
 ```
 
-- `target: "none"` records a deliberate build-only project: `{ "target": "none", "scope": "hub",
+- `target: "none"` records a deliberate build-only project: `{ "target": "none", "scope": "product",
   "publishRepo": null, "basePath": "/", "source": "unavailable", ... }`.
 - `connect` is **idempotent** — re-running it overwrites the single connection in place (a project has
   one docs target at a time; switching targets is just another `connect`).

package/skills/yad-connect-docs/references/docs-registry.md

@@ -1,7 +1,7 @@
 # `.sdlc/docs.json` — the docs/Pages registry
 
 Project-wide, shared across every epic's docs site **and** the project overview site (NOT per-epic).
-The sibling of `.sdlc/hub.json`, `.sdlc/repos.json`, and `.sdlc/design.json`. Written by
+The sibling of `.sdlc/product.json`, `.sdlc/repos.json`, and `.sdlc/design.json`. Written by
 `yad-connect-docs`; read by `yad-docs`, `yad-docs-overview`, `yad-docs-sync`, and the `yad docs` CLI.
 Holds **no credentials** — every field is a plain reference. Auth is always the local user's own
 `gh`/`glab`/git session.
@@ -11,8 +11,8 @@ Holds **no credentials** — every field is a plain reference. Auth is always th
 ```json
 {
   "target": "github-pages | gitlab-pages | none",
-  "scope": "hub | <repo-name> | dedicated",
-  "publishRepo": "<repo or hub name>",
+  "scope": "product | <repo-name> | dedicated",
+  "publishRepo": "<repo or Product name>",
   "basePath": "/<repo>/",
   "public": true,
   "auth": "user",
@@ -25,7 +25,7 @@ Holds **no credentials** — every field is a plain reference. Auth is always th
 | Field | Meaning |
 |-------|---------|
 | `target` | The publish adapter. `none` = deliberate build-only (no publish, no error). |
-| `scope` | Where the Pages site publishes from: the `hub` repo, one connected `<repo-name>`, or a `dedicated` docs repo. |
+| `scope` | Where the Pages site publishes from: the `product` repo, one connected `<repo-name>`, or a `dedicated` docs repo. A file written before 4.0 says `hub`, the old name for `product`; read it the same way. A code repo that is itself named `product` is recorded by its registry `path` (for example `repos/product`), so it is not read as the Product. |
 | `publishRepo` | The concrete repo name resolved from `scope`. `null` when `target: "none"`. |
 | `basePath` | The Vite `base` substituted into each generated site (resolution table below). Normalized to a leading + trailing `/`. |
 | `public` | Whether the published site is public. |
@@ -36,15 +36,15 @@ Holds **no credentials** — every field is a plain reference. Auth is always th
 `target: "none"` records `{ "target": "none", "publishRepo": null, "basePath": "/", "source":
 "unavailable", ... }`.
 
-## Platform auto-detection (from `.sdlc/hub.json`)
+## Platform auto-detection (from `.sdlc/product.json`)
 
-When `target` is not given, map the Product's `platform` the same way `yad-connect-repos` maps a repo host:
+When `target` is not given, read `.sdlc/product.json` (`.sdlc/hub.json` on an older Product that has only that name) and map the Product's `platform` the same way `yad-connect-repos` maps a repo host:
 
-| `hub.json` `platform` | default `target` |
+| `product.json` `platform` | default `target` |
 |-----------------------|------------------|
 | `github` | `github-pages` |
 | `gitlab` | `gitlab-pages` |
-| `null` / no hub.json | `none` (build-only) |
+| `null` / no settings file | `none` (build-only) |
 
 ## Base-path resolution table
 

package/skills/yad-connect-learning/SKILL.md

@@ -27,7 +27,7 @@ explains the concept. The learning layer is **purely opt-in and never blocks a g
   an MCP like the design/testing tools (DeepTutor ships no MCP server). The skill detects the **binary on
   PATH** and degrades when it is absent; it never installs DeepTutor.
 - Registry: `{project-root}/.sdlc/learning.json` (project-wide, shared across all epics — NOT per-epic),
-  the sibling of `.sdlc/repos.json`, `.sdlc/hub.json`, `.sdlc/design.json`, and `.sdlc/testing.json`.
+  the sibling of `.sdlc/repos.json`, `.sdlc/product.json`, `.sdlc/design.json`, and `.sdlc/testing.json`.
 - Per-epic, per-member learning records + rendered tutorials are written later by `yad-learn`
   (`epics/EP-<slug>/.sdlc/learning-records.json` and `epics/EP-<slug>/learning/`), not here.
 - Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.

package/skills/yad-connect-learning/references/learning-registry.md

@@ -51,7 +51,7 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
 ## Git tracking
 
 Commit the **registry** (`learning.json`) — it is small, reviewable, and holds no secrets (references
-only). This mirrors how `repos.json`, `hub.json`, `design.json`, and `testing.json` are committed.
+only). This mirrors how `repos.json`, `product.json`, `design.json`, and `testing.json` are committed.
 
 ## Greenfield
 

package/skills/yad-connect-repos/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-connect-repos
-description: 'Connects code repos to the Product so the front/"brain" phases are code-aware. Registers N code repos (GitHub or GitLab, local-user auth, no stored tokens) into the project-wide .sdlc/repos.json, then caches an AI-readable picture of each — a compressed Repomix pack and a lightweight code-map (existing endpoints/events/data-models/modules), secret-scanned. Run at one-time setup or any time a new repo is added. Reusable, idempotent, refreshable; staleness is tracked by HEAD sha. `yad repo refresh --push` publishes the refreshed code-maps + registry to the Product default branch as a chore(hub): sync code-context [skip ci] audit commit. Also drafts each code repo's risk map (.sdlc/risk-map — a level per directory, no names), classified by reading the code and marked guessed for a person to confirm. Use when the user says "connect a repo", "connect the code repos", "refresh the code context", "list connected repos", or "push the code-map refresh".'
+description: 'Connects code repos to the Product so the front/"brain" phases are code-aware. Registers N code repos (GitHub or GitLab, local-user auth, no stored tokens) into the project-wide .sdlc/repos.json, then caches an AI-readable picture of each — a compressed Repomix pack and a lightweight code-map (existing endpoints/events/data-models/modules), secret-scanned. Run at one-time setup or any time a new repo is added. Reusable, idempotent, refreshable; staleness is tracked by HEAD sha. `yad repo refresh --push` publishes the refreshed code-maps + registry to the Product default branch as a chore(product): sync code-context [skip ci] audit commit. Also drafts each code repo''s risk map (.sdlc/risk-map — a level per directory, no names), classified by reading the code and marked guessed for a person to confirm. Use when the user says "connect a repo", "connect the code repos", "refresh the code context", "list connected repos", or "push the code-map refresh".'
 ---
 
 # SDLC — Connect Code Repos (make the brain code-aware)
@@ -28,7 +28,7 @@ repo itself — a draft of that repo's risk map (Step 3b), which the team commit
 
 ## Inputs
 
-- `action` — `connect` | `refresh` | `list` | `disconnect` | `detect-hub` (default `connect`).
+- `action` — `connect` | `refresh` | `list` | `disconnect` | `detect-product` (default `connect`; `detect-hub`, the old name, still works).
 - `repo` — the repo's short name (the key used in stories' `repos:` tag, e.g. `backend`).
 - `path` — local path to the code repo (relative to `{project-root}` or absolute). For local repos.
   It must resolve inside the **workspace** — the project root's parent — so the standard layout, where
@@ -50,6 +50,9 @@ repo itself — a draft of that repo's risk map (Step 3b), which the team commit
   directly in `$HOME` — with the Product at `~/product` the workspace becomes `~` and every home-dir
   sibling turns into a registrable repo. The workspace directory itself (`..`) is never registrable.
 - `git_url` — optional remote (SSH or HTTPS; GitHub or GitLab). Used when the repo is not yet on disk.
+  `yad join` and `yad repo clone` clone only a network address (`https://`, `http://`, `ssh://`,
+  `git://`, `user@host:path`, or an ssh alias `host:path`); a local path is refused unless
+  `YAD_ALLOW_LOCAL_REMOTES=1` is set, and then only a folder that exists outside the workspace.
 
 yadflow keeps **no list of people** (E62): no roster, no roles, no repo owners, no commit emails. Do not
 ask for them and do not write them.
@@ -59,7 +62,13 @@ ask for them and do not write them.
 ### Step 1 — Resolve the repo and its auth (GitHub + GitLab, local user)
 Determine where the code is:
 - If `path` is given and is a git repo (`.git` present) → use it in place.
-- Else if `git_url` is given → **clone it as the local user** into a working location
+- A teammate joining an existing Product gets every registered repo cloned at its recorded `path` by
+  `yad join <url>` (E79) — no need to clone them one by one here.
+- A repo that is **already registered** but missing on this machine (a teammate registered it after you
+  joined) → run **`yad repo clone [<name>]`** (E81). It clones at the recorded `path`, with the same
+  checks as `join`, and never touches a repo that is already there. `yad repo list` and `yad doctor`
+  name such a repo as not cloned. Clone by hand only a repo that is **not registered yet**.
+- Else if `git_url` is given (a repo not registered yet) → **clone it as the local user** into a working location
   (`{code_repos_root}/<repo>/` by `config.yaml` `build.code_repos_root`, or a path the user names):
   ```
   git clone <git_url> <dest>
@@ -152,7 +161,7 @@ the Shape phases will now load this repo's code-map. Nothing auto-advances; this
   `syncedHead` + `lastSyncedAt`. Same machinery as `connect`. Once the AI has regenerated the
   `code-map.md` (Step 3), publish it to the Product with **`yad repo refresh <repo> --push`**: it
   commits the tracked code-maps + `.sdlc/repos.json` (never the gitignored `pack.md`) as one
-  audit-trail commit `chore(hub): sync code-context — <repos> by @<login> [skip ci]` and pushes it
+  audit-trail commit `chore(product): sync code-context — <repos> by @<login> [skip ci]` and pushes it
   straight to the Product's **default branch** (add `--allow-branch` to commit on a non-default branch).
   This is the code-context analogue of `yad checkpoint` — human-owned machine state, no Task trailer,
   no Co-Authored-By.
@@ -164,10 +173,13 @@ the Shape phases will now load this repo's code-map. Nothing auto-advances; this
 ## Product detection (the Shape review bridge)
 
 The Product is itself a git repo on a platform. This action records that so the Shape review/comment/
-approval cycle can run through a real PR/MR on the Product (`yad-review-gate` + `yad-hub-bridge`). It
-writes only `{project-root}/.sdlc/hub.json` (`config.yaml` `product.config` (older projects: `hub.config`)) — never an epic's state/approvals.
+approval cycle can run through a real PR/MR on the Product (`yad-review-gate` + `yad-product-bridge`). It
+writes only `{project-root}/.sdlc/product.json` and its older name `.sdlc/hub.json` (`config.yaml` `product.config` (older projects: `hub.config`)) — never an epic's state/approvals.
 
-- **`detect-hub`** — detect the Product's own platform and upsert `.sdlc/hub.json`. Run
+- **`detect-product`** — detect the Product's own platform and upsert the Product settings: read
+  `.sdlc/product.json` (`.sdlc/hub.json` on an older Product that has only that name), then write
+  `.sdlc/product.json` and copy it byte for byte to `.sdlc/hub.json` (`cp .sdlc/product.json .sdlc/hub.json`;
+  both until v5 — two that differ by even a space are refused, YAD-STATE-008 — E122). Run
   `git remote get-url origin` **on the Product** and read the host with the SAME logic Step 1 uses for code
   repos: `github.com` → `github`, GitLab host → `gitlab`, no remote → `platform: null`. Record
   `git_url`, `default_branch`, `detectedAt`, and **all three of** `ledger`, `bridge_enabled` and
@@ -204,6 +216,17 @@ platform login that gave it. The platform, not a stored list, decides who can ap
 If the Product has no remote (`platform: null`) or the verified ledger is disabled, the Shape gate runs
 local with no error — the verified ledger is purely additive.
 
+## The Product-link record (E120)
+Each connected code repo also carries `.sdlc/product-link.json` — the Product's `git_url`, the `path`
+where CI checks the Product out (`.yad/product` by default) and its `default_branch`. It is not written
+here: `yad setup`, `yad check --fix` and `yad update` write it (from the Product's own settings, with
+any user name or password taken out of `git_url`) into every connected repo, and `--push` commits it
+to each repo's default branch — a record on disk that is not committed as it stands is committed by the
+next `--push`, though `yad check` reads it as `ok`. The Product-reading gates read it from
+the base; `checks/product-checkout.sh` uses it with the `YAD_PRODUCT_TOKEN` secret. After connecting a
+repo, run `yad check --fix --push`; `yad doctor` warns `repos:product-link-missing` until it is on
+the repo's default branch.
+
 ## Live on-demand (the third context layer)
 The cached pack + map are the default. When a Shape phase needs an **area** not in the map, it may
 re-run Repomix **live**, scoped to that area:
@@ -229,7 +252,7 @@ it does not silently re-pack. Refreshing the cache is a human decision. Document
 ## Reference
 - Registry schema + freshness rule: `references/repos-registry.md`.
 - The risk map — format, rubric, what the agent may change: `references/risk-map.md`.
-- Product config (the review bridge): `references/hub-config.md`.
+- Product config (the review bridge): `references/product-config.md`.
 - Repomix command, secret-scan, degrade path, the code-map prompt, and live on-demand:
   `references/code-context.md`.
 - The repomix discipline this reuses (one-feature-at-a-time variant): `../yad-backfill/references/backfill.md`.

package/skills/yad-connect-repos/references/code-context.md

@@ -81,7 +81,7 @@ side-effect:** when a repo is stale (HEAD ≠ `syncedHead`), the phase **flags i
 "`<repo>` is stale; run `yad repo refresh <repo>` to re-pack the cache + `syncedHead`" — rather than
 silently re-packing the whole repo. A phase never refreshes the registry on its own; the human runs
 `yad repo refresh` (or `yad check --fix`). After the AI regenerates the code-map, `yad repo refresh
---push` publishes the refreshed code-maps + registry to the Product's default branch as a `chore(hub): sync
+--push` publishes the refreshed code-maps + registry to the Product's default branch as a `chore(product): sync
 code-context … [skip ci]` audit commit (never the pack's content; `--allow-branch` overrides the branch
 guard). The `pack.md` is gitignored — `yad repo refresh`/`yad setup` scaffold
 `.sdlc/code-context/*/pack.md` into the Product `.gitignore` (so a regenerated pack never dirties the tree),