@captain_z/zsk 1.7.0 → 1.8.2

package/schemas/zsk-config.schema.json

@@ -2,10 +2,10 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://unpkg.com/@captain_z/zsk/schemas/zsk-config.schema.json",
   "title": "ZSK Project Config",
-  "description": "Project-level configuration for ZSK resource origins, workspace paths, tools, and module index locations.",
+  "description": "Project-level configuration for ZSK raw source origins, template defaults, workspace paths, tools, and module index locations.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["project", "paths", "sources", "tools", "modules"],
+  "required": ["project", "sources"],
   "properties": {
     "project": {
       "description": "Project identity used in generated docs and resource manifests.",
@@ -29,15 +29,91 @@
       }
     },
     "layoutVersion": {
-      "description": "Workspace layout version. Version 2 keeps all zsk-managed outputs under .zsk/ by default.",
+      "description": "Workspace layout version. Version 2 keeps all zsk-managed outputs under .zsk/ by default and prefers paths.raws for fact sources.",
       "type": "integer",
       "minimum": 2
     },
+    "template": {
+      "description": "Template preset used to resolve omitted defaults. The default init template is founder-os.",
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id"],
+          "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1
+            },
+            "version": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "metadata": {
+              "$ref": "#/$defs/metadata"
+            }
+          }
+        }
+      ]
+    },
+    "mode": {
+      "description": "Template-specific operating mode. Keep as a string so projects can define their own modes without schema churn.",
+      "type": "string",
+      "minLength": 1
+    },
+    "scale": {
+      "description": "Template-specific project/team scale. Keep as a string so projects can define their own scales without schema churn.",
+      "type": "string",
+      "minLength": 1
+    },
+    "workflow": {
+      "description": "Optional explicit workflow profile selection. Detailed workflow rules can be ejected into .zsk/workflow.yaml.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "profile": {
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "gates": {
+      "description": "Optional project-level quality gate policy. Omit to use template defaults; configure only when the project needs custom thresholds.",
+      "$ref": "#/$defs/gatesConfig"
+    },
+    "customize": {
+      "description": "Compact pointers to ejected project-local customization files.",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "roles": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "workflow": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "providers": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "gates": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
     "paths": {
       "description": "Top-level project knowledge workspace paths.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["docs", "modules", "resources", "issues", "evidence", "playwright"],
       "properties": {
         "docs": {
           "$ref": "#/$defs/pathRef"
@@ -46,10 +122,11 @@
           "$ref": "#/$defs/pathRef"
         },
         "resources": {
+          "description": "Deprecated compatibility alias for paths.raws.",
           "$ref": "#/$defs/pathRef"
         },
         "raws": {
-          "description": "Legacy resource root accepted only for compatibility with older workspaces.",
+          "description": "Preferred immutable raw fact-source root.",
           "$ref": "#/$defs/pathRef"
         },
         "issues": {
@@ -70,10 +147,10 @@
       }
     },
     "sources": {
-      "description": "Project-level resource origins. May be empty after init and filled by AI or zsk config setup.",
+      "description": "Project-level raw source origins. Keep this concise: configure source roots or provider entry points, then let prepare materialize snapshots and indexes under paths.raws.",
       "type": "object",
       "additionalProperties": {
-        "$ref": "#/$defs/sourceRef"
+        "$ref": "#/$defs/sourceTree"
       },
       "properties": {
         "metadata": {
@@ -85,7 +162,6 @@
       "description": "Preferred AI/tool capabilities for project-level workflows.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["runtime_ui", "design"],
       "properties": {
         "runtime_ui": {
           "description": "Preferred tools for runtime UI verification.",
@@ -96,7 +172,7 @@
           "uniqueItems": true
         },
         "design": {
-          "description": "Preferred tools for design and Figma resource capture.",
+          "description": "Preferred tools for design source and asset capture.",
           "type": "array",
           "items": {
             "$ref": "#/$defs/toolName"
@@ -112,7 +188,6 @@
       "description": "Module discovery and module config locations.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["index", "root"],
       "properties": {
         "index": {
           "$ref": "#/$defs/pathRef"
@@ -224,8 +299,12 @@
         }
       }
     },
+    "staffing": {
+      "description": "Project-local role pool used by dispatch/staffing. Keep config.yaml concise by pointing rolePool at a .zsk YAML file, or define small inline overrides under roles.",
+      "$ref": "#/$defs/staffingConfig"
+    },
     "sync": {
-      "description": "Optional deterministic or AI-assisted raw resource sync configuration.",
+      "description": "Optional deterministic or AI-assisted raw source sync configuration.",
       "type": "object",
       "additionalProperties": {
         "$ref": "#/$defs/syncRef"
@@ -242,9 +321,9 @@
       "minLength": 1
     },
     "toolName": {
-      "description": "Known tool or capability name.",
+      "description": "Project-specific tool or capability name. ZSK does not restrict this to a fixed platform list.",
       "type": "string",
-      "enum": ["computer_use", "browser_use", "playwright", "playwright_cli", "playwright_mcp", "figma_mcp", "script", "manual", "skill"]
+      "minLength": 1
     },
     "commandStage": {
       "description": "Automation command list for a workflow stage.",
@@ -268,12 +347,12 @@
       }
     },
     "sourceType": {
-      "description": "Resource role.",
+      "description": "Raw source role. Common examples include srs, prd, design, api_contract, backend_repo, test_case, design_asset, vendor_doc, and manual, but projects may define their own roles.",
       "type": "string",
-      "enum": ["srs", "prd", "design", "api_contract", "backend_repo", "test_case", "design_asset", "vendor_doc", "manual"]
+      "minLength": 1
     },
     "sourceRef": {
-      "description": "Resource source reference.",
+      "description": "Raw source reference. `snapshot` is optional; when omitted, ZSK derives paths.raws/<source-path>/source.md and maintains index.md files in the raw source directories.",
       "type": "object",
       "additionalProperties": false,
       "required": ["type", "origin"],
@@ -285,6 +364,7 @@
           "$ref": "#/$defs/originRef"
         },
         "snapshot": {
+          "description": "Optional explicit materialized snapshot path. Omit this for entry-point sources such as a Figma file, Confluence space, repository, or issue query.",
           "$ref": "#/$defs/pathRef"
         },
         "metadata": {
@@ -292,75 +372,64 @@
         }
       }
     },
-    "originRef": {
-      "description": "Online or local source origin.",
+    "sourceTree": {
+      "description": "A raw source reference or a grouping object whose keys mirror .zsk/raws/prepare responsibility lanes.",
       "oneOf": [
         {
-          "$ref": "#/$defs/urlOrigin"
-        },
-        {
-          "$ref": "#/$defs/localOrigin"
-        },
-        {
-          "$ref": "#/$defs/gitOrigin"
-        },
-        {
-          "$ref": "#/$defs/figmaOrigin"
+          "$ref": "#/$defs/sourceRef"
         },
         {
-          "$ref": "#/$defs/modaoOrigin"
-        },
-        {
-          "$ref": "#/$defs/openapiOrigin"
-        },
-        {
-          "$ref": "#/$defs/manualOrigin"
+          "$ref": "#/$defs/sourceGroup"
         }
       ]
     },
-    "urlOrigin": {
+    "sourceGroup": {
+      "description": "Nested source grouping object.",
       "type": "object",
-      "additionalProperties": false,
-      "required": ["kind", "url"],
+      "additionalProperties": {
+        "$ref": "#/$defs/sourceTree"
+      },
       "properties": {
-        "kind": {
-          "type": "string",
-          "const": "url"
-        },
-        "url": {
-          "type": "string",
-          "minLength": 1
-        },
         "metadata": {
           "$ref": "#/$defs/metadata"
         }
       }
     },
-    "localOrigin": {
+    "originRef": {
+      "description": "Generic online, local, or provider-managed source origin. `kind` names the acquisition mode, while fields such as provider, path, url, repository, query, jql, id, ref, and note are intentionally extensible.",
       "type": "object",
-      "additionalProperties": false,
-      "required": ["kind", "path"],
+      "additionalProperties": true,
+      "required": ["kind"],
       "properties": {
         "kind": {
           "type": "string",
-          "const": "local"
+          "minLength": 1
+        },
+        "provider": {
+          "type": "string",
+          "minLength": 1
         },
         "path": {
           "$ref": "#/$defs/pathRef"
         },
-        "metadata": {
-          "$ref": "#/$defs/metadata"
-        }
-      }
-    },
-    "gitOrigin": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["kind", "repository"],
-      "properties": {
-        "kind": {
+        "csvPath": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "csv": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "exportPath": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "assetPath": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "filePath": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "url": {
           "type": "string",
-          "const": "git"
+          "minLength": 1
         },
         "repository": {
           "type": "string",
@@ -370,32 +439,19 @@
           "type": "string",
           "minLength": 1
         },
-        "path": {
-          "$ref": "#/$defs/pathRef"
-        },
-        "metadata": {
-          "$ref": "#/$defs/metadata"
-        }
-      }
-    },
-    "figmaOrigin": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["kind", "url"],
-      "properties": {
-        "kind": {
+        "query": {
           "type": "string",
-          "const": "figma"
+          "minLength": 1
         },
-        "url": {
+        "jql": {
           "type": "string",
           "minLength": 1
         },
-        "file_key": {
+        "id": {
           "type": "string",
           "minLength": 1
         },
-        "node_id": {
+        "note": {
           "type": "string",
           "minLength": 1
         },
@@ -404,63 +460,145 @@
         }
       }
     },
-    "modaoOrigin": {
+    "staffingConfig": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["kind", "url"],
       "properties": {
-        "kind": {
-          "type": "string",
-          "const": "modao"
+        "rolePool": {
+          "$ref": "#/$defs/pathRef"
         },
-        "url": {
-          "type": "string",
-          "minLength": 1
+        "timeoutPolicy": {
+          "$ref": "#/$defs/staffingTimeoutPolicy"
+        },
+        "roles": {
+          "$ref": "#/$defs/rolePoolRoles"
         },
         "metadata": {
           "$ref": "#/$defs/metadata"
         }
       }
     },
-    "openapiOrigin": {
+    "gatesConfig": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["kind"],
       "properties": {
-        "kind": {
-          "type": "string",
-          "const": "openapi"
+        "defaultThreshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 10
         },
-        "url": {
-          "type": "string",
-          "minLength": 1
-        },
-        "path": {
-          "$ref": "#/$defs/pathRef"
+        "thresholds": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 10
+          }
         },
         "metadata": {
           "$ref": "#/$defs/metadata"
         }
-      },
-      "anyOf": [
-        {
-          "required": ["url"]
+      }
+    },
+    "staffingTimeoutPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "heartbeatIntervalMs": {
+          "type": "integer",
+          "minimum": 1000
         },
-        {
-          "required": ["path"]
+        "staleAfterMs": {
+          "type": "integer",
+          "minimum": 1000
+        },
+        "maxAttempts": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "onTimeout": {
+          "type": "string",
+          "enum": ["fallback-to-leader-sequential"]
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
         }
-      ]
+      }
     },
-    "manualOrigin": {
+    "rolePoolRoles": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/rolePoolRole"
+      }
+    },
+    "rolePoolRole": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["kind", "note"],
       "properties": {
-        "kind": {
+        "subagentType": {
           "type": "string",
-          "const": "manual"
+          "minLength": 1
         },
-        "note": {
+        "stages": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "lanes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "remoteSources": {
+          "type": "boolean"
+        },
+        "activation": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "owns": {
+          "$ref": "#/$defs/stringList"
+        },
+        "doesNotOwn": {
+          "$ref": "#/$defs/stringList"
+        },
+        "inputs": {
+          "$ref": "#/$defs/stringList"
+        },
+        "writeScope": {
+          "$ref": "#/$defs/stringList"
+        },
+        "outputs": {
+          "$ref": "#/$defs/stringList"
+        },
+        "evidenceRequired": {
+          "$ref": "#/$defs/stringList"
+        },
+        "forbiddenDecisions": {
+          "$ref": "#/$defs/stringList"
+        },
+        "stopCondition": {
           "type": "string",
           "minLength": 1
         },
@@ -469,6 +607,14 @@
         }
       }
     },
+    "stringList": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
     "scriptSync": {
       "description": "Resource produced by a deterministic script command.",
       "type": "object",

package/templates/issue/default/issue.md

@@ -4,6 +4,10 @@
 
 __ISSUE_TYPE__
 
+## 作用域
+
+__ISSUE_SCOPE__
+
 ## 问题级别
 
 __SEVERITY__
@@ -66,7 +70,7 @@ __SEVERITY__
   - [ ] `.zsk/modules/{module}/design.md`
   - [ ] `.zsk/modules/{module}/tasks.md`
   - [ ] `.zsk/docs/SYSTEM-SPEC.md`
-  - [ ] `.zsk/resources`
+  - [ ] `.zsk/raws`
 - 更新内容或 no-update rationale：
 - 反哺时机：修复通过 verify 且经用户/产品确认后执行
 

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

@@ -1,5 +1,88 @@
 # __MODULE_NAME__ Design
 
+## Project Rules Gate
+
+| Rule Source | Rule / Constraint | Design Impact | Status |
+| --- | --- | --- | --- |
+| `.zsk/docs/PROJECT-CONFIG.md` |  |  | TODO |
+| `.zsk/docs/SYSTEM-SPEC.md` |  |  | TODO |
+
+Do not approve this design until project-level path boundaries, evidence routing, issue routing, source priority, and stage-document rules are mapped to implementation surfaces or recorded as blockers.
+
+## Implementation Map
+
+| Requirement / AC | Surface | Files / Modules | Interface / State / Data Flow | Risk |
+| --- | --- | --- | --- | --- |
+| FR-001 / AC-001 |  |  |  |  |
+
+## Design Views
+
+Use Mermaid or linked configured design-source evidence to make boundaries, flows, states, and dependencies reviewable. Keep a view N/A only with rationale.
+
+### Context / Container View
+
+```mermaid
+flowchart LR
+    User[User / Actor] --> App[Module / Application]
+    App --> API[API / Service]
+    API --> Data[(Data Store)]
+```
+
+Clarifies:
+- Spec / AC:
+- Decision / risk / verification path:
+
+### Sequence / Flow View
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant UI as UI
+    participant API as API
+    User->>UI: Trigger scenario
+    UI->>API: Request
+    API-->>UI: Response
+    UI-->>User: Observable result
+```
+
+Clarifies:
+- Spec / AC:
+- Decision / risk / verification path:
+
+### State View
+
+```mermaid
+stateDiagram-v2
+    [*] --> Loading
+    Loading --> Success
+    Loading --> Error
+    Error --> Retry
+    Retry --> Loading
+```
+
+Clarifies:
+- Spec / AC:
+- Decision / risk / verification path:
+
+### Data Flow / UX Flow View
+
+N/A rationale or diagram:
+
+## Decisions
+
+| Decision | Alternatives Rejected | Rationale / Evidence | Rollback / Migration Note |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+## States And Failure Modes
+
+| State | User/System Observable Behavior | Test / Demo Evidence |
+| --- | --- | --- |
+| loading |  |  |
+| empty |  |  |
+| error |  |  |
+| permission |  |  |
+
 ## Playwright Locator And State Strategy
 
 | Scenario | Page / Route | Preferred Locator Strategy | State Coverage | API / Mock | Auth / Storage | Evidence |
@@ -11,6 +94,16 @@ 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.
+- Keep generated docs, issues, evidence, and Playwright assets inside the `.zsk` paths required by `PROJECT-CONFIG.md` and `SYSTEM-SPEC.md`.
+- Route unclear behavior back to spec instead of redesigning requirements here.
+
+## Best-Practice Checklist
+
+- [ ] Behavior maps to files/modules/interfaces/state/data flow without changing approved requirements.
+- [ ] Design includes useful diagrams/charts for context, flow, state, data, dependency, or UX where complexity requires them; otherwise N/A rationale is explicit.
+- [ ] Security/auth/privacy, migration/rollback, performance, and rollout risks are recorded when touched.
+- [ ] UI work includes accessible locator/state strategy and Playwright evidence needs.
+- [ ] Project military rules from `PROJECT-CONFIG.md` and `SYSTEM-SPEC.md` are enforced or blocked.
 
 ## Documentation Feedback