yadflow 3.18.0 → 3.19.0-next.2

package/skills/yad-change/SKILL.md

@@ -7,21 +7,21 @@ description: 'Phase 6 post-lock change management — the change-request/defect
 
 **Goal:** Turn a post-lock change request, defect, or hotfix into a **new epic threaded to its parent**,
 so the feature's locked artifacts are never mutated — only *superseded*. The change-epic **inherits**
-the front artifacts it does not change (by reference) and **re-authors** only the ones it does, so the
+the Shape artifacts it does not change (by reference) and **re-authors** only the ones it does, so the
 thread head always describes current behaviour and the SDLC stays a trusted source of truth for the next
 change. This skill does the **intake + triage + seeding** and then hands off to the normal authoring
-skills + `yad-review-gate`. It is a **front state**: human-confirmed, **never auto-advances**.
+skills + `yad-review-gate`. It is a **Shape step**: human-confirmed, **never auto-advances**.
 
-This is the answer to "the front/spec docs go stale after the contract locks": a behavioural change can
-no longer ship through the build half against an old story — `epic-open` seals a fully-shipped epic, so
+This is the answer to "the Shape/spec docs go stale after the contract locks": a behavioural change can
+no longer ship through Build against an old story — `epic-open` seals a fully-shipped epic, so
 new behaviour must enter here, and its re-authored stories/test-cases describe the change.
 
 ## Conventions
 
 - `{project-root}` resolves from the product hub.
 - Artifacts live under `{project-root}/epics/EP-<slug>/` — the change-epic gets its OWN `EP-<slug>`
-  (assigned here, never renamed) and its own `stories/EP-<slug>-S0N`, so every existing gate, the bridge,
-  `yad next`, and the build-half traceability keep working unchanged.
+  (assigned here, never renamed) and its own `stories/EP-<slug>-S0N`, so every existing gate, the verified ledger,
+  `yad next`, and the Build traceability keep working unchanged.
 - The thread is **derived** from `parent:` frontmatter (no registry); `thread:` is a cache that must
   equal the computed root (`yad doctor` flags a mismatch). Thread id = the genesis epic's id.
 - Lineage frontmatter, the inherited-step shape, the pointer-lock, `change.json`, and
@@ -67,7 +67,7 @@ in `references/triage.md`).
 
 ### Step 2 — Gather the change + triage the DEPTH (auto-propose, human-confirm)
 With the requester, classify the change into one **depth** (the `yad-backfill` discipline: auto-propose,
-human-confirm). The depth decides which front states are **re-authored** vs **inherited**:
+human-confirm). The depth decides which Shape steps are **re-authored** vs **inherited**:
 
 | depth | re-authors (active) | inherits (pre-done, by reference) | first step |
 |-------|---------------------|-----------------------------------|-----------|
@@ -121,7 +121,7 @@ by `yad-architecture` downstream.
 
 ### Step 5 — Seed `state.json` (inherited steps pre-done; only the changed steps run)
 Create `.sdlc/state.json` with the **same 10-step chain** as `yad-epic` (so `advanceState`/`nextAction`/
-`gatePredicate`/the bridge run unchanged), but:
+`gatePredicate`/the verified ledger run unchanged), but:
 - **Inherited** authoring steps **and their review gates**: `status: "done"`, `"inherited": true`,
   `"inheritedFrom": "<owning epic from the resolved truth>"`, `"boundHash": "<that artifact's current
   hash>"`.
@@ -136,7 +136,7 @@ Seed `.sdlc/comments.json` = `[]` and create `reviews/`.
 
 Commit the seed on the `change/EP-<slug>` branch. It reaches the hub's default branch through this
 change-epic's **first** review PR/MR — cut the `review/EP-<slug>/<artifact>` branch from `change/…` so
-it carries the seed. In bridge mode `ledger-guard` exempts a new epic's ledger (creation, not mutation,
+it carries the seed. In verified mode `ledger-guard` exempts a new epic's ledger (creation, not mutation,
 #162), so no direct push to a protected default branch is needed; every later change to that ledger is
 CI's. See `../yad-epic/references/state-schema.md`, "Authoring branches".
 
@@ -166,16 +166,16 @@ defect to the gate that should have caught it. Add `"parentStub": true` when the
 un-promoted stub (Step 5) — omit it (or `false`) otherwise.
 
 ### Step 7 — Hotfix only: record the ship-first exception + open reconcile debt
-If `kind: hotfix`, the build half MAY run before these front gates approve (severity demands it). Record
+If `kind: hotfix`, Build MAY run before these Shape gates approve (severity demands it). Record
 `hotfix: { "shipFirst": true }` in `change.json` and **append** to `.sdlc/reconcile-debt.json`:
 `{ "thread": "<…>", "epicId": "<…>", "openedDate": "<today>", "reason": "<why>", "requires": ["artifacts-updated","regression-test"], "status": "open", "paidDate": null, "paidBy": null, "evidence": { "artifacts": [], "regressionTest": "" } }`.
 Tell the user the debt **freezes the next normal change** on this thread (`reconcile-debt` gate) until it
