@event4u/agent-config 9.9.0 → 9.11.0

package/docs/guidelines/agent-infra/api-cost-levers.md

@@ -109,18 +109,69 @@ different model.
 
 ## Claude Code note
 
-In Claude Code, prompt caching is automatic — resending the same context prefix
-is cheap, so keeping a stable prefix pays off without any explicit
-`cache_control`. The session-level hygiene levers are `/clear` and `/compact` to
-shed accumulated context, plus subagent delegation for verbose output so it
-never lands in the main context window.
+In Claude Code, prompt caching is automatic for the **main loop** — resending
+the same context prefix is cheap, so keeping a stable prefix pays off without
+any explicit `cache_control`. The session-level hygiene levers are `/clear`
+and `/compact` to shed accumulated context, plus subagent delegation for
+verbose output so it never lands in the main context window.
+
+**Subagents and forks pay a different cache economy — verified against host
+version 2.1.220 (2026-07-30), re-check on drift:**
+
+- A **named subagent** starts its own conversation with its own system
+  prompt and tool set. It builds its own cache from scratch, so its **first
+  call has no cache hit** — the entire per-spawn preamble (rules, tools,
+  dispatch prompt) is a cold write. Subagents use the **five-minute TTL**
+  even on a subscription; there is no per-agent setting to change that (see
+  `## Known upstream costs` below).
+- A **fork** inherits the parent's system prompt, tools, and conversation
+  history exactly, so its first request **reads the parent's cache** instead
+  of writing a fresh one — the only documented mechanism that shares a cache
+  across a dispatch boundary. Forking forces background mode, which changes
+  the tool set and therefore invalidates the very prefix that motivated the
+  fork; weigh that cost before reaching for it — see the fork-vs-subagent
+  ordering rule in See also.
+- Either way, the **cold-start preamble is re-written on every spawn** — the
+  always-loaded rule set, the tool definitions, and the dispatch prompt are
+  not shared across separate subagent instances. Fan-out (many subagents
+  from one parent) multiplies this cost by cohort size; see
+  `## Known upstream costs` below for the fan-out re-prefill issue this
+  package cannot fix.
+
+## Known upstream costs
+
+Host-controlled behaviour this package has confirmed but cannot change at
+any layer. Each entry carries the host version observed and the command to
+re-verify it — a stale entry degrades into a dated observation, never a
+false promise, when Anthropic changes the behaviour underneath it.
+
+| Cost | Observed on | Re-verify |
+|---|---|---|
+| Fan-out (`do-in-parallel`-shaped dispatch) re-prefills the parent-accumulated context **per child** — the waste scales linearly with fan-out width, worst exactly where fan-out is most valuable (anthropics/claude-code#81389, open). No fix at any layer. | Claude Code 2.1.220, 2026-07-30 | `claude --version`; re-check the linked issue for a status change |
+| Host-dispatched subagents are pinned to the **five-minute** cache TTL regardless of subscription tier or any environment variable; `ENABLE_PROMPT_CACHING_1H` does not apply to them. | Claude Code 2.1.220, 2026-07-30 | `claude --version`; re-check the official caching docs for a subagent-TTL setting |
+
+Neither entry implies a package-side fix exists or is planned — both are
+request-construction facts inside the host binary, outside this package's
+reach. This package's own scope is measurement and payload size (what it
+authors), never subagent request construction (what the host authors).
 
 ## See also
 
+- [`cache-economy-refusals`](../../../agents/settings/contexts/cache-economy-refusals.md) —
+  the measured cache figures behind the Claude Code note above, plus the
+  refusals (no interception proxy, no blanket 1h TTL, no cache-hit auto-tuning)
+  recorded so they are not rebuilt.
+
 - [`model-recommendation.md`](model-recommendation.md) — tier routing (the
   capability band behind lever 3).
 - [`size-and-scope.md`](size-and-scope.md) — token discipline for the artifacts
   that become the cached prefix.
