yadflow 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -1,10 +1,28 @@
-# [2.3.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.2.0...v2.3.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 CodeRabbit review on PR [#48](https://github.com/abdelrahmannasr/yadflow/issues/48) ([2f182f7](https://github.com/abdelrahmannasr/yadflow/commit/2f182f72b68e226196b6190802771b0e12b585f9))
+
+
+### Features
+
+* 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

@@ -51,6 +51,8 @@ human**. Detailed walkthroughs for each phase follow below.
 | `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-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. |
@@ -123,10 +125,10 @@ 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 (9 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 20 `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
@@ -134,10 +136,13 @@ simultaneous advancements can be lost; the next event or scheduled sweep re-sync
 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 code repos** — register each repo into `.sdlc/repos.json` and cache a Repomix pack.
-7. **Wire each repo** — CI gates, PR/MR template, and review-comment scaffold.
-8. **AI review** — optionally write `.coderabbit.yaml`.
-9. **Done** — stamp `.sdlc/cli-version.json` and hand off the AI-only steps (code-maps; first epic).
+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
@@ -175,10 +180,11 @@ with a fix-it hint per finding. Failures carry stable, greppable codes, also pri
 | `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 20)
+## 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
@@ -201,6 +207,25 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
   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)
 
@@ -297,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).
@@ -318,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).
 

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, TESTING_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';
@@ -115,6 +115,28 @@ export function projectChecks(checks, root) {
     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/errors.mjs

@@ -22,6 +22,7 @@ export const CODES = {
   '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,7 +10,7 @@ import { readFileSync } from 'node:fs';
 const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const VERSION = version;
 
-// The 20 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',
@@ -21,6 +21,8 @@ export const SKILLS = [
   'yad-connect-repos',
   'yad-connect-design',
   'yad-connect-testing',
+  'yad-connect-learning',
+  'yad-learn',
   'yad-spec',
   'yad-implement',
   'yad-checks',
@@ -96,12 +98,22 @@ export const DESIGN_PRIMARY = 'figma';
 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, TESTING_TOOLS, TESTING_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'];
@@ -115,6 +115,34 @@ export function registerTesting(root, { tool, project_url = null, suites = null,
   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) {
@@ -128,7 +156,7 @@ function applyActions(actions, { force = false } = {}) {
 }
 
 export async function runSetup(root, opts = {}) {
-  const total = 9;
+  const total = 10;
   log(c.bold(`\nSDLC Workflow setup  ${c.dim('v' + VERSION)}`));
   log(c.dim(`target: ${root}`));
 
@@ -224,8 +252,25 @@ export async function runSetup(root, opts = {}) {
       : `wrote ${PROJECT_FILES.testingConfig} (${tool})`);
   }
 
-  // 6. Connect code repos
-  step(6, total, 'Connect code repos');
+  // 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));
@@ -248,8 +293,8 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 7. Wire each connected repo + the hub itself
-  step(7, 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})`)}`);
@@ -264,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 });
 
-  // 8. Optional CodeRabbit
-  step(8, 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; }
@@ -275,8 +320,8 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 9. Summary + version stamp
-  step(9, 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('');
@@ -290,6 +335,10 @@ export async function runSetup(root, opts = {}) {
   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).'));

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 20 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>
@@ -294,6 +294,8 @@
         <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>
@@ -445,7 +447,7 @@ 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 20 skills live and where you pull updates from. No real product work happens inside it.</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>
@@ -536,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 20 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>
@@ -679,7 +681,7 @@ each code repo/
 
 <!-- ======================================================= -->
 <section id="skills">
-  <h2>6. The 20 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>, …).
@@ -747,6 +749,29 @@ 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">
@@ -923,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. Nine steps: preflight (git/node check), install all 20 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 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.3.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

@@ -150,6 +150,27 @@ testing:
   # 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

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-test-cases yad-connect-repos yad-connect-design yad-connect-testing 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,4 +1,5 @@
 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 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
@@ -8,6 +9,8 @@ SDLC Workflow,yad-test-cases,Author Test Cases,TC,"Front state 9 (PARALLEL, non-
 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-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`.

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

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

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

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

package/skills/yad-learn/SKILL.md

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

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

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

package/skills/yad-status/SKILL.md

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