yadflow 3.18.1 → 4.0.0-next.1

package/skills/yad-checks/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: yad-checks
-description: 'Build-half Step C of the gated SDLC — the production-safety check gates. Wire and run the CI gates on a code repo: spec-link (every change links a real story/spec via its Task trailer), contract-check (a diff that changes the contract surface without a Contract-Change + an updated, re-locked contract FAILS and routes back to the architecture gate), build/test/lint, verified-commits (no unverified commits from unverified users — platform-Verified signature + roster-allowlisted author, on the hub and every repo), and the Phase 6 feature-thread gates lineage-check / epic-open / reconcile-debt (a change links a real threaded epic; a sealed epic refuses new behaviour; a thread with open hotfix debt is frozen until paid). The gates are CI-agnostic bash, invoked by GitHub Actions and GitLab CI. Use when the user says "wire the check gates", "run the gates", "require signed commits", or "set up CI checks" for a repo.'
+description: 'Build Step C of the gated SDLC — the production-safety check gates. Wire and run the CI gates on a code repo: spec-link (every change links a real story/spec via its Task trailer), contract-check (a diff that changes the contract surface without a Contract-Change + an updated, re-locked contract FAILS and routes back to the architecture gate), build/test/lint, verified-commits (no unsigned commits — every commit carries a platform-Verified signature; write access to the repo decides who can author, on the Product and every repo), and the Phase 6 feature-thread gates lineage-check / epic-open / reconcile-debt (a change links a real threaded epic; a sealed epic refuses new behaviour; a thread with open hotfix debt is frozen until paid), plus an advisory risk-map check (warns when .sdlc/risk-map is stale). The gates are CI-agnostic bash, invoked by GitHub Actions and GitLab CI. Use when the user says "wire the check gates", "run the gates", "require signed commits", or "set up CI checks" for a repo.'
 ---
 
-# SDLC — Check Gates (build-half Step C)
+# SDLC — Check Gates (Build Step C)
 
 **Goal:** Install and run the **check gates** that protect production for a code repo. They run
 in CI on every PR/MR and must pass before merge (build plan §C). Each is a small, separate check:
@@ -16,31 +16,53 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
    contract upstream, it **FAILS and routes back to the architecture gate**. The shared surface is
    never widened from inside a code repo (Phase 2 contract representation: delimited block + SHA-256 lock).
    Every story whose slice the diff touches is checked, not just the first — see `references/check-gates.md`.
+   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.
 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
+   npm with a warning when an npm lockfile is present, and fails closed otherwise); an npm repo
+   without that field retains the historical npm behavior. A declared manager requires a full, exact semantic
+   version (with Corepack's optional integrity suffix supported), and CI activates that exact version.
+   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,
+   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`).
-4. **verified-commits** — no unverified commits from unverified users: every commit in the range must
-   carry a signature the platform marks **Verified** AND be authored by a known identity
-   (`.sdlc/verified-authors`, generated from the hub roster's `email` fields). Enforced on the
-   **product hub and every connected repo**; runs on PRs/MRs only, so the gate-sync bot's direct
-   ledger pushes are unaffected (never replace it with a default-branch push rule — see
+4. **verified-commits** — no unsigned commits: every commit in the range must carry a signature the
+   platform marks **Verified**. There is no author allowlist (E62): write access to the repo decides who
+   can author. An old `.sdlc/verified-authors` file is no longer read, and the gate prints a note when it
+   finds one. Enforced on the **Product and every connected repo**; runs on PRs/MRs only, so the
+   gate-sync bot's direct ledger pushes are unaffected (never replace it with a default-branch push rule — see
    `references/check-gates.md` §4).
 5. **lineage-check** (Phase 6) — the change's owning epic is a valid node in a **feature thread**: a
    `change`/`defect`/`hotfix` epic must thread to a real `parent`. Builds on spec-link's story→epic
    resolution; the every-code-change-has-a-threaded-epic enforcement.
 6. **epic-open** (Phase 6, the staleness preventer) — an epic is **sealed** once every story is
    `shipped`; a commit targeting a sealed epic **FAILS**, forcing new behaviour into a new threaded
-   change-epic (so the front artifacts can never go stale).
+   change-epic (so the Shape artifacts can never go stale).
 7. **reconcile-debt** (Phase 6) — a hotfix that shipped first opens debt; the **next** change on its
    thread **FAILS** until the debt is paid (artifacts updated + a regression test added).
+8. **risk-map** (E65, **advisory — never fails**) — reads the code repo's `.sdlc/risk-map` (one line per
+   directory: `high` / `medium` / `low`, no names) and **warns** when this change adds a directory no line
+   covers, leaves a line whose directory is gone, touches a line still `unset` or `guessed`, or edits the
+   map itself. A repo with no map gets one note. It also prints the **approver count** (E66): a change
+   touching a directory the **base branch's** map marks `high` asks for one more approver — reported,
+   never enforced: branch protection holds the merge — and names who has **committed there in the last 30 days**
+   (E67), so the team knows who can meet that ask. The map is the team's file, never wired; the
+   `yad-connect-repos` skill drafts it. See `references/check-gates.md` §10.
 
-The Phase 6 gates read the owning epic in the **product hub** via `specs/<story>/link.md`'s
-`product-repo` path (like contract-check), and degrade to a PASS-with-note when the hub is not reachable
+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`.
 
 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;
-**nothing auto-advances**. The gates are blocking in CI, but the human still owns the merge (Step E).
+**nothing auto-advances**. The gates are blocking in CI (all but the advisory risk-map check), but the human still owns the merge (Step E).
 
 ## Conventions
 
@@ -50,10 +72,11 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
   (`config.yaml` `build.code_repos_root`).
 - 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,build-test-lint,verified-commits}.sh`
-  - `templates/checks/ledger-guard.sh` → **hub-only** gate, active **only in bridge mode** — hub.json
-    carries BOTH a `platform` and `bridge_enabled` (or the legacy `bridge`) true, the same predicate
-    `isBridge` (`cli/gate.mjs`) applies, so the gate and the CLI can never disagree about who owns the
+  - `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`
+    (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
@@ -62,27 +85,36 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
     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`
