yadflow 4.0.0-next.3 → 4.0.0

package/skills/yad-checks/SKILL.md

@@ -19,7 +19,12 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
    A claimed `Contract-Change` against an epic that has **no lock at all** fails too: an epic on a short
    lane (`chore`/`spike`) has no architecture step and never locks a surface, so it may consume the
    contract but not change it, and the change belongs to a new epic on `classic`. That failure needs the
-   epic's ledger directory to resolve — a Product that is simply not checked out still defers, as before.
+   epic's ledger directory to resolve — a Product that is simply not checked out still defers, as before,
+   except on a repo's **first spec** (no `link.md` on the base names a Product): there a slice change whose
+   `product-repo` reaches nothing **fails** (E119), because the PR chose that value itself. Where the
+   Product lives is a repo fact once `yad check --fix --push` has merged `.sdlc/product-link.json` into
+   the code repo (E120): the gates read it from the base first, and `checks/product-checkout.sh` clones
+   the Product there in CI when the `YAD_PRODUCT_TOKEN` secret is set (see `references/check-gates.md`).
 3. **build/test/lint** — standard quality stage; tests must actually exercise new behavior, not just pass.
    CI installs and runs through the package manager declared by the repo's standard
    `package.json#packageManager` field (`npm` and `pnpm` are supported; any other manager stays on
@@ -29,7 +34,7 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
    The code-repo `yad-checks` workflow uses Node 22 by default (the build/test/lint job on GitHub; every
    `yad-*` gate job's image in the GitLab fragment) and reads `YAD_NODE_VERSION` (a GitHub repository
    variable or GitLab CI/CD variable) for repos whose declared runtime differs (a declared `packageManager` needs Corepack, so the override must be a line that
-   bundles a current one: 20.19+, 22.14+ or 24; Node 25+ dropped it). The Product-side workflows (verified-commits, hub-checks, update-guard,
+   bundles a current one: 20.19+, 22.14+ or 24; Node 25+ dropped it). The Product-side workflows (verified-commits, product-checks, update-guard,
    gate-sync) only run the `yad` CLI and keep their own pinned Node; the variable does not reach them.
    The CI job sets `YAD_TEST_MAX_WORKERS` (default `2`); the gate caps jest/vitest test concurrency at
    that and is a no-op for other runners (see `references/check-gates.md`).
@@ -58,7 +63,8 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
 
 The Phase 6 gates read the owning epic in the **Product** via `specs/<story>/link.md`'s
 `product-repo` path (like contract-check), and degrade to a PASS-with-note when the Product is not reachable
-from CI. See `references/check-gates.md` and `skills/yad-change`.
+from CI. `product-repo` is read from the base, a Product this repo tracks is read from the base commit, and
+`epic:` must be the story ID's prefix — the PR cannot choose what is gated (E117, E118). See `references/check-gates.md` and `skills/yad-change`.
 
 The gates are **CI-agnostic bash** in `checks/`; thin pipeline configs invoke them on GitHub Actions
 and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the skill or let CI run them;
@@ -73,29 +79,31 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
 - Canonical gate sources live in this skill's `templates/` (the source of truth that gets installed
   into each code repo):
   - `templates/checks/{spec-link,contract-check,package-manager,install-deps,build-test-lint,verified-commits,risk-map-check}.sh`
