npm - yadflow - Versions diffs - 2.16.0 → 2.17.0 - Mend

yadflow 2.16.0 → 2.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/CHANGELOG.md +2 -2
package/README.md +29 -9
package/bin/yad.mjs +5 -3
package/cli/artifact-status.mjs +6 -1
package/cli/commit.mjs +9 -2
package/cli/epic-state.mjs +66 -4
package/cli/gate.mjs +27 -5
package/cli/manifest.mjs +2 -1
package/cli/next.mjs +26 -11
package/cli/openpr.mjs +78 -6
package/package.json +2 -2
package/skills/sdlc/config.yaml +18 -4
package/skills/sdlc/install.sh +1 -1
package/skills/sdlc/module-help.csv +1 -0
package/skills/yad-analysis/SKILL.md +12 -1
package/skills/yad-checks/templates/github/yad-hub-checks.yml +7 -0
package/skills/yad-commit/SKILL.md +2 -1
package/skills/yad-discovery/SKILL.md +132 -0
package/skills/yad-discovery/references/discovery-schema.md +106 -0
package/skills/yad-docs-overview/references/pipeline-model.md +14 -2
package/skills/yad-epic/SKILL.md +14 -1
package/skills/yad-open-pr/SKILL.md +8 -0
package/skills/yad-ship/SKILL.md +4 -0

package/CHANGELOG.md CHANGED Viewed

@@ -1,9 +1,9 @@
-# [2.16.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.15.0...v2.16.0) (2026-06-25)
+# [2.17.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.16.1...v2.17.0) (2026-06-26)
 ### Features
