@captain_z/zsk 1.4.3 → 1.5.1

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

@@ -92,7 +92,7 @@ examples:
 | 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` | `.zsk/config.yaml#paths.issues` | bug、截图、日志、复测证据 |
+| Issues / evidence | `.issues/README.md` / `.issues/index.md` / `.issues/{module}/index.md` | `.zsk/config.yaml#paths.issues` | bug、截图、日志、复测证据、模块状态索引、全局统计 |
 
 ## 3. `.raws` / `docs` / `.issues` 边界
 
@@ -113,6 +113,8 @@ examples:
 > 设计资产：`.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`。
@@ -125,7 +127,7 @@ examples:
 | Language | `<language>` | TypeScript / Java / Go / etc. |
 | Build | `<build command>` | 与 package manager 保持一致 |
 | Test | `<test command>` | CI 和本地验收都应可复用 |
-| UI / Runtime verification | `computer_use / browser_use` | 具体工具以 `.zsk/config.yaml#tools` 为准 |
+| UI / Runtime verification | `playwright_cli / playwright_mcp / browser_use / computer_use` | Playwright 默认执行与证据；Browser Use 复用登录态；Computer Use 处理视觉/系统级场景 |
 
 ## 6. 冲突处理顺序
 
@@ -149,4 +151,4 @@ examples:
 - [ ] `.raws/index.md` 与相关分类 `index.md`
 - [ ] 受影响模块的 `docs/{module}/module.yaml`
 - [ ] 受影响模块的 `docs/{module}/spec.md` / `design.md`
-- [ ] 必要时新增或更新 `.issues/{module}/BUG-xxxx/issue.md`
+- [ ] 必要时新增或更新 `.issues/{module}/BUG-xxxx/issue.md`，并同步 `.issues/{module}/index.md` 与 `.issues/index.md`