@event4u/agent-config 14.10.0 → 14.11.0

package/dist/agent-src/skills/wireframe/references/story-beat-ledger.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "story-beat-ledger.schema.json",
+  "title": "Story-beat ledger and style bible",
+  "description": "The one cleanly unmet gap Phase 9.1 of road-to-frontend-fidelity-calibration verified: `grep -rilE 'beat ledger|story ledger|style bible' src/` returned zero paths on 2026-08-22. Hosted in `wireframe` because that skill already owns the low-fidelity artefact — a beat ledger IS a low-fidelity artefact, one axis further along than a static skeleton. No skill was created to hold a schema. Two halves in one file, deliberately: the ledger is what happens in order, the style bible is what it looks like throughout, and splitting them into two files would let a beat reference a style that no longer exists.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "beats"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "schema_version": {
+      "enum": [
+        1
+      ],
+      "description": "Pinned. One-member `enum` rather than `const`: this repo's Draft-07 subset validator enforces `enum` and silently ignores `const`."
+    },
+    "surface": {
+      "type": "string",
+      "description": "The page or route the ledger describes."
+    },
+    "style_bible": {
+      "type": "object",
+      "description": "What holds STILL across every beat. A property that changes per beat belongs on the beat, not here — that split is the point of having a bible at all.",
+      "additionalProperties": true,
+      "properties": {
+        "palette_ref": {
+          "type": "string",
+          "description": "A token reference, never a literal. `brand-source-of-truth` governs: the consumer's registered tokens win over anything a bible proposes."
+        },
+        "type_ref": {
+          "type": "string",
+          "description": "Token reference for the type system, per `typography-system`."
+        },
+        "motion_band": {
+          "type": "string",
+          "description": "The motion band this surface sits in. `fe-design` § Motion is the timing source of truth; this names a band, it does not define one."
+        },
+        "reduced_motion_presentation": {
+          "type": "string",
+          "description": "What the surface presents INSTEAD of motion when `prefers-reduced-motion` is set. Required by convention on any bible whose beats carry `motion`: `animation: none` is a suppression, not a presentation. This field is the schema half of step 9.3."
+        },
+        "art_direction_note": {
+          "type": "string",
+          "description": "The brief-level direction a `design-director` read would judge against. Free text."
+        }
+      }
+    },
+    "beats": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Ordered. A scroll-driven surface is a sequence, and the order is the content.",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "intent"
+        ],
+        "additionalProperties": true,
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable beat id. The scroll evidence artefact in `design-review/references/verification-automation.md` references these ids, which is what lets a review check a beat rather than a pixel row."
+          },
+          "intent": {
+            "type": "string",
+            "description": "What this beat is FOR, in one sentence. A beat with no intent is a section, and a wireframe does not need a ledger to list sections."
+          },
+          "enters_at": {
+            "type": [
+              "string",
+              "number",
+              "null"
+            ],
+            "description": "Where the beat begins — a scroll fraction, a viewport-height multiple, or null when the ledger is authored before any layout exists. `null` is the honest value at wireframe stage and must stay allowed."
+          },
+          "element_states": {
+            "type": "array",
+            "description": "What is asserted to be true at this beat. The unit a review can check.",
+            "items": {
+              "type": "object",
+              "required": [
+                "selector",
+                "state"
+              ],
+              "additionalProperties": true,
+              "properties": {
+                "selector": {
+                  "type": "string",
+                  "description": "A CSS selector, or a wireframe region name before markup exists."
+                },
+                "state": {
+                  "type": "string",
+                  "description": "The asserted state — `visible`, `pinned`, `faded`, `offscreen`, and so on. A vocabulary the reviewer and the ledger share, not a free-form description."
+                }
+              }
+            }
+          },
+          "motion": {
+            "type": "string",
+            "description": "The motion this beat uses, if any. A beat carrying this obliges `style_bible.reduced_motion_presentation` to say what replaces it."
+          },
+          "maturity": {
+            "enum": [
+              "wireframe",
+              "comp"
+            ],
+            "description": "Which axis of `design-fidelity` § Two axes this beat sits on. A `wireframe` beat carries a STRUCTURE mandate: its greys and its exact offsets are non-decisions and must not be reproduced 1:1. Present so a ledger cannot be handed over as a pixel spec by omission."
+          }
+        }
+      }
+    }
+  }
+}

