yadflow 2.17.0 → 2.18.0

package/skills/sdlc/module-help.csv

@@ -30,3 +30,7 @@ SDLC Workflow,yad-connect-docs,Connect Docs Target,DX,"Setup/maintenance: connec
 SDLC Workflow,yad-docs,Author Docs Site,DS,"Generate the per-epic interactive documentation SPA (animated flow canvas + role-based stakeholder doc pages) from the epic's approved artifacts (epic, architecture, locked contract, ui-design, stories, code-context, test-cases), themed by the connected design system, into epics/EP-<slug>/docs-site/. Copies the vendored React/Vite/Tailwind shell verbatim and generates src/data/*.ts deterministically; drives the yad docs build/deploy CLI to publish to Pages (or build-only). An OUTPUT ENRICHMENT — never a gate; never mutates state.json, approvals, or the contract lock.",,{epic: EP-<slug>} {action: generate|refresh|deploy} {login_gate: true|false},,yad-review-gate,,false,epics/EP-<slug>/docs-site/,docs-site/ docs-build.json
 SDLC Workflow,yad-docs-overview,Docs Overview Site,DO,"Generate the project SDLC-overview interactive site (docs/sdlc-site/) — every stage from setup to ship modeled as flow paths, system components, and stakeholder roles — reusing the same vendored shell, themed with yadflow's brand palette. Reads config.yaml + module-help.csv + the overview diagram as the pipeline source. Folds the hand-maintained docs/index.html report into the site as report.html (linked from the nav). Not a gate — a project-level enrichment that regenerates whenever the skill set / pipeline changes.",,{action: generate|deploy},,,,false,docs/sdlc-site/,sdlc-site/ .docs-build.json
 SDLC Workflow,yad-docs-sync,Docs Sync,DY,"Maintenance/CI: keep the generated doc sites fresh. Detect staleness (a content hash of the approved artifacts + the connected repos' HEAD shas + the doc-shell version vs each site's build manifest), report which sites drifted and why, regenerate + redeploy the stale ones, and wire a CI job that rebuilds on push (carrying [skip ci] + a concurrency group to prevent deploy loops). Generalizes the rule that feature work must hand-update docs/index.html + diagrams + skill counts. Refresh is always a human/CI decision; never a gate.",,{action: check|refresh|wire} {epic: EP-<slug>},,,,false,epics/EP-<slug>/.sdlc/,docs-build.json yad-docs.yml
+SDLC Workflow,yad-change,Change/Defect Intake,CH,"Phase 6 post-lock change management: the INTAKE + TRIAGE step of a feature thread. 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 + yad-review-gate.",,{parent: EP-<slug>} {title: one-line} {kind: change|defect|hotfix} {origin: production|staging|qa|review} {severity: sev1..sev4} {description: text} {affected: artifacts},1-front,,yad-review-gate,false,epics/EP-<slug>/,epic.md state.json change.json reconcile-debt.json contract-lock.json
+SDLC Workflow,yad-timeline,Feature Timeline,TL,"Render a feature THREAD (its linked epics, genesis->changes->defects) as an evolution view (the vendored React/Vite/Tailwind shell HTML + a TIMELINE.md summary) AND resolve the inheritance chain into the authoritative current artifact set (thread-resolved.md: the winning source per artifact + the resolved contract-lock hash) — the composed source-of-truth AI/humans read for the next change. Reads frontmatter lineage + each change.json + build-log.json. An OUTPUT ENRICHMENT — never a gate; never mutates state.",,{thread: EP-<genesis>} {action: generate|deploy},,,,false,epics/EP-<genesis>/,timeline-site/ thread-resolved.md TIMELINE.md
+SDLC Workflow,yad-defects,Quality-Gap Report,DF,"Generate a per-epic AND per-thread defect/bug report (same vendored shell + DEFECTS.md). Walks the thread for every kind:defect change-epic + each change.json defect block + shipped regressions in build-log.json, aggregates by escape_stage (the SDLC gate that should have caught it) and root_cause, and visualizes WHERE quality gaps systematically come from (e.g. % of thread defects that escaped at the test-cases gate) so the team can harden the originating stage. An OUTPUT ENRICHMENT — never a gate; never mutates state.",,{epic: EP-<slug> | thread: EP-<genesis>} {action: generate|deploy},,,,false,epics/EP-<slug>/,defects-site/ DEFECTS.md
+SDLC Workflow,yad-reconcile,Change Reconciler,RE,"Maintenance/CI (mirrors yad-docs-sync — never a gate): detect post-lock DRIFT/ORPHANS — shipped code or a repo HEAD advance (the repos.json syncedHead-vs-current-HEAD rule) with NO owning change-epic in any thread — plus open hotfix reconcile debt, and report which thread drifted and why. refresh scaffolds a reconcile change-epic stub (hands to yad-change) — never silent; wire commits advisory CI ([skip ci] + concurrency, like yad-docs-sync). The actual merge BLOCK is the lineage-check / reconcile-debt gates; this only discovers.",,{action: check|refresh|wire} {thread: EP-<genesis>},,,,false,epics/EP-<genesis>/.sdlc/,(report) reconcile-debt.json yad-reconcile.yml

