@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/decision-engine-gates.md

@@ -1,120 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-13
----
-
-# Decision-engine gates (v1)
-
-**Status:** beta — landed 2026-05-14 via `road-to-productization.md` Phase 2.
-**Owners:** `work_engine` maintainers.
-**Scope:** the optional `decision_engine:` block in `.agent-settings.yml`.
-
-## Purpose
-
-Cross the package from **observable** (Level-5) to **controllable**
-(Level-6). The engine has scored confidence-bands, risk-classes, and
-memory-hits since Phase 4 of `road-to-decision-trace`; this contract
-turns those signals into refusal gates the user opts into.
-
-Absent block = unchanged behaviour. Enforcement is opt-in only; the
-engine never silently halts on a signal the user did not configure.
-
-## Schema
-
-All keys optional. Unknown keys are rejected hard by
-`scripts/validate_decision_engine.py` and by
-`work_engine.scoring.decision_engine.parse`.
-
-| Key                    | Type            | Default | Notes |
-|------------------------|-----------------|---------|-------|
-| `surface_traces`       | bool            | `false` | Mirrored to `DecisionTraceHook`. Predates the gates; lives here so the block has one schema. |
-| `min_confidence`       | enum            | `off`   | `low` \| `medium` \| `high` \| `off`. Phase=Plan floor. |
-| `block_on_risk`        | enum            | `off`   | `low` \| `medium` \| `high` \| `off`. Phase=Implement ceiling. |
-| `require_memory_hits`  | bool            | `false` | Phase=Refine demands `memory_hits >= 1`. |
-| `on_block`             | enum            | `stop`  | `stop` \| `ask` \| `warn`. Action when a gate fires. |
-| `ask_timeout_seconds`  | int (>= 0)      | `30`    | Non-TTY wait before applying `on_block_fallback`. |
-| `on_block_fallback`    | enum            | `stop`  | `stop` \| `warn`. Resolution after `ask_timeout`. |
-
-## Gate-to-phase mapping
-
-Each gate fires on exactly one phase. The dispatcher emits gate
-decisions on `AFTER_STEP` for that phase only.
-
-| Gate                  | Phase     | Signal compared             | Fires when                          |
-|-----------------------|-----------|-----------------------------|-------------------------------------|
-| `min_confidence`      | Plan      | `confidence_band`           | actual < floor                      |
-| `require_memory_hits` | Refine    | `state.memory.hits`         | hits < 1                            |
-| `block_on_risk`       | Implement | `risk_class`                | actual >= ceiling                   |
-
-`low` < `medium` < `high` for both confidence and risk. `off` disables
-the gate.
-
-## Conflict matrix
-
-Only one gate fires per phase, so cross-phase conflicts are impossible
-by construction. Within a phase, **only the highest-impact gate
-applies**; downstream gates are evaluated against the same phase but
-skipped if a higher-priority gate already fired.
-
-Priority (highest → lowest):
-
-1. `block_on_risk` (Implement)
-2. `require_memory_hits` (Refine)
-3. `min_confidence` (Plan)
-
-This priority surfaces only when a future schema adds gates that
-overlap on the same phase; today each gate owns a unique phase and the
-priority is documentary. The order is locked so future additions
-inherit the contract.
-
-### Worked examples
-
-| Config                                                                                | Phase     | confidence | risk     | hits | Outcome                          |
-|---------------------------------------------------------------------------------------|-----------|------------|----------|------|----------------------------------|
-| `min_confidence: medium`                                                              | Plan      | `low`      | -        | -    | `min_confidence` fires, action=stop |
-| `min_confidence: medium`                                                              | Plan      | `high`     | -        | -    | no fire — band at/above floor    |
-| `block_on_risk: medium`                                                               | Implement | -          | `high`   | -    | `block_on_risk` fires, action=stop |
-| `block_on_risk: high`                                                                 | Implement | -          | `medium` | -    | no fire — below ceiling          |
-| `require_memory_hits: true`                                                           | Refine    | -          | -        | 0    | `require_memory_hits` fires      |
-| `require_memory_hits: true`                                                           | Refine    | -          | -        | 2    | no fire                          |
-| `min_confidence: high, block_on_risk: low, require_memory_hits: true` (all on)        | Plan      | `low`      | `low`    | 0    | `min_confidence` fires (Plan-owning gate) — Refine/Implement gates inert this phase |
-
-## Non-TTY timeout protocol
-
-`on_block=ask` is interactive. In a non-interactive context the
-engine cannot block waiting for keystrokes that will never arrive.
-Detection follows two signals (either disables interactivity):
-
-- environment variable `CI` set to `1`, `true`, `yes` (case-insensitive)
-- `sys.stdin.isatty()` or `sys.stdout.isatty()` returns false
-
-When non-interactive, `on_block=ask` collapses to action `ask_timeout`.
-The consumer (CLI / dispatcher) is expected to:
-
-1. wait `ask_timeout_seconds` for a stdin response;
-2. apply `on_block_fallback` (`stop` or `warn`) when the timeout
-   elapses or stdin is closed;
-3. surface `block_reason=ask_timeout` on the decision trace so the
-   reason is replay-visible.
-
-Default fallback is `stop` (fail-safe). Flip to `warn` only when CI
-explicitly wants advisory gates.
-
-## Rollback
-
-The block is config-only. Remove the `decision_engine:` block and
-the engine reverts to observe-only behaviour — no migration, no DB
-state, no schema lock. Per-key removal also works (each key has a
-safe default).
-
-## Test surface
-
-Coverage lives in `tests/work_engine/scoring/test_decision_engine.py`:
-
-- schema parser: defaults, unknown-key rejection, bad-type rejection;
-- gate evaluation: per-phase, per-signal, conflict isolation;
-- TTY detection: env-var detection, fallback to `ask_timeout`;
-- action resolution: `stop` / `warn` short-circuit interactivity.
-
-Wiring tests (dispatcher + hook) live in
-`tests/work_engine/test_decision_gate_hook.py`.

