yadflow 2.2.0 → 2.4.0

package/skills/yad-connect-learning/references/learning-context.md

@@ -0,0 +1,79 @@
+# Learning context — CLI detection, knowledge-base build, capability map, degrade path
+
+How `yad-connect-learning` reaches DeepTutor, grounds it in the project, and how `yad-learn` consumes the
+connection. DeepTutor is a **CLI subprocess** (Apache-2.0, `pip install -U deeptutor`) — it ships **no
+MCP server**, so this adapter detects a **binary on PATH**, the same shape as Repomix's `npx` in
+`yad-connect-repos`/`yad-backfill`, not the MCP shape of the design/testing tools.
+
+## CLI detection
+
+Best-effort, never fatal:
+
+```
+deeptutor --version        # success => provider: "deeptutor-cli", capture the version
+deeptutor config show      # fallback probe if --version is unavailable
+```
+
+- Binary found → `source: "deeptutor-cli"`.
+- Binary absent → `source: "harness-native"` (no error). Report that `yad-learn` will tutor via the
+  harness model reading the project artifacts.
+
+DeepTutor's own setup (`deeptutor init`, LLM provider keys under `data/user/settings/`) is the **user's**
+responsibility and lives outside this repo. The skill never runs `deeptutor init` and never writes keys.
+
+## Knowledge-base build (grounding)
+
+When `ground: true` and the CLI is present, build/refresh a project knowledge base so tutoring quotes
+what is actually being built:
+
+```
+deeptutor kb create <kb>             # idempotent — reuse if it already exists
+deeptutor kb add <kb> --doc <path>   # once per source path below
+deeptutor kb list                    # verify
+```
+
+Ingest only **committed, secret-scanned** sources (never raw repos):
+
+- Per epic under `epics/EP-<slug>/`: `epic.md`, `architecture.md`, `contract.md`, `ui-design.md`, and the
+  `stories/*.md` files.
+- Per connected repo: `.sdlc/code-context/<repo>/code-map.md` (already secret-scanned by
+  `yad-connect-repos`). Do **not** add `pack.md` or the raw repo.
+
+Record `kb` and `kb_sources` in the registry. If there are no artifacts yet (greenfield), skip and record
+`kb: null` — `yad-learn` falls back to passing context inline.
+
+## Mode → capability map (consumed by `yad-learn`)
+
+`config.yaml` `learning.capabilities` maps a `yad-learn` mode to a DeepTutor capability:
+
+| `yad-learn` mode | DeepTutor capability | use |
+|------------------|----------------------|-----|
+| `explain` (default) | `chat` | a focused, grounded explanation of the concept |
+| `deep` | `deep_research` | a deeper, multi-source dive |
+| `quiz` | `deep_question` | generate questions to confirm comprehension (records a signal) |
+
+`yad-learn` invokes:
+
+```
+deeptutor run <capability> "<concept> — in the context of <scoped artifact/stage>" \
+  --kb <kb> --format json
+```
+
+`--format json` streams **NDJSON** — one event per line with a `type` (`content` | `tool_call` |
+`tool_result` | `done`) and a `session_id`. `yad-learn` concatenates `content` events into the tutorial
+and captures `session_id` from the `done` event for the learning record.
+
+## Degrade path (harness-native)
+
+When `source: "harness-native"` (no CLI, or `tool: "none"`), `yad-learn` does **not** fail. It tutors
+using the **harness model itself**: it reads the scoped epic's `epic.md` / `architecture.md` /
+`contract.md` / code-maps and explains the concept grounded in them. The local-only learning record is
+written identically (with `"tool": "harness-native"`), so the learning layer always works and always
+records — DeepTutor only adds knowledge-base grounding, deep research, and quizzes.
+
+## Freshness
+
+Like the code-context cache, the knowledge base can drift from the artifacts. `refresh` rebuilds it from
+the current committed artifacts and moves `lastSyncedAt`. Rebuilding is a human decision (run `connect`/
+`refresh`); `yad-learn` never silently rebuilds the kb mid-tutorial — at most it notes the kb may be
+stale and proceeds.

package/skills/yad-connect-learning/references/learning-registry.md

