yadflow 3.18.1 → 4.0.0-next.1

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

@@ -0,0 +1,374 @@
+# Foundation schema — the sections and the ledger
+
+The Foundation is the Product level (E75). It lives in `{project-root}/foundation/`, with its fixed id
+`EP-foundation`:
+
+```
+foundation/
+  purpose.md  market.md  scope.md  mvp.md  roadmap.md  stack.md  repos.md  risks.md
+  .sdlc/state.json  approvals.json  comments.json  product-prs.json  hub-prs.json
+  reviews/
+```
+
+## The ledger (`foundation/.sdlc/state.json`)
+
+Written by `yad foundation new`, never by hand. What it holds, for reference:
+
+```text
+epicId       EP-foundation
+kind         foundation       the marker every reader keys off (not a work-item type — there is none)
+profile      foundation       the route: two steps, no Build
+currentStep  foundation → foundation-review → foundation-done
+steps        foundation (author, artifact foundation/) · foundation-review (review+approve, artifact foundation/)
+```
+
+- `artifact: "foundation/"` is a **virtual** base: the gate fingerprints the Foundation sections together
+  (`foundationHash` in `cli/epic-state.mjs`). An edit to any section revokes prior approvals. The
+  frontmatter `status:` line is not part of the fingerprint, so the gate flipping it is not an edit.
+- The six **required** sections must all exist before the Foundation is reviewable. The two
+  **optional** ones (`market.md`, `risks.md`) count once they exist.
+- On approval the gate sets `currentStep: "foundation-done"`. The Foundation has no Build, so it never
+  becomes `ready-for-build`.
+- The review branch is `review/EP-foundation/foundation`, which both gate-sync workflows already match.
+- On a **verified** ledger, `foundation/.sdlc/` and `foundation/reviews/` are CI-owned exactly like an
+  epic's. The committed `checks/ledger-guard.sh` must be from E75 or later to guard them — `yad doctor`
+  warns when it is not, and `yad update` refreshes it.
+
+## When a section counts as written (E76)
+
+A section that still holds **only its template** is not written. "Only its template" means nothing but
+the frontmatter, `#` and `##` headings, `<!-- comments -->`, blank lines, `---` dividers, and an empty table
+(its header row, its `|---|` rule, and rows whose cells are all empty). One real sentence, one filled
+table row, or one `###` sub-heading makes it written.
+
+The engine checks this, and only ever **warns**:
+
+- `yad gate open` and `yad gate sync` print `Foundation not written yet — <files> hold nothing but their
+  template` when a section that exists is still empty.
+- `yad doctor` reports `foundation:unwritten` once the review has **opened or passed** with an empty
+  section. While the Foundation is still being written, an empty section is just work not done yet.
+
+So write every example into a comment, never as a table row: a filled row is read as your content.
+
+## Section templates and what goes in them
+
+Every section carries the same frontmatter block:
+
+```markdown
+---
+id: EP-foundation
+artifact: <section>
+status: draft
+owner:
+---
+```
+
+Each section below has four parts:
+
+- **The template** — the file to start from. Keep its headings; reviewers look for them.
+- **Ask** — the questions to put to the user. Ask them one at a time and write down the user's answer,
+  not your own guess.
+- **A good answer** — what the section holds when it is done.
+- **The reviewer checks** — what a reviewer holds it against at the gate.
+
+The examples use one made-up product, **Tally**: an app for flatmates to split shared bills.
+
+### `purpose.md`
+
+```markdown
+## Why this exists
+## Who it is for
+## What success looks like
+<!-- measurable where possible -->
+```
+
+**Ask:**
+- What problem does this solve, and what do people do about it today?
+- Who has the problem most? Name one kind of person, not "everyone".
+- A year after launch, what number would tell you this worked?
+
+**A good answer:** one short paragraph per heading. The problem is stated from the user's side, not as a
+feature. There is one main user group, with others named as secondary. Success is two or three
+measurable signals, each with a number or a clear yes/no.
+
+**The reviewer checks:** could someone outside the team say who this is for and why after one read? Is
+every success signal something you could actually measure?
+
+**Example (Tally):**
+
+```markdown
+## Why this exists
+Flatmates split rent, bills and shopping. Today they use a shared spreadsheet or a group chat, and
+someone always ends up owed money they are too awkward to ask for.
+
+## Who it is for
+People aged 20–35 sharing a flat with two to five others. Secondary: couples who share bills.
+
+## What success looks like
+- 40% of flats that add a second member are still logging expenses 8 weeks later.
+- A flat settles up (everyone at zero) at least once a month.
+```
+
+### `market.md` *(optional)*
+
+```markdown
+## Who else does this
+| Competitor | What they do | Where they fall short |
+|---|---|---|
+## Why us
+```
+
+**Ask:**
+- Who does this already, including "a spreadsheet" or "nobody bothers"?
+- For each one: why would your user still not be happy with it?
+- What can you do that they cannot, or will not?
+
+**A good answer:** three to five real alternatives, each with one honest line on where it falls short.
+"Why us" names an advantage the team really has, not a wish.
+
+**The reviewer checks:** is any obvious alternative missing? Does "why us" follow from the gaps in the
+table, or is it unrelated to them?
+
+**Example (Tally):**
+
+```markdown
+## Who else does this
+| Competitor | What they do | Where they fall short |
+|---|---|---|
+| Splitwise | Tracks shared expenses for any group | Built for trips; recurring rent and bills are clumsy |
+| A shared spreadsheet | Free and flexible | Nobody updates it; no reminders |
+
+## Why us
+We only do flats, so recurring bills and a monthly settle-up are the default, not an add-on.
+```
+
+### `scope.md`
+
+```markdown
+## What it is
+## What it is NOT
+<!-- explicit non-goals — the list a reviewer checks each feature epic against -->
+```
+
+**Ask:**
+- In one sentence, what is this product?
+- What will people expect it to do that it will **not** do? Keep asking until the user has named at
+  least three things.
+- Which of those are "not now" and which are "never"?
+
+**A good answer:** "What it is" is one or two sentences. "What it is NOT" is a list of concrete
+non-goals, each one a thing a real person might ask for. Mark each one *not now* or *never*.
+
+**The reviewer checks:** every later feature epic is compared with this list, so each non-goal must be
+specific enough to say yes or no to. "Not a bank" is useful; "not bloated" is not.
+
+**Example (Tally):**
+
+```markdown
+## What it is
+A shared ledger for one flat: log what each person paid, see who owes whom, settle up.
+
+## What it is NOT
+- Not a payment app — it never moves money (never).
+- Not for trips or one-off groups (not now).
+- Not a budgeting tool for one person (never).
+```
+
+### `mvp.md`
+
+```markdown
+## The smallest thing worth shipping
+## What is deliberately left out of it, and why
+```
+
+**Ask:**
+- What is the least a first user needs to get the value in `purpose.md`?
+- Walk through one user's first week. Which steps must work for that week to succeed?
+- What did you want to include but can live without at first?
+
+**A good answer:** a short list of capabilities — not screens, not technical tasks — that together
+deliver the first success signal. The "left out" list names each thing and one line on why it can wait.
+
+**The reviewer checks:** is every item really needed for the first success signal? Does anything here
+contradict `scope.md`'s non-goals?
+
+**Example (Tally):**
+
+```markdown
+## The smallest thing worth shipping
+- Create a flat and invite flatmates by link.
+- Log an expense and who it is split between.
+- See each person's balance, and mark a settle-up.
+
+## What is deliberately left out of it, and why
+- Recurring bills — people can log rent by hand for the first months; we learn the real patterns first.
+- Receipts and photos — nice, but nobody leaves over it.
+```
+
+### `roadmap.md` (the spine of the review)
+
+```markdown
+## Summary
+<!-- the product thesis in 2–3 lines -->
+
+## Phase 1 — MVP
+| Feature | Proposed epic id | Status |
+|---------|------------------|--------|
+<!-- one row per feature, e.g. | Registration | EP-registration | planned |. Write the Status once, when you add the row; do not update it by hand — `yad foundation status` reads it from the epic ledgers -->
+
+## Phase 2 — <name>
+| Feature | Proposed epic id | Status |
+|---------|------------------|--------|
+
+## Later / parked
+<!-- explicitly deferred, with why -->
+```
+
+**Ask:**
+- What does the MVP break down into, as features a team could build one at a time?
+- After the MVP, what comes next, and what has to be true before it starts?
+- What have you decided to park, and why?
+
+**A good answer:** Phase 1 holds exactly the MVP from `mvp.md`, one row per feature. Later phases are
+ordered by a stated reason (what they depend on, or what they unlock). Parked items are listed with why.
+Each proposed epic id follows `EP-<2–4 lowercase words>`.
+
+**The reviewer checks:** does Phase 1 match `mvp.md`, no more and no less? Is anything in a later phase
+a non-goal in `scope.md`?
+
+The proposed ids are suggestions — `yad-epic` still assigns the id, and never picks the reserved
+`EP-foundation` or `EP-discovery`.
+
+**Do not update the Status column by hand.** The roadmap table is part of what the Foundation's
+reviewers approved, so editing a row after the review has passed changes the Foundation's fingerprint,
+and `yad doctor` then reports its approvals as stale. Instead, `yad foundation status` reads how far each
+feature has got from the epic ledgers:
+
+| Status | Meaning |
+|---|---|
+| `planned` | No epic ledger with the proposed id exists yet |
+| `in-shape` | The epic is seeded and still in Shape (epic, architecture, UI, stories) |
+| `in-build` | Shape is done, and Build has not shipped every story in every repo |
+| `shipped` | Every story in the epic has a Build state, every repo each story declares has a lane, and every lane is shipped (or the epic is a brownfield anchor) |
+
+It also names feature epics that no row proposes — `yad-epic` may give an epic a different id from the
+one proposed. Write `planned` when you first add a row; an older Foundation that says `epic-started` or
+`shipped` can stay as it is, and the command notes where the column and the ledgers disagree.
+
+**Example (Tally):**
+
+```markdown
+## Summary
+Flatmates should never have to chase money. Tally is the shared ledger for one flat.
+
+## Phase 1 — MVP
+| Feature | Proposed epic id | Status |
+|---------|------------------|--------|
+| Flats and invites | EP-flat-invites | planned |
+| Log and split an expense | EP-log-expense | planned |
+| Balances and settle-up | EP-settle-up | planned |
+
+## Phase 2 — Recurring bills
+| Feature | Proposed epic id | Status |
+|---------|------------------|--------|
+| Recurring bills | EP-recurring-bills | planned |
+
+## Later / parked
+- Receipt photos — parked until people ask for it.
+```
+
+### `stack.md`
+
+```markdown
+## Languages and frameworks
+## Hosting and runtime
+## Data stores
+<!-- brownfield: what the connected repos actually use, from their code-maps -->
+```
+
+**Ask (greenfield — nothing is built yet):**
+- What does the team already know well? A stack nobody knows is a risk, not a choice.
+- What does the product need that narrows the choice (offline use, a phone app, heavy data, a region
+  the data must stay in)?
+- For each choice: what else did you consider, and why not that?
+
+**A good answer:** for each heading, the **decision**, the **alternatives rejected** and **why**, in a
+line or two each. Say what would make you change the choice later. On a greenfield product this records
+intended choices; nothing has to exist yet.
+
+**The reviewer checks:** does every choice have a reason tied to this product or this team? Is anything
+chosen that `mvp.md` does not need yet?
+
+**Example (Tally):**
+
+```markdown
+## Languages and frameworks
+TypeScript everywhere. Web app in React; no native app for the MVP (a phone browser is enough).
+Rejected: a native app first — two codebases before we know people want it.
+
+## Hosting and runtime
+One Node service on a managed platform in the EU. Rejected: running our own servers — no one to run them.
+
+## Data stores
+PostgreSQL. Balances must add up exactly, so we want transactions. Rejected: a document store.
+```
+
+### `repos.md`
+
+```markdown
+## Layout
+<!-- monorepo or separate repos, and why -->
+| Repo | What it does |
+|------|--------------|
+```
+
+**Ask (greenfield):**
+- How many deployable parts does the MVP have?
+- Will different people or teams own different parts?
+- Do the parts release together, or on their own schedules?
+
+**A good answer:** the layout decision (one repo, or several) with the reason, and a table with one row
+per repo. Each row says what the repo does in one line. On a greenfield product the repos may not exist
+yet — list what you intend to create.
+
+**The reviewer checks:** does every part in `stack.md` have a home here? Is the reason for the layout
+about how the team works, not just taste?
+
+**Example (Tally):**
+
+```markdown
+## Layout
+One repo for now. One small team owns everything and it all releases together; we split when a second
+team joins.
+
+| Repo | What it does |
+|------|--------------|
+| tally | The web app, the API and the database migrations |
+```
+
+### `risks.md` *(optional)*
+
+```markdown
+| Risk | Why it could kill this | What we do about it |
+|------|------------------------|---------------------|
+```
+
+**Ask:**
+- What would make this fail even if it is built well?
+- What are you assuming about users, the market, or the law that might be wrong?
+- For each risk: what is the cheapest way to find out early?
+
+**A good answer:** three to six risks, each with a concrete action — a test, a limit, or a decision
+point — not "monitor closely".
+
+**The reviewer checks:** is the biggest risk the team talks about in private written here? Does each
+action happen before the risk would hurt?
+
+**Example (Tally):**
+
+```markdown
+| Risk | Why it could kill this | What we do about it |
+|------|------------------------|---------------------|
+| Only one flatmate uses it | The ledger is useless if others do not log | Measure second-member activity from week 1; stop if under 20% |
+| People want it to move money | "Not a payment app" loses them | Ask the first 20 flats; revisit scope.md at 8 weeks |
+```