package/docs/contracts/decision-trace-v1.md

@@ -1,177 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Decision-trace v1
-
-**Purpose.** Pin the JSON shape that `/implement-ticket` and `/work`
-runs emit when the user opts into trace surfacing. The trace is the
-audit substrate for the rule-interaction matrix
-([`rule-interactions.md`](rule-interactions.md)) and feeds the
-showcase-session capture pipeline
-([`outcome-baseline.md`](../../agents/settings/contexts/outcome-baseline.md)).
-
-**Scope.** Defines the JSON envelope written next to a `WorkState`
-file when `decision_engine.surface_traces: true`. Does **not**
-specify how individual rules detect their own activation — that is
-the rule's own responsibility — only the shape of the report.
-
-Last refreshed: 2026-05-04.
-
-## Opt-in
-
-Off by default. Toggled in `.agent-settings.yml`:
-
-```yaml
-decision_engine:
-  surface_traces: true
-```
-
-The `/work` and `/implement-ticket` engines check this flag at phase
-boundaries and emit one trace file per phase when set.
-
-## File location
-
-```
-agents/runtime/state/work/<work-id>/decision-trace-<phase>.json
-```
-
-`work-id` matches the `WorkState` directory; `phase` is one of
-`refine`, `memory`, `analyze`, `plan`, `implement`, `test`, `verify`,
-`report`. Files are gitignored.
-
-## Envelope shape
-
-```json
-{
-  "schema_version": 1,
-  "work_id": "ABCD-1234-2026-05-04T12-34-56Z",
-  "phase": "implement",
-  "started_at": "2026-05-04T12:35:01Z",
-  "ended_at": "2026-05-04T12:38:42Z",
-  "confidence_band": "high",
-  "risk_class": "low",
-  "rules": [
-    {
-      "rule_id": "verify-before-complete",
-      "applied": true,
-      "skipped": false,
-      "conflicted_with": [],
-      "evidence_refs": ["agents/runtime/state/work/.../verify.log"]
-    }
-  ],
-  "memory": {
-    "asks": 3,
-    "hits": 2,
-    "ids": ["mem_42", "mem_57"]
-  },
-  "verify": {
-    "claims": 1,
-    "first_try_passes": 1
-  }
-}
-```
-
-Concerns and engines MUST treat unknown top-level keys as forward-
-compat extensions and MUST NOT raise on them.
-
-## Field semantics
-
-| Field | Meaning |
-|---|---|
-| `schema_version` | Always `1` for this contract. Major bump on breaking changes. |
-| `work_id` | Stable id of the WorkState directory. Allows cross-trace correlation across phases. |
-| `phase` | Engine phase that produced the trace. One of the eight phases above. |
-| `confidence_band` | One of `low` / `medium` / `high`. Heuristic defined below — derived from memory hits + ambiguity flags + verify evidence count. |
-| `risk_class` | One of `low` / `medium` / `high`. Per [`rule-interactions.md`](rule-interactions.md) — drives reviewer routing. |
-| `rules[].rule_id` | Stable rule id, matches the filename under `.agent-src.uncondensed/rules/` minus `.md`. |
-| `rules[].applied` | True if the rule's Iron Law fired and changed engine behaviour this phase. |
-| `rules[].skipped` | True if the rule was checked but produced no effect (no trigger match). |
-| `rules[].conflicted_with` | List of rule_ids that fired against this one. Reduction handled per `rule-interactions.md`. |
-| `rules[].evidence_refs` | Optional list of paths under `agents/runtime/state/` or `tests/` that back the `applied` claim. |
-| `memory.asks` | Count of `memory_retrieve` calls during the phase. |
-| `memory.hits` | Count of calls that returned ≥ 1 result. |
-| `memory.ids` | Stable memory entry ids returned. Bounded to ≤ 32 ids per phase; remainder dropped silently. |
-| `verify.claims` | Count of "done"-class claims the engine attempted this phase. |
-| `verify.first_try_passes` | Count of those claims that passed the verify gate without a re-prompt. |
-
-## Confidence-band heuristic
-
-```
-high:    memory.hits ≥ 2  AND  verify.first_try_passes == verify.claims  AND  no ambiguity flag
-medium:  memory.hits ≥ 1  OR   verify.first_try_passes ≥ 1
-low:     otherwise
-```
-
-Edge case: `verify.claims == 0` is not "high" by default — it folds
-into "medium" if at least one memory hit landed, "low" otherwise.
-
-## Risk-class heuristic
-
-Mirrors [`file-ownership-matrix.json`](file-ownership-matrix.json):
-the trace inherits the **maximum** risk class across all files the
-phase touched. If no files were touched (pure planning phase), risk
-is `low`.
-
-## Memory consequence keys
-
-**Purpose.** Bound the surface area where a memory hit can be said
-to have *changed* an outcome. Closed list, not open — without this
-bound, every memory call risks the "memory affected everything"
-failure mode (Risk register row 2 of the `road-to-proof-not-features`
-roadmap; see `agents/roadmaps/` or `agents/roadmaps/archive/`).
-
-**Closed list (v1).** Exactly four keys. Adding a fifth requires a
-schema bump + entry under `### Breaking` in `CHANGELOG.md`.
-
-| Key | Source | Diff semantics |
-|---|---|---|
-| `confidence_band` | Top-level envelope field. | String inequality (`high` ≠ `medium` ≠ `low`). |
-| `risk_class` | Top-level envelope field. | String inequality. |
-| `applied_rules` | Derived: sorted list of `rules[].rule_id` where `applied == true`. | Set inequality. |
-| `test_plan` | Derived: sorted list of test paths captured in the Plan-phase `state.plan.tests` slice. May be `null` when the phase is not `plan` or no Plan-phase tests were captured. | Set inequality; `null` on either side suppresses the key from the diff. |
-
-**Diff semantics.** The producer renders two traces for the same
-phase: one **with** the memory entry consulted, one **without**
-(re-running the heuristic against `memory.hits` decremented by the
-entry's contribution). The `affected` field is the sorted list of
-keys above whose values differ between the two traces. Empty list
-means "consulted but no key diverged" — the call was informational,
-not load-bearing.
-
-**Out of scope for v1.** Gradations beyond binary key-diverged /
-not-diverged (overridden, combined, filtered). Tracked as a Phase-1-
-gated revisit in the same Risk register.
-
-## Privacy floor
-
-- `memory.ids` carries opaque ids only — no entry bodies, no secrets.
-- `evidence_refs` carries paths only — no file contents.
-- `rules[].rule_id` is stable id, not free-form text.
-
-The visibility line surfaced to the user (Phase 4) consumes this file
-under the same floor.
-
-## Stability
-
-Beta. Breaking changes between v1 and v2 are allowed in a minor
-release if the change appears in `CHANGELOG.md` under a `### Breaking`
-heading. Engines MUST gate on `schema_version` and refuse unknown
-majors.
-
-## Cross-references
-
-- Personas (Architect, Risk-Officer) live in the package's persona
-  library under [`.agent-src.uncondensed/personas/`](../../.agent-src.uncondensed/personas/).
-  This contract does not duplicate them — when a future trace consumer
-  attributes a decision to one of those personas, the persona file is
-  the source of truth, not this envelope.
-- Rule-interaction matrix:
-  [`rule-interactions.md`](rule-interactions.md) (machine-readable
-  source: [`rule-interactions.yml`](rule-interactions.yml)).
-- Confidence-band heuristic is implemented in
-  `work_engine/scoring/decision_trace.py` and exercised by
-  `tests/work_engine/scoring/test_decision_trace_scoring.py`.
-- Outcome metrics consume `verify.first_try_passes`:
-  [`outcome-baseline.md`](../../agents/settings/contexts/outcome-baseline.md).

package/docs/contracts/design-artifact-lifecycle.md

@@ -1,93 +0,0 @@
-# Design-Artifact Lifecycle Contract
-
-Phase 1 of `road-to-design-artifact-fidelity`.
-One lifecycle every design/artifact skill points at, so "context before taste"
-and "rendered artifact before claim" are a shared workflow, not per-skill folklore.
-Design work is a **pipeline** — understand, inspect, plan, build, verify, hand
-off — not a bag of styling tips.
-
-This contract is advisory (staged-rollout stage 1 per
-[`design-artifact-verification` § Staged rollout](design-artifact-verification.md#staged-rollout)):
-skills reference these stages; nothing here is a default gate yet.
-
-## The lifecycle
-
-Six stages. Every design task runs the stages its branch (below) selects — never
-skips straight to "build".
-
-| # | Stage | What it does | Exercised by fixtures |
-|---|---|---|---|
-| 1 | **Understand** | Medium, audience, fidelity, target host. What *kind* of artifact (screen, deck, doc, component, prototype), for whom, at what polish, verifiable how (per the capability table). | `daf-no-context` |
-| 2 | **Inspect** | Read the existing design system + code **before** styling — code over screenshots when available; copy the visual vocabulary; confirm assets exist. Ask when no context is attached. | `daf-inaccessible-design-system`, `daf-missing-asset` |
-| 3 | **Plan** | Define the visual system + the variation plan: which axis varies, how many options, labelled. No unrequested variations. | `daf-requested-variations`, `daf-unwanted-variations` |
-| 4 | **Build** | Produce the artifact against the system. Surgical on edits; no invented filler (§ Design constraints). | `daf-edit-preservation` |
-| 5 | **Verify** | Prove the rendered artifact — render / load / responsive / export — via a primitive the host has, else caveat honestly (never fake). | `daf-overlapping-text`, `daf-mobile-fit`, `daf-export-readback-failure` |
-| 6 | **Handoff** | Brief, honest handoff: what was built, what is verified vs caveated, implementation intent, preserved comment anchors. | `daf-export-readback-failure` |
-
-Fixtures are defined in [`tests/design-artifacts/eval-fixtures.md`](../../tests/design-artifacts/eval-fixtures.md);
-the ids are stable so skill edits in later phases can prove the stage is operational.
-
-## Skill → stage map
-
-Skills own the *depth* at each stage; the lifecycle owns the *order*. A skill
-cites the stage(s) it serves instead of re-describing the workflow.
-
-| Stage | Primary skills |
-|---|---|
-| Understand | [`fe-design`](../../src/skills/fe-design/SKILL.md), [`design-review`](../../src/skills/design-review/SKILL.md) |
-| Inspect | [`existing-ui-audit`](../../src/skills/existing-ui-audit/SKILL.md), [`brand-audit`](../../src/skills/brand-audit/SKILL.md), [`brand-to-tokens`](../../src/skills/brand-to-tokens/SKILL.md) |
-| Plan | [`fe-design`](../../src/skills/fe-design/SKILL.md), [`ui-component-architect`](../../src/skills/ui-component-architect/SKILL.md) |
-| Build | [`ui-component-architect`](../../src/skills/ui-component-architect/SKILL.md), [`html-deck`](../../src/skills/html-deck/SKILL.md) (decks), [`doc-coauthoring`](../../src/skills/doc-coauthoring/SKILL.md) (documents) |
-| Verify | [`playwright-testing`](../../src/skills/playwright-testing/SKILL.md), [`design-review`](../../src/skills/design-review/SKILL.md), [`markitdown`](../../src/skills/markitdown/SKILL.md) (export readback) |
-| Handoff | [`design-review`](../../src/skills/design-review/SKILL.md), [`design-system-capture`](../../src/skills/design-system-capture/SKILL.md) |
-
-(The roadmap's conceptual "presentations" / "PDF / document" skills map to the
-real `html-deck`, `markitdown`, and `doc-coauthoring` skills above.)
-
-## Branch rules
-
-The lifecycle is not linear for every task. Pick the branch first; it selects
-which stages run and which fixtures gate it (each branch has ≥1 fixture).
-
-| Branch | Trigger | Stages run | Gating fixtures |
-|---|---|---|---|
-| **New design** | Greenfield artifact, no prior version | 1→2→3→4→5→6 (full) | `daf-no-context`, `daf-inaccessible-design-system`, `daf-requested-variations` |
-| **Targeted edit** | Change one named thing in an existing artifact | 2 (light) → 4 → 5 | `daf-edit-preservation`, `daf-unwanted-variations` |
-| **Iteration** | Refine an existing artifact across a version bump | 1 (delta) → 3 → 4 → 5; **preserve the prior version** on a major revision | `daf-requested-variations` |
-| **Design-system extraction** | Derive tokens/components from existing artifacts | 2 (deep) → 6 | `daf-inaccessible-design-system` |
-| **Handoff to production code** | Turn a design into implementation intent | 5 → 6 | `daf-overlapping-text`, `daf-mobile-fit`, `daf-export-readback-failure` |
-
-**Targeted edit stays surgical** — no redesign of neighbours, no reformatting of
-untouched regions, comment anchors preserved (the `daf-edit-preservation`
-contract; mirrors [`minimal-safe-diff`](../../src/rules/minimal-safe-diff.md) for
-visual work). **Iteration preserves the prior version** on a major revision so a
-regression is recoverable.
-
-## Design constraints — do not invent filler
-
-```
-EMPTY SPACE IS A COMPOSITION PROBLEM, NOT PERMISSION TO ADD MATERIAL.
-NEVER INVENT FAKE SECTIONS, FAKE METRICS, LOREM-STYLE COPY, OR STOCK
-DECORATION TO FILL A LAYOUT. ASK BEFORE ADDING MATERIAL THAT ISN'T IN THE BRIEF.
-```
-
-- **Do not invent filler.** A sparse layout is solved with composition
-  (spacing, scale, hierarchy), not with fabricated content. Fake KPIs, invented
-  testimonials, placeholder charts with made-up numbers, and decorative
-  stock-like imagery are content the user did not ask for and cannot trust.
-- **Ask before adding material.** If the artifact genuinely needs content that
-  isn't supplied (a section the brief implies but doesn't provide), surface the
-  gap and ask — do not silently manufacture it. Realistic placeholder clearly
-  labelled as placeholder is acceptable when the user asked for a mock; passing
-  invented data off as real is not.
-
-This is the design-surface instance of the no-invented-facts discipline
-([`direct-answers`](../../src/rules/direct-answers.md) Iron Law 2) and the
-no-placeholder-slop rule ([`output-discipline`](../../src/rules/output-discipline.md)).
-
-## Related
-
-- [`design-artifact-verification`](design-artifact-verification.md) — the Phase-0 host-capability & degrade contract this lifecycle's Verify stage runs against.
-- [`tests/design-artifacts/eval-fixtures.md`](../../tests/design-artifacts/eval-fixtures.md) — the nine fixtures the stages + branches gate on.
-- [`design-fidelity`](../../src/rules/design-fidelity.md) — the provided-design-is-the-spec rule the Inspect stage enforces.
-- [`fe-design`](../../src/skills/fe-design/SKILL.md), [`existing-ui-audit`](../../src/skills/existing-ui-audit/SKILL.md), [`design-review`](../../src/skills/design-review/SKILL.md), [`ui-component-architect`](../../src/skills/ui-component-architect/SKILL.md) — the design skills that cite these stages.

package/docs/contracts/design-artifact-verification.md

@@ -1,153 +0,0 @@
-# Design-Artifact Verification — Host-Capability & Degrade Contract
-
-Phase 0 substrate for `road-to-design-artifact-fidelity`.
-Design work is only production-grade if the agent **verifies the rendered
-artifact** — but a verification step the host cannot run must degrade honestly,
-never block the work or fake a green check.
-
-This is the **design-verification** sibling of
-[`host-capability-manifest`](../../src/agent-src/contexts/execution/host-capability-manifest.md)
-(which covers *subagent* primitives). Same philosophy: resolve once per session,
-**unknown host assumes nothing**, a missing capability degrades to "prove or
-caveat" rather than a hard block.
-
-## Iron Law — prove or caveat, never fake
-
-```
-A DESIGN ARTIFACT IS "VERIFIED" ONLY BY A CHECK THE HOST ACTUALLY RAN.
-A CAPABILITY THE HOST LACKS DEGRADES TO AN HONEST CAVEAT — NEVER A
-FABRICATED "LOOKS GOOD", NEVER A HARD BLOCK ON ALL DESIGN WORK.
-UNKNOWN HOST → ASSUME STATIC-INSPECTION ONLY.
-```
-
-## Verification primitives
-
-Each design-verification gate needs one of these host primitives:
-
-| Primitive | What it proves | Typical mechanism |
-|---|---|---|
-| `local_browser` | The artifact opens + paints in a real engine | launch a browser on a local URL/file |
-| `playwright` | Automated open + interact + assert, headless | Playwright / Puppeteer runner |
-| `screenshot` | Captured pixels for visual diff / review | Playwright `screenshot`, OS capture |
-| `console_inspect` | No runtime JS errors / warnings on load | devtools / Playwright console API |
-| `canvas_pixel` | Canvas/WebGL actually drew (not blank) | pixel read-back on a screenshot |
-| `pdf_render` | A PDF paginates + renders without error | headless render / `pdftoppm` / lib |
-| `deck_export` | A slide deck exports to the target format | deck tool export path |
-| `doc_export` | A document exports (DOCX/MD/PDF) + re-reads | office/markdown export + readback |
-| `image_decode` | An image decodes to real dimensions/format | image lib / the host's image reader |
-| `static_inspect` | Source/markup read without rendering | file read + parse (always available) |
-
-## Host-class capability table
-
-Precise per-host support varies with what is installed (Playwright is a dev
-dependency, not a guarantee). Resolve the **actual** row at session start; when
-unsure, take the lower capability. Classes, not brand promises:
-
-| Primitive | A · local-with-tooling<br>(Claude Code, Cursor, Windsurf, Augment, Cline, Zed on a dev machine) | B · cloud / sandboxed<br>(claude.ai web, Skills API) | C · CI / headless<br>(GitHub Actions, containers) |
-|---|---|---|---|
-| `local_browser` | ⚠️ if a browser is installed | ❌ | ❌ |
-| `playwright` | ⚠️ if the Playwright dep is present | ❌ | ✅ (headless, deps installed) |
-| `screenshot` | ⚠️ via Playwright / OS capture | ❌ | ✅ via Playwright |
-| `console_inspect` | ⚠️ via Playwright | ❌ | ✅ via Playwright |
-| `canvas_pixel` | ⚠️ via a screenshot read-back | ❌ | ✅ via screenshot read-back |
-| `pdf_render` | ⚠️ if a renderer/lib is present | ❌ | ✅ if the lib is installed |
-| `deck_export` | ⚠️ if the deck tool is present | ❌ | ⚠️ if the tool is installed |
-| `doc_export` | ⚠️ if the office/md tool is present | ❌ | ⚠️ if the tool is installed |
-| `image_decode` | ✅ (image lib / host image reader) | ⚠️ if the host renders images | ✅ (image lib) |
-| `static_inspect` | ✅ | ✅ | ✅ |
-
-Legend: ✅ available · ⚠️ available **only if** the named dependency is present
-(probe first, never assume) · ❌ not available → degrade.
-
-**Resolution rule.** Before a design-verification gate runs, confirm the
-primitive is actually present (e.g. `npx playwright --version`, a renderer on
-`PATH`, the host's image reader). A `⚠️` that fails the probe resolves to `❌`
-for that session — exactly the safe-default of the subagent manifest.
-
-## Honest-degrade behavior
-
-When the needed primitive is `❌` (or a `⚠️` probe fails):
-
-1. **Do the work anyway** — never block design work because a check can't run.
-2. **State the caveat explicitly** in the handoff: *"Not render-verified on this
-   host (no `playwright`); static-inspected only — open `X` locally to confirm
-   Y."* Name the specific unverified property, not a blanket disclaimer.
-3. **Offer the fallback check** the host *can* run (static inspection of the
-   markup, a structural assertion, an image-decode dimension check).
-4. **Never emit a fabricated verification claim** ("renders correctly", "no
-   console errors") for a check that did not run — that is an invented fact
-   ([`direct-answers`](../../src/rules/direct-answers.md) Iron Law 2).
-
-## Verification checklist
-
-Run before claiming a design artifact done. Each step is gated by the primitive
-it needs — a step whose primitive is absent is **skipped with a caveat**, never
-faked (§ Honest-degrade). "Looks good" is not a verification result.
-
-1. **Open the artifact** (`local_browser` / `playwright` / `pdf_render` / `doc_export`) — it opens and paints; a static-only host inspects the source instead.
-2. **Console / load errors** (`console_inspect`) — no runtime errors or failed loads on open.
-3. **Desktop + mobile viewport** (`screenshot`) — inspect a desktop width and ~375px; no overflow / clipping.
-4. **Text fit / no overlap** (`screenshot`, degrade `static_inspect`) — no collisions or truncation at the target breakpoints.
-5. **Referenced assets decode** (`image_decode`) — every referenced image / font resolves and decodes (no broken `src`).
-6. **Key interaction state** (`playwright`) — the primary interaction (open / submit / toggle) behaves; description-only where unavailable.
-7. **Capture evidence only when supported** (`screenshot`) — attach a screenshot / diff when the host can; otherwise cite what was statically checked.
-
-**Completion contract.** A design task with render capability present cannot
-claim "done" without at least steps 1–5 as evidence. Where capability is absent
-(no browser / renderer), report that plainly (§ Rollback language) and keep the
-completion claim scoped to what was actually checked. The checklist is exercised
-by the verification golden tasks in
-[`eval-fixtures.md`](../../tests/design-artifacts/eval-fixtures.md)
-(`daf-nonblank-canvas`, `daf-mobile-fit`, `daf-missing-asset`,
-`daf-overlapping-text`, `daf-broken-interaction`, `daf-export-readback-failure`).
-
-Skills wire this in: [`playwright-testing`](../../src/skills/playwright-testing/SKILL.md)
-runs it when a browser primitive is present; [`design-review`](../../src/skills/design-review/SKILL.md)
-gates its verdict on it; static decks / documents use the deck / PDF / document
-verification path ([`html-deck`](../../src/skills/html-deck/SKILL.md),
-[`markitdown`](../../src/skills/markitdown/SKILL.md) readback).
-
-## Staged rollout
-
-Design-artifact fidelity rolls out in three stages so nothing becomes a hard
-gate before its capability + evals exist:
-
-1. **Advisory** — the lifecycle contract + these capability rows ship as
-   guidance the design skills reference. No gate; agents follow the workflow
-   and caveat honestly.
-2. **Routed** — the design skills (`fe-design`, `design-review`,
-   `existing-ui-audit`, `ui-component-architect`, …) are updated to point at
-   the lifecycle stages + the eval fixtures. Still no default block.
-3. **Default gates where capability exists** — a verification gate becomes
-   default-on **only** for host classes whose row shows the primitive `✅`/`⚠️`
-   present; classes without it stay advisory + caveat. A gate is never
-   default-on for a class that can only `static_inspect`.
-
-## Rollback language for a default-on gate
-
-Any default-on verification gate carries this escape, so a host without render
-support degrades instead of blocking every design task:
-
-> **Render verification unavailable on this host.** `<gate>` needs `<primitive>`,
-> which this host class (`<class>`) does not provide. Proceeding without the
-> render check; the artifact is **static-inspected only**. Unverified: `<named
-> property>`. To verify, run `<fallback>` or open the artifact on a
-> local-with-tooling host.
-
-A gate that cannot degrade this way is misconfigured — fix the gate, do not
-strand the user.
-
-## Eval baseline
-
-The design-artifact eval fixtures (the nine cases this phase seeds) live in
-[`tests/design-artifacts/eval-fixtures.md`](../../tests/design-artifacts/eval-fixtures.md).
-Each fixture names the primitive it needs, so a fixture is scored on a host only
-when that primitive resolves present — and skipped-with-caveat otherwise. Phase 1
-links the lifecycle branches to these fixture ids.
-
-## Related
-
-- [`host-capability-manifest`](../../src/agent-src/contexts/execution/host-capability-manifest.md) — the subagent-primitive sibling manifest (same resolve-once / safe-default shape).
-- [`capability-boundary`](capability-boundary.md) — the broader capability-vs-pack boundary.
-- [`playwright-testing`](../../src/skills/playwright-testing/SKILL.md) — the runner most design gates use when `playwright` is present.
-- [`design-review`](../../src/skills/design-review/SKILL.md), [`existing-ui-audit`](../../src/skills/existing-ui-audit/SKILL.md), [`fe-design`](../../src/skills/fe-design/SKILL.md) — the design skills the routed stage updates.