+- [`subagent-orchestration/prompts/README.md`](../../../src/skills/subagent-orchestration/prompts/README.md)
+  § Prompt-cache discipline — sibling-uniformity rules and the
+  fork-vs-subagent dispatch ordering that follow from this cache economy.
+- [`docs/contracts/ai-council-config.md`](../../contracts/ai-council-config.md)
+  § `prompt_cache.ttl` — the one surface where this package DOES control a
+  cache-control TTL (the council's own Anthropic calls, never host subagents).
 - The Claude Code `claude-api` plugin skill (external, not vendored here) — the
   authoritative, versioned API reference these figures derive from; re-check it
   when Anthropic pricing or the caching/batch surface changes.

package/docs/guidelines/agent-infra/simplicity-and-goal-demos.md

@@ -1,3 +1,13 @@
+---
+demo_for: minimal-safe-diff, think-before-action
+layer: pattern-memory
+prose_delta:
+  rule_chars_before: 5927
+  rule_chars_after: 6903
+  measured_at: lint-examples-shape-conformance-pass
+  note: "Counts are of THIS demo file, measured with wc -c before and after the pass. The delta is frontmatter plus the Demo / Wrong shape / Right shape / Failure mode / Why it works headings required by lint_examples — no prose was migrated out of a rule and none was removed; every code block is byte-identical."
+---
+
 # Simplicity and Goal Discipline — wrong/right demos
 
 Recognition surface for [`minimal-safe-diff § Anti-over-engineering`](../../src/rules/minimal-safe-diff.md)
@@ -7,11 +17,13 @@ execution clause in `think-before-action`. Per council convergence
 the violation cannot recognize it, no matter how crisp the checklist question.
 Match your diff against the *right* column before presenting.
 
-## 1. Over-abstraction vs. one function
+## Demo 1 — Over-abstraction vs. one function
 
 **Ask:** "Add a function to calculate a percentage discount."
 
-**Wrong — Strategy pattern for a single caller (PHP):**
+### Wrong shape
+
+Strategy pattern for a single caller (PHP):
 
 ```php
 interface DiscountStrategy { public function calculate(float $amount): float; }
@@ -21,7 +33,13 @@ final readonly class DiscountConfig { /* strategy, minPurchase, maxDiscount */ }
 final class DiscountCalculator { /* 30+ lines of orchestration */ }
 ```
 
-**Right — one function until the second discount type is real:**
+**Failure mode:** the wrong version is not "bad code" — it is *premature*
+code: harder to read, more surface to test, and speculative until the
+requirement exists.
+
+### Right shape
+
+One function until the second discount type is real:
 
 ```php
 function calculateDiscount(float $amount, float $percent): float
@@ -30,17 +48,19 @@ function calculateDiscount(float $amount, float $percent): float
 }
 ```
 
-**Why:** No second caller, no second strategy → no abstraction. When the
+### Why it works
+
+No second caller, no second strategy → no abstraction. When the
 second type genuinely arrives, refactor then (`prefer-enums-over-literals` /
-Strategy sniff test governs that moment). The wrong version is not "bad
-code" — it is *premature* code: harder to read, more surface to test, and
-speculative until the requirement exists.
+Strategy sniff test governs that moment).
 
-## 2. Speculative features vs. just-what-was-asked
+## Demo 2 — Speculative features vs. just-what-was-asked
 
 **Ask:** "Save user preferences to the database."
 
-**Wrong — options nobody requested (TypeScript):**
+### Wrong shape
+
+Options nobody requested (TypeScript):
 
 ```ts
 class PreferenceManager {
@@ -52,7 +72,13 @@ class PreferenceManager {
 }
 ```
 
-**Right — the ask, nothing else:**
+**Failure mode:** every optional parameter with one call site, every
+"flexibility" flag, and every handler for a scenario that cannot occur is
+speculative complexity.
+
+### Right shape
+
+The ask, nothing else:
 
 ```ts
 async function savePreferences(db: Db, userId: number, prefs: Prefs) {
@@ -61,66 +87,94 @@ async function savePreferences(db: Db, userId: number, prefs: Prefs) {
 }
 ```
 
-**Why:** Every optional parameter with one call site, every "flexibility"
-flag, and every handler for a scenario that cannot occur is speculative
-complexity. Add caching when performance data demands it, validation when bad
+### Why it works
+
+Add caching when performance data demands it, validation when bad
 data appears, merging when the requirement lands.
 
