yadflow 3.19.0-next.2 → 4.0.0-next.3

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

@@ -1,8 +1,9 @@
-# `yad-run` — the loop, the trust verdict, the threshold
+# `yad-run` — the loop and the trust verdict
 
 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`**.
+and pins down the judgment the skill makes: **what trust verdict to record**. Whether a step advances on
+its own is not a judgment any more — the team sets the dial with `yad dial` (E34), and the engine answers
+what applies.
 
 ## The Build steps
 
@@ -12,39 +13,66 @@ 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 `yad-spec` (the heavy ceremony, then the atomic `tasks.md`).
-`implement` is one atomic task via `yad-implement`. `checks` is `yad-checks (action: run)`.
-`engineer-review` is the human gate at `yad-engineer-review` — always a stop, never automated.
+**These names are the engine's DEFAULTS, not a fixed wiring.** Which skill runs a step is the
+project's setting in `.sdlc/skills.json`, so the loop reads `yad skill list --json` once at Step 0 and
+runs every entry of that step's `skills`, in order, when it is bound to more than one. Unbound: `spec` and `tasks` are the two legs of `yad-spec` (the heavy ceremony, then the atomic
+`tasks.md`), `implement` is one atomic task via `yad-implement`, and `checks` is
+`yad-checks (action: run)`. `engineer-review` is the human gate at `yad-engineer-review` — always a
+stop, never automated, and bindable like any other step.
 
 ## The loop (pseudocode)
 
 ```
 cfg   = config.yaml.automation
-bs    = build-state/<story>.json.repos[<repo>]        # create from defaults if absent
+bs    = build-state/<story>.json.repos[<repo>]        # create the FILE from defaults if absent; if the file
+                                                      #   exists but has no entry for <repo>, add one from the
+                                                      #   defaults — never remove an entry you did not add
+if bs.status == "skipped":                            # E39: the whole lane was set aside with
+    STOP — report bs.record.reason                    #   `yad skip <epic> <story> --repo <repo>`; do not drive it.
+                                                      #   `yad unskip <epic> <story> --repo <repo>` puts it back.
+                                                      # Never write a single Build step as skipped or deferred.
 step  = from or bs.currentStep
 
 while step is a Build step (not engineer-review):
-    result = run_step_skill(step)                     # yad-spec | yad-implement | yad-checks
+    result = run_step_skill(step)                     # the skill(s) `yad next --json` names for this lane
 
     signals = derive_signals(step, result)            # see "Deriving signals"
     verdict = derive_verdict(signals)                 # rejected | approved-with-edits | approved-unchanged
     uid = fresh_short_token()                          # e.g. `openssl rand -hex 4` — unique per run,
                                                        #   never reuse; a collision would fuse two runs
     write trust-log/<story>-<repo>-<step>-<uid>.json   # ONE shard file = ONE entry (never append to a shared file)