-  - `templates/checks/ledger-guard.sh` → **Product-only** gate, active **only in verified mode** — hub.json
-    carries BOTH a `platform` and `ledger: "verified"` — or, before `yad migrate`, `bridge_enabled`
+  - `templates/checks/ledger-guard.sh` → **Product-only** gate, active **only in verified mode** — `product.json`
+    (`hub.json` on an older Product) carries BOTH a `platform` and `ledger: "verified"` — or, before `yad migrate`, `bridge_enabled`
     (or the legacy `bridge`) true. The same predicate
     `isVerifiedLedger` (`cli/manifest.mjs`) applies, so the gate and the CLI can never disagree about who owns the
     ledger (#186). A no-op otherwise, when humans legitimately own it. On review PRs it FAILs any
     commit that touches the
-    CI-owned gate ledger (`.sdlc/{state,approvals,comments,hub-prs}.json`, `reviews/*.md`) unless it
-    is a **verified gate-bot commit** — bot-authored AND platform-Verified, since author text alone is
-    spoofable. `.sdlc/contract-lock.json` is artifact-side and exempt. So is a **new epic's seed**:
+    CI-owned gate ledger (`.sdlc/{state,approvals,comments,product-prs,hub-prs}.json`, `reviews/*.md`) unless it
+    is a **verified gate-bot commit** — bot-authored AND platform-Verified. (Known gap: the Verified
+    badge proves only that the committer signed, not that the bot did, so the GitHub job is given no
+    token and refuses every such commit; on GitLab the gap is still open. See `references/check-gates.md`.) `.sdlc/contract-lock.json` is artifact-side and exempt. So is a **new epic's seed**:
     no CI path can create a ledger (`gate ci` only *advances* an existing chain, at merge, on the
     default branch), so an epic whose `.sdlc/state.json` is absent from the base ref may be created by
     a human on its first review PR/MR — **creation, not mutation** (#162). Once the ledger is on the
-    default branch the guard is absolute again. Runs in `yad-hub-checks`; `verified-commits` runs beside
+    default branch the guard is absolute again. Runs in `yad-product-checks`; `verified-commits` runs beside
     it in its own `yad-verified-commits` workflow (and requires the bot's signature like any other
-    commit's). See `yad-hub-bridge`.
-  - `templates/hooks/ledger-guard.sh` → **Product-only** agent guardrail, active **only in verified mode**
+    commit's). See `yad-product-bridge`.
+  - `templates/hooks/ledger-guard.mjs` → **Product-only** agent guardrail, active **only in verified mode**
     (the same `isVerifiedLedger` predicate). Not a CI gate: it is a **harness hook** that refuses an agent's
     edit to the CI-owned ledger at the moment it is attempted and names `yad gate open` instead — the
-    local half of `checks/ledger-guard.sh` (#171). Installed to `<product>/hooks/ledger-guard.sh` with the
+    local half of `checks/ledger-guard.sh` (#171). Installed to `<product>/hooks/ledger-guard.mjs` with the
     `PreToolUse` entry in `.claude/settings.json`; a `.cursor` project also gets
-    `templates/hooks/ledger-guard-cursor.sh` and a `preToolUse` entry in `.cursor/hooks.json`.
-    Fails OPEN; see "Step 2b" below.
-  - `templates/hooks/yad-capture.sh` → **Product-only**, in **both** ledger modes (E43): the post-edit
+    `templates/hooks/ledger-guard-cursor.mjs` and a `preToolUse` entry in `.cursor/hooks.json`.
+    Fails OPEN; see "Step 2b" below. Every hook is a Node script the entry runs as `node <script>`, so
+    it needs no bash and no execute bit and runs on Windows too (E113).
+  - `templates/hooks/yad-capture.mjs` → **Product-only**, in **both** ledger modes (E43): the post-edit
     harness hook that runs `yad capture --hook`, which snapshots every changed Shape artifact onto the
     person's private `yad/wip/<name>/<epic>` branches without touching the checkout. Wired as a
     `PostToolUse` entry in `.claude/settings.json` and an `afterFileEdit` entry in `.cursor/hooks.json`;
@@ -121,16 +129,18 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
 
 ## Inputs
 
-- `repo`  — the code repo to wire/run gates for (one of an epic's repos), or `hub` to wire the Product itself.
+- `repo`  — the code repo to wire/run gates for (one of an epic's repos), or `product` to wire the Product itself (`hub`, the old name, still works). A code repo that is itself named
+  `product`: give its registered path instead (for example `repos/product`), so it is not taken for the Product.
 - `action` — `wire` (install the gates into the repo) | `run` (run the three gates now). Default `run`.
 - `base`  — for `run`: the base ref to diff against (the PR/MR target; default the repo's default branch).
 
 ## On Activation
 
 ### Step 1 — Resolve the code repo
-Map `repo` → `{project-root}/demo-repos/<repo>/` (or the registry `path` in `.sdlc/repos.json`); confirm
-it is its own git repo. Operate inside it with absolute paths. For `repo: hub`, the target is
-`{project-root}` itself and the platform comes from `.sdlc/hub.json` — see "Wiring the Product" in
+Map `repo` → `{project-root}/demo-repos/<repo>/` (or the registry `path` in `.sdlc/repos.json`). A `repo` value with a `/` in it is a registry `path`, not a name: match it against each entry's `path`
+(so a code repo named `product` is reached as, for example, `repos/product`). Confirm
+it is its own git repo. Operate inside it with absolute paths. For `repo: product`, the target is
+`{project-root}` itself and the platform comes from `.sdlc/product.json` (`.sdlc/hub.json` on an older Product) — see "Wiring the Product" in
 `references/check-gates.md`.
 
 ### Step 2 — `wire` (install the gates, syncing with any existing CI)
@@ -183,12 +193,12 @@ Re-running `wire` is **idempotent** — markers (`# yad-managed: yad-checks`,
 `# yad-managed-include: yad-checks`) and the include-entry check make a second run a no-op.
 Commit the wiring on the repo's default branch (it is shared infrastructure, not a task diff).
 
-**The Product is wired the same way.** `repo: hub` wires the Product repo itself (platform from `.sdlc/hub.json`)
+**The Product is wired the same way.** `repo: product` wires the Product repo itself (platform from `.sdlc/product.json`)
 with a Product-flavored gate set — see "Wiring the Product" in `references/check-gates.md`.
 
-**The Product also gets the agent guardrail** (see below): `templates/hooks/ledger-guard.sh` →
-`<product>/hooks/ledger-guard.sh`, plus the `PreToolUse` entry in `.claude/settings.json`. A project
-whose targets include `.cursor` also gets `templates/hooks/ledger-guard-cursor.sh` and a `preToolUse`
+**The Product also gets the agent guardrail** (see below): `templates/hooks/ledger-guard.mjs` →
+`<product>/hooks/ledger-guard.mjs`, plus the `PreToolUse` entry in `.claude/settings.json`. A project
+whose targets include `.cursor` also gets `templates/hooks/ledger-guard-cursor.mjs` and a `preToolUse`
 entry in `.cursor/hooks.json`. `yad setup` and `yad check --fix` install them; nothing by hand.
 
 ### Step 2b — the agent guardrail (harness hooks, verified mode only)
@@ -198,7 +208,7 @@ verified mode the gate ledger is **CI-owned**, so an agent that hand-edits
 nothing connecting cause to effect — and by then the write has to be reverted before the review
 PR/MR can go green.
 
-`hooks/ledger-guard.sh` is the local half of that same rule. It runs as a **harness hook** before a
+`hooks/ledger-guard.mjs` is the local half of that same rule. It runs as a **harness hook** before a
 file-editing tool call and refuses the write up front, naming the command that owns the transition
 (`yad gate open`), so the agent corrects itself instead of failing a pipeline.
 
@@ -208,7 +218,7 @@ file-editing tool call and refuses the write up front, naming the command that o
   straight at the script. Cursor does NOT: its `preToolUse` is a **permission hook**, which wants a
   JSON verdict on stdout and treats an empty or off-schema answer as a refusal — and this script
   prints nothing when it allows, so wiring it there directly would block every file write in the
-  project. Cursor's entry points at `hooks/ledger-guard-cursor.sh` instead, which runs
+  project. Cursor's entry runs `node hooks/ledger-guard-cursor.mjs` instead, which runs
   `yad hook ledger-guard --format cursor` and always answers `{"permission":"allow"}` or
   `{"permission":"deny","user_message":…,"agent_message":…}`. **Check which kind a harness is
   before wiring it by hand.** A hook that fires only AFTER the write, such as Cursor's
@@ -217,7 +227,7 @@ file-editing tool call and refuses the write up front, naming the command that o
 - **Targets with no such hook are named, not skipped.** `.agents`, `.gemini`, `.zencoder` and
   `.opencode` get the script and no wiring, and `yad doctor` says which of a project's targets are
   guarded by CI alone. Silence about an unguarded target reads as a guarded one.
-- **Same scope as the CI gate**, deliberately: guarded are `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json`
+- **Same scope as the CI gate**, deliberately: guarded are `epics/*/.sdlc/{state,approvals,comments,product-prs,hub-prs}.json`
   and `epics/*/reviews/*.md` (at the gate's own glob depth, which spans `/`); exempt are
   `contract-lock.json`, `change.json`, and every artifact. A **new** epic's ledger is exempt too —
   creation, not mutation (#162), decided by listing the epics the **base ref** carries (an
@@ -226,7 +236,8 @@ file-editing tool call and refuses the write up front, naming the command that o
   skills describe is *correct*, so nothing is wired and nothing is blocked.
 - **It fails OPEN** — no `yad`, no Product, an unreadable config, an unparseable payload all ALLOW, with
   a note on stderr. `ledger-guard` in CI fails *closed* and remains the authority. `YAD_HOOK_DISABLE=1`
-  skips one command.
+  skips one command. A PERSON who must commit a ledger change anyway uses `yad commit --manual --reason
+  "<why>"` (E49) — never the agent on its own initiative.
 - **Known gaps** (both caught by the CI gate instead): a `Bash` tool call (`sed -i epics/…`) is not
   intercepted — matching it would mean parsing shell; and the hook arms sessions **rooted at the
   Product**, since a harness reads hooks from its own project root — a session opened at the workspace
@@ -235,6 +246,16 @@ file-editing tool call and refuses the write up front, naming the command that o
 `yad doctor` reports the guardrail as `agent ledger guard wired` / `not wired` on a verified Product.
 See `references/check-gates.md` §"The agent guardrail".
 
+**The same rule for a person's `git commit` (E48).** On a verified Product, `yad check --fix` also
+installs `.git/hooks/pre-commit` in the clone it runs in. It runs `node hooks/ledger-guard.mjs
+--staged`, which judges the files the commit is about to record by the same rules as the CI gate (a
+merge commit and a `yad-gate-sync` commit pass, as they do in CI) and refuses the commit with the files,
+the `git restore --staged` line and the owning command. It is per clone — git never copies hooks — so
+`yad doctor` warns `git-hook` in a clone that has none. A `pre-commit` that is not yad's, or a
+`core.hooksPath` folder, is never written: print the one line `yad doctor` gives and let the person add
+it. Branch protection is what makes the CI gates hold a merge at all: point the team at yadflow's
+`docs/branch-protection.md`.
+
 ### Step 3 — `run` (run the gates now)
 From inside the repo, run each gate against `base` and report PASS/FAIL per gate:
 ```