package/skills/yad-change/SKILL.md

@@ -0,0 +1,174 @@
+---
+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.'
+---
+
+# 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
+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**.
+
+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
+new behaviour must enter here, and its re-authored stories/test-cases describe the change.
+
+## Conventions
+
+- `{project-root}` resolves from the product hub.
+- 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.
+- 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
+  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`.
+
+## 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).
+- `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`,
+  `test-cases`, `architecture`, …). Feeds the `yad-defects` quality report.
+- `root_cause` — defect/hotfix only: a short tag (e.g. `missing-negative-test`).
+- `description` — free text: what is wrong / what must change.
+- `affected` — the artifacts the requester believes change (the triage confirms/adjusts this).
+
+## On Activation
+
+### Step 1 — Resolve the parent + thread (validate; STOP on a broken lineage)
+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
+`thread: <its own id>` to its `epic.md` (a one-line, non-gated frontmatter add).
+
+The new epic's `thread` = the parent's thread (the genesis id). Its `parent` = the given `parent` (the
+immediate predecessor — usually the current tip; if the parent is not the tip, see "concurrent changes"
+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**:
+
+| depth | re-authors (active) | inherits (pre-done, by reference) | first step |
+|-------|---------------------|-----------------------------------|-----------|
+| **defect-fix** — the spec was right, code/coverage was wrong | `stories` (a regression story), `test-cases` (the missing case) | epic, architecture, contract, ui-design | `stories` |
+| **behavioral-no-surface** — behaviour changes, contract surface unchanged | epic (delta), `stories`, `test-cases` (+ ui-design if visible) | architecture, **contract (no re-lock)** | `stories` (or `ui-design`) |
+| **contract-surface** — the shared cross-repo surface changes | **architecture + contract (RE-LOCK)**, `stories`, `test-cases` (+ epic/ui as needed) | whatever is genuinely untouched | `architecture` |
+| **new-capability** — not a change to this feature, a new one | full chain (`epic`…`test-cases`) | lineage/context only | `epic` |
+
+Print the chosen depth and the **re-author vs inherit** split; **get explicit confirmation** before
+seeding. A `new-capability` is usually a *new genesis epic* (`yad-epic`) — only thread it when it truly
+extends this feature's evolution.
+
+### Step 3 — Derive the change-epic id + open the authoring branch
+Derive a distinct `EP-<slug>` from the title (2–4 lowercase words; check `epics/` for collisions, append
+a word if needed). Create `{project-root}/epics/EP-<slug>/`. Open the `change/EP-<slug>` authoring branch
+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:
+
+```markdown
+---
+id: EP-<slug>
+status: draft
+kind: <change|defect|hotfix>
+parent: <EP-parent>
+thread: <EP-genesis>
+inherits: [<the inherited bases>]
+supersedes: [<parent story ids this replaces, optional>]
+owner:
+repos: [<inherit from the resolved current truth / parent>]
+# defect/hotfix only:
+origin: <…>
+severity: <sevN>
+escape_stage: <stage>
+root_cause: <tag>
+---
+
+## Change
+<!-- 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 -->
+
+## Re-authored vs inherited
+<!-- the Step 2 split, for the reviewers -->
+```
+
+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/`.
+
+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`.)
+
+### Step 6 — Write `.sdlc/change.json` (intake + triage record)
+Record the intake: `epicId`, `thread`, `parent`, `kind`, `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.
+
+### 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
+`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"`).
+
+### 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
+`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.
+- **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.
+- **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.
+
+## Reference
+- Depth triage details, the exact seeding shape, the pointer-lock recipe, genesis migration, and the
+  concurrent-change (re-parent) rule: `references/triage.md`.
+- The lineage frontmatter + ledger schemas: `../yad-epic/references/state-schema.md` (Phase 6).
+- The authoring skills this hands off to: `../yad-architecture/`, `../yad-stories/`, `../yad-test-cases/`,
+  and the gate `../yad-review-gate/`.
+- The thread view + reports: `yad thread`, `../yad-timeline/`, `../yad-defects/`.
+- The gates that enforce it: `../yad-checks/` (lineage-check, epic-open, reconcile-debt).

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

@@ -0,0 +1,102 @@
+# Change triage — depth, seeding, 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*.
+
+## Depth → re-author vs inherit (the triage table, expanded)
+
+The depth is the single decision that drives everything else. Pick the SHALLOWEST depth that honestly
+describes the change — a deeper depth re-authors (and re-reviews) more than necessary.
+
+| depth | when | re-authors | inherits | first runnable step |
+|-------|------|-----------|----------|---------------------|
+| **defect-fix** | the design was right; the code or its coverage was wrong. No behaviour the spec promised changes. | `stories` (a regression story stating the correct behaviour), `test-cases` (the case that would have caught it) | epic, architecture, contract, ui-design | `stories` |
+| **behavioral-no-surface** | observable behaviour changes (validation, an edge case, a non-surface field), but the **cross-repo contract surface** does not | `epic` (a delta), `stories`, `test-cases`; `ui-design` too if the change is visible | architecture, **contract (inherited, NO re-lock)** | `stories` (or `ui-design`) |
+| **contract-surface** | the shared API/event/data-model surface itself changes | **architecture + contract (re-author + RE-LOCK)**, `stories`, `test-cases`; `epic`/`ui-design` as needed | only what is genuinely untouched | `architecture` |
+| **new-capability** | this is not a change to the feature — it is a new feature | the full chain | lineage/context only | `epic` |
+
+**Heuristics for the surface question** (defect-fix / behavioral-no-surface vs contract-surface): does
+the change alter an endpoint's path/method, a request/response field, an event name/payload, or a shared
+enum/identifier in the genesis (or current-truth) `contract.md` `CONTRACT-SURFACE` block? If yes →
+contract-surface. If it only changes internal behaviour, validation, or a repo-private field → not the
+surface.
+
+## The seeded `state.json` (worked shape)
+
+Same 10 steps as `yad-epic`. For a **defect-fix** that inherits epic/architecture/ui-design and
+re-authors stories+test-cases:
+
+```json
+{
+  "epicId": "EP-<slug>", "createdAt": "<today>", "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": [] }
+  ]
+}
+```
+
+`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.
+
+`approvals.json` provenance record per inherited gate (append-only, NOT an approval that the predicate
+counts — it just documents where the sign-off lives):
+
+```json
+{ "artifact": "architecture.md", "step": "architecture-review", "status": "inherited",
+  "from": "EP-<genesis>", "boundHash": "sha256:…", "date": "<today>" }
+```
+
+## The pointer-lock (when `architecture` is inherited)
+
+Write `.sdlc/contract-lock.json` with the parent'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
+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".
+
+## Genesis migration (one-time, per feature)
+
+A feature epic authored before Phase 6 has no lineage frontmatter. Before a change threads off it, add
+to its `epic.md` frontmatter:
+
+```yaml
+kind: feature
+thread: <its own id>
+```
+
+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
+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.
+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
+the loser until it re-specs against the new tip.

