yadflow 3.9.3 → 3.10.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
+# [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)
 
+
+_Maintenance release — CHANGELOG backfill and dependency-audit fixes (`chore`/`docs` commits carry no user-facing changes)._
+
+
+
 ## [3.9.2](https://github.com/abdelrahmannasr/yadflow/compare/v3.9.1...v3.9.2) (2026-07-06)
 
 

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/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.3",
+  "version": "3.10.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",
@@ -63,6 +63,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
     "eslint": "^10.5.0",
     "semantic-release": "^25.0.3"
   }

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