yadflow 2.2.0 → 2.4.0

package/docs/index.html

@@ -284,7 +284,7 @@
     <div class="lane">
       <div class="lane-title">0 · One-time setup (team lead, per project)</div>
       <div class="flow-v">
-        <div class="node plain"><strong>Install the module</strong><small><code>npx yadflow setup</code> — copies the 18 skills into your IDE dirs</small></div>
+        <div class="node plain"><strong>Install the module</strong><small><code>npx yadflow setup</code> — copies the 22 skills into your IDE dirs</small></div>
         <div class="arrow-v">▼</div>
         <div class="node plain"><strong>Wire each repo</strong><small><code>yad-checks</code> · <code>yad-pr-template</code> · <code>yad-review-comments</code> (CI gates, PR template, comment scaffold)</small></div>
         <div class="arrow-v">▼</div>
@@ -292,6 +292,10 @@
         <div class="arrow-v">▼</div>
         <div class="node plain"><strong>Connect a design tool</strong><small><code>yad-connect-design</code> → <code>design.json</code> (Figma-first, pluggable) so <code>yad-ui</code> can materialize the screens <em>(optional — degrades to markdown-only)</em></small></div>
         <div class="arrow-v">▼</div>
+        <div class="node plain"><strong>Connect a testing tool</strong><small><code>yad-connect-testing</code> → <code>testing.json</code> (Playwright-first, pluggable) so <code>yad-test-cases</code> can implement the automation <em>(optional — degrades to artifacts-only)</em></small></div>
+        <div class="arrow-v">▼</div>
+        <div class="node plain"><strong>Connect a learning tool</strong><small><code>yad-connect-learning</code> → <code>learning.json</code> (DeepTutor-first, pluggable) so the learning layer can tutor in context <em>(optional — degrades to harness-native)</em></small></div>
+        <div class="arrow-v">▼</div>
         <div class="node plain"><strong>Optional: hub on a platform</strong><small>detect GitHub/GitLab + reviewer roster, so reviews run on real PRs/MRs</small></div>
       </div>
     </div>
@@ -321,7 +325,9 @@
         <div class="arrow-v">▼</div>
         <div class="node gate">gate · stories review<small><strong>per-repo:</strong> base rule + the engineer of each touched repo</small></div>
         <div class="arrow-v">▼</div>
-        <div class="node sentinel"><strong>ready-for-build</strong><small>the front half is done — building can start</small></div>
+        <div class="node sentinel"><strong>ready-for-build</strong><small>the gating front half is done — building can start (and <code>yad-test-cases</code> opens in parallel)</small></div>
+        <div class="arrow-v">▼</div>
+        <div class="node artifact"><strong>yad-test-cases</strong> <em>(parallel · non-blocking)</em><small>opens when the stories gate passes and runs <strong>alongside the build half</strong> — with the test architect → <code>test-cases.md</code> + the automation tests in the connected testing tool (<code>test-links.json</code>) → its own base-rule review. Never blocks <code>ready-for-build</code>.</small></div>
       </div>
     </div>
 
@@ -371,9 +377,10 @@
     contract.md          the LOCKED shared surface (APIs, events, data model)
     ui-design.md         + DESIGN.md (+ the screens in the connected design tool)
     stories/             one file per story (EP-&lt;slug&gt;-S01.md …)
+    test-cases.md        the test cases (+ the automation tests when a testing tool is connected)
     reviews/             reviewer comments, per artifact
     .sdlc/               state.json · approvals.json · contract-lock.json
-                         design-links.json · build-state/ · trust-log.json · build-log.json
+                         design-links.json · test-links.json · build-state/ · trust-log.json · build-log.json
 
 each code repo/
   specs/&lt;story-id&gt;/      spec, plan, tasks (+ link.md back to the story)
@@ -440,8 +447,8 @@ each code repo/
   <div class="term"><strong>State machine</strong><span class="badge b-core">core</span><br>The core design: the workflow is a fixed set of <em>states</em> (steps). Each state does its work and waits at a gate. The states never change — only the <em>trigger</em> (who moves work forward) changes. That is what lets the team start fully manual and automate gradually without rebuilding anything.</div>
   <div class="term"><strong>Product hub (product repo)</strong><span class="badge b-core">core</span><br>The git repo that holds the shared “thinking”: epics, architecture, the contract, UI design, stories, reviews and all state. The brain of the project. Code never lives here.</div>
   <div class="term"><strong>Code repo</strong><span class="badge b-core">core</span><br>A separate git repo holding real application code (e.g. backend, mobile, dashboard). Each story’s spec lives inside the code repo it belongs to, with a link back to the story in the hub.</div>
-  <div class="term"><strong>Skills source (this repo)</strong><span class="badge b-core">core</span><br>The <code>yadflow</code> repo itself — where the 18 skills live and where you pull updates from. No real product work happens inside it.</div>
-  <div class="term"><strong>Front half (“decide” / the brain)</strong><span class="badge b-core">core</span><br>The first half of the workflow, run once per epic in the product hub: analysis (optional) → epic → architecture + contract → UI design → stories — each followed by a human review gate. Permanently human-approved.</div>
+  <div class="term"><strong>Skills source (this repo)</strong><span class="badge b-core">core</span><br>The <code>yadflow</code> repo itself — where the 22 skills live and where you pull updates from. No real product work happens inside it.</div>
+  <div class="term"><strong>Front half (“decide” / the brain)</strong><span class="badge b-core">core</span><br>The first half of the workflow, run once per epic in the product hub: analysis (optional) → epic → architecture + contract → UI design → stories — each followed by a human review gate, ending at <code>ready-for-build</code>. <strong>Test cases</strong> is a parallel, non-blocking track that opens at the stories gate and runs alongside the build half. Permanently human-approved.</div>
   <div class="term"><strong>Back half / build half (“build”)</strong><span class="badge b-core">core</span><br>The second half, run once per story per code repo, inside that repo: spec → implement → checks → PR → ship. These mechanical steps may earn automation over time.</div>
   <div class="term"><strong>Gate</strong><span class="badge b-core">core</span><br>A stopping point after a step. The step writes its output and <em>waits</em>; a human must approve before the workflow moves on. “Every step stops at a gate” is the heart of the whole system.</div>
   <div class="term"><strong>Assistance dial</strong><span class="badge b-core">core</span><br>A per-step setting for how much AI helps with the work: <code>none</code>, <code>review</code> (AI checks human work), or <code>heavy</code> (AI does the drafting, human directs).</div>
