yadflow 1.0.1

package/skills/sdlc-hub-bridge/references/login-roster.md

@@ -0,0 +1,42 @@
+# Login roster — schema, resolution, per-repo routing
+
+The roster lives in `.sdlc/hub.json` (`roster: [...]`) and is the only thing that turns a platform
+**login** into an SDLC **name + role** for the ledger. Schema and the no-tokens rule are documented once
+in `../../sdlc-connect-repos/references/hub-config.md`; this file covers how the bridge *uses* it.
+
+## Entry
+
+```json
+{ "login": "abdelrahmannasr", "name": "alice", "role": "owner" }
+```
+
+- `login` — the GitHub/GitLab username whose review/approval is being mapped.
+- `name` — the SDLC name written to `approvals.json` / `comments.json` (the same names as `epic.md`
+  `owner` and `repos.json` `domain_owner`). Keep it stable.
+- `role` — the person's default role: `owner` or `reviewer`. **Not** `domain-owner` — that is derived.
+
+## Resolution
+
+1. **login → name + role** from the roster.
+2. **domain-owner is derived:** if the resolved `name` equals a repo's `domain_owner` in `repos.json`,
+   and that repo is a **touched domain** for the step under review, the bridge also emits a
+   `domain-owner` approval scoped to that repo (`domain: <repo>`). One person owning several repos yields
+   several `domain-owner` records with different `domain` values — exactly what the gate predicate allows.
+3. **Unmapped login → reviewer (flagged).** A login not in the roster maps to `name: <login>`,
+   `role: reviewer`, with `<!-- unverified login: <login> -->` in the review record. It counts as a
+   reviewer but is **never** auto-promoted to owner/domain-owner, so a stranger can never satisfy the
+   owner/domain-owner requirement. The marker prompts a human to add the login to the roster.
+
+## Per-repo routing (stories review, and any escalated step)
+
+The stories review needs a `domain-owner` per repo in the **union of every story's `repos`**. On the
+review PR the bridge makes this legible and enforceable:
+
+- Add a `domain:<repo>` **label** per touched repo.
+- **Request** each touched repo's `domain_owner` login as a reviewer (resolved via the roster).
+- On `sync`, an approval from login *L* maps to `domain-owner` for repo *R* **iff**
+  `repos.json[R].domain_owner == roster[L].name`. So a domain owner's approval is scoped to exactly the
+  repos they own, and a repo with no approving owner shows up as still-required in the gate report.
+
+This is the same touched-domains computation the gate uses (`../sdlc-review-gate/references/gating.md`):
+architecture+contract → `epic.repos`; stories → union of story `repos`.

package/skills/sdlc-hub-bridge/templates/checks/hub-route.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Hub review routing — the front-half analogue of sdlc-pr-template's risk-route.sh. Reads a hub review
+# PR/MR description's "Impact & Risk (front-half)" block and prints the required reviewers, reusing
+# sdlc-review-gate's rule: base = owner + 1 reviewer; if a risk tag (contract|auth|payments) is set OR
+# the artifact is the stories set, ALSO a domain-owner per touched repo. Advisory: it ROUTES the human
+# review; it does not approve or merge.
+set -euo pipefail
+
+BODY="${1:?usage: hub-route.sh <hub-pr-description-file>}"
+[ -f "$BODY" ] || { echo "hub-route: file not found: $BODY" >&2; exit 2; }
+
+# Value side of the FIRST line matching a label regex, comments + markdown markers stripped. Tolerant:
+# a missing label yields empty (never aborts) — an advisory helper must still print for a half-filled body.
+value_of() {
+  grep -iE "$1" "$BODY" 2>/dev/null | head -1 \
+    | sed -E 's/<!--.*$//; s/^[^:]*://; s/[*`]//g; s/^[[:space:]]*//; s/[[:space:]]*$//' || true
+}
+
+risk_tags="$(printf '%s' "$(value_of 'Risk tags:')" | tr 'A-Z' 'a-z')"
+repos="$(value_of 'Domains.*touched:')"
+artifact="$(value_of 'Artifact:')"
+
+echo "Risk tags: ${risk_tags:-none}"
+echo "Repos touched: ${repos:-unspecified}"
+
+escalate=no
+why=""
+case "$risk_tags" in
+  *contract*) escalate=yes; why="risk tag: contract" ;;
+esac
+case "$risk_tags" in *auth*) escalate=yes; why="${why:+$why, }risk tag: auth" ;; esac
+case "$risk_tags" in *payments*) escalate=yes; why="${why:+$why, }risk tag: payments" ;; esac
+# The stories review routes per-repo even with no risk tag.
+case "$artifact" in *stories*) escalate=yes; why="${why:+$why, }stories per-repo routing" ;; esac
+
+if [ "$escalate" = "yes" ]; then
+  echo "ROUTE: ESCALATED (${why}) -> owner + 1 reviewer PLUS one domain-owner approval per touched repo"
+  echo "       (same escalation as sdlc-review-gate; map each repo to its domain_owner in repos.json)."
+  case "$repos" in
+    ""|*"<"*|*"…"*|*"|"*)
+      echo "  (Repos line not filled in — list each touched repo to route the domain owners.)" ;;
+    *)
+      printf '%s\n' "$repos" | tr ',' '\n' | while IFS= read -r r; do
+        r="$(printf '%s' "$r" | sed -E 's/^[[:space:]]*//; s/[[:space:]]*$//')"
+        [ -n "$r" ] && echo "  - domain-owner: $r"
+      done ;;
+  esac
+else
+  echo "ROUTE: base rule -> owner + 1 reviewer (no domain-owner escalation)."
+fi

