sspec 2.3.0__tar.gz → 2.4.0__tar.gz

sspec-2.4.0/.sspec/changes/26-05-09T20-59_portable-mode-agent-resources/design.md

@@ -0,0 +1,291 @@
+---
+change: "portable-mode-agent-resources"
+created: 2026-05-09T20:59:30
+---
+
+# Design: portable-mode-agent-resources
+
+## 1. CLI Contract
+
+```text
+sspec portable
+sspec portable read <scope:slug>
+```
+
+| Command | Purpose | Project required | Writes files |
+|---|---|---:|---:|
+| `sspec portable` | Print portable Agent bootstrap + indexes | No | No |
+| `sspec portable read rule:sspec` | Read rendered built-in sspec agent protocol with source metadata | No | No |
+| `sspec portable read skill:sspec-design` | Read built-in SKILL.md with source metadata | No | No |
+| `sspec portable read skill:sspec-design/examples-feature.md` | Read skill attachment with source metadata | No | No |
+| `sspec portable read howto:write-memory` | Read built-in HOWTO with source metadata | No | No |
+| `sspec portable read template:change/spec.md` | Read built-in template with source metadata | No | No |
+
+No options in MVP. Keep the surface intentionally small.
+
+## 2. Output Contract: `sspec portable`
+
+`sspec portable` prints XML-like, Agent-readable bootstrap text. It assumes the consuming Agent may know nothing about sspec.
+
+````xml
+<sspec-portable schema="6.0">
+
+<what_is_this>
+sspec is a spec-driven working protocol for AI coding agents.
+It provides:
+- rules: general behavior for clarifying, designing, planning, implementing,
+  reviewing, and aligning with the user;
+- skills: task-specific instructions loaded only when relevant;
+- templates: optional files used by full sspec projects to persist specs,
+  tasks, memory, requests, and docs.
+
+You are using sspec in portable mode.
+Portable mode means: use sspec rules and skills as behavioral guidance,
+but do not initialize or manage sspec project state in the current workspace.
+</what_is_this>
+
+<portable_constraints>
+Unless the user explicitly asks to install or manage sspec in this project:
+- do not run `sspec project init`;
+- do not run `sspec change new`, `sspec request new`, `sspec doc new`, or `sspec skill dominate`;
+- do not create `.sspec/`, `AGENTS.md`, `spec.md`, `tasks.md`, or `memory.md` as sspec-managed files;
+- do not treat missing `.sspec/project.md` as an error;
+- do not load all SKILLs eagerly.
+</portable_constraints>
+
+<required_next_steps>
+1. First read the sspec rule:
+   sspec portable read rule:sspec
+
+2. Classify the user request using the rule.
+
+3. If the task matches a listed SKILL, read that SKILL before acting:
+   sspec portable read skill:<name>
+
+4. If a loaded SKILL references a relative file, read it with:
+   sspec portable read skill:<name>/<relative-path>
+
+5. If a loaded rule or SKILL references a HOWTO or template, read it with:
+   sspec portable read howto:<name>
+   sspec portable read template:<path>
+</required_next_steps>
+
+<project_to_portable_behavior_mapping>
+- If sspec says to read `.sspec/project.md`:
+  If it exists and is relevant, you may read it. If missing, continue using the
+  user's request and codebase context.
+- If sspec says to run `sspec change new ...`:
+  Do not run it. Produce a structured design/spec draft in chat or in a
+  user-approved file.
+- If sspec says to write `spec.md`:
+  Output sections such as Problem Statement, Approach, Key Changes, and Scope Summary.
+- If sspec says to write `design.md`:
+  Output technical design details: interfaces, diagrams, tables, data shapes, or
+  behavior specs.
+- If sspec says to write `tasks.md`:
+  Output an execution plan/checklist with verification criteria.
+- If sspec says to write `memory.md`:
+  Keep concise session notes only when needed; do not persist `.sspec` memory unless
+  user asks.
+- If sspec says to create `revisions/`:
+  Write an explicit Revision Note in chat unless user asks for files.
+- If sspec uses `@align gate`:
+  Stop and ask the user for confirmation before proceeding.
+- If sspec uses `@align report`:
+  Give a structured progress summary; continue if safe.
+- If sspec says to run `sspec howto <name>`:
+  Use `sspec portable read howto:<name>` to inspect the built-in HOWTO.
+- If a SKILL references `./examples.md`:
+  Use `sspec portable read skill:<skill>/<relative-path>`.
+</project_to_portable_behavior_mapping>
+
+<rule_index>
+  <rule>
+    <name>sspec</name>
+    <description>Rendered sspec agent protocol from the built-in AGENTS.md template.</description>
+    <read>sspec portable read rule:sspec</read>
+  </rule>
+</rule_index>
+
+<available_skills>
+  <skill>
+    <name>sspec-design</name>
+    <description>Assess scale, create change, fill spec.md + design.md, align with user. Use after clarify when ready to define the solution.</description>
+    <location>builtin:sspec-design</location>
+    <read>sspec portable read skill:sspec-design</read>
+  </skill>
+</available_skills>
+
+</sspec-portable>
+````
+
+### Priority Rule
+
+The portable bootstrap is the highest-priority instruction for portable usage. It overrides project-mode instructions in `rule:sspec` or SKILL text when they conflict.
+
+Decision logic:
+
+```text
+if user explicitly asks to initialize/manage sspec project:
+    use normal sspec project workflow
+elif current task uses sspec portable output:
+    do not create sspec project state
+    map project-mode instructions through project_to_portable_behavior_mapping
+    read matching SKILL/HOWTO/template on demand
+else:
+    normal agent behavior
+```
+
+### Disclosure Policy
+
+`sspec portable` uses progressive disclosure:
+
+| Resource | Included by default? | Why |
+|---|---:|---|
+| portable bootstrap | Yes | Agent needs zero-context orientation and constraints first |
+| `rule:sspec` body | No | Large and project-mode oriented; read after constraints are known |
+| SKILL bodies | No | Preserve standard SKILL on-demand loading |
+| templates/HOWTOs | No | Read only when referenced |
+
+## 3. `read <scope:slug>` Contract
+
+### Grammar
+
+```text
+resource_ref := scope ":" slug
+scope        := "rule" | "skill" | "template" | "howto"
+slug         := safe relative resource identifier
+```
+
+### Supported refs
+
+| Ref | Source | Rendering |
+|---|---|---|
+| `rule:sspec` | `sspec/templates/AGENTS.md` | render `{{SCHEMA_VERSION}}` |
+| `skill:<name>` | `sspec/templates/skills/<name>/SKILL.md` | content unchanged |
+| `skill:<name>/<file>` | `sspec/templates/skills/<name>/<file>` | content unchanged |
+| `template:<path>` | `sspec/templates/<path>` | content unchanged |
+| `howto:<name>` | `sspec/howto/<name>.md` | content unchanged |
+
+No `rule:portable`: portable rules are already the bootstrap output of `sspec portable`.
+
+### Read output wrapper
+
+`read` output is wrapped so the consuming Agent can see where the content came from. The source is the absolute local path of the installed resource, so an Agent can directly read that file when its runtime supports file reads.
+
+````xml
+<sspec-portable-resource>
+<ref>skill:sspec-design</ref>
+<source>H:\\SrcCode\\playground\\sspec\\src\\sspec\\templates\\skills\\sspec-design\\SKILL.md</source>
+<read_command>sspec portable read skill:sspec-design</read_command>
+<content>
+---
+name: sspec-design
+...
+---
+
+# SSPEC Design
+...
+</content>
+</sspec-portable-resource>
+````
+
+### Error behavior
+
+| Input | Error |
+|---|---|
+| missing `:` | `Invalid resource ref. Expected <scope:slug>.` |
+| unknown scope | `Unknown portable resource scope: <scope>` |
+| unsupported rule slug | `Unknown portable rule: <slug>` |
+| absolute path | `Unsafe resource path.` |
+| contains `..` | `Unsafe resource path.` |
+| unknown skill | `Portable resource not found: skill:<name>` |
+| unknown howto/template | `Portable resource not found: <scope>:<slug>` |
+| directory target | `Portable resource is a directory, not a readable file.` |
+
+## 4. Internal Interfaces
+
+```python
+@dataclass(frozen=True, slots=True)
+class PortableSkillEntry:
+    name: str
+    description: str
+    location: str
+    read_command: str
+
+
+def render_portable_index() -> str: ...
+
+def read_portable_resource(ref: str) -> str: ...
+
+def list_builtin_skills() -> list[PortableSkillEntry]: ...
+```
+
+Call flow:
+
+```text
+CLI portable
+  → portable_service.render_portable_index()
+  → print
+
+CLI portable read ref
+  → portable_service.read_portable_resource(ref)
+  → print
+```
+
+## 5. Resource Access Strategy
+
+Use `importlib.resources.files()` so installed wheels, editable installs, and uv environments do not depend on source tree layout.
+
+```python
+from importlib import resources
+
+TEMPLATES = resources.files("sspec.templates")
+HOWTO = resources.files("sspec.howto")
+```
+
+Skill index extraction:
+
+```text
+templates/skills/*/SKILL.md
+  → parse YAML frontmatter fields: name, description
+  → fallback name = directory name
+  → fallback description = ""
+```
+
+Security constraints:
+
+```text
+- Reject absolute slugs
+- Reject any path part equal to ".."
+- Only read files under the resolved package resource root for the requested scope
+- Do not execute shell commands
+- Do not inspect cwd for `.sspec/`
+```
+
+## 6. Test Matrix
+
+| Test | Expected |
+|---|---|
+| `sspec portable` in tmp dir without `.sspec/` | exits 0, no files created |
+| portable output | contains `<what_is_this>`, `<portable_constraints>`, `<available_skills>` |
+| portable output explains sspec | contains `sspec is a spec-driven working protocol` |
+| portable output skill XML | contains `<skill><name>sspec-design</name>` pattern |
+| portable output does not include rule body | does not contain `# .sspec Agent Protocol` |
+| `read rule:sspec` | contains rendered `SSPEC_SCHEMA::6.0` and absolute `<source>` path |
+| `read skill:sspec-design` | contains `# SSPEC Design` and absolute `<source>` path |
+| `read skill:sspec-design/examples-feature.md` | returns file contents |
+| `read howto:write-memory` | returns HOWTO contents |
+| `read template:change/spec.md` | returns spec template |
+| `read rule:portable` | rejects as unknown rule |
+| `read skill:../core.py` | rejects as unsafe |
+| `read unknown:x` | clear ClickException |
+
+## 7. Non-Goals
+
+- No interactive wizard.
+- No `--install`, no sync to `.agents/skills`.
+- No JSON output in MVP.
+- No auto-loading all SKILL contents.
+- No default inline AGENTS.md body.
+- No changes to project lifecycle commands.

