sspec 2.2.0__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.0 → 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.0 → 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.3.0/.sspec/requests/26-05-02T17-42_patch-method.md

@@ -0,0 +1,45 @@
+---
+name: patch-method
+created: 2026-05-02T17:42:04
+status: OPEN
+attach-change: null
+tldr: ""
+---
+
+<!-- MUST follow frontmatter schema:
+status: OPEN | DOING | DONE | CLOSED
+tldr: One-sentence summary for list views — fill this! -->
+
+# Request: patch-method
+
+## Problem
+
+
+当前的 builtin tool 中支持 patch tool，非常有用；但是我注意到当前的 Edit 似乎是顺序执行的，这可能带来意外的错误
+
+比如：原文 foo bar, patch : foo -> bar, bar -> tee
+
+结果报错，因为第二条 rule apply 的时候发现了两个 bar.
+
+---
+
+Think: 是不是应该做两阶段，先 match，确认范围，然后 repalce？
+
+Question: 这里就需要考虑 match 之后发现了 overlap scope 怎么办了；一种最简单的策略就是停下来报错
+
+## Initial Direction
+<!-- Your rough idea or preferred direction — details are fine but not required.
+This becomes the starting point for the change's spec.md Approach. -->
+
+请你首先梳理当前的 patch 算法是如何 apply 的，然后讨论优化策略
+
+## Success Criteria
+<!-- Conditions that indicate the problem has been resolved and meets the user's intention -->
+让 sspec tool patch 正确率更高，让 AGENT 更容易写对 patch blocks
+
+---
+
+## @AGENT
+<!-- What should Agent do to implement this request -->
+Adhere to the SSPEC protocol and commence development from the current Request file, following the SSPEC Change Lifecycle.
+Next step: Read `sspec-clarify` SKILL + `sspec-design` SKILL + `sspec change new --from <this>`.

sspec-2.3.0/.sspec/tmp/26-05-02_patch-two-phase-design.md