package/dist/agent-src/skills/workspace-link/SKILL.md

@@ -0,0 +1,131 @@
+---
+model_tier: medium
+name: workspace-link
+description: "Use when a cross-workspace import will not resolve — cannot find module @org/*, TS2307 — to link the packages properly with the workspace: protocol instead of patching tsconfig paths."
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# Linking workspace packages
+
+One workspace imports another and the import does not resolve. The fix is a
+**dependency declaration**, not a resolver override.
+
+> **Own analysis.** The forms and failure modes below are derived from the
+> public behaviour of the package managers named, not adopted from a third-party
+> artefact, so no provenance ledger entry backs them. Verify the protocol
+> support against the manager version the repository actually pins — see
+> § Check the manager, not the table.
+
+## When to use
+
+- `Cannot find module '@org/ui'` or `Cannot find module '@org/ui' or its
+  corresponding type declarations`.
+- TypeScript `TS2307`, or a bundler resolving a workspace import to `undefined`.
+- A workspace import that works in the editor and fails in the build (or the
+  reverse) — the classic signature of a `paths` patch standing in for a
+  dependency.
+
+## Procedure
+
+### 1. Declare the dependency in the importing workspace
+
+The importing workspace's `package.json` must name the imported workspace in
+`dependencies` (or `devDependencies` when the import is test-only):
+
+```json
+{
+  "name": "@org/web",
+  "dependencies": { "@org/ui": "workspace:*" }
+}
+```
+
+The name on the left is the imported package's own `name` field — not its
+directory. Then re-run the install so the manager creates the link.
+
+### 2. Pick the form
+
+Four forms, and the difference only shows up at publish time:
+
+| Form | Resolves locally to | On publish, rewritten to |
+|---|---|---|
+| `workspace:*` | the local workspace, any version | the exact version at publish |
+| `workspace:^` | the local workspace | `^<version>` |
+| `workspace:~` | the local workspace | `~<version>` |
+| `workspace:<range>` | the local workspace if its version satisfies `<range>`, else fails the install | `<range>` |
+
+For a private monorepo that never publishes, `workspace:*` is the right default
+— it cannot drift out of sync with the local version. For packages that *are*
+published, `workspace:^` is what keeps the released range honest.
+
+The explicit-range form is the only one that can **fail** the install, and that
+is a feature: it is how a workspace states which version of a sibling it needs.
+
+### 3. Check the manager, not the table
+
+Protocol support is not uniform. pnpm and Yarn (berry) implement all four forms;
+Bun implements the protocol; npm's support arrived later than the others.
+Confirm against the version in `packageManager` / the lockfile rather than
+assuming — [`monorepo-workspace`](../monorepo-workspace/SKILL.md) step 1 reports
+which manager this repository actually uses.
+
+Where the protocol is unsupported, the correct fallback is still a dependency
+declaration — the sibling's version range — never a resolver override.
+
+### 4. Verify it resolves for real
+
+Re-run the failing command, not the editor. A resolved editor and a failing
+build is the exact state a `paths` patch produces, so the build is the probe.
+
+## Output format
+
+A workspace-link answer MUST contain, in order:
+
+1. **The unresolved import, named** — the importing workspace path, the imported
+   package `name` (not its directory), and the exact error text.
+2. **The declaration to add** — the `package.json` path, the section
+   (`dependencies` or `devDependencies`), and the `workspace:` form chosen, with
+   one sentence on why that form (private-and-unpublished → `workspace:*`;
+   published → `workspace:^`).
+3. **The install command for this repository's manager**, read from
+   `packageManager` / the lockfile rather than assumed.
+4. **The verification** — the failing build or test command re-run, not the
+   editor, plus its result. A resolved editor and a failing build is the state
+   a `paths` patch produces, so the build is the probe.
+
+## Gotcha
+
+- Adding the dependency without re-running the install changes nothing: the
+  manager creates the symlink at install time.
+- A `workspace:` dependency on a package that is not actually in the workspace
+  globs fails with a confusing "not found" — check the globs
+  ([`monorepo-workspace`](../monorepo-workspace/SKILL.md) step 2) before the
+  spelling of the name.
+- The imported package still needs a valid entry point (`main` / `exports` /
+  `types`). A correct link into a package that exports nothing reads as the same
+  `TS2307`.
+- Circular workspace dependencies install fine and break the task graph later.
+
+## Do NOT
+
+- **Do NOT patch `tsconfig.json` `paths` to point at the sibling's source.** It
+  silences the type error in the editor while the runtime and the bundler still
+  have no dependency to resolve, and it hides the edge from the task runner, so
+  the affected-set calculation and build ordering both go wrong. A `paths` entry
+  is a compiler hint, not a dependency.
+- **Do NOT hand-edit `package.json` link fields or the lockfile** to point at a
+  relative path (`file:../ui`, a hand-written entry under `node_modules`). It
+  works once, on one machine, and is undone by the next install.
+- Do not add the dependency to the *root* `package.json` to make the error go
+  away — the importing workspace is what must declare it.
+- Do not install the sibling from the registry to satisfy the import. That
+  silently pins a published copy while the local source keeps changing.
+
+## See also
+
+- [`monorepo-workspace`](../monorepo-workspace/SKILL.md) — which manager, which workspaces, which graph.
+- [`monorepo-antipatterns`](../../../docs/guidelines/monorepo-antipatterns.md) — the task-graph mistakes a `paths` patch hides.
+- [`blast-radius-analyzer`](../blast-radius-analyzer/SKILL.md) — § Monorepo, once the edge exists.