-      = { story, repo, step, uid, automation: bs.step.automation, verdict, signals, ranBy, date }
+      # `automation` is recorded in the OLD vocabulary (this is a history record, and `yad migrate`
+      #  deliberately leaves it alone). Read the step's dial from EITHER spelling.
+      = { story, repo, step, uid, automation: bs.step.automation ?? old_name_for(bs.step.advance), 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; checkpoint; STOP and report the human action needed
-    elif eff == "machine_advance":
-        bs.step.status = "done"; advance bs.currentStep to next; persist; checkpoint; continue  # Step B advance
-    else:  # human_approve
-        bs.step.status = "done"; persist; checkpoint; STOP and report "waiting for human at <next>"
+        # `blocked` needs its `record` (E38) — that is what separates a halted lane from one that has
+        # simply not started. `reason` is the halt cause you already have in hand.
+        bs.step.status = "blocked"
+        bs.step.record = { reason: "<check FAIL | scope overrun | contract touch | ambiguous>",
+                           by: "<platform login, else git user.name, or null>", date: "<YYYY-MM-DD>" }
+        persist; checkpoint; STOP and report the human action needed
+    elif eff == "auto":
+        bs.step.status = "done"
+        bs.step.closed = { by: "<platform login, else git user.name, or null>", date: "<YYYY-MM-DD>", via: "auto", run: uid }
+        advance bs.currentStep to next; persist; checkpoint; continue  # Step B advance
+    else:  # "human"
+        bs.step.status = "done"
+        bs.step.closed = { by: "<platform login, else git user.name, or null>", date: "<YYYY-MM-DD>", via: "human", run: uid }
+        persist; checkpoint; STOP and report "waiting for human at <next>"
 
 # reached engineer-review: always stop, hand to yad-engineer-review (human gate, finalizes the verdict)
 ```
 
+`closed` is the step's **closing record** (E18): who wrote it, when, and how the lane moved past the
+step. `via: "auto"` means the dial let the run go on by itself; `via: "human"` means it stopped for a
+person. `run` is the `uid` of the trust-log shard this run wrote, so the record points at the evidence.
+`by` is the login `gh api user` / `glab api user` reports, else git `user.name`, else `null`
+(`YAD_PLATFORM_LOGIN=0` turns the lookup off).
+Write it only when you write `done`, and never over a `closed` already on the step.
+
 `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.
@@ -56,24 +84,22 @@ way `git gc` folds loose objects later (`yad tidy up` folds finished shards into
 `trust-log.json` / `build-log.json`) — plus any story `status:` flip (→ in-build/shipped) once that
 story has a build-log ship (#112) — as one
 `chore(hub): sync Build state — <epic>/<story> by @<login> [skip ci]`
-audit-trail commit, on the default branch only,
+audit-trail commit (`@<login>` when the platform login is known, else the git `user.name`, else `unknown`), on the default branch only,
 staging *only* those files by an explicit allowlist (never a Shape gate file — so `ledger-guard`
 never trips). It is idempotent (a no-op when nothing changed), so calling it after every transition —
 including a halt — is safe and keeps the shared trust evidence current for CI, teammates, and
 `yad status` on other machines. It refuses to run off the default branch (an unsigned `[skip ci]`
 commit inside a future PR range would fail `verified-commits` and strand the PR).
 
-## Effective dial (kill switch & locks always win)
+## Effective dial (the kill switch and gates 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"
+eff = (yad dial <epic> <story> --repo <repo> <step> --json).advance    # "human" | "auto"
 ```
 
-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 five Shape steps are covered by `locked` / `locked_steps`.
+The engine reads the lane step's dial under either spelling (the OLD name wins), and answers `human`
+when the step is a gate (`engineer-review`) or the kill switch in `.sdlc/automation.json` is on — whatever
+the dial says. Its `why` says which: `lane`, `gate`, `kill` or `unknown` (a step id this release does not know), and `automationError` is present when the file cannot be read.
 
 ## Deriving signals & the provisional verdict
 
@@ -106,35 +132,31 @@ may also override it to `rejected` — e.g. the human discards/regenerates the s
 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 machine's work was accepted as-is. Any human correction is `approved-with-edits` (useful, and a sign
+the step still wants a person); any failure or boundary breach is `rejected`.
 
-## The trust threshold (when a step is earned)
+## The run record as advice (E34)
 
-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`:
+`yad dial` prints a step's record when someone sets its dial, and whenever it is asked with no `--to`:
 
 ```
-# read the ledger by UNION: the folded trust-log.json `runs` array PLUS every loose trust-log/ shard
-# (concatenate — every shard is a distinct run; never dedup by story/repo/step, the threshold counts re-runs)
-all   = trust-log.json.runs + [read each file in trust-log/]
-slice = entries in `all` for this step (this story's repo; widen to the project if you track it there)
+all   = trust-log.json.runs + [read each file in trust-log/]   # UNION; every shard is a distinct run
+slice = entries in `all` for this step in this repo
 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.
+It is **advice, never a rule.** There is no threshold and no refusal: the team decides whether a step
+runs on auto, and the record is what they read to decide. A step with no runs says so — no evidence either
+way is not evidence against.
 
-Reverting (`to: human_approve`) is never gated — automation must be reversible in one move.
+Reverting (`--to human`) and the kill switch are always one move.
 
 ## What stays human, always
 
 - `engineer-review` — the merge gate. `yad-run` always stops here and hands to `yad-engineer-review`.
-- The five Shape steps (`epic`, `architecture`, `ui-design`, `stories`, `test-cases`) — not in
-  `back_steps`, in `locked_steps`; the dial-setter refuses them.
+- The Shape steps — this loop never drives them. A Shape author step's dial may be set to auto for the
+  project (`yad dial <step> --to auto`), and is only recorded until the engine runs agents (E26); every
+  Shape review gate is a person.
 - Any contract-surface change — halts the loop and routes back to the architecture gate, regardless of
   the dial.

package/skills/yad-ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-ship
-description: 'Build helper of the gated SDLC — commit AND open the task PR/MR in one step. A thin orchestration over yad-commit then yad-open-pr: commit the staged atomic change by the conventions (Conventional-Commits subject, Task → Contract-Change trailers, an OPTIONAL Co-Authored-By footer that is OFF by default and added only when --ai <id> is explicitly passed, ≤3-file atomic guard), then push the branch and open the PR/MR from the committed template with the roster auto-assigned. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the `yad ship` CLI; never merges. Use when the user says "ship this task", "commit and open the PR", or "commit and raise the MR". (For the engineer review + merge, use yad-engineer-review.)'
+description: 'Build helper of the gated SDLC — commit AND open the task PR/MR in one step. A thin orchestration over yad-commit then yad-open-pr: commit the staged atomic change by the conventions (Conventional-Commits subject, Task → Contract-Change trailers, an OPTIONAL Co-Authored-By footer that is OFF by default and added only when --ai <id> is explicitly passed, ≤3-file atomic guard), then push the branch and open the PR/MR from the committed template, assigned to the logged-in gh/glab login with no reviewers requested. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the `yad ship` CLI; never merges. Use when the user says "ship this task", "commit and open the PR", or "commit and raise the MR". (For the engineer review + merge, use yad-engineer-review.)'
 ---
 
 # SDLC — Commit + Open PR/MR (Build helper)
@@ -19,12 +19,12 @@ its own and **never merges**. The engineer review + merge are Step E (`yad-engin
     `Task → Contract-Change → Co-Authored-By` (the footer **off by default** — added only via an explicit
     `--ai`), the ≤3-file atomic guard (`../yad-commit/SKILL.md`).
   - PR/MR: pushed branch, the committed template prefilled, title defaulting to the commit subject,
-    roster auto-assign, risk routing (`../yad-open-pr/SKILL.md`).
+    the assignee set and no reviewers requested, risk routing (`../yad-open-pr/SKILL.md`).
 - **Order matters:** the PR/MR is opened **only if the commit lands**. A failed commit, a tripped
   atomic guard, or `--dry-run` stops the step before anything is pushed.
-- **Stage-aware on the product hub** (via `yad-open-pr`): on a `review/EP-*` branch `ship` opens the
+- **Stage-aware on the Product** (via `yad-open-pr`): on a `review/EP-*` branch `ship` opens the
   Shape **artifact-review** PR (delegating to `yad gate open` — `--title` is ignored); on any
-  other hub branch it opens the **code-task** PR from the bundled code-task template. In a code repo
+  other Product branch it opens the **code-task** PR from the bundled code-task template. In a code repo
   it is unchanged.
 
 ## Inputs
@@ -33,11 +33,11 @@ its own and **never merges**. The engineer review + merge are Step E (`yad-engin
 - `ai`              — co-author footer: `claude|copilot|cursor|coderabbit|none` (default `none` = **no
   footer**; the `Co-Authored-By` trailer appears only when this flag names a tool).
 - `task`           — Task trailer (optional; derived from the branch when omitted).
-- `contractChange` — flag; marks the contract surface touched (commit trailer + PR escalation).
+- `contractChange` — flag; marks the contract surface touched (commit trailer + a raised approver count on the PR).
 - `repo` / `risk` / `platform` / `title` — PR/MR options (see `yad-open-pr`).
 - `base`           — override the PR/MR base. The default is the repo's own default branch, resolved
   by the full chain in **Base branch** (`yad-open-pr`) — the canonical description, including the
-  hub rung — never a hardcoded `main`. A non-default base loses the AI first pass; `ship` warns and
+  Product rung — never a hardcoded `main`. A non-default base loses the AI first pass; `ship` warns and
   still opens.
 
 ## On Activation
@@ -53,12 +53,16 @@ yad ship --type <type> -m "<subject>" [--ai <id>] [--task <id>] [--contract-chan
          [--repo <name>] [--risk <level>] [--title "<subject>"]
 ```
 The CLI runs `yad commit` and, only if it succeeds, `yad open-pr` — committing the change, pushing the
-branch, and opening the PR/MR with the template prefilled and reviewers auto-assigned.
+branch, and opening the PR/MR with the template prefilled and the assignee set. No reviewers are
+requested: it prints `no reviewers were requested — ask them on the PR itself`.
 
 ### Step 3 — Route + stop (no merge)
-On `high` risk or a contract touch, run `bash checks/risk-route.sh <pr-body>` for the required
-domain-owner reviewers. Report the commit + the PR/MR URL. The PR now runs the check gates (Step C);
-the engineer review and merge are Step E (`yad-engineer-review`).
+The open step prints how many approvers the PR asks for — the body's level and the base branch's risk
+map, the larger step winning (E66). When it asks for more than one, `bash checks/risk-route.sh "<pr body>"`
+lists the touched domains to ask; ask reviewers on the PR/MR itself. It also prints a reviewer
+**suggestion** (E68): who has committed in the touched folders in the last 30 days, and what CODEOWNERS
+lists — a hint about who may know the code, never a request and never a list of owners. Report the commit + the PR/MR URL. The PR now
+runs the check gates (Step C); the engineer review and merge are Step E (`yad-engineer-review`).
 
 ## Hard rules
 
@@ -67,7 +71,7 @@ the engineer review and merge are Step E (`yad-engineer-review`).
 - **No AI footer by default.** The wrapped commit writes a `Co-Authored-By` trailer ONLY when `--ai <id>`
   is explicitly passed; never add it on the AI's own initiative.
 - **No PR without a landed commit.** A failed/`--dry-run` commit stops the step before pushing.
-- **High risk routes to domain owners** — the same escalation as the gate.
+- **High risk raises the approver count** — the same count as the gate.
 - **Shipping here never merges.** The human owns the merge in `yad-engineer-review`.
 
 ## Reference

package/skills/yad-spec/SKILL.md

@@ -30,7 +30,7 @@ is the same graceful-degradation pattern `yad-ui` uses for Impeccable.
   `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`.
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.
 
 ## Inputs
 
@@ -59,7 +59,20 @@ Read `epics/<epic>/contract.md` and `epics/<epic>/.sdlc/contract-lock.json`. The
 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.
+contract here. (On a route that HAS one; the short lanes do not — see below.)
+
+- **Short-lane-safe:** read `epics/<epic>/.sdlc/state.json`'s `profile` first (an epic seeded before
+  file shape 6 has no such key — fall back to what its `steps[]` contains). On the `chore` and
+  `spike` routes there is no architecture step, so `contract.md` and `contract-lock.json` **never
+  exist** — that is the route's design, not a missing file to chase. Write the spec from the story and
+  `epic.md` alone, record `contract-lock: none` in Step 6's frontmatter, and say in the spec that this
+  epic defines no contract surface.
+- A short lane has no architecture gate to route back to. So the rule above becomes stricter, not
+  looser: if the story turns out to need the shared cross-repo surface to CHANGE, **STOP and escalate
+  to a human** — the work belongs to a new epic on `classic`. Do not write the change into a spec on a
+  short lane. Do not create `specs/<story>/contracts/` at all on one — a short-lane story has no
+  surface to quote, and a slice folder under a lockless epic is what the CI gate refuses. (If one
+  already exists, a commit that only DELETES it is allowed through, which is the way back out.)
 
 ### Step 4 — Detect Spec Kit
 Check for `/speckit.*` slash-commands and/or `demo-repos/<repo>/.specify/`. Record the result for
@@ -83,7 +96,9 @@ to read. See `references/spec-handoff.md` for the exact file map and per-file de
 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
+in the code repo — or the literal `none` on a short-lane epic, which has no lock; never a made-up or
+empty hash, which the CI gate reads as a broken lock and fails), `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 (Shape state untouched)
@@ -93,7 +108,7 @@ Report: the spec folder path, the files written, whether Spec Kit was used, the
 
 ### Step 8 — Record the `spec` trust signal (Phase 4b)
 When this step runs under the orchestrator (`yad-run`), the generated spec is a Build run that the
-trust log measures (it is the evidence that could later earn the `spec` step a `machine_advance`). The
+trust log measures (part of the run record `yad dial` shows beside the `spec` dial). 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
@@ -104,8 +119,8 @@ pattern as the engineer review finalizing `implement` at `yad-engineer-review`).
 entry in its own shard `epics/<epic>/.sdlc/trust-log/<story>-<repo>-spec-<uid>.json` (a fresh `uid` per
 run; readers union the folded `trust-log.json` + the loose shards). Schema:
 `../yad-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.
+log measures orchestrated runs. The record is advice: the `spec` dial is
+whatever the team sets with `yad dial`, and this step never changes it.
 
 ## Hard rules (build plan §A, Cross-cutting)
 

package/skills/yad-spec/references/spec-handoff.md

@@ -33,6 +33,7 @@ demo-repos/<repo>/specs/<story-id>/
   research.md     # decisions/unknowns resolved during clarify
   data-model.md   # entities/fields THIS repo implements (quoting the shared ones from the contract)
   contracts/      # the API/event surface this repo implements (quoted from the locked contract)
+                  # OMITTED ENTIRELY on a short-lane epic — see below
   plan.md         # technical approach for this repo
   tasks.md        # numbered atomic tasks (T01…), each scoped to the files it may touch
   link.md         # back-pointer to the story in the product repo (Step A adds this; not a Spec Kit file)
@@ -54,6 +55,11 @@ comes from the story's acceptance criteria and the **locked contract surface**
 - **`contracts/`** — the slice of the API/event surface this repo implements, **quoted from the locked
   `contract.md`** (e.g. `POST /orders` request/response). Add a one-line note that this is a quote of
   the locked surface, not a new definition.
+  **Do NOT create this folder on a short-lane epic** (`profile: chore` or `spike`). Those routes have
+  no architecture step, so there is no locked `contract.md` to quote and no lock for CI to check the
+  quote against — the gate refuses a slice under a lockless epic. A short-lane story consumes the
+  shared surface through the code it calls; it never restates it. If one already exists, a commit
+  that only DELETES it is allowed through, which is the way back out.
 - **`plan.md`** — the technical approach for this repo at story altitude (components, sequence,
   test approach). No new cross-repo surface.
 - **`tasks.md`** — numbered atomic tasks. Each task: an ID (`T01`, `T02`, …), a one-line goal, and an
@@ -69,7 +75,9 @@ epic: EP-<slug>
 repo: <repo>
 feature-id: EP-<slug>-S0N
 product-repo: <path to the product repo — absolute, or relative to THIS file's dir (specs/<story>/)>
-contract-lock: sha256:<hex copied from epics/EP-<slug>/.sdlc/contract-lock.json>
+contract-lock: sha256:<hex copied from epics/EP-<slug>/.sdlc/contract-lock.json>   # or the literal
+                 # `none` on a short-lane epic, which has no lock. Never an empty or invented hash:
+                 # CI reads an unparseable value as a broken lock and fails.
 speckit: installed | not-installed
 generated: <YYYY-MM-DD>
 ---
@@ -89,12 +97,16 @@ back to the architecture gate in the product repo — it is never widened from t
 `product-repo` is the one field CI resolves on disk (contract-check, lineage-check, epic-open,
 reconcile-debt all read it). Every gate resolves it the SAME way: an **absolute** path is used as-is; a
 **relative** path is joined to this `link.md`'s own directory, `specs/<story>/` — `../../` climbs out
-of the story dir and out of `specs/` to the code-repo root, so a hub checked out beside the code repo
-is `../../../<hub-dir>`. A relative value that only resolves from the **repo root** still works too
+of the story dir and out of `specs/` to the code-repo root, so a Product checked out beside the code repo
+is `../../../<product-dir>`. A relative value that only resolves from the **repo root** still works too
 (what contract-check historically did), so older `link.md` files keep gating. Write it as an
 **unquoted scalar** — `"..."` or `'...'` is taken literally, and a leading `~`/`$VAR` is never
-expanded. An unreachable path degrades the hub-reading gates to a PASS-with-note rather than failing
-them, and each one now says so in its output.
+expanded. An unreachable path degrades the Product-reading gates to a PASS-with-note rather than failing
+them, and each one now says so in its output. **Reachable-but-lockless is a different case and does
+NOT degrade:** when the Product resolves and `epics/<epic>/.sdlc/` is there with no
+`contract-lock.json` in it, a claimed `Contract-Change: yes` FAILS, because nothing exists for the
+claim to be true of. That is the ordinary state of a short-lane epic, of a stub, and of a classic epic
+that has not reached its architecture gate yet.
 
 ## Do not re-invent the contract
 

package/skills/yad-status/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-status
-description: 'Read-only view of an SDLC epic: prints the current step, each step''s dials (assistance/automation) and status, and which approvals are still required at the active gate. For stories in Build it also prints each Build step''s automation dial, status, and trust record (runs / % approved-unchanged / whether it clears the threshold to be earned), plus the system-wide kill-switch state — so the team can see WHY a step is automated and reverse it with evidence. Also prints the cross-cutting personal skills-log roll-up from the LOCAL-ONLY learning ledger (gitignored, never committed/pushed — the local learner''s own learning, by stage). Surfaces the Phase 5 instrumentation signals: per-step "earned but manual" (nudge cost) and, across multiple epics, a fleet roll-up (scale of read). Use when the user says "yad status", "where is epic EP-...", "what is blocking the gate", "show the trust record", "team skills", or "fleet status".'
+description: 'Read-only view of an SDLC epic: prints the current step, each step''s dials (driver/advance, under either spelling) and status, and which approvals are still required at the active gate. For stories in Build it also prints each Build step''s automation dial, status, and run record (runs / % approved-unchanged, as advice), plus the kill switch and the Shape author dials from .sdlc/automation.json — so the team can see WHY a step is automated and reverse it. Also prints the cross-cutting personal skills-log roll-up from the LOCAL-ONLY learning ledger (gitignored, never committed/pushed — the local learner''s own learning, by stage). Across multiple epics, prints a fleet roll-up (scale of read). Use when the user says "yad status", "where is epic EP-...", "what is blocking the gate", "show the trust record", "team skills", or "fleet status".'
 ---
 
 # SDLC — Status (read-only)
@@ -10,7 +10,8 @@ reads `.sdlc/` and `reviews/` and reports.
 
 ## Conventions
 - `{project-root}` resolves from the project working directory.
-- Operate on one epic: `{project-root}/epics/EP-<slug>/`.
+- Operate on one epic: `{project-root}/epics/EP-<slug>/`. The Product level is the exception:
+  `EP-foundation` lives at `{project-root}/foundation/` (its `.sdlc/` and `reviews/` are there).
 
 ## On Activation
 
@@ -27,7 +28,9 @@ distinct run; never dedup by story/repo/step — but DO skip a shard whose full
 `(story,repo,step,uid)` already appears in the folded `runs`, i.e. a half-applied `yad tidy up`). All are committed by `yad checkpoint` (so a fresh clone
 or another machine sees current evidence; `yad tidy up` folds finished shards into `trust-log.json`).
 Also read the `automation` block of