-is paid (front artifacts updated **and** a regression test added, then `status: "paid"`).
+is paid (Shape artifacts updated **and** a regression test added, then `status: "paid"`).
 
 ### Step 8 — Stop; hand off (NO auto-advance)
 Report: the new `EP-<slug>`, its thread + parent, the re-author-vs-inherit split, the seeded
 `currentStep`, and the next skill — `yad-architecture` (contract-surface), else `yad-stories` /
-`yad-test-cases` — followed by `yad-review-gate`. Front states do not auto-advance. Suggest
+`yad-test-cases` — followed by `yad-review-gate`. Shape steps do not auto-advance. Suggest
 `yad thread <thread>` to see the evolution and `yad-timeline` / `yad-defects` to render it.
 
 ## Hard rules
@@ -186,7 +186,7 @@ Report: the new `EP-<slug>`, its thread + parent, the re-author-vs-inherit split
   `boundHash`; the pointer-lock carries the parent hash verbatim. The gate never re-reviews them.
 - **Contract-surface ⇒ re-author architecture.** Omitting `architecture` from `inherits` is the ONLY way
   to change the surface; it re-locks (new hash) and routes through the escalated architecture review —
-  the same mechanism as the build-half `Contract-Change` route, unified.
+  the same mechanism as the Build `Contract-Change` route, unified.
 - **A hotfix opens debt, never waives it.** Ship-first is allowed once; the thread freezes for new work
   until the debt is paid.
 - **Never auto-advances.** This skill seeds + records; humans author and approve via the normal gates.

package/skills/yad-change/references/triage.md

@@ -69,15 +69,14 @@ Write `.sdlc/contract-lock.json` with the parent's hash **verbatim**:
 ```
 
 Get the parent hash from the owning epic's `.sdlc/contract-lock.json` `hash` field (do NOT recompute — copy
-it). `contract-check.sh` reads only `hash`, so a build-half story in the change-epic pins this identical
+it). `contract-check.sh` reads only `hash`, so a Build story in the change-epic pins this identical
 hash via its `link.md` and the gate passes unchanged. There is no `contract.md` in the change-epic, so
 the surface physically cannot drift.
 
 **To CHANGE the surface instead:** do not inherit `architecture`. Then `yad-architecture` re-authors
 `contract.md` in the change-epic between fresh `CONTRACT-SURFACE` markers, computes a **new** hash, and
 writes a real (non-pointer) `contract-lock.json`. `architecture-review` carries `risk_tags: ["contract"]`
-→ the escalated domain-owner review. This is the same re-lock-invalidates-approvals behaviour the front
-half already has, relocated from "edit the locked file" to "author a contract-surface change-epic".
+→ the escalated domain-owner review. This is the same re-lock-invalidates-approvals behaviour Shape already has, relocated from "edit the locked file" to "author a contract-surface change-epic".
 
 ## Genesis migration (one-time, per feature)
 

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 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.'
 ---
 
-# 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:
@@ -17,6 +17,16 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
    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`.
 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 hub-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
@@ -30,7 +40,7 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
    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).
 
@@ -50,10 +60,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}.sh`
+  - `templates/checks/ledger-guard.sh` → **hub-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
@@ -65,17 +76,24 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
     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
+  - `templates/hooks/ledger-guard.sh` → **hub-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.
   - `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`
+  - `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`).
@@ -151,9 +169,9 @@ with a hub-flavored gate set — see "Wiring the hub" in `references/check-gates
 `<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.
 
-### 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.
@@ -171,7 +189,7 @@ file-editing tool call and refuses the write up front, naming the command that o
   `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
   a note on stderr. `ledger-guard` in CI fails *closed* and remains the authority. `YAD_HOOK_DISABLE=1`
@@ -181,7 +199,7 @@ file-editing tool call and refuses the write up front, naming the command that o
   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`.
 
-`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 hub.
 See `references/check-gates.md` §"The agent guardrail".
 
 ### Step 3 — `run` (run the gates now)

package/skills/yad-checks/references/check-gates.md

@@ -1,6 +1,6 @@
 # Check gates — definitions, scripts, CI wiring, convention map
 
-The gates are the production-safety core of the build half (Phase 3 build plan §C). They are
+The gates are the production-safety core of Build (Phase 3 build plan §C). They are
 deliberately small, separate, and CI-agnostic: plain bash in `checks/`, invoked by whatever CI the
 repo uses. Each reads conventions established by earlier steps — it invents nothing.
 
