yadflow 3.18.1 → 4.0.0-next.1

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

@@ -3,42 +3,211 @@
 ## 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`)
+- `approvers = { a.approver : a in A }`  (distinct people — two records from one person are one)
 
-**Base pass:** `|owners| >= 1` AND `|reviewers| >= default_reviewers` (default `1`).
+**Pass (team mode):** `|approvers| >= 1` — the **base**. Missing, the gate reports `1 approval(s)`.
 
-**Escalated pass** (step `risk_tags` ∩ `{contract, auth, payments}` ≠ ∅): base pass AND, for every
-touched `domain`, `|domainOwners[domain]| >= 1`.
+There are no roles. yadflow keeps no list of people, so there is no owner rule, no reviewer rule and no
+domain-owner rule. Older records may still carry `role` and `domain`; they stay on disk and nothing
+reads them. The gate's `rule` label for a team gate is `count` (`solo`, `inherited` and `skipped` are
+unchanged).
+
+## The per-step count rule
+
+The count is the whole rule. It counts people, not roles:
+
+`needed = base + risk step`, where `base` is `1` — one human approval from someone other than the author.
+The engine never compares the approver with the author: GitHub stops you approving your own PR, GitLab
+does only when the project's approval settings say so, and on a local-only ledger nothing does — so do
+not record the author's own approval — and the **risk step** comes from the step's own
+`risk_tags`:
+
+| Tags on the step | Risk | Risk step | `needed` |
+|---|---|---|---|
+| none | normal | +0 | 1 |
+| `auth` and/or `payments` | high | +1 | 2 |
+| `contract` | contract surface | +2 | 3 |
+
+Several tags take the **highest** step, never the sum — a gate is one decision about the riskiest thing
+it touches. `have` is the number of **distinct approvers**. The tags are read from the step as the epic
+records it in `state.json`, so adding `auth` to a step by hand raises that epic's full count.
+
+**What holds the gate: only the base.** The base (1) always holds every team gate, and for now it is the only part that does. The rule is one
+formula: `needed = base + risk step`, **capped** at `active − 1`, with a floor of 1. `active` is the live
+count of people who committed or approved lately (E71); `yad gate status` and `yad gate sync` print it,
+and the predicate carries it as `active`. Since E72 the engine **computes, prints and records** the cap,
+but it does **not enforce** it — the risk step stays advisory, capped or not, and its shortfall is
+reported as `short`, never blocking:
+
+| Active people | Contract gate: capped ask (full count 3) |
+|---|---|
+| 0–1 | 1 (never below 1) |
+| 2 | 1 (one seat is left for the author) |
+| 3 | 2 |
+| 4 or more | 3 |
+
+The `− 1` is **one seat left for the author**. It is a seat, not a check: the engine does not know who
+the author is. The platform decides whether the author may approve (GitHub never allows it; GitLab only
+when its settings say so; a local ledger checks nothing). The floor of 1 means the cap only ever trims
+the risk step.
+
+**Why the cap is not enforced yet.** The count of people errs high in the normal case. A commit is
+counted by its git name, an approval by its platform login, and yadflow never joins the two without
+exact evidence. So an ordinary two-person team can read as **four**. At four the cap lowers nothing,
+and an enforced contract gate would ask three approvals of a team with one person who is not the author
+— a gate it could never pass. A later yadflow change turns the capped count on together with
+`yad gate lower --reason`, the way out of a gate that cannot be met, once the count is accurate.
+
+**When a gate may not pass (E73).** `yad gate status` and `yad gate sync` print a warning line under a
+team review gate that has not passed yet, when the count of people suggests the gate may not pass. It is a
+**warning only**: it never holds a gate, never changes whether the gate passed, and writes nothing. There
+are two kinds of line:
+
+- `! may not be met: …` is about **today's rule**: the one approval that is always required (the base) may
+  have nobody but the author to give it.
+- `! if the risk step were enforced: …` is a **what-if**. Today only the base is enforced, so the gate can
+  still pass, and the line ends by saying that nothing beyond the one enforced approval is needed today.
+  It says what would happen if a later yadflow change enforced the extra approvals that risk tags add
+  (the risk step). "The approvals asked" means the count after the cap. The cap limits the count to the
+  active people less one, and never below 1.
+
+Every line talks about **the people counted**, and says "may" or "if", because the count can be wrong both
+ways. It is too low when a reviewer has not committed or approved inside the counting window (the same
+window as the `active people:` line), because nothing in that window records them. It is too high when
+one person commits with a work email (recorded as a name) and approves on GitHub (recorded as a login):
+yadflow never joins a name and a login without proof, so that person counts twice.
+
+| Kind | When it prints | Example line (a 90-day window) |
+|---|---|---|
+| Today | 0 or 1 active person counted, and no approval in the window | ``! may not be met: only 1 active person counted and no approval in the last 90 days, so if nobody but the author can approve, this gate cannot pass. Someone who has not committed or approved in the last 90 days is not counted. Another person's approval settles it, or use the recorded way out, `yad mode solo --reason` `` |
+| Today | Exactly 2 people counted, one not matched to a platform login and one login, and no approval in the window. Example: one developer who commits with a work email and also through GitHub's web editor, which records the login | ``! may not be met: 1 of the 2 people counted is not matched to a platform login and may be the same person as the one login, and there is no approval in the last 90 days, so the team may be one person. Then, if nobody but the author can approve, this gate cannot pass. Another person's approval settles it, or use the recorded way out, `yad mode solo --reason` `` |
+| What-if | The cap lowered the count, and the approvals do not show more people than were counted | `! if the risk step were enforced: with no cap, the full count of 3 is more than 2 active people can give (one seat is left for the author), so if nobody else joins, this gate could not pass. Nothing beyond the one enforced approval is needed today` |
+| What-if | Some people are not matched to a platform login and at least one is a login, and the smallest possible team could not give the approvals asked | `! if the risk step were enforced: 2 of the 4 people counted are not matched to a platform login, and up to 2 of them may be the same people as the logins, so the team may be as small as 2. That leaves room for 1 of the 3 approvals asked, so if the team is that small, this gate could not pass. Nothing beyond the one enforced approval is needed today` |
+
+A what-if line is not printed when a today line is. When the cap lowered the count, the last line says
+"approvals asked after the cap", because the full-count line above it quotes the number before the cap.
+
+"Not matched to a platform login" means yadflow knows the person only by a name: a git author name, or an
+approval record that carries no login (an older hand-written one, or an engineer-review record, even when
+it holds a login, because nothing in it proves that). Each such name may be a second row for one of the
+logins, so the smallest possible team is the larger of the two groups: the logins, or the names. It is
+never fewer people than the approvals prove.
+
+**An approval is evidence.** Any approval in the counting window shows that approvals can be given, so no
+today line prints. It also raises the smallest team a what-if line assumes: at least the approvals on this
+step plus one (the author), and at least two people once anyone has approved anything. That assumes
+authors cannot approve their own work: always true on GitHub, true on GitLab only when its settings say
+so, and never checked on a Product with no platform. Where it is not true, the smallest team is guessed
+too high, so a what-if line may stay quiet when it should speak; it never raises a false alarm because of
+this.
+
+A Product with no platform (every record is a name) gets no name line, because there is no login to
+compare against. Two spellings of one name (`bo` and `Bo Chen`) still count as two people; no line can
+see that yet.
+
+No line prints in solo mode, under a step that passed, under a waived step (inherited from a parent epic,
+skipped, or deferred), or when the people could not be counted. A line about the whole Product prints
+once per command, under the first step it applies to.
+
+Run `yad gate status` yourself while the review is still open: reviewers can still approve then, and a
+merged review PR cannot take approvals. Do not wait for CI to show it. The wired Product workflow runs only
+for merged review PRs (at the merge, and in a scheduled sweep of merged PRs), and it usually cannot count
+people, because the connected repos are not on disk there.
+
+**When the people cannot be counted** (`active: null` — a source could not be read), **no cap is
+computed or shown**, and the base holds as always. The engine never guesses a small number from an
+unknown. Product CI is usually this case: it checks out only the hub, so on a Product with connected
+repos the repos are not on disk.
+
+**Every cap is recorded.** When a **team** gate passes on its counted approvals while the cap lowered
+its ask, its closing record gets `capped: { needed, to, active }` beside `waived` — the full count, the
+capped ask, and the count of people it read. It records what the gate ASKED, not what held it (the base
+held). It is not written in solo mode, where nothing was counted, nor on a step that passed by its skip
+or inherited shortcut, where nothing was asked. The same rules are listed in
+`../../yad-epic/references/state-schema.md` (Closing records) and `docs/CLI.md`. `yad gate status` prints it as
+`count capped from 3 to 1 (2 active people)`. The generated review-PR body also keeps the count as it
+was when the PR was opened.
+
+Why count people: the rule names no person, no role and no step. A stored list of people goes
+stale; repository access decides who can approve.
+
+Four surfaces print the count with its cap: `yad gate sync`, `yad gate status`, the generated
+review-PR body and `yad open-pr`. (`checks/risk-route.sh` and `checks/hub-route.sh` print the count
+without the cap — they cannot count people.) `yad gate sync` and `yad gate status` share one suffix; the review-PR body and `yad
+open-pr` word the cap their own way (below). The shared suffix appears only when the step has a risk
+step. It names the cap only when the cap lowered the ask, and always ends by saying what holds:
+- ` — capped to 1: 2 active people, less one seat for the author — base enforced, risk step advisory` — the cap lowered the ask;
+- ` — capped to 1: 1 active person (never below 1) — base enforced, risk step advisory` — at 1 active person (at 0 it reads `0 active people (never below 1)`);
+- ` — base enforced, risk step advisory` — the cap lowered nothing, or the people could not be counted.
+
+Where each surface puts it:
+- `yad gate sync`: `1 approved; count: 3 approvers = base 1 + contract risk 2 — capped to 1: 2 active people, less one seat for the author — base enforced, risk step advisory`
+- `yad gate status`: `; count: <sum>` with the same suffix, after the distinct-people count. Above the
+  gates it prints the count of people and what it does, for example
+  `active people: 2 in the last 90 days — caps each gate's count at 1 approver (one seat is left for the author); reported, only the base is enforced`
+  (at 0 or 1 people the bracket reads `(never below 1)`),
+  or, when it cannot count them, `active people: NOT COUNTED — <reason> — no cap can be shown, and only the base holds each gate`.
+- the generated review-PR body: `- **Approvals needed:** 1 (enforced) · full count 3 approvers = base 1 + contract risk 2, capped to 1 for 2 active people when this PR was opened (the risk step is advisory)`.
+  With no cap: `- **Approvals needed:** 1 (enforced) · full count 3 approvers = base 1 + contract risk 2 (the risk step is advisory)`.
+  Its Active-people line: ``- **Active people:** 2 when this PR was opened (the cap is 1 (one seat is left for the author), so this gate's count is 1; `yad gate status` counts it live)``
+  (at 0 or 1 people the inner bracket reads `(never below 1)`);
+  with no risk step it ends ``… (`yad gate status` counts it live)``.
+- `yad open-pr` (a code-repo task PR, Build half): `this PR asks for 3 approvers = base 1 + contract risk 2, capped to 1 for 2 active people — base enforced, risk step advisory; …`
+  (the line goes on to name `checks/risk-route.sh`, which prints the count without the cap). The cap
+  appears only when `yad open-pr` is run from the Product; from inside a code repo the people are not counted.
+
+`yad gate review` prints JSON, and it carries the rule as an object under `step.gateRule`, and the cap under `step.cap` — an object `{ active, limit, to, capped }`, where `to` is the count asked for after the cap and
+`capped` is true when the cap lowered it — instead of a sentence. The whole `step.cap` field is `null`
+when the people were not counted.
+
+Solo mode waives approvals entirely, exactly as before, and reports no shortfall. No `capped` record is
+written in solo mode. The merge and the
+resolved threads still advance the step, and the review step's closing record carries `waived: "solo"`
+(E10). Switch with `yad mode solo --reason "<why>"` / `yad mode team`.
+In solo mode, `yad gate status`, `yad mode`, `yad next` and `yad doctor` count the active people and print
+`! solo mode is on, but …` when more than one person may work on the Product (E74): 2 or more platform
+logins, or 2 or more names not matched to a login, or an approval by someone with a platform login in the
+counting window with more than one person counted. It only suggests `yad mode team`; nothing switches by
+itself, and it never suggests solo mode. It says "may", because one person with two accounts, two
+spellings of their name, or a bot that commits or auto-approves also reads as two. When the people could
+not be counted, nothing is suggested: `yad mode` and `yad doctor` (a warning) say so; `gate status` and
+`yad next` do not repeat it.
 
 **Engagement (the Review Companion).** Each approval carries `engagement: verified | none` —
 `verified` when it was recorded through the companion (a real trailer/cards/chat session), `none` for a
 bare UI click. By **default (soft)** both count: a bare approve still passes the gate but is recorded
 `none` and draws a friendly public @-mention nudge, so review *quality* is visible without blocking
 anyone. When `hub.review.requireEngagement: true`, only `verified` approvals are counted toward the
-sets above (a determined faker can still run an empty session — the signal is **gameable by design**;
-it raises the cost of a rubber-stamp and makes laziness visible, it does not prove a human read the
-artifact). Philosophy: *visible, not impossible.*
-
-**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 / test-cases 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`.
+approvers above; when that leaves the gate short, it adds a line saying how many approvals did not count (a determined faker
+can still run an empty session — the signal is **gameable by design**; it raises the cost of a
+rubber-stamp and makes laziness visible, it does not prove a human read the artifact). Philosophy:
+*visible, not impossible.*
+
+**Touched domains** are resolved from files, not hardcoded. They name and label a review (`domain:<repo>`
+labels on the review PR); they add no approvals:
+- A step with a risk tag (e.g. architecture+contract review): the epic's `repos`.
+- Stories review: the **union of every story's `repos`** under `stories/`.
+
+So one gate, one shape — only the full count changes with the tags:
+- Epic / UI / stories / test-cases reviews (no risk tags): the count asks for 1.
+- Architecture+contract review (`risk_tags: ["contract"]`): the full count asks for **3 distinct
+  approvers** (base 1 + contract 2). The base (1) holds the gate; a shortfall against 3 is reported
+  without blocking.
+- `stories-review` is an ordinary count gate. It no longer routes per repo.
 
 ## 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).
 
+The engine checks this by content, not by date. A bridge approval records `artifactHash`, the
+fingerprint of what was approved. When the artifact's fingerprint no longer matches, the approval is
+counted as revoked: it stays on disk, it no longer counts, and the gate reports `N approval(s) revoked —
+artifact changed; re-approve`. An approval recorded with no `artifactHash` is never treated as stale.
+A hand-written approval (the `approve` action, on a Product with no platform) carries no fingerprint and
+no platform evidence, so an edit to the artifact does **not** revoke it: after a real change, remove the
+old approval and record it again once the reviewer has seen the new content.
+
 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
@@ -48,24 +217,25 @@ drifted from its lock — run it rather than recomputing by hand.
 
 ## 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)
+1. `action: open` → step `epic-review` set `in_review`; `currentStep = epic-review`.
+2. Reviewer *bob* leaves comments → captured in the comments file; the author *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**.
+3. Predicate before any approval: `|approvers|=0` → **fails**. Gate reports "missing: 1 approval(s)".
+   *alice* wrote the artifact, so her own approval is not recorded.
+4. `action: approve` approver *bob* → ledger entry added. Predicate: `|approvers|=1` → **base pass**
+   (`epic-review` has no risk tags, so the full count is also 1 and nothing is short).
 5. `action: advance` → `epic-review.status=done`, `architecture.status=in_progress`,
    `currentStep=architecture`. Gate reports the advance. The paired authoring step (`epic`) is closed
-   too, if it was not already — a gate cannot have passed on an unauthored artifact. `doctor` reports
+   too, if it was not already — a gate cannot have passed on an unauthored artifact. Each step it closes
+   gets a `closed` record: `via: "approved"` on the review step, `via: "review-passed"` on the author step (E18). In solo mode the
+   review step's record also carries `waived: "solo"` (E10). `doctor` reports
    any surviving violation as `YAD-STATE-005`; `yad gate repair <epic>` heals it.
 
 ## 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
+alone decide the gate — but it makes the `approved.md` record's "Reviewed / commented by" section
 attributable, and it is the same shape a future service or the platform bridge can write.
 
 ## Non-blocking companion comments (`<!-- yad:noblock -->`)
@@ -77,33 +247,39 @@ marker, and the gate **excludes marked threads** from the unresolved-thread bloc
 not "resolve to pass" — it ignores them). A reviewer's *genuine* concern is posted **without** the
 marker and blocks normally, exactly as a `CHANGES_REQUESTED` or any unresolved human thread does.
 
-## 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`
-(`yad-hub-bridge`) reads that platform state with the reviewer's own `gh`/`glab` and writes the **same**
+## Platform-backed input (the verified ledger)
+When the Product has a platform (`.sdlc/hub.json`), reviewers can approve/comment
+on a real PR/MR instead of (or as well as) the skill recording it directly. The sync reads that platform
+state with the local user'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(s) via the roster's **per-scope map** (`roles: { hub: [...], <repo>: [...] }`): a person
-  can hold owner + reviewer + domain-owner at once, and a repo can list several people per role. The
-  `hub` roles plus each touched domain's `roles[<repo>]` are emitted; `domain-owner` is also **derived**
-  when a roster `name` equals a repo's `domain_owner`/`domain_owners` (legacy fallback) and that repo is a
-  touched domain; an unmapped login is a plain `reviewer`, never promoted.
-- On PR/MR open the assignee is the committer and reviewers are the scope's `reviewer` + `domain-owner`
-  members (minus the committer); the owner/author is recorded, not requested. See
+tagged `"source": "bridge"`. With a local ledger `yad gate sync` writes them; with a verified ledger
+`yad gate ci` writes them at merge, and a local `yad gate sync` only prints. **The predicate above is
+unchanged**: it counts distinct approvers regardless of how they were recorded.
+
+- The `approver` / `commenter` is the platform login that reviewed. There is no lookup and no role.
+- On PR/MR open the assignee is whoever opens it: `@me` on GitHub, and the login `glab` reports on GitLab.
+  **No reviewers are requested** — the command prints `no reviewers were requested — ask them on the
+  PR itself`. `domain:<repo>` labels for the touched domains are still applied. See
   `../yad-hub-bridge/references/login-roster.md`.
-- `sync` is idempotent (upsert by `(step, approver, role, domain)`; key comments on comment id) and
-  never touches **manual** approvals. A revoked approval is superseded **while the step is open**; once
+- `sync` is idempotent (upsert by `(step, approver)`, one record per person; comment records by
+  `(step, commenter, round)`, an unchanged round rewritten in place) and never touches **manual** approvals. An older bridge record that carries `role`/`domain` is
+  recognised as `../yad-hub-bridge/references/login-roster.md` → "Older records" describes, and replaced
+  by one login-named record that keeps its fingerprint. Every sync write (`yad gate sync`, `yad gate ci`)
+  also records the login on the older records the roster can place for certain; only those it cannot
+  place still need the roster on a later sync. A bridge approval records the
+  platform's evidence (`approvedAt`, and on GitHub `commit`, `url`, `reviewId`) — for the record only. A revoked approval is superseded **while the step is open**; once
   the step is `done` its approvals are kept as the record of why it passed, and a re-sync only re-binds
   new ones (see `../yad-hub-bridge/references/bridge.md` → "Idempotent re-sync").
-- 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: `../yad-hub-bridge/references/bridge.md`.
+- The architecture+contract staleness rule applies to bridge approvals too: a re-lock changes the
+  surface fingerprint, so bridge approvals of the old surface stop counting (they stay on disk as revoked).
+- No platform / no CLI → the gate runs local with no error. Detail: `../yad-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).
+- One approver who is not the author 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).
+- The risk step asks for more people only where a change can break a shared surface
+  (contract/auth/payments). It is advisory for now: the capacity cap (E72) is reported. A later change will
+  enforce it together with `yad gate lower --reason`, so that a gate asking for more people than the team
+  has will always have a way out. Until then E73 only warns when a gate may not pass.
+- No stored list of people: it goes stale, and repository access already decides who can approve.
 - Everything is a file, so a future service can drive the same gate by writing the same records.

package/skills/yad-run/SKILL.md

@@ -1,26 +1,25 @@
 ---
 name: yad-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".'
+description: 'Phase 4 (automation) — the orchestrator that makes the second dial real. Drives a story''s Build loop (spec → tasks → implement → checks) in one code repo, reading each step''s advance dial from build-state: on `auto` it advances on its own, on `human` it stops for a human. Records every run in the trust log, the run record `yad dial` shows as advice. With `checks` on auto, a clean gate pass advances to engineer-review; any failure, scope overrun, or contract-surface touch HALTS and pulls in a human. Also sets a step''s dial (`yad dial`, nothing to earn since E34) and flips the kill switch (`yad kill` / `yad unkill`). Never advances a Shape step or the engineer review. Use when the user says "run Build", "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 —
+**Goal:** Be the **engine** that the advance 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 Build 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.
+(dial `advance: auto`, step succeeded) or **stop for a human** (dial `advance: human`, or any halt
+condition). Every run is recorded in the **trust log** — the run record `yad dial` shows the team, as
+advice, when it sets a dial.
 
 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`.
+human regardless of any dial. This skill **drives Build only**: it never drives a Shape step, and the
+**engineer review is a gate** — always a person.
 
-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.
+**Nothing has to be earned (E34).** Automation used to be unlocked per step once its trust log cleared a
+threshold. Now the team sets each lane step's dial with `yad dial`, which prints that step's run record
+beside it as advice and never refuses on it. The kill switch (`yad kill`) holds every step at `human`.
 
 ## Conventions
 
@@ -28,16 +27,17 @@ signal to seed them from, so they are earned only on real runs.
   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).
