prompt-contract 0.2.0 → 0.3.0

package/README.md

@@ -7,8 +7,7 @@
 
 English · [简体中文](README.zh-CN.md)
 
-![PromptContract playground running the self-contained demo: a vague one-line request enhanced into a structured task spec, with six rule assertions passing](docs/assets/hero-playground.png)
-<sub>The playground running its self-contained demo (`?demo=1`) against the local mock upstream — actual pipeline output, six rule assertions passing.</sub>
+![PromptContract — a vague one-line request becomes a structured task spec (goal, scope, acceptance criteria, non-goals), verified by six hard rules via `prompt-prompt-contract check`. Real-LLM latency P50 2.3s; engine adds 0.005ms. CLI · MCP · Playground — zero dependencies, BYOK, offline-capable.](docs/assets/hero-cover.png)
 
 **PromptContract is a deterministic prompt-contract layer for AI coding agents.** It compiles a vague one-line request into a structured task specification — goal, scope, constraints, acceptance criteria — and verifies the result against six hard rules before you ever see it.
 
@@ -17,7 +16,7 @@ It is *not* a smarter brain: your model does the thinking, PromptContract makes
 ## Why PromptContract
 
 - **Stable agent inputs** — a profile plus hard constraints turn "a website for my dog" into goal / scope / acceptance criteria / explicit non-goals. Reduced retries and scope drift are hypotheses measured by the task-level harness, not current product claims.
-- **Six deterministic guardrails** — language consistency, enhanced-text-only, length & completeness, expand-don't-answer, no hallucinated tech. Every enhancement can be asserted with `contract check`; the same spec drives templates and tests.
+- **Six deterministic guardrails** — language consistency, enhanced-text-only, length & completeness, expand-don't-answer, no hallucinated tech. Every enhancement can be asserted with `prompt-prompt-contract check`; the same spec drives templates and tests.
 - **One engine, three surfaces** — a CLI, an MCP server (agent-invoked **tool** + user-invoked **slash prompts**), and a browser playground. All share one zero-dependency core.
 - **Private by architecture** — bring your own key, no server in the middle, no telemetry, offline-capable via Ollama.
 
@@ -31,16 +30,21 @@ node packages/cli/bin/contract.js "帮我做一个展示我家狗的网站" \
 node packages/playground/serve.js                       # → http://127.0.0.1:8123/  (or ?demo=1 for the self-running demo)
 ```
 
-Install: `npm i -g prompt-contract` — or zero-install: `npx prompt-contract "your vague idea"`.
+Install: `npm i -g prompt-contract` — or zero-install: `npx prompt-prompt-prompt-contract "your vague idea"`.
 
 ## Your real model
 
 ```bash
-export CONTRACT_API_KEY=sk-xxx CONTRACT_MODEL=gpt-4o-mini    # any OpenAI-compatible endpoint (DeepSeek, Qwen, GLM, vLLM…)
-contract "A website for my dog"
+export CONTRACT_API_KEY=sk-xxx CONTRACT_MODEL=gpt-4o-mini    # any OpenAI-compatible endpoint (vLLM, OpenRouter, your gateway…)
+prompt-prompt-contract "A website for my dog"
+
+export CONTRACT_PROVIDER=deepseek CONTRACT_API_KEY=sk-…      # vendor presets carry the base URL + a suggested model
+export CONTRACT_PROVIDER=qwen                                 # also: glm, moonshot, groq, openrouter, lmstudio (keyless)
+export CONTRACT_PROVIDER=anthropic CONTRACT_API_KEY=sk-ant-…  # native Messages API — thinking deltas dropped in transport
+prompt-prompt-contract "帮我写一封请假邮件"
 
 export CONTRACT_PROVIDER=ollama CONTRACT_MODEL=qwen3:4b      # fully local/offline; keep_alive pins the model in RAM