package/dist/agent-src/skills/workspace-link/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "skill": "workspace-link",
+  "last_eval": "2026-08-23",
+  "description": "5 should-trigger + 5 should-not-trigger. Should-trigger covers an unresolved cross-workspace import and the workspace: protocol that fixes it, including the editor-resolves-build-fails signature of a tsconfig paths patch. Should-not-trigger covers near-miss neighbors: a third-party package that is genuinely missing, structural orientation (monorepo-workspace), impact analysis (blast-radius-analyzer), a TypeScript type error that is not a resolution failure, and a general dependency upgrade.",
+  "queries": [
+    {"q": "cannot find module @org/ui when I import it from apps/web", "trigger": true},
+    {"q": "TS2307 on a workspace import but the package is right there", "trigger": true},
+    {"q": "how do I link one workspace package to another", "trigger": true},
+    {"q": "should I use workspace:* or workspace:^ for this dependency", "trigger": true},
+    {"q": "the import resolves in my editor but the build cannot find it", "trigger": true},
+    {"q": "cannot find module lodash", "trigger": false, "note": "a third-party package that is not installed, not a workspace link"},
+    {"q": "which packages depend on @org/ui", "trigger": false, "note": "structural orientation → monorepo-workspace"},
+    {"q": "what breaks if I change this shared component", "trigger": false, "note": "impact set → blast-radius-analyzer § Monorepo"},
+    {"q": "type error: string is not assignable to number", "trigger": false, "note": "an ordinary type error, nothing to resolve"},
+    {"q": "upgrade react to 19 across the repo", "trigger": false, "note": "dependency upgrade → dependency-upgrade"}
+  ]
+}

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "14.10.0"
+agent_config_version: "14.11.0"
 
 # --- Project identity ---
 project:

package/dist/agent-src/templates/playbook.md

