yadflow 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -1,3 +1,57 @@
+# [4.4.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.3.0...v4.4.0) (2026-10-03)
+
+
+### Bug Fixes
+
+* **skill:** E51 review 1 — read the route the epic records, never a guess ([cefdb21](https://github.com/abdelrahmannasr/yadflow/commit/cefdb216139e4608961b83a5ec61f1ca6cb318c7))
+* **skill:** E51 review 2 — say an epic's route is unknown; simplify the change-epic seed ([c5e6f0e](https://github.com/abdelrahmannasr/yadflow/commit/c5e6f0e12e56a768196088aff10d2eebd3f70293))
+* **skill:** E52 flag a pick bound in place of yadflow's skill; list prints the catalogue's age ([a0b76f3](https://github.com/abdelrahmannasr/yadflow/commit/a0b76f30fd1d9fb3123977532ab0ef055daf89bf))
+* **skill:** E52 review 1 — yadflow's skill must run last, plugin names, route view in list ([fcf675a](https://github.com/abdelrahmannasr/yadflow/commit/fcf675a6fe64788f3d0b2c12f8f7aad14eb6448c))
+* **skill:** E52 review 2 — a bare bound name never matches a plugin-qualified pick ([4199fd3](https://github.com/abdelrahmannasr/yadflow/commit/4199fd332f36eb532f9aa4bd2a4f05a77bfa6cec))
+* **skill:** E52 review 3 — a marketplace-spelled binding is the same pick ([04d7aaa](https://github.com/abdelrahmannasr/yadflow/commit/04d7aaafe640253dd0ecc48e922c993e0d7b3860))
+* **toolbox:** E87 review 1 — CRLF, unseen tools, no Product, honest Repomix fallback ([dc3bd75](https://github.com/abdelrahmannasr/yadflow/commit/dc3bd7577271c5fb71fe5522e8a6d1f2c1fff575))
+* **toolbox:** E87 review 10 — unclosed fence refused, frontmatter skipped ([577786c](https://github.com/abdelrahmannasr/yadflow/commit/577786c2ff939be1bf7565c9bc4f3b72d9569cd7))
+* **toolbox:** E87 review 11 notes — frontmatter hides nothing, exact round trip ([b8bb924](https://github.com/abdelrahmannasr/yadflow/commit/b8bb924c5320f3fdf531f03fa968f77dc970f8c8))
+* **toolbox:** E87 review 12 — a section can never cross the frontmatter ([cb1c111](https://github.com/abdelrahmannasr/yadflow/commit/cb1c11184fd2caea1e2f6b4c7082b65e5de462f3))
+* **toolbox:** E87 review 13 notes — frontmatter closes at '--- ' or '...' ([df6c644](https://github.com/abdelrahmannasr/yadflow/commit/df6c644f639eaeef04b36eb1da2116b472452f39))
+* **toolbox:** E87 review 14 — frontmatter needs a YAML key; no write leaves two copies ([20f3c75](https://github.com/abdelrahmannasr/yadflow/commit/20f3c75a231461d42566474d8be972e08edc59df))
+* **toolbox:** E87 review 15 — check names the two-copy refusal too ([88757ac](https://github.com/abdelrahmannasr/yadflow/commit/88757acf9015dc8a8b2adae7137fdf1b8a151959))
+* **toolbox:** E87 review 2 — connector-only sections, safer section finder ([00127ec](https://github.com/abdelrahmannasr/yadflow/commit/00127ecd4ae61c10cc5b34beaf32d42512d8ea05))
+* **toolbox:** E87 review 3 — a removal works, a misread is refused by content ([a42bc78](https://github.com/abdelrahmannasr/yadflow/commit/a42bc78bc5a53ba1e9c17073615f9313bab3b66e))
+* **toolbox:** E87 review 4 — one heading rule, a guard that quotes its line ([768b43a](https://github.com/abdelrahmannasr/yadflow/commit/768b43a7f8df84aeb1ca1d53818a421a1dca5ba2)), closes [#s](https://github.com/abdelrahmannasr/yadflow/issues/s)
+* **toolbox:** E87 review 5 notes — fence-aware copy count, dividers, linear heading read ([d9eb679](https://github.com/abdelrahmannasr/yadflow/commit/d9eb6793ead27dfa9f76f60bc301a45df727a832)), closes [#s](https://github.com/abdelrahmannasr/yadflow/issues/s)
+* **toolbox:** E87 review 6 — truly linear heading read, underline guard reads real headings ([83d0885](https://github.com/abdelrahmannasr/yadflow/commit/83d0885c9f8c6c216a35e740b365c6eebaca6b54)), closes [#s](https://github.com/abdelrahmannasr/yadflow/issues/s) [#hashtag](https://github.com/abdelrahmannasr/yadflow/issues/hashtag)
+* **toolbox:** E87 review 7 — no slow pattern left in the section readers ([7201076](https://github.com/abdelrahmannasr/yadflow/commit/72010765951c569ea0c0cbc52b67c13f96c9f248))
+* **toolbox:** E87 review 8 — a divider ends the block; the guard is checked against marked ([750187c](https://github.com/abdelrahmannasr/yadflow/commit/750187cecd34e8ff49c39e141424656781def287)), closes [#tag](https://github.com/abdelrahmannasr/yadflow/issues/tag)
+* **toolbox:** E88 review 1 — refuse future and impossible vetting dates; pin every Repomix line ([20048b5](https://github.com/abdelrahmannasr/yadflow/commit/20048b562129a3860a521dc8a159cc8641dc3d9a))
+* **toolbox:** E88 review 2 — install-line test fails closed; pin test covers npm install ([e955cbd](https://github.com/abdelrahmannasr/yadflow/commit/e955cbddc5d1d596c833dfb596b1536516b4d489))
+* **toolbox:** E88 review 3 — a terms page that says license is not a licence file ([34edaf8](https://github.com/abdelrahmannasr/yadflow/commit/34edaf84f0a4a3d7338de1aae61964f975c6e2e3))
+* **toolbox:** E88 review 4 — tell a licence file by where it lives, not its letter case ([4e9dbc0](https://github.com/abdelrahmannasr/yadflow/commit/4e9dbc0850ca9cba27ceba00e8b9dea777c1d1e6))
+* **toolbox:** E88 review 5 — a repository's front page is not a licence file ([3f9fe15](https://github.com/abdelrahmannasr/yadflow/commit/3f9fe15a54a259c7c784a18b4e52e69ce50a7104))
+
+
+### Features
+
+* **skill:** E51 bind a skill for one route only ([654488c](https://github.com/abdelrahmannasr/yadflow/commit/654488c7e7d876fbe29122959f2befe1122ebffe))
+* **skill:** E52 recommendation catalogue and yad skill recommend ([2b4fba0](https://github.com/abdelrahmannasr/yadflow/commit/2b4fba05a6e27af978dcaeb25fe61a0dc61c36b6))
+* **toolbox:** E88 vet every toolbox tool, and pin Repomix to the vetted version ([e4026f3](https://github.com/abdelrahmannasr/yadflow/commit/e4026f3140428a6b80c1842e410c8174f5ecb205))
+* **toolbox:** every skill that uses a tool declares its fallback (E87) ([8d4963e](https://github.com/abdelrahmannasr/yadflow/commit/8d4963e603e92be0fcbc616e98a5ea5939befbc4))
+
+# [4.3.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.2.0...v4.3.0) (2026-10-01)
+
+
+### Bug Fixes
+
+* **toolbox:** E85 review 1 — hint order, the folder check looks in, team-wide remove advice ([c7f6592](https://github.com/abdelrahmannasr/yadflow/commit/c7f65922cdad49e9816c4cbe81190283392c1df6))
+* **toolbox:** E85 review 2 — look for tools at the top of the repo, read --dir's Product ([82fb5ed](https://github.com/abdelrahmannasr/yadflow/commit/82fb5ed6a1afcf364a9844d3faf2676bd4a84274))
+* **toolbox:** E85 review 3 — a worktree is its own checkout; look at the deepest top ([4926799](https://github.com/abdelrahmannasr/yadflow/commit/4926799f6db758c7abb59029bd8e71923550c227))
+* **toolbox:** E85 review 4 — find the checkout top under both spellings of a linked folder ([9728384](https://github.com/abdelrahmannasr/yadflow/commit/9728384c140178d55608d2ab2b67037a2f80140d))
+
+
+### Features
+
+* **toolbox:** offer the missing tools in setup, check, update and join (E85) ([53e06c6](https://github.com/abdelrahmannasr/yadflow/commit/53e06c6da8bf585ced68435b052d01ba4ca5e6fa))
+
 # [4.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.1.0...v4.2.0) (2026-10-01)
 
 

package/README.md

@@ -257,7 +257,8 @@ The record is worth trusting because people approve what goes into it.
 - linked changes and `yad thread`
 - `yad history`, `yad next` and `yad usage`
 - `yad detect`, which lists the skills, agents, MCP servers and plugins installed for each AI agent
-- `yad toolbox list`, which shows the external tools yadflow can use, which ones you have, and what happens without each; `yad toolbox add` / `remove` record the tools your team uses, and `yad toolbox check` lists the ones not ready on your machine
+- `yad toolbox list`, which shows the external tools yadflow can use, which ones you have, and what happens without each; `yad toolbox add` / `remove` record the tools your team uses, and `yad toolbox check` lists the ones not ready on your machine (`yad setup`, `check`, `update` and `join` print the same list, and never install anything); each skill that uses a tool reads the same answer and says what it does without it
+- `yad skill recommend`, which lists hand-picked skills from the recommended skill collections for each step, why each fits, and the command to bind one; it binds nothing, and every pick was checked against its source
 - draft saving, claims and owners
 - the CI checks
 - the Review Companion

package/bin/commands.mjs

@@ -12,13 +12,13 @@
 
 export { runSetup } from '../cli/setup.mjs';
 export { runNew, runInit, runJoin } from '../cli/workspace.mjs';
-export { findProduct, hasProduct, workspaceProduct, registryEntryFor, WORKSPACE_FILE } from '../cli/find-product.mjs';
+export { findProduct, hasProduct, workspaceProduct, registryEntryFor, toolsFolder, WORKSPACE_FILE } from '../cli/find-product.mjs';
 export { reconcile } from '../cli/reconcile.mjs';
 export { gateOpen, gateSync, gateComments, gateStatus, gateCi, gateReview, gateTrailer, gateWalkthrough, gateRepair } from '../cli/gate.mjs';
 export { gateApprove, gateComment, gateAdvance } from '../cli/gate-local.mjs';
 export { isValidEpicId, productDriftError, seedableProfiles } from '../cli/epic-state.mjs';
 export { runEpicNew, runFoundationNew, runFoundationStatus } from '../cli/epic.mjs';
-export { runSkillBind, runSkillList, runSkillUnbind } from '../cli/skill.mjs';
+export { runSkillBind, runSkillList, runSkillRecommend, runSkillUnbind } from '../cli/skill.mjs';
 export { runCommit } from '../cli/commit.mjs';
 export { runOpenPr } from '../cli/openpr.mjs';
 export { reviewTrailer, reviewContext, reviewNudge, reviewReconcile, reviewWalkthrough } from '../cli/review.mjs';

package/bin/yad.mjs

@@ -24,7 +24,8 @@ ${c.bold('Start a workspace')} ${c.dim('(the folder holding product/ and the cod
                        Never commits, pushes, or changes a shared file
 
 ${c.bold('Setup & maintenance')}
-  yad setup            Guided first-run setup (profile interview, install, connect & wire repos)
+  yad setup            Guided first-run setup (profile interview, install, connect & wire repos,
+                       then the tools this project uses that are missing — offered, never installed)
                        profile flags: --solo | --team <n>, --greenfield | --brownfield,
                        --monorepo | --separate, --tools (configure design/testing/learning now)
   yad check            Report what is missing / drifted / modified / stale / legacy (read-only)
@@ -110,12 +111,22 @@ ${c.bold('Where am I / what next')}
   yad next --all                       Every active epic's next action at once
   yad next [<epic>] --json             The same answer as a machine-readable action object (for
                                        agents/CI) — always every epic, so --all is implied
-  yad skill list [--json]              Which skill runs which step, and whether that is this
-                                       project's choice or the engine's default
-  yad skill bind <step> <skill> [<skill> ...]
-                                       Bind a step to a skill of your own. Several skills run in
-                                       the order given, one after another — each costs tokens
-  yad skill unbind <step>              Drop the binding; the step goes back to the engine's default
+  yad skill list [--profile <p> | --epic <id>] [--json]
+                                       Which skill runs which step, whether that is one route's
+                                       choice, the project's or the engine's default, and whether
+                                       each skill is installed here (--epic: that epic's route)
+  yad skill bind <step> <skill> [<skill> ...] [--profile <p>]
+                                       Bind a step to a skill of your own — for every epic, or
+                                       with --profile for epics on that route only (it wins).
+                                       Several skills run in the order given — each costs tokens.
+                                       Warns when the skill is not installed here
+  yad skill unbind <step> [--profile <p>]
+                                       Drop the binding; the step goes back to the project-wide
+                                       binding, then the engine's default
+  yad skill recommend [<step>] [--profile <p> | --epic <id>] [--json]
+                                       Hand-picked skills from the recommended pools for each step,
+                                       why each fits, whether it is installed here, and the bind
+                                       command (pool skill first, yadflow's skill last). Binds nothing
   yad toolbox list [--json] [--dir <folder>]
                                        The external tools yadflow can use — core (offered at setup),
                                        recommended pools, the design/testing/learning connectors and
@@ -424,7 +435,7 @@ let runningCmd = null;
 const ACTIONS = {
   epic: { known: ['new'] },
   foundation: { known: ['new', 'status'] },
-  skill: { known: ['list', 'bind', 'unbind'], default: 'list' },
+  skill: { known: ['list', 'bind', 'unbind', 'recommend'], default: 'list' },
   gate: { known: ['open', 'sync', 'comments', 'status', 'repair', 'review', 'walkthrough', 'trailer', 'ci', 'approve', 'comment', 'advance'] },
   review: { known: ['trailer', 'context', 'chat', 'cards', 'walkthrough', 'nudge', 'reconcile'] },
   tidy: { known: ['up'] },
@@ -539,8 +550,12 @@ async function main() {
   // registers (through `.yad-workspace.json`) — and says where, on stderr. A code-repo command keeps acting
   // on the repo it runs in, and is handed the Product to read (its registry: name, platform, branch).
   const dirGiven = process.argv.slice(2).some((a) => a === '--dir' || a.startsWith('--dir='));
+  // E85: where `check` and `update` look for tools, and whose choices they read — worked out from the
+  // folder the person ran yad in (or named), before a Product command moves `o.dir` to the Product.
+  let toolboxAt = null;
   if (PRODUCT_CMDS.has(cmd) || REPO_CMDS.has(cmd)) {
     const found = commands.findProduct(dirGiven ? o.dir : shellCwd());
+    toolboxAt = { from: commands.toolsFolder(found, dirGiven ? o.dir : shellCwd()), product: found?.root ?? null };
     const shown = (p) => path.relative(process.cwd(), p) || '.';
     if (found?.problem) warn(`${found.problem} — using ${o.dir}`);
     else if (found?.elsewhere) {
@@ -625,11 +640,11 @@ async function main() {
     }
     case 'check':
       if (noProduct()) break;
-      result = await commands.reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today });
+      result = await commands.reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today, toolbox: toolboxAt });
       break;
     case 'update':
       if (noProduct()) break;
-      result = await commands.reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today });
+      result = await commands.reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today, toolbox: toolboxAt });
       break;
     case 'doctor':
       result = await commands.runDoctor(o.dir, { json: o.json });
@@ -655,7 +670,7 @@ async function main() {
         else if (found?.elsewhere) warn(`this folder is not in a repo the Product registers — the Product is ${rel(found.elsewhere)}: cd there, or pass --dir ${rel(found.elsewhere)}`);
         const productRoot = found?.root ?? null;
         const run = action === 'list' ? commands.runToolboxList : commands.runToolboxCheck;
-        result = run(o.dir || process.cwd(), { json: o.json, productRoot });
+        result = run(commands.toolsFolder(found, o.dir || process.cwd()), { json: o.json, productRoot });
         break;
       }
       if (extra) { refuse(`yad toolbox ${action} takes one tool id (got also: ${extra})`, usage); break; }
@@ -730,11 +745,12 @@ async function main() {
     }
     case 'skill': {
       const [, action, step, ...rest] = o._;
-      if (action === 'list' || action === undefined) { result = commands.runSkillList(o.dir, { json: o.json }); break; }
+      if (action === 'list' || action === undefined) { result = commands.runSkillList(o.dir, { json: o.json, profile: o.profile, epic: o.epic }); break; }
       if ((action === 'bind' || action === 'unbind') && noProduct()) break;
-      if (action === 'bind') { result = commands.runSkillBind(o.dir, { step, skills: rest }); break; }
-      if (action === 'unbind') { result = commands.runSkillUnbind(o.dir, { step }); break; }
-      refuse(`unknown skill action: ${action} (list, bind, unbind)`, 'usage: yad skill list [--json] | yad skill bind <step> <skill> [<skill> ...] | yad skill unbind <step>');
+      if (action === 'bind') { result = commands.runSkillBind(o.dir, { step, skills: rest, profile: o.profile }); break; }
+      if (action === 'unbind') { result = commands.runSkillUnbind(o.dir, { step, profile: o.profile }); break; }
+      if (action === 'recommend') { result = commands.runSkillRecommend(o.dir, { step: step ?? null, json: o.json, profile: o.profile, epic: o.epic }); break; }
+      refuse(`unknown skill action: ${action} (list, bind, unbind, recommend)`, 'usage: yad skill list [--profile <p> | --epic <id>] [--json] | yad skill bind <step> <skill> [<skill> ...] [--profile <p>] | yad skill unbind <step> [--profile <p>] | yad skill recommend [<step>] [--profile <p> | --epic <id>] [--json]');
       break;
     }
     case 'next': {

package/cli/detect.mjs

@@ -4,8 +4,8 @@
 //   yad detect [--json] [--dir <folder>]
 //
 // Worked out fresh on every run and never saved: nothing reads it yet except a person, and a saved copy
-// would be a new file shape that goes stale the moment someone installs a skill. E51 (bind per profile)
-// and E85 (the toolbox check) are the readers this is built for.
+// would be a new file shape that goes stale the moment someone installs a skill. `yad skill list` /
+// `yad skill bind` (E51, "is this skill installed here?") and E85 (the toolbox check) read it too.
 //
 // TWO PLACES ARE LOOKED IN: the folder the command runs on (what a teammate who clones it also gets), and
 // the user's home folder (where most people install skills). Every item says which one, and which agents

package/cli/docs.mjs

@@ -2,7 +2,7 @@
 // documentation sites generated by the yad-docs / yad-docs-overview skills. The CONTENT generation
 // (reading epic/architecture/contract/ui/stories → writing src/data/*.ts and theming index.css) is
 // the AI step inside those skills; this module only does the mechanical parts: npm build (a
-// subprocess, like yad-spec shelling npx repomix), the platform Pages wiring (reusing platform.mjs),
+// subprocess, like yad-spec shelling out to Repomix), the platform Pages wiring (reusing platform.mjs),
 // and the manifest-hash staleness check (reusing the head-sha idea from repo.mjs). It NEVER touches
 // epic state, approvals, or the contract lock — docs are an output enrichment, not a gate.
 //

package/cli/doctor.mjs

@@ -10,7 +10,7 @@ import { VERSION, BACKUP_SUFFIX, MIRRORED_FILES, mirrorDrift, PROJECT_FILES, MOD
 import { mergeHookSettings, hookMatcherFires, ideTargetsFor, safeIdeTargetStateFor, hookScriptReady, miswiredGuardCommand, gitHookState, legacyModuleActions, legacyProductActions, renamedNameHits, PRODUCT_CHECK_WORKFLOWS, productProfileEffect, workflowsPassingProduct, productGateBlockers, oldProfileAdvice, gateProfileFix } from './plan.mjs';
 import { hasSiblingRepo, workspaceFileState, WORKSPACE_FILE } from './find-product.mjs';
 import { planMigration } from './migrate.mjs';
-import { ADVANCE_VALUES, isGateStep, killSwitchOn, loadAutomation, stepDef as catalogueStep, loadLedger, owedSteps, epicIds, epicRel, epicRoot, FOUNDATION_DIR, FOUNDATION_EPIC, DISCOVERY_EPIC, staleFoundationGuards, unwrittenSections, artifactBase, artifactAgrees, epicStories, laneStarted, isValidEpicId, epicLineage, isGenesisType, readFrontmatter, resolveThread, stateInvariants, contractSurfaceHash, acceptedHashes, isStaleHash, workItemType, WORK_ITEM_TYPES, themeOf, themeKey, stepPhase, stepDef, matchLifecycleProfile, lifecycleProfile, LIFECYCLE_PROFILES, SENTINELS, normalizeBindings, optionalStepsFor, isSkippableStep, recordedRouteDisagrees, isPassed, stepStatus, claimsSkipped, STEP_STATES, isStepRecord, RECORDED_STEP_STATES, productDriftPairs } from './epic-state.mjs';
+import { ADVANCE_VALUES, isGateStep, killSwitchOn, loadAutomation, stepDef as catalogueStep, loadLedger, owedSteps, epicIds, epicRel, epicRoot, FOUNDATION_DIR, FOUNDATION_EPIC, DISCOVERY_EPIC, staleFoundationGuards, unwrittenSections, artifactBase, artifactAgrees, epicStories, laneStarted, isValidEpicId, epicLineage, isGenesisType, readFrontmatter, resolveThread, stateInvariants, contractSurfaceHash, acceptedHashes, isStaleHash, workItemType, WORK_ITEM_TYPES, themeOf, themeKey, stepPhase, stepDef, matchLifecycleProfile, lifecycleProfile, LIFECYCLE_PROFILES, SENTINELS, normalizeBindings, stepsReadingBinding, optionalStepsFor, isSkippableStep, recordedRouteDisagrees, isPassed, stepStatus, claimsSkipped, STEP_STATES, isStepRecord, RECORDED_STEP_STATES, productDriftPairs } from './epic-state.mjs';
 import { loadDebt } from './thread.mjs';
 import { readShips } from './ledger.mjs';
 import { gitHead, insideWorkspace } from './setup.mjs';
@@ -2099,16 +2099,88 @@ export function skillBindingChecks(checks, root) {
       `${rel} binds ${gates.join(', ')}, which no skill runs — review gates are driven by \`yad gate\``,
       'bind the author step instead (for example `architecture`, not `architecture-review`)');
   }
+  const routeBound = profileBindingChecks(checks, rel, raw.profiles);
+  if (routeBound === null) return;
   // Its OWN id, not `skills` again. A file with one good binding and one broken line fires both, and
   // two checks sharing an id put a green tick under the complaint in prose — and, worse, let a `--json`
   // consumer keying by id overwrite the warning with the tick.
-  if (bound.length) {
+  if (bound.length || routeBound) {
     const chained = bound.filter(([, list]) => list.length > 1).length;
     check(checks, 'skills:bound', 'project', 'ok',
-      `skills: ${bound.length} step(s) bound${chained ? `, ${chained} to more than one skill` : ''}`);
+      `skills: ${bound.length} step(s) bound${chained ? `, ${chained} to more than one skill` : ''}`
+        + (routeBound ? `; ${routeBound} more for one route only` : ''));
   }
 }
 
+// `profiles.<p>.steps` (E51): the same three "your line did nothing" warnings, each naming its route,
+// plus the two only a route can have — a route this release does not carry, and a step the route never
+// walks (`architecture` on `spike`: no epic on it ever reaches that step, which is why `yad skill bind`
+// refuses the same line). Returns how many lines bind something, or null after a fail.
+function profileBindingChecks(checks, rel, profiles) {
+  if (profiles === undefined) return 0;
+  if (!isPlainObject(profiles)) {
+    check(checks, 'skills:profiles', 'project', 'fail', `${rel}: \`profiles\` must be a JSON object [YAD-STATE-002]`,
+      'expected `"profiles": { "<profile>": { "steps": { "<step-id>": "<skill>" } } }`');
+    return null;
+  }
+  const broken = Object.entries(profiles)
+    .filter(([, v]) => !isPlainObject(v) || (v.steps !== undefined && !isPlainObject(v.steps)))
+    .map(([id]) => id);
+  if (broken.length) {
+    check(checks, 'skills:profiles', 'project', 'fail',
+      `${rel}: ${broken.map((id) => `\`profiles.${id}\``).join(', ')} must hold a \`steps\` object [YAD-STATE-002]`,
+      'expected `"<profile>": { "steps": { "<step-id>": "<skill>" } }`');
+    return null;
+  }
+  const bindings = normalizeBindings({ profiles });
+  const unusable = [];
+  const unknownStep = [];
+  const gates = [];
+  const offRoute = [];
+  const unknownRoute = [];
+  let bound = 0;
+  for (const [id, entry] of Object.entries(profiles)) {
+    const kept = (Object.hasOwn(bindings.profiles, id) ? bindings.profiles[id].steps : null) || {};
+    const route = lifecycleProfile(id);
+    if (!route && Object.keys(kept).length) unknownRoute.push(id);
+    for (const step of Object.keys(entry.steps || {})) {
+      if (!Object.hasOwn(kept, step)) { unusable.push(`${id}: ${step}`); continue; }
+      bound += 1;
+      const def = stepDef(step);
+      if (!def) unknownStep.push(`${id}: ${step}`);
+      else if (!def.skill) gates.push(`${id}: ${step}`);
+      else if (route && (def.phase === 'build' ? route.level !== 'feature'
+        : !stepsReadingBinding(step).some((s) => route.rows.some((r) => r.id === s)))) offRoute.push(`${id}: ${step}`);
+    }
+  }
+  if (unusable.length) {
+    check(checks, 'skills:profile-unusable', 'project', 'warn',
+      `${rel}: ${unusable.length} route binding(s) name no skill and are ignored — ${unusable.join(', ')} [YAD-CFG-006]`,
+      'each value must be a skill name or a non-empty list of them');
+  }
+  if (unknownRoute.length) {
+    check(checks, 'skills:unknown-profile', 'project', 'warn',
+      `${rel} binds skills for ${unknownRoute.length} route(s) this yadflow does not have: ${unknownRoute.join(', ')}`,
+      `check the spelling against the routes (${LIFECYCLE_PROFILES.map((p) => p.id).join(', ')}), or upgrade yadflow if the route is from a newer release`);
+  }
+  if (unknownStep.length) {
+    check(checks, 'skills:profile-unknown-step', 'project', 'warn',
+      `${rel} binds ${unknownStep.length} route step(s) this yadflow does not run: ${unknownStep.join(', ')}`,
+      'check the spelling against `yad skill list`, or upgrade yadflow if the step is from a newer release');
+  }
+  if (gates.length) {
+    check(checks, 'skills:profile-review-step', 'project', 'warn',
+      `${rel} binds ${gates.join(', ')}, which no skill runs — review gates are driven by \`yad gate\``,
+      'bind the author step instead (for example `architecture`, not `architecture-review`)');
+  }
+  if (offRoute.length) {
+    check(checks, 'skills:off-route', 'project', 'warn',
+      `${rel} binds ${offRoute.join(', ')}, a step that route never walks — no epic on it reaches the step`,
+      'bind it for a route that has the step, or project-wide under `steps`');
+  }
+  return bound;
+}
+
 // `.sdlc/toolbox.json`: which toolbox tools this Product uses or skips, and its own tools (E86). Absent is
 // the normal case. THE FILE ONLY: whether a tool is installed is `yad toolbox check`'s answer, and a
 // missing tool is never a doctor line (decided with E86 — no tool is required). A broken file fails, as

package/cli/epic-state.mjs

@@ -2297,8 +2297,8 @@ export function markInReview(state, step, close = null) {
 // E108 — is `gateRuleFor` and `gateCapFor` at the top of this file (E7, E62, E72), which read
 // the `risk_tags` a seed copies from the row below into the epic's own `state.json`;
 // the fuller step-state model is E38. The `skill` column stays here as the shipped DEFAULT, and a
-// project overrides it in `.sdlc/skills.json` (E6, below) — E51 later slides a per-profile default
-// between the two, once E50 can detect which skills are installed. Three of the five
+// project overrides it in `.sdlc/skills.json` (E6, below), for every epic or for one route only
+// (E51: `profiles.<id>.steps`, which wins over the project-wide line). Three of the five
 // skills that used to hand-write a seed now run `yad epic new` instead (E17b), `yad-discovery` runs
 // `yad foundation new` (E75), and `yad-change` runs `yad epic new --parent` for a threaded change-epic
 // (E42).
@@ -2443,9 +2443,9 @@ export const STEPS = [
 // `yad epic new` (E17, cli/epic.mjs); shape 6 is where an epic first RECORDS which profile it is on,
 // and an epic seeded before that field existed still has its route derived by matching its chain
 // (`matchLifecycleProfile`). Which steps are optional per route already lives here and is read per
-// EPIC (E35, `optionalStepsFor`); the short chore and spike lanes are E40. A PROJECT-wide skill
-// binding already exists (E6, below); E51 adds a per-profile one between it and the catalogue
-// default, so two routes can run different skills for the same step.
+// EPIC (E35, `optionalStepsFor`); the short chore and spike lanes are E40. Which skill runs a step
+// is bound per project (E6, below) and, more specifically, per route (E51) — both in
+// `.sdlc/skills.json`, never here, so two routes can run different skills for the same step.
 export const LIFECYCLE_PROFILES = [
   {
     id: 'classic',
@@ -2877,8 +2877,9 @@ const BUILD_STEP_ORDER = STEPS.filter((s) => s.phase === 'build').map((s) => s.i
 // THE FILE WINS, AND THE DOCTOR ONLY REPORTS. Same discipline as `workItemType` and the lifecycle
 // profile: a project may bind a skill this engine has never heard of — that is the whole point, since
 // the engine cannot know what a team installed. So nothing here validates a skill NAME. `yad doctor`
-// reports a binding on a step id the catalogue does not know, and changes nothing. Detecting which
-// skills are actually installed is E50; per-profile defaults are E51.
+// reports a binding on a step id the catalogue does not know, and changes nothing. `yad skill list`
+// and `yad skill bind` ask `yad detect` (E50) whether a bound skill is installed on THIS machine, and
+// only ever warn: a teammate may have it, and the engine cannot see their home folder.
 //
 // SEVERAL SKILLS PER STEP IS A CHAIN, NEVER A PANEL (closed decision 7). They run in the order given,
 // each one seeing what the one before it produced, and the LAST output is the artifact. A panel — run
@@ -2897,8 +2898,19 @@ const BUILD_STEP_ORDER = STEPS.filter((s) => s.phase === 'build').map((s) => s.i
 //   }
 //
 // A value may be one skill or a list of them; both are read back as a list, so nothing downstream has
-// to handle two shapes. The wrapper object exists so that E50 and E51 can add keys beside `steps`
-// without the file changing shape.
+// to handle two shapes. The wrapper object exists so that later rows can add keys beside `steps`
+// without the file changing shape — and E51 did:
+//
+//     "profiles": {
+//       "spike": { "steps": { "epic": "spike-epic" } }
+//     }
+//
+// A binding under `profiles.<id>` applies only to an epic that RECORDS that route (`recordedRoute`,
+// below — never a route guessed from its chain). THE MOST SPECIFIC LINE WINS: the route's
+// own line, then the project-wide `steps`, then the catalogue. A team that binds `epic` for `spike`
+// gets it on spike epics only, and its project-wide lines still cover every other route. No shape
+// moves: an older yadflow keeps the unknown key (`yad skill bind` writes the document it read) and
+// simply runs the project-wide answer for every route.
 
 // The catalogue's own answer for a step, Shape or Build. One lookup, because a step id belongs to
 // exactly one of the two tables (`catalogueSkills` splits them on the same `phase === 'build'` rule),
@@ -2908,7 +2920,8 @@ const BUILD_STEP_ORDER = STEPS.filter((s) => s.phase === 'build').map((s) => s.i
 // chain carrying a step called `constructor` would otherwise resolve its "skill" to a function.
 const CATALOGUE_SKILL = { __proto__: null, ...STEP_SKILL, ...BUILD_STEP_SKILL };
 
-// Read a raw parsed `.sdlc/skills.json` into `{ steps: { <id>: [skill, …] } }`.
+// Read a raw parsed `.sdlc/skills.json` into
+// `{ steps: { <id>: [skill, …] }, profiles: { <profile>: { steps: { <id>: [skill, …] } } } }`.
 //
 // Junk is DROPPED here rather than rejected, and that is deliberate: this runs inside `yad next`,
 // which must keep working on a project whose config file someone mistyped. An empty string, an empty
@@ -2925,20 +2938,75 @@ const CATALOGUE_SKILL = { __proto__: null, ...STEP_SKILL, ...BUILD_STEP_SKILL };
 // and the two surfaces would disagree about it: the rendered Build chain folds them (that is what
 // `dedupeConsecutive` has always done for spec+tasks) while the cost note counted them, so a step
 // bound to `["a", "a"]` would be billed for two runs and shown as one.
-export function normalizeBindings(raw) {
+//
+// `profiles` gets the same treatment one level down (E51): a profile id is a key out of the same
+// hand-edited file, so `__proto__` there is added with `defineProperty` too, and a profile whose
+// `steps` binds nothing usable is left out — it would only route a lookup to an empty layer.
+const ownKey = (obj, key, value) => Object.defineProperty(obj, key, { value, enumerable: true, writable: true, configurable: true });
+
+function normalizeSteps(steps) {
   const out = {};
-  const steps = isPlainObject(raw) ? raw.steps : null;
   if (isPlainObject(steps)) {
     for (const [id, value] of Object.entries(steps)) {
       const list = dedupeConsecutive((Array.isArray(value) ? value : [value])
         .filter((s) => typeof s === 'string' && s.trim())
         .map((s) => s.trim()));
-      if (list.length) Object.defineProperty(out, id, { value: list, enumerable: true, writable: true, configurable: true });
+      if (list.length) ownKey(out, id, list);
     }
   }
-  return { steps: out };
+  return out;
+}
+
+export function normalizeBindings(raw) {
+  const profiles = {};
+  const rawProfiles = isPlainObject(raw) ? raw.profiles : null;
+  if (isPlainObject(rawProfiles)) {
+    for (const [id, value] of Object.entries(rawProfiles)) {
+      const steps = normalizeSteps(isPlainObject(value) ? value.steps : null);
+      if (Object.keys(steps).length) ownKey(profiles, id, { steps });
+    }
+  }
+  return { steps: normalizeSteps(isPlainObject(raw) ? raw.steps : null), profiles };
+}
+
+// The bindings as ONE epic sees them: the project's, plus which route the epic is on (E51).
+//
+// A view, not a merge. `stepSkills` reads the route's layer first and the project's after it, so a
+// line in either layer keeps saying where it came from — `yad skill list` needs that for `source`,
+// and a merged object would make a route's line indistinguishable from a project-wide one. The same
+// object goes to every reader of one epic (`nextAction` and the line `yad next` prints beside it), so
+// the JSON and the prose cannot name two different skills for one step.
+//
+// `profile` is null for "no route": no epic yet (`yad next` on an empty Product, `yad setup`), or an
+// epic whose route nothing can tell. Then only the project-wide layer applies — never a guessed route.
+export function bindingsForProfile(bindings, profile) {
+  const base = isPlainObject(bindings) ? bindings : { steps: {}, profiles: {} };
+  const id = typeof profile === 'string' && profile ? profile : null;
+  return { ...base, profile: id };
 }
 
+// The route an epic RECORDS, as written — or null when it records none.
+//
+// NOT `epicProfileId`, which falls back to matching the chain. That guess is fine for what a step may
+// skip, where a wrong answer is a refusal a person sees at once. Here it would be a silent claim that
+// is believed and acted on: `yad next` names the skill and `yad-run` runs it. Every hand-written and
+// pre-shape-6 ledger is a shortened `classic`, and the shortest route that fits `[epic, epic-review]`
+// is `chore` — so a `chore`-only line would reach every older classic epic. The E40 rule for
+// `routeLacksStep`, for the same reason.
+//
+// A route this release does not KNOW is still used as written (rule 3): an epic from a newer release
+// that records it gets the lines the team bound for it, which is what `yad skill bind` promises when it
+// records one. The lookup is `Object.hasOwn`, so an unknown id is safe.
+export const recordedRoute = (state) =>
+  (isPlainObject(state) && typeof state.profile === 'string' && state.profile ? state.profile : null);
+
+// The view for an epic's own `state.json` — its recorded route. A view that already names a route is
+// kept: a caller that resolved it once hands the same object on.
+export const bindingsForEpic = (bindings, state) =>
+  (isPlainObject(bindings) && Object.hasOwn(bindings, 'profile')
+    ? bindings
+    : bindingsForProfile(bindings, recordedRoute(state)));
+
 // The project's bindings, or the empty set when the file is absent or unreadable.
 export const loadSkillBindings = (root) =>
   normalizeBindings(readJSON(path.join(root, PROJECT_FILES.skillsConfig), null));
@@ -2955,22 +3023,48 @@ export function stepSkills(stepId, bindings = null) {
   // object `Object.prototype` answers for `constructor`, `toString` and friends — so a chain carrying
   // a step called `constructor` resolved its "skill" to a function, and `yad next` threw trying to
   // spread it. The catalogue map below is `__proto__: null` for the same reason.
-  const steps = bindings?.steps;
-  const boundTo = (id) => (isPlainObject(steps) && Object.hasOwn(steps, id) ? steps[id] : null);
-  const bound = boundTo(stepId);
-  if (Array.isArray(bound) && bound.length) return [...bound];
-  // A step that took over from an OLD id inherits the old id's binding until it is given one of its
-  // own (rule 3). A project that bound its own skill to `discovery` before E75 renamed the product
-  // step to `foundation` would otherwise be switched back to the default without anyone deciding it.
-  const legacy = Object.hasOwn(BINDING_SUCCEEDS, stepId) ? boundTo(BINDING_SUCCEEDS[stepId]) : null;
-  if (Array.isArray(legacy) && legacy.length) return [...legacy];
+  const found = boundSkills(stepId, bindings);
+  if (found) return [...found.skills];
   const fallback = CATALOGUE_SKILL[stepId];
   return typeof fallback === 'string' ? [fallback] : [];
 }
 
+// Which LAYER binds a step, and to what: `{ skills, source: 'profile' | 'project' }`, or null when
+// neither does (the step is on the catalogue's default). The most specific layer wins (E51): the
+// epic's route, then the project-wide `steps`.
+//
+// Inside each layer, a step that took over from an OLD id inherits the old id's binding until it is
+// given one of its own (rule 3). A project that bound its own skill to `discovery` before E75 renamed
+// the product step to `foundation` would otherwise be switched back to the default without anyone
+// deciding it. The layer order comes first: a route's `discovery` line beats a project-wide
+// `foundation` one, because it is the more specific CHOICE, whatever it is spelled.
+export function boundSkills(stepId, bindings = null) {
+  const lookup = (steps) => {
+    const boundTo = (id) => (isPlainObject(steps) && Object.hasOwn(steps, id) ? steps[id] : null);
+    const own = boundTo(stepId);
+    if (Array.isArray(own) && own.length) return own;
+    const legacy = Object.hasOwn(BINDING_SUCCEEDS, stepId) ? boundTo(BINDING_SUCCEEDS[stepId]) : null;
+    return Array.isArray(legacy) && legacy.length ? legacy : null;
+  };
+  const profiles = bindings?.profiles;
+  const profile = bindings?.profile;
+  const route = typeof profile === 'string' && isPlainObject(profiles) && Object.hasOwn(profiles, profile)
+    ? profiles[profile]?.steps : null;
+  const fromRoute = lookup(route);
+  if (fromRoute) return { skills: fromRoute, source: 'profile' };
+  const fromProject = lookup(bindings?.steps);
+  return fromProject ? { skills: fromProject, source: 'project' } : null;
+}
+
 // new step id -> the old step id whose binding it inherits while it has none of its own.
 const BINDING_SUCCEEDS = { __proto__: null, foundation: 'discovery' };
 
+// The step ids that read a line written under `id` — itself, and any step that took over from it. For
+// `yad doctor`: a `discovery` line on the `foundation` route is read for `foundation`, so it is not a
+// line no epic reaches.
+export const stepsReadingBinding = (id) =>
+  [id, ...Object.keys(BINDING_SUCCEEDS).filter((k) => BINDING_SUCCEEDS[k] === id)];
+
 // The two keys every action object carries for its skill, from one resolved list.
 //
 // `skill` STAYS A STRING and is the first of the chain, because ~20 call sites and `yad next --json`
@@ -3318,8 +3412,11 @@ export function repairState(state, close = null) {
 //   reopened — a lane per step re-opened behind finished work (E41), each shaped like an action
 //   debt     — the steps still owed as debt (`owedSteps`), the reminder that repeats until they are paid
 export function nextAction(ledger, opts = {}) {
-  const a = shapeNextAction(ledger, opts);
   const state = ledger?.state;
+  // E51: every skill this action names is the one for THIS epic's route. Resolved once, here, so the
+  // Shape step, the Build lanes and the re-opened lanes all read the same view.
+  opts = { ...opts, bindings: bindingsForEpic(opts.bindings ?? null, state) };
+  const a = shapeNextAction(ledger, opts);
   if (!state || !Array.isArray(state.steps) || isProductLevel(state) || backfillAnchorKind(state)) return a;
   const lanes = reopenedLanes(ledger, { epicId: a.epicId, currentStep: state.currentStep, bindings: opts.bindings ?? null });
   const debt = owedSteps(state).map((s) => ({ step: s.id, status: stepStatus(s) ?? s.status, record: s.record || null }));

package/cli/epic.mjs

@@ -36,7 +36,7 @@ import {
   DISCOVERY_EPIC, epicIds, epicLineage, epicRel, epicRoot, epicStories, featureStatus, FOUNDATION_EPIC, FOUNDATION_SECTIONS,
   isGenesisType, isValidEpicId, lifecycleProfile, loadLedger, loadSkillBindings, PRODUCT_DONE, PRODUCT_EPICS,
   planThreadedSeed, readFrontmatter, roadmapFeatures, seedableProfiles, seedFoundationState,
-  seedState, staleFoundationGuards, stepSkills, typeNoun, WORK_ITEM_TYPES, workItemType, writeJSON, writeState,
+  seedState, staleFoundationGuards, stepSkills, bindingsForEpic, typeNoun, WORK_ITEM_TYPES, workItemType, writeJSON, writeState,
 } from './epic-state.mjs';
 import { epicFiles, isVerifiedLedger, productConfigPath } from './manifest.mjs';
 import { refreshIndexAfterWrite } from './product-index.mjs';
@@ -223,8 +223,9 @@ export async function runEpicNew(root, { slug, type = null, profile = null, stub
   // Everything else asks the PROJECT first (E6): a team that bound its own skill to `epic` must be
   // told to run that one, or this command would hand a brand-new epic straight to a skill their
   // `yad next` will never name again. `yad-backfill` is the one exception, because waking a stub is
-  // the engine's own `promote` verb rather than a step on any chain.
-  const skills = stub ? ['yad-backfill'] : stepSkills(first.id, loadSkillBindings(root));
+  // the engine's own `promote` verb rather than a step on any chain. The route is the one just seeded
+  // (E51), read off the state as `yad next` will read it, so the two name the same skill.
+  const skills = stub ? ['yad-backfill'] : stepSkills(first.id, bindingsForEpic(loadSkillBindings(root), state));
   const skill = skills[0] || null;
   // `nextSkills` appears only for a bound chain, the same rule `yad next --json` follows — a key that
   // showed up on every seed would be one more always-null field for every reader to ignore.
@@ -314,7 +315,8 @@ function seedThreaded(root, { epic, dir, files, mdPath, fm, type, parent, profil
 
   const { state } = plan;
   const first = state.steps.find((s) => s.id === state.currentStep);
-  const skills = stepSkills(first.id, loadSkillBindings(root));
+  // The route the change takes from its parent, which `planThreadedSeed` records on the new state.
+  const skills = stepSkills(first.id, bindingsForEpic(loadSkillBindings(root), state));
   const carried = state.steps.filter((s) => s.inherited);
   if (json) {
     return emitJSON({
@@ -389,7 +391,7 @@ export async function runFoundationNew(root, { today, json = false } = {}) {
   for (const f of [files.approvals, files.comments]) if (!fs.existsSync(f)) writeJSON(f, []);
   fs.mkdirSync(path.join(epicRoot(root, FOUNDATION_EPIC), 'reviews'), { recursive: true });
 
-  const skills = stepSkills(state.steps[0].id, loadSkillBindings(root));
+  const skills = stepSkills(state.steps[0].id, bindingsForEpic(loadSkillBindings(root), state));
   const skill = skills[0] || null;
   const required = FOUNDATION_SECTIONS.filter((s) => !s.optional).map((s) => s.file);
   const optional = FOUNDATION_SECTIONS.filter((s) => s.optional).map((s) => s.file);

package/cli/find-product.mjs

@@ -181,6 +181,30 @@ export function gitTopOf(dir) {
   }
 }
 
+// Where `yad toolbox` and the toolbox section of `check` / `update` look for tools (E85), given
+// `findProduct(from)`'s answer. Finding reads `<folder>/.claude/…` and never walks up, so a subfolder
+// must be lifted to the top of what the person is working in. That is the DEEPEST of these that holds
+// `from`: the git checkout it is in (a worktree inside `api/` is its own checkout, on its own branch — never
+// swapped for api's, as in E80 review 3), the registered repo holding it (`apps/web` in a monorepo is not
+// a checkout of its own), and the Product found from it. A checkout ABOVE the Product (a Product that is
+// not a git repo, inside one that is not ours) is never deeper than the Product, so it never wins. Reads
+// only whether `.git` exists; runs nothing.
+export function toolsFolder(found, from) {
+  const at = real(from);
+  if (!at) return from;
+  // Both spellings: the shell's (through a link) and the one on disk, so `check` (given the shell's
+  // folder) and `yad toolbox check` (given the process's) look in the same place (E85 review 4).
+  const candidates = [gitTopOf(from), gitTopOf(at)];
+  if (found?.root && found.repo && typeof found.repo.path === 'string') candidates.push(path.resolve(found.root, found.repo.path));
+  if (found?.root && (found.via === 'here' || found.via === 'above')) candidates.push(found.root);
+  let best = null;
+  for (const c of candidates) {
+    const cAt = c && real(c);
+    if (cAt && within(at, cAt) && (!best || cAt.length > best.length)) best = cAt;
+  }
+  return best ?? from;
+}
+
 // The registry entry for the code repo a code-repo command runs in (E80), with the folder to work in.
 // It is the CHECKOUT that must be the registered repo — not merely a folder inside it: a worktree or a
 // repo nested in `backend/` is another checkout, on another branch, and must never be swapped for