sspec 2.2.1__tar.gz → 2.3.0__tar.gz

sspec-2.3.0/.agents/skills/write-spec-doc/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: write-spec-doc
+description: Create and maintain spec-docs — knowledge that code alone cannot adequately convey.
+metadata:
+  author: frostime
+  version: 4.0.0
+---
+
+# Write Spec-Doc
+
+## §1 Decision: When to Create
+
+Code is the local ground truth. Spec-docs reduce the cost of recovering that ground truth for agents.
+
+Two categories of knowledge that justify a spec-doc:
+
+**A) In code, but scattered or implicit** — Cross-module architecture (call chains, data flows, layer relationships) distributed across many files; implicit specifications (state machines, invariants, schema contracts) that are implemented but never declared; design norms embedded in implementation choices; deliberate trade-offs whose rationale is invisible from outcomes alone. Reconstructing any of these demands expensive multi-file traversal and inference.
+
+**B) Outside code entirely** — Platform rules, API quirks, business constraints, deployment assumptions. Code reflects these as outcomes, but the constraints themselves cannot be inferred from it. Example: a SQLite-over-Postgres choice is invisible without knowing the single-machine deployment constraint.
+
+**Write-gate**: "If an agent read only the code (including comments), could they obtain this information — fully and without excessive effort?" Yes → don't create. No → create.
+
+**Don't create** when:
+- Code comments and type signatures adequately capture the design
+- The topic is a single-file implementation detail
+- The information duplicates framework/library documentation
+- A one-liner in `project.md` Conventions or Notes is sufficient
+
+## §2 Creation & Structure
+
+### CLI
+
+| Command | Use |
+|---------|-----|
+| `sspec doc new "<name>"` | Create single-file spec-doc from template |
+| `sspec doc new "<name>" --dir` | Create multi-file spec-doc (directory + `index.md`) |
+| `sspec doc list` | List all spec-docs with metadata |
+
+Always use CLI to create — it scaffolds from template with correct frontmatter. Do not hand-create spec-doc files.
+
+### Frontmatter
+
+All fields required:
+
+```yaml
+---
+name: Authentication System
+description: JWT-based auth with refresh tokens and rate limiting
+updated: 2026-01-27
+scope:
+  - /src/auth/**
+  - /src/middleware/auth.ts
+---
+```
+
+`scope` lists file paths (glob patterns) this spec-doc covers. Agents use it to locate relevant code. Include primary implementation and tests; omit generic utilities.
+
+### Body
+
+Start with `## Overview`. Beyond that, invent sections that fit the content. Example structures:
+
+- **Architecture**: Overview → Architecture (diagram) → Components → Key Decisions
+- **External constraints**: Overview → Constraints → Implications for Code → References
+- **Design norms**: Overview → Principles → Rules (with examples) → Exceptions
+- **Implicit spec**: Overview → Specification (state machine / invariants) → Implementation Notes
+
+**Self-check for every section**: Would removing this force an agent into expensive reconstruction — multi-file traversal, cross-reference inference, external research, or guessing? If the agent could reach the same understanding from code alone at comparable cost, the section is redundant — cut it.
+
+**Representation**: Complex relationships — call chains, state transitions, data flows, hierarchies — are more precisely conveyed through diagrams, pseudocode, or tables than through prose. Prefer semi-formal representations; they are easier for both agents and humans to verify and navigate.
+
+### Registration
+
+After creating a spec-doc, add an entry to `project.md` **Spec-Docs Index**. This is the agent's responsibility — the CLI does not automate it.
+
+Format: `- [Name](spec-docs/<filename>.md) — one-sentence description`
+
+### Linking from Changes
+
+When a change creates or heavily depends on a spec-doc, add to the change's `spec.md` frontmatter:
+
+```yaml
+reference:
+  - source: "spec-docs/<name>.md"
+    type: "doc"
+```
+
+## §3 Traceability
+
+Spec-docs are navigable knowledge graphs, not dead-end prose.
+
+Every named entity — symbol, concept, external reference — MUST be traceable to its source (file path, URL, or another spec-doc). Establish the reference on **first mention**; subsequent uses within the same document need not repeat the link when the referent is unambiguous from context.
+
+**Source types**: file path · URL · relative link to another spec-doc.
+Omit line numbers — they go stale with code changes.
+
+**BAD** — agent must search to resolve:
+```markdown
+The `AuthManager` handles token refresh. Rate limits follow Stripe's rules.
+```
+
+**GOOD** — traceable on first mention, concise thereafter:
+```markdown
+[`AuthManager`](/src/auth/manager.ts) handles token refresh.
+Rate limits follow [Stripe's API rules](https://docs.stripe.com/rate-limits) (≤100 req/s per key).
+
+... later in the same doc ...
+
+`AuthManager` delegates to the refresh service when tokens expire.
+```
+
+## §4 Style
+
+- **Imperative mood**: "Validate tokens" not "The system should validate"
+- **Direct**: No filler ("It's worth noting...", "As mentioned earlier...")
+- **Precise & quantified**: "Use Redis (5min TTL)" not "Consider using Redis"
+- **Current state only**: No changelogs — history lives in git
+- **Single topic per doc**: Don't mix unrelated concerns
+- **File links**: Workspace-relative with forward slashes (`/src/core.py`). Same-level or sub-directory may use `./`
+
+## §5 Lifecycle
+
+### Updating
+
+When a change modifies code covered by a spec-doc's `scope`:
+
+1. Add task in tasks.md: "Update spec-doc `spec-docs/<name>.md`"
+2. Update `updated` field and affected sections
+3. Verify `scope` still matches actual files
+
+Spec-docs MUST NOT be silently outdated by a change.
+
+### Deprecation
+
+Mark `deprecated: true` + `replacement: /path/to/new.md` in frontmatter. Move to `spec-docs/archive/`. Strip details; keep only: what it was, why deprecated, link to replacement.
+
+### Multi-file Specs
+
+Use `sspec doc new "<name>" --dir`. Entry point is `index.md` with overview + navigation. Each sub-file has its own frontmatter with narrowed scope. Cross-references use relative paths.

