yadflow 3.18.0 → 3.19.0-next.2

package/skills/yad-checks/templates/checks/package-manager.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# Shared package-manager detection for the dependency installer and build/test/lint gate.
+# The standard package.json `packageManager` field is authoritative. A pnpm lockfile is a
+# compatibility fallback for local gate execution, but CI installation requires an exact pnpm
+# version so a generated workflow never silently changes toolchains.
+
+readonly YAD_PACKAGE_JSON="package.json"
+readonly YAD_PNPM_LOCKFILE="pnpm-lock.yaml"
+readonly YAD_NPM_LOCKFILE="package-lock.json"
+readonly YAD_NPM_SHRINKWRAP="npm-shrinkwrap.json"
+
+# Corepack is the Node tool that downloads and activates the declared version. It is bundled with
+# Node 18 through 24 (Node 25+ dropped it), and a copy older than 0.31 — before Node 18.20.7 /
+# 20.19 / 22.14 — predates the 2025 npm registry key rotation and rejects anything published since
+# with a raw "Cannot find matching keyid". A declared packageManager without a working Corepack must
+# say so instead of dying with "command not found" or that error in the middle of the job.
+readonly YAD_COREPACK_LINES="set YAD_NODE_VERSION to a current 20, 22 or 24 line, or install a current Corepack first (npm install -g corepack)"
+yad_require_corepack() {
+  if command -v corepack >/dev/null 2>&1; then return 0; fi
+  echo "FAIL [package-manager]: package.json#packageManager is set but corepack is not on PATH (Node 25+ no longer bundles it) — $YAD_COREPACK_LINES." >&2
+  return 1
+}
+# `corepack prepare` with the guidance attached to every way it can fail: a stale Corepack (the
+# keyid error above), no network, or a version the registry does not have.
+yad_corepack_prepare() {
+  local spec="$1"
+  if corepack prepare "$spec" --activate; then return 0; fi
+  echo "FAIL [package-manager]: corepack could not activate $spec. A Corepack older than 0.31 cannot verify packages signed after the 2025 npm registry key rotation — $YAD_COREPACK_LINES; otherwise check that the version exists and the registry is reachable." >&2
+  return 1
+}
+
+# The command that runs the declared manager. Corepack activates a pinned npm but never shims it
+# (`corepack enable` covers pnpm and yarn only), so a bare `npm` would be the Node image's ambient
+# npm; a pinned npm is dispatched through Corepack instead, for `npm ci` and for the gate's `run`s.
+# Prints the words space-separated so callers can `read -r -a` them into an array (bash 3.2 has no
+# mapfile); the words are fixed literals, never repo input.
+yad_package_manager_command() {
+  local spec="$1" manager="$2"
+  if [[ "$spec" == npm@* ]]; then
+    yad_require_corepack || return 1
+    printf '%s\n' "corepack npm"
+  else
+    printf '%s\n' "$manager"
+  fi
+}
+
+yad_validate_exact_package_manager_spec() {
+  local spec="$1"
+  # The JavaScript is deliberately single-quoted so Bash cannot expand its template literals.
+  # shellcheck disable=SC2016
+  YAD_PACKAGE_MANAGER_SPEC="$spec" node --input-type=module -e '
+    const spec = process.env.YAD_PACKAGE_MANAGER_SPEC;
+    const at = spec.indexOf("@");
+    const version = spec.slice(at + 1);
+    // The Corepack integrity suffix is `+<algorithm>.<hex digest>`: it hashes the download with the
+    // named algorithm and compares the LOWERCASE hex string byte for byte. Every algorithm Corepack
+    // has written or accepts is listed with its digest length; anything else is not a Corepack
+    // suffix and fails closed.
+    const COREPACK_DIGEST_HEX_LENGTH = { sha1: 40, sha224: 56, sha256: 64, sha384: 96, sha512: 128 };
+    const exactSemver = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+    const match = exactSemver.exec(version);
+    const invalidNumericPrerelease = match?.[4]?.split(".").some(
+      identifier => /^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith("0"),
+    );
+    const isCorepackIntegrity = (build) => {
+      const [algorithm, digest, ...rest] = build.split(".");
+      const length = COREPACK_DIGEST_HEX_LENGTH[algorithm];
+      return rest.length === 0 && length !== undefined && new RegExp(`^[0-9a-f]{${length}}$`).test(digest ?? "");
+    };
+    const invalidBuildMetadata = match?.[5] !== undefined && !isCorepackIntegrity(match[5]);
+    if (!match || match[0] !== version || invalidNumericPrerelease || invalidBuildMetadata) {
+      const algorithms = Object.keys(COREPACK_DIGEST_HEX_LENGTH).join("|");
+      process.stderr.write(`FAIL [package-manager]: packageManager ${JSON.stringify(spec)} must name an exact semantic version, optionally followed by the Corepack integrity suffix +<${algorithms}>.<lowercase hex digest>.\n`);
+      process.exit(1);
+    }
+  '
+}
+
+yad_package_manager_spec() {
+  if [ ! -f "$YAD_PACKAGE_JSON" ]; then
+    echo "FAIL [package-manager]: package.json is missing." >&2
+    return 1
+  fi
+  # The JavaScript is deliberately single-quoted so Bash cannot expand its template literals.
+  # shellcheck disable=SC2016
+  node --input-type=module -e '
+    import fs from "node:fs";
+    let pkg;
+    // npm strips a UTF-8 byte-order mark before parsing (Windows editors often write one); do the same
+    // so a manifest npm itself installs from is not rejected here.
+    try { pkg = JSON.parse(fs.readFileSync("package.json", "utf8").replace(/^\uFEFF/, "")); }
+    catch { process.stderr.write("FAIL [package-manager]: package.json is not valid JSON.\n"); process.exit(1); }
+    if (pkg === null || typeof pkg !== "object" || Array.isArray(pkg)) {
+      process.stderr.write("FAIL [package-manager]: package.json must be a JSON object.\n"); process.exit(1);
+    }
+    if (pkg.packageManager !== undefined && typeof pkg.packageManager !== "string") {
+      process.stderr.write("FAIL [package-manager]: packageManager must be a string.\n"); process.exit(1);
+    }
+    if (pkg.packageManager && /[\r\n]/.test(pkg.packageManager)) {
+      process.stderr.write(`FAIL [package-manager]: packageManager ${JSON.stringify(pkg.packageManager)} must name an exact semantic version.\n`);
+      process.exit(1);
+    }
+    process.stdout.write(pkg.packageManager || "");
+  '
+}
+yad_detect_package_manager() {
+  local spec="${1-}"
+  case "$spec" in
+    "")
+      # No declaration: npm, exactly as before this field was read — UNLESS the repo carries a pnpm
+      # lockfile and no npm one. A repo with both (a stale package-lock.json after a migration is
+      # common) keeps the historical npm path rather than silently flipping toolchains.
+      if [ -f "$YAD_PNPM_LOCKFILE" ] && [ ! -f "$YAD_NPM_LOCKFILE" ] && [ ! -f "$YAD_NPM_SHRINKWRAP" ]; then
+        printf '%s\n' "pnpm"
+      else
+        printf '%s\n' "npm"
+      fi
+      ;;
+    npm@*)
+      yad_validate_exact_package_manager_spec "$spec" || return 1
+      printf '%s\n' "npm"
+      ;;
+    pnpm@*)
+      yad_validate_exact_package_manager_spec "$spec" || return 1
+      printf '%s\n' "pnpm"
+      ;;
+    *)
+      # yarn/bun declared for local use while CI installs from an npm lockfile was green before this
+      # field was read; keep that repo on the historical npm path, with a warning, rather than
+      # failing every PR on upgrade. Without an npm lockfile there is nothing to fall back to.
+      if [ -f "$YAD_NPM_LOCKFILE" ] || [ -f "$YAD_NPM_SHRINKWRAP" ]; then
+        echo "WARN [package-manager]: packageManager '$spec' is not supported by the gate (npm, pnpm); an npm lockfile is present, so continuing on the historical npm path." >&2
+        printf '%s\n' "npm"
+      else
+        echo "FAIL [package-manager]: unsupported packageManager '$spec' (supported: npm, pnpm)." >&2
+        return 1
+      fi
+      ;;
+  esac
+}