-contract "帮我写一封请假邮件"
+prompt-prompt-prompt-contract "帮我写一封请假邮件"
 ```
 
 Or write `~/.prompt-contract/config.json` once: `{ "provider": "openai", "baseUrl": "…", "apiKey": "…", "model": "…" }`.
@@ -69,7 +73,7 @@ Community profiles are the main contribution surface — a PR adding `profiles/<
 ## Quality gates — and their honest limits
 
 ```bash
-npm test        # 60 tests: engine units + SSE/ndjson streaming + CLI/MCP e2e against a local mock
+npm test        # 102 tests (serial): engine units + SSE/ndjson streaming + CLI/MCP e2e against a local mock
 npm run eval    # 9 deterministic cases over the six hard-constraint assertions
 npm run eval:tasks -- --format-only  # validate the coding-agent task fixture format gate
 npm run bench   # engine overhead: P50 ≈ 0.005ms (budget < 5ms)
@@ -82,20 +86,20 @@ npm run bench   # engine overhead: P50 ≈ 0.005ms (budget < 5ms)
 ```
 raw input → script/scenario detect → profile + hard constraints + strength (+ optional context)
   → single streaming LLM call (small fast model by default; the model does the thinking)
-  → deterministic cleaning (quotes/fences/length clamp, empty → llm_error)
+  → deterministic cleaning (reasoning-block strip, quotes/fences/length clamp, empty → llm_error)
   → { enhanced, original, meta } — original always preserved, one-key revert in every surface
 ```
 
 ## Status & roadmap — stated honestly
 
-- **Shipped:** engine, CLI (`contract` / `check` / `doctor` / `profiles` / `spike-0`), MCP server (tool + zero-key prompts), playground, 3 profiles, eval cases, CI matrix.
-- **Gated:** `contract watch` (global-hotkey resident mode) remains intentionally unavailable. `contract spike-0` measures macOS capture/clipboard safety and dry-run focus eligibility, but never pastes or unlocks watch by itself; see [docs/SPIKE-0.md](docs/SPIKE-0.md).
+- **Shipped:** engine, CLI (`prompt-contract` / `check` / `doctor` / `profiles` / `spike-0` / `watch`), MCP server (tool + zero-key prompts), playground, 3 profiles, eval cases, CI matrix.
+- **Resident mode:** `prompt-prompt-contract watch` — select text anywhere on macOS, press ⌥B, and the enhanced prompt replaces your selection: clipboard backed up and restored, focus re-validated before pasting, gated by `prompt-prompt-contract spike-0` evidence (decision D7). See [docs/WATCH.md](docs/WATCH.md). `prompt-prompt-contract spike-0` itself remains a dry-run diagnostic and never pastes; see [docs/SPIKE-0.md](docs/SPIKE-0.md).
 - **Open validation:** task-level outcome evaluation remains an evidence-gathering task. The harness and curated fixture set exist, but PromptContract's downstream effectiveness is still a hypothesis until a declared runner produces reviewed results.
 - Deferred: animated demo asset, IDE plugins, LLM-as-judge as *one* scorer inside the task-level eval.
 
 ## Layout
 
-`packages/core` (engine, browser-safe, zero deps) · `packages/providers` (OpenAI-compatible SSE + Ollama `keep_alive`) · `packages/cli` · `packages/mcp-server` · `packages/playground` · `profiles/` · `eval/` · `mock/` · `docs/ACCEPTANCE.md` · `docs/SPIKE-0.md` (requirements → implementation → acceptance + evidence boundaries)
+docs/ACCEPTANCE.md` · `docs/SPIKE-0.md` · `docs/WATCH.md` (requirements → implementation → acceptance + evidence boundaries)
 
 ## Contributing & License
 

package/README.zh-CN.md

@@ -6,16 +6,16 @@
 
 [English](README.md) · 简体中文
 
+![PromptContract——模糊的一句话被编译成结构化任务规范（目标 / 范围 / 验收标准 / 明确不做的事），六条硬规则经 `prompt-prompt-contract check` 校验。真实 LLM 端到端 P50 2.3s，引擎附加开销 0.005ms。CLI · MCP · Playground——零依赖、BYOK、可离线。](docs/assets/hero-cover.png)
+
 **PromptContract 是面向 AI 编码 agent 的确定性 prompt 契约层**：把模糊的一句话编译成结构化任务规范（目标 / 范围 / 约束 / 验收标准），并在你看到结果之前用六条硬规则完成校验。
 
 它不是「更聪明的大脑」：思考由你的模型完成，PromptContract 让 agent 的输入变得稳定、可审查、可跨模型与跨工具迁移。
 
