@event4u/agent-config 9.10.0 → 9.11.0

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

@@ -16,13 +16,24 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
+import {
+    UNSUPPORTED_LANE,
+    bundle_line,
+    unsupported_stack_questions,
+} from './stack_bundles.js';
 
-/** Map `state.stack.frontend` → agent-directive skill name. */
+/** Map `state.stack.frontend` → agent-directive verb. */
 export const STACK_DIRECTIVES: Record<string, string> = {
     'blade-livewire-flux': 'ui-design-review-blade-livewire-flux',
+    'blade-livewire': 'ui-design-review-blade-livewire',
+    filament: 'ui-design-review-filament',
     'react-shadcn': 'ui-design-review-react-shadcn',
+    react: 'ui-design-review-react',
     vue: 'ui-design-review-vue',
     plain: 'ui-design-review-plain',
+    // Present so the `keys == KNOWN_STACKS` invariant holds. Never emitted —
+    // the step intercepts this lane and refuses instead of dispatching.
+    unknown: 'ui-design-review-unsupported',
 };
 
 /** Fallback directive when `state.stack` is missing or malformed. */
@@ -181,12 +192,20 @@ function _stack_label(state: DeliveryState): string {
 function _delegate_to_review_skill(state: DeliveryState): StepResult {
     const directive = _resolve_directive(state);
     const stack_label = _stack_label(state);
+    if (stack_label === UNSUPPORTED_LANE) {
+        return new StepResult({
+            outcome: Outcome.BLOCKED,
+            questions: unsupported_stack_questions('review'),
+            message: 'UI review refused: frontend framework not modelled by any lane.',
+        });
+    }
     return new StepResult({
         outcome: Outcome.BLOCKED,
         questions: [
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Reviewing rendered components ` +
                 'against the locked design brief.',
+            bundle_line(stack_label, 'review'),
             '> The review pass compares `state.ticket.ui_apply.rendered` ' +
                 'against `state.ui_design` (microcopy, states, a11y, layout) ' +
                 'and produces a structured `findings` list.',

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

@@ -0,0 +1,179 @@
+/**
+ * Verb → skill-bundle map for the stack-dispatched UI steps.
+ *
+ * The UI steps halt with `@agent-directive: ui-apply-<stack>` (and the
+ * `ui-design-review-` / `ui-polish-` equivalents). Those names are **directive
+ * verbs, not skill paths** — the same shape as `run-tests`, `create-plan`, and
+ * `apply-plan`, which likewise resolve to no skill file. Only 2 of the engine's
+ * 11 literal verbs name a real skill, so a verb is something the agent
+ * interprets, and the mapping from verb to the skills that implement it is a
+ * separate fact that has to be written down somewhere.
+ *
+ * Before this module that mapping lived only in a prose table in
+ * `docs/contracts/ui-track-flow.md`. Nothing verified it, and two of its four
+ * rows were wrong: `vue` pointed at the directive verb itself (naming no skill
+ * at all) and `plain` — which is also the fallback for every unrecognised
+ * project — pointed at `blade-ui`, a skill whose frontmatter is
+ * `packs: [laravel]` and which a non-Laravel consumer therefore does not have
+ * installed.
+ *
+ * Keeping the map here makes it checkable: `lint_ui_stack_bundles` asserts every
+ * member resolves to a real skill, and that no lane reachable without the
+ * `laravel` pack names a `laravel`-only skill. A CI check in this repo cannot
+ * see a consumer's installed pack combination, so the second assertion is the
+ * part that actually prevents the `plain → blade-ui` class of defect.
+ */
+
+/** Skills that implement a lane, in the order the agent should load them. */
+export interface StackBundle {
+    /** Skills that build / fix UI for this lane (`apply`, `polish`). */
+    readonly build: ReadonlyArray<string>;
+    /** Skills that review UI for this lane (`review`). */
+    readonly review: ReadonlyArray<string>;
+    /**
+     * True when every skill above ships outside the framework packs, i.e. the
+     * lane is safe as a fallback for a consumer whose packs we cannot predict.
+     * Only lanes marked `pack_agnostic` may be used as `DEFAULT_*`.
+     */
+    readonly pack_agnostic: boolean;
+}
+
+/**
+ * The pack-agnostic pair. Both live in `engineering-base`, so they are present
+ * in every install; both self-describe as stack-neutral
+ * (`ui-component-architect`: "the same lens applies to Blade, Livewire, React,
+ * or Vue trees"; `tailwind-engineer`: "the **how** for any Tailwind-stack
+ * screen"). This is the honest floor for a lane with no framework-specific
+ * executor — not a claim that the lane is fully served.
+ */
+const GENERIC_BUILD: ReadonlyArray<string> = ['ui-component-architect', 'tailwind-engineer'];
+
+/** `design-review` is stack-neutral and ships in `engineering-base`. */
+const GENERIC_REVIEW: ReadonlyArray<string> = ['design-review'];
+
+/**
+ * Lane → bundle. Keys mirror `KNOWN_STACKS`; the dispatch tables in
+ * `apply` / `review` / `polish` keep their own verb strings (a tested public
+ * contract) and consume this map only to name the skills in the halt body.
+ */
+export const STACK_BUNDLES: Readonly<Record<string, StackBundle>> = {
+    'blade-livewire-flux': {
+        build: ['flux', 'livewire', 'blade-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    // Livewire without Flux — the common Laravel frontend. Previously fell
+    // into `plain` because detection required Livewire AND Flux.
+    'blade-livewire': {
+        build: ['livewire', 'blade-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    // Filament is Livewire + Blade + Tailwind under the hood; the same
+    // executors apply. A Filament-specific skill is gated on evidence that
+    // these produce unusable output for it, not assumed.
+    filament: {
+        build: ['livewire', 'blade-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    'react-shadcn': {
+        build: ['react-shadcn-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    // React without Radix/shadcn. `react-shadcn-ui` still carries the React
+    // component idiom; the shadcn-specific parts simply do not apply.
+    react: {
+        build: ['react-shadcn-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    // No Vue executor exists. The previous prose row pointed at the directive
+    // verb itself, which named nothing; the generic pair is a smaller lie and a
+    // stated one — the halt body says the lane has no Vue-specific skill.
+    vue: {
+        build: GENERIC_BUILD,
+        review: GENERIC_REVIEW,
+        pack_agnostic: true,
+    },
+    plain: {
+        build: GENERIC_BUILD,
+        review: GENERIC_REVIEW,
+        pack_agnostic: true,
+    },
+};
+
+/**
+ * Lanes served by the stack-neutral pair rather than a framework executor.
+ *
+ * `plain` and `vue` share the bundle but not the meaning, and the halt body has
+ * to say which it is. For `plain` the pair IS the right answer — there is no
+ * framework to be idiomatic about. For `vue` it is a gap: a Vue project has a
+ * definite idiom and the package has no executor for it, so the result must not
+ * read as Vue support.
+ */
+export const GENERIC_LANES: ReadonlySet<string> = new Set(['vue', 'plain']);
+
+/** Lanes where the stack-neutral pair is the correct answer, not a shortfall. */
+const NATIVELY_GENERIC_LANES: ReadonlySet<string> = new Set(['plain']);
+
+/**
+ * The label detection returns for a framework it recognises but does not
+ * model. Mirrors `stack/detect.ts::UNSUPPORTED_STACK`; duplicated as a literal
+ * because this module is import-free by design (the detector is a leaf module
+ * the directives must not depend on).
+ */
+export const UNSUPPORTED_LANE = 'unknown';
+
+/** Return the bundle for `stack`, or the `plain` bundle when unmapped. */
+export function bundle_for(stack: string): StackBundle {
+    return STACK_BUNDLES[stack] ?? (STACK_BUNDLES['plain'] as StackBundle);
+}
+
+/**
+ * Questions for the refusal halt on an unmodelled framework.
+ *
+ * Not a directive — there is nothing honest to dispatch to. The agent names
+ * the actual markers from the manifest (it has filesystem access; the engine
+ * deliberately does not carry them on `StackResult`), and the user chooses
+ * between the stack-neutral floor and stopping.
+ */
+export function unsupported_stack_questions(step: string): string[] {
+    return [
+        '> Detection found a frontend framework this package does not model, ' +
+            `so there is no \`${step}\` lane for it.`,
+        '> Name the markers you see in `composer.json` / `package.json` so the ' +
+            'choice below is made on the real stack, not on a guess.',
+        '> 1. Continue on the stack-neutral floor — `ui-component-architect` + ' +
+            '`tailwind-engineer`. Output will not be idiomatic for this ' +
+            'framework; say so in the result.',
+        '> 2. Abort — drop this UI request and add a lane first ' +
+            '(`docs/contracts/ui-stack-extension.md`).',
+    ];
+}
+
+/**
+ * Render the "load these skills" line for a dispatch halt.
+ *
+ * The engine cannot load a skill itself; naming the bundle is what stops the
+ * agent from resolving an unresolvable verb by guessing. A lane with no
+ * framework-specific executor says that outright rather than presenting the
+ * generic pair as if it were stack support.
+ */
+export function bundle_line(stack: string, role: 'build' | 'review'): string {
+    const bundle = bundle_for(stack);
+    const skills = role === 'review' ? bundle.review : bundle.build;
+    const rendered = skills.map((name) => `\`${name}\``).join(' + ');
+    if (NATIVELY_GENERIC_LANES.has(stack)) {
+        return `> Skills: ${rendered} — stack-neutral, which is what \`${stack}\` means.`;
+    }
+    if (GENERIC_LANES.has(stack)) {
+        return (
+            `> Skills: ${rendered} — there is no \`${stack}\`-specific executor, ` +
+            'so this is the stack-neutral floor, not idiomatic ' +
+            `\`${stack}\`. Say so in the result.`
+        );
+    }
+    return `> Skills: ${rendered}.`;
+}

package/src/agent-src/templates/scripts/work_engine/stack/detect.ts

@@ -17,17 +17,35 @@
  *
  * 1. `composer.json` lists `livewire/livewire` AND `livewire/flux` →
  *    `blade-livewire-flux`
- * 2. `package.json` lists `react` AND any of `@radix-ui/*`,
+ * 2. `composer.json` lists `filament/filament` → `filament` (before bare
+ *    Livewire: Filament pulls Livewire in transitively)
+ * 3. `composer.json` lists `livewire/livewire` → `blade-livewire`
+ * 4. `package.json` lists `react` AND any of `@radix-ui/*`,
  *    `shadcn-ui` or has a `components.json` (the shadcn marker file)
  *    → `react-shadcn`
- * 3. `package.json` lists `vue` (any major) → `vue`
- * 4. Otherwise → `plain`
+ * 5. `package.json` lists `react` → `react`
+ * 6. `package.json` lists `vue` (any major) → `vue`
+ * 7. Either manifest names a recognised-but-unmodelled framework
+ *    (Svelte, Angular, Nuxt, Astro, Solid, Qwik, Inertia) → `unknown`
+ * 8. Otherwise → `plain`
+ *
+ * Rules 3, 5 and 7 exist because the earlier table sent three common
+ * shapes into `plain`: Laravel+Livewire without Flux failed rule 1's `&&`,
+ * React without Radix failed rule 4, and every unmodelled framework was
+ * indistinguishable from a genuinely plain project. `plain` now means "no
+ * frontend markers"; `unknown` means "a framework we do not model", and
+ * dispatch refuses on it rather than handing over generic tooling silently.
  *
  * Detection is filesystem-cheap: at most three small JSON reads per
  * project root. Errors (missing file, malformed JSON, missing `require`
  * section) downgrade to `plain` rather than raising — a wrong stack
  * label is recoverable (audit catches it, user can override), but a
  * crash mid-dispatch is not.
+ *
+ * Root manifests only, by design: a monorepo caller passes the workspace
+ * root that carries the manifest it cares about. Note the consequence —
+ * a caller that always passes the repository root gets `plain` for a
+ * monorepo, so the caller owns scope selection, not the detector.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -43,18 +61,59 @@ import * as path from 'node:path';
  */
 export const KNOWN_STACKS: ReadonlySet<string> = new Set([
     'blade-livewire-flux',
+    'blade-livewire',
+    'filament',
     'react-shadcn',
+    'react',
     'vue',
     'plain',
+    'unknown',
 ]);
 
-/** Fallback when no manifest signal matches. */
+/**
+ * Label for a project with no frontend markers at all.
+ *
+ * `plain` used to carry two meanings — "genuinely a plain HTML/Tailwind
+ * project" and "detection failed, here is generic tooling anyway" — which made
+ * a loud failure impossible without punishing real plain projects. The second
+ * meaning is now {@link UNSUPPORTED_STACK}.
+ */
 export const DEFAULT_STACK = 'plain';
 
+/**
+ * Label for a project whose frontend IS recognisable but is not modelled.
+ *
+ * Dispatch refuses on this label instead of degrading to generic tooling: a
+ * Filament or Svelte project silently routed to a Tailwind-only bundle is
+ * user-hostile precisely because the output looks like it worked.
+ */
+export const UNSUPPORTED_STACK = 'unknown';
+
 const _SHADCN_RADIX_PREFIX = '@radix-ui/';
 const _SHADCN_PACKAGE_NAMES: ReadonlySet<string> = new Set(['shadcn-ui', 'shadcn']);
 const _FLUX_PACKAGE = 'livewire/flux';
 const _LIVEWIRE_PACKAGE = 'livewire/livewire';
+const _FILAMENT_PACKAGE = 'filament/filament';
+
+/**
+ * Frontend markers this package recognises but does not model.
+ *
+ * One of these present means detection **succeeded** at recognising a
+ * framework and the package simply has no lane for it — the `unknown` case,
+ * not the `plain` case. Keep the list short and factual; a marker leaves it
+ * only when a real lane exists.
+ */
+const _UNMODELLED_MARKERS: ReadonlyArray<string> = [
+    'svelte',
+    '@angular/core',
+    'nuxt',
+    'astro',
+    'solid-js',
+    '@builder.io/qwik',
+    '@inertiajs/vue3',
+    '@inertiajs/react',
+    'inertiajs/inertia-laravel',
+];
 
 /**
  * A heterogeneous JSON object, mirroring a Python `dict[str, object]`.
@@ -109,14 +168,51 @@ export function detect_stack(project_root: string): StackResult {
         return new StackResult({ frontend: 'blade-livewire-flux', mtime });
     }
 
+    // Filament before bare Livewire: it pulls Livewire in transitively, so a
+    // Filament project would otherwise be labelled by its dependency rather
+    // than by the framework the developer actually works in.
+    if (_has_package(composer, ['require', 'require-dev'], _FILAMENT_PACKAGE)) {
+        return new StackResult({ frontend: 'filament', mtime });
+    }
+
+    // Livewire WITHOUT Flux is the common Laravel frontend, not an unknown
+    // one. It used to fail the `&&` above and land in `plain`.
+    if (_has_package(composer, ['require', 'require-dev'], _LIVEWIRE_PACKAGE)) {
+        return new StackResult({ frontend: 'blade-livewire', mtime });
+    }
+
     if (_is_react_shadcn(pkg, components_json)) {
         return new StackResult({ frontend: 'react-shadcn', mtime });
     }
 
+    // React without Radix/shadcn is a served stack, not an unknown one.
+    if (_has_package(pkg, _PKG_DEP_KEYS, 'react')) {
+        return new StackResult({ frontend: 'react', mtime });
+    }
+
     if (_has_vue(pkg)) {
         return new StackResult({ frontend: 'vue', mtime });
     }
 
+    // A recognised-but-unmodelled framework is NOT `plain`. Refusing here is
+    // the point: `plain` means "no frontend markers", and conflating the two
+    // is what let a Svelte or Inertia project receive Tailwind-only tooling
+    // and no warning.
+    if (_has_unmodelled_marker(composer, pkg)) {
+        return new StackResult({ frontend: UNSUPPORTED_STACK, mtime });
+    }
+
+    // Monorepo: no manifest at the root, but one sits in a workspace directory.
+    // That is a wrong-scope call, not a plain project — the caller owns scope
+    // selection, so say so instead of labelling the whole repo `plain` and
+    // dispatching generic tooling at it.
+    //
+    // A repo with no manifest ANYWHERE stays `plain`: that is greenfield, and
+    // the scaffold path depends on it.
+    if (mtime === 0.0 && _has_nested_manifest(project_root)) {
+        return new StackResult({ frontend: UNSUPPORTED_STACK, mtime });
+    }
+
     return new StackResult({ frontend: DEFAULT_STACK, mtime });
 }
 
@@ -185,6 +281,61 @@ function _all_dependencies(manifest: Manifest, ...keys: string[]): Manifest {
     return merged;
 }
 
+/** Dependency sections a `package.json` can carry. */
+const _PKG_DEP_KEYS: ReadonlyArray<string> = [
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies',
+];
+
+/** True when `name` appears in any of `manifest`'s named dependency sections. */
+function _has_package(
+    manifest: Manifest,
+    sections: ReadonlyArray<string>,
+    name: string,
+): boolean {
+    return name in _all_dependencies(manifest, ...sections);
+}
+
+/** Workspace directories a monorepo conventionally puts its packages in. */
+const _WORKSPACE_DIRS: ReadonlyArray<string> = ['packages', 'apps', 'services', 'libs'];
+
+/**
+ * True when no root manifest exists but a workspace directory holds one.
+ *
+ * Deliberately shallow — one `readdir` per conventional workspace directory,
+ * one `stat` per child. It answers "was this called at the wrong scope?", not
+ * "where is the real project", which stays the caller's job.
+ */
+function _has_nested_manifest(project_root: string): boolean {
+    for (const dir of _WORKSPACE_DIRS) {
+        const base = path.join(project_root, dir);
+        let entries: string[];
+        try {
+            entries = fs.readdirSync(base);
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (
+                _is_file(path.join(base, entry, 'composer.json')) ||
+                _is_file(path.join(base, entry, 'package.json'))
+            ) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+/** True when either manifest names a framework we recognise but do not model. */
+function _has_unmodelled_marker(composer: Manifest, pkg: Manifest): boolean {
+    const composer_deps = _all_dependencies(composer, 'require', 'require-dev');
+    const pkg_deps = _all_dependencies(pkg, ..._PKG_DEP_KEYS);
+    return _UNMODELLED_MARKERS.some((marker) => marker in composer_deps || marker in pkg_deps);
+}
+
 function _is_blade_livewire_flux(composer: Manifest): boolean {
     const deps = _all_dependencies(composer, 'require', 'require-dev');
     return _LIVEWIRE_PACKAGE in deps && _FLUX_PACKAGE in deps;

package/src/agent-src/templates/scripts/work_engine/state.ts

@@ -629,10 +629,12 @@ function _validate_app_spec(app_spec: JsonValue): void {
  * agent-directive that populates it. An empty dict is the in-progress
  * shape after the skill returns but before the brief lands; the gate
  * treats it the same as `null`. Once populated, `design_confirmed`
- * (when present) must be a bool. Other keys (`layout`, `components`,
- * `states`, `microcopy`, `a11y`, `reused_from_audit`) are
- * validated by the design handler against the skill contract — the
- * schema only enforces shape, not content.
+ * (when present) must be a bool, and `states` (when present and not
+ * `null`) must be an object — the design gate's per-state loop is
+ * object-guarded, so a string or list would bypass all five checks.
+ * The remaining keys (`layout`, `components`, `microcopy`, `a11y`,
+ * `reused_from_audit`) are validated by the design handler against the
+ * skill contract — the schema only enforces shape, not content.
  */
 function _validate_ui_design(ui_design: JsonValue): void {
     if (ui_design === null) {
@@ -652,6 +654,21 @@ function _validate_ui_design(ui_design: JsonValue): void {
             'state.ui_design.design_confirmed must be a boolean when present',
         );
     }
+    // `states` is shape-checked here, not left to the handler. The design
+    // gate's per-state loop was guarded on "is this an object", so a string or
+    // list silently skipped all five required-state checks — the gate passed
+    // while covering no state at all. Rejecting the wrong shape at the schema
+    // boundary means the loop can no longer be bypassed by type.
+    if (
+        'states' in ui_design &&
+        ui_design['states'] !== null &&
+        !_isDict(ui_design['states'])
+    ) {
+        throw new SchemaError(
+            'state.ui_design.states must be a JSON object (one key per ' +
+                `required state) or null; got ${pyTypeName(ui_design['states'])}`,
+        );
+    }
 }
 
 /**

package/src/config/discovery/packs.yml

@@ -62,6 +62,11 @@
   description: Laravel framework patterns; depends on PHP at the artefact level.
   workspaces: [engineering]
   requires: [php, engineering-base]
+  # The design layer is a companion, not a dependency: this pack ships UI
+  # executors (blade-ui, flux, livewire) whose grounded selection lives in
+  # frontend-design, but a Laravel API-only project needs none of it. Advisory
+  # so the wizard offers it; `requires` would force the weight on every install.
+  suggests: [frontend-design]
   cluster: php
   trust_level_default: professional
   domain: engineering
@@ -98,6 +103,8 @@
   description: React framework patterns.
   workspaces: [engineering]
   requires: [javascript, engineering-base]
+  # Companion, not dependency — see the note on `laravel`.
+  suggests: [frontend-design]
   cluster: typescript
   trust_level_default: professional
   domain: engineering

package/src/config/evaluator-budgets.json

@@ -8,7 +8,7 @@
         "unpacked_size_mb": {
             "max": 28,
             "last_measured": 26.05,
-            "method": "npm pack --json → dist.unpackedSize / 1e6 — includes the Phase-1 precompiled bundles (dist/hooks/dispatch.js + dist/mcp/server.mjs, ~2.1 MB) that bought the 23x hook-latency win and the tsx removal"
+            "method": "npm pack --json → dist.unpackedSize / 1e6 — includes the Phase-1 precompiled bundles (dist/hooks/dispatch.js + dist/mcp/server.mjs, ~2.1 MB) that bought the 23x hook-latency win and the tsx removal, plus dist/cli-delegate/ (~1.40 MB, ADR-204) which finished that removal for the consumer command surface. This gate is the ONLY size trip-wire on those bundles by design: a dedicated per-bundle budget key would need its own measurement wired into evaluator_umbrella.sh, and an unwired key fails check_evaluator_budgets with 'no measurement supplied' instead of guarding anything. ADR-204 projected 27.45 against max 28 without packing — the next real measurement here is the confirming one, and headroom is thin"
         },
         "node_modules_mb": {
             "max": 140,

package/src/config/pack-size-budget.json

@@ -0,0 +1,27 @@
+{
+    "_comment": "Payload budget for the published npm tarball (road-to-zero-ceremony-install Phase 4). MEASURED, NEVER INVENTED — the numbers below come from `npm pack --dry-run --json --ignore-scripts` on the tracked tree at 9.9.0 (2026-07-31). Two metrics, both genuinely ungated before this file: COMPRESSED tarball size, and PER-SKILL share of the skills subtree. The UNPACKED size is deliberately absent — it is already owned by src/config/evaluator-budgets.json (unpacked_size_mb), and a second number for one lever is how three conflicting figures start circulating.",
+    "schema_version": 1,
+    "owner": "maintainer",
+    "review_by": "2027-07-31",
+    "regression_pct": 10,
+    "measurement_conditions": "npm pack --dry-run --json --ignore-scripts, run at the repo root on a clean checkout. `--ignore-scripts` means NO build runs, so dist/cli, dist/ui, dist/mcp and dist/hooks are absent and the figure covers only the TRACKED payload (src/scripts/, dist/agent-src/, dist/install/, docs/guidelines/, templates). That is deliberate: this gate is always-on for every PR, and the tracked content tree is exactly the surface that grows by accretion. The built artifact is ~5.4 MB larger and is gated separately, at release time, by evaluator-budgets.unpacked_size_mb.",
+    "budgets": {
+        "packed_size_mb": {
+            "max": 6.4,
+            "last_measured": 5.903,
+            "method": "npm pack --dry-run --json --ignore-scripts → dist.size / 1e6 (the compressed tarball a consumer actually downloads)"
+        }
+    },
+    "per_skill_share": {
+        "max_pct": 5.0,
+        "basis": "a single skill's share of the total bytes under dist/agent-src/skills/ in the tarball",
+        "rationale": "Measured 2026-07-31: the largest non-excepted skill is corpus-grounding at 2.33%, so a 5% cap is green with better than 2x headroom and red for any skill that doubles. It is a falsifiable gate, not a ritual one.",
+        "exceptions": {
+            "design-intelligence": {
+                "max_pct": 23.0,
+                "measured_pct": 22.63,
+                "reason": "771 KB of BM25 corpus (27 CSVs + 16 design-language prose specs + manifest.json) consumed at runtime by corpus-grounding's retriever, and referenced by 6 further skills. Moving it behind a lazy fetch would add a network dependency to a skill that works offline today — the same trade-off ADR-061 §8 already REJECTED for a 745 KB font index. The exception is visible debt, not an endorsement: raising max_pct requires a reason in the same commit."
+            }
+        }
+    }
+}

package/src/install/emit_host_rules_cli.ts

@@ -21,7 +21,8 @@
  *     the Phase-1b rule filter, so scoped installs get scoped host files
  *     for free;
  *   - re-using the exported emitters keeps consumer output byte-identical
- *     to the maintainer projection (Pipeline B never drifts from A).
+ *     to the maintainer projection (the consumer install never drifts from
+ *     Pipeline A, the source projection into `dist/agent-src/`).
  * The trade-off (node required at install time) matches the rule-scope
  * resolver: no node → install.sh keeps its legacy fallback surfaces.
  *

package/src/install/rule_scope.ts

@@ -1,7 +1,11 @@
 /**
- * Install-time rule scoping — Pipeline B of consumer-scoped rule projection
+ * Install-time rule scoping for the consumer install
  * (road-to-request-scoped-rule-load Phase 1b).
  *
+ * Naming: this is the CONSUMER INSTALL path, not `docs/architecture.md`'s
+ * Pipeline B (which is the `.augment/` projection). Earlier drafts called it
+ * "Pipeline B" and collided with that name; use "the consumer install" here.
+ *
  * The projection filter (`rule_in_scope`, condense.ts) covered only the
  * maintainer projection; the consumer install pipeline shipped rules
  * unfiltered (dead `EXCLUDE_RULES` in install.sh; no exclude at all on the

package/src/install/toolDetection.ts

@@ -71,6 +71,44 @@ export function knownToolIds(): readonly string[] {
     return Object.keys(TOOL_SIGNALS);
 }
 
+/**
+ * Executable names declared for `id` on `$PATH`, in table order. Empty for
+ * tools detected only by a config dir / app bundle (and for the two
+ * signal-less ids). Exposed so callers that need the resolved *path* (not
+ * just a boolean) can reuse this table instead of restating the binary names.
+ */
+export function toolBinaries(id: string): readonly string[] {
+    return TOOL_SIGNALS[id]?.bins ?? [];
+}
+
+/**
+ * First declared binary for `id` that resolves on `$PATH`, or `null`. This is
+ * the path-returning twin of `detectInstalledTools`, which reports presence as
+ * a boolean across all three signal kinds — a tool can be "installed" (config
+ * dir present) while this returns `null` (no executable on `$PATH`).
+ */
+export function resolveToolBinary(id: string, pathEnv?: string): string | null {
+    const env = pathEnv ?? process.env['PATH'] ?? '';
+    for (const bin of toolBinaries(id)) {
+        const resolved = resolveBinaryPath(bin, env);
+        if (resolved !== null) return resolved;
+    }
+    return null;
+}
+
+/** Absolute path of `name` on `pathEnv`, or `null`. Mirrors `binOnPath`'s probe order. */
+function resolveBinaryPath(name: string, pathEnv: string): string | null {
+    if (pathEnv.length === 0) return null;
+    for (const dir of pathEnv.split(delimiter)) {
+        if (dir.length === 0) continue;
+        for (const candidate of [name, `${name}.exe`, `${name}.cmd`]) {
+            const full = join(dir, candidate);
+            if (existsSync(full)) return full;
+        }
+    }
+    return null;
+}
+
 /**
  * Is an executable named `name` resolvable on `$PATH`? Exported for one-off
  * presence checks (e.g. `rtk` on the Editor-and-tooling step). Defaults to
@@ -81,14 +119,7 @@ export function isBinaryOnPath(name: string, pathEnv?: string): boolean {
 }
 
 function binOnPath(name: string, pathEnv: string): boolean {
-    if (pathEnv.length === 0) return false;
-    for (const dir of pathEnv.split(delimiter)) {
-        if (dir.length === 0) continue;
-        if (existsSync(join(dir, name))) return true;
-        // Windows-style executables.
-        if (existsSync(join(dir, `${name}.exe`)) || existsSync(join(dir, `${name}.cmd`))) return true;
-    }
-    return false;
+    return resolveBinaryPath(name, pathEnv) !== null;
 }
 
 function isToolInstalled(signal: ToolSignal, home: string, pathEnv: string): boolean {

package/src/install/wizard-plan.ts

@@ -193,8 +193,8 @@ export function expandWizardSources(inputs: WizardExpandInputs): PlanSource[] {
             const srcDir = join(packageRoot, srcRel);
             const destDir = destSub.length === 0 ? destRoot : join(destRoot, destSub);
             // Rule sources get the install-time scoping filter — the same
-            // predicate the projection path uses (Phase 1b: Pipeline B may
-            // never drift from Pipeline A).
+            // predicate the projection path uses (Phase 1b: the consumer
+            // install may never drift from Pipeline A, the source projection).
             const isRuleSource = srcRel === 'dist/agent-src/rules';
             out.push({
                 toolId,

package/src/scripts/_cli/cmd_conformance.ts

@@ -37,6 +37,7 @@ import * as installed_tools from '../_lib/installed_tools.js';
 import { atomicAppendLine } from '../../install/atomic.js';
 import { readRecentEntries } from '../../install/txlog.js';
 import { detectToolPresence } from '../../install/detect.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 import {
     _classify,
     _collect_manifest_entries,
@@ -56,7 +57,7 @@ type Dict = Record<string, unknown>;
 const _HERE = fileURLToPath(import.meta.url);
 
 /** Package root — two levels above `src/scripts/_cli/`. */
-export const PACKAGE_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
+export const PACKAGE_ROOT = resolvePackageRoot(import.meta.url);
 
 /** Ordered registry of conformance check identifiers. */
 export const CONFORMANCE_CHECK_IDS = [