@@ -0,0 +1,194 @@
+# Design: patch tool Two-Phase Apply
+
+> 26-05-02 | mini change | request: 26-05-02T17-42_patch-method.md
+
+## Problem
+
+`apply_patches()` 顺序 apply：每条 patch 独立调用 `apply_patch()`，后者每次重新读文件。
+前一条 patch 的 REPLACE 改变了文件内容，后续 patch 的 SEARCH 基于新内容匹配 → 失败。
+
+```
+文件: foo bar
+Patch 1: SEARCH "foo" → REPLACE "bar"  → 文件变为 "bar bar"
+Patch 2: SEARCH "bar" → REPLACE "tee"  → 匹配到两处 → search_ambiguous ❌
+```
+
+Agent 意图是两个 patch 都能 apply，但顺序执行破坏了匹配基础。
+
+## Design
+
+**核心思路**：同文件多条 search patch → 全部基于原始内容 match → overlap 检查 → 从后往前 apply。
+
+### 架构
+
+```
+apply_patches()                           # 改写
+  ├─ parse_patches()                      # 不动
+  ├─ group patches by file                # 新增
+  └─ per file group:
+      ├─ 1 patch → apply_patch()          # 不动
+      └─ ≥2 search patches →
+           _apply_search_patches_batch()  # 新增
+```
+
+### 新增数据结构
+
+```python
+@dataclass
+class PatchMatch:
+    """Phase 1 match 结果，不做任何写入"""
+    patch: PatchBlock
+    abs_start: int            # 文件绝对行索引（0-based）
+    abs_end: int              # exclusive，基于绝对坐标
+    match_mode: str           # 'exact' | 'loose'
+    match_line: int           # 文件中 1-based 行号（= abs_start + 1）
+    status: str               # 'matched' | 'already_applied' | 'search_not_found' | 'search_ambiguous' | 'overlap_conflict'
+    error: str | None = None
+    related_lines: list[int] | None = None
+```
+
+> **注**：存绝对行索引而非 region-relative 偏移，避免跨不同 `line_range` 的 patch 坐标空间不一致导致 overlap 误判。
+
+### 新增函数：`_apply_search_patches_batch()`
+
+```python
+def _apply_search_patches_batch(
+    patches: list[PatchBlock],
+    *,
+    dry_run: bool = False,
+) -> list[PatchApplyResult]:
+    """
+    同文件多条 search patch 的协调 apply：
+    Phase 1: 所有 patch 基于原始文件内容 match（只读）
+    Phase 2: 验证无 overlap → 从后往前 apply
+    """
+```
+
+**Phase 1 详细流程**：
+
+```
+1. 读文件内容，检测编码和换行
+2. 逐条 patch:
+   a. 按 line_range 裁剪搜索区域（与现有 apply_patch 一致）
+   b. find_preferred_matches() 找 match
+   c. 结果写入 PatchMatch
+   d. 异常情况直接标记 status（already_applied / not_found / ambiguous）
+3. 检查 overlap：所有 status='matched' 的 match 基于**绝对行索引**两两比较
+   - 有 overlap → 全部标记为新 status='overlap_conflict'，附带 overlap 对的行号信息
+```
+
+**Phase 2 详细流程**：
+
+```
+1. 若有任何 success=False 的 status（search_not_found / search_ambiguous / overlap_conflict / missing_file 等）→ 不 apply，全部返回各自结果；already_applied 视为成功，不阻塞 apply
+2. 按 abs_start 降序排列（绝对坐标，splice 时不影响前面的索引）
+3. new_lines = file_lines[:] 作为 mutable 工作副本
+4. 逐个 splice：new_lines[:abs_start] + replace_lines + new_lines[abs_end:]（累积作用在上一次结果上）
+5. atomic_write_text(''.join(new_lines))
+```
+
+### 改写 `apply_patches()`
+
+```python
+def apply_patches(patch_text, *, project_root=None, dry_run=False):
+    parse_result = parse_patches(patch_text, project_root=project_root)
+    if parse_result.errors:
+        return BatchApplyResult(results=[...error results...])
+
+    # Group by (file_path, operation)
+    from itertools import groupby
+    patches = parse_result.patches
+
+    # 分离独立操作和需要协调的 search 操作，记录原始顺序
+    indexed_results: list[tuple[int, PatchApplyResult]] = []
+    file_search_patches: dict[Path, list[tuple[int, PatchBlock]]] = {}
+
+    for idx, p in enumerate(patches):
+        if p.operation == 'search':
+            file_search_patches.setdefault(p.file_path, []).append((idx, p))
+        else:
+            # CREATE / OVERWRITE 直接 apply（独立）
+            indexed_results.append((idx, apply_patch(p, dry_run=dry_run)))
+
+    # 同文件多 search → batch
+    for file_path, indexed_search_ps in file_search_patches.items():
+        if len(indexed_search_ps) == 1:
+            orig_idx, p = indexed_search_ps[0]
+            indexed_results.append((orig_idx, apply_patch(p, dry_run=dry_run)))
+        else:
+            search_ps = [p for _, p in indexed_search_ps]
+            batch_results = _apply_search_patches_batch(search_ps, dry_run=dry_run)
+            for (orig_idx, _), result in zip(indexed_search_ps, batch_results):
+                indexed_results.append((orig_idx, result))
+
+    # 按原始 patch 顺序排列，保证 CLI 输出顺序与输入一致
+    indexed_results.sort(key=lambda x: x[0])
+    results = [r for _, r in indexed_results]
+
+    return BatchApplyResult(results=results)
+```
+
+### Overlap 检测算法
+
+```python
+def _check_overlap(matches: list[PatchMatch]) -> list[tuple[PatchMatch, PatchMatch]]:
+    """基于绝对行索引返回所有重叠的 match 对"""
+    matched = [m for m in matches if m.status == 'matched']
+    overlaps = []
+    for i in range(len(matched)):
+        for j in range(i + 1, len(matched)):
+            a, b = matched[i], matched[j]
+            if a.abs_start < b.abs_end and b.abs_start < a.abs_end:
+                overlaps.append((a, b))
+    return overlaps
+```
+
+### 不动的部分
+
+| 组件 | 原因 |
+|------|------|
+| `apply_patch()` | 单条 patch 逻辑正确，复用它处理单文件单 patch |
+| `parse_patches()` | 解析层无问题 |
+| CLI 层 (`register_command`) | 纯展示 + 调度，不需要改 |
+| 所有 norm / match 工具函数 | 直接复用 |
+
+## 边界情况
+
+| 场景 | 行为 |
+|------|------|
+| 同文件 CREATE + SEARCH | CREATE 独立 apply，SEARCH 单独走 apply_patch |
+| 同文件 OVERWRITE + SEARCH | OVERWRITE 先 apply（顺序），SEARCH 后 apply |
+| patch 内 line_range | Phase 1 match 时按 line_range 裁剪 region |
+| 文件不存在 | Phase 1 读文件失败 → 全部 `missing_file` |
+| 已 apply 过（REPLACE 已在文件中） | Phase 1 `already_applied` → 不 apply 也不报错 |
+| 换行风格差异 | 与现有逻辑一致，detect + convert |
+
+## 代码量估算
+
+- `PatchMatch` dataclass: ~12 行
+- `_apply_search_patches_batch()`: ~80 行
+- `apply_patches()` 改写: ~35 行（含排序逻辑）
+- `_check_overlap()`: ~10 行
+- `PATCH_PROMPT` 措辞更新: ~2 行
+- **总计: ~140 行新增/改写，0 行删除**
+
+### PATCH_PROMPT 更新
+
+WARN 段落从：
+> patch-blocks are applied sequentially, lines affected by previous blocks may cause later blocks to fail.
+
+改为：
+> Multi-blocks targeting the same file are matched against the original content (not sequentially). Overlapping matches cause all related blocks to fail.
+
+## 测试计划
+
+```
+1. 基本 two-phase: 同文件 2 条不重叠 search patch → 都 apply
+2. overlap 检测: 2 条 search 区间重叠 → 全部失败
+3. 单文件单 patch: 走原有 apply_patch()，行为不变
+4. 已 apply 检测: REPLACE 已存在 → already_applied
+5. line_range 限制: 带 line_range 的 patch → match 区域正确裁剪
+6. 混合操作: CREATE + 多 search → CREATE 独立，search 走 two-phase
+7. 多文件交织: patch text 含 file1 + file2 + file1 → 正确分组
+8. 现有测试: uv run pytest tests/ 全通过（回归）
+```

{sspec-2.2.0 → 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.0 → sspec-2.3.0}/PKG-INFO

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