@elementarno/eawf 0.5.2

package/hooks/post_push.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Eä-managed Claude Code hook wrapper for post_push.
+# Generator: eawf plugin install claude (managed file — re-render via
+# `eawf plugin update claude`; hand-edits are detected by `eawf plugin doctor`).
+set -euo pipefail
+
+# Synthesise a JSON payload from positional args (Claude passes args, not stdin).
+# We escape only the minimum set of characters required for a JSON string body
+# (backslash + double-quote) so the payload is portable across bash versions.
+_eawf_json_escape() {
+    local s="${1-}"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    printf '%s' "$s"
+}
+
+_eawf_arg1="$(_eawf_json_escape "${1-}")"
+_eawf_arg2="$(_eawf_json_escape "${2-}")"
+_eawf_arg3="$(_eawf_json_escape "${3-}")"
+_eawf_arg4="$(_eawf_json_escape "${4-}")"
+
+_eawf_payload=$(printf '{"hook_event_name":"%s","claude_event_name":"%s","args":["%s","%s","%s","%s"]}' \
+    "PostToolUse" \
+    "post_push" \
+    "${_eawf_arg1}" \
+    "${_eawf_arg2}" \
+    "${_eawf_arg3}" \
+    "${_eawf_arg4}")
+
+printf '%s' "${_eawf_payload}" | exec uv run eawf hook run post_push --runtime claude

package/hooks/pre_commit.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Eä-managed Claude Code hook wrapper for pre_commit.
+# Generator: eawf plugin install claude (managed file — re-render via
+# `eawf plugin update claude`; hand-edits are detected by `eawf plugin doctor`).
+set -euo pipefail
+
+# Synthesise a JSON payload from positional args (Claude passes args, not stdin).
+# We escape only the minimum set of characters required for a JSON string body
+# (backslash + double-quote) so the payload is portable across bash versions.
+_eawf_json_escape() {
+    local s="${1-}"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    printf '%s' "$s"
+}
+
+_eawf_arg1="$(_eawf_json_escape "${1-}")"
+_eawf_arg2="$(_eawf_json_escape "${2-}")"
+_eawf_arg3="$(_eawf_json_escape "${3-}")"
+_eawf_arg4="$(_eawf_json_escape "${4-}")"
+
+_eawf_payload=$(printf '{"hook_event_name":"%s","claude_event_name":"%s","args":["%s","%s","%s","%s"]}' \
+    "PreToolUse" \
+    "pre_commit" \
+    "${_eawf_arg1}" \
+    "${_eawf_arg2}" \
+    "${_eawf_arg3}" \
+    "${_eawf_arg4}")
+
+printf '%s' "${_eawf_payload}" | exec uv run eawf hook run pre_commit --runtime claude

package/hooks/pre_compact.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Eä-managed Claude Code hook wrapper for pre_compact.
+# Generator: eawf plugin install claude (managed file — re-render via
+# `eawf plugin update claude`; hand-edits are detected by `eawf plugin doctor`).
+set -euo pipefail
+
+# Synthesise a JSON payload from positional args (Claude passes args, not stdin).
+# We escape only the minimum set of characters required for a JSON string body
+# (backslash + double-quote) so the payload is portable across bash versions.
+_eawf_json_escape() {
+    local s="${1-}"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    printf '%s' "$s"
+}
+
+_eawf_arg1="$(_eawf_json_escape "${1-}")"
+_eawf_arg2="$(_eawf_json_escape "${2-}")"
+_eawf_arg3="$(_eawf_json_escape "${3-}")"
+_eawf_arg4="$(_eawf_json_escape "${4-}")"
+
+_eawf_payload=$(printf '{"hook_event_name":"%s","claude_event_name":"%s","args":["%s","%s","%s","%s"]}' \
+    "PreCompact" \
+    "pre_compact" \
+    "${_eawf_arg1}" \
+    "${_eawf_arg2}" \
+    "${_eawf_arg3}" \
+    "${_eawf_arg4}")
+
+printf '%s' "${_eawf_payload}" | exec uv run eawf hook run pre_compact --runtime claude

