# Pipeline model — the yadflow workflow as `src/data/*.ts`

`yad-docs-overview` reuses the per-epic shell, but the *content* is the **workflow itself** rather than
one epic's flows. This file pins how the setup→ship pipeline maps onto the shell's primitives. The
ordering source of truth is `skills/sdlc/module-help.csv` (`phase`, `preceded-by`, `followed-by`,
`outputs`); the dial defaults come from `skills/sdlc/config.yaml`; the node classes come from
`docs/diagrams/sdlc-overview.mmd`.

## Primitive mapping

| Shell primitive | Overview meaning |
|-----------------|------------------|
| `FlowPath` (`paths.ts`) | a **phase**: Setup, Front-zero (discovery), Shape, Build, 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 Product, each `.sdlc/*.json`, code repos, the design/testing/learning tools, the platform). |
| `RoleConfig` (`roles.ts`) | a **lens** → its relevant sections + paths. |
| doc sections (`docSections.ts`/`referenceData.ts`) | the phase narratives + the dial reference tables (from `config.yaml` + the build-plan docs). |

## Flow paths = phases, with their skills in order

Order each path's steps by `module-help.csv` `phase` then the `preceded-by`/`followed-by` chain.

### Path: Setup (`phase: 0-setup`)
The connectors that make the brain context-aware and the outputs publishable. Each writes a `.sdlc/*.json`
and never gates.

| Step (skill) | Outputs / sideEffects |
|--------------|------------------------|
| `yad-connect-repos` | `repos.json`, `code-context/<repo>/pack.md` + `code-map.md` (+ `detect-product` → `product.json` + `hub.json`) |
| `yad-connect-design` | `design.json` |
| `yad-connect-testing` | `testing.json` |
| `yad-connect-learning` | `learning.json` |
| `yad-connect-docs` | `docs.json` |

### Path: Front-zero (`phase: 0-front`)
The OPTIONAL once-per-product **Foundation** (E75) — the Product level, in its own folder `foundation/`
under the fixed id `EP-foundation`. Greenfield AND brownfield; a 2-step author→review chain whose
review binds to the required sections and terminates at `foundation-done` (no Build). Its approval is
reported, not enforced, before feature work begins.

| Step (skill) | Gate | Outputs / sideEffects |
|--------------|------|------------------------|
| `yad foundation new` then `yad-discovery` *(optional)* | → `foundation-review` (base rule) | `purpose.md`, `scope.md`, `mvp.md`, `roadmap.md`, `stack.md`, `repos.md` (+ optional `market.md`, `risks.md`); seeds `foundation/.sdlc/state.json` |

`roadmap.md` is the menu of features each `yad-epic` reads (Step 2c) — reference-only, never
auto-seeds epics. A product created before E75 may still hold the old spelling, `epics/EP-discovery/`
(six files, ending at `discovery-done`); `yad migrate --apply` converts it on a local ledger.

<!-- `1-front` and `3-build` are DATA — the `phase` column in skills/sdlc/module-help.csv, which
     the overview build reads. The Shape/Build/Run rename deliberately left them alone: change-safety
     rule 3 says a release may add but never rename, so a stored value moves in a major with a
     migration, not in a wording sweep. The display names below are the new vocabulary; the ids are
     the old one, on purpose. -->

<!-- Each skill's `phase` in module-help.csv agrees with where this model places it. `4-automate` holds
     yad-run and the docs skills; `6-change` holds yad-change, yad-stub, yad-timeline, yad-defects and
     yad-reconcile; yad-status (a read-only view) and yad-learn (a tutor for any stage) are `anytime`, the
     value for a skill available at every stage — they are listed under
     Automation below only because the site needs one place to draw them. yad-report has no phase: it is
     a CLI helper, not a pipeline step.
     Moving three of these from `1-front` needed no migration, and that does not contradict the note
     above: module-help.csv is catalogue content the tool ships, read from the package's skills/sdlc/ folder
     and never installed into a project. It is not state a user's project stores. The note above is about
     the `1-front` / `3-build` ids as they are read back. -->

### Path: Shape (`phase: 1-front`)
The gated authoring chain + the reusable review gate (10 steps, or 12 with the optional analysis).

