yadflow 2.6.0 → 2.8.0

package/skills/yad-docs/templates/app/src/store/useAuthStore.ts

@@ -0,0 +1,42 @@
+import { create } from 'zustand';
+
+// Login gate — presentational ONLY, never a security control (real access control is the
+// repo / Pages ACL). `yad docs` sets DOCS_REQUIRE_LOGIN to `false` by default for public docs;
+// teams publishing to a private Pages site can flip it to `true` (login_gate: true) and set
+// credentials via the Vite env vars VITE_DOCS_USER / VITE_DOCS_PASS at build time.
+const DOCS_REQUIRE_LOGIN = false;
+const CREDENTIALS = {
+  username: import.meta.env.VITE_DOCS_USER ?? 'docs',
+  password: import.meta.env.VITE_DOCS_PASS ?? 'docs',
+};
+
+interface AuthStore {
+  isAuthenticated: boolean;
+  username: string | null;
+  error: string | null;
+  login: (username: string, password: string) => boolean;
+  logout: () => void;
+}
+
+export const useAuthStore = create<AuthStore>((set) => ({
+  isAuthenticated: !DOCS_REQUIRE_LOGIN || sessionStorage.getItem('auth') === 'true',
+  username: sessionStorage.getItem('auth_user'),
+  error: null,
+
+  login: (username, password) => {
+    if (username === CREDENTIALS.username && password === CREDENTIALS.password) {
+      sessionStorage.setItem('auth', 'true');
+      sessionStorage.setItem('auth_user', username);
+      set({ isAuthenticated: true, username, error: null });
+      return true;
+    }
+    set({ error: 'Invalid username or password' });
+    return false;
+  },
+
+  logout: () => {
+    sessionStorage.removeItem('auth');
+    sessionStorage.removeItem('auth_user');
+    set({ isAuthenticated: false, username: null, error: null });
+  },
+}));

package/skills/yad-docs/templates/app/src/store/useFlowStore.ts

