@christang/keel 5.1.1

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@christang/keel",
+  "displayName": "Keel",
+  "description": "Keel OpenSpec execution discipline CLI for Claude Code, Codex, and OpenCode.",
+  "version": "5.1.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanglmChris/keel.git"
+  },
+  "bin": {
+    "keel": "bin/keel.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "src/core/",
+    "assets/",
+    "README.md",
+    "plugins/"
+  ],
+  "scripts": {
+    "validate": "node scripts/run_python.js scripts/validate_plugin.py",
+    "test": "node scripts/run_python.js scripts/validate_plugin.py --all"
+  },
+  "dependencies": {
+    "@fission-ai/openspec": "^1.4.1"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "allowScripts": {
+    "@fission-ai/openspec@1.6.0": true
+  }
+}

package/plugins/keel/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "keel",
+  "version": "5.1.1",
+  "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
+  "author": {
+    "name": "TanglmChris",
+    "url": "https://github.com/TanglmChris"
+  },
+  "repository": "https://github.com/TanglmChris/keel",
+  "license": "MIT",
+  "keywords": [
+    "openspec",
+    "workflow",
+    "keel",
+    "discipline"
+  ]
+}

package/plugins/keel/.codex-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "keel",
+  "version": "5.1.1",
+  "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
+  "author": {
+    "name": "TanglmChris",
+    "url": "https://github.com/TanglmChris"
+  },
+  "repository": "https://github.com/TanglmChris/keel",
+  "license": "MIT",
+  "keywords": [
+    "openspec",
+    "workflow",
+    "keel",
+    "discipline"
+  ],
+  "skills": "./skills/",
+  "agents": "./agents/",
+  "interface": {
+    "displayName": "Keel",
+    "shortDescription": "OpenSpec execution discipline for coding agents",
+    "longDescription": "Keel packages reusable OpenSpec authoring and execution skills: expectation alignment before specs and tasks finalize, task-capsule discipline, deterministic gate usage, review, debugging, and handoff hygiene. The separately installed keel CLI owns context, gates, schema, and overlays.",
+    "developerName": "TanglmChris",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive"
+    ]
+  }
+}

package/plugins/keel/agents/keel-single-task-goal-claude.md

@@ -0,0 +1,16 @@
+---
+name: keel-single-task-goal-claude
+description: Thin Claude activation adapter for one authorized OpenSpec task; single /goal within the 4,000-character budget with read-only subagent helpers only.
+target: claude
+role: single-task-goal-activation
+---
+
+# keel-single-task-goal-claude
+
+Thin Claude adapter for the `keel-run-single-task-goal` skill. It activates one `/goal` for exactly one authorized OpenSpec task and never introduces a scheduler, global Stop hook, agent team, or cross-task authority.
+
+- Activation: compile the view with `keel project goal --target claude --change C --task T --json`; the goal condition stays within the 4,000-character budget, and Keel refuses activation rather than omit Acceptance, fingerprint, or stop authority.
+- Evidence: Claude's evaluator is transcript-only, so surface every command result and gate outcome before any success claim; only `keel gate task-complete` plus the current agent's durable checkbox complete the task.
+- Helpers: Claude subagents are used only as bounded read-only evidence producers via `keel project helper`; they carry no write, delegation, acceptance, or completion authority, and their returns are accepted only after repository byte identity.
+- Stop: terminate after one task on completion, drift, blocker, or premature native success; continuing requires a new explicit authorization and start fingerprint.
+- Fallback: with disabled hooks, managed policy, or missing trust, report and run the identical manual Keel loop.

package/plugins/keel/agents/keel-single-task-goal-codex.md

