yadflow 2.2.0 → 2.4.0

package/skills/yad-learn/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: yad-learn
+description: 'The cross-cutting learning layer: at ANY SDLC stage, a team member can ask to learn a concept and be tutored in the context of what the team is building. Routes the request to the connected learning tool (.sdlc/learning.json, DeepTutor-first) grounded in the project knowledge base, or degrades to harness-native tutoring (the harness model reading the artifacts) when no tool is connected. Renders a tutorial artifact and appends to a per-member learning ledger that is kept LOCAL-ONLY — gitignored, never committed or pushed to the product hub or any code repo — so it stays a private, personal skills log (yad-status rolls up the local records). Purely opt-in — it NEVER blocks a gate and never touches epic state, approvals, or the contract lock. Use when the user says "teach me <concept>", "learn about <concept>", or "yad-learn".'
+---
+
+# SDLC — Learn (the cross-cutting tutor)
+
+**Goal:** At any SDLC stage, a team member can pause and ask to learn a concept — e.g. *"teach me why the
+architecture hash-locks the contract surface"* — and get tutored **in the context of this project**. The
+tutorial is rendered as an artifact and the request is recorded in a **personal, local skills log**
+(`yad-status` shows the roll-up of your local records). This makes a learner's own understanding — and
+therefore their **control over what is being built** — explicit, without ever exposing who-learned-what
+to the team.
+
+**Learning output is LOCAL-ONLY.** The records ledger and the rendered tutorials are personal artifacts:
+they are **gitignored and must never be committed or pushed** — not to the product hub and not to any
+code repo. The skill ensures the product hub's `.gitignore` lists these paths before it writes them. The
+only committed, shared learning file is the connection registry `.sdlc/learning.json` (no secrets, no
+personal data) — written by `yad-connect-learning`, not here.
+
+This is a **cross-cutting, opt-in** skill (like `yad-status`, it runs any time). It is **never a gate**:
+it does not move `currentStep`, never records an approval, and never touches `.sdlc/state.json`, the
+approvals ledger, or the contract lock. It writes only the local learning ledger + tutorial artifacts.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory (the **product hub**).
+- The tutor is reached via the project's learning connection (`.sdlc/learning.json`, written by
+  `yad-connect-learning`). **DeepTutor-first** (a CLI subprocess); when no tool is connected (or the
+  `deeptutor` binary is absent) it degrades to **harness-native** tutoring — the harness model reads the
+  scoped artifacts and explains the concept itself. Either way `yad-learn` always works and always
+  records.
+- Per-epic learning records: `epics/EP-<slug>/.sdlc/learning-records.json` (append-only personal log).
+  Rendered tutorials: `epics/EP-<slug>/learning/`.
+- When no epic is scoped, records go to `.sdlc/learning-records.json` and tutorials to `.sdlc/learning/`
+  (cross-project learning).
+- **Local-only, never committed.** All of the above paths are personal output. Before writing any of
+  them, ensure the **product hub's** `.gitignore` ignores learning output (idempotent — append only if
+  the lines are absent):
+  ```
+  # yadflow learning layer — personal, local-only (never commit or push)
+  .sdlc/learning-records.json
+  .sdlc/learning/
+  epics/*/.sdlc/learning-records.json
+  epics/*/learning/
+  ```
+  Never write learning output into a connected **code repo** — it lives only in the product hub, and only
+  on the local machine. `.sdlc/learning.json` (the connection registry) is the sole committed learning
+  file and is NOT ignored.
+- Speak in the configured `communication_language`; write tutorials in `document_output_language`.
+
+## Inputs
+
+- `concept` — **required.** The idea to learn (e.g. "contract versioning", "async/await", "the per-repo
+  stories gate").
+- `context` — optional free text narrowing the focus (e.g. "why the surface is hash-locked", "in the
+  backend event loop").
+- `epic` — optional `EP-<slug>` to scope the tutorial + record to one epic (default: cross-project).
+- `stage` — optional SDLC stage the learner is at (e.g. `architecture-review`, `implement`), recorded for
+  the skills roll-up.
+- `member` — the learner (default: the invoking user).
+- `mode` — `explain` (default) | `deep` | `quiz` (`config.yaml` `learning.capabilities`).
+- `action` — `learn` (default) | `list` | `complete`.
+
+## On Activation (`action: learn`)
+
+### Step 1 — Resolve the connection and route
+Read `.sdlc/learning.json`:
+
+- **DeepTutor available** (`source: "deeptutor-cli"`): run the CLI with the mapped capability
+  (`explain→chat`, `deep→deep_research`, `quiz→deep_question`), grounded in the kb:
+  ```
+  deeptutor run <capability> "<concept> — in the context of <epic/stage + scoped artifact>" \
+    --kb <kb> --format json
+  ```
+  Parse the NDJSON: concatenate `content` events into the tutorial body; capture `session_id` from the
+  `done` event. `mode: quiz` issues a `deep_question` follow-up and records the comprehension signal.
+- **Harness-native** (`tool: "none"`, absent registry, or `source: "harness-native"`): tutor with the
+  harness model. Read the scoped epic's `epic.md` / `architecture.md` / `contract.md` and any connected
+  `code-context/<repo>/code-map.md`, and write a focused explanation grounded in them. No error — this is
+  the normal degraded path.
+
+Keep the tutorial focused (usually < 600 words): explain the concept, then tie it to **one concrete
+example from this project** (an artifact line, a contract field, a story).
+
+### Step 2 — Render the tutorial artifact (local-only)
+First ensure the product hub's `.gitignore` lists the learning-output paths (see Conventions — append the
+block only if absent, so the artifacts can never be committed or pushed). Then write the tutorial to
+`epics/EP-<slug>/learning/<member>--<concept-slug>.md` (or `.sdlc/learning/` when no epic is scoped).
+Front-matter the file with `member`, `concept`, `stage`, `tool`, and `requestedAt`.
+
+### Step 3 — Record in the learning ledger (append-only)
+Append to `epics/EP-<slug>/.sdlc/learning-records.json` (create the array if absent):
+
+```json
+{
+  "member": "alice",
+  "concept": "contract versioning",
+  "context": "why the architecture hash-locks the surface",
+  "stage": "architecture-review",
+  "mode": "explain",
+  "tool": "deeptutor",
+  "sessionId": "…",
+  "tutorial": "learning/alice--contract-versioning.md",
+  "comprehension": null,
+  "status": "in-progress",
+  "requestedAt": "<YYYY-MM-DD>",
+  "completedAt": null
+}
+```
+
+`tool` is `deeptutor` or `harness-native`. `comprehension` holds the quiz signal when `mode: quiz`,
+else `null`.
+
+### Step 4 — Present + confirm (record-only, NO gate)
+Show the tutorial and ask the member to confirm they've reviewed it. This is **record-keeping only** —
+there is no approval and no gate. The learner runs `action: complete` (below) when done.
+
+## Other actions
+
+- **`list`** — print the learning records for the scoped epic (or cross-project): who learned what, by
+  stage, with status. Read-only.
+- **`complete`** — mark a record `status: "learned"` and set `completedAt` (match on `member` + `concept`,
+  newest in-progress record). Record-only; advances nothing.
+
+## Hard rules
+
+- **Opt-in, never a gate.** `yad-learn` never moves `currentStep`, never records an approval, and never
+  blocks any step. Learning is additive.
+- **Read-only except the learning ledger.** It writes only `learning-records.json` + tutorial artifacts;
+  it never touches `state.json`, `approvals.json`, `comments.json`, or the contract lock.
+- **Local-only output.** The records ledger and tutorials are gitignored personal artifacts — never
+  commit or push them, and never write them into a code repo. Ensure the hub `.gitignore` covers them
+  before writing (see Conventions).
+- **Always works.** No DeepTutor / no connection → tutor harness-native. Never fail because a tool is
+  absent.
+- **Grounded.** Prefer the project's own artifacts/kb; a generic answer with no project tie-in is a last
+  resort, and say so when that happens.
+- **Attributable.** Every record names the `member` and `stage`, so the `yad-status` roll-up is a true
+  picture of the local learner's own skills log.
+
+## Reference
+- Record schema, the mode→capability map, and the harness-native degrade path:
+  `references/learning-state.md`.
+- The connection this consumes: `../yad-connect-learning/SKILL.md`.
+- The read-only roll-up: `../yad-status/SKILL.md` (the local skills-log section).

package/skills/yad-learn/references/learning-state.md

@@ -0,0 +1,75 @@
+# Learning state — record schema, capability map, degrade path
+
+How `yad-learn` records a learner's own learning, drives DeepTutor, and degrades. The records are the
+evidence base for the **local skills-log roll-up** in `yad-status`.
+
+## Location
+
+- Per-epic ledger: `epics/EP-<slug>/.sdlc/learning-records.json` (append-only JSON array).
+- Cross-project ledger (no epic scoped): `.sdlc/learning-records.json`.
+- Rendered tutorials: `epics/EP-<slug>/learning/<member>--<concept-slug>.md` (or `.sdlc/learning/`).
+
+(`config.yaml` `learning.records` and `learning.artifacts`.)
+
+**Local-only.** Every path above is personal output and is **gitignored — never committed or pushed**, to
+the product hub or any code repo. `yad-learn` ensures the hub `.gitignore` lists them before writing. The
+only committed learning file is the connection registry `.sdlc/learning.json`.
+
+## Record schema
+
+```json
+{
+  "member": "alice",                                 // the learner (default: invoking user)
+  "concept": "contract versioning",                  // what was learned
+  "context": "why the surface is hash-locked",        // optional focus
+  "stage": "architecture-review",                     // SDLC stage the learner was at; null if unscoped
+  "mode": "explain",                                  // explain | deep | quiz
+  "tool": "deeptutor",                                // deeptutor | harness-native
+  "sessionId": "…",                                   // DeepTutor session id; null when harness-native
+  "tutorial": "learning/alice--contract-versioning.md",
+  "comprehension": null,                              // quiz signal (e.g. "4/5") when mode: quiz, else null
+  "status": "in-progress",                            // in-progress | learned
+  "requestedAt": "2026-06-14",
+  "completedAt": null                                 // set by `action: complete`
+}
+```
+
+## Rules
+
+- **Append-only.** `learn` pushes a new record. `complete` mutates the newest in-progress record matching
+  `member` + `concept` (status → `learned`, set `completedAt`). Never rewrite history.
+- **Attributable.** `member` + `stage` are always set so the local roll-up is accurate.
+- **No secrets.** Records hold concept text + references only — never keys or raw tool output beyond the
+  rendered tutorial.
+- **Never commit the ledger or tutorials.** They are personal, local-only artifacts: gitignored, never
+  committed or pushed (to the hub or a code repo). Only `.sdlc/learning.json` is committed.
+
+## Mode → DeepTutor capability
+
+| mode | capability | invocation |
+|------|------------|------------|
+| `explain` | `chat` | `deeptutor run chat "<concept> — in context of <…>" --kb <kb> --format json` |
+| `deep` | `deep_research` | `deeptutor run deep_research "<…>" --kb <kb> --format json` |
+| `quiz` | `deep_question` | `deeptutor run deep_question "<…>" --kb <kb> --format json` → record `comprehension` |
+
+`--format json` is **NDJSON**: one event per line, each with `type` (`content` | `tool_call` |
+`tool_result` | `done`) and `session_id`. Concatenate `content` into the tutorial; read `session_id` from
+`done`.
+
+## Harness-native degrade
+
+When `.sdlc/learning.json` is absent, `tool: "none"`, or `source: "harness-native"`:
+
+1. Read the scoped epic's `epic.md` / `architecture.md` / `contract.md` and any
+   `code-context/<repo>/code-map.md`.
+2. Explain `concept` (+ `context`) grounded in what those say, with one concrete example from the project.
+3. Write the tutorial + record exactly as the DeepTutor path does, with `"tool": "harness-native"` and
+   `"sessionId": null`.
+
+The learning layer therefore **always works and always records** — DeepTutor only adds kb grounding,
+deep research, and quizzes.
+
+## Greenfield / no epic
+
+With no epic scoped, write to the cross-project ledger `.sdlc/learning-records.json` and tutorials to
+`.sdlc/learning/`. `yad-status` reads both the per-epic and cross-project ledgers for the local roll-up.

package/skills/yad-review-gate/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: yad-review-gate
-description: 'The reusable team review + approve gate for the SDLC. Shares an authored artifact for review, records reviewer comments and approvals as files, enforces the owner + 1 reviewer rule (escalating to domain owners on contract/auth/payments), and advances the epic state ONLY when approval is recorded. Use when the user says "review the analysis/epic/architecture/UI/stories", "comment", "approve", or "advance the gate".'
+description: 'The reusable team review + approve gate for the SDLC. Shares an authored artifact for review, records reviewer comments and approvals as files, enforces the owner + 1 reviewer rule (escalating to domain owners on contract/auth/payments), and advances the epic state ONLY when approval is recorded. Use when the user says "review the analysis/epic/architecture/UI/stories/test-cases", "comment", "approve", or "advance the gate".'
 ---
 
 # SDLC — Team Review Gate (build plan §3 piece 2, §4, §5)
 
 **Goal:** One reusable step type that turns any authored artifact into a gated, human-approved
 review. Every `review+approve` step in the workflow (the optional analysis, epic, architecture+contract,
-UI, stories) uses this exact gate. **No step advances until its review is approved** and recorded as a
-file. The `analysis-review` and `epic`/`ui-design` reviews use the **base** rule (owner + 1 reviewer);
-escalation applies only where `risk_tags` or per-repo routing call for it.
+UI, stories, test-cases) uses this exact gate. **No step advances until its review is approved** and
+recorded as a file. The `analysis-review`, `epic`/`ui-design`, and `test-cases` reviews use the **base**
+rule (owner + 1 reviewer); escalation applies only where `risk_tags` or per-repo routing call for it.
 
 This gate is **swappable and file-driven**: it talks only through files. A front step advances only on a
 human act — recording an approval and `advance`, or (with the bridge) **merging the approved,
