@captain_z/zsk 1.8.1 → 1.8.3

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 raw source 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.",
@@ -33,19 +33,87 @@
       "type": "integer",
       "minimum": 2
     },
-    "paths": {
-      "description": "Top-level project knowledge workspace paths.",
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["docs", "modules", "issues", "evidence", "playwright"],
-      "anyOf": [
+    "template": {
+      "description": "Template preset used to resolve omitted defaults. The default init template is founder-os.",
+      "oneOf": [
         {
-          "required": ["raws"]
+          "type": "string",
+          "minLength": 1
         },
         {
-          "required": ["resources"]
+          "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,
       "properties": {
         "docs": {
           "$ref": "#/$defs/pathRef"
@@ -70,16 +138,19 @@
         "playwright": {
           "$ref": "#/$defs/pathRef"
         },
+        "plans": {
+          "$ref": "#/$defs/pathRef"
+        },
         "metadata": {
           "$ref": "#/$defs/metadata"
         }
       }
     },
     "sources": {
-      "description": "Project-level raw source 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": {
@@ -91,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.",
@@ -118,7 +188,6 @@
       "description": "Module discovery and module config locations.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["index", "root"],
       "properties": {
         "index": {
           "$ref": "#/$defs/pathRef"
@@ -230,6 +299,10 @@
         }
       }
     },
+    "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 source sync configuration.",
       "type": "object",
@@ -248,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.",
@@ -274,12 +347,12 @@
       }
     },
     "sourceType": {
-      "description": "Raw source 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": "Raw 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"],
@@ -291,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": {
@@ -298,84 +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/sourceRef"
         },
         {
-          "$ref": "#/$defs/localOrigin"
-        },
-        {
-          "$ref": "#/$defs/gitOrigin"
-        },
-        {
-          "$ref": "#/$defs/figmaOrigin"
-        },
-        {
-          "$ref": "#/$defs/modaoOrigin"
-        },
-        {
-          "$ref": "#/$defs/designOrigin"
-        },
-        {
-          "$ref": "#/$defs/openapiOrigin"
-        },
-        {
-          "$ref": "#/$defs/jiraOrigin"
-        },
-        {
-          "$ref": "#/$defs/srsOrigin"
-        },
-        {
-          "$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",
-          "enum": ["git", "git-submodule"]
+          "minLength": 1
         },
         "repository": {
           "type": "string",
@@ -385,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
         },
@@ -419,157 +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"
         }
       }
     },
-    "designOrigin": {
+    "gatesConfig": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["kind", "provider"],
       "properties": {
-        "kind": {
-          "type": "string",
-          "const": "design"
-        },
-        "provider": {
-          "type": "string",
-          "minLength": 1
-        },
-        "url": {
-          "type": "string",
-          "minLength": 1
-        },
-        "path": {
-          "$ref": "#/$defs/pathRef"
+        "defaultThreshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 10
         },
-        "id": {
-          "type": "string",
-          "minLength": 1
+        "thresholds": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 10
+          }
         },
         "metadata": {
           "$ref": "#/$defs/metadata"
         }
       }
     },
-    "openapiOrigin": {
+    "staffingTimeoutPolicy": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["kind"],
       "properties": {
-        "kind": {
-          "type": "string",
-          "const": "openapi"
+        "heartbeatIntervalMs": {
+          "type": "integer",
+          "minimum": 1000
         },
-        "url": {
-          "type": "string",
-          "minLength": 1
+        "staleAfterMs": {
+          "type": "integer",
+          "minimum": 1000
         },
-        "path": {
-          "$ref": "#/$defs/pathRef"
+        "maxAttempts": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "onTimeout": {
+          "type": "string",
+          "enum": ["fallback-to-leader-sequential"]
         },
         "metadata": {
           "$ref": "#/$defs/metadata"
         }
-      },
-      "anyOf": [
-        {
-          "required": ["url"]
-        },
-        {
-          "required": ["path"]
-        }
-      ]
+      }
+    },
+    "rolePoolRoles": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/rolePoolRole"
+      }
     },
-    "jiraOrigin": {
+    "rolePoolRole": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["kind"],
       "properties": {
-        "kind": {
-          "type": "string",
-          "const": "jira"
-        },
-        "url": {
+        "subagentType": {
           "type": "string",
           "minLength": 1
         },
-        "path": {
-          "$ref": "#/$defs/pathRef"
+        "stages": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
         },
-        "jql": {
-          "type": "string",
-          "minLength": 1
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
         },
-        "metadata": {
-          "$ref": "#/$defs/metadata"
-        }
-      },
-      "anyOf": [
-        {
-          "required": ["url"]
+        "lanes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
         },
-        {
-          "required": ["path"]
+        "required": {
+          "type": "boolean"
         },
-        {
-          "required": ["jql"]
-        }
-      ]
-    },
-    "srsOrigin": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["kind"],
-      "properties": {
-        "kind": {
+        "remoteSources": {
+          "type": "boolean"
+        },
+        "activation": {
           "type": "string",
-          "const": "srs"
+          "minLength": 1
         },
-        "url": {
+        "reason": {
           "type": "string",
           "minLength": 1
         },
-        "path": {
-          "$ref": "#/$defs/pathRef"
+        "owns": {
+          "$ref": "#/$defs/stringList"
         },
-        "metadata": {
-          "$ref": "#/$defs/metadata"
-        }
-      },
-      "anyOf": [
-        {
-          "required": ["url"]
+        "doesNotOwn": {
+          "$ref": "#/$defs/stringList"
         },
-        {
-          "required": ["path"]
-        }
-      ]
-    },
-    "manualOrigin": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["kind", "note"],
-      "properties": {
-        "kind": {
-          "type": "string",
-          "const": "manual"
+        "inputs": {
+          "$ref": "#/$defs/stringList"
         },
-        "note": {
+        "writeScope": {
+          "$ref": "#/$defs/stringList"
+        },
+        "outputs": {
+          "$ref": "#/$defs/stringList"
+        },
+        "evidenceRequired": {
+          "$ref": "#/$defs/stringList"
+        },
+        "forbiddenDecisions": {
+          "$ref": "#/$defs/stringList"
+        },
+        "stopCondition": {
           "type": "string",
           "minLength": 1
         },
@@ -578,6 +607,14 @@
         }
       }
     },
+    "stringList": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
     "scriptSync": {
       "description": "Resource produced by a deterministic script command.",
       "type": "object",