@@ -0,0 +1,16 @@
+---
+name: keel-single-task-goal-codex
+description: Thin Codex activation adapter for one authorized OpenSpec task; bounded goal execution with read-only subagent helpers only.
+target: codex
+role: single-task-goal-activation
+---
+
+# keel-single-task-goal-codex
+
+Thin Codex adapter for the `keel-run-single-task-goal` skill. It activates one bounded goal for exactly one authorized OpenSpec task and never introduces a scheduler, global stop hook, agent team, or cross-task authority.
+
+- Activation: compile the view with `keel project goal --target codex --change C --task T --json`, then follow the single-task goal lifecycle. Where no callable goal surface exists, surface the exact command and treat the capability as advisory.
+- Ownership: the current agent stays the sole writer and owns Review, gates, the checkbox, and completion; a native evaluator success never completes the task.
+- Helpers: Codex subagents are used only as bounded read-only evidence producers via `keel project helper`; they carry no write, delegation, acceptance, or completion authority, and their returns are accepted only after repository byte identity.
+- Stop: terminate after one task on completion, drift, blocker, or premature native success; continuing requires a new explicit authorization and start fingerprint.
+- Fallback: without a callable Codex surface, run the identical manual Keel loop.

package/plugins/keel/hooks/hooks.json

@@ -0,0 +1,30 @@
+{
+  "description": "Keel plugin hooks: non-blocking SessionStart projection and the manifest-gated PreToolUse write guard, both backed by the shared keel CLI contract.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/session-start.js"],
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/pretooluse-guard.js"],
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/keel/scripts/pretooluse-guard.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+"use strict";
+
+// Keel plugin PreToolUse write guard: deterministic denial of out-of-Touch
+// file edits while an explicit keel/guard.json manifest is active. Absence of
+// the manifest allows everything silently; a present-but-untrusted manifest
+// fails closed. The hook never writes state, never spawns the keel CLI, and
+// always exits 0 — denial is expressed only through hook output. Paths that
+// resolve outside the repository root are not product writes and pass through.
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const MANIFEST_SCHEMA = "keel-write-guard/v1";
+const FILE_EDIT_TOOLS = new Map([
+  ["Edit", "file_path"],
+  ["Write", "file_path"],
+  ["NotebookEdit", "notebook_path"],
+]);
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function deny(reason) {
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: reason,
+      },
+    })}\n`
+  );
+}
+
+function sha256(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+function manifestShapeValid(manifest) {
+  return (
+    manifest
+    && manifest.schema === MANIFEST_SCHEMA
+    && typeof manifest.change === "string"
+    && manifest.change !== ""
+    && typeof manifest.task === "string"
+    && manifest.task !== ""
+    && Array.isArray(manifest.touch)
+    && manifest.touch.length > 0
+    && manifest.touch.every((item) => typeof item === "string" && item !== "")
+    && Array.isArray(manifest.authority)
+    && manifest.authority.length > 0
+    && manifest.authority.every(
+      (item) =>
+        item
+        && typeof item.path === "string"
+        && /^[0-9a-f]{64}$/.test(String(item.sha256 || ""))
+    )
+  );
+}
+
+function globPattern(value) {
+  const escaped = value.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(
+    `^${escaped
+      .replace(/\*\*/g, "\u0000")
+      .replace(/\*/g, "[^/]*")
+      .replace(/\u0000/g, ".*")}$`
+  );
+}
+
+function pathAllowed(candidate, touch) {
+  return touch.some((entry) => {
+    const normalized = entry.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (normalized.endsWith("/")) return candidate.startsWith(normalized);
+    if (normalized.includes("*")) return globPattern(normalized).test(candidate);
+    return candidate === normalized;
+  });
+}
+
+function main() {
+  let event = {};
+  try {
+    event = JSON.parse(readStdin() || "{}");
+  } catch {
+    event = {};
+  }
+  const repo =
+    typeof event.cwd === "string" && event.cwd ? event.cwd : process.cwd();
+  const manifestPath = path.join(repo, "keel", "guard.json");
+  if (!fs.existsSync(manifestPath)) return 0;
+
+  const pathField = FILE_EDIT_TOOLS.get(event.tool_name);
+  if (!pathField) return 0;
+
+  let manifest = null;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch {
+    manifest = null;
+  }
+  if (!manifestShapeValid(manifest)) {
+    deny(
+      "Keel write guard: keel/guard.json is present but invalid, so file "
+        + "edits fail closed. Run `keel guard clear`, then `keel gate "
+        + "task-start` and `keel guard start` to reauthorize."
+    );
+    return 0;
+  }
+  const pointer = `${manifest.change}#${manifest.task}`;
+
+  for (const entry of manifest.authority) {
+    const file = path.join(repo, entry.path);
+    let fresh = null;
+    try {
+      fresh = sha256(fs.readFileSync(file));
+    } catch {
+      fresh = null;
+    }
+    if (fresh !== entry.sha256) {
+      deny(
+        `Keel write guard: task authority drift detected for ${pointer} `
+          + `(${entry.path} changed since guard start), so file edits fail `
+          + "closed. Re-run `keel gate task-start` and `keel guard start` to "
+          + "reauthorize, or `keel guard clear` to stop enforcement."
+      );
+      return 0;
+    }
+  }
+
+  const target = event.tool_input ? event.tool_input[pathField] : null;
+  if (typeof target !== "string" || !target) return 0;
+  const relative = path.relative(repo, path.resolve(repo, target));
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    return 0;
+  }
+  const candidate = relative.replace(/\\/g, "/");
+  if (pathAllowed(candidate, manifest.touch)) return 0;
+
+  deny(
+    `Keel write guard: ${candidate} is outside Touch for ${pointer}. `
+      + `Touch allows: ${manifest.touch.join(", ")}. Stop and report an `
+      + "Out-of-scope Need, update the task authority and reauthorize via "
+      + "`keel gate task-start` and `keel guard start`, or run "
+      + "`keel guard clear` to stop enforcement."
+  );
+  return 0;
+}
+
+process.exit(main());