-![Playground 自运行演示：模糊一句话被增强为结构化任务规范，六条规则断言全部通过](docs/assets/hero-playground.png)
-
 ## 为什么
 
 - **稳定的 agent 输入**——profile + 硬约束把「帮我做个网站」编译成目标 / 范围 / 验收标准 / 明确不做的事；重试与范围漂移是否减少，仍须由任务级 harness 验证，当前不作产品结论
-- **六条确定性护栏**——语言一致性、只输出增强文本、长度与完整性、扩写而非回答、无幻觉技术栈；`contract check` 随时可断言，模板与测试共用同一份规格
+- **六条确定性护栏**——语言一致性、只输出增强文本、长度与完整性、扩写而非回答、无幻觉技术栈；`prompt-prompt-contract check` 随时可断言，模板与测试共用同一份规格
 - **一个引擎、三个形态**——CLI、MCP server（agent 调用的 tool + 用户调用的斜杠 prompts）、浏览器 Playground，共享同一个零依赖内核
 - **隐私即架构**——BYOK、无中间服务、零遥测，Ollama 全本地可用
 
@@ -29,16 +29,21 @@ node packages/cli/bin/contract.js "帮我做一个展示我家狗的网站" \
 node packages/playground/serve.js                       # → http://127.0.0.1:8123/（?demo=1 为自运行演示）
 ```
 
-安装：`npm i -g prompt-contract`；或零安装体验：`npx prompt-contract "你的模糊想法"`。
+安装：`npm i -g prompt-contract`；或零安装体验：`npx prompt-prompt-prompt-contract "你的模糊想法"`。
 
 ## 接入真实模型
 
 ```bash
-export CONTRACT_API_KEY=sk-xxx CONTRACT_MODEL=gpt-4o-mini   # 任意 OpenAI 兼容端点（DeepSeek/Qwen/GLM/vLLM…）
-contract "A website for my dog"
+export CONTRACT_API_KEY=sk-xxx CONTRACT_MODEL=gpt-4o-mini   # 任意 OpenAI 兼容端点（vLLM、OpenRouter、自家网关…）
+prompt-prompt-contract "A website for my dog"
+
+export CONTRACT_PROVIDER=deepseek CONTRACT_API_KEY=sk-…     # 厂商预设：自带 base URL 与建议默认模型
+export CONTRACT_PROVIDER=qwen                                # 另有 glm、moonshot、groq、openrouter、lmstudio（免 key）
+export CONTRACT_PROVIDER=anthropic CONTRACT_API_KEY=sk-ant-… # Anthropic 原生 Messages API——思考增量在传输层即被丢弃
+prompt-prompt-contract "帮我写一封请假邮件"
 
 export CONTRACT_PROVIDER=ollama CONTRACT_MODEL=qwen3:4b     # 全本地；keep_alive 把模型钉在内存
-contract "帮我写一封请假邮件"
+prompt-prompt-prompt-contract "帮我写一封请假邮件"
 ```
 
 或一次写入 `~/.prompt-contract/config.json`。
@@ -53,7 +58,7 @@ contract "帮我写一封请假邮件"
 ## 质量门禁与诚实边界
 
 ```bash
-npm test        # 60 项：引擎单测 + SSE/ndjson 流式 + CLI/MCP 端到端（对本地 mock）
+npm test        # 102 项（串行）：引擎单测 + SSE/ndjson 流式 + CLI/MCP 端到端（对本地 mock）
 npm run eval    # 9 个确定性用例（六条硬约束断言）
 npm run eval:tasks -- --format-only  # 校验 coding-agent 任务 fixture 的格式门禁
 npm run bench   # 引擎自身开销 P50 ≈ 0.005ms（预算 <5ms）
@@ -63,8 +68,8 @@ npm run bench   # 引擎自身开销 P50 ≈ 0.005ms（预算 <5ms）
 
 ## 状态与路线图（诚实版）
 