-## 3. Drive-by refactor vs. surgical diff
+## Demo 3 — Drive-by refactor vs. surgical diff
 
 **Ask:** "Fix the bug where an empty email crashes the validator."
 
-**Wrong:** the fix PLUS improved email regex, new username length checks,
+### Wrong shape
+
+The fix PLUS improved email regex, new username length checks,
 rewritten comments, and a fresh docstring — four changes, one was asked.
 
-**Right:** only the lines that make the empty-email case safe change; every
+**Failure mode:** the "improvements" belong in a follow-up proposed via
+`active-remediation`'s note-and-ask ladder — not smuggled into the bug fix.
+
+### Right shape
+
+Only the lines that make the empty-email case safe change; every
 other line of the function is byte-identical.
 
-**Why:** Every changed line must trace to the stated task
-(`minimal-safe-diff`). The "improvements" belong in a follow-up proposed via
-`active-remediation`'s note-and-ask ladder — not smuggled into the bug fix.
+### Why it works
 
-## 4. Style drift vs. match-existing-style
+Every changed line must trace to the stated task
+(`minimal-safe-diff`).
+
+## Demo 4 — Style drift vs. match-existing-style
 
 **Ask:** "Add logging to the upload function."
 
-**Wrong:** the diff adds logging AND flips quote style, adds type hints,
+### Wrong shape
+
+The diff adds logging AND flips quote style, adds type hints,
 reshapes the boolean return, reflows whitespace — the reviewer can no longer
 see the logging change.
 
-**Right:** logger import + three log lines, inserted in the file's existing
+**Failure mode:** a diff that reformats while changing behavior hides the
+behavior change.
+
+### Right shape
+
+Logger import + three log lines, inserted in the file's existing
 style (its quoting, its spacing, its return pattern), even where you would
 personally write it differently.
 
-**Why:** Style consistency is a repo property, not a per-diff taste decision.
-A diff that reformats while changing behavior hides the behavior change.
+### Why it works
 
-## 5. Own-orphan vs. pre-existing dead code
+Style consistency is a repo property, not a per-diff taste decision.
+
+## Demo 5 — Own-orphan vs. pre-existing dead code
 
 **Ask:** "Replace the legacy formatter call in `processA` with the new one."
 
-**Wrong (too little):** `processA` no longer calls `legacyFormat()`, but the
+### Wrong shape
+
+**Too little:** `processA` no longer calls `legacyFormat()`, but the
 now-unused import and the helper it alone referenced stay behind — the diff
 shipped its own litter.
 
-**Wrong (too much):** while in the file, the agent also deletes
+**Too much:** while in the file, the agent also deletes
 `oldHelper()`, which `processB` — untouched by this diff — still references
 in another module, or which was already orphaned *before* this task.
 
-**Right:** remove exactly the imports/variables/functions whose **last
+**Failure mode:** two directions of the same error — the diff shipped its own
+litter (too little), or it deleted code that untouched files still reference,
+or that was already orphaned before this task (too much).
+
+### Right shape
+
+Remove exactly the imports/variables/functions whose **last
 reference disappeared in a file this diff touched**; anything still
 referenced from untouched files — or orphaned before the task — is
 pre-existing debt: mention it, don't delete it.
 