@@ -0,0 +1,197 @@
+import { create } from "zustand";
+import type { FlowPath, FlowStep, PlaybackState, StakeholderView } from "../data/types";
+import { PATHS } from "../data/paths";
+
+export interface LogEntry {
+  id: string;
+  timestamp: Date;
+  level: 'info' | 'warn' | 'error' | 'debug';
+  source: string;
+  message: string;
+}
+
+interface FlowStore {
+  selectedPath: FlowPath;
+  activeSubPathId: string | null;
+  activeStepIndex: number;
+  playbackState: PlaybackState;
+  speed: number;
+  animatingMessages: boolean;
+
+  // Stakeholder
+  stakeholderView: StakeholderView;
+
+  // UI panels
+  zoomLevel: number;
+  isReferencePanelOpen: boolean;
+  isCommandPaletteOpen: boolean;
+  isLogsPanelOpen: boolean;
+
+  // Logs
+  logs: LogEntry[];
+
+  // Timer
+  elapsedTime: number;
+
+  selectPath: (pathId: number) => void;
+  selectSubPath: (subPathId: string) => void;
+  setActiveStep: (index: number) => void;
+  nextStep: () => void;
+  prevStep: () => void;
+  play: () => void;
+  pause: () => void;
+  stop: () => void;
+  setSpeed: (speed: number) => void;
+  setAnimatingMessages: (val: boolean) => void;
+
+  // Stakeholder
+  setStakeholderView: (view: StakeholderView) => void;
+
+  // Zoom
+  setZoomLevel: (level: number) => void;
+  zoomIn: () => void;
+  zoomOut: () => void;
+  resetZoom: () => void;
+
+  // Panels
+  toggleReferencePanel: () => void;
+  toggleCommandPalette: () => void;
+  toggleLogsPanel: () => void;
+
+  // Logs
+  addLog: (entry: Omit<LogEntry, 'id' | 'timestamp'>) => void;
+  clearLogs: () => void;
+
+  // Timer
+  tickElapsed: () => void;
+  resetElapsed: () => void;
+
+  // Replay
+  replayStep: () => void;
+
+  getCurrentSteps: () => FlowStep[];
+  getCurrentStep: () => FlowStep | null;
+  getTotalSteps: () => number;
+}
+
+let logCounter = 0;
+
+export const useFlowStore = create<FlowStore>((set, get) => ({
+  selectedPath: PATHS[0],
+  activeSubPathId: null,
+  activeStepIndex: 0,
+  playbackState: "idle",
+  speed: 1,
+  animatingMessages: false,
+
+  stakeholderView: 'rider-mobile-dev' as StakeholderView,
+
+  zoomLevel: 1,
+  isReferencePanelOpen: false,
+  isCommandPaletteOpen: false,
+  isLogsPanelOpen: false,
+  logs: [],
+  elapsedTime: 0,
+
+  selectPath: (pathId: number) => {
+    const path = PATHS.find((p) => p.id === pathId) || PATHS[0];
+    const hasSubPaths = path.subPaths && path.subPaths.length > 0;
+    set({
+      selectedPath: path,
+      activeStepIndex: 0,
+      playbackState: "idle",
+      animatingMessages: false,
+      activeSubPathId: hasSubPaths ? path.subPaths![0].id : null,
+    });
+  },
+
+  selectSubPath: (subPathId: string) => {
+    set({
+      activeSubPathId: subPathId,
+      activeStepIndex: 0,
+      playbackState: "idle",
+      animatingMessages: false,
+    });
+  },
+
+  setActiveStep: (index: number) => {
+    const steps = get().getCurrentSteps();
+    if (index >= 0 && index < steps.length) {
+      set({ activeStepIndex: index, animatingMessages: false });
+    }
+  },
+
+  nextStep: () => {
+    const { activeStepIndex, getCurrentSteps } = get();
+    const steps = getCurrentSteps();
+    if (activeStepIndex < steps.length - 1) {
+      set({ activeStepIndex: activeStepIndex + 1, animatingMessages: false });
+    } else {
+      set({ playbackState: "idle" });
+    }
+  },
+
+  prevStep: () => {
+    const { activeStepIndex } = get();
+    if (activeStepIndex > 0) {
+      set({ activeStepIndex: activeStepIndex - 1, animatingMessages: false });
+    }
+  },
+
+  play: () => set({ playbackState: "playing" }),
+  pause: () => set({ playbackState: "paused" }),
+  stop: () => set({ playbackState: "idle", activeStepIndex: 0, animatingMessages: false }),
+  setSpeed: (speed: number) => set({ speed }),
+  setAnimatingMessages: (val: boolean) => set({ animatingMessages: val }),
+
+  // Stakeholder
+  setStakeholderView: (view) => set({ stakeholderView: view }),
+
+  // Zoom
+  setZoomLevel: (level: number) => set({ zoomLevel: Math.max(0.5, Math.min(2, level)) }),
+  zoomIn: () => set((s) => ({ zoomLevel: Math.min(2, s.zoomLevel + 0.1) })),
+  zoomOut: () => set((s) => ({ zoomLevel: Math.max(0.5, s.zoomLevel - 0.1) })),
+  resetZoom: () => set({ zoomLevel: 1 }),
+
+  // Panels
+  toggleReferencePanel: () => set((s) => ({ isReferencePanelOpen: !s.isReferencePanelOpen })),
+  toggleCommandPalette: () => set((s) => ({ isCommandPaletteOpen: !s.isCommandPaletteOpen })),
+  toggleLogsPanel: () => set((s) => ({ isLogsPanelOpen: !s.isLogsPanelOpen })),
+
+  // Logs
+  addLog: (entry) => {
+    logCounter++;
+    set((s) => ({
+      logs: [...s.logs.slice(-200), { ...entry, id: `log-${logCounter}`, timestamp: new Date() }],
+    }));
+  },
+  clearLogs: () => set({ logs: [] }),
+
+  // Timer
+  tickElapsed: () => set((s) => ({ elapsedTime: s.elapsedTime + 0.1 })),
+  resetElapsed: () => set({ elapsedTime: 0 }),
+
+  // Replay
+  replayStep: () => {
+    set({ animatingMessages: false });
+  },
+
+  getCurrentSteps: () => {
+    const { selectedPath, activeSubPathId } = get();
+    if (selectedPath.subPaths && activeSubPathId) {
+      const sub = selectedPath.subPaths.find((s) => s.id === activeSubPathId);
+      return sub ? sub.steps : [];
+    }
+    return selectedPath.steps;
+  },
+
+  getCurrentStep: () => {
+    const { activeStepIndex } = get();
+    const steps = get().getCurrentSteps();
+    return steps[activeStepIndex] || null;
+  },
+
+  getTotalSteps: () => {
+    return get().getCurrentSteps().length;
+  },
+}));