package/plugins/keel/scripts/session-start.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+"use strict";
+
+// Keel plugin SessionStart projection: disposable context only.
+// OpenSpec and Git stay the durable authority; this script never writes
+// state, selects an ambiguous owner, records a fingerprint, creates a goal,
+// or blocks the session. It always exits 0.
+//
+// The projection is source-aware: a compact start reinjects the recomputed
+// task pointer (selection, recorded Contract fingerprint, next command) that
+// a summary is most likely to lose, a resume start reinjects the selection,
+// and startup, clear, or any unknown source falls back to the generic view.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const TIMEOUT_MS = Number(process.env.KEEL_HOOK_TIMEOUT_MS || 8000) || 8000;
+const MAX_REASONS = 3;
+const MAX_REASON_LENGTH = 300;
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function emit(context) {
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: context,
+      },
+    })}\n`
+  );
+}
+
+function runKeel(cwd, args) {
+  const cli = (process.env.KEEL_CLI || "keel").trim();
+  return spawnSync(`${cli} ${args.join(" ")}`, {
+    cwd,
+    shell: true,
+    encoding: "utf8",
+    timeout: TIMEOUT_MS,
+  });
+}
+
+function fallback(reason) {
+  emit(
+    `Keel hook fallback: ${reason} Run \`keel context\` manually; `
+      + "OpenSpec and Git remain the durable authority."
+  );
+}
+
+function main() {
+  let event = {};
+  try {
+    event = JSON.parse(readStdin() || "{}");
+  } catch {
+    event = {};
+  }
+  const cwd =
+    typeof event.cwd === "string" && event.cwd ? event.cwd : process.cwd();
+
+  if (!fs.existsSync(path.join(cwd, "openspec"))) {
+    return 0;
+  }
+
+  const version = runKeel(cwd, ["--version"]);
+  const versionMatch = String(version.stdout || "").match(/(\d+)\.\d+\.\d+/);
+  if (
+    version.error
+    || version.status !== 0
+    || !versionMatch
+    || Number(versionMatch[1]) < 3
+  ) {
+    fallback(
+      "the keel CLI is missing or incompatible with this plugin; install "
+        + "@christang/keel (npm install -g @christang/keel)."
+    );
+    return 0;
+  }
+
+  const result = runKeel(cwd, ["context", "--json"]);
+  if (result.error || result.status !== 0 || !String(result.stdout || "").trim()) {
+    fallback("`keel context --json` failed or timed out.");
+    return 0;
+  }
+  let context;
+  try {
+    context = JSON.parse(result.stdout);
+  } catch {
+    fallback("keel produced malformed context output.");
+    return 0;
+  }
+
+  const source = typeof event.source === "string" ? event.source : "";
+  const reinject = source === "compact" || source === "resume";
+  const header = source === "compact"
+    ? "Keel post-compaction reinjection (disposable; recomputed from OpenSpec and Git):"
+    : source === "resume"
+      ? "Keel resume reinjection (disposable; recomputed from OpenSpec and Git):"
+      : "Keel session projection (disposable; OpenSpec and Git are the durable authority):";
+
+  const lines = [header];
+  if (context.status === "ready" && context.selection) {
+    const task = context.selection.task ? `#${context.selection.task}` : "";
+    lines.push(
+      `- context ready: ${context.selection.change}${task} `
+        + `(${context.selection.source}); next action: `
+        + `${context.nextAction ? context.nextAction.kind : "unknown"}.`
+    );
+    if (reinject) {
+      const recorded = recordedContract(cwd, context.selection);
+      if (recorded) {
+        lines.push(
+          `- recorded Contract fingerprint: ${recorded} (recorded, not `
+            + "verified; gates recompile and compare before any write)."
+        );
+      }
+      lines.push(
+        "- next: re-run `keel context --json`, then `keel gate task-start` "
+          + "before continuing implementation; nothing was selected or "
+          + "recorded by this projection."
+      );
+    } else {
+      if (Array.isArray(context.read) && context.read.length > 0) {
+        lines.push(`- read first: ${context.read.slice(0, 5).join(", ")}.`);
+      }
+      lines.push(
+        "- run `keel gate task-start` before implementation; this projection "
+          + "selects nothing and records nothing."
+      );
+    }
+  } else {
+    lines.push(`- context status: ${context.status || "unknown"}.`);
+    for (const reason of (context.reasons || []).slice(0, MAX_REASONS)) {
+      lines.push(`- reason: ${String(reason).slice(0, MAX_REASON_LENGTH)}`);
+    }
+    lines.push(
+      "- next: run `keel context` and select an owner explicitly; this hook "
+        + "does not guess among candidates."
+    );
+  }
+  emit(lines.join("\n"));
+  return 0;
+}
+
+function recordedContract(repo, selection) {
+  if (!selection || !selection.change || !selection.task) return null;
+  const tasksPath = path.join(
+    repo,
+    "openspec",
+    "changes",
+    selection.change,
+    "tasks.md"
+  );
+  let content = "";
+  try {
+    content = fs.readFileSync(tasksPath, "utf8");
+  } catch {
+    return null;
+  }
+  const wanted = String(selection.task);
+  let inTask = false;
+  for (const line of content.split(/\r?\n/)) {
+    const heading = line.match(/^\s*-\s+\[[ xX]\]\s+(\d+(?:\.\d+)+)\s+/);
+    if (heading) {
+      inTask = heading[1] === wanted;
+      continue;
+    }
+    if (!inTask) continue;
+    const contract = line.match(/^\s*-\s*Contract:\s*(sha256:[0-9a-f]{64})\b/);
+    if (contract) return contract[1];
+  }
+  return null;
+}
+
+process.exit(main());