-**Why:** The boundary is mechanical (grep after editing), so there is no
+### Why it works
+
+The boundary is mechanical (grep after editing), so there is no
 judgment call to rationalize — see
 [`minimal-safe-diff § Own-orphan cleanup`](../../src/rules/minimal-safe-diff.md#own-orphan-cleanup).
 
-## 6. Vague plan vs. verifiable per-step plan
+## Demo 6 — Vague plan vs. verifiable per-step plan
 
 **Ask:** "Add rate limiting to the API."
 
-**Wrong — unverifiable narration:**
+### Wrong shape
+
+Unverifiable narration:
 
 ```
 1. Review the code
@@ -129,7 +183,11 @@ judgment call to rationalize — see
 4. Test the changes
 ```
 
-**Right — every step carries its check:**
+**Failure mode:** a step without a `verify:` is an assumption.
+
+### Right shape
+
+Every step carries its check:
 
 ```
 1. In-memory limit on one endpoint → verify: 11th request in a minute → 429 (test)
@@ -137,7 +195,9 @@ judgment call to rationalize — see
 3. Shared store backend → verify: counter survives app restart; two instances share the count
 ```
 
-**Why:** A step without a `verify:` is an assumption. Strong criteria let the
+### Why it works
+
+Strong criteria let the
 loop run independently (`verify-before-complete` then has something to
 check); "make it work" guarantees clarification churn after the fact instead
 of before.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.9.0",
+    "version": "9.11.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,
@@ -34,6 +34,7 @@
         ".augment-plugin/",
         ".claude-plugin/",
         "src/config/",
+        "agents/templates/",
         "dist/",
         "docs/guidelines/",
         "docs/contracts/persona-schema.md",
@@ -65,13 +66,14 @@
         "build:install-bundle": "esbuild src/scripts/install.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/install/install.mjs --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
         "build:hooks": "esbuild src/scripts/hooks/dispatch_entry.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/hooks/dispatch.js --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_HOOKS_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\"",
         "build:mcp-bundle": "esbuild src/scripts/mcp_server/__main__.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/mcp/server.mjs --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_MCP_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\"",
+        "build:cli-delegate": "esbuild src/scripts/_cli/cmd_*.ts --bundle --splitting --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outdir=dist/cli-delegate --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
         "build:ui": "vite build",
         "tokens:build": "node tokens/build-ac.mjs && node tokens/build-as.mjs",
         "tokens:check": "node tokens/build-ac.mjs --check && node tokens/build-as.mjs --check && node tokens/check-contrast.mjs",
         "build:discovery": "./scripts-run src/scripts/build_discovery_manifest --write --strict",
         "build:mcp-manifest": "./scripts-run src/scripts/build_mcp_registry_manifest --write --strict",
         "build:mcp-catalog": "./scripts-run src/scripts/build_mcp_catalog --write --strict",
-        "build": "npm run build:cli && npm run build:install-bundle && npm run build:hooks && npm run build:mcp-bundle && npm run build:ui",
+        "build": "npm run build:cli && npm run build:install-bundle && npm run build:hooks && npm run build:mcp-bundle && npm run build:cli-delegate && npm run build:ui",
         "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.scripts.json",
         "lint:ts": "eslint 'src/**/*.ts'",
         "test:ts": "vitest run",

package/src/agent-src/templates/scripts/tier_usage_report.ts

@@ -234,7 +234,7 @@ function _within_window(ts_bucket: string, window_days: number | null): boolean
     return ms >= Date.now() - window_days * 24 * 60 * 60 * 1000;
 }
 