@@ -87,7 +87,7 @@ counterpart to `approvals.json`):
 Then help the **owner address the comments** using the agent lens listed for this step
 (analysis → `analyst`; epic → `pm`; architecture → `architect`; ui-design → `ux-designer`;
 stories → `pm`, with `architect` for technical detail — there is **no `sm` agent**, Phase 0
-Deviation 1). Update the authored artifact in place.
+Deviation 1; test-cases → `test architect` / Murat, `bmad-tea`). Update the authored artifact in place.
 Repeat comment→address rounds until reviewers are satisfied. **Commenting never advances the gate.**
 
 **`approve`** — Record an approval. Append to `.sdlc/approvals.json`:
@@ -153,13 +153,16 @@ If the predicate **fails**: report exactly which approvals are still missing and
 
 If the predicate **passes**:
 - Mark this review step `status: "done"`.
-- If there **is** a next step in `steps[]`: set it `status` from `blocked` to `in_progress`
-  (authoring) or `in_review`, and set `currentStep` to that next step.
-- If this is the **last** step (`stories-review`, the final review): there is no further front step —
-  set `currentStep: "ready-for-build"` (the Phase 3 handoff sentinel; it is intentionally not a
-  `steps[]` entry). The front half is complete.
+- **`stories-review`** is the end of the gating chain: set `currentStep: "ready-for-build"` (the Phase 3
+  handoff sentinel; intentionally not a `steps[]` entry) **and** open the parallel **`test-cases`** track
+  (set its step `blocked` → `in_progress`). The build half can now start **and** the tester can work
+  `test-cases` at the same time.
+- **`test-cases-review`** is the parallel track's gate: mark it `done` but **leave `currentStep` at
+  `ready-for-build`** — completing test cases must never pull the epic back from the build half.
+- Any **other** review step: set the next step in `steps[]` from `blocked` to `in_progress` (authoring)
+  or `in_review`, and set `currentStep` to that next step.
 - Write `state.json`. Report the advance and what the next authored artifact is (or that the epic is
-  now `ready-for-build`).
+  now `ready-for-build`, with `test-cases` running in parallel).
 
 ### PR-driven automation (the `yad gate` CLI)
 When the hub has a platform, the mechanical `open`/`sync`/`advance` is performed deterministically by the