package/skills/yad-checks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-checks
-description: 'Build-half Step C of the gated SDLC — the production-safety check gates. Wire and run the CI gates on a code repo: spec-link (every change links a real story/spec via its Task trailer), contract-check (a diff that changes the contract surface without a Contract-Change + an updated, re-locked contract FAILS and routes back to the architecture gate), build/test/lint, and verified-commits (no unverified commits from unverified users — platform-Verified signature + roster-allowlisted author, on the hub and every repo). The gates are CI-agnostic bash, invoked by GitHub Actions and GitLab CI. Use when the user says "wire the check gates", "run the gates", "require signed commits", or "set up CI checks" for a repo.'
+description: 'Build-half Step C of the gated SDLC — the production-safety check gates. Wire and run the CI gates on a code repo: spec-link (every change links a real story/spec via its Task trailer), contract-check (a diff that changes the contract surface without a Contract-Change + an updated, re-locked contract FAILS and routes back to the architecture gate), build/test/lint, verified-commits (no unverified commits from unverified users — platform-Verified signature + roster-allowlisted author, on the hub and every repo), and the Phase 6 feature-thread gates lineage-check / epic-open / reconcile-debt (a change links a real threaded epic; a sealed epic refuses new behaviour; a thread with open hotfix debt is frozen until paid). The gates are CI-agnostic bash, invoked by GitHub Actions and GitLab CI. Use when the user says "wire the check gates", "run the gates", "require signed commits", or "set up CI checks" for a repo.'
 ---
 
 # SDLC — Check Gates (build-half Step C)