@@ -0,0 +1,75 @@
+# Playbook Template
+
+Template for a **`Playbook` context** (ADR-244) — the sixth type, beside Module, Domain,
+Service, Integration and Infrastructure. It lives in the playbook home and reuses the
+`contexts.md` machinery; it is not a new artefact class.
+
+The frontmatter below is the **playbook's own**, shown in a fence rather than written as
+this file's frontmatter — a template whose example metadata is real metadata gets read as a
+declaration about the template, which is what `check_discovery_frontmatter` correctly
+objected to. `contexts.md` carries none for the same reason.
+
+```yaml
+---
+task: "{one line — what this procedure accomplishes}"
+scope: "{a workspace path, e.g. packages/ui — or the literal `repo`}"
+grade: "{configured | observed}"
+invokes:
+  - "{script / turbo task / turbo generator id}"
+---
+```
+
+## The body
+
+# Playbook: {task}
+
+> **This is THIS repository's answer, and it outranks a shipped skill.** A shipped skill
+> is a generic answer to a generic question. A playbook encodes decisions this repository
+> already made — file layout, barrel exports, test co-location, naming — that no generic
+> skill can know. When both match, the playbook goes first.
+
+## The grade, and what it is claiming
+
+| grade | means | obligation |
+|---|---|---|
+| `configured` | every step invokes something **present in the tree and seen** | **no step may lack an `invokes` entry** |
+| `observed` | the procedure was inferred from a worked example | every step **cites the commit** it was seen in |
+
+Do not write `configured` for a generator you did not observe. That is the Class-A rule of
+`standards-from-config` applied to procedure, and the grade is the only field that tells a
+reader whether to trust the steps or check them.
+
+## Steps
+
+Numbered, in the `command-writing` shape. **Every step carries both lines** — a step
+without them is a suggestion wearing a procedure's formatting.
+
+### 1. {what this step does}
+
+- **Source of truth:** `{the script / generator / task it invokes}` — or, for an
+  `observed` playbook, `{commit sha}` where it was seen.
+- **Verify:** `{a command whose output settles whether the step worked}`
+
+{Any detail the invocation does not carry: a prompt answer to give, a flag that matters,
+a thing that goes wrong if skipped.}
+
+### 2. {…}
+
+- **Source of truth:** `{…}`
+- **Verify:** `{…}`
+
+## What this playbook does NOT cover
+
+{State the boundary. A playbook that silently stops short is worse than one that names
+where it ends, because the reader cannot tell completion from omission.}
+
+## Staleness
+
+Every `invokes` id is resolved by a deterministic check. When an id no longer exists the
+check **fails naming the id**, and the grade **downgrades** — so a renamed generator
+surfaces as a failure rather than as a playbook quietly instructing the wrong command.
+
+First release resolves ids against `package.json#scripts`, `turbo.json` tasks and
+`turbo gen` templates only. Nx generators and Plop are deliberately out of scope (ADR-244
+§ What the first release resolves): their discovery needs a consumer binary, and a gate
+that needs the consumer's toolchain installed is a gate that does not run.

package/dist/agent-src/templates/roadmaps.md

@@ -147,6 +147,43 @@ that was never a judgement call.
     resolves toward serial and a declaration is the cheap way to be right.
     Absent means no declared dependency, never “independent”: the overlap
     heuristic still runs.
