yadflow 1.0.1

package/skills/sdlc-pr-template/templates/checks/risk-route.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Risk routing (Phase 3 build plan §D). Reads a PR/MR description's Impact & Risk block and prints the
+# required reviewers, reusing sdlc-review-gate's escalation: a `high` risk level — or a touched
+# contract/auth/payments surface — requires a domain-owner approval per touched domain, on top of the
+# base rule (owner + 1 reviewer). Advisory: it ROUTES the human review; it does not approve or merge.
+set -euo pipefail
+
+BODY="${1:?usage: risk-route.sh <pr-description-file>}"
+[ -f "$BODY" ] || { echo "risk-route: file not found: $BODY" >&2; exit 2; }
+
+# Value side of the FIRST line matching a label regex, with any HTML comment + markdown markers
+# stripped. Tolerant: a missing label yields empty (never aborts) — an advisory helper must still
+# produce output for a half-filled body. Anchor on the real label so the right line is read.
+value_of() {
+  grep -iE "$1" "$BODY" 2>/dev/null | head -1 \
+    | sed -E 's/<!--.*$//; s/^[^:]*://; s/[*`]//g; s/^[[:space:]]*//; s/[[:space:]]*$//' || true
+}
+
+risk="$(printf '%s' "$(value_of 'Risk level:')" | tr 'A-Z' 'a-z' | grep -oE 'low|medium|high' | head -1 || true)"
+contract="$(printf '%s' "$(value_of 'Contract surface touched:')" | tr 'A-Z' 'a-z' | grep -oE 'yes|no' | head -1 || true)"
+domains="$(value_of 'Domains.*touched:')"
+
+echo "Risk level: ${risk:-unspecified}"
+echo "Contract surface touched: ${contract:-unspecified}"
+echo "Domains touched: ${domains:-unspecified}"
+
+if [ "$risk" = "high" ] || [ "$contract" = "yes" ]; then
+  why=""
+  [ "$risk" = "high" ] && why="risk: high"
+  [ "$contract" = "yes" ] && why="${why:+$why, }contract surface touched"
+  echo "ROUTE: ESCALATED (${why}) -> owner + 1 reviewer PLUS one domain-owner approval per touched domain"
+  echo "       (same escalation as sdlc-review-gate). Required domain owners:"
+  case "$domains" in
+    ""|*"<"*|*"…"*|*"|"*)
+      echo "  (Domains line not filled in — list each touched domain to route the owners.)" ;;
+    *)
+      printf '%s\n' "$domains" | tr ',' '\n' | while IFS= read -r d; do
+        d="$(printf '%s' "$d" | sed -E 's/^[[:space:]]*//; s/[[:space:]]*$//')"
+        [ -n "$d" ] && echo "  - domain-owner: $d"
+      done ;;
+  esac
+else
+  echo "ROUTE: base rule -> owner + 1 reviewer (no domain-owner escalation)."
+fi

package/skills/sdlc-pr-template/templates/github/pull_request_template.md

@@ -0,0 +1,30 @@
+<!-- SDLC PR template (Phase 3 build plan §D). One atomic task per PR. -->
+
+## Summary
+<!-- What this PR does, in one or two sentences. -->
+
+## Story / task
+<!-- The commits MUST carry a `Task: <story>-<task>` trailer (the spec-link gate checks this). -->
+- Story / task: `EP-<slug>-S0N-T0N`
+- Spec: `specs/EP-<slug>-S0N/` (link.md points back to the product repo)
+
+## Impact & Risk
+<!-- Fill every field. risk-route.sh + the engineer review read this block. -->
+- **Domains / repos touched:** <backend | mobile | …>
+- **Contract surface touched:** no <!-- yes => needs Contract-Change + a re-locked contract (contract-check) -->
+- **Risk level:** low <!-- low | medium | high — high (or a contract/auth/payments surface) routes to domain owners -->
+- **Rollback plan:** <how to revert if this misbehaves>
+
+> **Routing:** `low`/`medium` → base rule (owner + 1 reviewer). `high` (or a touched
+> contract/auth/payments surface) → **plus one domain-owner approval per touched domain**, the same
+> escalation `sdlc-review-gate` applies. Run `bash checks/risk-route.sh <this-description>` to list them.
+
+## Testing
+<!-- How the acceptance criteria were exercised. Tests must exercise behavior, not just pass. -->
+
+## Checklist
+- [ ] Commits carry a `Task: <story>-<task>` trailer (spec-link gate)
+- [ ] No contract-surface change without `Contract-Change: yes` + a re-locked contract (contract-check gate)
+- [ ] Lint, build, and tests pass (build/test/lint gate)
+- [ ] Diff stays inside the files the task's spec declared (≤3 where possible)
+- [ ] Impact & Risk filled; `high` risk adds the required domain-owner reviewers

