yadflow 3.18.1 → 4.0.0-next.1

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

@@ -1,10 +1,11 @@
-# `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 back-half steps
+## The Build steps
 
 From `config.yaml` `automation.back_steps` plus the human merge gate:
 
@@ -12,68 +13,93 @@ 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 back step (not engineer-review):
-    result = run_step_skill(step)                     # yad-spec | yad-implement | yad-checks
+while step is a Build step (not engineer-review):
+    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.
 
 `checkpoint` = run `yad checkpoint --push` from `{project-root}`. It commits the machine-written
-back-half ledgers (in this loop, the loose `trust-log/` shards this run wrote + `build-state/<story>.json`;
+Build ledgers (in this loop, the loose `trust-log/` shards this run wrote + `build-state/<story>.json`;
 also the `build-log/` shards at engineer-review) — the shard dirs are what checkpoint stages, the same
 way `git gc` folds loose objects later (`yad tidy up` folds finished shards into the folded
 `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 back-half state — <epic>/<story> by @<login> [skip ci]`
-audit-trail commit, on the default branch only,
-staging *only* those files by an explicit allowlist (never a front-half gate file — so `ledger-guard`
+`chore(hub): sync Build state — <epic>/<story> by @<login> [skip ci]`
+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 front states 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
 
@@ -93,7 +119,7 @@ finalizes the entry — a human always has the last word on the trust signal.
 - `contract_touch` — `true` if the diff touched the locked contract surface without an upstream
   re-lock (routes back to the architecture gate).
 
-`derive_verdict(signals)` — the same three-way shape for every back step:
+`derive_verdict(signals)` — the same three-way shape for every Build step:
 ```
 edited = human_edited_diff or human_edited_spec or task_rescoped
 if checks == "fail" or scope_overrun or contract_touch:   verdict = "rejected"
@@ -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 front states (`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,11 +1,11 @@
 ---
 name: yad-ship
-description: 'Build-half 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-half helper)
+# SDLC — Commit + Open PR/MR (Build helper)
 
-**Goal:** Do the two routine build-half hand-actions for ONE atomic task in a single step — **commit by
+**Goal:** Do the two routine Build hand-actions for ONE atomic task in a single step — **commit by
 convention, then open the task PR/MR** — so an implemented diff becomes a reviewable PR/MR without two
 separate invocations. It is a thin wrapper over `yad-commit` and `yad-open-pr`; it holds no logic of
 its own and **never merges**. The engineer review + merge are Step E (`yad-engineer-review`).
@@ -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
-  front-half **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
+- **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 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

@@ -1,17 +1,17 @@
 ---
 name: yad-spec
-description: 'Build-half Step A of the gated SDLC. For one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony ONCE (specify → clarify → plan → analyze → checklist → tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit''s own layout. Drives /speckit.* as harness slash-commands when installed; authors the same files by hand and records speckit: not-installed when absent. References the locked contract — never re-invents the surface. Writes link.md back to the story. Never auto-advances. Use when the user says "spec story <id> in <repo>" or after a story is ready-for-build.'
+description: 'Build Step A of the gated SDLC. For one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony ONCE (specify → clarify → plan → analyze → checklist → tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit''s own layout. Drives /speckit.* as harness slash-commands when installed; authors the same files by hand and records speckit: not-installed when absent. References the locked contract — never re-invents the surface. Writes link.md back to the story. Never auto-advances. Use when the user says "spec story <id> in <repo>" or after a story is ready-for-build.'
 ---
 
-# SDLC — Author Spec (build-half Step A)
+# SDLC — Author Spec (Build Step A)
 
 **Goal:** Turn ONE `ready-for-build` story into a per-repo Spec Kit spec/plan/tasks inside that
 story's code repo. The heavy spec ceremony runs **once per story per repo**; the light
 tasks → implement loop is **Step B** (`yad-implement`). This step **never re-locks the contract** —
 the cross-repo surface is owned upstream by the architecture gate (build plan §A, Cross-cutting
-"Heavy spec once per story, light loop per task"). It does not advance the front-half state machine;
+"Heavy spec once per story, light loop per task"). It does not advance the Shape state machine;
 when driven by the orchestrator (`yad-run`, Phase 4) it records a `spec`/`tasks` trust signal
-(Step 8) — but it never auto-advances a contract change or a front state.
+(Step 8) — but it never auto-advances a contract change or a Shape step.
 
 Spec Kit is driven as **harness slash-commands** (`/speckit.*`), not a subprocess CLI (Phase 0
 Deviation 3). When Spec Kit is not installed, the same files are hand-authored in Spec Kit's exact
@@ -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
 
@@ -43,11 +43,10 @@ is the same graceful-degradation pattern `yad-ui` uses for Impeccable.
 
 ### Step 1 — Resolve the story and check readiness
 Read `{project-root}/epics/<epic>/.sdlc/state.json`. Proceed only when
-`currentStep == "ready-for-build"` (the gating front half — through the **stories** gate — is `done`).
-The **`test-cases` track may still be `in_progress`**: it is parallel and non-blocking, so the build
-half runs alongside it — its status does not affect readiness here. Read the story file
+`currentStep == "ready-for-build"` (the gating Shape — through the **stories** gate — is `done`).
+The **`test-cases` track may still be `in_progress`**: it is parallel and non-blocking, so Build runs alongside it — its status does not affect readiness here. Read the story file
 `epics/<epic>/stories/<story>.md`; confirm `repo` is in its `repos`. If the epic is not ready, STOP
-and point the user at `yad-status`. **Do not mutate front-half state** — `ready-for-build` semantics
+and point the user at `yad-status`. **Do not mutate Shape state** — `ready-for-build` semantics
 stay intact.
 
 ### Step 2 — Resolve the target code repo
@@ -60,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
@@ -84,17 +96,19 @@ 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 (front-half state untouched)
+### Step 7 — Stop (Shape state untouched)
 Report: the spec folder path, the files written, whether Spec Kit was used, the task count from
 `tasks.md`, and that the next action is **Step B — `yad-implement`**. Do **not** edit the epic's
-`state.json`, `approvals.json`, or `contract-lock.json`. Step A is a generation step, not a front gate.
+`state.json`, `approvals.json`, or `contract-lock.json`. Step A is a generation step, not a Shape gate.
 
 ### Step 8 — Record the `spec` trust signal (Phase 4b)
-When this step runs under the orchestrator (`yad-run`), the generated spec is a back-half run that the
-trust log measures (it is the evidence that could later earn the `spec` step a `machine_advance`). The
+When this step runs under the orchestrator (`yad-run`), the generated spec is a Build run that 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
@@ -105,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