yadflow 2.17.0 → 2.18.1

package/bin/yad.mjs

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

package/cli/docs.mjs

@@ -121,6 +121,7 @@ export function docsStale(manifest, { artifactHash, repoHeads = {}, templateVers
 const BUILD_PUBLIC = [
   'mkdir -p public',
   'if [ -d docs/sdlc-site ]; then (cd docs/sdlc-site && npm ci && npm run build) && mkdir -p public/app && cp -r docs/sdlc-site/dist/. public/app/ && cp docs/sdlc-site/public/report.html public/index.html && cp docs/sdlc-site/public/report.html public/report.html; fi',
+  'if [ -d docs/tutorial-site ]; then (cd docs/tutorial-site && npm ci && npm run build) && mkdir -p public/tutorial && cp -r docs/tutorial-site/dist/. public/tutorial/; fi',
   'for d in epics/*/docs-site; do [ -d "$d" ] || continue; id=$(basename "$(dirname "$d")"); (cd "$d" && npm ci && npm run build) && mkdir -p "public/epics/$id" && cp -r "$d/dist/." "public/epics/$id/"; done',
 ];
 export function pagesWorkflow(platform) {
@@ -160,19 +161,19 @@ jobs:
       name: github-pages
       url: \${{ steps.deployment.outputs.page_url }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v6
         with:
           node-version: 20
       - name: Build the overview + per-epic sites into ./public
         run: |
 ${BUILD_PUBLIC.map((l) => `          ${l}`).join('\n')}
-      - uses: actions/configure-pages@v5
-      - uses: actions/upload-pages-artifact@v3
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
         with:
           path: public
       - id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5
 `;
 }
 export function pagesWorkflowPath(platform) {

package/cli/doctor.mjs

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

package/cli/epic-state.mjs

@@ -190,6 +190,21 @@ export function gatePredicate({
   merged = true,
   solo = false,
 }) {
+  // Phase 6: an INHERITED step (a change-epic carrying a parent artifact by reference) is satisfied
+  // without re-review — its approval lives upstream in the thread, recorded as an `inherited` provenance
+  // entry. It is pre-marked `done` in state.json, so the gate is normally never invoked on it; this
+  // short-circuit makes a direct call safe and surfaces a corrupted boundHash (a referenced artifact
+  // cannot change under the child, so a mismatch is corruption — re-thread, do not silently pass).
+  if (step?.inherited) {
+    const drift = step.boundHash && currentHash && step.boundHash !== currentHash;
+    return {
+      approvalsSatisfied: true, threadsResolved: true, merged: true, staleDropped: 0,
+      passed: !drift,
+      missing: drift ? [`inherited artifact drifted from ${step.inheritedFrom || 'parent'} — re-thread`] : [],
+      rule: 'inherited',
+    };
+  }
+
   const forStep = approvals.filter((a) => a.step === step.id && a.status === 'approved');
   // Revoke-on-change: an approval bound to a stale content hash no longer counts.
   const stale = forStep.filter((a) => a.artifactHash && currentHash && a.artifactHash !== currentHash);
@@ -372,4 +387,141 @@ export function nextAction(ledger, { epic } = {}) {
     why: pr ? `review PR #${pr.number} is open — sync its state to advance` : `${step.id} is open — create the review PR/MR` };
 }
 
+// ---- Phase 6: feature threads (lineage frontmatter on epic.md) -----------------------------------
+
+// Minimal frontmatter reader (key: value, and `inherits: [a, b]` arrays). Mirrors gate.mjs's reader so
+// the thread helpers and the gate agree on the same parse; shared here as the lineage source.
+export function readFrontmatter(file) {
+  if (!fs.existsSync(file)) return {};
+  const m = fs.readFileSync(file, 'utf8').match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return {};
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+    if (!kv) continue;
+    const [, k, v] = kv;
+    out[k] = /^\[.*\]$/.test(v) ? v.slice(1, -1).split(',').map((s) => s.trim()).filter(Boolean) : v.trim();
+  }
+  return out;
+}
+
+const asList = (v) => (Array.isArray(v) ? v : v ? [v] : []);
+
+// The lineage of an epic from epic.md frontmatter. `kind` defaults to `feature` (genesis) when absent,
+// so an un-migrated genesis epic behaves as the thread root. Greenfield/missing-safe.
+export function epicLineage(root, epic) {
+  const fm = readFrontmatter(path.join(epicRoot(root, epic), 'epic.md'));
+  return {
+    kind: fm.kind || 'feature',
+    parent: fm.parent || null,
+    thread: fm.thread || null,
+    inherits: asList(fm.inherits),
+    supersedes: asList(fm.supersedes),
+  };
+}
+
+// Walk `parent` to the thread root. Cycle- and missing-safe. Returns the genesis-first `chain`, the
+// computed `rootId`, and a `broken` reason (missing parent dir, a cycle, or a denormalized `thread`
+// cache that disagrees with the computed root) — the signal yad doctor / yad next --check report.
+export function resolveThread(root, epicId) {
+  const chain = [];
+  const seen = new Set();
+  let cur = epicId;
+  let broken = null;
+  while (cur) {
+    if (seen.has(cur)) { broken = `cycle at ${cur}`; break; }
+    seen.add(cur);
+    if (!fs.existsSync(epicRoot(root, cur))) {
+      broken = cur === epicId ? `missing epic ${cur}` : `missing parent epic ${cur}`;
+      break;
+    }
+    chain.unshift(cur); // genesis ends up first
+    const { parent } = epicLineage(root, cur);
+    if (!parent) break; // reached genesis
+    cur = parent;
+  }
+  const rootId = chain[0] || epicId;
+  const tip = epicLineage(root, epicId);
+  // A non-genesis epic (has a parent) MUST carry a `thread:` cache that equals the computed root.
+  // A missing cache is corruption too — without it the bash gates' parent-walk is the only safety net,
+  // and a tool reading the field would mis-scope the thread.
+  if (!broken && tip.parent && !tip.thread) {
+    broken = `missing thread cache on ${epicId} (kind:${tip.kind}, parent:${tip.parent}) — should be '${rootId}'`;
+  }
+  if (!broken && tip.thread && tip.thread !== rootId) {
+    broken = `thread cache '${tip.thread}' != computed root '${rootId}'`;
+  }
+  return { rootId, chain, broken };
+}
+
+// Every epic that belongs to a thread (resolved root == this thread's root), ordered genesis-first by
+// chain depth. Derived by scanning epics/ — no duplicated thread registry. Used by yad-timeline/yad-defects.
+export function threadEpics(root, threadOrEpicId) {
+  const { rootId } = resolveThread(root, threadOrEpicId);
+  const dir = path.join(root, 'epics');
+  if (!fs.existsSync(dir)) return [rootId];
+  const depth = new Map();
+  const members = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!e.isDirectory() || !isValidEpicId(e.name) || !fs.existsSync(path.join(dir, e.name, 'epic.md'))) continue;
+    const rt = resolveThread(root, e.name); // one walk per member (not per comparison)
+    if (rt.rootId !== rootId) continue;
+    members.push(e.name);
+    depth.set(e.name, rt.chain.length);
+  }
+  // Genesis-first by depth, then a STABLE, machine-independent tie-break (id order) so the resolver is
+  // deterministic across filesystems even when two epics sit at the same depth (a branch).
+  return members.sort((a, b) => (depth.get(a) - depth.get(b)) || a.localeCompare(b));
+}
+
+// Compose the CURRENT authoritative source per artifact base across a thread: the LATEST epic in the
+// chain that actually RE-AUTHORED it (did NOT list it in `inherits`). Genesis owns everything; a later
+// change-epic shadows only what it re-authored. Returns { <base>: <owning epic id> } — the source-of-
+// truth map AI/humans read for the next change (rendered by yad-timeline as thread-resolved.md).
+export const THREAD_ARTIFACT_BASES = ['epic', 'architecture', 'contract', 'ui-design', 'stories', 'test-cases'];
+// REPLACE bases — a re-author supersedes the prior version wholesale, so the LATEST re-author owns it
+// (a contract-surface change re-locks and replaces; a re-authored architecture supersedes the old one).
+const REPLACE_BASES = ['epic', 'architecture', 'contract', 'ui-design'];
+// ADDITIVE bases — each re-authoring epic CONTRIBUTES (stories add files; a change adds its test-cases
+// file), so the current truth is the UNION of contributors, never a single owner. Collapsing these to
+// one epic would drop the parent's inherited stories/cases.
+const ADDITIVE_BASES = ['stories', 'test-cases'];
+
+// The owning epic per artifact base across a thread. REPLACE bases resolve to a single epic id (the
+// latest re-author); ADDITIVE bases resolve to the ordered LIST of every epic that re-authored them
+// (genesis-first) — use resolveCurrentStories for story-id-level ownership of the composed set.
+export function resolveCurrentArtifacts(root, threadOrEpicId) {
+  const members = threadEpics(root, threadOrEpicId); // genesis-first
+  const out = {};
+  for (const b of REPLACE_BASES) out[b] = null;
+  for (const b of ADDITIVE_BASES) out[b] = [];
+  for (const id of members) {
+    const { inherits } = epicLineage(root, id);
+    for (const b of REPLACE_BASES) if (!inherits.includes(b)) out[b] = id;
+    for (const b of ADDITIVE_BASES) if (!inherits.includes(b)) out[b].push(id);
+  }
+  return out;
+}
+
+// Compose the current STORY SET at story-id granularity across the thread: each re-authoring epic's
+// stories/ files are overlaid (a later same-id supersedes; a `supersedes:` entry retires a parent
+// story). Returns { <story-id>: <owning epic id> } — the real current truth for stories, because a
+// change-epic re-authors only the stories it changes and inherits the rest by reference. Without this,
+// a defect-fix that adds one regression story would appear to drop every unchanged parent story.
+export function resolveCurrentStories(root, threadOrEpicId) {
+  const members = threadEpics(root, threadOrEpicId); // genesis-first
+  const owner = {};
+  for (const id of members) {
+    const lin = epicLineage(root, id);
+    for (const sid of lin.supersedes) delete owner[sid]; // explicitly retired parent stories
+    if (lin.inherits.includes('stories')) continue; // inherited wholesale -> contributes nothing new
+    const sdir = path.join(epicRoot(root, id), 'stories');
+    if (!fs.existsSync(sdir)) continue;
+    for (const f of fs.readdirSync(sdir).filter((x) => /\.md$/.test(x))) {
+      owner[f.replace(/\.md$/, '')] = id; // contribute / override same-id
+    }
+  }
+  return owner;
+}
+
 export { writeJSON };

package/cli/manifest.mjs

@@ -157,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.
@@ -166,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/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.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.",
+  "version": "2.18.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, 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

@@ -96,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
@@ -256,3 +260,44 @@ automation:
   # 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-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)
+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

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