@captain_z/zsk 1.6.0 → 1.7.0

package/dist/core/workspace-layout.d.ts

@@ -0,0 +1,54 @@
+export declare const WORKSPACE_LAYOUT_VERSION = 2;
+export declare const DEFAULT_WORKSPACE_PATHS: {
+    readonly docs: ".zsk/docs";
+    readonly modules: ".zsk/modules";
+    readonly resources: ".zsk/resources";
+    readonly issues: ".zsk/issues";
+    readonly evidence: ".zsk/evidence";
+    readonly playwright: ".zsk/playwright";
+    readonly plans: ".zsk/plans";
+};
+export type WorkspaceLayoutConfig = {
+    paths?: {
+        docs?: string;
+        modules?: string;
+        resources?: string;
+        issues?: string;
+        evidence?: string;
+        playwright?: string;
+        plans?: string;
+        raws?: string;
+    };
+    modules?: {
+        index?: string;
+        root?: string;
+    };
+    automation?: {
+        demo?: {
+            evidenceDir?: string;
+            scenarioDir?: string;
+            bridge?: {
+                planFile?: string;
+                executionFile?: string;
+            };
+        };
+    };
+};
+export type WorkspaceLayout = {
+    version: number;
+    docsRoot: string;
+    modulesRoot: string;
+    resourcesRoot: string;
+    issuesRoot: string;
+    evidenceRoot: string;
+    playwrightRoot: string;
+    plansRoot: string;
+};
+export type WorkspacePathKind = "config" | "workflowState" | "mcpPlaywrightConfig" | "docsRoot" | "projectConfig" | "systemSpec" | "modulesRoot" | "moduleIndex" | "moduleRoot" | "moduleConfig" | "moduleRuns" | "resourcesRoot" | "resourcesTesting" | "resourcesManifest" | "issuesRoot" | "moduleIssues" | "evidenceRoot" | "moduleEvidence" | "demoEvidence" | "playwrightRoot" | "plansRoot" | "modulePlaywright" | "playwrightSpecs" | "playwrightTestPlans" | "playwrightAuth" | "playwrightAuthState" | "playwrightResults" | "playwrightReport" | "playwrightExecution" | "demoSessionCurrent" | "bridgeOperationPlan" | "bridgeExecution";
+export type WorkspacePathOptions = {
+    module?: string;
+};
+export declare function resolveWorkspaceLayout(config?: WorkspaceLayoutConfig): WorkspaceLayout;
+export declare function getWorkspacePath(config: WorkspaceLayoutConfig, kind: WorkspacePathKind, options?: WorkspacePathOptions): string;
+export declare function resolveWorkspacePath(root: string, config: WorkspaceLayoutConfig, kind: WorkspacePathKind, options?: WorkspacePathOptions): string;
+export declare function interpolateModulePath(value: string, moduleId: string): string;

package/dist/core/workspace-layout.js