package/skills/sdlc-hub-bridge/templates/github/sdlc-gate-sync.yml

@@ -0,0 +1,63 @@
+# sdlc-managed: sdlc-hub-bridge
+# Event-driven gate sync for the PRODUCT HUB. When a reviewer approves, requests changes, or a
+# human merges a review/EP-* PR, this workflow runs `sdlc gate ci`, which maps the platform state
+# into the file ledger (epics/<epic>/.sdlc/*.json + reviews/*.md) and commits ONLY those ledger
+# files to the default branch. It never approves and never merges — the merge click remains the
+# human approval act; the gate predicate is the same one `sdlc gate sync` runs locally.
+#
+# Loop prevention: neither `pull_request_review` nor `pull_request` fires on a push to the default
+# branch, and the ledger commit carries [skip ci] to guard every other workflow.
+#
+# Protected default branch? The github.token push will fail (visibly — the run goes red and manual
+# `sdlc gate sync` still works). Options, in order of preference:
+#   a) add a ruleset bypass so GitHub Actions may push to the default branch, or
+#   b) store a fine-grained PAT as the SDLC_GATE_TOKEN secret and pass it to actions/checkout via
+#      `with: { token: ${{ secrets.SDLC_GATE_TOKEN }} }` — the one exception to the bridge's
+#      no-stored-tokens rule; see skills/sdlc-hub-bridge/references/bridge.md.
+name: sdlc-gate-sync
+on:
+  pull_request_review:
+    types: [submitted, dismissed]
+  pull_request:
+    types: [closed, synchronize] # closed -> merged advance; synchronize -> prompt revoke-on-change
+
+permissions:
+  contents: write # push the ledger commit
+  pull-requests: read # gh pr view + reviewThreads GraphQL
+
+# Serialize runs repo-wide so ledger pushes never race; sync reads the FULL platform state each
+# time, so a queued superseded run loses nothing.
+concurrency:
+  group: sdlc-gate-sync
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    if: >
+      startsWith(github.event.pull_request.head.ref, 'review/EP-') &&
+      (github.event_name == 'pull_request_review' ||
+       github.event.action == 'synchronize' ||
+       github.event.pull_request.merged == true)
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      # Check out the BASE branch (not the PR merge ref): the ledger lives there, and `gate ci`
+      # overlays the artifact from the head ref itself so approvals bind to the reviewed content.
+      # A head branch auto-deleted on merge is fine: the event payload still carries head.ref (the
+      # string `gate ci` parses), and a failed fetch just skips the overlay — by then the artifact
+      # is already on the base branch via the merge.
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.ref }}
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Sync the gate ledger
+        run: |
+          git config user.name  "sdlc-gate-sync[bot]"
+          git config user.email "sdlc-gate-sync[bot]@users.noreply.github.com"
+          npx -y -p yadflow@1 sdlc gate ci \
+            --branch "${{ github.event.pull_request.head.ref }}" \
+            --pr "${{ github.event.pull_request.number }}"

package/skills/sdlc-hub-bridge/templates/gitlab/gitlab-ci.include-root.yml

@@ -0,0 +1,7 @@
+# SDLC gate sync — minimal root pipeline for the PRODUCT HUB.
+# Written by the sdlc-hub-bridge `wire` action ONLY when the hub has no existing root
+# `.gitlab-ci.yml`. The job itself lives in the included fragment so the same single source is
+# reused whether or not a root pipeline already exists. If a root later grows real jobs, they
+# coexist with the included sdlc-* job (which carries `needs: []` and no `stage:`).
+include:
+  - local: '.gitlab/ci/sdlc-gate-sync.yml'

package/skills/sdlc-hub-bridge/templates/gitlab/sdlc-gate-sync.gitlab-ci.yml

