@event4u/agent-config 14.10.0 → 14.12.0

package/dist/agent-src/skills/terraform/SKILL.md

@@ -7,6 +7,9 @@ workspaces:
   - engineering
 packs:
   - engineering-base
+triggers:
+  - phrase: "terraform module"
+  - phrase: "terraform state"
 ---
 
 # terraform

package/dist/agent-src/skills/test-driven-development/SKILL.md

@@ -329,7 +329,7 @@ wait for their own failing tests.
   subagent cross-check) → [`test-case-discovery`](../test-case-discovery/SKILL.md)
 * Project type-checker / linter / formatter (PHPStan, ECS, Rector for PHP — tsc / eslint / prettier for TS — ruff / mypy for Python) → [`quality-tools`](../quality-tools/SKILL.md)
 * Full Pest conventions and Laravel test helpers → [`pest-testing`](../pest-testing/SKILL.md)
-* Running tests inside Docker → [`tests-execute`](../tests-execute/SKILL.md)
+* Running tests inside Docker → [`/tests:execute`](../../domains/engineering-base/tests/execute/command.md)
 * Investigating why a test is failing for non-obvious reasons →
   [`systematic-debugging`](../systematic-debugging/SKILL.md)
 

package/dist/agent-src/skills/threat-modeling/SKILL.md

@@ -54,8 +54,6 @@ Do NOT use when:
   [`security-audit`](../security-audit/SKILL.md)
 * The concern is end-to-end authorization enforcement — route to
   [`authz-review`](../authz-review/SKILL.md)
-* The concern is output/log leakage on an existing API — route to
-  [`data-exposure-review`](../data-exposure-review/SKILL.md)
 * The concern is implementing the controls once identified — route to
   [`security`](../security/SKILL.md)
 
@@ -224,7 +222,6 @@ run tests**.
   A05 Security Misconfiguration — cross-reference when naming abuse cases.
   [owasp.org/Top10/](https://owasp.org/Top10/)
 - [`authz-review`](../authz-review/SKILL.md),
-  [`data-exposure-review`](../data-exposure-review/SKILL.md),
   [`security`](../security/SKILL.md),
   [`security-audit`](../security-audit/SKILL.md) — sibling review / implementation skills.
 - Prompt-injection / agent-config defense: [`untrusted-input-defense`](../../rules/untrusted-input-defense.md),

package/dist/agent-src/skills/token-optimizer/SKILL.md

@@ -3,6 +3,9 @@ model_tier: medium
 name: token-optimizer
 description: "Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — decision tree keyed by intent citing the canonical token-saving asset."
 domain: process
+scope:
+  write: []
+  verification_reason: "an index-and-routing skill — it names other artefacts to load and writes nothing. Absence of a write is not something a command can prove."
 execution:
   type: assisted
   handler: shell

package/dist/agent-src/skills/typography-system/SKILL.md

@@ -13,6 +13,9 @@ trust:
   level: professional
 install:
   removable: true
+scope:
+  write: []
+  verification_reason: "execution declares no handler, so this skill runs nothing of its own — every write is the calling agent's, under the rules that govern it. No command can prove a scope the skill never executes."
 execution:
   type: manual
 ---

package/dist/agent-src/skills/ui-component-architect/SKILL.md

@@ -58,8 +58,24 @@ than under-splitting. Meet BOTH conditions before you extract.
 
 ### 1. Inspect prior art, state the responsibility in one sentence
 
-Review existing components in the codebase for the same
+**Read `DESIGN.md` § Owned components first** — it is the project's own inventory of what
+it already owns (component, status, story file, registry item), filled from the story files
+rather than from memory by
+[`design-system-capture`](../design-system-capture/SKILL.md). It is the cheapest possible
+prior-art check: one table, and a `deprecated` row tells you not to reach for something that
+still exists in the tree. Absent or empty → fall through to
+[`existing-ui-audit`](../existing-ui-audit/SKILL.md), which reads the codebase itself.
+
+Then review existing components in the codebase for the same
 responsibility — extend rather than rebuild when a match is found.
+
+**A new component's workshop is part of its design, on every React lane and not
+only `react-shadcn`.** When the extraction is agreed, the story set comes from
+[`storybook-workshop`](../storybook-workshop/SKILL.md) — one story per concept
+off the state-coverage matrix below, which is what makes the component
+agent-readable and its contrast floor checkable before it reaches a page. That
+skill is stack-agnostic and ships in `engineering-base`, so a plain-`react`
+project receives it exactly as a `react-shadcn` one does.
 If none exists, write the new component's purpose: *"Renders a
 labelled input with inline error and hint."* If the sentence has an
 "and" joining two unrelated jobs, the component is two components.

package/dist/agent-src/skills/upstream-contribute/SKILL.md

@@ -3,6 +3,9 @@ model_tier: inherit
 name: upstream-contribute
 description: "Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package."
 domain: process
+scope:
+  write: []
+  verification_reason: "execution.handler is internal, so this skill spawns no subprocess — writes happen through the agent's declared allowed_tools. No command can prove a scope the skill never executes."
 execution:
   type: assisted
   handler: internal

package/dist/agent-src/skills/validate-feature-fit/SKILL.md

@@ -3,6 +3,9 @@ model_tier: medium
 name: "validate-feature-fit"
 description: "Validate whether a feature request fits the existing codebase — check for duplicates, contradictions, scope creep, and architectural misfit"
 domain: quality
+scope:
+  write: []
+  verification_reason: "execution.handler is internal, so this skill spawns no subprocess — writes happen through the agent's declared allowed_tools. No command can prove a scope the skill never executes."
 execution:
   type: assisted
   handler: internal

package/dist/agent-src/skills/verify-completion-evidence/SKILL.md

@@ -66,7 +66,7 @@ mapping before running anything:
 ### 2. Run the command fresh
 
 * Run against the current working tree, not a cached summary.
-* If the project runs commands inside a container or VM (Docker, Devcontainer, Vagrant), run them there — not on the host. See [`docker`](../docker/SKILL.md) and [`tests-execute`](../tests-execute/SKILL.md).
+* If the project runs commands inside a container or VM (Docker, Devcontainer, Vagrant), run them there — not on the host. See [`docker`](../docker/SKILL.md) and [`/tests:execute`](../../domains/engineering-base/tests/execute/command.md).
 * Use targeted runs during iteration (`--filter=`, `--testNamePattern`).
   Run the full suite only in the final verification pass.
 
@@ -189,7 +189,7 @@ When reporting completion to the user:
 ## When to hand over to another skill
 
 * Exact PHP quality commands (PHPStan / Rector / ECS) → [`quality-tools`](../quality-tools/SKILL.md)
-* Running tests inside a container / VM → [`tests-execute`](../tests-execute/SKILL.md)
+* Running tests inside a container / VM → [`/tests:execute`](../../domains/engineering-base/tests/execute/command.md)
 * Writing the regression test that the gate requires →
   [`test-driven-development`](../test-driven-development/SKILL.md)
 * Diagnosing why the gate failed → [`systematic-debugging`](../systematic-debugging/SKILL.md)

package/dist/agent-src/skills/wireframe/SKILL.md

@@ -12,6 +12,9 @@ trust:
   level: professional
 install:
   removable: true
+scope:
+  write: []
+  verification_reason: "execution declares no handler, so this skill runs nothing of its own — every write is the calling agent's, under the rules that govern it. No command can prove a scope the skill never executes."
 execution:
   type: manual
 ---

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/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.12.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