@@ -520,7 +527,7 @@ each code repo/
   <div class="term"><strong>Trust threshold</strong><span class="badge b-auto">automation</span><br>The bar a step must clear to earn automation — by default at least 5 runs with ≥80% “approved-unchanged” (configurable in <code>config.yaml</code>).</div>
   <div class="term"><strong>Run verdicts</strong><span class="badge b-auto">automation</span><br>How each engineer review scores an automated run: <code>approved-unchanged</code> (merged exactly as authored — the strongest signal), <code>approved-with-edits</code> (a human fixed it first), <code>rejected</code> (failed).</div>
   <div class="term"><strong>Kill switch</strong><span class="badge b-auto">automation</span><br><code>yad-run action: kill</code> — one move that forces <em>every</em> step system-wide back to <code>human_approve</code> instantly, no code change needed. <code>unkill</code> restores earned automation. Automation is always reversible in one move.</div>
-  <div class="term"><strong>Locked steps</strong><span class="badge b-auto">automation</span><br>The steps that may <em>never</em> be set to <code>machine_advance</code>: all four front authoring steps, their reviews, and the engineer review. A front state advances only on a human act.</div>
+  <div class="term"><strong>Locked steps</strong><span class="badge b-auto">automation</span><br>The steps that may <em>never</em> be set to <code>machine_advance</code>: all five front authoring steps, their reviews, and the engineer review. A front state advances only on a human act.</div>
   <div class="term"><strong>Fleet roll-up</strong><span class="badge b-auto">automation</span><br>The cross-epic summary <code>yad-status</code> prints: where every epic stands, which steps are “earned but still manual” (nudge cost), at a glance.</div>
 
   <h3>Tools the workflow builds on</h3>
@@ -531,7 +538,7 @@ each code repo/
   <div class="term"><strong>CodeRabbit</strong><span class="badge b-tool">tools</span><br>An AI code-review service used as the advisory first pass on PRs. Optional; never the merge authority.</div>
   <div class="term"><strong>Graceful degradation</strong><span class="badge b-tool">tools</span><br>The rule that every optional tool (Spec Kit, Impeccable, Repomix, CodeRabbit) can be absent: the workflow falls back to doing the work directly and <em>records</em> that the tool was missing. You can start with none of them.</div>
   <div class="term"><strong>Tool-agnostic rule</strong><span class="badge b-tool">tools</span><br>Talk to every tool through its commands and files, never through its internal code — so each tool stays swappable.</div>
-  <div class="term"><strong>Skill</strong><span class="badge b-tool">tools</span><br>One of the 18 named agents (e.g. <code>yad-epic</code>) you invoke by name in your AI IDE. Each skill does one step’s work, writes files, and stops at its gate.</div>
+  <div class="term"><strong>Skill</strong><span class="badge b-tool">tools</span><br>One of the 22 named agents (e.g. <code>yad-epic</code>) you invoke by name in your AI IDE. Each skill does one step’s work, writes files, and stops at its gate.</div>
   <div class="term"><strong>The <code>yad</code> CLI</strong><span class="badge b-tool">tools</span><br>A zero-dependency command-line tool (npm: <code>yadflow</code>) that installs, wires and reconciles the workflow (<code>setup</code>, <code>check --fix</code>, <code>update</code>) and runs the deterministic pieces (<code>gate</code>, <code>commit</code>, <code>open-pr</code>, <code>repo</code>).</div>
 
   <h3>People &amp; AI roles</h3>
@@ -574,7 +581,7 @@ each code repo/
     <div class="flow-v">
       <div class="node plain"><strong>Setup</strong><small>install skills · create the hub repo · create empty code repos · wire each repo (CI gates + PR template) · <s>connect-repos</s> <em>skipped — nothing to map yet</em></small></div>
       <div class="arrow-v">▼</div>
-      <div class="node artifact"><strong>Front half</strong><small>(analysis) → epic → architecture + contract → UI (<code>craft</code> → <code>extract</code>) → stories — all human-gated</small></div>
+      <div class="node artifact"><strong>Front half</strong><small>(analysis) → epic → architecture + contract → UI (<code>craft</code> → <code>extract</code>) → stories — all human-gated; then test cases runs in parallel with the build half</small></div>
       <div class="arrow-v">▼</div>
       <div class="node"><strong>Build half</strong><small>spec → implement → checks → PR → ship, per story per repo — specs exist for 100% of the code from day one</small></div>
       <div class="arrow-v">▼</div>
@@ -674,7 +681,7 @@ each code repo/
 
 <!-- ======================================================= -->
 <section id="skills">
-  <h2>6. The 18 skills — what each does, how to use it, and when</h2>
+  <h2>6. The 22 skills — what each does, how to use it, and when</h2>
   <p>A <strong>skill</strong> is an agent you invoke <em>by name</em> in your AI IDE — you just ask in
   plain words, e.g. <em>“run <code>yad-epic</code>”</em>, adding any inputs the skill needs
   (<code>repo: backend</code>, <code>story: EP-…-S01</code>, <code>action: wire</code>, …).
@@ -685,11 +692,13 @@ each code repo/
     <tr><th>Skill</th><th>Half</th><th>One line</th></tr>
     <tr><td><a href="#sk-connect"><code>yad-connect-repos</code></a></td><td>Setup</td><td>Register a code repo with the hub + cache its code-map.</td></tr>
     <tr><td><a href="#sk-connect-design"><code>yad-connect-design</code></a></td><td>Setup</td><td>Connect a design tool (Figma-first) so <code>yad-ui</code> can materialize the screens.</td></tr>
