yadflow 4.2.0 → 4.4.0

package/cli/workspace.mjs

@@ -32,6 +32,7 @@ import { productConfigPath, PROJECT_FILES } from './manifest.mjs';
 import { runSetup, insideWorkspace, throughGitDir, selectIdeTargets } from './setup.mjs';
 import { moduleActions, gitHookActions } from './plan.mjs';
 import { writeWorkspaceFile, WORKSPACE_FILE } from './find-product.mjs';
+import { offerToolbox } from './toolbox.mjs';
 
 // E80: the file that lets yad find the Product from inside the repos it registers. Written by all three.
 function noteWorkspaceFile(product) {
@@ -483,13 +484,20 @@ export async function runJoin(cwd, url, folder, opts = {}) {
   const hook = gitHookActions(product);
   for (const a of hook) a.apply();
   if (hook.length) ok('installed the git pre-commit hook in this clone');
+  // E85: the tools the team chose (the Product's toolbox.json, just cloned) that this machine lacks. A
+  // new teammate is the person most likely to miss one. Offered, never installed.
+  log('');
+  log(c.bold('Toolbox'));
+  const toolbox = offerToolbox(product, product, { canRemove: false });
 
+  // Under a heading of its own, so these lines do not read as part of the toolbox list above.
   log('');
+  log(c.bold('Next'));
   if (repos.failed.length) hand(`${repos.failed.length} repo(s) not cloned — fix what is named above and re-run \`yad join ${shown(url)}\`; it keeps what is already there`);
   hand(`start with: cd ${fromShell(product)} && yad next`);
   return {
     workspace, product,
     repos, skills: { installed: skills.installed, stale: skills.stale.length, shared: skills.shared.length },
-    hook: hook.length ? 'installed' : 'unchanged',
+    hook: hook.length ? 'installed' : 'unchanged', toolbox,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "description": "Shared project memory and workflows for teams building with AI: a versioned record of plans, decisions, contracts and reviews across repos, human-approved review gates, and a zero-dependency `yad` CLI plus 38 skills for your AI assistant.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/sdlc/config.yaml

@@ -217,7 +217,7 @@ build:
   story_build_states: [in-build, shipped]   # in-build = some tasks shipped; shipped = all tasks in tasks.md shipped
   # Backfill (yad-backfill) — specs for already-built features in an existing repo.
   backfill:
-    tool: repomix                  # the one true CLI subprocess: `npx repomix@latest` (Phase 0 / RESEARCH-NOTES §3)
+    tool: repomix                  # the one true CLI subprocess: `npx repomix@1.18.1` (Phase 0 / RESEARCH-NOTES §3)
     pack_flags: "--compress --include <globs> --include-logs --style markdown"   # one feature at a time; Secretlint by default
     spec_location: "specs/backfill/<feature>/spec.md"   # draft (verified: false) until a human approves
     gate_scope: touched-features   # block a change only until the features it touches have approved specs

package/skills/sdlc/module-help.csv

@@ -24,7 +24,7 @@ SDLC Workflow,yad-open-pr,Open PR/MR,OP,"Build helper: open a code-repo task PR/
 SDLC Workflow,yad-ship,Commit + Open PR/MR,SP2,"Build helper: commit AND open the task PR/MR in one step — a thin orchestration over yad-commit then yad-open-pr. Commits the staged atomic change by the conventions, then pushes the branch and opens the PR/MR from the committed template, assigned to the logged-in gh/glab login with no reviewers requested. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the yad ship CLI. Never merges; never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {repo: <name>} {risk: low|medium|high} {contract-change: true|false} {base: <branch>},3-build,yad-pr-template,,false,<repo>/,one commit + one PR/MR
 SDLC Workflow,yad-product-bridge,Product Review Bridge,PB,"The templated PR/MR bridge for the Shape review gate: when the Product has a platform (.sdlc/product.json), open a review PR/MR on the Product for an authored artifact, apply the touched-domain labels (no reviewers are requested), and provide the read-only gh/glab recipes yad-review-gate's sync uses to pull platform comments + approvals into the file ledger. Local-user auth, no stored tokens; file ledger stays the source of truth; degrades to local when no platform/CLI. Never auto-advances.",,{epic: EP-<slug>} {artifact: epic.md|architecture.md|ui-design.md|stories/} {action: open|route},1-front,yad-review-gate,yad-review-gate,false,epics/EP-<slug>/.sdlc/,product-prs.json
 SDLC Workflow,yad-engineer-review,Engineer Review & Merge,ER,"Build Step E: wire an advisory AI first-pass (CodeRabbit) on the PR, record the human engineer review with the same advance-human discipline as the Shape gates (1 approval from someone other than the author; high risk / contract / auth / payments add an advisory risk step), and on merge record the ship in epics/<epic>/.sdlc/build-log.json and update the story state. AI review is advisory, never the authority; the human owns the merge. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {task: T0N} {repo: <repo>} {action: ai-review|approve|ship},3-build,yad-ship,,false,epics/EP-<slug>/.sdlc/,build-log.json story-status
-SDLC Workflow,yad-backfill,Backfill Specs,BF,"Build Step G: generate specs for already-built features in an existing repo. Confirm Repomix (npx repomix CLI), pack ONE feature (compress + git logs, secret-scan), feed to AI with a 'describe what exists, do not invent' prompt, write a DRAFT spec marked verified: false. Human approval (reuse yad-review-gate) makes it real. Boundary auto-proposed and human-confirmed. A change is blocked only until the features it touches have approved specs. The promote action flips a brownfield stub epic (yad-stub) to a real, verified feature epic once its backfill spec is approved. Never auto-advances.",,{repo: <repo>} {feature: <name + globs>} {action: pack|draft|approve|gate|promote} {epic: EP-<slug> (promote)},3-build,,,false,demo-repos/<repo>/specs/backfill/<feature>/,spec.md backfill-check.sh
+SDLC Workflow,yad-backfill,Backfill Specs,BF,"Build Step G: generate specs for already-built features in an existing repo. Confirm Repomix (npx repomix@1.18.1 CLI), pack ONE feature (compress + git logs, secret-scan), feed to AI with a 'describe what exists, do not invent' prompt, write a DRAFT spec marked verified: false. Human approval (reuse yad-review-gate) makes it real. Boundary auto-proposed and human-confirmed. A change is blocked only until the features it touches have approved specs. The promote action flips a brownfield stub epic (yad-stub) to a real, verified feature epic once its backfill spec is approved. Never auto-advances.",,{repo: <repo>} {feature: <name + globs>} {action: pack|draft|approve|gate|promote} {epic: EP-<slug> (promote)},3-build,,,false,demo-repos/<repo>/specs/backfill/<feature>/,spec.md backfill-check.sh
 SDLC Workflow,yad-run,Run (Automation),RN,"Phase 4 orchestrator: drive a story's Build loop (spec→tasks→implement→checks) in one code repo, reading each step's advance dial through the engine (yad dial --json) — on auto it advances on its own, on human it stops for a human. Records every run in the trust log, the run record yad dial shows as advice. A clean checks pass on auto advances to the engineer review; any FAIL / scope overrun / contract touch HALTS. set-dial runs yad dial (no trust threshold since E34; a gate is refused); kill/unkill run yad kill / yad unkill, recorded in .sdlc/automation.json. Never drives a Shape step; the human merge gate never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <repo>} {action: run|set-dial|kill|unkill} {step: <back-step>} {to: human|auto},4-automate,yad-spec,yad-engineer-review,false,epics/EP-<slug>/.sdlc/,build-state/<story-id>.json trust-log.json
 SDLC Workflow,yad-status,SDLC Status,SS,"Read-only: print the full Shape step chain, per-step dials, contract lock, story repo tags, and pending approvals at the active gate. For stories in Build, also print each Build step's automation dial and status, the run record (runs / % approved-unchanged, as advice), the Shape author dials and the kill switch from .sdlc/automation.json.",,{epic: EP-<slug>},anytime,,,false,,
 SDLC Workflow,yad-report,Report Issue,RP,"Self issue reporter: when a yad flow breaks, file a well-formed bug in the upstream yadflow repo with AUTO-SCRUBBED diagnostics (yadflow/node/os version, tool present+authenticated booleans, Product platform enum, the YadError code/hint, a path-scrubbed message, and the failing command + flag NAMES only) — never absolute paths, hostnames, git URLs, repo names, logins/emails, epic/story IDs, branch names, or flag values. Searches open issues first to avoid duplicates, previews the exact payload, and asks before posting to the public repo; files via an authenticated gh (the upstream repo is on GitHub) or a prefilled issues/new URL fallback. Also offered automatically after an unexpected failure (interactive only; YAD_NO_REPORT=1 disables). Never a gate, never touches epic state.",,{message: one-line summary},,,,false,,

package/skills/yad-backfill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-backfill
-description: 'Build Step G of the gated SDLC — backfill: generate specs for already-built features in an existing repo so new work does not break them. Confirm Repomix (the one true CLI subprocess: npx repomix), pack ONE feature at a time (compress + git logs, secret-scan), feed it to AI with a "describe what exists, do not invent" prompt, and write a DRAFT spec marked unverified. Require human approval (reuse yad-review-gate) before the spec counts as real. Boundary is auto-proposed from the project convention and human-confirmed. A change is blocked only until the features IT touches have approved specs. The `promote` action flips a brownfield stub epic (minted by yad-stub, so defects could thread off it) to a real, verified feature epic once its backfill spec is approved. Use when the user says "backfill specs", "document an existing feature", "spec the legacy code", or "promote the stub epic".'
+description: 'Build Step G of the gated SDLC — backfill: generate specs for already-built features in an existing repo so new work does not break them. Confirm Repomix (the one true CLI subprocess: npx repomix@1.18.1), pack ONE feature at a time (compress + git logs, secret-scan), feed it to AI with a "describe what exists, do not invent" prompt, and write a DRAFT spec marked unverified. Require human approval (reuse yad-review-gate) before the spec counts as real. Boundary is auto-proposed from the project convention and human-confirmed. A change is blocked only until the features IT touches have approved specs. The `promote` action flips a brownfield stub epic (minted by yad-stub, so defects could thread off it) to a real, verified feature epic once its backfill spec is approved. Use when the user says "backfill specs", "document an existing feature", "spec the legacy code", or "promote the stub epic".'
 ---
 
 # SDLC — Backfill (existing-code specs)
@@ -11,12 +11,41 @@ generating a spec for what is **already built** — so future changes have a con
 it count. Gating is **per touched feature**: a new change is blocked only until the features it touches
 have approved specs — never the whole repo at once.
 
+## When a tool is missing
+
+<!-- Written from yadflow's cli/toolbox.mjs (E87). Change the words there: a test holds this section to it. -->
+
+No tool below is required. When one is missing, this skill still finishes, using the fallback written
+beside it.
+
+For Repomix, decide from yad's answer, not from a guess:
+run `yad toolbox list --json` and read, in its `tools` list, the entry with the tool's `id`. Run it
+where the tool will run: for work inside a code repo, add `--dir <that repo>`, so the tools installed
+there are found.
+
+- **The team's choices.** They come from the Product. If the answer's `product` is null, yad found no
+  Product, so a tool the team chose not to use still shows `used: true`. Tell the person that.
+- **When yad cannot see the tool.** yad does not read every way a tool can be set up (an older install
+  may be missed). If the entry says `missing` but the check in the steps below finds the tool, use
+  it — but never when the entry says `used: false`.
+- **When yad cannot answer** (yad is not installed here, or the command fails), use the check in the
+  steps below.
+
+Tell the person which tools you used and which fallbacks, and why.
+
+- **Repomix** (`repomix`). Use it when its entry has `used: true` and `status.state` is `installed` or `available`. Otherwise — not found, its plugin turned off in Claude Code, or the team chose not to use it (`yad toolbox remove repomix`) — use the fallback.
+  - Fallback — no Repomix pack. yad-connect-repos and yad-backfill put the same context together by hand, from the source tree and the recent git log, and the Shape steps read the code map.
+  - Record `source: repomix-unavailable`. It means the tool was not used, whatever the reason.
+
+<!-- end: When a tool is missing -->
+
 ## Conventions
 
 - `{project-root}` resolves from the project working directory; code repos are separate git repos under
   `{project-root}/demo-repos/<repo>/`.
-- **Repomix is a true CLI subprocess** (Phase 0 / RESEARCH-NOTES §3): `npx repomix@latest [flags]` —
-  NOT a slash-command. It secret-scans by default (Secretlint).
+- **Repomix is a true CLI subprocess** (Phase 0 / RESEARCH-NOTES §3): `npx repomix@1.18.1 [flags]` —
+  NOT a slash-command. Run exactly that version: it is the one yadflow vetted, and `@latest` would
+  take a release nobody checked. It secret-scans by default (Secretlint).
 - Backfilled specs live in the code repo at `specs/backfill/<feature>/spec.md`.
 - A **feature** is the project's natural unit from the constitution (e.g. a module / a `src/<feature>/`
   directory). Auto-propose the boundary from the convention; **a human confirms** it where the code
@@ -40,12 +69,13 @@ guess silently where the code breaks the convention.
 ### Step 2 — `pack` (Repomix, one feature)
 Run, from inside the repo, over **only this feature's files**:
 ```
-npx repomix@latest --compress --include "<feature globs>" --include-logs --style markdown -o <out>.md
+npx repomix@1.18.1 --compress --include "<feature globs>" --include-logs --style markdown -o <out>.md
 ```
 `--compress` (Tree-sitter structural compression) keeps it small; `--include-logs` adds the relevant
 git history (default 50; `--include-logs-count N` to change); Secretlint secret-scans by default. If a
-secret is reported, STOP and have it removed/redacted before continuing. (If `npx repomix` is
-unavailable, degrade: hand-assemble the same feature context and record `repomix: unavailable`.)
+secret is reported, STOP and have it removed/redacted before continuing. (If Repomix is not
+used — see **When a tool is missing** — degrade: hand-assemble the same feature context and record
+`source: repomix-unavailable`.)
 
 ### Step 3 — `draft` (describe what exists — do NOT invent)
 Feed the packed context to the AI with the **"describe what exists, do not invent"** instruction
@@ -58,10 +88,13 @@ repo: <repo>
 artifact: backfill-spec
 status: draft
 verified: false
-source: repomix         # or "repomix: unavailable" when degraded
+source: repomix
 generated: <YYYY-MM-DD>
 ---
 ```
+
+When Repomix was not used, write `source: repomix-unavailable` instead.
+
 `verified: false` means the spec is not real until a human approves it. Keep that line free of a `#`
 comment: the gate reads the whole line, so `verified: true   # approved` would not count. Mark every
 uncertain item explicitly (`<!-- unverified: ... -->`); do not fill gaps with invented behaviour.

package/skills/yad-backfill/references/backfill.md

@@ -6,10 +6,10 @@ the whole repo.
 
 ## Repomix (the one true CLI subprocess)
 
-`npx repomix@latest [flags]` (Phase 0 / RESEARCH-NOTES §3). For a single feature:
+`npx repomix@1.18.1 [flags]` (Phase 0 / RESEARCH-NOTES §3). For a single feature:
 
 ```
-npx repomix@latest --compress --include "src/<feature>/**" --include-logs --style markdown -o <out>.md
+npx repomix@1.18.1 --compress --include "src/<feature>/**" --include-logs --style markdown -o <out>.md
 ```
 
 - `--compress` — Tree-sitter structural compression (keeps the pack small and signal-dense).
@@ -18,8 +18,9 @@ npx repomix@latest --compress --include "src/<feature>/**" --include-logs --styl
 - `--style markdown` — human/AI-readable; default output is `repomix-output.xml`.
 - **Secretlint runs by default** — if a secret is reported, STOP and redact before any AI sees the code.
 
-If `npx repomix` is unavailable, degrade: hand-assemble the same feature context (the feature's files +
-recent git log for those paths) and record `repomix: unavailable` in the spec frontmatter.
+If Repomix is not used (the skill's "When a tool is missing" section says how to tell), degrade:
+hand-assemble the same feature context (the feature's files + recent git log for those paths) and record
+`source: repomix-unavailable` in the spec frontmatter.
 
 ## The "describe what exists, do not invent" prompt
 

package/skills/yad-change/SKILL.md

@@ -249,7 +249,7 @@ is paid (Shape artifacts updated **and** a regression test added, then `status:
 Report: the new `EP-<slug>`, its thread + parent, the re-author-vs-inherit split, the seeded
 `currentStep`, and the next skill — run `yad next EP-<slug>` and name what it names, followed by
 `yad-review-gate`. Do NOT name a skill from memory: which skill runs a step is the project's setting
-(`.sdlc/skills.json`), so a team that bound its own would be sent to one this epic will never use
+(`.sdlc/skills.json`, for every epic or for this epic's route), so a team that bound its own would be sent to one this epic will never use
 again. Unbound, that command names `yad-architecture` for a contract-surface change and `yad-stories`
 / `yad-test-cases` otherwise, which is what this step used to say. Shape steps do not auto-advance. Suggest
 `yad thread <thread>` to see the evolution and `yad-timeline` / `yad-defects` to render it.

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

@@ -16,6 +16,22 @@ connected and its MCP is available, the `ux-designer` lens **generates** screens
 **links** an existing human-made design and reads it back); when nothing is connected, `yad-ui` runs
 markdown-only exactly as before.
 
+## When a tool is missing
+
+<!-- Written from yadflow's cli/toolbox.mjs (E87). Change the words there: a test holds this section to it. -->
+
+No tool below is required. When one is missing, this skill still finishes, using the fallback written
+beside it.
+
+Tell the person which tools you used and which fallbacks, and why.
+
+- **Figma** (`figma`, a connector). This skill connects it, by writing `.sdlc/design.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
+  - Fallback — markdown-only: yad-ui writes ui-design.md and DESIGN.md only.
+- **Pencil (pen.dev)** (`pencil`, a connector). This skill connects it, by writing `.sdlc/design.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
+  - Fallback — markdown-only: yad-ui writes ui-design.md and DESIGN.md only.
+
+<!-- end: When a tool is missing -->
+
 ## Conventions
 
 - `{project-root}` resolves from the project working directory (the **Product**).

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

@@ -17,6 +17,20 @@ available it drives the CLI (grounded in the knowledge base); when nothing is co
 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**.
 
+## When a tool is missing
+
+<!-- Written from yadflow's cli/toolbox.mjs (E87). Change the words there: a test holds this section to it. -->
+
+No tool below is required. When one is missing, this skill still finishes, using the fallback written
+beside it.
+
+Tell the person which tools you used and which fallbacks, and why.
+
+- **DeepTutor** (`deeptutor`, a connector). This skill connects it, by writing `.sdlc/learning.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
+  - Fallback — harness-native tutoring: yad-learn has your agent read the project files directly.
+
+<!-- end: When a tool is missing -->
+
 ## Conventions
 
 - `{project-root}` resolves from the project working directory (the **Product**).

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

@@ -14,6 +14,34 @@ This is **setup/maintenance**, not a gated Shape step — it never touches `.sdl
 epic's approvals. It writes the project-wide registry, the per-repo context cache, and — in the code
 repo itself — a draft of that repo's risk map (Step 3b), which the team commits there through a PR.
 
+## When a tool is missing
+
+<!-- Written from yadflow's cli/toolbox.mjs (E87). Change the words there: a test holds this section to it. -->
+
+No tool below is required. When one is missing, this skill still finishes, using the fallback written
+beside it.
+
+For Repomix, decide from yad's answer, not from a guess:
+run `yad toolbox list --json` and read, in its `tools` list, the entry with the tool's `id`. Run it
+where the tool will run: for work inside a code repo, add `--dir <that repo>`, so the tools installed
+there are found.
+
+- **The team's choices.** They come from the Product. If the answer's `product` is null, yad found no
+  Product, so a tool the team chose not to use still shows `used: true`. Tell the person that.
+- **When yad cannot see the tool.** yad does not read every way a tool can be set up (an older install
+  may be missed). If the entry says `missing` but the check in the steps below finds the tool, use
+  it — but never when the entry says `used: false`.
+- **When yad cannot answer** (yad is not installed here, or the command fails), use the check in the
+  steps below.
+
+Tell the person which tools you used and which fallbacks, and why.
+
+- **Repomix** (`repomix`). Use it when its entry has `used: true` and `status.state` is `installed` or `available`. Otherwise — not found, its plugin turned off in Claude Code, or the team chose not to use it (`yad toolbox remove repomix`) — use the fallback.
+  - Fallback — no Repomix pack. yad-connect-repos and yad-backfill put the same context together by hand, from the source tree and the recent git log, and the Shape steps read the code map.
+  - Record `source: repomix-unavailable`. It means the tool was not used, whatever the reason.
+
+<!-- end: When a tool is missing -->
+
 ## Conventions
 
 - `{project-root}` resolves from the project working directory (the **Product**).
@@ -21,8 +49,9 @@ repo itself — a draft of that repo's risk map (Step 3b), which the team commit
   Impeccable, later) are installed/run **here** and target the connected code repos **by path**. The
   code repos themselves need no install for this. (The Build CI gates are the exception — they
   live inside each code repo; see `yad-checks`.)
-- **Repomix is a true CLI subprocess** (Phase 0 / RESEARCH-NOTES §3): `npx repomix@latest [flags]` —
-  NOT a slash-command. It secret-scans by default (Secretlint).
+- **Repomix is a true CLI subprocess** (Phase 0 / RESEARCH-NOTES §3): `npx repomix@1.18.1 [flags]` —
+  NOT a slash-command. Run exactly that version: it is the one yadflow vetted, and `@latest` would
+  take a release nobody checked. It secret-scans by default (Secretlint).
 - Registry: `{project-root}/.sdlc/repos.json` (project-wide, shared across all epics — NOT per-epic).
 - Per-repo cache: `{project-root}/.sdlc/code-context/<repo>/` holds `pack.md` + `code-map.md`.
 
@@ -84,12 +113,12 @@ Determine where the code is:
 ### Step 2 — Pack the repo (Repomix, the full cached context layer)
 From the code repo, run (flags from `config.yaml` `code_context.pack_flags`):
 ```
-npx repomix@latest --compress --include-logs --style markdown -o {project-root}/.sdlc/code-context/<repo>/pack.md
+npx repomix@1.18.1 --compress --include-logs --style markdown -o {project-root}/.sdlc/code-context/<repo>/pack.md
 ```
 `--compress` (Tree-sitter structural compression) keeps it small and signal-dense; `--include-logs`
 adds recent git history; Secretlint secret-scans by default. **If a secret is reported, STOP and have
 it redacted before any AI reads the pack.** Pack the whole repo, or the source boundary from the
-project's constitution if one is defined. (If `npx repomix` is unavailable, degrade: hand-assemble the
+project's constitution if one is defined. (If Repomix is not used — see **When a tool is missing** — degrade: hand-assemble the
 same context — the repo's source tree + recent git log — and record `source: repomix-unavailable`.)
 
 ### Step 3 — Build the code-map (the lightweight index layer)
@@ -231,7 +260,7 @@ the repo's default branch.
 The cached pack + map are the default. When a Shape phase needs an **area** not in the map, it may
 re-run Repomix **live**, scoped to that area:
 ```bash
-npx repomix@latest --compress --include "<area globs>" --style markdown -o -
+npx repomix@1.18.1 --compress --include "<area globs>" --style markdown -o -
 ```
 Same CLI, invoked ad hoc — no registry write. A **stale repo** (HEAD ≠ `syncedHead`) is different: the
 phase **flags it and stops**, pointing the human at `yad repo refresh <repo>` (or `yad check --fix`) —

package/skills/yad-connect-repos/references/code-context.md

@@ -10,7 +10,7 @@ Run from the Product, targeting the connected repo (flags from `config.yaml`
 `code_context.pack_flags`):
 
 ```
-npx repomix@latest --compress --include-logs --style markdown \
+npx repomix@1.18.1 --compress --include-logs --style markdown \
   -o {project-root}/.sdlc/code-context/<repo>/pack.md
 ```
 
@@ -20,8 +20,8 @@ npx repomix@latest --compress --include-logs --style markdown \
 - **Secretlint runs by default** — if a secret is reported, **STOP and redact** before any AI reads the
   pack. Never let a secret reach the model or the cache.
 
-Pack the whole repo, or the source boundary defined in the project's constitution. If `npx repomix` is
-unavailable, degrade: hand-assemble the same context (the repo's source tree + recent git log) and
+Pack the whole repo, or the source boundary defined in the project's constitution. If Repomix is not
+used (the skill's "When a tool is missing" section says how to tell), degrade: hand-assemble the same context (the repo's source tree + recent git log) and
 record `source: repomix-unavailable` in the registry entry.
 
 ## Layer 2 — the code-map (lightweight index, the default the brain reads)
@@ -73,7 +73,7 @@ When a Shape phase needs an area not captured in the code-map, it may re-pack th
 scoped to the area, without writing the cache:
 
 ```bash
-npx repomix@latest --compress --include "<area globs>" --style markdown -o -
+npx repomix@1.18.1 --compress --include "<area globs>" --style markdown -o -
 ```
 
 This is for a one-off look at a specific area. **Staleness is a human decision, not an automatic
@@ -93,7 +93,7 @@ lands the removal + the managed `.gitignore` line in the same audit commit. The
 ## Why this stays DRY with backfill
 
 `yad-backfill` already documents the exact Repomix command, the Secretlint discipline, the
-`repomix: unavailable` degrade, and the "describe what exists, do not invent" prompt
+`source: repomix-unavailable` degrade, and the "describe what exists, do not invent" prompt
 (`../yad-backfill/references/backfill.md`). This skill reuses all of it; the only differences are
 **scope** (repo-wide index vs one feature) and **output** (a lightweight code-map for the brain vs a
 human-approved feature spec). Backfill produces a *verified* spec that gates changes; connect produces a

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

@@ -16,6 +16,26 @@ tool is connected and its MCP is available, the `test architect` lens **generate
 into the connected repo(s) (or **links** an existing suite and reads it back); when nothing is
 connected, `yad-test-cases` runs artifacts-only exactly as before.
 
+## When a tool is missing
+
+<!-- Written from yadflow's cli/toolbox.mjs (E87). Change the words there: a test holds this section to it. -->
+
+No tool below is required. When one is missing, this skill still finishes, using the fallback written
+beside it.
+
+Tell the person which tools you used and which fallbacks, and why.
+
+- **Playwright MCP** (`playwright`, a connector). This skill connects it, by writing `.sdlc/testing.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
+  - Fallback — artifacts-only: yad-test-cases writes test-cases.md only.
+- **Cypress** (`cypress`, a connector). This skill connects it, by writing `.sdlc/testing.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
+  - Fallback — artifacts-only: yad-test-cases writes test-cases.md only.
+- **pytest** (`pytest`, a connector). This skill connects it, by writing `.sdlc/testing.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
+  - Fallback — artifacts-only: yad-test-cases writes test-cases.md only.
+- **Maestro** (`maestro`, a connector). This skill connects it, by writing `.sdlc/testing.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
+  - Fallback — artifacts-only: yad-test-cases writes test-cases.md only.
+
+<!-- end: When a tool is missing -->
+
 ## Conventions
 
 - `{project-root}` resolves from the project working directory (the **Product**).

package/skills/yad-docs/SKILL.md

@@ -120,7 +120,7 @@ Optionally record a `docs:` line in a `DOCS.md` index under the epic.
 - `action: generate` (default) — generate the source + manifest; stop. The CLI may npm-build to verify,
   but no publish.
 - `action: deploy` — drive **`yad docs deploy --epic <id>`**: it npm-builds the site (`npm ci && npm run
-  build` as a subprocess, like `yad-spec` shelling `npx repomix`), ensures the Pages CI workflow is
+  build` as a subprocess, like `yad-spec` shelling out to Repomix), ensures the Pages CI workflow is
   present, and reports the deploy URL (publish happens via CI). **Degrades** to the local `dist/` path
   when no platform CLI / `target: "none"` (build-only). **A failed build exits 1**: if `npm ci` (or
   `npm install`, when the site has no lockfile) or `npm run build` fails, or the site was never generated, the command names the site and exits 1 —

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

@@ -119,6 +119,14 @@ binding that will never run: a value that is not a skill name (`YAD-CFG-006`), a
 does not know (`skills:unknown-step`) and a review gate, which `yad gate` drives (`skills:review-step`).
 It never rewrites the file.
 
+A line can also apply to **one route only** (E51): `"profiles": { "spike": { "steps": { "epic":
+"spike-skill" } } }`, written with `yad skill bind <step> <skill> --profile <route>`. The most specific
+line wins — the epic's route (the `profile` its `state.json` records, as written; an epic that records
+none uses the project-wide line, never a route guessed from its chain), then the project-wide `steps`,
+then the catalogue. `yad skill list --epic <id>` shows one
+epic's view; `yad doctor` also reports a route this release does not have (`skills:unknown-profile`)
+and a step the route never walks (`skills:off-route`).
+
 **The kill switch and the Shape dials live in `.sdlc/automation.json` (E34)**, also a Product-level file,
 also absent by default:
 
@@ -762,8 +770,8 @@ no `steps`, just the state and its record:
 `yad next` reads these files too: once an epic is `ready-for-build`, `yad next <epic>` resolves each
 story/repo's `currentStep` into the next build sub-step and prints it with the remaining chain and the
 step's advance dial — so Build is guided, not just hinted at. The skill it names comes from
-`.sdlc/skills.json` when the project bound one (see "The one column a project overrides is the skill"
-above); unbound, the defaults are `spec`/`tasks` → `yad-spec`, `implement` → `yad-implement`,
+`.sdlc/skills.json` when the project bound one — for the epic's route first, then project-wide (see
+"The one column a project overrides is the skill" above); unbound, the defaults are `spec`/`tasks` → `yad-spec`, `implement` → `yad-implement`,
 `checks` → `yad-checks`, `engineer-review` → `yad-engineer-review`.
 
 ## `trust-log.json` (shard-then-fold)

package/skills/yad-learn/SKILL.md

@@ -22,6 +22,20 @@ This is a **cross-cutting, opt-in** skill (like `yad-status`, it runs any time).
 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.
 
+## When a tool is missing
+
+<!-- Written from yadflow's cli/toolbox.mjs (E87). Change the words there: a test holds this section to it. -->
+
+No tool below is required. When one is missing, this skill still finishes, using the fallback written
+beside it.
+
+Tell the person which tools you used and which fallbacks, and why.
+
+- **DeepTutor** (`deeptutor`, a connector). Used when `.sdlc/learning.json` connects it. yad-connect-learning writes that file; follow it, not yad's toolbox answer.
+  - Fallback — harness-native tutoring: yad-learn has your agent read the project files directly.
+
+<!-- end: When a tool is missing -->
+
 ## Conventions
 
 - `{project-root}` resolves from the project working directory (the **Product**).

package/skills/yad-run/SKILL.md

@@ -72,15 +72,18 @@ it**: stop, report the recorded `record.reason`, and point at `yad unskip <epic>
 the lane is owed after all. **Never write a Build step as `skipped` or `deferred`**: a lane is skipped
 whole or not at all, and `yad doctor` reports a single step set aside.
 
-Also read **which skill runs each step** — `yad skill list --json`, whose `steps[]` gives each step id
-its `skills` array. That is the project's choice (`.sdlc/skills.json`, E6) and the engine's default
-when it has made none. Read it once here; it does not change during a run.
+Also read **which skill runs each step** — `yad skill list --epic <epic> --json`, whose `steps[]` gives
+each step id its `skills` array. Always pass `--epic`: a project may bind a step for one route only
+(`profiles.<route>` in `.sdlc/skills.json`, E51), and that line wins for an epic on the route — the
+plain `yad skill list` shows the project-wide answer, which may be the wrong skill for this epic. That
+is the project's choice (`.sdlc/skills.json`, E6) and the engine's default when it has made none. Read
+it once here; it does not change during a run.
 
 ### `action: run` — drive the loop
 Walk the steps for `repo` starting at `from`/`currentStep`. For each step:
 
 1. **Run the step's skill — use the list from Step 0, never a name written here.** Look the step id
-   up in `yad skill list --json` and run every entry of its `skills` **in order**, each one seeing what
+   up in `yad skill list --epic <epic> --json` and run every entry of its `skills` **in order**, each one seeing what
    the one before it produced; the last output is the result. (`yad next <epic> --json` gives the same
    answer per lane once `build-state/<story>.json` is on disk, if you already have it open.) Which
    skill runs a step is the project's setting, so a hardcoded name here would make this loop do one

package/skills/yad-run/references/run-loop.md

@@ -14,7 +14,8 @@ spec → tasks → implement → checks → engineer-review(locked)
 ```
 
 **These names are the engine's DEFAULTS, not a fixed wiring.** Which skill runs a step is the
-project's setting in `.sdlc/skills.json`, so the loop reads `yad skill list --json` once at Step 0 and
+project's setting in `.sdlc/skills.json` — for every epic, or for one route only — so the loop reads
+`yad skill list --epic <epic> --json` (that epic's route, E51) once at Step 0 and
 runs every entry of that step's `skills`, in order, when it is bound to more than one. Unbound: `spec` and `tasks` are the two legs of `yad-spec` (the heavy ceremony, then the atomic
 `tasks.md`), `implement` is one atomic task via `yad-implement`, and `checks` is
 `yad-checks (action: run)`. `engineer-review` is the human gate at `yad-engineer-review` — always a

package/skills/yad-spec/SKILL.md

@@ -14,10 +14,39 @@ when driven by the orchestrator (`yad-run`, Phase 4) it records a `spec`/`tasks`
 (Step 8) — but it never auto-advances a contract change or a Shape step.
 
 Spec Kit is driven as **harness slash-commands** (`/speckit.*`), not a subprocess CLI (Phase 0
-Deviation 3). When Spec Kit is not installed, the same files are hand-authored in Spec Kit's exact
-layout and the spec is marked `speckit: not-installed` — the workflow does not block on the tool. This
+Deviation 3). When Spec Kit is not used (**When a tool is missing** below), the same files are
+hand-authored in Spec Kit's exact layout and the spec is marked `speckit: not-installed` — the workflow
+does not block on the tool. This
 is the same graceful-degradation pattern `yad-ui` uses for Impeccable.
 
+## When a tool is missing
+
+<!-- Written from yadflow's cli/toolbox.mjs (E87). Change the words there: a test holds this section to it. -->
+
+No tool below is required. When one is missing, this skill still finishes, using the fallback written
+beside it.
+
+For Spec Kit, decide from yad's answer, not from a guess:
+run `yad toolbox list --json` and read, in its `tools` list, the entry with the tool's `id`. Run it
+where the tool will run: for work inside a code repo, add `--dir <that repo>`, so the tools installed
+there are found.
+
+- **The team's choices.** They come from the Product. If the answer's `product` is null, yad found no
+  Product, so a tool the team chose not to use still shows `used: true`. Tell the person that.
+- **When yad cannot see the tool.** yad does not read every way a tool can be set up (an older install
+  may be missed). If the entry says `missing` but the check in the steps below finds the tool, use
+  it — but never when the entry says `used: false`.
+- **When yad cannot answer** (yad is not installed here, or the command fails), use the check in the
+  steps below.
+
+Tell the person which tools you used and which fallbacks, and why.
+
+- **Spec Kit** (`spec-kit`). Use it when its entry has `used: true` and `status.state` is `installed` or `available`. Otherwise — not found, its plugin turned off in Claude Code, or the team chose not to use it (`yad toolbox remove spec-kit`) — use the fallback.
+  - Fallback — yad-spec writes the same spec files by hand, in Spec Kit's layout.
+  - Record `speckit: not-installed`. It means the tool was not used, whatever the reason.
+
+<!-- end: When a tool is missing -->
+
 ## Conventions
 
 - `{project-root}` resolves from the project working directory — the **product** repo (epic
@@ -75,17 +104,19 @@ contract here. (On a route that HAS one; the short lanes do not — see below.)
   already exists, a commit that only DELETES it is allowed through, which is the way back out.)
 
 ### Step 4 — Detect Spec Kit
-Check for `/speckit.*` slash-commands and/or `demo-repos/<repo>/.specify/`. Record the result for
-Step 6's frontmatter (`speckit: installed | not-installed`).
+Read Spec Kit's entry in `yad toolbox list --json --dir demo-repos/<repo>`, as **When a tool is
+missing** says. If yad cannot answer, check for `/speckit.*` slash-commands and/or
+`demo-repos/<repo>/.specify/`. Record the result for Step 6's
+frontmatter (`speckit: installed | not-installed`).
 
 ### Step 5 — Run the heavy ceremony ONCE (or degrade)
-**Installed** — from inside `demo-repos/<repo>/`, drive, in order:
+**Used** — from inside `demo-repos/<repo>/`, drive, in order:
 `/speckit.specify` → `/speckit.clarify` → `/speckit.plan` → `/speckit.analyze` →
 `/speckit.checklist` → `/speckit.tasks`. **Pin the feature to `<story>`** (do not accept an
 auto-slug). Seed `specify` from the story's acceptance criteria and the contract elements from Step 3.
 `/speckit.constitution` and `/speckit.implement` are **out of scope for Step A** (implement is Step B).
 
-**Not installed (degrade)** — hand-author the identical files in Spec Kit's layout under
+**Not used (degrade)** — hand-author the identical files in Spec Kit's layout under
 `demo-repos/<repo>/specs/<story>/`: `spec.md`, `research.md`, `data-model.md`, `contracts/`,
 `plan.md`, `tasks.md`. The content is what a real Spec Kit run would produce, traceable to the story's
 acceptance criteria and the locked contract surface. `tasks.md` MUST be numbered atomic tasks (`T01…`),

package/skills/yad-spec/references/spec-handoff.md

@@ -2,7 +2,7 @@
 
 Step A (`yad-spec`) runs the **heavy Spec Kit ceremony once per story per repo** and writes the
 result into the story's code repo. This reference pins the exact commands, the files they produce, and
-how to hand-author the same files faithfully when Spec Kit is not installed — so Step B
+how to hand-author the same files faithfully when Spec Kit is not used — so Step B
 (`yad-implement`, not built yet) can read them unchanged.
 
 ## The ceremony (run once, in order)
@@ -39,7 +39,7 @@ demo-repos/<repo>/specs/<story-id>/
   link.md         # back-pointer to the story in the product repo (Step A adds this; not a Spec Kit file)
 ```
 
-## Degradation rules (when Spec Kit is not installed)
+## Degradation rules (when Spec Kit is not used)
 
 Author each file by hand so it is **indistinguishable in shape** from a real Spec Kit run. The content
 comes from the story's acceptance criteria and the **locked contract surface** — never invented.

package/skills/yad-test-cases/SKILL.md

@@ -23,6 +23,26 @@ automation is materialized in the **testing tool connected via `yad-connect-test
 into it (or **links** an existing suite and reads it back); when none is connected, the step degrades to
 the Markdown artifact only — the testing tool is additive, exactly like the design tool.
 
+## When a tool is missing
+
+<!-- Written from yadflow's cli/toolbox.mjs (E87). Change the words there: a test holds this section to it. -->
+
+No tool below is required. When one is missing, this skill still finishes, using the fallback written
+beside it.
+
+Tell the person which tools you used and which fallbacks, and why.
+
+- **Playwright MCP** (`playwright`, a connector). Used when `.sdlc/testing.json` connects it. yad-connect-testing writes that file; follow it, not yad's toolbox answer.
+  - Fallback — artifacts-only: yad-test-cases writes test-cases.md only.
+- **Cypress** (`cypress`, a connector). Used when `.sdlc/testing.json` connects it. yad-connect-testing writes that file; follow it, not yad's toolbox answer.
+  - Fallback — artifacts-only: yad-test-cases writes test-cases.md only.
+- **pytest** (`pytest`, a connector). Used when `.sdlc/testing.json` connects it. yad-connect-testing writes that file; follow it, not yad's toolbox answer.
+  - Fallback — artifacts-only: yad-test-cases writes test-cases.md only.
+- **Maestro** (`maestro`, a connector). Used when `.sdlc/testing.json` connects it. yad-connect-testing writes that file; follow it, not yad's toolbox answer.
+  - Fallback — artifacts-only: yad-test-cases writes test-cases.md only.
+
+<!-- end: When a tool is missing -->
+
 ## Conventions
 
 - `{project-root}` resolves from the project working directory.