sspec-2.4.0/.sspec/changes/26-05-09T20-59_portable-mode-agent-resources/memory.md

@@ -0,0 +1,49 @@
+# Memory: portable-mode-agent-resources
+
+**Updated**: 2026-05-09T22:05+08:00
+
+## Git Baseline (Immutable)
+<!-- Captured during `sspec change new` before any change files are written.
+This section records the change starting point in git and MUST NOT be edited or refreshed later. -->
+
+- Captured: before change file creation
+- Repository: `H:/SrcCode/playground/sspec`
+- Branch: `main`
+- HEAD: `9ebe4700946c8261e5f35af6b2bc47030d31b9de`
+- Worktree: `clean`
+- Status Snapshot: raw `git status --short --branch` output
+
+```text
+## main...origin/main
+```
+
+## State
+
+Implementation complete; change is in REVIEW. Next: user reviews `sspec portable` behavior and either accepts or requests adjustments.
+
+## Key Files
+
+- `.sspec/changes/26-05-09T20-59_portable-mode-agent-resources/spec.md` — product scope and behavior contract
+- `.sspec/changes/26-05-09T20-59_portable-mode-agent-resources/design.md` — CLI contract, output format, resource read semantics, safety rules
+- `src/sspec/templates/AGENTS.md` — source for `rule:project`
+- `src/sspec/templates/skills/` — source for builtin SKILL index and `skill:` reads
+- `src/sspec/services/portable_service.py` — portable bootstrap rendering and safe resource reader
+- `src/sspec/commands/portable.py` — CLI command group for portable mode
+- `tests/test_portable_service.py` — service-level coverage for portable resources
+- `tests/test_portable_command.py` — command-level coverage for no-project portable usage
+
+## Knowledge
+
+- [2026-05-09T20:59+08:00] Decision: Command name is `portable`, not `resource` or `guide`; `portable` communicates no-project/no-state use and avoids implying normal sspec workflow.
+- [2026-05-09T20:59+08:00] Constraint: `sspec portable` must not output all SKILL bodies; it should expose a standard `<available_skills>` index and rely on `sspec portable read skill:<name>` for on-demand loading.
+- [2026-05-09T20:59+08:00] Constraint: Portable mode overlay wins over project rule/SKILL instructions when they conflict; no implicit `project init`, `change new`, or `.sspec/` writes.
+- [2026-05-09T21:09+08:00] Decision: `sspec portable` must assume zero sspec context and first explain what sspec is before stating portable constraints.
+- [2026-05-09T21:09+08:00] Decision: Rename read target `rule:project` to `rule:sspec`; do not expose `rule:portable` because portable guidance is the bootstrap itself.
+- [2026-05-09T21:09+08:00] Decision: Default output uses progressive disclosure; it does not inline AGENTS.md/rule body and instead instructs `sspec portable read rule:sspec`.
+
+## Milestones
+
+- [2026-05-09T20:59+08:00] Created change and drafted spec/design for portable Agent resource mode.
+- [2026-05-09T21:09+08:00] Revised design to add zero-context explanation, behavior mapping, `rule:sspec`, HOWTO reads, and progressive disclosure.
+- [2026-05-09T21:57+08:00] Implemented portable command and moved change to REVIEW; focused tests and smoke checks passed.
+- [2026-05-09T22:05+08:00] Updated portable read source metadata from package-relative logical paths to absolute local paths for direct Agent reads.