+    <tr><td><a href="#sk-connect-testing"><code>yad-connect-testing</code></a></td><td>Setup</td><td>Connect a testing tool (Playwright-first) so <code>yad-test-cases</code> can implement the automation.</td></tr>
     <tr><td><a href="#sk-analysis"><code>yad-analysis</code></a></td><td>Front</td><td><em>(Optional)</em> pressure-test an idea into <code>analysis.md</code>.</td></tr>
     <tr><td><a href="#sk-epic"><code>yad-epic</code></a></td><td>Front</td><td>Start a feature: write <code>epic.md</code>, assign the ID.</td></tr>
     <tr><td><a href="#sk-arch"><code>yad-architecture</code></a></td><td>Front</td><td>Author <code>architecture.md</code> + the locked <code>contract.md</code>.</td></tr>
     <tr><td><a href="#sk-ui"><code>yad-ui</code></a></td><td>Front</td><td>Author <code>ui-design.md</code> + <code>DESIGN.md</code>; materialize the screens in the connected design tool.</td></tr>
     <tr><td><a href="#sk-stories"><code>yad-stories</code></a></td><td>Front</td><td>Break the epic into repo-tagged stories.</td></tr>
+    <tr><td><a href="#sk-test-cases"><code>yad-test-cases</code></a></td><td>Front</td><td>With the test architect, author the test cases; implement the automation when a testing tool is connected.</td></tr>
     <tr><td><a href="#sk-gate"><code>yad-review-gate</code></a></td><td>Cross-cutting</td><td>Review / comment / approve / advance <strong>any</strong> gate.</td></tr>
     <tr><td><a href="#sk-bridge"><code>yad-hub-bridge</code></a></td><td>Cross-cutting</td><td>Run front-half reviews over real PRs/MRs and sync them back.</td></tr>
     <tr><td><a href="#sk-comments"><code>yad-review-comments</code></a></td><td>Setup</td><td>Install the structured review-comment scaffolds.</td></tr>
@@ -729,6 +738,40 @@ yad-connect-design action: disconnect</code></pre>
     <div class="row"><span class="lbl lbl-when">When</span> During one-time setup (the wizard records it), and again any time you switch design tools. <strong>No design tool? Skip it</strong> — <code>yad-ui</code> simply authors the Markdown, exactly as before.</div>
   </div>
 
+  <div class="skillcard" id="sk-connect-testing">
+    <h4><code>yad-connect-testing</code></h4>
+    <div class="row"><span class="lbl lbl-what">What</span> Connects a <strong>testing tool</strong> to the product hub so the test-cases step can implement the <em>actual</em> automation tests inside it, alongside the Markdown. <strong>Playwright-first but pluggable</strong> (a testing-tool adapter; <code>cypress</code> and <code>pytest</code> are second providers). It records the tool + project/suite references in <code>testing.json</code> through your own authenticated MCP session — <strong>no tokens are ever stored</strong> — and degrades to artifacts-only when no testing-tool MCP is available.</div>
+    <div class="row"><span class="lbl lbl-how">How</span> Run it in the product hub, once per project:</div>
+<pre><code>yad-connect-testing action: connect tool: playwright project_url: tests/playwright.config.ts
+yad-connect-testing action: list                 # show the connection + whether the MCP is available
+yad-connect-testing action: refresh              # re-detect the MCP (after authenticating a session)
+yad-connect-testing action: disconnect</code></pre>
+    <div class="row"><span class="lbl lbl-when">When</span> During one-time setup (the wizard records it), and again any time you switch testing tools. <strong>No testing tool? Skip it</strong> — <code>yad-test-cases</code> simply authors the test cases, exactly as before.</div>
+  </div>
+
+  <div class="skillcard" id="sk-connect-learning">
+    <h4><code>yad-connect-learning</code></h4>
+    <div class="row"><span class="lbl lbl-what">What</span> Connects a <strong>learning/tutoring tool</strong> to the product hub so the cross-cutting <strong>learning layer</strong> can tutor any team member, at any stage, in the context of what's being built. <strong>DeepTutor-first but pluggable.</strong> Unlike the design/testing tools, DeepTutor is a <strong>CLI subprocess</strong> (like Repomix's <code>npx</code>) — it ships no MCP — so this skill detects the <code>deeptutor</code> binary on PATH and optionally builds a project knowledge base from the SDLC artifacts + secret-scanned code-maps. It records the connection in <code>learning.json</code> — <strong>no tokens are ever stored</strong> — and degrades to <strong>harness-native</strong> tutoring when DeepTutor isn't installed.</div>
+    <div class="row"><span class="lbl lbl-how">How</span> Run it in the product hub, once per project:</div>
+<pre><code>yad-connect-learning action: connect tool: deeptutor
+yad-connect-learning action: list                # show the connection + whether the CLI is available
+yad-connect-learning action: refresh             # re-detect the CLI + rebuild the knowledge base
+yad-connect-learning action: disconnect</code></pre>
+    <div class="row"><span class="lbl lbl-when">When</span> During one-time setup (the wizard records it), and again any time you switch learning tools. <strong>No DeepTutor? Skip it</strong> — <code>yad-learn</code> still tutors using the harness model reading your artifacts.</div>
+  </div>
+
+  <h3>The learning layer — tutor any member, any stage (cross-cutting)</h3>
+
+  <div class="skillcard" id="sk-learn">
+    <h4><code>yad-learn</code></h4>
+    <div class="row"><span class="lbl lbl-what">What</span> The <strong>learning layer</strong>. At <em>any</em> SDLC stage a team member can ask to learn a concept and be tutored <em>in the context of what the team is building</em> — e.g. "teach me why the architecture hash-locks the contract surface." It routes to the connected learning tool (DeepTutor, grounded in the project knowledge base) or degrades to <strong>harness-native</strong> tutoring, renders a tutorial artifact, and appends to a per-member <strong>learning ledger</strong> kept <strong>local-only</strong> (gitignored — never committed or pushed, to the hub or any code repo) so it stays a private, personal skills log (<code>yad-status</code> rolls up the local records). <strong>Purely opt-in — it never blocks a gate</strong> and never touches epic state, approvals, or the contract lock.</div>
+    <div class="row"><span class="lbl lbl-how">How</span> Any time, from any stage:</div>
+<pre><code>run yad-learn — concept: "contract versioning" epic: EP-istifta-inquiries stage: architecture-review
+yad-learn action: list                           # your local skills-log records for this epic
+yad-learn action: complete concept: "contract versioning"   # mark it learned</code></pre>
+    <div class="row"><span class="lbl lbl-when">When</span> Whenever a member wants to understand what is being built — to review a gate with confidence, onboard onto a domain, or grow a skill. It is additive and reversible: learning never gates the work.</div>
+  </div>
+
   <h3>Front half — author the thinking (in the product hub)</h3>
 
   <div class="skillcard" id="sk-analysis">
