@captain_z/zsk 1.3.0 → 1.4.1

package/{templates/project-init/.zsk/schemas → schemas}/zsk-config.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://zsk.dev/schemas/zsk-config.schema.json",
+  "$id": "https://unpkg.com/@captain_z/zsk@1.3.0/schemas/zsk-config.schema.json",
   "title": "ZSK Project Config",
-  "description": "Project-level configuration for ZSK resource discovery, workspace paths, tools, and module index locations.",
+  "description": "Project-level configuration for ZSK resource origins, workspace paths, tools, and module index locations.",
   "type": "object",
   "additionalProperties": false,
   "required": ["project", "paths", "sources", "tools", "modules"],
@@ -49,29 +49,12 @@
       }
     },
     "sources": {
-      "description": "Project-level raw resource entry points.",
+      "description": "Project-level resource origins. May be empty after init and filled by AI or zsk config setup.",
       "type": "object",
-      "additionalProperties": false,
-      "required": ["srs", "figma_index", "api_contracts", "testing", "design_assets"],
+      "additionalProperties": {
+        "$ref": "#/$defs/sourceRef"
+      },
       "properties": {
-        "srs": {
-          "$ref": "#/$defs/sourceRef"
-        },
-        "figma_index": {
-          "$ref": "#/$defs/sourceRef"
-        },
-        "api_contracts": {
-          "$ref": "#/$defs/sourceRef"
-        },
-        "testing": {
-          "$ref": "#/$defs/sourceRef"
-        },
-        "design_assets": {
-          "$ref": "#/$defs/sourceRef"
-        },
-        "vendor_docs": {
-          "$ref": "#/$defs/sourceRef"
-        },
         "metadata": {
           "$ref": "#/$defs/metadata"
         }
@@ -143,28 +126,81 @@
       "type": "string",
       "enum": ["computer_use", "browser_use", "figma_mcp", "script", "manual", "skill"]
     },
+    "sourceType": {
+      "description": "Resource role.",
+      "type": "string",
+      "enum": ["srs", "prd", "design", "api_contract", "test_case", "design_asset", "vendor_doc", "manual"]
+    },
     "sourceRef": {
       "description": "Resource source reference.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "origin"],
+      "properties": {
+        "type": {
+          "$ref": "#/$defs/sourceType"
+        },
+        "origin": {
+          "$ref": "#/$defs/originRef"
+        },
+        "snapshot": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "originRef": {
+      "description": "Online or local source origin.",
       "oneOf": [
         {
-          "$ref": "#/$defs/localSource"
+          "$ref": "#/$defs/urlOrigin"
+        },
+        {
+          "$ref": "#/$defs/localOrigin"
+        },
+        {
+          "$ref": "#/$defs/gitOrigin"
         },
         {
-          "$ref": "#/$defs/scriptSource"
+          "$ref": "#/$defs/figmaOrigin"
         },
         {
-          "$ref": "#/$defs/skillSource"
+          "$ref": "#/$defs/modaoOrigin"
+        },
+        {
+          "$ref": "#/$defs/openapiOrigin"
+        },
+        {
+          "$ref": "#/$defs/manualOrigin"
         }
       ]
     },
-    "localSource": {
-      "description": "Resource that already exists in the project workspace.",
+    "urlOrigin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "url"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "url"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "localOrigin": {
       "type": "object",
       "additionalProperties": false,
       "required": ["kind", "path"],
       "properties": {
         "kind": {
-          "description": "Local source kind.",
           "type": "string",
           "const": "local"
         },
@@ -176,19 +212,133 @@
         }
       }
     },
-    "scriptSource": {
+    "gitOrigin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "repository"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "git"
+        },
+        "repository": {
+          "type": "string",
+          "minLength": 1
+        },
+        "ref": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "figmaOrigin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "url"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "figma"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "file_key": {
+          "type": "string",
+          "minLength": 1
+        },
+        "node_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "modaoOrigin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "url"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "modao"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "openapiOrigin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "openapi"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      },
+      "anyOf": [
+        {
+          "required": ["url"]
+        },
+        {
+          "required": ["path"]
+        }
+      ]
+    },
+    "manualOrigin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "note"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "manual"
+        },
+        "note": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "scriptSync": {
       "description": "Resource produced by a deterministic script command.",
       "type": "object",
       "additionalProperties": false,
       "required": ["kind", "command", "output"],
       "properties": {
         "kind": {
-          "description": "Script source kind.",
           "type": "string",
           "const": "script"
         },
         "command": {
-          "description": "Command that syncs this resource.",
           "type": "string",
           "minLength": 1
         },
@@ -200,19 +350,17 @@
         }
       }
     },