+- Automation config is `.sdlc/config.yaml` → `automation:` (`back_steps`, `default`). The kill
+  switch and the Shape dials live in `.sdlc/automation.json`, and are read and written **only through the
+  engine** — `yad dial … --json`, `yad kill`, `yad unkill`. Never read or edit either file for a dial.
+- Per-story Build state: `epics/<epic>/.sdlc/build-state/<story-id>.json` (per repo).
 - Trust ledger: **shard-then-fold** — each run is its own shard file
   `epics/<epic>/.sdlc/trust-log/<story>-<repo>-<step>-<uid>.json` (a fresh `uid` per run, so concurrent
   writers never conflict); readers UNION the folded `trust-log.json` with every loose shard, and
   `yad tidy up` folds finished shards back into `trust-log.json`. Schemas:
   `../yad-epic/references/state-schema.md`.
-- These machine-written back-half files (`build-state/<story>.json`, the `trust-log/` shards) are
-  committed by **`yad checkpoint`** — the back-half analogue of the front-half `yad gate` sync; the loop
+- These machine-written Build files (`build-state/<story>.json`, the `trust-log/` shards) are
+  committed by **`yad checkpoint`** — the Build analogue of the Shape `yad gate` sync; the loop
   calls it each iteration so the state is durable and shared without a human commit. (`yad checkpoint`
   stages the shard dirs; `yad tidy up` later folds finished shards — loose objects + `git gc`.)
 - The orchestrator **calls the existing step skills unchanged** — `yad-spec` (A), `yad-implement`