@@ -10,7 +10,7 @@ repo uses. Each reads conventions established by earlier steps — it invents no
 |------|-------|-------------|
 | spec-link | the `Task: <story>-<task>` commit trailer; `specs/<story>/link.md` | `yad-implement` (trailer), `yad-spec` (link.md) |
 | contract-check | changed files under `specs/<story>/contracts/`; the `Contract-Change: yes` trailer; `link.md`'s pinned `contract-lock`; the product repo's `contract-lock.json` | `yad-architecture` (lock), `yad-spec` (slice + link), `yad-implement` (trailer) |
-| build/test/lint | the repo's `npm run lint` / `npm run build` / `npm test` | the repo |
+| build/test/lint | the repo's configured package manager running `lint` / `build` / `test` | the repo |
 | lineage-check | the `Task:` trailer → `link.md` (`epic` + `product-repo`); the owning epic's `kind`/`parent` frontmatter in the hub | `yad-spec` (link.md), `yad-change` (lineage frontmatter) |
 | epic-open | the `Task:` trailer → `link.md` → the hub epic's `stories/*.md` `status:` (sealed = all `shipped`) | `yad-engineer-review` (story status), `yad-change` (the change-epic) |
 | reconcile-debt | the `Task:` trailer → `link.md` → the hub epic's `thread`; every thread epic's `reconcile-debt.json` | `yad-change` (opens hotfix debt) |
@@ -93,13 +93,44 @@ own CI runs, plus an assertion that each one actually *assigns* `BASE` from it.
 
 ## 3. build/test/lint (`templates/checks/build-test-lint.sh`)
 
-- Runs `npm run lint`, `npm run build`, `npm test` in order; any non-zero exit fails the gate.
+- Reads the standard `package.json#packageManager` field and runs `lint`, `build`, and `test` through
+  that manager in order; any non-zero exit fails the gate. `npm` and `pnpm` are supported; another
+  manager (yarn, bun) fails closed unless an npm lockfile is present, in which case the repo stays on
+  the historical npm path with a warning — a yarn-locally, npm-in-CI repo was green before this
+  field was read and must not go red on upgrade. A repo
+  without the field retains npm behavior unless it carries `pnpm-lock.yaml` and no npm lockfile
+  (`package-lock.json` / `npm-shrinkwrap.json`) — a repo with both keeps the npm path rather than
+  silently changing toolchains.
+- CI runs `install-deps.sh` first. A declared npm or pnpm manager must use a full, exact semantic
+  version with either no build metadata or Corepack's integrity suffix,
+  `+<sha1|sha224|sha256|sha384|sha512>.<lowercase hex digest>` at that algorithm's digest length
+  (Corepack hashes the download with the named algorithm and compares the lowercase hex string).
+  Other build metadata, digest algorithms, digest lengths, uppercase digests, or trailing
+  identifiers fail closed. The installer activates the declared version through
+  Corepack. Pinned npm is dispatched through Corepack — `corepack npm ci` here and `corepack npm run`
+  in the gate, since Corepack activates npm but never shims it — so Node's ambient npm cannot
+  override the declaration anywhere; packageManager-absent npm preserves the historical `npm ci` path. pnpm uses
+  `pnpm install --frozen-lockfile`. Partial versions, ranges, and tags also fail closed instead of
+  floating to a different toolchain.
+- The build/test/lint job defaults to Node 22. Set the GitHub repository variable or GitLab
+  project/group CI/CD variable `YAD_NODE_VERSION` when the repo requires another supported Node
+  release; generated files remain managed instead of accumulating consumer-specific edits. The
+  variable is read by the code repo's `yad-checks` workflow only (on GitHub the build/test/lint job;
+  in the GitLab fragment it sets the `node:` image of every `yad-*` gate job, which all share one
+  anchor) — the hub-side workflows run the `yad` CLI, not the repo's toolchain, and keep their own
+  pinned Node. A declared `packageManager` needs
+  Corepack, which ships with Node 18 through 24 (Node 25+ dropped it) and, before 18.20.7 / 20.19 /
+  22.14, carries registry keys too old to verify anything published since 2025 — so the override
+  should stay on a current 20, 22 or 24 line (or install a current Corepack first). The installer
+  checks for the binary and wraps `corepack prepare`, so both an absent and a stale Corepack fail
+  with that guidance instead of a bare "command not found" or "Cannot find matching keyid".
 - Tests must actually exercise behavior (build plan §C) — an empty or trivially-passing suite does not
   satisfy the gate's intent.
 - **Test worker cap.** When the CI job sets `YAD_TEST_MAX_WORKERS` (the templates default it to `2`)
   and the repo's `test` script is jest/vitest, the gate forwards `--maxWorkers=<n>` to bound CI