@@ -24,6 +24,18 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
    **product hub and every connected repo**; runs on PRs/MRs only, so the gate-sync bot's direct
    ledger pushes are unaffected (never replace it with a default-branch push rule — see
    `references/check-gates.md` §4).
+5. **lineage-check** (Phase 6) — the change's owning epic is a valid node in a **feature thread**: a
+   `change`/`defect`/`hotfix` epic must thread to a real `parent`. Builds on spec-link's story→epic
+   resolution; the every-code-change-has-a-threaded-epic enforcement.
+6. **epic-open** (Phase 6, the staleness preventer) — an epic is **sealed** once every story is
+   `shipped`; a commit targeting a sealed epic **FAILS**, forcing new behaviour into a new threaded
+   change-epic (so the front artifacts can never go stale).
+7. **reconcile-debt** (Phase 6) — a hotfix that shipped first opens debt; the **next** change on its
+   thread **FAILS** until the debt is paid (artifacts updated + a regression test added).
+
+The Phase 6 gates read the owning epic in the **product hub** via `specs/<story>/link.md`'s
+`product-repo` path (like contract-check), and degrade to a PASS-with-note when the hub is not reachable
+from CI. See `references/check-gates.md` and `skills/yad-change`.
 
 The gates are **CI-agnostic bash** in `checks/`; thin pipeline configs invoke them on GitHub Actions
 and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the skill or let CI run them;

package/skills/yad-checks/references/check-gates.md

@@ -11,6 +11,9 @@ repo uses. Each reads conventions established by earlier steps — it invents no
 | spec-link | the `Task: <story>-<task>` commit trailer; `specs/<story>/link.md` | `yad-implement` (trailer), `yad-spec` (link.md) |
 | contract-check | changed files under `specs/<story>/contracts/`; the `Contract-Change: yes` trailer; `link.md`'s pinned `contract-lock`; the product repo's `contract-lock.json` | `yad-architecture` (lock), `yad-spec` (slice + link), `yad-implement` (trailer) |
 | build/test/lint | the repo's `npm run lint` / `npm run build` / `npm test` | the repo |
+| lineage-check | the `Task:` trailer → `link.md` (`epic` + `product-repo`); the owning epic's `kind`/`parent` frontmatter in the hub | `yad-spec` (link.md), `yad-change` (lineage frontmatter) |
+| epic-open | the `Task:` trailer → `link.md` → the hub epic's `stories/*.md` `status:` (sealed = all `shipped`) | `yad-engineer-review` (story status), `yad-change` (the change-epic) |
+| reconcile-debt | the `Task:` trailer → `link.md` → the hub epic's `thread`; every thread epic's `reconcile-debt.json` | `yad-change` (opens hotfix debt) |
 | verified-commits | each commit's platform signature-verification status; the author email vs `.sdlc/verified-authors` | hub roster `email` fields (`yad check --fix` generates the allowlist) |
 | commit-message | each non-merge commit's subject + trailer block | `yad-commit` / `CONTRIBUTING.md` (`config.yaml build.commit_subject_style`) |
 | pr-title | the PR/MR title (from the CI event payload) | `yad-pr-template` (`config.yaml build.pr_title_style`) |
@@ -149,6 +152,28 @@ catches a free-form description that bypassed it:
     (`epics/**`, detected from the CI-supplied `--changed <file>` list) **FAILS** — artifact changes
     must go through a `review/EP-*` PR.
 
