@captain_z/zsk 1.4.2 → 1.5.1

package/templates/module/frontend-module/scenarios/index.md

@@ -0,0 +1,13 @@
+# __MODULE_NAME__ Scenarios
+
+Reusable demo, verify, and regression scenarios for this module.
+
+## Scenario Lifecycle
+
+| Stage | Responsibility |
+| --- | --- |
+| Spec | Define scenario contract and FR/AC linkage |
+| Design | Define locator/state/auth/evidence strategy |
+| Task | Create Playwright skeleton and fixture work |
+| Demo | Execute, record, and promote scenarios |
+| Verify | Reuse scenarios for fix verification |

package/templates/module/frontend-module/scenarios/p0-happy-path.spec.ts

@@ -0,0 +1,13 @@
+import { test, expect } from "@playwright/test";
+
+test.describe("__MODULE_NAME__ demo scenarios", () => {
+  test("P0 happy path", async ({ page }) => {
+    test.skip(!process.env.ZSK_DEMO_BASE_URL, "Set ZSK_DEMO_BASE_URL to run this scenario.");
+
+    await page.goto(process.env.ZSK_DEMO_BASE_URL);
+
+    // Replace this with the scenario contract from spec.md and locator strategy from design.md.
+    await expect(page).toHaveURL(/.+/);
+  });
+});
+

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

@@ -0,0 +1,21 @@
+# __MODULE_NAME__ Smoke
+
+## Resource Contract
+
+| Resource | Required | Source | Status | Used For | Blocker If Missing |
+| --- | --- | --- | --- | --- | --- |
+
+## Checks
+
+| Check | Command | Result | Evidence |
+| --- | --- | --- | --- |
+
+## Test Alignment
+
+| Test / Scenario | Source Requirement / Design / Issue | Expected Behavior | Accurate | Evidence |
+| --- | --- | --- | --- | --- |
+
+## Documentation Feedback
+
+- No-update rationale:
+  - Created from the ZSK module template; no smoke has been performed yet.

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

@@ -1,5 +1,19 @@
 # __MODULE_NAME__ Spec
 
+## Scenario Contracts
+
+| Scenario | User Goal | Entry | Preconditions | Observable Result | PRD/SRS / FR/AC | Automate |
+| --- | --- | --- | --- | --- | --- | --- |
+| P0 happy path |  |  |  |  |  | yes |
+
+Rules:
+
+- Define behavior and observable outcomes here.
+- Link every P0/P1 scenario back to the original PRD/SRS or accepted FR/AC.
+- Mark unclear or conflicting facts as blockers instead of choosing behavior silently.
+- Do not write brittle selectors in spec.
+- Mark which P0/P1 scenarios must become Playwright cases.
+
 ## Documentation Feedback
 
 - No-update rationale:

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

@@ -1,5 +1,18 @@
 # __MODULE_NAME__ Tasks
 
+## Playwright Case Tasks
+
+| Task | Scenario Contract | Case File | Fixture/Auth | Reuse Target | Status |
+| --- | --- | --- | --- | --- | --- |
+| Create P0 happy path skeleton | P0 happy path | `scenarios/p0-happy-path.spec.ts` |  | demo, verify, regression | TODO |
+
+Rules:
+
+- Create Playwright skeletons before demo.
+- Create or update source-aligned tests/scenarios before implementation for testable behavior changes.
+- Tag cases as smoke/demo/verify/regression.
+- Include tasks for labels/test ids required by stable locators.
+
 ## Documentation Feedback
 
 - No-update rationale:

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

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

@@ -2,13 +2,16 @@
 
 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}/
-    ├── README.md                         # optional module issue index
+    ├── index.md                       # module issue index and status table
     ├── BUG-0001-short-slug/
     │   ├── issue.md                      # required issue body
     │   ├── analysis.md                   # optional root-cause notes
@@ -17,12 +20,19 @@ This is the default issue root configured by `.zsk/config.yaml` `paths.issues`.
     │   │   └── 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.
@@ -32,6 +42,12 @@ Use `zsk issue create -m <module-id>` to generate issue folders from the package
 - 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? |

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

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

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

@@ -11,7 +11,8 @@ Start from `index.md` for the human/AI resource entry point. Use `manifest.json`
 - `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.
+- `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.

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

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

@@ -13,6 +13,8 @@ This file is the human/AI entry point for upstream facts and local snapshots. It
 │   └── 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
@@ -33,6 +35,7 @@ Real origins belong in `.zsk/config.yaml` `sources`. A source can be an online U
 |---|---|---|
 | 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 |

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

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

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

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

package/templates/project-init/.zsk/config.yaml

@@ -25,15 +25,70 @@ paths:
 #       kind: figma
 #       url: https://www.figma.com/file/...
 #     snapshot: .raws/design-sources/figma-main.json
+#   backend_api:
+#     type: backend_repo
+#     origin:
+#       kind: git
+#       repository: https://github.com/example/backend-api.git
+#       path: openapi.yaml
+#     snapshot: .raws/backend-repositories/backend-openapi.yaml
+#   acceptance_cases:
+#     type: test_case
+#     origin:
+#       kind: url
+#       url: https://example.com/qa-cases
+#     snapshot: .raws/testing/acceptance-cases.md
 sources: {}
 
 tools:
   runtime_ui:
-    - computer_use
+    - playwright_cli
+    - playwright_mcp
+    - playwright
     - browser_use
+    - computer_use
   design:
     - figma_mcp
 
 modules:
   index: docs/_module-index.md
   root: docs
+
+automation:
+  smoke:
+    commands:
+      - pnpm lint
+      - pnpm typecheck
+      - pnpm test
+  deploy:
+    command: pnpm deploy:staging
+  demo:
+    # Default hybrid lane:
+    # - Playwright CLI/UI mode is preferred for visible demo performance, controlled stop/pause, screenshots, traces, reports, and repeatable runs.
+    # - Playwright MCP inspects structured accessibility snapshots and proposes operations when needed.
+    # - Browser Use identifies the human-intent target and preserves existing logged-in browser/profile state when auth cannot be reproduced cheaply.
+    # - Computer Use is reserved for visual/system-level context that browser automation cannot expose.
+    # - Playwright consumes the handoff to pre-write/rehearse scenarios, then performs the external demo with visible trace/report evidence.
+    defaultMode: hybrid
+    baseUrl: http://localhost:3000
+    command: pnpm dev
+    evidenceDir: .issues/{module}/demo/_evidence
+    scenarioDir: docs/{module}/scenarios
+    playwright:
+      config: playwright.config.ts
+      project: chromium
+      cli: playwright-cli
+    computerUse:
+      enabled: false
+      role: understand-and-decide
+    bridge:
+      enabled: true
+      # decisionTool may be playwright_mcp for structured accessibility snapshots,
+      # browser_use for existing login/profile state, or computer_use for visual/system-level understanding.
+      decisionTool: playwright_mcp
+      executionTool: playwright
+      planFile: .zsk/demo-sessions/{module}/operation-plan.json
+      executionFile: .zsk/demo-sessions/{module}/playwright-execution.json
+  verify:
+    commands:
+      - pnpm test:e2e

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

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,55 @@
+{
+  "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

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

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

@@ -0,0 +1,154 @@
+---
+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`