@@ -768,7 +811,15 @@ yad-connect-design action: disconnect</code></pre>
     <div class="row"><span class="lbl lbl-what">What</span> With the pm AI, slices the approved epic into user stories small enough to build — one file each under <code>stories/</code>, with stable IDs (<code>EP-&lt;slug&gt;-S01</code>…) and a <code>repos:</code> tag naming which code repos must implement each one. Reads epic + architecture + contract + UI as input.</div>
     <div class="row"><span class="lbl lbl-how">How</span> In the product hub, after the UI gate passes:</div>
 <pre><code>run yad-stories — epic: EP-istifta-inquiries</code></pre>
-    <div class="row"><span class="lbl lbl-when">When</span> The last front-half author step. Stops at the <strong>stories review gate</strong> (per-repo rule). When that gate passes, the epic is <code>ready-for-build</code>.</div>
+    <div class="row"><span class="lbl lbl-when">When</span> After the UI gate passes. Stops at the <strong>stories review gate</strong> (per-repo rule). When it passes the epic is <code>ready-for-build</code> — the build half can start, and <code>yad-test-cases</code> opens in parallel.</div>
+  </div>
+
+  <div class="skillcard" id="sk-test-cases">
+    <h4><code>yad-test-cases</code></h4>
+    <div class="row"><span class="lbl lbl-what">What</span> With the <strong>test architect</strong> AI (Murat), authors the risk-based test cases that cover the approved stories → <code>test-cases.md</code> (cases prioritised P0–P3, with story→case traceability). When a testing tool is connected (<code>yad-connect-testing</code>), it also <strong>implements the automation tests in that tool</strong> — generating them into the connected code repo(s) or linking an existing suite — and records the case→test map in <code>test-links.json</code>; otherwise it stays artifacts-only. Reads epic + architecture + contract + UI + stories as input.</div>
+    <div class="row"><span class="lbl lbl-how">How</span> In the product hub, after the stories gate passes:</div>
+<pre><code>run yad-test-cases — epic: EP-istifta-inquiries</code></pre>
+    <div class="row"><span class="lbl lbl-when">When</span> A <strong>parallel, non-blocking</strong> track: it opens the moment the stories gate passes — the epic is already <code>ready-for-build</code>, so this runs <strong>alongside the build half</strong>, not before it. Stops at its own <strong>test-cases review gate</strong> (base rule); that review never blocks building.</div>
   </div>
 
   <h3>The review gate &amp; its plumbing (cross-cutting)</h3>
@@ -897,7 +948,7 @@ yad-status EP-istifta-inquiries     # one epic in detail</code></pre>
 
   <div class="skillcard">
     <h4><code>npx yadflow setup</code></h4>
-    <div class="row"><span class="lbl lbl-what">What</span> The guided first-run wizard. Eight steps: preflight (git/node check), install all 18 skills into the IDE dirs you pick, detect the hub’s platform + record the reviewer roster, connect a design tool (Figma-first; optional), connect your code repos, wire each one (CI gates, PR template, comment scaffold), optionally write the AI-review config, and stamp the installed version.</div>
+    <div class="row"><span class="lbl lbl-what">What</span> The guided first-run wizard. Ten steps: preflight (git/node check), install all 22 skills into the IDE dirs you pick, detect the hub’s platform + record the reviewer roster, connect a design tool (Figma-first; optional), connect a testing tool (Playwright-first; optional), connect a learning tool (DeepTutor-first; optional), connect your code repos, wire each one (CI gates, PR template, comment scaffold), optionally write the AI-review config, and stamp the installed version.</div>
     <div class="row"><span class="lbl lbl-how">How</span></div>
 <pre><code>cd &lt;product-hub-repo&gt;
 npx yadflow setup</code></pre>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yadflow",
-  "version": "2.2.0",
-  "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, repo). A BMAD module + 17 yad-* skills.",
+  "version": "2.4.0",
+  "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, repo). A BMAD module + 22 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",
   "license": "MIT",
@@ -50,7 +50,9 @@
     "bmad",
     "workflow",
     "cli",