package/hooks/pre_push.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Eä-managed Claude Code hook wrapper for pre_push.
+# Generator: eawf plugin install claude (managed file — re-render via
+# `eawf plugin update claude`; hand-edits are detected by `eawf plugin doctor`).
+set -euo pipefail
+
+# Synthesise a JSON payload from positional args (Claude passes args, not stdin).
+# We escape only the minimum set of characters required for a JSON string body
+# (backslash + double-quote) so the payload is portable across bash versions.
+_eawf_json_escape() {
+    local s="${1-}"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    printf '%s' "$s"
+}
+
+_eawf_arg1="$(_eawf_json_escape "${1-}")"
+_eawf_arg2="$(_eawf_json_escape "${2-}")"
+_eawf_arg3="$(_eawf_json_escape "${3-}")"
+_eawf_arg4="$(_eawf_json_escape "${4-}")"
+
+_eawf_payload=$(printf '{"hook_event_name":"%s","claude_event_name":"%s","args":["%s","%s","%s","%s"]}' \
+    "PreToolUse" \
+    "pre_push" \
+    "${_eawf_arg1}" \
+    "${_eawf_arg2}" \
+    "${_eawf_arg3}" \
+    "${_eawf_arg4}")
+
+printf '%s' "${_eawf_payload}" | exec uv run eawf hook run pre_push --runtime claude

package/hooks/session_end.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Eä-managed Claude Code hook wrapper for session_end.
+# Generator: eawf plugin install claude (managed file — re-render via
+# `eawf plugin update claude`; hand-edits are detected by `eawf plugin doctor`).
+set -euo pipefail
+
+# Synthesise a JSON payload from positional args (Claude passes args, not stdin).
+# We escape only the minimum set of characters required for a JSON string body
+# (backslash + double-quote) so the payload is portable across bash versions.
+_eawf_json_escape() {
+    local s="${1-}"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    printf '%s' "$s"
+}
+
+_eawf_arg1="$(_eawf_json_escape "${1-}")"
+_eawf_arg2="$(_eawf_json_escape "${2-}")"
+_eawf_arg3="$(_eawf_json_escape "${3-}")"
+_eawf_arg4="$(_eawf_json_escape "${4-}")"
+
+_eawf_payload=$(printf '{"hook_event_name":"%s","claude_event_name":"%s","args":["%s","%s","%s","%s"]}' \
+    "SessionEnd" \
+    "session_end" \
+    "${_eawf_arg1}" \
+    "${_eawf_arg2}" \
+    "${_eawf_arg3}" \
+    "${_eawf_arg4}")
+
+printf '%s' "${_eawf_payload}" | exec uv run eawf hook run session_end --runtime claude

package/hooks/session_start.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Eä-managed Claude Code hook wrapper for session_start.
+# Generator: eawf plugin install claude (managed file — re-render via
+# `eawf plugin update claude`; hand-edits are detected by `eawf plugin doctor`).
+set -euo pipefail
+
+# Synthesise a JSON payload from positional args (Claude passes args, not stdin).
+# We escape only the minimum set of characters required for a JSON string body
+# (backslash + double-quote) so the payload is portable across bash versions.
+_eawf_json_escape() {
+    local s="${1-}"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    printf '%s' "$s"
+}
+
+_eawf_arg1="$(_eawf_json_escape "${1-}")"
+_eawf_arg2="$(_eawf_json_escape "${2-}")"
+_eawf_arg3="$(_eawf_json_escape "${3-}")"
+_eawf_arg4="$(_eawf_json_escape "${4-}")"
+
+_eawf_payload=$(printf '{"hook_event_name":"%s","claude_event_name":"%s","args":["%s","%s","%s","%s"]}' \
+    "SessionStart" \
+    "session_start" \
+    "${_eawf_arg1}" \
+    "${_eawf_arg2}" \
+    "${_eawf_arg3}" \
+    "${_eawf_arg4}")
+
+printf '%s' "${_eawf_payload}" | exec uv run eawf hook run session_start --runtime claude