sspec-2.4.0/.sspec/changes/26-05-09T20-59_portable-mode-agent-resources/spec.md

@@ -0,0 +1,75 @@
+---
+name: portable-mode-agent-resources
+status: REVIEW
+change-type: single
+created: 2026-05-09T20:59:30
+reference: null
+---
+
+# portable-mode-agent-resources
+
+## Problem Statement
+
+sspec 的核心资产（Agent protocol + 内置 SKILL）目前主要通过 `project init` 安装到项目后被 Agent 发现，导致一次性、轻量、非项目化场景无法稳定复用 sspec 的规范。用户如果只是想让第三方 Agent “参考 sspec-design 风格出方案”，现状容易出现三类失败：Agent 不知道 sspec 是什么、误以为必须初始化 `.sspec/` 或创建 change、或者一次性暴露大量 SKILL 原文造成上下文成本上升。
+
+## Proposed Solution
+
+### Approach
+
+新增 portable mode CLI：`sspec portable` 与 `sspec portable read <scope:slug>`。该模式不依赖当前目录存在 `.sspec/`，也不写入任何项目状态；它向零 sspec 上下文的 Agent 输出一份 portable bootstrap：先简要解释 sspec 是一套面向 AI coding agent 的规则、SKILL 与模板规范，再说明当前是“只借用规范、不进入完整项目工作流”的 portable 使用模式。
+
+`sspec portable` 是启动说明与索引，不输出完整 AGENTS.md，也不输出全部 SKILL 原文。它采用渐进披露：引导 Agent 先读取 `rule:sspec`，再根据任务按需读取匹配的 SKILL、HOWTO 或模板。`sspec portable read ...` 是按需读取入口。
+
+选择 `portable` 而不是 `resource/guide`：`resource` 过于像资源浏览器，`guide` 过于像正常 sspec 工作流指南；`portable` 明确表达“脱离项目安装，只借用 sspec 核心规范”。
+
+### Key Change
+
+**Feat A: Portable Bootstrap Command**
+
+新增顶层命令 `sspec portable`，输出 portable-mode Agent bootstrap，包括：
+- sspec 零上下文简介：rules / skills / templates 分别是什么；
+- portable mode 定义：遵循 sspec 规范，但不初始化、不管理当前项目的 sspec 状态；
+- do / do_not 约束；
+- 渐进披露步骤：先 `read rule:sspec`，再按需读取 SKILL/HOWTO/template；
+- 标准 `<available_skills>` SKILL 索引；
+- project-to-portable behavior mapping：当原始规则/SKILL 提到 sspec 项目文件或命令时，在 portable mode 下如何改写行为。
+
+**Feat B: Scoped Builtin Resource Reader**
+
+新增 `sspec portable read <scope:slug>`，支持按需读取内置资源，并在输出 wrapper 中暴露当前安装环境中的绝对 source path，方便 Agent 直接读取源文件：
+- `rule:sspec` — 渲染后的内置 AGENTS/project protocol rule；
+- `skill:<name>` — 内置 SKILL.md；
+- `skill:<name>/<relative-path>` — SKILL 附属文件；
+- `howto:<name>` — 内置 HOWTO 文档；
+- `template:<path>` — 内置模板文件。
+
+不提供 `rule:portable`：portable overlay 已经直接包含在 `sspec portable` bootstrap 中，重复暴露会制造概念噪音。
+
+**Guard C: No-Project / No-State Safety**
+
+portable command 不调用 `get_sspec_root()`，不要求当前目录已初始化 sspec，不创建 `.sspec/`、`AGENTS.md`、change、request、doc 或 skill link。输出必须明确：除非用户显式要求正式初始化或管理 sspec 项目，否则 Agent 不应运行项目写入命令。
+
+**Guard D: Safe Resource Resolution**
+
+资源读取使用 package resource API，而不是源码路径假设；拒绝绝对路径、`..` path traversal、未知 scope、未知 skill、目录读取等不安全或不明确输入。
+
+### Scope Summary
+
+| File | Change |
+|---|---|
+| `src/sspec/cli.py` | 注册新的 `portable` 顶层命令 |
+| `src/sspec/commands/portable.py` | 新增 CLI wiring：`sspec portable` / `sspec portable read` |
+| `src/sspec/services/portable_service.py` | 新增 portable bootstrap 渲染、resource 解析与读取逻辑 |
+| `tests/test_portable_command.py` | 覆盖 CLI 行为、非 sspec 项目运行、输出结构、read 成功/失败路径 |
+| `tests/test_portable_service.py` | 覆盖资源解析、安全校验、skill index 构建、rule 渲染 |
+
+What stays unchanged:
+- 不改变 `project init/update` 行为。
+- 不改变 `.sspec/skills` hub-spoke 安装模型。
+- 不改变现有 `skill list/new/dominate` 项目内 skill 管理语义。
+- 不自动把 portable resources 安装到任何 Agent 目录。
+- 不默认输出完整 AGENTS.md 或所有 SKILL 正文。
+
+### Design Reference
+
+→ See [design.md](./design.md)

