@captain_z/zsk 1.6.1 → 1.8.1

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

@@ -1,12 +0,0 @@
-# __MODULE_NAME__ Verify
-
-## Verification
-
-| Issue / AC | Evidence | Result |
-| --- | --- | --- |
-
-## 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,57 +0,0 @@
-# .issues — Local Verification And Bug Evidence
-
-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.
-
-Every actionable finding from demo, smoke, review, formal test, verify, or acceptance should be persisted here or under the configured `paths.issues` root. Chat-only findings are not durable tracking.
-
-## Directory Contract
-
-```text
-.issues/
-├── README.md
-├── index.md                           # global module issue totals
-└── {area-or-module}/
-    ├── index.md                       # module issue index and status table
-    ├── 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
-    ├── demo/                          # optional stage view / evidence bucket
-    │   └── index.md
-    ├── _evidence/                        # shared evidence referenced by multiple issues/docs
-    └── _debug-logs/                      # untriaged or cross-issue historical logs only
-```
-
-Use `zsk issue create -m <module-id>` to generate issue folders from the packaged template. `zsk init` does not write `_templates/` into the project.
-
-`zsk issue update -m <module-id> --id <issue-dir> --status <status>` updates the concrete issue and refreshes:
-
-- `.issues/{module}/index.md` — all issues and statuses for one module.
-- `.issues/index.md` — module totals across the project.
-
-## Bug Directory Rules
-
-- Keep one confirmed bug per `BUG-xxxx-short-slug/` directory.
-- 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.
-
-## Closure And Documentation Feedback
-
-- Record the affected PRD/SRS, spec, design, task, test case, and evidence links in the issue.
-- After the fix is verified and confirmed by the user/product owner, update the relevant `docs/{module}/spec.md`, `docs/{module}/design.md`, `docs/{module}/tasks.md`, or project spec for gaps or vague behavior exposed by the issue.
-- Close the issue only after it links verification evidence, confirmation, documentation feedback update or no-update rationale, and regression guard.
-
-## 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/.issues/_taxonomy.md

@@ -1,35 +0,0 @@
-# Issue Taxonomy
-
-Managed issue records belong under `.issues/` or the configured `.zsk/config.yaml#paths.issues` root.
-
-Each module has a module index at `.issues/{module}/index.md`. The issue root has a global index at `.issues/index.md` with module totals. `zsk issue create` and `zsk issue update` refresh both indexes.
-
-| Type | Concrete Issue Directory | Prefix |
-| --- | --- | --- |
-| Demo Issue | `.issues/{module}/{prefix}-0001-slug/` | `DEMO` |
-| Smoke Issue | `.issues/{module}/{prefix}-0001-slug/` | `SMOKE` |
-| Review Issue | `.issues/{module}/{prefix}-0001-slug/` | `REV` |
-| Defect | `.issues/{module}/{prefix}-0001-slug/` | `DEFECT` |
-| Verify Issue | `.issues/{module}/{prefix}-0001-slug/` | `VER` |
-| Acceptance Issue | `.issues/{module}/{prefix}-0001-slug/` | `ACC` |
-
-Stage directories such as `.issues/{module}/demo/index.md` may exist as stage views or evidence buckets. The authoritative status indexes are `.issues/{module}/index.md` and `.issues/index.md`.
-
-`.raws/issues/` is reserved for imported external issue feeds or compatibility inputs.
-
-## Required Intake
-
-Every actionable issue should include:
-
-- reproduction steps or triggering command;
-- actual/current behavior;
-- expected behavior;
-- severity and rationale;
-- environment/version/data source;
-- evidence links;
-- root-cause hypothesis and confidence;
-- fix route;
-- Documentation Feedback target or no-update rationale;
-- regression guard.
-- verification evidence and user/product confirmation before closing behavior-changing issues;
-- updated module index and global issue index.

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

@@ -1,7 +0,0 @@
-# Issues Index
-
-Module-level issue totals. `zsk issue create` and `zsk issue update` refresh this file.
-
-| Module | Total | Open | Closed |
-| --- | ---: | ---: | ---: |
-|  | 0 | 0 | 0 |

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