-  concurrency. For any other runner (`node --test`, mocha, …) it is a no-op — the flag is never
-  passed, so the gate cannot break on an unknown option. Override it per repo via the
+  concurrency (as `-- --maxWorkers=<n>` under npm, which consumes the separator, and bare under pnpm,
+  which would forward a literal `--` to the script). For any other runner (`node --test`, mocha, …)
+  it is a no-op — the flag is never passed, so the gate cannot break on an unknown option. Override it per repo via the
   `YAD_TEST_MAX_WORKERS` CI variable, or unset it to remove the cap.
 
 ### Canonical `package.json` scripts (Node demo)
@@ -176,13 +207,13 @@ from the event payload):
   period (`config.yaml build.pr_title_style: same_as_commit_subject` — one task = one PR, the title is
   the squash-merge subject).
 - `--profile hub` → splits by the PR/MR **head branch** (passed via `--head`, injected by CI):
-  - `review/EP-*` head (or no `--head` — stays strict) → a front-half artifact-review title
+  - `review/EP-*` head (or no `--head` — stays strict) → a Shape artifact-review title
     `review: <artifact> (EP-<slug>)`, the shape `yad gate open` creates.
   - any other head → a tooling/code change to the hub itself, so it follows the `code` convention (a
     Conventional-Commits subject). This is what lets a PR that changes the hub's own workflows/checks
     pass — it has no EP artifact to review.
   - **Anti-bypass guard.** The branch name alone is not trusted: a non-review head that actually
-    changes front-half artifacts (any path under `epics/**`) **FAILS** — those changes must go through
+    changes Shape artifacts (any path under `epics/**`) **FAILS** — those changes must go through
     a `review/EP-*` PR and the artifact-review workflow. CI passes the PR's changed paths via
     `--changed <file>` (computed from the diff against the base ref); without that list (a direct
     by-hand caller) the guard is inert and the branch split alone applies.
@@ -196,10 +227,10 @@ catches a free-form description that bypassed it:
   `Risk level:` (`low|medium|high`).
 - `--profile hub` → splits by the PR/MR **head branch** (passed via `--head`, injected by CI):
   - `review/EP-*` head (or no `--head`) → requires the artifact-review template: `## Artifact under
-    review`, `## Impact & Risk (front-half)`, `## Checklist`, and a `Risk tags:` line.
+    review`, `## Impact & Risk (front-half)` (or `(Shape)`), `## Checklist`, and a `Risk tags:` line.
   - any other head → a hub tooling PR, so it requires the `code` task template (`## Summary`,
     `## Impact & Risk`, `## Checklist`, filled `Risk level:`).
-  - **Anti-bypass guard** (same as pr-title): a non-review head that changes front-half artifacts
+  - **Anti-bypass guard** (same as pr-title): a non-review head that changes Shape artifacts
     (`epics/**`, detected from the CI-supplied `--changed <file>` list) **FAILS** — artifact changes
     must go through a `review/EP-*` PR.
 
@@ -244,7 +275,7 @@ four copies stay byte-identical.
   epic in a thread" enforcement, layered on spec-link.
 - **epic-open** — an epic is **sealed** iff it has ≥1 story and **every** `stories/*.md` `status:` is
   `shipped`. A commit whose owning epic is sealed **FAILS**: new behaviour cannot mutate a shipped epic;