package/hooks/subagent_stop.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Eä-managed Claude Code hook wrapper for subagent_stop.
+# Generator: eawf plugin install claude (managed file — re-render via
+# `eawf plugin update claude`; hand-edits are detected by `eawf plugin doctor`).
+set -euo pipefail
+
+# Synthesise a JSON payload from positional args (Claude passes args, not stdin).
+# We escape only the minimum set of characters required for a JSON string body
+# (backslash + double-quote) so the payload is portable across bash versions.
+_eawf_json_escape() {
+    local s="${1-}"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    printf '%s' "$s"
+}
+
+_eawf_arg1="$(_eawf_json_escape "${1-}")"
+_eawf_arg2="$(_eawf_json_escape "${2-}")"
+_eawf_arg3="$(_eawf_json_escape "${3-}")"
+_eawf_arg4="$(_eawf_json_escape "${4-}")"
+
+_eawf_payload=$(printf '{"hook_event_name":"%s","claude_event_name":"%s","args":["%s","%s","%s","%s"]}' \
+    "SubagentStop" \
+    "subagent_stop" \
+    "${_eawf_arg1}" \
+    "${_eawf_arg2}" \
+    "${_eawf_arg3}" \
+    "${_eawf_arg4}")
+
+printf '%s' "${_eawf_payload}" | exec uv run eawf hook run subagent_stop --runtime claude

package/hooks.json

@@ -0,0 +1,88 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post_commit.sh",
+            "type": "command"
+          }
+        ],
+        "matcher": "Bash"
+      },
+      {
+        "hooks": [
+          {
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post_push.sh",
+            "type": "command"
+          }
+        ],
+        "matcher": "Bash"
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre_compact.sh",
+            "type": "command"
+          }
+        ],
+        "matcher": ""
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre_commit.sh",
+            "type": "command"
+          }
+        ],
+        "matcher": "Bash"
+      },
+      {
+        "hooks": [
+          {
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre_push.sh",
+            "type": "command"
+          }
+        ],
+        "matcher": "Bash"
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session_start.sh",
+            "type": "command"
+          }
+        ],
+        "matcher": ""
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session_end.sh",
+            "type": "command"
+          }
+        ],
+        "matcher": ""
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/subagent_stop.sh",
+            "type": "command"
+          }
+        ],
+        "matcher": ""
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@elementarno/eawf",
+  "version": "0.5.2",
+  "description": "E\u00e4 Workflow \u2014 state-first, agent-driven development framework (Claude Code plugin).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Elementarno9/eawf.git"
+  },
+  "files": [
+    ".claude-plugin/",
+    "skills/",
+    "agents/",
+    "hooks.json",
+    "hooks/",
+    "README.md"
+  ]
+}

package/skills/add-property-test/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: add-property-test
+description: Model-only playbook for adding a property-based test that pins a function's invariant.
+argument-hint: ""
+user-invocable: false
+disable-model-invocation: false
+---
+
+# add-property-test
+
+A model-only playbook for adding a property-based test. There is no slash command; the model invokes this when example-based tests leave a function's invariants under-specified.
+
+## When to reach for it
+
+- The function has an algebraic law (round-trip, idempotence, commutativity, monotonicity) that examples only sample.
+- The input space is large and edge cases keep slipping through hand- written cases.
+- A parser/serialiser pair should satisfy `decode(encode(x)) == x`.
+
+## Canonical procedure
+
+1. State the invariant in one sentence ("encoding then decoding returns the input").
+2. Pick the narrowest strategy that generates valid inputs; constrain it so generated values are in-domain rather than filtering after the fact.
+3. Assert the law inside the test body; let the framework shrink failures to a minimal counter-example.
+4. Keep one or two example-based tests alongside for the named boundary cases (empty, single, max-length) the contract calls out.
+5. When a property fails, treat the shrunk counter-example as a new regression fixture before fixing the code.
+
+## Guardrails
+
+- Property tests complement, never replace, the boundary-case AND error-path tests every public function owes (test-discipline rule).
+- Use `pytest.approx` for float laws and `numpy.testing.assert_allclose` for array laws.
+- Name the test `test_<func>_<invariant>` so the law is legible from the test report.

