npm - yadflow - Versions diffs - 2.18.0 → 2.18.1 - Mend

yadflow 2.18.0 → 2.18.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md +3 -3
package/README.md +60 -671
package/cli/docs.mjs +6 -5
package/package.json +1 -1
package/skills/yad-docs-overview/SKILL.md +1 -1
package/skills/yad-docs-overview/references/pipeline-model.md +22 -3

package/CHANGELOG.md CHANGED Viewed

@@ -1,9 +1,9 @@
-# [2.18.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.17.0...v2.18.0) (2026-06-26)
+## [2.18.1](https://github.com/abdelrahmannasr/yadflow/compare/v2.18.0...v2.18.1) (2026-06-28)
-### Features
+### Bug Fixes
-* **change:** post-lock change management via feature threads (Phase 6) ([#83](https://github.com/abdelrahmannasr/yadflow/issues/83)) ([f8024d5](https://github.com/abdelrahmannasr/yadflow/commit/f8024d5808070656d1c3039905ada39096fe7d3b)), closes [#1](https://github.com/abdelrahmannasr/yadflow/issues/1)
+* publish updated README and tutorial site to npm ([a7cd251](https://github.com/abdelrahmannasr/yadflow/commit/a7cd251203819565bbde76dd47959ff92b12900c)), closes [#84](https://github.com/abdelrahmannasr/yadflow/issues/84) [#85](https://github.com/abdelrahmannasr/yadflow/issues/85)
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)

package/README.md CHANGED Viewed

@@ -1,703 +1,92 @@
-# Yadflow — the gated, team, multi-repo SDLC on top of BMAD
+# Yadflow — keep AI-generated code from shipping ungoverned
 [![npm version](https://img.shields.io/npm/v/yadflow?logo=npm)](https://www.npmjs.com/package/yadflow)
 [![CI](https://github.com/abdelrahmannasr/yadflow/actions/workflows/ci.yml/badge.svg)](https://github.com/abdelrahmannasr/yadflow/actions/workflows/ci.yml)
-[![provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://docs.npmjs.com/generating-provenance-statements)
 [![node](https://img.shields.io/node/v/yadflow?logo=node.js)](https://github.com/abdelrahmannasr/yadflow/blob/main/package.json)
-[![security policy](https://img.shields.io/badge/security-policy-brightgreen)](https://github.com/abdelrahmannasr/yadflow/blob/main/SECURITY.md)
 [![report](https://img.shields.io/badge/docs-Yadflow%20report-2471a3)](https://abdelrahmannasr.github.io/yadflow/)
-> 📖 **Start here: the [Yadflow Terminology & Workflow Structure Report](https://abdelrahmannasr.github.io/yadflow/)** —
-> the full picture of every term, artifact, gate and skill in one richly illustrated page.
+**A gated software-development lifecycle where AI builds and a human approves every step.**
+*AI builds. The hand decides.* (*yad* — **يد**, Arabic for "hand".) On npm and GitHub as `yadflow`.
-**Yadflow** (*yahd-flow* — from **يد**, Arabic for "hand") is the AI-driven SDLC where a human hand
-moves every gate. *AI builds. The hand decides.* On npm and GitHub as `yadflow`.
+## The problem
-A custom BMAD module that turns BMAD from a solo tool into a **team, gated, file-driven SDLC
-engine**. Every step does its work, writes its output to a file, and **waits at a gate**. Who
-advances the gate (human now; machine later) is a per-step setting. All state lives in files —
-nothing hidden, no database.
+AI writes code faster than any team can review it. Left ungoverned, that speed turns into risk:
+unreviewed AI-generated changes merge straight into the codebase, architectural decisions get made
+by autocomplete, and the trail of *why* a change was made disappears. The faster the team ships with
+AI, the harder it gets to keep control of quality, architecture, and accountability.
-This repo is the **first deliverable** (see `docs/claude-code-build-plan.md` §10): verified research,
-a scaffolded module that installs cleanly, and a working **team review gate** you run by hand.
+## What Yadflow is
-## The workflow at a glance
+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 approves it (or, later, until
+a step has *earned* the right to auto-advance). 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."
-The whole lifecycle, from an empty project to shipped code. Setup is one-time; the optional
-**front-zero** (`yad-discovery`) frames the whole project once — market, feasibility, and a phased
-roadmap; the **front half** is human-gated and runs once per epic in the product hub; the **build
-half** runs once per story per code repo; **automation** is opt-in and earned. `yad-status` reads it
-all; `yad-hub-bridge` mirrors front-half reviews to real PR/MRs.
+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.
+## 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 front half, per-story build half, earned automation](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/sdlc-overview.svg)
-**Legend.** <span>🟨</span> **artifact** = an author step writes a file and stops; <span>🟧</span>
-**gate** = a human review that must pass (`open → comment → approve → advance`); <span>🟦</span>
-**earns automation** = a back step that can be set to `machine_advance` once it proves itself;
-<span>⬜ dashed</span> **locked** = the engineer review and every front state, **permanently
-human**. Detailed walkthroughs for each phase follow below.
-## What's here
-| Path | What it is |
-|------|-----------|
-| `RESEARCH-NOTES.md` | Verified Phase 0 facts about BMAD, Spec Kit, Repomix, Impeccable + deviations. |
-| `skills/sdlc/` | Module source of truth (`config.yaml`, `module-help.csv`, `install.sh`). Survives BMAD updates. |
-| `bin/`, `cli/` | The `yad` setup/update CLI (published to npm as `yadflow`). |
-| `skills/yad-discovery/` | Optional front-zero (once per project, greenfield + brownfield): market research, competitor study, feasibility, current-state, requirements (functional + non-functional) and a phased roadmap (MVP+) under the reserved `EP-discovery`. `roadmap.md` is the menu of features each epic reads. |
-| `skills/yad-analysis/` | Optional front state 1: pressure-test the idea with the analyst into `analysis.md` (skippable). |
-| `skills/yad-epic/` | Front state 1: author an epic with AI assist, assign its `EP-<slug>` ID, seed state. |
-| `skills/yad-architecture/` | Front state 3: author `architecture.md` + the locked `contract.md`; hash-lock the contract surface. |
-| `skills/yad-ui/` | Front state 5: author `ui-design.md` + `DESIGN.md` (Impeccable slash-commands, or graceful fallback). |
-| `skills/yad-stories/` | Front state 7: break the epic into repo-tagged stories with stable `EP-<slug>-S0N` IDs. |
-| `skills/yad-test-cases/` | Front state 9: with the test architect author `test-cases.md`; implement the automation in the connected testing tool, or produce artifacts only. |
-| `skills/yad-connect-repos/` | Connect code repos to the hub (GitHub/GitLab, local-user auth); cache a Repomix pack + **code-map** per repo so the front phases are code-aware. |
-| `skills/yad-connect-learning/` | Connect a learning tool (DeepTutor-first, pluggable) — a CLI subprocess like Repomix; record `.sdlc/learning.json` + an optional grounded knowledge base. |
-| `skills/yad-learn/` | The cross-cutting **learning layer**: tutor any member, at any stage, in the context of what's being built; records a personal, local-only skills log (gitignored, never committed/pushed). Opt-in, never gates. |
-| `skills/yad-review-gate/` | The reusable **team review + approve gate** (used for all five reviews). |
-| `skills/yad-spec/` | Build Step A: run the Spec Kit ceremony once per story per repo → `specs/<story-id>/`. |
-| `skills/yad-implement/` | Build Step B: implement ONE atomic task as a small diff on its own branch. |
-| `skills/yad-checks/` | Build Step C: wire + run the CI gates (spec-link, contract-check, build/test/lint, verified-commits). |
-| `skills/yad-pr-template/` | Build Step D: install the platform PR/MR template + risk routing (code repos **and** the hub). |
-| `skills/yad-review-comments/` | Install platform-matched PR/MR review-comment scaffolds (code repos and the hub). |
-| `skills/yad-hub-bridge/` | The templated PR/MR **review bridge**: open a review PR/MR on the hub and sync platform approvals/comments into the file ledger. |
-| `skills/yad-commit/` | Build helper: commit ONE staged atomic change by the conventions (Conventional subject, trailers, `--ai` footer, ≤3-file guard). |
-| `skills/yad-open-pr/` | Build helper: open a code-repo task PR/MR from the committed template (push, prefill, roster auto-assign). |
-| `skills/yad-ship/` | Build helper: commit **and** open the task PR/MR in one step (`yad commit` then `yad open-pr`). |
-| `skills/yad-engineer-review/` | Build Step E: AI review (advisory) → engineer review → merge + record in the build log. |
-| `skills/yad-backfill/` | Generate a human-verified spec for already-built code (Repomix), gated per touched feature. |
-| `skills/yad-run/` | Phase 4 orchestrator: drive a story's back half on the `automation` dial; kill switch. |
-| `skills/yad-status/` | Read-only view: front chain, build-half dials, trust record, fleet roll-up. |
-| `skills/yad-change/` | Phase 6: post-lock change/defect/hotfix **intake + triage** — seed a new epic threaded to its parent (inherit by reference, re-author only what changes). |
-| `skills/yad-timeline/` | Phase 6: render a feature **thread** as an evolution view + resolve its current truth (`thread-resolved.md`). |
-| `skills/yad-defects/` | Phase 6: per-epic/per-thread **quality-gap report** by `escape_stage` + `root_cause`. |
-| `skills/yad-reconcile/` | Phase 6: read-only **drift/orphan/debt sweep** across threads (mirrors `yad-docs-sync`; never a gate). |
-| `epics/EP-istifta-inquiries/` | A worked demo epic run **end to end** (front half + build half + automation + a Phase 6 change thread). |
-| `demo-repos/` | Throwaway code repos for the build half (separate git repos; regenerable — see `demo-repos/README.md`). |
-| `docs/` | The phased build plans (`phase-2`…`phase-6`) and the original workflow design. |
-| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Commit & PR/MR title convention (Conventional Commits, lowercase after the type). |
-## The `yad` CLI (install, update, reconcile)
-The module ships a zero-dependency CLI, published to npm as
-[`yadflow`](https://www.npmjs.com/package/yadflow). Run it
-with `npx` from your **product hub** repo — no clone needed.
-> **Platform support.** Linux and macOS are first-class — the test suite, the bash check gates, and
-> the end-to-end harness all run on both in CI. The CLI shells out to `git` (and the bash gate
-> scripts), so on **Windows use [WSL](https://learn.microsoft.com/windows/wsl/)**; native PowerShell
-> is not yet supported. Requires **Node.js ≥ 18**.
-| Command | What it does |
-|---------|--------------|
-| `npx yadflow setup` | Guided first-run wizard — a short **profile interview** (solo/team, greenfield/brownfield, monorepo/separate) then the branched steps below. Pre-answer for CI/scripts with `--solo`/`--team <n>`, `--greenfield`/`--brownfield`, `--monorepo`/`--separate`, `--tools`. |
-| `yad next [<epic>]` | **Where am I / what next.** With no epic: project-wide orientation — the one next action (run setup, start an epic, or the single active epic's step). With an epic: that epic's exact next action (a skill to invoke or a `yad` command to run). `yad next <epic> --check <step>` exits non-zero when a step is run out of order (the precondition guard); `yad next --all` lists every epic's next action. |
-| `npx yadflow check` | Read-only report: what is **missing** / **outdated** (drifted) / **stale** (code-context) / **legacy** (pre-2.0 `sdlc-*` names) vs the bundled manifest. |
-| `npx yadflow check --fix` | Reconcile: fill what is missing **and** update what changed — touches nothing already correct. |
-| `npx yadflow update` | Apply drift only (alias for `check --fix --scope=changed`). Also migrates a pre-2.0 install in place: `sdlc-*` skill copies and marker-owned `sdlc-*.yml` CI files are replaced by their `yad-*` names (a same-named file *you* authored is never touched). |
-| `npx yadflow doctor [--json]` | Environment + state health: tools on PATH and platform auth, config files parse and point at real repos, every epic ledger loads. Exit 1 on any failure; `--json` for CI and bug reports. |
-| `yad roster list` / `yad roster add <login>` | Manage the reviewer roster + per-repo roles **any time** (not just at setup). `add` upserts a member then walks each connected repo asking for their role; `grant`/`revoke <name> <repo> <role>` and `remove <login>` round it out. A `domain-owner` grant keeps `repos.json` `domain_owners` in sync. |
-| `yad gate open <epic> <artifact>` | Open the front-half **review PR/MR** for an artifact and mark the step `in_review`. |
-| `yad gate sync <epic> [artifact]` | Pull the PR/MR's reviews + comment threads into the file ledger; **auto-advance** the step when approvals are satisfied, all threads are resolved, and the PR is merged. |
-| `yad gate comments <epic> [artifact]` | Fetch the unresolved review comments to address (then reply on the PR; reviewers resolve their threads). |
-| `yad gate status <epic>` | Show each review step and its recorded approvals. |
-| `yad gate ci [--branch <head>] [--pr <n>]` | The CI entry the hub workflow calls on review/merge events: derive the epic/artifact from the `review/EP-*` branch, run the same sync, and commit **only the ledger** to the hub default branch (sweep every open review PR when no `--branch`). |
-| `yad commit --type <t> -m <subject>` | Commit by the SDLC convention — Conventional subject, `Task`/`Contract-Change`/`Co-Authored-By` trailers, atomic-file guard. |
-| `yad open-pr [--repo <name>]` | Open a **task** PR/MR from the platform template (build half). **Stage-aware on the hub:** a `review/EP-*` branch opens the front-half artifact-review PR (delegates to `yad gate open`); any other hub branch uses the code-task template (so hub tooling PRs pass the `pr-template` gate). |
-| `yad ship --type <t> -m <subject>` | Commit **and** open the task PR/MR in one step (`yad commit` then `yad open-pr`) — stage-aware, same as `open-pr`. |
-| `yad repo list` / `yad repo refresh [name]` | List connected repos as **fresh / stale**, and re-pack a stale one — staleness is now an explicit human decision, never an automatic skill side-effect. |
-| `yad repo sync [name]` | Switch every connected repo to its **default branch** and fast-forward it from origin (one or all). Dirty repos are skipped, never overwritten; fast-forward only. |
-| `yad thread [<epic>]` | **Feature threads (Phase 6).** No arg: list every thread. With an epic: show its thread (genesis → changes → defects), the **resolved current-truth** map (which epic owns each artifact now), and any open hotfix debt. `--json` for tooling. Read-only. |
-| `yad reconcile [check\|refresh\|wire]` | Sweep threads for **drift / orphans / open hotfix debt** and report which thread drifted and why (mirrors `yad docs sync`; advisory — the CI gates block at merge). |
-| `npx yadflow --version` | Print the installed CLI version. |
-Flags: `--dir <path>` targets a project other than the cwd; `--force` re-copies unchanged files (or
-bypasses the commit atomic guard). Commit flags: `--type`, `-m/--message`, `--task`, `--ai
-<claude\|copilot\|cursor\|coderabbit\|none>`, `--contract-change`, `--dry-run`. `open-pr` flags:
-`--repo`, `--risk <low\|medium\|high>`, `--contract-change`. `ship` takes the union of the `commit`
-and `open-pr` flags (it runs `open-pr` only if the commit lands).
-### The PR-driven review gate
-The front-half gate now rides the **PR/MR you open per step** (`yad gate open`). Reviewers approve and
-comment on the platform; `yad gate sync` maps that state into the file ledger (`approvals.json`,
-`comments.json`, `reviews/*.md`) — which stays the source of truth — and the step **auto-advances on
-merge** once three things hold: the reviewer rule is satisfied (owner + 1 reviewer, plus a domain-owner
-per touched repo on escalated steps), every comment thread is resolved, and the review PR/MR is merged.
-The merge click is the human approval act, so front steps still never `machine_advance`. Approvals are
-**revoked when the reviewed artifact actually changes** (re-hash), giving reviewers a fresh pass. With no
-hub platform / no `gh`/`glab`, the gate degrades to file-only with no error.
-**Solo mode.** A lone developer can't approve their own PR on GitHub, so an approval requirement would
-deadlock them. Opt in (`yad setup --solo`, recorded as `solo: true` in `.sdlc/hub.json`) and the gate
-**waives the approval requirement only** — the review PR/MR and its merge stay, so CI still runs on the
-PR and the **merge** advances the step. Net: the gate passes on *merged + all threads resolved*. It's a
-documented, reversible relaxation; `yad doctor` warns if branch protection still "requires approvals"
-(which would block the solo dev's own merge).
-**Event-driven sync.** Wire the hub once (`yad check --fix` installs `.github/workflows/yad-gate-sync.yml`,
-or the GitLab fragment + schedule) and every **approval, change request, and merge** on a review PR/MR
-triggers `yad gate ci` in the hub's own CI: the ledger updates land directly on the hub's default branch
-— no manual `yad gate sync` needed (it stays valid as the fallback). CI never approves and never merges;
-the human keeps the merge click. GitLab caveat: approvals are only picked up by the ~15-min scheduled
-sweep (GitLab fires no pipeline on approval) — details in `skills/yad-hub-bridge/references/bridge.md`.
-Concurrency caveat: on GitHub the workflow's `concurrency` group serializes runs repo-wide and every
-sync re-reads the full platform state, so racing reviewer events lose nothing. Outside that group —
-a manual `yad gate sync` racing CI, or GitLab pipelines — two simultaneous syncs serialize their
-*commits* via the rebase retry but each works from the state it read at start, so the rarer of two
-simultaneous advancements can be lost; the next event or scheduled sweep re-syncs and converges.
-### What `setup` walks you through (a guided, branching interview)
-Setup opens with a short **profile interview** — *solo or team (how many)? greenfield or brownfield?
-monorepo or separate repos?* — and the answers (recorded in `.sdlc/hub.json` as `solo` + `profile`)
-branch the rest so you only answer what your situation needs. Each step prints inline guidance (what it
-does / why / what to enter / what skipping means), and the step count adapts.
-0. **Profile** — the three questions above, plus "configure optional tools now?". Pre-answer for
-   CI/scripts with `--solo`/`--team <n>`, `--greenfield`/`--brownfield`, `--monorepo`/`--separate`, `--tools`.
-1. **Preflight** — confirm the hub is a git repo (offers `git init`); check `git`/`node`/`npx`.
-2. **Install the module** — copy all 31 `yad-*` skills into the IDE skill dirs you pick
-   (`.claude/`, `.agents/`, `.zencoder/`, `.opencode/`) and register `_bmad/sdlc/`.
-3. **Hub platform & roster** — detect GitHub/GitLab from the remote; record reviewers → `.sdlc/hub.json`.
-   **Solo skips the roster** (you review by merging your own PR). Edit the roster any time with `yad roster`.
-4. **Optional tools** — design (Figma/pencil), testing (Playwright/cypress/pytest), learning (DeepTutor).
-   Configure now, or **defer with one prompt** → all recorded as `none` (connect later with the
-   `yad-connect-*` skills; the MCPs/CLIs are confirmed there).
-5. **Connect code repos** — register repos into `.sdlc/repos.json`. **Monorepo** connects one repo and
-   skips domain-owner prompts; **greenfield** skips the Repomix pack (run `yad repo refresh` once it has code).
-6. **Wire each repo** — CI gates, PR/MR template, and review-comment scaffold.
-7. **AI review** — optionally write `.coderabbit.yaml`.
-8. **Done** — stamp `.sdlc/cli-version.json` and print a **profile-tailored next step** (brownfield →
-   `yad-backfill` first; everyone → `yad next` and your first epic via `yad-epic`).
-The deterministic file work runs automatically; the AI-only steps are handed to the Claude Code skills
-with a printed next-action. Re-run `… check --fix` any time the workflow updates — it never re-asks for
-input you already gave; re-running `setup` carries your profile forward.
-**Releases:** automated via semantic-release on merge to `main` (Conventional Commits → npm, with
-provenance). See [`RELEASING.md`](RELEASING.md).
-**Maintainers / no-CLI fallback:** the underlying copy is still a single script —
-`bash skills/sdlc/install.sh` — which the CLI's install step is a port of. The **source** stays in
-`skills/`, which a `bmad-method` update does not touch, so after any BMAD update just re-run the CLI
-(`… check --fix`) or the script.
-> **Releases are automated.** A `feat:`/`fix:` commit merged to `main` triggers
-> [semantic-release](https://semantic-release.gitbook.io/): it computes the version from the
-> [Conventional Commits](CONTRIBUTING.md), publishes to npm with build provenance (tokenless OIDC),
-> ships the `CHANGELOG.md` in the tarball, and cuts a GitHub release. No manual `npm publish`. See
-> [`RELEASING.md`](RELEASING.md).
-### Troubleshooting (`yad doctor` + error codes)
-When something is off, run `yad doctor` first — it checks the environment (git, gh/glab auth, node
-version), the project state (`.sdlc/*.json` parse and point at real repos), and every epic ledger,
-with a fix-it hint per finding. Failures carry stable, greppable codes, also printed by any failing
-`yad` command:
-| Code | Meaning | Fix |
-|------|---------|-----|
-| `YAD-ENV-001` | git is not installed or not on PATH | install git — every yad command needs it |
-| `YAD-ENV-002` | platform CLI (gh/glab) missing or not authenticated | install it and authenticate — `gh auth login` (GitHub) or `glab auth login` (GitLab); the gate degrades to file-only without it |
-| `YAD-ENV-003` | Node.js older than the supported range | install Node >= 18 |
-| `YAD-STATE-001` | a ledger/config JSON file exists but does not parse | fix the file or restore from git — never delete a ledger blindly |
-| `YAD-STATE-002` | a ledger/config file parses but has the wrong shape | fix the file or restore from git (the message names the field) |
-| `YAD-STATE-003` | a registered repo path is missing or not a git repo | fix the path in `.sdlc/repos.json` or re-connect the repo |
-| `YAD-CFG-001` | `hub.json` names an unknown platform | expected `github`, `gitlab`, or `null` — fix it or re-run `yad setup` |
-| `YAD-CFG-002` | `design.json` names an unknown design tool | expected one of `config.yaml` `design.tools` (e.g. `figma`, `pencil`), or `none` — fix it or re-run `yad setup` |
-| `YAD-CFG-003` | `testing.json` names an unknown testing tool | expected one of `config.yaml` `testing.tools` (e.g. `playwright`, `cypress`, `pytest`), or `none` — fix it or re-run `yad setup` |
-| `YAD-CFG-004` | `learning.json` names an unknown learning tool | expected one of `config.yaml` `learning.tools` (e.g. `deeptutor`), or `none` — fix it or re-run `yad setup` |
-Filing a bug? Attach `yad doctor --json` — it contains no secrets (names, paths, and check results only).
-## Agent skills (all 35)
-The CLI **installs and wires** the module; the skills below are the **agents you invoke by name** in your
-AI IDE (e.g. *“run `yad-epic`”*) to actually do the work. State lives in files you can also edit
-directly. Each skill stops at a gate and never auto-advances unless a step has *earned* automation.
-### Setup & code-awareness
-- **`yad-connect-repos`** — Connects code repos to the product hub so the front/"brain" phases are
-  code-aware. Registers N code repos (GitHub or GitLab, local-user auth, no stored tokens) into
-  `.sdlc/repos.json`, then caches an AI-readable picture of each — a compressed Repomix pack and a
-  lightweight code-map (existing endpoints/events/data-models/modules), secret-scanned. Idempotent and
-  refreshable; staleness tracked by HEAD sha.
-- **`yad-sync-repos`** — Brings every connected repo up to date in one shot: switches each repo in
-  `.sdlc/repos.json` to its `default_branch` and fast-forwards it from origin (local-user git, no stored
-  tokens). A working-tree-only maintenance op — never a gate, never writes the registry. A dirty repo is
-  skipped and reported (never overwritten); a diverged branch is left for manual resolution. Drives
-  `yad repo sync [name]`.
-- **`yad-connect-design`** — Connects a design tool (Figma-first, pluggable) so the UI step can
-  materialize the actual feature design (mobile screens / web pages) inside it, alongside the Markdown.
-  Records the tool + project/file references in `.sdlc/design.json` (local-user / MCP-session auth, no
-  stored tokens), detecting the design-tool MCP and degrading to markdown-only when absent. Idempotent
-  and refreshable; one connection per project.
-- **`yad-connect-testing`** — Connects a testing tool (Playwright-first, pluggable) so the test-cases
-  step can implement the actual automation tests inside it, alongside the Markdown. Records the tool +
-  project/suite references in `.sdlc/testing.json` (local-user / MCP-session auth, no stored tokens),
-  detecting the testing-tool MCP and degrading to artifacts-only when absent. Idempotent and
-  refreshable; one connection per project.
-- **`yad-connect-learning`** — Connects a learning/tutoring tool (DeepTutor-first, pluggable) so the
-  cross-cutting learning layer can tutor any team member in the context of what's being built. Records
-  the tool + an optional grounded knowledge base in `.sdlc/learning.json` (local-user auth, no stored
-  tokens), detecting the **DeepTutor CLI on PATH** (a subprocess like Repomix — DeepTutor ships no MCP)
-  and degrading to **harness-native** tutoring when absent. Idempotent and refreshable; one connection
-  per project.
-- **`yad-connect-docs`** — Connects a docs/Pages target (GitHub Pages / GitLab Pages, auto-detected from
-  `hub.json`) so the generated documentation sites can deploy. Records the target + scope + base path in
-  `.sdlc/docs.json` (local-user auth, no stored tokens), degrading to **build-only** when no Pages host /
-  CLI is present. Idempotent and refreshable; one connection per project.
-### Living documentation (generated, themed, auto-kept-fresh)
-- **`yad-docs`** — Generates an **interactive documentation site** for an epic (a React + Vite + Tailwind
-  SPA: an animated front-stage flow canvas + role-based stakeholder doc pages) from the authored
-  artifacts — `epic.md`, `architecture.md`, the locked `contract.md`, `ui-design.md`, the stories — into
-  `epics/EP-<slug>/docs-site/`, themed by the **connected design system** (`DESIGN.md` / `design.json`
-  tokens → the site's CSS). The content lives in generated `src/data/*.ts`; the shell is a vendored
-  template. An **output enrichment, never a gate** — it never touches epic state, approvals, or the
-  contract lock. `generate` / `refresh` / `deploy`.
-- **`yad-docs-overview`** — Generates the project **SDLC-overview site** (`docs/sdlc-site/`) — every
-  stage from setup → ship as flow paths / system components / stakeholder roles, reusing the same shell —
-  superseding the hand-maintained `docs/index.html` (folded into the site as `public/report.html`, linked
-  from the nav).
-- **`yad-docs-sync`** — Keeps the sites fresh: detects staleness (a content hash of the authored
-  artifacts + the connected repos' HEAD shas vs each site's build manifest), regenerates + redeploys, and
-  can wire a CI job that rebuilds on push. Generalizes the rule that feature work must hand-update the
-  docs — the overview now regenerates whenever the skill set / pipeline changes.
-### The learning layer (cross-cutting — any member, any stage)
-- **`yad-learn`** — At **any** SDLC stage, a team member can ask to learn a concept and be tutored *in
-  the context of what the team is building* — e.g. *"teach me why the architecture hash-locks the
-  contract surface"*. Routes the request to the connected learning tool (`.sdlc/learning.json`,
-  DeepTutor-first) grounded in the project knowledge base, or degrades to **harness-native** tutoring
-  (the harness model reading the artifacts) when nothing is connected — so it always works. Renders a
-  tutorial artifact and appends to a per-member **learning ledger** kept **local-only** (gitignored,
-  never committed or pushed — to the hub or any code repo) so it stays a private, personal **skills log**
-  (`yad-status` rolls up the local records). **Purely opt-in — it never blocks a gate** and
-  never touches epic state, approvals, or the contract lock. *AI builds, the hand decides* — and now the
-  hand can also learn, on demand, what it is deciding about.
-### Front-zero — frame the whole project (once per project, optional, human-gated)
-- **`yad-discovery`** — *Optional* front-zero, for **greenfield and brownfield**. With the analyst
-  and pm, run market research, a **competitor study** (both modes), a feasibility study, and — in
-  brownfield — a code-aware current-state study, then distil a **functional + non-functional
-  requirements** list and a **phased roadmap** (an explicit **MVP** phase, then later phases) under the
-  reserved `EP-discovery` ("epic zero"). It is gated by the same review gate (base rule: owner + 1
-  reviewer); on approval it terminates at `discovery-done` (no build half). Its `roadmap.md` is the menu
-  of features — each `yad-epic` reads it for project context (reference-only; discovery never
-  auto-seeds epics).
-### Front half — author the "thinking" (once per epic, human-gated)
-- **`yad-analysis`** — *Optional* front state 1. With the analyst, pressure-test a feature idea
-  and write the discovery brief into `analysis.md`. Assigns the `EP-<slug>` ID and seeds `.sdlc/` state
-  (the 12-step chain that puts analysis before epic). If skipped, the epic step does this shaping inline.
-- **`yad-epic`** — The epic front state. Shape the idea with the analyst (or read `analysis.md`
-  when it already ran), then write the epic with the pm into `epic.md`. The entry point when analysis is
-  skipped: assigns the `EP-<slug>` ID and seeds `.sdlc/` state.
-- **`yad-architecture`** — Front state 3. With the architect, author `architecture.md` and the
-  locked `contract.md` (the shared cross-repo surface), then hash-lock the contract surface into
-  `.sdlc/contract-lock.json`. Reads `epic.md`; escalates on the contract risk tag.
-- **`yad-ui`** — Front state 5. With the ux-designer, author `ui-design.md` and `DESIGN.md`,
-  driving Impeccable as harness slash-commands (document/extract/craft) when installed, or authoring
-  directly when not. When a design tool is connected (`yad-connect-design`), also **materializes the
-  feature design** — mobile screens / web pages — in the tool (generate or link), recording the
-  screen→frame map in `design-links.json`; degrades to markdown-only otherwise. Reads epic + architecture.
-- **`yad-stories`** — Front state 7. With the pm, break the approved epic into user stories, each
-  tagged with the repos that must implement it. Assigns zero-padded `EP-<slug>-S0N` IDs, one file per
-  story under `stories/`. Reads epic + architecture + contract + UI.
-- **`yad-test-cases`** — Front state 9, a **parallel, non-blocking** track: it opens when the stories
-  gate passes (the epic is already `ready-for-build`, so the build half runs alongside it). With the
-  test architect (Murat), author `test-cases.md` covering the approved stories (risk-based P0–P3 cases +
-  story→case traceability). When a testing tool is connected (`yad-connect-testing`), also **implements
-  the automation tests** in the connected code repo(s) (generate or link), recording the case→test map in
-  `test-links.json`; degrades to artifacts-only otherwise. Reads epic + architecture + contract + UI +
-  stories.
-### The review gate (cross-cutting — used by every review)
-- **`yad-review-gate`** — The reusable team review + approve gate. Shares an authored artifact, records
-  reviewer comments and approvals as files, enforces the **owner + 1 reviewer** rule (escalating to
-  domain owners on contract/auth/payments), and advances the epic state **only** when approval is
-  recorded.
-- **`yad-hub-bridge`** — The templated PR/MR bridge for the front-half gate. When the hub has a platform
-  (`.sdlc/hub.json`), it opens a review PR/MR per artifact, sets the required reviewers/labels, and
-  provides the read-only `gh`/`glab` recipes that sync platform comments + approvals back into the file
-  ledger. The file ledger stays the source of truth; degrades to a file-only gate with no platform.
-- **`yad-review-comments`** — Installs platform-matched PR/MR review-comment scaffolds so reviewers
-  leave structured, attributable feedback that maps cleanly into the file ledger.
+**Legend:** 🟨 **artifact** (a step writes a file and stops) · 🟧 **gate** (a human review that must
+pass) · 🟦 **earns automation** (a back step that can later auto-advance once it proves itself) ·
+⬜ **locked** (the engineer review and every front state — permanently human).
-### Build half — turn stories into shipped code (once per story, per repo)
+## Quickstart
-- **`yad-spec`** — Step A. For one ready-for-build story and one of its repos, run the Spec Kit ceremony
-  once (specify → clarify → plan → analyze → checklist → tasks) → `specs/<story-id>/`. Drives `/speckit.*`
-  when installed; references the locked contract — never re-invents the surface.
-- **`yad-implement`** — Step B. With the dev lens, implement **one** atomic task as a small diff
-  (≤3 files) on its own branch. The diff stays inside the files the task declared (flag and STOP if it
-  would grow). Commit ends with the task ID; `Contract-Change: yes` only if it touches the locked
-  contract surface.
-- **`yad-checks`** — Step C, the production-safety gates. Wire and run the CI gates: **spec-link**
-  (every change links a real story/spec), **contract-check** (a contract-surface diff without a
-  re-locked contract FAILS), **build/test/lint**, **verified-commits** (signed + roster-known authors),
-  and the **pattern gates** — **commit-message** (Conventional subject + trailer order), **pr-title**,
-  and **pr-template** (the PR/MR body uses the template). Profile-aware (`code`|`hub`), so they run on
-  both code repos and the product hub. CI-agnostic bash for GitHub Actions and GitLab CI.
-- **`yad-pr-template`** — Step D. Detect the repo's platform and commit the matching PR/MR template with
-  an Impact & Risk block; high risk (or a contract/auth/payments surface) routes the review to domain
-  owners. Includes `risk-route.sh` plus the `pr-title.sh` / `pr-template.sh` gate scripts.
-- **`yad-commit`** — build helper. Commit ONE staged atomic change by the conventions (Conventional
-  subject, `Task → Contract-Change → Co-Authored-By` trailers, the `--ai` co-author footer, the ≤3-file
-  atomic guard). Drives `yad commit`.
-- **`yad-open-pr`** — build helper. Open a code-repo task PR/MR from the committed template: push the
-  branch, prefill the body, auto-assign the repo-scoped roster. Drives `yad open-pr`.
-- **`yad-ship`** — build helper. Commit **and** open the task PR/MR in one step (`yad commit` then
-  `yad open-pr`; the PR step runs only if the commit lands). Drives `yad ship`.
-- **`yad-engineer-review`** — Step E. AI review (CodeRabbit, advisory) → engineer review (the human gate,
-  owner + 1 reviewer with the same escalation) → on merge, record the ship in the epic build-log and
-  update the story state so the epic → story → task → PR chain stays traceable.
-- **`yad-backfill`** — Step G. Generate specs for already-built features in an existing repo so new work
-  doesn't break them: pack one feature at a time with Repomix, write a DRAFT spec, require human approval
-  before it counts. A change is blocked only until the features it touches have approved specs.
+From your **product hub** repo (an empty git repo is fine):
-### Automation & status
-- **`yad-run`** — The Phase 4 orchestrator. Drives a story's back-half loop (spec → tasks → implement →
-  checks) on each step's automation dial, recording every run in the trust log. A clean `checks` pass
-  auto-advances to engineer-review; any failure, scope overrun, or contract-surface touch HALTS for a
-  human. Also sets a step's dial (gated by trust evidence) and flips the system-wide kill switch.
-- **`yad-status`** — Read-only view of an epic: the current step, each step's dials (assistance/
-  automation) and status, which approvals are still required, per-story back-half trust records, the
-  kill-switch state, and a fleet roll-up across epics.
-### Post-lock change management — feature threads (Phase 6)
-After the contract locks and code ships, a change must **not** mutate a locked artifact — it becomes a
-**new epic threaded to its parent**. A feature is a *thread* of linked epics (genesis → change → defect →
-…); a change-epic **inherits** the front artifacts it does not change (by reference) and **re-authors**
-only what it does. So artifacts never go stale — they are *superseded*; the feature's current truth is the
-head of the thread. This is what keeps the SDLC a trusted source of truth for AI on the next change.
-- **`yad-change`** — the intake + triage. Classifies the change *depth* (defect-fix /
-  behavioral-no-surface / contract-surface / new-capability), seeds a new `EP-<slug>` threaded to its
-  parent (lineage frontmatter, an inherited-step `state.json`, a pointer-lock `contract-lock.json`,
-  `change.json`), and for hotfixes opens `reconcile-debt.json`. Never auto-advances — hands off to the
-  normal authoring skills + the review gate.
-- **`yad-timeline`** — render the thread as an evolution view (yad-docs shell + `TIMELINE.md`) and emit
-  `thread-resolved.md`, the composed **current-truth map** (which epic owns each artifact now).
-- **`yad-defects`** — a per-epic/per-thread quality-gap report aggregating defects by **`escape_stage`**
-  (the gate that should have caught it) + `root_cause` — *where the SDLC leaks*, so the team hardens the
-  originating stage.
-- **`yad-reconcile`** — a read-only drift/orphan/debt sweep across threads (mirrors `yad-docs-sync`; never
-  a gate). The hard block is the CI gates.
-Three CI gates (in `yad-checks`) enforce it: **lineage-check** (a change links a real threaded epic),
-**epic-open** (a *sealed* epic — all stories shipped — refuses new behaviour, forcing a change-epic so the
-front artifacts can never go stale), and **reconcile-debt** (a thread with open hotfix debt is frozen
-until paid). Two read-only CLIs surface it: `yad thread <epic>` (the thread + resolved truth + open debt)
-and `yad reconcile` (the drift sweep).
-## The two dials (per step, build plan §2)
-- **assistance:** `none` | `review` | `heavy` — how much AI helps.
-- **automation:** `human_approve` | `machine_advance` — who advances the step.
-Defaults: every step starts `human_approve`. The four **front** authoring steps (epic, architecture,
-UI, stories) and their reviews are **locked** — they may not be set to `machine_advance` in this
-version. A front state advances only on a **human act** — recording an approval and `advance`, or
-merging the approved, fully-resolved review PR — never on a machine.
-As of **Phase 4a** the `automation` dial is no longer inert: the orchestrator `yad-run` reads it and,
-for the safe **back** steps, advances on its own when a step is set to `machine_advance` (and has
-*earned* it — see "Run the back half on the dial" below). The engineer review and all five front
-states stay `human_approve` forever.
-## Using the workflow end to end (all the steps, in order)
-This is the full path from nothing to shipped code. Each numbered step names the skill to invoke; the
-detailed sections below expand every phase. Invoke a skill by name in your agent/IDE (e.g. *“run
-`yad-epic`”*); state lives in files you can also edit directly.
-### 0 — One-time setup
-> **Shortcut:** `npx yadflow setup` runs the guided wizard interactively — module install, hub
-> detect + roster, connect a design/testing/learning tool (each optional), connect repos, wire each
-> repo. Run `… check --fix` any time afterwards to reconcile. The manual steps below are the
-> long-hand equivalent and still work.
-1. **Install the module:** `bash skills/sdlc/install.sh` (re-run after any BMAD update).
-2. **Have your code repo(s).** They are **separate git repos** (one `.git` each). For the demo they
-   live under `demo-repos/<repo>/` — regenerate from `demo-repos/README.md`.
-3. **Optional tools** (the workflow degrades gracefully and records it if any are absent): **Spec Kit**
-   (`/speckit.*`), **Impeccable** (`/impeccable …`), **Repomix** (`npx repomix`, used by
-   `yad-connect-repos` and `yad-backfill`), **CodeRabbit** (advisory AI review), **DeepTutor**
-   (`deeptutor`, the learning layer's tutor — degrades to harness-native, used by `yad-connect-learning`
-   and `yad-learn`).
-4. **Wire each code repo once:** `yad-checks repo:<repo> action: wire` (installs the CI gates —
-   *merges* with any existing CI, never clobbers), `yad-pr-template repo:<repo> action: wire` (PR/MR
-   template + risk routing), `yad-review-comments repo:<repo> action: wire` (review-comment scaffold).
-5. **Connect each code repo to the hub** (so the front phases see what's already built):
-   `yad-connect-repos action: connect repo:<repo> path:<path-or-git_url> domain_owner:<who>`. It
-   registers the repo in `.sdlc/repos.json` and caches a Repomix pack + a lightweight **code-map**
-   (existing endpoints/events/data-models/modules, secret-scanned). Clones/fetches as the **local user**
-   (SSH or credential helper; GitHub or GitLab; no stored tokens). Re-run for any new repo. Freshness is a
-   **human decision**: `yad repo list` shows fresh/stale, `yad repo refresh [name]` re-packs a moved repo
-   (skills flag staleness and point here — they never silently re-pack). Greenfield → skip it.
-6. **(Optional) Connect tools** so the matching steps do real work (each degrades gracefully and is
-   recorded if absent): `yad-connect-design action: connect` (Figma-first → `design.json`, lets
-   `yad-ui` materialize screens), `yad-connect-testing action: connect` (Playwright-first →
-   `testing.json`, lets `yad-test-cases` implement automation), `yad-connect-learning action: connect`
-   (DeepTutor-first → `learning.json`, powers the cross-cutting learning layer).
-7. **(Optional) Put the hub on a platform** so the front-half review runs through real PRs:
-   `yad-connect-repos action: detect-hub`, then `yad roster add <login>` once per reviewer (login →
-   SDLC name + per-repo roles — the `add` walk asks for each connected repo's role; `yad roster grant`
-   sets one directly), and `yad-pr-template repo:hub action: wire` / `yad-review-comments repo:hub
-   action: wire` / `yad-checks repo:hub action: wire`. With no hub platform the front gate runs file-only.
-8. **Conventions:** commits and PR/MR titles follow Conventional Commits (lowercase after the type), the
-   human author owns each commit with an optional per-commit `Co-Authored-By` AI trailer — see
-   [`CONTRIBUTING.md`](CONTRIBUTING.md).
-### A — Front half (human-authored, once per epic)
-Each author step writes its artifact, sets itself `done`, moves `currentStep` to its review, and
-**stops at the gate**. Run every gate with **`yad-review-gate`** — or, when the hub is on a platform,
-drive it deterministically with the **`yad gate`** CLI (`open → sync → … → merge`): the review rides
-the per-step PR/MR and the step **auto-advances on merge** once approvals are satisfied and all comment
-threads are resolved. Details: **“Run the full front half by hand”** below.
-0. *(optional, once per project)* `yad-discovery` → the discovery set (`market-research.md`,
-   `competitor-analysis.md`, `current-state.md`, `feasibility.md`, `requirements.md`, `roadmap.md`)
-   under the reserved `EP-discovery` → review (base rule) → `currentStep: discovery-done`. The whole
-   set is required to review; its `roadmap.md` then frames each epic below (read once it is approved).
-6. `yad-epic` → `epic.md` (assigns `EP-<slug>`, seeds state) → review (base rule).
-7. `yad-architecture` → `architecture.md` + locked `contract.md` → review (**escalated**: contract).
-8. `yad-ui` → `ui-design.md` + `DESIGN.md` → review (base rule).
-9. `yad-stories` → repo-tagged `stories/EP-<slug>-S0N.md` → review (**per-repo**).
-   → `state.json` reaches `currentStep: ready-for-build` — **the build half can start now.**
-10. `yad-test-cases` → `test-cases.md` (+ automation tests when a testing tool is connected) → review (base rule).
-    **Parallel, non-blocking:** opens when the stories gate passes and runs alongside the build half; its
-    review never moves `currentStep` off `ready-for-build`.
-### B — Build half (per story, per repo)
-From a `ready-for-build` story, for **each** repo the story is tagged with. Details: **“Run the full
-build half by hand”** below.
-10. `yad-spec story:<id> repo:<repo>` → writes `specs/<story-id>/` (spec/plan/tasks + `link.md`).
-11. `yad-implement story:<id> repo:<repo> task:<T0N>` → one atomic task = one branch = one commit
-    (repeat per task). Commit by convention with **`yad commit --type <t> -m <subject> [--ai <tool>]`**
-    (Task/Contract-Change/Co-Authored-By trailers, atomic-file guard).
-12. `yad-checks repo:<repo> action: run` → spec-link, contract-check, build/test/lint, verified-commits
-    (platform-Verified signature + roster-allowlisted author), and commit-message must pass. (The
-    `pr-title` / `pr-template` gates need the PR title + body, so they run in CI once the PR exists —
-    step 13.)
-13. Open the PR/MR from the wired template with **`yad open-pr --repo <repo> [--risk <level>]`** (or do
-    12+13 in one step with **`yad ship --type <t> -m <subject> --repo <repo>`**). The PR's CI now also
-    runs the `pr-title` and `pr-template` gates; `yad-pr-template repo:<repo> action: route` prints the
-    required reviewers from the Impact & Risk block.
-14. `yad-engineer-review` → `ai-review` (advisory) → `approve` (the human engineer gate) → `ship` (merge,
-    record in `build-log.json`, update story status to `in-build`/`shipped`).
-    - **Multi-repo:** repeat 10–14 in each repo, all from the **one** locked contract.
-    - **Existing code:** `yad-backfill` first, to produce a human-verified spec for a built feature.
-### C — Automation (optional, earned over time)
-15. After a back step accumulates trust evidence, earn it:
-    `yad-run action: set-dial step:<step> to: machine_advance` (refused if evidence is short or for a
-    front state / the engineer review).
-16. Drive a story's back half on the dials: `yad-run story:<id> repo:<repo>` — it auto-advances
-    earned steps and stops for a human otherwise, always halting at the engineer review.
-17. **Kill switch any time:** `yad-run action: kill` (everything → manual) / `action: unkill`.
-Details: **“Run the back half on the dial”** below.
-### Any time
-- **`yad-status [EP-<slug>]`** — read-only: the front chain, each build step's dial + status, the
-  trust record, and (across epics) the fleet roll-up. Start here to see what's blocking.
-## Run the full front half by hand
-Optionally preceded once per project by the **front-zero** — **`yad-discovery` → review →
-`discovery-done`** — which frames the whole product (market, competitor, feasibility, requirements,
-roadmap) under the reserved `EP-discovery`; its approved `roadmap.md` then feeds each epic. The front
-half itself walks **epic → review → architecture+contract → review → UI design → review → stories
-→ review → `ready-for-build`**, then **test cases → review** runs as a **parallel, non-blocking track**
-alongside the build half. It is all files under `epics/EP-<slug>/`. The skills below guide you, but you
-can also edit the files directly — that's the point.
-Each authoring step is the same shape: an author skill produces an artifact, sets its step `done`,
-moves `currentStep` to the matching review, and **stops at the gate**. Then **`yad-review-gate`**
-(one gate, reused for all five reviews) takes `open → comment → approve → advance`. When the hub is on a
-platform, the **`yad gate`** CLI runs that gate over a real PR/MR — `open` raises the review PR, `sync`
-pulls approvals + comment threads into the ledger, and the step **auto-advances when the approved,
-fully-resolved PR is merged** (the merge is the human approval act).
-**Code-aware (when repos are connected).** If you ran `yad-connect-repos` in setup, each author step
-first loads the connected repos' **code-maps** (from `.sdlc/code-context/<repo>/`) so it considers what
-already exists: the epic references existing behaviour, **the architecture cross-checks the contract
-surface against existing endpoints/events/entities before hash-locking it**, the UI reuses existing
-components, and stories anchor to real modules. Each artifact stamps what it read in its `code-context:`
-frontmatter; a repo that has moved since connect triggers a staleness warning — the step **flags it and
-stops**, pointing you at `yad repo refresh <repo>` (refreshing is a human decision, never an automatic
-side-effect). With no repos connected the steps proceed exactly as before (greenfield-safe).
-### Author steps
-1. **`yad-epic`** (state 1) → `epic.md`; assigns the stable `EP-<slug>` ID; seeds
-   `.sdlc/state.json` (all `human_approve`, front steps locked) + empty `.sdlc/approvals.json`.
-2. **`yad-architecture`** (state 3) → `architecture.md` + the locked `contract.md`; writes the
-   contract-surface SHA-256 to `.sdlc/contract-lock.json`.
-3. **`yad-ui`** (state 5) → `ui-design.md` + `DESIGN.md` (drives Impeccable
-   `document|extract|craft` slash-commands when installed; otherwise authors directly).
-4. **`yad-stories`** (state 7) → one file per story `stories/EP-<slug>-S0N.md`, each tagged
-   with the `repos` it implements.
-### The one gate (every review)
-Every review is the same loop — author writes, reviewers comment (which never advances), approvals
-accumulate, and the step moves forward only when the rule is met. **File-only** ends in an explicit
-`advance`; **PR-driven** (hub on a platform) ends when the approved, fully-resolved review PR is
-**merged**:
-<!-- Source: docs/diagrams/review-loop.mmd — edit the .mmd and run `npm run diagrams` to regenerate -->
-![Review gate loop — author, open, comment, approve, advance](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/review-loop.svg)
-**File-only** — invoke **`yad-review-gate`** with `open` (present the artifact; reviewers comment in
-`reviews/<artifact>--<date>--comments.md`), `approve` (name + role → `.sdlc/approvals.json`), and
-`advance` (moves **only if** the rule is satisfied, else it names the missing approval).
-**PR-driven** — when the hub is on a platform, the **`yad gate`** CLI runs the same gate over a PR/MR:
-- `yad gate open <epic> <artifact>` — raise the review PR/MR; mark the step `in_review`.
-- `yad gate sync <epic> [artifact]` — pull approvals + comment threads into the **same** ledger (your
-  own `gh`/`glab`, no stored tokens) and **auto-advance on merge** once the rule is met and every thread
-  is resolved. Approvals are **revoked when the reviewed artifact changes** (re-hash), so reviewers get
-  a fresh pass. Unresolved comments hold the step `in_review`.
-- `yad gate comments <epic>` fetches the open threads to address; `yad gate status <epic>` shows
-  approvals (counting only the non-stale ones). The file ledger stays the source of truth; with no
-  platform / no CLI it degrades to file-only.
-**The gate rule, by review:**
-- **Base** (epic, UI): `owner + 1 reviewer`.
-- **Escalated** (architecture+contract — `risk_tags: ["contract"]`): base **plus a domain owner for
-  every repo in `epic.repos`**. The contract-surface hash must still match `.sdlc/contract-lock.json`
-  (a changed surface invalidates approvals).
-- **Per-repo** (stories): base **plus a domain owner (the repo's engineer) for every repo that appears
-  in any story's `repos`**.
-### Check status anytime
-Invoke **`yad-status`** (read-only) to see the full 10-step chain, every step's dials/status, the
-contract lock, story repo tags, and which approvals the active gate still needs.
-## Worked example (already in this repo)
-`epics/EP-istifta-inquiries/` shows the **whole front half** walked end to end:
-- `epic.md` authored + approved (epic gate, base rule) — 2026-06-04.
-- `architecture.md` + `contract.md` authored; contract surface hash-locked in
-  `.sdlc/contract-lock.json`. Architecture gate **escalated** (contract): owner *alice* + reviewer
-  *bob* + domain owners *carol* (backend) and *dave* (mobile).
-- `ui-design.md` + `DESIGN.md` authored (Impeccable not installed → graceful fallback). UI gate base
-  rule (alice + bob).
-- Five repo-tagged stories `stories/EP-istifta-inquiries-S01..S05.md`. Stories gate **per-repo**: base
-  rule + a domain owner for each touched repo (carol/backend, dave/mobile).
-- `state.json` now reads `currentStep: ready-for-build`, every front step `done` — the Phase 3
-  handoff point.
-Inspect it:
 ```bash
-cat epics/EP-istifta-inquiries/.sdlc/state.json
-cat epics/EP-istifta-inquiries/.sdlc/approvals.json
-cat epics/EP-istifta-inquiries/.sdlc/contract-lock.json
-ls  epics/EP-istifta-inquiries/reviews/
-ls  epics/EP-istifta-inquiries/stories/
-# re-verify the contract surface still matches its lock:
-awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
-  epics/EP-istifta-inquiries/contract.md | shasum -a 256
+npx yadflow setup        # 1. guided wizard: install skills, connect repos, wire CI gates
 ```
-## Run the full build half by hand (Phase 3)
+Then, in your AI IDE, drive the lifecycle by invoking skills by name:
-From a `ready-for-build` story, the **build half** turns one atomic task into shipped code through
-gates that protect production. Per-repo specs live in each code repo; the contract stays singular in
-the product repo. Code repos are **separate git repos** under `demo-repos/<repo>/` (gitignored;
-`demo-repos/README.md` explains regeneration). **Nothing auto-advances** — every gate is human-owned.
-1. **Spec** — `yad-spec` runs the heavy Spec Kit ceremony **once per story per repo**
-   (`specify`→`clarify`→`plan`→`analyze`→`checklist`→`tasks`), writing `specs/<story-id>/` and a
-   `link.md` back to the story (drives `/speckit.*` when installed, else degrades). It **quotes** the
-   locked contract; it never widens it.
-2. **Implement** — `yad-implement` (the `dev` step): one atomic task = one branch
-   (`feat/<story>-<task>-…`) = one PR. The diff stays inside the files the task declared. Commit with
-   **`yad commit`** — it builds the conventional subject, derives the `Task:` trailer from the branch
-   (add `--contract-change` only if the locked surface is touched), appends an optional `--ai` co-author,
-   and refuses a non-atomic stage. Open the PR with **`yad open-pr --repo <repo>`** (template prefilled),
-   or do both in one step with **`yad ship`** (commit then open-pr).
-3. **Check gates** — `yad-checks` wires the CI gates (GitHub + GitLab) that must pass before merge:
-   **spec-link** (links a real story/spec), **contract-check** (a contract-surface change without
-   `Contract-Change` + a re-locked contract FAILS, routing back to the architecture gate),
-   **build/test/lint**, **verified-commits**, and the **pattern gates** **commit-message** / **pr-title**
-   / **pr-template** (profile-aware `code`|`hub`, so they also run on the product hub). They fail closed
-   on a bad base ref.
-4. **PR/MR template + risk routing** — `yad-pr-template` drops the platform-matched template with an
-   Impact & Risk block; `high` risk (or a contract/auth/payments surface) routes the review to domain
-   owners (`risk-route.sh`), the same escalation as the gate.
-5. **AI review → engineer review → merge** — `yad-engineer-review`: CodeRabbit is an advisory first pass
-   (never the authority); a human engineer approves (owner + 1 reviewer, escalating to domain owners); on
-   merge the ship is recorded in `.sdlc/build-log.json` and the story state becomes `in-build` →
-   `shipped`. The epic → story → task → PR → mergeCommit chain is traceable both ways.
+```text
+run yad-epic             # 2. author + gate the "thinking": epic → architecture → UI → stories
+run yad-spec   …         # 3. build half: spec → implement → checks → ship (per story, per repo)
+```
-**Multi-repo:** a story tagged `repos: [backend, mobile]` runs the above in each repo independently from
-the **one** locked contract; the contract-check blocks a surface bypass in either repo.
+Every step stops at a gate until a human approves. New here? **Walk it lesson-by-lesson in the
+[guided tutorial](https://abdelrahmannasr.github.io/yadflow/tutorial/)**, or read the
+[team guide](TEAM-GUIDE.md).
-**Backfill existing code:** `yad-backfill` packs one feature with **Repomix** (`npx repomix`, secret-scan
-by default), drafts an *unverified* spec ("describe what exists, do not invent"), a human approves it,
-and `backfill-check.sh` blocks a change to that feature until its spec is approved — gated per touched
-feature, never the whole repo.
+## How it works (in five points)
-The build half is walked end to end on the worked epic: story **S01** shipped (`status: shipped`,
-three tasks in `build-log.json`), **S03** built across backend + mobile, and a `health` feature
-backfilled. The code repos are regenerable from `demo-repos/README.md`.
+- **Front half = decide.** Once per epic, in the product hub: epic, architecture + a locked contract,
+  UI, stories, test cases. Always human-gated — nothing auto-advances.
+- **Build half = build.** Once per story per code repo: spec → implement → checks → ship.
+- **Every step stops at a gate.** A human moves it forward (file-only, or by merging a review PR/MR).
+- **Automation is opt-in and earned.** A safe back-half step can earn auto-advance after it proves
+  itself — and a one-command kill switch reverts everything to manual. The engineer review and all
+  front states are never automatable.
+- **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.
-## Run the back half on the dial (Phase 4 — automation, earned)
+## Who it's for
-Phase 4 is **automation, earned with evidence and reversible in one move**. Phase 4a made the
-`automation` dial real and earned the safest step (the check-gate advance); Phase 4b added the
-`implement → check` hand-off and the `spec`/`tasks` trust hooks. The engine is `yad-run`; the
-evidence lives in two new files per epic under `.sdlc/`: `build-state/<story-id>.json` (the back steps
-with their dials, per repo) and `trust-log.json` (every run's verdict). See
-`docs/phase-4-build-plan.md` and `docs/phase-4b-build-plan.md`.
+Tech leads and engineering managers who want their team to move fast with AI **without** giving up
+review, architectural control, or an audit trail — the governance layer around AI-assisted
+development, not another code generator.
-- **Drive a story's back half:** `yad-run {story} {repo}` walks `spec → tasks → implement → checks`,
-  reading each step's dial. On `machine_advance` it advances on its own; on `human_approve` it stops
-  for a human; on any FAIL, scope overrun, or contract-surface touch it **halts and pulls in a human**.
-  It always stops at the engineer review (`yad-engineer-review`), which is never automated.
-- **Read the trust log:** `yad-status {epic}` shows each back step's dial, status, and trust record —
-  runs, % `approved-unchanged`, and whether that clears the threshold (`automation.trust_threshold` in
-  `config.yaml`, default ≥5 runs and ≥80% unchanged). The engineer review records each run's verdict
-  (a diff merged as-authored is `approved-unchanged`; one edited first is `approved-with-edits`; a
-  failed one is `rejected`).
-- **Earn automation for a step:** once a step's trust record clears the threshold,
-  `yad-run action: set-dial step: checks to: machine_advance` flips it. The setter **refuses** if the
-  evidence is short, or for any front state / the engineer review. Reverting
-  (`to: human_approve`) is always allowed — automation is reversible in one move.
-- **Kill switch:** `yad-run action: kill` forces every step back to `human_approve` system-wide
-  instantly (no code change, no per-step edits); `yad-run action: unkill` restores earned automation.
+## Documentation
-**Earned so far:** `checks` (Step B, Phase 4a) and `implement` (Step D, Phase 4b — the
-`implement → check` hand-off; the scope/contract halts and the engineer review still gate the merge).
-`tasks` (Step C) and `spec` have their dials + trust hooks but stay `human_approve` until their own
-runs clear the threshold — there is no historical signal to seed them from, so they are earned only on
-genuine runs (never fabricated). See `docs/phase-4b-build-plan.md`.
+- **[Guided tutorial](https://abdelrahmannasr.github.io/yadflow/tutorial/)** — learn by doing, setup → first shipped feature.
+- **[Terminology & workflow report](https://abdelrahmannasr.github.io/yadflow/)** — every term, artifact, gate, and skill on one illustrated page.
+- **[TEAM-GUIDE.md](TEAM-GUIDE.md)** — the short, plain-language version for a developer team.
+- **[docs/CLI.md](docs/CLI.md)** — the full `yad` command reference, the PR-driven gate, and `yad doctor` codes.
+- **[docs/SKILLS.md](docs/SKILLS.md)** — the catalogue of all 35 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)**
-## What's intentionally NOT built yet
+---
-**Phase 4b Step C** (the remaining automation): `tasks` generation advance — gated until real
-`tasks`/`spec` trust evidence accrues. The hook that records that evidence is built; the dial flips
-only once the threshold is genuinely met. The scope guard and contract-surface halt always override
-the dial, and **front states and the engineer review stay `human_approve`, permanently.**
+**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**.
-**Phase 5 (conditional):** the optional service layer (watch repos, run earned-automation steps
-unattended, read-only dashboards), built only when the CLI genuinely can't keep up, with git remaining
-the source of truth. It is **trigger-gated** — `docs/phase-5-build-plan.md` is the build plan: its
-three parts (read-index, unattended runner, dashboard) each ship only when *their* bottleneck is
-measured, with the hard rules they inherit and the instrumentation (already shipped in `yad-status`)
-that makes the decision data-driven. See also `docs/claude-code-build-plan.md` §8.
+**Releases** are automated via [semantic-release](https://semantic-release.gitbook.io/) on merge to
+`main` (Conventional Commits → npm, with provenance). See [RELEASING.md](RELEASING.md).

package/cli/docs.mjs CHANGED Viewed

@@ -121,6 +121,7 @@ export function docsStale(manifest, { artifactHash, repoHeads = {}, templateVers
 const BUILD_PUBLIC = [
   'mkdir -p public',
   'if [ -d docs/sdlc-site ]; then (cd docs/sdlc-site && npm ci && npm run build) && mkdir -p public/app && cp -r docs/sdlc-site/dist/. public/app/ && cp docs/sdlc-site/public/report.html public/index.html && cp docs/sdlc-site/public/report.html public/report.html; fi',
+  'if [ -d docs/tutorial-site ]; then (cd docs/tutorial-site && npm ci && npm run build) && mkdir -p public/tutorial && cp -r docs/tutorial-site/dist/. public/tutorial/; fi',
   'for d in epics/*/docs-site; do [ -d "$d" ] || continue; id=$(basename "$(dirname "$d")"); (cd "$d" && npm ci && npm run build) && mkdir -p "public/epics/$id" && cp -r "$d/dist/." "public/epics/$id/"; done',
 ];
 export function pagesWorkflow(platform) {
@@ -160,19 +161,19 @@ jobs:
       name: github-pages
       url: \${{ steps.deployment.outputs.page_url }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v6
         with:
           node-version: 20
       - name: Build the overview + per-epic sites into ./public
         run: |
 ${BUILD_PUBLIC.map((l) => `          ${l}`).join('\n')}
-      - uses: actions/configure-pages@v5
-      - uses: actions/upload-pages-artifact@v3
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
         with:
           path: public
       - id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5
 `;
 }
 export function pagesWorkflowPath(platform) {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "2.18.0",
+  "version": "2.18.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 + 35 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/yad-docs-overview/SKILL.md CHANGED Viewed

@@ -56,7 +56,7 @@ git work tree). Generate and commit on it.
 Map the pipeline onto the same data structures `yad-docs` uses (concrete mapping in
 `references/pipeline-model.md`):
-- **Flow paths** = the **phases** — `Setup`, `Front half`, `Build half`, `Automation`.
+- **Flow paths** = the **phases** — `Setup`, `Front-zero` (discovery), `Front half`, `Build half`, `Automation`, `Change management` (feature threads).
 - **Flow steps** = the **skills/gates in order** (from `module-help.csv` `preceded-by`/`followed-by`),
   each step's `messages` = the skill's `outputs`, and `sideEffects` = the `.sdlc/` files it writes.
 - **System components** = the **durable state objects** — the product hub, each `.sdlc/*.json`

package/skills/yad-docs-overview/references/pipeline-model.md CHANGED Viewed

@@ -10,7 +10,7 @@ ordering source of truth is `skills/sdlc/module-help.csv` (`phase`, `preceded-by
 | Shell primitive | Overview meaning |
 |-----------------|------------------|
-| `FlowPath` (`paths.ts`) | a **phase**: Setup, Front half, Build half, Automation. |
+| `FlowPath` (`paths.ts`) | a **phase**: Setup, Front-zero (discovery), Front half, Build half, Automation, Change management (feature threads). |
 | `FlowStep` (within a path) | a **skill or gate** in order; `messages` = its `outputs`; `sideEffects` = the `.sdlc/` files it writes; `status`/`bookingStatus` annotate gated vs. enrichment vs. earned. |
 | `SystemComponent` (`components.ts`) | a **durable state object** (the hub, each `.sdlc/*.json`, code repos, the design/testing/learning tools, the platform). |
 | `RoleConfig` (`roles.ts`) | a **lens** → its relevant sections + paths. |
@@ -66,7 +66,7 @@ Per-story, per-repo: `spec → tasks → implement → checks → engineer-revie
 |--------------|------------------------|
 | `yad-spec` | `specs/<story-id>/` (Spec Kit layout), `link.md` |
 | `yad-implement` | a branch + commit per atomic task |
-| `yad-checks` | `checks/*.sh`, CI workflows |
+| `yad-checks` | `checks/*.sh`, CI workflows — the gate set: `spec-link · contract-check · build-test-lint · verified-commits · commit-message · pr-title · pr-template · lineage-check · epic-open · reconcile-debt` |
 | `yad-pr-template` | PR/MR template + routing helpers |
 | `yad-commit` / `yad-open-pr` / `yad-ship` | one commit / one PR/MR |
 | `yad-engineer-review` | engineer review + ship recorded in `build-log.json` |
@@ -83,11 +83,30 @@ node classes from the diagram.
 | `yad-status` | read-only view (no writes) |
 | `yad-docs` / `yad-docs-overview` / `yad-docs-sync` | the docs sites + their `docs-build.json` manifests |
+### Path: Change management — feature threads (`phase: 6-change`)
+The post-lock evolution layer. Once an epic is **sealed** (all stories shipped), behaviour can no longer
+be mutated in place — a change request becomes a **new epic threaded to its parent** (genesis → change →
+defect), inheriting unchanged front artifacts **by reference** and re-authoring only what changes, so
+locked artifacts are never mutated and never go stale, only superseded. Three CI gates enforce the thread
+(`lineage-check`, `epic-open`, `reconcile-debt`). This path never gates the front chain; `yad-change` is
+the intake, then it hands off to the normal authoring skills + the review gate.
+| Step (skill) | Outputs / sideEffects |
+|--------------|------------------------|
+| `yad-change` | intake + triage depth (defect-fix / behavioral-no-surface / contract-surface / new-capability); seeds a threaded change-epic — lineage frontmatter, inherited-step `state.json`, pointer-lock `contract-lock.json`, `change.json`, and `reconcile-debt.json` for hotfixes |
+| `yad-timeline` | `TIMELINE.md` (the thread evolution view) + `thread-resolved.md` (the resolved current truth) |
+| `yad-defects` | `DEFECTS.md` (quality-gap report by `escape_stage` + root cause) |
+| `yad-reconcile` | advisory drift / orphan / debt sweep (read-only; mirrors `yad-docs-sync`) |
+CLI: `yad thread [<epic>]` prints a thread + its resolved current truth + open debt; `yad reconcile`
+runs the sweep. The three thread gates ride in the build-half `yad-checks` set above.
 ## System components = the durable state objects
 `components.ts` renders these on the canvas (deterministic positions): the **product hub**; each
 `.sdlc/*.json` (`state.json`, `approvals.json`, `comments.json`, `hub.json`, `repos.json`, `design.json`,
-`testing.json`, `learning.json`, `docs.json`, `contract-lock.json`, `build-state/*`, `trust-log.json`);
+`testing.json`, `learning.json`, `docs.json`, `contract-lock.json`, `build-state/*`, `trust-log.json`,
+and the change-thread ledgers `change.json`, `reconcile-debt.json`, `build-log.json`);
 the **connected code repos**; the **design / testing / learning tools**; and the **platform**
 (GitHub/GitLab + Pages). A skill's `sideEffects` link its step to the component it writes.