yadflow 3.11.0 → 3.12.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [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)
+
+
+### Bug Fixes
+
+* **gate:** close the authoring step when its review gate advances ([8baaed9](https://github.com/abdelrahmannasr/yadflow/commit/8baaed9416a063013b5e6acf1ae36c5a1b3c920b))
+* **setup:** contain repo paths to the workspace so sibling repos connect ([265a7ae](https://github.com/abdelrahmannasr/yadflow/commit/265a7ae543fccf8697ff89726ecb1a6aadde62ce))
+
 # [3.11.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.10.1...v3.11.0) (2026-07-09)
 
 

package/bin/yad.mjs

@@ -4,7 +4,7 @@ import { VERSION } from '../cli/manifest.mjs';
 import { c, log, closePrompts, askYesNo } from '../cli/lib.mjs';
 import { runSetup } from '../cli/setup.mjs';
 import { reconcile } from '../cli/reconcile.mjs';
-import { gateOpen, gateSync, gateComments, gateStatus, gateCi, gateReview, gateTrailer, gateWalkthrough } from '../cli/gate.mjs';
+import { gateOpen, gateSync, gateComments, gateStatus, gateCi, gateReview, gateTrailer, gateWalkthrough, gateRepair } from '../cli/gate.mjs';
 import { isValidEpicId } from '../cli/epic-state.mjs';
 import { runCommit } from '../cli/commit.mjs';
 import { runOpenPr } from '../cli/openpr.mjs';
@@ -78,6 +78,8 @@ ${c.bold('Review gate (front half)')}
   yad gate sync <epic> [artifact]      Pull PR state -> ledger; advance on approved+resolved+merged
   yad gate comments <epic> [artifact]  Fetch unresolved review comments to address
   yad gate status <epic>               Show each review step + approvals
+  yad gate repair <epic> [--push]      Close an author step stranded behind a passed review gate
+                                       (YAD-STATE-005); --push commits state.json to the default branch
   yad gate review <epic> [artifact]    Print the grounding bundle for the review companion
                                        (artifact + risk + contract + PR + code-maps) — fun, easy review
   yad gate walkthrough <epic> [artifact]  Grounding bundle + ordered risk-tagged stops for the
@@ -259,7 +261,7 @@ async function main() {
       const [, action, epic, artifact] = o._;
       // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).
       if (action === 'ci') { await gateCi(o.dir, { branch: o.branch, pr: o.pr, merged: o.merged, push: !o.noPush, today }); break; }
-      if (!epic) { log(c.red('usage: yad gate <open|sync|comments|status|review|walkthrough|trailer|ci> <epic> [artifact]')); process.exitCode = 1; break; }
+      if (!epic) { log(c.red('usage: yad gate <open|sync|comments|status|repair|review|walkthrough|trailer|ci> <epic> [artifact]')); process.exitCode = 1; break; }
       // The epic id becomes a path segment under epics/ — reject anything but EP-<slug> outright.
       if (!isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
       // In bridge mode CI is the sole ledger writer: `open` only opens the PR, and local `sync` is
@@ -269,10 +271,11 @@ async function main() {
       else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today, local: true });
       else if (action === 'comments') await gateComments(o.dir, { epic, artifact, today });
       else if (action === 'status') await gateStatus(o.dir, { epic });
+      else if (action === 'repair') await gateRepair(o.dir, { epic, push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun });
       else if (action === 'review') await gateReview(o.dir, { epic, artifact });
       else if (action === 'walkthrough') await gateWalkthrough(o.dir, { epic, artifact });
       else if (action === 'trailer') await gateTrailer(o.dir, { epic, artifact, body: o.body || o.message, number: o.pr });
-      else { log(c.red(`unknown gate action: ${action} (open|sync|comments|status|review|walkthrough|trailer|ci)`)); process.exitCode = 1; }
+      else { log(c.red(`unknown gate action: ${action} (open|sync|comments|status|repair|review|walkthrough|trailer|ci)`)); process.exitCode = 1; }
       break;
     }
     case 'review': {

package/cli/doctor.mjs

@@ -6,9 +6,9 @@ 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, isValidEpicId, epicLineage, resolveThread } from './epic-state.mjs';
+import { loadLedger, epicRoot, isValidEpicId, epicLineage, resolveThread, stateInvariants } from './epic-state.mjs';
 import { loadDebt } from './thread.mjs';
-import { gitHead } from './setup.mjs';
+import { gitHead, insideWorkspace } from './setup.mjs';
 import { cliFor, validateLogin, hostFromGitUrl } from './platform.mjs';
 
 const MIN_NODE = 18;
@@ -18,6 +18,18 @@ const MIN_NODE = 18;
 const isSolo = (hub) => !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
 // owner/repo slug from a git url (https or ssh), for the branch-protection probe.
 const repoSlug = (url) => ((url || '').match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/) || [])[1] || null;
+// Is an already-resolved path nested under the project root? Repo paths are contained to the WORKSPACE
+// (the root's parent, see setup.insideWorkspace), so a registered sibling resolves outside the root —
+// which is what distinguishes "absent because it lives elsewhere" from "absent because it is broken".
+// The path.sep suffix keeps /proj-evil from reading as inside /proj.
+const underProjectRoot = (root, p) => {
+  const projectRoot = path.resolve(root);
+  return p === projectRoot || p.startsWith(projectRoot + path.sep);
+};
+// An absent path is only excused as "a sibling that lives elsewhere" when it is one the connect step
+// would actually accept. A hand-edited registry pointing outside the workspace entirely (../../x) is
+// corruption, and must not be reassured away as an expected sibling.
+const isRegistrableSibling = (root, rpath) => insideWorkspace(root, rpath);
 
 // Each check: { id, section, status: 'ok'|'warn'|'fail', message, hint? }
 function check(checks, id, section, status, message, hint = '') {
@@ -213,7 +225,15 @@ export function projectChecks(checks, root) {
       // would read as "healthy") — an entry with no path is malformed.
       if (!repo.path) { check(checks, `repo:${repo.name || '(unnamed)'}`, 'project', 'fail', `${repo.name || '(unnamed)'}: no \`path\` in repos.json [YAD-STATE-003]`, 're-connect the repo (`yad setup`)'); continue; }
       const repoRoot = path.resolve(root, repo.path);
-      if (!exists(repoRoot)) { check(checks, `repo:${repo.name}`, 'project', 'fail', `${repo.name}: path ${repo.path} does not exist [YAD-STATE-003]`, 'fix the path in repos.json or re-connect the repo'); continue; }
+      // A registered repo may be a SIBLING of the hub (`../backend`, the standard multi-repo layout).
+      // Such a checkout is legitimately absent wherever only the hub is checked out — hub CI, a fresh
+      // clone — so its absence is a warn, not corruption. A missing path INSIDE the project root is
+      // still a hard fail: nothing but damage explains it.
+      if (!exists(repoRoot)) {
+        if (underProjectRoot(root, repoRoot) || !isRegistrableSibling(root, repo.path)) check(checks, `repo:${repo.name}`, 'project', 'fail', `${repo.name}: path ${repo.path} does not exist [YAD-STATE-003]`, 'fix the path in repos.json or re-connect the repo');
+        else check(checks, `repo:${repo.name}`, 'project', 'warn', `${repo.name}: ${repo.path} is not present in this checkout (sibling repo, outside the hub)`, 'expected when only the hub is checked out; clone it alongside the hub to work on it here');
+        continue;
+      }
       const head = gitHead(repoRoot);
       if (!head) { check(checks, `repo:${repo.name}`, 'project', 'fail', `${repo.name}: ${repo.path} is not a git repository (or has no commits) [YAD-STATE-003]`, 'init/clone the repo, then re-connect it'); continue; }
       if (!repo.syncedHead) check(checks, `repo:${repo.name}`, 'project', 'warn', `${repo.name}: registered without a code-context pack (greenfield)`, 'run `yad repo refresh ' + repo.name + '` once it has code');
@@ -270,6 +290,13 @@ export function epicChecks(checks, root) {
       if (!ledger.state) check(checks, `epic:${e}`, 'epics', 'warn', `${e}: no state.json — epic not seeded`, 'author it via yad-epic, or remove the directory');
       else {
         check(checks, `epic:${e}`, 'epics', 'ok', `${e}: currentStep ${ledger.state.currentStep}`);
+        // Chain consistency: a passed review gate whose author step was never closed. currentStep alone
+        // cannot see this, yet it blocks every later step (including the parallel test-cases track).
+        for (const v of stateInvariants(ledger.state)) {
+          check(checks, `epic:${e}:${v.authorStep}`, 'epics', 'fail',
+            `${e}: ${v.message} [${v.code}]`,
+            `run \`yad gate repair ${e}\` to close it`);
+        }
         // Migration guard (pre-3.0 model): under the current model CI records the ledger on the
         // default branch only at merge (when the step is already done), and writes nothing during
         // review — so an OPEN (non-done) review PR recorded here means it was opened under an older

package/cli/epic-state.mjs

@@ -184,6 +184,29 @@ export function findReviewStep(state, artifact) {
 export const isEscalated = (step) =>
   (step?.risk_tags || []).some((t) => RISK_ESCALATORS.includes(t)) || step?.id === 'stories-review';
 
+// The authoring step paired with a review gate: `stories-review` -> `stories`. Resolved BY ID (the
+// same `-review` suffix convention `isSkippableStep` uses), never positionally — a chain may legally
+// omit the author step (a change-epic that carries only the gate), and `steps[i-1]` would then point
+// at an unrelated step. Returns null when the chain has no such step.
+export function authorStepFor(state, reviewStep) {
+  const id = String(reviewStep?.id || '');
+  if (!id.endsWith('-review')) return null;
+  return state?.steps?.find((s) => s.id === id.replace(/-review$/, '')) || null;
+}
+
+// Closing a review gate implies its artifact was authored — so the CLI, not the authoring skill, is
+// what makes `<step>.status = done` true. Without this an author step left at `in_progress` strands
+// forever: `preconditionsMet` requires every PRIOR step done, so the parallel `test-cases` track (and
+// every later step) stays blocked behind a review that already passed. Idempotent; a no-op on an
+// absent step and on a `skipped` one (already `done`, carrying its skip provenance).
+// Returns the id it closed, or null.
+function closeAuthorStep(state, reviewStep) {
+  const author = authorStepFor(state, reviewStep);
+  if (!author || author.status === 'done') return null;
+  author.status = 'done';
+  return author.id;
+}
+
 const uniqueBy = (arr, key) => {
   const seen = new Set();
   return arr.filter((x) => (seen.has(x[key]) ? false : seen.add(x[key])));
@@ -293,6 +316,10 @@ export function gatePredicate({
 export function advanceState(state, step) {
   const i = state.steps.findIndex((s) => s.id === step.id);
   state.steps[i] = { ...state.steps[i], status: 'done' };
+  // Defensive: `markInReview` normally closed the author step when the gate opened, but the CI bridge
+  // advances on a merge event without ever running it locally. Close it here too, so a passed gate can
+  // never leave its author step behind (issue #131).
+  closeAuthorStep(state, step);
   if (step.id === 'stories-review') {
     const tc = state.steps.find((s) => s.id === 'test-cases');
     if (tc && tc.status === 'blocked') tc.status = 'in_progress';
@@ -442,6 +469,9 @@ export function unskipStep(state, stepId) {
 export function markInReview(state, step) {
   const i = state.steps.findIndex((s) => s.id === step.id);
   if (state.steps[i].status !== 'done') state.steps[i].status = 'in_review';
+  // Opening a review gate means the artifact was authored — close the paired author step rather than
+  // trusting the authoring skill to have hand-edited state.json (issue #131).
+  closeAuthorStep(state, step);
   if (state.currentStep !== 'ready-for-build') state.currentStep = step.id;
   return state;
 }
@@ -567,6 +597,43 @@ export function preconditionsMet(state, stepId) {
   return { ok: true, blockedBy: null, reason: 'ready' };
 }
 
+// PURE. Consistency invariants over a chain, for `doctor` (report) and `gate repair` (heal). Today one
+// rule: a `review+approve` step that is `done` must have its paired author step `done` too — a gate
+// cannot have passed on an unauthored artifact. Violations are epics damaged by a pre-fix `gate sync`
+// (issue #131); they read as healthy to a `currentStep`-only check while silently blocking every later
+// step through `preconditionsMet`.
+//
+// Deliberately NOT the broader "no non-done step precedes a done one": the parallel `test-cases` track
+// legitimately sits `in_progress` after `stories-review` advanced the epic to ready-for-build.
+// No FS / network. Returns [] on a missing or malformed chain (loadLedger already reports that).
+export function stateInvariants(state) {
+  if (!state || !Array.isArray(state.steps)) return [];
+  const violations = [];
+  for (const step of state.steps) {
+    if (step.type !== 'review+approve' || step.status !== 'done') continue;
+    const author = authorStepFor(state, step);
+    if (!author || author.status === 'done') continue;
+    violations.push({
+      code: 'YAD-STATE-005',
+      reviewStep: step.id,
+      authorStep: author.id,
+      message: `${author.id} is '${author.status}' behind a completed ${step.id}`,
+    });
+  }
+  return violations;
+}
+
+// Apply the repair `stateInvariants` describes: close every author step stranded behind a done review
+// gate. Mutates `state` and returns the ids it closed (empty when already consistent — idempotent).
+export function repairState(state) {
+  const closed = [];
+  for (const v of stateInvariants(state)) {
+    const author = state.steps.find((s) => s.id === v.authorStep);
+    if (author && author.status !== 'done') { author.status = 'done'; closed.push(author.id); }
+  }
+  return closed;
+}
+
 // PURE next-action resolver for ONE epic's ledger — what `yad next <epic>` prints. Reads state + the
 // recorded review PRs only. kind:
 //   'new'         — no epic state yet (seed one with yad-epic)
@@ -688,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/errors.mjs

@@ -20,6 +20,7 @@ export const CODES = {
   'YAD-STATE-002': 'a ledger/config JSON file parses but has the wrong shape',
   'YAD-STATE-003': 'a registered repo path is missing or not a git repository',
   'YAD-STATE-004': 'an epic step cannot be skipped / un-skipped in its current state',
+  'YAD-STATE-005': 'an authoring step is stranded behind its completed review gate',
   'YAD-CFG-001': 'hub.json names an unknown platform (expected github, gitlab, or null)',
   'YAD-CFG-002': 'design.json names an unknown design tool (expected one of config.yaml design.tools, or none)',
   'YAD-CFG-003': 'testing.json names an unknown testing tool (expected one of config.yaml testing.tools, or none)',

package/cli/gate.mjs

@@ -11,8 +11,9 @@ import { PROJECT_FILES } from './manifest.mjs';
 import {
   epicRoot, loadLedger, findReviewStep, artifactBase, artifactHash, gatePredicate,
   advanceState, markInReview, isEscalated, parseReviewBranch, artifactFromBase,
-  upsertHubPr, DISCOVERY_FILES,
+  upsertHubPr, stateInvariants, repairState, DISCOVERY_FILES,
 } from './epic-state.mjs';
+import { hubGit, preflightGuardReadiness, resolveDefaultBranch, guardDefaultBranch } from './hubcommit.mjs';
 import {
   readPr, mapApprovers, createPr, reviewersForScopes, resolveCommitterLogin,
   getPrBody, editPrBody, postComment,
@@ -486,6 +487,70 @@ export async function gateStatus(root, { epic } = {}) {
   }
 }
 
+// PURE — the audit-trail commit message for a state repair (mirrors buildCheckpointMessage). The
+// subject passes the hub commit-message gate (valid type `chore`, scope `gate`, no trailing period)
+// and carries [skip ci]: the repair lands on the default branch, where a re-triggered gate workflow
+// would have nothing to do. No Task trailer and no Co-Authored-By footer — this is machine state a
+// human corrected, not an authored code change.
+export function buildRepairMessage({ epic, steps }) {
+  const subject = 'chore(gate): repair epic state — close stranded author step(s) [skip ci]';
+  return `${subject}\n\nEpic: ${epic}\nClosed: ${steps.join(', ')}\nReason: YAD-STATE-005 — author step(s) left behind a completed review gate`;
+}
+
+// `yad gate repair <epic>` — heal the chain inconsistency `doctor` reports as YAD-STATE-005: an author
+// step stranded at in_progress behind a review gate that already advanced (issue #131). A pre-fix
+// `gate sync` could leave this, and it never self-heals — sync skips a step that is already `done` — so
+// the damage needs an explicit, auditable correction.
+//
+// Only state.json is touched, and `--push` commits ONLY that file: a `[skip ci]` chore commit must never
+// sweep up an unrelated edit. It lands on the DEFAULT branch, where `ledger-guard` (which polices the
+// machine-written ledger on review PRs) does not apply — so this stays compatible with "CI is the sole
+// writer of the ledger" during review.
+export async function gateRepair(root, { epic, push = false, allowBranch = false, dryRun = false } = {}) {
+  const epicDir = epicRoot(root, epic);
+  const ledger = loadLedger(epicDir);
+  if (!ledger.state) { fail(`no epic state at ${epicDir}/.sdlc/state.json`); process.exitCode = 1; return { closed: [] }; }
+
+  log(c.bold(`\nyad gate repair  ${c.dim(epic)}`));
+  const violations = stateInvariants(ledger.state);
+  if (!violations.length) { ok('epic state is consistent — nothing to repair'); return { closed: [] }; }
+  for (const v of violations) warn(`${v.message} [${v.code}]`);
+
+  const closed = repairState(ledger.state);
+  if (dryRun) { info('dry run — nothing written'); return { closed }; }
+  writeJSON(ledger.files.state, ledger.state);
+  ok(`closed ${closed.length} stranded author step(s): ${c.dim(closed.join(', '))}`);
+  if (!push) { hand('re-run `yad doctor` to confirm, then commit epics/*/.sdlc/state.json (or re-run with --push)'); return { closed }; }
+
+  // --- publish: narrow, default-branch-only commit of the one repaired file ---
+  preflightGuardReadiness(root);
+  const git = hubGit(root);
+  const branch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
+  const defaultBranch = resolveDefaultBranch(git, loadHub(root).hub);
+  if (!guardDefaultBranch(branch, defaultBranch, { allowBranch, cmd: 'yad gate repair' })) return { closed };
+
+  const spec = path.relative(root, ledger.files.state);
+  if (!git('add', '--', spec).ok) { fail(`git add failed for ${spec}`); process.exitCode = 1; return { closed }; }
+  if (git('diff', '--cached', '--quiet', '--', spec).ok) { info('state.json unchanged on disk — nothing to commit'); return { closed }; }
+
+  const message = buildRepairMessage({ epic, steps: closed });
+  const cm = git('commit', '-m', message, '--', spec);
+  if (!cm.ok) {
+    git('reset', '-q', '--', spec); // never leave it staged for an unrelated commit to sweep up
+    fail(`git commit failed — ${cm.stderr.split('\n')[0] || cm.code}`);
+    process.exitCode = 1;
+    return { closed };
+  }
+  ok(`committed the repair: ${c.dim(message.split('\n')[0])}`);
+  // Push HEAD to its OWN branch — with --allow-branch we are not on the default branch, and pushing
+  // HEAD:defaultBranch would publish a WIP branch straight to it.
+  if (pushWithRebase(root, branch).ok) { ok(`pushed to origin/${branch}`); return { closed }; }
+  fail(`could not push to origin/${branch} — a protected branch, or an unresolvable rebase conflict`);
+  hand('run `git pull --rebase` and re-run `yad gate repair <epic> --push`');
+  process.exitCode = 1;
+  return { closed };
+}
+
 // `head` overrides the review branch the PR is opened against — `open-pr` delegates here after pushing
 // the user's checked-out branch, which for a per-story review (review/EP-*/stories-S01) does NOT equal
 // the branch this would otherwise recompute (artifactFromBase collapses stories-S01 → stories/). Pass

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

@@ -43,14 +43,28 @@ export function detectPlatform(remoteUrl = '') {
 }
 export const gitHead = (cwd) => run('git', ['rev-parse', 'HEAD'], { cwd }).stdout || null;
 
-// Containment: every repo path must live inside the project root — the registry path is later
-// joined and executed against (repomix cwd, CI wiring), and even the read-only remote probe must
-// not run against an arbitrary outside path. The path.sep-suffixed compare avoids the
-// /proj vs /proj-evil prefix trap.
-export function insideRoot(root, rpath) {
+// Containment: a repo path must live inside the WORKSPACE — the hub root's parent. The standard
+// multi-repo layout puts the code repos BESIDE the hub, not under it (project/{product,backend,frontend}),
+// so `../backend` has to register; containing to the hub root instead forced separate git repos to nest
+// inside the hub's own repo (issue #129). A nested path (demo-repos/api) still works.
+//
+// The bound stays real: the registry path is later joined and executed against (repomix cwd,
+// .coderabbit.yaml + CI wiring), and even the read-only remote probe must not run against an arbitrary
+// outside path — so `../../elsewhere` and absolute-outside paths are still rejected. The path.sep-suffixed
+// compare avoids the /project vs /project-evil prefix trap, now one level up at the workspace.
+// A sibling of the hub (../product-evil) is, correctly, indistinguishable from ../backend: both are
+// ordinary workspace members. The workspace DIRECTORY ITSELF (`..`) is not: it contains the hub, so
+// registering it as a code repo would point repomix and the CI writes at the whole tree. Only the hub
+// root itself (a monorepo, `.`) and strict descendants of the workspace pass.
+//
+// Place the hub one level below the workspace root (project/product), not directly in $HOME — the
+// workspace is the trust boundary, and a shallow hub makes every sibling of it registerable.
+export function insideWorkspace(root, rpath) {
   const projectRoot = path.resolve(root);
+  const parent = path.dirname(projectRoot);
+  const workspace = parent === projectRoot ? projectRoot : parent; // degenerate: root is the fs root
   const resolved = path.resolve(projectRoot, rpath);
-  return resolved === projectRoot || resolved.startsWith(projectRoot + path.sep);
+  return resolved === projectRoot || resolved.startsWith(workspace + path.sep);
 }
 
 // Validate + record one code repo into the registry (the testable half of the connect loop).
@@ -192,8 +206,8 @@ export function reconcileRepoRoles(root, name, repo, current = [], want = []) {
 }
 
 export function registerRepo(root, registry, { name, rpath, platform, domain_owner = '', domain_owners = null, default_branch = 'main', today = null, pack = true }) {
-  if (!insideRoot(root, rpath)) {
-    warn(`${rpath} resolves outside the project root — skipped`);
+  if (!insideWorkspace(root, rpath)) {
+    warn(`${rpath} resolves outside the workspace (the project root's parent) — skipped`);
     return null;
   }
   const repoRoot = path.resolve(root, rpath);
@@ -633,8 +647,9 @@ export async function runSetup(root, opts = {}) {
       const name = await ask('  repo name (blank to finish)', '');
       if (!name) break;
       if (known.has(name)) { warn(`${name} already registered — skipping`); continue; }
-      const rpath = await ask('    path (relative to project root)', `demo-repos/${name}`);
-      if (!insideRoot(root, rpath)) { warn(`${rpath} resolves outside the project root — skipped`); continue; }
+      // Siblings of the hub are the common layout (project/{product,backend}) — `../backend` is valid.
+      const rpath = await ask('    path (relative to project root, e.g. ../backend)', `demo-repos/${name}`);
+      if (!insideWorkspace(root, rpath)) { warn(`${rpath} resolves outside the workspace (the project root's parent) — skipped`); continue; }
       const detected = run('git', ['remote', 'get-url', 'origin'], { cwd: path.resolve(root, rpath) });
       const platform = (await ask('    platform (github/gitlab)', detectPlatform(detected.ok ? detected.stdout : '') || 'github')).toLowerCase();
       // Domain owners route the per-repo review. Solo (no roster) and monorepo (one repo = one owner)

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.0",
+  "version": "3.12.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 + 38 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/yad-connect-repos/SKILL.md

@@ -34,6 +34,24 @@ epic's approvals. It only writes the project-wide registry and the per-repo cont
   `roles` map, e.g. `roles: hub=owner,reviewer backend=domain-owner`). Validate the login against the
   hub (`gh api users/<login>` / `glab api users?username=`); a miss is flagged `unverified` (warn-only).
 - `path` — local path to the code repo (relative to `{project-root}` or absolute). For local repos.
+  It must resolve inside the **workspace** — the project root's parent — so the standard layout, where
+  the code repos sit **beside** the hub rather than under it, registers as `../backend`:
+
+  ```text
+  project/          <- the workspace (containment boundary)
+    product/        <- the hub repo; `yad setup` runs here
+    backend/        <- ../backend
+    frontend/       <- ../frontend
+  ```
+
+  A nested path (`demo-repos/api`, the demo layout) also works. A path that escapes the workspace
+  (`../../elsewhere`, or an absolute path outside it) is rejected and skipped — the registry path is
+  later used as a working directory (repomix) and written into (`.coderabbit.yaml`, CI wiring).
+  It is stored **exactly as typed**; every consumer re-resolves it against the project root.
+
+  The workspace is the trust boundary, so **put the hub one level below it** (`project/product`), not
+  directly in `$HOME` — with the hub at `~/product` the workspace becomes `~` and every home-dir
+  sibling turns into a registrable repo. The workspace directory itself (`..`) is never registrable.
 - `git_url` — optional remote (SSH or HTTPS; GitHub or GitLab). Used when the repo is not yet on disk.
 - `domain_owners` — the engineer(s) who own this repo's domain (a repo may have several; drives per-repo
   review routing). Each name is also written into that person's `roles[<repo>]` map in `hub.json`.

package/skills/yad-epic/SKILL.md

@@ -169,6 +169,11 @@ In `state.json`: set `epic.status: "done"`, set `epic-review.status: "in_review"
 `currentStep: "epic-review"`. Write `state.json`. Do **not** re-seed and do **not** touch
 `approvals.json` — only real reviewers approve, through the gate.
 
+> Since 3.11 the CLI closes the authoring step itself whenever its review gate opens or advances
+> (`yad gate open` / `sync`), so this edit is a no-op when the gate has already run. Keep making it —
+> it keeps `state.json` truthful before the gate opens — but it is no longer load-bearing: an epic
+> whose author step is left `in_progress` used to strand forever (`YAD-STATE-005`).
+
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: epic ID, the path to `epic.md`, and that the next action is **review** via
 `yad-review-gate`. **Never mark the epic-review step approved here** — only real reviewers do that

package/skills/yad-hub-bridge/references/bridge.md

@@ -169,6 +169,13 @@ opens the PR only; local `yad gate sync` is advisory in bridge mode (writes noth
 everyone `git checkout <default> && git pull`. (Without the bridge, humans own the ledger locally and
 these guards are no-ops.)
 
+**The one sanctioned human ledger write: `yad gate repair`.** It heals a `YAD-STATE-005` chain (an
+authoring step stranded behind a review gate that already advanced) by writing `state.json` alone. This
+is not a `ledger-guard` gap: the repair commits to the **default branch**, where `ledger-guard` — which
+only inspects review PRs — never runs, and where the `yad-update-guard` (platform-Verified signature +
+roster-allowlisted author) vets it instead, exactly as it does for `yad checkpoint` and `yad update`.
+The command refuses to commit off the default branch unless `--allow-branch` is passed.
+
 **Loop prevention & races.** The only ledger commit lands on the **default branch** at merge, which
 fires no PR trigger; it carries `[skip ci]` to guard sibling workflows. Because CI never pushes the
 review branch, there is no `synchronize` / MR-pipeline loop to prevent — and it is now **safe to enable**

package/skills/yad-review-gate/references/gating.md

@@ -55,7 +55,9 @@ re-approve. (Hash recipe: `yad-architecture/references/contract-format.md`.)
 4. `action: approve` approver *bob* role *reviewer* → ledger entry added. Predicate:
    `|owners|=1, |reviewers|=1` → **base pass**.
 5. `action: advance` → `epic-review.status=done`, `architecture.status=in_progress`,
-   `currentStep=architecture`. Gate reports the advance.
+   `currentStep=architecture`. Gate reports the advance. The paired authoring step (`epic`) is closed
+   too, if it was not already — a gate cannot have passed on an unauthored artifact. `doctor` reports
+   any surviving violation as `YAD-STATE-005`; `yad gate repair <epic>` heals it.
 
 ## Participation record (comments.json)
 `approvals.json` answers "who approved"; `.sdlc/comments.json` answers "who reviewed/commented". The

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-stories/SKILL.md

@@ -104,6 +104,10 @@ As a <role>, I want <capability>, so that <outcome>.
 In `state.json`: set `stories.status: "done"`, set `stories-review.status: "in_review"`, and set
 `currentStep: "stories-review"`. Write `state.json`. Do **not** touch `approvals.json`.
 
+> Since 3.11 the CLI also closes the authoring step when its review gate opens or advances, so this
+> edit is a no-op once `yad gate open` has run. A `stories` step left `in_progress` behind a passed
+> `stories-review` used to block the parallel `test-cases` track (`YAD-STATE-005`).
+
 ### Step 7 — Stop at the gate (do NOT advance)
 Report: the story IDs created, the repos each touches, and that the next action is **review** via
 `yad-review-gate`. Note that this review routes **per-repo reviewers**: owner + 1 reviewer **plus**, for

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