-- **已交付**：引擎、CLI（含 `spike-0`）、MCP server（tool + 零 key prompts）、Playground、3 个 profiles、eval 用例、CI 矩阵
-- **被门控**：`contract watch`（全局热键常驻）仍不可用。`contract spike-0` 只测 macOS 取词、剪贴板恢复和焦点校验的 dry-run，不发送粘贴，也不会自行解锁 watch；见 [docs/SPIKE-0.md](docs/SPIKE-0.md)
+- **已交付**：引擎、CLI（含 `prompt-prompt-contract spike-0`、`prompt-prompt-contract watch` 常驻模式）、MCP server（tool + 零 key prompts）、Playground、3 个 profiles、eval 用例、CI 矩阵
+- **常驻模式**：`prompt-prompt-contract watch`——在 macOS 任意应用选中一段粗糙 prompt，按 ⌥B，增强结果原地替换选区：剪贴板先备份后恢复、回贴前焦点复验（漂移即放弃）、以 `prompt-prompt-contract spike-0` 证据为启动门控（决策 D7）；详见 [docs/WATCH.md](docs/WATCH.md)。`prompt-prompt-contract spike-0` 本身仍是 dry-run 诊断，永不发送粘贴；见 [docs/SPIKE-0.md](docs/SPIKE-0.md)
 - **开放验证**：任务级效果评测的 harness 与任务 fixture 已交付，但还没有声明 runner 产生并复核结果；长期价值在此之前仍是假设
 - **推迟**：动画 demo 资产、IDE 插件、LLM-as-judge（作为任务级评测中的评分器之一）
 

package/package.json

@@ -1,21 +1,22 @@
 {
   "name": "prompt-contract",
-  "version": "0.2.0",
-  "description": "pc — one-key prompt enhancement: turn vague ideas into structured task specs anywhere you type to an AI. CLI + MCP server. Zero dependencies, BYOK, offline-capable (Ollama).",
+  "version": "0.3.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "One-key prompt enhancement — turn vague ideas into structured task specs anywhere you type to an AI. CLI + MCP server. Zero dependencies, BYOK, offline-capable (Ollama).",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {
     "node": ">=20"
   },
   "bin": {
-    "contract": "./packages/cli/bin/contract.js",
     "prompt-contract": "./packages/cli/bin/contract.js",
-    "prompt-contract-mcp": "./packages/mcp-server/bin/prompt-contract-mcp.js",
-    "pb": "./packages/cli/bin/contract.js"
+    "contract": "./packages/cli/bin/contract.js",
+    "prompt-contract-mcp": "./packages/mcp-server/bin/prompt-contract-mcp.js"
   },
   "keywords": [
     "prompt",
-    "prompt-contract",
     "prompt-engineering",
     "llm",
     "cli",
@@ -36,7 +37,7 @@
     "packages/",
     "profiles/",
     "README.md",
-    "README.en.md",
+    "README.zh-CN.md",
     "LICENSE"
   ]
 }

package/packages/cli/bin/contract.js

@@ -2,11 +2,13 @@
 /**
  * contract — PromptContract CLI (PRD §4 P0). Physical file kept as contract.js for path stability.
  * One-shot enhance (arg or stdin), profiles, check (rule assertions), doctor.
- * `contract watch` is intentionally gated by decision D7 (Spike-0 first) — see docs/SPIKE-0.md.
+ * One-shot enhance (arg or stdin), profiles, check (rule assertions), doctor,
+ * spike-0 (capture diagnostic), watch (resident hotkey mode — see docs/WATCH.md).
  */
 import { enhance, checkRules, PromptContractError, normalizeError } from '../../core/src/index.js';
 import { loadProfiles, loadProfile, resolveConfig } from '../../core/src/node.js';
 import { createOpenAIProvider } from '../../providers/src/openai.js';
+import { createAnthropicProvider } from '../../providers/src/anthropic.js';
 import { createOllamaProvider } from '../../providers/src/ollama.js';
 import { readFileSync, existsSync, writeFileSync } from 'node:fs';
 import { basename } from 'node:path';
@@ -18,30 +20,32 @@ import {
   resolveSpikeTargets,
   runSpike0,
 } from '../src/spike-0.js';
+import { runWatch } from '../src/watch.js';
 
-// `contract` was the command name before the prompt-contract rename; warn while the alias ships.
+// `prompt-contract` was the command name before the prompt-contract rename; warn while the alias ships.
 if (basename(process.argv[1] || '') === 'contract') {
-  process.stderr.write('[deprecated] this CLI is now `contract` (prompt-contract); the `contract` command will be removed in a future release.\n');
+  process.stderr.write('[deprecated] this CLI is now `prompt-contract` (prompt-contract); the `prompt-contract` command will be removed in a future release.\n');
 }
 