@@ -0,0 +1,107 @@
+import { isAbsolute, join, resolve } from "node:path";
+export const WORKSPACE_LAYOUT_VERSION = 2;
+export const DEFAULT_WORKSPACE_PATHS = {
+    docs: ".zsk/docs",
+    modules: ".zsk/modules",
+    resources: ".zsk/resources",
+    issues: ".zsk/issues",
+    evidence: ".zsk/evidence",
+    playwright: ".zsk/playwright",
+    plans: ".zsk/plans",
+};
+export function resolveWorkspaceLayout(config = {}) {
+    const paths = config.paths ?? {};
+    return {
+        version: WORKSPACE_LAYOUT_VERSION,
+        docsRoot: paths.docs ?? DEFAULT_WORKSPACE_PATHS.docs,
+        modulesRoot: paths.modules ?? config.modules?.root ?? DEFAULT_WORKSPACE_PATHS.modules,
+        resourcesRoot: paths.resources ?? paths.raws ?? DEFAULT_WORKSPACE_PATHS.resources,
+        issuesRoot: paths.issues ?? DEFAULT_WORKSPACE_PATHS.issues,
+        evidenceRoot: paths.evidence ?? DEFAULT_WORKSPACE_PATHS.evidence,
+        playwrightRoot: paths.playwright ?? DEFAULT_WORKSPACE_PATHS.playwright,
+        plansRoot: paths.plans ?? DEFAULT_WORKSPACE_PATHS.plans,
+    };
+}
+export function getWorkspacePath(config, kind, options = {}) {
+    const layout = resolveWorkspaceLayout(config);
+    const moduleId = options.module;
+    switch (kind) {
+        case "config":
+            return join(".zsk", "config.yaml");
+        case "workflowState":
+            return join(".zsk", "workflow-state.json");
+        case "mcpPlaywrightConfig":
+            return join(".zsk", "mcp", "playwright.json");
+        case "docsRoot":
+            return layout.docsRoot;
+        case "projectConfig":
+            return join(layout.docsRoot, "PROJECT-CONFIG.md");
+        case "systemSpec":
+            return join(layout.docsRoot, "SYSTEM-SPEC.md");
+        case "modulesRoot":
+            return layout.modulesRoot;
+        case "moduleIndex":
+            return config.modules?.index ?? join(layout.modulesRoot, "_module-index.md");
+        case "moduleRoot":
+            return join(layout.modulesRoot, requireModuleId(kind, moduleId));
+        case "moduleConfig":
+            return join(layout.modulesRoot, requireModuleId(kind, moduleId), "module.yaml");
+        case "moduleRuns":
+            return join(layout.modulesRoot, requireModuleId(kind, moduleId), "runs");
+        case "resourcesRoot":
+            return layout.resourcesRoot;
+        case "resourcesTesting":
+            return join(layout.resourcesRoot, "testing");
+        case "resourcesManifest":
+            return join(layout.resourcesRoot, "manifest.json");
+        case "issuesRoot":
+            return layout.issuesRoot;
+        case "moduleIssues":
+            return join(layout.issuesRoot, requireModuleId(kind, moduleId));
+        case "evidenceRoot":
+            return layout.evidenceRoot;
+        case "moduleEvidence":
+            return join(layout.evidenceRoot, requireModuleId(kind, moduleId));
+        case "demoEvidence":
+            return join(layout.evidenceRoot, requireModuleId(kind, moduleId), "demo");
+        case "playwrightRoot":
+            return layout.playwrightRoot;
+        case "plansRoot":
+            return layout.plansRoot;
+        case "modulePlaywright":
+            return join(layout.playwrightRoot, requireModuleId(kind, moduleId));
+        case "playwrightSpecs":
+            return join(layout.playwrightRoot, requireModuleId(kind, moduleId), "specs");
+        case "playwrightTestPlans":
+            return join(layout.playwrightRoot, requireModuleId(kind, moduleId), "test-plans");
+        case "playwrightAuth":
+            return join(layout.playwrightRoot, requireModuleId(kind, moduleId), ".auth");
+        case "playwrightAuthState":
+            return join(layout.playwrightRoot, requireModuleId(kind, moduleId), ".auth", "user.json");
+        case "playwrightResults":
+            return join(layout.playwrightRoot, requireModuleId(kind, moduleId), "results");
+        case "playwrightReport":
+            return join(layout.playwrightRoot, requireModuleId(kind, moduleId), "report");
+        case "playwrightExecution":
+            return join(layout.playwrightRoot, requireModuleId(kind, moduleId), "execution");
+        case "demoSessionCurrent":
+            return join(layout.playwrightRoot, requireModuleId(kind, moduleId), "execution", "current.json");
+        case "bridgeOperationPlan":
+            return join(layout.playwrightRoot, requireModuleId(kind, moduleId), "execution", "operation-plan.json");
+        case "bridgeExecution":
+            return join(layout.playwrightRoot, requireModuleId(kind, moduleId), "execution", "playwright-execution.json");
+    }
+}
+export function resolveWorkspacePath(root, config, kind, options = {}) {
+    const workspacePath = getWorkspacePath(config, kind, options);
+    return isAbsolute(workspacePath) ? workspacePath : resolve(root, workspacePath);
+}
+export function interpolateModulePath(value, moduleId) {
+    return value.split("{module}").join(moduleId);
+}
+function requireModuleId(kind, moduleId) {
+    if (moduleId)
+        return moduleId;
+    throw new Error(`${kind} requires a module id`);
+}
+//# sourceMappingURL=workspace-layout.js.map

package/dist/core/workspace-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-layout.js","sourceRoot":"","sources":["../../src/core/workspace-layout.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@captain_z/zsk",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "ZNorth Standard Kit — CLI installer for zsk skill bundles (npx @captain_z/zsk add)",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,7 @@
     "commander": "^12.1.0",
     "picocolors": "^1.1.1",
     "yaml": "^2.7.0",
-    "@captain_z/zsk-skills": "1.6.0"
+    "@captain_z/zsk-skills": "1.8.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/schemas/zsk-config.schema.json

@@ -28,21 +28,42 @@
         }
       }
     },