@@ -52,78 +52,108 @@ signal to seed them from, so they are earned only on real runs.
 - `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`).
+- For `set-dial`: `step` (a `back_steps` id), `to` — `human` | `auto` (the older `human_approve` |
+  `machine_advance` mean the same two things).
+- For `kill`: `reason` (required). For `unkill`: an optional `reason`.
 
 ## 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.
+Read `config.yaml` `automation` (for `back_steps`), the story's `build-state/<story>.json` (create it from the
+`back_steps` defaults if absent — all `advance: human` (`automation: human_approve`), `engineer-review` `locked:true`, and
+**write it to disk before the loop starts**, because `yad next` reads that file to know this lane
+exists), and `trust-log.json` (treat missing as `[]`). Resolve the code repo.
+
+If the file exists but has **no entry for this `repo`**, add that repo's entry from the same `back_steps`
+defaults — the file may already hold another repo, or a skipped lane — and never remove an entry you did
+not add. If this repo's entry is **`status: skipped`** (E39: the whole lane was set aside with
+`yad skip <epic> <story> --repo <repo>`, because the story needs no change in this repo), **do not drive
+it**: stop, report the recorded `record.reason`, and point at `yad unskip <epic> <story> --repo <repo>` if
+the lane is owed after all. **Never write a Build step as `skipped` or `deferred`**: a lane is skipped
+whole or not at all, and `yad doctor` reports a single step set aside.
+
+Also read **which skill runs each step** — `yad skill list --json`, whose `steps[]` gives each step id
+its `skills` array. That is the project's choice (`.sdlc/skills.json`, E6) and the engine's default
+when it has made none. Read it once here; it does not change during a run.
 
 ### `action: run` — drive the loop
 Walk the steps for `repo` starting at `from`/`currentStep`. For each step:
 
