orchestrix-skills 0.6.0 → 0.8.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrix-skills",
-  "version": "0.1.0",
+  "version": "0.7.0",
   "description": "Capability-first AI development skill graph (Anthropic-native): plan → build with a warm-context orchestrator, contract-wired skills, and independent verification.",
   "author": "Orchestrix",
   "homepage": "https://orchestrix-mcp.youlidao.ai",

package/README.md

@@ -33,7 +33,9 @@ the build loop runs lights-out, gated only by objective `verify`.
 
 ```bash
 npx orchestrix-skills install            # default: Claude Code (.claude/skills/)
+npx orchestrix-skills install --ide codex # Codex (.codex/skills/ + AGENTS.md)
 npx orchestrix-skills install --ide cursor
+npx orchestrix-skills doctor --ide codex  # validate an installation
 ```
 
 This copies the skills into your runtime's skills dir and scaffolds `knowledge/`
@@ -44,6 +46,26 @@ your own API key. No server, no license.
 For Claude Code you can also install via the plugin marketplace:
 `/plugin install orchestrix-skills`.
 
+## Runtime adapters
+
+`skills/` is the runtime-neutral source of truth. `adapters/` describes how a
+runtime maps generic capabilities to its tools. During a Codex install the CLI
+removes Claude-only `allowed-tools`, preserves the Orchestrix contract, and adds
+Codex runtime guidance. If the target has an unmanaged `AGENTS.md`, its content
+is left untouched and the guidance is placed at `.codex/orchestrix/AGENTS.md`
+for manual merging. Installer-created guidance uses a marked Orchestrix block,
+so later installs refresh that block while preserving surrounding user
+instructions.
+
+`doctor` validates every installed Skill's required frontmatter, Codex
+transformation, configuration shape, knowledge directory, and active root
+guidance. A reference file that has not been merged into an existing root
+`AGENTS.md` is reported as unhealthy rather than silently treated as active.
+
+Codex uses isolated agents when the active session exposes them and otherwise
+runs leaf skills sequentially. Cursor and Windsurf remain reference-rule
+installs until those runtimes provide native compatible skill execution.
+
 ## How it works
 
 - **Every skill is a standard [Anthropic Agent Skill](https://agentskills.io/specification)**

package/adapters/claude/runtime.json

@@ -0,0 +1,13 @@
+{
+  "name": "claude",
+  "skillsDir": ".claude/skills",
+  "projectInstructions": "CLAUDE.md",
+  "nativeSkills": true,
+  "capabilities": {
+    "filesystem.read": "Read, Grep, Glob",
+    "filesystem.write": "Write, Edit",
+    "shell.execute": "Bash",
+    "web.read": "WebSearch, WebFetch",
+    "agent.spawn": "Task"
+  }
+}

package/adapters/codex/AGENTS.md

@@ -0,0 +1,11 @@
+<!-- orchestrix:start -->
+# Orchestrix runtime guidance
+
+- Use the skills installed under `.codex/skills/`; start end-to-end work with `orchestrate`.
+- Treat each skill's `metadata.contract` as Orchestrix workflow data. Codex skill selection still depends on `name` and `description`.
+- Resolve logical knowledge and work namespaces through `core-config.yaml`.
+- Map capability names in `metadata.requires.capabilities` to the tools available in the current Codex session.
+- When isolated agents are available, dispatch independent leaf skills concurrently and await them. Otherwise execute leaf skills sequentially in the current context, reading only their declared inputs before each step.
+- Independently run every objective verification command. Never accept an agent's success report as proof.
+- Keep runtime evidence at the fixed `.orchestrate/` path described by the `orchestrate` skill.
+<!-- orchestrix:end -->

package/adapters/codex/runtime.json

@@ -0,0 +1,13 @@
+{
+  "name": "codex",
+  "skillsDir": ".codex/skills",
+  "projectInstructions": "AGENTS.md",
+  "nativeSkills": true,
+  "capabilities": {
+    "filesystem.read": "runtime file tools or shell",
+    "filesystem.write": "runtime patch/edit tools",
+    "shell.execute": "runtime shell tool",
+    "web.read": "runtime web tools when enabled",
+    "agent.spawn": "optional collaboration tools; otherwise sequential fallback"
+  }
+}

package/bin/install.js

@@ -2,20 +2,31 @@
 // orchestrix-skills installer — zero dependencies.
 // Free path: copy skills into the runtime's skills dir + scaffold knowledge/.
 // No MCP, no license. Premium (hosted orchestrator / KB / 建造中心) is a separate opt-in.
-import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), "..");
+const MANAGED_START = "<!-- orchestrix:start -->";
+const MANAGED_END = "<!-- orchestrix:end -->";
+// Written into the skills dir after every successful install. Two consumers:
+// this installer (prunes skills it placed that the package no longer ships) and
+// hosts that auto-upgrade projects (compare `version` against the npm dist-tag
+// to decide whether to reinstall — no second version constant to maintain).
+const STAMP = ".orchestrix-skills.json";
 
 // Where each runtime auto-loads skills from (relative to the target project).