| Step (skill) | Gate | Outputs / sideEffects |
|--------------|------|------------------------|
| `yad-analysis` *(optional)* | → `analysis-review` | `analysis.md`, seeds `state.json` |
| `yad-epic` | → `epic-review` | `epic.md`, seeds `state.json` |
| `yad-architecture` | → `architecture-review` (contract tag raises the count) | `architecture.md`, `contract.md`, `contract-lock.json` |
| `yad-ui` | → `ui-design-review` | `ui-design.md`, `DESIGN.md`, `design-links.json` |
| `yad-stories` | → `stories-review` (labelled with every touched repo) | `stories/EP-<slug>-S0N.md` |
| `yad-test-cases` | → `test-cases-review` (parallel, non-blocking) | `test-cases.md`, `test-links.json` |
| `yad-review-gate` | the shared gate | `reviews/*.md`, `approvals.json`, `comments.json` |
| `yad-review-companion` | the fun/visible review layer (trailer/cards/chat + engagement) | `approvals.json` `engagement`, platform trailer/cards |
| `yad-product-bridge` | the platform PR/MR bridge | `product-prs.json` + `hub-prs.json` |

### Path: Build (`phase: 3-build`)
Per-story, per-repo: `spec → tasks → implement → checks → engineer-review`, plus the commit/PR helpers.

| Step (skill) | Outputs / sideEffects |
|--------------|------------------------|
| `yad-spec` | `specs/<story-id>/` (Spec Kit layout), `link.md` |
| `yad-implement` | a branch + commit per atomic task |
| `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`, plus `yad-update-guard` (push-on-default: re-checks any direct-to-default commit with `verified-commits · commit-message`) |
| `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 as a `build-log/` shard |
| `yad-backfill` | DRAFT specs for legacy features — its own step in the Build path (Step G, brownfield) |

### Path: Automation (`phase: 4-automate`) — the second dial + observation
The orchestrator + the trust evidence + the read-only views. Maps the **earns** / **locked** / **sentinel**
node classes from the diagram.

| Step (skill) | Outputs / sideEffects |
|--------------|------------------------|
| `yad-run` | drives the Build loop; `build-state/<story>.json`, `trust-log.json`; dials and kill switch through `yad dial` / `yad kill` (`.sdlc/automation.json`) |
| `yad-learn` | tutoring; `learning-records.json` (LOCAL-ONLY, gitignored) |
| `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 Shape 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 Shape 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); writes a threaded change-epic's lineage frontmatter and `change.json`, seeds its ledger with `yad epic new --parent` (inherited-step `state.json`, pointer-lock `contract-lock.json` — E42), and opens `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 `yad-checks` set above.

## System components = the durable state objects

`components.ts` renders these on the canvas (deterministic positions): the **Product**; each
`.sdlc/*.json` (`state.json`, `approvals.json`, `comments.json`, `product.json`, `repos.json`, `design.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.

`trust-log.json` and `build-log.json` are the *folded* halves of two **shard-then-fold** ledgers — each
also has a shard dir (`.sdlc/trust-log/`, `.sdlc/build-log/`) holding the entries `yad tidy up` has not
folded yet. They render as one component each, but anything READING them must union the folded file with
its shards (`../../yad-engineer-review/references/ship-and-record.md`).

## Roles = the lenses

The eight yadflow lenses, each to its relevant phase sections + paths:

| Lens | Relevant phases / sections |
|------|----------------------------|
| analyst | Setup intent, the Foundation (the Product level), analysis step, Shape discovery |
| pm | the Foundation (purpose/scope/MVP/roadmap), epic, stories; the Shape gates |
| architect | architecture + the locked contract; the contract risk step |
| ux | UI design, design tool connection, the design system |
| dev | Build: spec → implement, the per-repo loop |
| tester | test-cases (parallel track), the testing tool, checks |
| reviewer | the review gate, comments, the Product bridge |
| engineer | engineer review + ship, the merge gate, automation dial/trust |

## Determinism + theme
Same discipline as `yad-docs`: stable-sort steps by phase then pipeline order, fixed key order, **no
timestamps** in `src/data/*.ts` (build time lives only in `.docs-build.json`). Theme the `:root` from
**yadflow's brand palette** (the legacy report's `:root`): `--accent: #2471a3`, and carry the node-class
colors through to step/path colors — `--artifact-* #b7950b`, `--gate-* #ca6f1e`, `--earns-* #2471a3`,
`--locked-* #566573`, `--sentinel-* #1e8449` — so the canvas reads like the existing diagram.