package/skills/yad-checks/templates/checks/reconcile-debt-check.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
-# reconcile-debt gate (Phase 6 — hotfix debt). A hotfix may ship code BEFORE its front gates approve
-# (ship-first), but it opens a reconcile-debt.json entry: the front artifacts do not yet describe what
+# reconcile-debt gate (Phase 6 — hotfix debt). A hotfix may ship code BEFORE its Shape gates approve
+# (ship-first), but it opens a reconcile-debt.json entry: the Shape artifacts do not yet describe what
 # is in production. That debt must be PAID (artifacts updated + a regression test added) before the NEXT
 # normal change on the same feature thread can ship. This gate FAILs a non-maintenance commit whose
 # owning epic is on a thread carrying an OPEN debt that this epic does not itself own.
@@ -148,7 +148,7 @@ while IFS= read -r sha; do
   if [ -n "$blockers" ]; then
     echo "FAIL [reconcile-debt]: thread ${thread} carries OPEN hotfix debt:"
     printf '%s\n' "$blockers" | sed 's/^/    /'
-    echo "  -> Pay it first: update the front artifacts + add the regression test, then mark the"
+    echo "  -> Pay it first: update the Shape artifacts + add the regression test, then mark the"
     echo "     reconcile-debt.json entry status: paid. The thread is frozen for new changes until then."
     rc=1
     continue