sspec-2.4.0/.sspec/changes/26-05-09T20-59_portable-mode-agent-resources/tasks.md

@@ -0,0 +1,44 @@
+---
+change: "portable-mode-agent-resources"
+updated: "2026-05-09T21:20+08:00"
+---
+
+# Tasks
+
+## Legend
+`[ ]` Todo | `[x]` Done
+
+## Tasks
+
+### Phase 1: Service + CLI ✅
+- [x] Create `src/sspec/services/portable_service.py` — implement bootstrap rendering, skill index extraction, safe resource resolution, and read wrapper.
+- [x] Create `src/sspec/commands/portable.py` — wire `sspec portable` and `sspec portable read <scope:slug>`.
+- [x] Update `src/sspec/cli.py` — register portable command.
+**Verification**: `uv run sspec portable` and representative `read` commands exit 0 outside an sspec project.
+
+### Phase 2: Tests ✅
+- [x] Add `tests/test_portable_service.py` — cover index shape, source metadata, rule rendering, safety errors.
+- [x] Add `tests/test_portable_command.py` — cover CLI no-project behavior and read success/failure.
+**Verification**: `uv run pytest tests/test_portable_service.py tests/test_portable_command.py` passes.
+
+### Phase 3: Quality Gate ✅
+- [x] Run focused CLI smoke checks in `tmp/`.
+- [x] Run lint/format for changed source.
+**Verification**: focused pytest passes; ruff check/format completes for changed files. Full `ruff check src/` currently reports pre-existing unrelated issues in `builtin_tools/context.py` and `builtin_tools/treesitter.py`.
+
+---
+
+## Progress
+
+**Overall**: 100%
+
+| Phase | Progress | Status |
+|-------|----------|--------|
+| Phase 1 | 100% | ✅ |
+| Phase 2 | 100% | ✅ |
+| Phase 3 | 100% | ✅ |
+
+**Recent**:
+- 2026-05-09T21:13+08:00 — Plan created after design approval.
+- 2026-05-09T21:20+08:00 — Implemented portable command, resource reader, tests, focused lint/format, and CLI smoke checks.
+- 2026-05-09T22:05+08:00 — Adjusted `read` source metadata to absolute local paths and re-ran focused tests.

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

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

