yadflow 3.18.1 → 4.0.0-next.1

package/skills/yad-change/SKILL.md

@@ -1,42 +1,46 @@
 ---
 name: yad-change
-description: 'Phase 6 post-lock change management — the change-request/defect INTAKE + TRIAGE step of a feature thread. After the contract locks and code ships, a change must NOT mutate a locked artifact; it becomes a NEW epic threaded to its parent. This skill classifies the change DEPTH (defect-fix / behavioral-no-surface / contract-surface / new-capability), seeds a new EP-<slug> change-epic threaded to its parent (lineage frontmatter kind/parent/thread/inherits/supersedes + a state.json whose inherited steps are pre-marked done and only the changed steps run; a pointer-lock contract-lock.json when architecture is inherited), and records the intake in change.json (escape_stage + root_cause for defects). For hotfixes it records the ship-first exception and opens reconcile-debt.json. Never auto-advances — hands off to the normal authoring skills + the team review gate. Use when the user says "log a change request", "file a defect", "thread a change off EP-…", "open a hotfix", or after a shipped feature needs a fix.'
+description: 'Phase 6 post-lock change management — the change-request/defect INTAKE + TRIAGE step of a feature thread. After the contract locks and code ships, a change must NOT mutate a locked artifact; it becomes a NEW epic threaded to its parent. This skill classifies the change DEPTH (defect-fix / behavioral-no-surface / contract-surface / new-capability), seeds a new EP-<slug> change-epic threaded to its parent (lineage frontmatter kind+type/parent/thread/inherits/supersedes; then `yad epic new --parent` writes the state.json whose inherited steps are carried by reference and only the changed steps run, plus a pointer-lock contract-lock.json when architecture is inherited), and records the intake in change.json (escape_stage + root_cause for defects). For hotfixes it records the ship-first exception and opens reconcile-debt.json. Never auto-advances — hands off to the normal authoring skills + the team review gate. Use when the user says "log a change request", "file a defect", "thread a change off EP-…", "open a hotfix", or after a shipped feature needs a fix.'
 ---
 
 # SDLC — Change/Defect Intake + Triage (Phase 6, the entry of a feature thread)
 
 **Goal:** Turn a post-lock change request, defect, or hotfix into a **new epic threaded to its parent**,
 so the feature's locked artifacts are never mutated — only *superseded*. The change-epic **inherits**
-the front artifacts it does not change (by reference) and **re-authors** only the ones it does, so the
+the Shape artifacts it does not change (by reference) and **re-authors** only the ones it does, so the
 thread head always describes current behaviour and the SDLC stays a trusted source of truth for the next
 change. This skill does the **intake + triage + seeding** and then hands off to the normal authoring
-skills + `yad-review-gate`. It is a **front state**: human-confirmed, **never auto-advances**.
+skills + `yad-review-gate`. It is a **Shape step**: human-confirmed, **never auto-advances**.
 
-This is the answer to "the front/spec docs go stale after the contract locks": a behavioural change can
-no longer ship through the build half against an old story — `epic-open` seals a fully-shipped epic, so
+This is the answer to "the Shape/spec docs go stale after the contract locks": a behavioural change can
+no longer ship through Build against an old story — `epic-open` seals a fully-shipped epic, so
 new behaviour must enter here, and its re-authored stories/test-cases describe the change.
 
 ## Conventions
 
-- `{project-root}` resolves from the product hub.
+- `{project-root}` resolves from the Product.
 - Artifacts live under `{project-root}/epics/EP-<slug>/` — the change-epic gets its OWN `EP-<slug>`
-  (assigned here, never renamed) and its own `stories/EP-<slug>-S0N`, so every existing gate, the bridge,
-  `yad next`, and the build-half traceability keep working unchanged.
+  (assigned here, never renamed) and its own `stories/EP-<slug>-S0N`, so every existing gate, the verified ledger,
+  `yad next`, and the Build traceability keep working unchanged.
 - The thread is **derived** from `parent:` frontmatter (no registry); `thread:` is a cache that must
   equal the computed root (`yad doctor` flags a mismatch). Thread id = the genesis epic's id.
 - Lineage frontmatter, the inherited-step shape, the pointer-lock, `change.json`, and
   `reconcile-debt.json` are all defined in `../yad-epic/references/state-schema.md` (Phase 6 section).
