yadflow 2.17.0 → 2.18.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [2.17.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.16.1...v2.17.0) (2026-06-26)
+# [2.18.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.17.0...v2.18.0) (2026-06-26)
 
 
 ### Features
 
-* **discovery:** add yad-discovery project front-zero phase ([#82](https://github.com/abdelrahmannasr/yadflow/issues/82)) ([4bb2a92](https://github.com/abdelrahmannasr/yadflow/commit/4bb2a928ea37cbd7d7b21f7c28a96a20492f527e))
+* **change:** post-lock change management via feature threads (Phase 6) ([#83](https://github.com/abdelrahmannasr/yadflow/issues/83)) ([f8024d5](https://github.com/abdelrahmannasr/yadflow/commit/f8024d5808070656d1c3039905ada39096fe7d3b)), closes [#1](https://github.com/abdelrahmannasr/yadflow/issues/1)
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/README.md

@@ -69,9 +69,13 @@ human**. Detailed walkthroughs for each phase follow below.
 | `skills/yad-backfill/` | Generate a human-verified spec for already-built code (Repomix), gated per touched feature. |
 | `skills/yad-run/` | Phase 4 orchestrator: drive a story's back half on the `automation` dial; kill switch. |
 | `skills/yad-status/` | Read-only view: front chain, build-half dials, trust record, fleet roll-up. |
-| `epics/EP-istifta-inquiries/` | A worked demo epic run **end to end** (front half + build half + automation). |
+| `skills/yad-change/` | Phase 6: post-lock change/defect/hotfix **intake + triage** — seed a new epic threaded to its parent (inherit by reference, re-author only what changes). |
+| `skills/yad-timeline/` | Phase 6: render a feature **thread** as an evolution view + resolve its current truth (`thread-resolved.md`). |
+| `skills/yad-defects/` | Phase 6: per-epic/per-thread **quality-gap report** by `escape_stage` + `root_cause`. |
+| `skills/yad-reconcile/` | Phase 6: read-only **drift/orphan/debt sweep** across threads (mirrors `yad-docs-sync`; never a gate). |
+| `epics/EP-istifta-inquiries/` | A worked demo epic run **end to end** (front half + build half + automation + a Phase 6 change thread). |
 | `demo-repos/` | Throwaway code repos for the build half (separate git repos; regenerable — see `demo-repos/README.md`). |
-| `docs/` | The phased build plans (`phase-2`…`phase-5`) and the original workflow design. |
+| `docs/` | The phased build plans (`phase-2`…`phase-6`) and the original workflow design. |
 | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Commit & PR/MR title convention (Conventional Commits, lowercase after the type). |
 
 ## The `yad` CLI (install, update, reconcile)
@@ -104,6 +108,8 @@ with `npx` from your **product hub** repo — no clone needed.
 | `yad ship --type <t> -m <subject>` | Commit **and** open the task PR/MR in one step (`yad commit` then `yad open-pr`) — stage-aware, same as `open-pr`. |
 | `yad repo list` / `yad repo refresh [name]` | List connected repos as **fresh / stale**, and re-pack a stale one — staleness is now an explicit human decision, never an automatic skill side-effect. |
 | `yad repo sync [name]` | Switch every connected repo to its **default branch** and fast-forward it from origin (one or all). Dirty repos are skipped, never overwritten; fast-forward only. |
+| `yad thread [<epic>]` | **Feature threads (Phase 6).** No arg: list every thread. With an epic: show its thread (genesis → changes → defects), the **resolved current-truth** map (which epic owns each artifact now), and any open hotfix debt. `--json` for tooling. Read-only. |
+| `yad reconcile [check\|refresh\|wire]` | Sweep threads for **drift / orphans / open hotfix debt** and report which thread drifted and why (mirrors `yad docs sync`; advisory — the CI gates block at merge). |
 | `npx yadflow --version` | Print the installed CLI version. |
 
 Flags: `--dir <path>` targets a project other than the cwd; `--force` re-copies unchanged files (or
@@ -206,7 +212,7 @@ with a fix-it hint per finding. Failures carry stable, greppable codes, also pri
 
 Filing a bug? Attach `yad doctor --json` — it contains no secrets (names, paths, and check results only).
 
-## Agent skills (all 31)
+## Agent skills (all 35)
 
 The CLI **installs and wires** the module; the skills below are the **agents you invoke by name** in your
 AI IDE (e.g. *“run `yad-epic`”*) to actually do the work. State lives in files you can also edit
@@ -369,6 +375,33 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
   automation) and status, which approvals are still required, per-story back-half trust records, the
   kill-switch state, and a fleet roll-up across epics.
 
+### Post-lock change management — feature threads (Phase 6)
+
+After the contract locks and code ships, a change must **not** mutate a locked artifact — it becomes a
+**new epic threaded to its parent**. A feature is a *thread* of linked epics (genesis → change → defect →
+…); a change-epic **inherits** the front artifacts it does not change (by reference) and **re-authors**
+only what it does. So artifacts never go stale — they are *superseded*; the feature's current truth is the
+head of the thread. This is what keeps the SDLC a trusted source of truth for AI on the next change.
+
+- **`yad-change`** — the intake + triage. Classifies the change *depth* (defect-fix /
+  behavioral-no-surface / contract-surface / new-capability), seeds a new `EP-<slug>` threaded to its
+  parent (lineage frontmatter, an inherited-step `state.json`, a pointer-lock `contract-lock.json`,
+  `change.json`), and for hotfixes opens `reconcile-debt.json`. Never auto-advances — hands off to the
+  normal authoring skills + the review gate.
+- **`yad-timeline`** — render the thread as an evolution view (yad-docs shell + `TIMELINE.md`) and emit
+  `thread-resolved.md`, the composed **current-truth map** (which epic owns each artifact now).
+- **`yad-defects`** — a per-epic/per-thread quality-gap report aggregating defects by **`escape_stage`**
+  (the gate that should have caught it) + `root_cause` — *where the SDLC leaks*, so the team hardens the
+  originating stage.
+- **`yad-reconcile`** — a read-only drift/orphan/debt sweep across threads (mirrors `yad-docs-sync`; never
+  a gate). The hard block is the CI gates.
+
+Three CI gates (in `yad-checks`) enforce it: **lineage-check** (a change links a real threaded epic),
+**epic-open** (a *sealed* epic — all stories shipped — refuses new behaviour, forcing a change-epic so the
+front artifacts can never go stale), and **reconcile-debt** (a thread with open hotfix debt is frozen
+until paid). Two read-only CLIs surface it: `yad thread <epic>` (the thread + resolved truth + open debt)
+and `yad reconcile` (the drift sweep).
+
 ## The two dials (per step, build plan §2)
 
 - **assistance:** `none` | `review` | `heavy` — how much AI helps.

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

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