diff --git a/README.md b/README.md index 25f5633..cf0a366 100644 --- a/README.md +++ b/README.md @@ -1,454 +1,487 @@ # SpecWave +[![npm version](https://img.shields.io/npm/v/spec-wave.svg)](https://www.npmjs.com/package/spec-wave) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +**Write your AI coding rules once. SpecWave installs them natively into Cursor, Claude Code, Copilot, and 10 more tools.** + [简体中文](README.zh-CN.md) | English -**SpecWave** (`spec-wave@3.0.2`) is a **multi-host coding CLI** — one declarative adapt table lands natively on Cursor, Claude Code, optional DSH, agents, and more — with **P0 gate / Harness process commands** and IDE landing. Discipline assets remain ICVO (Inform · Constrain · Verify · Orchestrate). +--- + +## The Problem + +Maintaining separate config files for each AI coding tool by hand: + +``` +.cursorrules ← Cursor rules (copy-paste) +CLAUDE.md ← Claude Code conventions (duplicate) +.github/copilot-instructions.md ← Copilot settings (also duplicate) +.windsurf/rules.md ← Windsurf rules (you get the idea...) +``` -> **Loading ≠ injecting.** Installing or loading the optional DSH plugin does **not** automatically rewrite the system prompt. `apply()` only registers tools. Only after you or the model calls `apply_coding_standards` will later turns' runtime context contain `# Coding Standards`. -> -> **New here?** First-hour terms — `task.md` / Harness / hats / `kit-*` — are defined in [GLOSSARY.md](GLOSSARY.md) (bilingual). -> -> Formerly SpecGate / `dsh-coding-kit` — rename history and migration: [MIGRATION.md](MIGRATION.md). +Every time you update one, you manually sync the others. Rules drift. Teams waste time. -## Prerequisites +## The SpecWave Solution -| Requirement | Notes | -|-------------|-------| -| **Node.js** | **`^22.19.0` or `>=24.0.0`** (see `package.json#engines`) | -| **Not supported** | **Node 20** (and earlier) — engines will fail; upgrade before `npx` / install | +**One source of truth.** One command. Native installations everywhere. ```bash -node -v # expect v22.19+ or v24+ +npx spec-wave host apply --tools cursor,claude,copilot,windsurf --yes ``` -## Quick start (5 steps) +SpecWave reads your declarative adapt table and generates the native config files each tool expects: -Primary entry is **`npx spec-wave`** from npm **`spec-wave@3.0.2`**. Plugin surface and CLI surface do not replace each other. +| Before SpecWave | After SpecWave | +|-----------------|----------------| +| Manually maintain 5+ config files | Maintain **one adapt table** | +| Copy-paste rules between tools | Run **one command** to sync all | +| Rules drift across tools | **Single source of truth** | +| No enforcement | **Fail-closed gates** (exit 2) | -```bash -# 1) Confirm package (pin recommended) -npx spec-wave@3.0.2 --version +--- -# 2) Validate adapt table (dry) -npx spec-wave@3.0.2 host validate +## Quick Start -# 3) Materialize hosts (dry-run, then write) -npx spec-wave@3.0.2 host apply --tools cursor,claude,dsh --profile core -npx spec-wave@3.0.2 host apply --tools cursor,claude,dsh --profile core --yes +```bash +# 1. Install and initialize +npx spec-wave@3.0.2 init --preset harness-only --tools cursor,claude --yes -# 4) Or first-time init (process root + host select) -npx spec-wave@3.0.2 init --preset harness-only --tools cursor,claude,dsh --yes +# 2. Verify everything is set up +npx spec-wave@3.0.2 check -# 5) After you have a task.md — mechanical gate (exit 2 = hard stop) -npx spec-wave@3.0.2 verify --task docs/tasks/active/task_.md +# 3. Apply coding standards to your IDE +# Cursor users: restart Cursor to load new rules +# Claude Code users: restart Claude Code to load new commands ``` -After `--yes`, Cursor should see `kit-verify` / …; Claude Code `/kit:verify`; DSH `.dsh/skills/kit-*`. Full host matrix and Entry A/B encyclopedia: [Multi-host matrix](#multi-host-matrix) · [Entry A · DSH plugin](#entry-a--dsh-plugin) · [Entry B · CLI](#entry-b--cli-cursor--claude-code--ci). Concepts: [Core objects](#core-objects) · [GLOSSARY.md](GLOSSARY.md). +**That's it.** Your coding rules are now active in both tools. -### Empty repo: minimal green when `test_strategy=required` +--- -CLI **never** writes example tasks into your `docs/tasks/` (S2). You copy the template yourself: +## Supported Hosts (13 Tools) -1. `npx spec-wave@3.0.2 sync prompts --yes` (materializes `docs/harness/templates/TASK_TEMPLATE.md` among prompts). -2. Copy the template → `docs/tasks/active/task_.md` (your action). -3. If meta sets **`test_strategy=required`**: add a **failing** automated test for the critical path **before** hat 30 changes implementation; then implement until green. -4. Human-gate table must be **4 columns**; `HG-AUDIT-R1` → `approved` before hat 30 may change code. -5. `npx spec-wave@3.0.2 task lint --file docs/tasks/active/task_.md` then `verify --task …`. +SpecWave generates native files for each host. One adapt table, 13 destinations: -Details: template path above · [Core objects](#core-objects) · [GLOSSARY.md](GLOSSARY.md). +| Host | Generated Files | Notes | +|------|----------------|-------| +| **Cursor** | `.cursor/rules/*.mdc`
`.cursor/commands/kit-*.md`
`.cursor/skills/` | Native Cursor rules & commands | +| **Claude Code** | `CLAUDE.md`
`.claude/commands/kit/*.md` → `/kit:*`
`.claude/skills/` | Product marker block + commands | +| **GitHub Copilot** | `AGENTS.md`
`.github/skills/` | Native GitHub skills directory | +| **Codex** | `AGENTS.md`
`.agents/skills/` | Repo-level scan directory | +| **Windsurf** | `AGENTS.md`
`.windsurf/skills/` | Native Windsurf skills | +| **Gemini CLI** | `GEMINI.md`
`.gemini/skills/` | Native Gemini context file | +| **OpenCode** | `AGENTS.md`
`.agents/skills/` | Agent-compatible path | +| **Roo Code** | `AGENTS.md` | AGENTS.md loaded via merged PR | +| **Zed** | `AGENTS.md`
`.agents/skills/` | Project-local directory | +| **Cline** | `AGENTS.md`
`.cline/skills/` | Workspace skills | +| **aider** | `AGENTS.md` | Injection layer (requires `aider --read AGENTS.md`) | +| **DSH** | `.dsh/skills/` | Hat skills + orchestration | +| **agents** | `AGENTS.md`
`.agents/skills/` | Generic agents standard | -## Which entry to choose +> **13 hosts. One command.** No manual file editing. -| Who you are | Entry | Do NOT | -|-------------|-------|--------| -| Cursor / Claude Code / CI on existing repos | `npx spec-wave` (+ optional `host apply`) | Don't treat the plugin `init_coding_kit` and the CLI `init` as the same entry | -| DSH session / model calling tools (optional) | `dsh plugin add spec-wave` (`dsh-coding-kit` **deprecated** — do not add the old name) | Don't just `npm install` (without the bundle layer the tools won't appear) | +--- -Transition bins `specgate` and `dsh-coding-kit` still work; new scripts should use `npx spec-wave`. +## Why Fail-Closed Gates? -### Multi-host matrix +SpecWave includes **P0 gates** that enforce process discipline: -One declarative table → native landing on several hosts (always_on + skills + **commands**). Verify truth stays in the CLI (`failClosed` exit **2**); IDE slash/commands only orchestrate. **Installing the npm package does not materialize IDE files** (no postinstall); run `init --tools` / `host apply` explicitly. +```bash +# Before making changes, verify task approval +npx spec-wave verify --task docs/tasks/active/task_login-limit.md +# Exit code 2 (BLOCKED) = do not proceed +# Exit code 0 (PASS) = approved, proceed +``` -| Host | What `host apply` writes (profile `core`) | -|------|-------------------------------------------| -| **Cursor** | `.cursor/rules/*.mdc` · `.cursor/commands/kit-*.md` · `.cursor/skills/` | -| **Claude Code** | `CLAUDE.md` product marker block · `.claude/commands/kit/.md` → **`/kit:verb`** · `.claude/skills/` | -| **DSH** | `.dsh/skills/` — hat skills **+** orchestration `kit-*` (discoverable via `/`; **no** `.dsh/commands/`) | -| **agents** (optional) | `AGENTS.md` fragment · `.agents/skills/` | -| **Copilot** | `AGENTS.md` fragment (shared marker block) · `.github/skills/` | -| **Codex** | `AGENTS.md` fragment (shared marker block) · `.agents/skills/` | -| **Windsurf** | `AGENTS.md` fragment (shared marker block) · `.windsurf/skills/` | -| **Gemini CLI** | `GEMINI.md` (same host-neutral fragment) · `.gemini/skills/` | -| **opencode** | `AGENTS.md` fragment (shared marker block) · `.agents/skills/` | -| **Roo Code** | `AGENTS.md` fragment (shared marker block; loaded per official-repo merged PR) · no skills dir (no official convention) | -| **Zed** | `AGENTS.md` fragment (shared marker block) · `.agents/skills/` | -| **Cline** | `AGENTS.md` fragment (shared marker block) · `.cline/skills/` | -| **aider** (injection layer) | `AGENTS.md` fragment (injection-layer support: aider does **not** auto-load AGENTS.md — use `aider --read AGENTS.md` or `.aider.conf.yml` with `conventions-file: AGENTS.md`) · no skills dir (no official convention) | +**Fail-closed** means: if a gate fails, the command exits with code `2` (not `0` or `1`). CI and agents **must** treat exit code `2` as a hard stop. -**2.2 W6 / 2.3 W6 host additions** (same package): the nine hosts above reuse the **agents** asset face (zero new assets); each landing follows the host's official docs, and hosts without an official skills convention get no skills directory (never fabricated). aider is a documented downgrade — injection layer only. +- **Exit 0**: Pass +- **Exit 1**: Usage error (non-blocking) +- **Exit 2**: Gate BLOCKED — **do not proceed** -**2.1 additions** (same package): Claude `/kit:` namespace UX · DSH `.dsh/skills/kit-*` orchestration · optional `--profile expanded` for `kit-hat-*` thin shells (default remains `core`). +This ensures: +- Human approval before code changes +- Test artifacts exist when required +- Review files exist before implementation +- No silent failures -**2.1.1 · install / upgrade UX** (aligned with OpenSpec `init --tools`): +--- -| Topic | Behavior | -|-------|----------| -| Sticky | Successful `--yes` write of `host apply` / `host update` / `init` (when materializing) updates `.coding-kit/host-tools.json` (`host_ids` + `profile`). Dry-run does **not** write sticky. | -| `--tools` | `LIST` (e.g. `cursor,claude,dsh`) · `all` (every host_id in the adapt table) · `none` (**init only**: process root, no host materialize). `host apply` **always** requires `--tools`. | -| `host update` (scheme **A**) | Resolve order: CLI `--tools` → sticky → else **exit 1**. With sticky, `host update --yes` refreshes **only** selected hosts. **BREAKING (small)** vs 2.1.0 “omit `--tools` = full table”. | -| `init` | TTY without `--tools` → **asks** (multi-select / all / none). Non-TTY / CI without `--tools` → **exit 1**. `tools≠none` and not `--no-host-adapt` → in-process `host apply` + sticky. `--no-host-adapt` → no apply and **no** sticky. | +## Terminal Demo -```bash -# After upgrading the package: refresh sticky hosts (no need to re-list --tools) -npx spec-wave@3.0.2 host update --yes -``` + -Full matrix: [`assets/ide/host-adapt/README.md`](assets/ide/host-adapt/README.md) · dogfood/recording: [`docs/guides/DOGFOOD_host_adapt_cursor_claude_录屏清单_v1_zh.md`](docs/guides/DOGFOOD_host_adapt_cursor_claude_录屏清单_v1_zh.md) · plan: [`docs/roadmap/PLAN_2_1_1_host_tools_ux_v1_zh.md`](docs/roadmap/PLAN_2_1_1_host_tools_ux_v1_zh.md). +**Demo placeholder:** Real terminal recording to be added. +Show: `host apply` → native files generated → `verify` gate check. -The `@deepseek-ai/cordis` and `@deepseek-ai/dsh-tools` entries in `peerDependencies` are the **DSH host plugin contract** (needed only when the host loads this package as a plugin; not needed for CLI-only use), and are marked **optional** in `peerDependenciesMeta`. +--- -## Core objects +## Features -The Harness process revolves around two file-level objects. `verify --task ` / `gate-check --task ` / `task close` all operate on the first one — this section defines both before you meet them in the command list. +### 🎯 Single Source of Truth +One declarative `mvp-hosts.yaml` generates all tool-specific configs. No more manual syncing. -### task.md — one executable, verifiable unit of work +### 🔒 Fail-Closed Gates +Mechanical gates (`verify`, `gate-check`, `audit`) exit with code 2 when blocked. No silent bypasses. -- **What it is**: a single Markdown file for one unit of work: background/goal, scope, non-goals, failure paths, acceptance criteria, Harness metadata (`test_strategy`, `wiki_delta`, …) and the human-gate table. `HG-AUDIT-R1` must be `approved` in that table before hat 30 may change code; `npx spec-wave verify --task ` reads the table as truth (chat claims do not count). -- **Where it comes from**: copy `docs/harness/templates/TASK_TEMPLATE.md`, materialized by `npx spec-wave sync prompts --yes`. The CLI never writes example tasks into your `docs/tasks/` — creating the file is always your explicit action. -- **Where it lives**: `docs/tasks/active/task_.md` while in flight; `npx spec-wave task close --file --yes` archives it to `docs/tasks/done/`. +### 📋 Harness Process +Task-driven workflow with: +- `task.md`: executable work units with approval gates +- `spec.md`: requirement specs with review gates +- `HG-AUDIT-R1`: human gate that must be `approved` before code changes -Minimal skeleton (full field list in the template): +### 🔄 Update Anywhere +After upgrading SpecWave, refresh all hosts with one command: -```markdown -# Task: add login rate limiting +```bash +npx spec-wave@3.0.2 host update --yes +``` -> **状态**：`draft` +Reads `.coding-kit/host-tools.json` (sticky selection) and regenerates only the tools you're using. -## Harness 元信息 -| 字段 | 值 | -|------|-----| -| **task_slug** | `login-rate-limit` | -| **test_strategy** | `required` | -| **wiki_delta** | `none` | +### 🧪 Test-Strategy Enforcement +When `test_strategy: required` in a task, the `verify` gate checks for real test artifacts: +- Test directories (`tests/`, `__tests__/`) +- Test config files (`jest.config.js`, `vitest.config.ts`, etc.) +- Test files (`*.test.ts`, `*_test.py`) +- CI with test steps -### 人工闸 - -| human_gate_id | status | blocks_hats | 说明 | -|---------------|--------|-------------|------| -| HG-AUDIT-R1 | pending | 30 | R1 审查后人签 | +Missing test artifacts → exit code 2 (BLOCKED). -## 范围 / ## 非范围 / ## 失败路径 / ## 验收标准 -（逐节照模板填写；验收须含可跑命令） -``` +--- -> **Gate table**: must be **4 columns** (last column `说明`). A 3-column table is **silently ignored** by the parser. Do **not** put bold `**` *inside* the id cell (that makes the whole row fail to parse); wrapping the whole id as `**HG-…**` is OK. +## Real-World Example -### spec.md — the requirement a task traces back to +A team maintaining coding standards for Cursor, Claude Code, and Copilot: -- **What it is**: the signed-off requirement spec (background / scope / non-scope / acceptance / failure paths) that a task references via `关联 SPEC`. `npx spec-wave verify --spec ` gates that a written review exists before implementation. -- **Where it comes from**: written by you or your agent (hat 10 flow) — the CLI does not materialize spec files. -- **Where it lives**: `docs/spec/` (this repo keeps specs under `docs/spec//`, e.g. `docs/spec/2_2-closed-loop-start/`). +```bash +# Before SpecWave: manually edit 3 files +vim .cursorrules +vim CLAUDE.md +vim .github/copilot-instructions.md + +# After SpecWave: edit one adapt table +vim .coding-kit/mvp-hosts.yaml +npx spec-wave host update --yes +# All 3 tools regenerated ✅ +``` -The same three-step chain is printed by `npx spec-wave init` (quickstart) — step 3 requires your project to be a git repository (run `git init` first if needed; `verify` checks git-root ownership). Terminology (Harness / hats / gates / S2) is collected in [GLOSSARY.md](GLOSSARY.md) (bilingual glossary — links back to this section). +**Time saved:** hours per update → seconds per update. +**Consistency:** guaranteed (single source of truth). +**Enforcement:** fail-closed gates prevent human error. --- -## Entry A · DSH plugin -Prefer npm (prebuilt, no allowBuilds needed): +## Installation & Setup + +### Prerequisites + +- **Node.js**: `^22.19.0` or `>=24.0.0` +- **Not supported**: Node 20 and earlier + +Check your version: ```bash -dsh plugin --profile web add spec-wave +node -v # expect v22.19+ or v24+ ``` -> **`dsh-coding-kit` is deprecated.** Use **`spec-wave`** as the DSH plugin package name (same product). +### Three Ways to Use SpecWave -Fallback: install from GitHub (needs a Node build; pnpm 10+ may require allowBuilds): +#### 1️⃣ CLI for Cursor / Claude Code / CI (Most Common) ```bash -dsh plugin --profile web add github:Cyning12/SpecWave#main +# Initialize with selected tools +npx spec-wave@3.0.2 init --preset harness-only --tools cursor,claude --yes + +# Or apply to existing repo +npx spec-wave@3.0.2 host apply --tools cursor,claude,copilot --profile core --yes ``` -### Confirmation layer +#### 2️⃣ DSH Plugin (Optional) ```bash -dsh --profile web --dump-config +# Install as DSH plugin +dsh plugin --profile web add spec-wave + +# In conversation: "Please apply the coding standards" +# Model calls: apply_coding_standards tool ``` -After a successful install, the profile's `package.json` will show the `spec-wave` dependency, and `dsh.profile.bundles` will contain the package name. Users generally don't need to hand-edit bundles; `dsh plugin add` maintains them. +#### 3️⃣ CI Integration + +Add to `.github/workflows/verify.yml`: -### Activation and invocation +```yaml +- name: Verify task gates + run: npx --yes spec-wave@3.0.2 verify --task docs/tasks/active/task_*.md +``` + +Exit code 2 = fail the build (gate blocked). -1. Start DSH with that profile (e.g. `dsh --profile web` / `dsh --profile web web`). -2. Say in the conversation: **Please apply the coding standards** (or "write code per the coding-kit standards"). -3. The model should call the `apply_coding_standards` tool. -4. On success, later turns' runtime context contains `# Coding Standards`. +--- -Optional parameters: `profile=l1|l1+l2|full` (default `l1+l2`); `persist=false` returns the body only in the current tool result. +## CLI Commands -Profile tier semantics: +### Core Commands -| Tier | Content | -|------|---------| -| `l1` | L1 standards + coding_wiki | -| `l1+l2` (default) | all standards + coding_wiki | -| `full` | **equivalent to `l1+l2` in the current version**; the enum value is reserved for future bundle extensions (differentiated injected content) | +```bash +# Process initialization +npx spec-wave init --preset harness-only --tools cursor,claude --yes + +# Host management +npx spec-wave host validate # Validate adapt table +npx spec-wave host apply --tools LIST --yes # Generate native files +npx spec-wave host update --yes # Refresh after upgrade + +# Gates (fail-closed: exit 2 on block) +npx spec-wave verify --task FILE # Pre-implementation gate +npx spec-wave verify --spec FILE # Review-existence gate +npx spec-wave gate-check --task FILE # Check human gates +npx spec-wave audit --task FILE # Audit trail check + +# Task management +npx spec-wave task lint --file FILE # Lint task file +npx spec-wave task close --file FILE # Archive to docs/tasks/done/ + +# Utilities +npx spec-wave check # Version check (always exit 0) +npx spec-wave sync prompts --yes # Materialize templates +``` -**Override root lookup rule (since 1.3.0)**: `apply_coding_standards` probes upward from the current working directory for `.coding-kit` and `.dsh/coding-kit`, stopping at the nearest ancestor directory containing `.git` (the git root) — so starting DSH from a monorepo subdirectory still hits the repo-root override, and directories above the git root are never picked up by mistake. Without `.git`, lookup continues to the filesystem root. The tool output's `source=override|package` and `root=` lines make the actual hit observable. +### Exit Codes (Fail-Closed) -When injected content exceeds 24k characters it is truncated at **file boundaries**: the cut only falls between files, never injecting half a file; skipped files can be derived from the full set under `root` minus the tool output's `files` list, and `truncated=true` carries the truncation marker. +| Code | Meaning | Commands | +|------|---------|----------| +| **0** | Pass or informational | `check` (always 0) | +| **1** | Usage error | Missing required flags | +| **2** | **Gate BLOCKED** (fail-closed) | `verify`, `gate-check`, `audit` | -### Initializing the project template (plugin surface) +**Do not remap exit code 2 to 0.** Treat it as a hard stop. -Initialization goes through the **`init_coding_kit`** tool (not the CLI `init`). +--- -Conversation: **Please initialize the coding-kit templates into this project** → the model calls `init_coding_kit`. -Then edit `.coding-kit/` and call `apply_coding_standards` again (`source=override`). `init_coding_kit` never overwrites existing files. +## Documentation -Note (asymmetric read/write roots, made explicit in 1.3.0): the **read side** (`apply_coding_standards`) looks up to the git root; the **write side** (`init_coding_kit`) still writes into the current working directory. Call `init_coding_kit` from a **repo-root** conversation, to avoid initializing in a monorepo subdirectory while the read side hits the repo root. +- **[GLOSSARY.md](GLOSSARY.md)**: Bilingual glossary of terms (task.md, Harness, hats, etc.) +- **[MIGRATION.md](MIGRATION.md)**: Migrate from `@cyning/harness` or `dsh-coding-kit` +- **[RELEASING.md](RELEASING.md)**: Release process for maintainers +- **[assets/ide/host-adapt/README.md](assets/ide/host-adapt/README.md)**: Full host matrix & CLI details -Some IDEs / yaml-language-server treat the root `cordis.patch.yml` as an RFC6902 JSON Patch and report missing `op` / `path` / `value`. This is a false positive and can be ignored; the file must keep the `- insert` form — do not convert it to JSON Patch. +--- -## Entry B · CLI (Cursor / Claude Code / CI) +## Migrating from @cyning/harness -P0 gates and G1–G7 (**delivered in 1.2.0**): +If you're using the old `@cyning/harness` package: ```bash -npx spec-wave init [--preset NAME] [--tools all|none|LIST] [--profile core|expanded] [--host-adapt|--no-host-adapt] [--yes] # NAME vocabulary: harness-only (the only legal value) -npx spec-wave upgrade --yes -npx spec-wave refresh-ide-blocks [--target PATH] [--dry-run] [--yes] [--json] -npx spec-wave check -npx spec-wave verify --task [--with-wiki-lint] # pre-30 gate; since 2.3: review file must also carry a machine-readable passing conclusion (G2) -npx spec-wave verify --spec # SPEC-to-00 review-existence gate (mutually exclusive with --task; --with-wiki-lint applies here too) -npx spec-wave verify # bare mode (2.3+): repo-wide reviews scan over both review dirs — done tasks fail-closed, active tasks info-only; legacy exemptions via docs/harness/legacy-gate-exempt.yaml -npx spec-wave gate-check --task -npx spec-wave audit --task -npx spec-wave task lint --file -npx spec-wave task close --file -npx spec-wave status [--target] [--task] [--json] [--check] -npx spec-wave timeline --task FILE -npx spec-wave lifecycle show [--target PATH] [--json] -npx spec-wave lifecycle dry-run --transition ID --from STATE -npx spec-wave discipline show [--target PATH] [--json] -npx spec-wave graph yaml compile|check|export -npx spec-wave graph ingest|snapshot|axioms -npx spec-wave graph ontology check [--file PATH] [--json] # + --hgm: instance check of the event-sourced graph against the bundled ontology -npx spec-wave sync index -npx spec-wave sync prompts [--target PATH] [--yes] [--force] [--json] -npx spec-wave skills install [--target DIR] [--out DIR] [--global] [--force] [--with-execute-hats] -npx spec-wave skills build [--with-execute-hats] -npx spec-wave skills check -npx spec-wave host validate [--file PATH] [--json] -npx spec-wave host apply --tools cursor,claude --profile core [--target PATH] [--file PATH] [--json] [--dry-run|--yes] -npx spec-wave host update [--tools LIST|all] [--profile core] [--target PATH] [--file PATH] [--json] [--dry-run|--yes] [--force] -npx spec-wave wiki export --json -npx spec-wave task lint-done -npx spec-wave task lint-wiki-delta -npx spec-wave task check --file PATH +# 1. Replace dependency +# In package.json: @cyning/harness → spec-wave (pin 3.0.2) + +# 2. Run upgrade +npx spec-wave@3.0.2 upgrade --yes + +# 3. Update scripts +# Replace: npx @cyning/harness → npx spec-wave ``` -`host apply` / `host update` sniff the host-adapt table version and optional `@deepseek-ai/dsh-tools` peer (**U-01**): mismatch → exit 2 and no writes (`--json` includes `contract.status`). `--tools dsh` keeps commands=[] (no `.dsh/commands/`) and lands orchestration as `.dsh/skills/kit-*`. **`host update` without `--tools`** uses sticky `.coding-kit/host-tools.json` (else exit 1). See **Multi-host in one package** above. +See [MIGRATION.md](MIGRATION.md) for the complete checklist. -This **source repo** dogfoods `graph yaml compile|check|export` against `docs/_tech_graph/` (**not** shipped in the npm package; https://github.com/Cyning12/SpecWave/tree/main/docs/_tech_graph). +--- -**Graph capability vs. ontology layer (3.0 ONTO-OPEN ruling)**: the graph surface is open — `graph yaml compile|check|export` works on consumer-authored graphs today, and `graph ontology check [--file PATH]` validates the bundled ontology file or a drifted copy you point it at. The bundled ontology (`assets/ontology.yaml`) is SpecWave's self-use meta-model, however — **不提供自定义本体能力**（the ontology layer is **not** open: no consumer-defined classes/relations; validator open ≠ ontology content open）. Re-examination triggers (research doc §7.3): a real consumer request · re-evaluation after the ontology-check surface stays stable for one minor · post-B5 ecosystem pull — via an HG-SCHEMA-CHANGE-style human gate. +## Why SpecWave? -`init` / `upgrade` / `sync index` / `skills build` never overwrite the S2 process domain (`docs/tasks/`, `docs/harness/reviews/`, `docs/harness/invokes/by-task/`, plus legacy bare `reviews/` / `invokes/by-task/`). **S2 prefix truth is a single shared constant** (`S2_TRUTH_PREFIXES` in `cli-shared`; F1 / 1.x MVP). `sync prompts` writes only the Starter whitelist under `docs/harness/prompts/` (**11** files) and `docs/harness/templates/TASK_TEMPLATE.md` — default dry-run; existing files with different content are listed as conflicts and are not overwritten unless you pass `--force`. +✅ **Consistency**: One adapt table, 13 tools. No drift. +✅ **Speed**: Update once, regenerate everywhere. +✅ **Enforcement**: Fail-closed gates prevent bypasses. +✅ **Transparency**: Exit codes + audit trails. +✅ **Flexibility**: Choose which tools to target (`--tools LIST`). -`verify --with-wiki-lint` (opt-in, non-breaking): appends the `lint-wiki-delta` check (default tier, `scope=all`) on top of the existing gates — effective in both `--task` and `--spec` modes. On a gap, verify is BLOCKED, lists the issues (which may come from sibling active/done tasks), and prints the exact same rerun command as PR CI: `npx --yes spec-wave task lint-wiki-delta --target .` (see `assets/ci/samples/lint-wiki-delta.yml.example`). `--json` gains a `wiki_lint` block (`ok` / `issues` / `scanned`). A target without `docs/tasks/` directories scans 0 files and never false-blocks. Without the flag, `verify` behaves exactly as before. +**If this saves you time, a ⭐ helps others find it.** -Since 1.7.0 the graph-facing behavior of `graph yaml export` / `graph yaml check` is corrected: ① export writes `graph_id` from the yaml-declared value (`data.graph_id`, e.g. `00_main`) as the single source of truth into graphs/nodes/edges, no longer the path-namespaced id (e.g. `l0/00_main`) — path ids remain input-compat only (`--graph-id` / file discovery); ② `check --all` filters graph.json slices with the same declared-value source as export output, so kit-produced root graph.json and check mutually recognize each other; ③ export preserves edge labels for every mark type (`?>` / `~>` / `::…` / `[…]`) — topology-protocol marks are carried as edge attributes instead of dropping the label text; ④ the Mermaid class block emitted by compile is driven by `nodes[].kind` (`flow`/`struct`/`external` → `phase`/`doc`/`infra`), with id-based inference kept as a fallback for nodes without `kind`. Exit codes are unchanged. **Consumer note**: consumers depending on the old export output (namespaced graph_id / dropped labels) must re-run `graph yaml export`. +--- -`check` compares `manifest.version` against the package version three ways (up-to-date / upgradeable / higher). Since 1.5.2, when the manifest carries a non-null `from_version` (i.e. it was migrated from the old `@cyning/harness` product line), a "higher" comparison reports a cross-product-line migration (`@cyning/harness X → spec-wave Y` — version numbers are not comparable across product lines) and suggests `npx spec-wave upgrade --yes`, instead of a misleading "possible downgrade" warning; since 1.7.0 this criterion is narrowed so only a `from_version` in the old product line's vocabulary (the 2.x series) takes the migration wording — a kit-line (1.x) `from_version` and `from_version: null` both keep the original three-way wording. The exit code is unchanged (always 0). +## Core Concepts (Deep Dive) -### refresh-ide-blocks (R-07 · literal refresh of stale commands in existing IDE blocks) +> **New here?** First-hour terms are defined in [GLOSSARY.md](GLOSSARY.md) (bilingual). -IDE blocks embedded by the wizard marker merge in the old `@cyning/harness` era (`` … ``) may still hold stale command literals. `refresh-ide-blocks` performs whitelisted literal replacement only inside such **product marker block bodies**: +### task.md — Executable Work Unit -- **Dry-run by default**: with no flag (or an explicit `--dry-run`) it only scans + reports — zero writes, exit 0; only `--yes` writes to disk. -- **Discovery surface (frozen whitelist)**: repo-root `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*.mdc` (single level). Files outside the discovery surface are not processed even if they contain markers. -- **Mapping table (frozen · effective only inside block bodies)**: +A `task.md` file describes one unit of work: - | Group | Rule | Behavior | - |-------|------|----------| - | A1 | `npx @cyning/harness` → `npx spec-wave` | auto-replaced; subcommand and arguments preserved verbatim | - | A2 | `npx @cyning/harness@` → `npx spec-wave` | auto-replaced; the version pin is dropped entirely (report records dropped_pin) | - | A3 | `npx --yes @cyning/harness[@]` → `npx --yes spec-wave` | auto-replaced; `--yes` kept, pin dropped | - | A4 | bare-bin forms `harness skills build` / `harness skills check` → `npx spec-wave skills build` / `npx spec-wave skills check` | auto-replaced (re-run guard when the line prefix already contains `npx spec-wave`) | - | A5 | `npx dsh-coding-kit` → `npx spec-wave` | auto-replaced (B-REFRESH · SpecWave rename) | - | A6 | `npx dsh-coding-kit@` → `npx spec-wave` | auto-replaced; pin dropped (dropped_pin) | - | A7 | `npx --yes dsh-coding-kit[@]` → `npx --yes spec-wave` | auto-replaced; `--yes` kept, pin dropped | - | B1–B5 | `CYNING_HARNESS` / `--with-scripts` / `wizard/` paths / `harness:` script names / other bare `@cyning/harness` references | **reported as "manual only", never replaced** | +- **Background & Goal**: What and why +- **Scope / Non-scope**: What's included, what's not +- **Failure Paths**: Known risks +- **Acceptance Criteria**: Runnable verification commands +- **Harness Metadata**: `test_strategy`, `wiki_delta` +- **Human Gate Table**: Must be 4 columns; `HG-AUDIT-R1` must be `approved` before hat 30 may change code -- **Discipline**: marker lines and out-of-block content stay byte-untouched; `` blocks are never rewritten; `docs/tasks/`, `docs/harness/reviews/`, `docs/harness/invokes/by-task/` (S2) are always write-refused. -- **preflight (--yes-only fail-fast, exit 2, zero writes)**: a dirty git tree / mixed old-and-new literals in one file (MIXED) / malformed marker pairing (MALFORMED) / any S2 assertion gate hit → refuse to write. The dirty-tree check follows `git status --porcelain` semantics — **untracked files count as dirty**, so commit or `git stash -u` before `--yes`. -- **Backup and rollback**: before `--yes` writes, the original bytes are backed up to `.coding-kit/backups/refresh-ide-blocks//` (keeping the latest 5 generations); for rollback prefer `git checkout -- `, or copy back from the backup in non-git repos. Backups are for local rollback only — consumers should add `.coding-kit/backups/` to `.gitignore` (do not commit them). Legacy `.cyning-harness/backups/` may still exist on older trees; new writes do not target it. -- **Marker-less files (report-only, never rewritten)**: discovery-surface files with 0 product blocks are scanned read-only with the same A/B rule set; hits appear in a "无 marker 检出（仅报告，不刷写）" human-report section and in the top-level `plain_mentions: [{path, rule, count}]` JSON field (schema stays `@1` — additive, backward-compatible). They never trigger the preflight fail-fast and never change the exit code. -- **Idempotent**: re-running on already-refreshed files yields 0 group-A hits, `files_written=0`, unchanged bytes, exit 0. -- `--json` prints a single-line machine report (schema `dsh-coding-kit/refresh-ide-blocks-report@1`; since 1.5.2 it additively includes `plain_mentions` / `totals.plain_mentions`). +**Location**: `docs/tasks/active/task_.md` while in flight. +**Archive**: `npx spec-wave task close --file FILE --yes` → moves to `docs/tasks/done/`. -### D5 test-artifact detection boundary (audit / verify · test_strategy=required) +Minimal skeleton: -When a task declares `test_strategy=required`, `audit` / `verify` run the D5 hard check: the target repo must contain **real test artifacts**, otherwise exit 2. D5 is artifact detection — it does not execute test commands. Detection scope (tightened in 1.3.0): +```markdown +# Task: add login rate limiting -**Strong-signal probes (presence = PASS)** +> **状态**: `draft` -- Directories: `test/` `tests/` `spec/` `specs/` `__tests__/` -- Config files: `jest.config.{js,ts}` `vitest.config.{js,ts}` `playwright.config.{js,ts}` `cypress.config.js` `pytest.ini` -- Test file names (within 3 levels of the repo root): `*.(test|spec).(js|ts|mjs|cjs)`, `*_test.py`, `test_*.py` +## Harness 元信息 +| 字段 | 值 | +|------|-----| +| **task_slug** | `login-rate-limit` | +| **test_strategy** | `required` | -**CI detection**: every `*.yml|*.yaml` under `.github/workflows/` is read as text; CI counts as having tests only if it hits one of these test-step patterns: `pytest` `vitest` `jest` `npm (run )?test` `pnpm (run )?test` `yarn test` `node --test` `go test` `cargo test` `tox` `unittest`, or a step `name:` containing `test`. +### 人工闸 +| human_gate_id | status | blocks_hats | 说明 | +|---------------|--------|-------------|------| +| HG-AUDIT-R1 | pending | 30 | R1 审查后人签 | -**Known false positives and the escape hatch** +## 范围 +Add rate limiting to login endpoint: max 5 attempts per 15 minutes per IP. -- `pyproject.toml` / `setup.py` are **no longer** treated as test artifacts (every modern Python repo has them, regardless of whether tests exist). -- Pure lint / pure deploy workflows (no test step) no longer pass. -- Detection depth is 3 levels from the repo root; for deeper monorepo layouts or custom test commands (e.g. `make test`) that miss the whitelist, drop any strong-signal file into the repo (e.g. a `tests/` directory, `*_test.py`). -- **WARN transition hardened (1.5.0)**: the transitional branch from 1.3.0–1.4.0 — "new detection fails but the old heuristic passes → `D5: WARN transition` exit 0, non-blocking" — has been removed; since 1.5.0 that situation is always a **FAIL** (verify BLOCKED / audit FAIL, exit 2). Before upgrading, add real test artifacts to the repo (e.g. `tests/`, `*_test.py`, `*.test.ts`, or CI with a test step). +## 验收标准 +- `pytest tests/test_rate_limit.py` passes +- Manual test: 6th attempt within 15min returns 429 +``` +### spec.md — Requirement Spec -### P0 gate exit codes (failClosed · F2 / 1.x MVP) +A `spec.md` file is the signed-off requirement spec that a task references: -| Code | Meaning | Typical commands | -|------|---------|------------------| -| **0** | Pass / informational | `check` **always** exits 0 (version advice only) | -| **1** | Usage error or non-blocking failure | Missing required flags, unknown args | -| **2** | **Gate BLOCKED** — failClosed; do not proceed | `verify` / `gate-check` / `audit` P0 failure; D5 missing artifacts when `test_strategy=required` | +- **Background / Scope / Non-scope** +- **Acceptance Criteria** +- **Failure Paths** -**failClosed**: a P0 gate failure exits **2**. CI and agents must treat 2 as hard stop (same family as Claude Code hook exit 2). Do not remap 2→0 locally to “keep going”. +**Location**: `docs/spec//` (e.g., `docs/spec/2_2-closed-loop-start/`) +**Gate**: `npx spec-wave verify --spec FILE` checks that a written review exists before implementation. -**Layered enforcement (document-level · 1.x — no cloud policy engine)**: +### Human Gates -1. Mechanical gate result in the consumer repo (`verify` / `gate-check` / `audit` exit 2) outranks local habit of skipping gates. -2. Task `HG-AUDIT-R1=approved` is required before hat 30 may change code. -3. Host hooks are **not** required for kit P0 — judgment is in-process CLI logic. +Human gates are approval checkpoints in the `task.md` table: +```markdown +| human_gate_id | status | blocks_hats | 说明 | +|---------------|--------|-------------|------| +| HG-AUDIT-R1 | approved | 30 | R1 审查后人签 | +``` -### pins consumer mode (consumer-repo version-pin freshness · 3.0.2+) +- **`HG-AUDIT-R1`**: R1 audit gate; must be `approved` before hat 30 (implementation) may change code +- **`HG-GRAPH-MODULES`**: D4-a gate; must be `approved` for module-graph changes -For repos that **consume** spec-wave. Upgrading used to mean hand-aligning several surfaces (exact pin in `package.json`, `spec-wave@` literals in CI workflows, version literals in test mocks); any missed surface drifts silently. `pins check --consumer` turns that into one mechanical CI gate (drift → exit 2): +`npx spec-wave verify --task FILE` reads this table as the source of truth (chat claims don't count). -- **Truth source (fallback chain)**: `package.json#devDependencies.spec-wave` → `#dependencies.spec-wave` → `#version`; first string wins. All three missing → exit 2 naming the full chain. Override explicitly with `--truth ` (e.g. `--truth package.json#devDependencies.spec-wave`; absolute paths and `../` are refused). -- **Exact versions**: `X.Y.Z` accepted as-is; `^`/`~` prefixes are normalized with a visible WARN (also in `--json` `warnings`); anything else (`*`, `workspace:*`, ranges) → exit 2 recommending an exact pin. -- **Default pin surface** (zero config): every `.github/workflows/*.{yml,yaml}` file that literally contains `@X.Y.Z` gets a synthesized pin; files without the literal are skipped (no false BLOCKED on unrelated workflows). -- **Optional declaration** `.spec-wave/pins-consumer.yaml` — replaces the default surface when present; malformed file → exit 2 failClosed (a broken declaration is never silently treated as absent): +### Hat System -```yaml -version: "1" -package_name: spec-wave # optional, default spec-wave -pins: - - id: consumer-test-mocks - path: tests/test_capability_harness_cli.py - extract: { kind: regex-all, pattern: 'spec-wave@(\d+\.\d+\.\d+)', flags: g } - expected: { kind: package-version } # = consumer truth version - required: true - fixable: true -``` +"Hats" are process roles: -- `pins fix --consumer` is dry-run by default; `--yes` writes (S2 process dirs stay mechanically write-refused). -- **Division of labor**: release mode (no flag) serves the spec-wave release repo itself (`assets/release-pins.yaml`); `--consumer` serves consumer repos. +- **Hat 00**: Delegate-only (no direct implementation) +- **Hat 10**: Spec/task drafting +- **Hat 20**: Spec/task audit +- **Hat 30**: Implementation (requires `HG-AUDIT-R1=approved`) +- **Hat 40**: Self-check +Skills for hats 10/20 are in `.cursor/skills/`, `.claude/skills/`, etc. (default install). +Skills for hats 30/40 are **not** installed by default (explicit `--with-execute-hats` required). -## Migrating from @cyning/harness +--- -Full checklist, layout rules (F4 scheme B), and **published** EOS / deprecate calendar: see [`MIGRATION.md`](./MIGRATION.md). +## Multi-Host Matrix (Detailed) -After pinning **spec-wave@3.0.2** you can drop `@cyning/harness`. Minimal path, three steps (required, in order): +One declarative adapt table → native landing on multiple hosts. Verify truth stays in the CLI (`failClosed` exit 2); IDE commands only orchestrate. -1. Replace the `devDependency` `@cyning/harness` with `spec-wave` (pin `3.0.2`; formerly `dsh-coding-kit`). -2. Run `npx spec-wave upgrade --yes` at the repo root (reads `.coding-kit/manifest.json` if present, else legacy `.cyning-harness/manifest.json`; **writes** `.coding-kit/manifest.json` with `version` pinned at 3.0.2 and `from_version` recording the old number; **does not delete** `.cyning-harness/`). -3. In CI / scripts, replace `npx @cyning/harness` / `npx dsh-coding-kit` with `npx spec-wave`. +**Note**: Installing the npm package does **not** materialize IDE files (no postinstall). Run `init --tools` or `host apply` explicitly. -**Layout**: new kit process files land under **`.coding-kit/`**. `.cyning-harness/` remains **legacy read-only**. Do not treat `.cyning-harness` as the new standard root. +| Host | Always-On Rules | Commands (profile `core`) | Skills | +|------|----------------|---------------------------|--------| +| **Cursor** | `.cursor/rules/*.mdc` | `.cursor/commands/kit-*.md` | `.cursor/skills/` | +| **Claude Code** | `CLAUDE.md` (marker block) | `.claude/commands/kit/.md` → `/kit:verb` | `.claude/skills/` | +| **DSH** | (empty) | `[]` (no `.dsh/commands/`) | `.dsh/skills/` (hats + orchestration) | +| **agents** | `AGENTS.md` fragment | `[]` | `.agents/skills/` | +| **Copilot** | `AGENTS.md` fragment | `[]` | `.github/skills/` | +| **Codex** | `AGENTS.md` fragment | `[]` | `.agents/skills/` | +| **Windsurf** | `AGENTS.md` fragment | `[]` | `.windsurf/skills/` | +| **Gemini CLI** | `GEMINI.md` | `[]` | `.gemini/skills/` | +| **opencode** | `AGENTS.md` fragment | `[]` | `.agents/skills/` | +| **Roo Code** | `AGENTS.md` fragment | `[]` | (no skills dir) | +| **Zed** | `AGENTS.md` fragment | `[]` | `.agents/skills/` | +| **Cline** | `AGENTS.md` fragment | `[]` | `.cline/skills/` | +| **aider** | `AGENTS.md` fragment (requires `--read`) | `[]` | (no skills dir) | -Skill installation is **recommended, not required** (the minimal path does not depend on DSH scanning skills). Commands are always `npx spec-wave`. **`@cyning/harness` is deprecated** on npm (2026-09-10 · maintainer-only); pin **`spec-wave@3.0.2`** and migrate via `MIGRATION.md`. +**2.2 W6 additions** (same package): Nine hosts reuse the `agents` asset face (zero new assets). Each landing follows the host's official docs. -### FAQ · pnpm peer +**2.1 additions** (same package): Claude `/kit:` namespace UX, DSH orchestration skills, optional `--profile expanded` for hat thin shells. -If pnpm install still fails on the peer chain (e.g. resolving to an unpublished host package): set `auto-install-peers=false` at the repo root (or one-shot `pnpm add -D spec-wave --config.auto-install-peers=false`). Even though **1.2.2** already marked cordis / dsh-tools as optional, keeping this fallback is recommended. +--- -### Copy-paste Prompt (for agents maintaining existing repos) +## Advanced: D5 Test-Artifact Detection -Paste the whole block: +When `test_strategy=required` in a task, `audit`/`verify` run the D5 check: the target repo must contain **real test artifacts**, else exit 2. -````text -You = the maintenance agent of this repository. Migrate this repo from @cyning/harness to spec-wave@3.0.2. +**Strong-signal probes** (presence = PASS): -Minimal path (required, in order): -1. package.json devDependency: delete @cyning/harness, replace with spec-wave (pinned at 3.0.2; formerly dsh-coding-kit). -2. Run at the repo root: npx spec-wave upgrade --yes - (reads .coding-kit/manifest.json or legacy .cyning-harness/manifest.json; writes .coding-kit/manifest.json; version pinned at 3.0.2, from_version records the old number; never deletes .cyning-harness/; never overwrites docs/tasks, reviews, invokes/by-task.) -3. Replace every npx @cyning/harness and npx dsh-coding-kit in CI and scripts with npx spec-wave. -Commands are always npx spec-wave. Never write npx @cyning/harness skills build again. -See MIGRATION.md for layout (.coding-kit vs legacy) and EOS calendar (pending human gates). +- Directories: `test/`, `tests/`, `spec/`, `specs/`, `__tests__/` +- Config files: `jest.config.{js,ts}`, `vitest.config.{js,ts}`, `playwright.config.{js,ts}`, `cypress.config.js`, `pytest.ini` +- Test file names (within 3 levels): `*.(test|spec).(js|ts|mjs|cjs)`, `*_test.py`, `test_*.py` -Recommended (not required · skill installation): -- In-repo: npx spec-wave skills install - Copies the pre-generated skills from the npm package (excluding 30/40 by default) into this repo's .dsh/skills. Existing files are not overwritten by default; add --force to overwrite. -- User-level: npx spec-wave skills install --global - Writes to $HOME/.dsh/skills (HOME is expanded; do not treat ~ as a relative path). +**CI detection**: Every `*.yml|*.yaml` under `.github/workflows/` is scanned for test-step patterns: `pytest`, `vitest`, `jest`, `npm test`, etc. -Path reference (never mix them up): -- .dsh/skills or $HOME/.dsh/skills = skill installation target (this command). -- .claude/skills or ~/.claude/skills = Claude Code's skill directory (this command does not write there by default; if you use Claude, copy separately or use --out). -- .dsh/coding-kit or .coding-kit = standards override (apply_coding_standards / init_coding_kit), NOT a skill directory. +**Known false positives**: `pyproject.toml`/`setup.py` alone are **not** test artifacts. For custom test commands (e.g., `make test`) not in the whitelist, add a strong-signal file (e.g., `tests/` directory). -Verified (against DSH upstream source): the DSH runtime automatically scans this repo's .dsh/skills and $HOME/.dsh/skills and loads them on demand. A skill is a /SKILL.md directory package or a flat .md file; frontmatter must include name/description; evidence anchors are in the README "Scan verification" section. +--- -Do NOT: GitHub Archive; npm publish / deprecate; make apply auto-inject at load time; install 30/40 by default; copy skills into .dsh/coding-kit. -```` +## Graph & Ontology (Advanced) -### Path reference +SpecWave includes graph capabilities for technical dependency modeling: -| Path | Purpose | Written by | -|------|---------|------------| -| Product package `assets/skills` | source of truth for generated artifacts; the comparison root of `skills check` | maintainer `skills build` (G5 freeze) | -| `/.dsh/skills` | consumer skill **installation target** | `skills install` | -| `$HOME/.dsh/skills` | user-level installation target | `skills install --global` | -| `/.claude/skills` or `~/.claude/skills` | Claude Code skill directory | user copies separately or uses `--out`; **not written by default** | -| `/.dsh/coding-kit` or `.coding-kit` | standards override (standards / wiki) | `init_coding_kit`; **forbidden** as a skill dest | +```bash +npx spec-wave graph yaml compile # Compile YAML graph → Mermaid +npx spec-wave graph yaml check # Validate graph structure +npx spec-wave graph yaml export # Export to graph.json +npx spec-wave graph ontology check # Validate ontology +``` -### Scan verification (checked against DSH upstream source) +**Ontology boundary** (3.0 ONTO-OPEN ruling): +- Graph surface is **open**: consumers can author their own graphs. +- Bundled ontology (`assets/ontology.yaml`) is **not open**: no consumer-defined classes/relations. +- Validator is open ≠ ontology content is open. -**Verified (2026-08-22 · against DSH upstream source deepseek-harness@141eb6f, i.e. dsh 0.1.0-rc.8)**: the DSH runtime **automatically scans** `/.dsh/skills` and `$HOME/.dsh/skills` and **loads them on demand** — these are exactly the two **installation targets** of this package's `skills install`. Evidence anchors: +This repo dogfoods `graph yaml compile|check|export` against `docs/_tech_graph/` (not shipped in npm package). -- `packages/skill/skill-filesystem/src/index.ts:246` — scans `/.dsh/skills` (source=`project-dsh`, rank 100); same file `:253` — scans `/skills` (`$DSH_HOME` or `~/.dsh`, source=`user-dsh`, rank 400). -- `docs/subsystems/skills.md` "Local discovery priority" table says the same (the rank 100/400 rows); loading mechanism: skill summaries are injected into the session catalog, and the model pulls the full body on demand via the `skill({ name })` tool (the "Session catalog and tool contract" section of that document). +--- -Structure and frontmatter requirements (same source): directory package `/SKILL.md` or flat `.md` (index.ts:724-728); frontmatter must include `name`/`description`, and `name` must be kebab-case (index.ts:810-816); projectRoot = the nearest ancestor directory containing `.git` (index.ts:937-947). +## Releasing (Maintainers) -Note: scanning/loading is a **behavioral contract of the DSH runtime** and evolves with upstream versions; the anchors above correspond to 0.1.0-rc.8. This package's responsibility ends at writing skills to the correct target and keeping frontmatter valid (`skills check`). +**Current package**: `spec-wave@3.0.2` — published (registry `latest=3.0.2`, tag `v3.0.2` ↔ tip `3d71b90`, verified 2026-09-24). -## Host usage (product Chat / communication agent) +Release process: see [RELEASING.md](RELEASING.md) — hard pre-publish checklist (commit-before-publish, four green gates, version pins, **human-only `npm publish`**). -Skills **do not** cover the full process surface. A Host that nests Harness process needs a Process Kernel object + CLI Capability + PromptAssembly slots — not a Skills copy alone. +--- -Recommended Capability allowlist (**Policy / H2 required**: default off · explicit Host-env grant · no arbitrary shell): +## GitHub Topics -- `npx --yes spec-wave@ verify …` -- `npx --yes spec-wave@ task …` +This repository's topics: `dsh-plugin`, `deepseek-harness`, `dsh-plugins`, `dsh`. -| Capability | Covered by Skills? | -|------------|-------------------| -| 10/20 audit guidance | Yes (default install) | -| 00 delegate-only | Weak: full 00 is not default; short delegate-only Skill is | -| 30/40 execute | Weak: not default (pre-T1); still needs `verify` | -| Gates / pre-30 / may_start_30 | **No**: CLI `verify` (or Host wrapping the same CLI) | -| Always-on hat system prompt | **No**: Skills are on-demand, not system | -| Host product Q&A | **No**: product Prompt Pack, not a harness Skill | +The npm keywords in `package.json` include `dsh-plugin` and `deepseek-harness`. -Three surfaces, not interchangeable: **System/Re-anchor** = short identity; **full prompts** = load on hat switch; **verify** = mechanical. +--- -## Releasing (maintainers) +## License -**Current package**: **`spec-wave@3.0.2`** — **published** (registry `latest=3.0.2` · `time.3.0.2`=2026-09-24T00:55:45.386Z · tag `v3.0.2` ↔ tip `3d71b90` · verified 2026-09-24). Prior published: **`3.0.1`** (signal-quality patch) · **`3.0.0`** (architecture leap) · **`2.4.2`** (acceptance-fixes patch) · **`2.4.1`** (acceptance-fixes patch) · **`2.4.0`** (gate strength) · **`2.3.1`** (acceptance-fixes patch) · **`2.3.0`** (wiring completion) · **`2.2.1`** (acceptance-fixes patch) · **`2.2.0`** (closed-loop start). +MIT -Release process: see [RELEASING.md](RELEASING.md) — hard pre-publish checklist (commit-before-publish · four green gates · version pins · Agent may bump/tag · **human-only `npm publish`**; institutionalizes the DEF-001 lesson). +--- -## GitHub topics +## Links -This repository's current GitHub topics: **`dsh-plugin`** (DSH's official discovery tag — see upstream deepseek-harness `README.md` and `CONTRIBUTING.md`; there is no app store), **`deepseek-harness`**, **`dsh-plugins`**, **`dsh`**. The npm keywords in `package.json` likewise include `dsh-plugin` and `deepseek-harness`. +- **npm**: [npmjs.com/package/spec-wave](https://www.npmjs.com/package/spec-wave) +- **Repository**: [github.com/Cyning12/SpecWave](https://github.com/Cyning12/SpecWave) +- **Issues**: [github.com/Cyning12/SpecWave/issues](https://github.com/Cyning12/SpecWave/issues) -## License +--- -MIT +Formerly SpecGate / `dsh-coding-kit` — rename history: [MIGRATION.md](MIGRATION.md). diff --git a/README.zh-CN.md b/README.zh-CN.md index 47d2428..af51a52 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,454 +1,487 @@ # SpecWave +[![npm 版本](https://img.shields.io/npm/v/spec-wave.svg)](https://www.npmjs.com/package/spec-wave) +[![许可证: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +**编写一次 AI 编码规则，SpecWave 将其原生安装到 Cursor、Claude Code、Copilot 等 10 多个工具中。** + 简体中文 | [English](README.md) -**SpecWave**（`spec-wave@3.0.2`）是 **多宿主编码 CLI**——单一声明式适配表原生落点 Cursor · Claude Code · 可选 DSH · agents 等——带 **P0 闸 / Harness 过程命令** 与 IDE 物化。纪律资产仍是 ICVO（Inform · Constrain · Verify · Orchestrate）。 +--- + +## 问题所在 + +手工维护每个 AI 编码工具的单独配置文件： + +``` +.cursorrules ← Cursor 规则（复制粘贴） +CLAUDE.md ← Claude Code 约定（重复） +.github/copilot-instructions.md ← Copilot 设置（也是重复） +.windsurf/rules.md ← Windsurf 规则（你懂的...） +``` -> **加载 ≠ 注入。** 安装或加载可选 DSH 插件 **不会** 自动改写 system prompt。`apply()` 只注册工具。必须由你或模型调用 `apply_coding_standards` 之后，后续回合的 runtime context 才会含 `# Coding Standards`。 -> -> **初见？** 首小时必懂术语——`task.md` / Harness / 帽制 / `kit-*`——见 [GLOSSARY.md](GLOSSARY.md)（双语术语表）。 -> -> 曾用名 SpecGate / `dsh-coding-kit`——改名史与迁移见 [MIGRATION.md](MIGRATION.md)。 +每次更新一个文件，就要手动同步其他文件。规则漂移，团队浪费时间。 -## Prerequisites（前置） +## SpecWave 解决方案 -| 要求 | 说明 | -|------|------| -| **Node.js** | **`^22.19.0` 或 `>=24.0.0`**（对齐 `package.json#engines`） | -| **不支持** | **Node 20**（及更早）会踩坑——engines 拒跑；装包 / `npx` 前请先升级 | +**单一真值源。** 一条命令。原生安装到所有工具。 ```bash -node -v # 期望 v22.19+ 或 v24+ +npx spec-wave host apply --tools cursor,claude,copilot,windsurf --yes ``` -## 最小上手（5 步） +SpecWave 读取你的声明式适配表，生成每个工具期望的原生配置文件： -主入口是 npm 包 **`spec-wave@3.0.2`** 的 **`npx spec-wave`**。插件面与 CLI 面互不替代。 +| 使用 SpecWave 之前 | 使用 SpecWave 之后 | +|-----------------|----------------| +| 手动维护 5+ 个配置文件 | 维护 **一个适配表** | +| 在工具间复制粘贴规则 | 运行 **一条命令** 同步所有工具 | +| 规则在工具间漂移 | **单一真值源** | +| 无强制执行 | **闭环门禁**（exit 2） | -```bash -# 1）确认包版本（推荐钉版） -npx spec-wave@3.0.2 --version +--- -# 2）校验适配表（dry） -npx spec-wave@3.0.2 host validate +## 快速开始 -# 3）物化宿主（先 dry-run，再写盘） -npx spec-wave@3.0.2 host apply --tools cursor,claude,dsh --profile core -npx spec-wave@3.0.2 host apply --tools cursor,claude,dsh --profile core --yes +```bash +# 1. 安装并初始化 +npx spec-wave@3.0.2 init --preset harness-only --tools cursor,claude --yes -# 4）或首次 init（过程根 + 宿主选型） -npx spec-wave@3.0.2 init --preset harness-only --tools cursor,claude,dsh --yes +# 2. 验证所有设置 +npx spec-wave@3.0.2 check -# 5）有 task.md 后跑机械闸（exit 2 = 硬停） -npx spec-wave@3.0.2 verify --task docs/tasks/active/task_.md +# 3. 应用编码标准到你的 IDE +# Cursor 用户：重启 Cursor 加载新规则 +# Claude Code 用户：重启 Claude Code 加载新命令 ``` -`--yes` 后：Cursor 可见 `kit-verify` 等；Claude Code `/kit:verify`；DSH `.dsh/skills/kit-*`。完整宿主矩阵与入口百科见 [一包多宿主矩阵](#一包多宿主矩阵) · [入口 A · DSH 插件](#入口-a--dsh-插件) · [入口 B · CLI](#入口-b--clicursor--claude-code--ci)。概念：[核心对象](#核心对象) · [GLOSSARY.md](GLOSSARY.md)。 +**就这样。** 你的编码规则现在在两个工具中都激活了。 -### 空仓：`test_strategy=required` 时如何最小可绿 +--- -CLI **永不**向你的 `docs/tasks/` 写入示例 task（S2）。模板须你自己复制： +## 支持的宿主（13 个工具） -1. `npx spec-wave@3.0.2 sync prompts --yes`（物化含 `docs/harness/templates/TASK_TEMPLATE.md`）。 -2. 复制模板 → `docs/tasks/active/task_.md`（你的显式动作）。 -3. 若元信息 **`test_strategy=required`**：帽 30 改实现**前**须先有关键路径的**可失败**自动化测试，再改实现至绿。 -4. 人工闸表须 **4 列**；`HG-AUDIT-R1` → `approved` 后帽 30 才可改码。 -5. `npx spec-wave@3.0.2 task lint --file docs/tasks/active/task_.md`，再 `verify --task …`。 +SpecWave 为每个宿主生成原生文件。一个适配表，13 个目标： -详见模板路径 · [核心对象](#核心对象) · [GLOSSARY.md](GLOSSARY.md)。 +| 宿主 | 生成的文件 | 备注 | +|------|----------------|-------| +| **Cursor** | `.cursor/rules/*.mdc`
`.cursor/commands/kit-*.md`
`.cursor/skills/` | 原生 Cursor 规则和命令 | +| **Claude Code** | `CLAUDE.md`
`.claude/commands/kit/*.md` → `/kit:*`
`.claude/skills/` | 产品 marker 块 + 命令 | +| **GitHub Copilot** | `AGENTS.md`
`.github/skills/` | 原生 GitHub skills 目录 | +| **Codex** | `AGENTS.md`
`.agents/skills/` | 仓库级扫描目录 | +| **Windsurf** | `AGENTS.md`
`.windsurf/skills/` | 原生 Windsurf skills | +| **Gemini CLI** | `GEMINI.md`
`.gemini/skills/` | 原生 Gemini 上下文文件 | +| **OpenCode** | `AGENTS.md`
`.agents/skills/` | Agent 兼容路径 | +| **Roo Code** | `AGENTS.md` | 通过 merged PR 加载 AGENTS.md | +| **Zed** | `AGENTS.md`
`.agents/skills/` | 项目本地目录 | +| **Cline** | `AGENTS.md`
`.cline/skills/` | 工作区 skills | +| **aider** | `AGENTS.md` | 注入层（需要 `aider --read AGENTS.md`） | +| **DSH** | `.dsh/skills/` | 帽子技能 + 编排 | +| **agents** | `AGENTS.md`
`.agents/skills/` | 通用 agents 标准 | -## 选哪条入口 +> **13 个宿主。一条命令。** 无需手动编辑文件。 -| 你是谁 | 入口 | 不要用 | -|--------|------|--------| -| Cursor / Claude Code / CI · 存量仓 | `npx spec-wave`（可选 `host apply`） | 不要把插件 `init_coding_kit` 与 CLI `init` 当成同一入口 | -| DSH 会话 / 模型调工具（可选） | `dsh plugin add spec-wave`（旧包 `dsh-coding-kit` **已 deprecate**，勿再 add 旧名） | 不要只 `npm install`（缺 bundle 层则工具不出现） | +--- -过渡 bin `specgate` / `dsh-coding-kit` 仍可用；新脚本请一律 `npx spec-wave`。 +## 为什么要闭环门禁？ -### 一包多宿主矩阵 +SpecWave 包含强制执行过程纪律的 **P0 门禁**： -单一声明式适配表 → 多个宿主原生落点（always_on + skills + **commands**）。Verify 真值仍在 CLI（`failClosed` exit **2**）；IDE slash/command 只编排。**装 npm 包不会自动物化 IDE 文件**（无 postinstall）；须显式跑 `init --tools` / `host apply`。 +```bash +# 更改代码前，验证任务批准 +npx spec-wave verify --task docs/tasks/active/task_login-limit.md +# 退出码 2（阻塞）= 不要继续 +# 退出码 0（通过）= 已批准，继续 +``` -| 宿主 | `host apply`（profile `core`）写入 | -|------|-------------------------------------| -| **Cursor** | `.cursor/rules/*.mdc` · `.cursor/commands/kit-*.md` · `.cursor/skills/` | -| **Claude Code** | `CLAUDE.md` 产品 marker 块 · `.claude/commands/kit/.md` → **`/kit:verb`** · `.claude/skills/` | -| **DSH** | `.dsh/skills/` — 帽子技能 **+** 编排 `kit-*`（`/` 可发现；**不**建 `.dsh/commands/`） | -| **agents**（可选） | `AGENTS.md` 片段 · `.agents/skills/` | -| **Copilot** | `AGENTS.md` 片段（共享 marker 块）· `.github/skills/` | -| **Codex** | `AGENTS.md` 片段（共享 marker 块）· `.agents/skills/` | -| **Windsurf** | `AGENTS.md` 片段（共享 marker 块）· `.windsurf/skills/` | -| **Gemini CLI** | `GEMINI.md`（同一份宿主中立片段）· `.gemini/skills/` | -| **opencode** | `AGENTS.md` 片段（共享 marker 块）· `.agents/skills/` | -| **Roo Code** | `AGENTS.md` 片段（共享 marker 块 · 官方仓 merged PR 加载）· 不物化 skills（无官方目录约定） | -| **Zed** | `AGENTS.md` 片段（共享 marker 块）· `.agents/skills/` | -| **Cline** | `AGENTS.md` 片段（共享 marker 块）· `.cline/skills/` | -| **aider**（注入层） | `AGENTS.md` 片段（注入层支持：aider **不会**自动加载 AGENTS.md——须 `aider --read AGENTS.md` 或在 `.aider.conf.yml` 写 `conventions-file: AGENTS.md`）· 不物化 skills（无官方约定） | +**闭环**意味着：如果门禁失败，命令以退出码 `2`（不是 `0` 或 `1`）退出。CI 和 agent **必须**将退出码 `2` 视为硬停止。 -**2.2 W6 / 2.3 W6 宿主增量**（同一包）：上述九宿主复用 **agents** 资产面（零新资产）；落点逐宿主官方文档取证，无官方 skills 目录约定的宿主不物化 skills（永不强造目录）。aider 为如实标注的降级——仅注入层。 +- **退出 0**：通过 +- **退出 1**：用法错误（非阻塞） +- **退出 2**：门禁阻塞 — **不要继续** -**2.1 增量**（同一包）：Claude `/kit:` 命名空间 · DSH `.dsh/skills/kit-*` 编排 · 可选 `--profile expanded` 物化 `kit-hat-*` 薄壳（默认仍 `core`）。 +这确保了： +- 代码更改前的人工批准 +- 需要时测试制品存在 +- 实现前审查文件存在 +- 没有静默失败 -**2.1.1 · 安装/升级 UX**（对齐 OpenSpec `init --tools`）： +--- -| 主题 | 行为 | -|------|------| -| 粘性 | `host apply` / `host update` / `init`（含物化）在 `--yes` 成功写盘后更新 `.coding-kit/host-tools.json`（`host_ids` + `profile`）。dry-run **不**写粘性。 | -| `--tools` | `LIST`（如 `cursor,claude,dsh`）· `all`（适配表全部 host_id）· `none`（**仅 init**：只过程根、不物化）。`host apply` **必须**带 `--tools`。 | -| `host update`（方案 **A**） | 解析序：CLI `--tools` → 粘性 → 否则 **exit 1**。有粘性时 `host update --yes` **只**刷已选宿主。相对 2.1.0「省略 `--tools` = 全表」为 **BREAKING（小）**。 | -| `init` | TTY 无 `--tools` → **询问**（多选 / all / none）。非 TTY / CI 无 `--tools` → **exit 1**。`tools≠none` 且未 `--no-host-adapt` → 同进程 `host apply` + 写粘性。`--no-host-adapt` → 不 apply **亦不**写粘性。 | +## 终端演示 -```bash -# 升包后：刷粘性已选宿主（不必再抄 --tools） -npx spec-wave@3.0.2 host update --yes -``` + -完整矩阵见 [`assets/ide/host-adapt/README.md`](assets/ide/host-adapt/README.md)；录屏清单见 [`docs/guides/DOGFOOD_host_adapt_cursor_claude_录屏清单_v1_zh.md`](docs/guides/DOGFOOD_host_adapt_cursor_claude_录屏清单_v1_zh.md)；规划见 [`docs/roadmap/PLAN_2_1_1_host_tools_ux_v1_zh.md`](docs/roadmap/PLAN_2_1_1_host_tools_ux_v1_zh.md)。 +**演示占位符：** 待添加真实终端录制。 +显示：`host apply` → 生成原生文件 → `verify` 门禁检查。 -`peerDependencies` 中的 `@deepseek-ai/cordis` 与 `@deepseek-ai/dsh-tools` 是 **DSH 宿主插件契约**（仅宿主加载本包为插件时需要；CLI-only 不需要），已在 `peerDependenciesMeta` 标为 **optional**。 +--- -## 核心对象 +## 特性 -Harness 过程围绕两个文件级对象运转。`verify --task ` / `gate-check --task ` / `task close` 都作用于第一个——在你于命令清单里遇到它们之前，本节先给出定义。 +### 🎯 单一真值源 +一个声明式 `mvp-hosts.yaml` 生成所有工具特定的配置。无需手动同步。 -### task.md —— 一个可执行、可验收的工作单元 +### 🔒 闭环门禁 +机械门禁（`verify`、`gate-check`、`audit`）在阻塞时以退出码 2 退出。没有静默绕过。 -- **是什么**：一个 Markdown 文件描述一个工作单元：背景与目标、范围、非范围、失败路径、验收标准、Harness 元信息（`test_strategy`、`wiki_delta` 等）与人工闸表。闸表中 `HG-AUDIT-R1` 必须为 `approved`，帽 30 才可改码；`npx spec-wave verify --task ` 以闸表为真值（聊天声称不算数）。 -- **从哪来**：复制 `docs/harness/templates/TASK_TEMPLATE.md`——由 `npx spec-wave sync prompts --yes` 物化。CLI 永不向你的 `docs/tasks/` 写入示例 task；是否落文件永远由你显式执行。 -- **放哪**：在途放 `docs/tasks/active/task_.md`；`npx spec-wave task close --file --yes` 验收归档至 `docs/tasks/done/`。 +### 📋 Harness 过程 +任务驱动的工作流程： +- `task.md`：带批准门禁的可执行工作单元 +- `spec.md`：带审查门禁的需求规格 +- `HG-AUDIT-R1`：在更改代码前必须 `approved` 的人工门禁 -最小骨架（完整字段见模板）： +### 🔄 随处更新 +升级 SpecWave 后，用一条命令刷新所有宿主： -```markdown -# Task：加登录限流 +```bash +npx spec-wave@3.0.2 host update --yes +``` -> **状态**：`draft` +读取 `.coding-kit/host-tools.json`（粘性选择）并只重新生成你正在使用的工具。 -## Harness 元信息 -| 字段 | 值 | -|------|-----| -| **task_slug** | `login-rate-limit` | -| **test_strategy** | `required` | -| **wiki_delta** | `none` | +### 🧪 测试策略强制 +当任务中 `test_strategy: required` 时，`verify` 门禁检查真实测试制品： +- 测试目录（`tests/`、`__tests__/`） +- 测试配置文件（`jest.config.js`、`vitest.config.ts` 等） +- 测试文件（`*.test.ts`、`*_test.py`） +- 带测试步骤的 CI -### 人工闸 - -| human_gate_id | status | blocks_hats | 说明 | -|---------------|--------|-------------|------| -| HG-AUDIT-R1 | pending | 30 | R1 审查后人签 | +缺少测试制品 → 退出码 2（阻塞）。 -## 范围 / ## 非范围 / ## 失败路径 / ## 验收标准 -（逐节照模板填写；验收须含可跑命令） -``` +--- -> **闸表**：须 **4 列**（末列为 `说明`）；**3 列会被静默忽略**。**id 单元格内不要用粗体**（内嵌 `**` 会导致整行解析失败；外层整格包裹 `**HG-…**` 仍可解析）。 +## 真实世界示例 -### spec.md —— task 回溯的需求规格 +一个团队为 Cursor、Claude Code 和 Copilot 维护编码标准： -- **是什么**：已签的需求规格（背景 / 范围 / 非范围 / 验收 / 失败路径），task 通过 `关联 SPEC` 引用它。`npx spec-wave verify --spec ` 闸「实现前须已有书面审查」。 -- **从哪来**：由你或你的 Agent 撰写（帽 10 流程）——CLI 不物化 spec 文件。 -- **放哪**：`docs/spec/`（本仓按主题分目录，如 `docs/spec/2_2-closed-loop-start/`）。 +```bash +# 使用 SpecWave 前：手动编辑 3 个文件 +vim .cursorrules +vim CLAUDE.md +vim .github/copilot-instructions.md + +# 使用 SpecWave 后：编辑一个适配表 +vim .coding-kit/mvp-hosts.yaml +npx spec-wave host update --yes +# 所有 3 个工具重新生成 ✅ +``` -同一条三步链由 `npx spec-wave init` 打印（quickstart）——第 3 步前提：项目须为 git 仓（先 `git init`；`verify` 有 git-root 归属校验）。术语（Harness / 帽制 / 门禁 / S2）汇总于 [GLOSSARY.md](GLOSSARY.md)（双语术语表 · 回链本节）。 +**节省的时间：** 每次更新从几小时 → 几秒钟。 +**一致性：** 有保证（单一真值源）。 +**强制执行：** 闭环门禁防止人为错误。 --- -## 入口 A · DSH 插件 -优先 npm（预构建，无需 allowBuilds）： +## 安装与设置 + +### 前置要求 + +- **Node.js**：`^22.19.0` 或 `>=24.0.0` +- **不支持**：Node 20 及更早版本 + +检查你的版本： ```bash -dsh plugin --profile web add spec-wave +node -v # 期望 v22.19+ 或 v24+ ``` -> **`dsh-coding-kit` 已 deprecate。** DSH 插件请装正式包名 **`spec-wave`**（同一产品）。 +### 使用 SpecWave 的三种方式 -备选：从 GitHub 安装（需 Node 构建；pnpm 10+ 可能要 allowBuilds）： +#### 1️⃣ CLI 用于 Cursor / Claude Code / CI（最常见） ```bash -dsh plugin --profile web add github:Cyning12/SpecWave#main +# 用选定的工具初始化 +npx spec-wave@3.0.2 init --preset harness-only --tools cursor,claude --yes + +# 或应用到现有仓库 +npx spec-wave@3.0.2 host apply --tools cursor,claude,copilot --profile core --yes ``` -### 确认层 +#### 2️⃣ DSH 插件（可选） ```bash -dsh --profile web --dump-config +# 作为 DSH 插件安装 +dsh plugin --profile web add spec-wave + +# 在对话中："请应用编码标准" +# 模型调用：apply_coding_standards 工具 ``` -安装成功后，profile 的 `package.json` 会出现依赖 `spec-wave`，且 `dsh.profile.bundles` 含该包名。用户一般不必手写 bundles；`dsh plugin add` 会维护。 +#### 3️⃣ CI 集成 + +添加到 `.github/workflows/verify.yml`： -### 激活与调用 +```yaml +- name: 验证任务门禁 + run: npx --yes spec-wave@3.0.2 verify --task docs/tasks/active/task_*.md +``` + +退出码 2 = 构建失败（门禁阻塞）。 -1. 用该 profile 启动 DSH（例如 `dsh --profile web` / `dsh --profile web web`）。 -2. 在对话中说：**请应用 coding standards**（或「按 coding-kit 规范写代码」）。 -3. 模型应调用工具 `apply_coding_standards`。 -4. 成功后后续回合的 runtime context 含 `# Coding Standards`。 +--- -可选参数：`profile=l1|l1+l2|full`（默认 `l1+l2`）；`persist=false` 表示只在当轮工具结果里给出正文。 +## CLI 命令 -profile 档语义： +### 核心命令 -| 档 | 内容 | -|----|------| -| `l1` | L1 规范 + coding_wiki | -| `l1+l2`（默认） | 全部 standards + coding_wiki | -| `full` | **当前版本等价于 `l1+l2`**；保留枚举值，为后续扩展 bundle（差异化注入内容）预留 | +```bash +# 过程初始化 +npx spec-wave init --preset harness-only --tools cursor,claude --yes + +# 宿主管理 +npx spec-wave host validate # 验证适配表 +npx spec-wave host apply --tools LIST --yes # 生成原生文件 +npx spec-wave host update --yes # 升级后刷新 + +# 门禁（闭环：阻塞时 exit 2） +npx spec-wave verify --task FILE # 实现前门禁 +npx spec-wave verify --spec FILE # 审查存在性门禁 +npx spec-wave gate-check --task FILE # 检查人工门禁 +npx spec-wave audit --task FILE # 审计追踪检查 + +# 任务管理 +npx spec-wave task lint --file FILE # Lint 任务文件 +npx spec-wave task close --file FILE # 归档到 docs/tasks/done/ + +# 工具 +npx spec-wave check # 版本检查（始终 exit 0） +npx spec-wave sync prompts --yes # 物化模板 +``` -**override 根查找规则（自 1.3.0）**：`apply_coding_standards` 从当前工作目录逐级向上探测 `.coding-kit` 与 `.dsh/coding-kit`，在最近的含 `.git` 的祖先目录（git root）处截止——monorepo 子目录启动 DSH 也能命中仓根 override；git root 之外的更上层目录不会被误吸。无 `.git` 时向上查找到文件系统根。工具输出的 `source=override|package` 与 `root=` 行可观测实际命中。 +### 退出码（闭环） -注入内容超 24k 字符时按**文件边界**截断：截断点只落在文件之间，不会注入半份文件；被略文件可由 `root` 下全集减去工具输出的 `files` 列表推出，且 `truncated=true` 附截断标记。 +| 代码 | 含义 | 命令 | +|------|---------|----------| +| **0** | 通过或信息性 | `check`（始终 0） | +| **1** | 用法错误 | 缺少必需标志 | +| **2** | **门禁阻塞**（闭环） | `verify`、`gate-check`、`audit` | -### 初始化项目模板（插件面） +**不要将退出码 2 重映射为 0。** 将其视为硬停止。 -初始化走工具 **`init_coding_kit`**（不是 CLI `init`）。 +--- -对话：**请把 coding-kit 模板初始化到本项目** → 模型调用 `init_coding_kit`。 -之后修改 `.coding-kit/`，再调用 `apply_coding_standards`（`source=override`）。`init_coding_kit` 不覆盖已有文件。 +## 文档 -注意（读写根口径不对称，自 1.3.0 明示）：**读取面**（`apply_coding_standards`）向上查找到 git root；**写入面**（`init_coding_kit`）仍写入当前工作目录。请在**仓根**对话中调用 `init_coding_kit`，避免在 monorepo 子目录里初始化后读取面却命中仓根。 +- **[GLOSSARY.md](GLOSSARY.md)**：术语双语词汇表（task.md、Harness、帽子等） +- **[MIGRATION.md](MIGRATION.md)**：从 `@cyning/harness` 或 `dsh-coding-kit` 迁移 +- **[RELEASING.md](RELEASING.md)**：维护者发布流程 +- **[assets/ide/host-adapt/README.md](assets/ide/host-adapt/README.md)**：完整宿主矩阵与 CLI 详情 -部分 IDE / yaml-language-server 会把根目录 `cordis.patch.yml` 当成 RFC6902 JSON Patch，报缺 `op` / `path` / `value`。这是误报，可忽略；该文件必须保持 `- insert`，不要改成 JSON Patch。 +--- -## 入口 B · CLI（Cursor / Claude Code / CI） +## 从 @cyning/harness 迁移 -P0 闸与 G1–G7（**1.2.0 已交付**）： +如果你正在使用旧的 `@cyning/harness` 包： ```bash -npx spec-wave init [--preset NAME] [--tools all|none|LIST] [--profile core|expanded] [--host-adapt|--no-host-adapt] [--yes] # NAME 词表: harness-only（唯一合法值） -npx spec-wave upgrade --yes -npx spec-wave refresh-ide-blocks [--target PATH] [--dry-run] [--yes] [--json] -npx spec-wave check -npx spec-wave verify --task [--with-wiki-lint] # 30 前闸；2.3 起审查文还须含可机读通过结论（G2 结论级） -npx spec-wave verify --spec # SPEC→00 前审查文存在性闸（与 --task 互斥 · --with-wiki-lint 同生效） -npx spec-wave verify # 裸模式（2.3 起）：仓级 reviews 双路径全量扫描 —— done failClosed · active 仅信息报告；存量豁免走 docs/harness/legacy-gate-exempt.yaml -npx spec-wave gate-check --task -npx spec-wave audit --task -npx spec-wave task lint --file -npx spec-wave task close --file -npx spec-wave status [--target] [--task] [--json] [--check] -npx spec-wave timeline --task FILE -npx spec-wave lifecycle show [--target PATH] [--json] -npx spec-wave lifecycle dry-run --transition ID --from STATE -npx spec-wave discipline show [--target PATH] [--json] -npx spec-wave graph yaml compile|check|export -npx spec-wave graph ingest|snapshot|axioms -npx spec-wave graph ontology check [--file PATH] [--json] # 另支持 --hgm：事件轨图谱实例 ⊆ 随包本体词汇校验 -npx spec-wave sync index -npx spec-wave sync prompts [--target PATH] [--yes] [--force] [--json] -npx spec-wave skills install [--target DIR] [--out DIR] [--global] [--force] [--with-execute-hats] -npx spec-wave skills build [--with-execute-hats] -npx spec-wave skills check -npx spec-wave host validate [--file PATH] [--json] -npx spec-wave host apply --tools cursor,claude --profile core [--target PATH] [--file PATH] [--json] [--dry-run|--yes] -npx spec-wave host update [--tools LIST|all] [--profile core] [--target PATH] [--file PATH] [--json] [--dry-run|--yes] [--force] -npx spec-wave wiki export --json -npx spec-wave task lint-done -npx spec-wave task lint-wiki-delta -npx spec-wave task check --file PATH +# 1. 替换依赖 +# 在 package.json 中：@cyning/harness → spec-wave（钉 3.0.2） + +# 2. 运行升级 +npx spec-wave@3.0.2 upgrade --yes + +# 3. 更新脚本 +# 替换：npx @cyning/harness → npx spec-wave ``` -`host apply` / `host update` 嗅探适配表 version 与可选 `@deepseek-ai/dsh-tools` peer（**U-01**）：不匹配 → exit 2、零写入（`--json` 含 `contract.status`）。`--tools dsh` 仍 commands=[]（不建 `.dsh/commands/`），编排落在 `.dsh/skills/kit-*`。**`host update` 省略 `--tools`** 时读粘性 `.coding-kit/host-tools.json`（否则 exit 1）。落点见上方 **一包多宿主**。 +完整清单见 [MIGRATION.md](MIGRATION.md)。 -kit **源码仓**以 `docs/_tech_graph/` 做 `graph yaml compile|check|export` 的 dogfood（**不随 npm 包发布**；https://github.com/Cyning12/SpecWave/tree/main/docs/_tech_graph）。 +--- -**图能力与本体的边界（3.0 ONTO-OPEN 裁决）**：图能力已开放 —— `graph yaml compile|check|export` 与消费者自建图今天可用，`graph ontology check [--file PATH]` 可校验随包本体或你指定的漂移副本；但随包本体（`assets/ontology.yaml`）是 SpecWave 自用元模型，**不提供自定义本体能力**（本体层不开放 · 消费者不可自定义类/关系 · 校验器开放 ≠ 本体内容开放）。复议触发（研究文 §7.3）：真实消费者请求 · ontology-check 面稳定一个 minor 后重估 · B5 后生态拉取 —— 走 HG-SCHEMA-CHANGE 式人闸。 +## 为什么选择 SpecWave？ -`init` / `upgrade` / `sync index` / `skills build` 不覆盖 S2 过程域（`docs/tasks/`、`docs/harness/reviews/`、`docs/harness/invokes/by-task/`，以及 legacy 裸 `reviews/` / `invokes/by-task/`）。**S2 前缀真值源唯一**（`cli-shared` 的 `S2_TRUTH_PREFIXES`；F1 / 1.x MVP）。`sync prompts` 仅写入 Starter 白名单（`docs/harness/prompts/` **11** 文件 + `docs/harness/templates/TASK_TEMPLATE.md`）——默认 dry-run；本地内容与包内不同则列为 conflict 且不覆盖（`--force` 显式覆盖）。 +✅ **一致性**：一个适配表，13 个工具。无漂移。 +✅ **速度**：更新一次，随处重新生成。 +✅ **强制执行**：闭环门禁防止绕过。 +✅ **透明度**：退出码 + 审计追踪。 +✅ **灵活性**：选择要针对的工具（`--tools LIST`）。 -`verify --with-wiki-lint`（显式旗标 · 非破坏）：在既有检查之上追加 `lint-wiki-delta`（默认档 · `scope=all`），`--task` 与 `--spec` 模式同生效。有缺口时 verify 判 BLOCKED，列出 issue（缺口可能来自兄弟 active/done task），并打印与 PR CI 逐字一致的复跑命令 `npx --yes spec-wave task lint-wiki-delta --target .`（见 `assets/ci/samples/lint-wiki-delta.yml.example`）；`--json` 增 `wiki_lint` 块（`ok` / `issues` / `scanned`）。target 无 `docs/tasks/` 目录时 scanned:0，不会误 BLOCKED。无旗标时 `verify` 行为与之前逐字一致。 +**如果这节省了你的时间，一个 ⭐ 可以帮助其他人找到它。** -`graph yaml export` / `graph yaml check` 的 graph 面行为自 1.7.0 起修正：① export 的 `graph_id` 以 yaml 声明值（`data.graph_id`，如 `00_main`）为唯一真值源写入 graphs/nodes/edges，不再用路径命名空间 id（如 `l0/00_main`）——路径 id 仅作输入兼容定位（`--graph-id` / 文件发现）；② `check --all` 的 graph.json 切片过滤口径与 export 输出对齐（同一声明值真值源），kit 自产根 json 与 check 互认；③ export 保留全部 mark 类型（`?>` / `~>` / `::…` / `[…]`）的边 label（拓扑协议标记作为边属性呈现，不再丢弃 label 文本）；④ compile 生成的 Mermaid class 段按 `nodes[].kind`（`flow`/`struct`/`external` → `phase`/`doc`/`infra`）生成，无 `kind` 时保留 id 推断作兜底。exit 码不变。**消费者注意**：依赖旧 export 输出（命名空间 graph_id / 空 label）的消费方需重跑 `graph yaml export`。 +--- -`check` 对 `manifest.version` 与包版本做三向比较（已是最新 / 可升级 / 高于）。自 1.5.2 起，当 manifest 带非 null `from_version`（即从旧 `@cyning/harness` 产品线迁来）时，「高于」分支输出跨产品线迁移语义（`@cyning/harness X → spec-wave Y`——跨产品线版本号不可比）并建议 `npx spec-wave upgrade --yes`，不再误报「可能为降级安装」；自 1.7.0 起该判据收窄为 `from_version` 属旧包产品线词表（2.x 系列）才走迁移文案，kit 线（1.x）`from_version` 与 `from_version: null` 均保留原三向文案。exit 码不变（恒 0）。 +## 核心概念（深入） -### refresh-ide-blocks（R-07 · 存量 IDE 块旧命令字面刷写） +> **初见？** 首小时术语在 [GLOSSARY.md](GLOSSARY.md) 中定义（双语）。 -旧包 `@cyning/harness` 时代 wizard marker merge 嵌入的 IDE 块（`` … ``）内可能滞留旧命令字面。`refresh-ide-blocks` 仅在这类 **product marker 块体内** 做白名单字面替换： +### task.md — 可执行工作单元 -- **默认 dry-run**：无旗标（或显式 `--dry-run`）只扫描 + 报告，零写入，exit 0；`--yes` 才写盘。 -- **发现面（冻结白名单）**：仓根 `AGENTS.md`、`CLAUDE.md`、`.cursor/rules/*.mdc`（单层）。发现面之外的文件即使含 marker 也不处理。 -- **映射表（冻结 · 仅块体内生效）**： +一个 `task.md` 文件描述一个工作单元： - | 组 | 规则 | 行为 | - |----|------|------| - | A1 | `npx @cyning/harness` → `npx spec-wave` | 自动替换，子命令与参数原样保留 | - | A2 | `npx @cyning/harness@` → `npx spec-wave` | 自动替换，钉版整体丢弃（报告记 dropped_pin） | - | A3 | `npx --yes @cyning/harness[@]` → `npx --yes spec-wave` | 自动替换，`--yes` 保留、钉版丢弃 | - | A4 | 裸 bin 形态 `harness skills build` / `harness skills check` → `npx spec-wave skills build` / `npx spec-wave skills check` | 自动替换（行前缀已含 `npx spec-wave` 时防二刷） | - | A5 | `npx dsh-coding-kit` → `npx spec-wave` | 自动替换（B-REFRESH · SpecGate 改名） | - | A6 | `npx dsh-coding-kit@` → `npx spec-wave` | 自动替换，钉版丢弃（dropped_pin） | - | A7 | `npx --yes dsh-coding-kit[@]` → `npx --yes spec-wave` | 自动替换，`--yes` 保留、钉版丢弃 | - | B1–B5 | `CYNING_HARNESS` / `--with-scripts` / `wizard/` 路径 / `harness:` script 名 / 其他裸 `@cyning/harness` 引用 | **仅报告「需人工」，不替换** | +- **背景与目标**：是什么和为什么 +- **范围 / 非范围**：包含什么，不包含什么 +- **失败路径**：已知风险 +- **验收标准**：可运行的验证命令 +- **Harness 元信息**：`test_strategy`、`wiki_delta` +- **人工门禁表**：必须 4 列；`HG-AUDIT-R1` 必须为 `approved`，帽 30 才可改码 -- **纪律**：marker 行与块外内容字节不动；`` 块永不改写；`docs/tasks/`、`docs/harness/reviews/`、`docs/harness/invokes/by-task/`（S2）一律拒写。 -- **preflight（--yes 专用 fail-fast，exit 2 零写入）**：git 脏树 / 单文件新旧字面混杂（MIXED）/ marker 配对畸形（MALFORMED）/ S2 断言闸任一命中即拒写。脏树判定采用 `git status --porcelain` 语义——**untracked 文件也计入脏树**，`--yes` 前请先 commit 或 `git stash -u`。 -- **备份与回滚**：--yes 写盘前原字节备份到 `.coding-kit/backups/refresh-ide-blocks//`（保留最近 5 代）；回滚首选 `git checkout -- `，非 git 仓用备份 cp 回。备份仅供本机回滚——建议消费者将 `.coding-kit/backups/` 加入 `.gitignore`（不入库）。存量树可能仍有 legacy `.cyning-harness/backups/`；新写不再以此为目标。 -- **无 marker 文件（仅报告，绝不改写）**：发现面内 0 product 块文件用 A/B 组同一组正则做只读扫描，命中入人类报告「无 marker 检出（仅报告，不刷写）」段与 --json top-level `plain_mentions: [{path, rule, count}]` 字段（schema 保持 `@1`，向后兼容增量）；不触发 preflight fail-fast，不改 exit 码。 -- **幂等**：已刷写文件再次运行 A 组命中 0，`files_written=0`、字节不变、exit 0。 -- `--json` 输出单行机器报告（schema `dsh-coding-kit/refresh-ide-blocks-report@1`；自 1.5.2 起向后兼容增量含 `plain_mentions` / `totals.plain_mentions`）。 +**位置**：在途时 `docs/tasks/active/task_.md`。 +**归档**：`npx spec-wave task close --file FILE --yes` → 移到 `docs/tasks/done/`。 -### D5 测试制品探测边界（audit / verify · test_strategy=required） +最小骨架： -`audit` / `verify` 在 task 声明 `test_strategy=required` 时执行 D5 强检查：目标仓须存在**真实测试制品**，否则 exit 2。D5 是制品探测，不执行测试命令。探测口径（自 1.3.0 收紧）： +```markdown +# Task：加登录限流 -**强信号探针（存在即 PASS）** +> **状态**：`draft` -- 目录：`test/` `tests/` `spec/` `specs/` `__tests__/` -- 配置文件：`jest.config.{js,ts}` `vitest.config.{js,ts}` `playwright.config.{js,ts}` `cypress.config.js` `pytest.ini` -- 测试文件名（仓根起 3 层内）：`*.(test|spec).(js|ts|mjs|cjs)`、`*_test.py`、`test_*.py` +## Harness 元信息 +| 字段 | 值 | +|------|-----| +| **task_slug** | `login-rate-limit` | +| **test_strategy** | `required` | -**CI 探测**：`.github/workflows/` 下 `*.yml|*.yaml` 逐一读文本，命中以下任一 test 步骤模式才算有 CI 测试：`pytest` `vitest` `jest` `npm (run )?test` `pnpm (run )?test` `yarn test` `node --test` `go test` `cargo test` `tox` `unittest`，或 step `name:` 含 `test`。 +### 人工闸 +| human_gate_id | status | blocks_hats | 说明 | +|---------------|--------|-------------|------| +| HG-AUDIT-R1 | pending | 30 | R1 审查后人签 | -**已知误判面与逃生口** +## 范围 +为登录端点添加速率限制：每 IP 每 15 分钟最多 5 次尝试。 -- `pyproject.toml` / `setup.py` 存在**不再**视为测试制品（任意现代 Python 仓都有，与有无测试无关）。 -- 纯 lint / 纯部署 workflow（无 test 步骤）不再放行。 -- 探测深度为仓根起 3 层；monorepo 更深层或自定义测试命令（如 `make test`）不命中白名单时，在仓内放任一强信号文件（如 `tests/` 目录、`*_test.py`）即可。 -- **WARN 过渡已硬化（1.5.0）**：1.3.0–1.4.0 期间「新探测失败但旧启发式通过 → `D5: WARN 过渡` exit 0 不阻塞」的过渡分支已删除；自 1.5.0 起上述情形一律 **FAIL**（verify BLOCKED / audit FAIL，exit 2）。升级前请在仓内补真实测试制品（如 `tests/`、`*_test.py`、`*.test.ts` 或含 test 步骤的 CI）。 +## 验收标准 +- `pytest tests/test_rate_limit.py` 通过 +- 手动测试：15 分钟内第 6 次尝试返回 429 +``` +### spec.md — 需求规格 -### P0 门禁退出码（failClosed · F2 / 1.x MVP） +一个 `spec.md` 文件是任务引用的已签署需求规格： -| 退出码 | 含义 | 典型命令 | -|--------|------|----------| -| **0** | 通过 / 仅信息 | `check` **恒为** 0（只给版本建议） | -| **1** | 用法错误或非阻断失败 | 缺必填旗标、未知参数 | -| **2** | **门禁阻断** — failClosed，不得放行 | `verify` / `gate-check` / `audit` 的 P0 失败；`test_strategy=required` 时 D5 无测试制品 | +- **背景 / 范围 / 非范围** +- **验收标准** +- **失败路径** -**failClosed**：P0 门禁失败一律 **exit 2**。CI / Agent 须把 2 当硬停（与 Claude Code hook「退出码 2 阻断」同族）。禁止在本地把 2 改映射成 0 以求「继续跑」。 +**位置**：`docs/spec//`（例如，`docs/spec/2_2-closed-loop-start/`） +**门禁**：`npx spec-wave verify --spec FILE` 检查实现前是否存在书面审查。 -**分层强制（文档级 · 1.x 不引入云/远程策略引擎）**： +### 人工门禁 -1. 消费者仓库内的机械门禁结论（`verify` / `gate-check` / `audit` 的 exit 2）优先于「本地习惯跳过门禁」。 -2. task 表 `HG-AUDIT-R1=approved` 之后，hat 30 才可改码。 -3. kit P0 **不依赖**宿主 hooks——判定在进程内 CLI 完成。 +人工门禁是 `task.md` 表中的批准检查点： +```markdown +| human_gate_id | status | blocks_hats | 说明 | +|---------------|--------|-------------|------| +| HG-AUDIT-R1 | approved | 30 | R1 审查后人签 | +``` -### pins consumer 模式（消费仓钉版保鲜 · 3.0.2+） +- **`HG-AUDIT-R1`**：R1 审计门禁；必须为 `approved`，帽 30（实现）才可改码 +- **`HG-GRAPH-MODULES`**：D4-a 门禁；必须为 `approved` 才能进行模块图更改 -面向**消费** spec-wave 的仓。以往每次升级要手工对齐多个面（`package.json` 精确钉版、CI workflow 里的 `spec-wave@` 字面、测试 mock 版本字面），任一面漏改即静默漂移。`pins check --consumer` 把它收成一条 CI 机械门禁（漂移 → exit 2）： +`npx spec-wave verify --task FILE` 将此表读取为真值源（聊天声称不算数）。 -- **真值源（回退链）**：`package.json#devDependencies.spec-wave` → `#dependencies.spec-wave` → `#version`，首个字符串胜；三处皆缺 → exit 2 点名完整链。可用 `--truth ` 显式指定（如 `--truth package.json#devDependencies.spec-wave`；绝对路径与 `../` 拒绝）。 -- **精确版本**：`X.Y.Z` 直接采用；`^`/`~` 前缀归一并给出可见 WARN（`--json` 下入 `warnings`）；其余形态（`*`、`workspace:*`、范围表达式）→ exit 2 并建议改精确钉版。 -- **默认钉面**（零配置）：`.github/workflows/*.{yml,yaml}` 中凡字面含 `@X.Y.Z` 的文件逐文件合成钉；不含该字面的 workflow 跳过（不误 BLOCKED 无关文件）。 -- **可选声明源** `.spec-wave/pins-consumer.yaml`——存在即替代默认钉面；文件损坏 → exit 2 failClosed（坏的声明源绝不静默当作不存在）： +### 帽子系统 -```yaml -version: "1" -package_name: spec-wave # 可选，缺省 spec-wave -pins: - - id: consumer-test-mocks - path: tests/test_capability_harness_cli.py - extract: { kind: regex-all, pattern: 'spec-wave@(\d+\.\d+\.\d+)', flags: g } - expected: { kind: package-version } # = consumer 真值版本 - required: true - fixable: true -``` +"帽子"是过程角色： -- `pins fix --consumer` 默认 dry-run；`--yes` 才写盘（S2 过程目录机械拒写不变）。 -- **分工**：release 模式（无旗标）面向 spec-wave 发布仓自身（`assets/release-pins.yaml`）；`--consumer` 面向消费仓。 +- **帽 00**：仅委派（无直接实现） +- **帽 10**：Spec/task 起草 +- **帽 20**：Spec/task 审计 +- **帽 30**：实现（需要 `HG-AUDIT-R1=approved`） +- **帽 40**：自检 +帽 10/20 的 Skills 在 `.cursor/skills/`、`.claude/skills/` 等中（默认安装）。 +帽 30/40 的 Skills **不**默认安装（需要显式 `--with-execute-hats`）。 -## 从 @cyning/harness 迁移 +--- -完整清单、F4 方案 B 布局与 **已公布** EOS / deprecate 日历：见 [`MIGRATION.md`](./MIGRATION.md)。 +## 多宿主矩阵（详细） -钉 **spec-wave@3.0.2** 后可去掉 `@cyning/harness`。最小路径三步（必须，按序）： +一个声明式适配表 → 多个宿主的原生落点。验证真值保留在 CLI（`failClosed` exit 2）；IDE 命令只编排。 -1. 把 `devDependency` `@cyning/harness` 换成 `spec-wave`（钉 `3.0.2`；曾用名 `dsh-coding-kit`）。 -2. 在仓根执行 `npx spec-wave upgrade --yes`（读优先 `.coding-kit/manifest.json`，否则 legacy `.cyning-harness/manifest.json`；**写入** `.coding-kit/manifest.json`，`version` 钉 3.0.2，`from_version` 记旧号；**不删除** `.cyning-harness/`）。 -3. CI / 脚本里把 `npx @cyning/harness` / `npx dsh-coding-kit` 换成 `npx spec-wave`。 +**注意**：安装 npm 包**不会**物化 IDE 文件（无 postinstall）。显式运行 `init --tools` 或 `host apply`。 -**布局**：过程落盘现行根为 **`.coding-kit/`**；`.cyning-harness/` 为 **legacy 只读**。勿再把 `.cyning-harness` 当新标准目录。 +| 宿主 | Always-On 规则 | 命令（profile `core`） | Skills | +|------|----------------|---------------------------|--------| +| **Cursor** | `.cursor/rules/*.mdc` | `.cursor/commands/kit-*.md` | `.cursor/skills/` | +| **Claude Code** | `CLAUDE.md`（marker 块） | `.claude/commands/kit/.md` → `/kit:verb` | `.claude/skills/` | +| **DSH** | （空） | `[]`（无 `.dsh/commands/`） | `.dsh/skills/`（帽子 + 编排） | +| **agents** | `AGENTS.md` 片段 | `[]` | `.agents/skills/` | +| **Copilot** | `AGENTS.md` 片段 | `[]` | `.github/skills/` | +| **Codex** | `AGENTS.md` 片段 | `[]` | `.agents/skills/` | +| **Windsurf** | `AGENTS.md` 片段 | `[]` | `.windsurf/skills/` | +| **Gemini CLI** | `GEMINI.md` | `[]` | `.gemini/skills/` | +| **opencode** | `AGENTS.md` 片段 | `[]` | `.agents/skills/` | +| **Roo Code** | `AGENTS.md` 片段 | `[]` | （无 skills 目录） | +| **Zed** | `AGENTS.md` 片段 | `[]` | `.agents/skills/` | +| **Cline** | `AGENTS.md` 片段 | `[]` | `.cline/skills/` | +| **aider** | `AGENTS.md` 片段（需要 `--read`） | `[]` | （无 skills 目录） | -Skill 安装为 **推荐、非必须**（最小路径不依赖 DSH 扫 skill）。命令一律 `npx spec-wave`。旧包 **`@cyning/harness` 已在 npm deprecate**（2026-09-10 · 仅维护者可操作）；请钉 **`spec-wave@3.0.2`** 并按 `MIGRATION.md` 迁移。 +**2.2 W6 新增**（同一包）：九个宿主复用 `agents` 资产面（零新资产）。每个落点遵循宿主的官方文档。 -### FAQ · pnpm peer +**2.1 新增**（同一包）：Claude `/kit:` 命名空间 UX，DSH 编排 skills，可选 `--profile expanded` 用于帽子薄壳。 -若 pnpm 安装仍因 peer 链失败（例如解析到未公开发布的宿主包）：在仓根设 `auto-install-peers=false`（或单次 `pnpm add -D spec-wave --config.auto-install-peers=false`）。即使 **1.2.2** 已将 cordis / dsh-tools 标为 optional，也建议保留此兜底。 +--- -### 可复制 Prompt（给存量仓 Agent） +## 高级：D5 测试制品检测 -整段粘贴： +当任务中 `test_strategy=required` 时，`audit`/`verify` 运行 D5 检查：目标仓库必须包含**真实测试制品**，否则 exit 2。 -````text -你 = 本仓库维护 Agent。把本仓从 @cyning/harness 迁到 spec-wave@3.0.2。 +**强信号探针**（存在 = 通过）： -最小路径（必须，按序）： -1. package.json 的 devDependency：删除 @cyning/harness，改为 spec-wave（钉 3.0.2；曾用名 dsh-coding-kit）。 -2. 在仓根执行：npx spec-wave upgrade --yes - （读 .coding-kit/manifest.json 或 legacy .cyning-harness/manifest.json；写入 .coding-kit/manifest.json；version 钉 3.0.2，from_version 记旧号；不删除 .cyning-harness/；不覆盖 docs/tasks、reviews、invokes/by-task。） -3. CI 与脚本里所有 npx @cyning/harness 与 npx dsh-coding-kit 换成 npx spec-wave。 -命令一律 npx spec-wave。禁止再写 npx @cyning/harness skills build。 -布局与 EOS 日历见 MIGRATION.md（人闸未批前不得宣称已 deprecate）。 +- 目录：`test/`、`tests/`、`spec/`、`specs/`、`__tests__/` +- 配置文件：`jest.config.{js,ts}`、`vitest.config.{js,ts}`、`playwright.config.{js,ts}`、`cypress.config.js`、`pytest.ini` +- 测试文件名（3 层内）：`*.(test|spec).(js|ts|mjs|cjs)`、`*_test.py`、`test_*.py` -推荐（非必须 · Skill 安装）： -- 仓内：npx spec-wave skills install - 复制 npm 包内已生成 skills（默认不含 30/40）到本仓 .dsh/skills。已有文件默认不覆盖；要覆盖才加 --force。 -- 用户级：npx spec-wave skills install --global - 写到 $HOME/.dsh/skills（展开 HOME；不要把 ~ 当成相对路径）。 +**CI 检测**：`.github/workflows/` 下的每个 `*.yml|*.yaml` 被扫描测试步骤模式：`pytest`、`vitest`、`jest`、`npm test` 等。 -路径对照（禁止混用）： -- .dsh/skills 或 $HOME/.dsh/skills = Skill 安装落点（本命令）。 -- .claude/skills 或 ~/.claude/skills = Claude Code 的 skill 目录（本命令默认不写；若你用 Claude 可另拷或 --out）。 -- .dsh/coding-kit 或 .coding-kit = 规范覆盖（apply_coding_standards / init_coding_kit），不是 skill 目录。 +**已知误报**：单独的 `pyproject.toml`/`setup.py` **不是**测试制品。对于不在白名单中的自定义测试命令（例如，`make test`），添加强信号文件（例如，`tests/` 目录）。 -已验证（对照 DSH 上游源码）：DSH runtime 自动扫描本仓 .dsh/skills 与 $HOME/.dsh/skills 并按需加载。skill 形态为 /SKILL.md 目录包或 .md 平铺文件，frontmatter 必填 name/description；证据锚点见 README「扫描验证」节。 +--- -不要做：GitHub Archive；npm publish / deprecate；让 apply 在加载时自动注入；默认安装 30/40；把 skills 拷进 .dsh/coding-kit。 -```` +## 图与本体（高级） -### 路径对照 +SpecWave 包含用于技术依赖建模的图能力： -| 路径 | 用途 | 谁写入 | -|------|------|--------| -| 产品包 `assets/skills` | 生成物真值；`skills check` 对照根 | 维护者 `skills build`（G5 freeze） | -| `/.dsh/skills` | 消费者 Skill **安装落点** | `skills install` | -| `$HOME/.dsh/skills` | 用户级安装落点 | `skills install --global` | -| `/.claude/skills` 或 `~/.claude/skills` | Claude Code skill 目录 | 用户另拷或 `--out`；**默认不写** | -| `/.dsh/coding-kit` 或 `.coding-kit` | 规范覆盖（standards / wiki） | `init_coding_kit`；**禁止**当作 skill dest | +```bash +npx spec-wave graph yaml compile # 编译 YAML 图 → Mermaid +npx spec-wave graph yaml check # 验证图结构 +npx spec-wave graph yaml export # 导出到 graph.json +npx spec-wave graph ontology check # 验证本体 +``` -### 扫描验证（已对照 DSH 上游源码） +**本体边界**（3.0 ONTO-OPEN 裁决）： +- 图面是**开放的**：消费者可以创作自己的图。 +- 捆绑本体（`assets/ontology.yaml`）**不开放**：无消费者定义的类/关系。 +- 验证器开放 ≠ 本体内容开放。 -**已验证（2026-08-22 · 对照 DSH 上游源码 deepseek-harness@141eb6f，即 dsh 0.1.0-rc.8）**：DSH runtime **会自动扫描** `/.dsh/skills` 与 `$HOME/.dsh/skills` 并 **按需加载**，二者正是本包 `skills install` 的两个 **安装落点**。证据锚点： +本仓对 `docs/_tech_graph/` 进行 `graph yaml compile|check|export` 的 dogfood（npm 包中不提供）。 -- `packages/skill/skill-filesystem/src/index.ts:246` —— 扫描 `/.dsh/skills`（source=`project-dsh`，rank 100）；同文件 `:253` —— 扫描 `/skills`（`$DSH_HOME` 或 `~/.dsh`，source=`user-dsh`，rank 400）。 -- `docs/subsystems/skills.md`「Local discovery priority」表同口径（rank 100/400 两行）；加载机制：skill 摘要注入会话 catalog，模型经 `skill({ name })` 工具按需拉取正文（该文档「Session catalog and tool contract」节）。 +--- -结构与 frontmatter 要求（同源码）：目录包 `/SKILL.md` 或平铺 `.md`（index.ts:724-728）；frontmatter 必填 `name`/`description`，`name` 须 kebab-case（index.ts:810-816）；projectRoot = 最近含 `.git` 的祖先目录（index.ts:937-947）。 +## 发版（维护者） -注意：扫描/加载是 **DSH runtime 的行为契约**，随上游版本演进；以上锚点对应 0.1.0-rc.8。本包职责止于把 skill 写入正确落点并保持 frontmatter 合法（`skills check`）。 +**当前包**：`spec-wave@3.0.2` — 已发布（registry `latest=3.0.2`，tag `v3.0.2` ↔ tip `3d71b90`，2026-09-24 验证）。 -## Host 使用 coding-kit（沟通 Agent / 产品 Chat） +发布流程：见 [RELEASING.md](RELEASING.md) — 发布前硬步骤清单（commit-before-publish、四门全绿、版本钉、**仅人 `npm publish`**）。 -Skills **不能**覆盖全部过程能力。Host 要嵌套 Harness 过程，须同时具备：Process Kernel 对象 + CLI Capability + PromptAssembly 槽，而不是只拷 Skills。 +--- -推荐 Capability 白名单（**须走 Policy / H2**：默认关 · Host env 显式授权 · 禁止任意 shell）： +## GitHub Topics -- `npx --yes spec-wave@ verify …` -- `npx --yes spec-wave@ task …` +本仓库的 topics：`dsh-plugin`、`deepseek-harness`、`dsh-plugins`、`dsh`。 -| 能力 | Skills 能否覆盖 | -|------|----------------| -| 10/20 审过程指引 | 能（默认分发） | -| 00 委派纪律 | 弱：全文不进默认；delegate-only 短 Skill 可默认装 | -| 30/40 执行 | 弱：不进默认（T1 前）；且执行仍须 `verify` | -| 闸 / pre-30 / may_start_30 | **否**：须 CLI `verify`（或 Host 封装同一 CLI） | -| 帽身份常驻 system | **否**：Skills 为 on-demand，非 system | -| Host 业务答题 | **否**：属产品 Prompt Pack | +`package.json` 中的 npm keywords 包括 `dsh-plugin` 和 `deepseek-harness`。 -三分：**System/Re-anchor** = 短身份；**prompts 全文** = 换帽加载；**verify** = 机械。不可互替。 +--- -## 发版（维护者） +## 许可证 -**现行包**：**`spec-wave@3.0.2`** — **已发布**（registry `latest=3.0.2` · `time.3.0.2`=2026-09-24T00:55:45.386Z · tag `v3.0.2` ↔ tip `3d71b90` · 2026-09-24 实测）。前一已发：**`3.0.1`**（信号质量 patch）· **`3.0.0`**（架构跃迁）· **`2.4.2`**（验收修复 patch）· **`2.4.1`**（验收修复 patch）· **`2.4.0`**（门禁强度补全）· **`2.3.1`**（验收修复 patch）· **`2.3.0`**（接线补全）· **`2.2.1`**（验收修复 patch）· **`2.2.0`**（闭环起步）。 +MIT -发布流程见 [RELEASING.md](RELEASING.md) —— publish 前硬步骤 checklist（先 commit 后 publish · 四门全绿 · 版本钉同步 · **Agent 可 bump/tag** · **`npm publish` 仅人**；DEF-001 教训制度化）。 +--- -## GitHub topic +## 链接 -本仓库当前 GitHub topics：**`dsh-plugin`**（DSH 官方发现机制 tag，见上游 deepseek-harness `README.md` 与 `CONTRIBUTING.md`；无应用商店）、**`deepseek-harness`**、**`dsh-plugins`**、**`dsh`**。`package.json` 的 npm keywords 同样含 `dsh-plugin` 与 `deepseek-harness`。 +- **npm**：[npmjs.com/package/spec-wave](https://www.npmjs.com/package/spec-wave) +- **仓库**：[github.com/Cyning12/SpecWave](https://github.com/Cyning12/SpecWave) +- **Issues**：[github.com/Cyning12/SpecWave/issues](https://github.com/Cyning12/SpecWave/issues) -## License +--- -MIT +曾用名 SpecGate / `dsh-coding-kit` — 改名史：[MIGRATION.md](MIGRATION.md)。