yadflow 4.3.0 → 4.5.0

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-status/SKILL.md

@@ -15,6 +15,9 @@ reads `.sdlc/` and `reviews/` and reports.
 
 ## On Activation
 
+This skill reports on epics. For people — what each team member did since the previous working day,
+what they are working on and what is waiting — point to `yad standup` (E132) instead of rebuilding it.
+
 ### Step 1 — Resolve the epic
 If no `EP-<slug>` was given, list the epics under `{project-root}/epics/` and ask which one (or
 report all if the user asked for an overview).

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.

package/skills/yad-ui/SKILL.md

@@ -12,7 +12,7 @@ screens and/or web pages — inside that tool (e.g. Figma), linked back from the
 passes to `yad-review-gate` (base rule: 1 distinct approver, who should not be the author).
 
 UI work is shaped by **Impeccable**, invoked as **harness slash-commands** (not a subprocess CLI) per
-the Phase 0 deviation. If Impeccable is not installed, the `ux-designer` lens authors the same outputs
+the Phase 0 deviation. If Impeccable is not used (**When a tool is missing** below), the `ux-designer` lens authors the same outputs
 directly — the workflow does not block on the tool.
 
 The visual design is materialized in the **design tool connected via `yad-connect-design`**
@@ -21,6 +21,38 @@ The visual design is materialized in the **design tool connected via `yad-connec
 is connected, the step degrades to the Markdown artifacts only — the design tool is additive, exactly
 like 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 Impeccable (the one tool here that is not a connector), 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.
+
+- **Impeccable** (`impeccable`). 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 impeccable`) — use the fallback.
+  - Fallback — markdown-only UI design: yad-ui writes ui-design.md and DESIGN.md directly.
+  - Record `impeccable: not-installed`. It means the tool was not used, whatever the reason.
+- **Figma** (`figma`, a connector). Used when `.sdlc/design.json` connects it. yad-connect-design writes that file; follow it, not yad's toolbox answer.
+  - Fallback — markdown-only: yad-ui writes ui-design.md and DESIGN.md only.
+- **Pencil (pen.dev)** (`pencil`, a connector). Used when `.sdlc/design.json` connects it. yad-connect-design writes that file; follow it, 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.
@@ -84,7 +116,7 @@ Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context
 `epic.repos`**, load the code-map `{project-root}/.sdlc/code-context/<repo>/code-map.md` so the UI
 **reuses existing components and conventions** rather than inventing parallel ones. This complements
 Impeccable's `/impeccable document` (Step 3), which reads code directly for the design system — when
-Impeccable is absent, the code-map is the brain's view of what UI/components already exist.
+Impeccable is not used, the code-map is the brain's view of what UI/components already exist.
 
 - **Greenfield-safe:** if `repos.json` is absent/empty, note "no repos connected" and proceed.
 - **Staleness:** if a repo's current HEAD ≠ its registry `syncedHead`, warn and suggest
@@ -102,7 +134,8 @@ Adopt the **ux-designer** lens. Drive Impeccable as slash-commands:
 `/impeccable document` generates the root `DESIGN.md` from existing code; `/impeccable extract` pulls
 components/tokens into the design system; `/impeccable craft` is shape-then-build for the new screens.
 
-**Graceful degradation:** if Impeccable is not installed (no `/impeccable …` commands available), the
+**Graceful degradation:** if Impeccable is not used (**When a tool is missing** says how to tell; if
+yad cannot answer, it is not used when no `/impeccable …` commands are available), the
 `ux-designer` lens authors `ui-design.md` and `DESIGN.md` directly, and you **note in `ui-design.md`
 that Impeccable was not used**. Do not run `npx impeccable skills install` as part of this step — tool
 installation is out of scope for Shape.