@@ -0,0 +1,64 @@
+# sdlc-managed-include: sdlc-hub-bridge
+# Event-driven gate sync for the PRODUCT HUB, as an INCLUDABLE fragment. Pulled into the hub's
+# root .gitlab-ci.yml via:
+#   include:
+#     - local: '.gitlab/ci/sdlc-gate-sync.yml'
+# so wiring never edits the foreign root pipeline beyond that one include line. The job carries
+# `needs: []` and no `stage:` (same merge-safety as the sdlc-checks fragment).
+#
+# What it does: run `sdlc gate ci`, which maps MR approvals / change-request discussions / the
+# merge into the file ledger (epics/<epic>/.sdlc/*.json + reviews/*.md) and commits ONLY those
+# ledger files to the default branch. It never approves and never merges — the merge click remains
+# the human approval act.
+#
+# GitLab is the DEGRADED path, stated honestly: GitLab fires no pipeline on an approval alone.
+#   - MR events (open / push to the review branch) and the merge are picked up near-immediately.
+#   - Approvals are only seen by the SCHEDULED sweep. Create a pipeline schedule (one-time, cannot
+#     be committed as code): cron `*/15 * * * *` with variable SDLC_GATE_SYNC=true — so an approval
+#     can take up to ~15 minutes to reach the ledger. UI: CI/CD > Schedules, or:
+#       glab api projects/:id/pipeline_schedules -X POST \
+#         -f description='sdlc gate sync' -f ref=main -f cron='*/15 * * * *'
+#       glab api "projects/:id/pipeline_schedules/<id>/variables" -X POST \
+#         -f key=SDLC_GATE_SYNC -f value=true
+#
+# Token (the one documented bend of the bridge's no-stored-tokens rule): CI_JOB_TOKEN can neither
+# read the approvals API nor push to a protected branch. Create a PROJECT ACCESS TOKEN with
+# `read_api` + `write_repository` (role Developer+, allowed to push to the default branch) and
+# store it as a masked CI/CD variable SDLC_GATE_TOKEN. Without it the job fails visibly and
+# manual `sdlc gate sync` remains the fallback.
+variables:
+  GIT_DEPTH: "0" # full history: gate ci fetches the review branch and pushes the ledger
+
+sdlc-gate-sync:
+  needs: []
+  image: node:20
+  rules:
+    # MR-event path: fires on MR open / push to the review branch — NOT on approval (see header).
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^review\/EP-/
+    # Merge path: branch pipeline on the default branch whose merge commit names a review branch.
+    # Squash/fast-forward merges may omit the branch name — those advance on the next scheduled sweep.
+    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_COMMIT_MESSAGE =~ /review\/EP-/
+    # Scheduled sweep: the only path that picks up approvals.
+    - if: $CI_PIPELINE_SOURCE == "schedule" && $SDLC_GATE_SYNC == "true"
+  script:
+    # Pinned glab binary (node:20 has no glab). Alternative: image registry.gitlab.com/gitlab-org/cli.
+    - GLAB_VERSION=1.55.0
+    - curl -fsSL "https://gitlab.com/gitlab-org/cli/-/releases/v${GLAB_VERSION}/downloads/glab_${GLAB_VERSION}_linux_amd64.deb" -o /tmp/glab.deb && dpkg -i /tmp/glab.deb
+    # The ledger lives on the default branch; gate ci overlays the artifact from the review branch itself.
+    - git fetch origin "$CI_DEFAULT_BRANCH"
+    - git checkout -B "$CI_DEFAULT_BRANCH" "origin/$CI_DEFAULT_BRANCH"
+    - git config user.name "sdlc-gate-sync" && git config user.email "sdlc-gate-sync@noreply.${CI_SERVER_HOST}"
+    - git remote set-url origin "https://oauth2:${SDLC_GATE_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
+    - export GITLAB_TOKEN="$SDLC_GATE_TOKEN" GITLAB_HOST="$CI_SERVER_URL"
+    - |
+      # Merge pushes have no CI_MERGE_REQUEST_IID — derive the just-merged review branch from the
+      # merge commit message so the merge advances in event mode; the scheduled sweep stays the
+      # catch-all (squash/FF merges whose message omits the branch land there).
+      REVIEW_BRANCH="$(printf '%s' "$CI_COMMIT_MESSAGE" | grep -oE 'review/EP-[A-Za-z0-9._/-]+' | head -n1 || true)"
+      if [ -n "$CI_MERGE_REQUEST_IID" ]; then
+        npx -y -p yadflow@1 sdlc gate ci --branch "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --pr "$CI_MERGE_REQUEST_IID"
+      elif [ -n "$REVIEW_BRANCH" ]; then
+        npx -y -p yadflow@1 sdlc gate ci --branch "$REVIEW_BRANCH"
+      else
+        npx -y -p yadflow@1 sdlc gate ci
+      fi