-    "skillSource": {
+    "skillSync": {
       "description": "Resource produced by an AI skill or tool-assisted workflow.",
       "type": "object",
       "additionalProperties": false,
       "required": ["kind", "skill", "output"],
       "properties": {
         "kind": {
-          "description": "Skill source kind.",
           "type": "string",
           "const": "skill"
         },
         "skill": {
-          "description": "Skill used to obtain the resource.",
           "type": "string",
           "minLength": 1
         },
@@ -228,10 +376,10 @@
       "description": "Optional sync entry for a resource provider.",
       "oneOf": [
         {
-          "$ref": "#/$defs/scriptSource"
+          "$ref": "#/$defs/scriptSync"
         },
         {
-          "$ref": "#/$defs/skillSource"
+          "$ref": "#/$defs/skillSync"
         }
       ]
     },

package/templates/issue/default/assets/index.md

@@ -0,0 +1,5 @@
+# Issue Assets Index
+
+Put screenshots, recordings, HAR files, JSON payloads, exported browser state, and other reproduction artifacts for this issue here.
+
+Reference each artifact from `../issue.md`.

package/templates/issue/default/debug-logs/index.md

@@ -0,0 +1,5 @@
+# Issue Debug Logs Index
+
+Put console output, test output, network logs, investigation logs, and command output for this issue here.
+
+Reference each log from `../issue.md`.

package/templates/issue/default/issue.md

@@ -0,0 +1,45 @@
+# __ISSUE_ID__-__ISSUE_SLUG__
+
+## 问题级别
+
+__SEVERITY__
+
+## 模块
+
+`__MODULE_ID__`
+
+## 环境
+
+- 日期：__DATE__
+- 分支：
+- URL：
+- 命令：
+- 浏览器：
+- 数据源：
+- 工具：
+
+## 复现步骤
+
+1.
+
+## 实际结果
+
+
+## 预期结果
+
+
+## 日志 / 截图
+
+- `assets/<file>`：
+- `debug-logs/<file>`：
+
+## 影响范围
+
+
+## 初步定位
+
+
+## 状态
+
+- 状态：Open
+- 复测：

package/templates/module/frontend-module/design.md

@@ -0,0 +1,6 @@
+# __MODULE_NAME__ Design
+
+## Documentation Feedback
+
+- No-update rationale:
+  - Created from the ZSK module template; no design decisions have been documented yet.

package/templates/module/frontend-module/module.yaml

@@ -0,0 +1,26 @@
+# yaml-language-server: $schema=https://unpkg.com/@captain_z/zsk@1.3.0/schemas/module.schema.json
+
+module:
+  id: __MODULE_ID__
+  name: __MODULE_NAME__
+
+sources: {}
+
+runtime:
+  url: http://localhost:3000
+  tools:
+    - computer_use
+    - browser_use
+
+tests:
+  raw_cases: []
+  derived_cases: []
+  automated:
+    unit: []
+    integration: []
+    e2e: []
+  tdd_required: true
+
+outputs:
+  docs: __DOCS_OUTPUT__
+  issues: __ISSUES_OUTPUT__

package/templates/module/frontend-module/spec.md

@@ -0,0 +1,6 @@
+# __MODULE_NAME__ Spec
+
+## Documentation Feedback
+
+- No-update rationale:
+  - Created from the ZSK module template; no accepted module behavior has been documented yet.

package/templates/module/frontend-module/tasks.md

@@ -0,0 +1,6 @@
+# __MODULE_NAME__ Tasks
+
+## Documentation Feedback
+
+- No-update rationale:
+  - Created from the ZSK module template; no implementation work has started yet.

package/templates/module/frontend-module/verification.md

@@ -0,0 +1,6 @@
+# __MODULE_NAME__ Verification
+
+## Documentation Feedback
+
+- No-update rationale:
+  - Created from the ZSK module template; no verification has been performed yet.

package/templates/project-init/.issues/README.md

@@ -1,26 +1,41 @@
-# Issues
+# .issues — Local Verification And Bug Evidence
 
-`.issues/` stores local review findings, bug reports, screenshots, logs, reproduction evidence, and verification records created during project work.
+This is the default issue root configured by `.zsk/config.yaml` `paths.issues`. It stores local review findings, bug reports, screenshots, logs, reproduction evidence, and verification records created during project work.
 
-## Layout
+## Directory Contract
 
 ```text
 .issues/
 ├── README.md
-├── _templates/
-│   └── issue.md
-└── {module}/
-    └── BUG-0001-short-slug/
-        ├── issue.md
-        ├── assets/
-        └── debug-logs/
+└── {area-or-module}/
+    ├── README.md                         # optional module issue index
+    ├── BUG-0001-short-slug/
+    │   ├── issue.md                      # required issue body
+    │   ├── analysis.md                   # optional root-cause notes
+    │   ├── reproduction.md               # optional detailed repro script
+    │   ├── assets/                       # screenshots, videos, HAR, exported state
+    │   │   └── index.md
+    │   └── debug-logs/                   # console, test, network, investigation logs
+    │       └── index.md
+    ├── _evidence/                        # shared evidence referenced by multiple issues/docs
+    └── _debug-logs/                      # untriaged or cross-issue historical logs only
 ```
 
-## Rules
+Use `zsk issue create -m <module-id>` to generate issue folders from the packaged template. `zsk init` does not write `_templates/` into the project.
+
+## Bug Directory Rules
 
 - Keep one confirmed bug per `BUG-xxxx-short-slug/` directory.
-- Group related bugs under the same module directory.
-- Put bug-specific screenshots and runtime evidence under that bug's `assets/`.
-- Put bug-specific console logs, test output, and investigation logs under that bug's `debug-logs/`.
-- Do not place runtime screenshots, debug logs, or failed verification artifacts under `docs/`.
-- Do not place local verification artifacts under `.raws/`.
+- Put the issue body in `issue.md`.
+- Put screenshots, recordings, HAR files, JSON payloads, exported browser state, and reproduction artifacts that belong to one bug under that bug's `assets/`.
+- Put console output, test output, debug logs, and investigation notes that belong to one bug under that bug's `debug-logs/`.
+- Use `analysis.md` only when root-cause reasoning is long enough that it would obscure the issue body.
+- If two symptoms share one root cause, keep one bug directory and list all symptoms as evidence inside it.
+
+## Relationship To Other Project Directories
+
+| Directory | Purpose | May contain local screenshots/logs? |
+|---|---|---|
+| `.raws/` | Upstream facts, mirrored snapshots, original external test cases | No |
+| `docs/{module}/` | Human-authored module proposal/spec/design/tasks/verification | No |
+| `.issues/{module}/` | Local defects, verification evidence, debug logs, issue-quality records | Yes |

package/templates/project-init/.raws/README.md

@@ -1,40 +1,26 @@
-# .raws/ — 项目原始事实源
+# Raw Snapshots
 
-本目录是项目的**原始事实源层**，存放由人类或外部系统维护、不由 LLM 自由改写的原始文档。
+This directory is the default local snapshot root configured by `.zsk/config.yaml` `paths.raws`.
 
-## 推荐内容
+Do not treat this directory as the source-origin configuration. SRS, PRD, Figma, Modao, API contracts, test cases, and design assets can come from online URLs, remote repositories, or local files. Their origins belong in `.zsk/config.yaml`.
 
-| 文件 / 子目录 | 用途 | zsk 配置入口 |
-| --- | --- | --- |
-| `SRS.md` | 原始需求文档（Software Requirements Spec） | `zsk.config.yaml#sources.srs.path` |
-| `FIGMA-INDEX.md` | 模块 → Figma URL / node-id 索引 | `zsk.config.yaml#sources.figma_index.path` |
-| `api-contracts/` | 后端 API 契约（OpenAPI / GraphQL schema） | `zsk.config.yaml#sources.api_contracts.path` |
-| `design-assets/{module}/{snapshot}/` | Figma 快照（由 `zsk:ue-mcp` 产出） | `zsk.config.yaml#sources.design_assets.path` |
-| `testing/` | 原始测试用例、验收用例、提测测试包 | `docs/{module}/module.yaml` 的 `tests.raw_cases` |
-| `manifest.json` | 资源同步清单，由 `zsk prep` / `zsk sync` 维护 | N/A |
+Start from `index.md` for the human/AI resource entry point. Use `manifest.json` as the generated machine index.
 
-## 消费路径
+## Expected Contents
 
-skill 通过 `zsk.config.yaml` 和 `docs/{module}/module.yaml` 找到本目录文件：
+- `index.md`: human/AI navigation entry point for raw resources.
+- `manifest.json`: machine-readable index maintained by `zsk prep` / `zsk sync`.
+- `requirements/`: SRS, PRD, acceptance notes, and other requirement snapshots.
+- `api-contracts/`: OpenAPI files, backend API repository snapshots, or exported API notes.
+- `design-sources/`: Figma, Modao, design handoff, and MCP capture snapshots.
+- `design-assets/`: Icons, images, tokens, and other design asset snapshots.
+- `testing/`: QA cases, acceptance cases, release cases, and imported test assets.
 
-```
-zsk.config.yaml:
-  sources:
-    srs:
-      path: .raws/SRS.md
-    testing:
-      path: .raws/testing
-```
+These directories are local landing zones only. The source addresses still belong in `.zsk/config.yaml` `sources`, so a resource can be online, a git repository path, a Figma/Modao URL, or a local file.
 
-## Git 状态建议
+## Rules
 
-- `SRS.md` / `FIGMA-INDEX.md`：**入库**（团队共享）
-- `design-assets/{module}/{snapshot}/raw/`：可选 `.gitignore`（体积大或含敏感信息）
-- 含敏感数据的文件：在本目录加 `.gitignore` 排除
-
-## 原则
-
-- **源文件不被 LLM 随意改写**：变更走人工/流程
-- **变更即新 snapshot**：Figma 更新→新 snapshot 目录，不覆盖历史
-- **编号锚稳定**：SRS 中的 `FR-001` / `US-001` / `AC-001` 一旦发布不改（仅废弃，合并/拆分留追踪）
-- **测试用例是一等资产**：原始测试用例保存在 `.raws/testing/`，派生测试矩阵和自动化映射写入 `docs/{module}/`
+- Preserve upstream wording. Do not rewrite snapshots to resolve conflicts.
+- Prefer new snapshots over overwriting historical design/API captures.
+- Keep runtime screenshots, debug logs, HAR files, and failed verification evidence out of this directory.
+- Skills must resolve this path from `.zsk/config.yaml`; they must not hard-code `.raws`.

package/templates/project-init/.raws/api-contracts/index.md

@@ -0,0 +1,22 @@
+# API Contracts Index
+
+Use this directory for backend API contracts needed by the current project. Organize by backend service, not by frontend page.
+
+## Organization
+
+```text
+.raws/api-contracts/
+├── index.md
+└── {service}/
+    ├── index.md
+    └── contracts/
+        └── {contract}.md
+```
+
+## Usage Rules
+
+- Configure API repositories, OpenAPI URLs, or local source paths in `.zsk/config.yaml` `sources`.
+- Prefer service-level folders such as `organization/`, `user/`, or `billing/`.
+- Keep selected frontend-facing contracts under `{service}/contracts/`.
+- If contracts are mirrored from another repo, record the original repository/ref/path in `.zsk/config.yaml`.
+- Avoid copying whole backend change directories unless the frontend module truly needs that context.

package/templates/project-init/.raws/design-assets/index.md

@@ -0,0 +1,25 @@
+# Design Assets Index
+
+Use this directory for design-layer static assets: icons, images, theme tokens, CSS exports, screenshots, and other files consumed by implementation.
+
+## Organization
+
+```text
+.raws/design-assets/
+├── index.md
+└── {module}/
+    ├── index.md
+    ├── *.json
+    ├── *.css
+    └── {YYYY-MM-DD}-{snapshot}/
+        ├── description.md
+        ├── screenshot-main.png
+        └── screenshot-{state}.png
+```
+
+## Usage Rules
+
+- Group assets by frontend module when possible.
+- Reference assets from `docs/{module}/design.md` or module-specific design handoff docs.
+- Record token/icon/component mapping decisions in module docs, not only in asset files.
+- Keep runtime verification screenshots under `.issues/`, not here.

package/templates/project-init/.raws/design-sources/index.md

@@ -0,0 +1,24 @@
+# Design Sources Index
+
+Use this directory for source-level design captures: Figma, Modao, design handoff exports, MCP readouts, and page/node metadata.
+
+## Organization
+
+```text
+.raws/design-sources/
+├── index.md
+└── {module-or-product-area}/
+    ├── index.md
+    ├── figma.json
+    ├── modao.json
+    └── {YYYY-MM-DD}-{snapshot}/
+        ├── description.md
+        └── raw/
+```
+
+## Usage Rules
+
+- Configure Figma/Modao URLs and node IDs in `.zsk/config.yaml` `sources`.
+- Keep source captures separate from implementation docs.
+- Use `description.md` when a snapshot needs human-readable layout, token, state, or interaction notes.
+- Treat raw MCP responses as cacheable unless the project chooses to commit them.

package/templates/project-init/.raws/index.md

@@ -0,0 +1,53 @@
+# .raws — Raw Resource Index
+
+This file is the human/AI entry point for upstream facts and local snapshots. It separates source configuration from local snapshot storage.
+
+## Directory Contract
+
+```text
+.raws/
+├── README.md
+├── index.md                 # this navigation index
+├── manifest.json            # generated machine index, refreshed by zsk prep
+├── requirements/            # SRS, PRD, acceptance notes, requirement snapshots
+│   └── index.md
+├── api-contracts/           # API contracts, OpenAPI files, backend repo extracts
+│   └── index.md
+├── design-sources/          # Figma, Modao, MCP, design handoff captures
+│   └── index.md
+├── design-assets/           # icons, images, tokens, screenshots, raw design assets
+│   └── index.md
+└── testing/                 # QA, acceptance, release, and imported test assets
+    └── index.md
+```
+
+## Source Configuration
+
+Real origins belong in `.zsk/config.yaml` `sources`. A source can be an online URL, git repository, Figma/Modao URL, OpenAPI location, or local file. Use `snapshot` only when the resource is materialized under `.raws/`.
+
+`manifest.json` is generated by `zsk prep` and records configured resources, snapshot existence, size, hash, and sync method. Do not edit it by hand unless recovering from a broken sync.
+
+## Categories
+
+| Category | Entry | Typical source types |
+|---|---|---|
+| Requirements | `requirements/index.md` | `srs`, `prd`, `manual` |
+| API contracts | `api-contracts/index.md` | `api_contract`, `vendor_doc` |
+| Design sources | `design-sources/index.md` | `design`, Figma, Modao, MCP |
+| Design assets | `design-assets/index.md` | `design_asset`, tokens, images |
+| Testing assets | `testing/index.md` | `test_case`, QA sheets, acceptance cases |
+
+## Boundary With Docs And Issues
+
+| Directory | Purpose | Runtime screenshots/logs |
+|---|---|---|
+| `.raws/` | Upstream facts and mirrored snapshots | No |
+| `docs/` | Human-authored module proposal/spec/design/tasks/verification | No |
+| `.issues/` | Local bugs, verification evidence, debug logs, screenshots | Yes |
+
+## Rules
+
+- Preserve upstream wording in snapshots.
+- Prefer appending new snapshots over overwriting historical captures.
+- Put source URLs and local origins in `.zsk/config.yaml`, not in scattered notes.
+- Keep runtime evidence, failed verification artifacts, HAR files, and debug logs under `.issues/`.