+    "layoutVersion": {
+      "description": "Workspace layout version. Version 2 keeps all zsk-managed outputs under .zsk/ by default.",
+      "type": "integer",
+      "minimum": 2
+    },
     "paths": {
       "description": "Top-level project knowledge workspace paths.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["raws", "docs", "issues"],
+      "required": ["docs", "modules", "resources", "issues", "evidence", "playwright"],
       "properties": {
-        "raws": {
+        "docs": {
           "$ref": "#/$defs/pathRef"
         },
-        "docs": {
+        "modules": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "resources": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "raws": {
+          "description": "Legacy resource root accepted only for compatibility with older workspaces.",
           "$ref": "#/$defs/pathRef"
         },
         "issues": {
           "$ref": "#/$defs/pathRef"
         },
+        "evidence": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "playwright": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "plans": {
+          "$ref": "#/$defs/pathRef"
+        },
         "metadata": {
           "$ref": "#/$defs/metadata"
         }
@@ -121,7 +142,7 @@
           "properties": {
             "defaultMode": {
               "type": "string",
-              "enum": ["manual", "script", "playwright", "computer-use", "hybrid"]
+              "enum": ["manual", "script", "optimized", "playwright", "computer-use", "hybrid"]
             },
             "baseUrl": {
               "type": "string",

package/templates/issue/default/issue.md

@@ -62,11 +62,11 @@ __SEVERITY__
 ## Documentation Feedback
 
 - 需要反哺的文档：
-  - [ ] `docs/{module}/spec.md`
-  - [ ] `docs/{module}/design.md`
-  - [ ] `docs/{module}/tasks.md`
-  - [ ] `docs/SYSTEM-SPEC.md`
-  - [ ] `.zsk/learning/proposals`
+  - [ ] `.zsk/modules/{module}/spec.md`
+  - [ ] `.zsk/modules/{module}/design.md`
+  - [ ] `.zsk/modules/{module}/tasks.md`
+  - [ ] `.zsk/docs/SYSTEM-SPEC.md`
+  - [ ] `.zsk/resources`
 - 更新内容或 no-update rationale：
 - 反哺时机：修复通过 verify 且经用户/产品确认后执行
 

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

@@ -9,19 +9,20 @@ sources: {}
 runtime:
   url: http://localhost:3000
   tools:
-    - playwright_mcp
+    - playwright_cli
     - playwright
     - computer_use
     - browser_use
 
 tests:
   raw_cases: []
-  derived_cases: []
+  derived_cases:
+    - __PLAYWRIGHT_TEST_PLANS__/test-plan.json
   automated:
     unit: []
     integration: []
     e2e:
-      - __DOCS_OUTPUT__/scenarios
+      - __PLAYWRIGHT_SPECS__
   tdd_required: true
 
 outputs:

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

@@ -4,11 +4,11 @@
 
 | 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 |
+| Create P0 happy path skeleton | P0 happy path | `__PLAYWRIGHT_SPECS__/p0-happy-path.spec.ts` |  | demo, verify, regression | TODO |
 
 Rules:
 
-- Create Playwright skeletons before demo.
+- Create Playwright skeletons under `__PLAYWRIGHT_SPECS__` 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.

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

@@ -1,16 +1,22 @@
 # yaml-language-server: $schema=__ZSK_CONFIG_SCHEMA_URL__
 
+layoutVersion: 2
+
 project:
   name: "<project-name>"
 
 paths:
-  raws: .raws
-  docs: docs
-  issues: .issues
+  docs: .zsk/docs
+  modules: .zsk/modules
+  resources: .zsk/resources
+  issues: .zsk/issues
+  evidence: .zsk/evidence
+  playwright: .zsk/playwright
+  plans: .zsk/plans
 
 # Resource origins. AI or zsk config setup should fill these with online URLs,
 # git repositories, Figma/Modao links, OpenAPI locations, or local files.
-# Optional snapshots should land under paths.raws, for example:
+# Optional snapshots should land under paths.resources, for example:
 #
 # sources:
 #   srs:
@@ -18,26 +24,26 @@ paths:
 #     origin:
 #       kind: url
 #       url: https://example.com/srs
-#     snapshot: .raws/requirements/srs.md
+#     snapshot: .zsk/resources/requirements/srs.md
 #   figma_main:
 #     type: design
 #     origin:
 #       kind: figma
 #       url: https://www.figma.com/file/...
-#     snapshot: .raws/design-sources/figma-main.json
+#     snapshot: .zsk/resources/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
+#     snapshot: .zsk/resources/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
+#     snapshot: .zsk/resources/testing/acceptance-cases.md
 sources: {}
 
 tools:
@@ -45,14 +51,14 @@ tools:
     - playwright_cli
     - playwright_mcp
     - playwright
-    - browser_use
     - computer_use
+    - browser_use
   design:
     - figma_mcp
 
 modules:
-  index: docs/_module-index.md
-  root: docs
+  index: .zsk/modules/_module-index.md
+  root: .zsk/modules
 
 automation:
   smoke:
@@ -63,17 +69,20 @@ automation:
   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
+    # Default optimized lane:
+    # - Formal test cases come from module tests.raw_cases or sources.testing, normally snapshots under .zsk/resources/testing.
+    # - Playwright storageState is the preferred way to reuse login/session state without stopping on login pages.
+    # - Computer Use is the preferred visual/current-page observation lane when it is available and authorized.
+    # - Browser Use is optional and runtime-specific; use it only where the agent platform supports it and permissions are available.
+    # - If neither Computer Use nor Browser Use exists, use Playwright MCP/ARIA/CDP snapshots or documented manual evidence as the compatible handoff.
+    # - zsk/agent generation writes test-plan.json, then Playwright CLI/Skills generate executable .spec.ts cases.
+    # - Playwright Test executes/debugs and records evidence. No MCP or bridge fallback is used in optimized mode.
+    # - Use --hybrid explicitly for the legacy bridge lane.
+    defaultMode: optimized
     baseUrl: http://localhost:3000
     command: pnpm dev
-    evidenceDir: .issues/{module}/demo/_evidence
-    scenarioDir: docs/{module}/scenarios
+    evidenceDir: .zsk/evidence/{module}/demo
+    scenarioDir: .zsk/playwright/{module}/specs
     playwright:
       config: playwright.config.ts
       project: chromium
@@ -83,12 +92,13 @@ automation:
       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.
+      # Legacy hybrid-only bridge. Not used by defaultMode: optimized.
+      # Prefer computer_use for visual/system-level understanding when available.
+      # Fall back to playwright_mcp for structured accessibility snapshots, or browser_use only on runtimes that support it.
       decisionTool: playwright_mcp
       executionTool: playwright
-      planFile: .zsk/demo-sessions/{module}/operation-plan.json
-      executionFile: .zsk/demo-sessions/{module}/playwright-execution.json
+      planFile: .zsk/playwright/{module}/execution/operation-plan.json
+      executionFile: .zsk/playwright/{module}/execution/playwright-execution.json
   verify:
     commands:
       - pnpm test:e2e

package/templates/project-init/.zsk/docs/PROJECT-CONFIG.md

@@ -0,0 +1,39 @@
+# Project Config
+
+This file is the human-readable companion to `.zsk/config.yaml`.
+
+## Workspace Layout
+
+`zsk init` owns only the `.zsk/` workspace by default:
+
+| Path | Purpose |
+| --- | --- |
+| `.zsk/config.yaml` | Machine-readable project config and path authority |
+| `.zsk/docs/` | Project-level docs such as this file and `SYSTEM-SPEC.md` |
+| `.zsk/modules/{module}/` | Module `module.yaml`, `proposal.md`, `spec.md`, `design.md`, `tasks.md` |
+| `.zsk/resources/` | Shared source snapshots and manually provided resources |
+| `.zsk/issues/` | Issues and issue indexes created on demand |
+| `.zsk/evidence/` | Runtime evidence, screenshots, traces, logs, and verification artifacts |
+| `.zsk/playwright/{module}/` | Playwright specs, plans, auth state, results, reports, and execution records |
+
+Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are not default write targets. Use explicit export or migration tooling when you need project-root copies.
+
+## Source Priorities
+
+1. `.zsk/config.yaml`
+2. `.zsk/docs/SYSTEM-SPEC.md`
+3. Project resource origins listed under `.zsk/config.yaml#sources`
+4. `.zsk/modules/{module}/module.yaml`
+5. `.zsk/modules/{module}/spec.md`
+6. `.zsk/modules/{module}/design.md`
+7. Runtime evidence under `.zsk/evidence/` and `.zsk/playwright/`
+
+When sources conflict, record the conflict under `.zsk/issues/{module}/` and update the affected module docs with a Documentation Feedback note or an explicit no-update rationale.
+
+## Maintenance Checklist
+
+- Update `.zsk/config.yaml` when paths, tools, or source origins change.
+- Keep project-wide reusable rules in `.zsk/docs/SYSTEM-SPEC.md`.
+- Keep module-specific decisions in `.zsk/modules/{module}/`.
+- Keep shared raw resources under `.zsk/resources/`.
+- Keep runtime outputs out of docs and under `.zsk/evidence/` or `.zsk/playwright/`.

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

@@ -0,0 +1,27 @@
+# System Spec
+
+This document captures project-wide rules that should guide module work.
+
+## Path Boundaries
+
+- `paths.docs` stores project-level docs only.
+- `paths.modules` stores module source-of-truth docs.
+- `paths.resources` stores shared source snapshots and manually provided resources.
+- `paths.issues` stores actionable issue records and indexes created on demand.
+- `paths.evidence` stores runtime evidence and verification artifacts.
+- `paths.playwright` stores Playwright specs, plans, auth state, results, reports, and execution records.
+
+Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are legacy or export surfaces, not default zsk write targets.
+
+## Testing Assets
+
+Original QA, acceptance, release, and manually supplied test cases belong in configured project sources and may be snapshotted under `paths.resources`. Module-derived test plans and Playwright specs belong under `paths.playwright/{module}`.
+
+## Completion Feedback
+
+Every stage document that changes durable behavior should include Documentation Feedback with either:
+
+- a concrete update to project/module docs, or
+- an explicit no-update rationale.
+
+Runtime evidence should be linked from docs, not embedded in docs.

package/templates/project-init/{.issues → .zsk/issues}/README.md

@@ -1,4 +1,4 @@
-# .issues — Local Verification And Bug Evidence
+# .zsk/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.
 
@@ -7,31 +7,32 @@ Every actionable finding from demo, smoke, review, formal test, verify, or accep
 ## Directory Contract
 
 ```text
-.issues/
+.zsk/issues/
 ├── README.md
-├── index.md                           # global module issue totals
+├── _taxonomy.md
+├── index.md                         # global module issue totals
 └── {area-or-module}/
-    ├── index.md                       # module issue index and status table
+    ├── 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
+    │   ├── 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
+    │   └── debug-logs/              # console, test, network, investigation logs
     │       └── index.md
-    ├── demo/                          # optional stage view / evidence bucket
+    ├── 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
+    ├── _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.
+- `.zsk/issues/{module}/index.md` - all issues and statuses for one module.
+- `.zsk/issues/index.md` - module totals across the project.
 
 ## Bug Directory Rules
 
@@ -45,13 +46,13 @@ Use `zsk issue create -m <module-id>` to generate issue folders from the package
 ## 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.
+- After the fix is verified and confirmed by the user/product owner, update the relevant `.zsk/modules/{module}/spec.md`, `.zsk/modules/{module}/design.md`, `.zsk/modules/{module}/tasks.md`, or `.zsk/docs/SYSTEM-SPEC.md` 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 |
+| `.zsk/resources/` | Upstream facts, mirrored snapshots, original external test cases | No |
+| `.zsk/modules/{module}/` | Human-authored module proposal/spec/design/tasks | No |
+| `.zsk/issues/{module}/` | Local defects, verification evidence, debug logs, issue-quality records | Yes |

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

@@ -0,0 +1,35 @@
+# Issue Taxonomy
+
+Managed issue records belong under `.zsk/issues/` or the configured `.zsk/config.yaml#paths.issues` root.
+
+Each module has a module index at `.zsk/issues/{module}/index.md`. The issue root has a global index at `.zsk/issues/index.md` with module totals. `zsk issue create` and `zsk issue update` refresh both indexes.
+
+| Type | Concrete Issue Directory | Prefix |
+| --- | --- | --- |
+| Demo Issue | `.zsk/issues/{module}/{prefix}-0001-slug/` | `DEMO` |
+| Smoke Issue | `.zsk/issues/{module}/{prefix}-0001-slug/` | `SMOKE` |
+| Review Issue | `.zsk/issues/{module}/{prefix}-0001-slug/` | `REV` |
+| Defect | `.zsk/issues/{module}/{prefix}-0001-slug/` | `DEFECT` |
+| Verify Issue | `.zsk/issues/{module}/{prefix}-0001-slug/` | `VER` |
+| Acceptance Issue | `.zsk/issues/{module}/{prefix}-0001-slug/` | `ACC` |
+
+Stage directories such as `.zsk/issues/{module}/demo/index.md` may exist as stage views or evidence buckets. The authoritative status indexes are `.zsk/issues/{module}/index.md` and `.zsk/issues/index.md`.
+
+`.zsk/resources/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/.zsk/modules/.gitkeep

@@ -0,0 +1 @@
+

package/templates/project-init/.zsk/plans/.gitkeep

@@ -0,0 +1 @@
+

package/templates/project-init/.zsk/playwright/.gitkeep

@@ -0,0 +1 @@
+

package/templates/project-init/.zsk/resources/.gitkeep

@@ -0,0 +1 @@
+

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

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