yadflow 2.16.1 → 2.18.0

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',
@@ -156,6 +157,9 @@ export const epicFiles = (epicRoot) => ({
   comments: `${epicRoot}/.sdlc/comments.json`,
   hubPrs: `${epicRoot}/.sdlc/hub-prs.json`,
   contractLock: `${epicRoot}/.sdlc/contract-lock.json`,
+  buildLog: `${epicRoot}/.sdlc/build-log.json`,
+  change: `${epicRoot}/.sdlc/change.json`,             // Phase 6 — change/defect intake + triage
+  reconcileDebt: `${epicRoot}/.sdlc/reconcile-debt.json`, // Phase 6 — hotfix ship-first debt
 });
 
 // Per-repo wiring: src is relative to PKG_ROOT, dest relative to the repo root.
@@ -165,6 +169,9 @@ export const REPO_WIRING = {
     { src: 'skills/yad-checks/templates/checks/spec-link.sh', dest: 'checks/spec-link.sh', exec: true },
     { src: 'skills/yad-checks/templates/checks/contract-check.sh', dest: 'checks/contract-check.sh', exec: true },
     { src: 'skills/yad-checks/templates/checks/build-test-lint.sh', dest: 'checks/build-test-lint.sh', exec: true },
+    { src: 'skills/yad-checks/templates/checks/lineage-check.sh', dest: 'checks/lineage-check.sh', exec: true },
+    { src: 'skills/yad-checks/templates/checks/epic-open.sh', dest: 'checks/epic-open.sh', exec: true },
+    { src: 'skills/yad-checks/templates/checks/reconcile-debt-check.sh', dest: 'checks/reconcile-debt-check.sh', exec: true },
     { src: 'skills/yad-checks/templates/checks/verified-commits.sh', dest: 'checks/verified-commits.sh', exec: true },
     { src: 'skills/yad-checks/templates/checks/commit-message.sh', dest: 'checks/commit-message.sh', exec: true },
     { src: 'skills/yad-pr-template/templates/checks/risk-route.sh', dest: 'checks/risk-route.sh', exec: true },

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/cli/thread.mjs

@@ -0,0 +1,174 @@
+// `yad thread` (read-only: print a feature thread + its resolved current artifacts) and
+// `yad reconcile` (Phase 6 change-reconciler: flag orphan drift + open hotfix debt, never a gate —
+// mirrors `yad docs sync`). The hard merge BLOCK is the CI gates (lineage-check / reconcile-debt);
+// this only DISCOVERS, exactly as yad-docs-sync flags and the build gates block. Node built-ins only.
+import path from 'node:path';
+import fs from 'node:fs';
+import { c, log, ok, info, warn, hand, readJSON, exists } from './lib.mjs';
+import {
+  epicRoot, isValidEpicId, epicLineage, readFrontmatter,
+  resolveThread, threadEpics, resolveCurrentArtifacts, resolveCurrentStories, THREAD_ARTIFACT_BASES,
+} from './epic-state.mjs';
+
+// ---- file readers (all derived; no DB) -----------------------------------------------------------
+
+export const loadChange = (root, epic) => readJSON(path.join(epicRoot(root, epic), '.sdlc', 'change.json'), null);
+export const loadDebt = (root, epic) => {
+  const v = readJSON(path.join(epicRoot(root, epic), '.sdlc', 'reconcile-debt.json'), []);
+  return Array.isArray(v) ? v : [];
+};
+export const loadBuildLog = (root, epic) => readJSON(path.join(epicRoot(root, epic), '.sdlc', 'build-log.json'), null);
+
+// An epic is SEALED once every authored story is `shipped` (config.yaml change.seal_on). A sealed epic
+// refuses new behaviour (epic-open.sh) — a further change must open a new threaded change-epic, which is
+// what keeps the front artifacts from going stale. An epic with no stories is NOT sealed (nothing built).
+export function sealedEpic(root, epic) {
+  const dir = path.join(epicRoot(root, epic), 'stories');
+  if (!exists(dir)) return false;
+  const stories = fs.readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && /\.md$/.test(e.name)).map((e) => e.name);
+  if (!stories.length) return false;
+  return stories.every((f) => readFrontmatter(path.join(dir, f)).status === 'shipped');
+}
+
+// The OPEN hotfix debt across a thread (every epic that shares the root). An open entry blocks the next
+// normal change on the thread until paid (reconcile-debt-check.sh enforces; this reports).
+export function openDebtOnThread(root, threadOrEpic) {
+  const out = [];
+  for (const id of threadEpics(root, threadOrEpic)) {
+    for (const d of loadDebt(root, id)) if (d.status === 'open') out.push({ ...d, epicId: d.epicId || id });
+  }
+  return out;
+}
+
+// ---- thread summary (what `yad thread` + yad-status render) --------------------------------------
+
+export function threadSummary(root, threadOrEpic) {
+  const { rootId, broken } = resolveThread(root, threadOrEpic);
+  const members = threadEpics(root, rootId);
+  const nodes = members.map((id) => {
+    const lin = epicLineage(root, id);
+    const state = readJSON(path.join(epicRoot(root, id), '.sdlc', 'state.json'), null);
+    const change = loadChange(root, id);
+    return {
+      id, kind: lin.kind, parent: lin.parent, inherits: lin.inherits,
+      currentStep: state?.currentStep || 'unseeded',
+      sealed: sealedEpic(root, id),
+      depth: change?.depth || null,
+      defect: change?.defect || null,
+      brokenThread: resolveThread(root, id).broken || null,
+    };
+  });
+  return {
+    thread: rootId,
+    broken,
+    nodes,
+    resolved: resolveCurrentArtifacts(root, rootId),
+    resolvedStories: resolveCurrentStories(root, rootId),
+    openDebt: openDebtOnThread(root, rootId),
+  };
+}
+
+const KIND_TAG = { feature: c.green('feature'), change: c.cyan('change'), defect: c.yellow('defect'), hotfix: c.red('hotfix') };
+
+export async function runThread(root, { epic, json = false } = {}) {
+  if (!epic) {
+    // List every distinct thread root in the project.
+    const dir = path.join(root, 'epics');
+    if (!exists(dir)) { log(c.red('no epics/ directory')); process.exitCode = 1; return; }
+    const roots = new Set();
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory() && isValidEpicId(e.name) && exists(path.join(dir, e.name, 'epic.md'))) {
+        roots.add(resolveThread(root, e.name).rootId);
+      }
+    }
+    log(c.bold('\nFeature threads'));
+    for (const r of [...roots].sort()) {
+      const s = threadSummary(root, r);
+      const debt = s.openDebt.length ? c.red(`  ⚠ ${s.openDebt.length} open reconcile-debt`) : '';
+      log(`  ${c.bold(r)}  ${c.dim(`${s.nodes.length} epic(s)`)}${debt}`);
+    }
+    log(c.dim('\n  yad thread <epic>   show one thread in full'));
+    return;
+  }
+  if (!isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic}`)); process.exitCode = 1; return; }
+  const s = threadSummary(root, epic);
+  if (json) { log(JSON.stringify(s, null, 2)); return; }
+
+  log(c.bold(`\nThread ${s.thread}`) + c.dim('  (genesis → tip)'));
+  if (s.broken) log(c.red(`  ✗ broken lineage: ${s.broken}`));
+  for (const n of s.nodes) {
+    const tag = KIND_TAG[n.kind] || n.kind;
+    const seal = n.sealed ? c.dim(' [sealed]') : '';
+    const dep = n.depth ? c.dim(` ${n.depth}`) : '';
+    log(`  • ${c.bold(n.id)}  ${tag}${dep}  ${c.dim('@ ' + n.currentStep)}${seal}`);
+    if (n.parent) log(c.dim(`      parent: ${n.parent}   inherits: [${n.inherits.join(', ') || '—'}]`));
+    if (n.defect) log(c.dim(`      defect: ${n.defect.severity || '?'} · escaped@${n.defect.escape_stage || '?'} · ${n.defect.root_cause || ''}`));
+    if (n.brokenThread) log(c.red(`      ✗ ${n.brokenThread}`));
+  }
+  log(c.bold('\n  Current truth') + c.dim('  (authoritative source per artifact)'));
+  for (const base of THREAD_ARTIFACT_BASES) {
+    const v = s.resolved[base];
+    const disp = Array.isArray(v) ? (v.length ? v.join(' + ') : c.dim('(none)')) : (v || c.dim('(none)'));
+    log(`    ${base.padEnd(12)} ${c.dim('←')} ${disp}`);
+  }
+  const sids = Object.keys(s.resolvedStories).sort();
+  if (sids.length) {
+    log(c.dim(`    composed stories (${sids.length}): ` + sids.map((id) => `${id}←${s.resolvedStories[id]}`).join(', ')));
+  }
+  if (s.openDebt.length) {
+    log(c.red('\n  ⚠ Open reconcile debt (blocks the next change until paid):'));
+    for (const d of s.openDebt) log(`    ${d.epicId}: ${d.reason || ''} — requires [${(d.requires || []).join(', ')}]`);
+  } else {
+    log(c.green('\n  ✓ no open reconcile debt'));
+  }
+}
+
+// ---- the change-reconciler (yad reconcile — advisory, never a gate) ------------------------------
+
+// Distinct thread roots in the project.
+function threadRoots(root) {
+  const dir = path.join(root, 'epics');
+  if (!exists(dir)) return [];
+  const roots = new Set();
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory() && isValidEpicId(e.name) && exists(path.join(dir, e.name, 'epic.md'))) {
+      roots.add(resolveThread(root, e.name).rootId);
+    }
+  }
+  return [...roots].sort();
+}
+
+export async function runReconcile(root, { action = 'check', thread = null } = {}) {
+  const roots = thread ? [resolveThread(root, thread).rootId] : threadRoots(root);
+  if (!roots.length) { info('no feature threads found (no epics with epic.md yet)'); return; }
+
+  log(c.bold(`\nChange reconcile  ${c.dim(action)}`));
+  let flags = 0;
+  for (const r of roots) {
+    const s = threadSummary(root, r);
+    const issues = [];
+    if (s.broken) issues.push(`broken lineage: ${s.broken}`);
+    for (const n of s.nodes) if (n.brokenThread) issues.push(`${n.id}: ${n.brokenThread}`);
+    for (const d of s.openDebt) issues.push(`open reconcile debt on ${d.epicId} — next change blocked until paid`);
+    if (!issues.length) { ok(`${r} — clean`); continue; }
+    flags += issues.length;
+    warn(`${r}`);
+    for (const i of issues) hand(i);
+  }
+
+  if (action === 'refresh') {
+    log('');
+    info('refresh is advisory: open a reconcile change-epic with `yad-change` (kind: change) threaded to');
+    info('the affected feature, then pay any open debt (update artifacts + add a regression test).');
+  }
+  if (action === 'wire') {
+    log('');
+    info('wire installs an advisory CI job that runs `yad reconcile --check` on push (no block) — the');
+    info('hard enforcement is the lineage-check / epic-open / reconcile-debt gates in yad-checks.');
+  }
+
+  log('');
+  if (flags) { warn(`${flags} item(s) need attention — reconcile is advisory; the gates block at merge`); }
+  else { ok('all threads reconciled — no drift, no open debt'); }
+}

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.18.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, thread, reconcile). A BMAD module + 35 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",
   "license": "MIT",
@@ -21,6 +21,7 @@
     "cli/",
     "!cli/test.mjs",
     "!cli/test-checks.mjs",
+    "!cli/test-threads.mjs",
     "skills/",
     "README.md",
     "LICENSE",
@@ -36,9 +37,9 @@
   "scripts": {
     "yad": "node bin/yad.mjs",
     "lint": "eslint cli bin",
-    "test": "node --test cli/test.mjs cli/test-checks.mjs",
+    "test": "node --test cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs",
     "test:e2e": "bash test/e2e/run.sh",
-    "coverage": "node --test --experimental-test-coverage --test-coverage-exclude='cli/test*.mjs' --test-coverage-lines=70 --test-coverage-branches=70 cli/test.mjs cli/test-checks.mjs",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-exclude='cli/test*.mjs' --test-coverage-lines=70 --test-coverage-branches=70 cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs",
     "diagrams": "npx -y @mermaid-js/mermaid-cli -i docs/diagrams/sdlc-overview.mmd -o docs/diagrams/sdlc-overview.svg -b transparent && npx -y @mermaid-js/mermaid-cli -i docs/diagrams/review-loop.mmd -o docs/diagrams/review-loop.svg -b transparent",
     "prepublishOnly": "npm test"
   },

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>"
 
@@ -82,7 +96,11 @@ build:
       - { id: coderabbit, name: "CodeRabbit",         email: "noreply@coderabbit.ai" }
       - { id: none,       name: "(no AI assistance)", email: "" }
   # Step C (yad-checks) — the CI gates that must pass before merge. CI-agnostic bash in checks/.
-  gates: [spec-link, contract-check, build-test-lint]
+  # Phase 6 adds three thread-aware gates: lineage-check (every change links a real threaded epic),
+  # epic-open (a SEALED epic — all stories shipped — refuses new behaviour, forcing a change-epic so the
+  # front artifacts can never go stale), and reconcile-debt (a hotfix's ship-first debt blocks the next
+  # change on its thread until paid). See the `change:` block below.
+  gates: [spec-link, contract-check, build-test-lint, lineage-check, epic-open, reconcile-debt]
   # Pattern gates — commit subject + PR/MR title + PR/MR template-usage. Profile-aware (code|hub): code
   # repos validate the Conventional-Commits / task-PR conventions; the product hub validates its
   # artifact-review conventions (review/EP-<slug>/<artifact>, the hub PR template). verified-commits is
@@ -238,7 +256,48 @@ 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
+
+# Phase 6 (post-lock change management) — FEATURE THREADS. After the contract locks and code ships, a
+# change must not MUTATE a locked artifact (that destroys the audit trail and the lock). Instead every
+# change request becomes a NEW epic, threaded to its parent: a feature is a thread of linked epics
+# (genesis -> change -> defect -> ...). A change-epic INHERITS unchanged front artifacts from its parent
+# BY REFERENCE and only RE-AUTHORS what it changes — so artifacts are never stale, only superseded; the
+# feature's current truth is the head of the thread, and the chain IS the evolution timeline. See
+# docs/phase-6-build-plan.md and skills/yad-change. yad-defects/yad-timeline render it; yad-reconcile
+# (read-only, like yad-docs-sync) flags orphan/drift; the three gates above enforce it.
+change:
+  # The kind of an epic (epic.md frontmatter `kind:`). `feature` is the genesis (default when absent).
+  kinds: [feature, change, defect, hotfix]
+  # Triage DEPTH (yad-change auto-proposes, human confirms) -> which front states are re-authored vs
+  # inherited. defect-fix re-authors stories+test-cases only; contract-surface re-authors architecture
+  # and RE-LOCKS (a new hash routes architecture-review through the contract escalation, as today).
+  depths: [defect-fix, behavioral-no-surface, contract-surface, new-capability]
+  thread_id: genesis_epic_id            # the thread id = the genesis epic's id (never renamed -> stablest anchor)
+  # Lineage frontmatter added to epic.md (mirrors the design:/testing: enrichment blocks — the locked
+  # state.json step shape is untouched). `thread` is a DERIVED cache (authoritative = walk `parent` to
+  # the root); a mismatch is detectable corruption (yad doctor threadChecks). defect/hotfix also carry
+  # origin/severity/escape_stage/root_cause for the quality report (yad-defects).
+  lineage_frontmatter: [kind, thread, parent, inherits, supersedes, origin, severity, escape_stage, root_cause]
+  artifact_bases: [epic, architecture, contract, ui-design, stories, test-cases]   # what `inherits` may list
+  severity: [sev1, sev2, sev3, sev4]    # defect/hotfix severity
+  # Per-change-epic ledgers (siblings of approvals.json; the locked state.json shape is untouched).
+  ledgers:
+    change: "{project-root}/epics/EP-<slug>/.sdlc/change.json"          # intake + triage (one per change/defect/hotfix epic)
+    debt:   "{project-root}/epics/EP-<slug>/.sdlc/reconcile-debt.json"  # append-only hotfix ship-first debt
+  # An inherited artifact is taken by REFERENCE: the change-epic's contract-lock.json is a POINTER-LOCK
+  # carrying the parent's hash verbatim (+ inheritedFrom/ref), so contract-check.sh passes UNCHANGED and
+  # the surface physically cannot drift (there is no contract.md in the child to edit). Omitting
+  # `architecture` from `inherits` is what triggers a real re-lock + the architecture gate.
+  inherit_by: reference
+  # An epic is SEALED once every story is `shipped` (build.story_build_states). epic-open.sh refuses new
+  # behaviour on a sealed epic -> the change must land in a new threaded change-epic (the front half is
+  # forced to stay current; staleness is unshippable).
+  seal_on: all-stories-shipped
+  hotfix:
+    ship_first: true                    # a hotfix may run the build half BEFORE its front gates approve
+    debt_blocks_next_change: true       # but opens reconcile-debt.json; the next change on the thread is blocked until paid
+    debt_requires: [artifacts-updated, regression-test]   # evidence that clears the debt

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

package/skills/yad-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.