-`skills/sdlc/config.yaml` (`back_steps`, `trust_threshold`, `locked_steps`, `kill_switch`). For the
+`.sdlc/config.yaml` (`back_steps`), and `.sdlc/automation.json` if present — the kill switch and the
+Shape author steps set to auto (absent = the switch off, every Shape step human). The effective dial of any
+step is `yad dial … --json`, which applies the kill switch and gates for you. For the
 cross-cutting learning layer, also read — if present — the **local-only** `.sdlc/learning-records.json`
 (the per-epic learning ledger, gitignored) and the project-wide `{project-root}/.sdlc/learning-records.json`.
 Do not modify any of them.
@@ -35,45 +38,115 @@ Do not modify any of them.
 ### Step 3 — Report
 Print, in this order:
 
-1. **Header:** render the kind noun from `epic.md` frontmatter `kind` — **Change request** (`change`),
-   **Defect** (`defect`), **Hotfix** (`hotfix`), or **Epic** (`feature`, and the default when `kind` is
-   absent) — followed by `epicId`, then `status` from `epic.md` frontmatter, `currentStep`, and `repos`
+1. **Header:** render the type noun from the `epic.md` frontmatter work-item type. Two names carry it,
+   `kind:` and `type:`; read `kind:` first, then `type:`. **Change request** (`change`),
+   **Defect** (`defect`), **Hotfix** (`hotfix`), **Chore** (`chore`), or **Epic** (`feature`, and the default when neither is
+   present) — followed by `epicId`, then `status` from `epic.md` frontmatter, `currentStep`, and `repos`
    (the touched domains). Example: `Defect EP-checkout-queue-filter — draft @ stories`. A bug is a defect