-* make hub pr-title/pr-template gates branch-aware so tooling PRs pass ([#79](https://github.com/abdelrahmannasr/yadflow/issues/79)) ([68050e0](https://github.com/abdelrahmannasr/yadflow/commit/68050e000010b4d98f304a7e5e1f6a39bc0c229c))
+* **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 CHANGED Viewed

@@ -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. |
@@ -98,8 +100,8 @@ with `npx` from your **product hub** repo — no clone needed.
 | `yad gate status <epic>` | Show each review step and its recorded approvals. |
 | `yad gate ci [--branch <head>] [--pr <n>]` | The CI entry the hub workflow calls on review/merge events: derive the epic/artifact from the `review/EP-*` branch, run the same sync, and commit **only the ledger** to the hub default branch (sweep every open review PR when no `--branch`). |
 | `yad commit --type <t> -m <subject>` | Commit by the SDLC convention — Conventional subject, `Task`/`Contract-Change`/`Co-Authored-By` trailers, atomic-file guard. |
-| `yad open-pr [--repo <name>]` | Open a code-repo **task** PR/MR from the repo's platform template (build half). |
-| `yad ship --type <t> -m <subject>` | Commit **and** open the task PR/MR in one step (`yad commit` then `yad open-pr`). |
+| `yad open-pr [--repo <name>]` | Open a **task** PR/MR from the platform template (build half). **Stage-aware on the hub:** a `review/EP-*` branch opens the front-half artifact-review PR (delegates to `yad gate open`); any other hub branch uses the code-task template (so hub tooling PRs pass the `pr-template` gate). |
+| `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. |
 | `npx yadflow --version` | Print the installed CLI version. |
@@ -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/bin/yad.mjs CHANGED Viewed

@@ -56,8 +56,10 @@ ${c.bold('Review gate (front half)')}
 ${c.bold('Build helpers')}
   yad commit --type <t> -m <subject>   Commit by convention (trailers, atomic guard)
-  yad open-pr [--repo <name>]          Open a code-repo task PR/MR from the template
-  yad ship --type <t> -m <subject>     Commit AND open the task PR/MR in one step
+  yad open-pr [--repo <name>]          Open a task PR/MR — stage-aware on the hub: a review/EP-*
+                                       branch opens the front-half artifact-review PR (delegates to
+                                       gate open), any other hub branch uses the code-task template
+  yad ship --type <t> -m <subject>     Commit AND open the task PR/MR in one step (stage-aware)
   yad repo list                        Show connected repos (fresh / stale)
   yad repo refresh [name]              Re-pack a stale repo (a human decision)
@@ -181,7 +183,7 @@ async function main() {
       // In bridge mode CI is the sole ledger writer: `open` only opens the PR, and local `sync` is
       // advisory (reads the platform, prints status, writes nothing). The artifact status flip is
       // CI's job at merge — never wired into the local gate. File-only mode keeps local writes.
-      if (action === 'open') await gateOpen(o.dir, { epic, artifact, today });
+      if (action === 'open') await gateOpen(o.dir, { epic, artifact });
       else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today, local: true });
       else if (action === 'comments') await gateComments(o.dir, { epic, artifact, today });
       else if (action === 'status') await gateStatus(o.dir, { epic });

package/cli/artifact-status.mjs CHANGED Viewed

@@ -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/commit.mjs CHANGED Viewed

@@ -7,7 +7,7 @@ import fs from 'node:fs';
 import { c, log, ok, info, warn, fail, run, exists } from './lib.mjs';
 import {
   COMMIT_TYPES, AI_COAUTHORS, ATOMIC_FILE_LIMIT,
-  TASK_TRAILER, CONTRACT_CHANGE_TRAILER, COAUTHOR_TRAILER,
+  TASK_TRAILER, CONTRACT_CHANGE_TRAILER, COAUTHOR_TRAILER, PROJECT_FILES,
 } from './manifest.mjs';
 // PURE — unit tested directly. Build the full commit message text.
@@ -51,7 +51,14 @@ export async function runCommit(root, opts = {}) {
   const branch = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: root }).stdout;
   const task = opts.task || taskFromBranch(branch);
-  if (!task) warn('no Task trailer (none given and branch has no -S0N-T0N) — spec-link gate will fail on a code repo');
+  if (!task) {
+    // spec-link is a code-repo gate (REPO_WIRING.common), not a hub gate — so a missing Task trailer
+    // is expected on a hub PR (front-half artifact review or hub tooling) and only matters on a repo.
+    const onHub = exists(path.join(root, PROJECT_FILES.hubConfig));
+    warn(onHub
+      ? 'no Task trailer (none given and branch has no -S0N-T0N) — fine for a hub PR; required on code-repo tasks (spec-link gate)'
+      : 'no Task trailer (none given and branch has no -S0N-T0N) — spec-link gate will fail on a code repo');
+  }
   let message;
   try {

package/cli/epic-state.mjs CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 });
@@ -449,7 +465,11 @@ export async function gateStatus(root, { epic } = {}) {
   }
 }
-export async function gateOpen(root, { epic, artifact } = {}) {
+// `head` overrides the review branch the PR is opened against — `open-pr` delegates here after pushing
+// the user's checked-out branch, which for a per-story review (review/EP-*/stories-S01) does NOT equal
+// the branch this would otherwise recompute (artifactFromBase collapses stories-S01 → stories/). Pass
+// the real pushed head so the PR targets a branch that exists. `creator` is injected in tests.
+export async function gateOpen(root, { epic, artifact, head, creator = createPr } = {}) {
   const { hub } = loadHub(root);
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
@@ -458,9 +478,10 @@ export async function gateOpen(root, { epic, artifact } = {}) {
   const step = findReviewStep(ledger.state, artifact);
   if (!step) { fail(`no review step for ${artifact}`); process.exitCode = 1; return; }
   const b = base(artifact);
-  const branch = `review/${epic}/${b}`;
+  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
@@ -487,7 +508,7 @@ export async function gateOpen(root, { epic, artifact } = {}) {
   const assignees = committer ? [committer] : [];
   const labels = isEscalated(step) ? domains.map((d) => `domain:${d}`) : [];
   info(`opening review ${hub.platform === 'gitlab' ? 'MR' : 'PR'} on branch ${branch} …`);
-  const r = createPr(hub.platform, { title: `review: ${artifact} (${epic})`, body, base: hub.default_branch || 'main', head: branch, reviewers, assignees, labels, cwd: root });
+  const r = creator(hub.platform, { title: `review: ${artifact} (${epic})`, body, base: hub.default_branch || 'main', head: branch, reviewers, assignees, labels, cwd: root });
   if (!r.ok) { warn(`could not open PR (${r.reason || 'unknown'})${bridge ? ' — open it manually; CI records the gate on merge' : '; step is in_review file-only'}`); return; }
   if (!bridge) {
@@ -498,6 +519,7 @@ export async function gateOpen(root, { epic, artifact } = {}) {
   hand(bridge
     ? 'reviewers approve/comment there; CI advances the gate on the default branch when it is merged'
     : `reviewers approve/comment there; then run \`yad gate sync ${epic} ${artifact}\``);
+  return { url: r.url };
 }
 // ---- helpers ------------------------------------------------------------------------------------