-  it must land in a new threaded change-epic. This is what stops the front artifacts from going stale.
+  it must land in a new threaded change-epic. This is what stops the Shape artifacts from going stale.
 - **reconcile-debt** — resolves the epic's `thread` (its `thread:` frontmatter, else the epic id) and
   scans every thread epic's `reconcile-debt.json`. An **open** entry the current epic does not own
   **FAILS** the change (the thread is frozen until the hotfix debt is paid: artifacts updated + a
@@ -296,11 +327,24 @@ The gates run identically under either CI; the config just invokes the scripts w
   read the title/body from the event payload: `pr-title` takes `${{ github.event.pull_request.title }}`
   and `pr-template` writes `${{ github.event.pull_request.body }}` to a temp file. All `--profile code`.
   The Phase 6 thread gates (`lineage-check`, `epic-open`, `reconcile-debt`) run as their own jobs with
-  `fetch-depth: 0`, the same `origin/${{ github.base_ref }}` base.
+  `fetch-depth: 0`, the same `origin/${{ github.base_ref }}` base. The build/test/lint checkout also
+  uses `filter: blob:none`; its installer follows `package.json#packageManager`, and `NX_BASE` /
+  `NX_HEAD` carry the exact base/head SHAs so Nx affected commands evaluate the PR rather than a
+  stale default. `YAD_NODE_VERSION` is read from GitHub repository variables with `22` as the default.
+  Dependencies are cached with `actions/cache` (npm's `~/.npm`, pnpm's store, and the Corepack home
+  holding the pinned manager, keyed on the lockfiles and package.json) rather than setup-node's
+  npm-only `cache:`, which must name the manager before package.json has been read.
 - **GitLab CI** — `templates/gitlab/yad-checks.gitlab-ci.yml` → `.gitlab/ci/yad-checks.yml`, pulled in
   by the root `.gitlab-ci.yml`'s `include:`. The jobs run on `merge_request_event` with `GIT_DEPTH: 0`,
   passing `origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME`; the pattern jobs read `$CI_MERGE_REQUEST_TITLE`
-  and `$CI_MERGE_REQUEST_DESCRIPTION`. All `--profile code`.
+  and `$CI_MERGE_REQUEST_DESCRIPTION`. The quality job uses the same package-manager-aware installer;
+  `NX_BASE=$CI_MERGE_REQUEST_DIFF_BASE_SHA` and `NX_HEAD=$CI_COMMIT_SHA` provide the equivalent Nx
+  range. Its `node:${YAD_NODE_VERSION}` image defaults to `22` and a project/group CI/CD variable may
+  override it without editing the managed fragment. Those three variables sit on the `.sdlc_mr_only`
+  anchor, not the fragment's top-level `variables:` — an included top-level block merges into the host
+  pipeline's globals, where `NX_BASE`/`NX_HEAD` could collide with a host's own Nx setup. The retained greenfield standalone template
+  (`templates/gitlab/.gitlab-ci.yml`) carries the same Node default, exact Nx range, and dependency
+  installer and test-worker-cap semantics. All `--profile code`.
 
 ## Sync with existing CI (merge, never clobber)
 
@@ -344,7 +388,7 @@ merge-not-clobber logic, with a **hub-flavored gate set** appropriate to a "thin
 - **approvals-present** — an epic at `ready-for-build` has the approvals its gate rule requires recorded
   in `.sdlc/approvals.json` (the same predicate `yad-review-gate` enforces).
 
-These are advisory checks on the hub's own PRs (the front-half review PRs the bridge opens); they keep
+These are advisory checks on the hub's own PRs (the Shape review PRs the verified ledger opens); they keep
 the hub's artifacts internally consistent. The hub never runs the code-repo `spec-link`/`build-test-lint`
 gates. Author the hub gate scripts under the hub's `checks/` following the same CI-agnostic-bash pattern.
 
@@ -352,12 +396,12 @@ The hub **does** run the verified-commits gate — `yad check --fix` installs `c
 plus a standalone workflow (`templates/github/yad-verified-commits.yml` →
 `.github/workflows/yad-verified-commits.yml`, or the GitLab fragment
 `templates/gitlab/yad-verified-commits.gitlab-ci.yml` → `.gitlab/ci/yad-verified-commits.yml` +
-its one include line) whenever `.sdlc/hub.json` has a platform with the bridge enabled. So the
-front-half review PRs are held to the same rule as code-repo PRs: signed, known authors only.
+its one include line) whenever `.sdlc/hub.json` has a platform with a verified ledger. So the
+Shape review PRs are held to the same rule as code-repo PRs: signed, known authors only.
 
 The hub **also** runs the three pattern gates (`commit-message`, `pr-title`, `pr-template`) with
 `--profile hub`. The pattern gates split by the PR/MR **head branch** (passed via `--head`): a
-`review/EP-*` head is a front-half review PR — Conventional-Commits commit subjects, a
+`review/EP-*` head is a Shape review PR — Conventional-Commits commit subjects, a
 `review: <artifact> (EP-<slug>)` title, and the hub artifact-review template body; **any other head is
 a tooling/code change to the hub itself** and follows the `code` convention (a Conventional-Commits
 title + the code task template), so a PR that changes the hub's own workflows/checks can pass.
@@ -370,7 +414,7 @@ line). Code repos run the same three with `--profile code` inside the main `yad-
 
 Not a CI gate — a **harness hook**, and the only piece of yadflow that runs *inside* an agent's tool
 loop. It exists because of the gap #171 reported: `checks/ledger-guard.sh` is correct and blocking,
-but it speaks at CI time. An agent that hand-edits `epics/*/.sdlc/state.json` in bridge mode learns
+but it speaks at CI time. An agent that hand-edits `epics/*/.sdlc/state.json` in verified mode learns
 twenty minutes later, from a FAIL with nothing connecting cause to effect, and by then the write must
 be reverted before the review PR/MR can go green.
 
@@ -410,7 +454,7 @@ logic is unit-tested (`cli/hook.mjs`, `cli/test.mjs`) instead of living in bash.
 - **Slugs are case-folded**, as the gate folds them. On a case-insensitive filesystem `epics/ep-x/…`
   and `epics/EP-X/…` are the same file, so a byte-exact compare would let a mutation be laundered as
   a creation.
-- Bridge-gated by the same `isBridgeHub` predicate the CLI and the wiring read (#186): without the
+- Verified-only by the same `isVerifiedLedger` predicate the CLI and the wiring read (#186): without the
   bridge the ledger is locally owned, the hand-edit the authoring skills describe is correct, and
   nothing is wired or blocked.
 
@@ -461,7 +505,7 @@ The settings file is the team's, so the rules around that one entry are delibera
 `.claude` is the only IDE target wired: it is the only one with a defined hook protocol. Other
 targets get the script, and the contract above is what they would wire by hand.
 
-`yad doctor` reports the guard on a bridge hub, and distinguishes the three states that matter — it
+`yad doctor` reports the guard on a verified hub, and distinguishes the three states that matter — it
 reads the same persisted `ideTargets` the wiring reads, so every gap it names is one the command it
 names can actually close:
 

package/skills/yad-checks/templates/checks/build-test-lint.sh

@@ -1,26 +1,44 @@
 #!/usr/bin/env bash
 # build / test / lint gate (Phase 3 build plan §C).
 # Standard quality stage: lint, build, and tests that actually exercise behavior (not just pass).
-# Delegates to the repo's npm scripts so each repo owns the specifics.
+# Delegates to the package manager named by package.json so each repo owns the specifics.
 set -euo pipefail
 
+YAD_CHECKS_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+readonly YAD_CHECKS_DIR
+# shellcheck source-path=SCRIPTDIR
+# shellcheck source=package-manager.sh
+source "$YAD_CHECKS_DIR/package-manager.sh"
+# Two assignments on purpose: nested inside another $(...), a failing yad_package_manager_spec would
+# be swallowed, and the gate would fall back to lockfile detection and PASS on a package.json it
+# had just rejected. Each step fails the gate on its own under `set -e`.
+package_manager_spec="$(yad_package_manager_spec)"
+package_manager="$(yad_detect_package_manager "$package_manager_spec")"
+# `npm`, `pnpm`, or `corepack npm` for a pinned npm — see yad_package_manager_command.
+run_with_words="$(yad_package_manager_command "$package_manager_spec" "$package_manager")"
+read -r -a run_with <<< "$run_with_words"
+
 echo "[build/test/lint] lint…"
-npm run --silent lint
+"${run_with[@]}" run --silent lint
 echo "[build/test/lint] build…"
-npm run --silent build
+"${run_with[@]}" run --silent build
 
 # Worker cap: when YAD_TEST_MAX_WORKERS is set AND the repo's test script is jest/vitest (the
 # runners that accept --maxWorkers), forward it to bound CI test concurrency. For any other runner
 # (node --test, mocha, …) it is a deliberate no-op so the gate never breaks on an unknown flag.
+# npm needs the `--` separator to hand the flag to the script; pnpm (7+) forwards a literal `--` to
+# the script instead, where jest reads `--maxWorkers=N` as a test-path pattern and finds no tests.
 extra=""
 if [ -n "${YAD_TEST_MAX_WORKERS:-}" ]; then
-  case "$(npm pkg get scripts.test 2>/dev/null || true)" in
-    *jest*|*vitest*) extra="-- --maxWorkers=${YAD_TEST_MAX_WORKERS}" ;;
+  case "$(node --input-type=module -e 'import fs from "node:fs"; const p=JSON.parse(fs.readFileSync("package.json", "utf8").replace(/^\uFEFF/, "")); process.stdout.write(p.scripts?.test || "")' 2>/dev/null || true)" in
+    *jest*|*vitest*)
+      if [ "$package_manager" = "pnpm" ]; then extra="--maxWorkers=${YAD_TEST_MAX_WORKERS}"; else extra="-- --maxWorkers=${YAD_TEST_MAX_WORKERS}"; fi
+      ;;
   esac
 fi
 echo "[build/test/lint] test…"
-# Intentional word-splitting: $extra is either empty or `-- --maxWorkers=N`.
+# Intentional word-splitting: $extra is empty, `-- --maxWorkers=N` (npm), or `--maxWorkers=N` (pnpm).
 # shellcheck disable=SC2086
-npm run --silent test $extra
+"${run_with[@]}" run --silent test $extra
 
 echo "PASS [build/test/lint]: lint, build, and tests all green."

package/skills/yad-checks/templates/checks/epic-open.sh

@@ -3,7 +3,7 @@
 # is `shipped`. A SEALED epic's artifacts are the final, approved description of shipped behaviour — so
 # new behaviour must NOT be added to it; it belongs in a NEW threaded change-epic whose re-authored
 # stories/test-cases describe the change. This gate FAILs any non-maintenance commit whose owning epic
-# is sealed, forcing the front half to stay current (staleness becomes unshippable).
+# is sealed, forcing Shape to stay current (staleness becomes unshippable).
 #
 # The owning epic lives in the PRODUCT repo (via specs/<story>/link.md `product-repo`). When it is not
 # reachable from CI, the seal cannot be read, so the commit PASSes with a note (degraded, fail-open here

package/skills/yad-checks/templates/checks/install-deps.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Deterministic CI dependency installation selected by package.json#packageManager.
+set -euo pipefail
+
+YAD_CHECKS_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+readonly YAD_CHECKS_DIR
+# shellcheck source-path=SCRIPTDIR
+# shellcheck source=package-manager.sh
+source "$YAD_CHECKS_DIR/package-manager.sh"
+
+package_manager_spec="$(yad_package_manager_spec)"
+package_manager="$(yad_detect_package_manager "$package_manager_spec")"
+
+case "$package_manager" in
+  npm)
+    if [ ! -f "$YAD_NPM_LOCKFILE" ] && [ ! -f "$YAD_NPM_SHRINKWRAP" ]; then
+      echo "FAIL [install-deps]: npm requires package-lock.json or npm-shrinkwrap.json." >&2
+      exit 1
+    fi
+    if [[ "$package_manager_spec" == npm@* ]]; then
+      yad_require_corepack
+      corepack enable
+      yad_corepack_prepare "$package_manager_spec"
+      # npm's shim is not enabled by Corepack, so dispatch it explicitly through Corepack — the same
+      # `corepack npm` the gate uses for lint/build/test, so package.json#packageManager selects the
+      # npm version end to end instead of the Node image's ambient npm binary.
+      corepack npm ci
+    else
+      npm ci
+    fi
+    ;;
+  pnpm)
+    if [ ! -f "$YAD_PNPM_LOCKFILE" ]; then
+      echo "FAIL [install-deps]: pnpm requires pnpm-lock.yaml." >&2
+      exit 1
+    fi
+    if [[ "$package_manager_spec" != pnpm@* ]]; then
+      echo "FAIL [install-deps]: pnpm CI requires an exact package.json#packageManager value (for example pnpm@9.15.0)." >&2
+      exit 1
+    fi
+    yad_require_corepack
+    corepack enable
+    yad_corepack_prepare "$package_manager_spec"
+    pnpm install --frozen-lockfile
+    ;;
+esac