+
+    **Companion field, same block — `relates:`.** The wider relation, of which
+    `depends` is one value:
+
+    ```yaml
+    relates:
+      - slug: road-to-other-thing
+        relation: extends        # extends | supersedes | depends | disjoint
+        note: "adds the path axis its § 3 left as slug-only"
+      - slug: road-to-old-thing
+        relation: supersedes
+        note: "same mechanism, this one replaces it"
+    ```
+
+    One row per hit from `agent-config roadmap:context`, which is what the
+    authoring surfaces run before drafting. Four relations and no more —
+    `extends`, `supersedes`, `depends`, `disjoint`; an unknown value is rejected
+    by the roadmap lint, because an open vocabulary here degrades into free-text
+    notes nothing can read.
+
+    A `relation: depends` row **mirrors into `depends:`** so the set contract's
+    edge source stays the single one already defined above; `relates:` never
+    becomes a second dependency source.
+
+    An explicit `relates: []` is a complete answer and the common one, but only
+    when it carries the probe's `scanned:` line as its justification:
+
+    ```yaml
+    relates: []   # scanned: 716 roadmap file(s), 0 sibling hits
+    ```
+
+    Absent-versus-empty is the whole point. Absent means nobody looked; `[]` with
+    a `scanned:` line means somebody looked and found nothing. A `relates: []`
+    written by reflex, with a boilerplate note, carries no information and is
+    worse than none — the pre-save self-check in
+    [`roadmap-writing`](../../skills/roadmap-writing/SKILL.md) asks for exactly
+    this distinction.
 19. **Source-derived roadmaps carry a gap-table + provenance; internally
     originated roadmaps carry neither.** This rule fires **only** when a
     roadmap originates from an external input (a suggestion, a competitive

package/dist/agent-src/templates/scripts/check_playbook_invokes.ts

@@ -0,0 +1,231 @@
+/**
+ * check_playbook_invokes — a `configured` playbook may not name a procedure the tree no
+ * longer has.
+ *
+ * Ships in the consumer `scripts/` template so it runs in the CONSUMER's CI, over the
+ * consumer's own playbooks and the consumer's own configuration. That placement is the
+ * whole design: staleness is a fact about their repository, and a gate in this package
+ * could only ever check this package.
+ *
+ * The grade is the contract (ADR-244). `configured` asserts every step invokes something
+ * present in the tree; when a generator is renamed, that assertion becomes false silently —
+ * the playbook still reads like a procedure and the command no longer exists. This check is
+ * what turns that into a failure instead of a surprise at the next `turbo gen`.
+ *
+ * Three resolvable kinds, and no more: a script name in the package manifest, a declared
+ * task in the task file, and a registered generator template. An Nx or Plop id is reported
+ * `unsupported` — NEVER as resolved and never as missing, because discovering those needs a
+ * binary this check deliberately does not run. Reporting a real id as missing would be the
+ * worse error: it would push a correct playbook to `observed`.
+ *
+ * Usage:
+ *   check_playbook_invokes [--root <dir>] [--home <dir>] [--quiet]
+ *
+ * Exit 0 = every `configured` playbook resolves (or there are none).
+ * Exit 1 = at least one `configured` step names an id the tree does not have.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Playbooks are a context type (ADR-244), so the home is the contexts home. */
+const DEFAULT_HOME = path.join('agents', 'settings', 'contexts');
+
+export interface PlaybookHead {
+    readonly file: string;
+    readonly grade: string;
+    readonly invokes: readonly string[];
+}
+
+export type Verdict = 'resolved' | 'missing' | 'unsupported';
+
+export interface Check {
+    readonly file: string;
+    readonly id: string;
+    readonly verdict: Verdict;
+    /** Where it resolved, for a `resolved` verdict. */
+    readonly where: string | null;
+}
+
+/** Ids this check cannot resolve without running a consumer binary. */
+const UNSUPPORTED_PREFIXES = ['nx ', 'nx:', 'plop ', 'plop:'] as const;
+
+const readJson = (p: string): Record<string, unknown> | null => {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8')) as Record<string, unknown>;
+    } catch {
+        return null;
+    }
+};
+
+const asRecord = (v: unknown): Record<string, unknown> =>
+    v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+
+/**
+ * Minimal frontmatter read — `grade` and the `invokes` list only.
+ *
+ * Deliberately not a YAML dependency: this file ships into a consumer repository, where
+ * adding a parser dependency to run one gate is a cost the consumer did not ask for.
+ */
+export const parseHead = (file: string, text: string): PlaybookHead | null => {
+    if (!text.startsWith('---')) return null;
+    const end = text.indexOf('\n---', 3);
+    if (end < 0) return null;
+    const head = text.slice(3, end);
+    const gradeMatch = /^grade:\s*["']?([A-Za-z]+)["']?\s*$/m.exec(head);
+    if (!gradeMatch) return null;
+
+    const invokes: string[] = [];
+    const lines = head.split('\n');
+    let inList = false;
+    for (const line of lines) {
+        if (/^invokes:\s*$/.test(line)) {
+            inList = true;
+            continue;
+        }
+        if (inList) {
+            const item = /^\s+-\s*["']?(.+?)["']?\s*$/.exec(line);
+            if (item?.[1] !== undefined) {
+                invokes.push(item[1]);
+                continue;
+            }
+            inList = false;
+        }
+        // An inline list is the other legal shape and a reader that only handled the block
+        // form would report a correct playbook as having no ids at all.
+        const inline = /^invokes:\s*\[(.*)\]\s*$/.exec(line);
+        if (inline?.[1] !== undefined) {
+            for (const part of inline[1].split(',')) {
+                const v = part.trim().replace(/^["']|["']$/g, '');
+                if (v.length > 0) invokes.push(v);
+            }
+        }
+    }
+    return { file, grade: gradeMatch[1] as string, invokes };
+};
+
+/** Generator templates registered in the tree, as `<runner> gen <name>` ids. */
+export const registeredGenerators = (root: string): Map<string, string> => {
+    const out = new Map<string, string>();
+    const dir = path.join(root, 'turbo', 'generators');
+    if (!fs.existsSync(dir)) return out;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.set(entry.name, path.relative(root, full));
+            continue;
+        }
+        const text = fs.readFileSync(full, 'utf8');
+        for (const m of text.matchAll(/\.(?:set|add)Generator\(\s*['"]([A-Za-z0-9_-]+)['"]/g)) {
+            out.set(m[1] as string, path.relative(root, full));
+        }
+    }
+    return out;
+};
+
+export const resolveId = (
+    root: string,
+    id: string,
+    gens: Map<string, string>,
+): { verdict: Verdict; where: string | null } => {
+    const lower = id.toLowerCase();
+    if (UNSUPPORTED_PREFIXES.some((p) => lower.startsWith(p))) {
+        return { verdict: 'unsupported', where: null };
+    }
+
+    const gen = /^\S+\s+gen\s+([A-Za-z0-9_-]+)/.exec(id);
+    if (gen) {
+        const name = gen[1] as string;
+        return gens.has(name)
+            ? { verdict: 'resolved', where: gens.get(name) ?? null }
+            : { verdict: 'missing', where: null };
+    }
+
+    const tasks = asRecord(readJson(path.join(root, 'turbo.json'))?.tasks);
+    if (Object.prototype.hasOwnProperty.call(tasks, id)) {
+        return { verdict: 'resolved', where: 'turbo.json#tasks' };
+    }
+    const scripts = asRecord(readJson(path.join(root, 'package.json'))?.scripts);
+    if (Object.prototype.hasOwnProperty.call(scripts, id)) {
+        return { verdict: 'resolved', where: 'package.json#scripts' };
+    }
+    return { verdict: 'missing', where: null };
+};
+
+export const checkAll = (root: string, home: string): Check[] => {
+    if (!fs.existsSync(home)) return [];
+    const gens = registeredGenerators(root);
+    const out: Check[] = [];
+    for (const name of fs.readdirSync(home).sort()) {
+        if (!name.endsWith('.md')) continue;
+        const file = path.join(home, name);
+        const head = parseHead(file, fs.readFileSync(file, 'utf8'));
+        // Only `configured` is a claim about the tree. An `observed` playbook already says
+        // its steps are unverified, so failing it here would punish the honest grade.
+        if (head === null || head.grade !== 'configured') continue;
+        for (const id of head.invokes) {
+            const { verdict, where } = resolveId(root, id, gens);
+            out.push({ file, id, verdict, where });
+        }
+    }
+    return out;
+};
+
+/**
+ * The remediation. BOTH options are printed verbatim on every failure, and neither is
+ * "delete the line": a playbook that loses its evidence line stops being checkable, which
+ * turns a caught drift into an uncatchable one.
+ */
+export const REMEDIATION = [
+    'Two ways to fix this, and only two:',
+    '  1. Fix the `invokes` id — the procedure moved, so point the playbook at where it moved to.',
+    '  2. Downgrade the step to `observed` and cite the commit it was last seen working in.',
+    'Do NOT delete the evidence line. A playbook without it is not a weaker claim, it is an',
+    'unverifiable one — and the next drift goes unnoticed.',
+].join('\n');
+
+const main = (): number => {
+    const argv = process.argv.slice(2);
+    const arg = (flag: string): string | null => {
+        const i = argv.indexOf(flag);
+        return i >= 0 && i + 1 < argv.length ? String(argv[i + 1]) : null;
+    };
+    const quiet = argv.includes('--quiet');
+    const root = arg('--root') ?? '.';
+    const home = arg('--home') ?? path.join(root, DEFAULT_HOME);
+
+    const checks = checkAll(root, home);
+    const missing = checks.filter((c) => c.verdict === 'missing');
+    const unsupported = checks.filter((c) => c.verdict === 'unsupported');
+
+    if (!quiet) {
+        for (const u of unsupported) {
+            process.stdout.write(
+                `ℹ️  ${u.file}: \`${u.id}\` is unsupported by this check (its discovery needs a ` +
+                    `consumer binary) — reported, not treated as missing\n`,
+            );
+        }
+        process.stdout.write(
+            `scanned: ${String(checks.length)} configured step(s) across ${String(new Set(checks.map((c) => c.file)).size)} playbook(s)\n`,
+        );
+    }
+
+    if (missing.length === 0) {
+        if (!quiet) {
+            process.stdout.write('✅  check_playbook_invokes: every configured step resolves in the tree.\n');
+        }
+        return 0;
+    }
+
+    for (const m of missing) {
+        process.stderr.write(
+            `❌  ${m.file}: step invoking \`${m.id}\` does not resolve — no such script, task, or generator in the tree\n`,
+        );
+    }
+    process.stderr.write(`\n${REMEDIATION}\n`);
+    return 1;
+};
+
+if (process.argv[1] !== undefined && process.argv[1].includes('check_playbook_invokes')) {
+    process.exit(main());
+}

package/dist/agent-src/templates/scripts/work_engine/directives/ui/apply.ts

@@ -18,13 +18,30 @@ import {
     agent_directive,
 } from '../../delivery_state.js';
 import { has_design_system, placeholder_paths, provided_artifact } from './design.js';
+import { _playbook_lines, _scaffold_playbooks } from './scaffold.js';
 import {
     is_ambiguous_stack,
     bundle_line,
+    scope_lines,
     unsupported_stack_questions,
 } from './stack_bundles.js';
 
 /** Map `state.stack.frontend` → agent-directive skill name. */
+/**
+ * Task words that make a playbook relevant to the `apply` verb.
+ *
+ * Same shape as `scaffold`'s list and deliberately a SEPARATE constant: `apply` implements
+ * into an existing surface, so a repository may reasonably carry a playbook for one verb and
+ * not the other. One shared list would silently dispatch a scaffold-only procedure here.
+ */
+export const APPLY_VERB_TERMS: ReadonlyArray<string> = [
+    'component',
+    'page',
+    'route',
+    'screen',
+    'view',
+];
+
 export const STACK_DIRECTIVES: Record<string, string> = {
     'blade-livewire-flux': 'ui-apply-blade-livewire-flux',
     'blade-livewire': 'ui-apply-blade-livewire',
@@ -267,10 +284,17 @@ function _delegate_to_stack_skill(state: DeliveryState): StepResult {
         });
     }
     const provided = provided_artifact(state.ui_design as Record<string, Any> | null);
+    // The repository's own procedure goes ahead of the stack skill when it has one. Empty
+    // when it does not, which is what keeps a project with no playbook home byte-identical.
+    // Imported from `scaffold` rather than duplicated: two copies of a scope-match rule
+    // drift, and the drift would be invisible — both lanes would still emit *something*.
+    const playbook_lines = _playbook_lines(_scaffold_playbooks(state, APPLY_VERB_TERMS));
     const lines: string[] = [
         agent_directive(directive),
+        ...playbook_lines,
         `> Stack: \`${stack_label}\`. Implementing the locked design brief.`,
         bundle_line(state.stack, 'build', stack_label),
+        ...scope_lines(state.stack),
         '> Microcopy is locked — every button label, empty-state ' +
             'message, and validation message must come verbatim from ' +
             '`state.ui_design.microcopy`.',