yadflow 4.0.0-next.3 → 4.0.0

package/README.md

@@ -46,12 +46,20 @@ pass) · 🟦 **can run on auto** (a Build step the team may set to advance on i
 
 ## Quickstart
 
-From your **Product** repo (an empty git repo is fine):
+Pick the way in that fits. A **workspace** is the folder that holds the Product (`product/`) and
+your code repos side by side:
 
 ```bash
-npx yadflow setup        # 1. guided wizard: install skills, connect repos, wire CI gates
+npx yadflow new acme     # 1a. new product: makes acme/product/, then runs the guided setup
+npx yadflow init         # 1b. repos you already have: run in the folder that holds them
+npx yadflow join <url>   # 1c. joining a team: clones the Product and every repo it registers
+npx yadflow setup        #     or run the guided setup inside an existing Product repo
 ```
 
+`new` creates nothing outside your machine — it prints the `gh`/`glab` line that puts the Product
+online. `join` never commits or pushes; it only adds per-machine files. All three leave a small
+`.yad-workspace.json` in the workspace, so `yad` finds the Product from any repo it registers.
+
 Then, in your AI IDE, drive the lifecycle by invoking skills by name:
 
 ```text
@@ -63,8 +71,20 @@ 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).
+Running `yad` tells you when a new release is out. To upgrade, run these in the Product:
+
+```bash
+npm install -g yadflow   # 1. install the latest release
+yad migrate              # 2. preview: which state files this release would rewrite (writes nothing)
+yad migrate --apply      # 3. rewrite them, keeping a <file>.yad-orig copy of each
+yad update               # 4. re-sync this project's skills, gate scripts and CI files
+yad doctor               # 5. confirm everything is healthy
+```
+
+`yad migrate` moves your state files onto the file shape the new release expects. On a minor or patch
+release it usually has nothing to do. Coming from 3.x? Read
+[upgrading to 4.0](docs/migrations/upgrading-to-4.md) first. See also
+[staying up to date](docs/CLI.md#staying-up-to-date).
 An update rewrites the files yad manages (gate scripts, CI, PR/MR templates) — but not one **you**
 edited: yad records the sha of every file it writes, so an edit to one is reported as `modified` and
 left alone. A file it has no record of (an install predating that record) is still replaced, but only
@@ -73,13 +93,26 @@ after saving a `.yad-orig` backup
 
 ## 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)
+![yad new acme — makes acme/product/, runs the guided setup wizard (install the yad-* skills, record the Product, wire the gates, stamp the .sdlc config), then prints the commands that put the Product on GitHub or GitLab](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/media/setup-wizard.gif)
 
-The wizard is idempotent and profile-driven (solo/team, greenfield/brownfield, monorepo/separate).
+The recording shows `yad new acme`, which runs this wizard inside the new `acme/product/`
+([how to re-record it](https://github.com/abdelrahmannasr/yadflow/blob/main/docs/media/setup-wizard.tape)). The wizard is idempotent and profile-driven (solo/team, greenfield/brownfield, monorepo/separate).
 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.
+- **The `yad` CLI** — zero-dependency Node, run via `npx` or a global install. The main groups:
+
+  | Group | Commands |
+  | --- | --- |
+  | Start a workspace | `new`, `init`, `join`, `setup` |
+  | Drive the lifecycle | `next`, `epic new`, `foundation`, `gate`, `skip` / `defer` / `unblock`, `mode`, `dial`, `kill` |
+  | Drafts and owners | `capture`, `claims`, `fold`, `assign` / `unassign` / `owners` |
+  | Build | `commit`, `open-pr`, `ship`, `review`, `checkpoint`, `tidy up` |
+  | Code repos | `repo` (`list`, `clone`, `refresh`, `sync`), `risk-map`, `codeowners` |
+  | Feature threads | `thread`, `reconcile` |
+  | Read the record | `history`, `index`, `usage`, `docs` |
+  | Keep healthy | `doctor`, `check`, `update`, `migrate`, `report` |
+
+  Every command, with its flags: [docs/CLI.md](docs/CLI.md#commands).
 - **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).
@@ -92,18 +125,24 @@ In one pass it produces:
   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 Product — `hooks/ledger-guard.sh`, a harness hook that refuses an
+- **An agent guardrail** on a verified Product — `hooks/ledger-guard.mjs`, 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
+  (stdin payload, exit 0 allows / 2 denies) and fails open — the CI gate stays the authority. The same
+  rule guards a person's `git commit` through a `pre-commit` hook `yad check --fix` installs in each clone
+  (E48); it never overwrites a hook of your own. What to turn on in GitHub or GitLab so the CI checks
+  actually hold a merge: [Branch protection](docs/branch-protection.md).
+- **Background capture** on every Product, in both ledger modes (E43) — `hooks/yad-capture.mjs`, 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. `yad epic new <slug>` does the same seeding
+Your first `yad-epic` seeds the `epics/EP-<slug>/` ledger — the step state and the approvals — so the
+audit trail starts the moment you begin real work. The contract lock (`.sdlc/contract-lock.json`, the
+hash of the shared contract surface) is written later, by `yad-architecture`. The one exception is a
+change-epic that carries its parent's architecture: `yad epic new <slug> --type change --parent EP-<parent> --inherits architecture,contract`
+(run for you by `yad-change`) writes a small **pointer-lock** that points at the parent's lock. `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
@@ -185,7 +224,7 @@ architecture". It is stronger advice than a claim, because it is decided in adva
 | `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 |
+| 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 product-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 |
@@ -226,11 +265,11 @@ failed pipeline. It needs a hook that can run *before* a write and refuse it. Tw
 | 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`,
+refusal — so a `.cursor` project also gets a small adapter script, `hooks/ledger-guard-cursor.mjs`,
 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
+Every other directory gets the script (`hooks/ledger-guard.mjs`) 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.
@@ -243,10 +282,13 @@ against a live Cursor session.
 setup → AI drafts an artifact → ⛔ gate waits → you approve → next step → ⛔ gate waits → …
 ```
 
-1. **`npx yadflow setup`** — the wizard installs skills, connects your repo, and wires the gates.
+1. **Get a workspace** — `npx yadflow new <name>` for a new product, `npx yadflow init` for repos you
+   already have, or `npx yadflow join <url>` to join a team (see [Quickstart](#quickstart)). The
+   wizard installs the skills, connects your repos, and wires the gates.
 2. **Run `yad-epic`** in your assistant — it drafts the epic, then **stops** and writes it to a file.
 3. **A gate waits.** Nothing advances until you review it.
-4. **You approve** — local, or by merging the review PR/MR.
+4. **You approve** — by merging the review PR/MR, or, with no GitHub or GitLab, with
+   `yad gate approve` and `yad gate advance`.
 5. **The workflow continues** to the next step, which stops again.
 
 Every step is the same contract: *AI proposes → a human decides → the trail is recorded.*
@@ -283,12 +325,13 @@ complementary: bring your favorite, and Yadflow wraps the engineering process ar
 
 Reviewing AI-generated code is where governance lives or dies, so Yadflow makes the honest review the
 *easiest* path. The **Review Companion** turns any PR/MR into a 60-second trailer, swipe-through cards,
-and a grounded chat. **Pair Review** (`yad pair-review`) goes further: the AI walks you through the
+and a grounded chat. **Pair Review** (the `yad-pair-review` skill; its CLI side is `yad gate walkthrough` for a Shape
+review and `yad review walkthrough` for a code PR) goes further: the AI walks you through the
 change one risk-ordered stop at a time, explains each, then asks you about it — until both sides are
 satisfied.
 
 It doubles as a lesson: it teaches a transferable review method, scores you against it, and records
-your review-skill growth in a **private, local-only** learning log (`yad status` rolls it up). It's
+your review-skill growth in a **private, local-only** learning log (the `yad-status` skill rolls it up). It's
 **soft and additive** — it never blocks a merge on its own, yet any genuine concern it surfaces blocks
 like a normal review comment.
 
@@ -316,8 +359,28 @@ workflow-hygiene flags — derived read-only, so an EM can see how the team actu
 ---
 
 **Platform support.** Linux and macOS are first-class (CI runs the test suite, bash gates, and the
-end-to-end harness on both). On **Windows use [WSL](https://learn.microsoft.com/windows/wsl/)** — native
-PowerShell is not yet supported. Requires **Node.js ≥ 18**.
+end-to-end harness on both). **On Windows, the agent hooks run natively, without WSL** (E113), and the
+CLI code they reach has been fixed for Windows — CI runs the hook scripts and those CLI tests on Windows.
+The rest of the CLI is not yet tested there. Requires **Node.js ≥ 18**.
+
+| On Windows | What to know |
+| --- | --- |
+| Agent hooks | Each hook is a Node script (`hooks/*.mjs`) that the agent runs as `node <script>`, so nothing needs bash or an execute bit. `node` must be on the PATH your agent runs with — if it is not, the hooks silently do not run |
+| Claude Code | Runs hook commands in **Git Bash** (part of Git for Windows). Without Git Bash it falls back to PowerShell, and the hooks do not run there. `yad doctor` warns when it cannot find Git Bash |
+| Cursor | Runs hook commands through PowerShell. The entry is `node hooks/<script>.mjs`, which PowerShell runs as it is |
+| Line endings | Set `git config core.autocrlf input` in the Product clone. With `true` (the Git for Windows default) git checks files out with CRLF line endings. yad's own managed files still compare equal, but an approval is bound to an artifact's exact bytes, so reviews approved elsewhere read as stale. `yad doctor` warns about this on Windows |
+| Check gates | Still bash scripts (`checks/*.sh`). They run on your CI runner, not on your machine |
+| Not yet tested on Windows | The full test suite and the end-to-end harness run on Linux and macOS only. A machine with no Git Bash is not covered for Claude Code |
+
+**Upgrading from a release before E113.** The hooks used to be bash scripts (`hooks/*.sh`). `yad check
+--fix` (or `yad update`) rewrites each hook entry to the Node command and deletes the old script — but
+only a copy yad's own record (`.sdlc/managed.json`) proves it wrote and nobody changed. A script you
+edited, or one your own hook entry still runs, is kept. The old script is also kept until the rewritten
+settings file is **committed**: yad never commits that file for you, and a teammate who pulls must not get
+an entry that runs a deleted script. So the order is: `yad check --fix`, commit `.claude/settings.json` and
+`.cursor/hooks.json`, then `yad check --fix` again to remove the old scripts. Everyone on the team should
+upgrade together: an older yadflow does not know the new entries, and its `check --fix` puts the old
+script and entry back beside them.
 
 **Releases** are a human decision. Merging to `main` never publishes; a person fast-forwards the
 `release` branch, and [semantic-release](https://semantic-release.gitbook.io/) publishes from there

package/bin/commands.mjs

@@ -11,10 +11,12 @@
 // is about to do real work.
 
 export { runSetup } from '../cli/setup.mjs';
+export { runNew, runInit, runJoin } from '../cli/workspace.mjs';
+export { findProduct, hasProduct, workspaceProduct, registryEntryFor, WORKSPACE_FILE } from '../cli/find-product.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 { isValidEpicId, productDriftError, 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';