-    alongside `verified-commits` (which waives the allowlist for the bot but still requires its
-    signature). See `yad-hub-bridge`.
-  - `templates/hooks/ledger-guard.sh` → **hub-only** agent guardrail, active **only in bridge mode**
-    (the same `isBridgeHub` predicate). Not a CI gate: it is a **harness hook** that refuses an agent's
+    default branch the guard is absolute again. Runs in `yad-hub-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**
+    (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 `<hub>/hooks/ledger-guard.sh` with the
-    `PreToolUse` entry in `.claude/settings.json`. Fails OPEN; see "Step 2b" below.
+    local half of `checks/ledger-guard.sh` (#171). Installed to `<product>/hooks/ledger-guard.sh` 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/github/yad-verified-commits.yml` + `templates/gitlab/yad-verified-commits.gitlab-ci.yml`
-    → the standalone hub-side verified-commits CI (installed by `yad check --fix` with the hub wiring)
-  - `templates/github/yad-checks.yml` → installs to `.github/workflows/yad-checks.yml` (marked `# yad-managed: yad-checks`)
-  - `templates/gitlab/yad-checks.gitlab-ci.yml` → includable fragment, installs to `.gitlab/ci/yad-checks.yml`
+    → the standalone Product-side verified-commits CI (installed by `yad check --fix` with the Product wiring)
+  - `templates/github/yad-checks.yml` → installs to `.github/workflows/yad-checks.yml` (marked `# yad-managed: yad-checks`);
+    its quality job uses `install-deps.sh`, reads the optional `YAD_NODE_VERSION` repository variable,
+    exports the PR's exact `NX_BASE`/`NX_HEAD`, and filters unrelated history blobs while preserving
+    the full commit graph.
+  - `templates/gitlab/yad-checks.gitlab-ci.yml` → includable fragment, installs to `.gitlab/ci/yad-checks.yml`;
+    it uses the same installer, honors a project/group `YAD_NODE_VERSION` CI/CD variable, and exports
+    the MR's exact `NX_BASE`/`NX_HEAD`.
   - `templates/gitlab/gitlab-ci.include-root.yml` → minimal root written only when no root `.gitlab-ci.yml` exists
-  - `templates/gitlab/.gitlab-ci.yml` → legacy standalone root (greenfield single-file option)
+  - `templates/gitlab/.gitlab-ci.yml` → legacy standalone root (greenfield single-file option), kept
+    semantically aligned with the includable fragment's Node version, Nx range, dependency install,
+    and test-worker cap
 - The gates depend on the conventions from earlier steps: the `Task:`/`Contract-Change:` commit
   trailers (`yad-implement`), the `specs/<story>/link.md` + `contracts/` slice (`yad-spec`), and the
   locked `contract.md` (`yad-architecture`).
 
 ## Inputs
 