package/skills/agent-dispatch/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: agent-dispatch
+description: Dispatch a claimed wave to a runtime per the V8 session-reuse ladder.
+argument-hint: "<wave-id> [--runtime=<id>]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# /agent-dispatch
+
+## v0.4 cross-links
+
+Dispatch resolves the wave's `RoleSpec` (`role`, `model`, `tools`, `isolation`) and renders the subagent's prompt from the wave's `agent_role` + the role's canonical contract. The dispatched session emits one `agent_end` report carrying an `EvidenceRecord` summary; the recorded evidence feeds the wave's `CloseReadiness`. When the operator pins a runtime preference, the choice persists via a `MEMORY` mutation (`MutationKind=update`) on the `Project` row so the next dispatch starts from the operator's pinned ladder.
+
+## Canonical algorithm
+
+1. Resolve the target `wave_id` (required; a missing id degrades to `status=needs_user`).
+2. Read the `Wave.runtime_preference` ladder (or an explicit `runtime_preference` arg); an explicit `runtime` arg overrides the ladder head.
+3. Surface the full ladder and the resolved head. No resolvable runtime is a soft `status=partial` (the dispatch can still proceed against the daemon default, but the operator can pin a preference).
+4. The daemon's `agent.dispatch` RPC is the canonical mutator; the skill routes to `eawf wave dispatch` via `next_valid_actions`.
+
+## Pre-flight checklist
+
+- [ ] The wave is claimed before dispatch.
+- [ ] The runtime ladder reflects how the planner sized the wave.
+
+## Decision surfaces
+
+A missing `wave_id` degrades to `status=needs_user`. When no runtime in the ladder resolves, the soft `status=partial` routes the operator to an `AskUserQuestion` prompt to pin a runtime preference rather than silently falling through to the daemon default.
+
+## Output contract
+
+Skill envelope with `header.skill = "/agent-dispatch"`. Body carries wave_id, runtime_preference, and resolved_runtime.

package/skills/audit/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: audit
+description: Fresh-context verification of a phase deliverable or wave outcome. Spawns a fresh auditor subagent that re-reads the diff against the success criteria.
+argument-hint: "<phase-id|wave-id|commit-range>"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# /audit
+
+## Canonical algorithm
+
+1. Resolve target: phase id, wave id, or commit range.
+2. Identify success criteria from the plan / phase spec and cite evidence with dense `[N]` references.
+3. Dispatch the auditor subagent with paths, line numbers, criteria.
+4. Parse the verdict; convert refutations into TODOs or new waves.
+5. Render audit evidence through `eawf audit show --md`.
+
+## v0.4 cross-links
+
+The auditor emits one `EvidenceRecord` per criterion (`evidence_kind` = `gate` | `claim` | `decision`). The aggregate verdict folds into the target wave / iter `CloseReadiness` projection — `/ship` reads the same projection so audit and ship share one source of truth on "is this iter actually closable?". Roles are pinned via `RoleSpec` (`role="auditor"`); fresh-context isolation stays a `RoleSpec` invariant, not an ad-hoc dispatch flag.
+
+## Pre-flight checklist
+
+- [ ] The auditor must NOT have access to the parent conversation.
+- [ ] Every quantitative claim must include source evidence and dense citation refs.
+- [ ] The target iter is NOT yet closed. Iter close is gated on `audit + polish + ship CI + PR review pass` per the `iter-phase-close-timing` rule in AGENTS.md; `/audit` runs before that close.
+
+## Decision surfaces
+
+On `pass-with-followups`: present the follow-up disposition (open backlog, open wave, defer) through `AskUserQuestion`. On `fail`: ask whether to halt the flow or open a remediation wave.
+
+## Output contract
+
+Skill envelope with a per-criterion verdict table and an aggregate status (`pass | pass-with-followups | fail`).