package/skills/yad-checks/templates/checks/ledger-guard.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # ledger-guard gate.
-# In BRIDGE mode the gate ledger is CI-owned: only the yad gate-sync bot may change the
+# In verified mode the gate ledger is CI-owned: only the yad gate-sync bot may change the
 # machine-written gate-state files. A commit on a review PR by anyone else that modifies them is
 # rejected — the human keeps the artifact, CI keeps the ledger. This makes "CI is the sole writer of
 # the ledger" a mechanical guarantee instead of a convention.
@@ -20,21 +20,22 @@
 # distinguishes CI-generated commits. A spoofed-author commit that is not Verified is treated as a
 # human edit and rejected.
 #
-# Scope: enforced ONLY when the bridge is enabled — hub.json carries BOTH a `platform` and
-# `bridge_enabled` (or the legacy `bridge`) true, the same predicate `isBridge` (cli/gate.mjs) and
-# `hubActions` (cli/plan.mjs) apply. Without the bridge (file-only / non-bridge, or a platform-less
-# hub) humans legitimately write the ledger locally, so the gate is a no-op.
+# Scope: enforced ONLY when the ledger is verified — hub.json carries BOTH a `platform` and either
+# `ledger: "verified"` or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or the
+# legacy `bridge`) true. That is the same predicate `isVerifiedLedger` (cli/manifest.mjs) and
+# `hubActions` (cli/plan.mjs) apply. With a local ledger — or a platform-less hub — humans
+# legitimately write the ledger themselves, so the gate is a no-op.
 #
 # Degradation: a base ref that cannot be resolved FAILs closed; no platform (cannot read the Verified
 # badge) WARNs and waives the signature half — the same stance verified-commits takes.
 set -euo pipefail
 
 # ---- bridge gate: only CI-owned ledgers are guarded -------------------------------------------