-   (`kind: defect`) — there is no separate noun. This is presentation only; the artifact is still an epic.
-2. **Steps table** — for every Shape step in `steps[]` order (10, or 12 when the optional analysis step
-   was run): `id`, `type`, `status`, `assistance`, `automation`, `locked`, and `risk_tags`. Mark the
-   `currentStep` with `→`. The gating chain is `[analysis → analysis-review →] epic → epic-review →
-   architecture → architecture-review → ui-design → ui-design-review → stories → stories-review` →
-   **`ready-for-build`** (the bracketed `analysis` prefix is present only when `yad-analysis` seeded it).
+   (type `defect`) — there is no separate noun. This is presentation only; the artifact is still an epic.
+2. **Steps table** — for every Shape step in `steps[]` order, however many there are: `id`, `type`,
+   `status`, the two dials (`driver`/`assistance` and `advance`/`automation` — read whichever the step carries, the OLD name wins), `locked`, and `risk_tags`. Mark the
+   `currentStep` with `→`. **The chain length is a fact about the epic's ROUTE, never a constant** —
+   read `profile` from `state.json`: `classic` is 10 steps, `analysis-first` 12, and the short lanes
+   `chore` 4 and `spike` 6 (E40). On `classic` the gating chain is `[analysis → analysis-review →]
+   epic → epic-review → architecture → architecture-review → ui-design → ui-design-review → stories →
+   stories-review` → **`ready-for-build`** (the bracketed `analysis` prefix is not on `classic`: it is
+   what makes `analysis-first`, the route `yad-analysis` seeds). A short lane runs `epic → epic-review → stories → stories-review` →
+   **`ready-for-build`**, with `analysis` in front on `spike`, and has no architecture, UI-design or
+   test-case rows at all — render what `steps[]` holds and never a step it lacks.
    `test-cases → test-cases-review` is a **parallel, non-blocking track**: it opens when `stories-review`
    passes and runs alongside Build, so when `currentStep` is `ready-for-build` the `test-cases`
    step may still be `in_progress`/`in_review` — show its status, and note "parallel" so it is clear it
    does not gate the build. Always render exactly the steps present in `steps[]`.
