yadflow 1.0.1

package/skills/sdlc-author-stories/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: sdlc-author-stories
+description: 'Front state 7 of the gated SDLC. With the pm, break the approved epic into user stories, each tagged with the repos that must implement it. Assigns zero-padded EP-<slug>-S0N IDs and writes one file per story under stories/. Reads epic + architecture + contract + UI as input. Never auto-advances — hands off to the team review gate (per-repo reviewer routing). Use when the user says "author the stories" or after the UI gate passes.'
+---
+
+# SDLC — Author Stories (front state 7)
+
+**Goal:** Break an approved epic into human-authored, AI-assisted user stories, each with a stable
+`EP-<slug>-S0N` ID and a `repos` tag listing which repos must implement it. This is a **front state**:
+human-authored with AI assist, **never auto-advances**. When the stories are drafted, control passes
+to `sdlc-review-gate`, which routes **per-repo reviewers** (each repo's engineer reviews the stories
+touching their repo).
+
+There is **no `sm` agent** (Phase 0 Deviation 1): the `pm` lens breaks down the epic; the `pm` or
+`architect` lens prepares each story's detail. IDs are engine-assigned and never renamed.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory.
+- Stories live under `{project-root}/epics/EP-<slug>/stories/` (build plan §6).
+- Story files are named `EP-<slug>-S0N.md` (zero-padded, e.g. `EP-istifta-inquiries-S01.md`).
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## On Activation
+
+### Step 1 — Resolve the epic and check the gate
+Resolve the `EP-<slug>` (ask if not provided). Read `.sdlc/state.json`. Only proceed when
+`currentStep == "stories"` and that step's `status == "in_progress"` (the UI review must already have
+passed). If not, stop and point the user at `sdlc-status` / the gate.
+
+### Step 1b — Open the authoring branch
+Open the stories authoring branch `stories/EP-<slug>` per the shared procedure
+(`../sdlc-author-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note
+if `{project-root}` is not a git work tree), check out the branch if it exists, else create it from the
+hub's default branch. Author and commit the story files under `stories/` on it. This is **distinct**
+from the bridge's `review/…` branch.
+
+### Step 2 — Read inputs
+Read `epic.md` (scope, acceptance signals, `repos`), `architecture.md` (components by repo, flows),
+`contract.md` (the shared surface stories must honour), and `ui-design.md` (screens/flows). Stories
+must collectively satisfy the epic's acceptance signals and stay within the contract surface.
+
+### Step 2b — Load existing-code context (make the brain code-aware)
+Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **each repo in
+`epic.repos`**, load the code-map `{project-root}/.sdlc/code-context/<repo>/code-map.md` so each story's
+**"Notes for build"** can point at the **real existing modules/files** a story extends — giving the
+Phase 3 build (Spec Kit per repo) accurate anchors instead of invented ones.
+
+- **Greenfield-safe:** if `repos.json` is absent/empty, note "no repos connected" and proceed.
+- **Staleness:** if a repo's current HEAD ≠ its registry `syncedHead`, warn and suggest
+  `sdlc repo refresh <repo>` (a human decision — flag and stop, never auto-refresh); stamp
+  `code-context: stale` in the story frontmatter.
+- **Traceability:** record the loaded maps in each story's `code-context:` frontmatter field.
+
+### Step 3 — Break down the epic (assist: pm)
+Adopt the **pm** lens (`bmad-agent-pm`, John). Decompose the epic into the smallest set of
+independently reviewable, independently buildable stories. For each story decide which repos it touches
+(must be a subset of the epic's `repos`). Prefer stories scoped to a clear slice of user value.
+
+### Step 4 — Assign IDs (engine-assigned, never by hand)
+Scan `stories/` for existing `EP-<slug>-S0N.md`. Assign the next zero-padded numbers continuing from
+the highest existing one (`S01`, `S02`, …). **Never renumber or rename** an existing story — IDs are
+permanent downstream links (build plan §6b).
+
+### Step 5 — Prepare each story (assist: pm / architect)
+Write one file per story, `{project-root}/epics/EP-<slug>/stories/EP-<slug>-S0N.md`, using EXACTLY this
+template (see `references/story-schema.md`):
+
+```markdown
+---
+id: EP-<slug>-S0N
+epic: EP-<slug>
+status: draft
+owner: <inherit from epic.md owner>   # the epic owner carries through; not retyped
+repos: [<subset of epic.repos this story implements>]
+code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # code-maps anchoring "Notes for build" (Step 2b)
+---
+
+## Story
+As a <role>, I want <capability>, so that <outcome>.
+
+## Acceptance criteria
+- [ ] <testable criterion>
+- [ ] <testable criterion>
+
+## Notes for build
+<!-- contract surface touched, architecture components involved, UI screens -->
+<!-- this is the context the Phase 3 build (Spec Kit per repo) will read -->
+```
+
+`repos` is the field the later build phase reads to know where to scaffold specs — set it precisely.
+
+### Step 6 — Advance the authoring step (NOT the gate)
+In `state.json`: set `stories.status: "done"`, set `stories-review.status: "in_review"`, and set
+`currentStep: "stories-review"`. Write `state.json`. Do **not** touch `approvals.json`.
+
+### Step 7 — Stop at the gate (do NOT advance)
+Report: the story IDs created, the repos each touches, and that the next action is **review** via
+`sdlc-review-gate`. Note that this review routes **per-repo reviewers**: owner + 1 reviewer **plus**, for
+each repo appearing in any story's `repos`, a `domain-owner` approval for that repo. **Never record
+approval here.** Front states do not auto-advance. When the hub has a platform, the gate opens a review
+PR on the hub (via `sdlc-hub-bridge`, with a `domain:<repo>` label per touched repo) and
+`sdlc-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review
+is recorded file-only.
+
+## Reference
+- Story frontmatter and body template: `references/story-schema.md`.
+- State schema and field meanings: `../sdlc-author-epic/references/state-schema.md`.
+- Connecting code repos + the code-context the brain reads: `../sdlc-connect-repos/SKILL.md`.

package/skills/sdlc-author-stories/references/story-schema.md

@@ -0,0 +1,46 @@
+# Story schema
+
+Each story authored at front state 7 is one Markdown file under `epics/EP-<slug>/stories/`, named
+`EP-<slug>-S0N.md` (zero-padded, never renamed).
+
+## Frontmatter
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| `id` | `EP-<slug>-S0N` | Stable story ID. Engine-assigned, zero-padded, never renamed. |
+| `epic` | `EP-<slug>` | Parent epic ID — the unbroken link back to the epic. |
+| `owner` | name | Inherited from `epic.md` `owner` (the single source — not retyped per story). Carries the responsible owner through to the build half. |
+| `status` | `draft` \| `in_review` \| `approved` | Story lifecycle within the stories gate. |
+| `repos` | subset of the epic's `repos` | Which repos must implement this story. **Drives per-repo review routing now and (Phase 3) where specs are scaffolded.** |
+| `code-context` | `{ repos: [<name@sha>], loaded: <date> }` | Optional. Which connected-repo code-maps anchored "Notes for build" (front state 7 Step 2b). The `@sha` (a repo's `syncedHead`) is recommended so freshness is recorded but may be omitted; the SKILL templates show the empty placeholder `{ repos: [], loaded: <date or none> }`. `none` / `[]` when no repos are connected. |
+
+## Body
+
+```markdown
+## Story
+As a <role>, I want <capability>, so that <outcome>.
+
+## Acceptance criteria
+- [ ] <testable criterion>
+- [ ] <testable criterion>
+
+## Notes for build
+<!-- contract surface touched, architecture components involved, UI screens -->
+```
+
+## Rules
+
+- **IDs are permanent.** Continue numbering from the highest existing `S0N`; never renumber. Renaming
+  breaks every downstream link (build plan §6b).
+- **`repos` must be a subset of `epic.repos`.** A story cannot touch a repo the epic does not declare.
+- **Acceptance criteria are testable.** They are what the Phase 3 build (Spec Kit `specify`→`tasks`)
+  and the check gates verify against.
+- **Stay within the contract surface.** "Notes for build" should reference the contract elements a
+  story touches; a story may not invent cross-repo surface that `contract.md` does not define.
+
+## Per-repo review routing (the stories gate)
+
+`sdlc-review-gate` treats each repo's engineer as the `domain-owner` for the stories touching that repo.
+The gate passes only when, in addition to the base rule (owner + 1 reviewer), **every repo appearing in
+any story's `repos`** has at least one `domain-owner` approval scoped to that repo (`domain` = repo
+name). The gate's `approved.md` lists which repos still lack sign-off.

package/skills/sdlc-author-ui/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: sdlc-author-ui
+description: 'Front state 5 of the gated SDLC. With the ux-designer, author ui-design.md and DESIGN.md for an approved architecture, driving Impeccable as harness slash-commands (document/extract/craft) when installed, or authoring directly when not. Reads epic + architecture as input. Never auto-advances — hands off to the team review gate. Use when the user says "author the UI design" or after the architecture gate passes.'
+---
+
+# SDLC — Author UI Design (front state 5)
+
+**Goal:** Produce a human-authored, AI-assisted `ui-design.md` and `DESIGN.md` for an approved
+architecture. This is a **front state**: human-authored with AI assist, **never auto-advances**. When
+the UI is drafted, control passes to `sdlc-review-gate` (base rule: owner + 1 reviewer).
+
+UI work is shaped by **Impeccable**, invoked as **harness slash-commands** (not a subprocess CLI) per
+the Phase 0 deviation. If Impeccable is not installed, the `ux-designer` lens authors the same outputs
+directly — the workflow does not block on the tool.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory.
+- Artifacts live under `{project-root}/epics/EP-<slug>/` (build plan §6).
+- `DESIGN.md` is Impeccable's conventional root design-system file (RESEARCH-NOTES §4).
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## On Activation
+
+### Step 1 — Resolve the epic and check the gate
+Resolve the `EP-<slug>` (ask if not provided). Read `.sdlc/state.json`. Only proceed when
+`currentStep == "ui-design"` and that step's `status == "in_progress"` (the architecture review must
+already have passed). If not, stop and point the user at `sdlc-status` / the gate.
+
+### Step 1b — Open the authoring branch
+Open the UI authoring branch `ui-design/EP-<slug>` per the shared procedure
+(`../sdlc-author-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note
+if `{project-root}` is not a git work tree), check out the branch if it exists, else create it from the
+hub's default branch. Author and commit `ui-design.md` / `DESIGN.md` on it. This is **distinct** from
+the bridge's `review/…` branch.
+
+### Step 2 — Read inputs
+Read `epic.md` (user-level acceptance signals, scope) and `architecture.md` (flows, components by
+repo). The UI must cover the user-facing flows the architecture defines.
+
+### Step 2b — Load existing-code context (make the brain code-aware)
+Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **each repo in
+`epic.repos`**, load the code-map `{project-root}/.sdlc/code-context/<repo>/code-map.md` so the UI
+**reuses existing components and conventions** rather than inventing parallel ones. This complements
+Impeccable's `/impeccable document` (Step 3), which reads code directly for the design system — when
+Impeccable is absent, the code-map is the brain's view of what UI/components already exist.
+
+- **Greenfield-safe:** if `repos.json` is absent/empty, note "no repos connected" and proceed.
+- **Staleness:** if a repo's current HEAD ≠ its registry `syncedHead`, warn and suggest
+  `sdlc repo refresh <repo>` (a human decision — flag and stop, never auto-refresh); stamp
+  `code-context: stale` in the frontmatter.
+- **Traceability:** record the loaded maps in the `ui-design.md` `code-context:` frontmatter field.
+
+### Step 3 — Shape the UI (assist: ux-designer + Impeccable slash-commands)
+Adopt the **ux-designer** lens (`bmad-agent-ux-designer`, Sally). Drive Impeccable as slash-commands:
+
+- **Existing project** (a codebase/design system already exists): `/impeccable document` → then
+  `/impeccable extract` → then `/impeccable craft`.
+- **New project** (no design system yet): `/impeccable craft` → then `/impeccable extract`.
+
+`/impeccable document` generates the root `DESIGN.md` from existing code; `/impeccable extract` pulls
+components/tokens into the design system; `/impeccable craft` is shape-then-build for the new screens.
+
+**Graceful degradation:** if Impeccable is not installed (no `/impeccable …` commands available), the
+`ux-designer` lens authors `ui-design.md` and `DESIGN.md` directly, and you **note in `ui-design.md`
+that Impeccable was not used**. Do not run `npx impeccable skills install` as part of this step — tool
+installation is out of scope for the front half.
+
+### Step 4 — Write the UI artifacts
+Write `{project-root}/epics/EP-<slug>/ui-design.md` using EXACTLY this template:
+
+```markdown
+---
+id: EP-<slug>
+artifact: ui-design
+status: draft
+owner: <inherit from epic.md owner>   # the epic owner carries through; not retyped
+repos: [<inherit from epic>]
+impeccable: <used | not-installed>
+code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # code-maps that informed component reuse (Step 2b)
+---
+
+## Screens & states
+<!-- one subsection per screen: purpose, key states (empty/loading/error/success) -->
+
+## User flows
+<!-- the click-paths that satisfy the epic's acceptance signals -->
+
+## Components & tokens
+<!-- components used; reference DESIGN.md tokens; what is new vs reused -->
+
+## Accessibility & responsiveness
+<!-- a11y notes; breakpoints/viewports covered -->
+```
+
+Also create/update `{project-root}/epics/EP-<slug>/DESIGN.md` (Impeccable's design-system file, or a
+hand-authored equivalent when degraded) capturing the design tokens/components the screens rely on.
+
+### Step 5 — Advance the authoring step (NOT the gate)
+In `state.json`: set `ui-design.status: "done"`, set `ui-design-review.status: "in_review"`, and set
+`currentStep: "ui-design-review"`. Write `state.json`. Do **not** touch `approvals.json`.
+
+### Step 6 — Stop at the gate (do NOT advance)
+Report: the paths to `ui-design.md` and `DESIGN.md`, whether Impeccable was used, and that the next
+action is **review** via `sdlc-review-gate` (base rule: owner + 1 reviewer). **Never record approval
+here.** Front states do not auto-advance. When the hub has a platform, the gate opens a review PR on the
+hub (via `sdlc-hub-bridge`) and `sdlc-review-gate action: sync` pulls platform approvals/comments into
+the ledger; otherwise the review is recorded file-only.
+
+## Reference
+- Impeccable commands and the slash-command-vs-CLI deviation: `RESEARCH-NOTES.md` §4 + Deviation 3.
+- State schema and field meanings: `../sdlc-author-epic/references/state-schema.md`.
+- Connecting code repos + the code-context the brain reads: `../sdlc-connect-repos/SKILL.md`.

package/skills/sdlc-backfill/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: sdlc-backfill
+description: 'Build-half Step G of the gated SDLC — backfill: generate specs for already-built features in an existing repo so new work does not break them. Confirm Repomix (the one true CLI subprocess: npx repomix), pack ONE feature at a time (compress + git logs, secret-scan), feed it to AI with a "describe what exists, do not invent" prompt, and write a DRAFT spec marked unverified. Require human approval (reuse sdlc-review-gate) before the spec counts as real. Boundary is auto-proposed from the project convention and human-confirmed. A change is blocked only until the features IT touches have approved specs. Use when the user says "backfill specs", "document an existing feature", or "spec the legacy code".'
+---
+
+# SDLC — Backfill (existing-code specs)
+
+**Goal:** Bring an existing repo (no specs) under the gated SDLC one **feature** at a time, by
+generating a spec for what is **already built** — so future changes have a contract to check against
+(build plan §G). The generated spec is a **draft, unverified** until a human approves it; only then does
+it count. Gating is **per touched feature**: a new change is blocked only until the features it touches
+have approved specs — never the whole repo at once.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory; code repos are separate git repos under
+  `{project-root}/demo-repos/<repo>/`.
+- **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).
+- Backfilled specs live in the code repo at `specs/backfill/<feature>/spec.md`.
+- A **feature** is the project's natural unit from the constitution (e.g. a module / a `src/<feature>/`
+  directory). Auto-propose the boundary from the convention; **a human confirms** it where the code
+  does not follow it.
+
+## Inputs
+
+- `repo` — the existing code repo to backfill.
+- `feature` — the feature name (and its file globs, e.g. `src/<feature>/**`).
+- `action` — `pack` | `draft` | `approve` | `gate` (default `pack`).
+
+## On Activation
+
+### Step 1 — Propose the boundary (auto-propose, human-confirm)
+From the constitution's convention (e.g. module = feature, or `src/<feature>/`), propose the feature's
+file set. Present it and **ask the human to confirm or adjust** the boundary before packing. Never
+guess silently where the code breaks the convention.
+
+### Step 2 — `pack` (Repomix, one feature)
+Run, from inside the repo, over **only this feature's files**:
+```
+npx repomix@latest --compress --include "<feature globs>" --include-logs --style markdown -o <out>.md
+```
+`--compress` (Tree-sitter structural compression) keeps it small; `--include-logs` adds the relevant
+git history (default 50; `--include-logs-count N` to change); Secretlint secret-scans by default. If a
+secret is reported, STOP and have it removed/redacted before continuing. (If `npx repomix` is
+unavailable, degrade: hand-assemble the same feature context and record `repomix: unavailable`.)
+
+### Step 3 — `draft` (describe what exists — do NOT invent)
+Feed the packed context to the AI with the **"describe what exists, do not invent"** instruction
+(`references/backfill.md`). Write `specs/backfill/<feature>/spec.md` describing the feature's actual
+endpoints/behaviour/data as built, with frontmatter:
+```yaml
+---
+feature: <feature>
+repo: <repo>
+artifact: backfill-spec
+status: draft
+verified: false        # not real until a human approves
+source: repomix         # or "repomix: unavailable" when degraded
+generated: <YYYY-MM-DD>
+---
+```
+Mark every uncertain item explicitly (`<!-- unverified: ... -->`); do not fill gaps with invented
+behaviour.
+
+### Step 4 — `approve` (human approval — reuse the gate)
+A human reads the draft against the real code and approves it with the same `human_approve` discipline
+as `sdlc-review-gate` (owner + 1 reviewer). On approval set the frontmatter `verified: true` and record
+the approver(s) + date. Only a `verified: true` backfill spec counts as real.
+
+### Step 5 — `gate` (block changes per touched feature)
+`bash checks/backfill-check.sh <base>` blocks a change that touches a feature being backfilled until
+that feature's spec is `verified: true`. It is **per touched feature** — a change touching feature A is
+not blocked by an unverified feature B. Forward-spec'd features (those with their own `specs/<story>/`)
+are not this gate's concern.
+
+### Step 6 — Stop (no auto-advance)
+Report the packed feature, the draft path (or the approval), and what is still unverified. Nothing
+auto-advances; a human owns the approval.
+
+## Hard rules (build plan §G, Cross-cutting)
+
+- **Describe what exists; never invent.** A backfill spec is a record of built behaviour, not a design.
+- **Draft until human-approved.** `verified: false` specs do not count; approval reuses the gate.
+- **One feature at a time; gate per touched feature.** Never block the whole repo.
+- **Repomix via its real CLI** (Phase 0); secret-scan before any AI sees the code.
+
+## Reference
+- The "describe what exists" prompt, the spec shape, and the gate: `references/backfill.md`.
+- The human approval discipline reused: `../sdlc-review-gate/SKILL.md`.
+- Repomix flags: `RESEARCH-NOTES.md` §3.

package/skills/sdlc-backfill/references/backfill.md

@@ -0,0 +1,66 @@
+# Backfill — Repomix pack, the "describe what exists" prompt, and the gate
+
+Backfill (build plan §G) brings an existing repo under the gated SDLC **one feature at a time**, by
+recording what is already built as a spec a human approves. It never invents behaviour and never blocks
+the whole repo.
+
+## Repomix (the one true CLI subprocess)
+
+`npx repomix@latest [flags]` (Phase 0 / RESEARCH-NOTES §3). For a single feature:
+
+```
+npx repomix@latest --compress --include "src/<feature>/**" --include-logs --style markdown -o <out>.md
+```
+
+- `--compress` — Tree-sitter structural compression (keeps the pack small and signal-dense).
+- `--include "<glob,glob>"` — restrict to this feature's files (one feature at a time).
+- `--include-logs` — add the relevant git commit history (default 50; `--include-logs-count N`).
+- `--style markdown` — human/AI-readable; default output is `repomix-output.xml`.
+- **Secretlint runs by default** — if a secret is reported, STOP and redact before any AI sees the code.
+
+If `npx repomix` is unavailable, degrade: hand-assemble the same feature context (the feature's files +
+recent git log for those paths) and record `repomix: unavailable` in the spec frontmatter.
+
+## The "describe what exists, do not invent" prompt
+
+> You are documenting an ALREADY-BUILT feature from its packed source + git history. Describe ONLY what
+> the code actually does: its endpoints/inputs/outputs, behaviour, and data as built. Do NOT invent
+> requirements, do NOT propose changes, do NOT fill gaps with assumptions. Where the behaviour is
+> unclear from the code, mark it `<!-- unverified: ... -->` rather than guessing. Output a spec a human
+> can confirm against the code.
+
+## The backfill spec
+
+`specs/backfill/<feature>/spec.md`:
+
+```yaml
+---
+feature: <feature>
+repo: <repo>
+artifact: backfill-spec
+status: draft
+verified: false
+source: repomix
+generated: <YYYY-MM-DD>
+---
+```
+
+`verified: false` until a human approves (the `sdlc-review-gate` discipline: owner + 1 reviewer). On
+approval, set `verified: true` and record the approver(s) + date. Only a `verified: true` backfill spec
+counts as real.
+
+## Boundary detection (auto-propose, human-confirm)
+
+Propose the feature's file set from the project convention (e.g. a module or a `src/<feature>/`
+directory — from the constitution). Present it; a human confirms or adjusts where the code does not
+follow the convention. Never finalise a boundary silently.
+
+## The gate — `checks/backfill-check.sh`
+
+A change is blocked **only until the features it touches** have approved specs — not the whole repo:
+
+- For each `src/<feature>/` the diff touches, if `specs/backfill/<feature>/spec.md` exists it must be
+  `verified: true`; otherwise **FAIL** (run backfill + approve for that feature first).
+- A feature with **no** `specs/backfill/<feature>/` is not this gate's concern (it is either
+  forward-spec'd via `sdlc-spec`, or not yet being backfilled).
+- Fails closed on an unresolvable base ref, like the other gates.

package/skills/sdlc-backfill/templates/checks/backfill-check.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# backfill gate (Phase 3 build plan §G). A change that touches a feature being backfilled must wait
+# until that feature's backfill spec is human-approved (verified: true). Gated PER touched feature, not
+# the whole repo: touching feature A is never blocked by an unverified feature B. Features that are
+# forward-spec'd (their own specs/<story>/) or not yet being backfilled are not this gate's concern.
+set -euo pipefail
+
+BASE="${1:-${SDLC_BASE:-origin/main}}"
+if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
+  echo "FAIL [backfill]: base ref '${BASE}' not found — fetch full history / check the base branch."
+  exit 1
+fi
+
+changed="$(git diff --name-only "${BASE}..HEAD")"
+# Feature = a directory under src/ (src/<feature>/...). Top-level src/*.js files are deliberately NOT
+# gated here (they belong to no single feature); only src/<feature>/ changes are checked.
+feats="$(printf '%s\n' "$changed" | sed -nE 's#^src/([^/]+)/.*#\1#p' | sort -u)"
+
+if [ -z "$feats" ]; then
+  echo "PASS [backfill]: no src/<feature> changes."
+  exit 0
+fi
+
+rc=0
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  spec="specs/backfill/${f}/spec.md"
+  [ -f "$spec" ] || { echo "note [backfill]: ${f} is not being backfilled (no ${spec}) — skipped."; continue; }
+  # Read ONLY the YAML frontmatter (between the first two --- lines) so a prose line that merely
+  # contains "verified: true" cannot false-pass the gate.
+  fm="$(awk 'NR==1 && /^---[[:space:]]*$/ {f=1; next} f && /^---[[:space:]]*$/ {exit} f {print}' "$spec")"
+  if printf '%s\n' "$fm" | grep -qiE '^verified:[[:space:]]*true[[:space:]]*$'; then
+    echo "PASS [backfill]: ${f} has an approved (verified) backfill spec."
+  else
+    echo "FAIL [backfill]: ${f} is being backfilled but its spec is not yet human-approved (verified: true)."
+    echo "  -> run sdlc-backfill approve for ${spec} before changing this feature."
+    rc=1
+  fi
+done <<EOF
+$feats
+EOF
+exit "$rc"

package/skills/sdlc-checks/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: sdlc-checks
+description: 'Build-half Step C of the gated SDLC — the production-safety check gates. Wire and run the CI gates on a code repo: spec-link (every change links a real story/spec via its Task trailer), contract-check (a diff that changes the contract surface without a Contract-Change + an updated, re-locked contract FAILS and routes back to the architecture gate), build/test/lint, and verified-commits (no unverified commits from unverified users — platform-Verified signature + roster-allowlisted author, on the hub and every repo). The gates are CI-agnostic bash, invoked by GitHub Actions and GitLab CI. Use when the user says "wire the check gates", "run the gates", "require signed commits", or "set up CI checks" for a repo.'
+---
+
+# SDLC — Check Gates (build-half Step C)
+
+**Goal:** Install and run the **check gates** that protect production for a code repo. They run
+in CI on every PR/MR and must pass before merge (build plan §C). Each is a small, separate check:
+
+1. **spec-link** — the change links a real story/spec: its commits carry a `Task: <story>-<task>`
+   trailer (the convention `sdlc-implement` writes) whose `<story>` resolves to `specs/<story>/link.md`.
+   No unlinked code reaches merge.
+2. **contract-check** — if the diff changes the **contract surface** (the repo's quoted slice under
+   `specs/<story>/contracts/`) without a `Contract-Change: yes` trailer **and** an updated, re-locked
+   contract upstream, it **FAILS and routes back to the architecture gate**. The shared surface is
+   never widened from inside a code repo (Phase 2 contract representation: delimited block + SHA-256 lock).
+3. **build/test/lint** — standard quality stage; tests must actually exercise new behavior, not just pass.
+4. **verified-commits** — no unverified commits from unverified users: every commit in the range must
+   carry a signature the platform marks **Verified** AND be authored by a known identity
+   (`.sdlc/verified-authors`, generated from the hub roster's `email` fields). Enforced on the
+   **product hub and every connected repo**; runs on PRs/MRs only, so the gate-sync bot's direct
+   ledger pushes are unaffected (never replace it with a default-branch push rule — see
+   `references/check-gates.md` §4).
+
+The gates are **CI-agnostic bash** in `checks/`; thin pipeline configs invoke them on GitHub Actions
+and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the skill or let CI run them;
+**nothing auto-advances**. The gates are blocking in CI, but the human still owns the merge (Step E).
+
+## 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>/`
+  (`config.yaml` `build.code_repos_root`).
+- Canonical gate sources live in this skill's `templates/` (the source of truth that gets installed
+  into each code repo):
+  - `templates/checks/{spec-link,contract-check,build-test-lint,verified-commits}.sh`
+  - `templates/github/sdlc-verified-commits.yml` + `templates/gitlab/sdlc-verified-commits.gitlab-ci.yml`
+    → the standalone hub-side verified-commits CI (installed by `sdlc check --fix` with the hub wiring)
+  - `templates/github/sdlc-checks.yml` → installs to `.github/workflows/sdlc-checks.yml` (marked `# sdlc-managed: sdlc-checks`)
+  - `templates/gitlab/sdlc-checks.gitlab-ci.yml` → includable fragment, installs to `.gitlab/ci/sdlc-checks.yml`
+  - `templates/gitlab/gitlab-ci.include-root.yml` → minimal root written only when no root `.gitlab-ci.yml` exists
+  - `templates/gitlab/.gitlab-ci.yml` → legacy standalone root (greenfield single-file option)
+- The gates depend on the conventions from earlier steps: the `Task:`/`Contract-Change:` commit
+  trailers (`sdlc-implement`), the `specs/<story>/link.md` + `contracts/` slice (`sdlc-spec`), and the
+  locked `contract.md` (`sdlc-author-architecture`).
+
+## Inputs
+
+- `repo`  — the code repo to wire/run gates for (one of an epic's repos), or `hub` to wire the product hub itself.
+- `action` — `wire` (install the gates into the repo) | `run` (run the three gates now). Default `run`.
+- `base`  — for `run`: the base ref to diff against (the PR/MR target; default the repo's default branch).
+
+## On Activation
+
+### Step 1 — Resolve the code repo
+Map `repo` → `{project-root}/demo-repos/<repo>/` (or the registry `path` in `.sdlc/repos.json`); confirm
+it is its own git repo. Operate inside it with absolute paths. For `repo: hub`, the target is
+`{project-root}` itself and the platform comes from `.sdlc/hub.json` — see "Wiring the hub" in
+`references/check-gates.md`.
+
+### Step 2 — `wire` (install the gates, syncing with any existing CI)
+Copy from this skill's `templates/`:
+- `templates/checks/*.sh` → `<repo>/checks/` (and `chmod +x`).
+- Detect the platform and **merge — never clobber — the matching** CI config. Inspect what is already
+  there first; the principle is **additive: never edit a foreign CI file**.
+
+  **GitHub** (detect by any `.github/workflows/*.y*ml`): our gates live in their own
+  `.github/workflows/sdlc-checks.yml`, which GitHub runs independently of every other workflow, so
+  "merge" reduces to "do not collide on the path".
+  - No file at our path → copy `templates/github/sdlc-checks.yml` verbatim.
+  - A file at our path whose **first line is `# sdlc-managed: sdlc-checks`** → it is ours; refresh it
+    (no-op if unchanged). 
+  - A **foreign** file occupies that path/name → write to a non-colliding filename
+    (`sdlc-checks.gen.yml`) and ensure its `name:` does not clash. Never merge jobs into a foreign
+    workflow; never edit one.
+
+  **GitLab** (detect by a root `.gitlab-ci.yml` and/or `.gitlab/ci/*.yml`): install the includable
+  fragment `templates/gitlab/sdlc-checks.gitlab-ci.yml` → `<repo>/.gitlab/ci/sdlc-checks.yml` (its jobs
+  carry `needs: []` and no `stage:`, so a foreign root `stages:` cannot break or reorder them).
+  - No root `.gitlab-ci.yml` → write `templates/gitlab/gitlab-ci.include-root.yml` to
+    `<repo>/.gitlab-ci.yml` (a minimal root that only `include:`s our fragment).
+  - Root exists → read its top-level `include:`. Add the `include:` key if absent; append
+    `- local: '.gitlab/ci/sdlc-checks.yml'` if the key exists but the entry is missing; **no-op** if it
+    is already listed. Touch nothing else in the root.
+  - If the existing YAML cannot be parsed safely → **STOP** and print the exact include snippet for the
+    human to paste (graceful degradation — never guess-edit a pipeline you cannot parse).
+  - The legacy standalone `templates/gitlab/.gitlab-ci.yml` is retained only for a clean greenfield repo
+    that prefers a single self-contained file; the include path above is the default.
+
+- Ensure `<repo>/package.json` defines `lint`, `build`, `test` scripts (see `references/check-gates.md`
+  for the canonical scripts). **Only ADD a missing script; never overwrite an existing one.**
+
+Re-running `wire` is **idempotent** — markers (`# sdlc-managed: sdlc-checks`,
+`# sdlc-managed-include: sdlc-checks`) and the include-entry check make a second run a no-op.
+Commit the wiring on the repo's default branch (it is shared infrastructure, not a task diff).
+
+**The hub is wired the same way.** `repo: hub` wires the hub repo itself (platform from `.sdlc/hub.json`)
+with a hub-flavored gate set — see "Wiring the hub" in `references/check-gates.md`.
+
+### Step 3 — `run` (run the gates now)
+From inside the repo, run each gate against `base` and report PASS/FAIL per gate:
+```
+bash checks/spec-link.sh "<base>"
+bash checks/contract-check.sh "<base>"
+bash checks/build-test-lint.sh
+```
+A non-zero exit is a FAIL. Summarize which gates passed and, for any failure, the exact remediation
+(spec-link: add the `Task:` trailer / spec; contract-check: route back to the architecture gate and
+re-lock the contract; build/test/lint: fix the failing lint/test).
+
+### Step 4 — Report; the advance decision belongs to the dial (Phase 4)
+Report the gate results. Passing gates do **not** merge anything — the AI review (Step D/E) and the
+human engineer review (Step E) still own the merge. This skill never edits the epic's `.sdlc/` state.
+
+- **Run standalone** (the Phase 3 default): **stop** here. A clean pass does not advance anything; a
+  human takes the next step.
+- **Run by the orchestrator** (`sdlc-run`, Phase 4): this skill still just reports PASS/FAIL — the
+  *advance decision* is the orchestrator's, read from the `checks` step's `automation` dial. On a clean
+  pass with `checks` earned to `machine_advance`, `sdlc-run` advances to `engineer-review` on its own;
+  on any FAIL it halts and pulls in a human (build plan §B). **What the gates check is unchanged** —
+  only who decides to proceed after a clean pass.
+
+## Hard rules (build plan §C, Cross-cutting)
+
+- **The gates are blocking in CI, advisory to no one.** A FAIL stops the merge; a PASS does not grant it.
+- **Contract surface is never widened from a code repo.** contract-check routes surface changes back
+  to the architecture gate; only an updated, re-locked contract + `Contract-Change: yes` may pass.
+- **Tests must exercise behavior.** build/test/lint is not satisfied by empty or trivial tests.
+- **The gate never advances itself.** A FAIL always halts. A clean PASS advances only when the
+  orchestrator's `checks` dial is `machine_advance` (earned) — and only as far as the engineer review,
+  which is always human. Standalone, the gate still stops and the human owns the merge.
+
+## Reference
+- Gate definitions, the canonical scripts, CI wiring, and the convention map: `references/check-gates.md`.
+- Commit-trailer conventions the gates read: `../sdlc-implement/references/implement-conventions.md`.
+- Contract surface + hash recipe: `../sdlc-author-architecture/references/contract-format.md`.