-# The predicate is BOTH a platform and the bridge flag, exactly as `isBridge` (cli/gate.mjs) and
+# The predicate is BOTH a platform and the verified ledger flag, exactly as `isVerifiedLedger` (`cli/manifest.mjs`) and
 # `hubActions` (cli/plan.mjs) define it. Requiring the flag alone put this gate out of step with every
-# other bridge detector (issue #186): a hub carrying `bridge_enabled: true` with no `platform` would
+# other ledger reader (issue #186): a hub carrying `bridge_enabled: true` with no `platform` would
 # have its human ledger commits rejected here while the CLI, reading the same file, called it
-# file-only and kept the LOCAL write path — no CI writer and no permitted human writer, so no gate
+# local and kept the LOCAL write path — no CI writer and no permitted human writer, so no gate
 # could advance. Reachable through a stale install (platform set, script wired, platform later
 # nulled), not through `yad setup`, which derives both from one value.
 #
@@ -45,7 +46,7 @@ set -euo pipefail
 # Matched at the ROOT LEVEL only. The shared `default_branch` read below is depth-blind, and that is
 # survivable there — a false match yields a bogus branch name and the gate fails loudly. Here it is
 # not: a nested `"bridge": true` (say under `review`) would silently ENABLE this gate on a hub whose