{sspec-2.2.1 → sspec-2.3.0}/.sspec/.meta.json

@@ -1,12 +1,12 @@
 {
   "meta_schema": "2.1",
   "sspec_schema": "6.0",
-  "sspec_version": "2.1.7.dev2+g2e9bdfd86.d20260430",
+  "sspec_version": "2.2.2.dev0+g827c13fab.d20260504",
   "created_at": "2026-02-07T18:42:39.297150",
-  "updated_at": "2026-04-30T18:44:24.863097",
+  "updated_at": "2026-05-04T17:57:06.107447",
   "file_hashes": {
     "skills/write-patch": "850929827559ba69",
-    "skills/write-spec-doc": "9d90be74022b6ece",
+    "skills/write-spec-doc": "13bb5686b0ff98e4",
     "skills/sspec-mdtoc": "b9fdfc4a23d816e0",
     "skills/sspec-design": "5568dff1e82ab5f3",
     "skills/sspec-implement": "04a20c5c851841a3",

{sspec-2.2.1 → sspec-2.3.0}/.sspec/project.md

@@ -46,7 +46,6 @@ Read it first every session. Update Conventions + Notes via @handover. -->
 
 ## Spec-Docs Index
 
-- [Project Specifications](spec-docs/README.md) — master index and maintenance rules for this spec-doc set
 - [Builtin Tools System](spec-docs/builtin-tools.md) — builtin `sspec tool` architecture, registration, and current tool inventory
 - [SKILL Installation & Sync](spec-docs/skill-installation.md) — hub-spoke skill install model, link policy, migration, and gitignore rules
 - [meta.json (Project Metadata)](spec-docs/meta-json.md) — `.sspec/.meta.json` schema, migration, and update-time guarantees

{sspec-2.2.1 → sspec-2.3.0}/AGENTS.md

@@ -12,25 +12,17 @@ This project uses sspec to develop sspec. Two sets of rules coexist:
 
 **Rule**: When developing templates, the **template source files** in `src/sspec/templates/` are ground truth.
 
-**Hard rule**: If a change touches AGENTS, SKILLs, or any template content, edit only `src/sspec/templates/`. Do **not** hand-edit `.github/`, `.claude/`, or `.sspec/` copies; refresh them with `uv run sspec project update`.
+**Hard rule**:
+- Edit of sspec itself SHOULD lies within `src/`, `tests/`
+- MUST NOT hand-edit `.github/`, `.claude/`, or `.sspec/` copies, refresh them with `uv run sspec project update`.
 
 **Auto-managed rule**: The SSPEC block below `SSPEC:START` is generated from `src/sspec/templates/AGENTS.md`. If that block needs to change, update the template source and run `uv run sspec project update` instead of editing the block directly.
 
 ---
 
-## 1. Cold Start (Development)
+## 1. Source
 
-1. Read `.sspec/project.md` — tech stack, conventions, project notes.
-2. Classify the request:
-
-| User Message | Action |
-|--------------|--------|
-| `@resume` or `@change` | Load change context (follow SSPEC block below) |
-| Template/SKILL change | Follow **Template Change Protocol** (Section 2) |
-| Python code change | Follow **Code Change Protocol** (Section 3) |
-| Bug report / feature idea | Follow SSPEC workflow in block below |
-
-3. If touching an unfamiliar area, check `src/sspec/` structure:
+`src/sspec/`:
 
 ```
 src/sspec/
@@ -115,13 +107,6 @@ cd tmp/test_<feature>
 uv run sspec <command>       # Test the command
 ```
 
-### Key architectural rules
-
-- `commands/` = CLI layer (click decorators, user I/O, output formatting)
-- `services/` = business logic (no click, no rich — pure functions)
-- `core.py` = shared types and constants (no business logic)
-- Keep commands thin: validate input → call service → format output
-
 ### Windows terminal encoding rule
 
 - Treat Windows GBK/cp936 terminals as a supported environment.
@@ -129,17 +114,6 @@ uv run sspec <command>       # Test the command
 - Keep `configure_stdio_error_fallback()` wired in CLI startup when refactoring entrypoints.
 - For new symbols/emojis in user-facing text, verify behavior in legacy encodings or provide ASCII fallback.
 
-
----
-
-## Git Commit
-
-When user asks Agent to commit:
-
-- Consult: git-commit-msg SKILL
-- Write suitable commit msg
-- If the change is too broad for one clean commit, ask whether to split it
-
 ---
 
 <!-- ====================================================================
@@ -159,6 +133,9 @@ SSPEC_SCHEMA::6.0
 
 A spec-driven workflow, via `sspec` CLI and `.sspec/`.
 
+**Core Principle**: The user MUST be able to predict the outcome before implementation begins.
+When uncertain, align — never proceed with unclarified assumptions.
+
 ```
 .sspec/
 ├── project.md     # Identity, conventions, notes
@@ -177,8 +154,10 @@ A spec-driven workflow, via `sspec` CLI and `.sspec/`.
 | Directive (`@resume`, `@memory`, etc.) | Execute → §4 |
 | Request under `.sspec/requests` | Assess scale → §2 |
 | Resume existing change | `read(memory)` → infer phase from State → load phase SKILL → continue |
+| Create request | `sspec request new` |
+| Create spec doc | `sspec doc new` |
 | Micro (≤3 files, ≤30min, obvious) | Do directly |
-| Mini (user opts out of formal change) | Clarify+Design thinking → `.sspec/tmp/` → §2.0 |
+| Mini (user opts out of formal change) | Clarify+Design thinking → `sspec tmp new` → §2.0 |
 
 **Trigger-word → SKILL**:
 
@@ -193,7 +172,7 @@ A spec-driven workflow, via `sspec` CLI and `.sspec/`.
 | mini change, 不要 change, 直接推进 | §2.0 |
 
 **Standing rules**:
-- The user MUST be able to predict what the code will look like before implementation begins. When uncertain, @align.
+- Follow `Core Principle`.
 - Important discovery → `memory.md` Knowledge immediately
 - Session end → MUST update memory.md (State + Milestones) · `sspec howto write-memory`
 - @align gate decisions → SHOULD update memory.md Knowledge
@@ -212,7 +191,7 @@ Implement(sspec-implement)  code + tasks progress   exit: @align gate ■
 Review   (sspec-review)     DONE | fix→Implement | amend→revision | follow-up→new change
 ```
 
-`■` = hard stop, MUST align. `→` = output summary, keep going. Failed gate → return, update, realign.
+`■` = hard stop, **MUST stop & align**. `→` = output summary, COULD keep going. Failed gate → return, update, realign.
 Post-Design gate: spec.md/design.md baselines immutable. Changes → `revisions/NNN-*.md`.
 memory.md: maintained throughout, not a phase. → `sspec howto write-memory`
 
@@ -241,6 +220,10 @@ Status in spec.md MUST follow state machine. → `sspec howto update-change-stat
 
 Structured sync at decision points. **Formalized exchange, not prose.**
 
+**Format rule**: MUST be scannable in 5 seconds.
+GOOD: structured (tables, labeled items, code blocks) with high density.
+BAD: prose-style, redundant.
+
 | Level | Behavior | When |
 |---|---|---|
 | `report` | Summary, **keep going** | Plan done, progress |

{sspec-2.2.1 → sspec-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sspec
-Version: 2.2.1
+Version: 2.3.0
 Summary: Lightweight AI collaboration spec for solo/small projects
 Author-email: frostime <frostime@foxmail.com>
 License: AGPL-V3

sspec-2.3.0/src/sspec/templates/skills/write-spec-doc/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: write-spec-doc
+description: Create and maintain spec-docs — knowledge that code alone cannot adequately convey.
+metadata:
+  author: frostime
+  version: 4.0.0
+---
+
+# Write Spec-Doc
+
+## §1 Decision: When to Create
+
+Code is the local ground truth. Spec-docs reduce the cost of recovering that ground truth for agents.
+
+Two categories of knowledge that justify a spec-doc:
+
+**A) In code, but scattered or implicit** — Cross-module architecture (call chains, data flows, layer relationships) distributed across many files; implicit specifications (state machines, invariants, schema contracts) that are implemented but never declared; design norms embedded in implementation choices; deliberate trade-offs whose rationale is invisible from outcomes alone. Reconstructing any of these demands expensive multi-file traversal and inference.
+
+**B) Outside code entirely** — Platform rules, API quirks, business constraints, deployment assumptions. Code reflects these as outcomes, but the constraints themselves cannot be inferred from it. Example: a SQLite-over-Postgres choice is invisible without knowing the single-machine deployment constraint.
+
+**Write-gate**: "If an agent read only the code (including comments), could they obtain this information — fully and without excessive effort?" Yes → don't create. No → create.
+
+**Don't create** when:
+- Code comments and type signatures adequately capture the design
+- The topic is a single-file implementation detail
+- The information duplicates framework/library documentation
+- A one-liner in `project.md` Conventions or Notes is sufficient
+
+## §2 Creation & Structure
+
+### CLI
+
+| Command | Use |
+|---------|-----|
+| `sspec doc new "<name>"` | Create single-file spec-doc from template |
+| `sspec doc new "<name>" --dir` | Create multi-file spec-doc (directory + `index.md`) |
+| `sspec doc list` | List all spec-docs with metadata |
+
+Always use CLI to create — it scaffolds from template with correct frontmatter. Do not hand-create spec-doc files.
+
+### Frontmatter
+
+All fields required:
+
+```yaml
+---
+name: Authentication System
+description: JWT-based auth with refresh tokens and rate limiting
+updated: 2026-01-27
+scope:
+  - /src/auth/**
+  - /src/middleware/auth.ts
+---
+```
+
+`scope` lists file paths (glob patterns) this spec-doc covers. Agents use it to locate relevant code. Include primary implementation and tests; omit generic utilities.
+
+### Body
+
+Start with `## Overview`. Beyond that, invent sections that fit the content. Example structures:
+
+- **Architecture**: Overview → Architecture (diagram) → Components → Key Decisions
+- **External constraints**: Overview → Constraints → Implications for Code → References
+- **Design norms**: Overview → Principles → Rules (with examples) → Exceptions
+- **Implicit spec**: Overview → Specification (state machine / invariants) → Implementation Notes
+
+**Self-check for every section**: Would removing this force an agent into expensive reconstruction — multi-file traversal, cross-reference inference, external research, or guessing? If the agent could reach the same understanding from code alone at comparable cost, the section is redundant — cut it.
+
+**Representation**: Complex relationships — call chains, state transitions, data flows, hierarchies — are more precisely conveyed through diagrams, pseudocode, or tables than through prose. Prefer semi-formal representations; they are easier for both agents and humans to verify and navigate.
+
+### Registration
+
+After creating a spec-doc, add an entry to `project.md` **Spec-Docs Index**. This is the agent's responsibility — the CLI does not automate it.
+
+Format: `- [Name](spec-docs/<filename>.md) — one-sentence description`
+
+### Linking from Changes
+
+When a change creates or heavily depends on a spec-doc, add to the change's `spec.md` frontmatter:
+
+```yaml
+reference:
+  - source: "spec-docs/<name>.md"
+    type: "doc"
+```
+
+## §3 Traceability
+
+Spec-docs are navigable knowledge graphs, not dead-end prose.
+
+Every named entity — symbol, concept, external reference — MUST be traceable to its source (file path, URL, or another spec-doc). Establish the reference on **first mention**; subsequent uses within the same document need not repeat the link when the referent is unambiguous from context.
+
+**Source types**: file path · URL · relative link to another spec-doc.
+Omit line numbers — they go stale with code changes.
+
+**BAD** — agent must search to resolve:
+```markdown
+The `AuthManager` handles token refresh. Rate limits follow Stripe's rules.
+```
+
+**GOOD** — traceable on first mention, concise thereafter:
+```markdown
+[`AuthManager`](/src/auth/manager.ts) handles token refresh.
+Rate limits follow [Stripe's API rules](https://docs.stripe.com/rate-limits) (≤100 req/s per key).
+
+... later in the same doc ...
+
+`AuthManager` delegates to the refresh service when tokens expire.
+```
+
+## §4 Style
+
+- **Imperative mood**: "Validate tokens" not "The system should validate"
+- **Direct**: No filler ("It's worth noting...", "As mentioned earlier...")
+- **Precise & quantified**: "Use Redis (5min TTL)" not "Consider using Redis"
+- **Current state only**: No changelogs — history lives in git
+- **Single topic per doc**: Don't mix unrelated concerns
+- **File links**: Workspace-relative with forward slashes (`/src/core.py`). Same-level or sub-directory may use `./`
+
+## §5 Lifecycle
+
+### Updating
+
+When a change modifies code covered by a spec-doc's `scope`:
+
+1. Add task in tasks.md: "Update spec-doc `spec-docs/<name>.md`"
+2. Update `updated` field and affected sections
+3. Verify `scope` still matches actual files
+
+Spec-docs MUST NOT be silently outdated by a change.
+
+### Deprecation
+
+Mark `deprecated: true` + `replacement: /path/to/new.md` in frontmatter. Move to `spec-docs/archive/`. Strip details; keep only: what it was, why deprecated, link to replacement.
+
+### Multi-file Specs
+
+Use `sspec doc new "<name>" --dir`. Entry point is `index.md` with overview + navigation. Each sub-file has its own frontmatter with narrowed scope. Cross-references use relative paths.

{sspec-2.2.1 → sspec-2.3.0}/src/sspec/templates/spec-docs/template.md

@@ -2,6 +2,7 @@
 name: {{SPEC_NAME}}
 description: ""
 updated: {{DATE}}
+scope: []
 ---
 
 # {{SPEC_NAME}}

sspec-2.3.0/tmp/write-spec-doc-v4-draft.md

@@ -0,0 +1,156 @@
+# write-spec-doc SKILL v4 — Design Draft
+
+> 供 review 用，不是最终 SKILL 文件。
+
+## 重构思路
+
+**核心变化**：判断力优先，写作规范精简，管理流程和 CLI 对齐。
+
+| 当前 v3 | v4 方向 | 理由 |
+|---------|---------|------|
+| When to Create 在前，但和 Style Guide 平级 | **Decision（何时写/不写）提为 §1，占 SKILL 核心位置** | 判断力 > 格式 |
+| Frontmatter 字段表 + Body Structure 4 种 example | 精简为一个 frontmatter 说明 + "结构跟随内容"原则 | 模板已有 scaffold，SKILL 不需要重复 |
+| Traceability 埋在 Style Guide 子节 | **提权为独立 §3，和 Decision 同级** | 这是 spec-doc 最核心的价值属性 |
+| Deprecation 完整流程 | 压缩为 3 行规则 | 实际使用率零，保留但不展开 |
+| Multi-file 完整说明 | 压缩为 CLI flag 提示 + 简要规则 | 同上 |
+| Relationship to Changes 要求 reference 字段 | 保留，措辞对齐 spec.md 的 reference schema | 这是真实能力 |
+| Maintenance Checklist | 移到 howto 或 SKILL reference | 琐碎 |
+| Diagramming (Mermaid examples) | 删除，agent 自己会写 mermaid | 不需要教 |
+| scope 字段 SKILL 说 required 但 template 没有 | **修 template，加 scope 字段** | 你确认 scope 必须保留 |
+| project.md 注册 | 明确写"agent 负责注册"，不期待 CLI 自动化 | 你的决定 |
+
+---
+
+## v4 SKILL 草稿
+
+```markdown
+---
+name: write-spec-doc
+description: Create and maintain spec-docs — knowledge that code alone cannot adequately convey.
+metadata:
+  author: frostime
+  version: 4.0.0
+---
+
+# Write Spec-Doc
+
+## §1 Decision: When to Create
+
+Code is the local ground truth. Spec-docs exist to **reduce the cost of recovering that ground truth** for agents.
+
+Two categories:
+
+- **A) In code, but scattered** — Cross-module architecture, call chains, data flows, layer relationships, deliberate design trade-offs. The information exists in code but is distributed across many files; reconstructing it requires expensive traversal + inference.
+- **B) Outside code entirely** — Platform rules, API quirks, business constraints, deployment assumptions. Code reflects these as outcomes, but the constraints themselves cannot be inferred from code.
+
+**Write-gate**: "If an agent read only the code (including comments), could they obtain this information — fully and without excessive effort?" Yes → don't create. No → create.
+
+**Don't create** when:
+- Code comments and type signatures adequately capture the design
+- The topic is a single-file implementation detail
+- The information duplicates framework/library documentation
+- A one-liner in `project.md` Conventions or Notes is sufficient
+
+## §2 Creation Workflow
+
+1. **Create**: `sspec doc new "<name>"` (single file) or `sspec doc new "<name>" --dir` (multi-file)
+2. **Fill frontmatter**: `name`, `description`, `updated`, `scope` — all required
+3. **Write content**: Start with `## Overview`, then invent sections that fit the knowledge
+4. **Register**: Add entry to `project.md` Spec-Docs Index (agent responsibility, not automated)
+5. **Link from change** (if created during a change): Add to spec.md `reference` field with `type: "doc"`
+
+### Frontmatter
+
+```yaml
+---
+name: Authentication System
+description: JWT-based auth with refresh tokens and rate limiting
+updated: 2026-01-27
+scope:
+  - /src/auth/**
+  - /src/middleware/auth.ts
+---
+```
+
+`scope` lists file paths (glob patterns) this spec-doc covers. Agents use it to find relevant code. Include primary implementation and tests; omit generic utilities.
+
+### Body
+
+Structure serves content. Every spec-doc MUST start with `## Overview`. Beyond that, invent sections that fit. Examples:
+
+- Architecture doc: Overview → Architecture (diagram) → Components → Key Decisions
+- External constraints: Overview → Constraints → Implications for Code → References
+- Design norms: Overview → Principles → Rules (with examples) → Exceptions
+
+## §3 Traceability
+
+Spec-docs are navigable knowledge graphs, not dead-end prose. Every named entity — symbol, concept, external reference — MUST carry its source.
+
+**Source types**: file path · URL · relative link to another spec-doc.
+Omit line numbers (they go stale).
+
+**BAD** — agent must search to resolve:
+```markdown
+The `AuthManager` handles token refresh. Rate limits follow Stripe's rules.
+```
+
+**GOOD** — agent can follow links directly:
+```markdown
+[`AuthManager`](/src/auth/manager.ts) handles token refresh.
+Rate limits follow [Stripe's API rules](https://docs.stripe.com/rate-limits) (≤100 req/s per key).
+```
+
+Alternative: define sources in a "Relative Code" block at the top, then reference by name in body text.
+
+## §4 Style
+
+- **Imperative mood**: "Validate tokens" not "The system should validate"
+- **Direct**: No filler ("It's worth noting...", "As mentioned earlier...")
+- **Precise**: "Use Redis (5min TTL)" not "Consider using Redis"
+- **Current state only**: No changelogs (history lives in git)
+- **Single topic per doc**: Don't mix unrelated concerns
+- **File links**: Use workspace-relative paths with forward slashes (`/src/core.py`). Same-level or sub-directory may use `./`.
+
+## §5 Lifecycle
+
+### Updating
+
+When a change modifies code covered by a spec-doc's `scope`:
+1. Add task in tasks.md: "Update spec-doc `spec-docs/<name>.md`"
+2. Update `updated` field and affected sections
+3. Verify `scope` still matches actual files
+
+Spec-docs MUST NOT be silently outdated by a change.
+
+### Deprecation
+
+Mark `deprecated: true` + `replacement: /path/to/new.md` in frontmatter. Move to `spec-docs/archive/`. Keep only: what it was, why deprecated, link to replacement.
+
+### Multi-file Specs
+
+Use `sspec doc new "<name>" --dir` → creates `spec-docs/<name>/index.md`.
+- `index.md` is the entry point with overview + navigation
+- Each sub-file has its own frontmatter with narrowed scope
+- Cross-references use relative paths
+```
+
+---
+
+## 变更清单（如果 v4 被批准）
+
+| 文件 | 变更 |
+|------|------|
+| `src/sspec/templates/skills/write-spec-doc/SKILL.md` | 替换为 v4 |
+| `src/sspec/templates/spec-docs/template.md` | 加 `scope: []` 字段 |
+| `src/sspec/templates/spec-docs/index.md` | 确认 scope 已有（已有） |
+| `.sspec/spec-docs/README.md` | 删除（legacy） |
+| `.sspec/project.md` Spec-Docs Index | 移除 README.md 条目 |
+| AGENTS.md §4 spec-doc 描述 | 不变（当前措辞已经准确） |
+
+## 未纳入 SKILL 的内容（可选去向）
+
+| 内容 | 建议去向 |
+|------|----------|
+| Mermaid diagramming examples | 不保留，agent 自己会 |
+| Maintenance checklist (updated/scope/links valid) | howto: `maintain-spec-doc` |
+| Detailed frontmatter field table (deprecated, replacement) | SKILL §5 已覆盖要点，不需要单独表 |