package/plugins/keel/skills/keel-align-expectations/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: keel-align-expectations
+description: Align explicit requirements, implicit expectations, non-goals, observable acceptance, evidence, and decision authority before OpenSpec specs and executable tasks finalize. Use when authoring or updating a proposal, design, specs, or tasks, or when a request hides a material product choice. Do not use for routine implementation of an already-authorized task, unrelated conversation, or facts the repository can answer.
+---
+
+# keel-align-expectations
+
+## Purpose
+
+Turn user intent and repository facts into durable OpenSpec authority before specs and executable tasks harden. Alignment is risk-scaled: clear, complete, low-risk requests pass through a compact quick path; material ambiguity switches to a focused deep path. This skill owns materiality routing, acceptance authority, and write-back ownership; how questions are presented interactively is the host runtime's concern, and it does not replace `/opsx:apply`, review, or OpenSpec artifact mechanics.
+
+## Routing
+
+Take the quick path when the request, repository facts, and intended observable outcome are coherent and no material choice is unresolved. Switch to the deep path when a choice can materially change: user-visible behavior, an external interface, acceptance, security/privacy/permission boundaries, data loss or migration, protocol/state/timing/reset semantics, generated equivalence, irreversible cost, a dependency or architecture commitment, or when a contradiction appears between user intent and repository facts.
+
+Missing wording, stylistic preference, discoverable facts, and reversible implementation detail stay on the quick path. For routine implementation of an authorized task, unrelated conversation, or a factual question the repository answers, do not start a product interview and do not mutate OpenSpec artifacts.
+
+## Quick path
+
+State the extracted goals, non-goals, observable Acceptance, constraints, and evidence expectations compactly, label any non-material assumptions, and proceed. A complete low-risk request may satisfy the checkpoint in one compact confirmation without an interactive pause.
+
+## Deep path
+
+Pause spec/task finalization and ask one material decision at a time. Each question explains in plain terms why the decision matters and provides a recommended answer. Continue only until executable authority is clear; do not run a broad brainstorming session. A material choice that stays unresolved becomes a Q<n> with an owner or resolution gate, and no affected task becomes executable until it is accepted, verified, durably owned, or explicitly discarded.
+
+## Implicit expectations are proposals
+
+Label inferred expectations (accessibility, compatibility, failure behavior, migration, performance, security, and similar unstated candidates) as candidate expectations and explain their impact. A candidate becomes authority only when the user explicitly accepts it or durable repository/product authority verifies it. Silence does not authorize a material product choice, interface change, risk boundary, or acceptance downgrade.
+
+## Repository facts before user questions
+
+Before asking the user, inspect the relevant code, tests, docs, OpenSpec artifacts, issues, and verified runtime behavior. Record verified facts as F<n> with their basis; escalate only the user-owned product choice that remains after the facts are known. When sources disagree on an acceptance-relevant fact, surface the contradiction and ask who or what has authority instead of silently choosing one source.
+
+## Write-back
+
+Accepted alignment routes to existing OpenSpec owners; create no separate alignment ledger, chat-memory dependency, or HANDOFF payload:
+
+- proposal.md owns motivation, scope, goals, and non-goals.
+- design.md owns accepted D/F/A/Q statements, rationale, constraints, and risks.
+- specs own observable requirements and positive/negative/edge/failure scenarios.
+- tasks.md owns Covers, verification strategy and checks, scope, and stop boundaries that reference the accepted authority instead of duplicating chat prose.
+
+## Domain references
+
+When the change touches a specific domain, read only the applicable reference before asking domain questions; do not load the others:
+
+- references/web.md for UI, API, routing, auth/session, persistence, or backend integration work.
+- references/hardware.md for Verilog/SystemVerilog interface, protocol, reset, or verification work.
+- references/hardware-dsl.md for hardware modeling DSL, generated RTL, or golden/equivalence work.
+
+## Boundaries
+
+Alignment does not implement code, expand Touch, change selected-task acceptance, replace `keel-review-checklist`, or own follow-ups. If implementation later discovers a new material expectation, stop and return to OpenSpec authoring before continuing.

