yadflow 3.9.4 → 3.10.1

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [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)
+
+
+### Bug Fixes
+
+* **sdlc:** satisfy lint gate and cover the yad skip CLI ([838eabc](https://github.com/abdelrahmannasr/yadflow/commit/838eabc0ba597eaeac3e9249c514e3d479de4830))
+
+
+### Features
+
+* **sdlc:** make the ui-design step optional (skippable N/A) ([2bc5583](https://github.com/abdelrahmannasr/yadflow/commit/2bc5583b58626ee0cf8f8cc993a8566e4b206221))
+
 ## [3.9.4](https://github.com/abdelrahmannasr/yadflow/compare/v3.9.3...v3.9.4) (2026-07-07)
 
 ## [3.9.3](https://github.com/abdelrahmannasr/yadflow/compare/v3.9.2...v3.9.3) (2026-07-07)

package/bin/yad.mjs

@@ -17,6 +17,7 @@ import { runRoster } from '../cli/roster.mjs';
 import { runDocs } from '../cli/docs.mjs';
 import { runDoctor } from '../cli/doctor.mjs';
 import { runNext } from '../cli/next.mjs';
+import { runSkip } from '../cli/skip.mjs';
 import { syncStatuses } from '../cli/artifact-status.mjs';
 import { runThread, runReconcile } from '../cli/thread.mjs';
 import { runReport } from '../cli/report.mjs';
@@ -66,6 +67,10 @@ ${c.bold('Where am I / what next')}
   yad next <epic>                      The single next action for one epic (skill or yad command)
   yad next <epic> --check <step>       Exit 0 if <step> is runnable now, else 1 (precondition guard)
   yad next --all                       Every active epic's next action at once
+  yad skip <epic> ui-design --reason <text>   Mark an optional step N/A for this epic (only
+                                       ui-design today) — a backend/API/data epic with no UI.
+                                       Stays visible & auditable (pre-done, gate short-circuited);
+                                       --undo reverses it until the stories review opens
 
 ${c.bold('Review gate (front half)')}
   yad gate open <epic> <artifact>      Open the review PR/MR; mark the step in_review
@@ -143,7 +148,7 @@ ${c.bold('Options')}
   -h, --help            Show this help
   -v, --version         Print version`;
 
-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']);
+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']);
 
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -163,6 +168,7 @@ function parseArgs(argv) {
     // positional. `o._[0]` is the command, already pushed by the time `--check` is seen in normal use.
     else if (a === '--check') { const v = argv[i + 1]; o.check = (o._[0] === 'next' && v !== undefined && !v.startsWith('-')) ? argv[++i] : true; }
     else if (a === '--all') o.all = true;
+    else if (a === '--undo') o.undo = true;
     // setup profile flags (pre-answer the Step 0 interview, for CI/scripts)
     else if (a === '--solo') o.solo = true;
     else if (a === '--greenfield') o.greenfield = true;
@@ -238,6 +244,12 @@ async function main() {
       await runNext(o.dir, { epic, check: typeof o.check === 'string' ? o.check : undefined, all: o.all });
       break;
     }
+    case 'skip': {
+      const [, epic, step] = o._;
+      if (!epic || !isValidEpicId(epic)) { log(c.red(`invalid or missing epic id: ${epic ?? '(none)'} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
+      await runSkip(o.dir, { epic, step, reason: o.reason, undo: o.undo, today });
+      break;
+    }
     case 'gate': {
       const [, action, epic, artifact] = o._;
       // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).

package/cli/epic-state.mjs

@@ -219,6 +219,20 @@ export function gatePredicate({
     };
   }
 
+  // A SKIPPED step (an optional step the team marked N/A for this epic — e.g. `ui-design` on a
+  // backend-only epic) is satisfied without review. Like `inherited`, it is pre-marked `done` in
+  // state.json so the gate is normally never invoked on it; this short-circuit makes a direct call
+  // safe and keeps the skip a first-class, auditable outcome (the reason lives on the step).
+  // GUARD: only honour the flag on a genuinely skippable step (the author step or its `-review` gate).
+  // A corrupted/hand-edited `skipped: true` on a non-optional step (e.g. `stories-review`) must NOT
+  // bypass approvals — it falls through to the real predicate below and fails for lack of approvals.
+  if (step?.skipped && isSkippableStep(step.id)) {
+    return {
+      approvalsSatisfied: true, threadsResolved: true, merged: true, staleDropped: 0,
+      passed: true, missing: [], rule: 'skipped',
+    };
+  }
+
   const forStep = approvals.filter((a) => a.step === step.id && a.status === 'approved');
   // Revoke-on-change: an approval bound to a stale content hash no longer counts.
   const stale = forStep.filter((a) => a.artifactHash && currentHash && a.artifactHash !== currentHash);
@@ -296,7 +310,12 @@ export function advanceState(state, step) {
     state.currentStep = 'discovery-done';
     return state;
   }
-  const next = state.steps[i + 1];
+  // Step over any SKIPPED steps (an optional step marked N/A for this epic — e.g. a skipped
+  // `ui-design`/`ui-design-review` pair). They are pre-marked `done`, so the next runnable step is the
+  // first later step that is not skipped. When the whole tail is skipped, fall through to ready-for-build.
+  let j = i + 1;
+  while (state.steps[j]?.skipped) j++;
+  const next = state.steps[j];
   if (next) {
     next.status = next.type === 'review+approve' ? 'in_review' : 'in_progress';
     state.currentStep = next.id;
@@ -306,6 +325,117 @@ export function advanceState(state, step) {
   return state;
 }
 
+// The front steps that may be marked N/A ("skipped") for an epic that does not need them. Only the
+// UI-design step is optional today: an epic with no user-facing surface (backend/API, data, infra)
+// can skip it. A skip carries a recorded reason and stays VISIBLE in the chain (both the author step
+// and its review gate pre-marked `done`, short-circuited by `gatePredicate`) — the auditable,
+// reversible counterpart to omitting `analysis` from the chain entirely.
+export const SKIPPABLE_STEPS = new Set(['ui-design']);
+
+// True for a genuinely skippable step id — the author step (`ui-design`) OR its paired review gate
+// (`ui-design-review`). Used to gate the `gatePredicate` skip short-circuit so a corrupted/hand-edited
+// `skipped: true` on a non-optional step cannot bypass its real approvals.
+export function isSkippableStep(id) {
+  return SKIPPABLE_STEPS.has(String(id || '').replace(/-review$/, ''));
+}
+
+// Strip the skip-provenance fields off a step — the inverse of the stamp `skipStep` applies.
+function withoutSkip(step) {
+  const rest = { ...step };
+  delete rest.skipped;
+  delete rest.skipReason;
+  delete rest.skippedBy;
+  delete rest.skippedAt;
+  return rest;
+}
+
+// PURE. Mark a skippable step (its author step + paired `<id>-review` gate) N/A for this epic: pre-mark
+// both `done` with a recorded reason, and — if currentStep is sitting on the pair — advance currentStep
+// past them to the next non-skipped step. Idempotent on an already-skipped step. Refuses once the step
+// was authored, once its review gate has opened, or once its downstream `stories` has started — the
+// step is optional only up to authoring it. Throws on a non-skippable id or a malformed (unpaired) chain.
+export function skipStep(state, stepId, { reason, by = null, at = null } = {}) {
+  if (!SKIPPABLE_STEPS.has(stepId)) {
+    throw err('YAD-STATE-004', `step '${stepId}' is not optional`, `only these steps may be skipped: ${[...SKIPPABLE_STEPS].join(', ')}`);
+  }
+  const ai = state.steps.findIndex((s) => s.id === stepId);
+  if (ai === -1) throw err('YAD-STATE-004', `step '${stepId}' is not in this epic's chain`, 'nothing to skip');
+  const author = state.steps[ai];
+  // Idempotent BEFORE the reason check: a repeat skip on an already-N/A step is a no-op that keeps the
+  // original reason/actor, so it must not fail merely for lacking a fresh --reason.
+  if (author.skipped) return state;
+  if (!reason || !String(reason).trim()) {
+    throw err('YAD-STATE-004', 'a skip needs a reason', 'pass a reason, e.g. "backend-only epic, no UI"');
+  }
+  // A skippable step must carry its paired `-review` gate — the change keeps BOTH in the chain. A
+  // missing gate is a malformed chain; refuse rather than half-stamp only the author step.
+  const ri = state.steps.findIndex((s) => s.id === `${stepId}-review`);
+  if (ri === -1) throw err('YAD-STATE-004', `malformed chain: ${stepId} has no ${stepId}-review gate`, 'restore state.json from git');
+  const review = state.steps[ri];
+  if (author.status === 'done') {
+    throw err('YAD-STATE-004', `${stepId} is already authored`, 'cannot skip a step whose artifact was already written');
+  }
+  // Once the review gate has opened (in_review / done), the UI work is effectively committed — skipping
+  // then would orphan a live review PR. Refuse; the step is optional only up to authoring it.
+  if (review.status !== 'blocked') {
+    throw err('YAD-STATE-004', `cannot skip ${stepId} — its review has already opened`, 'skip the UI step before its review begins');
+  }
+  const stories = state.steps.find((s) => s.id === 'stories');
+  if (stories && stories.status !== 'blocked') {
+    throw err('YAD-STATE-004', `cannot skip ${stepId} — stories have already started`, 'skip the UI step before stories begin');
+  }
+  const stamp = { skipped: true, skipReason: String(reason).trim(), skippedBy: by, skippedAt: at, status: 'done' };
+  state.steps[ai] = { ...author, ...stamp };
+  state.steps[ri] = { ...review, ...stamp };
+  // If currentStep was on the pair we just skipped, move it to the next non-skipped step.
+  if (state.currentStep === stepId || state.currentStep === `${stepId}-review`) {
+    let j = ri + 1;
+    while (state.steps[j]?.skipped) j++;
+    const next = state.steps[j];
+    if (next) {
+      if (next.status === 'blocked') next.status = next.type === 'review+approve' ? 'in_review' : 'in_progress';
+      state.currentStep = next.id;
+    } else {
+      state.currentStep = 'ready-for-build';
+    }
+  }
+  return state;
+}
+
+// PURE. Reverse a skip: clear the N/A stamp on the pair and restore the chain. Allowed only while the
+// downstream `stories-review` has not opened (state-only signal for "stories authoring is under way").
+// If every earlier step is done, the restored author step becomes the active step again (and a
+// downstream that the skip auto-opened is pushed back to `blocked` behind it); otherwise it just
+// returns to `blocked`. Throws if the step is not skipped or it is too late.
+export function unskipStep(state, stepId) {
+  if (!SKIPPABLE_STEPS.has(stepId)) {
+    throw err('YAD-STATE-004', `step '${stepId}' is not optional`, `only these steps may be skipped: ${[...SKIPPABLE_STEPS].join(', ')}`);
+  }
+  const ai = state.steps.findIndex((s) => s.id === stepId);
+  if (ai === -1) throw err('YAD-STATE-004', `step '${stepId}' is not in this epic's chain`, 'nothing to un-skip');
+  if (!state.steps[ai].skipped) throw err('YAD-STATE-004', `${stepId} is not skipped`, 'nothing to un-skip');
+  const storiesReview = state.steps.find((s) => s.id === 'stories-review');
+  if (storiesReview && storiesReview.status !== 'blocked') {
+    throw err('YAD-STATE-004', `cannot un-skip ${stepId} — the stories review has already opened`, 'un-skip before the stories review begins');
+  }
+  const ri = state.steps.findIndex((s) => s.id === `${stepId}-review`);
+  const priorAllDone = state.steps.slice(0, ai).every((s) => s.status === 'done');
+  state.steps[ai] = { ...withoutSkip(state.steps[ai]), status: priorAllDone ? 'in_progress' : 'blocked' };
+  if (ri !== -1) state.steps[ri] = { ...withoutSkip(state.steps[ri]), status: 'blocked' };
+  if (priorAllDone) {
+    // The restored author step is the active step again. Push the downstream the skip auto-opened
+    // back to `blocked` (it must wait behind the now-live step), and re-point currentStep here. Scan
+    // past any still-skipped steps (mirrors skipStep's step-over) and reset whether it was opened as
+    // an author step (`in_progress`) or a review gate (`in_review`).
+    let j = (ri !== -1 ? ri : ai) + 1;
+    while (state.steps[j]?.skipped) j++;
+    const after = state.steps[j];
+    if (after && (after.status === 'in_progress' || after.status === 'in_review')) after.status = 'blocked';
+    state.currentStep = stepId;
+  }
+  return state;
+}
+
 // Mark a step in-review (idempotent) and point currentStep at it — EXCEPT once the epic is
 // `ready-for-build`: the parallel `test-cases` track must not pull currentStep back (the build half
 // runs alongside the tester, and only the test-cases review is in flight at that point).

package/cli/errors.mjs

@@ -19,6 +19,7 @@ export const CODES = {
   'YAD-STATE-001': 'a ledger/config JSON file exists but does not parse',
   '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-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/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/skip.mjs

@@ -0,0 +1,45 @@
+// `yad skip <epic> <step> --reason "<why>"` (and `--undo`) — mark an OPTIONAL front step N/A for one
+// epic. Today only `ui-design` is skippable: an epic with no user-facing surface (backend/API, data,
+// infra) does not need a UI-design artifact + review gate. The skip stays VISIBLE and auditable — the
+// step is pre-marked `done` with a recorded reason (and actor/date), short-circuited at the gate — and
+// is reversible with `--undo` until the stories review opens. All state logic is the pure
+// `skipStep`/`unskipStep` in epic-state.mjs; this is the thin file-load/save + attribution wrapper.
+import { ok, info, hand, fail, run, writeJSON } from './lib.mjs';
+import { epicRoot, loadLedger, skipStep, unskipStep } from './epic-state.mjs';
+import { loadHub } from './gate.mjs';
+import { resolveCommitterLogin } from './platform.mjs';
+
+// Best-effort auditable actor for `skippedBy`: the roster login for the local git identity, else the
+// raw git user.name, else null. A malformed/absent hub degrades to the raw name — attribution is a
+// nicety on the audit trail, never a gate, so it must not block the skip.
+function skipActor(root) {
+  let roster = [];
+  try { roster = loadHub(root)?.hub?.roster || []; } catch { /* no hub / malformed — attribute by raw git name */ }
+  return resolveCommitterLogin(root, roster)
+    || (run('git', ['config', 'user.name'], { cwd: root }).stdout || '').trim()
+    || null;
+}
+
+export async function runSkip(root, { epic, step, reason, undo = false, today } = {}) {
+  const epicDir = epicRoot(root, epic);
+  const ledger = loadLedger(epicDir);
+  if (!ledger.state) { fail(`no epic state at ${epicDir} — seed the epic first with yad-epic`); process.exitCode = 1; return; }
+  if (!step) { fail('usage: yad skip <epic> <step> --reason "<why>"   (or: yad skip <epic> <step> --undo)'); process.exitCode = 1; return; }
+
+  // Guard violations throw a YadError (YAD-STATE-004) with a hint — the top-level catch in bin/yad.mjs
+  // renders those. Here we only handle the happy path + the two plain-arg checks above.
+  if (undo) {
+    unskipStep(ledger.state, step);
+    writeJSON(ledger.files.state, ledger.state);
+    ok(`${step} un-skipped — back in the chain`);
+    hand(`currentStep is now ${ledger.state.currentStep}`);
+    return;
+  }
+
+  const by = skipActor(root);
+  skipStep(ledger.state, step, { reason, by, at: today });
+  writeJSON(ledger.files.state, ledger.state);
+  ok(`${step} marked N/A${by ? ` by ${by}` : ''}${today ? ` on ${today}` : ''}`);
+  info(`reason: ${String(reason).trim()}`);
+  hand(`its review gate is short-circuited; currentStep is now ${ledger.state.currentStep}  (reverse with \`yad skip ${epic} ${step} --undo\`)`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.9.4",
+  "version": "3.10.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/sdlc/config.yaml

@@ -33,7 +33,8 @@ output_folder: "{project-root}/_bmad-output"
 defaults:
   assistance: review          # none | review | heavy
   automation: human_approve   # human_approve | machine_advance
-  # Front steps (discovery [optional front-zero], analysis [optional], epic, architecture, ui-design,
+  # Front steps (discovery [optional front-zero], analysis [optional], epic, architecture,
+  # ui-design [optional — skippable N/A for UI-less epics via `yad skip <epic> ui-design --reason "<why>"`],
   # stories, test-cases) are locked to human_approve and may NOT be set to machine_advance in this
   # version (build plan §1, §8.7).
   front_steps_locked: true

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
 

package/skills/yad-epic/SKILL.md

@@ -156,6 +156,12 @@ Notes:
   and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
   `[]`, and the `reviews/` directory. (`comments.json` is the machine-readable counterpart to the
   `reviews/*--comments.md` markdown — `yad-review-gate` appends to it on every `comment`.)
+- **No UI?** Seed the chain **as-is** (always include the two `ui-design` steps). If this epic has no
+  user-facing surface (a backend/API service, data pipeline, infra), the `ui-design` step is optional
+  and can be marked N/A now with `yad skip EP-<slug> ui-design --reason "<why>"` — it stays visible,
+  short-circuits its gate, and advances straight to `stories` when architecture is approved. It is
+  reversible with `--undo` until the stories review opens. Don't hand-edit the seed to drop the steps;
+  the skip is the single, auditable mechanism (see `references/state-schema.md` → "ui-design is optional").
 
 ### Step 5b — Advance the authoring step — analysis-ran only
 *(Only when analysis ran — `state.json` already exists from `yad-analysis`.)*

package/skills/yad-epic/references/state-schema.md

@@ -37,6 +37,32 @@ existing `state.json` and does **not** re-seed.
 `analysis-review`, `ui-design-review`, and `test-cases-review` carry no `risk_tags` (base rule:
 owner + 1 reviewer).
 
+### `ui-design` is optional (skippable)
+
+The `ui-design` step (and its `ui-design-review` gate) is **optional** for an epic with no
+user-facing surface — a backend/API service, a data pipeline, infra work. Unlike `analysis` (which is
+optional by being **omitted** from the chain at seed time), `ui-design` is **always seeded** and then
+**marked N/A in place** so the skip stays visible and auditable. The single mechanism is
+`yad skip EP-<slug> ui-design --reason "<why>"` (reverse with `--undo`), usable at epic-authoring time
+or any point **up to authoring the `ui-design` step** — the skip is refused once its review gate has
+opened (the UI work is committed by then) or once `stories` has started. `--undo` is allowed until the
+`stories` review opens.
+
+A skipped step gets four extra fields and is pre-marked `done`:
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| `skipped` | `true` | This step is N/A for this epic; pre-marked `done`, short-circuited by `gatePredicate` (`rule: "skipped"`) so no review is required. |
+| `skipReason` | string | Why it was skipped (e.g. "backend-only service, no UI"). |
+| `skippedBy` | login/name or `null` | Who marked it N/A (best-effort, from the roster/git identity). |
+| `skippedAt` | `YYYY-MM-DD` or `null` | When it was marked N/A. |
+
+Both the `ui-design` **and** `ui-design-review` entries carry these fields. `advanceState` steps over
+any `skipped` step, so approving `architecture-review` on a UI-less epic lands directly on `stories`;
+`preconditionsMet` treats the pre-`done` steps as satisfied. `unskipStep` (via `yad skip … --undo`)
+strips the fields and restores the chain, refused once `stories-review` has opened. Only `ui-design` is
+skippable today (engine `SKIPPABLE_STEPS`).
+
 ### `test-cases` is a parallel, non-blocking track
 
 `test-cases` (and its `test-cases-review` gate) sit in `steps[]` after `stories-review`, but they are a

package/skills/yad-status/SKILL.md

@@ -46,6 +46,13 @@ Print, in this order:
    passes and runs alongside the build half, so when `currentStep` is `ready-for-build` the `test-cases`
    step may still be `in_progress`/`in_review` — show its status, and note "parallel" so it is clear it
    does not gate the build. Always render exactly the steps present in `steps[]`.
+   - **Skipped (N/A) steps:** the optional `ui-design` step may be marked N/A for an epic with no
+     user-facing surface. **Both** the `ui-design` author step **and** its `ui-design-review` gate stay
+     in `steps[]`, each carrying `skipped: true`, `status: "done"`, and a `skipReason`. Render **each**
+     as `<id> — SKIPPED (N/A: <skipReason>)` (with `skippedBy`/`skippedAt` if present) instead of the
+     plain status, so the deliberate skip and its reason are visible and the gate does not appear to
+     vanish. The chain then reads `… architecture-review → ui-design (N/A) → ui-design-review (N/A) →
+     stories → …`; the review gate never needs approvals.
 3. **Active gate** — for the `currentStep` (if it is a `review+approve` step), compute and show:
    - the reviewer rule in force — **base** (`owner + 1 reviewer`), **escalated** (list the required
      domains), or **per-repo** for `stories-review` (list each repo needing sign-off),

package/skills/yad-stories/SKILL.md

@@ -45,6 +45,11 @@ Read `epic.md` (scope, acceptance signals, `repos`), `architecture.md` (componen
 `contract.md` (the shared surface stories must honour), and `ui-design.md` (screens/flows). Stories
 must collectively satisfy the epic's acceptance signals and stay within the contract surface.
 
+- **UI-optional-safe:** `ui-design.md` may be absent — the `ui-design` step is optional and can be
+  marked N/A for an epic with no user-facing surface (state.json shows it `skipped`). When there is no
+  UI design, proceed without UI screens; the epic's acceptance signals + contract remain the source of
+  truth for the stories.
+
 ### Step 2b — Load existing-code context (make the brain code-aware)
 Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **each repo in
 `epic.repos`**, load the code-map `{project-root}/.sdlc/code-context/<repo>/code-map.md` so each story's

package/skills/yad-test-cases/SKILL.md

@@ -60,6 +60,10 @@ Read `epic.md` (user-level acceptance signals, scope), `architecture.md` (flows,
 **all** approved `stories/EP-<slug>-S0N.md`. Each story's **acceptance criteria are the source of truth**
 for the cases — the test cases must collectively verify every story's criteria.
 
+- **UI-optional-safe:** `ui-design.md` may be absent — the `ui-design` step is optional and can be
+  marked N/A for a UI-less epic (state.json shows it `skipped`). When there is no UI design, there are
+  simply no screens to exercise; the stories' acceptance criteria remain the source of truth.
+
 ### Step 2b — Load existing-code context (make the brain code-aware)
 Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **each repo in
 `epic.repos`**, load the code-map `{project-root}/.sdlc/code-context/<repo>/code-map.md` so the

package/skills/yad-ui/SKILL.md

@@ -42,6 +42,19 @@ it passes.
 This passes when `ui-design` is the next runnable step per the state sequence — every prior step
 (through the architecture review) is `done` and `ui-design` is not already `done`.
 
+**This step is OPTIONAL.** If the epic has no user-facing surface (a backend/API service, a data
+pipeline, infra work), it does not need a UI design. Two signals to watch for:
+
+- **Already skipped:** if `ui-design.status` is `done` with `skipped: true` in `state.json` (the
+  `--check` above will report `ui-design is already done`), the step was marked N/A — **STOP**, there
+  is nothing to author; point the user at `yad next EP-<slug>` (the next step is `stories`).
+- **Should be skipped:** if you reach this step and the epic clearly produces no screens, do **not**
+  invent a hollow UI artifact. Offer to mark it N/A instead:
+  `yad skip EP-<slug> ui-design --reason "<why, e.g. backend-only service>"`. That pre-marks both the
+  `ui-design` and `ui-design-review` steps `done` (recorded reason + actor), short-circuits the review
+  gate, and advances to `stories`. It is reversible with `yad skip EP-<slug> ui-design --undo` until the
+  stories review opens. See `../yad-epic/references/state-schema.md` → "ui-design is optional".
+
 ### Step 1b — Open the authoring branch
 Open the UI authoring branch `ui-design/EP-<slug>` per the shared procedure
 (`../yad-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note