yadflow 3.11.1 → 3.12.1

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [3.12.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.12.0...v3.12.1) (2026-07-14)
+
+
+### Bug Fixes
+
+* **cli:** reject unsafe detected IDE targets and opencode write destinations ([792a40b](https://github.com/abdelrahmannasr/yadflow/commit/792a40b399b92f8db9d560e314110c432b98d93e)), closes [#134](https://github.com/abdelrahmannasr/yadflow/issues/134)
+* **cli:** repair and validate persisted IDE targets ([81242ed](https://github.com/abdelrahmannasr/yadflow/commit/81242ed9a075ea067acb2f4497a745ee40e540a6))
+
+# [3.12.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.11.1...v3.12.0) (2026-07-11)
+
+
+### Features
+
+* render an epic's kind as its noun in next/thread/status ([42e80e1](https://github.com/abdelrahmannasr/yadflow/commit/42e80e19e20e129a2a3941c85db6777a66ab00cc))
+
 ## [3.11.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.11.0...v3.11.1) (2026-07-11)
 
 

package/cli/epic-state.mjs

@@ -755,6 +755,13 @@ export function readFrontmatter(file) {
 
 const asList = (v) => (Array.isArray(v) ? v : v ? [v] : []);
 
+// The human-facing noun for a lineage kind. Presentation only — the artifact is always an epic
+// (`EP-<slug>`); this just renders WHAT KIND of work it is so `yad next`/`yad thread`/`yad status`
+// read as "Defect EP-…" / "Change request EP-…" instead of a generic "Epic". `feature` (and any
+// unknown/absent kind) falls back to "Epic". A bug is a defect (kind:defect) — no separate noun.
+export const KIND_NOUN = { feature: 'Epic', change: 'Change request', defect: 'Defect', hotfix: 'Hotfix' };
+export const kindNoun = (kind) => KIND_NOUN[kind] || 'Epic';
+
 // 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) {

package/cli/manifest.mjs

@@ -116,8 +116,10 @@ export const LEGACY_HUB_FILES = {
 };
 
 // IDE install targets (relative to the target project root).
-export const IDE_FOLDER_TARGETS = ['.claude', '.agents', '.zencoder']; // <ide>/skills/<skill>/ (folder copy)
-export const IDE_OPENCODE_DIR = '.opencode/commands'; // <skill>.md (flat SKILL.md copy)
+export const IDE_FOLDER_TARGETS = Object.freeze(['.claude', '.agents', '.zencoder']); // <ide>/skills/<skill>/ (folder copy)
+export const IDE_OPENCODE_TARGET = '.opencode';
+export const IDE_TARGETS = Object.freeze([...IDE_FOLDER_TARGETS, IDE_OPENCODE_TARGET]);
+export const IDE_OPENCODE_DIR = `${IDE_OPENCODE_TARGET}/commands`; // <skill>.md (flat SKILL.md copy)
 
 // Module registration files copied from skills/sdlc/ into _bmad/sdlc/.
 export const MODULE_FILES = ['config.yaml', 'module-help.csv'];

package/cli/next.mjs

@@ -13,7 +13,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { c, log, ok, info, warn, hand, fail, readJSON, exists } from './lib.mjs';
 import { PROJECT_FILES } from './manifest.mjs';
-import { epicRoot, loadLedger, nextAction, preconditionsMet, isValidEpicId, DISCOVERY_EPIC } from './epic-state.mjs';
+import { epicRoot, loadLedger, nextAction, preconditionsMet, isValidEpicId, epicLineage, kindNoun, DISCOVERY_EPIC } from './epic-state.mjs';
 
 // Is solo mode on? Persisted in hub.json by setup (Phase C/D); default false. Read defensively so a
 // missing/old hub.json never breaks the driver.
@@ -102,7 +102,10 @@ function actionLine(a, { solo } = {}) {
 
 // Full, friendly printout for a single epic.
 function printAction(a, { solo } = {}) {
-  log(`\n  ${c.bold(a.epicId || '(epic)')} ${c.dim(`— ${a.why}`)}`);
+  // Prefix the id with the kind noun (Defect / Change request / Hotfix / Epic) so a glance says what
+  // kind of work this is. The discovery front-zero is not a feature epic — leave it un-prefixed.
+  const noun = a.lineageKind && a.epicId !== DISCOVERY_EPIC ? `${kindNoun(a.lineageKind)} ` : '';
+  log(`\n  ${c.bold(`${noun}${a.epicId || '(epic)'}`)} ${c.dim(`— ${a.why}`)}`);
   // In the build half with live lanes, print each story/repo's next sub-step + remaining chain instead
   // of the single static hint; otherwise the one actionable line.
   if (a.kind === 'build' && a.builds?.length) printBuildLanes(a.builds);
@@ -139,7 +142,10 @@ function generalNext(root, { all } = {}) {
     return;
   }
 
-  const actions = featureEpics.map((id) => nextAction(loadLedger(epicRoot(root, id)), { epic: id }));
+  const actions = featureEpics.map((id) => ({
+    ...nextAction(loadLedger(epicRoot(root, id)), { epic: id }),
+    lineageKind: epicLineage(root, id).kind,
+  }));
   if (discoveryOpen) printAction(discoveryAction, { solo });   // an unfinished discovery comes first
 
   if (featureEpics.length === 1 || all) {
@@ -148,7 +154,7 @@ function generalNext(root, { all } = {}) {
   }
   // Several epics — list each with a one-liner, then point at the per-epic / --all views.
   log(`\n  ${c.bold(`${featureEpics.length} epics`)} ${c.dim('— next action each:')}`);
-  for (const a of actions) log(`    ${c.cyan(a.epicId)}  ${actionLine(a, { solo })}`);
+  for (const a of actions) log(`    ${c.cyan(`${kindNoun(a.lineageKind)} ${a.epicId}`)}  ${actionLine(a, { solo })}`);
   info(c.dim(`detail: ${c.bold('yad next <epic>')}  •  all at once: ${c.bold('yad next --all')}`));
 }
 
@@ -183,5 +189,8 @@ export async function runNext(root, { epic, check, all } = {}) {
     process.exitCode = 1;
     return;
   }
-  printAction(nextAction(loadLedger(epicDir), { epic }), { solo: isSolo(root) });
+  printAction(
+    { ...nextAction(loadLedger(epicDir), { epic }), lineageKind: epicLineage(root, epic).kind },
+    { solo: isSolo(root) },
+  );
 }

package/cli/plan.mjs

@@ -7,7 +7,7 @@ import {
   asset, exists, copyDir, copyFile, dirMatches, sameContent, readJSON,
 } from './lib.mjs';
 import {
-  SKILLS, IDE_FOLDER_TARGETS, IDE_OPENCODE_DIR, MODULE_FILES, wiringFor, HUB_WIRING, PROJECT_FILES,
+  SKILLS, IDE_TARGETS, IDE_OPENCODE_DIR, MODULE_FILES, wiringFor, HUB_WIRING, PROJECT_FILES,
   LEGACY_SKILLS, REMOVED_SKILLS, LEGACY_MARKER, LEGACY_REPO_FILES, LEGACY_HUB_FILES,
 } from './manifest.mjs';
 
@@ -36,13 +36,149 @@ const dirAction = (scope, item, src, dest, { root } = {}) => ({
   apply: () => copyDir(src, dest),
 });
 
-// Which IDE targets this project wants. Recorded at setup time; falls back to
-// whichever IDE base dirs already exist, else .claude.
+// Persisted state gets one deliberately narrow compatibility repair. Explicit setup/planner input
+// does not: a caller typo is an error, while the known v3.11.1 `.cluade` stamp is safely migrated.
+const PERSISTED_IDE_ALIASES = new Map([['.cluade', '.claude']]);
+const IDE_TARGET_ERROR_CODE = 'YAD_IDE_TARGET';
+const sameTargets = (a, b) => Array.isArray(a) && a.length === b.length && a.every((v, i) => v === b[i]);
+const displayTarget = (value) => {
+  if (value === undefined) return 'undefined';
+  try { return JSON.stringify(value) ?? String(value); } catch { return String(value); }
+};
+const ideTargetError = (message) => Object.assign(new Error(message), { code: IDE_TARGET_ERROR_CODE });
+const lstatIfPresent = (full) => {
+  try {
+    return fs.lstatSync(full);
+  } catch (e) {
+    if (e?.code === 'ENOENT') return null;
+    throw e;
+  }
+};
+const ideContainers = (ide) => ide === '.opencode'
+  ? [ide, IDE_OPENCODE_DIR]
+  : [ide, path.join(ide, 'skills')];
+
+function assertSafeIdeContainers(root, ide) {
+  for (const relPath of ideContainers(ide)) {
+    const stat = lstatIfPresent(path.join(root, relPath));
+    if (!stat) continue;
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      const kind = stat.isSymbolicLink() ? 'a symbolic link' : 'not a directory';
+      throw ideTargetError(`unsafe IDE target '${ide}': ${relPath} is ${kind}`);
+    }
+  }
+}
+
+function assertSafeOpenCodeWriteDestinations(root, skills) {
+  for (const skill of new Set(skills)) {
+    const relPath = path.join(IDE_OPENCODE_DIR, `${skill}.md`);
+    const stat = lstatIfPresent(path.join(root, relPath));
+    if (!stat) continue;
+    let kind = null;
+    if (stat.isSymbolicLink()) kind = 'a symbolic link';
+    else if (!stat.isFile()) kind = 'not a regular file';
+    else if (stat.nlink > 1) kind = 'linked to multiple paths';
+    if (kind) throw ideTargetError(`unsafe IDE target '.opencode': ${relPath} is ${kind}`);
+  }
+}
+
+// Pure target inspection. Valid entries are trimmed and deduplicated in input order; unsupported
+// entries are returned to the caller for reporting rather than ever becoming filesystem paths.
+export function normalizeIdeTargets(input, { repairAliases = false } = {}) {
+  const shapeValid = Array.isArray(input);
+  const invalid = shapeValid ? [] : [input];
+  const repaired = [];
+  const targets = [];
+  const seen = new Set();
+  for (const raw of shapeValid ? input : []) {
+    if (typeof raw !== 'string') { invalid.push(raw); continue; }
+    const trimmed = raw.trim();
+    const target = repairAliases ? (PERSISTED_IDE_ALIASES.get(trimmed) || trimmed) : trimmed;
+    if (!IDE_TARGETS.includes(target)) { invalid.push(raw); continue; }
+    if (target !== trimmed) repaired.push({ from: trimmed, to: target });
+    if (!seen.has(target)) { seen.add(target); targets.push(target); }
+  }
+  return { targets, invalid, repaired, shapeValid };
+}
+
+// Strict boundary for every explicit action-builder/setup input. Returning only canonical values
+// makes path construction below safe by construction.
+export function canonicalIdeTargets(input) {
+  const state = normalizeIdeTargets(input);
+  if (!state.shapeValid) {
+    throw ideTargetError(`IDE targets must be a non-empty array (supported: ${IDE_TARGETS.join(', ')})`);
+  }
+  if (state.invalid.length) {
+    throw ideTargetError(`unsupported IDE target(s): ${state.invalid.map(displayTarget).join(', ')} (supported: ${IDE_TARGETS.join(', ')})`);
+  }
+  if (!state.targets.length) {
+    throw ideTargetError(`at least one IDE target is required (supported: ${IDE_TARGETS.join(', ')})`);
+  }
+  return state.targets;
+}
+
+// A canonical relative name is necessary but not sufficient: an existing IDE root (or its install
+// container) could be a file or symlink that redirects writes/removals outside the project. Validate
+// every target before constructing ANY actions, so a bad later target cannot cause a partial install.
+export function safeIdeTargetsFor(root, input) {
+  const targets = canonicalIdeTargets(input);
+  for (const ide of targets) assertSafeIdeContainers(root, ide);
+  return targets;
+}
+
+// Fallback discovery must not promote a supported-looking file/symlink into an install target.
+// Keep unsafe entries for diagnostics, while returning only real IDE directories with safe install
+// containers. Unexpected filesystem errors remain fatal instead of being mistaken for bad input.
+export function detectedIdeTargetStateFor(root) {
+  const targets = [];
+  const unsafe = [];
+  for (const ide of IDE_TARGETS) {
+    if (!lstatIfPresent(path.join(root, ide))) continue;
+    try {
+      assertSafeIdeContainers(root, ide);
+      targets.push(ide);
+    } catch (e) {
+      if (e?.code !== IDE_TARGET_ERROR_CODE) throw e;
+      unsafe.push({ target: ide, message: e.message });
+    }
+  }
+  return { targets, unsafe };
+}
+
+// Which IDE targets this project wants. Persisted values are recovery-oriented: repair the one known
+// alias, filter everything else, then fall back to supported IDE dirs already present (or .claude).
+// The full state lets reconcile report drift without mutating during a read-only check.
+export function ideTargetStateFor(root) {
+  const stampPath = path.join(root, PROJECT_FILES.version);
+  const hasStamp = exists(stampPath);
+  const rec = readJSON(stampPath);
+  const recordIsObject = !!rec && typeof rec === 'object' && !Array.isArray(rec);
+  const hasField = recordIsObject && Object.hasOwn(rec, 'ideTargets');
+  const raw = hasField ? rec.ideTargets : undefined;
+  const normalized = normalizeIdeTargets(raw, { repairAliases: true });
+  let targets = normalized.targets;
+  let usedFallback = false;
+  let unsafeDetected = [];
+  if (!targets.length) {
+    const detected = detectedIdeTargetStateFor(root);
+    targets = detected.targets.length ? detected.targets : ['.claude'];
+    unsafeDetected = detected.unsafe;
+    usedFallback = true;
+  }
+  return {
+    ...normalized,
+    targets,
+    hasStamp,
+    recordIsObject,
+    hasField,
+    usedFallback,
+    unsafeDetected,
+    needsRepair: hasStamp && !sameTargets(raw, targets),
+  };
+}
+
 export function ideTargetsFor(root) {
-  const rec = readJSON(path.join(root, PROJECT_FILES.version));
-  if (rec?.ideTargets?.length) return rec.ideTargets;
-  const present = [...IDE_FOLDER_TARGETS, '.opencode'].filter((d) => exists(path.join(root, d)));
-  return present.length ? present : ['.claude'];
+  return ideTargetStateFor(root).targets;
 }
 
 // A brand-new first-party skill is `missing` on every existing install. Relabel that to status `'new'`
@@ -53,8 +189,10 @@ const asNewSkill = (a) => (a.status === 'missing' ? { ...a, status: 'new' } : a)
 
 // Module = skills installed into each IDE target + the _bmad/sdlc registration.
 export function moduleActions(root, ideTargets = ideTargetsFor(root)) {
+  const targets = safeIdeTargetsFor(root, ideTargets);
+  if (targets.includes('.opencode')) assertSafeOpenCodeWriteDestinations(root, SKILLS);
   const actions = [];
-  for (const ide of ideTargets) {
+  for (const ide of targets) {
     if (ide === '.opencode') {
       for (const s of SKILLS) {
         actions.push(asNewSkill(fileAction(
@@ -92,8 +230,15 @@ export function moduleActions(root, ideTargets = ideTargetsFor(root)) {
 // one, so a single update completes the rename even when the new copy would otherwise be
 // skipped as missing-scope.
 export function legacyModuleActions(root, ideTargets = ideTargetsFor(root)) {
+  const targets = safeIdeTargetsFor(root, ideTargets);
+  if (targets.includes('.opencode')) {
+    const writes = Object.entries(LEGACY_SKILLS)
+      .filter(([, old]) => exists(path.join(root, IDE_OPENCODE_DIR, `${old}.md`)))
+      .map(([skill]) => skill);
+    assertSafeOpenCodeWriteDestinations(root, writes);
+  }
   const actions = [];
-  for (const ide of ideTargets) {
+  for (const ide of targets) {
     for (const [skill, old] of Object.entries(LEGACY_SKILLS)) {
       if (ide === '.opencode') {
         const oldDest = path.join(root, IDE_OPENCODE_DIR, `${old}.md`);
@@ -137,8 +282,9 @@ export function legacyModuleActions(root, ideTargets = ideTargetsFor(root)) {
 // 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 targets = safeIdeTargetsFor(root, ideTargets);
   const actions = [];
-  for (const ide of ideTargets) {
+  for (const ide of targets) {
     for (const skill of REMOVED_SKILLS) {
       if (ide === '.opencode') {
         const dest = path.join(root, IDE_OPENCODE_DIR, `${skill}.md`);

package/cli/reconcile.mjs

@@ -14,6 +14,7 @@ import { VERSION, PROJECT_FILES } from './manifest.mjs';
 import {
   moduleActions, repoActions, hubActions, authorsActions,
   legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
+  ideTargetStateFor,
 } from './plan.mjs';
 import { gitHead, packRepo } from './setup.mjs';
 import { groupByRoot, commitUpdates } from './update-commit.mjs';
@@ -31,14 +32,36 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
   const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
   if (!exists(path.join(root, PROJECT_FILES.reposRegistry))) gaps.push('no repos registered (.sdlc/repos.json absent)');
 
+  // Resolve untrusted persisted IDE targets once, before any filesystem action is constructed.
+  // The returned list contains canonical allowlisted roots only.
+  const ideState = ideTargetStateFor(root);
+  const ideTargets = ideState.targets;
+  const stampPath = path.join(root, PROJECT_FILES.version);
+  const writeCanonicalStamp = () => {
+    const current = readJSON(stampPath, {});
+    const record = current && typeof current === 'object' && !Array.isArray(current) ? current : {};
+    writeJSON(stampPath, { ...record, version: VERSION, ideTargets });
+  };
+
   // --- 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)
   //     and purge of skills removed in a later release ('removed': delete the lingering install) ---
   const actions = [
-    ...moduleActions(root), ...legacyModuleActions(root), ...removedModuleActions(root),
+    ...moduleActions(root, ideTargets), ...legacyModuleActions(root, ideTargets), ...removedModuleActions(root, ideTargets),
     ...hubActions(root), ...legacyHubActions(root),
     ...authorsActions(root, registry.repos),
   ];
+  if (ideState.needsRepair) {
+    actions.push({
+      scope: 'hub',
+      item: `${PROJECT_FILES.version} ideTargets`,
+      status: 'outdated',
+      root,
+      paths: [PROJECT_FILES.version],
+      // The canonical stamp is written once, after every filesystem action succeeds below.
+      apply: () => undefined,
+    });
+  }
   for (const repo of registry.repos) actions.push(...repoActions(root, repo), ...legacyRepoActions(root, repo));
 
   // --- stale code-context (HEAD moved since last pack) ---
@@ -77,6 +100,30 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
     for (const i of notOk) log(`    ${MARK[i.status]}  ${i.item}`);
   }
   for (const g of gaps) warn(g);
+  const shownInvalid = ideState.invalid.map((v) => {
+    try { return JSON.stringify(v) ?? String(v); } catch { return String(v); }
+  });
+  if (ideState.hasStamp && !ideState.recordIsObject) {
+    warn(`${PROJECT_FILES.version}: version stamp is unreadable or not a JSON object; using safe targets: ${ideTargets.join(', ')}`);
+  } else if (ideState.hasStamp && !ideState.hasField) {
+    warn(`${PROJECT_FILES.version}: ideTargets is missing; using safe targets: ${ideTargets.join(', ')}`);
+  } else if (ideState.hasStamp && !ideState.shapeValid) {
+    warn(`${PROJECT_FILES.version}: ideTargets is not an array; ignored persisted value: ${shownInvalid.join(', ')}; using safe targets: ${ideTargets.join(', ')}`);
+  } else if (ideState.hasStamp && ideState.usedFallback && !ideState.invalid.length) {
+    warn(`${PROJECT_FILES.version}: ideTargets is empty; using safe targets: ${ideTargets.join(', ')}`);
+  }
+  if (ideState.invalid.length && ideState.shapeValid) {
+    warn(`${PROJECT_FILES.version}: ignored unsupported persisted IDE target(s): ${shownInvalid.join(', ')}`);
+  }
+  if (ideState.repaired.length) {
+    warn(`${PROJECT_FILES.version}: persisted .cluade target will be repaired to .claude`);
+  }
+  for (const unsafe of ideState.unsafeDetected) {
+    warn(`${PROJECT_FILES.version}: ignored unsafe detected IDE path '${unsafe.target}'; ${unsafe.message}; using safe targets: ${ideTargets.join(', ')}`);
+  }
+  if (exists(path.join(root, '.cluade'))) {
+    warn('existing .cluade path was left untouched; review its contents and remove it manually');
+  }
 
   const fixable = actions.filter((a) =>
     a.status !== 'ok' && (scope === 'all' ? true : a.status !== 'missing'),
@@ -103,9 +150,9 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
   if (force) {
     for (const a of actions.filter((a) => a.status === 'ok')) { a.apply(); appliedActions.push(a); }
   }
-  // refresh the version stamp (preserve recorded ideTargets) and let it ride the hub's update commit
-  const rec = readJSON(path.join(root, PROJECT_FILES.version), {});
-  writeJSON(path.join(root, PROJECT_FILES.version), { ...rec, version: VERSION });
+  // Refresh the version stamp and persist only the canonical targets used to build actions. This also
+  // completes legacy/corrupt target migration even when no skill content itself needed an update.
+  writeCanonicalStamp();
   appliedActions.push({ scope: 'hub', item: PROJECT_FILES.version, status: 'stamp', root, paths: [PROJECT_FILES.version] });
   applied ? ok(`reconciled ${applied} item(s)`) : info('nothing to fix');
   if (gaps.length) hand('one-time setup still missing — run `yad setup`.');

package/cli/setup.mjs

@@ -6,10 +6,11 @@ import {
   c, log, step, guide, ok, info, warn, hand, fail, ask, askYesNo, run, has,
   exists, readJSON, readJSONStrict, writeJSON,
 } from './lib.mjs';
-import { VERSION, IDE_FOLDER_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY, TESTING_TOOLS, TESTING_PRIMARY, LEARNING_TOOLS, LEARNING_PRIMARY } from './manifest.mjs';
+import { VERSION, IDE_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY, TESTING_TOOLS, TESTING_PRIMARY, LEARNING_TOOLS, LEARNING_PRIMARY } from './manifest.mjs';
 import {
   moduleActions, repoActions, hubActions, authorsActions,
   legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
+  safeIdeTargetsFor, detectedIdeTargetStateFor,
 } from './plan.mjs';
 import { validateLogin, rolesForScope } from './platform.mjs';
 
@@ -34,7 +35,26 @@ export function parseRolesSpec(s) {
   return out;
 }
 
-const ALL_IDES = [...IDE_FOLDER_TARGETS, '.opencode'];
+// Programmatic setup is strict; interactive setup keeps asking until it receives at least one valid
+// canonical target. Both paths return the same trimmed, ordered, deduplicated representation.
+export async function selectIdeTargets(root, provided, asker = ask) {
+  if (provided !== undefined) return safeIdeTargetsFor(root, provided);
+  const detected = detectedIdeTargetStateFor(root);
+  const present = detected.targets;
+  for (const unsafe of detected.unsafe) warn(`${unsafe.message}; excluded from IDE defaults`);
+  const def = (present.length ? present : ['.claude']).join(',');
+  for (;;) {
+    const answer = await asker(`IDE targets to install ${c.dim('(comma-separated: ' + IDE_TARGETS.join(', ') + ')')}`, def);
+    if (answer === undefined || answer === null) throw new Error('IDE target selection ended before a valid choice was provided');
+    const values = String(answer ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    try {
+      return safeIdeTargetsFor(root, values);
+    } catch (e) {
+      if (process.env.SDLC_NONINTERACTIVE || e?.code !== 'YAD_IDE_TARGET') throw e;
+      warn(e.message);
+    }
+  }
+}
 
 export function detectPlatform(remoteUrl = '') {
   if (/gitlab/i.test(remoteUrl)) return 'gitlab';
@@ -416,13 +436,7 @@ export async function runSetup(root, opts = {}) {
     'Copies the yad-* skills into your AI tool(s) so they appear in Claude Code / agents / opencode.',
     'Enter the IDE folders to install into, comma-separated; default = whatever is already present.',
   ]);
-  let ideTargets = opts.ideTargets;
-  if (!ideTargets) {
-    const present = ALL_IDES.filter((d) => exists(path.join(root, d)));
-    const def = (present.length ? present : ['.claude']).join(',');
-    const answer = await ask(`IDE targets to install ${c.dim('(comma-separated: ' + ALL_IDES.join(', ') + ')')}`, def);
-    ideTargets = answer.split(',').map((s) => s.trim()).filter(Boolean);
-  }
+  const ideTargets = await selectIdeTargets(root, opts.ideTargets);
   applyActions(moduleActions(root, ideTargets), { force: true });
   // Migrate any pre-2.0 install in place: remove the old sdlc-* skill copies in the project's
   // IDE targets and install their yad-* renames. Without this, setup only ADDED yad-* and left

package/cli/thread.mjs

@@ -7,7 +7,7 @@ import fs from 'node:fs';
 import { c, log, ok, info, warn, hand, readJSON, exists } from './lib.mjs';
 import { readShips } from './ledger.mjs';
 import {
-  epicRoot, isValidEpicId, epicLineage, readFrontmatter, isStubEpic,
+  epicRoot, isValidEpicId, epicLineage, readFrontmatter, isStubEpic, kindNoun,
   resolveThread, threadEpics, resolveCurrentArtifacts, resolveCurrentStories, THREAD_ARTIFACT_BASES,
 } from './epic-state.mjs';
 
@@ -73,7 +73,10 @@ export function threadSummary(root, threadOrEpic) {
   };
 }
 
-const KIND_TAG = { feature: c.green('feature'), change: c.cyan('change'), defect: c.yellow('defect'), hotfix: c.red('hotfix') };
+// Colour a node's kind noun for the tree render. The noun words live in one place (`kindNoun`); this
+// only layers the per-kind colour on top, so the two never drift. Unknown kind → uncoloured noun.
+const KIND_COLOR = { feature: c.green, change: c.cyan, defect: c.yellow, hotfix: c.red };
+const kindTag = (kind) => (KIND_COLOR[kind] || ((s) => s))(kindNoun(kind));
 
 export async function runThread(root, { epic, json = false } = {}) {
   if (!epic) {
@@ -103,7 +106,7 @@ export async function runThread(root, { epic, json = false } = {}) {
   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 tag = kindTag(n.kind);
     const seal = n.sealed ? c.dim(' [sealed]') : '';
     const stub = n.stub ? c.yellow(' [stub · backfill pending]') : '';
     const dep = n.depth ? c.dim(` ${n.depth}`) : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.11.1",
+  "version": "3.12.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 + 38 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/yad-status/SKILL.md

@@ -35,8 +35,11 @@ Do not modify any of them.
 ### Step 3 — Report
 Print, in this order:
 
-1. **Epic:** `epicId`, `status` from `epic.md` frontmatter, `currentStep`, and `repos` (the touched
-   domains).
+1. **Header:** render the kind noun from `epic.md` frontmatter `kind` — **Change request** (`change`),
+   **Defect** (`defect`), **Hotfix** (`hotfix`), or **Epic** (`feature`, and the default when `kind` is
+   absent) — followed by `epicId`, then `status` from `epic.md` frontmatter, `currentStep`, and `repos`
+   (the touched domains). Example: `Defect EP-istifta-queue-filter — draft @ stories`. A bug is a defect
+   (`kind: defect`) — there is no separate noun. This is presentation only; the artifact is still an epic.
 2. **Steps table** — for every front step in `steps[]` order (10, or 12 when the optional analysis step
    was run): `id`, `type`, `status`, `assistance`, `automation`, `locked`, and `risk_tags`. Mark the
    `currentStep` with `→`. The gating chain is `[analysis → analysis-review →] epic → epic-review →

package/skills/yad-timeline/SKILL.md

@@ -48,7 +48,9 @@ deterministically; theme from the design system). The thread maps onto the shell
   = what it re-authored, its side-effects = the ships it produced + any contract re-lock.
 - **System components** = the artifacts (epic/architecture/contract/ui/stories/test-cases), each labelled
   with the epic that currently **owns** it (from the resolved map).
-- Colour nodes by `kind` (feature/change/defect/hotfix); mark sealed epics and open debt.
+- Label and colour nodes by `kind` — render each node's kind noun (**Change request** / **Defect** /
+  **Hotfix** / **Epic** for feature) alongside its id, not the generic word "epic"; mark sealed epics and
+  open debt. (A bug is a defect — `kind: defect`. Presentation only; every node is still an epic.)
 
 ### Step 4 — Emit `thread-resolved.md` (the current-truth map — derived, non-authoritative)
 Write `epics/<thread>/thread-resolved.md`: for each artifact base, the **owning epic** (the latest in the
@@ -58,7 +60,7 @@ is the file the next `yad-change` / `yad-epic` reads as "the feature's current t
 
 ### Step 5 — Emit `TIMELINE.md` + (optional) deploy
 Write a short `epics/<thread>/TIMELINE.md` (the chain, what each node changed, ships, open debt) for a
-plain-text read. On `action: deploy`, `yad docs deploy` the site (build-only when no target).
+plain-text read — head each node with its kind noun (Change request / Defect / Hotfix / Epic) + id. On `action: deploy`, `yad docs deploy` the site (build-only when no target).
 
 ## Hard rules