package/plugins/keel/skills/keel-align-expectations/references/hardware-dsl.md

@@ -0,0 +1,21 @@
+# Hardware DSL alignment reference
+
+Domain lens for hardware modeling DSL work. Use during alignment when generated RTL, golden output, or model equivalence assumptions may be implicit.
+
+## Material risk surface
+
+Treat these as deep-path candidates when the change touches them: DSL syntax or semantics, generated RTL, generated tests, regeneration order, golden output, equivalence expectations, lowering rules, scheduling, reset semantics, valid-ready mapping, CSR generation, naming stability, and artifact ownership. Ask only questions that materially affect Acceptance, verification checks, Touch, specs, design decisions, or non-goals; stop when the task contract can be written without guessing.
+
+## Durable placement
+
+- specs for observable DSL behavior and generated artifact expectations.
+- design.md for lowering decisions, regeneration policy, equivalence rationale, conflict authority, and baseline policy.
+- tasks.md for Covers, verification, Touch, stop/autonomy details, and Coupling when source and generated artifacts must change together.
+
+## Evidence expectations
+
+Prefer reproducible evidence: golden output or snapshot evidence when generated artifacts are deterministic; regeneration commands when source changes must update generated RTL or tests; equivalence or behavioral checks when generated output must preserve model semantics; coupled-task evidence when DSL source, generated artifacts, and baselines must be evaluated as one candidate.
+
+## Execution and review checks
+
+While implementing and reviewing, keep source and generated artifacts moving as one candidate: after any DSL or lowering change, re-run the full regeneration command and commit-or-diff every regenerated artifact — a hand-edited generated file is a defect, not a fix. Prove semantics with equivalence or behavior checks rather than diff-silence alone, and treat golden output updates as decisions needing a recorded rationale. In review, reject changes where generated RTL, generated tests, or baselines moved without their DSL source (or vice versa), and confirm naming and interface stability expectations still hold after regeneration.