package/skills/sdlc-pr-template/templates/gitlab/merge_request_templates/Default.md

@@ -0,0 +1,32 @@
+<!-- SDLC MR template (Phase 3 build plan §D). One atomic task per MR. -->
+
+## Summary
+<!-- What this MR does, in one or two sentences. -->
+
+## Story / task
+<!-- The commits MUST carry a `Task: <story>-<task>` trailer (the spec-link gate checks this). -->
+- Story / task: `EP-<slug>-S0N-T0N`
+- Spec: `specs/EP-<slug>-S0N/` (link.md points back to the product repo)
+
+## Impact & Risk
+<!-- Fill every field. risk-route.sh + the engineer review read this block. -->
+- **Domains / repos touched:** <backend | mobile | …>
+- **Contract surface touched:** no <!-- yes => needs Contract-Change + a re-locked contract (contract-check) -->
+- **Risk level:** low <!-- low | medium | high — high (or a contract/auth/payments surface) routes to domain owners -->
+- **Rollback plan:** <how to revert if this misbehaves>
+
+> **Routing:** `low`/`medium` → base rule (owner + 1 reviewer). `high` (or a touched
+> contract/auth/payments surface) → **plus one domain-owner approval per touched domain**, the same
+> escalation `sdlc-review-gate` applies. Run `bash checks/risk-route.sh <this-description>` to list them.
+
+## Testing
+<!-- How the acceptance criteria were exercised. Tests must exercise behavior, not just pass. -->
+
+## Checklist
+- [ ] Commits carry a `Task: <story>-<task>` trailer (spec-link gate)
+- [ ] No contract-surface change without `Contract-Change: yes` + a re-locked contract (contract-check gate)
+- [ ] Lint, build, and tests pass (build/test/lint gate)
+- [ ] Diff stays inside the files the task's spec declared (≤3 where possible)
+- [ ] Impact & Risk filled; `high` risk adds the required domain-owner reviewers
+
+/assign me

package/skills/sdlc-pr-template/templates/hub/github/pull_request_template.md