-   - **Skipped (N/A) steps:** the optional `ui-design` step may be marked N/A for an epic with no
-     user-facing surface. **Both** the `ui-design` author step **and** its `ui-design-review` gate stay
-     in `steps[]`, each carrying `skipped: true`, `status: "done"`, and a `skipReason`. Render **each**
-     as `<id> — SKIPPED (N/A: <skipReason>)` (with `skippedBy`/`skippedAt` if present) instead of the
-     plain status, so the deliberate skip and its reason are visible and the gate does not appear to
-     vanish. The chain then reads `… architecture-review → ui-design (N/A) → ui-design-review (N/A) →
+   - **Skipped (N/A) steps:** a step the epic's route marks optional — `ui-design`, on the routes that
+     ship — may be marked N/A with `yad skip`. **Both** the author step **and** its `-review` gate stay
+     in `steps[]`, each with `status: "skipped"` and a `record` (`{ reason, by, date }`). A file from
+     before shape 7 spells the same thing `status: "done"` with `skipped: true` and a `skipReason`
+     beside it; read either. Render **each** as `<id> — SKIPPED (N/A: <reason>)` (with who and when if
+     present) instead of the plain status, so the deliberate skip and its reason are visible and the
+     gate does not appear to vanish. The chain then reads `… architecture-review → ui-design (N/A) → ui-design-review (N/A) →
      stories → …`; the review gate never needs approvals.
+   - **Deferred steps:** `yad defer` sets an optional step aside to come back to later. Both the author
+     step and its `-review` gate carry `status: "deferred"` and a `record`. Render each as
+     `<id> — DEFERRED (later: <reason>)`, with who and when if present. A deferred step is still owed:
+     never render it as done or as N/A.
+   - **Debt:** a step carrying `"debt": true` (written by `yad defer … --debt`) is owed back and must be
+     reminded until paid. Add `· DEBT` to its line, and list every debt in a short **Owed** block under
+     the chain with the command that pays it: `yad undefer <epic> <id>` while it is still `deferred` (on a verified Product,
+     say that verb is refused once the ledger is on the default branch), or
+     "being paid back — clears when `<id>-review` passes" once it is back in progress. The flag is
+     removed only when that review passes. `yad doctor` reports the same list as `step:debt`.
+   - **Closed steps:** a `done` step may carry `closed` (E18) — `{ by, date, via, pr?, … }`. Add
+     `(closed <date>, via <via>, PR #<pr>)` to its line when it is there, and nothing when it is not: a
+     step closed before this release has none, and that is not a fault.
+   - **Re-opened steps:** an unfinished step with a later step `done` (not its own `-review` gate) was
+     put back after the chain built past it — a late `yad undefer`. Render it as
+     `<id> — RE-OPENED (beside finished work)`: it does not block the finished steps after it, and
+     `currentStep` stays where it is. `yad next <epic>` prints it as a `re-opened lane`.
+   - **Blocked steps:** a step with `status: "blocked"` **and** a `record` is waiting on someone outside
+     the workflow. Render it as `<id> — BLOCKED (<reason>)`, with who recorded it and when, and say it is
+     cleared with `yad unblock <epic> <id>` once the wait is over — on a verified Product that verb refuses
+     once the ledger is on the default branch, so say so. A `blocked` with no record is the older
+     word for `todo`: render it as not started.
+   - **Owned steps:** `yad assign` (E47) gives an authoring step to one person, in
+     `<epic>/.sdlc/owners/<step>.json` (`{ step, owner, name, assignedBy, date }`). Add `· owner: <name>`
+     to the author step's line **and** its `-review` line while it is live — the author step, or its
+     review, not yet passed (`done`, `skipped`, `deferred`, `satisfied`). A passed step's file is a record:
+     say nothing. It is advice, not a lock, and never changes what the gate needs. A file that is not valid
+     JSON, or whose `step` is not its own file name, is not an owner: name it and point to `yad owners`.
+     `yad owners [<epic>] --json` gives the same list ready-made.
 3. **Active gate** — for the `currentStep` (if it is a `review+approve` step), compute and show:
-   - the reviewer rule in force — **base** (`owner + 1 reviewer`), **escalated** (list the required
-     domains), or **per-repo** for `stories-review` (list each repo needing sign-off),
-   - approvals **recorded so far** (from `approvals.json`), and
-   - approvals **still required** to pass the gate (name the missing domains/repos).
+   - the count in force — **distinct approvers** recorded, against the **base** (1, enforced) and the
+     **full count** from the step's risk tags (advisory),
+   - approvals **recorded so far** (from `approvals.json`, one line per approver), and
+   - approvals **still required** to pass the gate (`1 approval(s)`, or none).
    Do not advance — just state whether the gate would pass right now.
 
    Apply the same predicate `yad-review-gate` uses (restated here so this skill is
    self-contained). From the `approved` records in `approvals.json` for the current step:
-   - `owners` = records with `role == "owner"`; `reviewers` = distinct `role == "reviewer"`;
-     `domainOwners` = `role == "domain-owner"`, grouped by `domain`.
-   - **Base pass:** `|owners| >= 1` AND `|reviewers| >= 1` (the configured `default_reviewers`).
-   - **Escalated pass** (step `risk_tags` ∩ `{contract, auth, payments}` ≠ ∅): base pass AND, for
-     every touched domain, `|domainOwners[domain]| >= 1`. Touched domains = `epic.repos` for
-     `architecture-review`; the union of every story's `repos` for `stories-review`.
-   - Approvals are **stale** (gate fails) if the artifact was edited after the newest `approved`
-     record. For `architecture-review`, also flag staleness if the contract-surface hash no longer
-     matches `.sdlc/contract-lock.json`.
+   - `approvers` = the distinct, non-empty `approver` values of the approvals that are not stale (below).
+     A record that names nobody counts as nobody. When `requireEngagement` is on in the Product config,
+     only approvals with `engagement: verified` count. There are no roles; a `role` or `domain` an older
+     record carries is legacy data, and it counts for nothing.
+   - **Pass (team mode):** `|approvers| >= 1` — the base — plus, with a platform, resolved review threads and a merged
+     review PR/MR. Solo mode waives approvals entirely.
+   - **The full count, reported on every step that is not inherited, skipped or deferred:** `needed = base 1 + risk step` — plus `2` when the
+     step's `risk_tags` carry `contract`, or `1` when they carry `auth`/`payments` (the highest tag,
+     never the sum). The engine **caps** that ask at `active − 1` (floor 1) and prints it (E72) — for
+     example a contract gate asks 3, and with 2 active people the capped ask is 1. The risk step is
+     ADVISORY, capped or not — it never decides whether the gate would pass, because the count
+     of people can read high (a git name and a platform login are two people until proven one). When the
+     people could not be counted, no cap is shown. `yad gate status` prints the sum and the shortfall
+     (`; 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 — 1 short`, or without the `capped to …` part
+     when the cap lowered nothing) — read it from there rather than recomputing it, and say "short N"
+     rather than "blocked" when it is short. A closed team gate whose ask was lowered says
+     `count capped from 3 to 1 (2 active people)`. In solo mode it prints no shortfall.
+   - **A gate that may not pass (E73):** under a team gate that has not passed, `yad gate status` can
+     print a warning line. Relay it as stated, as a warning and never as "blocked": it holds nothing.
+     A line starting `! may not be met:` means there is no approval in the counting window and the one
+     required approval may have nobody but the author to give it; another person's approval settles it.
+     A line starting `! if the risk step were enforced:` is a what-if: the extra approvals that risk
+     tags add could not all be given by the people counted. The gate can still pass today, and the line
+     says so.
+   - **How many people there are to ask (E71), printed once per epic and not per step:** `active people:
+     4 in the last 90 days — caps each gate's count at 3 approvers (one seat is left for the author);
+     reported, only the base is enforced`, with the window's basis on the line under it. It is
+     the count the cap (E72) uses, so never report a step as blocked by it. A source that could not be
+     read prints `active people: NOT COUNTED — <which source> — no cap can be shown, and only the base
+     holds each gate`: report that wording as it stands and NEVER as a number or as "no people" — an
+     unreadable input is not a small team.
+   - **Solo mode may be wrong (E74):** in solo mode, under the `active people:` line, `yad gate status`
+     can print `! solo mode is on, but … so more than one person may work on this Product`. Relay it as
+     a suggestion to run `yad mode team`, never as a fault and never as switched: nothing changes until
+     a person runs it. It never suggests solo mode.
+   - Touched domains (`epic.repos` for a step with a risk tag; the union of every story's `repos` for
+     `stories-review`) only label the review. They add no approvals.
+   - An approval is **stale** (it no longer counts) when the `artifactHash` it recorded no longer
+     matches the artifact's current fingerprint — the content changed after that person approved. For
+     `architecture-review` the fingerprint is the contract surface in `contract.md`. An approval with no
+     `artifactHash` is never stale. `yad gate status` prints the stale count. For `architecture-review`,
+     also flag when the contract-surface hash no longer matches `.sdlc/contract-lock.json`.
 4. **Contract lock** — if `.sdlc/contract-lock.json` exists, show the locked hash and `lockedAt`
    (and, when at/after `architecture-review`, whether the current surface still matches it).
 5. **Stories** — if `stories/` has files, list each story `id` and its `repos` tags.
