@captain_z/zsk 1.4.3 → 1.6.0

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

@@ -3,3 +3,9 @@
 Put screenshots, recordings, HAR files, JSON payloads, exported browser state, and other reproduction artifacts for this issue here.
 
 Reference each artifact from `../issue.md`.
+
+## Artifact Log
+
+| File | Type | Captured At | Used By | Notes |
+| --- | --- | --- | --- | --- |
+| `<file>` | screenshot / recording / HAR / JSON / other | `<ISO time>` | demo / smoke / verify / defect / review | `<why this artifact matters>` |

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

@@ -3,3 +3,9 @@
 Put console output, test output, network logs, investigation logs, and command output for this issue here.
 
 Reference each log from `../issue.md`.
+
+## Log Index
+
+| File | Source | Command / Context | Captured At | Result |
+| --- | --- | --- | --- | --- |
+| `<file>` | terminal / browser / server / CI / other | `<command or context>` | `<ISO time>` | pass / fail / inconclusive |

package/templates/issue/default/issue.md

@@ -1,9 +1,19 @@
 # __ISSUE_ID__-__ISSUE_SLUG__
 
+## 问题类型
+
+__ISSUE_TYPE__
+
 ## 问题级别
 
 __SEVERITY__
 
+## 严重性理由
+
+- 用户/业务影响：
+- 阻塞范围：
+- 是否有 workaround：
+
 ## 模块
 
 `__MODULE_ID__`
@@ -22,7 +32,7 @@ __SEVERITY__
 
 1.
 
-## 实际结果
+## 实际结果（当前现状）
 
 
 ## 预期结果
@@ -36,10 +46,33 @@ __SEVERITY__
 ## 影响范围
 
 
-## 初步定位
+## 根因分析
+
+- 初步根因：
+- 置信度：
+- 受影响代码/配置/资源：
+- 排除过的原因：
+
+## 修复路线
+
+- 路由：Coding / Spec 更新 / Design 更新 / 测试数据 / 环境 / 无效问题
+- Owner：
+- 回归保护：测试 / 场景 / lint / checklist / 豁免
+
+## Documentation Feedback
+
+- 需要反哺的文档：
+  - [ ] `docs/{module}/spec.md`
+  - [ ] `docs/{module}/design.md`
+  - [ ] `docs/{module}/tasks.md`
+  - [ ] `docs/SYSTEM-SPEC.md`
+  - [ ] `.zsk/learning/proposals`
+- 更新内容或 no-update rationale：
+- 反哺时机：修复通过 verify 且经用户/产品确认后执行
 
 
 ## 状态
 
 - 状态：Open
 - 复测：
+- 确认时间：

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

@@ -0,0 +1,18 @@
+# __MODULE_NAME__ Acceptance
+
+## Verdict
+
+- Result: NOT_STARTED
+- Accepted by:
+- Date:
+
+## Evidence Summary
+
+| Source | Conclusion | Link |
+| --- | --- | --- |
+
+## Documentation Feedback
+
+- No-update rationale:
+  - Created from the ZSK module template; no acceptance has been performed yet.
+

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

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

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

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

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

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

@@ -1,5 +1,17 @@
 # __MODULE_NAME__ Design
 
+## Playwright Locator And State Strategy
+
+| Scenario | Page / Route | Preferred Locator Strategy | State Coverage | API / Mock | Auth / Storage | Evidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| P0 happy path |  | getByRole / getByLabel / getByTestId | loading / success / error |  |  | screenshot + trace |
+
+Guidelines:
+
+- Prefer user-facing locators: `getByRole`, `getByLabel`, `getByPlaceholder`, `getByTestId`.
+- Add implementation tasks for missing accessible names, labels, or stable test ids.
+- Define auth/storage reuse before demo so Playwright can run repeatably.
+
 ## Documentation Feedback
 
 - No-update rationale:

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

@@ -9,6 +9,8 @@ sources: {}
 runtime:
   url: http://localhost:3000
   tools:
+    - playwright_mcp
+    - playwright
     - computer_use
     - browser_use
 
@@ -18,7 +20,8 @@ tests:
   automated:
     unit: []
     integration: []
-    e2e: []
+    e2e:
+      - __DOCS_OUTPUT__/scenarios
   tdd_required: true
 
 outputs:

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

@@ -0,0 +1,7 @@
+# __MODULE_NAME__ Proposal
+
+## Documentation Feedback
+
+- No-update rationale:
+  - Created from the ZSK module template; no proposal has been drafted yet.
+

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

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

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

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

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