package/plugins/keel/skills/keel-align-expectations/references/hardware.md

@@ -0,0 +1,21 @@
+# Hardware alignment reference
+
+Domain lens for Verilog/SystemVerilog work. Use during alignment when hardware protocol, timing, reset, or verification assumptions may be implicit.
+
+## Material risk surface
+
+Treat these as deep-path candidates when the change touches them: signals, module interfaces, reset, valid-ready, backpressure, ordering, arbitration, CSR or protocol fields, CDC, reset crossing, timing assumptions, security/permission paths, random behavior, keys, authentication, and testbench/formal expectations. Ask only questions that materially affect Acceptance, verification checks, Touch, specs, design decisions, or non-goals; stop when the task contract can be written without guessing.
+
+## Durable placement
+
+- specs for observable protocol behavior, ordering guarantees, register/CSR behavior, and error cases.
+- design.md for timing assumptions, reset/CDC rationale, arbitration choices, verification strategy, and trade-offs.
+- tasks.md for Covers, verification, Touch, and stop/autonomy details.
+
+## Evidence expectations
+
+Prefer behavior evidence appropriate to the layer: simulation or testbench evidence for interface, reset, valid-ready, backpressure, ordering, and protocol behavior; lint or static checks for structural safety when they are part of Acceptance; formal or assertion evidence for invariants tests cannot exhaustively cover; golden traces or waveform references only when stable and tied to Acceptance.
+
+## Execution and review checks
+
+While implementing and reviewing, prove behavior at the interface: drive reset entry and exit, valid-ready handshakes including stall and backpressure, and ordering through simulation before trusting lint; a protocol or CSR field change needs testbench evidence for both legal and illegal accesses. Watch for silent X-propagation, unregistered CDC crossings, and new reset-domain assumptions introduced by the change. In review, reject waveform screenshots without a repeatable run command, require assertion or formal evidence for invariants simulation cannot exhaustively cover, and confirm any golden trace update carries an explicit rationale tied to Acceptance.

package/plugins/keel/skills/keel-align-expectations/references/web.md