@@ -0,0 +1,36 @@
+<!-- SDLC HUB PR template — front-half artifact review (epic / architecture+contract / ui-design / stories). -->
+<!-- This PR is a REVIEW VEHICLE on the product hub, not a code merge. The file gate (sdlc-review-gate)
+     advances the step; do NOT rely on merging this PR to advance. Reviewers approve/comment here, then a
+     `sdlc-review-gate action: sync` pulls that into the file ledger. -->
+
+## Artifact under review
+- Epic: `EP-<slug>`
+- Artifact: `epic.md | architecture.md (+contract.md) | ui-design.md | stories/`
+- Gate step: `<epic-review | architecture-review | ui-design-review | stories-review>`
+- Owner: `<epic.md owner>`
+
+## What changed
+<!-- One or two sentences on what this artifact says / what changed since the last review round. -->
+
+## Impact & Risk (front-half)
+- **Domains / repos touched:** <epic.repos, e.g. backend, mobile>
+- **Risk tags:** <none | contract | auth | payments>  <!-- contract/auth/payments => escalates to domain owners -->
+- **Contract surface:** <n/a | locked @ sha256:…>  <!-- architecture only; a re-lock invalidates prior approvals -->
+
+## Required approvals (sdlc-review-gate rule)
+- Base: **owner + 1 reviewer**.
+- Escalated (risk tag set, or a stories PR): **plus one domain-owner per touched repo** — see the
+  requested reviewers / `domain:<repo>` labels on this PR. Run `bash checks/hub-route.sh <this-description>`
+  to list them.
+
+## How to review (this drives the gate)
+- **Approve** this PR to record an `owner` / `reviewer` / `domain-owner` approval in the file ledger
+  (your platform login maps to your SDLC name + role via `.sdlc/hub.json`'s roster).
+- **Comment / request changes** to record review comments (synced into `reviews/<artifact>--<date>--comments.md`).
+- **Do NOT merge to advance** — `sdlc-review-gate action: sync` + `action: advance` move the step.
+
+## Checklist
+- [ ] `owner` set in the artifact frontmatter (inherited from `epic.md`)
+- [ ] Contract re-locked (`.sdlc/contract-lock.json`) if the surface changed (architecture only)
+- [ ] Risk tags reflect the real surface touched (contract/auth/payments escalate)
+- [ ] No secrets or tokens in the artifact or this description

package/skills/sdlc-pr-template/templates/hub/gitlab/merge_request_templates/Default.md

@@ -0,0 +1,37 @@
+<!-- SDLC HUB MR template — front-half artifact review (epic / architecture+contract / ui-design / stories). -->
+<!-- This MR is a REVIEW VEHICLE on the product hub, not a code merge. The file gate (sdlc-review-gate)
+     advances the step; do NOT rely on merging this MR to advance. Reviewers approve/comment here, then a
+     `sdlc-review-gate action: sync` pulls that into the file ledger. -->
+
+## Artifact under review
+- Epic: `EP-<slug>`
+- Artifact: `epic.md | architecture.md (+contract.md) | ui-design.md | stories/`
+- Gate step: `<epic-review | architecture-review | ui-design-review | stories-review>`
+- Owner: `<epic.md owner>`
+
+## What changed
+<!-- One or two sentences on what this artifact says / what changed since the last review round. -->
+
+## Impact & Risk (front-half)
+- **Domains / repos touched:** <epic.repos, e.g. backend, mobile>
+- **Risk tags:** <none | contract | auth | payments>  <!-- contract/auth/payments => escalates to domain owners -->
+- **Contract surface:** <n/a | locked @ sha256:…>  <!-- architecture only; a re-lock invalidates prior approvals -->
+
+## Required approvals (sdlc-review-gate rule)
+- Base: **owner + 1 reviewer**.
+- Escalated (risk tag set, or a stories MR): **plus one domain-owner per touched repo** — see the
+  reviewers / `domain:<repo>` labels on this MR. Run `bash checks/hub-route.sh <this-description>` to list them.
+
+## How to review (this drives the gate)
+- **Approve** this MR to record an `owner` / `reviewer` / `domain-owner` approval in the file ledger
+  (your platform login maps to your SDLC name + role via `.sdlc/hub.json`'s roster).
+- **Comment** to record review comments (synced into `reviews/<artifact>--<date>--comments.md`).
+- **Do NOT merge to advance** — `sdlc-review-gate action: sync` + `action: advance` move the step.
+
+## Checklist
+- [ ] `owner` set in the artifact frontmatter (inherited from `epic.md`)
+- [ ] Contract re-locked (`.sdlc/contract-lock.json`) if the surface changed (architecture only)
+- [ ] Risk tags reflect the real surface touched (contract/auth/payments escalate)
+- [ ] No secrets or tokens in the artifact or this description
+
+/assign me

package/skills/sdlc-review-comments/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: sdlc-review-comments
+description: 'Installs platform-matched PR/MR review-comment scaffolds into a repo so reviewers leave structured, attributable feedback that maps cleanly into the SDLC file ledger. Works for code repos and the product hub. GitHub has no repo-level multi-comment template, so the scaffold is a committed REVIEW_COMMENTS.md reviewers copy from (saved as Saved Replies on GitHub / comment templates on GitLab). Each canned comment carries an attributable `**<name> (<role>)**` header that matches the `## <name> (<role>)` headings sdlc-review-gate writes. Use when the user says "add the comment templates" or "set up review comments" for a repo.'
+---
+
+# SDLC — Review Comment Templates
+
+**Goal:** Give reviewers a consistent, **attributable** set of canned PR/MR comments so review feedback
+reads the same across repos and **maps cleanly into the file ledger** the gate keeps. The headers match
+the `## <name> (<role>)` shape `sdlc-review-gate` writes into `reviews/<artifact>--<date>--comments.md`
+and the per-commenter record in `comments.json`, so a synced or copy-pasted comment lands without
+reformatting.
+
+## Platform reality (why this is a committed doc, not a config file)
+
+Neither GitHub nor GitLab has a **repo-level** multi-comment template convention: GitHub *Saved Replies*
+are per-account and GitLab *comment templates* are per-user/group, both set in the UI — there is no
+`.github/comment_templates/` or `.gitlab/comment_templates/` the repo can ship. The pragmatic mechanism
+on **both** is a single committed doc reviewers copy from (and optionally paste once into their personal
+Saved Replies / comment templates). This skill ships that doc.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory — the **product** repo (holds the
+  canonical templates under this skill).
+- Canonical sources live in this skill's `templates/`:
+  - `templates/github/REVIEW_COMMENTS.md` → installs to `<repo>/.github/REVIEW_COMMENTS.md`
+  - `templates/gitlab/REVIEW_COMMENTS.md` → installs to `<repo>/.gitlab/REVIEW_COMMENTS.md`
+- The two variants are identical except a footer line (GitHub: "save these as Saved Replies"; GitLab:
+  "save these as comment templates").
+
+## Inputs
+
+- `repo`   — the repo to add the scaffold to (one of an epic's repos), or `hub` for the product hub.
+- `action` — `wire` (install the matching scaffold). Default `wire`.
+
+## On Activation
+
+### Step 1 — Resolve the repo and detect the platform
+Map `repo` → its path (`{project-root}/demo-repos/<repo>/` or the registry `path`); for `repo: hub` the
+target is `{project-root}` and the platform comes from `.sdlc/hub.json`. Detect the platform: a GitHub
+remote or `.github/` → GitHub; a GitLab remote or `.gitlab/` → GitLab. If ambiguous, ask.
+
+### Step 2 — `wire` (drop only the matching scaffold)
+Copy the matching `templates/<platform>/REVIEW_COMMENTS.md` into the repo's `.github/` or `.gitlab/`.
+Do not clobber an existing non-SDLC file of the same name — back it up / ask. Commit on the repo's
+default branch (shared infrastructure, not a task diff). Idempotent — re-running refreshes in place.
+
+### Step 3 — Stop (no auto-advance)
+Report what was committed. The scaffold is an aid to human review; it approves nothing and touches no
+`.sdlc/` state.
+
+## Hard rules
+
+- **Drop only the matching scaffold** for the detected platform.
+- **Attributable headers** — every canned comment keeps the `**<name> (<role>)**` form so the gate's
+  ledger and the PR thread agree.
+- **Nothing auto-advances.** Comments feed the human review and (via the bridge) `sdlc-review-gate`.
+
+## Reference
+- Comment conventions + the full scaffold contents: `references/comment-conventions.md`.
+- The ledger headings these match: `../sdlc-review-gate/SKILL.md` (comment action) and `references/gating.md`.
+- The review bridge that syncs platform comments into the ledger: `../sdlc-hub-bridge/SKILL.md`.

package/skills/sdlc-review-comments/references/comment-conventions.md

@@ -0,0 +1,55 @@
+# Review comment conventions
+
+The scaffold (`REVIEW_COMMENTS.md`) groups canned comments into **blocking** (a gate would fail / must
+be fixed before merge) and **non-blocking** (suggestions, nits, questions). Every comment starts with an
+attributable header:
+
+```
+**<name> (<role>)**
+```
+
+`<role>` is one of `owner | reviewer | domain-owner` — the same roles `sdlc-review-gate` records. This
+header matches the `## <name> (<role>)` headings the gate writes into
+`reviews/<artifact>--<date>--comments.md`, so a comment copied from the PR thread (or synced by
+`sdlc-hub-bridge`) needs no reformatting to land in the ledger.
+
+## Blocking comments (a gate or rule says stop)
+
+These map to the code-repo check gates (`sdlc-checks`) and the file-boundary / contract rules:
+
+- **spec-link** — "This commit has no `Task: <story>-<task>` trailer; the spec-link gate will fail. Add
+  the trailer (and ensure `specs/<story>/link.md` exists)."
+- **contract-check** — "This diff changes the contract surface without `Contract-Change: yes` + a
+  re-locked contract. Route back to the architecture gate and re-lock before this can merge."
+- **build-test-lint** — "Lint/build/test is red (or the test doesn't exercise the new behavior). The
+  build-test-lint gate must pass with a test that actually exercises the acceptance criterion."
+- **file-boundary** — "This diff touches files the task's `Files:` list didn't declare. Re-scope the
+  task (re-run `sdlc-spec`) rather than widening the diff silently."
+
+## Escalation / routing comment
+
+- **routing** — "Risk is `high` / a contract|auth|payments surface is touched — this needs a
+  domain-owner approval per touched repo (the same escalation `sdlc-review-gate` applies). Run
+  `bash checks/risk-route.sh <body>` (code repo) or `bash checks/hub-route.sh <body>` (hub)."
+
+## Non-blocking comments
+
+- **suggestion** — "Suggestion (non-blocking): …"
+- **nit** — "Nit: …"
+- **question** — "Question: … (not blocking — just want to understand)."
+
+## Approval note
+
+- **approve** — "Approving as `<role>`. Recorded in `approvals.json` (code-repo ship: `build-log.json`).
+  On the hub, your approval here is pulled in by `sdlc-review-gate action: sync`."
+
+## Hub front-artifact review
+
+The hub scaffold adds a **Front-artifact review** section whose headers mirror the gate's comment file
+exactly, so reviewing an `epic.md` / `architecture.md` / `ui-design.md` / `stories/` PR produces comments
+that drop straight into `reviews/<artifact>--<date>--comments.md`:
+
+```
+**<name> (<role>)**
+- <comment about scope / contract surface / acceptance signals / story split>
+```

package/skills/sdlc-review-comments/templates/github/REVIEW_COMMENTS.md

@@ -0,0 +1,49 @@
+# Review comments — canned replies
+
+Copy a block below into a PR review comment. Keep the `**<name> (<role>)**` header — it matches the
+SDLC review ledger (`reviews/<artifact>--<date>--comments.md`) so feedback stays attributable.
+`<role>` is one of `owner | reviewer | domain-owner`.
+
+## Blocking (a gate or rule says stop — must be fixed before merge)
+
+**<name> (<role>)**
+- spec-link: this range has no `Task: <story>-<task>` trailer — the spec-link gate will fail. Add the
+  trailer and make sure `specs/<story>/link.md` exists.
+
+**<name> (<role>)**
+- contract-check: this diff changes the contract surface without `Contract-Change: yes` + a re-locked
+  contract. Route back to the architecture gate and re-lock before merge.
+
+**<name> (<role>)**
+- build-test-lint: lint/build/test is red, or the test doesn't exercise the new behavior. The gate must
+  pass with a test that actually exercises the acceptance criterion.
+
+**<name> (<role>)**
+- file-boundary: this touches files the task's `Files:` list didn't declare. Re-scope the task (re-run
+  `sdlc-spec`) instead of widening the diff.
+
+## Routing / escalation
+
+**<name> (<role>)**
+- routing: risk is `high` / a contract|auth|payments surface is touched — needs a domain-owner approval
+  per touched repo (same escalation as `sdlc-review-gate`). Run `bash checks/risk-route.sh <body>`.
+
+## Non-blocking
+
+**<name> (<role>)**
+- Suggestion (non-blocking): …
+
+**<name> (<role>)**
+- Nit: …
+
+**<name> (<role>)**
+- Question: … (not blocking — just want to understand).
+
+## Approval
+
+**<name> (<role>)**
+- Approving as `<role>`. Recorded in `approvals.json` (ship: `build-log.json`).
+
+---
+> Tip (GitHub): paste the blocks you use most into your personal **Saved Replies**
+> (Settings → Saved replies) so they are one click away in any PR.

package/skills/sdlc-review-comments/templates/gitlab/REVIEW_COMMENTS.md

@@ -0,0 +1,49 @@
+# Review comments — canned replies
+
+Copy a block below into an MR review comment. Keep the `**<name> (<role>)**` header — it matches the
+SDLC review ledger (`reviews/<artifact>--<date>--comments.md`) so feedback stays attributable.
+`<role>` is one of `owner | reviewer | domain-owner`.
+
+## Blocking (a gate or rule says stop — must be fixed before merge)
+
+**<name> (<role>)**
+- spec-link: this range has no `Task: <story>-<task>` trailer — the spec-link gate will fail. Add the
+  trailer and make sure `specs/<story>/link.md` exists.
+
+**<name> (<role>)**
+- contract-check: this diff changes the contract surface without `Contract-Change: yes` + a re-locked
+  contract. Route back to the architecture gate and re-lock before merge.
+
+**<name> (<role>)**
+- build-test-lint: lint/build/test is red, or the test doesn't exercise the new behavior. The gate must
+  pass with a test that actually exercises the acceptance criterion.
+
+**<name> (<role>)**
+- file-boundary: this touches files the task's `Files:` list didn't declare. Re-scope the task (re-run
+  `sdlc-spec`) instead of widening the diff.
+
+## Routing / escalation
+
+**<name> (<role>)**
+- routing: risk is `high` / a contract|auth|payments surface is touched — needs a domain-owner approval
+  per touched repo (same escalation as `sdlc-review-gate`). Run `bash checks/risk-route.sh <body>`.
+
+## Non-blocking
+
+**<name> (<role>)**
+- Suggestion (non-blocking): …
+
+**<name> (<role>)**
+- Nit: …
+
+**<name> (<role>)**
+- Question: … (not blocking — just want to understand).
+
+## Approval
+
+**<name> (<role>)**
+- Approving as `<role>`. Recorded in `approvals.json` (ship: `build-log.json`).
+
+---
+> Tip (GitLab): paste the blocks you use most into your personal/group **Comment templates**
+> (Preferences → Comment templates) so they are one click away in any MR.

package/skills/sdlc-review-gate/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: sdlc-review-gate
+description: 'The reusable team review + approve gate for the SDLC. Shares an authored artifact for review, records reviewer comments and approvals as files, enforces the owner + 1 reviewer rule (escalating to domain owners on contract/auth/payments), and advances the epic state ONLY when approval is recorded. Use when the user says "review the analysis/epic/architecture/UI/stories", "comment", "approve", or "advance the gate".'
+---
+
+# SDLC — Team Review Gate (build plan §3 piece 2, §4, §5)
+
+**Goal:** One reusable step type that turns any authored artifact into a gated, human-approved
+review. Every `review+approve` step in the workflow (the optional analysis, epic, architecture+contract,
+UI, stories) uses this exact gate. **No step advances until its review is approved** and recorded as a
+file. The `analysis-review` and `epic`/`ui-design` reviews use the **base** rule (owner + 1 reviewer);
+escalation applies only where `risk_tags` or per-repo routing call for it.
+
+This gate is **swappable and file-driven**: it talks only through files. A front step advances only on a
+human act — recording an approval and `advance`, or (with the bridge) **merging the approved,
+fully-resolved review PR/MR**. It works the same whether a human or the `sdlc gate` CLI triggers it — the
+trigger is a parameter, not a hardcoded human.
+
+## Conventions
+- `{project-root}` resolves from the project working directory.
+- Operate on one epic: `{project-root}/epics/EP-<slug>/`.
+- State files: `.sdlc/state.json`, `.sdlc/approvals.json`, `.sdlc/comments.json`, and (when the bridge is
+  used) `.sdlc/hub-prs.json`. Review records: `reviews/`.
+- The artifact base name drops the extension (`epic.md` → `epic`; story `stories/...S01.md` → `stories-S01`).
+
+## Inputs
+- `epic`: the `EP-<slug>` to operate on.
+- `artifact`: the file under the epic being reviewed (e.g. `epic.md`).
+- `action`: one of `open` | `comment` | `approve` | `sync` | `advance` (default: `open`).
+- For `comment` / `approve`: the reviewer name and role (`owner` | `reviewer` | `domain-owner`),
+  and for domain owners the `domain` (repo/area). Ask if not provided.
+- `sync` needs no reviewer input — it reads the platform PR/MR review state (via `sdlc-hub-bridge`).
+
+## On Activation
+
+### Step 1 — Load state
+Read `.sdlc/state.json`. Find the `review+approve` step whose `artifact` matches the input (or the
+step named `currentStep` if it is a review step). Read `.sdlc/approvals.json`. Read `epic.md` for the
+epic's `repos` (the **touched domains**). Determine the **reviewer rule** for this step:
+- **Base rule:** `owner + 1 reviewer` — at least one `owner` approval AND at least one distinct
+  non-owner `reviewer` approval.
+- **Escalation option (risk-driven):** if the step's `risk_tags` intersect `{contract, auth,
+  payments}`, ALSO require at least one `domain-owner` approval **per touched domain** (build plan §4,
+  §5). For the **architecture+contract** review (`risk_tags: ["contract"]`), the touched domains are
+  the epic's `repos` — each repo's owner must sign off on the shared surface, so it escalates by
+  default.
+- **Per-repo routing option (stories):** for the **stories** review, the relevant domain engineer
+  reviews the stories touching their repo: treat each repo's engineer as a `domain-owner` for that
+  repo's stories. The touched domains are the **union of every story's `repos`** under `stories/`
+  (build plan §4 step 8). The `domain` field on each approval is the repo name.
+
+Escalation and per-repo routing are **options of this one gate**, selected by `risk_tags` and the
+touched `repos` — never a forked or copied gate.
+
+### Step 2 — Dispatch on `action`
+
+**`open`** — Present the artifact for review. Summarise what changed, list the required reviewers per
+the rule above, and tell reviewers how to comment/approve. Set the step `status` to `in_review` and
+`currentStep` to this step in `state.json` if not already. Do not advance.
+
+If `.sdlc/hub.json` has a non-null `platform`, `bridge_enabled: true`, `config.yaml` `hub.bridge: true`,
+and `gh`/`glab` is authenticated, **also open a review PR/MR on the hub** by invoking
+`sdlc-hub-bridge action: open` (epic + artifact). Record the PR in `epics/<epic>/.sdlc/hub-prs.json`
+(`{step, artifact, platform, number, url, branch, lastSyncedAt}`) and report the URL + required
+reviewers. Otherwise (no platform / disabled / no CLI) proceed **file-only** exactly as before — no
+error. Opening the PR records no approvals and never advances.
+
+**`comment`** — Capture reviewer feedback. Append/create a review file
+`reviews/<artifact-base>--<YYYY-MM-DD>--comments.md` with a heading per reviewer:
+
+```markdown
+# Review comments — <artifact> — <YYYY-MM-DD>
+
+## <reviewer> (<role>)
+- <comment>
+- <comment>
+```
+
+Also append a **machine-readable** participation record to `.sdlc/comments.json` (create as `[]` if
+absent — the markdown stays the human-readable record, this makes commenter names queryable, the
+counterpart to `approvals.json`):
+```json
+{ "artifact": "<artifact>", "step": "<step id>", "commenter": "<name>", "role": "<owner|reviewer|domain-owner>", "domain": "<optional>", "round": <n>, "count": <comments this round>, "date": "<YYYY-MM-DD>" }
+```
+`round` increments each comment→address cycle for the artifact; upsert by `(step, commenter, round)`.
+
+Then help the **owner address the comments** using the agent lens listed for this step
+(analysis → `analyst`; epic → `pm`; architecture → `architect`; ui-design → `ux-designer`;
+stories → `pm`, with `architect` for technical detail — there is **no `sm` agent**, Phase 0
+Deviation 1). Update the authored artifact in place.
+Repeat comment→address rounds until reviewers are satisfied. **Commenting never advances the gate.**
+
+**`approve`** — Record an approval. Append to `.sdlc/approvals.json`:
+```json
+{ "artifact": "<artifact>", "step": "<step id>", "approver": "<name>", "role": "<owner|reviewer|domain-owner>", "domain": "<optional>", "status": "approved", "date": "<YYYY-MM-DD>" }
+```
+Also write/refresh `reviews/<artifact-base>--<YYYY-MM-DD>--approved.md` as a **named roster** with three
+sections, so every participant is attributable in one place:
+
+```markdown
+# Approval record — <artifact> — <YYYY-MM-DD>
+
+Reviewer rule in force: **<base | escalated | per-repo>** (<why — e.g. risk_tags / touched repos>).
+
+## Approved by
+- <name> — <role>[ (<domain>)] — approved <date>
+
+## Reviewed / commented by (participation, from comments.json)
+- <name> — <role> — <n> comment(s) across <r> round(s)
+
+## Still required to pass the gate
+- <missing owner/reviewer/domain-owner, or "none">
+
+Gate status: **<PASSED | BLOCKED>** — <reason>.
+```
+
+Then **re-evaluate the rule** (Step 3). Recording an approval does NOT itself advance — advancement is
+a separate, explicit check.
+
+**`sync`** — (the platform bridge input path) Pull the hub review PR/MR's review state into the ledger,
+then re-evaluate the rule (Step 3). Read the PR for this step from `.sdlc/hub-prs.json` and use
+`sdlc-hub-bridge`'s read recipes (`../sdlc-hub-bridge/references/bridge.md`) to fetch reviews + comments
+via the local user's `gh`/`glab`. For each:
+- map the platform `login` → SDLC `name` + `role` via `.sdlc/hub.json`'s roster (a roster `name` equal
+  to a repo's `domain_owner` in `repos.json` becomes that repo's `domain-owner` for a touched domain;
+  an unmapped login is a plain `reviewer`, flagged, never promoted);
+- an `APPROVED` review / MR approval → append an `approved` record to `approvals.json` tagged
+  `"source": "bridge"`; a `COMMENTED`/`CHANGES_REQUESTED`/note → write to
+  `reviews/<artifact-base>--<YYYY-MM-DD>--comments.md` + `comments.json` (never an approval).
+**Idempotent:** upsert bridge approvals by `(step, approver, role, domain)`, supersede revoked ones, and
+key comments on the platform comment id (re-running `sync` does not duplicate). **Manual approvals (no
+`source` tag) are never touched.** For the architecture+contract step, discard bridge approvals dated
+before a new contract lock (re-lock invalidates platform approvals too). Then refresh the `approved.md`
+roster, set `hub-prs.json` `lastSyncedAt`, and **re-evaluate Step 3**. Under the PR-driven CLI (`sdlc
+gate sync`), `sync` advances the step when Step 3 passes on a **merged**, fully-resolved, approved PR
+(the merge is the human act); otherwise it records state and holds the step `in_review`.
+
+**`advance`** — Run the gate predicate (Step 3). Only advance if it passes.
+
+### Step 3 — Gate predicate (the only path that advances)
+The step may advance **iff ALL hold**:
+1. `automation` is `human_approve` (it always is for front steps) and the required approvals exist:
+   ≥1 `owner` AND ≥`review_gate.default_reviewers` (1) distinct non-owner `reviewer`, AND — if the
+   step is escalated — ≥1 `domain-owner` for each touched domain.
+2. The artifact has not changed since the latest approval round (no newer authored edit than the
+   newest `approved` record). If it changed, approvals are stale → return to `comment`. For the
+   **architecture+contract** review, also recompute the contract-surface hash (see
+   `../sdlc-author-architecture/references/contract-format.md`): if it no longer matches
+   `.sdlc/contract-lock.json`, the surface changed → approvals stale → return to `comment` and re-lock.
+
+If the predicate **fails**: report exactly which approvals are still missing and STOP. Do not modify
+`currentStep`.
+
+If the predicate **passes**:
+- Mark this review step `status: "done"`.
+- If there **is** a next step in `steps[]`: set it `status` from `blocked` to `in_progress`
+  (authoring) or `in_review`, and set `currentStep` to that next step.
+- If this is the **last** step (`stories-review`, the final review): there is no further front step —
+  set `currentStep: "ready-for-build"` (the Phase 3 handoff sentinel; it is intentionally not a
+  `steps[]` entry). The front half is complete.
+- Write `state.json`. Report the advance and what the next authored artifact is (or that the epic is
+  now `ready-for-build`).
+
+### PR-driven automation (the `sdlc gate` CLI)
+When the hub has a platform, the mechanical `open`/`sync`/`advance` is performed deterministically by the
+**`sdlc gate` CLI** (`sdlc gate open|sync|comments|status`), which writes the same `.sdlc/` + `reviews/`
+records this skill describes. The skill's job is then the human half: presenting the artifact, helping the
+owner address comments, and narrating the gate. The CLI is the single implementation of the gh/glab
+mechanics — do not hand-run gh/glab recipes when it is installed.
+
+Under that CLI the gate **advances on merge**: a review PR/MR whose reviewer rule is satisfied, whose
+comment threads are **all resolved**, and which has been **merged** auto-marks the step `done` and
+unblocks the next step. (Until those three hold, the step stays `in_review`.)
+
+`sync` can also be **event-driven**: when the hub is wired with the gate-sync CI (`sdlc-hub-bridge`
+`wire` action), every approval / change request / dismissal / merge on the review PR/MR triggers
+`sdlc gate ci` on the hub, which runs the same sync and commits the ledger updates directly to the
+hub's default branch (pull to see them locally). The predicate, the human merge, and manual
+`sdlc gate sync` are all unchanged — CI never approves and never merges.
+
+### Hard rules (build plan §1, §5)
+- **The merge click is the human approval act.** A front step advances only when a human merges the
+  approved, fully-resolved review PR — there is no machine-driven advance. A step `locked: true` may not
+  be switched to `machine_advance`; refuse such a request.
+- **Approvals are revoked when the reviewed artifact changes.** `sync` re-hashes the artifact (the locked
+  contract surface for architecture) and drops any approval bound to a stale hash, so a reviewer must
+  re-approve the new content. Unresolved comments / `CHANGES_REQUESTED` hold the gate `in_review`.
+- The gate talks only through `.sdlc/` and `reviews/` files — never hidden state.
+- **The platform is an input path only.** `open`/`sync` use the local user's own `gh`/`glab` (no stored
+  tokens), and the **file ledger remains the source of truth** — the Step 3 predicate is unchanged
+  whether approvals arrive manually or via `sync`. With no hub platform / no CLI, the gate runs file-only
+  with no error (record approvals manually and `advance`).
+
+## Reference
+- Gating details and worked example: `references/gating.md`.
+- The platform PR/MR bridge (`open`/`sync` mechanics, read recipes, roster): `../sdlc-hub-bridge/SKILL.md`.