@@ -0,0 +1,60 @@
+# Learning registry — schema + freshness rule
+
+The registry is the product hub's record of which learning tool is connected and how to reach it. It is
+**project-wide** (one learning tool per project, shared across every epic), so it lives at the product
+root, not under any `epics/EP-<slug>/.sdlc/`.
+
+## Location
+
+`{project-root}/.sdlc/learning.json`
+
+(`config.yaml` `learning.registry`.) Create the file and its parent `.sdlc/` on the first `connect`.
+
+## Schema
+
+```json
+{
+  "tool": "deeptutor",                               // deeptutor | <adapter id> | none (harness-native)
+  "provider": "deeptutor-cli",                       // the concrete CLI: deeptutor-cli | null
+  "version": "1.4.5",                                // CLI version reported at detect time; null if absent
+  "kb": "yadflow-istifta",                           // grounded knowledge-base name; null if not built
+  "kb_sources": ["epic.md", "architecture.md", "contract.md", "ui-design.md", "stories/", "code-context/*/code-map.md"],
+  "auth": "user",                                    // ALWAYS the user's own DeepTutor config / LLM keys — never a token
+  "connectedAt": "2026-06-14",                       // first connect (YYYY-MM-DD)
+  "lastSyncedAt": "2026-06-14",                       // last connect/refresh
+  "source": "deeptutor-cli"                          // deeptutor-cli (CLI on PATH) | harness-native (degraded)
+}
+```
+
+## Rules
+
+- **`tool`** selects the adapter; it MUST be one of `config.yaml` `learning.tools` (or `none`). At
+  **connect** time an unknown tool is normalized to `learning.primary` with a warning (so the registry
+  never persists an unknown value); a registry hand-edited to an unknown or missing tool **fails
+  `doctor`** with `YAD-CFG-004` and must be fixed.
+- **Auth is never stored.** No LLM key, token, or any credential in the registry. `kb`/`kb_sources` are
+  plain references; DeepTutor is reached through the user's own `deeptutor` config.
+- **`connect` overwrites in place** — a project carries exactly one learning connection at a time;
+  switching tools is just another `connect`. There is no array (unlike `repos.json`). The original
+  `connectedAt` is preserved across re-connects; only `lastSyncedAt` moves.
+- **`source`** is the authority for availability: `deeptutor-cli` means `yad-learn` can drive the CLI
+  (grounded in `kb`); `harness-native` means `yad-learn` tutors via the harness model reading the
+  artifacts directly. `refresh` re-detects and may flip it.
+- **`ground` is not persisted.** The `ground: true|false` input only governs whether the AI connect
+  step builds/refreshes the knowledge base at connect time; the registry records the *result* (`kb` +
+  `kb_sources`), never the flag itself.
+- **`tool: "none"`** is a valid, deliberate state: a project that has chosen harness-native tutoring.
+  `yad-learn` treats it exactly like an absent registry — it still tutors, just without DeepTutor.
+- **`disconnect`** removes the file (or sets `tool: "none"`). DeepTutor's own config and knowledge bases
+  are never touched.
+
+## Git tracking
+
+Commit the **registry** (`learning.json`) — it is small, reviewable, and holds no secrets (references
+only). This mirrors how `repos.json`, `hub.json`, `design.json`, and `testing.json` are committed.
+
+## Greenfield
+
+A brand-new product hub has no `learning.json`. That is valid — `yad-learn` treats "no learning tool
+connected" the same as `tool: "none"` and tutors harness-native. The registry appears the first time
+`connect` runs.