package/skills/blitz/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: blitz
+description: Auto-chained research follow-up skill with recursion guard for residual unknowns.
+argument-hint: "[--residual-unknowns=<n>]"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# /blitz
+
+## Canonical algorithm
+
+1. Read residual unknown count and follow-up research args.
+2. Increment the recursion guard (`EAWF_BLITZ_DEPTH_COUNTER`) against `EAWF_BLITZ_DEPTH` (default 8).
+3. Return a follow-up `/research` action with `blitz=false` so the next research pass does not recurse indefinitely.
+
+## Pre-flight checklist
+
+- [ ] Confirm `/research` produced more than one residual unknown.
+- [ ] Confirm recursion depth has not exceeded the configured cap.
+
+## Output contract
+
+Skill envelope with `header.skill = "/blitz"`. Body carries depth, depth_cap, residual_unknowns, followup_research_args, and next_actions.

package/skills/coauthor/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: coauthor
+description: Resolve the Co-Authored-By trailer policy for the active repo.
+argument-hint: "[--mode=runtime|project|disabled]"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# /coauthor
+
+## Canonical algorithm
+
+1. Read the `vcs.coauthor` config block (`mode` ∈ `runtime|project|disabled`) and the caller-supplied `mode` / `runtime` / `message_text` args.
+2. Run the canonical resolver (`resolve_coauthor_trailer`) to turn the config + the explicit runtime opt-in into a `Co-Authored-By:` trailer line (or `None` when trailers are disabled).
+3. On `mode=runtime` with no resolvable runtime (no explicit opt-in and no usable default identity), degrade to `status=needs_user` so the runtime adapter surfaces a `coauthor resolve` prompt rather than guessing.
+
+This skill is a thin surface over the shipped co-author policy machinery; it does not reimplement trailer resolution.
+
+## Pre-flight checklist
+
+- [ ] Never invent an author identity — `disabled` mode rejects an existing trailer in `message_text`.
+- [ ] No PII beyond the canonical author block.
+
+## Decision surfaces
+
+`status=needs_user` routes to a `coauthor resolve` `AskUserQuestion` when the runtime cannot be resolved.
+
+## Output contract
+
+Skill envelope with `header.skill = "/coauthor"`. Body carries mode, runtime, and the resolved trailer (or a reason on the needs_user path).

package/skills/compress/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: compress
+description: Compress the session conversation when context approaches the limit.
+argument-hint: "[--tokens-before=<n>] [--tokens-after=<n>] [--runtime=<id>]"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# /compress
+
+## Canonical algorithm
+
+1. Read `tokens_before` (required; missing/zero degrades to `status=needs_user`) and `tokens_after` (defaults to a no-op when omitted; clamped so a pass can only shrink the context).
+2. Build the per-runtime compression directive (cache-control wiring) for the target `runtime` (defaults to `claude-code`, the only runtime with a caller-side cache-control marker). An unknown runtime degrades to `status=needs_user`.
+3. Append the canonical `compression_emitted` event carrying the token deltas and the realised ratio so the telemetry projector can chart context pressure over a session.
+
+The model summarisation fan-out lives behind the runtime adapter's cache-control hook; the skill records the requested compression.
+
+## Pre-flight checklist
+
+- [ ] `tokens_before` is present and > 0.
+- [ ] The target runtime is a known runtime id.
+
+## Decision surfaces
+
+A missing/zero `tokens_before` or an unknown `runtime` degrades to `status=needs_user`, which routes the operator to an `AskUserQuestion` prompt for the missing input rather than emitting a compression event against an unresolved runtime.
+
+## Output contract
+
+Skill envelope with `header.skill = "/compress"`. Body carries tokens_before, tokens_after, ratio, runtime, and cache_control_applied.