-    "spec-driven-development"
+    "spec-driven-development",
+    "learning",
+    "deeptutor"
   ],
   "devDependencies": {
     "@eslint/js": "^9.39.4",

package/skills/sdlc/config.yaml

@@ -20,12 +20,12 @@ output_folder: "{project-root}/_bmad-output"
 defaults:
   assistance: review          # none | review | heavy
   automation: human_approve   # human_approve | machine_advance
-  # Front steps (analysis [optional], epic, architecture, ui-design, stories) are locked to
+  # Front steps (analysis [optional], epic, architecture, ui-design, stories, test-cases) are locked to
   # human_approve and may NOT be set to machine_advance in this version (build plan §1, §8.7).
   front_steps_locked: true
   # Each front authoring step opens its own branch at the start of the step (the <step> is the step id:
-  # analysis | epic | architecture | ui-design | stories). Git/greenfield-safe; distinct from the
-  # bridge's review branch (hub.artifact_branch). See yad-epic/references/state-schema.md.
+  # analysis | epic | architecture | ui-design | stories | test-cases). Git/greenfield-safe; distinct
+  # from the bridge's review branch (hub.artifact_branch). See yad-epic/references/state-schema.md.
   front_authoring_branch: "<step>/EP-<slug>"
 
 # Team review gate defaults (build plan §3 piece 2, §4).
@@ -134,6 +134,43 @@ design:
   # NO tokens in the registry (project_url/files are plain references, never credentials).
   auth: user
 
+# Testing tool (yad-connect-testing) — the test-cases step (yad-test-cases) materializes the actual
+# automation tests inside a connected testing tool, alongside test-cases.md. The tool is reached through
+# its MCP (a harness MCP server, like the design tool — NOT a CLI), detected per provider and DEGRADING
+# to artifacts-only when absent. Playwright-first but PLUGGABLE: a testing-tool adapter, like the
+# design-tool adapter. Connection is one-per-project, recorded at setup; the per-epic case->test map
+# (test-links.json) is written by yad-test-cases per epic.
+testing:
+  registry: "{project-root}/.sdlc/testing.json"      # project-wide testing connection (NOT per-epic)
+  tools: [playwright, cypress, pytest]                # supported adapters; an unknown tool falls back to `primary`
+  primary: playwright                                 # the default/named provider
+  degrade: artifacts-only                             # no tool / no MCP => yad-test-cases authors test-cases.md only
+  links: "{project-root}/epics/EP-<slug>/.sdlc/test-links.json"   # per-epic case->test map (yad-test-cases)
+  # Auth: `yad-connect-testing` connects through the LOCAL user's own authenticated MCP session and stores
+  # NO tokens in the registry (project_url/suites are plain references, never credentials).
+  auth: user
+
+# Learning tool (yad-connect-learning) — the cross-cutting LEARNING LAYER. At any SDLC stage a team member
+# can invoke `yad-learn` to be tutored on a concept IN THE CONTEXT of what is being built, and the request
+# is recorded in a personal, LOCAL-ONLY skills log (gitignored, never committed/pushed; surfaced read-only
+# by yad-status for the local learner). The tool is
+# DeepTutor (https://github.com/HKUDS/DeepTutor) — an Apache-2.0 Python CLI, reached as a SUBPROCESS like
+# Repomix's `npx` (it has NO MCP), NOT the MCP shape of the design/testing tools. DeepTutor-first but
+# PLUGGABLE: a learning-tool adapter. Connection is one-per-project, recorded at setup; the per-epic,
+# per-member learning ledger (learning-records.json) + rendered tutorials are written by yad-learn.
+learning:
+  registry: "{project-root}/.sdlc/learning.json"     # project-wide learning connection (NOT per-epic) — the ONLY committed learning file (no secrets/personal data)
+  tools: [deeptutor]                                  # supported adapters; an unknown tool falls back to `primary`
+  primary: deeptutor                                  # the default/named provider
+  degrade: harness-native                             # no deeptutor CLI => yad-learn tutors via the harness model
+                                                      # reading the project artifacts directly (always works, never blocks)
+  records: "{project-root}/epics/EP-<slug>/.sdlc/learning-records.json"   # per-epic learning ledger (yad-learn) — LOCAL-ONLY, gitignored, never committed/pushed
+  artifacts: "{project-root}/epics/EP-<slug>/learning/"   # rendered tutorial markdown (yad-learn) — LOCAL-ONLY, gitignored, never committed/pushed
+  capabilities: { explain: chat, deep: deep_research, quiz: deep_question }   # yad-learn mode -> deeptutor capability
+  # Auth: `yad-connect-learning` uses the LOCAL user's own deeptutor CLI config/session and stores NO
+  # tokens in the registry (kb name + sources are plain references, never credentials). Opt-in, never a gate.
+  auth: user
+
 # Hub platform + front-half review bridge (yad-connect-repos `detect-hub`; yad-review-gate + yad-hub-bridge).
 # The product hub is itself a git repo on a platform. With the bridge enabled, the front-half review/
 # comment/approval cycle runs through a real PR/MR on the hub: a review PR is opened per artifact, reviewers
@@ -166,7 +203,7 @@ automation:
   # Hard lock — the dial-setter REFUSES machine_advance for these, regardless of trust evidence.
   # The front authoring steps (already locked:true in state.json; analysis is optional) + the human
   # merge gate.
-  locked_steps: [analysis, epic, architecture, ui-design, stories, engineer-review]
+  locked_steps: [analysis, epic, architecture, ui-design, stories, test-cases, engineer-review]
   # Kill switch (phase-4-build-plan.md §Safety): true => every step forced to human_approve
   # system-wide, no per-step edits. One line, instantly reversible. Toggle via `yad-run action: kill`.
   kill_switch: false

package/skills/sdlc/install.sh

@@ -11,7 +11,7 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$ROOT"
 
-SKILLS=(yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-connect-repos yad-connect-design yad-spec yad-implement yad-checks yad-pr-template yad-review-comments yad-hub-bridge yad-ship yad-backfill yad-run yad-review-gate yad-status)
+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 yad-pr-template yad-review-comments yad-hub-bridge yad-ship yad-backfill yad-run yad-review-gate yad-status)
 
 echo "Installing sdlc module from $ROOT/skills ..."
 

package/skills/sdlc/module-help.csv

@@ -1,11 +1,16 @@
 module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+SDLC Workflow,yad-analysis,Author Analysis,AN,"Optional front state: 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 chain that puts analysis before epic). If skipped, the epic step does this shaping inline. Never auto-advances.",,{idea: one-line feature idea},1-front,,yad-review-gate,false,epics/EP-<slug>/,analysis.md state.json
 SDLC Workflow,yad-epic,Author Epic,AE,"Front state 1: shape an idea with analyst then pm into epic.md; assign EP-<slug> ID and seed .sdlc state. Never auto-advances.",,{idea: one-line feature idea},1-front,,yad-review-gate,true,epics/EP-<slug>/,epic.md state.json