-- `repo`  — the code repo to wire/run gates for (one of an epic's repos), or `hub` to wire the product hub itself.
+- `repo`  — the code repo to wire/run gates for (one of an epic's repos), or `hub` to wire the Product itself.
 - `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).
 
@@ -91,7 +123,7 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
 ### 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 hub" in
+`{project-root}` itself and the platform comes from `.sdlc/hub.json` — see "Wiring the Product" in
 `references/check-gates.md`.
 
 ### Step 2 — `wire` (install the gates, syncing with any existing CI)
@@ -144,16 +176,17 @@ 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 hub is wired the same way.** `repo: hub` wires the hub repo itself (platform from `.sdlc/hub.json`)
-with a hub-flavored gate set — see "Wiring the hub" in `references/check-gates.md`.
+**The Product is wired the same way.** `repo: hub` wires the Product repo itself (platform from `.sdlc/hub.json`)
+with a Product-flavored gate set — see "Wiring the Product" in `references/check-gates.md`.
 
-**The hub also gets the agent guardrail** (see below): `templates/hooks/ledger-guard.sh` →
-`<hub>/hooks/ledger-guard.sh`, plus the `PreToolUse` entry in `.claude/settings.json`. `yad setup`
-and `yad check --fix` install both; there is nothing to do by hand.
+**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`
+entry in `.cursor/hooks.json`. `yad setup` and `yad check --fix` install them; nothing by hand.
 
-### Step 2b — the agent guardrail (harness hooks, bridge mode only)
+### Step 2b — the agent guardrail (harness hooks, verified mode only)
 The CI gates speak at CI time. That is too late for one failure the field kept hitting (#171): in
-bridge mode the gate ledger is **CI-owned**, so an agent that hand-edits
+verified mode the gate ledger is **CI-owned**, so an agent that hand-edits
 `epics/*/.sdlc/state.json` only finds out twenty minutes later, from a `ledger-guard` FAIL with
 nothing connecting cause to effect — and by then the write has to be reverted before the review
 PR/MR can go green.
@@ -164,24 +197,35 @@ file-editing tool call and refuses the write up front, naming the command that o
 
 - **Harness-agnostic by contract.** The script only locates `yad` and hands the tool payload to
   `yad hook ledger-guard`: **stdin** is a JSON tool-call payload, **exit 0** allows, **exit 2**
-  denies with the reason on stderr. Claude Code's `PreToolUse` protocol is exactly that, so no
-  adapter logic is needed; another harness needs only those two exit codes.
+  denies with the reason on stderr. Claude Code's `PreToolUse` reads exactly that, so its entry points
+  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
+  `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
+  `afterFileEdit`, is not used: it could report the edit but never refuse it, and reporting is what
+  the CI gate already does.
+- **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`
   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
   `origin/` ref, case-folded slugs), never by looking at the working tree.
-- **A no-op without the bridge.** There the ledger is locally owned and the hand-edit the authoring
+- **A no-op with a local ledger.** There the ledger is locally owned and the hand-edit the authoring
   skills describe is *correct*, so nothing is wired and nothing is blocked.
-- **It fails OPEN** — no `yad`, no hub, an unreadable config, an unparseable payload all ALLOW, with
+- **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.
 - **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
-  hub**, since a harness reads hooks from its own project root — a session opened at the workspace
-  above the hub never loads the hub's `.claude/settings.json`.
+  Product**, since a harness reads hooks from its own project root — a session opened at the workspace
+  above the Product never loads the Product's `.claude/settings.json`.
 
-`yad doctor` reports the guardrail as `agent ledger guard wired` / `not wired` on a bridge hub.
+`yad doctor` reports the guardrail as `agent ledger guard wired` / `not wired` on a verified Product.
 See `references/check-gates.md` §"The agent guardrail".
 
 ### Step 3 — `run` (run the gates now)
@@ -206,8 +250,8 @@ human engineer review (Step E) still own the merge. This skill never edits the e
 - **Run standalone** (the Phase 3 default): **stop** here. A clean pass does not advance anything; a
   human takes the next step.
 - **Run by the orchestrator** (`yad-run`, Phase 4): this skill still just reports PASS/FAIL — the
-  *advance decision* is the orchestrator's, read from the `checks` step's `automation` dial. On a clean
-  pass with `checks` earned to `machine_advance`, `yad-run` advances to `engineer-review` on its own;
+  *advance decision* is the orchestrator's, read from the `checks` step's advance dial. On a clean
+  pass with `checks` set to `advance: auto`, `yad-run` advances to `engineer-review` on its own;
   on any FAIL it halts and pulls in a human (build plan §B). **What the gates check is unchanged** —
   only who decides to proceed after a clean pass.
 
@@ -218,7 +262,7 @@ human engineer review (Step E) still own the merge. This skill never edits the e
   to the architecture gate; only an updated, re-locked contract + `Contract-Change: yes` may pass.
 - **Tests must exercise behavior.** build/test/lint is not satisfied by empty or trivial tests.
 - **The gate never advances itself.** A FAIL always halts. A clean PASS advances only when the
-  orchestrator's `checks` dial is `machine_advance` (earned) — and only as far as the engineer review,
+  orchestrator's `checks` dial is `advance: auto` (`yad dial`) — and only as far as the engineer review,
   which is always human. Standalone, the gate still stops and the human owns the merge.
 
 ## Reference