yadflow 2.16.1 → 2.18.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [2.16.1](https://github.com/abdelrahmannasr/yadflow/compare/v2.16.0...v2.16.1) (2026-06-25)
+# [2.18.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.17.0...v2.18.0) (2026-06-26)
 
 
-### Bug Fixes
+### Features
 
-* **open-pr:** make build helpers stage-aware on the hub (closes [#80](https://github.com/abdelrahmannasr/yadflow/issues/80)) ([#81](https://github.com/abdelrahmannasr/yadflow/issues/81)) ([8d74e3d](https://github.com/abdelrahmannasr/yadflow/commit/8d74e3d267d4c056992d3bc6f5a2a7a15a66b431))
+* **change:** post-lock change management via feature threads (Phase 6) ([#83](https://github.com/abdelrahmannasr/yadflow/issues/83)) ([f8024d5](https://github.com/abdelrahmannasr/yadflow/commit/f8024d5808070656d1c3039905ada39096fe7d3b)), closes [#1](https://github.com/abdelrahmannasr/yadflow/issues/1)
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/README.md

@@ -23,10 +23,11 @@ a scaffolded module that installs cleanly, and a working **team review gate** yo
 
 ## The workflow at a glance
 
-The whole lifecycle, from an empty project to shipped code. Setup is one-time; the **front half**
-is human-gated and runs once per epic in the product hub; the **build half** runs once per story
-per code repo; **automation** is opt-in and earned. `yad-status` reads it all; `yad-hub-bridge`
-mirrors front-half reviews to real PR/MRs.
+The whole lifecycle, from an empty project to shipped code. Setup is one-time; the optional
+**front-zero** (`yad-discovery`) frames the whole project once — market, feasibility, and a phased
+roadmap; the **front half** is human-gated and runs once per epic in the product hub; the **build
+half** runs once per story per code repo; **automation** is opt-in and earned. `yad-status` reads it
+all; `yad-hub-bridge` mirrors front-half reviews to real PR/MRs.
 
 <!-- Source: docs/diagrams/sdlc-overview.mmd — edit the .mmd and run `npm run diagrams` to regenerate -->
 ![Yadflow SDLC overview — setup, human-gated front half, per-story build half, earned automation](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/sdlc-overview.svg)
@@ -44,6 +45,7 @@ human**. Detailed walkthroughs for each phase follow below.
 | `RESEARCH-NOTES.md` | Verified Phase 0 facts about BMAD, Spec Kit, Repomix, Impeccable + deviations. |
 | `skills/sdlc/` | Module source of truth (`config.yaml`, `module-help.csv`, `install.sh`). Survives BMAD updates. |
 | `bin/`, `cli/` | The `yad` setup/update CLI (published to npm as `yadflow`). |
+| `skills/yad-discovery/` | Optional front-zero (once per project, greenfield + brownfield): market research, competitor study, feasibility, current-state, requirements (functional + non-functional) and a phased roadmap (MVP+) under the reserved `EP-discovery`. `roadmap.md` is the menu of features each epic reads. |
 | `skills/yad-analysis/` | Optional front state 1: pressure-test the idea with the analyst into `analysis.md` (skippable). |
 | `skills/yad-epic/` | Front state 1: author an epic with AI assist, assign its `EP-<slug>` ID, seed state. |
 | `skills/yad-architecture/` | Front state 3: author `architecture.md` + the locked `contract.md`; hash-lock the contract surface. |
@@ -67,9 +69,13 @@ human**. Detailed walkthroughs for each phase follow below.
 | `skills/yad-backfill/` | Generate a human-verified spec for already-built code (Repomix), gated per touched feature. |
 | `skills/yad-run/` | Phase 4 orchestrator: drive a story's back half on the `automation` dial; kill switch. |
 | `skills/yad-status/` | Read-only view: front chain, build-half dials, trust record, fleet roll-up. |
-| `epics/EP-istifta-inquiries/` | A worked demo epic run **end to end** (front half + build half + automation). |
+| `skills/yad-change/` | Phase 6: post-lock change/defect/hotfix **intake + triage** — seed a new epic threaded to its parent (inherit by reference, re-author only what changes). |
+| `skills/yad-timeline/` | Phase 6: render a feature **thread** as an evolution view + resolve its current truth (`thread-resolved.md`). |
+| `skills/yad-defects/` | Phase 6: per-epic/per-thread **quality-gap report** by `escape_stage` + `root_cause`. |
+| `skills/yad-reconcile/` | Phase 6: read-only **drift/orphan/debt sweep** across threads (mirrors `yad-docs-sync`; never a gate). |
+| `epics/EP-istifta-inquiries/` | A worked demo epic run **end to end** (front half + build half + automation + a Phase 6 change thread). |
 | `demo-repos/` | Throwaway code repos for the build half (separate git repos; regenerable — see `demo-repos/README.md`). |
-| `docs/` | The phased build plans (`phase-2`…`phase-5`) and the original workflow design. |
+| `docs/` | The phased build plans (`phase-2`…`phase-6`) and the original workflow design. |
 | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Commit & PR/MR title convention (Conventional Commits, lowercase after the type). |
 
 ## The `yad` CLI (install, update, reconcile)
@@ -102,6 +108,8 @@ with `npx` from your **product hub** repo — no clone needed.
 | `yad ship --type <t> -m <subject>` | Commit **and** open the task PR/MR in one step (`yad commit` then `yad open-pr`) — stage-aware, same as `open-pr`. |
 | `yad repo list` / `yad repo refresh [name]` | List connected repos as **fresh / stale**, and re-pack a stale one — staleness is now an explicit human decision, never an automatic skill side-effect. |
 | `yad repo sync [name]` | Switch every connected repo to its **default branch** and fast-forward it from origin (one or all). Dirty repos are skipped, never overwritten; fast-forward only. |
+| `yad thread [<epic>]` | **Feature threads (Phase 6).** No arg: list every thread. With an epic: show its thread (genesis → changes → defects), the **resolved current-truth** map (which epic owns each artifact now), and any open hotfix debt. `--json` for tooling. Read-only. |
+| `yad reconcile [check\|refresh\|wire]` | Sweep threads for **drift / orphans / open hotfix debt** and report which thread drifted and why (mirrors `yad docs sync`; advisory — the CI gates block at merge). |
 | `npx yadflow --version` | Print the installed CLI version. |
 
 Flags: `--dir <path>` targets a project other than the cwd; `--force` re-copies unchanged files (or
@@ -150,7 +158,7 @@ does / why / what to enter / what skipping means), and the step count adapts.
 0. **Profile** — the three questions above, plus "configure optional tools now?". Pre-answer for
    CI/scripts with `--solo`/`--team <n>`, `--greenfield`/`--brownfield`, `--monorepo`/`--separate`, `--tools`.
 1. **Preflight** — confirm the hub is a git repo (offers `git init`); check `git`/`node`/`npx`.
-2. **Install the module** — copy all 30 `yad-*` skills into the IDE skill dirs you pick
+2. **Install the module** — copy all 31 `yad-*` skills into the IDE skill dirs you pick
    (`.claude/`, `.agents/`, `.zencoder/`, `.opencode/`) and register `_bmad/sdlc/`.
 3. **Hub platform & roster** — detect GitHub/GitLab from the remote; record reviewers → `.sdlc/hub.json`.
    **Solo skips the roster** (you review by merging your own PR). Edit the roster any time with `yad roster`.
@@ -204,7 +212,7 @@ with a fix-it hint per finding. Failures carry stable, greppable codes, also pri
 
 Filing a bug? Attach `yad doctor --json` — it contains no secrets (names, paths, and check results only).
 
-## Agent skills (all 30)
+## Agent skills (all 35)
 
 The CLI **installs and wires** the module; the skills below are the **agents you invoke by name** in your
 AI IDE (e.g. *“run `yad-epic`”*) to actually do the work. State lives in files you can also edit
@@ -274,6 +282,17 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
   never touches epic state, approvals, or the contract lock. *AI builds, the hand decides* — and now the
   hand can also learn, on demand, what it is deciding about.
 
+### Front-zero — frame the whole project (once per project, optional, human-gated)
+
+- **`yad-discovery`** — *Optional* front-zero, for **greenfield and brownfield**. With the analyst
+  and pm, run market research, a **competitor study** (both modes), a feasibility study, and — in
+  brownfield — a code-aware current-state study, then distil a **functional + non-functional
+  requirements** list and a **phased roadmap** (an explicit **MVP** phase, then later phases) under the
+  reserved `EP-discovery` ("epic zero"). It is gated by the same review gate (base rule: owner + 1
+  reviewer); on approval it terminates at `discovery-done` (no build half). Its `roadmap.md` is the menu
+  of features — each `yad-epic` reads it for project context (reference-only; discovery never
+  auto-seeds epics).
+
 ### Front half — author the "thinking" (once per epic, human-gated)
 
 - **`yad-analysis`** — *Optional* front state 1. With the analyst, pressure-test a feature idea
@@ -356,6 +375,33 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
   automation) and status, which approvals are still required, per-story back-half trust records, the
   kill-switch state, and a fleet roll-up across epics.
 
+### Post-lock change management — feature threads (Phase 6)
+
+After the contract locks and code ships, a change must **not** mutate a locked artifact — it becomes a
+**new epic threaded to its parent**. A feature is a *thread* of linked epics (genesis → change → defect →
+…); a change-epic **inherits** the front artifacts it does not change (by reference) and **re-authors**
+only what it does. So artifacts never go stale — they are *superseded*; the feature's current truth is the
+head of the thread. This is what keeps the SDLC a trusted source of truth for AI on the next change.
+
+- **`yad-change`** — the intake + triage. Classifies the change *depth* (defect-fix /
+  behavioral-no-surface / contract-surface / new-capability), seeds a new `EP-<slug>` threaded to its
+  parent (lineage frontmatter, an inherited-step `state.json`, a pointer-lock `contract-lock.json`,
+  `change.json`), and for hotfixes opens `reconcile-debt.json`. Never auto-advances — hands off to the
+  normal authoring skills + the review gate.
+- **`yad-timeline`** — render the thread as an evolution view (yad-docs shell + `TIMELINE.md`) and emit
+  `thread-resolved.md`, the composed **current-truth map** (which epic owns each artifact now).
+- **`yad-defects`** — a per-epic/per-thread quality-gap report aggregating defects by **`escape_stage`**
+  (the gate that should have caught it) + `root_cause` — *where the SDLC leaks*, so the team hardens the
+  originating stage.
+- **`yad-reconcile`** — a read-only drift/orphan/debt sweep across threads (mirrors `yad-docs-sync`; never
+  a gate). The hard block is the CI gates.
+
+Three CI gates (in `yad-checks`) enforce it: **lineage-check** (a change links a real threaded epic),
+**epic-open** (a *sealed* epic — all stories shipped — refuses new behaviour, forcing a change-epic so the
+front artifacts can never go stale), and **reconcile-debt** (a thread with open hotfix debt is frozen
+until paid). Two read-only CLIs surface it: `yad thread <epic>` (the thread + resolved truth + open debt)
+and `yad reconcile` (the drift sweep).
+
 ## The two dials (per step, build plan §2)
 
 - **assistance:** `none` | `review` | `heavy` — how much AI helps.
@@ -423,6 +469,10 @@ drive it deterministically with the **`yad gate`** CLI (`open → sync → …
 the per-step PR/MR and the step **auto-advances on merge** once approvals are satisfied and all comment
 threads are resolved. Details: **“Run the full front half by hand”** below.
 
+0. *(optional, once per project)* `yad-discovery` → the discovery set (`market-research.md`,
+   `competitor-analysis.md`, `current-state.md`, `feasibility.md`, `requirements.md`, `roadmap.md`)
+   under the reserved `EP-discovery` → review (base rule) → `currentStep: discovery-done`. The whole
+   set is required to review; its `roadmap.md` then frames each epic below (read once it is approved).
 6. `yad-epic` → `epic.md` (assigns `EP-<slug>`, seeds state) → review (base rule).
 7. `yad-architecture` → `architecture.md` + locked `contract.md` → review (**escalated**: contract).
 8. `yad-ui` → `ui-design.md` + `DESIGN.md` → review (base rule).
@@ -468,7 +518,10 @@ Details: **“Run the back half on the dial”** below.
 
 ## Run the full front half by hand
 
-The front half walks **epic → review → architecture+contract → review → UI design → review → stories
+Optionally preceded once per project by the **front-zero** — **`yad-discovery` → review →
+`discovery-done`** — which frames the whole product (market, competitor, feasibility, requirements,
+roadmap) under the reserved `EP-discovery`; its approved `roadmap.md` then feeds each epic. The front
+half itself walks **epic → review → architecture+contract → review → UI design → review → stories
 → review → `ready-for-build`**, then **test cases → review** runs as a **parallel, non-blocking track**
 alongside the build half. It is all files under `epics/EP-<slug>/`. The skills below guide you, but you
 can also edit the files directly — that's the point.

package/bin/yad.mjs

@@ -15,6 +15,7 @@ import { runDocs } from '../cli/docs.mjs';
 import { runDoctor } from '../cli/doctor.mjs';
 import { runNext } from '../cli/next.mjs';
 import { syncStatuses } from '../cli/artifact-status.mjs';
+import { runThread, runReconcile } from '../cli/thread.mjs';
 
 const HELP = `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
 
@@ -63,6 +64,12 @@ ${c.bold('Build helpers')}
   yad repo list                        Show connected repos (fresh / stale)
   yad repo refresh [name]              Re-pack a stale repo (a human decision)
 
+${c.bold('Feature threads (post-lock change management)')}
+  yad thread                           List every feature thread (genesis → changes → defects)
+  yad thread <epic> [--json]           Show one thread: its epics, the resolved current truth, open debt
+  yad reconcile [check|refresh|wire]   Flag orphan drift + open hotfix debt across threads (advisory,
+                                       never a gate — the gates block at merge)
+
 ${c.bold('Interactive docs (generated sites)')}
   yad docs list                        Show the docs target + per-site freshness
   yad docs build [--epic <id>|--overview]    npm-build a generated doc site
@@ -216,6 +223,23 @@ async function main() {
       await runDocs(o.dir, { action: action || 'list', epic: o.epic, overview: o.overview, sync, today });
       break;
     }
+    case 'thread': {
+      const [, epic] = o._;
+      if (epic && !isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
+      await runThread(o.dir, { epic, json: o.json });
+      break;
+    }
+    case 'reconcile': {
+      const [, action] = o._;
+      const thread = o.epic || o.thread || null;
+      if (thread && !isValidEpicId(thread)) { log(c.red(`invalid epic id: ${thread} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
+      const act = action || (o.wire ? 'wire' : o.refresh ? 'refresh' : 'check');
+      if (!['check', 'refresh', 'wire'].includes(act)) {
+        log(c.red(`unknown reconcile action: ${act} (check|refresh|wire)`)); process.exitCode = 1; break;
+      }
+      await runReconcile(o.dir, { action: act, thread });
+      break;
+    }
     default:
       log(c.red(`unknown command: ${cmd}`));
       log(HELP);

package/cli/artifact-status.mjs

@@ -6,7 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { c, log, ok, info, readJSONStrict } from './lib.mjs';
-import { epicRoot, artifactBase, artifactFromBase, findReviewStep } from './epic-state.mjs';
+import { epicRoot, artifactBase, artifactFromBase, findReviewStep, DISCOVERY_FILES } from './epic-state.mjs';
 import { epicFiles } from './manifest.mjs';
 
 // The front-gate lifecycle this command manages. Forward-only: a status is only ever moved UP this
@@ -75,6 +75,11 @@ export async function syncStatuses(root, { epic, dryRun = false } = {}) {
         files.push({ base: 'stories', file: path.join(storiesDir, f) });
       }
     }
+    // Discovery ("epic zero") set: the project-discovery files all key to the single discovery /
+    // discovery-review step pair, so they reconcile together (mirrors the stories/ set above).
+    for (const f of DISCOVERY_FILES) {
+      if (fs.existsSync(path.join(dir, f))) files.push({ base: 'discovery', file: path.join(dir, f) });
+    }
 
     for (const { base, file } of files) {
       if (!fs.existsSync(file)) continue;

package/cli/doctor.mjs

@@ -6,7 +6,8 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { c, log, ok, info, warn, fail, hand, run, has, exists, readJSON, readJSONStrict } from './lib.mjs';
 import { VERSION, PROJECT_FILES, DESIGN_TOOLS, TESTING_TOOLS, LEARNING_TOOLS } from './manifest.mjs';
-import { loadLedger, epicRoot } from './epic-state.mjs';
+import { loadLedger, epicRoot, isValidEpicId, epicLineage, resolveThread } from './epic-state.mjs';
+import { loadDebt } from './thread.mjs';
 import { gitHead } from './setup.mjs';
 import { cliFor, validateLogin, hostFromGitUrl } from './platform.mjs';
 
@@ -264,11 +265,40 @@ export function epicChecks(checks, root) {
   }
 }
 
+// Phase 6 — feature-thread integrity. A change-epic must thread to a real parent and its denormalized
+// `thread` cache must equal the computed root; an open hotfix reconcile-debt is a warn (the next change
+// on that thread is blocked at the gate until it is paid). Pure reporting, like the other sections.
+export function threadChecks(checks, root) {
+  const epicsDir = path.join(root, 'epics');
+  if (!exists(epicsDir)) return;
+  for (const e of fs.readdirSync(epicsDir).sort()) {
+    if (!fs.statSync(path.join(epicsDir, e)).isDirectory() || !isValidEpicId(e)) continue;
+    if (!exists(path.join(epicsDir, e, 'epic.md'))) continue;
+    const lin = epicLineage(root, e);
+    if (lin.kind === 'feature' && !lin.parent) continue; // genesis with no lineage — nothing to check
+    const { broken } = resolveThread(root, e);
+    if (broken) {
+      check(checks, `thread:${e}`, 'threads', 'fail', `${e}: ${broken}`,
+        'a change-epic must thread to a real parent; fix `parent:`/`thread:` in epic.md frontmatter');
+    } else {
+      check(checks, `thread:${e}`, 'threads', 'ok', `${e}: ${lin.kind} threaded to ${lin.thread || lin.parent}`);
+    }
+    for (const d of loadDebt(root, e)) {
+      if (d.status === 'open') {
+        check(checks, `thread:${e}:debt`, 'threads', 'warn',
+          `${e}: open reconcile debt (${d.reason || 'hotfix shipped first'})`,
+          'pay it — update the artifacts + add a regression test; the next change on this thread is blocked until then');
+      }
+    }
+  }
+}
+
 export async function runDoctor(root, { json = false } = {}) {
   const checks = [];
   envChecks(checks);
   projectChecks(checks, root);
   epicChecks(checks, root);
+  threadChecks(checks, root);
 
   const failed = checks.filter((x) => x.status === 'fail');
   const warned = checks.filter((x) => x.status === 'warn');

package/cli/epic-state.mjs

@@ -38,6 +38,7 @@ export function parseReviewBranch(branch = '') {
 // (storiesHash fingerprints the directory), so any story branch syncs the same review step.
 export function artifactFromBase(base) {
   if (base === 'stories' || /^stories-S\d+$/i.test(base)) return 'stories/';
+  if (base === 'discovery') return 'discovery/';
   return `${base}.md`;
 }
 
@@ -47,6 +48,7 @@ export function artifactFromBase(base) {
 export function artifactPaths(base) {
   if (base === 'architecture') return ['architecture.md', 'contract.md', '.sdlc/contract-lock.json'];
   if (base === 'stories') return ['stories'];
+  if (base === 'discovery') return [...DISCOVERY_FILES];
   return [`${base}.md`];
 }
 
@@ -87,13 +89,41 @@ export function storiesHash(epicDir) {
   return 'sha256:' + createHash('sha256').update(parts.join('\n')).digest('hex');
 }
 
+// The reserved id of the project front-zero ("epic zero"). yad-discovery seeds it; yad-epic /
+// yad-analysis must never pick this slug for a feature.
+export const DISCOVERY_EPIC = 'EP-discovery';
+
+// The project-discovery artifact set (EP-discovery / "epic zero"). The `discovery-review` step binds
+// to the whole set, mirroring how stories-review binds to the stories/ directory — editing any file
+// revokes prior approvals. A fixed list (not a dir scan) because the files live in the epic root.
+export const DISCOVERY_FILES = [
+  'market-research.md',
+  'competitor-analysis.md',
+  'current-state.md',
+  'feasibility.md',
+  'requirements.md',
+  'roadmap.md',
+];
+
+// Deterministic fingerprint of the discovery set: hash every file in the fixed DISCOVERY_FILES order,
+// combine. The WHOLE set is the reviewable unit — if any required artifact is missing the discovery is
+// incomplete and NON-REVIEWABLE, so this returns null (no hash to bind an approval to), the same
+// "nothing to lock" signal storiesHash/contractSurfaceHash give for an absent/malformed surface. Once
+// the full set exists, an edit (or deletion) of any file changes the hash and revokes prior approvals.
+export function discoveryHash(epicDir) {
+  if (!DISCOVERY_FILES.every((f) => fs.existsSync(path.join(epicDir, f)))) return null;
+  const parts = DISCOVERY_FILES.map((f) => `${f}:${fileSha(path.join(epicDir, f))}`);
+  return 'sha256:' + createHash('sha256').update(parts.join('\n')).digest('hex');
+}
+
 // The content fingerprint an approval is bound to. For architecture the fingerprint is the locked
-// contract surface (a re-lock => stale); for stories it is the whole stories/ set; for every other
-// artifact it is the file's bytes.
+// contract surface (a re-lock => stale); for stories it is the whole stories/ set; for discovery it is
+// the whole discovery file set; for every other artifact it is the file's bytes.
 export function artifactHash(epicDir, artifact) {
   const b = artifactBase(artifact);
   if (b === 'architecture') return contractSurfaceHash(epicDir);
   if (b === 'stories') return storiesHash(epicDir);
+  if (b === 'discovery') return discoveryHash(epicDir);
   return fileSha(path.join(epicDir, artifact.replace(/\/$/, '')));
 }
 
@@ -160,6 +190,21 @@ export function gatePredicate({
   merged = true,
   solo = false,
 }) {
+  // Phase 6: an INHERITED step (a change-epic carrying a parent artifact by reference) is satisfied
+  // without re-review — its approval lives upstream in the thread, recorded as an `inherited` provenance
+  // entry. It is pre-marked `done` in state.json, so the gate is normally never invoked on it; this
+  // short-circuit makes a direct call safe and surfaces a corrupted boundHash (a referenced artifact
+  // cannot change under the child, so a mismatch is corruption — re-thread, do not silently pass).
+  if (step?.inherited) {
+    const drift = step.boundHash && currentHash && step.boundHash !== currentHash;
+    return {
+      approvalsSatisfied: true, threadsResolved: true, merged: true, staleDropped: 0,
+      passed: !drift,
+      missing: drift ? [`inherited artifact drifted from ${step.inheritedFrom || 'parent'} — re-thread`] : [],
+      rule: 'inherited',
+    };
+  }
+
   const forStep = approvals.filter((a) => a.step === step.id && a.status === 'approved');
   // Revoke-on-change: an approval bound to a stale content hash no longer counts.
   const stale = forStep.filter((a) => a.artifactHash && currentHash && a.artifactHash !== currentHash);
@@ -221,6 +266,13 @@ export function advanceState(state, step) {
     state.currentStep = 'ready-for-build';
     return state;
   }
+  // Discovery is the project front-zero ("epic zero"): it has no build half, so its review terminates
+  // at a `discovery-done` sentinel rather than `ready-for-build` (which would make `yad next` claim the
+  // build half can run). The roadmap it approved is the input the real feature epics read.
+  if (step.id === 'discovery-review') {
+    state.currentStep = 'discovery-done';
+    return state;
+  }
   const next = state.steps[i + 1];
   if (next) {
     next.status = next.type === 'review+approve' ? 'in_review' : 'in_progress';
@@ -244,6 +296,7 @@ export function markInReview(state, step) {
 // The front authoring step a `yad next` action maps to — the skill the user invokes for that step.
 // Review (review+approve) steps are driven by the `yad gate` CLI, not a skill, so they are not here.
 export const STEP_SKILL = {
+  discovery: 'yad-discovery',
   analysis: 'yad-analysis',
   epic: 'yad-epic',
   architecture: 'yad-architecture',
@@ -258,8 +311,8 @@ export const STEP_SKILL = {
 // (the Phase B rail) and by the driver. No FS / network.
 export function preconditionsMet(state, stepId) {
   if (!state || !Array.isArray(state.steps)) {
-    const ok = stepId === 'epic' || stepId === 'analysis';
-    return { ok, blockedBy: null, reason: ok ? 'entry step (no epic seeded yet)' : `start with yad-epic — no epic state for '${stepId}'` };
+    const ok = stepId === 'epic' || stepId === 'analysis' || stepId === 'discovery';
+    return { ok, blockedBy: null, reason: ok ? 'entry step (no state seeded yet)' : `start with yad-epic — no epic state for '${stepId}'` };
   }
   const i = state.steps.findIndex((s) => s.id === stepId);
   if (i === -1) return { ok: false, blockedBy: null, reason: `unknown step '${stepId}'` };
@@ -281,6 +334,30 @@ export function nextAction(ledger, { epic } = {}) {
   const epicId = epic || state?.epicId || null;
   if (!state) return { epicId, kind: 'new', skill: 'yad-epic', why: 'no epic state yet — seed it with yad-epic' };
 
+  // EP-discovery ("epic zero") is the project front-zero: a 2-step author→review chain with no build
+  // half and no parallel track. Resolve its action in isolation so the feature-epic logic below never
+  // applies to it.
+  if (state.kind === 'discovery') {
+    if (state.currentStep === 'discovery-done') {
+      return { epicId, kind: 'discovery-done', step: 'discovery-done', status: 'done',
+        why: 'discovery approved — seed feature epics with yad-epic (each reads roadmap.md)' };
+    }
+    const dstep = state.steps.find((s) => s.id === state.currentStep)
+      || state.steps.find((s) => s.status !== 'done');
+    if (!dstep) return { epicId, kind: 'discovery-done', step: 'discovery-done', why: 'discovery is done' };
+    if (dstep.type === 'author') {
+      return { epicId, kind: 'author', step: dstep.id, status: dstep.status,
+        skill: STEP_SKILL[dstep.id] || null, artifact: dstep.artifact,
+        why: `${dstep.id} is ${dstep.status} — author ${dstep.artifact}` };
+    }
+    const dpr = (ledger.hubPrs || []).find((p) => artifactBase(p.artifact) === artifactBase(dstep.artifact));
+    const dverb = dpr ? 'sync' : 'open';
+    return { epicId, kind: dpr ? 'review-sync' : 'review-open', step: dstep.id, status: dstep.status,
+      artifact: dstep.artifact, pr: dpr ? dpr.number : null,
+      command: `yad gate ${dverb} ${epicId} ${dstep.artifact}`,
+      why: dpr ? `review PR #${dpr.number} is open — sync its state to advance` : `${dstep.id} is open — create the review PR/MR` };
+  }
+
   // The parallel test-cases track stays workable even once the epic is ready-for-build.
   const tc = state.steps.find((s) => s.id === 'test-cases');
   const tcOpen = !!tc && tc.status !== 'done' && tc.status !== 'blocked';
@@ -310,4 +387,141 @@ export function nextAction(ledger, { epic } = {}) {
     why: pr ? `review PR #${pr.number} is open — sync its state to advance` : `${step.id} is open — create the review PR/MR` };
 }
 
+// ---- Phase 6: feature threads (lineage frontmatter on epic.md) -----------------------------------
+
+// Minimal frontmatter reader (key: value, and `inherits: [a, b]` arrays). Mirrors gate.mjs's reader so
+// the thread helpers and the gate agree on the same parse; shared here as the lineage source.
+export function readFrontmatter(file) {
+  if (!fs.existsSync(file)) return {};
+  const m = fs.readFileSync(file, 'utf8').match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return {};
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+    if (!kv) continue;
+    const [, k, v] = kv;
+    out[k] = /^\[.*\]$/.test(v) ? v.slice(1, -1).split(',').map((s) => s.trim()).filter(Boolean) : v.trim();
+  }
+  return out;
+}
+
+const asList = (v) => (Array.isArray(v) ? v : v ? [v] : []);
+
+// The lineage of an epic from epic.md frontmatter. `kind` defaults to `feature` (genesis) when absent,
+// so an un-migrated genesis epic behaves as the thread root. Greenfield/missing-safe.
+export function epicLineage(root, epic) {
+  const fm = readFrontmatter(path.join(epicRoot(root, epic), 'epic.md'));
+  return {
+    kind: fm.kind || 'feature',
+    parent: fm.parent || null,
+    thread: fm.thread || null,
+    inherits: asList(fm.inherits),
+    supersedes: asList(fm.supersedes),
+  };
+}
+
+// Walk `parent` to the thread root. Cycle- and missing-safe. Returns the genesis-first `chain`, the
+// computed `rootId`, and a `broken` reason (missing parent dir, a cycle, or a denormalized `thread`
+// cache that disagrees with the computed root) — the signal yad doctor / yad next --check report.
+export function resolveThread(root, epicId) {
+  const chain = [];
+  const seen = new Set();
+  let cur = epicId;
+  let broken = null;
+  while (cur) {
+    if (seen.has(cur)) { broken = `cycle at ${cur}`; break; }
+    seen.add(cur);
+    if (!fs.existsSync(epicRoot(root, cur))) {
+      broken = cur === epicId ? `missing epic ${cur}` : `missing parent epic ${cur}`;
+      break;
+    }
+    chain.unshift(cur); // genesis ends up first
+    const { parent } = epicLineage(root, cur);
+    if (!parent) break; // reached genesis
+    cur = parent;
+  }
+  const rootId = chain[0] || epicId;
+  const tip = epicLineage(root, epicId);
+  // A non-genesis epic (has a parent) MUST carry a `thread:` cache that equals the computed root.
+  // A missing cache is corruption too — without it the bash gates' parent-walk is the only safety net,
+  // and a tool reading the field would mis-scope the thread.
+  if (!broken && tip.parent && !tip.thread) {
+    broken = `missing thread cache on ${epicId} (kind:${tip.kind}, parent:${tip.parent}) — should be '${rootId}'`;
+  }
+  if (!broken && tip.thread && tip.thread !== rootId) {
+    broken = `thread cache '${tip.thread}' != computed root '${rootId}'`;
+  }
+  return { rootId, chain, broken };
+}
+
+// Every epic that belongs to a thread (resolved root == this thread's root), ordered genesis-first by
+// chain depth. Derived by scanning epics/ — no duplicated thread registry. Used by yad-timeline/yad-defects.
+export function threadEpics(root, threadOrEpicId) {
+  const { rootId } = resolveThread(root, threadOrEpicId);
+  const dir = path.join(root, 'epics');
+  if (!fs.existsSync(dir)) return [rootId];
+  const depth = new Map();
+  const members = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!e.isDirectory() || !isValidEpicId(e.name) || !fs.existsSync(path.join(dir, e.name, 'epic.md'))) continue;
+    const rt = resolveThread(root, e.name); // one walk per member (not per comparison)
+    if (rt.rootId !== rootId) continue;
+    members.push(e.name);
+    depth.set(e.name, rt.chain.length);
+  }
+  // Genesis-first by depth, then a STABLE, machine-independent tie-break (id order) so the resolver is
+  // deterministic across filesystems even when two epics sit at the same depth (a branch).
+  return members.sort((a, b) => (depth.get(a) - depth.get(b)) || a.localeCompare(b));
+}
+
+// Compose the CURRENT authoritative source per artifact base across a thread: the LATEST epic in the
+// chain that actually RE-AUTHORED it (did NOT list it in `inherits`). Genesis owns everything; a later
+// change-epic shadows only what it re-authored. Returns { <base>: <owning epic id> } — the source-of-
+// truth map AI/humans read for the next change (rendered by yad-timeline as thread-resolved.md).
+export const THREAD_ARTIFACT_BASES = ['epic', 'architecture', 'contract', 'ui-design', 'stories', 'test-cases'];
+// REPLACE bases — a re-author supersedes the prior version wholesale, so the LATEST re-author owns it
+// (a contract-surface change re-locks and replaces; a re-authored architecture supersedes the old one).
+const REPLACE_BASES = ['epic', 'architecture', 'contract', 'ui-design'];
+// ADDITIVE bases — each re-authoring epic CONTRIBUTES (stories add files; a change adds its test-cases
+// file), so the current truth is the UNION of contributors, never a single owner. Collapsing these to
+// one epic would drop the parent's inherited stories/cases.
+const ADDITIVE_BASES = ['stories', 'test-cases'];
+
+// The owning epic per artifact base across a thread. REPLACE bases resolve to a single epic id (the
+// latest re-author); ADDITIVE bases resolve to the ordered LIST of every epic that re-authored them
+// (genesis-first) — use resolveCurrentStories for story-id-level ownership of the composed set.
+export function resolveCurrentArtifacts(root, threadOrEpicId) {
+  const members = threadEpics(root, threadOrEpicId); // genesis-first
+  const out = {};
+  for (const b of REPLACE_BASES) out[b] = null;
+  for (const b of ADDITIVE_BASES) out[b] = [];
+  for (const id of members) {
+    const { inherits } = epicLineage(root, id);
+    for (const b of REPLACE_BASES) if (!inherits.includes(b)) out[b] = id;
+    for (const b of ADDITIVE_BASES) if (!inherits.includes(b)) out[b].push(id);
+  }
+  return out;
+}
+
+// Compose the current STORY SET at story-id granularity across the thread: each re-authoring epic's
+// stories/ files are overlaid (a later same-id supersedes; a `supersedes:` entry retires a parent
+// story). Returns { <story-id>: <owning epic id> } — the real current truth for stories, because a
+// change-epic re-authors only the stories it changes and inherits the rest by reference. Without this,
+// a defect-fix that adds one regression story would appear to drop every unchanged parent story.
+export function resolveCurrentStories(root, threadOrEpicId) {
+  const members = threadEpics(root, threadOrEpicId); // genesis-first
+  const owner = {};
+  for (const id of members) {
+    const lin = epicLineage(root, id);
+    for (const sid of lin.supersedes) delete owner[sid]; // explicitly retired parent stories
+    if (lin.inherits.includes('stories')) continue; // inherited wholesale -> contributes nothing new
+    const sdir = path.join(epicRoot(root, id), 'stories');
+    if (!fs.existsSync(sdir)) continue;
+    for (const f of fs.readdirSync(sdir).filter((x) => /\.md$/.test(x))) {
+      owner[f.replace(/\.md$/, '')] = id; // contribute / override same-id
+    }
+  }
+  return owner;
+}
+
 export { writeJSON };

package/cli/gate.mjs

@@ -11,7 +11,7 @@ import { PROJECT_FILES } from './manifest.mjs';
 import {
   epicRoot, loadLedger, findReviewStep, artifactBase, artifactHash, gatePredicate,
   advanceState, markInReview, isEscalated, parseReviewBranch, artifactFromBase,
-  upsertHubPr,
+  upsertHubPr, DISCOVERY_FILES,
 } from './epic-state.mjs';
 import { readPr, mapApprovers, createPr, reviewersForScopes, resolveCommitterLogin } from './platform.mjs';
 import { syncStatuses } from './artifact-status.mjs';
@@ -48,7 +48,12 @@ export function touchedDomains(epicDir, step) {
   return frontmatter(path.join(epicDir, 'epic.md')).repos || [];
 }
 
-const ownerOf = (epicDir) => frontmatter(path.join(epicDir, 'epic.md')).owner || '<owner>';
+// The artifact owner shown in the review PR/MR body. Feature epics carry it in epic.md; the discovery
+// front-zero (EP-discovery) has no epic.md, so fall back to roadmap.md's frontmatter owner.
+const ownerOf = (epicDir) =>
+  frontmatter(path.join(epicDir, 'epic.md')).owner
+  || frontmatter(path.join(epicDir, 'roadmap.md')).owner
+  || '<owner>';
 
 // A null architecture hash with a BEGIN marker present means the surface block is malformed
 // (no END, or empty) — approvals would not be hash-bound, so make that visible.
@@ -61,6 +66,16 @@ function warnUnlockedContract(epicDir, artifact) {
   }
 }
 
+// A null discovery hash means the discovery set is incomplete (a required artifact is missing), so the
+// review is not yet reviewable and an approval would not be hash-bound. Name the missing files so the
+// owner can complete the set before the gate is opened/advanced (mirrors warnUnlockedContract).
+function warnIncompleteDiscovery(epicDir, artifact) {
+  if (artifactBase(artifact) !== 'discovery') return;
+  if (artifactHash(epicDir, artifact) !== null) return;
+  const missing = DISCOVERY_FILES.filter((f) => !fs.existsSync(path.join(epicDir, f)));
+  warn(`discovery set incomplete — missing ${missing.join(', ')}; review is not yet reviewable (approvals will not be hash-bound until the full set exists)`);
+}
+
 // Fail fast on a corrupt or wrong-shape hub config: a silently-defaulted hub.json would degrade
 // every gate to file-only without anyone noticing, and a typo'd platform would read as "no bridge".
 function loadHub(root) {
@@ -202,6 +217,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, l
 
     const curHash = artifactHash(epicDir, pr.artifact);
     warnUnlockedContract(epicDir, pr.artifact);
+    warnIncompleteDiscovery(epicDir, pr.artifact);
     const recs = mapApprovers(pull.reviews, { roster, repos, touchedDomains: domains, headOid: pull.headOid });
     approvals = upsertBridge(approvals, recs, { stepId: step.id, artifact: pr.artifact, curHash, today });
 
@@ -465,6 +481,7 @@ export async function gateOpen(root, { epic, artifact, head, creator = createPr
   const branch = head || `review/${epic}/${b}`;
   const domains = touchedDomains(epicDir, step);
   warnUnlockedContract(epicDir, artifact);
+  warnIncompleteDiscovery(epicDir, artifact);
 
   const bridge = isBridge(hub);
   // Outside bridge mode (file-only, OR a platform with no gate-sync CI) there is no CI to write the