package/skills/sdlc-implement/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: sdlc-implement
+description: 'Build-half Step B of the gated SDLC. With the dev lens, implement ONE atomic task from a story''s Spec Kit tasks.md as a small diff (≤3 files) on its own branch in the code repo. The diff stays inside the files the task declared — flag and STOP if it would grow beyond them. Commit per convention, ending with the task ID; add Contract-Change: yes only if the diff touches the locked contract surface (which routes back to the architecture gate). The step never advances itself; it produces a committed branch and hands off to the check gates, which the orchestrator (sdlc-run) may auto-run once `implement` is earned to machine_advance (Phase 4b Step D) — the merge still needs the gates and the engineer review. Use when the user says "implement task <id>" or after a story is spec''d.'
+---
+
+# SDLC — Implement Task (build-half Step B)
+
+**Goal:** Turn ONE atomic task from a story's `tasks.md` (produced by Step A `sdlc-spec`) into a small,
+reviewable diff on its own branch in the code repo. **One atomic task = one branch = one PR/MR**
+(build plan §B). This is the **light per-task loop**: it runs once per task; the heavy spec ceremony
+already ran once for the story.
+
+This step **never auto-advances**. When the task is implemented and committed, control passes to the
+**check gates** (Step C — `sdlc-checks`: spec-link, contract-check, build/test/lint) and then human/AI
+review (Steps D–E, not built yet). Implementation here produces a branch + commit and stops.
+
+The implementing lens is **`dev`** (`bmad-agent-dev`, Amelia). The dev writes only what the task
+declares; it does not redesign, does not widen the contract, and does not pick up sibling tasks.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory — the **product** repo.
+- The work happens **inside the code repo** (a separate git repo) at
+  `{project-root}/demo-repos/<repo>/` (`config.yaml` `build.code_repos_root`). Use absolute paths.
+- **Branch name:** `feat/<story-id>-<task-id>-<short-slug>` (e.g.
+  `feat/EP-istifta-inquiries-S01-T01-create-inquiry`). Branched off the code repo's default branch.
+- **Commit message:** a conventional subject, body describing the change, and a **required `Task:`
+  trailer** (e.g. `Task: EP-istifta-inquiries-S01-T01`) in the trailer block. Add `Contract-Change: yes`
+  **only** if the diff touches the locked contract surface (see Step 5), and a per-commit
+  `Co-Authored-By:` for any AI tool that helped author the diff (the human author owns the commit;
+  trailer order `Task:` → `Contract-Change:` → `Co-Authored-By:`). The skill installs a `.gitmessage`
+  template that scaffolds these (Step 2).
+- Speak in the configured `communication_language`; write code/comments in `document_output_language`.
+
+## Inputs
+
+- `epic`  — the `EP-<slug>` (ask if not provided).
+- `story` — the `EP-<slug>-S0N` whose spec is being implemented (ask if not provided).
+- `repo`  — the code repo the story's spec lives in (one of the story's `repos`).
+- `task`  — the ONE atomic task ID to implement, e.g. `T01` (ask if not provided).
+
+## On Activation
+
+### Step 1 — Resolve the spec and the task
+Read `demo-repos/<repo>/specs/<story>/tasks.md`. Find the block for `<task>` (`## <task> — …`). Read
+its one-line goal and its **Files:** list (the declared file boundary) and the acceptance criterion it
+satisfies. If the task ID is not in `tasks.md`, STOP. Confirm the spec exists (Step A ran); if not,
+STOP and point at `sdlc-spec`.
+
+### Step 2 — Resolve the code repo and branch
+Confirm `demo-repos/<repo>/` is its own git repo (`.git` present). From its default branch, create the
+task branch `feat/<story>-<task>-<short-slug>`. If a branch for this task already exists, reuse it
+rather than forking a second one (one task = one branch).
+
+**On the first implement in a repo, install the commit template** (idempotent): copy this skill's
+`templates/.gitmessage` to `<repo>/.gitmessage` and run `git -C <repo> config commit.template .gitmessage`
+so every commit is pre-scaffolded with the `Task:` trailer and the commented per-commit `Co-Authored-By:`
+choices (`config.yaml` `build.ai_coauthor.allowed`). Do the same at the hub root for hub commits. Skip if
+already configured.
+
+### Step 3 — Read the spec inputs (do NOT re-derive the contract)
+Read the story's `spec.md`, `plan.md`, `data-model.md`, and `contracts/` for this task's context. The
+contract slice is **quoted** from the product repo's locked `contract.md` — implement to it, never
+change it here.
+
+### Step 4 — Implement the task (dev lens), inside the declared files ONLY
+Adopt the **dev** lens. Implement the task's goal so it satisfies its acceptance criterion, touching
+**only the files in the task's `Files:` list** (≤3 where possible). Write real, working code — tests
+must exercise behavior, not just pass (build plan §C). **Before committing, run a smoke or test that
+actually exercises the task's acceptance criterion** — the task is not done until the criterion is
+demonstrably met (record the result in the Step 7 report).
+
+**File-boundary rule (hard):** if the implementation genuinely needs a file **not** in the declared
+list, **flag and STOP** — do not silently widen the diff. Report the extra file(s) needed so the
+task's spec can be corrected (re-run `sdlc-spec` / re-scope the task) before implementing. A task whose
+declared files are wrong is a spec bug, not an implementation decision.
+
+This stop is a **scope overrun** — a halt condition that pulls in a human regardless of any automation
+dial. When this step is driven by the orchestrator (`sdlc-run`, Phase 4), the stop must be legible to
+it: mark the `implement` step `status: blocked` in `build-state/<story>.json` and surface
+`scope_overrun: true` so the run records a `rejected` trust entry and halts (it never advances past a
+boundary breach). The same applies to the Step 5 contract-surface stop (`contract_touch: true`).
+
+### Step 5 — Contract-surface check (local pre-flight for Step C)
+Determine whether the diff touches the **locked contract surface** (the API/event/data-model shapes in
+`epics/<epic>/contract.md`'s `CONTRACT-SURFACE` block). Normal implementation **consumes** the
+contract (e.g. implementing `POST /inquiries` to the agreed shape) — that is **not** a contract change.
+A contract change means the diff alters the agreed cross-repo shape itself.
+
+- If the diff does **not** change the surface: proceed; no `Contract-Change` trailer.
+- If the task **requires** changing the surface: **flag and STOP**. The contract is owned upstream;
+  route back to the **architecture gate** to amend and re-lock `contract.md` first. Only then return
+  here, and record `Contract-Change: yes` in the commit body (the Step C contract-check will require a
+  matching, already-updated contract).
+
+### Step 6 — Commit on the task branch
+Stage only the declared files. Commit with the convention: a conventional subject, a short body, and a
+`Task: <story>-<task>` trailer (plus `Contract-Change: yes` if Step 5 applies). The human author owns the
+commit; if an AI tool helped author this diff, add its `Co-Authored-By:` line from
+`config.yaml` `build.ai_coauthor.allowed` (the `.gitmessage` template scaffolds the choices). Keep all
+trailers in one contiguous block. Do not commit sibling tasks' work.
+
+### Step 7 — Report; the advance decision belongs to the dial (Phase 4)
+Report: the branch name, the files changed, how the change satisfies the task's acceptance criterion,
+the result of any test/smoke run, and the next action — the **check gates** (Step C — `sdlc-checks`)
+then the PR and review (Steps D–E). Do **not** open a PR, merge, or hand-edit the epic's front-half
+`state.json`. Step B ends at a committed task branch.
+
+- **Run standalone:** stop here; a human triggers the gates.
+- **Run by the orchestrator** (`sdlc-run`): this skill still just produces the committed branch and
+  signals success (or a scope/contract halt). The orchestrator records the `implement` step's status
+  and trust entry and, when `implement` is earned to `machine_advance` (Step D, Phase 4b), **auto-runs
+  the check gates** instead of waiting for a manual nudge. The diff still cannot merge without the
+  gates passing and the engineer review — Step D removes only the "now run the gates" hand-off.
+
+### Step 8 — Record the `tasks` trust signal on first consume (Phase 4b)
+Resolving a task from `tasks.md` (Step 1) is the moment the generated task list "survives contact" —
+the evidence that could later earn the `tasks` step a `machine_advance`. When driven by `sdlc-run`,
+finalize a `tasks` trust entry, anchored to what the human/dev actually did with the list:
+- the task is implemented with its declared `Files:`/scope **as generated** → `approved-unchanged`;
+- the task is **re-scoped** first (its `Files:`/boundary edited) → `approved-with-edits`
+  (signal `task_rescoped: true`);
+- the task list is discarded / regenerated → `rejected`.
+Append the entry to `epics/<epic>/.sdlc/trust-log.json` (schema:
+`../sdlc-author-epic/references/state-schema.md`). `tasks` stays `human_approve` until its slice clears
+the threshold — this only *gathers* evidence. (The `implement` step's own verdict is finalized later,
+at the engineer review in `sdlc-ship`: merged as authored → `approved-unchanged`; edited first →
+`approved-with-edits`; scope/contract/checks halt → `rejected`.)
+
+## Hard rules (build plan §B, Cross-cutting)
+
+- **One atomic task = one branch = one PR/MR.** Never bundle tasks; never exceed the declared files.
+- **Light loop per task.** Do not re-run the heavy spec ceremony; that already ran once in Step A.
+- **Never widen the contract here.** Surface changes go back to the architecture gate (Step 5).
+- **The step never advances itself.** A scope overrun or contract touch always halts. The
+  `implement → checks` hand-off advances only when the orchestrator's `implement` dial is
+  `machine_advance` (earned, Step D) — and never past the engineer review, which is always human.
+  Standalone, the step stops at a committed branch.
+
+## Reference
+- Branch/commit conventions, the file-boundary rule, the Contract-Change rule: `references/implement-conventions.md`.
+- The task list this step consumes: Step A's `references/spec-handoff.md` (`../sdlc-spec/...`).
+- Contract surface + hash recipe: `../sdlc-author-architecture/references/contract-format.md`.

package/skills/sdlc-implement/references/implement-conventions.md

@@ -0,0 +1,103 @@
+# Implement conventions — branch, commit, file boundary, contract change
+
+Step B (`sdlc-implement`) turns ONE atomic task into ONE branch and ONE commit in the code repo. These
+conventions are what the later steps (check gates §C, PR template §D, review §E) rely on to trace a
+diff back to its task, story, and contract.
+
+## Branch naming
+
+```
+feat/<story-id>-<task-id>-<short-slug>
+```
+
+- `<story-id>` — the permanent story ID, e.g. `EP-istifta-inquiries-S01`.
+- `<task-id>` — the atomic task ID from `tasks.md`, e.g. `T01`.
+- `<short-slug>` — 2–4 hyphenated words naming the change, e.g. `create-inquiry`.
+
+Example: `feat/EP-istifta-inquiries-S01-T01-create-inquiry`. Branched off the code repo's default
+branch. One task = one branch; never reuse a branch for a different task, never fork a second branch
+for the same task.
+
+## Commit message
+
+```
+<type>: <subject ending with what changed>
+
+<body — what and why, 1–3 lines>
+
+Task: <story-id>-<task-id>
+[Contract-Change: yes]
+[Co-Authored-By: <AI name> <email>]
+```
+
+- The **`<type>` is lowercase** (`feat`, `fix`, `docs`, `refactor`, `test`, `perf`, `build`, `ci`,
+  `chore`, `revert`) and the **`<subject>` starts lowercase**, is **imperative**, and has **no trailing
+  period** — Conventional Commits (see `CONTRIBUTING.md` and `config.yaml` `build.commit_subject_style`).
+  Proper nouns/acronyms keep their case (`fix: refresh OAuth token`). e.g. `feat: add POST /inquiries
+  create path`, not `feat: Add POST /inquiries create path.`
+- The **`Task:` trailer is required** (`Task: EP-istifta-inquiries-S01-T01`) — the anchor the spec-link
+  check (§C) and the PR (§D) read to connect the diff to its spec and story. It need not be the *last*
+  line: the spec-link gate finds it with git's native trailer parser
+  (`%(trailers:key=Task)`), which is order-independent. All trailers must sit in **one contiguous block**
+  in the last paragraph (no blank lines between them) so git parses them as trailers.
+- **Trailer order:** `Task:` → `Contract-Change:` (if any) → `Co-Authored-By:` (if any), last.
+- `Contract-Change: yes` appears **only** when the diff alters the locked contract surface (see below).
+  Omit it for normal implementation.
+
+## Commit ownership & AI co-authors
+
+The **human git author owns the commit** (`config.yaml` `build.commit_owner: git_author`). When an AI
+tool assisted, record it **per commit** as a `Co-Authored-By` trailer — the AI is a co-author, **never**
+the author. The owner picks the tool from `config.yaml` `build.ai_coauthor.allowed`:
+
+```
+Co-Authored-By: Claude <noreply@anthropic.com>
+Co-Authored-By: GitHub Copilot <copilot@users.noreply.github.com>
+Co-Authored-By: Cursor <noreply@cursor.com>
+Co-Authored-By: CodeRabbit <noreply@coderabbit.ai>
+```
+
+- Choose the entry whose `id` matches the tool that actually helped author the diff; add more than one
+  line if several did. CodeRabbit is a co-author only when it **contributed code**, not when it merely
+  reviewed (that is `ai_review` in `sdlc-ship`).
+- For a fully human-authored commit, pick `id: none` — i.e. **omit** the trailer. `ai_coauthor.required`
+  is `false`, so a missing trailer is valid and no gate fails on it.
+- `sdlc-implement` installs the `.gitmessage` template (`templates/.gitmessage`) and sets
+  `git config commit.template .gitmessage` in the repo, so these lines are pre-scaffolded (commented) for
+  the owner to uncomment.
+
+## File-boundary rule (hard stop)
+
+Each task in `tasks.md` declares a `Files:` list (≤3 where possible). The implementation diff must stay
+**inside that list**. If the task genuinely needs a file not listed:
+
+1. **Stop.** Do not widen the diff silently.
+2. Report the extra file(s) needed.
+3. Treat it as a **spec bug**: the task's declared files were wrong. Correct the task (re-run
+   `sdlc-spec` / re-scope) so the boundary is right, then implement.
+
+A diff that quietly spreads beyond the declared files is the single easiest way to smuggle unreviewed
+scope past the gates — hence the hard stop.
+
+## Contract-change rule
+
+The **locked contract surface** is the cross-repo agreement in `epics/<epic>/contract.md` (the
+`CONTRACT-SURFACE` block, hash-locked at `.sdlc/contract-lock.json`). Distinguish:
+
+- **Consuming the contract** (normal) — implementing an endpoint/event/entity to the shape the contract
+  already agreed (e.g. building `POST /inquiries` to its agreed request/response). **Not** a contract
+  change; no trailer.
+- **Changing the contract** (exceptional) — altering the agreed shape itself (new field crossing repos,
+  changed status enum, new shared endpoint). This is **not** an implementation decision. Stop, go back
+  to the **architecture gate**, amend and re-lock `contract.md` (which re-escalates that review per the
+  contract `risk_tags`), and only then implement — recording `Contract-Change: yes` so the §C
+  contract-check finds the matching, already-updated contract.
+
+This keeps the contract singular and owned upstream: a code repo can never widen the shared surface
+from inside an implementation branch.
+
+## Why one task at a time
+
+Small diffs scoped to declared files are reviewable, revertable, and traceable. The heavy spec ceremony
+(specify→tasks) ran once for the whole story in Step A; Step B is the **light loop** — repeat per task,
+each its own branch and PR, each passing the gates independently.

