yadflow 2.16.1 → 2.17.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.17.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.16.1...v2.17.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))
+* **discovery:** add yad-discovery project front-zero phase ([#82](https://github.com/abdelrahmannasr/yadflow/issues/82)) ([4bb2a92](https://github.com/abdelrahmannasr/yadflow/commit/4bb2a928ea37cbd7d7b21f7c28a96a20492f527e))
 
 # [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. |
@@ -150,7 +152,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 +206,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 31)
 
 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 +276,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
@@ -423,6 +436,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 +485,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/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/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(/\/$/, '')));
 }
 
@@ -221,6 +251,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 +281,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 +296,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 +319,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';

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

package/cli/manifest.mjs

@@ -10,8 +10,9 @@ import { readFileSync } from 'node:fs';
 const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const VERSION = version;
 
-// The 30 hand-authored yad-* skills (mirrors skills/sdlc/install.sh).
+// The hand-authored yad-* skills (mirrors skills/sdlc/install.sh).
 export const SKILLS = [
+  'yad-discovery',
   'yad-analysis',
   'yad-epic',
   'yad-architecture',

package/cli/next.mjs

@@ -1,6 +1,6 @@
 // `yad next` — the unified next-step driver. Read-only: it never writes state or acts. It reads the
 // file ledger and prints the ONE concrete, copy-pasteable next action (and a one-line why), so a user
-// never has to remember which of the 30 skills / gate commands comes next. "Guide, don't act" — the
+// never has to remember which of the 31 skills / gate commands comes next. "Guide, don't act" — the
 // front half still never auto-advances.
 //
 //   yad next                  general orientation across the whole project
@@ -11,7 +11,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { c, log, ok, info, warn, hand, fail, readJSON, exists } from './lib.mjs';
 import { PROJECT_FILES } from './manifest.mjs';
-import { epicRoot, loadLedger, nextAction, preconditionsMet, isValidEpicId } from './epic-state.mjs';
+import { epicRoot, loadLedger, nextAction, preconditionsMet, isValidEpicId, DISCOVERY_EPIC } from './epic-state.mjs';
 
 // Is solo mode on? Persisted in hub.json by setup (Phase C/D); default false. Read defensively so a
 // missing/old hub.json never breaks the driver.
@@ -47,6 +47,8 @@ function actionLine(a, { solo } = {}) {
       return `${c.bold(a.command)}${solo ? c.dim('   (solo: no approval needed — just merge your own PR)') : ''}`;
     case 'build':
       return `${c.bold('yad-run')} ${c.dim('(or per story: yad-spec → yad-implement → yad ship → yad-engineer-review)')}`;
+    case 'discovery-done':
+      return `invoke the ${c.bold('yad-epic')} skill ${c.dim('(seed a feature epic from roadmap.md)')}`;
     default:
       return c.dim('nothing to do');
   }
@@ -67,23 +69,36 @@ function generalNext(root, { all } = {}) {
     hand(`run ${c.bold('yad setup')} ${c.dim('(then come back to `yad next`)')}`);
     return;
   }
-  const epics = listEpics(root);
-  if (!epics.length) {
-    const brownfield = profileOf(root)?.codebase === 'brownfield';
-    log(`\n  ${c.bold('Set up — no epics yet.')}`);
+  const solo = isSolo(root);
+  const brownfield = profileOf(root)?.codebase === 'brownfield';
+  // The project front-zero (EP-discovery / "epic zero") is not a feature epic — split it out so it is
+  // surfaced on its own line and never mixed into the feature-epic roll-up.
+  const allEpics = listEpics(root);
+  const hasDiscovery = allEpics.includes(DISCOVERY_EPIC);
+  const featureEpics = allEpics.filter((id) => id !== DISCOVERY_EPIC);
+  const discoveryAction = hasDiscovery
+    ? nextAction(loadLedger(epicRoot(root, DISCOVERY_EPIC)), { epic: DISCOVERY_EPIC })
+    : null;
+  const discoveryOpen = !!discoveryAction && discoveryAction.kind !== 'discovery-done';
+
+  if (!featureEpics.length) {
+    if (discoveryOpen) { printAction(discoveryAction, { solo }); return; }
+    log(`\n  ${c.bold('Set up — no feature epics yet.')}`);
     if (brownfield) hand(`capture what already exists first: invoke the ${c.bold('yad-backfill')} skill`);
-    hand(`start your first epic: invoke the ${c.bold('yad-epic')} skill`);
+    if (!hasDiscovery) hand(`frame the whole project (market, feasibility, roadmap): invoke the ${c.bold('yad-discovery')} skill ${c.dim('(optional front-zero)')}`);
+    hand(`start your first epic: invoke the ${c.bold('yad-epic')} skill${hasDiscovery ? c.dim(' (it reads the approved roadmap.md)') : ''}`);
     return;
   }
-  const solo = isSolo(root);
-  const actions = epics.map((id) => nextAction(loadLedger(epicRoot(root, id)), { epic: id }));
 
-  if (epics.length === 1 || all) {
+  const actions = featureEpics.map((id) => nextAction(loadLedger(epicRoot(root, id)), { epic: id }));
+  if (discoveryOpen) printAction(discoveryAction, { solo });   // an unfinished discovery comes first
+
+  if (featureEpics.length === 1 || all) {
     for (const a of actions) printAction(a, { solo });
     return;
   }
   // Several epics — list each with a one-liner, then point at the per-epic / --all views.
-  log(`\n  ${c.bold(`${epics.length} epics`)} ${c.dim('— next action each:')}`);
+  log(`\n  ${c.bold(`${featureEpics.length} epics`)} ${c.dim('— next action each:')}`);
   for (const a of actions) log(`    ${c.cyan(a.epicId)}  ${actionLine(a, { solo })}`);
   info(c.dim(`detail: ${c.bold('yad next <epic>')}  •  all at once: ${c.bold('yad next --all')}`));
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yadflow",
-  "version": "2.16.1",
-  "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo). A BMAD module + 30 yad-* skills.",
+  "version": "2.17.0",
+  "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo). A BMAD module + 31 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",
   "license": "MIT",

package/skills/sdlc/config.yaml

@@ -10,6 +10,19 @@ methodology: gated-team-multirepo-sdlc
 product_root: "{project-root}"
 epics_folder: "{project-root}/epics"
 
+# Project discovery (yad-discovery) — the OPTIONAL front-zero, run once per project (greenfield AND
+# brownfield). It is modelled as the reserved "epic zero" `EP-discovery` so the entire review gate +
+# PR/MR bridge + CI sync + `yad next` operate on it unchanged. A 2-step author→review chain whose
+# review binds to the whole artifact set; on approval it terminates at `discovery-done` (no build half).
+# Output: a phased roadmap (incl. MVP) that each feature epic reads (yad-epic Step 2c) — reference-only,
+# never auto-seeds epics.
+discovery:
+  epic_id: "EP-discovery"                              # reserved id; yad-epic/yad-analysis never pick it
+  location: "{project-root}/epics/EP-discovery/"       # discovery artifacts + ledger live here
+  optional: true                                       # skip-able; a team that knows what to build starts at yad-epic
+  modes: [greenfield, brownfield]                       # current-state is code-aware in brownfield; competitor study in both
+  artifacts: [market-research.md, competitor-analysis.md, current-state.md, feasibility.md, requirements.md, roadmap.md]
+
 # Core configuration values (inherited convention from _bmad/config.toml).
 project_name: yadflow
 communication_language: English
@@ -20,11 +33,12 @@ output_folder: "{project-root}/_bmad-output"
 defaults:
   assistance: review          # none | review | heavy
   automation: human_approve   # human_approve | machine_advance
-  # Front steps (analysis [optional], epic, architecture, ui-design, stories, test-cases) are locked to
-  # human_approve and may NOT be set to machine_advance in this version (build plan §1, §8.7).
+  # Front steps (discovery [optional front-zero], analysis [optional], epic, architecture, ui-design,
+  # stories, test-cases) are locked to human_approve and may NOT be set to machine_advance in this
+  # version (build plan §1, §8.7).
   front_steps_locked: true
   # Each front authoring step opens its own branch at the start of the step (the <step> is the step id:
-  # analysis | epic | architecture | ui-design | stories | test-cases). Git/greenfield-safe; distinct
+  # discovery | analysis | epic | architecture | ui-design | stories | test-cases). Git/greenfield-safe; distinct
   # from the bridge's review branch (hub.artifact_branch). See yad-epic/references/state-schema.md.
   front_authoring_branch: "<step>/EP-<slug>"
 
@@ -238,7 +252,7 @@ automation:
   # Hard lock — the dial-setter REFUSES machine_advance for these, regardless of trust evidence.
   # The front authoring steps (already locked:true in state.json; analysis is optional) + the human
   # merge gate.
-  locked_steps: [analysis, epic, architecture, ui-design, stories, test-cases, engineer-review]
+  locked_steps: [discovery, analysis, epic, architecture, ui-design, stories, test-cases, engineer-review]
   # Kill switch (phase-4-build-plan.md §Safety): true => every step forced to human_approve
   # system-wide, no per-step edits. One line, instantly reversible. Toggle via `yad-run action: kill`.
   kill_switch: false

package/skills/sdlc/install.sh

@@ -11,7 +11,7 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$ROOT"
 
-SKILLS=(yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-sync-repos yad-connect-design yad-connect-testing yad-connect-learning yad-connect-docs yad-docs yad-docs-overview yad-docs-sync yad-learn yad-spec yad-implement yad-checks yad-pr-template yad-review-comments yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-status)
+SKILLS=(yad-discovery yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-sync-repos yad-connect-design yad-connect-testing yad-connect-learning yad-connect-docs yad-docs yad-docs-overview yad-docs-sync yad-learn yad-spec yad-implement yad-checks yad-pr-template yad-review-comments yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-status)
 
 echo "Installing sdlc module from $ROOT/skills ..."
 

package/skills/sdlc/module-help.csv

@@ -1,4 +1,5 @@
 module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+SDLC Workflow,yad-discovery,Project Discovery,DI,"Optional front-zero (once per project, greenfield AND brownfield): with the analyst + pm run market research, a competitor study, a feasibility study, and (brownfield) a current-state study, then distil functional + non-functional requirements and a phased roadmap (MVP and beyond) under the reserved EP-discovery. roadmap.md becomes the menu of features each yad-epic reads. Never auto-advances.",,{idea: one-line product idea} {mode: greenfield|brownfield},0-front,,yad-review-gate,false,epics/EP-discovery/,market-research.md competitor-analysis.md current-state.md feasibility.md requirements.md roadmap.md state.json
 SDLC Workflow,yad-analysis,Author Analysis,AN,"Optional front state: with the analyst pressure-test a feature idea and write the discovery brief into analysis.md. Assigns the EP-<slug> ID and seeds .sdlc state (the chain that puts analysis before epic). If skipped, the epic step does this shaping inline. Never auto-advances.",,{idea: one-line feature idea},1-front,,yad-review-gate,false,epics/EP-<slug>/,analysis.md state.json
 SDLC Workflow,yad-epic,Author Epic,AE,"Front state 1: shape an idea with analyst then pm into epic.md; assign EP-<slug> ID and seed .sdlc state. Never auto-advances.",,{idea: one-line feature idea},1-front,,yad-review-gate,true,epics/EP-<slug>/,epic.md state.json
 SDLC Workflow,yad-review-gate,Team Review Gate,RG,"Reusable review+approve gate for all five reviews. Shares an artifact for review, records comments and approvals as files, enforces owner + 1 reviewer (escalates on contract/auth/payments; per-repo routing for stories), advances state only when approved.",,{artifact: file under the epic} {action: open|comment|approve|advance},1-front,,,true,epics/EP-<slug>/reviews/,reviews/*.md approvals.json state.json

package/skills/yad-analysis/SKILL.md

@@ -50,9 +50,20 @@ connected repo** (the epic's `repos` are not chosen yet), load the lightweight c
   stamp `code-context: stale` in the frontmatter.
 - **Traceability:** record which maps you loaded in the analysis frontmatter `code-context:` field.
 
+### Step 2c — Read the project roadmap (project context, only once discovery is APPROVED)
+Consume the project front-zero (`yad-discovery`) **only after its review gate has passed** — never a
+draft or in-review roadmap (that would bypass `discovery-review`). Gate on the **state**, not file
+existence: read `{project-root}/epics/EP-discovery/.sdlc/state.json` and proceed **only when
+`currentStep == "discovery-done"`**. When it is, read its `roadmap.md` and sibling `requirements.md`
+for the project framing: which phase (MVP / later) this feature belongs to and the requirements it
+carries — so the analysis's **Problem / Options / Recommendation** stay consistent with the approved
+roadmap. **Optional & non-blocking:** if there is no discovery, or it has not yet reached
+`discovery-done`, proceed unchanged — do not consume an unapproved roadmap.
+
 ### Step 3 — Generate the Epic ID (engine-assigned, never by hand)
 Derive `EP-<slug>` where `slug` is **2–4 lowercase words joined by hyphens**, drawn from the idea
-(e.g. `EP-istifta-inquiries`). Lowercase except the fixed `EP` prefix. **The ID is assigned once and
+(e.g. `EP-istifta-inquiries`). Lowercase except the fixed `EP` prefix. `EP-discovery` is **reserved**
+for the project front-zero — never use it for a feature. **The ID is assigned once and
 never renamed** — renaming breaks every downstream link (build plan §6b). Check
 `{project-root}/epics/` for collisions; if the slug exists, append a distinguishing word.
 

package/skills/yad-discovery/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: yad-discovery
+description: 'Optional front-zero of the gated SDLC — the once-per-project discovery phase. With the field-expert lenses (analyst + pm), run market research, a competitor study, a feasibility study, and (brownfield) a current-state study, then distil a functional + non-functional requirements list and a phased roadmap (MVP and beyond) into the reserved EP-discovery. Greenfield AND brownfield. Its roadmap.md becomes the menu of features each yad-epic reads. Seeds the EP-discovery state and hands off to the team review gate; never auto-advances. Use when the user says "start the project", "do discovery", "market research / feasibility / roadmap", or "what should we build first".'
+---
+
+# SDLC — Project Discovery (optional front-zero, "epic zero")
+
+**Goal:** Produce a human-authored, AI-assisted **project-level discovery set** — the field expert's
+requirement-gathering for the whole product — under the reserved `EP-discovery` ("epic zero"), then
+hand off to `yad-review-gate`. The output `roadmap.md` is the menu of features; each feature is later
+taken into the normal `yad-epic` flow, which reads the roadmap for project context.
+
+This is a **front state**: human-authored with AI assist and **never auto-advances**. It runs **once
+per project** and is **optional** — a team that already knows what to build can skip it and start at
+`yad-epic`. It supports **both greenfield and brownfield**, and produces a **competitor study in both**.
+
+This skill enforces the build plan's core rules: all state lives in files; IDs are engine-assigned
+(the reserved `EP-discovery`, never a typed feature slug); front steps are locked to `human_approve`.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory.
+- Discovery artifacts live under `{project-root}/epics/EP-discovery/` (the reserved "epic zero").
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## On Activation
+
+### Step 1 — Entry guard (runs once per project)
+The id is the reserved `EP-discovery` — never a feature slug. Discovery seeds its state exactly once:
+if `{project-root}/epics/EP-discovery/.sdlc/state.json` already exists, **STOP** and point the user at
+`yad next EP-discovery` (the phase is in review or done; edit the artifacts in place, don't re-seed).
+When no `state.json` exists yet, proceed and seed state in Step 5.
+
+Detect the project mode from `{project-root}/.sdlc/hub.json` `profile.codebase`
+(`greenfield` | `brownfield`, set by `yad setup`). If absent, ask the user; default `greenfield`.
+
+### Step 2 — Shape with the field-expert lenses (assist: analyst + pm)
+Adopt the **analyst** lens (`bmad-agent-analyst`, Mary) and the **pm** lens (`bmad-agent-pm`) to gather
+requirements as a domain expert would. Drive the existing BMAD research skills as the assist — they
+already exist in this project:
+- `bmad-market-research` — market size, segments, demand, trends, positioning.
+- `bmad-domain-research` — the problem domain, regulations, and constraints of the field.
+- `bmad-product-brief` — personas, value proposition, success metrics.
+
+Pressure-test: who are the users, what problem, what is the market, **who are the competitors and how
+do we differ** (required in BOTH modes), what is feasible, what is the smallest valuable slice (MVP),
+and what sequences after it.
+
+### Step 2b — Brownfield current-state (make discovery code-aware)
+Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **every
+connected repo**, load the lightweight code-map `{project-root}/.sdlc/code-context/<repo>/code-map.md`
+and base `current-state.md` on **what already exists** — modules, endpoints, data, gaps — so the
+roadmap extends the real system rather than re-proposing it.
+
+- **Greenfield-safe:** if `repos.json` is absent/empty (greenfield), `current-state.md` is a short
+  "clean slate / assumptions & non-goals" note, and you proceed.
+- **Staleness:** if a repo's current HEAD (`git -C <path> rev-parse HEAD`) ≠ its registry `syncedHead`,
+  warn and suggest `yad repo refresh <repo>` (a human decision — flag, never auto-refresh).
+- **Backfill pointer:** for an existing codebase, point the user at `yad-backfill` to capture specs for
+  already-built features; discovery frames the *forward* roadmap, backfill captures the *current* one.
+
+### Step 3 — Open the authoring branch
+Open the discovery authoring branch `discovery/EP-discovery` per the shared procedure
+(`../yad-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if
+`{project-root}` is not a git work tree), check out the branch if it exists, else create it from the
+hub's default branch. Author and commit the discovery set on it. Distinct from the bridge's
+`review/EP-discovery/discovery` branch.
+
+### Step 4 — Write the discovery set
+Write these files under `{project-root}/epics/EP-discovery/`. Each is a normal Markdown artifact; the
+gate binds to the **whole set** (editing any one revokes approvals). `roadmap.md` summarises and links
+the others and is the spine of the review.
+
+- `market-research.md` — market, segments, demand, trends (assist: `bmad-market-research`).
+- `competitor-analysis.md` — competitors, capabilities, gaps, our differentiation (**both modes**).
+- `current-state.md` — brownfield: what exists today (Step 2b); greenfield: clean-slate assumptions.
+- `feasibility.md` — technical/operational/economic feasibility, risks, viability, go/no-go.
+- `requirements.md` — the consolidated requirements list, **functional AND non-functional**, as a
+  table (see `references/discovery-schema.md`). Functional rows are candidate features (registration,
+  login, …); non-functional rows are cross-cutting (performance, security, accessibility, i18n …).
+- `roadmap.md` — the phased plan with an explicit **MVP** phase, then later phases. Each feature row
+  carries a proposed `EP-<slug>` id, its target phase, and a `status:` of `planned`
+  (see `references/discovery-schema.md` for the exact templates).
+
+Leave `owner` for the user to set in each frontmatter. Fill the bodies with the user.
+
+### Step 5 — Seed the state machine
+Create `{project-root}/epics/EP-discovery/.sdlc/state.json` describing the **2-step** front-zero
+sequence, both steps `automation: human_approve` and `locked`, with the `kind: "discovery"` marker the
+engine keys off. Use this exact shape (see `references/discovery-schema.md`):
+
+```json
+{
+  "epicId": "EP-discovery",
+  "kind": "discovery",
+  "createdAt": "<YYYY-MM-DD>",
+  "currentStep": "discovery-review",
+  "steps": [
+    { "id": "discovery",        "type": "author",         "artifact": "discovery/", "assistance": "review", "automation": "human_approve", "locked": true, "status": "done",      "risk_tags": [] },
+    { "id": "discovery-review", "type": "review+approve", "artifact": "discovery/", "assistance": "review", "automation": "human_approve", "locked": true, "status": "in_review", "risk_tags": [] }
+  ]
+}
+```
+
+Notes:
+- The review step's artifact is the virtual base `discovery/` — the gate fingerprints the whole
+  discovery file set (`market-research`, `competitor-analysis`, `current-state`, `feasibility`,
+  `requirements`, `roadmap`), so editing any of them revokes prior approvals (mirrors `stories/`).
+  **All six must exist to review:** if any is missing the set is incomplete and non-reviewable (the
+  hash is `null`) and `yad gate open`/`sync` warn — so write all six (Step 4) before the gate.
+- `discovery-review` carries no `risk_tags` — it is the **base** rule (owner + 1 reviewer); discovery
+  never escalates to domain owners (no contract surface is touched yet).
+- Also create an empty approvals ledger `.sdlc/approvals.json` and comments ledger
+  `.sdlc/comments.json`, each containing `[]`, and the `reviews/` directory.
+
+### Step 6 — Stop at the gate (do NOT advance)
+Report: the path to the discovery set, and that the next action is **review** via `yad-review-gate`
+(base rule: owner + 1 reviewer) on the virtual artifact `discovery/`. **Never mark discovery-review
+approved here** — only real reviewers do that through the gate. When the discovery gate passes, the
+state moves to the `discovery-done` sentinel (not `ready-for-build` — discovery has no build half); the
+roadmap is now the input that each `yad-epic` reads (its "Step 2c — read the roadmap"). When the hub
+has a platform, the gate opens a review PR on the hub (via `yad-hub-bridge`) and
+`yad-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review
+is recorded file-only.
+
+## Reference
+- Discovery artifact templates + the 2-step state shape: `references/discovery-schema.md`.
+- State schema, chain shapes, and the authoring-branch procedure:
+  `../yad-epic/references/state-schema.md`.
+- The epic step that consumes `roadmap.md`: `../yad-epic/SKILL.md` (Step 2c).
+- Capturing already-built features in a brownfield codebase: `../yad-backfill/SKILL.md`.
+- Connecting code repos + the code-context the brain reads: `../yad-connect-repos/SKILL.md`.

package/skills/yad-discovery/references/discovery-schema.md

@@ -0,0 +1,106 @@
+# Discovery schema — artifacts + the front-zero state shape
+
+The project discovery phase ("epic zero") lives under `{project-root}/epics/EP-discovery/`. It reuses
+the per-epic ledger files (`.sdlc/state.json`, `approvals.json`, `comments.json`, `reviews/`,
+`hub-prs.json`) unchanged — `EP-discovery` is a valid epic id, so the existing gate, PR/MR bridge, CI
+sync, and `yad next` all operate on it. What is special is the `kind: "discovery"` marker on the state
+object and the 2-step chain.
+
+## State (`.sdlc/state.json`)
+
+```json
+{
+  "epicId": "EP-discovery",
+  "kind": "discovery",
+  "createdAt": "<YYYY-MM-DD>",
+  "currentStep": "discovery-review",
+  "steps": [
+    { "id": "discovery",        "type": "author",         "artifact": "discovery/", "assistance": "review", "automation": "human_approve", "locked": true, "status": "done",      "risk_tags": [] },
+    { "id": "discovery-review", "type": "review+approve", "artifact": "discovery/", "assistance": "review", "automation": "human_approve", "locked": true, "status": "in_review", "risk_tags": [] }
+  ]
+}
+```
+
+- `artifact: "discovery/"` is a **virtual** base: `artifactHash` fingerprints the whole discovery file
+  set (`discoveryHash` in `cli/epic-state.mjs`), so an edit to any discovery file revokes prior
+  approvals — exactly like `stories/` fingerprints the stories directory.
+- The **full set is required to review**: if any of the six files is missing, `discoveryHash` returns
+  `null` — the discovery is **incomplete and non-reviewable** (no hash to bind an approval to), and
+  `yad gate open` / `yad gate sync` warn with the missing filenames. Write all six (in greenfield,
+  `current-state.md` is a short clean-slate note) before handing off to the gate.
+- On approval the gate sets `currentStep: "discovery-done"` (a terminal sentinel — discovery has **no**
+  build half, so it never becomes `ready-for-build`).
+- The discovery files (relative to the epic dir) the gate commits on the review branch and re-hashes at
+  merge are: `market-research.md`, `competitor-analysis.md`, `current-state.md`, `feasibility.md`,
+  `requirements.md`, `roadmap.md` (the `DISCOVERY_FILES` list).
+
+## Artifact templates
+
+### `requirements.md`
+
+```markdown
+---
+id: EP-discovery
+artifact: requirements
+status: draft
+owner:
+---
+
+## Functional requirements
+<!-- candidate features — each becomes (or seeds) a feature epic later -->
+
+| Ref | Requirement | Description | Priority | MVP? |
+|-----|-------------|-------------|----------|------|
+| F-01 | Registration | A new user can create an account | must | yes |
+| F-02 | Login | A returning user can authenticate | must | yes |
+
+## Non-functional requirements
+<!-- cross-cutting qualities the whole product must hold -->
+
+| Ref | Category | Requirement | Target / acceptance |
+|-----|----------|-------------|---------------------|
+| N-01 | Performance | p95 page load | < 2s on 4G |
+| N-02 | Security | auth + data-at-rest | OWASP ASVS L1; encrypted at rest |
+| N-03 | Accessibility | WCAG conformance | AA |
+```
+
+### `roadmap.md` (the spine of the review)
+
+```markdown
+---
+id: EP-discovery
+artifact: roadmap
+status: draft
+owner:
+---
+
+## Summary
+<!-- the product thesis in 2–3 lines; links to market-research, competitor-analysis,
+     current-state, feasibility, requirements -->
+
+## Phase 1 — MVP
+<!-- the smallest valuable slice; the features here are built first -->
+
+| Feature | Proposed epic id | Requirements | Status |
+|---------|------------------|--------------|--------|
+| Registration | EP-registration | F-01 | planned |
+| Login | EP-login | F-02 | planned |
+
+## Phase 2 — <name>
+| Feature | Proposed epic id | Requirements | Status |
+|---------|------------------|--------------|--------|
+| … | EP-… | F-… | planned |
+
+## Later / parked
+<!-- explicitly deferred, with why -->
+```
+
+Per-feature `status:` lifecycle (set by hand): `planned` → `epic-started` (a feature epic has been
+seeded with `yad-epic`) → `shipped`. The proposed `EP-<slug>` ids are suggestions for the eventual
+`yad-epic` runs — `yad-epic` still assigns the id (and skips the reserved `EP-discovery`).
+
+The other four artifacts (`market-research.md`, `competitor-analysis.md`, `current-state.md`,
+`feasibility.md`) are free-form Markdown with a `--- id / artifact / status / owner ---` frontmatter
+block matching the two above. `competitor-analysis.md` is required in BOTH greenfield and brownfield;
+`current-state.md` is the substantive code-aware study in brownfield and a short clean-slate note in
+greenfield.

package/skills/yad-docs-overview/references/pipeline-model.md

@@ -32,6 +32,18 @@ and never gates.
 | `yad-connect-learning` | `learning.json` |
 | `yad-connect-docs` | `docs.json` |
 
+### Path: Front-zero (`phase: 0-front`)
+The OPTIONAL once-per-project discovery phase, modelled as the reserved "epic zero" `EP-discovery`.
+Greenfield AND brownfield; a 2-step author→review chain whose review binds to the whole artifact set
+and terminates at `discovery-done` (no build half).
+
+| Step (skill) | Gate | Outputs / sideEffects |
+|--------------|------|------------------------|
+| `yad-discovery` *(optional)* | → `discovery-review` (base rule) | `market-research.md`, `competitor-analysis.md`, `current-state.md`, `feasibility.md`, `requirements.md`, `roadmap.md`; seeds `EP-discovery/.sdlc/state.json` |
+
+`roadmap.md` is the menu of features each `yad-epic` reads (Step 2c) — reference-only, never
+auto-seeds epics.
+
 ### Path: Front half (`phase: 1-front`)
 The gated authoring chain + the reusable review gate (10 steps, or 12 with the optional analysis).
 
@@ -85,8 +97,8 @@ The eight yadflow lenses, each to its relevant phase sections + paths:
 
 | Lens | Relevant phases / sections |
 |------|----------------------------|
-| analyst | Setup intent, analysis step, front-half discovery |
-| pm | epic, stories, roadmap; the front gates |
+| analyst | Setup intent, project discovery (front-zero), analysis step, front-half discovery |
+| pm | project discovery (market/feasibility/roadmap), epic, stories; the front gates |
 | architect | architecture + the locked contract; escalation |
 | ux | UI design, design tool connection, the design system |
 | dev | build half: spec → implement, the per-repo loop |

package/skills/yad-epic/SKILL.md

@@ -68,10 +68,23 @@ and let it inform which `repos` the epic should touch.
 - For depth on a specific area not in the map, do a live on-demand read (see `yad-connect-repos`
   `references/code-context.md`) — do not block on it.
 
+### Step 2c — Read the project roadmap (project context, only once discovery is APPROVED)
+Consume the project front-zero (`yad-discovery`) **only after its review gate has passed** — never a
+draft or in-review roadmap (that would bypass `discovery-review`). Gate on the **state**, not file
+existence: read `{project-root}/epics/EP-discovery/.sdlc/state.json` and proceed **only when
+`currentStep == "discovery-done"`**. When it is, read its `roadmap.md` and sibling `requirements.md`
+for the project framing: which phase (MVP / later) this feature belongs to, the functional/non-functional
+requirements it carries, and how it fits the wider plan — so the epic's **Goal / Scope / Acceptance
+signals** stay consistent with the approved roadmap. **Optional & non-blocking:** if there is no
+discovery, or it has not yet reached `discovery-done` (absent / still draft / in-review), proceed
+unchanged — do not consume an unapproved roadmap. After seeding the epic, the matching roadmap row's
+`status:` can be bumped `planned → epic-started` by hand (a human edit; discovery never auto-seeds epics).
+
 ### Step 3 — Generate the Epic ID (engine-assigned, never by hand) — analysis-skipped only
 *(Skip when analysis ran — the ID was already assigned by `yad-analysis`.)*
 Derive `EP-<slug>` where `slug` is **2–4 lowercase words joined by hyphens**, drawn from the idea
-(e.g. `EP-istifta-inquiries`). Lowercase except the fixed `EP` prefix. **The ID is assigned once and
+(e.g. `EP-istifta-inquiries`). Lowercase except the fixed `EP` prefix. `EP-discovery` is **reserved**
+for the project front-zero — never use it for a feature. **The ID is assigned once and
 never renamed** — renaming breaks every downstream link (build plan §6b).
 Check `{project-root}/epics/` for collisions; if the slug exists, append a distinguishing word.