-- Genesis epics authored before Phase 6 must be **migrated once** (`kind: feature`, `thread: <self>` in
+- Genesis epics authored before Phase 6 must be **migrated once** (`kind: feature` + `type: feature`, `thread: <self>` in
   their `epic.md`) before a change threads off them — see `references/triage.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
 
 - `parent` — **required.** The `EP-<slug>` this change evolves (the thread predecessor; usually the
   feature's current tip).
-- `title` — **required.** One line describing the change.
-- `kind` — `change` | `defect` | `hotfix` (default `change`). `feature` is reserved for a genesis epic
-  (use `yad-epic`, not this skill).
+- `title` — **required.** One line describing the change. It is written twice, with the same words:
+  as `title:` in `epic.md` (Step 4) and as `title` in `change.json` (Step 6).
+- `kind` (also accepted as `type`) — the work-item **type**: `change` | `defect` | `hotfix`
+  (default `change`). Both input names mean the same thing, the same way both frontmatter keys do.
+  `feature` and
+  `chore` are the genesis types and are reserved for a work item with no parent (use `yad-epic`,
+  not this skill). Two names carry this value — see Step 4.
 - `origin` — defect/hotfix only: `production` | `staging` | `qa` | `review`.
 - `severity` — defect/hotfix only: `sev1`..`sev4`.
 - `escape_stage` — defect/hotfix only: the SDLC gate that *should* have caught it (`stories`,
@@ -51,12 +55,12 @@ new behaviour must enter here, and its re-authored stories/test-cases describe t
 Confirm `parent` exists (`epics/<parent>/epic.md` + `.sdlc/state.json`). Read its lineage and resolve
 the thread root (`yad thread <parent>` / `resolveThread`). **STOP** if the parent is missing, or its
 lineage is broken (a cycle, or a `thread` cache ≠ the computed root) — fix the parent first. If the
-parent is a **genesis epic not yet migrated** (no `kind:`), migrate it now: add `kind: feature` and
+parent is a **genesis epic not yet migrated** (no type at all), migrate it now: add `kind: feature`, `type: feature` and
 `thread: <its own id>` to its `epic.md` (a one-line, non-gated frontmatter add).
 
 **Missing parent (brownfield) — never silent.** If the requested `parent` does **not exist at all**
 because the feature was built before it had an epic, do NOT dead-end: point the user at **`yad-stub`** to
-mint a stub genesis epic (a minimal `kind: feature` thread anchor) for that feature first, then re-run
+mint a stub genesis epic (a minimal `feature`-type thread anchor) for that feature first, then re-run
 this skill with that stub as the `parent`. A change MUST still thread to a real parent — `yad-stub` just
 creates the smallest real one so the defect can be captured now (the `yad-reconcile` → anchor → change
 discipline).
@@ -67,7 +71,7 @@ in `references/triage.md`).
 
 ### Step 2 — Gather the change + triage the DEPTH (auto-propose, human-confirm)
 With the requester, classify the change into one **depth** (the `yad-backfill` discipline: auto-propose,
-human-confirm). The depth decides which front states are **re-authored** vs **inherited**:
+human-confirm). The depth decides which Shape steps are **re-authored** vs **inherited**:
 
 | depth | re-authors (active) | inherits (pre-done, by reference) | first step |
 |-------|---------------------|-----------------------------------|-----------|
@@ -86,15 +90,37 @@ a word if needed). Create `{project-root}/epics/EP-<slug>/`. Open the `change/EP
 per the shared "Authoring branches" procedure (git/greenfield-safe).
 
 ### Step 4 — Write `epic.md` (the change brief + lineage frontmatter)
-Write a thin brief carrying the lineage frontmatter:
+Write a thin brief carrying the lineage frontmatter.
+
+**Write the work-item type under BOTH names, with the same value.** `kind:` is the original name and
+is still the one every reader uses; `type:` is the name from shape 5 on. Writing `type:` alone is the
+one mistake here that breaks something: `lineage-check.sh` runs inside the code repo and reads
+`kind:`. Finding none it defaults to `feature`, decides the epic is a parent-free genesis, and stops
+requiring the `parent:` a change, defect or hotfix must have. `yad doctor` FAILS on that.
+
+**Carry the parent's `theme:` down.** A theme is the free grouping tag that puts several epics under
+one heading (there is no rung above the Epic; grouping is a label). Read the parent's `epic.md`: if it
+has a `theme:`, copy the spelling **exactly** onto this one, so the change groups with the work it
+changes. If the parent has none, leave `theme:` empty. Never invent a new spelling of an existing
+theme — `yad doctor` reports that, because two spellings group as two themes. Write the tag bare, with
+no `#`: `yad next` and `yad thread` print it as `#checkout-revamp`, but that `#` is decoration on the
+screen and is kept as part of the value if it lands in the file.
+
+**Write `title:` in `epic.md` too**, with the same words as the `title` input. It is the name a list of
+work items shows for this change (E111). Write it on ONE line, as plain words. If it begins with `[` and ends with `]` (such as `[Mobile] Checkout [v2]`), wrap the whole title in double quotes, writing an inner `"` as `\"` — otherwise it is read as a list, which is not a title. Never end it with a `#` comment (the comment becomes part of the title), and never use a YAML block (`>` or `|`): only one line is read. "The same words" means the title as it READS: quotes you add around it in `epic.md` are not part of it, so do not copy them into `change.json`. The full rules are the `title` row of the `epic.md` frontmatter table in `../yad-epic/references/state-schema.md`. Set it now — the
+review gate is bound to a hash of the file, so a title changed after approval drops the approval.
+
 
 ```markdown
 ---
 id: EP-<slug>
+title: <the title input, exactly as it goes into change.json>
 status: draft
 kind: <change|defect|hotfix>
+type: <the same value as kind>
 parent: <EP-parent>
 thread: <EP-genesis>
+theme: <the parent's theme, or leave empty>
 inherits: [<the inherited bases>]
 supersedes: [<parent story ids this replaces, optional>]
 owner:
@@ -110,7 +136,12 @@ root_cause: <tag>
 <!-- what is wrong / what must change, and why now -->
 
 ## Resolved current truth (input)
-<!-- run `yad thread <parent>`: which epic currently owns each artifact this change builds on -->
+<!-- run `yad thread <parent>`: which epic currently owns each artifact this change builds on.
+     Run `yad doctor` FIRST and resolve anything it reports about the parent's ledger. That map is
+     built from each epic's `state.json`, and a ledger the engine cannot parse falls back to "this
+     epic owns everything" — the safe answer for a read-only display, and the wrong one to copy into
+     an `inheritedFrom`, which is a provenance record. An artifact shown as `(none)` has no owner:
+     the parent's route never produced it, so there is nothing to inherit and nothing to point at. -->
 
 ## Re-authored vs inherited
 <!-- the Step 2 split, for the reviewers -->
@@ -119,38 +150,61 @@ root_cause: <tag>
 For a **contract-surface** depth, do NOT inherit `architecture` — it will be re-authored (and re-locked)
 by `yad-architecture` downstream.
 
-### Step 5 — Seed `state.json` (inherited steps pre-done; only the changed steps run)
-Create `.sdlc/state.json` with the **same 10-step chain** as `yad-epic` (so `advanceState`/`nextAction`/
-`gatePredicate`/the bridge run unchanged), but:
-- **Inherited** authoring steps **and their review gates**: `status: "done"`, `"inherited": true`,
-  `"inheritedFrom": "<owning epic from the resolved truth>"`, `"boundHash": "<that artifact's current
-  hash>"`.
-- The **first re-authored** authoring step: `status: "in_progress"`; its review: `status: "in_review"`
-  only once authored — seed it `blocked` and let the authoring skill open it. Set `currentStep` to the
-  first re-authored authoring step.
-- Remaining re-authored steps: `blocked`.
-
-Seed `.sdlc/approvals.json` with one **provenance** record per inherited gate (NOT a forged approval):
-`{ "artifact": "<art>", "step": "<…-review>", "status": "inherited", "from": "<epic>", "boundHash": "<hash>", "date": "<today>" }`.
-Seed `.sdlc/comments.json` = `[]` and create `reviews/`.
-
-Commit the seed on the `change/EP-<slug>` branch. It reaches the hub's default branch through this
+### Step 5 — Seed the ledger with the engine (inherited steps carried; only the changed steps run)
+Run it from the Product, after Step 4 has written `epic.md`:
+
+```bash
+yad epic new EP-<slug> --type <change|defect|hotfix> --parent <EP-parent> --inherits <bases>
+```
+
+`<bases>` is the Step 2 inherit list, comma-separated — for a defect-fix off a `classic` parent,
+`epic,architecture,contract,ui-design`. It must be the same list as `inherits:` in `epic.md`: the command
+reads that header, takes its answer when a flag is left off, and refuses a flag that contradicts it. Leave
+`--profile` off. The child takes the **parent's** route — a 4-step `chore` parent gives a 4-step child —
+and the command refuses a route that differs.
+
+The engine writes everything this step used to spell out by hand (E42):
+
+- `.sdlc/state.json` — the parent's chain and route. Every inherited step **and its review gate** is
+  `satisfied`, with `inherited: true`, `inheritedFrom` (the epic along the parent's line that owns the
+  artifact — not always the parent), `boundHash` (that artifact's current hash) and a `record`. The first
+  re-authored step is `in_progress` and is the `currentStep`; the rest are `todo`.
+- `.sdlc/approvals.json` — one **provenance** record per inherited gate
+  (`{ artifact, step, status: "inherited", from, boundHash, date }`) — never a forged approval.
+- `.sdlc/comments.json` = `[]` and `reviews/`.
+- `.sdlc/contract-lock.json` — the **pointer-lock**, only when `architecture` and `contract` are inherited:
+  the owner's hash copied verbatim, with `inheritedFrom` and `ref`. There is no `contract.md` in the
+  change-epic, so the surface cannot drift, and `contract-check` passes unchanged because the hash is
+  identical. (Field shapes: `references/triage.md`.)
+
+**A refusal means the triage is wrong, and nothing is written.** Fix the inherit list and run it again:
+
+| The command says | Why | What to do |
+|---|---|---|
+| `<owner> skipped <step>` | a skip is a decision, not an artifact — carrying it would claim a review nobody did | leave that base out of `inherits`, then `yad skip` it on this epic if it does not apply here either |
+| `<owner> deferred <step>` | that work is still owed | leave the base out and author it on this epic, so the owed work follows the thread |
+| `<owner> has not finished <step>` | nothing approved exists yet | finish it on the owner, or author it here |
+| `holds no usable contract lock` / `surface no longer matches its lock` | you may skip authoring a contract, never having one | lock (or re-lock) the owner's surface first (`yad-architecture` Step 5) |
+| `stories cannot be inherited` / `test-cases cannot be inherited` | every change writes its own; `stories-review` is what hands an epic to Build | leave them out |
+| `architecture and contract are inherited together` | the architecture step writes `contract.md` | list both, or neither (a contract-surface change) |
+| `route has no <base> step` | a short-lane parent never had it | leave it out |
+| `architecture is owned by <A> but the contract by <B>` | one step writes both, so one epic must own both | in the epic between them, list both in `inherits:`, or neither |
+| `ledger carries <step> from <epic>, but its epic.md does not list <base>` | that epic's two records disagree about where the artifact lives | fix that epic's `inherits:` first |
+| `epic.md says …, --parent says …` · `--inherits says …` · `thread: …` · `has no parent:` / `has no thread:` · `write it as inherits: [a, b]` | the header is what `yad thread` reads, so it must say the same as the flags — in brackets for a list | fix `epic.md` (Step 4), or drop the flag |
+| `already has a contract-lock.json` · `already has an approvals.json with records in it` | a file already there is somebody's record | remove it only if it is left over from a mistake |
+
+Commit the seed on the `change/EP-<slug>` branch. It reaches the Product's default branch through this
 change-epic's **first** review PR/MR — cut the `review/EP-<slug>/<artifact>` branch from `change/…` so
-it carries the seed. In bridge mode `ledger-guard` exempts a new epic's ledger (creation, not mutation,
+it carries the seed. In verified mode `ledger-guard` exempts a new epic's ledger (creation, not mutation,
 #162), so no direct push to a protected default branch is needed; every later change to that ledger is
 CI's. See `../yad-epic/references/state-schema.md`, "Authoring branches".
 
-When `architecture` is **inherited**, materialize the **pointer-lock** `.sdlc/contract-lock.json`:
-`{ "artifact": "contract.md", "hash": "<parent surface hash, verbatim>", "lockedAt": "<today>", "inheritedFrom": "<epic>", "ref": "../../<epic>/.sdlc/contract-lock.json" }`.
-There is no `contract.md` in the change-epic, so the surface cannot drift, and `contract-check` passes
-unchanged because the hash is identical. (Exact recipe + field shapes: `references/triage.md`.)
-
 **Stub parent (brownfield, no locked surface yet).** When the `parent` is a **stub**
 (`stub: backfill-pending` / `verified: false`, minted by `yad-stub`), it has no `architecture.md` /
-`contract.md` / `ui-design.md` to inherit — the surface has not been documented yet. So for the bases the
-stub lacks, mark the inherited steps `"inherited": true, "inheritedFrom": "<stub>", "boundHash": null`
+`contract.md` / `ui-design.md` to inherit — the surface has not been documented yet. `yad epic new`
+sees the anchor and carries those bases as `"inherited": true, "inheritedFrom": "<stub>", "boundHash": null`
 (a `null` boundHash is treated as "nothing locked upstream → no drift" by the gate predicate, so the step
-passes and never blocks), and write **NO** `contract-lock.json` (there is no surface to point at — the
+passes and never blocks), and it writes **NO** `contract-lock.json` (there is no surface to point at — the
 child never touches `specs/*/contracts/**`, so `contract-check` passes trivially). Contract protection on
 this thread begins only after `yad-backfill promote` documents and locks the feature. Record
 `"parentStub": true` in `change.json` so it is auditable that the change threaded off an undocumented
@@ -158,35 +212,56 @@ stub. Prefer the `defect-fix` / `behavioral-no-surface` depth against a stub —
 change against an undocumented feature should wait until the stub is promoted (backfilled + a real
 contract locked).
 
+**Short-lane parent (no architecture step ever existed).** When the parent records `profile: "chore"`
+or `"spike"`, it has no `architecture.md`, no `contract.md`, no `ui-design.md` and no lock — not
+because they are undocumented, as with a stub, but because **its route never had those steps**. The
+engine already handles the ledger: it seeds the parent's short chain and route, writes no lock, and
+refuses `architecture`, `contract` or `ui-design` in `inherits`, because inheriting a step the parent
+never walked would stamp `inherited: true` on a review that never happened anywhere. What is left for
+this skill:
+
+- **Record `"parentShortLane": "<the parent's profile>"` in `change.json`**, the same way a stub parent
+  records `"parentStub": true`, so it is auditable that this thread inherited from a route with no
+  locked surface.
+- **A `contract-surface` depth is not available here.** Its first runnable step is `architecture`,
+  which this chain does not have. If the change really does move the shared cross-repo surface, it is
+  not a thread off this parent — seed a **new epic on `classic`** and note the parent in its lineage.
+  Prefer `defect-fix` or `behavioral-no-surface`, exactly as against a stub.
+
 ### Step 6 — Write `.sdlc/change.json` (intake + triage record)
-Record the intake: `epicId`, `thread`, `parent`, `kind`, `depth`, `intakeBy`, `intakeDate`, `title`,
+Record the intake: `epicId`, `thread`, `parent`, `kind` **and `type`** (the same value under both
+names, as in `epic.md`), `depth`, `intakeBy`, `intakeDate`, `title`,
 `description`, `affectedArtifacts`, `reauthors`, `inherits`, and for a defect/hotfix the `defect` block
 (`origin`, `severity`, `escape_stage`, `root_cause`). This is what `yad-defects` reads to attribute the
 defect to the gate that should have caught it. Add `"parentStub": true` when the parent is an
 un-promoted stub (Step 5) — omit it (or `false`) otherwise.
 
 ### Step 7 — Hotfix only: record the ship-first exception + open reconcile debt
-If `kind: hotfix`, the build half MAY run before these front gates approve (severity demands it). Record
+If the type is `hotfix`, Build MAY run before these Shape gates approve (severity demands it). Record
 `hotfix: { "shipFirst": true }` in `change.json` and **append** to `.sdlc/reconcile-debt.json`:
 `{ "thread": "<…>", "epicId": "<…>", "openedDate": "<today>", "reason": "<why>", "requires": ["artifacts-updated","regression-test"], "status": "open", "paidDate": null, "paidBy": null, "evidence": { "artifacts": [], "regressionTest": "" } }`.
 Tell the user the debt **freezes the next normal change** on this thread (`reconcile-debt` gate) until it
-is paid (front artifacts updated **and** a regression test added, then `status: "paid"`).
+is paid (Shape artifacts updated **and** a regression test added, then `status: "paid"`).
 
 ### Step 8 — Stop; hand off (NO auto-advance)
 Report: the new `EP-<slug>`, its thread + parent, the re-author-vs-inherit split, the seeded
-`currentStep`, and the next skill — `yad-architecture` (contract-surface), else `yad-stories` /
-`yad-test-cases` — followed by `yad-review-gate`. Front states do not auto-advance. Suggest
+`currentStep`, and the next skill — run `yad next EP-<slug>` and name what it names, followed by
+`yad-review-gate`. Do NOT name a skill from memory: which skill runs a step is the project's setting
+(`.sdlc/skills.json`), so a team that bound its own would be sent to one this epic will never use
+again. Unbound, that command names `yad-architecture` for a contract-surface change and `yad-stories`
+/ `yad-test-cases` otherwise, which is what this step used to say. Shape steps do not auto-advance. Suggest
 `yad thread <thread>` to see the evolution and `yad-timeline` / `yad-defects` to render it.
 
 ## Hard rules
 
 - **Never mutate a locked artifact.** A change is a new threaded epic, not an edit to a shipped one.
 - **A change MUST thread to a real parent.** Validate the parent + thread first; STOP on a broken lineage.
-- **Inherit by reference, never copy.** Inherited steps are pre-done with `inherited: true` + a
-  `boundHash`; the pointer-lock carries the parent hash verbatim. The gate never re-reviews them.
+- **Inherit by reference, never copy.** `yad epic new --parent` carries inherited steps as `satisfied` with
+  `inherited: true` + a `boundHash`; the pointer-lock carries the owner's hash verbatim. The gate never
+  re-reviews them, and only work written AND approved upstream can be carried.
 - **Contract-surface ⇒ re-author architecture.** Omitting `architecture` from `inherits` is the ONLY way
-  to change the surface; it re-locks (new hash) and routes through the escalated architecture review —
-  the same mechanism as the build-half `Contract-Change` route, unified.
+  to change the surface; it re-locks (new hash) and routes through the architecture review again (its `contract` tag raises the full approver count, which stays advisory — E72 reports it capped at the active people less one) —
+  the same mechanism as the Build `Contract-Change` route, unified.
 - **A hotfix opens debt, never waives it.** Ship-first is allowed once; the thread freezes for new work
   until the debt is paid.
 - **Never auto-advances.** This skill seeds + records; humans author and approve via the normal gates.

package/skills/yad-change/references/triage.md

@@ -1,4 +1,4 @@
-# Change triage — depth, seeding, the pointer-lock, migration, concurrency
+# Change triage — depth, what the seed writes, the pointer-lock, migration, concurrency
 
 This is the detail behind `yad-change`. The lineage frontmatter + ledger schemas live in
 `../../yad-epic/references/state-schema.md` (Phase 6 section); this file is the *how*.
@@ -21,35 +21,45 @@ enum/identifier in the genesis (or current-truth) `contract.md` `CONTRACT-SURFAC
 contract-surface. If it only changes internal behaviour, validation, or a repo-private field → not the
 surface.
 
-## The seeded `state.json` (worked shape)
+## What `yad epic new --parent` writes (worked shape)
 
-Same 10 steps as `yad-epic`. For a **defect-fix** that inherits epic/architecture/ui-design and
-re-authors stories+test-cases:
+The engine writes this (E42); it is shown so the author and the reviewers know what to expect, and a
+test keeps it equal to what the engine really writes. The child's chain is always the PARENT's chain and
+`profile`: 10 steps under a `classic` parent, 4 under a `chore` one (no `architecture`/`ui-design` rows to
+inherit and no pointer-lock — see "Short-lane parent" in `../SKILL.md` Step 5).
+
+For a **defect-fix** off a `classic` parent, inheriting epic/architecture/contract/ui-design and re-authoring
+stories+test-cases:
 
 ```json
 {
-  "schemaVersion": 1,
-  "epicId": "EP-<slug>", "createdAt": "<today>", "currentStep": "stories",
+  "schemaVersion": 10,
+  "epicId": "EP-<slug>", "createdAt": "<today>", "type": "<the same value as epic.md kind/type>",
+  "profile": "classic",
+  "currentStep": "stories",
   "steps": [
-    { "id": "epic",                "type": "author",         "artifact": "epic.md",         "assistance": "review", "automation": "human_approve", "locked": true, "status": "done", "inherited": true, "inheritedFrom": "EP-<genesis>", "boundHash": "sha256:…", "risk_tags": [] },
-    { "id": "epic-review",         "type": "review+approve", "artifact": "epic.md",         "assistance": "review", "automation": "human_approve", "locked": true, "status": "done", "inherited": true, "inheritedFrom": "EP-<genesis>", "boundHash": "sha256:…", "risk_tags": [] },
-    { "id": "architecture",        "type": "author",         "artifact": "architecture.md", "assistance": "review", "automation": "human_approve", "locked": true, "status": "done", "inherited": true, "inheritedFrom": "EP-<genesis>", "boundHash": "sha256:…", "risk_tags": [] },
-    { "id": "architecture-review", "type": "review+approve", "artifact": "architecture.md", "assistance": "review", "automation": "human_approve", "locked": true, "status": "done", "inherited": true, "inheritedFrom": "EP-<genesis>", "boundHash": "sha256:…", "risk_tags": ["contract"] },
-    { "id": "ui-design",           "type": "author",         "artifact": "ui-design.md",    "assistance": "review", "automation": "human_approve", "locked": true, "status": "done", "inherited": true, "inheritedFrom": "EP-<genesis>", "boundHash": "sha256:…", "risk_tags": [] },
-    { "id": "ui-design-review",    "type": "review+approve", "artifact": "ui-design.md",    "assistance": "review", "automation": "human_approve", "locked": true, "status": "done", "inherited": true, "inheritedFrom": "EP-<genesis>", "boundHash": "sha256:…", "risk_tags": [] },
-    { "id": "stories",             "type": "author",         "artifact": "stories/",        "assistance": "review", "automation": "human_approve", "locked": true, "status": "in_progress", "risk_tags": [] },
-    { "id": "stories-review",      "type": "review+approve", "artifact": "stories/",        "assistance": "review", "automation": "human_approve", "locked": true, "status": "blocked",     "risk_tags": [] },
-    { "id": "test-cases",          "type": "author",         "artifact": "test-cases.md",   "assistance": "review", "automation": "human_approve", "locked": true, "status": "blocked",     "risk_tags": [] },
-    { "id": "test-cases-review",   "type": "review+approve", "artifact": "test-cases.md",   "assistance": "review", "automation": "human_approve", "locked": true, "status": "blocked",     "risk_tags": [] }
+    { "id": "epic",                "type": "author",         "artifact": "epic.md",         "assistance": "review", "driver": "pair", "automation": "human_approve", "advance": "human", "locked": true, "status": "satisfied", "inherited": true, "inheritedFrom": "EP-<genesis>", "boundHash": "sha256:…", "record": { "reason": "carried by reference from EP-<genesis>", "by": null, "date": "<today>", "link": "EP-<genesis>" }, "risk_tags": [] },
+    { "id": "epic-review",         "type": "review+approve", "artifact": "epic.md",         "assistance": "review", "driver": "pair", "automation": "human_approve", "advance": "human", "locked": true, "status": "satisfied", "inherited": true, "inheritedFrom": "EP-<genesis>", "boundHash": "sha256:…", "record": { "reason": "carried by reference from EP-<genesis>", "by": null, "date": "<today>", "link": "EP-<genesis>" }, "risk_tags": [] },
+    { "id": "architecture",        "type": "author",         "artifact": "architecture.md", "assistance": "review", "driver": "pair", "automation": "human_approve", "advance": "human", "locked": true, "status": "satisfied", "inherited": true, "inheritedFrom": "EP-<genesis>", "boundHash": "sha256:…", "record": { "reason": "carried by reference from EP-<genesis>", "by": null, "date": "<today>", "link": "EP-<genesis>" }, "risk_tags": [] },
+    { "id": "architecture-review", "type": "review+approve", "artifact": "architecture.md", "assistance": "review", "driver": "pair", "automation": "human_approve", "advance": "human", "locked": true, "status": "satisfied", "inherited": true, "inheritedFrom": "EP-<genesis>", "boundHash": "sha256:…", "record": { "reason": "carried by reference from EP-<genesis>", "by": null, "date": "<today>", "link": "EP-<genesis>" }, "risk_tags": ["contract"] },
+    { "id": "ui-design",           "type": "author",         "artifact": "ui-design.md",    "assistance": "review", "driver": "pair", "automation": "human_approve", "advance": "human", "locked": true, "status": "satisfied", "inherited": true, "inheritedFrom": "EP-<genesis>", "boundHash": "sha256:…", "record": { "reason": "carried by reference from EP-<genesis>", "by": null, "date": "<today>", "link": "EP-<genesis>" }, "risk_tags": [] },
+    { "id": "ui-design-review",    "type": "review+approve", "artifact": "ui-design.md",    "assistance": "review", "driver": "pair", "automation": "human_approve", "advance": "human", "locked": true, "status": "satisfied", "inherited": true, "inheritedFrom": "EP-<genesis>", "boundHash": "sha256:…", "record": { "reason": "carried by reference from EP-<genesis>", "by": null, "date": "<today>", "link": "EP-<genesis>" }, "risk_tags": [] },
+    { "id": "stories",             "type": "author",         "artifact": "stories/",        "assistance": "review", "driver": "pair", "automation": "human_approve", "advance": "human", "locked": true, "status": "in_progress", "risk_tags": [] },
+    { "id": "stories-review",      "type": "review+approve", "artifact": "stories/",        "assistance": "review", "driver": "pair", "automation": "human_approve", "advance": "human", "locked": true, "status": "todo",        "risk_tags": [] },
+    { "id": "test-cases",          "type": "author",         "artifact": "test-cases.md",   "assistance": "review", "driver": "pair", "automation": "human_approve", "advance": "human", "locked": true, "status": "todo",        "risk_tags": [] },
+    { "id": "test-cases-review",   "type": "review+approve", "artifact": "test-cases.md",   "assistance": "review", "driver": "pair", "automation": "human_approve", "advance": "human", "locked": true, "status": "todo",        "risk_tags": [] }
   ]
 }
 ```
 
-`boundHash` is the inherited artifact's **current** hash from the owning epic — the same hashes
+`inheritedFrom` is the epic that owns the artifact along the parent's line — the latest one that
+re-authored it, which is not always the parent. `boundHash` is the inherited artifact's **current** hash from the owning epic — the same hashes
 `cli/epic-state.mjs` computes: `contractSurfaceHash` for `architecture`, `storiesHash` for `stories`,
-the file bytes otherwise. The gate predicate treats an `inherited` step as satisfied (never re-reviewed)
-as long as `boundHash` matches the thread's current hash for that artifact — which it always does,
-because the artifact lives in the parent and cannot be edited from the child.
+the file otherwise — every file without its frontmatter `status:` line (`reviewedSha`, shape 9). A
+`boundHash` computed over the whole file by an older release is still accepted. The gate predicate treats an `inherited` step as satisfied (never re-reviewed)
+as long as `boundHash` matches the current hash of that artifact in the owning epic (`inheritedFrom`) —
+which holds unless the owner's copy changes. Compare against the OWNER's copy, never the child's: a
+change-epic writes its own `epic.md` (the change brief), which is not the epic it carries.
 
 `approvals.json` provenance record per inherited gate (append-only, NOT an approval that the predicate
 counts — it just documents where the sign-off lives):
@@ -61,23 +71,23 @@ counts — it just documents where the sign-off lives):
 
 ## The pointer-lock (when `architecture` is inherited)
 
-Write `.sdlc/contract-lock.json` with the parent's hash **verbatim**:
+`yad epic new` writes `.sdlc/contract-lock.json` with the owning epic's hash **verbatim**:
 
 ```json
 { "artifact": "contract.md", "hash": "sha256:<parent hash, copied byte-for-byte>", "lockedAt": "<today>",
   "inheritedFrom": "EP-<genesis>", "ref": "../../EP-<genesis>/.sdlc/contract-lock.json" }
 ```
 
-Get the parent hash from the owning epic's `.sdlc/contract-lock.json` `hash` field (do NOT recompute — copy
-it). `contract-check.sh` reads only `hash`, so a build-half story in the change-epic pins this identical
+The engine copies the `hash` field of the owning epic's `.sdlc/contract-lock.json` (it never recomputes
+it), and refuses when that lock is missing, malformed, or no longer matches the owner's `contract.md`
+surface — a pointer to a stale lock would pass the drift down the thread. `contract-check.sh` reads only `hash`, so a Build story in the change-epic pins this identical
 hash via its `link.md` and the gate passes unchanged. There is no `contract.md` in the change-epic, so
 the surface physically cannot drift.
 
 **To CHANGE the surface instead:** do not inherit `architecture`. Then `yad-architecture` re-authors
 `contract.md` in the change-epic between fresh `CONTRACT-SURFACE` markers, computes a **new** hash, and
 writes a real (non-pointer) `contract-lock.json`. `architecture-review` carries `risk_tags: ["contract"]`
-→ the escalated domain-owner review. This is the same re-lock-invalidates-approvals behaviour the front
-half already has, relocated from "edit the locked file" to "author a contract-surface change-epic".
+→ the contract-risk review (full approver count 3, capped at the active people less one and reported, E72; only the base 1 is enforced). This is the same re-lock-invalidates-approvals behaviour Shape already has, relocated from "edit the locked file" to "author a contract-surface change-epic".
 
 ## Genesis migration (one-time, per feature)
 
@@ -86,17 +96,21 @@ to its `epic.md` frontmatter:
 
 ```yaml
 kind: feature
+type: feature
 thread: <its own id>
 ```
 
+Both names, same value: `kind:` is the one every reader still uses, `type:` is the name from shape 5 on.
+
 This is a non-gated, idempotent frontmatter add (no `parent`, since a genesis epic is the thread root).
-`epicLineage` already defaults an absent `kind` to `feature`, so an un-migrated genesis still behaves as
+`workItemType` already defaults an absent type to `feature`, so an un-migrated genesis still behaves as
 a root — migration just makes the `thread` cache explicit and lets `yad thread` group it.
 
 ## Concurrent changes on one feature (forward-only resolution)
 
-Two change-epics threaded off the same tip that re-author the same artifact are a **fork**: the resolver
-sees two non-inherited owners of one base at the same depth, and `yad doctor` / `yad reconcile` warn.
+Two change-epics threaded off the same tip that re-author the same artifact are a **fork**. Nothing
+detects it today: the current-truth resolver silently picks one owner (the sibling whose epic id sorts last),
+and neither `yad doctor` nor `yad reconcile` warns. Look for two siblings in `yad thread` before threading.
 Resolution is forward-only — the second to merge **re-parents** onto the first (set `parent` to the new
 tip) and re-inherits; no artifact is mutated, no lock conflicts. The contract is the natural
 serialization point: only one re-lock can win, and `contract-check`'s pinned-hash fidelity check fails