yadflow 3.19.0-next.2 → 4.0.0-next.3

package/README.md

@@ -13,8 +13,8 @@ AI builds and a human clears every gate.**
 > Yadflow doesn't write your code; it governs how AI-written code ships. Keep Cursor, GitHub Copilot,
 > Claude Code, Continue — or hand-written commits. The zero-dependency `yad` CLI and the CI gates
 > review the work **no matter who or what produced it.** The workflow skills run today in
-> **Claude Code** (plus `.agents`, Zencoder, and OpenCode), and **BMAD is the default packaging,
-> not a limitation.**
+> **Claude Code, Codex CLI, Cursor, Gemini CLI, GitHub Copilot, Zencoder and opencode** — see
+> [which agent reads which directory](#which-ai-agents-are-supported).
 
 ## The problem
 
@@ -27,26 +27,26 @@ AI, the harder it gets to keep control of quality, architecture, and accountabil
 
 Yadflow puts a **human gate on every step** of the lifecycle. Each step does its work, writes its
 output to a plain file, and **waits** — it never advances until a human clears its gate (by approving,
-or in solo mode by merging your own PR), or, later, once a step has *earned* the right to auto-advance.
+or in solo mode, switched with `yad mode`, by merging your own PR) — or, for a Build step the team set to `auto`, on its own after a clean run.
 Reviews ride real PR/MRs; all state lives in files you
 can read, diff, and edit — no database, nothing hidden. The result is a paper trail for every decision
 and a hard wall between "AI proposed" and "we shipped it."
 
-It installs as a custom [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) module and works across
-one product hub + many code repos, solo or team.
+It installs with one command (`npx yadflow setup`) and works across one Product + many code repos,
+solo or team.
 
 ## How the workflow looks
 
 <!-- Source: docs/diagrams/sdlc-overview.mmd — edit the .mmd and run `npm run diagrams` to regenerate -->
-![Yadflow SDLC overview — setup, human-gated Shape, per-story Build, earned automation](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/sdlc-overview.svg)
+![Yadflow SDLC overview — setup, human-gated Shape, per-story Build, automation you switch on](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/sdlc-overview.svg)
 
 **Legend:** 🟨 **artifact** (a step writes a file and stops) · 🟧 **gate** (a human review that must
-pass) · 🟦 **earns automation** (a Build step that can later auto-advance once it proves itself) ·
-⬜ **locked** (the engineer review and every Shape step — permanently human).
+pass) · 🟦 **can run on auto** (a Build step the team may set to advance on its own, with `yad dial`) ·
+⬜ **locked** (the engineer review — always a person).
 
 ## Quickstart
 