package/skills/sdlc-implement/templates/.gitmessage

@@ -0,0 +1,17 @@
+# <type>: <subject — lowercase, imperative, no trailing period>
+#   types: feat fix docs refactor test perf build ci chore revert
+#
+# <body — what changed and why, 1–3 lines. Wrap at ~72 cols.>
+#
+# --- Trailers (keep them in ONE contiguous block below, no blank lines between) ---
+# Task: is REQUIRED — it anchors the spec-link gate. Order: Task -> Contract-Change -> Co-Authored-By.
+Task: <EP-slug-S0N-T0N>
+# Contract-Change: yes        # ONLY if this diff alters the locked contract surface (routes to architecture gate)
+#
+# Per-commit AI co-author (the HUMAN git author owns the commit; AI is only a co-author).
+# Uncomment the line for the tool that actually helped author this diff (add more than one if needed).
+# Leave all commented for a fully human-authored commit (id: none — the trailer is optional).
+# Co-Authored-By: Claude <noreply@anthropic.com>
+# Co-Authored-By: GitHub Copilot <copilot@users.noreply.github.com>
+# Co-Authored-By: Cursor <noreply@cursor.com>
+# Co-Authored-By: CodeRabbit <noreply@coderabbit.ai>

package/skills/sdlc-pr-template/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: sdlc-pr-template
+description: 'Build-half Step D of the gated SDLC. Detect a code repo''s platform and commit the matching PR/MR template — .github/pull_request_template.md (GitHub) or .gitlab/merge_request_templates/Default.md (GitLab). The template carries an Impact & Risk block; a high risk level (or a touched contract/auth/payments surface) routes the review to domain owners, reusing sdlc-review-gate''s escalation. Includes risk-route.sh to print the required reviewers from a PR body. Never auto-advances. Use when the user says "add the PR template" or "set up the MR template" for a repo.'
+---
+
+# SDLC — PR/MR Template (build-half Step D)
+
+**Goal:** Commit the platform-correct PR/MR template into a code repo so every PR/MR carries an
+**Impact & Risk** block and a checklist tied to the check gates. A **high** risk level (or a touched
+contract/auth/payments surface) **routes the review to domain owners** — the same escalation
+`sdlc-review-gate` applies on the front-half gates (owner + 1 reviewer, plus one domain-owner per
+touched domain). This step **never auto-advances**; it sets up the template and the routing helper.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory — the **product** repo (holds the
+  canonical templates under this skill).
+- Code repos are separate git repos under `{project-root}/demo-repos/<repo>/`.
+- Canonical sources live in this skill's `templates/`:
+  - `templates/github/pull_request_template.md` → installs to `<repo>/.github/pull_request_template.md`
+  - `templates/gitlab/merge_request_templates/Default.md` → installs to
+    `<repo>/.gitlab/merge_request_templates/Default.md`
+  - `templates/checks/risk-route.sh` → installs to `<repo>/checks/risk-route.sh` (advisory routing helper)
+  - **Hub variants** (`repo: hub`) — front-half artifact-review PR/MR bodies:
+    `templates/hub/github/pull_request_template.md` → `{project-root}/.github/pull_request_template.md`;
+    `templates/hub/gitlab/merge_request_templates/Default.md` →
+    `{project-root}/.gitlab/merge_request_templates/Default.md`. The hub body carries no `Task:` trailer
+    (hub PRs change artifacts, not code); its routing helper is `sdlc-hub-bridge`'s `hub-route.sh`.
+- The Impact & Risk block reuses the conventions of earlier steps: the `Task: <story>-<task>` trailer
+  (`sdlc-implement`), the contract surface (`sdlc-author-architecture` / contract-check), and the
+  domain-owner escalation (`sdlc-review-gate`).
+- **PR/MR title.** One atomic task = one branch = one PR/MR, so the title **defaults to that task's
+  commit subject** and follows the same Conventional Commits style — `<type>: <lowercase imperative
+  description, no trailing period>`, proper nouns/acronyms keep their case (`config.yaml`
+  `build.pr_title_style`; see `CONTRIBUTING.md`). Because PRs are squash-merged, the title becomes the
+  merge commit subject — so it must be the clean, lowercase-after-the-type form, not `Fix: ...` or a
+  trailing period.
+
+## Inputs
+
+- `repo`   — the code repo to add the template to (one of an epic's repos), or `hub` for the product hub.
+- `action` — `wire` (commit the matching template + helper) | `route` (print required reviewers from a
+  PR body). Default `wire`.
+- `body`   — for `route`: a file holding the PR/MR description to evaluate.
+
+## On Activation
+
+### Step 1 — Resolve the repo and detect the platform
+Map `repo` → `{project-root}/demo-repos/<repo>/` (or the registry `path`). Detect the platform: a GitHub
+remote or `.github/` → GitHub; a GitLab remote or `.gitlab/` → GitLab. If ambiguous, ask. For
+`repo: hub`, the target is `{project-root}` itself and the platform comes from `.sdlc/hub.json`.
+
+### Step 2 — `wire` (drop only the matching template)
+Copy from this skill's `templates/`:
+- GitHub → `templates/github/pull_request_template.md` to `<repo>/.github/pull_request_template.md`.
+- GitLab → `templates/gitlab/merge_request_templates/Default.md` to
+  `<repo>/.gitlab/merge_request_templates/Default.md`.
+- **`repo: hub`** → use the `templates/hub/<platform>/…` variants, installed into `{project-root}`'s own
+  `.github/`/`.gitlab/`. The hub's routing helper (`hub-route.sh`) is installed by `sdlc-hub-bridge`.
+Drop **only the matching** template (drop both only if the repo genuinely uses both). For code repos also
+install `templates/checks/risk-route.sh` to `<repo>/checks/` (`chmod +x`). If the target already has a
+non-SDLC PR/MR template, do not clobber it — back it up / ask. Commit the template on the repo's default
+branch (shared infrastructure, not a task diff).
+
+### Step 3 — `route` (show who must review)
+Run `bash checks/risk-route.sh <body>` to parse the PR description's Impact & Risk block and print the
+required reviewers:
+- **low | medium** risk → base rule: owner + 1 reviewer.
+- **high** risk (or a contract/auth/payments surface touched) → base rule **plus** one domain-owner
+  approval per touched domain — identical to `sdlc-review-gate`'s escalation. The actual approvals are
+  recorded by the engineer review (Step E), via `sdlc-review-gate`.
+
+### Step 4 — Stop (no auto-advance)
+Report what was committed (or the routing result). The template and routing are advisory inputs to the
+human review (Step E); they do not approve or merge. Do not touch the epic's `.sdlc/` state.
+
+## Hard rules (build plan §D, Cross-cutting)
+
+- **Drop only the matching template** for the detected platform.
+- **High risk routes to domain owners** — the same escalation as the gate; never a separate rule.
+- **Nothing auto-advances.** The template sets up review; the human owns the merge.
+
+## Reference
+- The Impact & Risk block, the risk levels, and the routing rule: `references/risk-routing.md`.
+- The escalation this reuses: `../sdlc-review-gate/SKILL.md` and its `references/gating.md`.
+- The check gates the checklist references: `../sdlc-checks/references/check-gates.md`.

package/skills/sdlc-pr-template/references/risk-routing.md

@@ -0,0 +1,54 @@
+# Impact & Risk block and review routing
+
+The PR/MR template (Phase 3 build plan §D) carries an **Impact & Risk** block so every change states
+its blast radius before review, and so high-risk changes pull in the right reviewers automatically —
+reusing the escalation `sdlc-review-gate` already applies on the front-half gates.
+
+## The Impact & Risk block
+
+```
+## Impact & Risk
+- **Domains / repos touched:** <backend | mobile | …>
+- **Contract surface touched:** no
+- **Risk level:** low
+- **Rollback plan:** <how to revert>
+```
+
+- **Domains / repos touched** — the domains this change affects; these are the candidate domain owners
+  when the change escalates.
+- **Contract surface touched** — `yes` means the diff changes the shared contract surface. That path is
+  governed by `contract-check` (needs `Contract-Change: yes` + a re-locked contract) AND it escalates
+  the review (contract is a `sdlc-review-gate` risk tag).
+- **Risk level** — `low | medium | high`. The author's assessment of blast radius.
+- **Rollback plan** — how to revert safely.
+
+## Routing rule (reuses the gate's escalation)
+
+| Condition | Required reviewers |
+|-----------|--------------------|
+| `low` / `medium`, no sensitive surface | **base rule:** owner + 1 reviewer |
+| `high`, OR a touched contract/auth/payments surface | base rule **plus one domain-owner approval per touched domain** |
+
+This is exactly `sdlc-review-gate`'s rule (`references/gating.md`): the base rule is owner + 1
+reviewer; escalation adds a domain-owner per touched domain. The PR template applies the same logic at
+the code-review boundary so a risky PR cannot be approved by just any two people. The **approvals are
+recorded by the engineer review (Step E) through `sdlc-review-gate`** — the template and `risk-route.sh`
+only *route* (advisory); they never approve or merge.
+
+## risk-route.sh
+
+`bash checks/risk-route.sh <pr-description-file>` parses the Impact & Risk block and prints the required
+reviewers. Example (high risk, two domains):
+
+```
+Risk level: high
+Contract surface touched: no
+Domains touched: backend, mobile
+ROUTE: ESCALATED (risk: high) -> owner + 1 reviewer PLUS one domain-owner approval per touched domain
+       (same escalation as sdlc-review-gate). Required domain owners:
+  - domain-owner: backend
+  - domain-owner: mobile
+```
+
+It is **advisory** — not a blocking gate. CI may run it to comment the required reviewers; the human
+review (Step E) still owns the merge.