-type BucketKey = string; // `${tier}${command}` — composite (tier, command) key.
+type BucketKey = string; // `${tier}\0${command}` — composite (tier, command) key.
 interface RowStats {
     count: number;
     distinct_users: number;
@@ -274,7 +274,7 @@ function aggregate(log_path: string, window_days: number): AggregateResult {
         }
         kept += 1;
         const tier = Math.trunc(rec.tier);
-        const key = `${tier}${rec.command}`;
+        const key = `${tier}\0${rec.command}`;
         if (!keyMeta.has(key)) {
             keyMeta.set(key, { tier, command: rec.command });
             counts.set(key, 0);

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

@@ -17,14 +17,25 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
-import { PLACEHOLDER_PATTERNS } from './design.js';
+import { placeholder_paths } from './design.js';
+import {
+    UNSUPPORTED_LANE,
+    bundle_line,
+    unsupported_stack_questions,
+} from './stack_bundles.js';
 
 /** Map `state.stack.frontend` → agent-directive skill name. */
 export const STACK_DIRECTIVES: Record<string, string> = {
     'blade-livewire-flux': 'ui-apply-blade-livewire-flux',
+    'blade-livewire': 'ui-apply-blade-livewire',
+    filament: 'ui-apply-filament',
     'react-shadcn': 'ui-apply-react-shadcn',
+    react: 'ui-apply-react',
     vue: 'ui-apply-vue',
     plain: 'ui-apply-plain',
+    // Present so the `keys == KNOWN_STACKS` invariant holds. Never emitted —
+    // the step intercepts this lane and refuses instead of dispatching.
+    unknown: 'ui-apply-unsupported',
 };
 
 /** Fallback directive when `state.stack` is missing or malformed. */
@@ -104,47 +115,36 @@ function _resolve_directive(state: DeliveryState): string {
     return DEFAULT_DIRECTIVE;
 }
 
-/** Return paths into `envelope['rendered']` whose text matches a pattern. */
+/**
+ * Return paths into `envelope['rendered']` whose text matches a pattern.
+ *
+ * Delegates to the walker shared with `design`, so the producer-side and
+ * consumer-side gates cannot drift apart. They previously held
+ * byte-identical copies of the same array-blind recursion, which meant the
+ * contract's "defense-in-depth" framing described two layers that failed on
+ * exactly the same inputs.
+ */
 function _placeholder_violations_in_output(envelope: Record<string, Any>): string[] {
-    const rendered = envelope['rendered'];
-    if (!_isDict(rendered)) {
-        return [];
-    }
-    const violations: string[] = [];
-    _walk_rendered(rendered, '', violations);
-    return violations;
-}
-
-function _walk_rendered(node: Record<string, Any>, prefix: string, violations: string[]): void {
-    for (const key of Object.keys(node)) {
-        const value = node[key];
-        const path = prefix ? `${prefix}.${key}` : String(key);
-        if (_isDict(value)) {
-            _walk_rendered(value, path, violations);
-            continue;
-        }
-        if (typeof value !== 'string') {
-            continue;
-        }
-        const lowered = value.toLowerCase();
-        for (const pattern of PLACEHOLDER_PATTERNS) {
-            if (lowered.includes(pattern)) {
-                violations.push(path);
-                break;
-            }
-        }
-    }
+    return placeholder_paths(envelope['rendered']);
 }
 
 /** First-pass halt — emit the stack-specific apply directive. */
 function _delegate_to_stack_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('apply'),
+            message: 'UI apply refused: frontend framework not modelled by any lane.',
+        });
+    }
     return new StepResult({
         outcome: Outcome.BLOCKED,
         questions: [
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Implementing the locked design brief.`,
+            bundle_line(stack_label, 'build'),
             '> Microcopy is locked — every button label, empty-state ' +
                 'message, and validation message must come verbatim from ' +
                 '`state.ui_design.microcopy`.',

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

@@ -146,7 +146,17 @@ function _missing_required_keys(design: Record<string, Any>): string[] {
             missing.push(key);
             continue;
         }
-        if (key === 'states' && _isDict(value)) {
+        if (key === 'states') {
+            // A non-object `states` (a string, a list) used to skip the
+            // per-state loop entirely, so `states: "n/a"` satisfied the gate
+            // without covering a single state. Report every required key
+            // instead — the author gets the same actionable list either way.
+            if (!_isDict(value)) {
+                for (const state_key of REQUIRED_STATE_KEYS) {
+                    missing.push(`states.${state_key}`);
+                }
+                continue;
+            }
             for (const state_key of REQUIRED_STATE_KEYS) {
                 if (!_pyTruthy(value[state_key])) {
                     missing.push(`states.${state_key}`);
@@ -157,37 +167,74 @@ function _missing_required_keys(design: Record<string, Any>): string[] {
     return missing;
 }
 
-/** Return microcopy paths whose values match a placeholder pattern. */
+/**
+ * Return brief paths whose values match a placeholder pattern.
+ *
+ * Covers `microcopy` **and** `states`. The five required states were checked
+ * for truthiness only, so `states.error: "TBD"` satisfied the gate — the brief
+ * looked complete while covering nothing. Both slots carry strings the user
+ * signs off on, so both are held to the same bar.
+ *
+ * An explicit `"n/a"` stays legitimate: a static landing page genuinely has no
+ * error or disabled state, and *declaring* that is the opposite of inventing
+ * filler. That is why the gate demands all five keys rather than branching on
+ * page type — the author states the answer instead of the engine guessing which
+ * states a surface ought to have.
+ */
 function _placeholder_violations(design: Record<string, Any>): string[] {
-    const microcopy = design['microcopy'];
-    if (!_isDict(microcopy)) return [];
+    return [
+        ...placeholder_paths(design['microcopy'], 'microcopy'),
+        ...placeholder_paths(design['states'], 'states'),
+    ];
+}
+
+/**
+ * Return every path under `node` whose leaf string carries a placeholder.
+ *
+ * Traverses objects **and arrays**. The array arm is load-bearing, not
+ * defensive: a list is the natural shape for the most common microcopy
+ * (`nav_items`, `menu`, `steps`) and for a rendered file split into lines,
+ * and a walker that recursed into objects only let
+ * `{ nav_items: ["Home", "TODO: Link"] }` through both the brief lock and
+ * the rendered-output gate.
+ *
+ * Array elements are addressed `key[i]` so the halt names the exact element
+ * the author has to fix, not just the list.
+ *
+ * Shared by `design` (producer side, on `microcopy`) and `apply` (consumer
+ * side, on the rendered envelope). One implementation on purpose: the two
+ * call sites previously carried byte-identical copies of the same bug, so
+ * duplicating them bought no independence — see
+ * `docs/contracts/ui-track-flow.md` § implement → apply.
+ */
+export function placeholder_paths(node: Any, prefix = ''): string[] {
     const violations: string[] = [];
-    _walk_microcopy(microcopy, '', violations);
+    _walk_placeholders(node, prefix, violations);
     return violations;
 }
 
-function _walk_microcopy(
-    node: Record<string, Any>,
-    prefix: string,
-    violations: string[],
-): void {
-    for (const key of Object.keys(node)) {
-        const value = node[key];
-        const path = prefix ? `${prefix}.${key}` : String(key);
-        if (_isDict(value)) {
-            _walk_microcopy(value, path, violations);
-            continue;
-        }
-        if (typeof value !== 'string') {
-            continue;
-        }
-        const lowered = value.toLowerCase();
+function _walk_placeholders(node: Any, prefix: string, violations: string[]): void {
+    if (typeof node === 'string') {
+        const lowered = node.toLowerCase();
         for (const pattern of PLACEHOLDER_PATTERNS) {
             if (lowered.includes(pattern)) {
-                violations.push(path);
-                break;
+                violations.push(prefix);
+                return;
             }
         }
+        return;
+    }
+    if (Array.isArray(node)) {
+        node.forEach((value, index) => {
+            _walk_placeholders(value, `${prefix}[${index}]`, violations);
+        });
+        return;
+    }
+    if (_isDict(node)) {
+        for (const key of Object.keys(node)) {
+            const path = prefix ? `${prefix}.${key}` : String(key);
+            _walk_placeholders(node[key], path, violations);
+        }
     }
 }
 
@@ -311,15 +358,23 @@ function _halt_unconfirmed(state: DeliveryState, design: Record<string, Any>): S
     });
 }
 
-/** Count leaf string entries in `microcopy` (recursive). */
-function _count_microcopy(microcopy: Record<string, Any>): number {
-    let total = 0;
-    for (const value of Object.values(microcopy)) {
-        if (_isDict(value)) {
-            total += _count_microcopy(value);
-        } else if (typeof value === 'string') {
-            total += 1;
-        }
+/**
+ * Count leaf string entries in `microcopy` (recursive, arrays included).
+ *
+ * The count is shown in the sign-off the user confirms, so it has to agree
+ * with what the placeholder walker inspects — an object-only count reported
+ * fewer locked strings than were actually locked.
+ */
+function _count_microcopy(microcopy: Any): number {
+    if (typeof microcopy === 'string') return 1;
+    if (Array.isArray(microcopy)) {
+        return microcopy.reduce((total: number, value) => total + _count_microcopy(value), 0);
+    }
+    if (_isDict(microcopy)) {
+        return Object.values(microcopy).reduce(
+            (total: number, value) => total + _count_microcopy(value),
+            0,
+        );
     }
-    return total;
+    return 0;
 }