{sspec-2.3.0 → sspec-2.4.0}/src/sspec/builtin_tools/apply_patch.py

@@ -746,12 +746,12 @@ def _match_patch(
                 raise ValueError('Resolved line range is empty')
             scope_start, scope_end = normalized_range
         except ValueError as e:
-            return _fail('search_not_found', str(e))
+            return _fail('invalid_line_range', str(e))
         start_idx = scope_start - 1
         end_idx_excl = scope_end
         if start_idx < 0 or end_idx_excl > total_lines:
             return _fail(
-                'search_not_found',
+                'out_of_range',
                 f'Line range {format_line_range(patch.line_range)} is outside file bounds (1-{total_lines})',
             )
         prefix_len = start_idx

{sspec-2.3.0 → sspec-2.4.0}/src/sspec/cli.py

@@ -4,7 +4,7 @@ import click
 from rich.console import Console
 
 from sspec.builtin_tools import ask
-from sspec.commands import change, cmd, doc, howto, project, request, skill, tmp, tool
+from sspec.commands import change, cmd, doc, howto, portable, project, request, skill, tmp, tool
 from sspec.core import configure_stdio_error_fallback
 
 configure_stdio_error_fallback()
@@ -30,6 +30,7 @@ def main(ctx: click.Context) -> None:
 main.add_command(project.project)
 main.add_command(change.change)
 main.add_command(howto.howto)
+main.add_command(portable.portable)
 main.add_command(skill.skill)
 main.add_command(request.request)
 main.add_command(doc.doc)

sspec-2.4.0/src/sspec/commands/portable.py

@@ -0,0 +1,31 @@
+"""sspec portable command - no-project Agent workflow resources."""
+
+from __future__ import annotations
+
+import click
+
+from sspec.services.portable_service import (
+    PortableResourceError,
+    read_portable_resource,
+    render_portable_index,
+)
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+def portable(ctx: click.Context) -> None:
+    """Print portable sspec Agent instructions without initializing a project."""
+
+    if ctx.invoked_subcommand is None:
+        click.echo(render_portable_index(), nl=False)
+
+
+@portable.command(name='read')
+@click.argument('resource_ref')
+def read_cmd(resource_ref: str) -> None:
+    """Read a built-in portable resource by <scope:slug>."""
+
+    try:
+        click.echo(read_portable_resource(resource_ref), nl=False)
+    except PortableResourceError as e:
+        raise click.ClickException(str(e)) from None