yadflow 1.0.1

package/skills/sdlc-review-gate/references/gating.md

@@ -0,0 +1,79 @@
+# Gate predicate — details & worked example
+
+## Reviewer rule
+Let `A` = the set of `approved` records in `.sdlc/approvals.json` for this step.
+
+- `owners = { a in A : a.role == "owner" }`
+- `reviewers = { a in A : a.role == "reviewer" }`  (distinct by `approver`)
+- `domainOwners = { a in A : a.role == "domain-owner" }`  (grouped by `a.domain`)
+
+**Base pass:** `|owners| >= 1` AND `|reviewers| >= default_reviewers` (default `1`).
+
+**Escalated pass** (step `risk_tags` ∩ `{contract, auth, payments}` ≠ ∅): base pass AND, for every
+touched `domain`, `|domainOwners[domain]| >= 1`.
+
+**Touched domains** are resolved from files, not hardcoded:
+- Architecture+contract review: the touched domains are the epic's `repos` (every repo shares the
+  contract surface).
+- Stories review: the touched domains are the **union of every story's `repos`** under `stories/`.
+
+So one gate, two option-shapes:
+- Epic / UI reviews: base rule (no risk tags, no per-repo routing).
+- Architecture+contract review: escalated (`risk_tags: ["contract"]`) — owner + 1 reviewer + a
+  `domain-owner` for **each** repo in `epic.repos`. (A small team may have one engineer own several
+  repos — one person can supply several `domain-owner` records with different `domain` values.)
+- Stories review: per-repo routing — owner + 1 reviewer + a `domain-owner` (the repo's engineer) for
+  **each** repo that appears in any story's `repos`.
+
+## Staleness
+An approval round is invalidated if the authored artifact was edited after the newest `approved`
+record's date/round. When that happens, drop back to `comment` — reviewers must re-approve the new
+content. This prevents "approve, then quietly change it" (build plan §5 spirit).
+
+For the architecture+contract review there is a second, content-based staleness check: recompute the
+SHA-256 of the contract-surface block and compare it to `.sdlc/contract-lock.json`. A mismatch means
+the locked surface changed even if the file's mtime looks fine — approvals are stale, re-lock and
+re-approve. (Hash recipe: `sdlc-author-architecture/references/contract-format.md`.)
+
+## Worked example — epic gate
+
+1. `action: open` → `reviews/epic--2026-06-04--comments.md` seeded; step `epic-review` set
+   `in_review`; `currentStep = epic-review`.
+2. Reviewer *bob* leaves comments → captured in the comments file; owner *alice* (pm-assisted)
+   edits `epic.md`.
+3. `action: approve` approver *alice* role *owner* → ledger entry added. Predicate re-evaluated:
+   `|owners|=1, |reviewers|=0` → **fails** (need 1 reviewer). Gate reports "missing: 1 reviewer".
+4. `action: approve` approver *bob* role *reviewer* → ledger entry added. Predicate:
+   `|owners|=1, |reviewers|=1` → **base pass**.
+5. `action: advance` → `epic-review.status=done`, `architecture.status=in_progress`,
+   `currentStep=architecture`. Gate reports the advance.
+
+## Participation record (comments.json)
+`approvals.json` answers "who approved"; `.sdlc/comments.json` answers "who reviewed/commented". The
+gate appends a record per commenter per round on every `comment` action (the machine-readable
+counterpart to the `reviews/*--comments.md` markdown). It does **not** feed the predicate — approvals
+alone decide the gate — but it makes the `approved.md` roster's "Reviewed / commented by" section
+attributable, and it is the same shape a future service or the platform bridge can write.
+
+## Platform-backed input (the bridge)
+When the hub has a platform (`.sdlc/hub.json`) and the bridge is enabled, reviewers can approve/comment
+on a real PR/MR instead of (or as well as) the skill recording it directly. `action: sync`
+(`sdlc-hub-bridge`) reads that platform state with the reviewer's own `gh`/`glab` and writes the **same**
+`approvals.json` / `comments.json` / `reviews/*.md` records the manual path writes — bridge approvals
+tagged `"source": "bridge"`. **The predicate above is unchanged**: it counts owner/reviewer/domain-owner
+approvals regardless of how they were recorded.
+
+- login → role via the roster; `domain-owner` derived when a roster `name` equals a repo's `domain_owner`
+  and that repo is a touched domain; an unmapped login is a plain `reviewer`, never promoted.
+- `sync` is idempotent (upsert by `(step, approver, role, domain)`; supersede revoked; key comments on
+  comment id) and never touches **manual** approvals.
+- The architecture+contract staleness rule applies to bridge approvals too: a re-lock discards bridge
+  approvals dated before the new lock.
+- No platform / no CLI → the gate runs file-only with no error. Detail: `../sdlc-hub-bridge/references/bridge.md`.
+
+## Why this shape
+- Owner + 1 reviewer keeps review load low on a small team (design priority 2) while still requiring
+  a second pair of eyes (priority 1, code quality / production safety).
+- Risk-based escalation spends scarce domain-owner attention only where a change can break a shared
+  surface (contract/auth/payments).
+- Everything is a file, so a future service can drive the same gate by writing the same records.

package/skills/sdlc-run/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: sdlc-run
+description: 'Phase 4 (automation) — the orchestrator that makes the second dial real. Drives a story''s back-half loop (spec → tasks → implement → checks) in one code repo, reading each step''s automation dial from build-state: on machine_advance it advances on its own, on human_approve it stops for a human. Records every run in the trust log (the evidence base for earning automation). Realizes Step B: when checks is earned, a clean gate pass auto-advances to engineer-review; any failure, scope overrun, or contract-surface touch HALTS and pulls in a human. Also sets a step''s dial (gated by trust evidence) and flips the system-wide kill switch. Never advances a front state or the engineer review. Use when the user says "run the build half", "advance story <id>", "set the checks dial", or "kill switch".'
+---
+
+# SDLC — Run (Phase 4 orchestrator)
+
+**Goal:** Be the **engine** that the `automation` dial finally drives. Until Phase 4 the dial was inert
+config; this skill reads it and acts. For ONE story in ONE code repo, walk the back-half steps —
+`spec → tasks → implement → checks → engineer-review` — and at each step either **advance on its own**
+(dial `machine_advance`, step succeeded) or **stop for a human** (dial `human_approve`, or any halt
+condition). Every run is recorded in the **trust log**, the evidence that earns a step its automation.
+
+This is the most dangerous skill in the system, so it is built to **halt-and-escalate over guess**:
+a failing check, ambiguity, a scope overrun, or a contract-surface touch stops the loop and pulls in a
+human regardless of any dial. The **front states and the engineer review never auto-advance** — they
+are not in `automation.back_steps` and `engineer-review` is `locked`.
+
+Earned so far: **`checks`** (Step B, Phase 4a — safest, a gate's pass/fail was never human judgment)
+and **`implement`** (Step D, Phase 4b — the `implement → check` hand-off; the scope/contract halts and
+the engineer review still gate the merge). **`tasks`** (Step C) and `spec` have their dials and trust
+hooks but stay `human_approve` until their own evidence clears the threshold — there is no historical
+signal to seed them from, so they are earned only on real runs.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory — the **product** repo (source of
+  truth: it holds the story, the build-state, and the trust log).
+- Code repos are separate git repos under `{project-root}/demo-repos/<repo>/`
+  (`config.yaml` `build.code_repos_root`). Operate inside them with absolute paths.
+- Automation config is `skills/sdlc/config.yaml` → `automation:` (`back_steps`, `default`,
+  `trust_threshold`, `locked_steps`, `kill_switch`).
+- Per-story build-half state: `epics/<epic>/.sdlc/build-state/<story-id>.json` (per repo).
+- Trust ledger: `epics/<epic>/.sdlc/trust-log.json` (append-only). Schemas:
+  `../sdlc-author-epic/references/state-schema.md`.
+- The orchestrator **calls the existing step skills unchanged** — `sdlc-spec` (A), `sdlc-implement`
+  (B), `sdlc-checks` (C). It owns only the *advance decision*, never what a step does.
+
+## Inputs
+
+- `epic` / `story` / `repo` — the story and code repo to drive (ask if not provided).
+- `action` — `run` (default) | `set-dial` | `kill` | `unkill`.
+- For `run`: optional `from` (the step id to start at; default the repo's `currentStep` in
+  build-state) and `task` (the atomic task id for the `implement`/`checks` legs).
+- For `set-dial`: `step` (a `back_steps` id), `to` (`human_approve` | `machine_advance`).
+
+## On Activation
+
+### Step 0 — Load state
+Read `config.yaml` `automation`, the story's `build-state/<story>.json` (create it from the
+`back_steps` defaults if absent — all `human_approve`, `engineer-review` `locked:true`), and
+`trust-log.json` (treat missing as `[]`). Resolve the code repo.
+
+### `action: run` — drive the loop
+Walk the steps for `repo` starting at `from`/`currentStep`. For each step:
+
+1. **Run the step's skill** — `spec`→`sdlc-spec`, `tasks`→ the tasks leg of `sdlc-spec`,
+   `implement`→`sdlc-implement`, `checks`→`sdlc-checks (action: run)`. Capture its result.
+2. **Derive trust signals & append a trust-log entry** (`ranBy: machine` if this advance was
+   automated, else `human`) — see `references/run-loop.md` for the derivation. Do this for *every*
+   step run, pass or fail; the log is the evidence base.
+3. **Compute the effective dial.** Start from the step's `automation` in build-state, then **force it
+   to `human_approve`** if `automation.kill_switch` is true OR the step is `locked` OR the step id is
+   in `automation.locked_steps`. (So a kill switch or a lock always wins.)
+4. **Decide:**
+   - **HALT** if the step failed — any check FAIL, a scope overrun (`sdlc-implement` stopped on the
+     file-boundary rule), a contract-surface touch, or any ambiguity. Set the step `status: blocked`,
+     write the `rejected` trust entry, **stop the loop**, and report what a human must resolve.
+   - else if effective dial is **`machine_advance`** → set the step `done`, advance `currentStep` to
+     the next step, and **continue the loop** (this is the Step B auto-advance for `checks`).
+   - else (**`human_approve`**) → set the step `done`/`in_review`, **stop** and report
+     "waiting for a human at `<next-step>`".
+5. **Always stop at `engineer-review`** (it is `locked`): hand off to `sdlc-ship` for the human merge
+   gate, which finalizes the trust verdict (confirm/override the provisional one).
+
+### `action: set-dial` — earn (or revert) a step's automation
+Flip `step`'s `automation` to `to` in build-state. Enforce, in order:
+- **Refuse** if `step` is in `automation.locked_steps` or is a front state or `engineer-review` —
+  these can never be `machine_advance` (front-state lock, build plan §E). Report the refusal reason.
+- For `to: machine_advance`, **refuse unless the trust threshold is met**: the step's slice of
+  `trust-log.json` has `>= trust_threshold.min_runs` entries AND the fraction with
+  `verdict == "approved-unchanged"` is `>= trust_threshold.min_approved_unchanged`. If it is not met,
+  report the current evidence (runs, % unchanged) and how far short it is — "it seems fine" is not
+  evidence.
+- `to: human_approve` is **always allowed** (reverting automation is one move, never gated).
+
+### `action: kill` / `action: unkill` — the kill switch
+Set `automation.kill_switch` to `true` (`kill`) or `false` (`unkill`) in `config.yaml`. While true,
+**every** step's effective dial is `human_approve` system-wide — no per-step edits, instantly
+reversible (build plan §Safety). Report the new state and that `sdlc-status` will show it.
+
+## Hard rules (phase-4-build-plan.md)
+
+- **Earned per step, with evidence.** A step goes `machine_advance` only after its trust log clears
+  the threshold; `set-dial` enforces it.
+- **Reversible in one move.** `human_approve` is never gated; the kill switch reverts everything with
+  one command and no code change.
+- **Halt-and-escalate beats guess.** A failing check, ambiguity, scope overrun, or contract-surface
+  touch halts the loop and pulls in a human, regardless of the dial.
+- **Front states and the engineer review never auto-advance.** They are not in `back_steps`;
+  `engineer-review` is `locked`; the kill switch and locks always override the dial.
+- **The orchestrator never changes what a step does** — it calls the existing skills and owns only the
+  advance decision and the trust record.
+
+## Reference
+- The loop, the trust-verdict derivation, and the threshold predicate: `references/run-loop.md`.
+- State/trust schemas: `../sdlc-author-epic/references/state-schema.md`.
+- The steps it drives: `../sdlc-spec/`, `../sdlc-implement/`, `../sdlc-checks/`; the human gate it
+  hands off to: `../sdlc-ship/`.

package/skills/sdlc-run/references/run-loop.md

@@ -0,0 +1,121 @@
+# `sdlc-run` — the loop, the trust verdict, the threshold
+
+This is the detail behind `SKILL.md`. It restates the orchestration so the skill is self-contained,
+and pins down the two judgments the skill makes: **what trust verdict to record** and **when a step
+has earned `machine_advance`**.
+
+## The back-half steps
+
+From `config.yaml` `automation.back_steps` plus the human merge gate:
+
+```
+spec → tasks → implement → checks → engineer-review(locked)
+```
+
+`spec` and `tasks` are the two legs of `sdlc-spec` (the heavy ceremony, then the atomic `tasks.md`).
+`implement` is one atomic task via `sdlc-implement`. `checks` is `sdlc-checks (action: run)`.
+`engineer-review` is the human gate at `sdlc-ship` — always a stop, never automated.
+
+## The loop (pseudocode)
+
+```
+cfg   = config.yaml.automation
+bs    = build-state/<story>.json.repos[<repo>]        # create from defaults if absent
+step  = from or bs.currentStep
+
+while step is a back step (not engineer-review):
+    result = run_step_skill(step)                     # sdlc-spec | sdlc-implement | sdlc-checks
+
+    signals = derive_signals(step, result)            # see "Deriving signals"
+    verdict = derive_verdict(signals)                 # rejected | approved-with-edits | approved-unchanged
+    append trust-log entry { story, repo, step, automation: bs.step.automation,
+                             verdict, signals, ranBy, date }
+
+    eff = effective_dial(step, bs, cfg)               # see "Effective dial"
+
+    if result is a HALT (failed / scope overrun / contract touch / ambiguous):
+        bs.step.status = "blocked"; persist; STOP and report the human action needed
+    elif eff == "machine_advance":
+        bs.step.status = "done"; advance bs.currentStep to next; persist; continue   # Step B advance
+    else:  # human_approve
+        bs.step.status = "done"; persist; STOP and report "waiting for human at <next>"
+
+# reached engineer-review: always stop, hand to sdlc-ship (human gate, finalizes the verdict)
+```
+
+`ranBy` is `machine` when the *previous* step's effective dial caused this step to run without a human
+nudge; otherwise `human`. Persist build-state after every transition so a halt leaves an accurate,
+resumable record.
+
+## Effective dial (kill switch & locks always win)
+
+```
+eff = bs.step.automation                 # human_approve | machine_advance
+if cfg.kill_switch == true:        eff = "human_approve"
+if bs.step.locked == true:         eff = "human_approve"
+if step in cfg.locked_steps:       eff = "human_approve"
+```
+
+So a kill switch, a `locked` flag, or membership in `locked_steps` forces a stop no matter what the
+per-step dial says. `engineer-review` and the four front states are covered by `locked` / `locked_steps`.
+
+## Deriving signals & the provisional verdict
+
+`signals` are the raw facts of the run; the **provisional `verdict`** is derived from them. The human
+gate for each step (the engineer review at `sdlc-ship` for `implement`; spec acceptance for `spec`;
+first-consume for `tasks`; the gate itself for `checks`) later confirms or overrides the verdict and
+finalizes the entry — a human always has the last word on the trust signal.
+
+`signals` (only the relevant ones are set per step — see the table in
+`../sdlc-author-epic/references/state-schema.md`):
+- `checks` — `pass` | `fail` | `n/a` (only the `checks` step runs the three gates).
+- `human_edited_diff` — `true` if a human changed the produced **diff** before merge (`implement`).
+- `human_edited_spec` — `true` if a human edited the generated **spec/plan/tasks** before accepting (`spec`).
+- `task_rescoped` — `true` if a task's declared `Files:`/scope was edited before implementing (`tasks`).
+- `scope_overrun` — `true` if `sdlc-implement` stopped on the file-boundary rule (diff outside the
+  task's declared files).
+- `contract_touch` — `true` if the diff touched the locked contract surface without an upstream
+  re-lock (routes back to the architecture gate).
+
+`derive_verdict(signals)` — the same three-way shape for every back step:
+```
+edited = human_edited_diff or human_edited_spec or task_rescoped
+if checks == "fail" or scope_overrun or contract_touch:   verdict = "rejected"
+elif edited:                                              verdict = "approved-with-edits"
+else:                                                     verdict = "approved-unchanged"
+```
+
+This is the **provisional** verdict from the recorded signals. The human gate that finalizes the entry
+may also override it to `rejected` — e.g. the human discards/regenerates the spec or the task list, or
+rejects the diff at the engineer review for a reason no signal captured. A human override always wins.
+
+Rationale: the trust log should count an output as fully trustworthy (`approved-unchanged`) only when
+the machine's work was accepted as-is. Any human correction is `approved-with-edits` (useful but not
+yet trustworthy enough to automate); any failure or boundary breach is `rejected`.
+
+## The trust threshold (when a step is earned)
+
+A step is a **candidate** for `machine_advance` only when its trust evidence clears
+`config.yaml` `automation.trust_threshold`. `set-dial` enforces this predicate before flipping a step
+to `machine_advance`:
+
+```
+slice = trust-log entries for this step (this story's repo; widen to the project if you track it there)
+runs  = len(slice)
+unchanged = count(e.verdict == "approved-unchanged" in slice)
+earned = runs >= trust_threshold.min_runs
+         AND (unchanged / runs) >= trust_threshold.min_approved_unchanged
+```
+
+Defaults: `min_runs: 5`, `min_approved_unchanged: 0.8`. If `earned` is false, `set-dial` refuses and
+reports `runs`, the `unchanged/runs` fraction, and how far short of the bar it is.
+
+Reverting (`to: human_approve`) is never gated — automation must be reversible in one move.
+
+## What stays human, always
+
+- `engineer-review` — the merge gate. `sdlc-run` always stops here and hands to `sdlc-ship`.
+- The four front states (`epic`, `architecture`, `ui-design`, `stories`) — not in `back_steps`, in
+  `locked_steps`; the dial-setter refuses them.
+- Any contract-surface change — halts the loop and routes back to the architecture gate, regardless of
+  the dial.

package/skills/sdlc-ship/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: sdlc-ship
+description: 'Build-half Step E of the gated SDLC — AI review, engineer review, then ship. Wire an advisory AI first-pass (CodeRabbit) on the PR/MR; record the human engineer review with the same human_approve discipline as the front gates (owner + 1 reviewer, escalating to domain owners on high risk / contract / auth / payments — the Step D routing); and on merge, record the ship in the epic build-log and update the story state so the epic → story → task → PR chain is traceable. Never auto-advances — the human owns the merge. Use when the user says "ship this task", "record the engineer review", or "wire the AI review".'
+---
+
+# SDLC — Review & Ship (build-half Step E)
+
+**Goal:** Take a task PR/MR that has passed the **check gates** (Step C) through two sets of eyes and
+out to production: an **AI first-pass** (advisory) and a **human engineer review** (the authority),
+then **ship** — merge, record the ship, and update the story state. This is the last build-half step
+(build plan §E). It is a **human gate**, the same `human_approve` discipline as the front states:
+**nothing auto-advances**; the engineer owns the merge.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory — the **product** repo (the source of
+  truth: it holds the story and the build ledger).
+- Code repos are separate git repos under `{project-root}/demo-repos/<repo>/`.
+- The build ledger is `{project-root}/epics/<epic>/.sdlc/build-log.json` (append-only).
+- The engineer-review rule reuses `sdlc-review-gate`: base = at least one `owner` AND one distinct
+  `reviewer`; **escalated** (the PR's Impact & Risk is `high`, or it touches contract/auth/payments) =
+  base PLUS one `domain-owner` per touched domain — the same routing `sdlc-pr-template`'s
+  `risk-route.sh` prints.
+- AI review wiring: `templates/.coderabbit.yaml` → `<repo>/.coderabbit.yaml`.
+
+## Inputs
+
+- `epic` / `story` / `task` / `repo` — the PR under review (the task branch `feat/<story>-<task>-…`).
+- `action` — `ai-review` | `approve` | `ship` (default `ai-review`).
+- For `approve`: the reviewer `name` and `role` (`owner` | `reviewer` | `domain-owner`), and for a
+  domain owner the `domain`.
+
+## On Activation
+
+### Step 1 — `ai-review` (advisory first pass)
+Ensure the AI reviewer is wired: copy `templates/.coderabbit.yaml` to `<repo>/.coderabbit.yaml` (commit
+on the default branch if missing). CodeRabbit reviews each PR automatically and posts comments — it is
+a **second set of eyes, never the authority**: it cannot approve or merge. Where CodeRabbit can't run
+(no remote), run an equivalent AI first-pass by hand and capture its notes. Record that the AI review
+ran; surface its findings to the engineer. Do **not** treat AI approval as a gate.
+
+### Step 2 — `approve` (the engineer review — the human gate)
+A human engineer reads the diff **against the spec** (`specs/<story>/`) and the acceptance criteria,
+and records an approval. Determine the rule from the PR's Impact & Risk block (run
+`../sdlc-pr-template/templates/checks/risk-route.sh` on the PR body): base, or escalated to a
+domain-owner per touched domain. Record each approval; re-evaluate whether the rule is satisfied.
+Recording an approval does **not** ship — shipping is a separate, explicit step. Front-half discipline:
+the gate talks only through files; refuse to treat AI review as a human approval.
+
+### Step 3 — `ship` (merge + record + update state)
+Ship **iff ALL hold**: the check gates pass (Step C), the AI review has run (advisory), and the
+engineer-review rule is satisfied (Step 2). Then:
+- **Merge** the task branch into the repo's default branch (the human performs/authorises the merge).
+- **Record the ship** — append to `epics/<epic>/.sdlc/build-log.json`:
+  ```json
+  { "story": "<story>", "task": "<task>", "repo": "<repo>", "branch": "feat/<story>-<task>-…",
+    "pr": "<url|#>", "mergeCommit": "<sha>", "gates": ["spec-link","contract-check","build-test-lint"],
+    "ai_review": "coderabbit (advisory)", "engineer_review": [{"approver":"<name>","role":"<role>","domain":"<opt>"}],
+    "risk": "<low|medium|high>", "shippedAt": "<YYYY-MM-DD>" }
+  ```
+- **Update the story state** — when **every** task in `specs/<story>/tasks.md` has a ship record, set
+  the story frontmatter `status: shipped`; otherwise `status: in-build`. The chain
+  **epic → story → task → PR → mergeCommit** is now traceable end to end.
+- **Finalize the trust verdict (Phase 4).** If this story has a `build-state/<story>.json` (it ran
+  through `sdlc-run`), the engineer **confirms or overrides** the provisional trust verdict that the
+  orchestrator derived for this run, and the final verdict is written to
+  `epics/<epic>/.sdlc/trust-log.json`. The human has the last word on the trust signal: a diff merged
+  as authored is `approved-unchanged`; one the engineer edited before merge is `approved-with-edits`;
+  a rejected one is `rejected`. This is the evidence that later earns a step its `machine_advance`
+  (it never weakens the merge gate — the engineer still owns the merge).
+
+### Step 4 — Stop
+Report what shipped and the story's state. Do not advance anything else; the front-half `state.json`
+stays as it was (`ready-for-build`). The build half is recorded in `build-log.json` + the story status.
+
+## Hard rules (build plan §E, Cross-cutting)
+
+- **AI review is advisory, never the authority.** Only a human engineer approval counts toward the gate.
+- **High risk routes to domain owners** — the same escalation as `sdlc-review-gate` / `risk-route.sh`.
+- **Ship only after gates + engineer review.** No gate skipped; the human owns the merge.
+- **Nothing auto-advances.** Step E records human decisions in files; it never machine-advances.
+
+## Reference
+- The build ledger + story-state rules: `references/ship-and-record.md`.
+- The escalation reused: `../sdlc-review-gate/SKILL.md`; the routing helper: `../sdlc-pr-template/`.
+- The gates that must pass first: `../sdlc-checks/references/check-gates.md`.

package/skills/sdlc-ship/references/ship-and-record.md

@@ -0,0 +1,67 @@
+# Ship — the build ledger and the story state
+
+Step E (`sdlc-ship`) closes the build half: AI review (advisory) → engineer review (the human gate) →
+ship. Shipping records the merge and updates the story state so the whole chain is traceable.
+
+## Two sets of eyes
+
+1. **AI review (advisory).** CodeRabbit (`.coderabbit.yaml`) reviews each PR and comments. It is a
+   second set of eyes — it **never approves or merges**. Its findings inform the engineer; they do not
+   gate. Where CodeRabbit can't run (no remote), an equivalent AI first-pass is run by hand and its
+   notes captured.
+2. **Engineer review (the authority).** A human reads the diff against the spec and the acceptance
+   criteria and records an approval. The rule is `sdlc-review-gate`'s:
+   - **base:** at least one `owner` AND one distinct `reviewer`.
+   - **escalated:** when the PR's Impact & Risk is `high`, or it touches contract/auth/payments — base
+     PLUS one `domain-owner` per touched domain (exactly what `risk-route.sh` prints).
+
+## The build ledger — `epics/<epic>/.sdlc/build-log.json`
+
+Append-only. One record per shipped task:
+
+```json
+{
+  "epic": "EP-istifta-inquiries",
+  "ships": [
+    {
+      "story": "EP-istifta-inquiries-S01",
+      "task": "T01",
+      "repo": "backend",
+      "branch": "feat/EP-istifta-inquiries-S01-T01-create-inquiry",
+      "pr": "<url|#|local>",
+      "mergeCommit": "<sha>",
+      "gates": ["spec-link", "contract-check", "build-test-lint"],
+      "ai_review": "coderabbit (advisory)",
+      "engineer_review": [
+        { "approver": "amelia", "role": "owner" },
+        { "approver": "carol", "role": "reviewer" }
+      ],
+      "risk": "low",
+      "shippedAt": "2026-06-06"
+    }
+  ]
+}
+```
+
+This is the back-half analogue of the front half's `approvals.json` — files only, no hidden state, so a
+future service can drive ship by writing the same records.
+
+## Story state
+
+The story frontmatter `status` reflects build progress:
+
+- `in-build` — at least one, but not all, of the story's tasks (from `specs/<story>/tasks.md`) have ship
+  records.
+- `shipped` — **every** task in `tasks.md` has a ship record.
+
+So the chain is traceable both ways: from the epic down (`epic.md` → `stories/<story>.md` →
+`tasks.md` → `build-log.json` ship → `mergeCommit`) and from a merge commit back up (its `Task:`
+trailer → story → epic).
+
+## Preconditions for ship (all required)
+
+1. The three **check gates** pass (Step C) — re-run them on the PR branch if unsure.
+2. The **AI review** has run (advisory; findings surfaced to the engineer).
+3. The **engineer review** rule is satisfied (base or escalated per the Impact & Risk block).
+
+Only then does the human merge and `sdlc-ship` record it. Nothing auto-advances.

package/skills/sdlc-ship/templates/.coderabbit.yaml

@@ -0,0 +1,19 @@
+# CodeRabbit — AI first-pass review (Phase 3 build plan §E).
+# Advisory only: a second set of eyes that COMMENTS on every PR. It never approves or merges — the
+# human engineer review (sdlc-review-gate discipline) owns that decision. See skills/sdlc-ship.
+language: en
+reviews:
+  request_changes_workflow: false   # never block the merge — the engineer review is the gate
+  high_level_summary: true
+  review_status: true
+  poem: false
+  auto_review:
+    enabled: true
+    drafts: false
+  path_instructions:
+    - path: "src/**"
+      instructions: >-
+        Check the diff against the task's spec under specs/<story>/; flag any change that leaves the
+        files the task declared, or that alters the contract surface without Contract-Change.
+chat:
+  auto_reply: true

package/skills/sdlc-spec/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: sdlc-spec
+description: 'Build-half Step A of the gated SDLC. For one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony ONCE (specify → clarify → plan → analyze → checklist → tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit''s own layout. Drives /speckit.* as harness slash-commands when installed; authors the same files by hand and records speckit: not-installed when absent. References the locked contract — never re-invents the surface. Writes link.md back to the story. Never auto-advances. Use when the user says "spec story <id> in <repo>" or after a story is ready-for-build.'
+---
+
+# SDLC — Author Spec (build-half Step A)
+
+**Goal:** Turn ONE `ready-for-build` story into a per-repo Spec Kit spec/plan/tasks inside that
+story's code repo. The heavy spec ceremony runs **once per story per repo**; the light
+tasks → implement loop is **Step B** (`sdlc-implement`). This step **never re-locks the contract** —
+the cross-repo surface is owned upstream by the architecture gate (build plan §A, Cross-cutting
+"Heavy spec once per story, light loop per task"). It does not advance the front-half state machine;
+when driven by the orchestrator (`sdlc-run`, Phase 4) it records a `spec`/`tasks` trust signal
+(Step 8) — but it never auto-advances a contract change or a front state.
+
+Spec Kit is driven as **harness slash-commands** (`/speckit.*`), not a subprocess CLI (Phase 0
+Deviation 3). When Spec Kit is not installed, the same files are hand-authored in Spec Kit's exact
+layout and the spec is marked `speckit: not-installed` — the workflow does not block on the tool. This
+is the same graceful-degradation pattern `sdlc-author-ui` uses for Impeccable.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory — the **product** repo (epic
+  "thinking" + per-epic `.sdlc/` state live here).
+- **Code repos are separate git repos**, one `.git` each, under `{project-root}/demo-repos/<repo>/`
+  (`config.yaml` `build.code_repos_root`). All Spec Kit outputs land **inside the code repo**, never
+  in the product repo.
+- `{feature-id}` is the **story ID** (e.g. `EP-istifta-inquiries-S01`) — **pinned**, never Spec Kit's
+  numbered auto-slug (which is unstable and severs the permanent story link). The spec folder is
+  `specs/<story-id>/`.
+- Spec Kit output layout (RESEARCH-NOTES §2): `specs/<feature-id>/spec.md` (+ `research.md`,
+  `data-model.md`, `contracts/`), `plan.md`, `tasks.md`; constitution at `.specify/memory/constitution.md`.
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## Inputs
+
+- `epic`  — the `EP-<slug>` to operate on (ask if not provided).
+- `story` — the ONE story to spec, `EP-<slug>-S0N` (ask if not provided).
+- `repo`  — one entry from that story's `repos` (the ONE repo to spec; ask if the story lists more
+  than one).
+
+## On Activation
+
+### Step 1 — Resolve the story and check readiness
+Read `{project-root}/epics/<epic>/.sdlc/state.json`. Proceed only when
+`currentStep == "ready-for-build"` (the whole front half is `done`). Read the story file
+`epics/<epic>/stories/<story>.md`; confirm `repo` is in its `repos`. If the epic is not ready, STOP
+and point the user at `sdlc-status`. **Do not mutate front-half state** — `ready-for-build` semantics
+stay intact.
+
+### Step 2 — Resolve the target code repo
+Map `repo` → `{project-root}/demo-repos/<repo>/`. Confirm it exists and is its own git repo
+(`demo-repos/<repo>/.git` present). If missing, STOP and point the user at `demo-repos/README.md`
+(how to regenerate the throwaway repo). Operate **inside this repo** with absolute paths.
+
+### Step 3 — Read the contract (reference, do NOT re-invent)
+Read `epics/<epic>/contract.md` and `epics/<epic>/.sdlc/contract-lock.json`. The spec's contract
+inputs (the API shapes, data-model entities, and events the story touches) are **quoted from the
+locked surface**, not re-authored. The spec MUST stay within that surface. If the story needs surface
+the contract does not define, STOP and route back to the **architecture gate** — never extend the
+contract here.
+
+### Step 4 — Detect Spec Kit
+Check for `/speckit.*` slash-commands and/or `demo-repos/<repo>/.specify/`. Record the result for
+Step 6's frontmatter (`speckit: installed | not-installed`).
+
+### Step 5 — Run the heavy ceremony ONCE (or degrade)
+**Installed** — from inside `demo-repos/<repo>/`, drive, in order:
+`/speckit.specify` → `/speckit.clarify` → `/speckit.plan` → `/speckit.analyze` →
+`/speckit.checklist` → `/speckit.tasks`. **Pin the feature to `<story>`** (do not accept an
+auto-slug). Seed `specify` from the story's acceptance criteria and the contract elements from Step 3.
+`/speckit.constitution` and `/speckit.implement` are **out of scope for Step A** (implement is Step B).
+
+**Not installed (degrade)** — hand-author the identical files in Spec Kit's layout under
+`demo-repos/<repo>/specs/<story>/`: `spec.md`, `research.md`, `data-model.md`, `contracts/`,
+`plan.md`, `tasks.md`. The content is what a real Spec Kit run would produce, traceable to the story's
+acceptance criteria and the locked contract surface. `tasks.md` MUST be numbered atomic tasks (`T01…`),
+each declaring the files it may touch, so Step B's "stay inside the declared files" rule has something
+to read. See `references/spec-handoff.md` for the exact file map and per-file degradation rules.
+
+### Step 6 — Write link.md back to the story
+Write `demo-repos/<repo>/specs/<story>/link.md` (template in `references/spec-handoff.md`) with
+frontmatter linking the spec back to the product repo: `story`, `epic`, `repo`, `feature-id`,
+`product-repo` (path), `contract-lock` (the hash **copied** from `contract-lock.json`, NOT recomputed
+in the code repo), `speckit` (`installed | not-installed`), `generated` (date). This `link.md` plus the
+spec folder is the authoritative record that this story's spec exists.
+
+### Step 7 — Stop (front-half state untouched)
+Report: the spec folder path, the files written, whether Spec Kit was used, the task count from
+`tasks.md`, and that the next action is **Step B — `sdlc-implement`**. Do **not** edit the epic's
+`state.json`, `approvals.json`, or `contract-lock.json`. Step A is a generation step, not a front gate.
+
+### Step 8 — Record the `spec` trust signal (Phase 4b)
+When this step runs under the orchestrator (`sdlc-run`), the generated spec is a back-half run that the
+trust log measures (it is the evidence that could later earn the `spec` step a `machine_advance`). The
+verdict is **anchored to the human who accepts the spec**, never self-graded:
+- the human approves the generated `specs/<story>/` untouched → `approved-unchanged`;
+- the human edits the spec/plan/tasks before accepting → `approved-with-edits` (signal
+  `human_edited_spec: true`);
+- the spec is rejected or the ceremony re-run → `rejected`.
+`sdlc-run` records a provisional entry when the spec is generated; this acceptance finalizes it (same
+pattern as the engineer review finalizing `implement` at `sdlc-ship`). Append the finalized entry to
+`epics/<epic>/.sdlc/trust-log.json` (schema:
+`../sdlc-author-epic/references/state-schema.md`). **Run standalone, no trust entry is written** — the
+log measures orchestrated runs. `spec` stays `human_approve` until its slice clears the threshold;
+this step only *gathers* the evidence, it does not flip the dial.
+
+## Hard rules (build plan §A, Cross-cutting)
+
+- **Heavy spec once per story, not per task.** specify/clarify/plan/analyze/checklist/tasks run once
+  per story per repo. Do not re-run the ceremony for each task.
+- **Per-repo spec, shared contract.** Spec/plan/tasks live in the code repo; the contract stays
+  singular in the product repo. Never widen the contract surface from here.
+- **Nothing auto-advances.** Step A generates files and stops; no state machine is advanced.
+
+## Reference
+- Command list, output map, degradation rules, link.md template: `references/spec-handoff.md`.
+- Contract surface format + hash recipe: `../sdlc-author-architecture/references/contract-format.md`.
+- Spec Kit facts and the slash-command-vs-CLI deviation: `RESEARCH-NOTES.md` §2 + Phase 3 decisions + Deviation 3.