-1. **Run the step's skill** — `spec`→`yad-spec`, `tasks`→ the tasks leg of `yad-spec`,
-   `implement`→`yad-implement`, `checks`→`yad-checks (action: run)`. Capture its result.
+1. **Run the step's skill — use the list from Step 0, never a name written here.** Look the step id
+   up in `yad skill list --json` and run every entry of its `skills` **in order**, each one seeing what
+   the one before it produced; the last output is the result. (`yad next <epic> --json` gives the same
+   answer per lane once `build-state/<story>.json` is on disk, if you already have it open.) Which
+   skill runs a step is the project's setting, so a hardcoded name here would make this loop do one
+   thing while `yad next` tells the user another — on the same project, with the automation half
+   winning. Unbound, the engine answers `spec`→`yad-spec`, `tasks`→ the tasks leg of `yad-spec`,
+   `implement`→`yad-implement`, `checks`→`yad-checks`, which is what this step used to say. Pass
+   `action: run` to `yad-checks`. Capture the result.
 2. **Derive trust signals & write a trust-log shard** — write the entry to its own file
    `trust-log/<story>-<repo>-<step>-<uid>.json` (a fresh `uid` per run; never append to a shared file),
    with `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.)
+3. **Ask the engine for the effective dial:** `yad dial <epic> <story> --repo <repo> <step> --json`, and use
+   its `advance`. It is `human` whenever the step is a gate (`why: gate` — a read never refuses one), the kill switch
+   is on, or `.sdlc/automation.json` cannot be read (`automationError` says so) — so never work the dial out from the files yourself.
 4. **Decide:**
    - **HALT** if the step failed — any check FAIL, a scope overrun (`yad-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>`".
+     file-boundary rule), a contract-surface touch, or any ambiguity. Set the step `status: blocked`
+     **with a `record`** — `{ "reason": "<the halt cause>", "by": "<login or null>", "date":
+     "<YYYY-MM-DD>" }` — write the `rejected` trust entry, **stop the loop**, and report what a human
+     must resolve. The record is not decoration: since shape 7 a `blocked` step with nothing recorded
+     on it reads as `todo` ("not started"), so a halt written without one is indistinguishable from a
+     lane nobody has begun. `yad doctor` reports the difference as `step:no-record`.
+   - else if effective dial is **`advance: auto`** → set the step `done` **with a `closed`** —
+     `{ "by": "<login or null>", "date": "<YYYY-MM-DD>", "via": "auto", "run": "<the trust-log uid>" }` —
+     advance `currentStep` to the next step, and **continue the loop** (this is the Step B auto-advance
+     for `checks`).
+   - else (**`advance: human`**) → set the step `done`/`in_review`, and give a `done` step a `closed` —
+     `{ "by": "<login or null>", "date": "<YYYY-MM-DD>", "via": "human", "run": "<the trust-log uid>" }` —
+     then **stop** and report "waiting for a human at `<next-step>`".
+   - `closed` is the step's **closing record** (E18): how the lane moved past it, and which run did it.
+     Never write one over a `closed` already on the step. See `references/run-loop.md`.
 5. **Always stop at `engineer-review`** (it is `locked`): hand off to `yad-engineer-review` for the human merge
    gate, which finalizes the trust verdict (confirm/override the provisional one).
 
 **Commit the machine-written state.** After each iteration's writes (the trust-log shard in 2 and the
 build-state change in 4), run `yad checkpoint --push` from `{project-root}`. It commits *only* the
-`trust-log/` shards + `build-state/<story>.json` (never a front-half gate file) as one `chore(hub): …`
+`trust-log/` shards + `build-state/<story>.json` (never a Shape gate file) as one `chore(hub): …`
 audit-trail commit, and only ever on the default branch. It is a safe no-op when nothing changed, so
 call it every iteration — teammates don't review these machine writes, but CI and `yad status` on
 other machines must see current trust evidence. Never run it off the default branch (it will refuse):
-an unpushed or branch-stranded trust log quietly undermines the "earned automation" premise.
-
-### `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 the trust
-  ledger — the **union** of the folded `trust-log.json` `runs` PLUS every `trust-log/` shard, filtered to
-  this step (and repo) — 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).
+an unpushed or branch-stranded trust log leaves the run record `yad dial` shows out of date.
+
+### `action: set-dial` — set (or revert) a step's advance dial
+Run `yad dial <epic> <story> --repo <repo> <step> --to <human|auto>` (map `human_approve` → `human` and
+`machine_advance` → `auto` first). The engine writes both dial names on the lane step, refuses a gate and
+a lane step `yad-run` has not written yet, and prints the step's run record in that repo **as advice**.
+Relay its output. There is **no threshold** (E34): the team decides, and "it seems fine" is theirs to
+judge. `--to human` is always accepted. Never edit `build-state` for a dial yourself.
+
+For a Shape author step the team wants on auto, point at `yad dial <step> --to auto` — project-wide, and
+recorded only: this loop never drives a Shape step.
 
 ### `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 `yad-status` will show it.
+Run `yad kill --reason "<why>"` or `yad unkill [--reason "<why>"]`. The engine records who, when and why
+in `.sdlc/automation.json`; while the switch is on, **every** step's effective dial is `human`. Tell the
+user to commit that file so every machine and CI sees it. Never set a `kill_switch` in `config.yaml`:
+nothing reads it, and `yad doctor` fails on one left `true`.
 
 ## 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.
+- **The dial is the team's (E34).** `yad dial` sets it and shows the run record as advice; nothing is
+  earned, and nothing is refused on evidence. A gate is never auto.
+- **Reversible in one move.** `yad dial … --to human` is never refused; `yad kill --reason "<why>"` holds
+  every step at human, with 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.
+- **This skill never drives a Shape step, and never passes the engineer review.** The review is a gate,
+  and the kill switch holds every step at human.
 - **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`.
+- The loop and the trust-verdict derivation: `references/run-loop.md`.
 - State/trust schemas: `../yad-epic/references/state-schema.md`.
 - The steps it drives: `../yad-spec/`, `../yad-implement/`, `../yad-checks/`; the human gate it
   hands off to: `../yad-engineer-review/`.