yadflow 3.10.0 → 3.11.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [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)
+
+
+### Bug Fixes
+
+* re-run pr-template gate on an edited PR body ([17ad94a](https://github.com/abdelrahmannasr/yadflow/commit/17ad94a4881610b4b653700be50a4eddd7036c5d))
+* stop yad repo refresh --push stranding the regenerated pack.md ([f0b5f4c](https://github.com/abdelrahmannasr/yadflow/commit/f0b5f4ce9f22afcd6078aae3ea1dd5a64885be35))
+
 # [3.10.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.9.4...v3.10.0) (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

@@ -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)}
 
@@ -146,7 +147,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']);
 
@@ -364,4 +369,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/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/repo-publish.mjs

@@ -5,8 +5,13 @@
 // analogue of `yad checkpoint` (cli/checkpoint.mjs) and reuses its default-branch commit machinery.
 //
 // Invariants (shared with checkpoint):
-//   1. Stage an EXPLICIT allowlist — exactly the tracked code-maps + the registry (never `git add -A`,
-//      which would sweep unrelated work in the hub). The gitignored repomix pack.md is never staged.
+//   1. Commit an EXPLICIT allowlist via `git commit -- <paths>` (--only) — the tracked code-maps, the
+//      registry, and (only when its change is the managed pack-ignore block alone) the hub `.gitignore`.
+//      NEVER `git add -A` and NEVER a whole-index `git reset`: both would mutate unrelated staged work.
+//      The repomix pack.md is gitignored (setup + publish scaffold the ignore via ensurePackIgnored) and
+//      never committed as content. A pack committed BEFORE that ignore existed is self-healed here: its
+//      on-disk file is held aside across the --only commit so the deletion is recorded (the regenerable
+//      cache is restored right after), clearing the stranded working tree — see the commit block below.
 //   2. Commit ONLY on the hub's default branch (unless --allow-branch), so the `[skip ci]` audit
 //      commit never enters a PR's base..HEAD range where it would strand required checks.
 import fs from 'node:fs';
@@ -16,6 +21,7 @@ import { PROJECT_FILES } from './manifest.mjs';
 import { loadHub } from './gate.mjs';
 import { resolveCommitterLogin } from './platform.mjs';
 import { hubGit, resolveDefaultBranch, guardDefaultBranch, preflightGuardReadiness } from './hubcommit.mjs';
+import { ensurePackIgnored, PACK_IGNORE_BLOCK } from './setup.mjs';
 import { checkpointAuthor } from './checkpoint.mjs';
 
 // Collapse any whitespace/newline runs to a single space — keeps a hostile `git user.name` or a stray
@@ -25,6 +31,9 @@ const oneLine = (s = '') => String(s).replace(/\s+/g, ' ').trim();
 // The tracked code-map for a repo: the registered path, else the conventional location.
 const codeMapOf = (repo) => repo.codeMap || path.posix.join('.sdlc/code-context', repo.name, 'code-map.md');
 
+// The repomix pack for a repo: the registered path, else the conventional location.
+const packOf = (repo) => repo.contextPack || path.posix.join('.sdlc/code-context', repo.name, 'pack.md');
+
 // PURE — the repo-relative pathspecs to stage: the registry plus each registered repo's code-map that
 // exists on disk. When `name` is given (a scoped `yad repo refresh <name> --push`), only that repo's
 // code-map is staged, so an unrelated repo's uncommitted code-map never rides along in a named refresh's
@@ -41,6 +50,57 @@ export function codeMapPathspecs(root, registry = { repos: [] }, name = null) {
   return out;
 }
 
+// PURE — each registered repo's on-disk pack path (scoped by `name` like codeMapPathspecs). These are
+// UNTRACK candidates, not content to stage: the pack is gitignored, but a hub that committed it before
+// the ignore existed would otherwise strand a dirty pack on every refresh. publishCodeContext keeps only
+// the still-tracked ones and records their removal in the audit commit (see the self-heal block there).
+export function packPathspecs(root, registry = { repos: [] }, name = null) {
+  const out = [];
+  for (const repo of registry.repos || []) {
+    if (name && repo.name !== name) continue;
+    const rel = packOf(repo);
+    if (fs.existsSync(path.join(root, rel))) out.push(rel);
+  }
+  return out;
+}
+
+// True iff committing `.gitignore` would carry ONLY the managed pack-ignore block (comments + glob) and
+// nothing else. Guards invariant 1: a hub whose `.gitignore` also has unrelated uncommitted edits must
+// keep them OUT of the `[skip ci]` audit commit. The publish commit is `git commit -- <paths>` (--only,
+// reads the WORKING TREE), so this compares the working tree — an untracked `.gitignore` must be wholly
+// managed; a tracked one must differ from HEAD by the managed block alone (added, nothing removed).
+// `git` is a hubGit-style accessor; `root` is the hub root. Mirrors checkpoint's stagedStoryIsStatusOnly.
+export function ignoreChangeIsManagedOnly(git, root) {
+  const gi = path.join(root, '.gitignore');
+  if (!fs.existsSync(gi)) return false;
+  const managed = new Set(PACK_IGNORE_BLOCK.map((l) => l.trim()));
+  if (!git('ls-files', '--error-unmatch', '--', '.gitignore').ok) {
+    // untracked: every non-blank line of the whole file must be a managed line
+    let seen = 0;
+    for (const l of fs.readFileSync(gi, 'utf8').split('\n')) {
+      const body = l.trim();
+      if (body === '') continue;
+      if (!managed.has(body)) return false;
+      seen++;
+    }
+    return seen > 0;
+  }
+  // tracked: the working-tree-vs-HEAD diff must ADD only managed lines and remove nothing
+  const d = git('diff', '-U0', 'HEAD', '--', '.gitignore');
+  if (!d.ok) return false;
+  let added = 0;
+  for (const ln of d.stdout.split('\n')) {
+    if (ln.startsWith('+++') || ln.startsWith('---') || ln.startsWith('@@')) continue; // headers/hunks
+    if (ln.startsWith('-')) return false;              // we only ever append — any removal ⇒ not ours
+    if (ln.startsWith('+')) {
+      const body = ln.slice(1).trim();
+      if (body !== '' && !managed.has(body)) return false; // a non-managed added line ⇒ a user edit
+      added++;
+    }
+  }
+  return added > 0;
+}
+
 // PURE — turn the staged pathspecs into the subject `label` + the body's file list. A `<name>` is
 // pulled from any `.sdlc/code-context/<name>/code-map.md` path; a commit that only touched the
 // registry is labelled `registry`.
@@ -49,7 +109,9 @@ export function summarizeCodeContext(files = []) {
   const basenames = [];
   for (const f of files) {
     basenames.push(f);
-    const m = f.match(/\.sdlc\/code-context\/([^/]+)\/code-map\.md$/);
+    // A repo name comes from either its code-map (content) or a pack removal (self-heal), so the
+    // subject label stays accurate even when untracking a stranded pack is the only change.
+    const m = f.match(/\.sdlc\/code-context\/([^/]+)\/(?:code-map|pack)\.md$/);
     if (m) repos.add(m[1]);
   }
   let label;
@@ -88,11 +150,26 @@ export async function publishCodeContext(root, { push = false, allowBranch = fal
   const defaultBranch = resolveDefaultBranch(git, hub);
   if (!guardDefaultBranch(branch, defaultBranch, { allowBranch, cmd: 'yad repo refresh --push' })) return;
 
+  // Stage the EXPLICIT allowlist (code-maps + registry), scoped so an unrelated pre-staged file is never
+  // swept in and the user's index is left untouched — mirrors `runCheckpoint`. NEVER `git add -A` and
+  // NEVER a whole-index `git reset` (both would mutate unrelated staged work). The commit below is
+  // `git commit -- <paths>` (--only), which reads the WORKING TREE for the named paths only.
   const pathspecs = codeMapPathspecs(root, registry, name);
-  if (!pathspecs.length) { info('no code-context to publish — nothing to commit'); return; }
+  if (pathspecs.length) {
+    const add = git('add', '--', ...pathspecs);
+    if (!add.ok) { fail(`git add failed — ${add.stderr.split('\n')[0] || add.code}`); process.exitCode = 1; return; }
+  }
 
-  const add = git('add', '--', ...pathspecs);
-  if (!add.ok) { fail(`git add failed — ${add.stderr.split('\n')[0] || add.code}`); process.exitCode = 1; return; }
+  // Make the "pack is gitignored" assumption true (idempotent; packRepo also does this on refresh) so a
+  // hub whose pack was tracked before the ignore existed stops stranding a dirty tree. Publish `.gitignore`
+  // ONLY when the change is the managed pack-ignore block alone (invariant 1) — a hub whose `.gitignore`
+  // also carries unrelated uncommitted edits keeps them OUT of this audit commit; the pack is still ignored
+  // on disk and the human commits their own `.gitignore` edits through their own change. When we do carry
+  // it, `git add` makes an untracked `.gitignore` known so the --only commit can include it.
+  const ignoreChanged = ensurePackIgnored(root);
+  const commitIgnore = ignoreChangeIsManagedOnly(git, root);
+  if (commitIgnore) git('add', '--', '.gitignore');
+  else if (ignoreChanged) hand('.gitignore has unrelated uncommitted edits — commit them yourself so the pack ignore is published (it is already ignored locally)');
 
   // Push HEAD to its OWN branch — on the default branch this is the same; with --allow-branch it keeps a
   // WIP branch from being force-published onto the default branch. Shared by the fresh-commit path and
@@ -105,7 +182,20 @@ export async function publishCodeContext(root, { push = false, allowBranch = fal
     return false;
   };
 
-  if (git('diff', '--cached', '--quiet', '--', ...pathspecs).ok) {
+  // Self-heal (invariant 1): a pack committed before it was gitignored strands the working tree on every
+  // refresh. Any STILL-TRACKED pack must be recorded as removed in this commit — but `git rm --cached`
+  // can't be committed under --only (which reads the working tree, where the regenerated pack still
+  // exists). So we untrack it below by momentarily removing the on-disk file across the commit (restored
+  // right after), letting --only record a clean deletion while the regenerable cache is preserved.
+  const trackedPacks = packPathspecs(root, registry, name)
+    .filter((p) => git('ls-files', '--error-unmatch', '--', p).ok);
+
+  // The exact files this audit commit will touch: the staged allowlist (+ managed `.gitignore`) plus any
+  // pack removal. Scopes the --only commit and, being all known to git, is a safe commit pathspec.
+  const ignoreSpec = commitIgnore ? ['.gitignore'] : [];
+  const staged = git('diff', '--cached', '--name-only', '--', ...pathspecs, ...ignoreSpec).stdout.split('\n').filter(Boolean);
+  const fileset = [...staged, ...trackedPacks];
+  if (!fileset.length) {
     // Nothing new to commit. A non-push run is simply done. But on a push run a PRIOR run may have
     // committed and then FAILED to push (the commit sits ahead of origin) — a plain re-run must land
     // that commit, not silently no-op and exit 0 while it stays stranded. Push any unpushed commit(s).
@@ -117,27 +207,37 @@ export async function publishCodeContext(root, { push = false, allowBranch = fal
     pushHead();
     return;
   }
-  // The exact files staged from the allowlist — scopes the commit to ONLY the allowlist, so any
-  // unrelated pre-staged file never rides along.
-  const staged = git('diff', '--cached', '--name-only', '--', ...pathspecs).stdout.split('\n').filter(Boolean);
 
   // Only relevant when we are about to push a commit straight to the default branch: warn (never block)
   // if signing/allowlisting would make the yad-update-guard reject it. Gated on `push` and deferred to
   // here so it isn't noise on a guard-refused branch or a nothing-to-commit run.
   if (push) preflightGuardReadiness(root);
 
-  const { label, basenames } = summarizeCodeContext(staged);
+  const { label, basenames } = summarizeCodeContext(fileset);
   const author = checkpointAuthor(resolveCommitterLogin(root, hub?.roster || []), git('config', 'user.name').stdout);
   const message = buildCodeMapMessage({ label, author, basenames });
 
-  const cm = git('commit', '-m', message, '--', ...staged);
-  if (!cm.ok) {
-    git('reset', '-q', '--', ...pathspecs); // don't leave the allowlist staged for an unrelated commit to sweep up
-    fail(`git commit failed — ${cm.stderr.split('\n')[0] || cm.code}`);
-    process.exitCode = 1;
-    return { message };
+  // Untrack the packs by holding their bytes and removing the files across the --only commit, then
+  // restoring them (now gitignored ⇒ a clean tree). try/finally so the regenerable cache is always put
+  // back, even on a commit failure.
+  const held = [];
+  try {
+    for (const p of trackedPacks) {
+      const abs = path.join(root, p);
+      held.push({ abs, buf: fs.readFileSync(abs) });
+      fs.rmSync(abs);
+    }
+    const cm = git('commit', '-m', message, '--', ...fileset); // --only: adds from the tree, packs as deletions
+    if (!cm.ok) {
+      git('reset', '-q', '--', ...pathspecs, ...ignoreSpec); // unstage only OUR allowlist for a clean retry
+      fail(`git commit failed — ${cm.stderr.split('\n')[0] || cm.code}`);
+      process.exitCode = 1;
+      return { message };
+    }
+  } finally {
+    for (const h of held) if (!fs.existsSync(h.abs)) fs.writeFileSync(h.abs, h.buf);
   }
-  ok(`published ${staged.length} file(s): ${c.dim(label)}`);
+  ok(`published ${fileset.length} file(s): ${c.dim(label)}`);
 
   if (!push) return { message };
   pushHead();

package/cli/repo.mjs

@@ -73,8 +73,9 @@ export async function runRepo(root, { action = 'list', name, today, push = false
     if (push) {
       // Publish whatever tracked code-context now differs (the AI-regenerated code-maps + the stamped
       // registry) straight to the hub's default branch as one audit-trail commit. The pack itself is
-      // gitignored; the code-map is regenerated by the AI (yad-connect-repos) — run that first if a
-      // repo's map is stale, then `yad repo refresh --push` lands it.
+      // gitignored (packRepo scaffolds the ignore; publish self-heals a pre-ignore tracked pack); the
+      // code-map is regenerated by the AI (yad-connect-repos) — run that first if a repo's map is stale,
+      // then `yad repo refresh --push` lands it.
       await publishCodeContext(root, { push: true, allowBranch, name });
     } else {
       hand('regenerate the code-map in Claude Code (yad-connect-repos) — the pack is cached, the map is the AI step');

package/cli/setup.mjs

@@ -740,12 +740,40 @@ export async function runSetup(root, opts = {}) {
   log(c.dim('Re-run anytime: `yad check` (report) / `yad check --fix` (reconcile).'));
 }
 
+// The repomix pack is a large, regenerable artifact — the hub tracks the AI-authored code-map, not the
+// pack. `yad repo refresh --push` relies on the pack being gitignored (repo-publish.mjs never stages it);
+// this makes that assumption true in every hub, so a regenerated pack never strands as a dirty tree.
+export const PACK_IGNORE_GLOB = '.sdlc/code-context/*/pack.md';
+
+// The exact lines ensurePackIgnored appends — a comment pair + the glob. Kept as data (not inline
+// strings) so the publish gate can verify a staged `.gitignore` change is ONLY this managed block and
+// never sweep an unrelated user edit into the audit commit (repo-publish.mjs, invariant 1).
+export const PACK_IGNORE_BLOCK = [
+  '# Repomix code-context packs are large, regenerable artifacts (yad repo refresh) — the',
+  '# tracked code-map.md is the reviewed AI output; the pack itself is never committed.',
+  PACK_IGNORE_GLOB,
+];
+
+// Idempotently ensure the hub `.gitignore` ignores the repomix pack. No-op (returns false) if the line
+// is already present (as its own entry); otherwise appends the managed block to a fresh or existing file
+// and returns true.
+export function ensurePackIgnored(root) {
+  const gi = path.join(root, '.gitignore');
+  const lines = exists(gi) ? fs.readFileSync(gi, 'utf8').split('\n') : [];
+  if (lines.some((l) => l.trim() === PACK_IGNORE_GLOB)) return false;
+  const body = lines.join('\n').replace(/\n*$/, '');
+  const prefix = body ? `${body}\n\n` : '';
+  fs.writeFileSync(gi, `${prefix}${PACK_IGNORE_BLOCK.join('\n')}\n`);
+  return true;
+}
+
 // Deterministic repomix pack (code-map generation itself is an AI step, handed off).
 export function packRepo(root, repo) {
   const repoRoot = path.resolve(root, repo.path);
   const out = path.join(root, repo.contextPack);
   if (!has('npx')) { warn(`${repo.name}: npx missing — skipped repomix pack`); return false; }
   fs.mkdirSync(path.dirname(out), { recursive: true });
+  ensurePackIgnored(root); // keep the pack out of git before it is (re)written — see repo-publish.mjs invariant 1
   info(`${repo.name}: packing with repomix …`);
   const r = run('npx', ['repomix@latest', '--compress', '--include-logs', '--style', 'markdown', '-o', out], { cwd: repoRoot });
   if (r.ok) { ok(`${repo.name}: cached ${repo.contextPack}`); hand(`${repo.name}: generate the code-map in Claude Code (yad-connect-repos)`); return true; }

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.0",
+  "version": "3.11.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-checks/references/check-gates.md

@@ -215,7 +215,11 @@ The gates run identically under either CI; the config just invokes the scripts w
 
 - **GitHub Actions** — `templates/github/yad-checks.yml` → `.github/workflows/yad-checks.yml`. The
   jobs run on `pull_request` with `fetch-depth: 0`, passing `origin/${{ github.base_ref }}` as base
-  (verified-commits also gets a read-only `GH_TOKEN` for the Verified-badge lookup). The pattern jobs
+  (verified-commits also gets a read-only `GH_TOKEN` for the Verified-badge lookup). The trigger sets
+  `types: [opened, synchronize, reopened, edited]` — the extra `edited` so a title/body correction
+  re-runs the pattern gates without a close/reopen (a plain re-run replays the frozen original payload).
+  The commit-range jobs carry `if: github.event.action != 'edited'` so a bare body/title edit only
+  re-runs `pr-title`/`pr-template`, not the whole suite. The pattern jobs
   read the title/body from the event payload: `pr-title` takes `${{ github.event.pull_request.title }}`
   and `pr-template` writes `${{ github.event.pull_request.body }}` to a temp file. All `--profile code`.
   The Phase 6 thread gates (`lineage-check`, `epic-open`, `reconcile-debt`) run as their own jobs with

package/skills/yad-checks/templates/github/yad-checks.yml

@@ -6,11 +6,16 @@
 name: yad-checks
 on:
   pull_request:
+    # `edited` (beyond the opened/synchronize/reopened defaults) so a PR title/body correction
+    # re-runs the pattern gates without a close/reopen — e.g. fixing a body the pr-template gate held.
+    # The commit-range jobs below skip a bare `edited` (only pr-title/pr-template need to re-check).
+    types: [opened, synchronize, reopened, edited]
     branches: ["**"]
 
 jobs:
   spec-link:
     runs-on: ubuntu-latest
+    if: github.event.action != 'edited'
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
@@ -18,6 +23,7 @@ jobs:
 
   contract-check:
     runs-on: ubuntu-latest
+    if: github.event.action != 'edited'
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
@@ -25,6 +31,7 @@ jobs:
 
   build-test-lint:
     runs-on: ubuntu-latest
+    if: github.event.action != 'edited'
     env:
       YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
     steps:
@@ -41,6 +48,7 @@ jobs:
   # story->epic resolution and degrade to a note when the product repo is not reachable from CI.
   lineage-check:
     runs-on: ubuntu-latest
+    if: github.event.action != 'edited'
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
@@ -48,6 +56,7 @@ jobs:
 
   epic-open:
     runs-on: ubuntu-latest
+    if: github.event.action != 'edited'
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
@@ -55,14 +64,17 @@ jobs:
 
   reconcile-debt:
     runs-on: ubuntu-latest
+    if: github.event.action != 'edited'
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
       - run: bash checks/reconcile-debt-check.sh "origin/${{ github.base_ref }}"
 
   # Pattern gates: commit subject + PR title + PR body all follow the convention (profile: code).
+  # commit-message reads the commit range, not the title/body — skip it on a bare `edited` event.
   commit-message:
     runs-on: ubuntu-latest
+    if: github.event.action != 'edited'
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
@@ -88,8 +100,10 @@ jobs:
           bash checks/pr-template.sh --profile code "$body"
 
   # No unverified commits from unverified users: platform-Verified signature + allowlisted author.
+  # Reads the commit range, not the title/body — skip it on a bare `edited` event.
   verified-commits:
     runs-on: ubuntu-latest
+    if: github.event.action != 'edited'
     permissions:
       contents: read
     env:

package/skills/yad-connect-repos/references/code-context.md

@@ -82,7 +82,13 @@ side-effect:** when a repo is stale (HEAD ≠ `syncedHead`), the phase **flags i
 silently re-packing the whole repo. A phase never refreshes the registry on its own; the human runs
 `yad repo refresh` (or `yad check --fix`). After the AI regenerates the code-map, `yad repo refresh
 --push` publishes the refreshed code-maps + registry to the hub's default branch as a `chore(hub): sync
-code-context … [skip ci]` audit commit (never `pack.md`; `--allow-branch` overrides the branch guard).
+code-context … [skip ci]` audit commit (never the pack's content; `--allow-branch` overrides the branch
+guard). The `pack.md` is gitignored — `yad repo refresh`/`yad setup` scaffold
+`.sdlc/code-context/*/pack.md` into the hub `.gitignore` (so a regenerated pack never dirties the tree),
+and a hub that tracked the pack *before* that ignore existed is self-healed: `--push` untracks it and
+lands the removal + the managed `.gitignore` line in the same audit commit. The commit is a scoped
+`git commit -- <paths>` — it never sweeps unrelated staged work, and an unrelated hand-edit to
+`.gitignore` is left for the human to commit rather than riding the `[skip ci]` audit commit.
 
 ## Why this stays DRY with backfill