+## 8. Phase 6 — feature-thread gates (`lineage-check.sh`, `epic-open.sh`, `reconcile-debt-check.sh`)
+
+After the contract locks and code ships, a change must not mutate a locked artifact — it becomes a new
+epic threaded to its parent (`config.yaml` `change:`). These three gates keep that discipline. All three
+resolve the owning epic the same way: `Task:` trailer → `specs/<story>/link.md` (`epic` + `product-repo`)
+→ the hub epic. All **fail closed** on an unresolvable base; all are **per commit**; `ci|chore|build|test`
+commits are exempt. When the **product hub is not reachable** from CI (the usual case for a code-repo
+PR), each degrades to a **PASS-with-note** — the hub-side check (`yad doctor` / `yad reconcile`) covers
+that path, and spec-link still proves the story link.
+
+- **lineage-check** — reads the hub epic's `kind`/`parent` frontmatter. A `feature` (genesis) epic
+  passes. A `change`/`defect`/`hotfix` epic **FAILS** unless it declares a `parent:` that resolves to a
+  real `epics/<parent>/` in the hub (no orphan threads). This is the "every code change has an owning
+  epic in a thread" enforcement, layered on spec-link.
+- **epic-open** — an epic is **sealed** iff it has ≥1 story and **every** `stories/*.md` `status:` is
+  `shipped`. A commit whose owning epic is sealed **FAILS**: new behaviour cannot mutate a shipped epic;
+  it must land in a new threaded change-epic. This is what stops the front artifacts from going stale.
+- **reconcile-debt** — resolves the epic's `thread` (its `thread:` frontmatter, else the epic id) and
+  scans every thread epic's `reconcile-debt.json`. An **open** entry the current epic does not own
+  **FAILS** the change (the thread is frozen until the hotfix debt is paid: artifacts updated + a
+  regression test added, then `status: paid`). Thread-scoped — only the affected thread freezes.
+
 ## CI wiring (both platforms)
 
 The gates run identically under either CI; the config just invokes the scripts with the PR/MR base.
@@ -158,6 +183,8 @@ The gates run identically under either CI; the config just invokes the scripts w
   (verified-commits also gets a read-only `GH_TOKEN` for the Verified-badge lookup). The pattern jobs
   read the title/body from the event payload: `pr-title` takes `${{ github.event.pull_request.title }}`
   and `pr-template` writes `${{ github.event.pull_request.body }}` to a temp file. All `--profile code`.
+  The Phase 6 thread gates (`lineage-check`, `epic-open`, `reconcile-debt`) run as their own jobs with
+  `fetch-depth: 0`, the same `origin/${{ github.base_ref }}` base.
 - **GitLab CI** — `templates/gitlab/yad-checks.gitlab-ci.yml` → `.gitlab/ci/yad-checks.yml`, pulled in
   by the root `.gitlab-ci.yml`'s `include:`. The jobs run on `merge_request_event` with `GIT_DEPTH: 0`,
   passing `origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME`; the pattern jobs read `$CI_MERGE_REQUEST_TITLE`