package/cli/manifest.mjs CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/cli/openpr.mjs CHANGED Viewed

@@ -8,6 +8,8 @@ import { c, log, ok, info, hand, fail, run, exists, readJSON } from './lib.mjs';
 import { PROJECT_FILES } from './manifest.mjs';
 import { detectPlatform, createPr, reviewersForScopes, resolveCommitterLogin } from './platform.mjs';
 import { taskFromBranch } from './commit.mjs';
+import { parseReviewBranch, artifactFromBase } from './epic-state.mjs';
+import { gateOpen } from './gate.mjs';
 // Resolve the target code repo: --repo <name> from the registry, else --dir, else cwd.
 function resolveRepo(root, { repo, dir }) {
@@ -19,11 +21,59 @@ function resolveRepo(root, { repo, dir }) {
   return { repoRoot: path.resolve(root, dir || '.'), meta: null };
 }
-function templateBody(repoRoot, platform, { task, risk, contract, domains }) {
-  const tplPath = platform === 'gitlab'
-    ? path.join(repoRoot, '.gitlab/merge_request_templates/Default.md')
-    : path.join(repoRoot, '.github/pull_request_template.md');
-  const base = exists(tplPath) ? fs.readFileSync(tplPath, 'utf8') : '## Summary\n\n## Impact & Risk\n';
+// Which SDLC stage is this PR? The hub serves two vehicles; a code repo only one. Mirrors the
+// `--head` split the hub pattern gates (pr-title.sh/pr-template.sh) already apply:
+//   code-repo    — NOT the product hub (a registry repo via --repo, or root is not a hub).
+//   hub-front    — the hub itself AND head is a review/EP-* branch (artifact-review PR).
+//   hub-tooling  — the hub itself AND head is anything else (a tooling/CI change to the hub).
+// `meta` (truthy when resolved from the repos registry via --repo) is a connected code repo, so it is
+// never the hub regardless of its path. Otherwise "is the hub" = repoRoot resolves to root AND root
+// carries .sdlc/hub.json. path.resolve normalises `--dir .` / trailing slashes.
+export function detectStage(root, repoRoot, head, meta) {
+  if (meta) return 'code-repo';
+  const isHub = path.resolve(repoRoot) === path.resolve(root)
+    && exists(path.join(root, PROJECT_FILES.hubConfig));
+  if (!isHub) return 'code-repo';
+  return /^review\/EP-[a-z0-9-]+\//.test(head || '') ? 'hub-front' : 'hub-tooling';
+}
+// The bundled code-task template — the same file `REPO_WIRING` installs into code repos, resolved
+// from the package (mirrors how manifest.mjs reads ../package.json). Used for a hub-tooling PR, whose
+// `.github/pull_request_template.md` is the ARTIFACT-REVIEW template (wrong shape for the code-task
+// hub gate). Falls back to a minimal body that still carries every section the gate requires.
+function codeTaskTemplate(platform) {
+  const rel = platform === 'gitlab'
+    ? '../skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md'
+    : '../skills/yad-pr-template/templates/github/pull_request_template.md';
+  try {
+    return fs.readFileSync(new URL(rel, import.meta.url), 'utf8');
+  } catch {
+    return [
+      '## Summary', '',
+      '## Impact & Risk',
+      '- **Domains / repos touched:** <repo>',
+      '- **Contract surface touched:** no',
+      '- **Risk level:** low',
+      '',
+      '## Checklist',
+      '- [ ] Lint, build, and tests pass (build/test/lint gate)',
+      '',
+    ].join('\n');
+  }
+}
+export function templateBody(repoRoot, platform, { task, risk, contract, domains, stage }) {
+  // hub-tooling: the hub's own template is artifact-review — use the bundled code-task template so the
+  // body matches the shape the hub `pr-template` gate demands for a non-review head.
+  let base;
+  if (stage === 'hub-tooling') {
+    base = codeTaskTemplate(platform);
+  } else {
+    const tplPath = platform === 'gitlab'
+      ? path.join(repoRoot, '.gitlab/merge_request_templates/Default.md')
+      : path.join(repoRoot, '.github/pull_request_template.md');
+    base = exists(tplPath) ? fs.readFileSync(tplPath, 'utf8') : codeTaskTemplate(platform);
+  }
   // Fill the obvious fields; leave the rest of the committed template intact for the author.
   return base
     .replace(/EP-<slug>-S0N-T0N/g, task || 'EP-<slug>-S0N-T0N')
@@ -45,6 +95,28 @@ export async function runOpenPr(root, opts = {}) {
   const baseBranch = opts.base || meta?.default_branch || 'main';
   if (branch === baseBranch) { fail(`on ${baseBranch} — switch to your task branch first`); process.exitCode = 1; return; }
+  const stage = detectStage(root, repoRoot, branch, meta);
+  // hub-front: this is a front-half artifact-review PR (review/EP-*/<artifact> head on the hub). The
+  // artifact-review title, body, and ledger bookkeeping all live in `yad gate open` — delegate to it
+  // rather than emit the code-task shape (which the hub gate would reject). Push first (gateOpen does
+  // not push), then hand off; any --title/--message is dropped (gateOpen sets `review: …`).
+  if (stage === 'hub-front') {
+    const parsed = parseReviewBranch(branch);
+    if (!parsed) { fail(`could not parse review branch '${branch}' (expected review/EP-<slug>/<artifact>)`); process.exitCode = 1; return; }
+    info(`pushing ${branch} …`);
+    const fpush = run('git', ['push', '-u', 'origin', branch], { cwd: repoRoot });
+    if (!fpush.ok) { fail(`git push failed — ${fpush.stderr.split('\n')[0] || 'unknown'}`); process.exitCode = 1; return; }
+    // Pass the branch we just pushed as the head so gateOpen opens the PR against it (its own
+    // recompute would collapse a per-story base). gateOpen signals failure by returning no url —
+    // mirror open-pr's own error contract so `ship` sees the non-zero exit and never reports success.
+    // (On a platform-less hub gateOpen marks the step in_review file-only and returns no url; open-pr's
+    // job is to open a PR, so "no PR opened" is a non-zero outcome here, unlike `yad gate open`.)
+    const res = await gateOpen(root, { epic: parsed.epic, artifact: artifactFromBase(parsed.base), head: branch });
+    if (!res?.url) process.exitCode = 1;
+    return res;
+  }
   // Push the branch (sets upstream) using the user's own auth. Abort on failure — creating a PR for a
   // branch that is not on the remote just fails with a more confusing error.
   info(`pushing ${branch} …`);
@@ -54,7 +126,7 @@ export async function runOpenPr(root, opts = {}) {
   const task = opts.task || taskFromBranch(branch);
   const title = opts.title || run('git', ['log', '-1', '--format=%s'], { cwd: repoRoot }).stdout || `task ${task || branch}`;
   const body = templateBody(repoRoot, platform, {
-    task, risk: opts.risk || 'low', contract: !!opts.contractChange, domains: meta?.name,
+    task, risk: opts.risk || 'low', contract: !!opts.contractChange, domains: meta?.name, stage,
   });
   // Auto-assign from the hub roster, scoped to this repo: assignee = the committer (resolved from

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "yadflow",
-  "version": "2.16.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 + 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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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-checks/templates/github/yad-hub-checks.yml CHANGED Viewed

@@ -9,11 +9,17 @@
 name: yad-hub-checks
 on:
   pull_request:
+    # `edited` (beyond the opened/synchronize/reopened defaults) so a PR title/body correction
+    # re-runs the pattern gates without a close/reopen — e.g. fixing a body the pr-template gate held.
+    types: [opened, synchronize, reopened, edited]
     branches: ["**"]
 jobs:
+  # commit-message + ledger-guard read the commit range, not the PR title/body — skip them on a bare
+  # `edited` event (only pr-title/pr-template need to re-check a title/body fix).
   commit-message:
     runs-on: ubuntu-latest
+    if: github.event.action != 'edited'
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
@@ -52,6 +58,7 @@ jobs:
   # The gate ledger is CI-owned: reject non-bot commits to .sdlc/*.json or reviews/*.md.
   ledger-guard:
     runs-on: ubuntu-latest
+    if: github.event.action != 'edited'
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }

package/skills/yad-commit/SKILL.md CHANGED Viewed

@@ -21,7 +21,8 @@ and `yad-ship` use. It **never auto-advances**; it just commits.
   `feat|fix|docs|refactor|test|perf|build|ci|chore|revert`; proper nouns/acronyms keep their case.
 - **Task trailer** — required on a code repo (anchors the `spec-link` + `commit-message` gates). Given
   with `--task`, else derived from the branch (`feat/<story>-<task>-…`). Hub commits are not
-  task-scoped, so the trailer is optional there.
+  task-scoped, so the trailer is optional there — a missing-Task warning is informational on the hub
+  (`spec-link` is a code-repo gate) and only flags a real gate failure in a code repo.
 - **Contract-Change trailer** — `--contract-change` only when the diff touches the locked contract
   surface; it routes the change back to the architecture gate.
 - **AI co-author footer — OFF by default.** No `Co-Authored-By` trailer is written unless `--ai <id>`

package/skills/yad-discovery/SKILL.md ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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.

package/skills/yad-open-pr/SKILL.md CHANGED Viewed

@@ -22,6 +22,14 @@ the product hub.
   `.gitlab/merge_request_templates/Default.md`) with `Task:`, `Risk level:`, `Contract surface
   touched:`, and `Domains` prefilled; the rest is left for the author. This satisfies the `pr-template`
   gate.
+- **Stage-aware on the product hub** — `open-pr` mirrors the `--head` split the hub gates apply:
+  - a **`review/EP-*/<artifact>`** branch is a front-half artifact-review PR → it **delegates to
+    `yad gate open`** (artifact-review title `review: <artifact> (EP-<slug>)`, the hub artifact-review
+    body, and the gate ledger bookkeeping all in one place). Any `--title`/`-m` is ignored here.
+  - any **other hub branch** is a tooling/CI change → it uses the bundled **code-task** template
+    (`## Summary` / `Risk level:` / `## Checklist`) instead of the hub's artifact-review
+    `pull_request_template.md`, so the hub `pr-template` gate passes.
+  In a code repo nothing changes — it reads the repo's own committed code-task template.
 - **Auto-assign** — from the hub roster scoped to this repo: assignee = the committer (resolved from
   the local git identity), reviewers = the repo's `reviewer`/`domain-owner` logins minus the committer.
   Degrades cleanly when there is no roster.

package/skills/yad-ship/SKILL.md CHANGED Viewed

@@ -22,6 +22,10 @@ its own and **never merges**. The engineer review + merge are Step E (`yad-engin
     roster auto-assign, risk routing (`../yad-open-pr/SKILL.md`).
 - **Order matters:** the PR/MR is opened **only if the commit lands**. A failed commit, a tripped
   atomic guard, or `--dry-run` stops the step before anything is pushed.
+- **Stage-aware on the product hub** (via `yad-open-pr`): on a `review/EP-*` branch `ship` opens the
+  front-half **artifact-review** PR (delegating to `yad gate open` — `--title` is ignored); on any
+  other hub branch it opens the **code-task** PR from the bundled code-task template. In a code repo
+  it is unchanged.
 ## Inputs