@captain_z/zsk 1.6.0 → 1.7.0

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

@@ -1,17 +0,0 @@
-# __MODULE_NAME__ Archive
-
-## Closure
-
-| Item | Link |
-| --- | --- |
-
-## Learning Proposals
-
-| Finding | Target | Evidence |
-| --- | --- | --- |
-
-## Documentation Feedback
-
-- No-update rationale:
-  - Created from the ZSK module template; archive has not run yet.
-

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

@@ -1,15 +0,0 @@
-# __MODULE_NAME__ Commit
-
-## Commit Evidence
-
-| Item | Evidence |
-| --- | --- |
-| Review gate | |
-| Smoke gate | |
-| Commit | |
-
-## Documentation Feedback
-
-- No-update rationale:
-  - Created from the ZSK module template; no commit evidence has been captured yet.
-

package/templates/module/frontend-module/demo-outline.md

@@ -1,59 +0,0 @@
-# __MODULE_NAME__ Demo Outline
-
-## Demo Flow
-
-Use this section as the speaking order. The audience should be able to follow the demo from top to bottom without reading any appendix.
-
-| Step | Show | Function / Business Point | Scenario | Source Alignment | Playwright Case | Presenter Line | Expected Visible Result | Next |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| 1 | Starting state and primary goal |  |  | PRD/SRS + Spec + Task + Test | `scenarios/<case>.spec.ts` |  |  | 2 |
-| 2 | Core happy path / main value |  |  | PRD/SRS + Spec + Task + Test | `scenarios/<case>.spec.ts` |  |  | 3 |
-| 3 | Required branch / role / validation / edge |  |  | PRD/SRS + Spec + Task + Test | `scenarios/<case>.spec.ts` |  |  | Final |
-| Final | Final state, evidence, and known gaps |  |  | PRD/SRS + Spec + Task + Test |  | summarize evidence and known gaps |  | close |
-
-## Opening
-
-- Audience:
-- One-sentence goal:
-- Starting state:
-- Primary user journey:
-- What this demo proves:
-
-## Coverage Alignment
-
-Every required function point in the PRD/SRS should appear here, either as a demo step or as a known gap.
-
-| Function / Business Point | PRD / SRS Need | Spec / Design Contract | Task Scope | Test Case / Assertion | Demo Step | Status |
-| --- | --- | --- | --- | --- | --- | --- |
-|  |  |  |  |  | 1 | covered |
-|  |  |  |  |  | 2 | covered |
-|  |  |  |  |  | 3 | covered |
-
-## Rehearsal Checklist
-
-| Demo Step | Browser Use Handoff | Playwright Case | Rehearsed | Evidence | Ready |
-| --- | --- | --- | --- | --- | --- |
-| 1 |  |  | no | trace/report/screenshot | no |
-| 2 |  |  | no | trace/report/screenshot | no |
-| 3 |  |  | no | trace/report/screenshot | no |
-
-## Pause Rules
-
-- Pause if login/session state is lost.
-- Pause if the UI no longer matches the prepared Playwright case.
-- Pause if a P0/P1 function point cannot be shown.
-- Do not improvise new clicks during the external demo; record the blocker and return to Demo Prep.
-
-## Appendix: Prep Sources
-
-| Source | Path / Link | Used For |
-| --- | --- | --- |
-| SRS / PRD |  | user goal and scope |
-| Spec / AC |  | observable pass criteria |
-| Test cases |  | scenario steps and expected result |
-| Browser Use handoff |  | login state, visible target, candidate locators |
-
-## Documentation Feedback
-
-- No-update rationale:
-  - Created from the ZSK module template; no demo outline has been generated yet.

package/templates/module/frontend-module/demo-report.md

@@ -1,23 +0,0 @@
-# __MODULE_NAME__ Demo Report
-
-## Session
-
-- Session id:
-- Status: NOT_STARTED
-- Mode:
-
-## Coverage
-
-| Function Point | FR/AC | Scenario | Result | Evidence | Issues |
-| --- | --- | --- | --- | --- | --- |
-
-## Reusable Scenarios
-
-| Scenario | Source | Reuse Target | Evidence |
-| --- | --- | --- | --- |
-
-## Documentation Feedback
-
-- No-update rationale:
-  - Created from the ZSK module template; no demo has been performed yet.
-

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

@@ -1,18 +0,0 @@
-# __MODULE_NAME__ Deploy
-
-## Deployment
-
-| Environment | URL | Version | Result | Evidence |
-| --- | --- | --- | --- | --- |
-
-## Rollback
-
-- Owner:
-- Command:
-- Notes:
-
-## Documentation Feedback
-
-- No-update rationale:
-  - Created from the ZSK module template; no deployment has been performed yet.
-

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

@@ -1,12 +0,0 @@
-# __MODULE_NAME__ Ready
-
-## Gate
-
-| Issue | Fix Evidence | Deployment | Ready |
-| --- | --- | --- | --- |
-
-## Documentation Feedback
-
-- No-update rationale:
-  - Created from the ZSK module template; no fixes have been marked ready for verify yet.
-

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

@@ -1,12 +0,0 @@
-# __MODULE_NAME__ Review
-
-## Review Findings
-
-| Finding | Severity | Owner | Issue |
-| --- | --- | --- | --- |
-
-## Documentation Feedback
-
-- No-update rationale:
-  - Created from the ZSK module template; no review has been performed yet.
-

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

@@ -1,21 +0,0 @@
-# __MODULE_NAME__ Scenarios
-
-Reusable demo, verify, and regression scenarios for this module.
-
-Use this index to keep human test cases, Playwright scenarios, and evidence links aligned with module FR/AC IDs. Scenario files should stay module-local and should be referenced from `module.yaml` when they become part of the verification baseline.
-
-## 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 |
-
-## Scenario Index
-
-| Scenario | FR/AC Link | Automation | Evidence | Status |
-| --- | --- | --- | --- | --- |
-| `<scenario-name>` | `<FR/AC id>` | manual / Playwright / other | `<relative evidence path>` | draft / active / blocked / retired |

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

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

@@ -1,21 +0,0 @@
-# __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/verification.md

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

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/_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/.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/manifest.json

@@ -1,4 +0,0 @@
-{
-  "version": 1,
-  "resources": []
-}

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/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.