package/skills/yad-checks/templates/checks/epic-open.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# epic-open gate (Phase 6 — the staleness preventer). An epic is SEALED once every one of its stories
+# is `shipped`. A SEALED epic's artifacts are the final, approved description of shipped behaviour — so
+# new behaviour must NOT be added to it; it belongs in a NEW threaded change-epic whose re-authored
+# stories/test-cases describe the change. This gate FAILs any non-maintenance commit whose owning epic
+# is sealed, forcing the front half to stay current (staleness becomes unshippable).
+#
+# The owning epic lives in the PRODUCT repo (via specs/<story>/link.md `product-repo`). When it is not
+# reachable from CI, the seal cannot be read, so the commit PASSes with a note (degraded, fail-open here
+# because lineage/spec-link still gate the link itself). Per commit; ci/chore/build/test exempt.
+# Fails CLOSED on an unresolvable base.
+set -euo pipefail
+
+BASE="${1:-${SDLC_BASE:-origin/main}}"
+
+if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
+  echo "FAIL [epic-open]: base ref '${BASE}' not found — fetch full history / check the base branch."
+  exit 1
+fi
+RANGE="${BASE}..HEAD"
+EXEMPT='ci|chore|build|test'
+
+# Read one frontmatter value from the FIRST --- … --- block only (awk stops at the first closing fence).
+fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f && index($0, k":")==1 {sub("^" k ":[ \t]*", ""); print; exit}' "$2" 2>/dev/null | tr -d '\r'; }
+
+# Is the epic SEALED? true iff it has >=1 story and EVERY stories/*.md frontmatter status is `shipped`.
+epic_sealed() {
+  ep_dir="$1"
+  sdir="${ep_dir}/stories"
+  [ -d "$sdir" ] || return 1
+  found=0
+  for f in "$sdir"/*.md; do
+    [ -e "$f" ] || continue
+    found=1
+    st="$(fm_val status "$f")"
+    [ "$st" = "shipped" ] || return 1
+  done
+  [ "$found" = "1" ] || return 1
+  return 0
+}
+
+commits="$(git rev-list --no-merges "$RANGE")"
+if [ -z "$commits" ]; then
+  echo "PASS [epic-open]: no non-merge commits in ${RANGE}"
+  exit 0
+fi
+
+rc=0
+while IFS= read -r sha; do
+  [ -z "$sha" ] && continue
+  short="$(git log -1 --format=%h "$sha")"
+  subject="$(git log -1 --format=%s "$sha")"
+  if printf '%s' "$subject" | grep -qE "^(${EXEMPT})(\([a-z0-9._-]+\))?!?: "; then
+    echo "PASS [epic-open]: ${short} '${subject}' — maintenance commit (exempt)"
+    continue
+  fi
+  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | sed '/^$/d' | head -1)"
+  if ! printf '%s' "$task" | grep -qE '.+-T[0-9]+$'; then
+    echo "note [epic-open]: ${short} has no resolvable Task trailer — deferring to spec-link."
+    continue
+  fi
+  story="$(printf '%s' "$task" | sed -E 's/-T[0-9]+$//')"
+  link="specs/${story}/link.md"
+  [ -f "$link" ] || { echo "note [epic-open]: ${short} ${task} — link.md missing (spec-link will FAIL)."; continue; }
+  product_rel="$(fm_val product-repo "$link")"
+  epic="$(fm_val epic "$link")"
+  # A malformed link.md (empty product-repo, or an epic that is not a real EP-<slug>) must FAIL, not
+  # slip through as "not reachable" — an empty epic would collapse ep_dir to <product>/epics/ (a real
+  # dir) and pass the seal check as if the epic were open.
+  if [ -z "$product_rel" ] || ! printf '%s' "$epic" | grep -qE '^EP-[a-z0-9-]+$'; then
+    echo "FAIL [epic-open]: ${short} ${task} — link.md has no valid product-repo/epic metadata."
+    rc=1
+    continue
+  fi
+  # product-repo is relative to the link.md's directory (specs/<story>/), so join it there.
+  prod="specs/${story}/${product_rel}"
+  ep_dir="${prod}/epics/${epic}"
+  if [ ! -d "$prod" ]; then
+    echo "PASS [epic-open]: ${short} ${task} -> ${epic} (product repo not reachable — seal check deferred)."
+    continue
+  fi
+  if [ ! -d "$ep_dir" ]; then
+    echo "FAIL [epic-open]: ${short} ${task} -> epic ${epic} does not exist in the product repo (orphan story link)."
+    rc=1
+    continue
+  fi
+  if epic_sealed "$ep_dir"; then
+    echo "FAIL [epic-open]: ${short} ${task} targets SEALED epic ${epic} (all stories shipped)."
+    echo "  -> New behaviour cannot mutate a shipped epic. Open a threaded change-epic with yad-change"
+    echo "     (kind: change|defect|hotfix, parent: ${epic}) and implement against ITS stories instead."
+    rc=1
+    continue
+  fi
+  echo "PASS [epic-open]: ${short} ${task} -> ${epic} (epic is open — has unshipped stories)."
+done <<EOF
+$commits
+EOF
+exit "$rc"

package/skills/yad-checks/templates/checks/lineage-check.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# lineage-check gate (Phase 6 — feature threads). Builds on spec-link: every NON-MAINTENANCE commit
+# must link a real story (spec-link enforces that), and the OWNING epic must be a valid node in a
+# feature thread — a change/defect/hotfix epic MUST thread to a real parent. This is the
+# "every code change has an owning epic in a thread" enforcement. Per commit; maintenance commits
+# (ci/chore/build/test) are exempt. Fails CLOSED on an unresolvable base.
+#
+# The owning epic lives in the PRODUCT repo (reached via specs/<story>/link.md's `product-repo` path,
+# exactly like contract-check). When the product repo is not reachable from CI, lineage is verified
+# best-effort: the commit PASSes with a note (spec-link already proved the story link).
+set -euo pipefail
+
+BASE="${1:-${SDLC_BASE:-origin/main}}"
+
+if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
+  echo "FAIL [lineage-check]: base ref '${BASE}' not found — fetch full history / check the base branch."
+  exit 1
+fi
+RANGE="${BASE}..HEAD"
+EXEMPT='ci|chore|build|test'
+
+# Read one frontmatter value from the FIRST --- … --- block only. awk bounds to the first block (stops
+# at the first closing fence), so a body `---` or an absent key can never leak a body line. Plain
+# scalars only.
+fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f && index($0, k":")==1 {sub("^" k ":[ \t]*", ""); print; exit}' "$2" 2>/dev/null | tr -d '\r'; }
+
+commits="$(git rev-list --no-merges "$RANGE")"
+if [ -z "$commits" ]; then
+  echo "PASS [lineage-check]: no non-merge commits in ${RANGE}"
+  exit 0
+fi
+
+rc=0
+while IFS= read -r sha; do
+  [ -z "$sha" ] && continue
+  short="$(git log -1 --format=%h "$sha")"
+  subject="$(git log -1 --format=%s "$sha")"
+  if printf '%s' "$subject" | grep -qE "^(${EXEMPT})(\([a-z0-9._-]+\))?!?: "; then
+    echo "PASS [lineage-check]: ${short} '${subject}' — maintenance commit (exempt)"
+    continue
+  fi
+  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | sed '/^$/d' | head -1)"
+  # No / malformed Task trailer is spec-link's job to FAIL; here we only skip what we can't resolve.
+  if ! printf '%s' "$task" | grep -qE '.+-T[0-9]+$'; then
+    echo "note [lineage-check]: ${short} has no resolvable Task trailer — deferring to spec-link."
+    continue
+  fi
+  story="$(printf '%s' "$task" | sed -E 's/-T[0-9]+$//')"
+  link="specs/${story}/link.md"
+  if [ ! -f "$link" ]; then
+    echo "note [lineage-check]: ${short} ${task} — specs/${story}/link.md missing (spec-link will FAIL)."
+    continue
+  fi
+  product_rel="$(fm_val product-repo "$link")"
+  epic="$(fm_val epic "$link")"
+  if [ -z "$epic" ]; then
+    echo "FAIL [lineage-check]: ${short} ${task} — link.md has no 'epic:' (cannot place it in a thread)."
+    rc=1
+    continue
+  fi
+  # product-repo is relative to the link.md's directory (specs/<story>/), so join it there.
+  prod="specs/${story}/${product_rel}"
+  epicmd="${prod}/epics/${epic}/epic.md"
+  # Defer ONLY when the product checkout itself is unreachable. A reachable hub whose epic is missing is
+  # an orphaned story link — FAIL, do not pass it off as "not reachable".
+  if [ -z "$product_rel" ] || [ ! -d "$prod" ]; then
+    echo "PASS [lineage-check]: ${short} ${task} -> epic ${epic} (product repo not reachable — lineage check deferred)."
+    continue
+  fi
+  if [ ! -f "$epicmd" ]; then
+    echo "FAIL [lineage-check]: ${short} ${task} -> epic ${epic} does not exist in the product repo (orphan story link)."
+    rc=1
+    continue
+  fi
+  kind="$(fm_val kind "$epicmd")"
+  [ -z "$kind" ] && kind="feature"
+  if [ "$kind" = "feature" ]; then
+    echo "PASS [lineage-check]: ${short} ${task} -> ${epic} (genesis feature epic)."
+    continue
+  fi
+  # A change/defect/hotfix epic MUST thread to a real parent.
+  parent="$(fm_val parent "$epicmd")"
+  if [ -z "$parent" ]; then
+    echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} is kind:${kind} but declares no 'parent:' — a change-epic must thread to its predecessor."
+    rc=1
+    continue
+  fi
+  if [ ! -f "${prod}/epics/${parent}/epic.md" ]; then
+    echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} threads to '${parent}', but epics/${parent}/ does not exist in the hub (orphan thread)."
+    rc=1
+    continue
+  fi
+  echo "PASS [lineage-check]: ${short} ${task} -> ${epic} (kind:${kind} threaded to ${parent})."
+done <<EOF
+$commits
+EOF
+exit "$rc"