package/skills/yad-review-gate/references/gating.md

@@ -18,7 +18,7 @@ touched `domain`, `|domainOwners[domain]| >= 1`.
 - Stories review: the touched domains are the **union of every story's `repos`** under `stories/`.
 
 So one gate, two option-shapes:
-- Epic / UI reviews: base rule (no risk tags, no per-repo routing).
+- Epic / UI / test-cases reviews: base rule (no risk tags, no per-repo routing).
 - Architecture+contract review: escalated (`risk_tags: ["contract"]`) — owner + 1 reviewer + a
   `domain-owner` for **each** repo in `epic.repos`. (A small team may have one engineer own several
   repos — one person can supply several `domain-owner` records with different `domain` values.)

package/skills/yad-run/references/run-loop.md

@@ -57,7 +57,7 @@ if step in cfg.locked_steps:       eff = "human_approve"
 ```
 
 So a kill switch, a `locked` flag, or membership in `locked_steps` forces a stop no matter what the
-per-step dial says. `engineer-review` and the four front states are covered by `locked` / `locked_steps`.
+per-step dial says. `engineer-review` and the five front states are covered by `locked` / `locked_steps`.
 
 ## Deriving signals & the provisional verdict
 
@@ -115,7 +115,7 @@ Reverting (`to: human_approve`) is never gated — automation must be reversible
 ## What stays human, always
 
 - `engineer-review` — the merge gate. `yad-run` always stops here and hands to `yad-ship`.
-- The four front states (`epic`, `architecture`, `ui-design`, `stories`) — not in `back_steps`, in
-  `locked_steps`; the dial-setter refuses them.
+- The five front states (`epic`, `architecture`, `ui-design`, `stories`, `test-cases`) — not in
+  `back_steps`, in `locked_steps`; the dial-setter refuses them.
 - Any contract-surface change — halts the loop and routes back to the architecture gate, regardless of
   the dial.

package/skills/yad-spec/SKILL.md

@@ -43,7 +43,9 @@ is the same graceful-degradation pattern `yad-ui` uses for Impeccable.
 
 ### Step 1 — Resolve the story and check readiness
 Read `{project-root}/epics/<epic>/.sdlc/state.json`. Proceed only when
-`currentStep == "ready-for-build"` (the whole front half is `done`). Read the story file
+`currentStep == "ready-for-build"` (the gating front half — through the **stories** gate — is `done`).
+The **`test-cases` track may still be `in_progress`**: it is parallel and non-blocking, so the build
+half runs alongside it — its status does not affect readiness here. Read the story file
 `epics/<epic>/stories/<story>.md`; confirm `repo` is in its `repos`. If the epic is not ready, STOP
 and point the user at `yad-status`. **Do not mutate front-half state** — `ready-for-build` semantics
 stay intact.

package/skills/yad-status/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-status
-description: 'Read-only view of an SDLC epic: prints the current step, each step''s dials (assistance/automation) and status, and which approvals are still required at the active gate. For stories in the build half it also prints each back-half step''s automation dial, status, and trust record (runs / % approved-unchanged / whether it clears the threshold to be earned), plus the system-wide kill-switch state — so the team can see WHY a step is automated and reverse it with evidence. Surfaces the Phase 5 instrumentation signals: per-step "earned but manual" (nudge cost) and, across multiple epics, a fleet roll-up (scale of read). Use when the user says "yad status", "where is epic EP-...", "what is blocking the gate", "show the trust record", or "fleet status".'
+description: 'Read-only view of an SDLC epic: prints the current step, each step''s dials (assistance/automation) and status, and which approvals are still required at the active gate. For stories in the build half it also prints each back-half step''s automation dial, status, and trust record (runs / % approved-unchanged / whether it clears the threshold to be earned), plus the system-wide kill-switch state — so the team can see WHY a step is automated and reverse it with evidence. Also prints the cross-cutting personal skills-log roll-up from the LOCAL-ONLY learning ledger (gitignored, never committed/pushed — the local learner''s own learning, by stage). Surfaces the Phase 5 instrumentation signals: per-step "earned but manual" (nudge cost) and, across multiple epics, a fleet roll-up (scale of read). Use when the user says "yad status", "where is epic EP-...", "what is blocking the gate", "show the trust record", "team skills", or "fleet status".'
 ---
 
 # SDLC — Status (read-only)
@@ -22,20 +22,25 @@ report all if the user asked for an overview).
 Read `.sdlc/state.json`, `.sdlc/approvals.json`, `epic.md` frontmatter (for `repos`), and — if present
 — `.sdlc/contract-lock.json`. For the build half (Phase 4), also read — if present — every
 `.sdlc/build-state/<story-id>.json`, `.sdlc/trust-log.json`, and the `automation` block of
-`skills/sdlc/config.yaml` (`back_steps`, `trust_threshold`, `locked_steps`, `kill_switch`). Do not
-modify any of them.
+`skills/sdlc/config.yaml` (`back_steps`, `trust_threshold`, `locked_steps`, `kill_switch`). For the
+cross-cutting learning layer, also read — if present — the **local-only** `.sdlc/learning-records.json`
+(the per-epic learning ledger, gitignored) and the project-wide `{project-root}/.sdlc/learning-records.json`.
+Do not modify any of them.
 
 ### Step 3 — Report
 Print, in this order:
 
 1. **Epic:** `epicId`, `status` from `epic.md` frontmatter, `currentStep`, and `repos` (the touched
    domains).
-2. **Steps table** — for every front step in `steps[]` order (8, or 10 when the optional analysis step
+2. **Steps table** — for every front step in `steps[]` order (10, or 12 when the optional analysis step
    was run): `id`, `type`, `status`, `assistance`, `automation`, `locked`, and `risk_tags`. Mark the
-   `currentStep` with `→`. The full front-state chain is `[analysis → analysis-review →] epic →
-   epic-review → architecture → architecture-review → ui-design → ui-design-review → stories →
-   stories-review` (then `ready-for-build`); the bracketed `analysis` prefix is present only when
-   `yad-analysis` seeded it. Always render exactly the steps present in `steps[]`.
+   `currentStep` with `→`. The gating chain is `[analysis → analysis-review →] epic → epic-review →
+   architecture → architecture-review → ui-design → ui-design-review → stories → stories-review` →
+   **`ready-for-build`** (the bracketed `analysis` prefix is present only when `yad-analysis` seeded it).
+   `test-cases → test-cases-review` is a **parallel, non-blocking track**: it opens when `stories-review`
+   passes and runs alongside the build half, so when `currentStep` is `ready-for-build` the `test-cases`
+   step may still be `in_progress`/`in_review` — show its status, and note "parallel" so it is clear it
+   does not gate the build. Always render exactly the steps present in `steps[]`.
 3. **Active gate** — for the `currentStep` (if it is a `review+approve` step), compute and show:
    - the reviewer rule in force — **base** (`owner + 1 reviewer`), **escalated** (list the required
      domains), or **per-repo** for `stories-review` (list each repo needing sign-off),
@@ -79,13 +84,28 @@ Print, in this order:
    recommendation to flip — earning the evidence and flipping the dial stay deliberate human acts
    (`yad-run action: set-dial`). See `docs/phase-5-build-plan.md` §"What to instrument now".
 
-9. **Fleet roll-up (overview only).** When the user asked for an overview, or more than one epic exists
-   under `{project-root}/epics/`, print a one-line-per-epic roll-up across the fleet: each epic's
-   `currentStep` (front gate) and, for stories in the build half, a count of back-half steps **waiting
-   at a human gate** and of steps flagged **earned-but-manual**. Close with fleet totals (epics at each
-   front gate; total earned-but-manual back steps). This is the *scale-of-read* signal the Phase 5
-   trigger watches — when this roll-up stops fitting in one glance, that is the measured bottleneck.
-   Still strictly read-only; it only scans the per-epic files.
+9. **My skills (the learning layer — local-only).** If `.sdlc/learning-records.json` exists for the epic
+   (or the project-wide ledger does), print the **personal skills-log** roll-up from it — read-only. These
+   records are **local-only (gitignored, never committed or pushed)**, so this reflects only the local
+   learner's own learning, not the team's. Show:
+   - **By member:** each `member` present in the local ledger with the concepts they have `learned` and
+     those `in-progress` (count + names).
+   - **By stage:** how many learning requests landed at each SDLC `stage` (e.g. `architecture-review: 3`),
+     so heavy-learning stages stand out.
+   - **Tool:** whether tutoring ran on `deeptutor` (grounded in the kb) or `harness-native`, per the
+     records' `tool` field.
+   This section is purely informational — learning is opt-in and never gates a step (it is produced by
+   `yad-learn`). If no learning ledger exists, omit the section silently (greenfield/learning not used).
+
+10. **Fleet roll-up (overview only).** When the user asked for an overview, or more than one epic exists
+    under `{project-root}/epics/`, print a one-line-per-epic roll-up across the fleet: each epic's
+    `currentStep` (front gate) and, for stories in the build half, a count of back-half steps **waiting
+    at a human gate** and of steps flagged **earned-but-manual**, plus a **local skills-log** count (records
+    in the local-only `learning-records.json`: learned / in-progress). Close with fleet totals (epics at
+    each front gate; total earned-but-manual back steps; total concepts learned locally across the fleet).
+    This is the
+    *scale-of-read* signal the Phase 5 trigger watches — when this roll-up stops fitting in one glance,
+    that is the measured bottleneck. Still strictly read-only; it only scans the per-epic files.
 
 ### Hard rule
 This skill is strictly read-only. If the user wants to comment, approve, or advance, point them to

package/skills/yad-stories/SKILL.md

@@ -97,7 +97,9 @@ In `state.json`: set `stories.status: "done"`, set `stories-review.status: "in_r
 ### Step 7 — Stop at the gate (do NOT advance)
 Report: the story IDs created, the repos each touches, and that the next action is **review** via
 `yad-review-gate`. Note that this review routes **per-repo reviewers**: owner + 1 reviewer **plus**, for
