yadflow 3.18.1 → 4.0.0-next.1

package/skills/yad-discovery/SKILL.md

@@ -1,134 +1,170 @@
 ---
 name: yad-discovery
-description: 'Optional front-zero of the gated SDLC — the once-per-project discovery phase. With the field-expert lenses (analyst + pm), run market research, a competitor study, a feasibility study, and (brownfield) a current-state study, then distil a functional + non-functional requirements list and a phased roadmap (MVP and beyond) into the reserved EP-discovery. Greenfield AND brownfield. Its roadmap.md becomes the menu of features each yad-epic reads. Seeds the EP-discovery state and hands off to the team review gate; never auto-advances. Use when the user says "start the project", "do discovery", "market research / feasibility / roadmap", or "what should we build first".'
+description: 'The Foundation step of the gated SDLC — the Product level, run once per product before any feature epic. With the field-expert lenses (analyst + pm), frame the product and write the Foundation sections into foundation/ — purpose, market (optional), scope (what it is AND what it is not), MVP, roadmap, stack, repos, risks (optional). Greenfield AND brownfield (brownfield reads the connected code). The engine seeds the ledger with `yad foundation new`; this skill authors the sections, then hands off to the team review gate and never auto-advances. Its roadmap.md is the menu of features each yad-epic reads. Use when the user says "start the project", "write the Foundation", "do discovery", "market research / feasibility / roadmap", or "what should we build first".'
 ---
 
-# SDLC — Project Discovery (optional front-zero, "epic zero")
+# SDLC — Foundation (the Product level)
 
-**Goal:** Produce a human-authored, AI-assisted **project-level discovery set** — the field expert's
-requirement-gathering for the whole product — under the reserved `EP-discovery` ("epic zero"), then
-hand off to `yad-review-gate`. The output `roadmap.md` is the menu of features; each feature is later
-taken into the normal `yad-epic` flow, which reads the roadmap for project context.
+**Goal:** Produce a human-authored, AI-assisted **Foundation** for the whole product under
+`{project-root}/foundation/`, then hand off to `yad-review-gate`. The Foundation says why the product
+exists, what it is and is not, the smallest thing worth shipping, and the rough order after that. Its
+`roadmap.md` is the menu of features; each feature is later taken into the normal `yad-epic` flow,
+which reads it for project context.
 
-This is a **front state**: human-authored with AI assist and **never auto-advances**. It runs **once
-per project** and is **optional** — a team that already knows what to build can skip it and start at
-`yad-epic`. It supports **both greenfield and brownfield**, and produces a **competitor study in both**.
+**What the Foundation is.** The roadmap (`docs/roadmap-idea-1.md`, Part 1) has two levels. The
+**Product** level runs once per product and holds the Foundation. The **Feature** level runs once per
+epic and walks the six phases. The Foundation has its own gate: one approval before feature work
+begins. That approval is **reported, not enforced** in this release — `yad next` says when feature
+epics are going ahead of an unapproved Foundation, and nothing is blocked.
 
-This skill enforces the build plan's core rules: all state lives in files; IDs are engine-assigned
-(the reserved `EP-discovery`, never a typed feature slug); front steps are locked to `human_approve`.
+This is a **Shape step**: human-authored with AI assist and **never auto-advances**. It is
+**optional** — a team that already knows what to build can start at `yad-epic`. It supports **both
+greenfield and brownfield**.
+
+The skill keeps its old name, `yad-discovery`. Before E75 it wrote a different set of files under the
+reserved `EP-discovery` epic; that older spelling is still read (see Step 1).
 
 ## Conventions
 
 - `{project-root}` resolves from the project working directory.
-- Discovery artifacts live under `{project-root}/epics/EP-discovery/` (the reserved "epic zero").
-- Speak in the configured `communication_language`; write documents in `document_output_language`.
+- The Foundation lives in `{project-root}/foundation/`: its sections directly inside it, its ledger in
+  `foundation/.sdlc/`, and its review summaries in `foundation/reviews/`. Its fixed id is
+  `EP-foundation` — every `yad` command takes that id.
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.
 
 ## On Activation
 