package/skills/design/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: design
+description: Read-only design pass for an interactive surface: produces a statechart + action x context matrix + journey scenarios backed by an 11-rule lint contract. No state mutations.
+argument-hint: "<surface-slug> [--final] [--from-brief <path>]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# /design
+
+## Purpose
+
+Prevent the P20-I03 class of failure: a phase that audit-passes its declared criteria but breaks the lived user experience at runtime because a transition, a refresh trigger, or a multi-keystroke dispatch was never enumerated in the design step. `/design` produces a triangulated design spec — statechart + action x context matrix + journey scenarios — backed by a six-category event taxonomy, per-view liveness contracts, a multi-keystroke substate rule, cross-component contracts, and an 11-rule lint contract. It runs after `/research --final`, before `/roadmap propose`. Read-only: it writes only under `.ea/local/`.
+
+## Canonical algorithm
+
+1. Resolve the surface slug from the argument (or `AskUserQuestion` if absent). The slug suffixes the artifact stem: `<YYYY-MM-DD>-<surface>-design.md`.
+2. Round 1 — personas + goals. AUQ batch; every selected persona has
+   >=1 goal and every (persona, goal) gets a one-sentence success
+criterion.
+3. Round 2 — event sources + statechart + liveness contracts. AUQ batch. The six-category event taxonomy is mandatory; every long-lived view requires a liveness contract row; every multi-char key sequence requires a substate chain (never a flat `KEY_oH`).
+4. Round 3 — action x context matrix. AUQ batch. No blank cells (`-` is the only legal intentional no-op); matrix columns are parity-locked to statechart states.
+5. Round 4 — journey scenarios. AUQ batch. >=1 scenario per (persona x goal), >=1 time-advance scenario per long-lived view, plus edge scenarios per declared failure mode.
+6. Self-lint. Walk the 11-rule lint contract (L1..L11); round-close is gated on a lint pass.
+7. Write `.ea/local/research/<YYYY-MM-DD>-<surface>-design.md` using the artifact chassis and return the output envelope. On `--final` with residual unknowns > 0, emit a `/blitz` follow-up under the standard recursion guard.
+
+## The three load-bearing rigour mechanisms
+
+These are the additions over a generic statechart-plus-matrix doc; each catches one concrete P20-I03 defect at design-review time:
+
+- Per-view liveness contract — caught the live git pane that never rebound to a refresh trigger.
+- Six-category event taxonomy — caught the missing periodic tick (round 2 rejects close when a long-lived view declares no refresh trigger).
+- Multi-keystroke substate rule — caught the verb-prefix sequence wired flat (lint L6 rejects flat `KEY_oH` entries; the substate chain is mandatory).
+
+## Lint contract (L1..L11)
+
+Until the `eawf design lint <path>` binary lands, the skill agent walks the rules in-conversation at the end of rounds 3 and 4. A round does not close while any rule fails. The rules cover statechart/matrix parity (L1, L2), no surprise events (L3), no unfilled cells (L4), liveness-row completeness (L5), substate-backed multi-char keys (L6), scenario coverage (L7, L8), scrub-clean citations (L9), cross-component rows resolving to real test paths (L10), and append-only revisions (L11).
+
+## Design to audit loop
+
+When a phase touches an interactive surface, the ship-gate audit binds to the design artifact and adds criteria A1..A4 (every statechart `on:` clause, every non-`-` matrix cell, every Gherkin scenario, and every liveness contract has a covering test). Without this loop the design artifact becomes write-once advisory and the P20-I03 class recurs.
+
+## Pre-flight checklist
+
+- [ ] No state mutations — read-only; writes only under `.ea/local/`.
+- [ ] Surface slug matches the future wave / iter / phase prefix so dispatch renderers surface this brief.
+- [ ] Event taxonomy populated for all six categories (present or N/A with a one-sentence reason).
+- [ ] Statechart `on:` clauses complete; no named state has an unhandled named event.
+- [ ] Every long-lived view has a liveness contract row with all five fields.
+- [ ] Every multi-char key sequence is a substate chain — no flat `KEY_oH` entries.
+- [ ] Matrix has no blank cells; `-` is the only legal no-op value.
+- [ ] >=1 journey scenario per (persona x goal); >=1 time-advance scenario per long-lived view; edge scenarios per declared edge category.
+- [ ] Cross-component contracts list every cross-module event with its integration test path.
+- [ ] Lint L1..L11 all pass.
+- [ ] Citations repo-relative, external URL, or eawf URN — no absolute local paths, no host-local URLs, no PII.
+
+## Decision surfaces
+
+Every round's picks (personas, goals, event sources, statechart shape, matrix cells, scenarios) are surfaced through `AskUserQuestion` batches, never free-text. `/design` is convention-only: no state field, no `/roadmap propose` hard gate. The artifact is cited from the roadmap proposal body and from each wave dispatch prompt; dispatch renderers surface design artifacts under a `## Design references` section by filename match.
+
+## Output contract
+
+Eä-rendered skill envelope (`OutputEnvelope`) with `header.skill = "/design"`. Body carries the surface slug, the artifact path, the rounds completed, the declared / N/A event sources, the screen + long-lived-view counts, the matrix fill tally, the scenario count, the lint status, and any residual unknowns.

