yadflow 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -1,16 +1,27 @@
-# [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-13)
+# [2.4.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.3.0...v2.4.0) (2026-06-13)
 
 
 ### Bug Fixes
 
-* address code review on the design-tool connection ([1275146](https://github.com/abdelrahmannasr/yadflow/commit/1275146e9e24251d481d90eb26894a729e894997))
+* address CodeRabbit review on PR [#48](https://github.com/abdelrahmannasr/yadflow/issues/48) ([2f182f7](https://github.com/abdelrahmannasr/yadflow/commit/2f182f72b68e226196b6190802771b0e12b585f9))
 
 
 ### Features
 
-* add yad-connect-design skill (Figma-first, pluggable) ([d1de46d](https://github.com/abdelrahmannasr/yadflow/commit/d1de46d2b08995db0228e60a58877649649b5cd0))
-* materialize the feature design in yad-ui (generate or link) ([e440571](https://github.com/abdelrahmannasr/yadflow/commit/e44057131e86fed45d9a9c4151cd762eb98f24e8))
-* wire the design-tool connection through the CLI ([1867ed4](https://github.com/abdelrahmannasr/yadflow/commit/1867ed433dd57025ae4143f5a236db32f1a99c41))
+* add DeepTutor learning layer across all SDLC stages ([bd8d4ea](https://github.com/abdelrahmannasr/yadflow/commit/bd8d4eaaa0258242a62ed1b131f7e3f74506af64))
+* make learning-layer output local-only (never committed or pushed) ([aa8f74e](https://github.com/abdelrahmannasr/yadflow/commit/aa8f74eb61855d3a663810a0c68cf8e37fbedd66))
+
+# [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
+
+
+### Features
+
+* add parallel test-cases step with pluggable testing-tool connection ([#45](https://github.com/abdelrahmannasr/yadflow/issues/45)) ([19c282f](https://github.com/abdelrahmannasr/yadflow/commit/19c282f6bd737364bca122179b05de8ea94493a9))
+
+
+### Continuous Integration
+
+* wire the hub's gate-sync + verified-commits CI and stamp the CLI version ([#46](https://github.com/abdelrahmannasr/yadflow/issues/46)) ([c856398](https://github.com/abdelrahmannasr/yadflow/commit/c856398a213b17aebea9c46204dbf955b92ea9cf))
 
 # [1.1.0](https://github.com/abdelrahmannasr/sdlc-workflow/compare/v1.0.3...v1.1.0) (2026-06-09)
 

package/README.md

@@ -49,8 +49,11 @@ human**. Detailed walkthroughs for each phase follow below.
 | `skills/yad-architecture/` | Front state 3: author `architecture.md` + the locked `contract.md`; hash-lock the contract surface. |
 | `skills/yad-ui/` | Front state 5: author `ui-design.md` + `DESIGN.md` (Impeccable slash-commands, or graceful fallback). |
 | `skills/yad-stories/` | Front state 7: break the epic into repo-tagged stories with stable `EP-<slug>-S0N` IDs. |
+| `skills/yad-test-cases/` | Front state 9: with the test architect author `test-cases.md`; implement the automation in the connected testing tool, or produce artifacts only. |
 | `skills/yad-connect-repos/` | Connect code repos to the hub (GitHub/GitLab, local-user auth); cache a Repomix pack + **code-map** per repo so the front phases are code-aware. |
-| `skills/yad-review-gate/` | The reusable **team review + approve gate** (used for all four reviews). |
+| `skills/yad-connect-learning/` | Connect a learning tool (DeepTutor-first, pluggable) — a CLI subprocess like Repomix; record `.sdlc/learning.json` + an optional grounded knowledge base. |
+| `skills/yad-learn/` | The cross-cutting **learning layer**: tutor any member, at any stage, in the context of what's being built; records a personal, local-only skills log (gitignored, never committed/pushed). Opt-in, never gates. |
+| `skills/yad-review-gate/` | The reusable **team review + approve gate** (used for all five reviews). |
 | `skills/yad-spec/` | Build Step A: run the Spec Kit ceremony once per story per repo → `specs/<story-id>/`. |
 | `skills/yad-implement/` | Build Step B: implement ONE atomic task as a small diff on its own branch. |
 | `skills/yad-checks/` | Build Step C: wire + run the CI gates (spec-link, contract-check, build/test/lint, verified-commits). |
@@ -122,18 +125,24 @@ a manual `yad gate sync` racing CI, or GitLab pipelines — two simultaneous syn
 *commits* via the rebase retry but each works from the state it read at start, so the rarer of two
 simultaneous advancements can be lost; the next event or scheduled sweep re-syncs and converges.
 
-### What `setup` walks you through (8 steps)
+### What `setup` walks you through (10 steps)
 
 1. **Preflight** — confirm the hub is a git repo (offers `git init`); check `git`/`node`/`npx`.
-2. **Install the module** — copy all 18 `yad-*` skills into the IDE skill dirs you pick
+2. **Install the module** — copy all 22 `yad-*` skills into the IDE skill dirs you pick
    (`.claude/`, `.agents/`, `.zencoder/`, `.opencode/`) and register `_bmad/sdlc/`.
 3. **Hub platform & roster** — detect GitHub/GitLab from the remote; record reviewers → `.sdlc/hub.json`.
 4. **Connect a design tool** — record the design tool (Figma / pencil / none) → `.sdlc/design.json` so
    the UI step can materialize the design; the MCP itself is confirmed later by `yad-connect-design`.
-5. **Connect code repos** — register each repo into `.sdlc/repos.json` and cache a Repomix pack.
-6. **Wire each repo** — CI gates, PR/MR template, and review-comment scaffold.
-7. **AI review** — optionally write `.coderabbit.yaml`.
-8. **Done** — stamp `.sdlc/cli-version.json` and hand off the AI-only steps (code-maps; first epic).
+5. **Connect a testing tool** — record the testing tool (Playwright / cypress / pytest / none) →
+   `.sdlc/testing.json` so the test-cases step can implement the automation; the MCP itself is confirmed
+   later by `yad-connect-testing`.
+6. **Connect a learning tool** — record the learning tool (DeepTutor / none) → `.sdlc/learning.json` so
+   the learning layer can tutor the team; the CLI + knowledge base are confirmed later by
+   `yad-connect-learning`.
+7. **Connect code repos** — register each repo into `.sdlc/repos.json` and cache a Repomix pack.
+8. **Wire each repo** — CI gates, PR/MR template, and review-comment scaffold.
+9. **AI review** — optionally write `.coderabbit.yaml`.
+10. **Done** — stamp `.sdlc/cli-version.json` and hand off the AI-only steps (code-maps; first epic).
 
 The deterministic file work runs automatically; the AI-only steps are handed to the Claude Code skills
 with a printed next-action. Re-run `… check --fix` any time the workflow updates — it never re-asks for
@@ -170,10 +179,12 @@ with a fix-it hint per finding. Failures carry stable, greppable codes, also pri
 | `YAD-STATE-003` | a registered repo path is missing or not a git repo | fix the path in `.sdlc/repos.json` or re-connect the repo |
 | `YAD-CFG-001` | `hub.json` names an unknown platform | expected `github`, `gitlab`, or `null` — fix it or re-run `yad setup` |
 | `YAD-CFG-002` | `design.json` names an unknown design tool | expected one of `config.yaml` `design.tools` (e.g. `figma`, `pencil`), or `none` — fix it or re-run `yad setup` |
+| `YAD-CFG-003` | `testing.json` names an unknown testing tool | expected one of `config.yaml` `testing.tools` (e.g. `playwright`, `cypress`, `pytest`), or `none` — fix it or re-run `yad setup` |
+| `YAD-CFG-004` | `learning.json` names an unknown learning tool | expected one of `config.yaml` `learning.tools` (e.g. `deeptutor`), or `none` — fix it or re-run `yad setup` |
 
 Filing a bug? Attach `yad doctor --json` — it contains no secrets (names, paths, and check results only).
 
-## Agent skills (all 18)
+## Agent skills (all 22)
 
 The CLI **installs and wires** the module; the skills below are the **agents you invoke by name** in your
 AI IDE (e.g. *“run `yad-epic`”*) to actually do the work. State lives in files you can also edit
@@ -191,12 +202,36 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
   Records the tool + project/file references in `.sdlc/design.json` (local-user / MCP-session auth, no
   stored tokens), detecting the design-tool MCP and degrading to markdown-only when absent. Idempotent
   and refreshable; one connection per project.
+- **`yad-connect-testing`** — Connects a testing tool (Playwright-first, pluggable) so the test-cases
+  step can implement the actual automation tests inside it, alongside the Markdown. Records the tool +
+  project/suite references in `.sdlc/testing.json` (local-user / MCP-session auth, no stored tokens),
+  detecting the testing-tool MCP and degrading to artifacts-only when absent. Idempotent and
+  refreshable; one connection per project.
+- **`yad-connect-learning`** — Connects a learning/tutoring tool (DeepTutor-first, pluggable) so the
+  cross-cutting learning layer can tutor any team member in the context of what's being built. Records
+  the tool + an optional grounded knowledge base in `.sdlc/learning.json` (local-user auth, no stored
+  tokens), detecting the **DeepTutor CLI on PATH** (a subprocess like Repomix — DeepTutor ships no MCP)
+  and degrading to **harness-native** tutoring when absent. Idempotent and refreshable; one connection
+  per project.
+
+### The learning layer (cross-cutting — any member, any stage)
+
+- **`yad-learn`** — 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* — e.g. *"teach me why the architecture hash-locks the
+  contract surface"*. 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 nothing is connected — so it always works. Renders a
+  tutorial artifact and appends to a per-member **learning ledger** kept **local-only** (gitignored,
+  never committed or pushed — to the 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. *AI builds, the hand decides* — and now the
+  hand can also learn, on demand, what it is deciding about.
 
 ### Front half — author the "thinking" (once per epic, human-gated)
 
 - **`yad-analysis`** — *Optional* front state 1. With the analyst, pressure-test a feature idea
   and write the discovery brief into `analysis.md`. Assigns the `EP-<slug>` ID and seeds `.sdlc/` state
-  (the 10-step chain that puts analysis before epic). If skipped, the epic step does this shaping inline.
+  (the 12-step chain that puts analysis before epic). If skipped, the epic step does this shaping inline.
 - **`yad-epic`** — The epic front state. Shape the idea with the analyst (or read `analysis.md`
   when it already ran), then write the epic with the pm into `epic.md`. The entry point when analysis is
   skipped: assigns the `EP-<slug>` ID and seeds `.sdlc/` state.
@@ -211,6 +246,13 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
 - **`yad-stories`** — Front state 7. With the pm, break the approved epic into user stories, each
   tagged with the repos that must implement it. Assigns zero-padded `EP-<slug>-S0N` IDs, one file per
   story under `stories/`. Reads epic + architecture + contract + UI.
+- **`yad-test-cases`** — Front state 9, a **parallel, non-blocking** track: it opens when the stories
+  gate passes (the epic is already `ready-for-build`, so the build half runs alongside it). With the
+  test architect (Murat), author `test-cases.md` covering the approved stories (risk-based P0–P3 cases +
+  story→case traceability). When a testing tool is connected (`yad-connect-testing`), also **implements
+  the automation tests** in the connected code repo(s) (generate or link), recording the case→test map in
+  `test-links.json`; degrades to artifacts-only otherwise. Reads epic + architecture + contract + UI +
+  stories.
 
 ### The review gate (cross-cutting — used by every review)
 
@@ -269,7 +311,7 @@ merging the approved, fully-resolved review PR — never on a machine.
 
 As of **Phase 4a** the `automation` dial is no longer inert: the orchestrator `yad-run` reads it and,
 for the safe **back** steps, advances on its own when a step is set to `machine_advance` (and has
-*earned* it — see "Run the back half on the dial" below). The engineer review and all four front
+*earned* it — see "Run the back half on the dial" below). The engineer review and all five front
 states stay `human_approve` forever.
 
 ## Using the workflow end to end (all the steps, in order)
@@ -280,17 +322,19 @@ detailed sections below expand every phase. Invoke a skill by name in your agent
 
 ### 0 — One-time setup
 
-> **Shortcut:** `npx yadflow setup` walks through steps 1, 4, 5 and 6 below
-> interactively (module install, hub detect + roster, connect repos, wire each repo). Run
-> `… check --fix` any time afterwards to reconcile. The manual steps below are the long-hand
-> equivalent and still work.
+> **Shortcut:** `npx yadflow setup` runs the guided wizard interactively — module install, hub
+> detect + roster, connect a design/testing/learning tool (each optional), connect repos, wire each
+> repo. Run `… check --fix` any time afterwards to reconcile. The manual steps below are the
+> long-hand equivalent and still work.
 
 1. **Install the module:** `bash skills/sdlc/install.sh` (re-run after any BMAD update).
 2. **Have your code repo(s).** They are **separate git repos** (one `.git` each). For the demo they
    live under `demo-repos/<repo>/` — regenerate from `demo-repos/README.md`.
 3. **Optional tools** (the workflow degrades gracefully and records it if any are absent): **Spec Kit**
    (`/speckit.*`), **Impeccable** (`/impeccable …`), **Repomix** (`npx repomix`, used by
-   `yad-connect-repos` and `yad-backfill`), **CodeRabbit** (advisory AI review).
+   `yad-connect-repos` and `yad-backfill`), **CodeRabbit** (advisory AI review), **DeepTutor**
+   (`deeptutor`, the learning layer's tutor — degrades to harness-native, used by `yad-connect-learning`
+   and `yad-learn`).
 4. **Wire each code repo once:** `yad-checks repo:<repo> action: wire` (installs the CI gates —
    *merges* with any existing CI, never clobbers), `yad-pr-template repo:<repo> action: wire` (PR/MR
    template + risk routing), `yad-review-comments repo:<repo> action: wire` (review-comment scaffold).
@@ -301,11 +345,16 @@ detailed sections below expand every phase. Invoke a skill by name in your agent
    (SSH or credential helper; GitHub or GitLab; no stored tokens). Re-run for any new repo. Freshness is a
    **human decision**: `yad repo list` shows fresh/stale, `yad repo refresh [name]` re-packs a moved repo
    (skills flag staleness and point here — they never silently re-pack). Greenfield → skip it.
-6. **(Optional) Put the hub on a platform** so the front-half review runs through real PRs:
+6. **(Optional) Connect tools** so the matching steps do real work (each degrades gracefully and is
+   recorded if absent): `yad-connect-design action: connect` (Figma-first → `design.json`, lets
+   `yad-ui` materialize screens), `yad-connect-testing action: connect` (Playwright-first →
+   `testing.json`, lets `yad-test-cases` implement automation), `yad-connect-learning action: connect`
+   (DeepTutor-first → `learning.json`, powers the cross-cutting learning layer).
+7. **(Optional) Put the hub on a platform** so the front-half review runs through real PRs:
    `yad-connect-repos action: detect-hub`, then `action: roster` once per reviewer (login → SDLC
    name + role), and `yad-pr-template repo:hub action: wire` / `yad-review-comments repo:hub action:
    wire` / `yad-checks repo:hub action: wire`. With no hub platform the front gate just runs file-only.
-7. **Conventions:** commits and PR/MR titles follow Conventional Commits (lowercase after the type), the
+8. **Conventions:** commits and PR/MR titles follow Conventional Commits (lowercase after the type), the
    human author owns each commit with an optional per-commit `Co-Authored-By` AI trailer — see
    [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
@@ -320,7 +369,10 @@ threads are resolved. Details: **“Run the full front half by hand”** below.
 7. `yad-architecture` → `architecture.md` + locked `contract.md` → review (**escalated**: contract).
 8. `yad-ui` → `ui-design.md` + `DESIGN.md` → review (base rule).
 9. `yad-stories` → repo-tagged `stories/EP-<slug>-S0N.md` → review (**per-repo**).
-   → `state.json` reaches `currentStep: ready-for-build`.
+   → `state.json` reaches `currentStep: ready-for-build` — **the build half can start now.**
+10. `yad-test-cases` → `test-cases.md` (+ automation tests when a testing tool is connected) → review (base rule).
+    **Parallel, non-blocking:** opens when the stories gate passes and runs alongside the build half; its
+    review never moves `currentStep` off `ready-for-build`.
 
 ### B — Build half (per story, per repo)
 From a `ready-for-build` story, for **each** repo the story is tagged with. Details: **“Run the full
@@ -355,12 +407,13 @@ Details: **“Run the back half on the dial”** below.
 ## Run the full front half by hand
 
 The front half walks **epic → review → architecture+contract → review → UI design → review → stories
-→ review → `ready-for-build`**. It is all files under `epics/EP-<slug>/`. The skills below guide you,
-but you can also edit the files directly — that's the point.
+→ review → `ready-for-build`**, then **test cases → review** runs as a **parallel, non-blocking track**
+alongside the build half. It is all files under `epics/EP-<slug>/`. The skills below guide you, but you
+can also edit the files directly — that's the point.
 
 Each authoring step is the same shape: an author skill produces an artifact, sets its step `done`,
 moves `currentStep` to the matching review, and **stops at the gate**. Then **`yad-review-gate`**
-(one gate, reused for all four reviews) takes `open → comment → approve → advance`. When the hub is on a
+(one gate, reused for all five reviews) takes `open → comment → approve → advance`. When the hub is on a
 platform, the **`yad gate`** CLI runs that gate over a real PR/MR — `open` raises the review PR, `sync`
 pulls approvals + comment threads into the ledger, and the step **auto-advances when the approved,
 fully-resolved PR is merged** (the merge is the human approval act).
@@ -417,7 +470,7 @@ accumulate, and the step moves forward only when the rule is met. **File-only**
   in any story's `repos`**.
 
 ### Check status anytime
-Invoke **`yad-status`** (read-only) to see the full 8-step chain, every step's dials/status, the
+Invoke **`yad-status`** (read-only) to see the full 10-step chain, every step's dials/status, the
 contract lock, story repo tags, and which approvals the active gate still needs.
 
 ## Worked example (already in this repo)

package/cli/doctor.mjs

@@ -5,7 +5,7 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { c, log, ok, info, warn, fail, hand, run, has, exists, readJSON, readJSONStrict } from './lib.mjs';
-import { VERSION, PROJECT_FILES, DESIGN_TOOLS } from './manifest.mjs';
+import { VERSION, PROJECT_FILES, DESIGN_TOOLS, TESTING_TOOLS, LEARNING_TOOLS } from './manifest.mjs';
 import { loadLedger, epicRoot } from './epic-state.mjs';
 import { gitHead } from './setup.mjs';
 import { cliFor } from './platform.mjs';
@@ -88,13 +88,55 @@ export function projectChecks(checks, root) {
     }
     if (designBroken) { /* reported above */ }
     else if (typeof design !== 'object' || Array.isArray(design) || design === null) check(checks, 'design', 'project', 'fail', `${PROJECT_FILES.designConfig} has the wrong shape [YAD-STATE-002]`, 'expected a JSON object');
-    else if (![...DESIGN_TOOLS, 'none', null, undefined].includes(design.tool)) check(checks, 'design', 'project', 'fail', `${PROJECT_FILES.designConfig}: unknown design tool '${design.tool}' [YAD-CFG-002]`, `expected one of ${DESIGN_TOOLS.join(', ')}, or none`);
-    else if (!design.tool || design.tool === 'none') check(checks, 'design', 'project', 'ok', 'design: markdown-only');
+    else if (design.tool === 'none') check(checks, 'design', 'project', 'ok', 'design: markdown-only');
+    else if (!DESIGN_TOOLS.includes(design.tool)) check(checks, 'design', 'project', 'fail', `${PROJECT_FILES.designConfig}: unknown or missing design tool '${design.tool}' [YAD-CFG-002]`, `expected one of ${DESIGN_TOOLS.join(', ')}, or none`);
     else if (design.source && design.source !== 'unavailable') check(checks, 'design', 'project', 'ok', `design: ${design.tool} (${design.source})`);
     else if (design.source === 'unavailable') check(checks, 'design', 'project', 'warn', `design: ${design.tool} MCP unavailable — yad-ui runs markdown-only`, 'connect the MCP, then run `yad-connect-design` (action: refresh)');
     else check(checks, 'design', 'project', 'warn', `design: ${design.tool} recorded but the MCP is not confirmed`, 'run `yad-connect-design` in Claude Code to detect the MCP');
   }
 
+  // testing.json: parse + shape + tool + MCP confirmation (absent is the normal artifacts-only default —
+  // pre-feature projects have none, so silence rather than warn when the file does not exist).
+  const testingPath = path.join(root, PROJECT_FILES.testingConfig);
+  if (exists(testingPath)) {
+    let testing = null, testingBroken = false;
+    try {
+      testing = readJSONStrict(testingPath, null);
+    } catch (e) {
+      testingBroken = true;
+      check(checks, 'testing', 'project', 'fail', `${PROJECT_FILES.testingConfig} does not parse [${e.code || 'YAD-STATE-001'}]`, e.hint || 'fix the JSON or restore it from git');
+    }
+    if (testingBroken) { /* reported above */ }
+    else if (typeof testing !== 'object' || Array.isArray(testing) || testing === null) check(checks, 'testing', 'project', 'fail', `${PROJECT_FILES.testingConfig} has the wrong shape [YAD-STATE-002]`, 'expected a JSON object');
+    else if (testing.tool === 'none') check(checks, 'testing', 'project', 'ok', 'testing: artifacts-only');
+    else if (!TESTING_TOOLS.includes(testing.tool)) check(checks, 'testing', 'project', 'fail', `${PROJECT_FILES.testingConfig}: unknown or missing testing tool '${testing.tool}' [YAD-CFG-003]`, `expected one of ${TESTING_TOOLS.join(', ')}, or none`);
+    else if (testing.source && testing.source !== 'unavailable') check(checks, 'testing', 'project', 'ok', `testing: ${testing.tool} (${testing.source})`);
+    else if (testing.source === 'unavailable') check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} MCP unavailable — yad-test-cases runs artifacts-only`, 'connect the MCP, then run `yad-connect-testing` (action: refresh)');
+    else check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} recorded but the MCP is not confirmed`, 'run `yad-connect-testing` in Claude Code to detect the MCP');
+  }
+
+  // learning.json: parse + shape + tool + CLI confirmation (absent is the normal harness-native default —
+  // pre-feature projects have none, so silence rather than warn when the file does not exist). DeepTutor
+  // has no MCP, so `source` is deeptutor-cli (found on PATH) or harness-native (degraded).
+  const learningPath = path.join(root, PROJECT_FILES.learningConfig);
+  if (exists(learningPath)) {
+    let learning = null, learningBroken = false;
+    try {
+      learning = readJSONStrict(learningPath, null);
+    } catch (e) {
+      learningBroken = true;
+      check(checks, 'learning', 'project', 'fail', `${PROJECT_FILES.learningConfig} does not parse [${e.code || 'YAD-STATE-001'}]`, e.hint || 'fix the JSON or restore it from git');
+    }
+    if (learningBroken) { /* reported above */ }
+    else if (typeof learning !== 'object' || Array.isArray(learning) || learning === null) check(checks, 'learning', 'project', 'fail', `${PROJECT_FILES.learningConfig} has the wrong shape [YAD-STATE-002]`, 'expected a JSON object');
+    else if (learning.tool === 'none') check(checks, 'learning', 'project', 'ok', 'learning: harness-native');
+    else if (!LEARNING_TOOLS.includes(learning.tool)) check(checks, 'learning', 'project', 'fail', `${PROJECT_FILES.learningConfig}: unknown or missing learning tool '${learning.tool}' [YAD-CFG-004]`, `expected one of ${LEARNING_TOOLS.join(', ')}, or none`);
+    else if (learning.source === 'deeptutor-cli') check(checks, 'learning', 'project', 'ok', `learning: ${learning.tool} (${learning.source})`);
+    else if (learning.source === 'harness-native') check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool} CLI unavailable — yad-learn tutors harness-native`, 'install the deeptutor CLI, then run `yad-connect-learning` (action: refresh)');
+    else if (learning.source == null) check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool} recorded but the CLI is not confirmed`, 'run `yad-connect-learning` in Claude Code to detect the CLI');
+    else check(checks, 'learning', 'project', 'fail', `${PROJECT_FILES.learningConfig}: unknown source '${learning.source}' [YAD-STATE-002]`, 'expected deeptutor-cli, harness-native, or null');
+  }
+
   // repos.json: parse + every entry is a live git repo; staleness vs syncedHead
   let registry = { repos: [] };
   let regBroken = false;

package/cli/epic-state.mjs

@@ -197,9 +197,24 @@ export function gatePredicate({
 
 // Advance the step in state.json once the predicate passes. Mirrors yad-review-gate Step 3:
 // mark this review step done, unblock the next step, or set `ready-for-build` for the last one.
+//
+// `test-cases` is a PARALLEL, non-blocking track so the build half can start while the tester works:
+// approving `stories-review` makes the epic `ready-for-build` (the build half keys off this) AND opens
+// `test-cases` for the tester; completing `test-cases-review` never pulls `currentStep` back from
+// `ready-for-build`. Both rules degrade safely for an old chain that has no test-cases steps.
 export function advanceState(state, step) {
   const i = state.steps.findIndex((s) => s.id === step.id);
   state.steps[i] = { ...state.steps[i], status: 'done' };
+  if (step.id === 'stories-review') {
+    const tc = state.steps.find((s) => s.id === 'test-cases');
+    if (tc && tc.status === 'blocked') tc.status = 'in_progress';
+    state.currentStep = 'ready-for-build';
+    return state;
+  }
+  if (step.id === 'test-cases-review') {
+    state.currentStep = 'ready-for-build';
+    return state;
+  }
   const next = state.steps[i + 1];
   if (next) {
     next.status = next.type === 'review+approve' ? 'in_review' : 'in_progress';
@@ -210,11 +225,13 @@ export function advanceState(state, step) {
   return state;
 }
 
-// Mark a step in-review (idempotent) and point currentStep at it.
+// Mark a step in-review (idempotent) and point currentStep at it — EXCEPT once the epic is
+// `ready-for-build`: the parallel `test-cases` track must not pull currentStep back (the build half
+// runs alongside the tester, and only the test-cases review is in flight at that point).
 export function markInReview(state, step) {
   const i = state.steps.findIndex((s) => s.id === step.id);
   if (state.steps[i].status !== 'done') state.steps[i].status = 'in_review';
-  state.currentStep = step.id;
+  if (state.currentStep !== 'ready-for-build') state.currentStep = step.id;
   return state;
 }
 

package/cli/errors.mjs

@@ -21,6 +21,8 @@ export const CODES = {
   'YAD-STATE-003': 'a registered repo path is missing or not a git repository',
   'YAD-CFG-001': 'hub.json names an unknown platform (expected github, gitlab, or null)',
   'YAD-CFG-002': 'design.json names an unknown design tool (expected one of config.yaml design.tools, or none)',
+  'YAD-CFG-003': 'testing.json names an unknown testing tool (expected one of config.yaml testing.tools, or none)',
+  'YAD-CFG-004': 'learning.json names an unknown learning tool (expected one of config.yaml learning.tools, or none)',
 };
 
 export const err = (code, message, hint) => new YadError(code, message, hint);

package/cli/manifest.mjs

@@ -10,15 +10,19 @@ import { readFileSync } from 'node:fs';
 const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const VERSION = version;
 
-// The 18 hand-authored yad-* skills (mirrors skills/sdlc/install.sh).
+// The 22 hand-authored yad-* skills (mirrors skills/sdlc/install.sh).
 export const SKILLS = [
   'yad-analysis',
   'yad-epic',
   'yad-architecture',
   'yad-ui',
   'yad-stories',
+  'yad-test-cases',
   'yad-connect-repos',
   'yad-connect-design',
+  'yad-connect-testing',
+  'yad-connect-learning',
+  'yad-learn',
   'yad-spec',
   'yad-implement',
   'yad-checks',
@@ -87,11 +91,29 @@ export const MODULE_FILES = ['config.yaml', 'module-help.csv'];
 export const DESIGN_TOOLS = ['figma', 'pencil'];
 export const DESIGN_PRIMARY = 'figma';
 
+// Supported testing-tool adapters (mirrors skills/sdlc/config.yaml `testing.tools`); `TESTING_PRIMARY`
+// is the fallback `registerTesting`/setup use when an unknown tool is named, and `none` is the explicit
+// artifacts-only choice. (doctor does NOT fall back — an unknown tool there is a hard YAD-CFG-003 fail,
+// mirroring the design-tool YAD-CFG-002.)
+export const TESTING_TOOLS = ['playwright', 'cypress', 'pytest'];
+export const TESTING_PRIMARY = 'playwright';
+
+// Supported learning-tool adapters (mirrors skills/sdlc/config.yaml `learning.tools`); `LEARNING_PRIMARY`
+// is the fallback `registerLearning`/setup use when an unknown tool is named, and `none` is the explicit
+// harness-native choice (yad-learn tutors via the harness model when no tool is connected). DeepTutor is
+// a CLI subprocess (no MCP), so the connect skill detects the binary — not an MCP — but the registry +
+// degrade shape mirrors design/testing. (doctor does NOT fall back — an unknown tool there is a hard
+// YAD-CFG-004 fail, mirroring the design-tool YAD-CFG-002.)
+export const LEARNING_TOOLS = ['deeptutor'];
+export const LEARNING_PRIMARY = 'deeptutor';
+
 // Project-level files setup produces (used by `check` to spot missing setup).
 export const PROJECT_FILES = {
   reposRegistry: '.sdlc/repos.json',
   hubConfig: '.sdlc/hub.json',
   designConfig: '.sdlc/design.json',
+  testingConfig: '.sdlc/testing.json',
+  learningConfig: '.sdlc/learning.json',
   version: '.sdlc/cli-version.json',
 };
 

package/cli/setup.mjs

@@ -5,7 +5,7 @@ import {
   c, log, step, ok, info, warn, hand, fail, ask, askYesNo, run, has,
   exists, readJSON, writeJSON,
 } from './lib.mjs';
-import { VERSION, IDE_FOLDER_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY } from './manifest.mjs';
+import { VERSION, IDE_FOLDER_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY, TESTING_TOOLS, TESTING_PRIMARY, LEARNING_TOOLS, LEARNING_PRIMARY } from './manifest.mjs';
 import { moduleActions, repoActions, hubActions, authorsActions } from './plan.mjs';
 
 const ALL_IDES = [...IDE_FOLDER_TARGETS, '.opencode'];
@@ -87,6 +87,62 @@ export function registerDesign(root, { tool, project_url = null, files = null, t
   return design;
 }
 
+// Record the project's testing-tool connection into .sdlc/testing.json (the deterministic half of the
+// connect loop; MCP detection itself is an AI step, handed off to `yad-connect-testing`). An unknown
+// tool falls back to the primary adapter rather than being rejected — mirrors registerDesign. `none` is
+// the explicit artifacts-only choice.
+export function registerTesting(root, { tool, project_url = null, suites = null, today = null } = {}) {
+  // Idempotent re-connect: carry the original first-connect date forward; only lastSyncedAt moves.
+  const testingPath = path.join(root, PROJECT_FILES.testingConfig);
+  const prev = readJSON(testingPath, null);
+  const connectedAt = prev && prev.connectedAt ? prev.connectedAt : today;
+  let t = (tool || '').toLowerCase();
+  if (t === 'none' || t === '') {
+    const off = { tool: 'none', provider: null, project_url: null, auth: 'user',
+      suites: {}, connectedAt, lastSyncedAt: today, source: 'unavailable' };
+    writeJSON(testingPath, off);
+    return off;
+  }
+  if (!TESTING_TOOLS.includes(t)) { warn(`unknown testing tool '${tool}' — using ${TESTING_PRIMARY}`); t = TESTING_PRIMARY; }
+  // source stays null until `yad-connect-testing` detects the MCP in the harness (AI step). doctor
+  // reports a recorded-but-unconfirmed connection as a warning pointing at that skill.
+  const testing = {
+    tool: t, provider: null, project_url: project_url || null, auth: 'user',
+    suites: suites || {},
+    connectedAt, lastSyncedAt: today, source: null,
+  };
+  writeJSON(testingPath, testing);
+  return testing;
+}
+
+// Record the project's learning-tool connection into .sdlc/learning.json (the deterministic half of the
+// connect loop; CLI detection + the kb build are AI steps, handed off to `yad-connect-learning`). An
+// unknown tool falls back to the primary adapter rather than being rejected — mirrors registerDesign/
+// registerTesting. `none` is the explicit harness-native choice (yad-learn tutors via the harness model).
+// DeepTutor has no MCP, so `source` stays null at setup until the connect skill detects the CLI on PATH.
+export function registerLearning(root, { tool, kb = null, today = null } = {}) {
+  // Idempotent re-connect: carry the original first-connect date forward; only lastSyncedAt moves.
+  const learningPath = path.join(root, PROJECT_FILES.learningConfig);
+  const prev = readJSON(learningPath, null);
+  const connectedAt = prev && prev.connectedAt ? prev.connectedAt : today;
+  let t = (tool || '').toLowerCase();
+  if (t === 'none' || t === '') {
+    const off = { tool: 'none', provider: null, version: null, kb: null, kb_sources: [], auth: 'user',
+      connectedAt, lastSyncedAt: today, source: 'harness-native' };
+    writeJSON(learningPath, off);
+    return off;
+  }
+  if (!LEARNING_TOOLS.includes(t)) { warn(`unknown learning tool '${tool}' — using ${LEARNING_PRIMARY}`); t = LEARNING_PRIMARY; }
+  // source stays null until `yad-connect-learning` detects the CLI on PATH (AI step). doctor reports a
+  // recorded-but-unconfirmed connection as a warning pointing at that skill.
+  const learning = {
+    tool: t, provider: null, version: null, kb: kb || null, kb_sources: [], auth: 'user',
+    connectedAt, lastSyncedAt: today, source: null,
+  };
+  writeJSON(learningPath, learning);
+  return learning;
+}
+
 function applyActions(actions, { force = false } = {}) {
   let changed = 0;
   for (const a of actions) {
@@ -100,7 +156,7 @@ function applyActions(actions, { force = false } = {}) {
 }
 
 export async function runSetup(root, opts = {}) {
-  const total = 8;
+  const total = 10;
   log(c.bold(`\nSDLC Workflow setup  ${c.dim('v' + VERSION)}`));
   log(c.dim(`target: ${root}`));
 
@@ -178,8 +234,43 @@ export async function runSetup(root, opts = {}) {
       : `wrote ${PROJECT_FILES.designConfig} (${tool})`);
   }
 
-  // 5. Connect code repos
-  step(5, total, 'Connect code repos');
+  // 5. Connect a testing tool (Playwright-first, pluggable; the test-cases step implements automation here)
+  step(5, total, 'Connect a testing tool (playwright / cypress / pytest / none)');
+  const testingPath = path.join(root, PROJECT_FILES.testingConfig);
+  if (exists(testingPath) && !(await askYesNo('testing.json exists — reconfigure?', false))) {
+    info('keeping existing .sdlc/testing.json');
+  } else {
+    let tool = (await ask(`Testing tool (${TESTING_TOOLS.join('/')}/none)`, TESTING_PRIMARY)).toLowerCase();
+    if (![...TESTING_TOOLS, 'none'].includes(tool)) {
+      warn(`unknown testing tool '${tool}' — using ${TESTING_PRIMARY}`);
+      tool = TESTING_PRIMARY;
+    }
+    const project_url = tool === 'none' ? null : (await ask('  project/config reference (blank to set later)', '')) || null;
+    registerTesting(root, { tool, project_url, today: opts.today ?? null });
+    ok(tool === 'none'
+      ? `wrote ${PROJECT_FILES.testingConfig} (artifacts-only)`
+      : `wrote ${PROJECT_FILES.testingConfig} (${tool})`);
+  }
+
+  // 6. Connect a learning tool (DeepTutor-first, pluggable; the learning layer tutors team members here)
+  step(6, total, 'Connect a learning tool (deeptutor / none)');
+  const learningPath = path.join(root, PROJECT_FILES.learningConfig);
+  if (exists(learningPath) && !(await askYesNo('learning.json exists — reconfigure?', false))) {
+    info('keeping existing .sdlc/learning.json');
+  } else {
+    let tool = (await ask(`Learning tool (${LEARNING_TOOLS.join('/')}/none)`, LEARNING_PRIMARY)).toLowerCase();
+    if (![...LEARNING_TOOLS, 'none'].includes(tool)) {
+      warn(`unknown learning tool '${tool}' — using ${LEARNING_PRIMARY}`);
+      tool = LEARNING_PRIMARY;
+    }
+    registerLearning(root, { tool, today: opts.today ?? null });
+    ok(tool === 'none'
+      ? `wrote ${PROJECT_FILES.learningConfig} (harness-native)`
+      : `wrote ${PROJECT_FILES.learningConfig} (${tool})`);
+  }
+
+  // 7. Connect code repos
+  step(7, total, 'Connect code repos');
   const regPath = path.join(root, PROJECT_FILES.reposRegistry);
   const registry = readJSON(regPath, { repos: [] });
   const known = new Set(registry.repos.map((r) => r.name));
@@ -202,8 +293,8 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 6. Wire each connected repo + the hub itself
-  step(6, total, 'Wire connected repos + the hub (CI gates, PR template, comment scaffold, gate-sync)');
+  // 8. Wire each connected repo + the hub itself
+  step(8, total, 'Wire connected repos + the hub (CI gates, PR template, comment scaffold, gate-sync)');
   if (registry.repos.length === 0) info('no repos to wire');
   for (const repo of registry.repos) {
     log(`  ${c.bold(repo.name)} ${c.dim(`(${repo.platform})`)}`);
@@ -218,8 +309,8 @@ export async function runSetup(root, opts = {}) {
   // author allowlists for the verified-commits gate (hub + every repo), from the roster emails
   applyActions(authorsActions(root, registry.repos), { force: true });
 
-  // 7. Optional CodeRabbit
-  step(7, total, 'AI review (CodeRabbit)');
+  // 9. Optional CodeRabbit
+  step(9, total, 'AI review (CodeRabbit)');
   for (const repo of registry.repos) {
     const cr = path.join(path.resolve(root, repo.path), '.coderabbit.yaml');
     if (exists(cr)) { info(`${repo.name}: .coderabbit.yaml present`); continue; }
@@ -229,8 +320,8 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 8. Summary + version stamp
-  step(8, total, 'Done');
+  // 10. Summary + version stamp
+  step(10, total, 'Done');
   writeJSON(path.join(root, PROJECT_FILES.version), { version: VERSION, ideTargets, updatedAt: opts.today ?? null });
   ok(`stamped ${PROJECT_FILES.version} (v${VERSION})`);
   log('');
@@ -240,6 +331,14 @@ export async function runSetup(root, opts = {}) {
   if (design && design.tool && design.tool !== 'none') {
     hand(`confirm the design tool: run \`yad-connect-design\` to detect the ${design.tool} MCP (or it degrades to markdown-only)`);
   }
+  const testing = readJSON(testingPath, null);
+  if (testing && testing.tool && testing.tool !== 'none') {
+    hand(`confirm the testing tool: run \`yad-connect-testing\` to detect the ${testing.tool} MCP (or it degrades to artifacts-only)`);
+  }
+  const learning = readJSON(learningPath, null);
+  if (learning && learning.tool && learning.tool !== 'none') {
+    hand(`confirm the learning tool: run \`yad-connect-learning\` to detect the ${learning.tool} CLI (or it degrades to harness-native)`);
+  }
   hand('author your first epic: run `yad-epic`');
   log('');
   log(c.dim('Re-run anytime: `yad check` (report) / `yad check --fix` (reconcile).'));