yadflow 2.18.0 → 3.0.0

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

@@ -33,7 +33,6 @@ export const SKILLS = [
   'yad-implement',
   'yad-checks',
   'yad-pr-template',
-  'yad-review-comments',
   'yad-hub-bridge',
   'yad-commit',
   'yad-open-pr',
@@ -43,6 +42,10 @@ export const SKILLS = [
   'yad-run',
   'yad-review-gate',
   'yad-status',
+  'yad-change',
+  'yad-timeline',
+  'yad-defects',
+  'yad-reconcile',
 ];
 
 // Pre-2.0 skill names (the sdlc-* -> yad-* rename). `check`/`update` migrate any install
@@ -58,7 +61,6 @@ export const LEGACY_SKILLS = {
   'yad-implement': 'sdlc-implement',
   'yad-checks': 'sdlc-checks',
   'yad-pr-template': 'sdlc-pr-template',
-  'yad-review-comments': 'sdlc-review-comments',
   'yad-hub-bridge': 'sdlc-hub-bridge',
   // Step E ("ship") was renamed to yad-engineer-review (the yad-ship name now belongs to the new
   // commit+open-PR combined skill). Pre-2.0 installs carry sdlc-ship → migrate it to yad-engineer-review.
@@ -71,6 +73,14 @@ export const LEGACY_SKILLS = {
   'yad-status': 'sdlc-status',
 };
 
+// Skills removed in a later release that must be PURGED from existing installs. Unlike
+// LEGACY_SKILLS (a rename: drop old name, install new), these have no replacement — a rerun of
+// `yad update` / `yad setup` deletes any installed copy from every IDE target so a breaking
+// removal actually takes effect. List every install basename to purge, including any pre-rename
+// alias the skill ever shipped under.
+//   yad-review-comments — removed in 2.x (was sdlc-review-comments pre-2.0).
+export const REMOVED_SKILLS = ['yad-review-comments', 'sdlc-review-comments'];
+
 // Pre-2.0 wired-file dests replaced by renamed ones (old dest -> new dest, per platform).
 // An old file is removed ONLY when its first line carries the old ownership marker —
 // a same-named file the user authored themselves is never touched.
@@ -181,12 +191,10 @@ export const REPO_WIRING = {
   github: [
     { src: 'skills/yad-checks/templates/github/yad-checks.yml', dest: '.github/workflows/yad-checks.yml' },
     { src: 'skills/yad-pr-template/templates/github/pull_request_template.md', dest: '.github/pull_request_template.md' },
-    { src: 'skills/yad-review-comments/templates/github/REVIEW_COMMENTS.md', dest: '.github/REVIEW_COMMENTS.md' },
   ],
   gitlab: [
     { src: 'skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml', dest: '.gitlab/ci/yad-checks.yml' },
     { src: 'skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md', dest: '.gitlab/merge_request_templates/Default.md' },
-    { src: 'skills/yad-review-comments/templates/gitlab/REVIEW_COMMENTS.md', dest: '.gitlab/REVIEW_COMMENTS.md' },
   ],
 };
 

package/cli/plan.mjs

@@ -8,7 +8,7 @@ import {
 } from './lib.mjs';
 import {
   SKILLS, IDE_FOLDER_TARGETS, IDE_OPENCODE_DIR, MODULE_FILES, wiringFor, HUB_WIRING, PROJECT_FILES,
-  LEGACY_SKILLS, LEGACY_MARKER, LEGACY_REPO_FILES, LEGACY_HUB_FILES,
+  LEGACY_SKILLS, REMOVED_SKILLS, LEGACY_MARKER, LEGACY_REPO_FILES, LEGACY_HUB_FILES,
 } from './manifest.mjs';
 
 // status: 'ok' | 'missing' | 'outdated'
@@ -105,6 +105,39 @@ export function legacyModuleActions(root, ideTargets = ideTargetsFor(root)) {
   return actions;
 }
 
+// Purge of skills removed in a later release (REMOVED_SKILLS). Status is 'removed' — like 'legacy'
+// it is applied by `yad update` (--scope=changed) too, because the skill IS installed and a
+// breaking removal must actually delete it. An action is emitted ONLY when a copy is present, so a
+// clean tree yields nothing and the purge is idempotent. apply() just deletes the install (no
+// replacement — that is what makes this a removal, not a rename).
+export function removedModuleActions(root, ideTargets = ideTargetsFor(root)) {
+  const actions = [];
+  for (const ide of ideTargets) {
+    for (const skill of REMOVED_SKILLS) {
+      if (ide === '.opencode') {
+        const dest = path.join(root, IDE_OPENCODE_DIR, `${skill}.md`);
+        if (!exists(dest)) continue;
+        actions.push({
+          scope: ide,
+          item: `${skill}.md (removed)`,
+          status: 'removed',
+          apply: () => fs.rmSync(dest, { force: true }),
+        });
+      } else {
+        const dest = path.join(root, ide, 'skills', skill);
+        if (!exists(dest)) continue;
+        actions.push({
+          scope: ide,
+          item: `${skill} (removed)`,
+          status: 'removed',
+          apply: () => fs.rmSync(dest, { recursive: true, force: true }),
+        });
+      }
+    }
+  }
+  return actions;
+}
+
 // True only for a file WE installed pre-2.0: its first line carries the old ownership marker
 // (`# sdlc-managed:` / `# sdlc-managed-include:`). A same-named user-authored file is never ours.
 function ownedByOldInstall(p) {
@@ -152,7 +185,7 @@ export function legacyHubActions(root) {
   return legacyFileActions('hub', root, LEGACY_HUB_FILES[hub.platform], wiring);
 }
 
-// Per-repo wiring (gate scripts, CI, PR template, comment scaffold).
+// Per-repo wiring (gate scripts, CI, PR template).
 export function repoActions(root, repo) {
   const repoRoot = path.resolve(root, repo.path);
   return wiringFor(repo.platform).map((w) =>

package/cli/reconcile.mjs

@@ -8,11 +8,11 @@ import {
 import { VERSION, PROJECT_FILES } from './manifest.mjs';
 import {
   moduleActions, repoActions, hubActions, authorsActions,
-  legacyModuleActions, legacyRepoActions, legacyHubActions,
+  legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
 } from './plan.mjs';
 import { gitHead, packRepo } from './setup.mjs';
 
-const MARK = { missing: c.red('missing'), outdated: c.yellow('outdated'), stale: c.yellow('stale'), legacy: c.yellow('legacy'), ok: c.green('ok') };
+const MARK = { missing: c.red('missing'), outdated: c.yellow('outdated'), stale: c.yellow('stale'), legacy: c.yellow('legacy'), removed: c.yellow('removed'), ok: c.green('ok') };
 
 export async function reconcile(root, { fix = false, scope = 'all', force = false } = {}) {
   log(c.bold(`\nSDLC reconcile  ${c.dim('v' + VERSION)}`));
@@ -26,9 +26,10 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
   if (!exists(path.join(root, PROJECT_FILES.reposRegistry))) gaps.push('no repos registered (.sdlc/repos.json absent)');
 
   // --- deterministic file actions (module + hub CI + author allowlists + every registered repo),
-  //     plus pre-2.0 sdlc-* -> yad-* migrations ('legacy': old name installed; rename in place) ---
+  //     plus pre-2.0 sdlc-* -> yad-* migrations ('legacy': old name installed; rename in place)
+  //     and purge of skills removed in a later release ('removed': delete the lingering install) ---
   const actions = [
-    ...moduleActions(root), ...legacyModuleActions(root),
+    ...moduleActions(root), ...legacyModuleActions(root), ...removedModuleActions(root),
     ...hubActions(root), ...legacyHubActions(root),
     ...authorsActions(root, registry.repos),
   ];
@@ -50,7 +51,7 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
     if (!byScope.has(a.scope)) byScope.set(a.scope, []);
     byScope.get(a.scope).push(a);
   }
-  const counts = { missing: 0, outdated: 0, stale: 0, legacy: 0, ok: 0 };
+  const counts = { missing: 0, outdated: 0, stale: 0, legacy: 0, removed: 0, ok: 0 };
   for (const [scopeName, items] of byScope) {
     const notOk = items.filter((i) => i.status !== 'ok');
     items.forEach((i) => counts[i.status]++);
@@ -64,7 +65,7 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
     a.status !== 'ok' && (scope === 'all' ? true : a.status !== 'missing'),
   );
   log('');
-  log(c.dim(`summary: ${counts.missing} missing, ${counts.outdated} outdated, ${counts.stale} stale, ${counts.legacy} legacy, ${counts.ok} ok`));
+  log(c.dim(`summary: ${counts.missing} missing, ${counts.outdated} outdated, ${counts.stale} stale, ${counts.legacy} legacy, ${counts.removed} removed, ${counts.ok} ok`));
 
   if (!fix) {
     if (fixable.length || gaps.length) hand('run `yad check --fix` to reconcile (or `yad setup` for missing one-time setup).');

package/cli/setup.mjs

@@ -9,7 +9,7 @@ import {
 import { VERSION, IDE_FOLDER_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY, TESTING_TOOLS, TESTING_PRIMARY, LEARNING_TOOLS, LEARNING_PRIMARY } from './manifest.mjs';
 import {
   moduleActions, repoActions, hubActions, authorsActions,
-  legacyModuleActions, legacyRepoActions, legacyHubActions,
+  legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
 } from './plan.mjs';
 import { validateLogin, rolesForScope } from './platform.mjs';
 
@@ -399,6 +399,9 @@ export async function runSetup(root, opts = {}) {
   // IDE targets and install their yad-* renames. Without this, setup only ADDED yad-* and left
   // stale sdlc-* sitting next to them (the rename only ran under `yad update` / `yad check --fix`).
   applyActions(legacyModuleActions(root, ideTargets), { force: true });
+  // Purge any skill removed in a later release (REMOVED_SKILLS) that a prior install left behind —
+  // setup only ADDS current skills, so without this a breaking removal would linger next to them.
+  applyActions(removedModuleActions(root, ideTargets), { force: true });
   ok(`module installed into: ${ideTargets.join(', ')}`);
 
   // Global leftovers: a pre-2.0 install may have put sdlc-* skills in the user's global
@@ -416,6 +419,18 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
+  // Same opt-in pass for skills removed in a later release (REMOVED_SKILLS) that linger in the
+  // global ~/.claude/skills — purge them so a global install also drops the dead command.
+  const globalRemoved = process.env.SDLC_NONINTERACTIVE ? [] : removedModuleActions(os.homedir(), ['.claude']);
+  if (globalRemoved.length) {
+    if (await askYesNo(`Found ${globalRemoved.length} removed skill(s) in your global ~/.claude/skills. Delete them?`, true)) {
+      applyActions(globalRemoved, { force: true });
+      ok('purged removed skill(s) from global ~/.claude/skills');
+    } else {
+      info('left global ~/.claude/skills untouched — re-run `yad setup` or purge later with `yad update`');
+    }
+  }
+
   // Detect hub platform + roster
   S(solo ? 'Hub platform (solo — no roster)' : 'Hub platform & reviewer roster');
   guide(solo
@@ -619,7 +634,7 @@ export async function runSetup(root, opts = {}) {
   }
 
   // Wire each connected repo + the hub itself
-  S('Wire connected repos + the hub (CI gates, PR template, comment scaffold, gate-sync)');
+  S('Wire connected repos + the hub (CI gates, PR template, gate-sync)');
   guide(['Installs the CI safety gates, PR/MR template, and gate-sync — automatic, no input needed.']);
   if (registry.repos.length === 0) info('no repos to wire');
   for (const repo of registry.repos) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yadflow",
-  "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.",
+  "version": "3.0.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 + 34 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",
   "license": "MIT",

package/skills/sdlc/install.sh

@@ -11,10 +11,27 @@ 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 yad-change yad-timeline yad-defects yad-reconcile)
+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-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)
+
+# Skills removed in a later release: this installer only refreshes names still in SKILLS, so a
+# rerun would otherwise leave a dropped skill sitting in the IDE dirs. Purge any lingering copy
+# (current name + any pre-rename alias) so the breaking removal takes effect for existing installs.
+# Mirrors the CLI's REMOVED_SKILLS purge in `yad update`.
+REMOVED_SKILLS=(yad-review-comments sdlc-review-comments)
 
 echo "Installing sdlc module from $ROOT/skills ..."
 
+for ide in .claude .agents .zencoder; do
+  for s in "${REMOVED_SKILLS[@]}"; do
+    rm -rf "$ide/skills/$s"
+  done
+done
+if [ -d ".opencode/commands" ]; then
+  for s in "${REMOVED_SKILLS[@]}"; do
+    rm -f ".opencode/commands/$s.md"
+  done
+fi
+
 # 1. Folder-per-skill IDEs: .claude, .agents, .zencoder
 for ide in .claude .agents .zencoder; do
   for s in "${SKILLS[@]}"; do

package/skills/sdlc/module-help.csv

@@ -20,7 +20,6 @@ SDLC Workflow,yad-pr-template,PR/MR Template,PT,"Build-half Step D: detect a cod
 SDLC Workflow,yad-commit,Commit by Convention,CM,"Build-half helper: commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer block (Task -> Contract-Change -> Co-Authored-By), and the <=3-file atomic guard. The human git author owns the commit; an assisting AI is recorded only as a Co-Authored-By footer chosen per-commit with --ai (claude|copilot|cursor|coderabbit|none, default none). Drives the yad commit CLI. Never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {task: <id>} {contract-change: true|false},3-build,yad-implement,,false,<repo>/,one commit
 SDLC Workflow,yad-open-pr,Open PR/MR,OP,"Build-half helper: open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the task branch, create the PR/MR with the body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Auto-assigns from the hub roster (assignee = committer, reviewers = repo reviewers + domain-owners); high risk / contract surface routes to domain owners (risk-route.sh). Drives the yad open-pr CLI. Never merges; never auto-advances.",,{repo: <name>} {risk: low|medium|high} {contract-change: true|false},3-build,yad-commit,,false,<repo>/,one PR/MR
 SDLC Workflow,yad-ship,Commit + Open PR/MR,SP2,"Build-half helper: commit AND open the task PR/MR in one step — a thin orchestration over yad-commit then yad-open-pr. Commits the staged atomic change by the conventions, then pushes the branch and opens the PR/MR from the committed template with the roster auto-assigned. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the yad ship CLI. Never merges; never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {repo: <name>} {risk: low|medium|high} {contract-change: true|false},3-build,yad-pr-template,,false,<repo>/,one commit + one PR/MR
-SDLC Workflow,yad-review-comments,Review Comment Templates,RC,"Install platform-matched PR/MR review-comment scaffolds (committed REVIEW_COMMENTS.md) into a code repo or the product hub, so reviewers leave structured, attributable feedback whose **name (role)** headers map cleanly into the SDLC file ledger. GitHub Saved Replies / GitLab comment templates are per-user, so a committed doc is the repo-level mechanism. Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire},3-build,,,false,<repo>/.github|.gitlab/,REVIEW_COMMENTS.md
 SDLC Workflow,yad-hub-bridge,Hub Review Bridge,HB,"The templated PR/MR bridge for the front-half review gate: when the product hub has a platform (.sdlc/hub.json), open a review PR/MR on the hub for an authored artifact, set required reviewers/labels from the routing rule, and provide the read-only gh/glab recipes yad-review-gate's sync uses to pull platform comments + approvals into the file ledger. Local-user auth, no stored tokens; file ledger stays the source of truth; degrades to file-only when no platform/CLI. Never auto-advances.",,{epic: EP-<slug>} {artifact: epic.md|architecture.md|ui-design.md|stories/} {action: open|route},1-front,yad-review-gate,yad-review-gate,false,epics/EP-<slug>/.sdlc/,hub-prs.json
 SDLC Workflow,yad-engineer-review,Engineer Review & Merge,ER,"Build-half Step E: wire an advisory AI first-pass (CodeRabbit) on the PR, record the human engineer review with the same human_approve discipline as the front gates (owner + 1 reviewer, escalating to domain owners on high risk / contract / auth / payments), and on merge record the ship in epics/<epic>/.sdlc/build-log.json and update the story state. AI review is advisory, never the authority; the human owns the merge. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {task: T0N} {repo: <repo>} {action: ai-review|approve|ship},3-build,yad-ship,,false,epics/EP-<slug>/.sdlc/,build-log.json story-status
 SDLC Workflow,yad-backfill,Backfill Specs,BF,"Build-half Step G: generate specs for already-built features in an existing repo. Confirm Repomix (npx repomix CLI), pack ONE feature (compress + git logs, secret-scan), feed to AI with a 'describe what exists, do not invent' prompt, write a DRAFT spec marked verified: false. Human approval (reuse yad-review-gate) makes it real. Boundary auto-proposed and human-confirmed. A change is blocked only until the features it touches have approved specs. Never auto-advances.",,{repo: <repo>} {feature: <name + globs>} {action: pack|draft|approve|gate},3-build,,,false,demo-repos/<repo>/specs/backfill/<feature>/,spec.md backfill-check.sh

package/skills/yad-docs-overview/SKILL.md

@@ -56,7 +56,7 @@ git work tree). Generate and commit on it.
 Map the pipeline onto the same data structures `yad-docs` uses (concrete mapping in
 `references/pipeline-model.md`):
 
-- **Flow paths** = the **phases** — `Setup`, `Front half`, `Build half`, `Automation`.
+- **Flow paths** = the **phases** — `Setup`, `Front-zero` (discovery), `Front half`, `Build half`, `Automation`, `Change management` (feature threads).
 - **Flow steps** = the **skills/gates in order** (from `module-help.csv` `preceded-by`/`followed-by`),
   each step's `messages` = the skill's `outputs`, and `sideEffects` = the `.sdlc/` files it writes.
 - **System components** = the **durable state objects** — the product hub, each `.sdlc/*.json`

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

@@ -10,7 +10,7 @@ ordering source of truth is `skills/sdlc/module-help.csv` (`phase`, `preceded-by
 
 | Shell primitive | Overview meaning |
 |-----------------|------------------|
-| `FlowPath` (`paths.ts`) | a **phase**: Setup, Front half, Build half, Automation. |
+| `FlowPath` (`paths.ts`) | a **phase**: Setup, Front-zero (discovery), Front half, Build half, Automation, Change management (feature threads). |
 | `FlowStep` (within a path) | a **skill or gate** in order; `messages` = its `outputs`; `sideEffects` = the `.sdlc/` files it writes; `status`/`bookingStatus` annotate gated vs. enrichment vs. earned. |
 | `SystemComponent` (`components.ts`) | a **durable state object** (the hub, each `.sdlc/*.json`, code repos, the design/testing/learning tools, the platform). |
 | `RoleConfig` (`roles.ts`) | a **lens** → its relevant sections + paths. |
@@ -57,7 +57,6 @@ The gated authoring chain + the reusable review gate (10 steps, or 12 with the o
 | `yad-test-cases` | → `test-cases-review` (parallel, non-blocking) | `test-cases.md`, `test-links.json` |
 | `yad-review-gate` | the shared gate | `reviews/*.md`, `approvals.json`, `comments.json` |
 | `yad-hub-bridge` | the platform PR/MR bridge | `hub-prs.json` |
-| `yad-review-comments` | comment scaffolds | repo comment templates |
 
 ### Path: Build half (`phase: 3-build`)
 Per-story, per-repo: `spec → tasks → implement → checks → engineer-review`, plus the commit/PR helpers.
@@ -66,7 +65,7 @@ Per-story, per-repo: `spec → tasks → implement → checks → engineer-revie
 |--------------|------------------------|
 | `yad-spec` | `specs/<story-id>/` (Spec Kit layout), `link.md` |
 | `yad-implement` | a branch + commit per atomic task |
-| `yad-checks` | `checks/*.sh`, CI workflows |
+| `yad-checks` | `checks/*.sh`, CI workflows — the gate set: `spec-link · contract-check · build-test-lint · verified-commits · commit-message · pr-title · pr-template · lineage-check · epic-open · reconcile-debt` |
 | `yad-pr-template` | PR/MR template + routing helpers |
 | `yad-commit` / `yad-open-pr` / `yad-ship` | one commit / one PR/MR |
 | `yad-engineer-review` | engineer review + ship recorded in `build-log.json` |
@@ -83,11 +82,30 @@ node classes from the diagram.
 | `yad-status` | read-only view (no writes) |
 | `yad-docs` / `yad-docs-overview` / `yad-docs-sync` | the docs sites + their `docs-build.json` manifests |
 
+### Path: Change management — feature threads (`phase: 6-change`)
+The post-lock evolution layer. Once an epic is **sealed** (all stories shipped), behaviour can no longer
+be mutated in place — a change request becomes a **new epic threaded to its parent** (genesis → change →
+defect), inheriting unchanged front artifacts **by reference** and re-authoring only what changes, so
+locked artifacts are never mutated and never go stale, only superseded. Three CI gates enforce the thread
+(`lineage-check`, `epic-open`, `reconcile-debt`). This path never gates the front chain; `yad-change` is
+the intake, then it hands off to the normal authoring skills + the review gate.
+
+| Step (skill) | Outputs / sideEffects |
+|--------------|------------------------|
+| `yad-change` | intake + triage depth (defect-fix / behavioral-no-surface / contract-surface / new-capability); seeds a threaded change-epic — lineage frontmatter, inherited-step `state.json`, pointer-lock `contract-lock.json`, `change.json`, and `reconcile-debt.json` for hotfixes |
+| `yad-timeline` | `TIMELINE.md` (the thread evolution view) + `thread-resolved.md` (the resolved current truth) |
+| `yad-defects` | `DEFECTS.md` (quality-gap report by `escape_stage` + root cause) |
+| `yad-reconcile` | advisory drift / orphan / debt sweep (read-only; mirrors `yad-docs-sync`) |
+
+CLI: `yad thread [<epic>]` prints a thread + its resolved current truth + open debt; `yad reconcile`
+runs the sweep. The three thread gates ride in the build-half `yad-checks` set above.
+
 ## System components = the durable state objects
 
 `components.ts` renders these on the canvas (deterministic positions): the **product hub**; each
 `.sdlc/*.json` (`state.json`, `approvals.json`, `comments.json`, `hub.json`, `repos.json`, `design.json`,
-`testing.json`, `learning.json`, `docs.json`, `contract-lock.json`, `build-state/*`, `trust-log.json`);
+`testing.json`, `learning.json`, `docs.json`, `contract-lock.json`, `build-state/*`, `trust-log.json`,
+and the change-thread ledgers `change.json`, `reconcile-debt.json`, `build-log.json`);
 the **connected code repos**; the **design / testing / learning tools**; and the **platform**
 (GitHub/GitLab + Pages). A skill's `sideEffects` link its step to the component it writes.
 

package/skills/yad-review-comments/SKILL.md

@@ -1,63 +0,0 @@
----
-name: yad-review-comments
-description: 'Installs platform-matched PR/MR review-comment scaffolds into a repo so reviewers leave structured, attributable feedback that maps cleanly into the SDLC file ledger. Works for code repos and the product hub. GitHub has no repo-level multi-comment template, so the scaffold is a committed REVIEW_COMMENTS.md reviewers copy from (saved as Saved Replies on GitHub / comment templates on GitLab). Each canned comment carries an attributable `**<name> (<role>)**` header that matches the `## <name> (<role>)` headings yad-review-gate writes. Use when the user says "add the comment templates" or "set up review comments" for a repo.'
----
-
-# SDLC — Review Comment Templates
-
-**Goal:** Give reviewers a consistent, **attributable** set of canned PR/MR comments so review feedback
-reads the same across repos and **maps cleanly into the file ledger** the gate keeps. The headers match
-the `## <name> (<role>)` shape `yad-review-gate` writes into `reviews/<artifact>--<date>--comments.md`
-and the per-commenter record in `comments.json`, so a synced or copy-pasted comment lands without
-reformatting.
-
-## Platform reality (why this is a committed doc, not a config file)
-
-Neither GitHub nor GitLab has a **repo-level** multi-comment template convention: GitHub *Saved Replies*
-are per-account and GitLab *comment templates* are per-user/group, both set in the UI — there is no
-`.github/comment_templates/` or `.gitlab/comment_templates/` the repo can ship. The pragmatic mechanism
-on **both** is a single committed doc reviewers copy from (and optionally paste once into their personal
-Saved Replies / comment templates). This skill ships that doc.
-
-## Conventions
-
-- `{project-root}` resolves from the project working directory — the **product** repo (holds the
-  canonical templates under this skill).
-- Canonical sources live in this skill's `templates/`:
-  - `templates/github/REVIEW_COMMENTS.md` → installs to `<repo>/.github/REVIEW_COMMENTS.md`
-  - `templates/gitlab/REVIEW_COMMENTS.md` → installs to `<repo>/.gitlab/REVIEW_COMMENTS.md`
-- The two variants are identical except a footer line (GitHub: "save these as Saved Replies"; GitLab:
-  "save these as comment templates").
-
-## Inputs
-
-- `repo`   — the repo to add the scaffold to (one of an epic's repos), or `hub` for the product hub.
-- `action` — `wire` (install the matching scaffold). Default `wire`.
-
-## On Activation
-
-### Step 1 — Resolve the repo and detect the platform
-Map `repo` → its path (`{project-root}/demo-repos/<repo>/` or the registry `path`); for `repo: hub` the
-target is `{project-root}` and the platform comes from `.sdlc/hub.json`. Detect the platform: a GitHub
-remote or `.github/` → GitHub; a GitLab remote or `.gitlab/` → GitLab. If ambiguous, ask.
-
-### Step 2 — `wire` (drop only the matching scaffold)
-Copy the matching `templates/<platform>/REVIEW_COMMENTS.md` into the repo's `.github/` or `.gitlab/`.
-Do not clobber an existing non-SDLC file of the same name — back it up / ask. Commit on the repo's
-default branch (shared infrastructure, not a task diff). Idempotent — re-running refreshes in place.
-
-### Step 3 — Stop (no auto-advance)
-Report what was committed. The scaffold is an aid to human review; it approves nothing and touches no
-`.sdlc/` state.
-
-## Hard rules
-
-- **Drop only the matching scaffold** for the detected platform.
-- **Attributable headers** — every canned comment keeps the `**<name> (<role>)**` form so the gate's
-  ledger and the PR thread agree.
-- **Nothing auto-advances.** Comments feed the human review and (via the bridge) `yad-review-gate`.
-
-## Reference
-- Comment conventions + the full scaffold contents: `references/comment-conventions.md`.
-- The ledger headings these match: `../yad-review-gate/SKILL.md` (comment action) and `references/gating.md`.
-- The review bridge that syncs platform comments into the ledger: `../yad-hub-bridge/SKILL.md`.

package/skills/yad-review-comments/references/comment-conventions.md

@@ -1,55 +0,0 @@
-# Review comment conventions
-
-The scaffold (`REVIEW_COMMENTS.md`) groups canned comments into **blocking** (a gate would fail / must
-be fixed before merge) and **non-blocking** (suggestions, nits, questions). Every comment starts with an
-attributable header:
-
-```
-**<name> (<role>)**
-```
-
-`<role>` is one of `owner | reviewer | domain-owner` — the same roles `yad-review-gate` records. This
-header matches the `## <name> (<role>)` headings the gate writes into
-`reviews/<artifact>--<date>--comments.md`, so a comment copied from the PR thread (or synced by
-`yad-hub-bridge`) needs no reformatting to land in the ledger.
-
-## Blocking comments (a gate or rule says stop)
-
-These map to the code-repo check gates (`yad-checks`) and the file-boundary / contract rules:
-
-- **spec-link** — "This commit has no `Task: <story>-<task>` trailer; the spec-link gate will fail. Add
-  the trailer (and ensure `specs/<story>/link.md` exists)."
-- **contract-check** — "This diff changes the contract surface without `Contract-Change: yes` + a
-  re-locked contract. Route back to the architecture gate and re-lock before this can merge."
-- **build-test-lint** — "Lint/build/test is red (or the test doesn't exercise the new behavior). The
-  build-test-lint gate must pass with a test that actually exercises the acceptance criterion."
-- **file-boundary** — "This diff touches files the task's `Files:` list didn't declare. Re-scope the
-  task (re-run `yad-spec`) rather than widening the diff silently."
-
-## Escalation / routing comment
-
-- **routing** — "Risk is `high` / a contract|auth|payments surface is touched — this needs a
-  domain-owner approval per touched repo (the same escalation `yad-review-gate` applies). Run
-  `bash checks/risk-route.sh <body>` (code repo) or `bash checks/hub-route.sh <body>` (hub)."
-
-## Non-blocking comments
-
-- **suggestion** — "Suggestion (non-blocking): …"
-- **nit** — "Nit: …"
-- **question** — "Question: … (not blocking — just want to understand)."
-
-## Approval note
-
-- **approve** — "Approving as `<role>`. Recorded in `approvals.json` (code-repo ship: `build-log.json`).
-  On the hub, your approval here is pulled in by `yad-review-gate action: sync`."
-
-## Hub front-artifact review
-
-The hub scaffold adds a **Front-artifact review** section whose headers mirror the gate's comment file
-exactly, so reviewing an `epic.md` / `architecture.md` / `ui-design.md` / `stories/` PR produces comments
-that drop straight into `reviews/<artifact>--<date>--comments.md`:
-
-```
-**<name> (<role>)**
-- <comment about scope / contract surface / acceptance signals / story split>
-```

package/skills/yad-review-comments/templates/github/REVIEW_COMMENTS.md

@@ -1,49 +0,0 @@
-# Review comments — canned replies
-
-Copy a block below into a PR review comment. Keep the `**<name> (<role>)**` header — it matches the
-SDLC review ledger (`reviews/<artifact>--<date>--comments.md`) so feedback stays attributable.
-`<role>` is one of `owner | reviewer | domain-owner`.
-
-## Blocking (a gate or rule says stop — must be fixed before merge)
-
-**<name> (<role>)**
-- spec-link: this range has no `Task: <story>-<task>` trailer — the spec-link gate will fail. Add the
-  trailer and make sure `specs/<story>/link.md` exists.
-
-**<name> (<role>)**
-- contract-check: this diff changes the contract surface without `Contract-Change: yes` + a re-locked
-  contract. Route back to the architecture gate and re-lock before merge.
-
-**<name> (<role>)**
-- build-test-lint: lint/build/test is red, or the test doesn't exercise the new behavior. The gate must
-  pass with a test that actually exercises the acceptance criterion.
-
-**<name> (<role>)**
-- file-boundary: this touches files the task's `Files:` list didn't declare. Re-scope the task (re-run
-  `yad-spec`) instead of widening the diff.
-
-## Routing / escalation
-
-**<name> (<role>)**
-- routing: risk is `high` / a contract|auth|payments surface is touched — needs a domain-owner approval
-  per touched repo (same escalation as `yad-review-gate`). Run `bash checks/risk-route.sh <body>`.
-
-## Non-blocking
-
-**<name> (<role>)**
-- Suggestion (non-blocking): …
-
-**<name> (<role>)**
-- Nit: …
-
-**<name> (<role>)**
-- Question: … (not blocking — just want to understand).
-
-## Approval
-
-**<name> (<role>)**
-- Approving as `<role>`. Recorded in `approvals.json` (ship: `build-log.json`).
-
----
-> Tip (GitHub): paste the blocks you use most into your personal **Saved Replies**
-> (Settings → Saved replies) so they are one click away in any PR.

package/skills/yad-review-comments/templates/gitlab/REVIEW_COMMENTS.md

@@ -1,49 +0,0 @@
-# Review comments — canned replies
-
-Copy a block below into an MR review comment. Keep the `**<name> (<role>)**` header — it matches the
-SDLC review ledger (`reviews/<artifact>--<date>--comments.md`) so feedback stays attributable.
-`<role>` is one of `owner | reviewer | domain-owner`.
-
-## Blocking (a gate or rule says stop — must be fixed before merge)
-
-**<name> (<role>)**
-- spec-link: this range has no `Task: <story>-<task>` trailer — the spec-link gate will fail. Add the
-  trailer and make sure `specs/<story>/link.md` exists.
-
-**<name> (<role>)**
-- contract-check: this diff changes the contract surface without `Contract-Change: yes` + a re-locked
-  contract. Route back to the architecture gate and re-lock before merge.
-
-**<name> (<role>)**
-- build-test-lint: lint/build/test is red, or the test doesn't exercise the new behavior. The gate must
-  pass with a test that actually exercises the acceptance criterion.
-
-**<name> (<role>)**
-- file-boundary: this touches files the task's `Files:` list didn't declare. Re-scope the task (re-run
-  `yad-spec`) instead of widening the diff.
-
-## Routing / escalation
-
-**<name> (<role>)**
-- routing: risk is `high` / a contract|auth|payments surface is touched — needs a domain-owner approval
-  per touched repo (same escalation as `yad-review-gate`). Run `bash checks/risk-route.sh <body>`.
-
-## Non-blocking
-
-**<name> (<role>)**
-- Suggestion (non-blocking): …
-
-**<name> (<role>)**
-- Nit: …
-
-**<name> (<role>)**
-- Question: … (not blocking — just want to understand).
-
-## Approval
-
-**<name> (<role>)**
-- Approving as `<role>`. Recorded in `approvals.json` (ship: `build-log.json`).
-
----
-> Tip (GitLab): paste the blocks you use most into your personal/group **Comment templates**
-> (Preferences → Comment templates) so they are one click away in any MR.