package/skills/yad-connect-testing/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: yad-connect-testing
+description: 'Connects a testing tool (Playwright, or another tool — pluggable) to the product hub so the test-cases step can implement the actual automation tests, not just Markdown test cases. Registers the tool into the project-wide .sdlc/testing.json (local-user / MCP-session auth, no stored tokens), detecting whether a testing-tool MCP is available and degrading to artifacts-only when it is not. Run at setup or any time the testing tool changes. Reusable, idempotent, refreshable. Use when the user says "connect Playwright", "connect a testing tool", "refresh the testing connection", or "list the testing connection".'
+---
+
+# SDLC — Connect a Testing Tool (make the test-cases step automation-aware)
+
+**Goal:** Let the test-cases step (`yad-test-cases`) produce the **actual automation tests** — the
+runnable specs in a connected code repo — alongside the Markdown artifact (`test-cases.md`). This skill
+**connects** a testing tool such as **Playwright** to the product hub and records *how* to reach it (the
+tool, the suite references, which MCP runs it) — never a credential.
+
+This is **setup/maintenance**, not a gated front state — it never touches `.sdlc/state.json` or any
+epic's approvals. It only writes the project-wide testing registry. `yad-test-cases` consumes it: when a
+tool is connected and its MCP is available, the `test architect` lens **generates** automation tests
+into the connected repo(s) (or **links** an existing suite and reads it back); when nothing is
+connected, `yad-test-cases` runs artifacts-only exactly as before.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory (the **product hub**).
+- The integration is **Playwright-first but pluggable** (`config.yaml` `testing.tools`): a testing-tool
+  *adapter*, like the GitHub/GitLab platform adapter or the design-tool adapter. Playwright is the
+  primary provider; `cypress` and `pytest` are second providers; `none` → artifacts-only.
+- **The testing tool is reached through its MCP** (a harness MCP server), NOT a subprocess CLI — the
+  same shape as the design tool's MCP, not Repomix's `npx`. The skill detects the MCP and degrades when
+  it is absent; it never installs an MCP server.
+- Registry: `{project-root}/.sdlc/testing.json` (project-wide, shared across all epics — NOT per-epic),
+  the sibling of `.sdlc/repos.json`, `.sdlc/hub.json`, and `.sdlc/design.json`.
+- Per-epic test→suite links are written later by `yad-test-cases`
+  (`epics/EP-<slug>/.sdlc/test-links.json`), not here.
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## Inputs
+
+- `action` — `connect` (default) | `refresh` | `list` | `disconnect`.
+- `tool` — `playwright` | `cypress` | `pytest` | another adapter id (`config.yaml` `testing.tools`).
+  `none` records a deliberate artifacts-only project.
+- `project_url` — the testing tool's project/config reference (e.g. a `playwright.config.ts` path or a
+  test-runner project URL). Optional — a connection with no suite yet is valid; `yad-test-cases` can
+  create one on first generate.
+- `suites` — optional default suite mapping per repo (`{ <repo>: <ref> }`).
+
+## On Activation
+
+### Step 1 — Resolve the tool and its MCP (the testing-tool adapter)
+Determine which tool is being connected from `tool` (default `playwright`); reject a `tool` not in
+`config.yaml` `testing.tools` (fall back to the configured `testing.primary` with a warning, the same
+way `registerRepo` falls back on an unknown platform). Then **detect the tool's MCP** in this harness:
+
+- **playwright** → a Playwright MCP server (drives a browser, generates/runs E2E + API specs).
+- **cypress** → the Cypress MCP (generate/run Cypress specs).
+- **pytest** → a pytest MCP (generate/run service-layer tests).
+- another adapter → its named MCP.
+
+Record `provider` (the concrete MCP, e.g. `playwright-mcp` | `cypress-mcp` | `pytest-mcp`) and whether
+it is available. **Auth is the local user's own** — the user's authenticated MCP session. The skill
+**stores no tokens**; `project_url`/`suites` are plain references, never credentials.
+
+**Graceful degradation:** if no testing-tool MCP is available, record `source: "unavailable"` and report
+that `yad-test-cases` will run **artifacts-only** until an MCP is connected (no error — the testing tool
+is purely additive, exactly like the design tool being absent). Do **not** install an MCP server as part
+of this step.
+
+### Step 2 — Record the connection in the registry
+Upsert into `{project-root}/.sdlc/testing.json` (create the file + parent `.sdlc/` if absent):
+
+```json
+{
+  "tool": "playwright",
+  "provider": "playwright-mcp",
+  "project_url": "tests/playwright.config.ts",
+  "auth": "user",
+  "suites": { "backend": null, "mobile": null },
+  "connectedAt": "<YYYY-MM-DD>",
+  "lastSyncedAt": "<YYYY-MM-DD>",
+  "source": "playwright-mcp"
+}
+```
+
+- `tool: "none"` records a deliberate artifacts-only project: `{ "tool": "none", "provider": null,
+  "source": "unavailable", ... }`.
+- `connect` is **idempotent** — re-running it overwrites the single connection in place (a project has
+  one testing tool at a time; switching tools is just another `connect`).
+
+### Step 3 — Report (never auto-advance)
+Report the connected `tool`, its `provider`, whether the MCP is available (or that `yad-test-cases` will
+degrade to artifacts-only), the `project_url`, and that **`yad-test-cases` will now generate/link the
+automation tests here**. Nothing auto-advances; this is setup.
+
+## Other actions
+
+- **`refresh`** — re-detect the MCP and update `lastSyncedAt` (after the user authenticates a session or
+  changes tools). Same machinery as `connect`. Re-detection may flip `source` between an MCP id and
+  `unavailable` — report the change.
+- **`list`** — print the current connection: `tool`, `provider`, `project_url`, the suite mapping, and a
+  **available/unavailable** flag for the MCP (best-effort, the user's own session). No testing tool
+  connected ⇒ "artifacts-only".
+- **`disconnect`** — remove the registry file (or set `tool: "none"`). The testing tool's own
+  project/suites are **never touched** — only the hub's record of them.
+
+## Hard rules
+
+- **Local-user / MCP-session auth only; store no tokens.** Connect through the user's authenticated MCP
+  session; never embed a token or any credential in the registry. `project_url`/`suites` are plain
+  references.
+- **Degrade gracefully.** No testing tool / no MCP → `yad-test-cases` runs artifacts-only with no error.
+  The testing tool is additive, never a blocker — the same discipline as the design tool and Impeccable.
+- **Setup, not a gate.** Never touch `.sdlc/state.json`, approvals, or the contract lock from here.
+- **Idempotent + refreshable.** `connect`/`refresh` are safe to re-run; a project carries one testing
+  connection at a time.
+- **Describe the connection; do not author tests here.** This skill records *how to reach* the tool. The
+  actual automation tests are generated/linked by `yad-test-cases`, per epic.
+
+## Reference
+- Registry schema + freshness rule: `references/testing-registry.md`.
+- MCP detection per provider, the generate-vs-link recipes, the degrade path, and the honest
+  write-vs-read-only MCP capability note: `references/testing-context.md`.
+- The connect pattern this mirrors (design tool): `../yad-connect-design/SKILL.md`.
+- The consumer — how `yad-test-cases` generates/links and writes `test-links.json`:
+  `../yad-test-cases/SKILL.md`.

package/skills/yad-connect-testing/references/testing-context.md

@@ -0,0 +1,67 @@
+# Testing context — MCP detection, generate vs link, and the degrade path
+
+How a connected testing tool turns into the actual automation tests the test-cases step materializes.
+The testing tool is reached through its **MCP** (a harness MCP server), the same shape as the design
+tool — detect it, use it when present, degrade cleanly when absent. This is the testing-side analogue of
+`yad-connect-design`'s design-context.
+
+## Provider detection
+
+`connect`/`refresh` records `provider` (the concrete MCP) and `source` (the MCP id, or `unavailable`).
+Detection is best-effort against the user's own authenticated MCP session:
+
+| `tool` | MCP / provider | Capability |
+|--------|----------------|------------|
+| `playwright` | a Playwright MCP | **generate** — author + run E2E/API specs against the app |
+| `cypress` | the Cypress MCP | **generate** — author + run Cypress specs |
+| `pytest` | a pytest MCP | **generate** — author + run service-layer tests |
+| any | a read-only runner MCP | **link** — reference an existing suite and read results back |
+| other | the adapter's named MCP | per that adapter |
+
+**Honest capability note:** not every testing-tool MCP can *write* tests. A read-only runner MCP
+supports **link + read-back** only; *generate* needs a write-capable provider. `yad-test-cases` picks
+the direction the connected provider actually supports and records which one it used
+(`direction: generated | linked`). It never claims to have generated tests a read-only MCP cannot
+produce.
+
+## Generate (write automation tests into the repo)
+
+When the connected provider is write-capable, the `test architect` lens (Murat, `bmad-tea` +
+`bmad-testarch-automate`) produces the epic's automation tests in the connected code repo(s), covering
+the cases `test-cases.md` enumerates and the acceptance criteria the stories define:
+
+- **Playwright** — the lens authors `*.spec.ts` E2E/API specs (reusing the repo's existing fixtures and
+  the code-maps from `yad-test-cases` Step 2b), one spec per high-priority (P0/P1) case, and runs them
+  via the MCP to confirm they execute.
+- **Cypress / pytest** — the lens authors the equivalent specs in that framework's layout.
+
+Reuse what already exists: load the connected code repos' code-maps (`yad-test-cases` Step 2b) so
+generated tests target real endpoints/components, not invented ones, and prefer the lowest useful test
+level (unit > integration > E2E) per Murat's principles.
+
+## Link (reference an existing suite)
+
+When a suite already exists (or the provider is read-only), point `yad-test-cases` at it and **read the
+suite back** so `test-cases.md` reflects the real tests: list each test as a case, capture its
+path/name + URL, and map it to the story it covers.
+
+## Write back the linkage (done by `yad-test-cases`, per epic)
+
+Either direction ends by writing `epics/EP-<slug>/.sdlc/test-links.json` — the machine-readable
+case→test map — and a `## Automation (<tool>)` section in `test-cases.md` linking each case to its test.
+The tests themselves live in the code repo; the hub keeps the *links* and the Markdown spec beside the
+other epic artifacts.
+
+## Degrade path (no MCP / no tool)
+
+If `testing.json` is absent, `tool: "none"`, or `source: "unavailable"`, `yad-test-cases` runs
+**artifacts-only**: it authors `test-cases.md` exactly as before and records `testing: none` in the
+frontmatter with a one-line note (mirroring the `design: none` degrade). No error — the testing tool is
+purely additive.
+
+## Staleness / refresh
+
+A re-generated or hand-edited suite is like a moved code repo: `yad-test-cases` **flags** a divergence
+and lets a human decide (re-run the step, or `yad-connect-testing` action: refresh). It never silently
+overwrites a hand-written suite — refreshing the automation is a human decision, the same discipline as
+`code_context.refresh: human`.

package/skills/yad-connect-testing/references/testing-registry.md

@@ -0,0 +1,55 @@
+# Testing registry — schema + freshness rule
+
+The registry is the product hub's record of which testing tool is connected and how to reach it. It is
+**project-wide** (one testing tool per project, shared across every epic), so it lives at the product
+root, not under any `epics/EP-<slug>/.sdlc/`.
+
+## Location
+
+`{project-root}/.sdlc/testing.json`
+
+(`config.yaml` `testing.registry`.) Create the file and its parent `.sdlc/` on the first `connect`.
+
+## Schema
+
+```json
+{
+  "tool": "playwright",                              // playwright | cypress | pytest | <adapter id> | none (artifacts-only)
+  "provider": "playwright-mcp",                      // the concrete MCP: playwright-mcp | cypress-mcp | pytest-mcp | null
+  "project_url": "tests/playwright.config.ts",       // project/config reference; null if none yet
+  "auth": "user",                                    // ALWAYS the user's own MCP session — never a token
+  "suites": { "backend": null, "mobile": null },     // optional default suite refs per repo
+  "connectedAt": "2026-06-13",                       // first connect (YYYY-MM-DD)
+  "lastSyncedAt": "2026-06-13",                       // last connect/refresh
+  "source": "playwright-mcp"                          // the MCP detected at connect | unavailable (degraded)
+}
+```
+
+## Rules
+
+- **`tool`** selects the adapter; it MUST be one of `config.yaml` `testing.tools` (or `none`). At
+  **connect** time an unknown tool is normalized to `testing.primary` with a warning (so the registry
+  never persists an unknown value); a registry hand-edited to an unknown or missing tool **fails
+  `doctor`** with `YAD-CFG-003` and must be fixed.
+- **Auth is never stored.** No token, API key, or any credential in the registry. `project_url` and
+  `suites` are plain references; `connect` reaches the tool through the user's authenticated MCP session.
+- **`connect` overwrites in place** — a project carries exactly one testing connection at a time;
+  switching tools is just another `connect`. There is no array (unlike `repos.json`).
+- **`source`** is the authority for availability: an MCP id (`playwright-mcp` / `cypress-mcp` / …) means
+  `yad-test-cases` can generate/link; `unavailable` means `yad-test-cases` degrades to artifacts-only.
+  `refresh` re-detects and may flip it.
+- **`tool: "none"`** is a valid, deliberate state: a project that has chosen artifacts-only.
+  `yad-test-cases` treats it exactly like an absent registry.
+- **`disconnect`** removes the file (or sets `tool: "none"`). The testing tool's own project/suites are
+  never touched.
+
+## Git tracking
+
+Commit the **registry** (`testing.json`) — it is small, reviewable, and holds no secrets (references
+only). This mirrors how `repos.json`, `hub.json`, and `design.json` are committed.
+
+## Greenfield
+
+A brand-new product hub has no `testing.json`. That is valid — `yad-test-cases` treats "no testing tool
+connected" the same as `tool: "none"` and produces the Markdown test-case artifact only. The registry
+appears the first time `connect` runs.

package/skills/yad-epic/SKILL.md

@@ -14,7 +14,7 @@ drafted, control passes to `yad-review-gate`.
 - **Analysis ran** — `.sdlc/state.json` already exists with `currentStep == "epic"`. The epic **reads
   `analysis.md`** as its shaped input and does not re-seed state.
 - **Analysis skipped** (the default) — no `state.json` yet. The epic is the entry point: it shapes the
-  idea inline with the analyst, assigns `EP-<slug>`, and seeds the **8-step** chain.
+  idea inline with the analyst, assigns `EP-<slug>`, and seeds the **10-step** chain.
 
 This skill enforces the build plan's core rules: all state lives in files; IDs are generated by the
 engine (never typed by hand); front steps are locked to `human_approve`.
@@ -105,9 +105,9 @@ Fill the body with the user; leave `owner` / `technical_product_owner` for the u
 `repos` to the repos this epic will touch.
 
 ### Step 5 — Seed the state machine — analysis-skipped only
-*(Skip when analysis ran — `yad-analysis` already seeded the 10-step chain. Go to Step 5b.)*
-Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **8-step** front-state
-sequence (no analysis), all steps defaulting to `automation: human_approve`, with the four authoring
+*(Skip when analysis ran — `yad-analysis` already seeded the 12-step chain. Go to Step 5b.)*
+Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **10-step** front-state
+sequence (no analysis), all steps defaulting to `automation: human_approve`, with the five authoring
 steps **locked**. Use this exact shape (see `references/state-schema.md`):
 
 ```json
@@ -123,7 +123,9 @@ steps **locked**. Use this exact shape (see `references/state-schema.md`):
     { "id": "ui-design",          "type": "author",         "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
     { "id": "ui-design-review",   "type": "review+approve", "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
     { "id": "stories",            "type": "author",         "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
-    { "id": "stories-review",     "type": "review+approve", "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] }
+    { "id": "stories-review",     "type": "review+approve", "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "test-cases",         "type": "author",         "artifact": "test-cases.md",    "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "test-cases-review",  "type": "review+approve", "artifact": "test-cases.md",    "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] }
   ]
 }
 ```
@@ -131,6 +133,9 @@ steps **locked**. Use this exact shape (see `references/state-schema.md`):
 Notes:
 - `architecture-review` carries `risk_tags: ["contract"]` so the gate escalates it by default
   (build plan §4): the contract review needs domain owners, not just owner + 1.
+- `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `blocked` and open
+  when `stories-review` passes — at which point the epic is already `ready-for-build`, so the build half
+  runs alongside the tester. They never gate `ready-for-build` (see `references/state-schema.md`).
 - Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
   and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
   `[]`, and the `reviews/` directory. (`comments.json` is the machine-readable counterpart to the

package/skills/yad-epic/references/state-schema.md

@@ -17,7 +17,7 @@ Each `steps[]` entry:
 
 | Field | Values | Meaning |
 |-------|--------|---------|
-| `id` | `analysis`, `analysis-review`, `epic`, `epic-review`, `architecture`, `architecture-review`, `ui-design`, `ui-design-review`, `stories`, `stories-review` | Step identity. |
+| `id` | `analysis`, `analysis-review`, `epic`, `epic-review`, `architecture`, `architecture-review`, `ui-design`, `ui-design-review`, `stories`, `stories-review`, `test-cases`, `test-cases-review` | Step identity. |
 
 ### Two valid chain shapes (analysis is optional)
 
@@ -26,20 +26,37 @@ ran `yad-analysis` before the epic. The entry-point skill (whichever runs first)
 that assigns `EP-<slug>` and seeds `state.json` + the empty ledgers; the other skill detects an
 existing `state.json` and does **not** re-seed.
 
-- **With analysis** (10 steps — `yad-analysis` seeded the chain):
+- **With analysis** (12 steps — `yad-analysis` seeded the chain):
   `analysis → analysis-review → epic → epic-review → architecture → architecture-review → ui-design →
-  ui-design-review → stories → stories-review`. Seeded `currentStep` is `analysis-review`; `epic`
-  starts `blocked`.
-- **Without analysis** (8 steps — `yad-epic` is the entry point, the default):
-  `epic → epic-review → … → stories-review`. Seeded `currentStep` is `epic-review`.
-
-After `stories-review` passes, `currentStep` becomes the `ready-for-build` sentinel either way.
-`analysis-review` carries no `risk_tags` (base rule: owner + 1 reviewer).
+  ui-design-review → stories → stories-review → test-cases → test-cases-review`. Seeded `currentStep`
+  is `analysis-review`; `epic` starts `blocked`.
+- **Without analysis** (10 steps — `yad-epic` is the entry point, the default):
+  `epic → epic-review → … → stories-review → test-cases → test-cases-review`. Seeded `currentStep` is
+  `epic-review`.
+
+`analysis-review`, `ui-design-review`, and `test-cases-review` carry no `risk_tags` (base rule:
+owner + 1 reviewer).
+
+### `test-cases` is a parallel, non-blocking track
+
+`test-cases` (and its `test-cases-review` gate) sit in `steps[]` after `stories-review`, but they are a
+**parallel track that does not gate the build half**. When `stories-review` passes, `advanceState`:
+- sets `currentStep` to the **`ready-for-build`** sentinel — so the build half (`yad-spec` → … keyed off
+  `currentStep == "ready-for-build"`) can start **immediately**, and
+- opens `test-cases` (`blocked` → `in_progress`) so the tester can work **in parallel**.
+
+The `test-cases` track is therefore driven by its own step `status`, **not** by `currentStep`:
+`yad-test-cases` proceeds when `test-cases.status == "in_progress"`, and neither it nor the
+`test-cases-review` gate (`advanceState` / `markInReview`) ever moves `currentStep` away from
+`ready-for-build`. So implementation and test-case authoring run at the same time; the epic is
+`ready-for-build` the moment the **stories** gate passes, whether or not test cases are done. (For an old
+epic seeded before this step existed, `stories-review` → `ready-for-build` with no test-cases track —
+unchanged.)
 
 ### Authoring branches
 
 Each front **authoring** step opens its own git branch at the start of the step, named
-`<step>/EP-<slug>` where `<step>` ∈ `analysis | epic | architecture | ui-design | stories`
+`<step>/EP-<slug>` where `<step>` ∈ `analysis | epic | architecture | ui-design | stories | test-cases`
 (`config.yaml` `defaults.front_authoring_branch`). This is **distinct** from the review branch
 `review/EP-<slug>/<artifact-base>` that `yad-hub-bridge` opens later for the review PR/MR.
 
@@ -99,6 +116,20 @@ chain is unchanged — this is an *output enrichment*, mirrored by the `design:`
   "source": "<mcp id>" }
 ```
 
+## `test-links.json`
+Present only when the `test-cases` step materialized automation in a connected testing tool
+(`yad-connect-testing` → `.sdlc/testing.json`). Written by `yad-test-cases`, the machine-readable
+case→test map (sibling of `contract-lock.json` / `design-links.json`; the locked `state.json` step shape
+is untouched). The `test-cases` step chain is unchanged — this is an *output enrichment*, mirrored by the
+`testing:` frontmatter block and the `## Automation (<tool>)` section in `test-cases.md`. Absent when the
+step ran artifacts-only (`testing: none`).
+
+```json
+{ "tool": "playwright", "suite": "<url/path>", "generatedAt": "<YYYY-MM-DD>", "direction": "generated|linked",
+  "tests": [ { "case": "<id>", "story": "EP-<slug>-S0N", "repo": "<name>", "level": "unit|integration|e2e", "path": "<test path>", "url": "<url>" } ],
+  "source": "<mcp id>" }
+```
+
 ## `reviews/`
 Human-readable review records, one file per round:
 `reviews/<artifact-base>--<YYYY-MM-DD>--<status>.md` where `status` ∈ `comments` | `approved`