-const VERSION = '0.2.0';
-const USAGE = `contract — one-key prompt enhancement (PromptContract v${VERSION})
+const VERSION = '0.3.0';
+const USAGE = `prompt-contract — one-key prompt enhancement (PromptContract v${VERSION})
 
 Usage:
-  contract "build me a website for my dog"     enhance a prompt (prints enhanced text to stdout)
-  cat prompt.txt | contract                    enhance from stdin
-  contract profiles                            list built-in profiles
-  contract check --original "..." --enhanced "..."
+  prompt-prompt-prompt-contract "build me a website for my dog"     enhance a prompt (prints enhanced text to stdout)
+  cat prompt.txt | prompt-contract                    enhance from stdin
+  prompt-prompt-contract profiles                            list built-in profiles
+  prompt-prompt-prompt-contract check --original "..." --enhanced "..."
                                          run the six hard-constraint rule assertions
-  contract doctor                              verify config, provider reachability, profiles
-  contract spike-0                             macOS-only capture/restore compatibility diagnostic (dry-run)
-  contract watch                               NOT BUILT — gated by decision D7 (Spike-0 first); see docs/SPIKE-0.md
+  prompt-prompt-contract doctor                              verify config, provider reachability, profiles
+  prompt-prompt-prompt-contract spike-0                             macOS-only capture/restore compatibility diagnostic (dry-run)
+  prompt-prompt-prompt-contract watch                               resident mode: select text → hotkey → enhanced text replaces it (macOS; docs/WATCH.md)
 
 Options:
   -p, --profile <name>     scenario profile (default: coding-agent)
   -s, --strength <mode>    polish | standard (default) | expand
   -m, --model <model>      model override
-      --provider <name>    openai (default) | ollama
+      --provider <name>    openai (default) | anthropic | ollama | vendor presets:
+                           deepseek qwen glm moonshot groq openrouter lmstudio
       --base-url <url>     OpenAI-compatible base URL (or CONTRACT_BASE_URL)
       --api-key <key>      API key (or CONTRACT_API_KEY; local ollama needs none)
       --context <text>     background context to assemble into the prompt
@@ -54,19 +58,30 @@ Options:
       --setup-delay-ms <ms> Spike-0 delay before each target capture
       --no-prompt          Spike-0 do not wait for target/app setup
       --output <path>      write Spike-0 JSON report to a file