package/skills/yad-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-docs
-description: 'Generates the per-epic interactive documentation site — a vendored React/Vite/Tailwind SPA with an animated flow canvas and role-based stakeholder doc pages — from the epic''s approved artifacts (epic, architecture, the locked contract, UI design, stories, code-context, test cases). Themes it from the design tokens, wires the docs.json base path, and drives `yad docs build/deploy` to publish to Pages (or build-only when no target). This is an OUTPUT ENRICHMENT, never a gated front state: it never mutates state.json steps, approvals, or the contract lock. Use when the user says "generate the docs site", "build the interactive docs", or "deploy the epic docs".'
+description: 'Generates the per-epic interactive documentation site — a vendored React/Vite/Tailwind SPA with an animated flow canvas and role-based stakeholder doc pages — from the epic''s approved artifacts (epic, architecture, the locked contract, UI design, stories, code-context, test cases). Themes it from the design tokens, wires the docs.json base path, and drives `yad docs build/deploy` to publish to Pages (or build-only when no target). This is an OUTPUT ENRICHMENT, never a gated Shape step: it never mutates state.json steps, approvals, or the contract lock. Use when the user says "generate the docs site", "build the interactive docs", or "deploy the epic docs".'
 ---
 
 # SDLC — Author the Interactive Docs Site (per-epic, output enrichment)