-From your **product hub** repo (an empty git repo is fine):
+From your **Product** repo (an empty git repo is fine):
 
 ```bash
 npx yadflow setup        # 1. guided wizard: install skills, connect repos, wire CI gates
@@ -80,23 +80,160 @@ In one pass it produces:
 
 - **The `yad` CLI** — zero-dependency Node (`setup`, `gate`, `commit`, `open-pr`, `ship`, `repo`,
   `thread`, `reconcile`, `usage`, `doctor`), run via `npx` or a global install.
-- **38 workflow skills** installed into your AI assistant — **Claude Code** (`.claude/`) first-class,
-  plus `.agents`, Zencoder, and OpenCode.
-- **`.sdlc/` config** — the product hub, connected repos, reviewer roster, and tool connections
+- **38 workflow skills** installed into your AI assistant — Claude Code, Codex CLI, Cursor,
+  Gemini CLI, GitHub Copilot, Zencoder and opencode. See
+  [which agent reads which directory](#which-ai-agents-are-supported).
+- **`.sdlc/` config** — the Product, connected repos, and tool connections
   (design, testing, learning), all as plain JSON you can read and diff.
-- **CI gates**, wired into every connected repo and the hub as **GitHub Actions or GitLab CI** —
-  spec-link, contract-check, verified-commits, build/test/lint, the feature-thread gates, and the
-  push-on-main **`yad-update-guard`** (which re-checks any direct-to-default commit — e.g. from
+- **CI gates**, wired into every connected repo and the Product as **GitHub Actions or GitLab CI** —
+  spec-link, contract-check, verified-commits, build/test/lint, the feature-thread gates, the advisory
+  risk-map check (warns when a code repo's `.sdlc/risk-map` — a risk level per directory, no names — is
+  stale, says how many approvers a PR asks for — one more when it touches a `high` directory — and names
+  who has worked in that directory in the last 30 days), and the push-on-main **`yad-update-guard`** (which re-checks any direct-to-default commit — e.g. from
   `yad update --push` — with just `verified-commits` + `commit-message`), shipped as CI-agnostic bash
   under `checks/`.
-- **An agent guardrail** on a verified hub — `hooks/ledger-guard.sh`, a harness hook that refuses an
+- **An agent guardrail** on a verified Product — `hooks/ledger-guard.sh`, a harness hook that refuses an
   agent the CI-owned gate-ledger write at the moment it tries it and names the command that owns the
   transition, instead of letting it surface as a CI failure twenty minutes later. Harness-agnostic
   (stdin payload, exit 0 allows / 2 denies) and fails open — the CI gate stays the authority.
+- **Background capture** on every Product, in both ledger modes (E43) — `hooks/yad-capture.sh`, a
+  harness hook that runs `yad capture` after each agent edit. It snapshots every changed Shape artifact
+  onto your private `yad/wip/<you>/<epic>` branches, so a draft is never lost and nobody types a git
+  command. See [Background capture](#background-capture) below.
 - **PR/MR templates** and an opt-in CodeRabbit config.
 
 Your first `yad-epic` seeds the `epics/EP-<slug>/` ledger — state, approvals, and the contract lock —
-so the audit trail starts the moment you begin real work.
+so the audit trail starts the moment you begin real work. `yad epic new <slug>` does the same seeding
+from the CLI when you would rather lay the track before the writing starts.
+
+Before any epic, you can also frame the whole product once: `yad foundation new` seeds the
+**Foundation** — the Product level, in `foundation/` — and the `yad-discovery` skill writes its
+sections (purpose, scope, MVP, roadmap, stack, repos). It is optional, and each epic reads its approved
+roadmap.
+
+## Which AI agents are supported
+
+An **agent skill** is a folder holding a `SKILL.md` file — instructions the agent loads when the task
+matches. `SKILL.md` is now a format several agents read, and `.agents/skills/` is the directory
+several of them agreed to look in. So one install can serve more than one agent.
+
+`yad setup` asks which directories to install into. Pick by the agent you use:
+
+| Directory | Agents that read it |
+| --- | --- |
+| `.claude/` | Claude Code. Cursor also reads it for compatibility. |
+| `.agents/` | Codex CLI, Gemini CLI, Cursor, GitHub Copilot |
+| `.cursor/` | Cursor — its own directory. Not needed if you install `.agents/`. |
+| `.gemini/` | Gemini CLI — its own directory. Not needed if you install `.agents/`. |
+| `.zencoder/` | Zencoder |
+| `.opencode/` | opencode — installed as flat `commands/<skill>.md` files, not folders |
+
+A fresh setup offers **`.claude,.agents`**, which together cover every agent in the table. A project that already
+has an INSTALL in one of them — a `skills/` folder, or an armed hook entry — is offered that one
+instead; a `.cursor/` holding only Cursor rules is not an install, and is offered the default. Checked against each agent's
+own documentation on 2026-09-16; `yad doctor` prints the same table's verdict for your project.
+
+### Background capture
+
+`yad capture` saves your work in progress without touching your checkout (E43). It takes every changed
+file under `epics/` and `foundation/` — except the ledger (any `.sdlc/` folder and `reviews/`; the four
+files a person or a skill writes there, `contract-lock.json`, `change.json`, `design-links.json` and
+`test-links.json`, are included) — and commits it onto
+a private branch per epic, `yad/wip/<your git name>/<epic>`. It uses git's low-level commands in a
+throwaway index, so your branch, your staged changes and your files stay exactly as they were, and no
+git hook runs.
+
+| What | How |
+| --- | --- |
+| When | After every agent edit, by a hook yad wires in both ledger modes: Claude Code `PostToolUse` in `.claude/settings.json`, Cursor `afterFileEdit` in `.cursor/hooks.json`. Any other agent or editor: run `yad capture` yourself. Each capture takes every changed artifact, so your own editor's edits ride along |
+| Push | A capture commits at once, locally. The hook pushes your capture branches (and fetches everyone else's, for claims) in the background at most once every 5 minutes, with no password prompt and a short timeout, so an edit never waits on the network. `yad capture` by hand pushes straight away. With no remote, or offline, the captures stay local and nothing fails |
+| CI | yadflow's own push workflow skips `yad/wip/**`. `yad doctor` names any of **your** workflows a push to `yad/wip/*` would start (no branch filter, `branches: ["**"]`, or a `branches-ignore` that does not name it), so you can add `branches-ignore: ["yad/wip/**"]` |
+| Off | `"capture": false` in the Product config (`yad check --fix` then removes the hook), or `YAD_CAPTURE=0` for one shell |
+
+The capture commits are unsigned on purpose — a signing prompt inside a hook would hang the agent — and
+each carries `Yad-Epic`, `Yad-Base` and `Yad-Branch` lines. They are drafts: the commit your history
+keeps is the fold, below. The push is never forced: if you capture the same epic on two machines, the second push is refused rather than overwriting the first, and a `yad capture` you run by hand says so and names the branch (delete one copy with `git branch -D` to continue the other) — the hook's background push cannot report it. **To remove a capture branch for good** — say a secret was captured — delete it on origin first, then on every machine that has it run `git branch -D yad/wip/<you>/<epic>` **and** `git branch -dr origin/yad/wip/<you>/<epic>` (the second deletes that machine's saved copy of origin's branch; it says so if there is none): a machine that still holds either one rebuilds the branch and pushes it back. On a fresh clone, a capture continues the branch already on origin. Two people with the same git name share branches. The people count that caps review gates
+(E71) does not count capture commits.
+
+### Who else is editing a file (claims)
+
+`yad claims` lists who else is editing which artifact right now (E46). It is **advice, not a lock**:
+nothing stops anyone, because with no server a real lock is impossible. There is nothing to record by
+hand — a claim is read from the capture branches: someone's `yad/wip/<name>/<epic>` branch holds a
+saved change to that file that is not on the default branch yet.
+
+| What | How |
+| --- | --- |
+| A claim | A file of the epic that differs between the capture branch's last save and the commit that save was built on — the person's own edits, never what a pull brought in |
+| Ends | 4 hours after that branch's last save, or at once when the file on the default branch matches the saved one (the work was merged) |
+| `yad claims [<epic>]` | Fetches everyone's capture branches first (short timeout, no prompts), then lists each claim: file, person, last save. `--no-fetch` reads what is already here; `--json` too |
+| At edit time | When an edit changes a file someone else has a claim on, the capture hook says so. Under Claude Code the agent reads it (and you see it); under Cursor it is a line on stderr. It never blocks, never waits on the network, and names the same person and file at most once an hour |
+| Fresh enough | The hook's background push (at most every 5 minutes) also fetches everyone's capture branches in the background |
+
+**Limits.** Someone with capture off, or offline, is invisible. A claim can be up to about 5 minutes
+late. Two people with the same git name share capture branches, so they never see each other. Times
+are the saver's own clock, shown in UTC.
+
+### Who owns a step (assign)
+
+`yad assign` gives one authoring step to one person (E47) — for example "Bob writes the
+architecture". It is stronger advice than a claim, because it is decided in advance, but it is still
+**advice, not a lock**: it never blocks an edit, never holds a review gate and never stops a fold.
+
+| What | How |
+| --- | --- |
+| `yad assign <epic> <step> [--to <name>]` | Assigns the step to you, or to the person whose **git name** you give (the name they commit with). Only authoring steps that write an artifact (`epic`, `architecture`, `stories`, …); review steps are not assigned, because the platform and the gate count decide who approves. If someone else already owns the step it is refused and names them; `--force` replaces them |
+| `yad unassign <epic> <step>` | Removes the assignment. Your own freely; someone else's needs `--force` |
+| `yad owners [<epic>]` | Lists every assignment, whether it is live, and any owner file that cannot be read. `--json` too |
+| Where it is kept | One small file per step: `epics/<epic>/.sdlc/owners/<step>.json` (`foundation/.sdlc/owners/` for the Foundation). It is not a ledger file, so you can write it in both ledger modes. `yad assign` does not commit it, and `yad fold` never takes it (an assignment is not authoring): commit it on its own — on a `verified` Product, in a PR of its own (the Product checks let a PR that changes only owner files through, since E47; run `yad update` so your copies of the checks and of the hub-checks workflow have that rule; `yad doctor` warns `owners:rename-blind` if a hand-edited workflow was kept) — so the team sees it when they pull. It is captured to your `yad/wip/…` branch like any artifact, but it is not counted as a claim |
+| Live | While the step's work is open: the step is not finished, or its review has not passed yet. After that the file stays as a record; re-opening the step makes it live again. There is no time limit |
+| Shown | `yad next` prints `owner: <name>` under the step (and under its review) while it is live |
+| At edit time | When your edit changes a file of a step someone else owns, the capture hook says so — to the agent under Claude Code, on stderr under Cursor — at most once an hour per step. One note carries both this and any claim warning |
+
+**Limits.** The name is the git name, made branch-safe the way capture branch names are — so it matches
+the capture hook without asking GitHub or GitLab. Two people with the same git name look like one owner.
+A git name with no Latin letters is branch-safe only through the person's email, so someone else can
+assign it only once that person has a capture branch here (`--to` finds it by the git name the branch was
+saved under). With capture off, there is no edit-time warning.
+
+### Folding a step into one commit
+
+`yad fold <epic> <step>` ends an authoring step (E44). It makes the one commit the record keeps,
+`docs(<epic>): author <step>` — for example `docs(EP-checkout): author architecture`. The authoring
+skills run it at the end of their step; you can run it yourself too.
+
+| What | How |
+| --- | --- |
+| Files | Only that step's files: the ones its review covers (architecture is `architecture.md`, `contract.md` and `.sdlc/contract-lock.json`; stories is everything under `stories/`), plus what the step's skill writes beside them (`DESIGN.md` and `.sdlc/design-links.json` for the UI step, `.sdlc/test-links.json` for test cases). Other changed files of the epic are named and left on disk, so a half-written draft of another step never lands in this commit |
+| The ledger | Follows `ledger` mode. `local`: the epic's changed ledger files go in the same commit — one step, one commit. `verified`: CI writes the ledger at merge, so the fold leaves those files for CI — except while the epic is brand new (no `.sdlc/state.json` in HEAD yet): then its new ledger files are its seed, which is the case `ledger-guard` allows and the only way a seed reaches the default branch. Once the epic is seeded, even a NEW ledger file (a `reviews/*.md` written by hand) is left for CI, because the guard would reject it |
+| The seed | While the epic is brand new, the first fold also takes the new person-written `.sdlc/` files beside the ledger — a change-epic's `change.json` and its pointer `contract-lock.json` — in both modes |
+| The commit | A normal `git commit`, so it is signed if your git signs (with `ledger: verified` it warns when signing is off: the review PR's signature check would fail), and your commit hooks run. Only the step's files are committed; anything else you staged stays staged. It ends with `Yad-Epic`, `Yad-Step` and `Yad-Folded` lines — the last is the tip of your capture branch, the drafts this commit folds (`none` with capture off) |
+| Where | With `ledger: verified`, never on the default branch — artifacts reach it only through the review PR. With `ledger: local`, anywhere |
+| The drafts | Your `yad/wip/<you>/<epic>` branch is left as it is: the draft history stays for the later rework measurement (E95), and nothing has to be deleted on other machines. The next capture has nothing new to save |
+
+A step with no changed files has nothing to fold, and says so. `yad open-pr` on a review branch warns
+when that step's files have changes no fold has committed — they are not in the review.
+
+### The local ledger guard, per agent
+
+In **verified mode** — where CI owns the gate ledger — yadflow installs a local guardrail that stops
+an agent hand-editing the gate files, at the moment of the edit rather than twenty minutes later in a
+failed pipeline. It needs a hook that can run *before* a write and refuse it. Two agents have one:
+
+| Agent | Wired into | Event |
+| --- | --- | --- |
+| Claude Code | `.claude/settings.json` | `PreToolUse` |
+| Cursor | `.cursor/hooks.json` | `preToolUse` |
+
+Cursor answers this kind of hook in JSON rather than by exit code, and treats an empty answer as a
+refusal — so a `.cursor` project also gets a small adapter script, `hooks/ledger-guard-cursor.sh`,
+which always replies properly. Without it the guard would have blocked every file write instead of
+just the gate files.
+
+Every other directory gets the script (`hooks/ledger-guard.sh`) and no wiring — they have no such
+hook, so those agents are guarded by CI alone. `yad doctor` says so by name rather than staying
+silent. The Cursor wiring follows Cursor's published hook protocol and has not yet been exercised
+against a live Cursor session.
 
 ## Your first five minutes
 
@@ -116,14 +253,14 @@ Every step is the same contract: *AI proposes → a human decides → the trail
 
 ## How it works (in five points)
 
-- **Shape = decide.** Once per epic, in the product hub: epic, architecture + a locked contract,
+- **Shape = decide.** Once per epic, in the Product: epic, architecture + a locked contract,
   UI, stories, test cases. Always human-gated — nothing auto-advances.
 - **Build = make it real.** Once per story per code repo: spec → implement → checks → ship.
 - **Every step stops at a gate.** A human moves it forward (local, or by merging a review PR/MR).
   <!-- IMAGE: docs/media/pr-gate.png — "The review gate rides a real PR/MR: approve to advance, comment to block." -->
-- **Automation is opt-in and earned.** A safe Build step can earn auto-advance after it proves
-  itself — and a one-command kill switch reverts everything to manual. The engineer review and all
-  Shape steps are never automatable.
+- **Automation is opt-in.** The team switches a Build step to auto with `yad dial`, which shows that
+  step's run record as advice — and `yad kill` holds everything at manual in one command. A review
+  gate — the engineer review and every Shape review — is never automatic.
 - **Everything is files.** State, approvals, the contract lock, the build log — all plain files under
   `epics/EP-<slug>/`. No database. The audit trail *is* the repo.
 
@@ -139,7 +276,7 @@ complementary: bring your favorite, and Yadflow wraps the engineering process ar
 | **Layer**     | Writes the code          | Governs how it ships                                 |
 | **Output**    | Diffs, completions       | Gated artifacts + a file-based audit trail           |
 | **Answers**   | "Write this for me"      | "Should this merge — and who approved it?"           |
-| **Review**    | You eyeball the diff     | Human-gated PR/MR, contract lock, earned automation  |
+| **Review**    | You eyeball the diff     | Human-gated PR/MR, contract lock, switchable automation |
 | **Fit**       | Bring your own           | Wraps around all of them                             |
 
 ## Review, made a pairing — and a lesson
@@ -174,6 +311,7 @@ workflow-hygiene flags — derived read-only, so an EM can see how the team actu
 - **[docs/SKILLS.md](docs/SKILLS.md)** — the catalogue of all 38 agent skills.
 - **[docs/WALKTHROUGH.md](docs/WALKTHROUGH.md)** — the by-hand, end-to-end path through every phase.
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** · **[RESEARCH-NOTES.md](RESEARCH-NOTES.md)** · **[RELEASING.md](RELEASING.md)**
+- **[SECURITY.md](SECURITY.md)** — how to report a vulnerability, which versions get fixes, and the supply-chain stance. **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — the community standards for taking part.
 
 ---
 

package/bin/commands.mjs

@@ -0,0 +1,46 @@
+// Every command module, behind ONE dynamic import (E11 review).
+//
+// `yad hook ledger-guard` runs on EVERY file-editing tool call an agent makes, inside its tool
+// loop. It needs `cli/hook.mjs` and nothing else, but a static import list in `bin/yad.mjs` is
+// hoisted and evaluated before any code runs — so the hook was loading all 29 modules of the CLI,
+// measured at ~30ms against ~14ms for what it actually uses, on every single edit.
+//
+// Re-exporting through one module keeps that mechanical: `bin/yad.mjs` awaits this once, after it
+// has already handled `hook`, and every command reads off the result. Nothing here is lazy in
+// itself — importing this file still loads everything, which is exactly right for a command that
+// is about to do real work.
+
+export { runSetup } from '../cli/setup.mjs';
+export { reconcile } from '../cli/reconcile.mjs';
+export { gateOpen, gateSync, gateComments, gateStatus, gateCi, gateReview, gateTrailer, gateWalkthrough, gateRepair } from '../cli/gate.mjs';
+export { gateApprove, gateComment, gateAdvance } from '../cli/gate-local.mjs';
+export { isValidEpicId, seedableProfiles } from '../cli/epic-state.mjs';
+export { runEpicNew, runFoundationNew, runFoundationStatus } from '../cli/epic.mjs';
+export { runSkillBind, runSkillList, runSkillUnbind } from '../cli/skill.mjs';
+export { runCommit } from '../cli/commit.mjs';
+export { runOpenPr } from '../cli/openpr.mjs';
+export { reviewTrailer, reviewContext, reviewNudge, reviewReconcile, reviewWalkthrough } from '../cli/review.mjs';
+export { runShip } from '../cli/ship.mjs';
+export { runCheckpoint } from '../cli/checkpoint.mjs';
+export { runTidy } from '../cli/tidy.mjs';
+export { runCapture } from '../cli/capture.mjs';
+export { runFold } from '../cli/fold.mjs';
+export { runClaims } from '../cli/claims.mjs';
+export { runAssign, runUnassign, runOwners } from '../cli/owners.mjs';
+export { runIndex } from '../cli/index-command.mjs';
+export { runHistory, HISTORY_FLAGS } from '../cli/history.mjs';
+export { runRepo } from '../cli/repo.mjs';
+export { runRiskMap } from '../cli/riskmap-command.mjs';
+export { runCodeowners } from '../cli/codeowners-command.mjs';
+export { runDocs } from '../cli/docs.mjs';
+export { runDoctor } from '../cli/doctor.mjs';
+export { runMigrate, warnIfProjectAhead } from '../cli/migrate.mjs';
+export { runNext } from '../cli/next.mjs';
+export { runSkip, runDefer, runUnblock, runLaneSkip } from '../cli/skip.mjs';
+export { runDial, runKill } from '../cli/dial.mjs';
+export { runMode } from '../cli/mode.mjs';
+export { syncStatuses } from '../cli/artifact-status.mjs';
+export { runThread, runReconcile } from '../cli/thread.mjs';
+export { runReport } from '../cli/report.mjs';
+export { runUsage } from '../cli/usage.mjs';
+export { maybeNotifyUpdate } from '../cli/update-notice.mjs';