yadflow 3.10.1 → 3.11.1

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [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)
+
+
+### Features
+
+* notify when a newer yadflow is published ([9b7a5bf](https://github.com/abdelrahmannasr/yadflow/commit/9b7a5bfca4f27ab08ce4e3e48f2ba331c3e8bfd5))
+
 ## [3.10.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.10.0...v3.10.1) (2026-07-08)
 
 

package/README.md

@@ -63,6 +63,9 @@ Every step stops at a gate until a human approves. New here? **Walk it lesson-by
 [guided tutorial](https://abdelrahmannasr.github.io/yadflow/tutorial/)**, or read the
 [team guide](TEAM-GUIDE.md).
 
+Running `yad` tells you when a new release is out — upgrade with `npm install yadflow -g`, then
+`yad update` to re-sync this project's skills. See [staying up to date](docs/CLI.md#staying-up-to-date).
+
 ## What `npx yadflow setup` installs
 
 ![npx yadflow setup — the guided wizard installs the yad-* skills, wires the CI gates, and stamps the .sdlc config](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/media/setup-wizard.gif)

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';
@@ -22,6 +22,7 @@ import { syncStatuses } from '../cli/artifact-status.mjs';
 import { runThread, runReconcile } from '../cli/thread.mjs';
 import { runReport } from '../cli/report.mjs';
 import { runUsage } from '../cli/usage.mjs';
+import { maybeNotifyUpdate } from '../cli/update-notice.mjs';
 
 const HELP = `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
 
@@ -77,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
@@ -146,7 +149,11 @@ ${c.bold('Options')}
   --push                check --fix / update: commit + push applied changes to the default branch
   --allow-branch        check --fix --push / update --push / repo refresh --push: allow committing on a non-default branch
   -h, --help            Show this help
-  -v, --version         Print version`;
+  -v, --version         Print version
+
+${c.bold('Environment')}
+  YAD_NO_UPDATE_NOTIFIER=1   Silence the "update available" notice (also off in CI)
+  YAD_NO_REPORT=1            Never offer to file a bug report after a failure`;
 
 const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--name', '--email', '--roles', '--team', '--body', '--out', '--since', '--until', '--member', '--format', '--reason']);
 
@@ -254,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
@@ -264,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': {
@@ -364,4 +372,15 @@ main()
       } catch { /* reporting is best-effort — never mask the original failure */ }
     }
   })
-  .finally(closePrompts);
+  // Runs for every command, success or failure, after any report prompt. Prints to stderr and never
+  // touches process.exitCode, so a command's stdout contract and exit status are unaffected.
+  // The try/finally is load-bearing, not defensive noise: a rejection here would escape as an
+  // unhandled rejection (exit 1 on an otherwise successful command) AND skip closePrompts(), leaving
+  // the readline handle open so the process never exits.
+  .finally(async () => {
+    try {
+      await maybeNotifyUpdate();
+    } catch { /* the notice is never worth failing or hanging a command over */ } finally {
+      closePrompts();
+    }
+  });

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)

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

@@ -10,6 +10,10 @@ import { readFileSync } from 'node:fs';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const VERSION = pkg.version;
 
+// The published npm package name — the registry path the update check queries, and the name in the
+// `npm install <name> -g` line it prints. Read from package.json so a rename can never desync them.
+export const PKG_NAME = pkg.name;
+
 // The upstream yadflow repo, as `owner/name` — where `yad report` files issues. Derived from
 // package.json `bugs.url` (the single source of truth) so it tracks a fork/rename automatically;
 // falls back to the canonical slug if the field is ever malformed.

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/update-notice.mjs

@@ -0,0 +1,179 @@
+// "A new yadflow is out" — the update disclaimer printed after every `yad` command.
+//
+// Three rules make this safe to run on every invocation:
+//   1. It never throws and never touches process.exitCode. A dead registry, an unwritable home, or a
+//      malformed cache degrades to silence, never to a failed command.
+//   2. It prints to STDERR (the `note()` convention in lib.mjs), so `--json` commands, the grounding
+//      bundles, and `yad -v` keep a machine-readable STDOUT.
+//   3. It is cache-first: the network is touched at most once per TTL. Every other run is pure disk.
+//
+// Deliberately NOT suppressed on a non-TTY. Skills invoke `yad` through an agent's Bash tool, where
+// stdout/stderr are piped — the usual "only notify on a TTY" guard would hide the notice from exactly
+// the case we most want it in. `CI` is the suppression signal instead.
+import os from 'node:os';
+import path from 'node:path';
+import { VERSION, PKG_NAME, UPSTREAM_REPO } from './manifest.mjs';
+import { c, exists, readJSON, writeJSON, PKG_ROOT } from './lib.mjs';
+
+export const DAY_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 1500;
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+
+// An env var counts as "set" only when it carries a meaningful value — `CI=false` and `CI=0` are
+// common in shells that always export the name.
+const truthy = (v) => !!v && v !== '0' && v !== 'false';
+
+// ---- semver -------------------------------------------------------------
+// A deliberately small parser: we only ever compare a released `x.y.z` against another. Anything the
+// registry hands us that is not a clean triple (garbage, a range, undefined) yields null → no notice.
+export function parseVersion(v) {
+  if (typeof v !== 'string') return null;
+  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(v.trim());
+  if (!m) return null;
+  return { major: +m[1], minor: +m[2], patch: +m[3], pre: m[4] ?? null };
+}
+
+// The canonical `x.y.z` form. `parseVersion` tolerates a leading `v`, so anything interpolated into
+// the banner or the release-tag URL must be normalized first — otherwise a `v`-prefixed `latest`
+// (from a mirror registry or a hand-edited cache) yields a dead `.../releases/tag/vv3.11.0` link.
+export function normalizeVersion(v) {
+  const p = parseVersion(v);
+  return p ? `${p.major}.${p.minor}.${p.patch}${p.pre ? `-${p.pre}` : ''}` : null;
+}
+
+// True when `latest` is a release strictly newer than `current`. A prerelease `latest` never nags a
+// user on a stable version — dist-tags.latest should never be one, but a mis-tagged publish would
+// otherwise pester every user until it was fixed. Prereleases are not ordered against each other
+// (rc.2 does not "beat" rc.1); the only prerelease transition we announce is rc → its stable.
+export function isNewer(latest, current) {
+  const l = parseVersion(latest);
+  const cur = parseVersion(current);
+  if (!l || !cur) return false;
+  if (l.pre && !cur.pre) return false;
+  if (l.major !== cur.major) return l.major > cur.major;
+  if (l.minor !== cur.minor) return l.minor > cur.minor;
+  if (l.patch !== cur.patch) return l.patch > cur.patch;
+  // Same x.y.z: the stable release supersedes the prerelease of that same version, so a user sitting
+  // on 4.0.0-rc.1 is told when 4.0.0 final ships.
+  return !l.pre && !!cur.pre;
+}
+
+// ---- registry -----------------------------------------------------------
+export function registryBase({ env = process.env } = {}) {
+  const base = env.YAD_REGISTRY_URL || env.npm_config_registry || DEFAULT_REGISTRY;
+  return base.replace(/\/+$/, '');
+}
+
+// The `dist-tags` endpoint returns a few dozen bytes (`{"latest":"3.10.1"}`); the packument at
+// /<pkg> or /<pkg>/latest is orders of magnitude larger for the same one field.
+// `fetchImpl` must NOT default to a bare `fetch` in the parameter list: default parameters are
+// evaluated before the function body's try/catch is entered, so on a runtime without a global fetch
+// (Node 18 started with --no-experimental-fetch) that would throw a ReferenceError straight past
+// every guard here and out through bin/yad.mjs's .finally. Resolve it inside the try instead.
+export async function fetchLatest({ env = process.env, timeoutMs = FETCH_TIMEOUT_MS, fetchImpl } = {}) {
+  try {
+    const doFetch = fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== 'function') return null; // no fetch on this runtime — stay quiet
+    const url = `${registryBase({ env })}/-/package/${encodeURIComponent(PKG_NAME)}/dist-tags`;
+    const res = await doFetch(url, {
+      signal: AbortSignal.timeout(timeoutMs),
+      headers: { accept: 'application/json' },
+    });
+    if (!res.ok) return null;
+    const tags = await res.json();
+    return typeof tags?.latest === 'string' ? tags.latest : null;
+  } catch {
+    return null; // offline, DNS failure, timeout, non-JSON body — all mean "we don't know", not "fail"
+  }
+}
+
+// ---- cache --------------------------------------------------------------
+// The CLI's only per-user state. Everything else it writes is project-scoped under .sdlc/.
+export function cacheFile({ env = process.env, platform = process.platform, home = os.homedir() } = {}) {
+  if (env.YAD_CACHE_DIR) return path.join(env.YAD_CACHE_DIR, 'update-check.json');
+  if (env.XDG_CACHE_HOME) return path.join(env.XDG_CACHE_HOME, 'yadflow', 'update-check.json');
+  if (platform === 'win32' && env.LOCALAPPDATA) return path.join(env.LOCALAPPDATA, 'yadflow', 'update-check.json');
+  return path.join(home, '.cache', 'yadflow', 'update-check.json');
+}
+
+export const readCache = (file) => readJSON(file, null);
+
+// A read-only home (CI images, locked-down laptops, a root-owned ~/.cache) must not break `yad`.
+// Losing the cache only costs one registry round-trip per command.
+export function writeCache(file, data) {
+  try {
+    writeJSON(file, data);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---- suppression --------------------------------------------------------
+// `pkgRoot` carrying a .git means yad is running from a source checkout (`npm run yad`, the test
+// suite's execFileSync calls), not from a global npm install. Nagging a maintainer about the version
+// they are editing is noise.
+export function shouldSuppress({ env = process.env, pkgRoot = PKG_ROOT } = {}) {
+  if (truthy(env.YAD_NO_UPDATE_NOTIFIER)) return true;
+  if (truthy(env.CI)) return true;
+  if (truthy(env.SDLC_NONINTERACTIVE)) return true;
+  if (exists(path.join(pkgRoot, '.git'))) return true;
+  return false;
+}
+
+// ---- banner -------------------------------------------------------------
+// `yad update` is the necessary second half: upgrading the global CLI leaves this project's installed
+// yad-* skills stamped at the old version in .sdlc/cli-version.json, which `yad doctor` then flags.
+export function formatBanner(current, latest) {
+  // Normalize so a `v`-prefixed input can never produce `.../releases/tag/vv3.11.0`. Callers only
+  // reach here after isNewer(), so parseVersion has already accepted both — the ?? is belt and braces.
+  const v = normalizeVersion(latest) ?? latest;
+  const url = `https://github.com/${UPSTREAM_REPO}/releases/tag/v${v}`;
+  return [
+    '',
+    `  ${c.yellow('!')} ${c.bold(`${PKG_NAME} update available`)} — ${c.dim(current)} → ${c.green(v)}`,
+    `    ${c.dim('Changelog:')}  ${url}`,
+    `    ${c.dim('Update:')}     ${c.cyan(`npm install ${PKG_NAME} -g`)}`,
+    `    ${c.dim('Then:')}       ${c.cyan('yad update')}   ${c.dim("(re-sync this project's yad-* skills)")}`,
+  ].join('\n');
+}
+
+// ---- orchestrator -------------------------------------------------------
+// Returns true when a banner was printed (tests assert on this; callers ignore it).
+export async function maybeNotifyUpdate({
+  env = process.env,
+  now = Date.now(),
+  pkgRoot = PKG_ROOT,
+  ttlMs = DAY_MS,
+  current = VERSION,
+  out = (s) => console.error(s),
+  fetchImpl, // resolved to globalThis.fetch inside fetchLatest — see the note there
+} = {}) {
+  try {
+    if (shouldSuppress({ env, pkgRoot })) return false;
+
+    const file = cacheFile({ env });
+    const cache = readCache(file);
+    // `age >= 0` matters: a lastCheck stamped in the future (a clock that jumped forward, an NTP
+    // correction, a cache synced from another machine) yields a negative age, which would read as
+    // "fresh" and pin a stale `latest` until real time caught up. Treat it as expired instead.
+    const age = now - cache?.lastCheck;
+    const fresh = Number.isFinite(cache?.lastCheck) && age >= 0 && age < ttlMs;
+
+    let latest = typeof cache?.latest === 'string' ? cache.latest : null;
+    if (!fresh) {
+      const fetched = await fetchLatest({ env, fetchImpl });
+      if (fetched) latest = fetched;
+      // Stamp lastCheck even when the fetch failed: an offline user would otherwise pay the full
+      // timeout on every single command. We keep any previously-known `latest` so the banner survives
+      // a temporary outage.
+      writeCache(file, { lastCheck: now, latest });
+    }
+
+    if (!isNewer(latest, current)) return false;
+    out(formatBanner(current, latest));
+    return true;
+  } catch {
+    return false; // never let the notifier turn a successful command into a failed one
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.10.1",
+  "version": "3.11.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-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-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