package/skills/differentiate/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: differentiate
+description: Recommend the cheapest experiment that discriminates between two or more candidate paths.
+argument-hint: "<candidate-id>"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# /differentiate
+
+## Canonical algorithm
+
+1. Take a candidate path and the alternatives under consideration.
+2. Identify the discriminating signal (`what would change my mind?`).
+3. Recommend the cheapest experiment that produces the signal.
+
+## Pre-flight checklist
+
+- [ ] Read-only — no state mutations.
+
+## Output contract
+
+Skill envelope listing the discriminating experiments and the recommended next move.

package/skills/extract-function/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: extract-function
+description: Model-only refactoring playbook for pulling a coherent block out of a long function into a named helper.
+argument-hint: ""
+user-invocable: false
+disable-model-invocation: false
+---
+
+# extract-function
+
+A model-only refactoring playbook. There is no slash command; the model invokes this to pull a coherent block out of a long function into a named helper.
+
+## When to reach for it
+
+- A function spans more than one screen and reads as several phases.
+- A comment introduces a block ("# now normalise the rows") — the comment is begging to become a function name.
+- The same computation appears in two places (DRY).
+
+## Canonical procedure
+
+1. Identify the block and the minimal set of variables it reads (inputs) and the single value it produces (output). If it produces two, that is two extractions.
+2. Name the helper for WHAT it returns, not how — `normalised_rows`, not `do_step_two`.
+3. Lift the block into a pure function where viable: explicit args in, explicit value out, no hidden state mutation.
+4. Replace the original block with a call; keep the surrounding function's shape so the diff is reviewable.
+5. Give the new helper full type hints, a docstring with a `Raises:` block if it can raise, and boundary + error-path tests if it is public.
+
+## Guardrails
+
+- Stop and reconsider if the helper needs four or more parameters — that often signals a missing value object, not a missing function.
+- Three similar lines are fine; do not extract a one-line helper used once (YAGNI / KISS).
+- Use named arguments once arity reaches three (explicit-over-implicit).