package/skills/yad-docs/templates/app/src/utils/iconMap.ts

@@ -0,0 +1,46 @@
+export const COMPONENT_ICONS: Record<string, string> = {
+  'rider-app': 'smartphone',
+  'driver-app': 'directions_car',
+  'backend-api': 'cloud_queue',
+  'bullmq': 'layers',
+  'ops-dashboard': 'monitor_heart',
+  'pubsub': 'cell_tower',
+  'dac': 'assignment',
+  'database': 'database',
+};
+
+export const COMPONENT_ROLES: Record<string, string> = {
+  'rider-app': 'Client',
+  'driver-app': 'Client',
+  'backend-api': 'Gateway',
+  'bullmq': 'Worker',
+  'ops-dashboard': 'Dashboard',
+  'pubsub': 'Messaging',
+  'dac': 'Actions',
+  'database': 'Storage',
+};
+
+export const CATEGORY_ICONS: Record<string, string> = {
+  success: 'check_circle',
+  'rider-cancel': 'cancel',
+  'driver-cancel': 'person_off',
+  timeout: 'schedule',
+  ops: 'admin_panel_settings',
+  'active-cancel': 'cancel',
+};
+
+export const ACTOR_ICONS: Record<string, string> = {
+  rider: 'person',
+  driver: 'directions_car',
+  ops: 'admin_panel_settings',
+  system: 'dns',
+};
+
+export const MESSAGE_TYPE_ICONS: Record<string, string> = {
+  request: 'input',
+  response: 'output',
+  event: 'bolt',
+  job: 'work',
+  notification: 'notifications',
+  cleanup: 'cleaning_services',
+};

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

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

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

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

package/skills/yad-docs/templates/app/tsconfig.node.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts"]
+}

package/skills/yad-docs/templates/app/vite.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+// `base` is substituted by `yad docs` at generate time from .sdlc/docs.json `basePath`
+// (GitHub project Pages serve at /<repo>/; user/org Pages and GitLab Pages use /).
+export default defineConfig({
+  base: '__BASE_PATH__',
+  plugins: [react(), tailwindcss()],
+})

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