package/skills/yad-checks/templates/github/yad-checks.yml

@@ -34,12 +34,33 @@ jobs:
     if: github.event.action != 'edited'
     env:
       YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
+      YAD_NODE_VERSION: ${{ vars.YAD_NODE_VERSION || '22' }} # repo variable; a current 20, 22 or 24 line (Node 25+ has no Corepack)
+      NX_BASE: ${{ github.event.pull_request.base.sha }}
+      NX_HEAD: ${{ github.event.pull_request.head.sha }}
+      COREPACK_HOME: ${{ github.workspace }}/.corepack-cache # pinned-manager downloads, cached below
     steps:
       - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
+        with:
+          fetch-depth: 0
+          filter: blob:none
       - uses: actions/setup-node@v4
-        with: { node-version: "20", cache: "npm" }
-      - run: npm ci # install deps so the real lint/build/test toolchain can run (mirrors the GitLab template)
+        with:
+          node-version: ${{ env.YAD_NODE_VERSION }}
+      # Dependency cache for either manager: npm's ~/.npm, pnpm's content-addressable store, and the
+      # Corepack home where `corepack prepare` keeps the pinned manager (otherwise re-downloaded from
+      # the registry on every job, even when the dependency cache hits). Keyed on the lockfiles AND
+      # package.json, since a packageManager bump changes no lockfile. setup-node's own `cache:` must
+      # name the manager up front (and needs pnpm on PATH before it runs), which package.json only
+      # decides later — so cache the directories directly.
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            ~/.local/share/pnpm/store
+            ${{ env.COREPACK_HOME }}
+          key: yad-deps-${{ runner.os }}-node${{ env.YAD_NODE_VERSION }}-${{ hashFiles('package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'package.json') }}
+          restore-keys: yad-deps-${{ runner.os }}-node${{ env.YAD_NODE_VERSION }}-
+      - run: bash checks/install-deps.sh
       - run: bash checks/build-test-lint.sh
 
   # Phase 6 — feature-thread gates. lineage-check: the change links a real threaded epic. epic-open:

package/skills/yad-checks/templates/github/yad-hub-checks.yml

@@ -1,6 +1,6 @@
 # yad-managed: yad-checks
 # Pattern gates for the PRODUCT HUB. They run with `--profile hub` and split by head branch:
-#   review/EP-* PRs are front-half artifact-review vehicles — a `review: <artifact> (EP-<slug>)` title
+#   review/EP-* PRs are Shape artifact-review vehicles — a `review: <artifact> (EP-<slug>)` title
 #     and the hub artifact-review template body.
 #   every other PR is a tooling/code change to the hub itself — a Conventional-Commits title and the
 #     code task template body (same convention the code repos use).
@@ -27,7 +27,7 @@ jobs:
 
   # Pass the title via env (never interpolate untrusted ${{ }} into a run line — injection-safe).
   # fetch-depth: 0 + the base ref give us the PR's changed paths, so the gate can reject an artifact
-  # change (epics/**) riding a non-review head past the front-half review with a plain code title.
+  # change (epics/**) riding a non-review head past the Shape review with a plain code title.
   pr-title:
     runs-on: ubuntu-latest
     env:

package/skills/yad-checks/templates/github/yad-verified-commits.yml

@@ -1,5 +1,5 @@
 # yad-managed: yad-checks
-# verified-commits gate for the PRODUCT HUB: every PR (including the front-half review/EP-* PRs)
+# verified-commits gate for the PRODUCT HUB: every PR (including the Shape review/EP-* PRs)
 # must contain only commits whose signature the platform marks Verified AND whose author email is a
 # known identity (.sdlc/verified-authors — generated by `yad check --fix` from the hub roster).
 # Standalone workflow so it never collides with the hub-flavored yad-checks workflow.

package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml

@@ -4,7 +4,7 @@
 stages: [spec-link, contract-check, build-test-lint, verified-commits]
 
 default:
-  image: node:20
+  image: node:${YAD_NODE_VERSION}
 
 .mr_only:
   rules:
@@ -12,6 +12,9 @@ default:
 
 variables:
   GIT_DEPTH: "0"   # full history so the gates can diff against the target branch
+  YAD_NODE_VERSION: "22" # override with a project/group CI variable (a current 20, 22 or 24 line; Node 25+ has no Corepack)
+  NX_BASE: $CI_MERGE_REQUEST_DIFF_BASE_SHA
+  NX_HEAD: $CI_COMMIT_SHA
 
 spec-link:
   stage: spec-link
@@ -28,7 +31,10 @@ contract-check:
 build-test-lint:
   stage: build-test-lint
   extends: .mr_only
+  variables:
+    YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
   script:
+    - bash checks/install-deps.sh
     - bash checks/build-test-lint.sh
 
 # Needs a CI/CD variable GITLAB_TOKEN (or SDLC_API_TOKEN) with read_api scope — CI_JOB_TOKEN cannot

package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml

@@ -14,10 +14,19 @@
 # top-level `default:` merges into the HOST root pipeline; if the host already sets a top-level
 # `image:`, GitLab rejects the whole config ("image is defined in top-level and 'default:' entry").
 # Putting them on the anchor scopes them to the gate jobs (which all `extends: .sdlc_mr_only`) and
-# never touches the host root.
+# never touches the host root. The same goes for the gate jobs' own variables (`YAD_NODE_VERSION`,
+# `NX_BASE`, `NX_HEAD`): an included top-level `variables:` merges into the host's globals, where a
+# generic name like NX_BASE can collide with one the host already computes for its own Nx jobs.
+# Only `GIT_DEPTH` stays global — the gates need the full history and a host that sets its own wins.
 
 .sdlc_mr_only:
-  image: node:20
+  image: node:${YAD_NODE_VERSION}
+  variables:
+    # A project/group CI/CD variable overrides a YAML value, so YAD_NODE_VERSION can be changed in
+    # project settings without editing the managed fragment (a current 20, 22 or 24 line; Node 25+ has no Corepack).
+    YAD_NODE_VERSION: "22"
+    NX_BASE: $CI_MERGE_REQUEST_DIFF_BASE_SHA
+    NX_HEAD: $CI_COMMIT_SHA
   # Runner selection. These jobs need a docker/dind executor; on instances whose runners are all
   # tag-locked (run_untagged: false) an untagged image job never starts. Set the YAD_RUNNER_TAGS
   # CI/CD variable (Settings → CI/CD → Variables, e.g. `dind_runner`) to route them — it lives in
@@ -50,7 +59,7 @@ yad-build-test-lint:
   variables:
     YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
   script:
-    - npm ci
+    - bash checks/install-deps.sh
     - bash checks/build-test-lint.sh
 
 # Phase 6 — feature-thread gates (lineage / seal / hotfix-debt). Build on spec-link's story->epic

package/skills/yad-checks/templates/gitlab/yad-hub-checks.gitlab-ci.yml

@@ -3,7 +3,7 @@
 # .gitlab-ci.yml via:
 #   include:
 #     - local: '.gitlab/ci/yad-hub-checks.yml'
-# MRs run with `--profile hub` and split by source branch: review/EP-* MRs are front-half artifact-
+# MRs run with `--profile hub` and split by source branch: review/EP-* MRs are Shape artifact-
 # review vehicles (a `review: <artifact> (EP-<slug>)` title + the hub artifact-review template body);
 # every other MR is a tooling/code change to the hub itself and follows the code convention (a
 # Conventional-Commits title + the code task template body). The source branch is passed via --head so
@@ -28,7 +28,7 @@ yad-hub-commit-message:
     - bash checks/commit-message.sh --profile hub "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
 
 # GIT_DEPTH: 0 (above) gives the changed paths, so the gate can reject an artifact change (epics/**)
-# riding a non-review source branch past the front-half review with a plain code title/template.
+# riding a non-review source branch past the Shape review with a plain code title/template.
 yad-hub-pr-title:
   extends: .yad_hub_mr_only
   needs: []

package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml

@@ -3,7 +3,7 @@
 # .gitlab-ci.yml via:
 #   include:
 #     - local: '.gitlab/ci/yad-verified-commits.yml'
-# Every MR (including the front-half review/EP-* MRs) must contain only commits whose signature the
+# Every MR (including the Shape review/EP-* MRs) must contain only commits whose signature the
 # platform marks Verified AND whose author email is a known identity (.sdlc/verified-authors).
 #
 # Needs a CI/CD variable GITLAB_TOKEN (or SDLC_API_TOKEN) with read_api scope — CI_JOB_TOKEN cannot

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # ledger-guard HARNESS HOOK — the local half of the CI gate of the same name (#171).
 #
-# The gate ledger is CI-owned in bridge mode: `checks/ledger-guard.sh` rejects any non-bot commit
+# 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,hub-prs}.json` or `epics/*/reviews/*.md`.
 # 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`).

package/skills/yad-commit/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: yad-commit
-description: 'Build-half 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, 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-half helper)
+# 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

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

@@ -10,7 +10,7 @@ and/or web pages — inside a design tool such as **Figma**, alongside the Markd
 (`ui-design.md` / `DESIGN.md`). This skill **connects** a design tool to the product hub and records
 *how* to reach it (the tool, the project/file references, which MCP renders it) — never a credential.
 
-This is **setup/maintenance**, not a gated front state — it never touches `.sdlc/state.json` or any
+This is **setup/maintenance**, not a gated Shape step — it never touches `.sdlc/state.json` or any
 epic's approvals. It only writes the project-wide design registry. `yad-ui` consumes it: when a tool is
 connected and its MCP is available, the `ux-designer` lens **generates** screens into the tool (or
 **links** an existing human-made design and reads it back); when nothing is connected, `yad-ui` runs

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

@@ -10,7 +10,7 @@ description: 'Connects a docs/Pages publishing target to the product hub so the
 instead of only committing its source. This skill **connects** a publishing target to the product hub
 and records *how* to reach it (the platform, the publish scope, the base path) — never a credential.
 
-This is **setup/maintenance**, not a gated front state — it never touches `.sdlc/state.json` or any
+This is **setup/maintenance**, not a gated Shape step — it never touches `.sdlc/state.json` or any
 epic's approvals. It only writes the project-wide docs registry. `yad-docs` / `yad-docs-overview`
 consume it: when a target is connected, they theme + generate the site and drive `yad docs deploy`;
 when nothing is connected (`target: "none"`), they still generate and **npm-build** the site but stop

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

@@ -11,15 +11,15 @@ stories that contradict or duplicate what is built. This skill **connects** code
 hub and caches an AI-readable picture of each. It is the product → code half of the 2-way link (the
 code → product half is the existing `link.md` back-pointer each spec carries).
 
-This is **setup/maintenance**, not a gated front state — it never touches `.sdlc/state.json` or any
+This is **setup/maintenance**, not a gated Shape step — it never touches `.sdlc/state.json` or any
 epic's approvals. It only writes the project-wide registry and the per-repo context cache.
 
 ## Conventions
 
 - `{project-root}` resolves from the project working directory (the **product hub**).
-- The **product repo is the front-phase toolchain hub** (`config.yaml` `code_context`): Repomix (and
+- The **product repo is the Shape phase toolchain hub** (`config.yaml` `code_context`): Repomix (and
   Impeccable, later) are installed/run **here** and target the connected code repos **by path**. The
-  code repos themselves need no install for this. (The build-half CI gates are the exception — they
+  code repos themselves need no install for this. (The Build CI gates are the exception — they
   live inside each code repo; see `yad-checks`.)
 - **Repomix is a true CLI subprocess** (Phase 0 / RESEARCH-NOTES §3): `npx repomix@latest [flags]` —
   NOT a slash-command. It secret-scans by default (Secretlint).
@@ -90,7 +90,7 @@ Feed the pack to the AI with the **"describe what exists, do not invent"** instr
 (`references/code-context.md`) and write `{project-root}/.sdlc/code-context/<repo>/code-map.md`: a small
 index of **stack/conventions, entry points, public endpoints/APIs, events, data models/entities, and
 module layout**. Mark anything unclear `<!-- unverified: ... -->`; never fill gaps with invented
-behaviour. This is the cheap artifact every front phase loads by default (the full pack is read only
+behaviour. This is the cheap artifact every Shape phase loads by default (the full pack is read only
 when a phase needs depth).
 
 ### Step 4 — Record the repo in the registry
@@ -122,7 +122,7 @@ new repo later is the same `connect` action.
 
 ### Step 5 — Report
 Report the connected repo, its `platform`, the pack + code-map paths, the secret-scan result, and that
-the front phases will now load this repo's code-map. Nothing auto-advances; this is setup.
+the Shape phases will now load this repo's code-map. Nothing auto-advances; this is setup.
 
 ## Other actions
 
@@ -139,20 +139,37 @@ the front phases will now load this repo's code-map. Nothing auto-advances; this
 - **`disconnect`** — remove the repo from the registry and delete its cache dir. Leaves the **code repo
   itself untouched**.
 
-## Hub detection + reviewer roster (the front-half review bridge)
+## Hub detection + reviewer roster (the Shape review bridge)
 
-The hub is itself a git repo on a platform. These actions record that so the front-half review/comment/
+The hub is itself a git repo on a platform. These actions record that so the Shape review/comment/
 approval cycle can run through a real PR/MR on the hub (`yad-review-gate` + `yad-hub-bridge`). They
 write only `{project-root}/.sdlc/hub.json` (`config.yaml` `hub.config`) — never an epic's state/approvals.
 
 - **`detect-hub`** — detect the hub's own platform and upsert `.sdlc/hub.json`. Run
   `git remote get-url origin` **on the hub** 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 `bridge_enabled` — **`true` only when a platform was
-  detected, `false` alongside `platform: null`** (preserve an existing roster). The two travel
-  together: bridge mode is a platform AND the flag (`isBridge`, `cli/gate.mjs`), and `yad setup`
-  derives both from one value, so writing the flag onto a platform-less hub creates a state no CLI
-  path can produce and the gates read differently (#186).
+  `git_url`, `default_branch`, `detectedAt`, and **all three of** `ledger`, `bridge_enabled` and
+  `bridge`:
+
+  | a platform was detected | no platform (`platform: null`) |
+  |---|---|
+  | `"ledger": "verified"`, `bridge_enabled: true`, `bridge: true` | `"ledger": "local"`, `bridge_enabled: false`, `bridge: false` |
+
+  (Preserve an existing roster.)
+
+  **`ledger` is the one that decides.** `isVerifiedLedger` (`cli/manifest.mjs`) reads it first and
+  falls back to the booleans only when it is absent — so on a project that has already run
+  `yad migrate`, writing `bridge_enabled: true` while leaving `"ledger": "local"` in place turns
+  verified mode ON in the file and OFF in the engine. Nothing would be wired, no guard would arm,
+  and the report would say it worked. Write all three, and keep them saying the same thing.
+
+  The booleans are still written because a check gate committed in the repo may predate
+  `yad update`; see `docs/migrations/shape-2.md`.
+
+  A platform and a verified ledger travel together: verified mode is a platform AND the switch
+  (`isVerifiedLedger`, `cli/manifest.mjs`), and `yad setup` derives both from one value, so marking a
+  platform-less hub verified creates a state no CLI path can produce and the gates read
+  differently (#186).
   Auth is the local user's own `gh`/`glab`/git; **store no tokens**. Idempotent — safe to re-run.
 - **`roster`** — set one roster entry mapping a platform `login` → SDLC `name` + `email` + a per-scope
   `roles` map (`roles: { hub: ["owner","reviewer"], <repo>: ["domain-owner", …] }`). Upsert by `login`;
@@ -166,11 +183,11 @@ write only `{project-root}/.sdlc/hub.json` (`config.yaml` `hub.config`) — neve
   connected repo's role); `yad roster grant|revoke <name> <repo> <role>`; `yad roster remove <login>`.
   A `domain-owner` grant/revoke keeps `repos.json` `domain_owners` in sync so the gate never drifts.
 
-If the hub has no remote (`platform: null`) or the bridge is disabled, the front-half gate runs
-file-only with no error — the bridge is purely additive.
+If the hub 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.
 
 ## Live on-demand (the third context layer)
-The cached pack + map are the default. When a front phase needs an **area** not in the map, it may
+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:
 ```bash
 npx repomix@latest --compress --include "<area globs>" --style markdown -o -

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

@@ -64,12 +64,12 @@ source: repomix
 <!-- the main directories/modules and what each owns -->
 ```
 
-The code-map is deliberately small so every front phase can load it cheaply. The full `pack.md` is read
+The code-map is deliberately small so every Shape phase can load it cheaply. The full `pack.md` is read
 only when a phase needs depth (the architecture phase, primarily).
 
 ## Layer 3 — live on-demand (a specific area, not a stale repo)
 
-When a front phase needs an area not captured in the code-map, it may re-pack that **slice** live,
+When a Shape phase needs an area not captured in the code-map, it may re-pack that **slice** live,
 scoped to the area, without writing the cache:
 
 ```bash

package/skills/yad-connect-repos/references/hub-config.md

@@ -1,6 +1,6 @@
 # Hub config — schema, detection, and the reviewer roster
 
-The hub config is the product hub's record of **its own** platform (so the front-half review/comment/
+The hub config is the product hub's record of **its own** platform (so the Shape review/comment/
 approval cycle can run through a real PR/MR on the hub) and the **reviewer roster** that maps a platform
 login to an SDLC name + role. It is a single object for the hub itself — the sibling of the per-repo
 `repos.json` registry (see `repos-registry.md`), kept separate so it never pollutes that array.
@@ -15,10 +15,13 @@ login to an SDLC name + role. It is a single object for the hub itself — the s
 
 ```json
 {
+  "schemaVersion": 2,                                         // the file's shape. Absent means 1 (rule 1). `yad migrate` moves it; see docs/migrations/shape-2.md
   "platform": "github",                                       // github | gitlab (from the hub's own remote host); null when local-only
   "git_url": "https://github.com/abdelrahmannasr/yadflow.git", // REQUIRED when platform is non-null (scopes auth + opens PRs); yad doctor warns YAD-CFG-005 if absent
   "default_branch": "main",
-  "bridge_enabled": true,                                     // open review PRs/MRs on the hub for front-half reviews; travels WITH platform — bridge mode is both (isBridge), so never true beside platform: null (#186)
+  "ledger": "verified",                                       // WHO WRITES THE LEDGER, and the one that decides: "verified" = CI only, signed; "local" = this machine. Travels WITH platform — verified is both (isVerifiedLedger), so never "verified" beside platform: null (#186)
+  "bridge_enabled": true,                                     // the older spelling of the same switch, kept so a check gate that predates `yad update` still reads it. Write it to MATCH `ledger`, never against it
+  "bridge": true,                                             // older still. Same rule
   "gate_sync_version": "3.15.3",                              // OPTIONAL exact pin for the wired gate-sync job; an exact 3.x.y, prereleases included (3.16.0-rc.1) — anything else is skipped. Omitted => the .sdlc/cli-version.json stamp if that qualifies, else floating 3
   "review": { "requireEngagement": false },                   // Review Companion: false (soft) counts bare approves but nudges; true counts only verified-engagement approvals
   "detectedAt": "2026-06-08",                                 // last detect-hub run (YYYY-MM-DD)
@@ -72,16 +75,27 @@ as the registry). `detect-hub` upserts `hub.json` in place — it is idempotent
 
 **`git_url` is required whenever `platform` is non-null.** `yad doctor` uses it to scope the auth
 probe to the hub's own host (an unscoped `glab auth status` fails on any unrelated broken instance),
-and the bridge/PR flow uses it to open PRs. Doctor flags its absence with a warn (`YAD-CFG-005`);
+and the verified ledger/PR flow uses it to open PRs. Doctor flags its absence with a warn (`YAD-CFG-005`);
 re-running `yad setup` backfills it from the origin remote (idempotent, non-interactive).
 
-## Bridge enable / degradation
+## Who writes the ledger, and what happens when it degrades
 
-- `bridge_enabled: true` **and** a non-null `platform` **and** `gh`/`glab` authenticated → the front-half
+The switch is read in this order — `isVerifiedLedger` (`cli/manifest.mjs`) and the bash copy in
+`checks/ledger-guard.sh` both do exactly this, and a test asserts they agree on every shape:
+
+1. **`ledger`**, whenever the key is present. `"verified"` and nothing else means verified; any other
+   value, including an empty string, means local.
+2. **otherwise** the older booleans `bridge_enabled`, then `bridge`.
+3. and a non-null `platform` is required either way — without one there is no Verified badge to read.
+
+So on a migrated project `ledger` wins, and writing a boolean that contradicts it changes nothing.
+Keep all three in step.
+
+- `ledger: "verified"` **and** a non-null `platform` **and** `gh`/`glab` authenticated → the Shape
   review opens a PR/MR on the hub and `yad-review-gate action: sync` pulls platform state into the ledger.
-- `bridge_enabled: false`, `platform: null`, or no/unauthenticated CLI → the gate falls back to the
-  existing **file-only** flow with no error. The file ledger is the source of truth in both modes.
-- The master switch `config.yaml` `hub.bridge: false` disables the bridge globally regardless of `hub.json`.
+- `ledger: "local"`, `platform: null`, or no/unauthenticated CLI → the gate falls back to the
+  existing **local** flow with no error. The file ledger is the source of truth in both modes.
+- The master switch `config.yaml` `hub.bridge: false` disables the verified ledger globally regardless of `hub.json`.
 
 ## Review Companion engagement (`review.requireEngagement`)
 
@@ -90,7 +104,7 @@ engagement gate. Each approval records `engagement: verified | none`. **Soft (`f
 bare approve still passes but draws a friendly public nudge, so review *quality* is visible without
 blocking. **Strict (`true`):** the predicate counts only `verified` approvals. The signal is gameable by
 design ("visible, not impossible") — it raises the cost of a rubber-stamp, it does not prove a human
-read the artifact. Applies to both the front gate and the back-half engineer review.
+read the artifact. Applies to both the Shape gate and the Build engineer review.
 
 ## Git tracking
 
@@ -99,6 +113,6 @@ This mirrors how `repos.json` and the per-epic `.sdlc/` state are committed.
 
 ## Greenfield
 
-A brand-new hub has no `hub.json`. That is valid — the front-half gate runs file-only until `detect-hub`
-records a platform. The bridge is purely additive; nothing about authoring or the gate predicate changes.
+A brand-new hub has no `hub.json`. That is valid — the Shape gate runs local until `detect-hub`
+records a platform. The verified ledger is purely additive; nothing about authoring or the gate predicate changes.
 ```

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

@@ -37,7 +37,7 @@ not under any `epics/EP-<slug>/.sdlc/`.
 
 ## Rules
 
-- **`name`** is the join key. It MUST match the names used in epic/story `repos:` tags so the front
+- **`name`** is the join key. It MUST match the names used in epic/story `repos:` tags so the Shape
   phases can map `epic.repos` → registry entries → code-maps. Keep it stable.
 - **Auth is never stored.** No tokens, passwords, or PATs in the registry. `git_url` is a plain remote;
   `connect` clones/fetches as the local user (SSH key or git credential helper).
@@ -51,7 +51,7 @@ not under any `epics/EP-<slug>/.sdlc/`.
 ## Git tracking
 
 Commit the **registry** (`repos.json`) and each repo's **`code-map.md`** — they are small, reviewable,
-and are what the front phases actually read (a diff on a code-map shows when a repo's surface moved).
+and are what the Shape phases actually read (a diff on a code-map shows when a repo's surface moved).
 `yad repo refresh --push` commits and pushes exactly these (never `pack.md`) to the hub's default
 branch as one `chore(hub): sync code-context … [skip ci]` audit commit.
 **Ignore** the full Repomix `pack.md` — it is large and regenerable (`action: refresh`). The product
@@ -60,6 +60,6 @@ hub's `.gitignore` carries `.sdlc/code-context/*/pack.md` for this. This mirrors
 
 ## Greenfield
 
-A brand-new product hub has no `repos.json` (or an empty `{ "repos": [] }`). That is valid — the front
+A brand-new product hub has no `repos.json` (or an empty `{ "repos": [] }`). That is valid — the Shape
 phases treat "no repos connected" as "nothing to consider yet" and proceed unchanged. The registry
 appears the first time `connect` runs.

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

@@ -10,7 +10,7 @@ runnable specs in a connected code repo — alongside the Markdown artifact (`te
 **connects** a testing tool such as **Playwright** to the product hub and records *how* to reach it (the
 tool, the suite references, which MCP runs it) — never a credential.
 
-This is **setup/maintenance**, not a gated front state — it never touches `.sdlc/state.json` or any
+This is **setup/maintenance**, not a gated Shape step — it never touches `.sdlc/state.json` or any
 epic's approvals. It only writes the project-wide testing registry. `yad-test-cases` consumes it: when a
 tool is connected and its MCP is available, the `test architect` lens **generates** automation tests
 into the connected repo(s) (or **links** an existing suite and reads it back); when nothing is

package/skills/yad-defects/SKILL.md

@@ -34,7 +34,7 @@ Resolve the scope (`yad thread <id> --json` for a thread). Collect, across the s
   (`origin`, `severity`, `escape_stage`, `root_cause`);
 - the shipped regression fixes from each epic's build ledger (the fix that closed the defect, linking
   the change-epic → its regression story/test);
-- open reconcile debt (a hotfix whose front truth is not yet restored).
+- open reconcile debt (a hotfix whose Shape truth is not yet restored).
 
 The build ledger is **shard-then-fold**: read it as the **union** of the folded `.sdlc/build-log.json`
 `ships` PLUS every loose `.sdlc/build-log/` shard, deduped by `(story, task, repo)` — a shard WINS over a