-SDLC Workflow,yad-review-gate,Team Review Gate,RG,"Reusable review+approve gate for all four reviews. Shares an artifact for review, records comments and approvals as files, enforces owner + 1 reviewer (escalates on contract/auth/payments; per-repo routing for stories), advances state only when approved.",,{artifact: file under the epic} {action: open|comment|approve|advance},1-front,,,true,epics/EP-<slug>/reviews/,reviews/*.md approvals.json state.json
+SDLC Workflow,yad-review-gate,Team Review Gate,RG,"Reusable review+approve gate for all five reviews. Shares an artifact for review, records comments and approvals as files, enforces owner + 1 reviewer (escalates on contract/auth/payments; per-repo routing for stories), advances state only when approved.",,{artifact: file under the epic} {action: open|comment|approve|advance},1-front,,,true,epics/EP-<slug>/reviews/,reviews/*.md approvals.json state.json
 SDLC Workflow,yad-architecture,Author Architecture,AA,"Front state 3: with the architect author architecture.md and the locked contract.md; hash-lock the contract surface. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,architecture.md contract.md contract-lock.json state.json
 SDLC Workflow,yad-ui,Author UI Design,AU,"Front state 5: with the ux-designer author ui-design.md and DESIGN.md, driving Impeccable slash-commands when installed. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,ui-design.md DESIGN.md state.json
 SDLC Workflow,yad-stories,Author Stories,AS,"Front state 7: with the pm break the epic into repo-tagged stories with stable EP-<slug>-S0N IDs, one file each under stories/. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/stories/,stories/EP-<slug>-S0N.md state.json
+SDLC Workflow,yad-test-cases,Author Test Cases,TC,"Front state 9 (PARALLEL, non-blocking): opens when the stories gate passes — the epic is already ready-for-build, so the build half can start at the same time the tester works here. With the test architect (Murat) author test-cases.md covering the approved stories, and — when a testing tool is connected (.sdlc/testing.json) — generate/link the actual automation tests in it, recording test-links.json; otherwise produce the test-case artifact only. Its review never moves currentStep off ready-for-build. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,test-cases.md test-links.json state.json
 SDLC Workflow,yad-connect-repos,Connect Code Repos,CR,"Setup/maintenance: connect code repos to the product hub so the front/brain phases are code-aware. Registers each repo (GitHub or GitLab, local-user auth, no stored tokens) in .sdlc/repos.json and caches a Repomix pack + a lightweight code-map (existing endpoints/events/data-models/modules, secret-scanned). Idempotent and refreshable; staleness tracked by HEAD sha. Run at setup or any time a new repo is added. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {repo: <name>} {path: <path-or-absolute>} {git_url: <ssh-or-https>} {domain_owner: <who>},0-setup,,yad-epic,false,.sdlc/,repos.json code-context/<repo>/pack.md code-context/<repo>/code-map.md
 SDLC Workflow,yad-connect-design,Connect Design Tool,CD,"Setup/maintenance: connect a design tool (Figma-first, pluggable) to the product hub so the UI design step can materialize the actual feature design (mobile screens / web pages) inside it, alongside ui-design.md + DESIGN.md. Records the tool + project/file references in .sdlc/design.json (local-user / MCP-session auth, no stored tokens), detecting whether a design-tool MCP is available and degrading to markdown-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: figma|pencil|none} {project_url: <team/project/file url>} {files: {web,mobile}},0-setup,,yad-ui,false,.sdlc/,design.json
+SDLC Workflow,yad-connect-testing,Connect Testing Tool,CT,"Setup/maintenance: connect a testing tool (Playwright-first, pluggable) to the product hub so the test-cases step can implement the actual automation tests in it, alongside test-cases.md. Records the tool + project/suite references in .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 absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: playwright|cypress|pytest|none} {project_url: <project/config reference>} {suites: {<repo>}},0-setup,,yad-test-cases,false,.sdlc/,testing.json
+SDLC Workflow,yad-connect-learning,Connect Learning Tool,CL,"Setup/maintenance: connect a learning/tutoring tool (DeepTutor-first, pluggable) so the cross-cutting learning layer can tutor any team member, at any SDLC stage, in the context of what is being built. Records the tool + an optional grounded knowledge base in .sdlc/learning.json (local-user auth, no stored tokens), detecting whether the DeepTutor CLI is on PATH (a subprocess like Repomix, not an MCP) and degrading to harness-native tutoring when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: deeptutor|none} {kb: <name>} {ground: true|false},0-setup,,yad-learn,false,.sdlc/,learning.json
+SDLC Workflow,yad-learn,Learn (Tutor),LN,"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 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). Renders a tutorial artifact and appends to a per-member learning ledger kept LOCAL-ONLY (gitignored, never committed/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 — never blocks a gate, never touches epic state, approvals, or the contract lock.",,{concept: <idea>} {context: <focus>} {epic: EP-<slug>} {stage: <sdlc stage>} {member: <who>} {mode: explain|deep|quiz} {action: learn|list|complete},,,,,false,epics/EP-<slug>/,learning-records.json learning/<member>--<concept>.md
 SDLC Workflow,yad-spec,Author Spec,SP,"Build-half Step A: for one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony once (specify→clarify→plan→analyze→checklist→tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit's layout (drives /speckit.* when installed, else hand-authors and records speckit: not-installed). References the locked contract; never re-invents the surface. Writes link.md back to the story. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>},3-build,yad-review-gate,,false,demo-repos/<repo>/specs/<story-id>/,spec.md research.md data-model.md contracts/ plan.md tasks.md link.md
 SDLC Workflow,yad-implement,Implement Task,IM,"Build-half Step B: with the dev lens, implement ONE atomic task from a story's tasks.md as a small diff (<=3 files) on its own branch feat/<story>-<task>-<slug> in the code repo. Diff stays inside the task's declared files (flag and STOP if it grows beyond them). Commit ends with a Task: <story>-<task> trailer; add Contract-Change: yes only when the locked contract surface is touched (routes back to the architecture gate). Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>} {task: T0N},3-build,yad-spec,,false,demo-repos/<repo>/,branch+commit per atomic task
 SDLC Workflow,yad-checks,Check Gates,CK,"Build-half Step C: wire and run the three production-safety CI gates on a code repo — spec-link (every change links a real story/spec via its Task trailer), contract-check (a contract-surface change without Contract-Change + an updated re-locked contract FAILS and routes back to the architecture gate), and build/test/lint. CI-agnostic bash invoked by GitHub Actions and GitLab CI. Blocking in CI; the human still owns the merge. Never auto-advances.",,{repo: <one of an epic's repos>} {action: wire|run} {base: target branch},3-build,yad-implement,,false,demo-repos/<repo>/,checks/*.sh .github/workflows/yad-checks.yml .gitlab-ci.yml

package/skills/yad-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-analysis
-description: 'Optional front state 1 of the gated SDLC. 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). Never auto-advances — hands off to the team review gate. Optional: if skipped, the epic step does this shaping inline. Use when the user says "analyse the idea", "start with analysis", or "author the analysis".'
+description: 'Optional front state 1 of the gated SDLC. 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 12-step chain that puts analysis before epic). Never auto-advances — hands off to the team review gate. Optional: if skipped, the epic step does this shaping inline. Use when the user says "analyse the idea", "start with analysis", or "author the analysis".'
 ---
 
 # SDLC — Author Analysis (optional front state 1)
@@ -11,8 +11,8 @@ state machine in `.sdlc/`. This is a **front state**: human-authored with AI ass
 auto-advances**. When the analysis is drafted, control passes to `yad-review-gate`.
 
 This step is **optional**. When it runs, it is the entry point: it assigns the ID and seeds the
-**10-step** chain (`analysis` before `epic`). When it is **skipped**, `yad-epic` does the same
-analyst shaping inline and seeds the **8-step** chain — no behaviour change for teams that skip it.
+**12-step** chain (`analysis` before `epic`). When it is **skipped**, `yad-epic` does the same
+analyst shaping inline and seeds the **10-step** chain — no behaviour change for teams that skip it.
 
 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`.
@@ -88,7 +88,7 @@ code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # which code-maps in
 Fill the body with the user; leave `owner` for the user to set.
 
 ### Step 6 — Seed the state machine
-Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **10-step** front-state
+Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **12-step** front-state
 sequence (analysis before epic), all steps defaulting to `automation: human_approve`, with every
 authoring step **locked**. Use this exact shape (see `references/state-schema.md`):
 
@@ -107,7 +107,9 @@ authoring step **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": [] }
   ]
 }
 ```
@@ -116,6 +118,9 @@ Notes:
 - `analysis-review` carries no `risk_tags` — it is the **base** rule (owner + 1 reviewer).
 - `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 — the epic is already `ready-for-build` by then, so the build half runs
+  alongside the tester (see `../yad-epic/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.

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

@@ -20,7 +20,7 @@ markdown-only exactly as before.
 
 - `{project-root}` resolves from the project working directory (the **product hub**).
 - The integration is **Figma-first but pluggable** (`config.yaml` `design.tools`): a design-tool
-  *adapter*, like the `github`/`gitlab` platform adapter. Figma is the primary provider; `pencil`
+  *adapter*, like the GitHub/GitLab platform adapter. Figma is the primary provider; `pencil`
   (the `.pen` web/mobile editor) is a second, write-capable provider; `none` → markdown-only.
 - **The design tool is reached through its MCP** (a harness MCP server), NOT a subprocess CLI — the same
   shape as Impeccable's slash-commands, not Repomix's `npx`. The skill detects the MCP and degrades when

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

@@ -27,8 +27,10 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
 
 ## Rules
 
-- **`tool`** selects the adapter; it MUST be one of `config.yaml` `design.tools` (or `none`). An unknown
-  tool falls back to `design.primary` with a warning — never silently accepted.
+- **`tool`** selects the adapter; it MUST be one of `config.yaml` `design.tools` (or `none`). At
+  **connect** time an unknown tool is normalized to `design.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-002` and must be fixed.
 - **Auth is never stored.** No Figma PAT, OAuth token, or any credential in the registry. `project_url`
   and `files` are plain references; `connect` reaches the tool through the user's authenticated MCP
   session.

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

@@ -0,0 +1,140 @@
+---
+name: yad-connect-learning
+description: 'Connects a learning/tutoring tool (DeepTutor, or another tool — pluggable) to the product hub so the cross-cutting learning layer can tutor any team member, at any SDLC stage, in the context of what is being built. Registers the tool into the project-wide .sdlc/learning.json (local-user auth, no stored tokens), detecting whether the DeepTutor CLI is on PATH and degrading to harness-native tutoring (the harness model reading project artifacts) when it is not. Optionally builds a project knowledge base from the SDLC artifacts + secret-scanned code-maps so tutoring is grounded. Run at setup or any time the learning tool changes. Reusable, idempotent, refreshable. Use when the user says "connect DeepTutor", "connect a learning tool", "refresh the learning connection", or "list the learning connection".'
+---
+
+# SDLC — Connect a Learning Tool (the cross-cutting learning layer)
+
+**Goal:** Let any team member pause at **any** SDLC stage and ask to learn a concept — and get tutored
+*in the context of what the team is actually building*. This skill **connects** a learning tool such as
+**DeepTutor** to the product hub and records *how* to reach it (the tool, the CLI, an optional grounded
+knowledge base) — never a credential. The consumer skill **`yad-learn`** does the tutoring per request
+and records the team's skills.
+
+This is **setup/maintenance**, not a gated state — it never touches `.sdlc/state.json` or any epic's
+approvals. It only writes the project-wide learning registry. `yad-learn` consumes it: when DeepTutor is
+available it drives the CLI (grounded in the knowledge base); when nothing is connected, `yad-learn`
+degrades to **harness-native** tutoring — the harness model reads the project artifacts directly and
+explains the concept. The learning layer is **purely opt-in and never blocks a gate**.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory (the **product hub**).
+- The integration is **DeepTutor-first but pluggable** (`config.yaml` `learning.tools`): a learning-tool
+  *adapter*, like the design/testing adapters. `none` → harness-native (yad-learn still tutors via the
+  harness model).
+- **DeepTutor is reached as a CLI SUBPROCESS** (`deeptutor …`), the same shape as Repomix's `npx` — NOT
+  an MCP like the design/testing tools (DeepTutor ships no MCP server). The skill detects the **binary on
+  PATH** and degrades when it is absent; it never installs DeepTutor.
+- Registry: `{project-root}/.sdlc/learning.json` (project-wide, shared across all epics — NOT per-epic),
+  the sibling of `.sdlc/repos.json`, `.sdlc/hub.json`, `.sdlc/design.json`, and `.sdlc/testing.json`.
+- Per-epic, per-member learning records + rendered tutorials are written later by `yad-learn`
+  (`epics/EP-<slug>/.sdlc/learning-records.json` and `epics/EP-<slug>/learning/`), not here.
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## Inputs
+
+- `action` — `connect` (default) | `refresh` | `list` | `disconnect`.
+- `tool` — `deeptutor` | another adapter id (`config.yaml` `learning.tools`). `none` records a deliberate
+  harness-native project.
+- `kb` — optional knowledge-base name (default `yadflow-<project-slug>`). The DeepTutor kb that grounds
+  tutoring in this project.
+- `ground` — `true` (default) | `false`. When `true` and DeepTutor is available, build/refresh the
+  knowledge base from the SDLC artifacts + code-maps (the "grounded in the project" piece).
+
+## On Activation
+
+### Step 1 — Resolve the tool and detect the CLI (the learning-tool adapter)
+Determine which tool is being connected from `tool` (default `deeptutor`); reject a `tool` not in
+`config.yaml` `learning.tools` (fall back to the configured `learning.primary` with a warning, the same
+way `registerRepo`/`registerDesign` fall back). Then **detect the tool's CLI on PATH**:
+
+- **deeptutor** → run a best-effort `deeptutor --version` (or `deeptutor config show`). If it succeeds,
+  record `provider: "deeptutor-cli"` and the reported `version`.
+- another adapter → its named CLI.
+
+**Auth is the local user's own** — DeepTutor's own config (`deeptutor init`, `data/user/settings/`) and
+the user's LLM provider keys. The skill **stores no tokens**; `kb`/`kb_sources` are plain references.
+
+**Graceful degradation:** if the `deeptutor` binary is not on PATH, record `source: "harness-native"`
+and report that `yad-learn` will still tutor **using the harness model reading the project artifacts**
+(no error — the learning layer is additive and always works; DeepTutor only adds knowledge-base
+grounding, quizzes, and deep research). Do **not** install DeepTutor as part of this step.
+
+### Step 2 — Ground it in the project (optional, when DeepTutor is available)
+When `ground: true` and DeepTutor is available, build or refresh a project **knowledge base** so tutoring
+quotes what is actually being built:
+
+```
+deeptutor kb create <kb>            # idempotent: reuse if it exists
+deeptutor kb add <kb> --doc <path>  # per source below
+```
+
+Add only **already-committed** artifacts + the **secret-scanned code-maps** (never raw repos): each
+epic's `epic.md`, `architecture.md`, `contract.md`, `ui-design.md`, the `stories/` files, and every
+`.sdlc/code-context/<repo>/code-map.md`. Record the kb name and the source globs in the registry. Skip
+silently (record `kb: null`) when there are no artifacts yet (greenfield-safe).
+
+### Step 3 — Record the connection in the registry
+Upsert into `{project-root}/.sdlc/learning.json` (create the file + parent `.sdlc/` if absent):
+
+```json
+{
+  "tool": "deeptutor",
+  "provider": "deeptutor-cli",
+  "version": "1.4.5",
+  "kb": "yadflow-<project-slug>",
+  "kb_sources": ["epic.md", "architecture.md", "contract.md", "ui-design.md", "stories/", "code-context/*/code-map.md"],
+  "auth": "user",
+  "connectedAt": "<YYYY-MM-DD>",
+  "lastSyncedAt": "<YYYY-MM-DD>",
+  "source": "deeptutor-cli"
+}
+```
+
+- `tool: "none"` records a deliberate harness-native project: `{ "tool": "none", "provider": null,
+  "kb": null, "source": "harness-native", ... }`.
+- A DeepTutor connection whose CLI is absent records `{ "tool": "deeptutor", "provider": null,
+  "kb": null, "source": "harness-native", ... }` until a `refresh` finds the binary.
+- `connect` is **idempotent** — re-running it overwrites the single connection in place; the original
+  `connectedAt` is preserved and only `lastSyncedAt` moves.
+
+### Step 4 — Report (never auto-advance)
+Report the connected `tool`, its `provider`, whether the CLI is available (or that `yad-learn` will run
+harness-native), the `kb`, and that **`yad-learn` will now tutor team members on request**. Nothing
+auto-advances; this is setup.
+
+## Other actions
+
+- **`refresh`** — re-detect the CLI, rebuild the knowledge base from the latest artifacts, and update
+  `lastSyncedAt`. Same machinery as `connect`. Re-detection may flip `source` between `deeptutor-cli` and
+  `harness-native` — report the change.
+- **`list`** — print the current connection: `tool`, `provider`, `version`, the `kb`, and an
+  **available/harness-native** flag for the CLI (best-effort). No learning tool connected ⇒
+  "harness-native".
+- **`disconnect`** — remove the registry file (or set `tool: "none"`). DeepTutor's own config and
+  knowledge bases are **never touched** — only the hub's record of them.
+
+## Hard rules
+
+- **Local-user auth only; store no tokens.** Connect through the user's own DeepTutor config / LLM keys;
+  never embed a key or any credential in the registry. `kb`/`kb_sources` are plain references.
+- **Degrade gracefully.** No DeepTutor CLI → `yad-learn` tutors harness-native with no error. The
+  learning layer is additive and always works — never a blocker.
+- **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 learning
+  connection at a time.
+- **Ground only committed, secret-scanned sources.** Feed the knowledge base from committed SDLC
+  artifacts + the already-scanned code-maps — never raw repository contents.
+- **Describe the connection; do not tutor here.** This skill records *how to reach* the tool. The actual
+  tutoring + the personal, local-only learning records are produced by `yad-learn`, per request.
+- **The registry is the only committed learning file.** `.sdlc/learning.json` is shared, reviewable
+  config (no secrets, no personal data). The records ledger and tutorials `yad-learn` writes are
+  local-only — gitignored, never committed or pushed.
+
+## Reference
+- Registry schema + freshness rule: `references/learning-registry.md`.
+- CLI detection, the knowledge-base build recipe, the mode→capability map, and the harness-native degrade
+  path: `references/learning-context.md`.
+- The connect pattern this mirrors (testing tool): `../yad-connect-testing/SKILL.md`.
+- The consumer — how `yad-learn` tutors and writes `learning-records.json`: `../yad-learn/SKILL.md`.