+      --hotkey <spec>      watch trigger combo: ctrl=⌃ alt/option=⌥ cmd=⌘ shift=⇧ + key,
+                           e.g. "ctrl+alt+b" = hold ⌃⌥ and press B (default alt+b; persist via "hotkey"
+                           in ~/.prompt-contract/config.json)
+      --trigger <name>     watch trigger source: hotkey (default) | stdin (each Enter = trigger, q quits)
+      --report <path>      Spike-0 JSON report satisfying the watch evidence gate (D7)
+      --force              run watch without Spike-0 evidence (at your own risk)
+      --dry-run            watch: capture + enhance but never paste
+      --paste-delay-ms <ms> watch: wait between ⌘V and clipboard restore (default: 1000)
+      --cooldown-ms <ms>   watch: minimum gap between cycles (default: 800)
       --json               machine-readable output {original, enhanced, meta, rules}
       --no-stream          buffer instead of streaming progress
   -h, --help               show this help`;
 
 function parseArgs(argv) {
   const flags = { _: [] };
-  const needsValue = new Set(['--profile', '-p', '--strength', '-s', '--model', '-m', '--provider', '--base-url', '--api-key', '--context', '--max-chars', '--timeout', '--app', '--iterations', '--settle-ms', '--pause-ms', '--setup-delay-ms', '--output', '--original', '--enhanced']);
+  const needsValue = new Set(['--profile', '-p', '--strength', '-s', '--model', '-m', '--provider', '--base-url', '--api-key', '--context', '--max-chars', '--timeout', '--app', '--iterations', '--settle-ms', '--pause-ms', '--setup-delay-ms', '--output', '--original', '--enhanced', '--hotkey', '--trigger', '--report', '--paste-delay-ms', '--cooldown-ms']);
   const camel = (k) => k.replace(/^--?/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase());
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--json') flags.json = true;
     else if (a === '--no-stream') flags.noStream = true;
     else if (a === '--no-prompt') flags.noPrompt = true;
+    else if (a === '--dry-run') flags.dryRun = true;
+    else if (a === '--force') flags.force = true;
     else if (a === '--help' || a === '-h') flags.help = true;
     else if (a === '--version') flags.version = true;
     else if (needsValue.has(a)) flags[camel(a)] = argv[++i];
@@ -77,9 +92,9 @@ function parseArgs(argv) {
 }
 
 function buildProvider(cfg) {
-  return cfg.provider === 'ollama'
-    ? createOllamaProvider({ baseUrl: cfg.baseUrl })
-    : createOpenAIProvider({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+  if (cfg.provider === 'ollama') return createOllamaProvider({ baseUrl: cfg.baseUrl });
+  if (cfg.provider === 'anthropic') return createAnthropicProvider({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+  return createOpenAIProvider({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
 }
 
 function makeProvider(cfg, { warm = false } = {}) {
@@ -133,7 +148,7 @@ async function cmdEnhance(flags) {
     if (!flags.noStream) {
       process.stderr.write(`\n— ${res.meta.profile} · ${res.meta.model} · ${res.meta.ms}ms · ${res.meta.chars} chars\n`);
       if (!rules.pass) {
-        process.stderr.write('rule assertions (advisory — run `contract check` for gate mode):\n');
+        process.stderr.write('rule assertions (advisory — run `prompt-prompt-prompt-contract check` for gate mode):\n');
         for (const r of rules.results.filter((r) => !r.pass)) {
           process.stderr.write(`  [FAIL] ${r.title}${r.detail ? ` — ${r.detail}` : ''}\n`);
         }
@@ -168,7 +183,7 @@ function cmdCheck(flags) {
     }
   }
   if (original === undefined || enhanced === undefined) {
-    process.stderr.write('contract check requires --original and --enhanced (or a JSON {original, enhanced} line on stdin)\n');
+    process.stderr.write('prompt-prompt-contract check requires --original and --enhanced (or a JSON {original, enhanced} line on stdin)\n');
     return 2;
   }
   const rules = checkRules(original, enhanced, { maxChars: flags.maxChars ? parseInt(flags.maxChars, 10) : 800 });
@@ -204,7 +219,7 @@ async function cmdDoctor(flags) {
 
 async function cmdSpike0(flags) {
   if (!isMacOS) {
-    process.stderr.write('contract spike-0 is macOS-only: requires pbpaste, pbcopy, and Accessibility-backed System Events.\n');
+    process.stderr.write('prompt-prompt-contract spike-0 is macOS-only: requires pbpaste, pbcopy, and Accessibility-backed System Events.\n');
     return 2;
   }
 
@@ -216,7 +231,7 @@ async function cmdSpike0(flags) {
   const pauseMs = flags.pauseMs === undefined ? 0 : Number.parseInt(flags.pauseMs, 10);
   const setupDelayMs = flags.setupDelayMs === undefined ? 0 : Number.parseInt(flags.setupDelayMs, 10);
   if (!Number.isInteger(iterations) || iterations < 1 || !Number.isInteger(settleMs) || settleMs < 0 || !Number.isInteger(pauseMs) || pauseMs < 0 || !Number.isInteger(setupDelayMs) || setupDelayMs < 0) {
-    process.stderr.write('contract spike-0 requires non-negative integer --settle-ms/--pause-ms/--setup-delay-ms and positive integer --iterations\n');
+    process.stderr.write('prompt-prompt-contract spike-0 requires non-negative integer --settle-ms/--pause-ms/--setup-delay-ms and positive integer --iterations\n');
     return 2;
   }
 
@@ -237,6 +252,10 @@ async function cmdSpike0(flags) {
   return report.decision.pass ? 0 : 1;
 }
 
+async function cmdWatch(flags) {
+  return runWatch(flags);
+}
+
 async function main() {
   const flags = parseArgs(process.argv.slice(2));
   if (flags.help) { process.stdout.write(USAGE + '\n'); return 0; }
@@ -249,9 +268,7 @@ async function main() {
     case 'check': return cmdCheck(flags);
     case 'doctor': return await cmdDoctor(flags);
     case 'spike-0': return await cmdSpike0(flags);
-    case 'watch':
-      process.stderr.write('contract watch is gated by decision D7: run `contract spike-0` and review its evidence before implementing watch.\nThe watch implementation remains intentionally unavailable in this Spike-0-only change.\n');
-      return 2;
+    case 'watch': return await cmdWatch(flags);
     default:
       // treat unknown first word as prompt text
       flags._.unshift(cmd);

package/packages/cli/src/spike-0.js

@@ -36,6 +36,9 @@ export const APP_TARGETS = Object.freeze({
 });
 
 const COPY_SCRIPT = 'tell application "System Events" to keystroke "c" using {command down}';
+// Used only by prompt-contract watch. The Spike-0 diagnostic itself never issues ⌘V; its
+// safety contract is enforced in captureSelectedText/validatePasteBackDryRun.
+const PASTE_SCRIPT = 'tell application "System Events" to keystroke "v" using {command down}';
 
 // The report deliberately excludes AXValue: it can contain the user's prompt or
 // other sensitive text. These attributes are enough to conservatively detect a
@@ -212,6 +215,12 @@ export function createMacOSAdapter({ run = runCommand } = {}) {
       if (result.code !== 0) throw commandError('osascript-copy', result);
     },
 
+    async pasteSelection() {
+      const result = await run('/usr/bin/osascript', ['-e', PASTE_SCRIPT]);
+      if (result.error) throw result.error;
+      if (result.code !== 0) throw commandError('osascript-paste', result);
+    },
+
     async getFocusIdentity() {
       const result = await run('/usr/bin/osascript', ['-e', CONTEXT_SCRIPT], { timeoutMs: 5000 });
       if (result.error) throw result.error;
@@ -275,7 +284,7 @@ function fingerprintForContext(context) {
   return createHash('sha256').update(fields.join('\u001f')).digest('hex').slice(0, 16);
 }
 
-function sameFocusIdentity(left, right) {
+export function sameFocusIdentity(left, right) {
   if (!left || !right) return false;
   const appStable = normalized(left.processName) === normalized(right.processName)
     && normalized(left.bundleId) === normalized(right.bundleId)
@@ -309,8 +318,17 @@ export async function captureSelectedText(adapter, { settleMs = 75 } = {}) {
     clipboardUntouched = false;
     await adapter.copySelection();
     await adapter.sleep(settleMs);
-    const copiedText = await adapter.readClipboard();
-    selectedText = typeof copiedText === 'string' && copiedText.trim() ? copiedText : null;
+    let copiedText = await adapter.readClipboard();
+    // ⌘C is delivered asynchronously: a read that still shows the pre-copy
+    // clipboard means the copy has not landed — poll briefly instead of
+    // mistaking the stale clipboard for the selection. A read identical to the
+    // pre-copy clipboard after polling reports an empty selection (the
+    // clipboard fallback then covers the intentional selection==clipboard case).
+    for (let polls = 0; copiedText === originalClipboard && polls < 6; polls++) {
+      await adapter.sleep(60);
+      copiedText = await adapter.readClipboard();
+    }
+    selectedText = typeof copiedText === 'string' && copiedText.trim() && copiedText !== originalClipboard ? copiedText : null;
     contextAfterCapture = await adapter.getFocusIdentity();
   } catch (captureError) {
     error = captureError;
@@ -457,7 +475,7 @@ export function buildCompatibilityReport({
       pass: reasons.length === 0,
       reasons,
       watchGate: 'closed',
-      note: 'A dry-run cannot prove actual paste landing; contract watch remains gated until a separate implementation decision.',
+      note: 'A dry-run cannot prove actual paste landing; this report is evidence for prompt-contract watch, never an authorization by itself.',
     },
   };
 }
@@ -575,7 +593,7 @@ export function formatSpike0Summary(report) {
     `capture ${summary.captureSuccesses}/${summary.attempts} (${summary.captureSuccessRate})`,
     `clipboard restore ${summary.clipboardRestoreSuccesses}/${summary.attempts} (${summary.clipboardRestoreSuccessRate})`,
     `dry-run paste-back eligibility ${summary.dryRunPasteBackSuccesses}/${summary.attempts} (${summary.dryRunPasteBackRate})`,
-    report.decision.reasons.length ? `reasons: ${report.decision.reasons.join('; ')}` : 'thresholds met; contract watch remains gated',
+    report.decision.reasons.length ? `reasons: ${report.decision.reasons.join('; ')}` : 'thresholds met; evidence usable by prompt-contract watch',
   ].join('\n');
 }