@@ -0,0 +1,131 @@
+---
+name: yad-docs-overview
+description: 'Generates the project-level SDLC-overview interactive site — the same React/Vite/Tailwind shell as the per-epic docs — showing every yadflow stage from setup → ship: the pipeline as a flow canvas, each skill/gate as a flow step, the durable .sdlc state objects as system components, and the lenses as stakeholder roles. Themed with yadflow''s own brand palette for continuity, built from config.yaml + module-help.csv + the overview diagram. Folds the legacy hand-maintained docs/index.html report into the site as report.html (linked from the nav) and deploys via `yad docs deploy --overview`. This is project documentation, not a gated state — it never touches any epic''s state or approvals. Use when the user says "generate the overview site", "build the SDLC overview docs", or after the pipeline (module-help.csv / config.yaml / skill count) changes.'
+---
+
+# SDLC — Author the Overview Site (project-level, the pipeline as a living map)
+
+**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
+automation dial, the setup connectors. It is the regenerable successor to the hand-maintained
+overview report, which is folded into this site as `public/report.html`.
+
+This is **project documentation, not a gated state** — there is no epic, no `state.json`, no approvals.
+It only reads the pipeline definition and writes a project-level site. When a docs target is connected
+(`.sdlc/docs.json`) it builds + deploys; otherwise it build-only.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory (the **product hub**).
+- 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`.
+- 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`.
+
+## Inputs
+
+- `action` — `generate` (default) | `refresh` | `deploy`.
+- `login_gate` — `true` | `false` (default `false`).
+
+## On Activation
+
+### Step 1 — Read the pipeline definition (the data sources)
+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/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:
+  artifact / gate / earns / locked / sentinel).
+- the build-plan docs under `docs/` — phase narratives for the section copy.
+
+### Step 1b — Open the authoring branch
+Open the `docs/overview` authoring branch per the shared procedure
+(`../yad-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if not a
+git work tree). Generate and commit on it.
+
+### Step 2 — Model the pipeline with the shell primitives
+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 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`
+  (`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.
+- **Roles** = the **lenses** (analyst / pm / architect / ux / dev / tester / reviewer / engineer) → each
+  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
+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-*`,
+`--earns-*`, `--locked-*`, `--sentinel-*`) — and substitute the Vite base from `.sdlc/docs.json`
+`basePath` (the overview sits at the base root, e.g. `/<repo>/`).
+
+### Step 4 — Write the overview build manifest (the staleness baseline)
+Write `docs/sdlc-site/.docs-build.json` — `yad-docs-sync` compares against it:
+
+```json
+{
+  "builtAt": "<YYYY-MM-DD>",
+  "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>"
+}
+```
+
+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
+— it is **not** a separate hash input, since `module-help.csv` already moves whenever the skill set does.
+Not per-epic artifacts/repo heads.
+
+### Step 5 — Fold the legacy report into the site
+Relocate the hand-maintained static report into the generated site as `docs/sdlc-site/public/report.html`
+(Vite copies `public/` verbatim into `dist/`, so it publishes alongside the app at `<base>/report.html`),
+and link it from the app nav (a "Full report" link in `TopNavBar`). The interactive overview becomes the
+primary documentation and the legacy report rides along as its detailed companion — no orphaned
+`docs/index.html` at the repo root. This generalizes the standing rule that feature work hand-updates the
+report: the overview site now **regenerates** instead.
+
+### 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"`.
+
+### 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
+palette, the deploy URL or "build-only", the staleness baseline, and that the legacy report is folded in
+at `public/report.html` (linked from the nav). Never touches any epic state.
+
+## Hard rules
+
+- **Project documentation, not a gate.** No epic, no `state.json`, no approvals — this skill never reads
+  or writes any epic's gated state.
+- **The overview regenerates on pipeline change.** This **generalizes** the standing rule that feature
+  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/`.
+- **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.
+
+## Reference
+- The concrete mapping of every setup→ship stage to flow paths / steps / components / roles, with each
+  `yad-*` skill in pipeline order + its phase + outputs: `references/pipeline-model.md`.
+- The per-epic counterpart (shell, determinism, theming): `../yad-docs/SKILL.md`.
+- The connected docs target + base-path resolution: `../yad-connect-docs/SKILL.md`.
+- The staleness/CI reconciler that enforces overview regeneration: `../yad-docs-sync/SKILL.md`.

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

@@ -0,0 +1,102 @@
+# 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 dials/thresholds 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 half, Build half, Automation. |
+| `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. |
+| doc sections (`docSections.ts`/`referenceData.ts`) | the phase narratives + the dial/threshold 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-hub`/`roster` → `hub.json`) |
+| `yad-connect-design` | `design.json` |
+| `yad-connect-testing` | `testing.json` |
+| `yad-connect-learning` | `learning.json` |
+| `yad-connect-docs` | `docs.json` |
+
+### Path: Front half (`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` (escalates on contract) | `architecture.md`, `contract.md`, `contract-lock.json` |
+| `yad-ui` | → `ui-design-review` | `ui-design.md`, `DESIGN.md`, `design-links.json` |
+| `yad-stories` | → `stories-review` (per-repo routing) | `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-hub-bridge` | the platform PR/MR bridge | `hub-prs.json` |
+| `yad-review-comments` | comment scaffolds | repo comment templates |
+
+### Path: Build half (`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 |
+| `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` |
+| `yad-backfill` | DRAFT specs for legacy features |
+
+### Path: Automation (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 back-half loop; `build-state/<story>.json`, `trust-log.json`, kill switch |
+| `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 |
+
+## 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`);
+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.
+
+## Roles = the lenses
+
+The eight yadflow lenses, each to its relevant phase sections + paths:
+
+| Lens | Relevant phases / sections |
+|------|----------------------------|
+| analyst | Setup intent, analysis step, front-half discovery |
+| pm | epic, stories, roadmap; the front gates |
+| architect | architecture + the locked contract; escalation |
+| ux | UI design, design tool connection, the design system |
+| dev | build half: spec → implement, the per-repo loop |
+| tester | test-cases (parallel track), the testing tool, checks |
+| reviewer | the review gate, comments, the hub 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.