-### Step 1 — Entry guard (runs once per project)
-The id is the reserved `EP-discovery` — never a feature slug. Discovery seeds its state exactly once:
-if `{project-root}/epics/EP-discovery/.sdlc/state.json` already exists, **STOP** and point the user at
-`yad next EP-discovery` (the phase is in review or done; edit the artifacts in place, don't re-seed).
-When no `state.json` exists yet, proceed and seed state in Step 5.
+### Step 1 — Entry guard (one Foundation per product)
+- If `{project-root}/foundation/.sdlc/state.json` already exists, **STOP** and point the user at
+  `yad next EP-foundation`. The Foundation is already seeded; edit its sections in place.
+- If `{project-root}/epics/EP-discovery/.sdlc/state.json` exists, this product already has its Product
+  level **in the old spelling**. A product has ONE Foundation, so do not seed a second. **STOP** and tell
+  the user:
+  - on a **local** ledger, `yad migrate` (preview) then `yad migrate --apply` converts it into
+    `foundation/`, keeping its files and approvals;
+  - on a **verified** ledger CI owns that ledger and it cannot be moved by hand — keep working in
+    `epics/EP-discovery/`, and review it with `yad gate open EP-discovery discovery/`.
 
 Detect the project mode from `{project-root}/.sdlc/hub.json` `profile.codebase`
 (`greenfield` | `brownfield`, set by `yad setup`). If absent, ask the user; default `greenfield`.
 
 ### Step 2 — Shape with the field-expert lenses (assist: analyst + pm)
-Adopt the **analyst** lens (`bmad-agent-analyst`, Mary) and the **pm** lens (`bmad-agent-pm`) to gather
-requirements as a domain expert would. Drive the existing BMAD research skills as the assist — they
-already exist in this project:
-- `bmad-market-research` — market size, segments, demand, trends, positioning.
-- `bmad-domain-research` — the problem domain, regulations, and constraints of the field.
-- `bmad-product-brief` — personas, value proposition, success metrics.
-
-Pressure-test: who are the users, what problem, what is the market, **who are the competitors and how
-do we differ** (required in BOTH modes), what is feasible, what is the smallest valuable slice (MVP),
-and what sequences after it.
-
-### Step 2b — Brownfield current-state (make discovery code-aware)
+Adopt the **analyst** lens and the **pm** lens to frame the product as a domain expert would. Research:
+- **Market** — market size, segments, demand, trends, positioning.
+- **Domain** — the problem domain, regulations, and constraints of the field.
+- **Product brief** — the users it serves, the value proposition, success metrics.
+
+Pressure-test: who is this for and why does it exist, what does success look like, who else does this
+and why us, **what it is and explicitly what it is not**, what the smallest valuable slice is, what
+sequences after it, what it is built with, and what could kill it.
+
+### Step 2a — Greenfield: write the Foundation with the user, one section at a time
+On a **greenfield** product nothing is built yet, so every section comes from the user's answers. For
+each section, `references/foundation-schema.md` gives the template, the questions to **Ask**, what **a
+good answer** holds, what **the reviewer checks**, and a short example.
+
+Work in this order, because each section is the input to the next:
+
+1. `purpose.md` — why it exists, who for, how success is measured.
+2. `scope.md` — what it is, and at least three things it is **not**.
+3. `mvp.md` — the smallest set of capabilities that reaches the first success signal.
+4. `roadmap.md` — Phase 1 is exactly the MVP, one row per feature; later phases in a stated order.
+5. `stack.md` — for each choice: the decision, the alternatives rejected, and why.
+6. `repos.md` — the layout and one row per intended repo; they need not exist yet.
+7. `market.md` and `risks.md` — only if the user wants them. Both are optional.
+
+For each section:
+- Ask the questions **one at a time**. Write down the user's answer, not your own guess. When an answer is
+  vague ("everyone", "fast", "not bloated"), ask again for something concrete.
+- Draft the section's text, show it to the user, and change it until they agree. Then move to the next
+  one. The agreed text is written into `foundation/` in Step 5, once the authoring branch (Step 3) and the
+  ledger (Step 4) exist — never onto whatever branch happens to be checked out.
+- Check it against the sections before it: the MVP must not contradict a non-goal in `scope.md`, and
+  Phase 1 of the roadmap must match `mvp.md`.
+
+Keep examples inside `<!-- comments -->`. A section holding only its headings, comments and an empty table
+is **not written**, and the gate warns about it (Step 5) — but a filled example row counts as content.
+
+### Step 2b — Brownfield: read what already exists
 Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **every
 connected repo**, load the lightweight code-map `{project-root}/.sdlc/code-context/<repo>/code-map.md`
-and base `current-state.md` on **what already exists** — modules, endpoints, data, gaps — so the
-roadmap extends the real system rather than re-proposing it.
+and base `stack.md` and `repos.md` on **what already exists** — languages, frameworks, modules,
+endpoints, data — so the Foundation describes the real system rather than re-proposing it.
 
-- **Greenfield-safe:** if `repos.json` is absent/empty (greenfield), `current-state.md` is a short
-  "clean slate / assumptions & non-goals" note, and you proceed.
+- **Greenfield-safe:** if `repos.json` is absent or empty, there is nothing to read — write every
+  section with the user as in Step 2a, where `stack.md` and `repos.md` record the intended choices, the
+  alternatives rejected, and why.
 - **Staleness:** if a repo's current HEAD (`git -C <path> rev-parse HEAD`) ≠ its registry `syncedHead`,
   warn and suggest `yad repo refresh <repo>` (a human decision — flag, never auto-refresh).
 - **Backfill pointer:** for an existing codebase, point the user at `yad-backfill` to capture specs for
-  already-built features; discovery frames the *forward* roadmap, backfill captures the *current* one.
+  already-built features; the Foundation frames the *product*, backfill captures the *features*.
 
 ### Step 3 — Open the authoring branch
-Open the discovery authoring branch `discovery/EP-discovery` per the shared procedure
+Open the Foundation authoring branch `foundation/EP-foundation` per the shared procedure
 (`../yad-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if
 `{project-root}` is not a git work tree), check out the branch if it exists, else create it from the
-hub's default branch. Author and commit the discovery set on it. Distinct from the bridge's
-`review/EP-discovery/discovery` branch.
-
-### Step 4 — Write the discovery set
-Write these files under `{project-root}/epics/EP-discovery/`. Each is a normal Markdown artifact; the
-gate binds to the **whole set** (editing any one revokes approvals). `roadmap.md` summarises and links
-the others and is the spine of the review.
-
-- `market-research.md` — market, segments, demand, trends (assist: `bmad-market-research`).
-- `competitor-analysis.md` — competitors, capabilities, gaps, our differentiation (**both modes**).
-- `current-state.md` — brownfield: what exists today (Step 2b); greenfield: clean-slate assumptions.
-- `feasibility.md` — technical/operational/economic feasibility, risks, viability, go/no-go.
-- `requirements.md` — the consolidated requirements list, **functional AND non-functional**, as a
-  table (see `references/discovery-schema.md`). Functional rows are candidate features (registration,
-  login, …); non-functional rows are cross-cutting (performance, security, accessibility, i18n …).
-- `roadmap.md` — the phased plan with an explicit **MVP** phase, then later phases. Each feature row
-  carries a proposed `EP-<slug>` id, its target phase, and a `status:` of `planned`
-  (see `references/discovery-schema.md` for the exact templates).
+Product's default branch. Author and commit the Foundation on it. Distinct from the verified ledger's
+`review/EP-foundation/foundation` branch.
 
-Leave `owner` for the user to set in each frontmatter. Fill the bodies with the user.
+### Step 4 — Seed the ledger with the engine
+Run:
 
-### Step 5 — Seed the state machine
-Create `{project-root}/epics/EP-discovery/.sdlc/state.json` describing the **2-step** front-zero
-sequence, both steps `automation: human_approve` and `locked`, with the `kind: "discovery"` marker the
-engine keys off. Use this exact shape (see `references/discovery-schema.md`):
-
-```json
-{
-  "epicId": "EP-discovery",
-  "kind": "discovery",
-  "createdAt": "<YYYY-MM-DD>",
-  "currentStep": "discovery-review",
-  "steps": [
-    { "id": "discovery",        "type": "author",         "artifact": "discovery/", "assistance": "review", "automation": "human_approve", "locked": true, "status": "done",      "risk_tags": [] },
-    { "id": "discovery-review", "type": "review+approve", "artifact": "discovery/", "assistance": "review", "automation": "human_approve", "locked": true, "status": "in_review", "risk_tags": [] }
-  ]
-}
+```
+yad foundation new
 ```
 
-Notes:
-- The review step's artifact is the virtual base `discovery/` — the gate fingerprints the whole
-  discovery file set (`market-research`, `competitor-analysis`, `current-state`, `feasibility`,
-  `requirements`, `roadmap`), so editing any of them revokes prior approvals (mirrors `stories/`).
-  **All six must exist to review:** if any is missing the set is incomplete and non-reviewable (the
-  hash is `null`) and `yad gate open`/`sync` warn — so write all six (Step 4) before the gate.
-- `discovery-review` carries no `risk_tags` — it is the **base** rule (owner + 1 reviewer); discovery
-  never escalates to domain owners (no contract surface is touched yet).
-- Also create an empty approvals ledger `.sdlc/approvals.json` and comments ledger
-  `.sdlc/comments.json`, each containing `[]`, and the `reviews/` directory.
-- Commit the seed on the `discovery/EP-discovery` branch, and cut `review/EP-discovery/discovery` from
-  it so the **first** review PR/MR carries the ledger to the default branch. In bridge mode
-  `ledger-guard` exempts a new epic's ledger (creation, not mutation, #162); every later change to it
-  is CI's. See `../yad-epic/references/state-schema.md`, "Authoring branches".
+That writes `foundation/.sdlc/state.json` with the Foundation's two-step chain (`foundation` →
+`foundation-review`), an empty `approvals.json` and `comments.json`, and the `foundation/reviews/`
+folder. The engine owns that file: do not write or edit it by hand. The command refuses a second
+Foundation and a product still on the old spelling (Step 1 already stopped for both).
+
+### Step 5 — Write the Foundation sections
+Write these files directly in `{project-root}/foundation/`, one per section, using the templates in
+`references/foundation-schema.md` for their headings. The bodies are the text already agreed with the
+user — on greenfield, the sections drafted in Step 2a; on brownfield, what Step 2b read from the
+code-maps. Do not start a section over from its blank template. The gate binds to the **whole set**: editing any section revokes
+approvals. (The frontmatter `status:` line does not count — the gate rewrites it after the review.)
+
+| File | Section | Required? |
+|---|---|---|
+| `purpose.md` | Why this exists, who it is for, what success looks like | required |
+| `market.md` | Who else does this, and why us | optional |
+| `scope.md` | What it is — **and explicitly what it is not** | required |
+| `mvp.md` | The smallest thing worth shipping | required |
+| `roadmap.md` | The rough order after the MVP — the menu of feature epics | required |
+| `stack.md` | Languages, frameworks, hosting, databases | required |
+| `repos.md` | How many repos, what each does, monorepo or separate | required |
+| `risks.md` | What could kill this | optional |
+
+**All six required sections must exist to review.** Until they do, the Foundation has no fingerprint to
+bind an approval to, and `yad gate open` warns. An optional section counts once it exists — adding or
+removing one after an approval revokes it, like any other edit.
+
+**Every section that exists must also be written.** A section that still holds only its template — the
+frontmatter, `#` and `##` headings, comments, `---` dividers and an empty table — makes `yad gate open` and `yad gate sync` warn
+`Foundation not written yet`, and once the review has opened or passed `yad doctor` reports it as
+`foundation:unwritten`. These are warnings, not refusals: finish the section before asking for review.
+
+Leave `owner` for the user to set in each frontmatter. Fill the bodies with the user.
 
 ### Step 6 — Stop at the gate (do NOT advance)
-Report: the path to the discovery set, and that the next action is **review** via `yad-review-gate`
-(base rule: owner + 1 reviewer) on the virtual artifact `discovery/`. **Never mark discovery-review
-approved here** — only real reviewers do that through the gate. When the discovery gate passes, the
-state moves to the `discovery-done` sentinel (not `ready-for-build` — discovery has no build half); the
-roadmap is now the input that each `yad-epic` reads (its "Step 2c — read the roadmap"). When the hub
-has a platform, the gate opens a review PR on the hub (via `yad-hub-bridge`) and
-`yad-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review
-is recorded file-only.
+Report the path to the Foundation, and that the next action is **review** via `yad-review-gate`:
+
+```
+yad gate open EP-foundation foundation/
+```
+
+**Never mark `foundation-review` approved here** — only real reviewers do that through the gate. When
+the gate passes, the ledger moves to the `foundation-done` sentinel (not `ready-for-build` — the
+Foundation has no Build). From then on `foundation/roadmap.md` and `foundation/scope.md` are the inputs
+each `yad-epic` reads (its "Step 2c"). When the Product has a platform, the gate opens a review PR on the
+Product (via `yad-hub-bridge`) and `yad-review-gate action: sync` pulls platform approvals and comments
+into the ledger; otherwise the review is recorded locally.
 
 ## Reference
-- Discovery artifact templates + the 2-step state shape: `references/discovery-schema.md`.
+- Foundation section templates: `references/foundation-schema.md`.
+- The older spelling of the Product level (`EP-discovery`, its six files, and how it converts):
+  `references/discovery-schema.md`.
 - State schema, chain shapes, and the authoring-branch procedure:
   `../yad-epic/references/state-schema.md`.
 - The epic step that consumes `roadmap.md`: `../yad-epic/SKILL.md` (Step 2c).

package/skills/yad-discovery/references/discovery-schema.md

@@ -1,4 +1,17 @@
-# Discovery schema — artifacts + the front-zero state shape
+# Discovery schema — the OLD spelling of the Product level
+
+> **Since E75 this is the older spelling.** New products get a Foundation in `{project-root}/foundation/`
+> — see `foundation-schema.md`, seeded by `yad foundation new`. This page stays because a product that
+> already has an `EP-discovery` keeps working exactly as described here: the engine still reads it, gates
+> it, and ends its review at `discovery-done`.
+>
+> **Converting it.** On a **local** ledger, `yad migrate --apply` moves `epics/EP-discovery/` into
+> `foundation/`: the six files keep their names (so their fingerprint, and every approval bound to it,
+> is unchanged), the ledger is re-labelled to the Foundation's ids, and the step keeps `artifact:
+> "discovery/"` so the gate still hashes those six files. On a **verified** ledger CI owns the files and
+> the move cannot be made by a human commit, so the gate bot makes it: `yad gate ci` moves the folder at
+> the next merged review it handles, once the product level's own review has passed and the checks
+> committed in the repo know `foundation/`. A product has ONE product level: never seed a Foundation beside an `EP-discovery`.
 
 The project discovery phase ("epic zero") lives under `{project-root}/epics/EP-discovery/`. It reuses
 the per-epic ledger files (`.sdlc/state.json`, `approvals.json`, `comments.json`, `reviews/`,
@@ -15,21 +28,22 @@ object and the 2-step chain.
   "createdAt": "<YYYY-MM-DD>",
   "currentStep": "discovery-review",
   "steps": [
-    { "id": "discovery",        "type": "author",         "artifact": "discovery/", "assistance": "review", "automation": "human_approve", "locked": true, "status": "done",      "risk_tags": [] },
-    { "id": "discovery-review", "type": "review+approve", "artifact": "discovery/", "assistance": "review", "automation": "human_approve", "locked": true, "status": "in_review", "risk_tags": [] }
+    { "id": "discovery",        "type": "author",         "artifact": "discovery/", "assistance": "review", "driver": "pair", "automation": "human_approve", "advance": "human", "locked": true, "status": "done",      "risk_tags": [] },
+    { "id": "discovery-review", "type": "review+approve", "artifact": "discovery/", "assistance": "review", "driver": "pair", "automation": "human_approve", "advance": "human", "locked": true, "status": "in_review", "risk_tags": [] }
   ]
 }
 ```
 
 - `artifact: "discovery/"` is a **virtual** base: `artifactHash` fingerprints the whole discovery file
   set (`discoveryHash` in `cli/epic-state.mjs`), so an edit to any discovery file revokes prior
-  approvals — exactly like `stories/` fingerprints the stories directory.
+  approvals — exactly like `stories/` fingerprints the stories directory. The frontmatter `status:` line
+  is left out of each file's fingerprint, so the gate flipping it to `approved` is not an edit.
 - The **full set is required to review**: if any of the six files is missing, `discoveryHash` returns
   `null` — the discovery is **incomplete and non-reviewable** (no hash to bind an approval to), and
   `yad gate open` / `yad gate sync` warn with the missing filenames. Write all six (in greenfield,
   `current-state.md` is a short clean-slate note) before handing off to the gate.
 - On approval the gate sets `currentStep: "discovery-done"` (a terminal sentinel — discovery has **no**
-  build half, so it never becomes `ready-for-build`).
+  Build, so it never becomes `ready-for-build`).
 - The discovery files (relative to the epic dir) the gate commits on the review branch and re-hashes at
   merge are: `market-research.md`, `competitor-analysis.md`, `current-state.md`, `feasibility.md`,
   `requirements.md`, `roadmap.md` (the `DISCOVERY_FILES` list).
@@ -95,8 +109,10 @@ owner:
 <!-- explicitly deferred, with why -->
 ```
 
-Per-feature `status:` lifecycle (set by hand): `planned` → `epic-started` (a feature epic has been
-seeded with `yad-epic`) → `shipped`. The proposed `EP-<slug>` ids are suggestions for the eventual
+**Do not update the `Status` column by hand.** Editing the roadmap after its review has passed makes the
+approvals read as stale; `yad foundation status` reads each feature's status from the epic ledgers, for
+this spelling too. (The column's old hand-set ladder was `planned` → `epic-started` → `shipped`; rows that
+already say so can stay.) The proposed `EP-<slug>` ids are suggestions for the eventual
 `yad-epic` runs — `yad-epic` still assigns the id (and skips the reserved `EP-discovery`).
 
 The other four artifacts (`market-research.md`, `competitor-analysis.md`, `current-state.md`,