@@ -1,27 +0,0 @@
-# Raw Snapshots
-
-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`.
-
-Start from `index.md` for the human/AI resource entry point. Use `manifest.json` as the generated machine index.
-
-## Expected Contents
-
-- `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, API schemas, or exported API notes.
-- `backend-repositories/`: small backend repository extracts that prove API/domain behavior.
-- `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.
-
-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.
-
-## Rules
-
-- 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

@@ -1,22 +0,0 @@
-# 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/backend-repositories/index.md

@@ -1,12 +0,0 @@
-# Backend Repositories
-
-Store lightweight backend repository snapshots here when a module needs API or domain evidence from server code.
-
-Prefer small, provenance-rich extracts over full repository dumps:
-
-- OpenAPI or generated API contract files.
-- Route/controller index excerpts that prove endpoint behavior.
-- DTO/schema/type definitions used by frontend contracts.
-- README or integration notes that define runtime requirements.
-
-Record the real repository origin in `.zsk/config.yaml` `sources`; this directory is only the local snapshot landing zone.

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

@@ -1,25 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-# 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

@@ -1,56 +0,0 @@
-# .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
-├── backend-repositories/    # lightweight 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` |
-| Backend repositories | `backend-repositories/index.md` | `backend_repo`, git repository extracts |
-| 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/`.

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

@@ -1,4 +0,0 @@
-# Raw Issue Imports
-
-Use this directory for imported issue feeds from external systems. Normalized managed issues belong under `.issues/`.
-

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

@@ -1,23 +0,0 @@
-# Requirements Index
-
-Use this directory for local snapshots of SRS, PRD, acceptance notes, product decisions, and other requirement documents.
-
-## Organization
-
-```text
-.raws/requirements/
-├── index.md
-├── srs.md
-├── prd.md
-└── {source-or-date}/
-    ├── page.md
-    ├── comments.json
-    └── attachments/
-```
-
-## Usage Rules
-
-- Configure real origins in `.zsk/config.yaml` `sources`.
-- Use this directory for immutable or append-only snapshots.
-- Reference requirement snapshots from `docs/{module}/proposal.md` and `docs/{module}/spec.md`.
-- Do not rewrite upstream text to resolve conflicts; document conflict analysis in module docs or `.issues/`.

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

@@ -1,22 +0,0 @@
-# Testing Assets Index
-
-Use this directory for upstream or imported test assets: QA sheets, acceptance cases, release cases, manual verification scripts, and exported test documents.
-
-## Organization
-
-```text
-.raws/testing/
-├── index.md
-├── qa-cases.md
-├── acceptance-cases.md
-└── {source-or-release}/
-    ├── cases.md
-    └── cases.xlsx
-```
-
-## Usage Rules
-
-- Configure real test case origins in `.zsk/config.yaml` `sources`.
-- Map module-level raw cases in `docs/{module}/module.yaml` `tests.raw_cases` or `sources.testing`.
-- Derived cases and automated tests belong in module docs or code test files.
-- `zsk check` treats non-index files here as raw test assets that should be mapped to a module.

package/templates/project-init/.zsk/checkpoints/index.md

@@ -1,4 +0,0 @@
-# ZSK Checkpoints
-
-Harness checkpoints and workflow traces belong here.
-

package/templates/project-init/.zsk/learning/index.md

@@ -1,14 +0,0 @@
-# ZSK Learning
-
-Project feedback and learning proposals belong here. Learning artifacts may propose changes to templates, constraints, skills, or packs, but they must not auto-mutate core assets.
-
-## Rules
-
-- Project-specific lessons stay in module archive docs or `docs/SYSTEM-SPEC.md`.
-- Reusable improvements become proposals under `.zsk/learning/proposals/`.
-- Core zsk changes require review, evidence, and a regression prompt before promotion.
-- Learning proposals may target harness constraints, templates, resource maps, root skills, or optional packs; they do not edit those targets automatically.
-
-## Proposal Template
-
-Use `harness/learning/proposal-template.md` from the installed zsk source as the canonical shape.

package/templates/project-init/.zsk/learning/proposals/.gitkeep

@@ -1 +0,0 @@
-

package/templates/project-init/.zsk/resource-manifest.json

@@ -1,55 +0,0 @@
-{
-  "version": 1,
-  "resources": {
-    "configured-sources": {
-      "source": ".zsk/config.yaml",
-      "status": "present",
-      "evidence": []
-    },
-    "resource-manifest": {
-      "source": ".zsk/resource-manifest.json",
-      "status": "present",
-      "evidence": []
-    },
-    "requirements": {
-      "source": ".raws/requirements",
-      "status": "missing",
-      "evidence": []
-    },
-    "api-contracts": {
-      "source": ".raws/api-contracts",
-      "status": "missing",
-      "evidence": []
-    },
-    "backend-repositories": {
-      "source": ".raws/backend-repositories",
-      "status": "missing",
-      "evidence": []
-    },
-    "design-sources": {
-      "source": ".raws/design-sources",
-      "status": "missing",
-      "evidence": []
-    },
-    "design-assets": {
-      "source": ".raws/design-assets",
-      "status": "missing",
-      "evidence": []
-    },
-    "test-cases": {
-      "source": ".raws/testing",
-      "status": "missing",
-      "evidence": []
-    },
-    "issue-records": {
-      "source": ".issues",
-      "status": "present",
-      "evidence": []
-    },
-    "learning-proposals": {
-      "source": ".zsk/learning/proposals",
-      "status": "present",
-      "evidence": []
-    }
-  }
-}

package/templates/project-init/.zsk/workflow-state.json

@@ -1,6 +0,0 @@
-{
-  "version": 1,
-  "modules": {},
-  "updatedAt": "__INIT_TIMESTAMP__"
-}
-

package/templates/project-init/docs/SYSTEM-SPEC.md

@@ -1,53 +0,0 @@
-# System Spec
-
-This file defines project-level behavior rules for humans and AI agents. Keep stable constraints here, and keep machine-readable paths and source origins in `.zsk/config.yaml`.
-
-## Source Priority
-
-When sources conflict, use this priority order until the project overrides it:
-
-1. `docs/SYSTEM-SPEC.md`
-2. `.zsk/config.yaml`
-3. Project sources listed in `.zsk/config.yaml`
-4. Module sources listed in `docs/{module}/module.yaml`
-5. `docs/{module}/spec.md`
-6. `docs/{module}/design.md`
-
-If two upstream sources conflict, do not silently choose one. Record the conflict under the configured issue root, then ask for confirmation before changing accepted specs or designs.
-
-## Store Policy
-
-- `paths.raws` stores local snapshots of upstream facts only.
-- `paths.docs` stores digested module knowledge, decisions, tasks, and verification.
-- `paths.issues` stores defects, local verification evidence, screenshots, logs, and retest records.
-- Runtime screenshots, debug logs, HAR files, and failed verification artifacts must not be stored under the docs root.
-
-## Testing Policy
-
-Test cases are first-class project assets.
-
-- Original QA, acceptance, release, and manually supplied test cases belong in configured project sources and may be snapshotted under `paths.raws`.
-- Module-derived test cases belong under each module's configured docs output.
-- AI coding must be TDD-driven from raw and module-derived test cases.
-- A task is not done until the relevant test case is covered by automated tests or recorded as runtime/manual verification evidence.
-
-## Documentation Feedback Policy
-
-Every project stage must feed confirmed conversation outcomes back into durable files.
-
-Required stage record:
-
-```md
-## Documentation Feedback
-
-- Conversation decisions captured:
-  - {decision or "None"}
-- Durable files updated:
-  - `{path}`: {what changed and why}
-- Source links:
-  - `{path or issue}`: {source role}
-- No-update rationale:
-  - {required when no file changed}
-```
-
-A stage is not complete until its documentation feedback check is complete.

package/templates/project-init/docs/_module-index.md

@@ -1,15 +0,0 @@
-# Module Index
-
-This file is the entry point for project modules. It is maintained by `zsk prep`, `zsk module init`, and AI-assisted module discovery.
-
-Use it to answer three questions before starting a skill stage:
-
-- which modules exist;
-- where each module's `module.yaml` lives;
-- whether the module is ready for proposal/spec/design/task/coding work.
-
-| Module | Name | Config | Status |
-| --- | --- | --- | --- |
-| `<module-id>` | `<module-name>` | `docs/<module-id>/module.yaml` | pending |
-
-Status values are project-owned. Recommended baseline: `pending`, `active`, `blocked`, `verified`, `archived`.

package/templates/project-init/project-config.md

@@ -1,154 +0,0 @@
----
-meta:
-  project_name: "<project-name>"
-  project_type: "<project-type>"
-  project_role: "<project-role>"
-  created: "<YYYY-MM-DD>"
-  maintainers: []
-
-config:
-  machine_config: ".zsk/config.yaml"
-  system_spec: "docs/SYSTEM-SPEC.md"
-
-paths:
-  raws_root: ".raws"
-  raws_index: ".raws/index.md"
-  raws_manifest: ".raws/manifest.json"
-  requirements_index: ".raws/requirements/index.md"
-  api_contracts_index: ".raws/api-contracts/index.md"
-  design_sources_index: ".raws/design-sources/index.md"
-  design_assets_index: ".raws/design-assets/index.md"
-  testing_index: ".raws/testing/index.md"
-  docs_root: "docs"
-  module_index: "docs/_module-index.md"
-  issues_root: ".issues"
-  issues_index: ".issues/README.md"
-
-source_registry:
-  canonical: ".zsk/config.yaml#sources"
-  local_snapshot_root: ".raws"
-  generated_manifest: ".raws/manifest.json"
-
-modules:
-  root: "docs"
-  index: "docs/_module-index.md"
-  module_config: "docs/{module}/module.yaml"
-  module_docs: "docs/{module}/proposal.md | spec.md | design.md | tasks.md | verification.md"
-  module_issues: ".issues/{module}"
-
-scripts:
-  install: "<install command>"
-  dev: "<dev command>"
-  build: "<build command>"
-  lint: "<lint command>"
-  type_check: "<typecheck command>"
-  test: "<test command>"
-  format: "<format command>"
-
-stack:
-  framework: "<framework>"
-  language: "<language>"
-  language_strict: true
-  build_tool: "<build-tool>"
-  css: "<css-stack>"
-  ui_lib: "<ui-library>"
-  test_framework: "<test-framework>"
-
-quality:
-  documentation_feedback_required: true
-  runtime_evidence_root: ".issues"
-  raw_snapshot_root: ".raws"
-  docs_runtime_artifacts_forbidden: true
-
-examples:
-  module_id: "sample-module"
-  issue_id: "BUG-0001"
----
-
-# Project Config — <project-name>
-
-> **定位**：项目级 AI 配置与机械查表锚点。
-> **维护方式**：与 [docs/SYSTEM-SPEC.md](./docs/SYSTEM-SPEC.md) 和 [.zsk/config.yaml](./.zsk/config.yaml) 同步维护。
-> **适用范围**：`.zsk/`、`.raws/`、`docs/`、`.issues/` 和项目代码。
-> **当前结论**：本文件面向人和 AI；机器校验以 `.zsk/config.yaml` 为准。
-
----
-
-## 1. 配置入口
-
-| 文件 | 定位 | 维护方式 |
-|---|---|---|
-| `.zsk/config.yaml` | 机器可读配置：路径、sources、tools、module root | 由 AI/人工编辑，`zsk config check` 校验 |
-| `project-config.md` | 人读项目配置：技术栈、脚本、路径、约束查表 | 与系统规约同步维护 |
-| `docs/SYSTEM-SPEC.md` | 项目级规则、事实源优先级、质量门禁 | 稳定约束变更时更新 |
-
-## 2. 资源入口
-
-| 资源 | 统一入口 | 机器索引 / 配置 | 说明 |
-|---|---|---|---|
-| Raw facts | `.raws/index.md` | `.raws/manifest.json` | 上游事实与本地快照导航 |
-| Requirements | `.raws/requirements/index.md` | `.zsk/config.yaml#sources` | SRS、PRD、验收说明 |
-| API contracts | `.raws/api-contracts/index.md` | `.zsk/config.yaml#sources` | OpenAPI、后端仓库、接口契约 |
-| Design sources | `.raws/design-sources/index.md` | `.zsk/config.yaml#sources` | Figma、Modao、MCP、设计交付源 |
-| Design assets | `.raws/design-assets/index.md` | `.zsk/config.yaml#sources` | token、图片、图标、截图、静态设计资产 |
-| Testing assets | `.raws/testing/index.md` | `.zsk/config.yaml#sources` + `docs/{module}/module.yaml` | QA、验收、发布测试用例 |
-| Issues / evidence | `.issues/README.md` / `.issues/index.md` / `.issues/{module}/index.md` | `.zsk/config.yaml#paths.issues` | bug、截图、日志、复测证据、模块状态索引、全局统计 |
-
-## 3. `.raws` / `docs` / `.issues` 边界
-
-| 目录 | 存放内容 | 不应存放 |
-|---|---|---|
-| `.raws/` | 上游事实、外部资源快照、原始测试资产 | 本地运行截图、debug log、失败验证证据 |
-| `docs/` | 模块 proposal/spec/design/tasks/verification、系统规约 | 运行时证据、HAR、控制台日志 |
-| `.issues/` | 本地缺陷、验证证据、截图、debug log、复测记录 | 上游 SRS/API/Figma 原文快照 |
-
-## 4. Module 文档如何引用资源
-
-模块文档优先通过相对路径引用资源：
-
-```md
-> 原始需求：`.raws/requirements/{file}`
-> API 契约：`.raws/api-contracts/{service}/contracts/{contract}.md`
-> 设计来源：`.raws/design-sources/{module}/`
-> 设计资产：`.raws/design-assets/{module}/`
-> 测试资产：`.raws/testing/{case-file}`
-> 本地问题：`.issues/{module}/BUG-0001-short-slug/issue.md`
-> 模块索引：`.issues/{module}/index.md`
-> 全局统计：`.issues/index.md`
-```
-
-模块级映射写入 `docs/{module}/module.yaml`，项目级来源写入 `.zsk/config.yaml#sources`。
-
-## 5. Coding 约束查表
-
-| 维度 | 当前项目值 | 说明 |
-|---|---|---|
-| Framework | `<framework>` | 从项目实际依赖填写 |
-| Language | `<language>` | TypeScript / Java / Go / etc. |
-| Build | `<build command>` | 与 package manager 保持一致 |
-| Test | `<test command>` | CI 和本地验收都应可复用 |
-| UI / Runtime verification | `playwright_cli / playwright_mcp / browser_use / computer_use` | Playwright 默认执行与证据；Browser Use 复用登录态；Computer Use 处理视觉/系统级场景 |
-
-## 6. 冲突处理顺序
-
-1. 用户明确指令 / 仓库 `AGENTS.md`
-2. `docs/SYSTEM-SPEC.md`
-3. `project-config.md`
-4. `.zsk/config.yaml`
-5. `.raws/` 中的上游事实源
-6. `docs/{module}/proposal.md|spec.md|design.md|tasks.md`
-7. 通用 skills / 模板
-
-如果两个上游事实源冲突，不要静默选择。应在 `.issues/{module}/` 记录冲突，并在模块 `spec.md` 或 `design.md` 的 Documentation Feedback 中写明处理结果。
-
-## 7. 维护清单
-
-项目硬约束新增或调整时，至少同步检查：
-
-- [ ] `.zsk/config.yaml`
-- [ ] `project-config.md`
-- [ ] `docs/SYSTEM-SPEC.md`
-- [ ] `.raws/index.md` 与相关分类 `index.md`
-- [ ] 受影响模块的 `docs/{module}/module.yaml`
-- [ ] 受影响模块的 `docs/{module}/spec.md` / `design.md`
-- [ ] 必要时新增或更新 `.issues/{module}/BUG-xxxx/issue.md`，并同步 `.issues/{module}/index.md` 与 `.issues/index.md`