@event4u/agent-config 1.14.0 → 1.16.0

package/docs/contracts/rule-interactions.yml

@@ -0,0 +1,238 @@
+# Rule-Interaction Matrix
+# -----------------------
+# Machine-readable contract for how the package's `always` rules relate
+# when more than one fires on the same turn. Linted by
+# `scripts/lint_rule_interactions.py`. Rendered diagram in
+# `docs/contracts/rule-interactions.md`.
+#
+# Schema:
+#   version: integer
+#   rules: list of rule slugs that participate in any interaction (each
+#     must exist as `.agent-src.uncompressed/rules/<slug>.md`)
+#   pairs: list of pairwise interactions
+#     - id:        kebab-case stable identifier
+#       rules:     [senior, junior] — `senior` wins on conflict
+#       relation:  overrides | narrows | defers_to | restates | gates | complements
+#       conflict:  one-line trigger that causes both to fire
+#       resolution: one paragraph — what the agent does
+#       evidence:  list of `file#anchor` citations
+#       tests:     optional list of test paths
+#
+# Anchor pair: `non-destructive-by-default` × five rules per
+# `road-to-post-pr29-optimize.md` Phase 2.
+
+version: 1
+
+rules:
+  - non-destructive-by-default
+  - autonomous-execution
+  - scope-control
+  - commit-policy
+  - ask-when-uncertain
+  - verify-before-complete
+  - agent-authority
+  - language-and-tone
+  - direct-answers
+
+pairs:
+
+  - id: ndd-x-autonomous-execution
+    rules: [non-destructive-by-default, autonomous-execution]
+    relation: overrides
+    conflict: >-
+      Standing autonomy directive ("arbeite selbstständig") is active and
+      the next step crosses a Hard-Floor trigger (production-branch merge,
+      deploy, push, prod data/infra, whimsical bulk deletion, commit with
+      bulk deletion / infra change).
+    resolution: >-
+      Autonomy never lifts the floor. Stop, surface the action via one
+      numbered-options block, wait for explicit user confirmation on
+      this turn before proceeding.
+    evidence:
+      - .agent-src.uncompressed/rules/non-destructive-by-default.md#the-iron-law
+      - .agent-src.uncompressed/rules/autonomous-execution.md#hard-floor--see-non-destructive-by-default
+
+  - id: ndd-x-scope-control
+    rules: [non-destructive-by-default, scope-control]
+    relation: restates
+    conflict: >-
+      Push, merge, branch creation, PR ops, tag pushes — both rules speak
+      to the same git operations.
+    resolution: >-
+      `scope-control` is the canonical permission gate; the floor restates
+      the prod-trunk and deploy-tied subset so the never-overridable layer
+      cannot be weakened by future scope-control edits. On any conflict,
+      the floor wins.
+    evidence:
+      - .agent-src.uncompressed/rules/non-destructive-by-default.md#the-iron-law
+      - .agent-src.uncompressed/rules/scope-control.md#git-operations--permission-gated
+      - .agent-src.uncompressed/rules/scope-control.md#production-infrastructure-bulk-destructive--hard-floor
+
+  - id: ndd-x-commit-policy
+    rules: [non-destructive-by-default, commit-policy]
+    relation: gates
+    conflict: >-
+      A commit is otherwise authorized by one of `commit-policy`'s four
+      paths (user-this-turn, standing instruction, `/commit*` invocation,
+      roadmap pre-scan), but the diff contains bulk deletions or infra
+      changes (row 6 of the Hard Floor).
+    resolution: >-
+      The commit pre-scan triggers regardless of which authorization path
+      applies. Surface the diff (paths + counts), confirm this turn,
+      then commit. The four exceptions cover *whether* commits happen;
+      the floor covers *which diffs* still need a separate confirmation.
+    evidence:
+      - .agent-src.uncompressed/rules/non-destructive-by-default.md#the-iron-law
+      - .agent-src.uncompressed/rules/commit-policy.md#hard-floor-still-applies--bulk-deletions-and-infra-changes
+
+  - id: ndd-x-ask-when-uncertain
+    rules: [non-destructive-by-default, ask-when-uncertain]
+    relation: complements
+    conflict: >-
+      A floor trigger fires AND the request is ambiguous (e.g. "delete
+      the legacy folder" without a file list).
+    resolution: >-
+      Both rules require the same response — stop and ask. The floor
+      provides the categorical reason (destructive); ask-when-uncertain
+      provides the question shape (one numbered-options block, blocking).
+      No conflict; both fire harmoniously.
+    evidence:
+      - .agent-src.uncompressed/rules/non-destructive-by-default.md#failure-modes
+      - .agent-src.uncompressed/rules/ask-when-uncertain.md#vague-request-triggers--must-ask
+
+  - id: ndd-x-verify-before-complete
+    rules: [non-destructive-by-default, verify-before-complete]
+    relation: complements
+    conflict: >-
+      A floor-crossing action (deploy, prod-data write) was authorized
+      and executed; agent is about to claim "done".
+    resolution: >-
+      Both rules apply independently. Floor is satisfied by user
+      confirmation; verify-before-complete is satisfied by fresh
+      verification evidence in the same message. Skipping either is a
+      rule violation.
+    evidence:
+      - .agent-src.uncompressed/rules/non-destructive-by-default.md#the-iron-law
+      - .agent-src.uncompressed/rules/verify-before-complete.md#the-iron-law
+
+  - id: autonomy-x-scope-control
+    rules: [scope-control, autonomous-execution]
+    relation: gates
+    conflict: >-
+      Autonomy is `on` and the next step is a permission-gated git
+      operation (push, branch create/delete, PR open, tag push) below
+      the floor threshold.
+    resolution: >-
+      `scope-control`'s permission gate stays in force. Autonomy
+      suppresses *trivial* questions only; git-shape decisions are
+      blocking. Stop and ask.
+    evidence:
+      - .agent-src.uncompressed/rules/scope-control.md#git-operations--permission-gated
+      - .agent-src.uncompressed/rules/autonomous-execution.md#blocking--still-ask-regardless-of-personalautonomy
+
+  - id: autonomy-x-commit-policy
+    rules: [commit-policy, autonomous-execution]
+    relation: overrides
+    conflict: >-
+      Autonomy is `on` and the agent could plausibly "just commit" after
+      a green verification step.
+    resolution: >-
+      `commit-policy` Iron Law forbids both committing AND asking about
+      committing unless one of the four exceptions applies. Autonomy
+      does not add a fifth exception.
+    evidence:
+      - .agent-src.uncompressed/rules/commit-policy.md#the-iron-law
+      - .agent-src.uncompressed/rules/autonomous-execution.md#commit-policy--see-commit-policy
+
+  - id: authority-x-ndd
+    rules: [agent-authority, non-destructive-by-default]
+    relation: defers_to
+    conflict: >-
+      Both rules speak to "may the agent do this autonomously?" — the
+      Priority Index points to the Hard Floor as Band 1.
+    resolution: >-
+      `agent-authority` is a router, never a source of truth. The Hard
+      Floor's Iron Law lives verbatim in `non-destructive-by-default`
+      and wins every conflict. The index points; it never restates.
+    evidence:
+      - .agent-src.uncompressed/rules/agent-authority.md#index-rules
+      - .agent-src.uncompressed/rules/non-destructive-by-default.md#the-iron-law
+
+  - id: authority-x-scope-control
+    rules: [agent-authority, scope-control]
+    relation: defers_to
+    conflict: >-
+      Permission Gate questions (push, branch, PR, architectural change)
+      surface during routine work — the index labels Band 2.
+    resolution: >-
+      The Priority Index routes to `scope-control` for git-shape and
+      scope-expansion decisions. Index never narrows or weakens the
+      gate; canonical rule wins on any wording divergence.
+    evidence:
+      - .agent-src.uncompressed/rules/agent-authority.md#index-rules
+      - .agent-src.uncompressed/rules/scope-control.md#git-operations--permission-gated
+
+  - id: authority-x-commit-policy
+    rules: [agent-authority, commit-policy]
+    relation: defers_to
+    conflict: >-
+      The "about to commit" decision arises — the index labels it Band 3
+      (Commit Default = never, with four exceptions).
+    resolution: >-
+      `commit-policy` Iron Law is canonical. The Priority Index points
+      to it; it does not enumerate the four exceptions itself. Future
+      edits to commit-policy do not require Index updates unless the
+      band ordering changes.
+    evidence:
+      - .agent-src.uncompressed/rules/agent-authority.md#index-rules
+      - .agent-src.uncompressed/rules/commit-policy.md#exceptions--when-committing-is-allowed
+
+  - id: scope-x-commit-policy
+    rules: [scope-control, commit-policy]
+    relation: narrows
+    conflict: >-
+      `scope-control` § "Git operations" forbids committing without
+      explicit permission as one of several git-op gates; `commit-policy`
+      narrows the commit case to a never-ask default with four named
+      exceptions.
+    resolution: >-
+      `commit-policy` is the narrower, canonical rule for the commit
+      sub-case. `scope-control` continues to govern push, branch, PR,
+      tag operations. On commit specifics, defer to `commit-policy`;
+      on other git ops, defer to `scope-control`.
+    evidence:
+      - .agent-src.uncompressed/rules/scope-control.md#git-operations--permission-gated
+      - .agent-src.uncompressed/rules/commit-policy.md#the-iron-law
+
+  - id: ask-x-direct-answers
+    rules: [ask-when-uncertain, direct-answers]
+    relation: complements
+    conflict: >-
+      A vague request triggers `ask-when-uncertain` (must ask), but
+      `direct-answers` Iron Law 3 (brevity by default) discourages
+      overlong replies; could read as tension when the question needs
+      framing.
+    resolution: >-
+      Both rules apply. `ask-when-uncertain` decides *whether* to ask
+      and demands one question per turn with numbered options.
+      `direct-answers` shapes *how* the question reads — no flattery,
+      no padding, shortest form that fully states the choice.
+    evidence:
+      - .agent-src.uncompressed/rules/ask-when-uncertain.md#iron-law--one-question-per-turn-always
+      - .agent-src.uncompressed/rules/direct-answers.md#iron-law-3--brevity-by-default
+
+  - id: language-x-direct-answers
+    rules: [language-and-tone, direct-answers]
+    relation: complements
+    conflict: >-
+      User writes German; agent must mirror language AND avoid flattery,
+      invented facts, padding. Both rules speak to reply shape.
+    resolution: >-
+      `language-and-tone` decides the language token (mirror user's last
+      chat message); `direct-answers` decides content discipline (no
+      flattery, verified facts, brevity). They compose: a brief, direct,
+      flattery-free reply in the user's language. Neither weakens the
+      other.
+    evidence:
+      - .agent-src.uncompressed/rules/language-and-tone.md#iron-law--mirror-the-users-language-always
+      - .agent-src.uncompressed/rules/direct-answers.md#iron-law-1--no-flattery

package/docs/contracts/rule-priority-hierarchy.md

@@ -0,0 +1,87 @@
+---
+stability: beta
+---
+
+# Rule Priority Hierarchy
+
+> **Audience:** anyone reading or editing `.agent-src.uncompressed/rules/*.md`,
+> or trying to predict which rule wins when several fire on the same turn.
+> **Machine-readable counterpart:** [`rule-interactions.yml`](rule-interactions.yml)
+> (linted by `scripts/lint_rule_interactions.py`).
+> **Diagram + pair-by-pair narrative:** [`rule-interactions.md`](rule-interactions.md).
+
+This document is the **ordered list** view. The matrix files describe
+how *pairs* of rules interact; this file states **which band wins**
+when the bands themselves disagree.
+
+## The four-line principle
+
+```
+Safety beats autonomy.
+Scope beats helpfulness.
+Verification beats completion.
+User intent beats command suggestion.
+```
+
+Every band below is a concrete instance of one of those four lines.
+When in doubt, walk the list top-down and stop at the first band that
+fires — that band's canonical rule decides the turn.
+
+## The ordered list
+
+| Band | Rule | What it gates | Lifts under |
+|---|---|---|---|
+| 1 | [`non-destructive-by-default`](../../.agent-src.uncompressed/rules/non-destructive-by-default.md) | Prod-trunk merge · deploy · push · prod data/infra · whimsical bulk deletion · bulk-deletion or infra commit | **Never.** Explicit user confirmation *this turn* only. |
+| 2 | [`security-sensitive-stop`](../../.agent-src.uncompressed/rules/security-sensitive-stop.md) | Auth · billing · tenant boundaries · secrets · file uploads · webhooks · public endpoints | Threat-model pass completed and recorded *before* the edit. |
+| 3 | [`scope-control`](../../.agent-src.uncompressed/rules/scope-control.md) | Git ops (branch · PR · tag · push · merge · rebase) · architectural changes · new libraries · scope expansion | Explicit user permission *this turn* or unrevoked standing instruction. |
+| 4 | [`ask-when-uncertain`](../../.agent-src.uncompressed/rules/ask-when-uncertain.md) | Ambiguous requirements · vague-request triggers · fenced steps | Concrete evidence resolves the ambiguity, **or** user answers the single question. |
+| 5 | [`commit-policy`](../../.agent-src.uncompressed/rules/commit-policy.md) | Any `git commit` | Four exceptions only — explicit "commit now", standing instruction, `/commit*` invocation, roadmap authorization. |
+| 6 | [`verify-before-complete`](../../.agent-src.uncompressed/rules/verify-before-complete.md) | "Done" / "complete" claims · suggestions to commit, push, or PR | Fresh verification evidence in *this* message. |
+| 7 | [`autonomous-execution`](../../.agent-src.uncompressed/rules/autonomous-execution.md) | Trivial-vs-blocking classification · autonomy opt-in detection | Per-step decision; never above bands 1–6. |
+| 8 | [`command-suggestion-policy`](../../.agent-src.uncompressed/rules/command-suggestion-policy.md) | Surfacing slash-command matches as numbered options | User always picks; nothing auto-executes. |
+| 9 | [`language-and-tone`](../../.agent-src.uncompressed/rules/language-and-tone.md) | First-token language of every reply · `.md` always English | Mirror the user's last chat message — no momentum exception. |
+
+**Read direction:** top-to-bottom is *priority on conflict*, not chronology.
+A turn typically touches several bands at once; the hierarchy decides
+which one's Iron Law gets the final say.
+
+## Index rules
+
+- **Higher band wins.** A band-3 permission does not lift band-1; a band-5
+  commit exception does not lift band-3. Each band's "Lifts under" column
+  is its own escape hatch and only its own.
+- **No band restates an Iron Law.** Iron Laws live verbatim in the
+  canonical rule files. This hierarchy points; it does not paraphrase.
+- **Bands 1–2 are *Hard Floors*.** No autonomy setting, no roadmap step,
+  no standing instruction lifts them. See
+  [`agent-authority`](../../.agent-src.uncompressed/rules/agent-authority.md)
+  § Index rules for the matching authority statement.
+- **Unsure → ask.** [`ask-when-uncertain`](../../.agent-src.uncompressed/rules/ask-when-uncertain.md)
+  is the universal escape hatch when the band is unclear.
+
+## Worked examples
+
+| Situation | Bands that fire | Winner | Why |
+|---|---|---|---|
+| Standing autonomy + roadmap step says "merge to `main`" | 1, 7 | **1** | Hard Floor predates and outranks autonomy; surface the merge, ask. |
+| `/commit-in-chunks` on a diff that removes a directory | 1, 5 | **1** | Commit exception authorizes *commits*, not *bulk deletions*. Confirm diff this turn. |
+| User asks "improve this" with no metric named | 4, 7 | **4** | Vague-request trigger fires before any autonomy decision; ask the one clarifying question. |
+| Editing `app/Auth/PasswordReset.php` mid-feature | 2, 7 | **2** | Security-sensitive surface stops the edit until threat-model is recorded. |
+| Agent about to claim "ready to merge" with no fresh test output | 5, 6 | **6** | Verification gate fires before the commit/push question is even valid. |
+| User types free-form prompt that matches `/refine-ticket` | 8, 9 | **8 + 9** | Suggestion runs as numbered options, mirrored to user's language. No conflict. |
+
+## Cross-references
+
+- [`agent-authority`](../../.agent-src.uncompressed/rules/agent-authority.md) — the four-band authority router (bands 1–3 + 7 of this hierarchy).
+- [`rule-interactions.md`](rule-interactions.md) — pairwise interaction narrative + Mermaid diagram.
+- [`rule-interactions.yml`](rule-interactions.yml) — machine-readable, CI-linted matrix.
+- [`STABILITY.md`](STABILITY.md) — what the `stability: beta` tag means for breaking changes.
+
+## Stability
+
+`beta` — the band ordering and four-line principle are settled, but
+the *worked examples* and the inclusion of band 8 (`command-suggestion-policy`)
+in the public hierarchy have not yet shipped through one major release.
+A breaking change to the band ordering is a SemVer-minor-pre-1.0 bump
+or a SemVer-major bump after 1.0. Adding a row, refining a "Lifts under"
+clause, or expanding the worked-examples table is non-breaking.

package/docs/contracts/ui-stack-extension.md

@@ -0,0 +1,236 @@
+---
+stability: beta
+---
+
+# UI Stack Extension — adding a new frontend stack to the UI track
+
+> **Audience:** maintainers adding a new stack (Svelte, SolidJS, Astro,
+> Qwik, …) to the UI directive set. Consumers of the package never run
+> this; they get the stacks shipped here.
+> **Source of truth:** [`ui-track-flow.md`](ui-track-flow.md) for the
+> contract; [`adr-product-ui-track.md`](adr-product-ui-track.md) for
+> the rationale.
+> **Status:** recipe only — R3 ships four stacks
+> (`blade-livewire-flux`, `react-shadcn`, `vue`, `plain`); no
+> additional stacks are scheduled. Add one only when a real consumer
+> project asks for it.
+
+## What "adding a stack" actually means
+
+Three artefacts plus a Golden fixture. The engine's directive set is
+fixed; only the dispatch tables and the implementation skill bundles
+change.
+
+| Artefact | File | Change |
+|---|---|---|
+| Stack label | [`scripts/work_engine/stack/detect.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/stack/detect.py) | New entry in `KNOWN_STACKS` + a heuristic in `detect_stack` |
+| Apply skill | `.agent-src.uncompressed/skills/ui-apply-<stack>/SKILL.md` | New skill bundle |
+| Review skill | `.agent-src.uncompressed/skills/ui-design-review-<stack>/SKILL.md` | New skill bundle |
+| Polish skill | `.agent-src.uncompressed/skills/ui-polish-<stack>/SKILL.md` | New skill bundle |
+| Dispatch tables | `directives/ui/{apply,review,polish}.py` | New row in each `STACK_DIRECTIVES` map |
+| Golden fixture | `tests/golden/sandbox/recipes/gt_u<NN>_<stack>_*.py` | One happy-path baseline at minimum |
+
+Skill names are not free — they are read by the dispatcher as
+`ui-apply-<stack>`, `ui-design-review-<stack>`, `ui-polish-<stack>`.
+A typo is silently handled by the `DEFAULT_DIRECTIVE` fallback
+(`ui-apply-plain` / `ui-design-review-plain` / `ui-polish-plain`),
+which is recoverable but probably not what the maintainer intended.
+
+## Step 1 — pick the label
+
+Convention: lowercase, hyphenated, framework-only (no version pin).
+
+| Good | Bad | Why |
+|---|---|---|
+| `svelte` | `svelte5` | Major-version drift handled by the audit's version-anchor warning, not by splitting the stack. |
+| `solid` | `solid-js` | Match the package name developers say out loud. |
+| `astro` | `astro-content` | Sub-modes (Astro components vs MDX) live inside the apply skill, not in the label. |
+
+Add the label to `KNOWN_STACKS` (the frozenset is exported and used by
+state validation; missing it makes detection silent-fail back to
+`plain`).
+
+## Step 2 — heuristic in `detect_stack`
+
+The detector reads `composer.json` and `package.json` once and applies
+heuristics in **priority order** — first match wins. The order matters:
+a Laravel + React project must hit `blade-livewire-flux` only when
+Livewire and Flux are present, otherwise `react-shadcn`.
+
+Insert the new heuristic **before** the `plain` fallback and **after**
+any stack that could legitimately co-exist with yours. For Svelte:
+
+```python
+def _has_svelte(package: dict[str, object]) -> bool:
+    deps = _all_dependencies(
+        package,
+        "dependencies",
+        "devDependencies",
+        "peerDependencies",
+        "optionalDependencies",
+    )
+    return "svelte" in deps
+```
+
+```python
+# inside detect_stack(), before the `plain` fallback
+if _has_svelte(package):
+    return StackResult(frontend="svelte", mtime=mtime)
+```
+
+**Failure mode to watch.** A heuristic that overlaps with an existing
+stack (Astro lists `react` as a peer dep when used with React adapters)
+must be ordered carefully. Test against real fixtures, not hand-edited
+JSON.
+
+## Step 3 — three skills, one shape
+
+Each skill is a SKILL.md bundle with frontmatter and prose. The
+contract for each:
+
+### `ui-apply-<stack>`
+
+Reads `state.ui_design.brief` and `state.ui_audit.components_found`.
+Writes a populated `state.ticket["ui_apply"]` envelope:
+
+```yaml
+ui_apply:
+  files: ["resources/components/UserCard.svelte"]
+  rendered:                 # full text per file, microcopy-locked
+    "resources/components/UserCard.svelte": |
+      <script>...</script>
+      ...
+  components_added: ["UserCard"]
+  components_reused: ["Button", "Card"]   # from audit
+  microcopy_lock: true      # affirms strings come from brief verbatim
+```
+
+**Hard rule:** strings in `rendered` must not contain
+`PLACEHOLDER_PATTERNS` (`<placeholder>`, `lorem`, `todo:`, `tbd`,
+`xxx`). The dispatcher rejects on producer side; the skill must reject
+on consumer side too.
+
+### `ui-design-review-<stack>`
+
+Reads `state.ui_apply` + `state.ui_design.brief`. Writes
+`state.ui_review` with `findings: list` and `review_clean: bool`.
+Findings are tagged `kind` ∈ `{token_violation, microcopy_drift,
+a11y_gap, layout_break, prop_misuse, …}` — extend the kind set
+sparingly. Token violations carry `category` and `value` so polish
+can route them through token extraction.
+
+### `ui-polish-<stack>`
+
+Reads `state.ui_review.findings` + `state.ui_audit.design_tokens`.
+Writes a fix envelope and increments `state.ui_polish.rounds`. Hard
+ceiling at `POLISH_CEILING = 2` is enforced by the dispatcher;
+the skill does **not** check the ceiling itself but must respect
+`token_repeat_threshold = 2` for unmatched-token extraction.
+
+## Step 4 — wire dispatch tables
+
+Three identical edits in
+[`directives/ui/apply.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/apply.py),
+[`directives/ui/review.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/review.py),
+and [`directives/ui/polish.py`](../../.agent-src.uncompressed/templates/scripts/work_engine/directives/ui/polish.py):
+
+```python
+STACK_DIRECTIVES: dict[str, str] = {
+    "blade-livewire-flux": "ui-apply-blade-livewire-flux",
+    "react-shadcn": "ui-apply-react-shadcn",
+    "vue": "ui-apply-vue",
+    "plain": "ui-apply-plain",
+    "svelte": "ui-apply-svelte",          # ← new row
+}
+```
+
+Same shape in `review.py` (`ui-design-review-svelte`) and `polish.py`
+(`ui-polish-svelte`). The dispatcher does not validate that the skill
+actually exists — it emits the `@agent-directive` and trusts the agent
+loader. A typo or missing skill manifests as a halt loop the maintainer
+notices on first replay.
+
+## Step 5 — version anchor in skill frontmatter
+
+Every stack-specific skill declares the upstream library version it
+was tested against, in frontmatter:
+
+```yaml
+tested_against:
+  svelte: "5.x"
+  svelte_kit: "2.x"      # if applicable
+```
+
+The audit step reads installed versions from `package.json` and
+compares against the anchor. A mismatch warns but does not block;
+the user picks whether to proceed or pin. Forgetting the anchor
+fails CI (`task lint-skills` enforces presence on `ui-apply-*`,
+`ui-design-review-*`, `ui-polish-*`).
+
+## Step 6 — Golden fixture
+
+Add at least one happy-path Golden that exercises the full UI flow
+on the new stack. Recipe lives at
+`tests/golden/sandbox/recipes/gt_u<NN>_<stack>_happy.py` and follows
+the pattern of `gt_u11_high_confidence.py`:
+
+1. Seed state with a clear `ui-build` prompt and an audit that finds
+   exactly one strong match (so `audit_path = "high_confidence"`).
+2. Pin the halt budget — high-confidence happy path is **1 halt**
+   (design-brief sign-off only).
+3. Capture under `tests/golden/baseline/GT-U<NN>/` via `task golden-capture`.
+4. The replay harness (`tests/golden/test_replay.py`) auto-discovers
+   the new baseline; no Taskfile change needed.
+
+For a complete pair, also add an `ambiguous` fixture — `2 halts max`,
+matching `gt_u12_ambiguous.py`'s shape. Skip the greenfield branch
+unless the stack has a meaningful difference there.
+
+See [`tests/golden/CAPTURING.md`](../../tests/golden/CAPTURING.md)
+for capture mechanics.
+
+## Step 7 — verify end-to-end
+
+```bash
+task sync                  # propagate detect.py + skill changes
+task generate-tools        # refresh .claude/, .cursor/, etc.
+task lint-skills           # checks frontmatter + version anchor
+task golden-replay         # runs all R1+R2+R3 baselines
+task ci                    # full pipeline
+```
+
+If `golden-replay` regresses on a non-`<stack>` baseline, your
+detector heuristic is over-matching — re-order the priority chain.
+
+## What you do **not** add
+
+- **A new directive set.** UI / UI-trivial / mixed are exhaustive for
+  R3. A stack-specific directive set means you've reached for a hammer
+  the engine doesn't have.
+- **A new entrypoint command.** `/work` and `/implement-ticket` route
+  through `directive_set` and `state.stack.frontend`; a `/build-svelte`
+  command would create a UX divergence the engine's intent classifier
+  is supposed to prevent.
+- **`fe-design` content.** That skill is the framework-agnostic
+  reference; new stack-specific heuristics live in the apply skill,
+  not in `fe-design`.
+- **Visual review.** Roadmap 4's headless-browser pipeline is the
+  destination for screenshot capture and a11y tooling. Stack
+  extensions don't need to wait on it.
+
+## When NOT to add a stack
+
+Defer the work and stay on `plain` if any apply:
+
+- Only one consumer project asks; the cost of maintaining the apply
+  skill exceeds the value.
+- The framework's idiom is close enough to an existing stack that
+  the existing apply skill produces acceptable output (Preact ≈
+  `react-shadcn` for most components).
+- The framework is in beta or pre-1.0 — the version anchor will drift
+  faster than you can re-capture goldens.
+
+The audit gate is the safety net: even on `plain`, the audit finds
+existing components and the design step uses them. The cost of
+**not** adding a stack is generally lower than the cost of adding
+one prematurely.