@@ -0,0 +1,21 @@
+# Web alignment reference
+
+Domain lens for web frontend/backend work. Use during alignment when UI, API, routing, persistence, or integration behavior may hide product assumptions.
+
+## Material risk surface
+
+Treat these as deep-path candidates when the change touches them: UI-observable behavior, public interface contracts, routing, auth/session behavior, persistence, migrations, async state, loading/error states, accessibility expectations, browser compatibility, and backend integration boundaries. Ask only questions that materially affect Acceptance, verification checks, Touch, specs, design decisions, or non-goals; stop when the task contract can be written without guessing.
+
+## Durable placement
+
+- specs for user-visible behavior, API behavior, error handling, and scenarios.
+- design.md for framework choices, data flow, migration notes, auth/session assumptions, and trade-offs.
+- tasks.md for Covers, verification, Touch, and stop/autonomy details.
+
+## Evidence expectations
+
+Prefer public interface evidence: UI behavior through a rendered page or component workflow (no self-mocked internals); API behavior through route/client contract checks including user-affecting failure paths; data changes through migration/integration evidence when persistence semantics change; accessibility or responsive checks when Acceptance names them.
+
+## Execution and review checks
+
+While implementing and reviewing, prove behavior through the public interface: exercise UI changes in the rendered page, hit at least one user-affecting failure path (auth expiry, empty, error, slow response), and treat route, status-code, header, and payload shape as contract — a contract change needs a durable spec or task owner before review passes. Run persistence changes through a real forward migration and confirm auth/session boundaries did not silently widen. In review, reject build-only or component-shape evidence, and require explicit evidence for every loading, error, or empty state that Acceptance names.

package/plugins/keel/skills/keel-debug-failure/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: keel-debug-failure
+description: Debug Keel agent command or validation failures under Keel's selected OpenSpec task contract. Use when `/opsx:apply` or a selected task reports failed commands, failing tests, validation errors, retry-fuse decisions, or needs an evidence-bound failure report.
+---
+
+# keel-debug-failure
+## Purpose
+
+Use this skill when a command or validation path fails. Keep the investigation tied to the selected OpenSpec task. This skill owns the retry fuse, the task-contract binding, checkout preservation, and the failure-report shape; generic diagnosis mechanics (how to reproduce, minimise, or instrument) belong to the host runtime and are not restated here.
+
+## Context to read
+
+Read the selected OpenSpec task's Commands, Acceptance, Coupling, Candidate Boundary, Autonomy boundary, Stop Rules, Evidence, Stop if, Read, Touch, and Mode fields. When `Coupling: required`, also read design.md's Coupled Iteration Contract. Read the failed command output and any repository files needed to reproduce or explain the failure.
+
+## Domain reference
+
+When the change's artifacts or the failing surface signal a supported domain (web, hardware, hardware-dsl), consult the matching reference's `Execution and review checks` section under `keel-align-expectations/references/` before locking a root-cause hypothesis — only the matching reference, never all of them. When no domain signal exists, load nothing.
+
+## Fuse
+
+Try the same failure at most 2 attempts. If it still fails, stop and report the original key error plus what changed during each attempt.
+
+For `Coupling: required`, an allowed provisional failure inside a candidate does
+not count as an attempt. Count one attempt only when the same final assertion
+fails at the candidate completion gate. Follow the task's immediate task-stop
+rules for scope breach, missing design authority, non-reproducible evidence,
+or a baseline or acceptance change during a candidate.
+
+Preserve the current checkout on verification failure or context pressure.
+Only roll back to last-green when the selected task or human instruction
+explicitly authorizes it, and keep the failure evidence available.
+
+## Report boundary
+
+Follow-ups are limited to directly observed blockers, risks, missing scope, or escalation needs. Do not include roadmap suggestions, new feature suggestions, unrelated architecture critique, or opportunistic refactor suggestions.
+
+When the minimal fix needs files outside Touch, report an Out-of-scope Need with file or area, why needed, consequence if unchanged, minimal proposed change, and evidence. Do not modify those files.
+
+## Standalone use
+
+When used alone, report Summary, Failed command, Failure evidence, Attempts, Current hypothesis, and Required decision.