@@ -12,14 +12,14 @@ stakeholder doc pages** (each lens → a set of doc sections). The shell is gene
 generated entirely into `src/data/*.ts` and the theme into `src/index.css`.
 
 This is an **output enrichment**, exactly like `design-links.json` / `test-links.json` — **NOT a gated
-front state.** It **never** mutates `.sdlc/state.json` `steps[]`, `approvals.json`, or
+Shape step.** It **never** mutates `.sdlc/state.json` `steps[]`, `approvals.json`, or
 `contract-lock.json`, and it never adds a `state.json` step. It reads the *approved* shape and renders
 it; it never decides approval. When a docs target is connected (`yad-connect-docs` → `.sdlc/docs.json`)
 the site is built + deployed; when none is, it is npm-built to a local `dist/` (build-only).
 
 ## Conventions
 
-- `{project-root}` resolves from the project working directory (the **product hub**).
+- `{project-root}` resolves from the project working directory (the **Product**).
 - Artifacts live under `{project-root}/epics/EP-<slug>/`. The generated site lives at
   `epics/EP-<slug>/docs-site/`; its `dist/` and `node_modules/` are gitignored, the generated **source
   is committed**.
@@ -30,7 +30,7 @@ the site is built + deployed; when none is, it is npm-built to a local `dist/` (
 - The actual data-file **generation** (reading artifacts → writing `src/data/*.ts`, theming
   `index.css`) is the **AI step** inside this skill; the `yad docs` CLI only does the npm build +
   platform deploy + staleness hashing.
-- Speak in the configured `communication_language`; write documents in `document_output_language`.
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.
 
 ## Inputs
 
@@ -52,7 +52,7 @@ and point the user at the gate (`yad-review-gate`); do not render an unapproved
 Open the `docs/EP-<slug>` authoring branch 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. Generate and commit the site source on it.
+Product's default branch. Generate and commit the site source on it.
 
 ### Step 2 — Read the inputs (the data sources)
 Load each artifact and note what it feeds (full table in `references/data-mapping.md`):
@@ -85,9 +85,11 @@ Copy the shell from `templates/app/` **verbatim**, then:
    timestamps inside the data files** — so regenerating an unchanged input yields a byte-identical file
    (the staleness hash depends on it). Data must satisfy `src/data/types.ts`
    (`FlowPath`/`FlowStep`/`AnimatedMessage`/`SystemComponent`/`StakeholderView`, etc.).
-2. **Derive stakeholder roles** (`roles.ts`) from the hub roster roles (`.sdlc/hub.json`) ∩ the yadflow
-   lens set (analyst / pm / architect / ux / dev / tester / reviewer / engineer) ∩ the stories' `repos:`
-   tags — each role → its relevant doc `sectionIds` + `relevantPathIds` (`references/data-mapping.md`).
+2. **Derive stakeholder roles** (`roles.ts`) from the yadflow lens set (analyst / pm / architect / ux /
+   dev / tester / reviewer / engineer), kept only where the epic's artifacts give that lens something to
+   read (which steps have artifacts, and the stories' `repos:` tags). No people or roles are read from
+   `.sdlc/hub.json` — yadflow keeps no list of people. Each role → its relevant doc `sectionIds` +
+   `relevantPathIds` (`references/data-mapping.md`).
 3. **Theme the `:root` block of `src/index.css`** from the design tokens, by the 4-tier priority in
    `references/theme-map.md`: **DESIGN.md → design.json/design-links.json palette → code-map tokens →
    default theme** (stamp `theme: default` in the manifest when it falls through to the shell default).
@@ -107,7 +109,7 @@ Write `epics/EP-<slug>/.sdlc/docs-build.json` — the baseline `yad-docs-sync` c
   "artifactHash": "<sha256 of epic.md + architecture.md + contract.md CONTRACT-SURFACE + ui-design.md + each story>",
   "repoHeads": { "<repo>": "<HEAD sha>" },
   "deployUrl": "<url or null>",
-  "templateVersion": "<shell template version>"
+  "shellVersion": "<the `version` in templates/app/package.json>"
 }
 ```
 
@@ -120,7 +122,10 @@ Optionally record a `docs:` line in a `DOCS.md` index under the epic.
 - `action: deploy` — drive **`yad docs deploy --epic <id>`**: it npm-builds the site (`npm ci && npm run
   build` as a subprocess, like `yad-spec` shelling `npx repomix`), ensures the Pages CI workflow is
   present, and reports the deploy URL (publish happens via CI). **Degrades** to the local `dist/` path
-  when no platform CLI / `target: "none"` (build-only).
+  when no platform CLI / `target: "none"` (build-only). **A failed build exits 1**: if `npm ci` (or
+  `npm install`, when the site has no lockfile) or `npm run build` fails, or the site was never generated, the command names the site and exits 1 —
+  report that failure and give no deploy URL. npm missing from PATH is only a warning here (CI builds on
+  push). `--json` has `built` (a count) and `sites: [{ site, built, error }]`.
 
 ### Step 6 — Stop. Report (NEVER auto-advance)
 Report: the site path (`epics/EP-<slug>/docs-site/`), the data files produced, the **theme source** (or
@@ -152,7 +157,7 @@ the default-theme degrade), the **deploy URL** or "build-only", and the **stalen
 - The connected docs target + base-path resolution: `../yad-connect-docs/SKILL.md`.
 - The design tokens this themes from: `../yad-connect-design/SKILL.md`.
 - The code-context the data enriches: `../yad-connect-repos/SKILL.md`.
-- The authoring pattern (front-state author that writes link artifacts without gating):
+- The authoring pattern (Shape step author that writes link artifacts without gating):
   `../yad-ui/SKILL.md`.
 - State schema + the "Authoring branches" procedure: `../yad-epic/references/state-schema.md`.
 - The project overview site + the staleness/CI reconciler: `../yad-docs-overview/SKILL.md`,

package/skills/yad-docs/references/data-mapping.md

@@ -11,7 +11,7 @@ shell renders whatever these export, as long as it satisfies `src/data/types.ts`
 |----------------|---------|-------------------|-----------|
 | `components.ts` | `COMPONENTS: SystemComponent[]` | `architecture.md` system components + `code-map.md` module/endpoint names | each durable component → `{ id, label, icon, color, position, description }`; canvas `position` laid out deterministically; real module names from the code-map enrich `label`/`description`. |
 | `paths.ts` | `FLOW_PATHS: FlowPath[]` | `stories/*.md` (one FlowPath each) + `architecture.md` flows | each story → one `FlowPath` (`id`, `label`, `icon`, `color`, `category`, `steps[]`); each acceptance criterion → a `FlowStep` whose `messages: AnimatedMessage[]` animate the request/response/event/job and whose `sideEffects` record jobs/notifications/pubsub. UI states (from `ui-design.md`) annotate each step. |
-| `roles.ts` | `ROLES: RoleConfig[]` | hub roster (`.sdlc/hub.json`) + the yadflow lens set + stories' `repos:` tags | each stakeholder lens → `{ slug, label, shortLabel, icon, color, description, sectionIds, relevantPathIds }` (role derivation below). |
+| `roles.ts` | `ROLES: RoleConfig[]` | the yadflow lens set + which artifacts the epic has + stories' `repos:` tags | each stakeholder lens → `{ slug, label, shortLabel, icon, color, description, sectionIds, relevantPathIds }` (role derivation below). |
 | `docSections.ts` | `DOC_SECTIONS: DocSectionConfig[]` | `epic.md`, `architecture.md`, `contract.md`, `ui-design.md`, `test-cases.md` | the ordered doc-section registry (`{ id, title, icon, iconColor, component }`); each section id is referenced from `roles.ts`. |
 | `referenceData.ts` | the reference tables/payloads the doc-section components render | `contract.md` CONTRACT-SURFACE (authoritative) + `architecture.md` + `test-cases.md` | API reference rows, the status machine, the DB schema, feature flags, error codes, the test plan — the structured data behind the doc sections. |
 
@@ -21,8 +21,8 @@ shell renders whatever these export, as long as it satisfies `src/data/types.ts`
 organized around a central hub into four surrounding zones** so the spokes fan out without crossing,
 rather than scattering nodes:
 
-- **Center** — the product hub (the brain).
-- **Top band** — the file ledger the hub owns (state / approvals / contract-lock), spread across one row.
+- **Center** — the Product (the brain).
+- **Top band** — the file ledger the Product owns (state / approvals / contract-lock), spread across one row.
 - **Left** — the code side: each connector with its external target just beyond it (`repos-json → code-repos`).
 - **Right** — the connected tools as a single aligned column: each connector on the inner edge with its
   external tool on the same row just outside it (`design-json → Design Tool`, etc.).
@@ -52,13 +52,15 @@ contract is rendered exactly as locked — the docs are a *view* of the locked s
 
 ## Role derivation (`roles.ts`)
 
-A stakeholder role is generated for each lens that is **both** present in the hub roster **and** relevant
-to this epic:
+A stakeholder role is generated for each lens that is **relevant to this epic** — that is, the epic's
+artifacts give the lens something to read. yadflow keeps no list of people, so no people or roles are
+read from `.sdlc/hub.json`.
 
 1. Start from the **yadflow lens set**: `analyst`, `pm`, `architect`, `ux`, `dev`, `tester`, `reviewer`,
    `engineer`.
-2. Intersect with the **hub roster** roles (`.sdlc/hub.json` `roster[].roles`) — only emit lenses the
-   team actually has (an unmapped lens is dropped, never invented).
+2. Keep only the lenses the epic's artifacts support — for example `analyst` needs `analysis.md`, `ux`
+   needs `ui-design.md`, `tester` needs `test-cases.md`, and `dev`/`engineer` need at least one story
+   with a `repos:` tag. A lens with nothing to read is dropped, never invented.
 3. For the `dev`/`engineer` lenses, **fan out per `repos:` tag** present across the epic's stories (e.g.
    a `backend` dev role and a `mobile` dev role), so each repo audience gets its own integration view —
    mirroring the reference site's per-app dev roles.

package/skills/yad-docs/templates/app/package-lock.json

@@ -2396,9 +2396,9 @@
       "license": "MIT"
     },
     "node_modules/js-yaml": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.1.tgz",
-      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.2.tgz",
+      "integrity": "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==",
       "dev": true,
       "funding": [
         {

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

@@ -7,7 +7,7 @@ description: 'Generates the project-level SDLC-overview interactive site — the
 
 **Goal:** Render the **whole yadflow pipeline** — every stage from setup → ship — as an interactive site,
 reusing the same shell as the per-epic docs (`skills/yad-docs/templates/app/`). Where `yad-docs`
-animates one epic's flows, this animates the **workflow itself**: the front gates, the build half, the
+animates one epic's flows, this animates the **workflow itself**: the Shape gates, Build, the
 automation dial, the setup connectors. The hand-maintained overview report stays the **main
 documentation at the Pages root** (`<base>/`, served from `public/report.html` and `public/index.html`);
 this interactive SPA mounts under `<base>/app/` and is reached from the report — the report links
@@ -19,14 +19,17 @@ It only reads the pipeline definition and writes a project-level site. When a do
 
 ## Conventions
 
-- `{project-root}` resolves from the project working directory (the **product hub**).
+- `{project-root}` resolves from the project working directory (the **Product**).
 - The overview site lives at `{project-root}/docs/sdlc-site/`; its `dist/`/`node_modules/` are gitignored,
   the generated **source is committed**. The overview build manifest is `docs/sdlc-site/.docs-build.json`.
-- The shell template is `skills/yad-docs/templates/app/` — copied **verbatim**, themed only in the
-  `:root` of `index.css`. Generated data satisfies `src/data/types.ts`.
+- The shell template is `skills/yad-docs/templates/app/`. It is copied **only when `docs/sdlc-site/`
+  does not exist yet** — see Step 3. The overview site in this repo has since grown sections of its own
+  (for example CheckGates, CliReference, TwoDials, Glossary, ContractLock, ReviewGate, Connectors and the
+  Reference tables) and dropped the template's per-epic ones, so it is **updated in place, never
+  re-copied**. Generated data satisfies `src/data/types.ts`.
 - Theme: **yadflow's own brand palette** (the `:root` of the legacy report, now `docs/sdlc-site/public/report.html`) — for visual continuity with
   the existing overview, not an epic's design tokens.
-- Speak in the configured `communication_language`; write documents in `document_output_language`.
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.
 
 ## Inputs
 
@@ -39,8 +42,8 @@ It only reads the pipeline definition and writes a project-level site. When a do
 There is no epic; the inputs are the workflow's own config + manifest (full mapping in
 `references/pipeline-model.md`):
 
-- `skills/sdlc/config.yaml` — the front/back steps, the **two dials** (assistance, automation),
-  defaults, the review-gate rule, the build conventions, the automation/trust thresholds.
+- `skills/sdlc/config.yaml` — the Shape/Build steps, the **two dials** (`driver`/`assistance`, `advance`/`automation`),
+  defaults, the review-gate rule, the build conventions, the automation defaults.
 - `skills/sdlc/module-help.csv` — the **canonical skill manifest**: each skill's `phase`,
   `preceded-by` / `followed-by`, and `outputs`. This is the ordering source of truth.
 - `docs/diagrams/sdlc-overview.mmd` — the overview diagram (the node/edge shape + the node classes:
@@ -56,10 +59,10 @@ 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-zero` (discovery), `Front half`, `Build half`, `Automation`, `Change management` (feature threads).
+- **Flow paths** = the **phases** — `Setup`, `Front-zero` (discovery), `Shape`, `Build`, `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`
+- **System components** = the **durable state objects** — the Product, each `.sdlc/*.json`
   (`state.json`, `approvals.json`, `repos.json`, `design.json`, `testing.json`, `learning.json`,
   `docs.json`, `contract-lock.json`, `build-state/*`, `trust-log.json`), the connected code repos, the
   design/testing/learning tools, and the platform.
@@ -67,7 +70,16 @@ Map the pipeline onto the same data structures `yad-docs` uses (concrete mapping
   to its relevant sections + paths.
 
 ### Step 3 — Generate the site into `docs/sdlc-site/`
-Copy the shell from `templates/app/` **verbatim**, generate `src/data/*.ts` deterministically (same
+**First check whether `docs/sdlc-site/` already exists.**
+
+- **It does not exist** (a first build): copy the shell from `templates/app/` verbatim, then do the rest
+  of this step.
+- **It exists** (every build after the first): **do not copy the shell.** Copying it would overwrite the
+  site's own components and delete the sections the template does not have. Instead, update the site in
+  place: regenerate the data in `src/data/*.ts`, and edit a component only where the pipeline change
+  needs it. Before you finish, run `git status docs/sdlc-site/` and check that nothing was deleted.
+
+Then generate `src/data/*.ts` deterministically (same
 determinism rules as `yad-docs`: stable-ID sort by skill pipeline order / phase, fixed key order, no
 timestamps in the data files), theme the `:root` of `index.css` from **yadflow's brand palette** — the
 the legacy report's `:root`: `--accent: #2471a3` and the node colors (`--artifact-*`, `--gate-*`,
@@ -84,13 +96,14 @@ Write `docs/sdlc-site/.docs-build.json` — `yad-docs-sync` compares against it:
   "theme": "yadflow-brand",
   "artifactHash": "<sha256 of config.yaml + module-help.csv + docs/diagrams/sdlc-overview.mmd>",
   "skillCount": <number of yad-* skills>,
-  "deployUrl": "<url or null>",
-  "templateVersion": "<shell template version = the yad CLI version>"
+  "deployUrl": "<url or null>"
 }
 ```
 
-The overview's freshness inputs are the **config + manifest + diagram** (plus the `templateVersion`, so a
-doc-shell upgrade triggers a rebuild). `skillCount` rides along in the manifest as an informational field
+The overview's freshness inputs are the **config + manifest + diagram**. There is **no shell version**:
+the overview is not re-copied from the shell (Step 3), so a shell upgrade is not a reason to rebuild it.
+An older manifest may still carry a `templateVersion` (the yad CLI version); it is ignored, because it
+made the overview read stale after every release. `skillCount` rides along in the manifest as an informational field
 — it is **not** a separate hash input, since `module-help.csv` already moves whenever the skill set does.
 Not per-epic artifacts/repo heads.
 
@@ -108,7 +121,8 @@ root. This generalizes the standing rule that feature work hand-updates the repo
 ### Step 6 — Build / deploy (`action`)
 - `action: generate` (default) — generate source + manifest; stop.
 - `action: deploy` — drive **`yad docs deploy --overview`**: npm-build, ensure the Pages CI workflow,
-  report the deploy URL. Degrades to local `dist/` when no platform CLI / `target: "none"`.
+  report the deploy URL. Degrades to local `dist/` when no platform CLI / `target: "none"`. A failed
+  npm install or build exits 1 and names the site — report the failure, not a deploy URL.
 
 ### Step 7 — Stop. Report (no gate, no epic)
 Report: the site path (`docs/sdlc-site/`), the data files produced, that the theme is the yadflow brand
@@ -124,8 +138,9 @@ under `<base>/app/` and cross-linked. Never touches any epic state.
   work hand-updates `docs/index.html` + the overview diagram + skill counts: the overview site now
   regenerates whenever `module-help.csv` / `config.yaml` / the skill count changes — and `yad-docs-sync`
   **enforces** that (it flags the overview stale when those inputs move).
-- **Brand-palette themed, copy the shell verbatim.** Theme only the `:root`; generate only `src/data/*.ts`
-  + the Vite base. Never hand-edit `templates/app/`.
+- **Copy the shell once, then update in place.** The template is copied only into a missing
+  `docs/sdlc-site/`. An existing site is never re-copied over, because that deletes its own sections.
+  Theme only the `:root`. Never hand-edit `templates/app/` for the overview's sake.
 - **Deterministic generation.** Same stable-sort / fixed-key / no-timestamp discipline as `yad-docs`.
 - **Degrade gracefully.** No docs target → build-only; no `.mmd` / no build-plan docs → omit those
   sections with a note, never invent.