-each repo appearing in any story's `repos`, a `domain-owner` approval for that repo. **Never record
+each repo appearing in any story's `repos`, a `domain-owner` approval for that repo. When this gate
+passes the epic becomes **`ready-for-build`** — the build half can start **and** the parallel
+**`test-cases`** track opens for the tester (`yad-test-cases`); the two run at the same time. **Never record
 approval here.** Front states do not auto-advance. When the hub has a platform, the gate opens a review
 PR on the hub (via `yad-hub-bridge`, with a `domain:<repo>` label per touched repo) and
 `yad-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review

package/skills/yad-test-cases/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: yad-test-cases
+description: 'Front state 9 of the gated SDLC — a PARALLEL, non-blocking track. Opens when the stories gate passes (the epic is already ready-for-build, so the build half can start at the same time) and runs alongside implementation. With the test architect (Murat), author test-cases.md for the approved stories, and — when a testing tool is connected — generate/link the actual automation tests in it; otherwise produce the test-case artifact only. Reads epic + architecture + contract + UI + stories as input. Never auto-advances — hands off to the team review gate. Use when the user says "author the test cases" or after the stories gate passes.'
+---
+
+# SDLC — Author Test Cases (front state 9 — parallel, non-blocking)
+
+**Goal:** Produce a human-authored, AI-assisted `test-cases.md` for an approved epic — the risk-based
+test cases that cover the stories' acceptance criteria — **and**, when a testing tool is connected, the
+**actual automation tests** inside the connected code repo(s), linked back from the artifact. This is a
+**front state**: human-authored with AI assist, **never auto-advances**. When the test cases are
+drafted, control passes to `yad-review-gate` (base rule: owner + 1 reviewer).
+
+**This step does NOT block the build half.** It opens when the **stories** gate passes — at which point
+the epic is already `ready-for-build`, so implementation (`yad-spec` → `yad-implement` → …) can start
+**at the same time** the tester works here. The test-cases track is driven by its own step `status`
+(it opens to `in_progress` when `stories-review` passes) and its review **never moves `currentStep`
+away from `ready-for-build`**, so the two run in parallel.
+
+Test work is shaped by the **test architect** lens — **Murat** (`bmad-tea`), driving
+`bmad-testarch-test-design` for the cases and `bmad-testarch-automate` for the automation. The
+automation is materialized in the **testing tool connected via `yad-connect-testing`**
+(`.sdlc/testing.json`), reached through its MCP. When a tool is connected the lens **generates** tests
+into it (or **links** an existing suite and reads it back); when none is connected, the step degrades to
+the Markdown artifact only — the testing tool is additive, exactly like the design tool.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory.
+- Artifacts live under `{project-root}/epics/EP-<slug>/` (build plan §6).
+- The connected testing tool is recorded in `{project-root}/.sdlc/testing.json` (`config.yaml`
+  `testing`), written by `yad-connect-testing`. The per-epic case→test map is `test-links.json`
+  (Step 4b).
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## On Activation
+
+### Step 1 — Resolve the epic and check the track
+Resolve the `EP-<slug>` (ask if not provided). Read `.sdlc/state.json`. Only proceed when the
+**`test-cases` step's `status == "in_progress"`** — it opens when `stories-review` passes (the epic is
+already `ready-for-build` by then; `currentStep` stays there because this is a parallel track, so do
+**not** gate on `currentStep`). If `test-cases` is still `blocked`, the stories review has not passed —
+stop and point the user at `yad-status` / the gate.
+
+### Step 1b — Open the authoring branch
+Open the test-cases authoring branch `test-cases/EP-<slug>` 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 `test-cases.md` on it. This is **distinct** from the bridge's
+`review/…` branch.
+
+### Step 2 — Read inputs
+Read `epic.md` (user-level acceptance signals, scope), `architecture.md` (flows, components by repo),
+`contract.md` (the shared surface under test), `ui-design.md` (screens/states the tests exercise), and
+**all** approved `stories/EP-<slug>-S0N.md`. Each story's **acceptance criteria are the source of truth**
+for the cases — the test cases must collectively verify every story's criteria.
+
+### Step 2b — Load existing-code context (make the brain code-aware)
+Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **each repo in
+`epic.repos`**, load the code-map `{project-root}/.sdlc/code-context/<repo>/code-map.md` so the
+automation **targets real existing endpoints/components and reuses existing fixtures** rather than
+inventing parallel ones.
+
+- **Greenfield-safe:** if `repos.json` is absent/empty, note "no repos connected" and proceed.
+- **Staleness:** if a repo's current HEAD ≠ its registry `syncedHead`, warn and suggest
+  `yad repo refresh <repo>` (a human decision — flag and stop, never auto-refresh); stamp
+  `code-context: stale` in the frontmatter.
+- **Traceability:** record the loaded maps in the `test-cases.md` `code-context:` frontmatter field.
+
+### Step 3 — Author the test cases (assist: test architect)
+Adopt the **test architect** lens (`bmad-tea`, Murat), driving `bmad-testarch-test-design`. For each
+story / user flow shape risk-based test cases:
+
+- **Risk assessment** — categorize and score what can fail (probability × impact); depth scales with
+  impact (Murat's "risk-based testing" principle).
+- **Coverage plan** — assign each case a priority **P0 (critical) / P1 (high) / P2 (medium) / P3 (low)**
+  and a level, preferring the lowest useful level (unit > integration > E2E).
+- **Entry/exit criteria** and any **NFR** thresholds (security, performance, reliability) in scope.
+- Each case: a stable label, the story it covers, preconditions, steps, and expected result.
+
+### Step 3b — Materialize the automation in the connected tool (generate or link)
+Read `{project-root}/.sdlc/testing.json` (`config.yaml` `testing.registry`). Decide the path:
+
+- **No tool / `tool: "none"` / `source: "unavailable"`** (or the file is absent): **degrade** — author
+  the Markdown artifact only and record `testing: none` in the frontmatter with a one-line note
+  (mirrors the `design: none` degrade). Skip to Step 4.
+- **A tool is connected and its MCP is available:** adopt the `test architect` lens and, using the
+  provider recorded in `testing.json` (Playwright via a Playwright MCP, Cypress/pytest via theirs) drive
+  `bmad-testarch-automate`:
+  - **Generate** — when the provider is write-capable, author one automation test per high-priority
+    (P0/P1) case into the connected code repo(s) for the repos in `epic.repos`, reusing the code-maps
+    (Step 2b) and existing fixtures so tests target built endpoints/components, then run them via the MCP
+    to confirm they execute.
+  - **Link** — when the user points at an existing suite (or the provider is read-only), reference it and
+    **read the tests back** so `test-cases.md` reflects the real suite.
+
+  Capture each test's `name`, `repo`, `level`, `path`, and `url`. Record which direction was used
+  (`generated | linked`). Honest-capability rule: a read-only MCP supports **link** only — never claim a
+  test was generated that the provider cannot produce. See
+  `../yad-connect-testing/references/testing-context.md`.
+
+### Step 4 — Write the test-cases artifact
+Write `{project-root}/epics/EP-<slug>/test-cases.md` using EXACTLY this template:
+
+```markdown
+---
+id: EP-<slug>
+epic: EP-<slug>
+artifact: test-cases
+status: draft
+owner: <inherit from epic.md owner>   # the epic owner carries through; not retyped
+repos: [<inherit from epic>]
+code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # code-maps that informed the tests (Step 2b)
+testing: <none | { tool: <playwright|cypress|pytest|…>, direction: <generated|linked>, suite: <url/path>, tests: <N> }>   # the connected testing tool (Step 3b)
+---
+
+## Test strategy & risk
+<!-- risk assessment (category, probability, impact, score), entry/exit criteria, NFR thresholds in scope -->
+
+## Test cases
+<!-- one row/subsection per case: id, story covered, priority (P0–P3), level, preconditions, steps, expected -->
+
+## Coverage & traceability
+<!-- story -> case map; confirm every story's acceptance criteria are covered -->
+
+## Automation (<tool>)
+<!-- omit this section when testing: none. one row per automation test, linking to it in the repo.
+     mirrors test-links.json (Step 4b). -->
+<!-- - <Case id> -> <repo>:<test path> (<level>) — <url> -->
+```
+
+### Step 4b — Write the test-links map (when a tool was used)
+When Step 3b generated or linked automation, write the machine-readable case→test map to
+`{project-root}/epics/EP-<slug>/.sdlc/test-links.json` (sibling of `contract-lock.json` /
+`design-links.json`):
+
+```json
+{
+  "tool": "playwright",
+  "suite": "tests/playwright.config.ts",
+  "generatedAt": "<YYYY-MM-DD>",
+  "direction": "generated | linked",
+  "tests": [
+    { "case": "TC-01", "story": "EP-<slug>-S01", "repo": "backend", "level": "e2e",
+      "path": "tests/inquiry.spec.ts", "url": "<repo url to the test>" }
+  ],
+  "source": "playwright-mcp"
+}
+```
+
+Keep the `## Automation (<tool>)` section of `test-cases.md` in step with this file. When Step 3b
+degraded (`testing: none`), do **not** write `test-links.json`.
+
+### Step 5 — Advance the authoring step (NOT the gate)
+In `state.json`: set `test-cases.status: "done"` and set `test-cases-review.status: "in_review"`. **Leave
+`currentStep` at `ready-for-build`** — this is the parallel track; moving `currentStep` would pull it
+back from the build half. Write `state.json`. Do **not** touch `approvals.json`.
+
+### Step 6 — Stop at the gate (do NOT advance)
+Report: the path to `test-cases.md`, the connected testing tool and what it produced (e.g. "Playwright —
+6 tests generated", the suite path + `test-links.json` path, or "no testing tool — artifacts-only"), that
+the build half may already be underway in parallel, and that the next action is **review** via
+`yad-review-gate` (base rule: owner + 1 reviewer). **Never record approval here.** Front states do not
+auto-advance. 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.
+
+## Reference
+- Test-cases frontmatter, body template, and the `test-links.json` schema: `references/test-cases-schema.md`.
+- State schema and field meanings: `../yad-epic/references/state-schema.md`.
+- Connecting a testing tool (Playwright, pluggable) + generate-vs-link recipes and the degrade path:
+  `../yad-connect-testing/SKILL.md` (+ `references/testing-context.md`).
+- Connecting code repos + the code-context the brain reads: `../yad-connect-repos/SKILL.md`.