-const IDE_SKILLS_DIR = {
-  claude: ".claude/skills",
-  codex: ".codex/skills",
+function adapter(name) {
+  return JSON.parse(readFileSync(join(PKG, "adapters", name, "runtime.json"), "utf8"));
+}
+
+const RUNTIMES = {
+  claude: adapter("claude"),
+  codex: adapter("codex"),
   // Cursor / Windsurf don't auto-load Anthropic skills; they read rule files.
   // For those, skills are copied as reference rules (best-effort) until native support lands.
-  cursor: ".cursor/rules/orchestrix",
-  windsurf: ".windsurf/rules/orchestrix",
+  cursor: { skillsDir: ".cursor/rules/orchestrix", nativeSkills: false },
+  windsurf: { skillsDir: ".windsurf/rules/orchestrix", nativeSkills: false },
 };
 
 function arg(name, fallback) {
@@ -28,6 +39,7 @@ function help() {
 
 Usage:
   npx orchestrix-skills install [--ide claude|codex|cursor|windsurf] [--dir <project>]
+  npx orchestrix-skills doctor  [--ide claude|codex|cursor|windsurf] [--dir <project>]
 
 What it does (free, no license):
   1. Copies the skills into your runtime's skills dir (default: .claude/skills/)
@@ -37,21 +49,140 @@ Premium (hosted orchestrator, KB hosting, teams, 建造中心):
   see https://orchestrix-mcp.youlidao.ai`);
 }
 
+function transformSkill(source, runtime) {
+  if (runtime !== "codex") return source;
+  return source
+    .replace(/^allowed-tools:.*\n/m, "")
+    .replace(
+      /^(---\n\n# )/m,
+      "---\n\n<!-- Codex adapter: tool access is governed by the active session. Map metadata.requires capabilities to available tools. -->\n\n# ",
+    );
+}
+
+function packageVersion() {
+  return JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version;
+}
+
+function readStamp(target) {
+  try {
+    return JSON.parse(readFileSync(join(target, STAMP), "utf8"));
+  } catch {
+    return null; // absent, or written by a version that predates stamping
+  }
+}
+
+function installSkills(dir, runtimeName, runtime) {
+  const target = join(dir, runtime.skillsDir);
+  mkdirSync(target, { recursive: true });
+  const previous = readStamp(target);
+  const entries = readdirSync(join(PKG, "skills"), { withFileTypes: true });
+  for (const entry of entries) {
+    const source = join(PKG, "skills", entry.name);
+    const destination = join(target, entry.name);
+    if (!entry.isDirectory()) {
+      cpSync(source, destination);
+      continue;
+    }
+    mkdirSync(destination, { recursive: true });
+    for (const file of readdirSync(source, { withFileTypes: true })) {
+      if (file.isFile() && file.name === "SKILL.md") {
+        writeFileSync(join(destination, file.name), transformSkill(readFileSync(join(source, file.name), "utf8"), runtimeName));
+      } else {
+        cpSync(join(source, file.name), join(destination, file.name), { recursive: true });
+      }
+    }
+  }
+
+  const names = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  // Retire skills a PREVIOUS install of this package placed that it no longer
+  // ships. Only names recorded in our own stamp are candidates, so a skill the
+  // project or its host installed alongside ours is never touched.
+  let pruned = 0;
+  for (const name of previous?.skills ?? []) {
+    if (names.includes(name)) continue;
+    const stale = join(target, name);
+    if (!isDirectory(stale)) continue;
+    rmSync(stale, { recursive: true, force: true });
+    pruned += 1;
+  }
+  // Stamp LAST: a crash mid-copy leaves the older stamp in place, so the next
+  // run still sees a mismatch and reinstalls rather than declaring itself current.
+  writeFileSync(
+    join(target, STAMP),
+    `${JSON.stringify({ version: packageVersion(), ide: runtimeName, skills: names }, null, 2)}\n`,
+  );
+  return { count: names.length, pruned };
+}
+
+function installRuntimeGuidance(dir, runtimeName) {
+  if (runtimeName !== "codex") return;
+  const source = join(PKG, "adapters", "codex", "AGENTS.md");
+  const rootInstructions = join(dir, "AGENTS.md");
+  const referenceTarget = join(dir, ".codex", "orchestrix", "AGENTS.md");
+  mkdirSync(dirname(referenceTarget), { recursive: true });
+  cpSync(source, referenceTarget);
+  const guidance = readFileSync(source, "utf8");
+  if (!existsSync(rootInstructions)) {
+    writeFileSync(rootInstructions, guidance);
+    console.log("✓ AGENTS.md created with Codex runtime guidance");
+  } else {
+    const current = readFileSync(rootInstructions, "utf8");
+    const start = current.indexOf(MANAGED_START);
+    const end = current.indexOf(MANAGED_END);
+    if (start !== -1 && end > start) {
+      const updated = `${current.slice(0, start)}${guidance.trimEnd()}${current.slice(end + MANAGED_END.length)}`;
+      writeFileSync(rootInstructions, updated);
+      console.log("✓ Orchestrix block refreshed in AGENTS.md");
+    } else {
+      console.log("• AGENTS.md exists — left untouched; merge .codex/orchestrix/AGENTS.md to activate guidance");
+    }
+  }
+}
+
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function nonemptyFile(path) {
+  return isFile(path) && readFileSync(path, "utf8").trim().length > 0;
+}
+
+function validSkill(path, runtimeName, expectedName) {
+  if (!nonemptyFile(path)) return false;
+  const content = readFileSync(path, "utf8");
+  const frontmatter = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatter) return false;
+  if (!new RegExp(`^name:\\s*${expectedName}\\s*$`, "m").test(frontmatter[1])) return false;
+  if (!/^description:\s*\S.+$/m.test(frontmatter[1])) return false;
+  return runtimeName !== "codex" || !/^allowed-tools:/m.test(frontmatter[1]);
+}
+
 function install() {
   const ide = arg("ide", "claude");
   const dir = arg("dir", process.cwd());
-  const rel = IDE_SKILLS_DIR[ide];
-  if (!rel) {
-    console.error(`Unknown --ide "${ide}". Options: ${Object.keys(IDE_SKILLS_DIR).join(", ")}`);
+  const runtime = RUNTIMES[ide];
+  if (!runtime) {
+    console.error(`Unknown --ide "${ide}". Options: ${Object.keys(RUNTIMES).join(", ")}`);
     process.exit(1);
   }
 
   // 1. Skills (capabilities) — always refreshed.
-  const skillsTarget = join(dir, rel);
-  mkdirSync(skillsTarget, { recursive: true });
-  cpSync(join(PKG, "skills"), skillsTarget, { recursive: true });
-  const count = readdirSync(join(PKG, "skills"), { withFileTypes: true }).filter((d) => d.isDirectory()).length;
-  console.log(`✓ ${count} skills → ${rel}/`);
+  const { count, pruned } = installSkills(dir, ide, runtime);
+  console.log(`✓ ${count} skills → ${runtime.skillsDir}/ (v${packageVersion()})`);
+  if (pruned > 0) console.log(`✓ ${pruned} retired skill(s) removed`);
+  installRuntimeGuidance(dir, ide);
 
   // 2. Knowledge (the brain) — scaffold only if absent; never clobber the user's brain.
   const knowledgeTarget = join(dir, "knowledge");
@@ -77,6 +208,52 @@ function install() {
   console.log(`\nDone. Start with the "orchestrate" skill. Premium hosting: https://orchestrix-mcp.youlidao.ai`);
 }
 
+function doctor() {
+  const ide = arg("ide", "claude");
+  const dir = arg("dir", process.cwd());
+  const runtime = RUNTIMES[ide];
+  if (!runtime) {
+    console.error(`Unknown --ide "${ide}". Options: ${Object.keys(RUNTIMES).join(", ")}`);
+    process.exitCode = 1;
+    return;
+  }
+  const skillsTarget = join(dir, runtime.skillsDir);
+  const expectedSkills = readdirSync(join(PKG, "skills"), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+  const configPath = join(dir, "core-config.yaml");
+  const configContent = nonemptyFile(configPath) ? readFileSync(configPath, "utf8") : "";
+  const checks = [
+    ["skills directory", isDirectory(skillsTarget), skillsTarget],
+    [
+      `all ${expectedSkills.length} skills valid`,
+      expectedSkills.every((name) => validSkill(join(skillsTarget, name, "SKILL.md"), ide, name)),
+      skillsTarget,
+    ],
+    ["core config valid", /(^|\n)knowledge:\s*(#.*)?\n/.test(configContent) && /(^|\n)work:\s*(#.*)?\n/.test(configContent), configPath],
+    ["knowledge brain", isDirectory(join(dir, "knowledge")), join(dir, "knowledge")],
+  ];
+  if (ide === "codex") {
+    const reference = join(dir, ".codex", "orchestrix", "AGENTS.md");
+    const rootInstructions = join(dir, "AGENTS.md");
+    const referenceContent = nonemptyFile(reference) ? readFileSync(reference, "utf8") : "";
+    const rootContent = nonemptyFile(rootInstructions) ? readFileSync(rootInstructions, "utf8") : "";
+    checks.push(["Codex guidance reference", referenceContent.includes(MANAGED_START) && referenceContent.includes(MANAGED_END), reference]);
+    checks.push(["root AGENTS guidance active", rootContent.includes(MANAGED_START) && rootContent.includes(MANAGED_END), rootInstructions]);
+  }
+  let healthy = true;
+  for (const [label, ok, path] of checks) {
+    healthy &&= ok;
+    console.log(`${ok ? "✓" : "✗"} ${label}: ${path}`);
+  }
+  if (healthy) console.log(`\nHealthy: ${ide} installation is complete.`);
+  else {
+    console.error(`\nUnhealthy: run "orchestrix-skills install --ide ${ide} --dir ${dir}".`);
+    process.exitCode = 1;
+  }
+}
+
 const cmd = process.argv[2];
 if (cmd === "install") install();
+else if (cmd === "doctor") doctor();
 else help();

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "orchestrix-skills",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Capability-first AI development skill graph — Anthropic-native skills that run in any agent runtime.",
   "type": "module",
   "bin": {
     "orchestrix-skills": "bin/install.js"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "files": [
     "skills",
     "project-scaffold",
+    "adapters",
     "bin",
     ".claude-plugin"
   ],

package/project-scaffold/knowledge/taste/design-system.md

@@ -13,13 +13,23 @@ typography:
   typeface: "" # named (not Inter/Roboto unless deliberate + justified)
   scale: [] # real sizes/weights, e.g. [12/400, 14/400, 16/500, 24/600, 40/700]
   line_height: ""
-color: # roles, not framework swatches
+  measure: "" # target line length for running text, e.g. 65ch
+color: # roles, not framework swatches. THIS BLOCK IS THE LIGHT PALETTE.
   bg: ""
   surface: ""
   text: ""
-  accent: ""
-  states: { success: "", warning: "", error: "" }
-  contrast_floor: "" # e.g. WCAG AA 4.5:1 body text
+  accent: "" # the one brand hue. Never used to signal state.
+  states: { success: "", warning: "", error: "" } # semantic; must read as distinct from accent
+  contrast_floor: "" # e.g. WCAG AA — 4.5:1 body text, 3:1 UI + graphics
+theme:
+  modes: "" # light | dark | both. "both" = both are designed and reviewed, not inverted.
+  selection: "" # how a mode is chosen: OS preference | explicit user toggle | both
+  dark: # required when modes includes dark. Same roles, re-picked — never a naive inversion.
+    bg: ""
+    surface: ""
+    text: ""
+    accent: "" # must still meet contrast_floor on the dark ground
+    states: { success: "", warning: "", error: "" }
 space:
   scale: [] # e.g. [4, 8, 12, 16, 24, 32, 48, 64]
   density: "" # tight | airy, tied to the product
@@ -27,6 +37,9 @@ motion:
   timing: "" # e.g. 150ms enter / 100ms exit
   easing: ""
   use_where: "" # and where motion is deliberately absent
+  reduced_motion: "" # what prefers-reduced-motion removes, and what must still work without it
+focus:
+  visible_style: "" # the keyboard focus indicator every interactive element carries
 
 provenance: { source: design-system, added: "", approved_by: "" }
 ```

package/skills/README.md

@@ -1,4 +1,4 @@
-# Skills (v0.1)
+# Skills
 
 Capability-oriented skills, not role-oriented agents. Each skill is a single
 capability with a clear contract. The `orchestrate` skill wires them together by
@@ -14,6 +14,12 @@ SDK runtime reads `name` + `description` + `allowed-tools` and ignores
 `metadata.contract`, so each skill runs anywhere. Our orchestrator additionally
 reads `metadata.contract` to wire, gate, and verify.
 
+Runtime-neutral capability requirements live under
+`metadata.requires.capabilities` using names such as `filesystem.read`,
+`filesystem.write`, `shell.execute`, `web.read`, and optional `agent.spawn?`.
+Adapters map those names to runtime tools. Runtime-specific tool names are not
+part of the orchestration contract.
+
 ### The contract (6 fields)
 
 | Field         | Meaning                                            |
@@ -25,6 +31,16 @@ reads `metadata.contract` to wire, gate, and verify.
 | `verify`      | Objective, automated success check. Never skipped. |
 | `accept`      | Subjective human sign-off: `{ when, timing }`.     |
 
+**Optional entries** in `inputs` / `reads` / `updates` carry a trailing `?` and
+**must be quoted** — `"qa_feedback?"`, not `qa_feedback?`. A bare `?` inside a
+YAML flow sequence is not valid YAML; permissive loaders accept it, strict ones
+reject the whole file.
+
+**Names are semantic, not literal.** `inputs` name the role a skill needs
+(`story`, `diff`, `spec`); `outputs` name the artifact produced
+(`stories/<slug>.md`, `code_diff`). The orchestrator matches them by meaning —
+do not expect string equality when reading the graph.
+
 `accept.timing`:
 
 - `deferred` (default) — batch the human check at the end (lights-out middle).

package/skills/brainstorm/SKILL.md

@@ -4,6 +4,8 @@ description: Use before any build, when an idea or intent must become an agreed,
 license: MIT
 allowed-tools: [Read, Write, Grep, Glob]
 metadata:
+  requires:
+    capabilities: [filesystem.read, filesystem.write]
   contract:
     inputs: [intent, project_context]
     reads: [taste/*, architecture/*, registry/*]

package/skills/commit/SKILL.md

@@ -4,6 +4,8 @@ description: Use when verified work is ready to be recorded in version control.
 license: MIT
 allowed-tools: [Read, Bash]
 metadata:
+  requires:
+    capabilities: [filesystem.read, shell.execute]
   contract:
     inputs: [verified_changes, message_intent]
     reads: []

package/skills/deploy/SKILL.md

@@ -4,6 +4,8 @@ description: Use when an ACCEPTED deliverable must be shipped to a live environm
 license: MIT
 allowed-tools: [Read, Bash]
 metadata:
+  requires:
+    capabilities: [filesystem.read, shell.execute]
   contract:
     inputs: [accepted_deliverable, target]
     reads: [registry/deploy]

package/skills/design-architecture/SKILL.md

@@ -4,11 +4,13 @@ description: Use when a feature needs a new or changed architectural decision
 license: MIT
 allowed-tools: [Read, Write, Grep, Glob]
 metadata:
+  requires:
+    capabilities: [filesystem.read, filesystem.write]
   contract:
     inputs: [requirement, system_context]
     reads: [architecture/*, registry/api, registry/db]
     outputs: [specs/<slug>-arch.md]
-    updates: [architecture/decisions, registry/api?, registry/db?]
+    updates: [architecture/decisions, "registry/api?", "registry/db?"]
     authority: "Write to the specs namespace (default docs/specs/) and update the architecture KB / registry. No source code, no production."
     verify: "States the alternatives and the rationale; consistent with existing decisions (or explicitly supersedes one); no placeholder."
     accept:

package/skills/design-review/SKILL.md

@@ -4,12 +4,14 @@ description: Use after a UI feature is built and running, before merging, to rev
 license: MIT
 allowed-tools: [Read, Bash, Grep, Glob]
 metadata:
+  requires:
+    capabilities: [filesystem.read, shell.execute]
   contract:
-    inputs: [built_ui, ui_spec]
+    inputs: [built_ui, ui_spec, "screenshots?"]
     reads: [taste/design-system, taste/brand]
     outputs: [design_review_report]
-    authority: "Read-only on code; render and screenshot the running UI. No edits, no commits, no production."
-    verify: "Report is based on actual rendered screens (screenshots), not inferred from source; contains both verdicts (spec compliance AND visual quality)."
+    authority: "Read-only on code. Start and stop the app locally to render it, and drive it via browser automation or HTTP. No edits, no commits, no deploy, no external spend."
+    verify: "Every verdict rests on a rendered artifact, not on source; each objective check reports pass, fail, or untested-with-reason — never a pass without its evidence; contains all three verdicts (spec compliance, rendering + accessibility, visual quality); any process this skill started was cleaned up."
     accept:
       when: "never — findings route back to implement; the human reviews at the end batch."
       timing: deferred
@@ -18,45 +20,153 @@ metadata:
 # Design Review
 
 Review a built UI with a senior designer's eye. The visual counterpart of
-`review-code`: two verdicts, in order — does it match the spec, then is it
-world-class.
+`review-code`: three verdicts, in order — does it match the spec, does it
+actually render correctly, and is it world-class.
 
 **Core principle:** You cannot review design from source. Render it and look at
 the pixels. A claim about how it looks, without a screenshot, is a guess — the
 visual equivalent of claiming tests pass without running them.
 
+## The Iron Law
+
+```
+UNRENDERED IS NOT PASSED. Every check ends in exactly one of:
+pass (with evidence) | fail (with evidence) | untested (with the reason)
+```
+
+A review run without a browser is a partial review, and says so. It is never a
+clean one.
+
 ## Inputs
 
-- `built_ui` — the running app (url / dev server / screenshots of each screen).
-- `ui_spec` — `specs/<slug>-ui.md` it must satisfy.
+- `built_ui` — the running app (a live URL, or a dev server this skill starts).
+- `ui_spec` — `specs/<slug>-ui.md` it must satisfy, including its declared
+  **treatment** (`utility` / `product` / `editorial`).
+- `screenshots?` — captures a prior `smoke-test` already took. Use them instead
+  of relaunching the app for the same screen.
 - Read `taste/design-system` + `taste/brand` — the bar to calibrate against.
   Deviations from the system are higher severity, not lower.
 
-## Look at the real thing first
-
-Render every screen and state in the spec (loading, empty, error too). Capture
-screenshots. Review those, not the CSS.
+## How to render (do this before any verdict)
+
+Prefer what already exists: if `screenshots` covers a screen, do not relaunch
+the app for it. When you must launch it yourself, follow the same protocol
+`smoke-test` uses — it is the same hazard.
+
+1. **Discover how to run it.** `registry/app` first; else the project's manifest
+   (`package.json` scripts, `Makefile`, `README`). Genuinely unguessable → every
+   render-dependent check is `untested: cannot launch`. Do not invent a server.
+2. **Launch in the background, capture logs** to
+   `.orchestrate/verify/design-review-server.log`. Record the PID. Pick a free
+   port if configurable, to avoid colliding with anything already running.
+3. **Wait for readiness, bounded** — poll the health endpoint / port / ready
+   line for up to ~60s. Not ready → the checks are `failed: app did not start`,
+   attach the server log, skip to cleanup.
+4. **Render** every screen and state in the spec (loading, empty, error too), in
+   every mode under the system's `theme.modes`, with the best driver available:
+   - **Browser automation** (a Playwright/Chrome MCP tool, if available in this
+     session) — the only driver that can reach computed style, keyboard focus,
+     a media-query override, or a viewport change.
+   - **Handed-in screenshots** — enough for layout, hierarchy, contrast, and the
+     greyscale check; not enough for focus, computed font, or media queries.
+   - **No driver at all** — state it once, mark the dependent checks `untested`,
+     and still deliver Verdict 1 and every judgment call the spec supports.
+5. **Capture evidence per screen** to
+   `.orchestrate/verify/design-review-<screen>-<mode>.png` (or `.log`).
+6. **ALWAYS clean up** — kill only the processes you started, and remove temp
+   state you created. Cleanup runs even when checks fail.
+
+Record which modes you actually rendered. An unrendered mode is `untested`,
+never a passing one.
+
+## When the design system predates these fields
+
+A `taste/design-system` written before `theme`, `focus.visible_style`, and
+`motion.reduced_motion` existed will not carry them — and an upgrade never
+rewrites an existing brain, so this is the normal case for any project older
+than those fields. **A missing field is unspecified, not satisfied:**
+
+| Missing                 | Assume                                | Consequence                                                                     |
+| ----------------------- | ------------------------------------- | ------------------------------------------------------------------------------- |
+| `theme` / `theme.modes` | light-only                            | Render light. Do not fail a dark mode that was never designed.                  |
+| `color.contrast_floor`  | WCAG AA — 4.5:1 text, 3:1 UI/graphics | Still measure. Label the floor `assumed` in the report.                          |
+| `focus.visible_style`   | any clearly visible indicator         | Check 3 still runs; only the specific style is unspecified.                     |
+| `motion.reduced_motion` | all non-essential animation stops     | Check 5 still runs.                                                              |
+
+Every assumption goes in the report's `assumptions` list, so the human sees
+which bar was applied. Raise the gap **once** as a `Minor` finding so the system
+gets backfilled — never once per screen.
 
 ## Verdict 1 — Spec compliance
 
 For each screen/flow/state in `ui_spec`: present and correct, missing, or wrong.
 Missing a screen or a non-happy state → spec verdict FAIL.
 
-## Verdict 2 — Visual quality
+## Verdict 2 — Rendering & accessibility (objective)
+
+These are measurements, not opinions. Measure them; do not eyeball them. Each
+check reports `pass`, `fail`, or `untested` with its reason — **a check you
+could not run is never a pass.** The `needs` tag names what the check requires;
+without it, the check is `untested`. Any failure here is at least **Important**;
+anything that makes content unreadable or a control unreachable is **Critical**.
+
+1. **Themes** *(needs: a render per declared mode)*. Render each screen in every
+   declared mode. Also render the *un-stamped* default state — where no explicit
+   theme is selected and only the OS preference applies — because a color
+   defined solely inside a `[data-theme]` or media block never applies there,
+   and the page renders one theme's text on the other theme's ground. Any text,
+   icon, border, or focus ring that vanishes or loses contrast in one mode is a
+   defect in that mode.
+2. **Contrast** *(needs: a screenshot or computed style)*. Compute the ratios
+   against `contrast_floor` for body text and for UI/graphic elements, in every
+   rendered mode. Report the number, not an impression.
+3. **Keyboard focus** *(needs: browser)*. Tab through every screen. Every
+   interactive element has a visible focus indicator, focus order follows visual
+   order, and no element traps focus. An invisible focus ring is Critical.
+4. **Overflow** *(needs: browser — viewport resize)*. At the narrowest supported
+   width, the page body must not scroll horizontally. Wide content — tables,
+   code, charts, diagrams — scrolls inside its own container. Check for
+   overlapping or clipped elements at each tested width.
+5. **Reduced motion** *(needs: browser — media override)*. Render with
+   `prefers-reduced-motion: reduce`. Animation is removed or reduced, and
+   nothing becomes unusable or permanently invisible — scroll-reveal content
+   that never reveals is Critical.
+6. **Fonts actually loaded** *(needs: browser — computed style)*. Confirm the
+   system's named typeface is the one rendering, not a silent fallback to a
+   system face. Compare computed `font-family` against what actually painted.
+7. **Spacing integrity** *(needs: a screenshot + the spacing scale)*. Gaps
+   between sibling groups match the scale — no collapsed or doubled margins, no
+   ad-hoc values off the scale.
+8. **State without color** *(needs: a screenshot)*. Convert it to greyscale. If
+   success, warning, and error can no longer be told apart, state is encoded in
+   color alone — a defect, not a style.
+
+## Verdict 3 — Visual quality (judgment)
 
 Against the design system and world-class craft:
 
+- **Treatment match.** Compare against the treatment the spec declared. Flag
+  both directions: a `product` screen built with no hierarchy or presence, and a
+  `utility` screen wearing a hero, decorative motion, or ornament it did not
+  earn. **Over-design is a finding, at the same severity as under-design.**
 - **Hierarchy** obvious in one glance? **Spacing** on the system's scale?
 - **Consistency** with the system's type/color/tokens? Drift = defect.
 - Is the **memorable-thing** actually visible here?
 - **Non-happy states** real, not stubs (loading/empty/error)?
+- **Copy** — do labels, confirmations, empty states, and errors match the spec
+  and `taste/brand`? A control whose label and confirmation use different verbs,
+  an error that only apologizes, or shipped placeholder text are all findings.
 - **Interaction quality** — jank, slow transitions, layout shift?
 
 ### Anti-slop check
 
-Flag any AI-default tell: Inter/Roboto where the system says otherwise ·
-purple-blue gradient heroes · three-column rounded-card grids · default Tailwind
-swatches · drop shadows on everything · emoji as icons · generic everything.
+Flag any AI-default tell. The canonical list lives in the `design-system` skill;
+short form: warm cream + serif + terracotta · near-black with one acid-green or
+vermilion pop · purple-to-blue gradient hero · default framework swatches ·
+Inter / Roboto / Space Grotesk where the system says otherwise · three-column
+rounded-card grids · accent rail on a rounded card · `rounded-lg` and drop
+shadows on everything · emoji as icons · everything centered · `01 / 02 / 03`
+numbering on content that is not a sequence.
 
 Rate each finding **Critical** (must fix) · **Important** (fix before merge) ·
 **Minor** (note it).
@@ -64,20 +174,56 @@ Rate each finding **Critical** (must fix) · **Important** (fix before merge) ·
 ## Output: `design_review_report`
 
 ```yaml
+coverage: partial # full | partial — partial whenever any check is untested
+driver: browser # browser | screenshots | none
+themes_rendered: [light] # modes actually rendered; [] if none
+assumptions: ["contrast_floor absent from taste/design-system — applied WCAG AA 4.5:1"]
 spec_compliance: pass # pass | fail
+rendering_a11y: # one verdict per check: pass | fail | untested (+ reason)
+  themes: pass
+  contrast: fail
+  focus: untested — no browser driver in this session
+  overflow: untested — no browser driver in this session
+  reduced_motion: untested — no browser driver in this session
+  fonts: untested — no browser driver in this session
+  spacing: pass
+  state_without_color: pass
 missing: [<screen/state not built>]
 findings:
-  - { severity: Important, screen: settings, issue: "...", fix: "...", shot: "..." }
+  - {
+      severity: Important,
+      kind: rendering, # spec | rendering | a11y | visual | treatment | copy | anti-slop
+      screen: settings,
+      mode: dark,
+      issue: "...",
+      evidence: "measured 3.1:1 against a 4.5:1 floor",
+      fix: "...",
+      shot: ".orchestrate/verify/design-review-settings-dark.png",
+    }
 verdict: changes_requested # approved | changes_requested
+cleanup: "started pid 48213, killed" # or "nothing started"
 ```
 
 ## Rules
 
-- **Evidence-based.** Every finding names the screen and, where possible, a
-  screenshot. No "looks off" without showing it.
+- **Evidence-based.** Every finding names the screen and, where applicable, the
+  theme mode and a screenshot. Objective findings carry the measurement. No
+  "looks off" without showing it.
+- **`untested` never rounds up.** Do not infer a check from the CSS, from a
+  neighbouring screen, or from what the framework "usually" does. If `coverage`
+  is `partial`, say which checks are missing in one line — an `approved` verdict
+  must never imply coverage it does not have.
 - **Don't pre-judge.** Surface deviations; don't excuse one because the spec or a
   deadline pushed it.
 - **Findings route back, not to the human.** Critical/Important go to `implement`
   (re-run with this report as `qa_feedback`). The human sees the result at the
   end-of-run acceptance.
-- If it's clean and on-system, say so plainly and approve.
+- If it's clean, on-system, and on-treatment, say so plainly and approve.
+
+## Red flags — stop
+
+- Reporting `pass` on a check you could not run
+- A measurement (contrast, computed font) stated without the number
+- Leaving a dev server you started still running after the report
+- Failing a dark mode the design system never declared
+- Raising the same missing-KB-field finding once per screen

package/skills/design-system/SKILL.md

@@ -4,12 +4,14 @@ description: Use when a project has no design direction yet, or must (re)establi
 license: MIT
 allowed-tools: [Read, Write, WebSearch, Grep, Glob]
 metadata:
+  requires:
+    capabilities: [filesystem.read, filesystem.write, web.read]
   contract:
-    inputs: [product_context, references?]
+    inputs: [product_context, "references?"]
     reads: [taste/brand, taste/design-system]
     outputs: [taste/design-system, taste/brand]
     authority: "Author the durable design KB (taste/design-system, taste/brand). High-authority, audited (knowledge write). No source code, no production."
-    verify: "Specific, not generic: a named typeface, real type/space scales, named reference products, one memorable-thing. Covers type + color + space + motion. No AI-default tells (see anti-slop)."
+    verify: "Specific, not generic: a named typeface, real type/space scales, named reference products, one memorable-thing. Covers type + color + theme + space + motion + focus. Every mode listed under theme.modes has a full palette. No AI-default tells (see anti-slop)."
     accept:
       when: "Always — the aesthetic direction is foundational and brand-defining."
       timing: inline
@@ -47,27 +49,72 @@ point of view BEFORE specifying anything:
 ## Specify the system (specifics, not adjectives)
 
 - **Typography** — a named typeface (not Inter/Roboto unless deliberate and
-  justified), a type scale with real sizes/weights, line-height rules.
+  justified), a type scale with real sizes/weights, line-height rules, and the
+  target measure for running text (~65 characters).
 - **Color** — a real palette with roles (bg, surface, text, accent, states), not
-  default framework swatches; state the contrast floor.
+  default framework swatches; state the contrast floor as a number.
+  **Accent and semantic color are two different systems.** The accent is the one
+  brand hue; success/warning/error carry meaning. If the accent doubles as
+  "success", state cannot be read at a glance — pick again.
+- **Theme** — decide `light | dark | both`, and how a mode is selected (OS
+  preference, an explicit user toggle, or both). If dark is in scope, specify a
+  **second full palette, role for role**. A dark palette is re-picked, not
+  inverted: an accent that holds 4.5:1 on white usually fails on near-black.
+  Deciding light-only is allowed — but it must be written down as a decision, so
+  `design-review` knows there is nothing else to check.
 - **Space** — a spacing scale; density posture (tight/airy) tied to the product.
 - **Layout** — grid and composition principles; how hierarchy is created.
-- **Motion** — timing, easing, and where motion is used (and where it is not).
+- **Motion** — timing, easing, where motion is used (and where it is not), and
+  what `prefers-reduced-motion` removes while keeping the UI usable.
+- **Focus** — the keyboard focus indicator every interactive element carries. An
+  invisible focus ring is a broken system, not a style choice.
 
-## Anti-slop (forbidden defaults — name and avoid)
+## Anti-slop (the canonical list — `design-ui` and `design-review` check it too)
 
-Inter/Roboto by default · purple-blue gradient heroes · three-column
-rounded-card feature grids · drop shadows on everything · default Tailwind
-palette (blue-500…) · emoji as product icons · centered everything · gradients /
-glassmorphism with no reason. If a choice is one of these, it must be a
-deliberate, justified decision — not a default.
+AI-generated design converges on a small set of looks. These are not banned —
+they are **disqualified as defaults**. Picking one is allowed only as a stated,
+justified decision, never as where you landed without choosing.
+
+**Palettes** — warm cream ground (`#F4F1EA` and neighbors) with a serif display
+and a terracotta accent · near-black with one acid-green or vermilion pop ·
+purple-to-blue gradient hero on white · default framework swatches
+(`blue-500`, `slate-800`, …).
+
+**Type** — Inter, Roboto, or Space Grotesk as the "safe" face · a display face
+used at body sizes so its personality never shows.
+
+**Layout** — three-column rounded-card feature grids · an accent bar/rail down
+the side of a rounded card · `rounded-lg` on everything · drop shadow on
+everything · everything centered · broadsheet hairline rules over dense columns.
+
+**Ornament** — emoji as product icons or section markers · `01 / 02 / 03`
+numbering on content that is not actually a sequence · gradients or
+glassmorphism with no reason.
+
+Structural devices must encode something true. Number a set of steps only when
+order is information the reader needs; otherwise the numbers are decoration
+pretending to be structure.
 
 ## Output: the durable KB (structured, with provenance)
 
 Write `taste/design-system` and `taste/brand` as structured entries (per the
 knowledge format: terse, chunked, each with `source`/`added`/`approved_by`).
 Record the memorable-thing, the references, the one distinctive rule, and each
-specified token/scale. This is the source `design-ui` reads.
+specified token/scale. Leave no field of the seed blank: `theme`,
+`motion.reduced_motion`, and `focus.visible_style` are decisions, and a blank
+one reads to `design-review` as unspecified rather than as "not needed". This is
+the source `design-ui` reads.
+
+**Backfilling an older system.** An upgrade refreshes skills but never rewrites
+an existing `knowledge/` — that brain belongs to the project. So a system
+authored before `theme`, `focus.visible_style`, `motion.reduced_motion`, and
+`typography.measure` existed will simply be missing them, and `design-review`
+will report every dependent check against an assumed bar. When you re-run on
+such a project, add those fields rather than re-authoring the whole system:
+keep every existing value untouched, fill only the gaps, and give the new
+entries their own `added` date and approver. Adding a dark palette to a
+light-only product is a real design decision — put it through the same accept
+gate as the rest, don't infer it.
 
 ## Self-critique before done
 

package/skills/design-ui/SKILL.md

@@ -4,13 +4,15 @@ description: Use when a feature has a user interface, to design its screens and
 license: MIT
 allowed-tools: [Read, Write, Grep, Glob]
 metadata:
+  requires:
+    capabilities: [filesystem.read, filesystem.write]
   contract:
     inputs: [requirement, ui_context]
     reads: [taste/design-system, taste/brand]
     outputs: [specs/<slug>-ui.md]
-    updates: [taste/design-system?, taste/brand?]
+    updates: ["taste/design-system?", "taste/brand?"]
     authority: "Write to the specs namespace (default docs/specs/) and design assets. No source code, no production."
-    verify: "Every screen and flow maps to a requirement; expresses the design system (not generic defaults); passes the designer's-eye self-critique."
+    verify: "Every screen and flow maps to a requirement; a treatment is declared and held to; expresses the design system (not generic defaults); copy and non-happy states are specified for every screen; the design plan passed its critique before the spec was written."
     accept:
       when: "Visual direction — the look is foundational; everything downstream builds on it."
       timing: inline
@@ -34,33 +36,107 @@ aesthetic — that is exactly how product consistency dies.
 Carry the system's **memorable-thing** and **distinctive rule** through every
 screen. If this feature can't express them, say so.
 
+## Treatment — declare one before designing
+
+Craft is constant. Visual ambition is not. **Over-design is a defect, not
+enthusiasm**: a settings page with a full-bleed hero is as wrong as a landing
+page without one. Pick exactly one treatment for this feature, write it at the
+top of the spec, and hold every screen to it. `design-review` checks the built
+UI against the treatment you declared, so declaring `utility` and shipping
+ornament is a finding.
+
+| Treatment   | Use for                                              | Budget                                                                                                                     |
+| ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `utility`   | internal tools, admin, settings, dense data screens   | Information design only. Real hierarchy, spacing on the scale, system palette. No hero, no decorative motion, no ornament.   |
+| `product`   | the core user-facing surfaces — **the default**       | Full system expression. The memorable-thing is present but quiet. Motion is functional: state changes, transitions, feedback. |
+| `editorial` | marketing, landing, launch, first-run onboarding      | Opinionated composition. One deliberate aesthetic risk, spent in one place; everything around it stays quiet.                 |
+
+When the requirement doesn't say, use `product`. Escalating to `editorial` is a
+choice you must justify in one sentence in the spec.
+
 ## Process
 
-1. **Map screens to requirements.** Every screen/state must trace to a
+1. **Map screens to requirements.** Every screen and state must trace to a
    requirement. Cut the rest (YAGNI).
-2. **Apply the system, don't restate it.** Use its typeface, scale, palette,
-   spacing, motion. Reuse existing components/tokens before proposing new ones.
-3. **Specify each screen:** purpose, layout and hierarchy, the system tokens
+2. **Write the design plan, then attack it — before specifying anything.**
+   Three to five lines: the treatment, the system tokens this feature leans on,
+   the layout concept, and where the memorable-thing shows up. Then read it back
+   and ask: *would this same plan work, unchanged, for any other feature in any
+   other product?* Whatever survives that substitution is generic — revise it,
+   and record in the spec what you changed and why. Catching this in the plan is
+   far cheaper than catching it in a finished spec.
+3. **Apply the system, don't restate it.** Use its typeface, scale, palette,
+   spacing, motion. Reuse existing components and tokens before proposing new
+   ones.
+4. **Specify each screen:** purpose, layout and hierarchy, the system tokens
    used, and the non-happy states — loading, empty, error. These are where UIs
    actually fail.
-4. **Show, don't just tell.** When a layout choice is clearer shown than
-   described, produce a mockup/wireframe, not prose.
+5. **Specify the copy** for every screen — see below. A screen whose labels are
+   unwritten is not specified.
+6. **Cover every theme the system declares.** If `theme.modes` is `both`, each
+   screen's spec names the tokens it uses, not literal colors, and calls out any
+   place the two palettes need different treatment (elevation, dividers, images
+   on a dark ground). If the system is light-only, say so once and move on.
+7. **Show, don't just tell.** When a layout choice is clearer shown than
+   described, produce a mockup or wireframe, not prose.
+
+## Copy is design material
+
+Words are part of the design, not filler dropped in later. Read `taste/brand`
+for voice, then write the actual strings:
+
+- **Name things the way the user names them**, not the way the system is built.
+  A person manages *notifications*, not *webhook config*.
+- **A control says exactly what happens.** Button `Publish` → toast `Published`.
+  Label and confirmation must use the same verb.
+- **Errors state what went wrong and what to do next.** No apologies, no
+  "something went wrong", no error code alone.
+- **Empty states say what goes here and how to get the first one**, not "No
+  data".
+- Active voice. Specific beats clever. Never ship lorem ipsum or placeholder
+  text into a spec — write the real string or mark it `TODO: copy`.
+
+## When the surface is operated, not read
+
+A dashboard, console, or tool is scanned and acted on, not read top to bottom.
+For those screens the craft shifts from typography to information design:
+
+- Summary before detail. What needs attention resolves in one glance.
+- **Encode state in form, not only in number** — a pill, a chip, a severity
+  stripe. Color alone is not an encoding; it fails for color-blind users and in
+  a screenshot.
+- **Semantic color (success / warning / error) is separate from the accent hue**
+  and never counts as your accent.
+- Charts and sparklines get the same care as type: a considered fill, a faint
+  grid, an emphasized endpoint. Numbers in columns get tabular figures.
+- What is interactive must look interactive.
 
 ## Anti-slop (forbidden defaults)
 
-No Inter/Roboto unless the system says so · no purple-blue gradient heroes · no
-three-column rounded-card grids by reflex · no default Tailwind swatches · no
-drop shadows on everything · no emoji as icons. A default is only allowed as a
-deliberate, justified choice.
+The canonical list lives in the `design-system` skill; `design-review` checks
+the same one. Short form — none of these may be where you landed without
+choosing: warm cream + serif + terracotta · near-black with one acid-green or
+vermilion pop · purple-to-blue gradient hero · default framework swatches ·
+Inter / Roboto / Space Grotesk as the safe face · three-column rounded-card
+grids · accent rail on a rounded card · `rounded-lg` and drop shadows on
+everything · emoji as icons · everything centered · `01 / 02 / 03` numbering on
+content that is not a sequence.
+
+A default is only allowed as a deliberate, justified choice — and any deviation
+from `taste/design-system` needs the same justification.
 
 ## Designer's-eye self-critique (mandatory gate before done)
 
-Look at the result and ask:
+The plan critique in step 2 catches generic direction. This catches generic
+execution. Look at the result and ask:
 
 - Does this look like it could ship from {the named references}, or like a
   generic AI UI? If the latter, fix it.
 - Is hierarchy obvious in one glance? Is spacing on the scale? Is the
   memorable-thing visible here?
+- **Does the ambition match the declared treatment** — nothing under-designed,
+  and nothing decorated past its budget?
+- Every screen: loading, empty, error specified? Copy written, not placeholder?
 - Did any anti-slop tell sneak in?
 
 Fix until it passes. This is the visual equivalent of `run-tests` — don't claim
@@ -71,13 +147,20 @@ done without running it.
 ```markdown
 # <Feature> — UI Spec
 
+## Treatment — utility | product | editorial, and why (one sentence).
+
+## Design plan — the plan from step 2, plus what the critique changed and why.
+
 ## Screens — each: purpose, the requirement it serves, layout + hierarchy.
 
 ## Flows — how the user moves between screens.
 
 ## States — loading / empty / error for each screen.
 
-## System use — tokens/components used; how the memorable-thing shows up here.
+## Copy — the real strings per screen: labels, confirmations, empties, errors.
+
+## System use — tokens/components used; theme coverage; how the
+memorable-thing shows up here.
 
 ## New patterns — anything the system lacked, with rationale (candidate for KB).
 ```

package/skills/draft-story/SKILL.md

@@ -4,9 +4,11 @@ description: Use when a feature request or requirement must become an implementa
 license: MIT
 allowed-tools: [Read, Write, Grep, Glob]
 metadata:
+  requires:
+    capabilities: [filesystem.read, filesystem.write]
   contract:
     inputs: [requirement, context]
-    reads: [taste/coding-standards, registry/api, registry/db, front-end-spec?]
+    reads: [taste/coding-standards, registry/api, registry/db, "front-end-spec?"]
     outputs: [stories/<slug>.md]
     authority: "Write one flat story file in the stories namespace (physical path from core-config.yaml; default docs/stories/). No folders. No source code. No production. No spend."
     verify: "Every requirement maps to at least one acceptance criterion; constraints are copied verbatim; no placeholders (no TBD/TODO/'handle edge cases')."

package/skills/implement/SKILL.md

@@ -4,8 +4,10 @@ description: Use when implementing a feature or bugfix from a spec with acceptan
 license: MIT
 allowed-tools: [Read, Write, Edit, Bash]
 metadata:
+  requires:
+    capabilities: [filesystem.read, filesystem.write, shell.execute]
   contract:
-    inputs: [story, acceptance_criteria, scope, qa_feedback?]
+    inputs: [story, acceptance_criteria, scope, "qa_feedback?"]
     reads: [taste/coding-standards, registry/api, registry/db]
     outputs: [code_diff, ac_traceability, test_files]
     authority: "Write src/ and tests/. No production, no deploy, no network spend."

package/skills/investigate/SKILL.md

@@ -4,8 +4,10 @@ description: Use when something is broken and the CAUSE is unknown — a repeate
 license: MIT
 allowed-tools: [Read, Bash, Grep, Glob]
 metadata:
+  requires:
+    capabilities: [filesystem.read, shell.execute]
   contract:
-    inputs: [symptom, context?, prior_attempts?]
+    inputs: [symptom, "context?", "prior_attempts?"]
     reads: [registry/architecture, taste/coding-standards]
     outputs: [root_cause_report]
     authority: "Read code and run diagnostics/reproductions. Temporary instrumentation is allowed but MUST be reverted before finishing. No fixes — the fix belongs to a re-dispatched implement."

package/skills/map-codebase/SKILL.md

@@ -2,10 +2,12 @@
 name: map-codebase
 description: Use when entering an EXISTING codebase (brownfield) before designing or changing anything — build an evidence-based map of its architecture, conventions, and hazards.
 license: MIT
-allowed-tools: [Read, Bash, Grep, Glob]
+allowed-tools: [Read, Write, Bash, Grep, Glob]
 metadata:
+  requires:
+    capabilities: [filesystem.read, filesystem.write, shell.execute]
   contract:
-    inputs: [repo_path, focus?]
+    inputs: [repo_path, "focus?"]
     reads: []
     outputs: [codebase_map, registry_updates]
     authority: "Read-only on source; non-mutating commands only (ls, grep, git log, test discovery). Writes go ONLY to the registry/* namespace (physical path from core-config.yaml; default knowledge/registry/)."

package/skills/orchestrate/SKILL.md

@@ -4,9 +4,11 @@ description: Use when a goal must be delivered end-to-end by composing skills, w
 license: MIT
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Task]
 metadata:
-  version: 5
+  version: 6
+  requires:
+    capabilities: [filesystem.read, filesystem.write, shell.execute, "agent.spawn?"]
   contract:
-    inputs: [intent, constraints?]
+    inputs: [intent, "constraints?"]
     reads: [core-config, skill-registry, taste/*]
     outputs: [accepted_deliverable, run_ledger]
     authority: "Dispatch leaf skills, each within its own authority. Do not directly touch source, production, or spend — leaf skills do that, gated. Enforce every accept gate."
@@ -34,21 +36,22 @@ no step above intent.
 1. **Bind intent.** Read the human's goal and constraints. This is the only
    place intent enters. Then run the first-run preflight (below) before any
    wiring.
-2. **Select.** Read the skill registry. Pick skills by their `description`
-   (when-to-use). Load a skill's full `contract` only when it is a candidate —
-   never load every contract at once.
+2. **Select.** Read the skill registry (the `description:` line of every
+   SKILL.md in the runtime's skills directory). Pick skills by that
+   when-to-use description. Load a skill's full `contract` only when it is a
+   candidate — never load every contract at once.
 3. **Wire (emergent, not hardcoded).** Build the path by matching one skill's
    `outputs` to the next skill's `inputs`. Skills do not know each other; only
    you do. Do not assume a fixed pipeline — wire what this intent needs.
 4. **Dispatch.** Hand the skill exactly the `inputs` it declares, as files —
    resolving each logical namespace it reads/writes to a physical path via
-   `core-config.yaml` (see Namespace resolution). Run
-   it as a fresh subagent for isolation. Choose the cheapest model that can do
-   the step. **Dispatch independent steps in PARALLEL** (whose `inputs` don't
-   depend on each other) — as concurrent FOREGROUND subagents awaited together in
-   the same turn, for speed. Keep dependent steps sequential. NEVER fire-and-forget
-   a background subagent and end the turn waiting to be woken — run foreground and
-   await; there is no reliable async wake.
+   `core-config.yaml` (see Namespace resolution). If the runtime supports isolated
+   agents, run each leaf as a fresh dispatch and choose the cheapest capable model.
+   Dispatch independent steps concurrently and await them in the same turn; keep
+   dependent steps sequential. Never fire-and-forget a background agent. If the
+   runtime has no isolated-agent capability, execute leaves sequentially in the
+   current context, reloading only the declared inputs before each step. Isolation
+   is preferred; it is not required for correctness.
 5. **Verify (gate) — executable, not prose.** Prove the skill's `verify` with a
    REAL command you run yourself via Bash, and capture the proof:
 
@@ -66,8 +69,12 @@ no step above intent.
 6. **Accept (gate).** Apply the rule below. Then continue — do not pause to ask
    "should I keep going?" mid-run.
 7. **Repeat** 3–6 until the intent is fulfilled.
-8. **Final acceptance.** Present the batched deferred accepts and a final review
-   to the human, once. Apply corrections (see Metabolism), then deliver.
+8. **Final acceptance.** FIRST re-read the intent from the `run_start` ledger
+   line and check the assembled result against IT — every step passing its own
+   verify does not prove the composition serves the intent (steps can each be
+   right while the whole drifts). Then present the batched deferred accepts and
+   a final review to the human, once. Apply corrections (see Metabolism), then
+   deliver.
 
 ## Namespace resolution (`core-config.yaml`)
 
@@ -112,6 +119,27 @@ resolved paths):
 
 Both checks are per-run and idempotent: a populated brain makes them no-ops.
 
+## Hard wiring rules (what emergence cannot reach)
+
+Output→input matching wires most of the graph. Two skills it structurally
+CANNOT reach — wire these by rule, not by match:
+
+1. **`smoke-test` is the acceptance floor for runnable apps.** Nothing in the
+   graph outputs its `flows` or `run_instructions`, so no output→input match
+   will ever select it. If the deliverable is a runnable app or service and
+   this run changed it, wire `smoke-test` before final acceptance and derive
+   its inputs yourself: `flows` from the story's acceptance criteria (or from
+   the intent, when there is no story), `run_instructions` from `registry/app`
+   (or the project's own manifest). `run-tests` proves functions; `smoke-test`
+   proves the product — green unit tests are not this evidence. A `failed` or
+   `untested` verdict is a real result: carry it into final acceptance
+   verbatim, never round it up to passed.
+2. **`design-system` comes before `design-ui`.** `design-ui` READS
+   `taste/design-system` — it never produces it. If UI work is wired and the
+   resolved `taste/design-system` namespace is empty, wire `design-system`
+   first; otherwise `design-ui` dresses a project that has a brand in generic
+   defaults.
+
 ## Accept gate
 
 | Skill's `accept.timing` | Skill's `authority`                                               | Action                                                                                        |
@@ -139,8 +167,9 @@ aimed at a symptom re-rolls the dice.
 STOP the run — do not burn a 4th attempt. Write a `gate` event to the ledger
 (`{"e":"gate","kind":"rework_exhausted","question":"step <n> (<skill>) failed 3
 attempts: <one-line why>"}`), summarize the three failures for the human, and
-report AWAIT. A step that cannot pass its own verify after three tries needs a
-human decision (wrong approach, wrong spec, or wrong verify), not more tokens.
+stop for their decision. A step that cannot pass its own verify after three
+tries needs a human (wrong approach, wrong spec, or wrong verify), not more
+tokens.
 
 ## Metabolism — governed writeback
 
@@ -179,13 +208,18 @@ platform renders it as live progress). It is append-only JSONL: one JSON event
 per line, appended with `Bash` (`echo '<json>' >> .orchestrate/ledger.jsonl`).
 Never rewrite or delete lines. Timestamps: `date -u +%FT%TZ`.
 
+**Quoting hazard:** the single-quoted `echo` breaks on `'` inside the JSON —
+and a mangled line corrupts the run's only durable memory. Keep every free-text
+field (`intent`, `question`, `title`) to one line with no single quotes:
+rephrase (`don't` → `do not`) before writing, never fight the shell escaping.
+
 Events and when to write them:
 
 | Event | When | Shape |
 | ----- | ---- | ----- |
 | `run_start` | right after binding intent | `{"e":"run_start","run":"r-<yyyymmdd>-<slug>","intent":"...","ts":"..."}` |
 | `plan` | after wiring the graph, and EVERY time the graph changes | `{"e":"plan","run":"...","steps":[{"n":1,"skill":"research","title":"..."}, …]}` — full current plan; latest `plan` line wins; steps may be added, never removed |
-| `step` | immediately BEFORE each dispatch, and again after its verify | `{"e":"step","run":"...","n":3,"skill":"implement","status":"dispatched\|done\|failed","attempt":1,"evidence":"<file or one-line result>","ts":"..."}` — rework = same `n`, next `attempt` |
+| `step` | immediately BEFORE each dispatch, and again after its verify | `{"e":"step","run":"...","n":3,"skill":"implement","status":"dispatched\|done\|failed\|skipped","attempt":1,"evidence":"<file or one-line result>","ts":"..."}` — rework = same `n`, next `attempt`; a step a replan made obsolete gets `skipped` with the reason in `evidence` (plan lines are never removed, so this is how an obsolete step closes) |
 | `gate` | when stopping at a human gate | `{"e":"gate","run":"...","kind":"inline_accept","question":"...","ts":"..."}` |
 | `run_end` | at delivery or abandonment | `{"e":"run_end","run":"...","result":"delivered\|paused\|abandoned","ts":"..."}` |
 
@@ -194,6 +228,24 @@ step is required and should be the step's verify log path
 (`.orchestrate/verify/step-<n>-attempt-<k>.log`); a `done` with no evidence is
 a false claim.
 
+## Resume — cold re-entry (deterministic, not from memory)
+
+Whenever you enter with an existing ledger — after compaction, an interrupted
+session, or a wake-up — do NOT continue from what you remember. Replay:
+
+1. Read `.orchestrate/ledger.jsonl`. The active run is the last `run_start`
+   with no matching `run_end`. Its `intent` line — not your recollection — is
+   what you are delivering. No active run → this is a fresh start.
+2. Rebuild state from events alone: the latest `plan` wins; `done` and
+   `skipped` steps are closed; prior `attempt` values count toward each step's
+   cap of 3.
+3. **A dangling `dispatched`** (no `done`/`failed`/`skipped` after it) means
+   that attempt was cut off mid-flight. Trust it in NEITHER direction: run that
+   step's verify command now. Pass → append its `done` with the evidence.
+   Fail → re-dispatch as the next attempt.
+4. Continue the loop from the first open step. If the run was stopped at a
+   `gate`, re-ask that gate's question — never assume it was answered.
+
 ## Context discipline (stay lean)
 
 - **Files, not paste.** Move artifacts between steps as files. Never paste a
@@ -209,6 +261,8 @@ a false claim.
 - Hardcoding a fixed skill order instead of wiring outputs→inputs
 - Pasting a step's full output into your context instead of handing a file
 - Re-dispatching a step the ledger already marks done
+- Resuming from memory instead of replaying the ledger — or trusting a
+  dangling `dispatched` in either direction without running its verify
 - Dispatching a step without first writing its `dispatched` ledger line
 - Ending a run without a `run_end` ledger line
 - Marking a step done on the subagent's say-so, without your own verify command
@@ -217,4 +271,7 @@ a false claim.
 - Appending to `taste/*` without reading it first (duplicate/contradiction risk)
 - Dispatching a design/build skill in an existing codebase while `registry/*`
   is empty (first-run preflight skipped)
+- Delivering a runnable app this run changed with no `smoke-test` verdicts
+  (unit tests are not that evidence)
+- Dispatching `design-ui` while the resolved `taste/design-system` is empty
 - Marking the run complete without every step's `verify` evidence

package/skills/research/SKILL.md

@@ -2,8 +2,10 @@
 name: research
 description: Use when a planning or design decision needs external facts — market, competitor, feasibility, or a library/tech choice — before committing.
 license: MIT
-allowed-tools: [Read, WebSearch, WebFetch]
+allowed-tools: [Read, Write, WebSearch, WebFetch]
 metadata:
+  requires:
+    capabilities: [filesystem.read, filesystem.write, web.read]
   contract:
     inputs: [question, scope]
     reads: []

package/skills/review-code/SKILL.md

@@ -4,6 +4,8 @@ description: Use after implementing a task or feature and before merging, to che
 license: MIT
 allowed-tools: [Read, Bash, Grep, Glob]
 metadata:
+  requires:
+    capabilities: [filesystem.read, shell.execute]
   contract:
     inputs: [diff, spec]
     reads: [taste/coding-standards]

package/skills/run-tests/SKILL.md

@@ -4,8 +4,10 @@ description: Use before claiming any work is complete, fixed, or passing, and be
 license: MIT
 allowed-tools: [Read, Bash]
 metadata:
+  requires:
+    capabilities: [filesystem.read, shell.execute]
   contract:
-    inputs: [target, expected_outcome?]
+    inputs: [target, "expected_outcome?"]
     reads: []
     outputs: [verification_report]
     authority: "Run test, lint, and build commands. Read-only on source. No edits, no production."

package/skills/smoke-test/SKILL.md

@@ -4,8 +4,10 @@ description: Use when the deliverable is a runnable app or service and its real
 license: MIT
 allowed-tools: [Read, Bash, Grep, Glob]
 metadata:
+  requires:
+    capabilities: [filesystem.read, shell.execute]
   contract:
-    inputs: [run_instructions, flows, qa_feedback?]
+    inputs: [run_instructions, flows, "qa_feedback?"]
     reads: [registry/app]
     outputs: [smoke_report, verify_evidence]
     authority: "Start and stop the app locally; drive it via browser automation, HTTP, or CLI. Read-only on source. No deploy, no external spend, no mutations outside the app's own local state."