@@ -81,26 +154,18 @@ Print, in this order:
 7. **Build (per story, per repo)** — if any `.sdlc/build-state/<story-id>.json` exists, then for
    each such story and each of its repos print the Build chain
    `spec → tasks → implement → checks → engineer-review`, marking each step's `status`, its
-   `automation` dial, and `locked`. Mark that repo's `currentStep` with `→`. This shows, at a glance,
+   `advance` dial (or `automation`, whichever the step carries), and `locked`. Mark that repo's `currentStep` with `→`. A repo whose lane is `status: skipped` (a whole lane set aside with `yad skip <epic> <story> --repo <repo>`, E39) prints `skipped (N/A)` and its `record.reason` instead of the chain. This shows, at a glance,
    which Build steps are automated and where a run is waiting. (For the single *next* build sub-step to
    take per story/repo — rather than this full status view — point the user at `yad next <epic>`, which
    reads the same `build-state` files.)
-8. **Automation & trust** — print the system-wide **kill switch** state from `config.yaml`
-   `automation.kill_switch` (when `on`, note that every step is forced to `human_approve`). Then, for
-   each Build step that has entries in the trust ledger — the **union** of the folded
-   `.sdlc/trust-log.json` `runs` plus every loose `.sdlc/trust-log/` shard — print its **trust record**:
-   number of runs, the fraction with `verdict == "approved-unchanged"`, and whether that clears
-   `automation.trust_threshold` (`min_runs`, `min_approved_unchanged`) — i.e. whether the step is
-   **earned** (eligible to be flipped to `machine_advance`) or still **gathering evidence**. Restate
-   the predicate (self-contained): `earned = runs >= min_runs AND unchanged/runs >= min_approved_unchanged`.
-   Never recommend flipping a locked step or a Shape step — those can never be `machine_advance`.
-
-   **Nudge-cost signal (Phase 5 instrumentation).** For each Build step that is **earned but its dial
-   is still `human_approve`** (and it is not locked / not a Shape step), flag it:
-   `⚠ earned but manual — could be machine_advance`. This is the *nudge cost* the Phase 5 trigger
-   watches: automation that is proven safe but still hand-started. It is a read-only observation, not a
-   recommendation to flip — earning the evidence and flipping the dial stay deliberate human acts
-   (`yad-run action: set-dial`). See `docs/phase-5-build-plan.md` §"What to instrument now".
+8. **Automation & run record** — print the **kill switch** from `.sdlc/automation.json` (when on, who
+   turned it on, when and why, and that every step is held at `advance: human`), and the Shape author
+   steps the project set to `auto` — noting that a Shape `auto` is recorded only: nothing drives a Shape
+   step on its own yet. Then, for each Build step that has entries in the trust ledger — the **union** of
+   the folded `.sdlc/trust-log.json` `runs` plus every loose `.sdlc/trust-log/` shard — print its **run
+   record**: number of runs and the fraction with `verdict == "approved-unchanged"`. It is **advice**:
+   there is no threshold and nothing is "earned" (E34). Do not recommend flipping a dial; the team sets
+   dials with `yad dial`. A review gate is never auto.
 
 9. **My skills (the learning layer — local-only).** If `.sdlc/learning-records.json` exists for the epic
    (or the project-wide ledger does), print the **personal skills-log** roll-up from it — read-only. These
@@ -118,9 +183,9 @@ Print, in this order:
 10. **Fleet roll-up (overview only).** When the user asked for an overview, or more than one epic exists
     under `{project-root}/epics/`, print a one-line-per-epic roll-up across the fleet: each epic's
     `currentStep` (Shape gate) and, for stories in Build, a count of Build steps **waiting
-    at a human gate** and of steps flagged **earned-but-manual**, plus a **local skills-log** count (records
+    at a human gate**, plus a **local skills-log** count (records
     in the local-only `learning-records.json`: learned / in-progress). Close with fleet totals (epics at
-    each Shape gate; total earned-but-manual Build steps; total concepts learned locally across the fleet).
+    each Shape gate; total concepts learned locally across the fleet).
     This is the
     *scale-of-read* signal the Phase 5 trigger watches — when this roll-up stops fitting in one glance,
     that is the measured bottleneck. Still strictly read-only; it only scans the per-epic files.