@@ -106,7 +137,7 @@ and `<artifact-base>` is the artifact without extension (e.g. `epic`, `architect
 
 ## Dial defaults & locks
 - Every step defaults to `automation: human_approve` (build plan §2).
-- The four authoring front steps and their reviews are `locked: true` — the engine refuses to set
+- The five authoring front steps and their reviews are `locked: true` — the engine refuses to set
   them to `machine_advance` in this version (build plan §1, §8.7). Only back states (build pipeline,
   steps 9–14) may move toward machine-advance in a later iteration.
 

package/skills/yad-hub-bridge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-hub-bridge
-description: 'The templated PR/MR bridge for the front-half review gate. When the product hub has a platform (.sdlc/hub.json), it opens a review PR/MR on the hub for an authored artifact (the optional analysis / epic / architecture+contract / ui-design / stories), sets the required reviewers/labels from the routing rule, and provides the read-only gh/glab recipes that yad-review-gate uses to pull platform comments + approvals back into the file ledger. Can also wire event-driven sync on the hub: a CI workflow that runs `yad gate ci` whenever a reviewer approves / requests changes / a human merges, committing the ledger to the default branch. Local-user auth only — no stored tokens. The file ledger stays the source of truth; degrades to the file-only gate when there is no platform / no CLI. Use when the user says "open the review PR", "route the review", "wire the gate sync", or it is invoked by yad-review-gate open/sync.'
+description: 'The templated PR/MR bridge for the front-half review gate. When the product hub has a platform (.sdlc/hub.json), it opens a review PR/MR on the hub for an authored artifact (the optional analysis / epic / architecture+contract / ui-design / stories / test-cases), sets the required reviewers/labels from the routing rule, and provides the read-only gh/glab recipes that yad-review-gate uses to pull platform comments + approvals back into the file ledger. Can also wire event-driven sync on the hub: a CI workflow that runs `yad gate ci` whenever a reviewer approves / requests changes / a human merges, committing the ledger to the default branch. Local-user auth only — no stored tokens. The file ledger stays the source of truth; degrades to the file-only gate when there is no platform / no CLI. Use when the user says "open the review PR", "route the review", "wire the gate sync", or it is invoked by yad-review-gate open/sync.'
 ---
 
 # SDLC — Hub Review Bridge (the templated PR/MR bridge)
@@ -29,7 +29,7 @@ keeps platform mechanics out of the gate). `yad-review-gate` *calls* it; it neve
 ## Inputs
 
 - `epic`     — the `EP-<slug>` under review.
-- `artifact` — the artifact file (`analysis.md` | `epic.md` | `architecture.md` | `ui-design.md` | `stories/`).
+- `artifact` — the artifact file (`analysis.md` | `epic.md` | `architecture.md` | `ui-design.md` | `stories/` | `test-cases.md`).
 - `action`   — `open` | `route` | `wire` (default `route`). (`sync`'s ledger writes live in
   `yad-review-gate`; this skill provides the read recipes `sync` calls — see `references/bridge.md`.)