-# `isBridge` is false, recreating the exact no-writer deadlock #186 is about, from the other side. So
+# `isVerifiedLedger` is false, recreating the exact no-writer deadlock #186 is about, from the other side. So
 # the nesting is stripped rather than ignored: peel the outermost braces, then delete innermost
 # objects/arrays until none remain, leaving only root-level pairs to match against. Not a JSON parser
 # — a value containing a literal brace would confuse it — but hub.json is machine-written and the
@@ -67,9 +68,37 @@ done
 # SIGPIPE-under-pipefail problem this avoids).
 hub_str() { sed -nE "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p" <<< "$HUB_ROOT"; }
 hub_true() { grep -Eq "\"$1\"[[:space:]]*:[[:space:]]*true" <<< "$HUB_ROOT"; }
+# Is the key present with a STRING value at all, empty included? `hub_str` cannot answer this: it
+# returns nothing both for a missing key and for an empty one.
+hub_has_str() { grep -Eq "\"$1\"[[:space:]]*:[[:space:]]*\"" <<< "$HUB_ROOT"; }
 
-if [ ! -f "$HUB" ] || [ -z "$(hub_str platform)" ] || { ! hub_true bridge_enabled && ! hub_true bridge; }; then
-  echo "PASS [ledger-guard]: bridge not enabled — the ledger is locally owned, nothing to guard."
+# READ ORDER, identical to `isVerifiedLedger` (cli/manifest.mjs) — the two must never disagree:
+#   1. `ledger`, if hub.json carries it — shape 2 and later. "verified" and nothing else.
+#   2. otherwise the old booleans `bridge_enabled` (canonical) or `bridge` (older still).
+# A platform is required either way, for the reason in the header.
+#
+# Step 2 is NOT dead weight. This script is committed inside the user's repo and refreshed by
+# `yad update`, which is a separate act from `yad migrate` — so an un-migrated hub.json (no `ledger`
+# key at all) will be read by this version of the script, and it has to keep saying "verified".
+# cli/test-checks.mjs runs a table of hub.json variants through this script AND through the JS
+# reader and asserts they agree on every row.
+# Written as if/else rather than `cmd; verified=$?`: under the `set -e` above, a bare failing test
+# would EXIT the script instead of recording a false — and exiting mid-guard is indistinguishable
+# from passing, so the gate would silently stop guarding.
+# PRESENCE of the key decides which branch runs, not whether its value is non-empty. `"ledger": ""`
+# is a present key with a string value: the JS reader stops there and answers "local", so this must
+# too. Testing `-n` instead sent an empty value down to the old booleans and the two readers gave
+# OPPOSITE answers — the guard rejecting human writes while the CLI kept the local path open, which
+# is the no-writer deadlock of #186 reached from a third direction.
+verified=no
+if hub_has_str ledger; then
+  if [ "$(hub_str ledger)" = "verified" ]; then verified=yes; fi
+elif hub_true bridge_enabled || hub_true bridge; then
+  verified=yes
+fi
+
+if [ ! -f "$HUB" ] || [ -z "$(hub_str platform)" ] || [ "$verified" != yes ]; then
+  echo "PASS [ledger-guard]: the ledger is locally owned (ledger: local) — nothing to guard."
   exit 0
 fi
 
@@ -159,7 +188,7 @@ trusted_bot() {
 # A brand-new epic's ledger has no CI author. `gate ci` only ADVANCES an existing chain — it bails on
 # a missing state.json ("the review branch is cut from the default branch, so it should carry it") and
 # writes only at merge, on the default branch — and the engine itself reads a missing state.json as
-# "not seeded yet". `gate open` writes nothing in bridge mode, and `checkpoint` stages back-half
+# "not seeded yet". `gate open` writes nothing in verified mode, and `checkpoint` stages Build
 # ledgers only. So the seed the authoring skills write (yad-epic / yad-change / yad-analysis /
 # yad-discovery / yad-stub) can reach the trunk ONLY through the first review PR/MR — the one place
 # this gate runs. Guarding it there makes the documented flow unshippable on a protected trunk, so an