@captain_z/zsk 1.8.4 → 1.8.5

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

@@ -12,40 +12,44 @@ template:
 mode: standard
 scale: auto
 
-# Prepare source capture strategy:
-# - Register source origins under sources.prepare.<lane>.<source-id>.
-# - Prefer stable local exports or provider API/export URLs over bare browser
-#   pages when fidelity matters.
-# - Keep credentials out of config; reference env names under origin.auth or use
-#   .zsk/playwright/.auth storageState created by `zsk prepare auth`.
-# - Run `zsk prepare plan` before acquisition, `zsk prepare auth-check` for
-#   remote/private URLs, then `zsk prepare sync --source=<id> --allow-network`
-#   when acquisition is intentionally allowed.
-# - Design/Figma sources are evidence only. Pair them with
-#   .zsk/raws/prepare/ux/{topic}/interaction-handoff.md for page/module
-#   interaction details before proposal/spec/design consume them. In
-#   module-targeted preproposal runs, {topic} defaults to the module id.
-sources: {}
+# Provider connection profiles. Keep credentials out of this file; reference
+# environment variables or global profiles instead.
+providers: {}
+
+# Resource intents to prepare. Directories under .zsk/raws/** are created only
+# for configured resources that actually produce snapshots.
+resources: []
+
+# Routes map prepared resources into controlled consumption surfaces such as
+# .zsk/modules/<module>/_issues or module source references.
+routes: []
 
-# Example source shape:
-# sources:
-#   prepare:
-#     product:
-#       prd:
-#         type: prd
-#         origin:
-#           kind: local
-#           path: docs/PRD.md
-#         snapshot: .zsk/raws/prepare/product/prd.md
-#     design:
-#       figma-product:
-#         type: design-source
-#         origin:
-#           kind: url
-#           provider: figma
-#           url: https://www.figma.com/file/<file-id>/<name>
-#           exportPath: exports/figma-product.json
-#         snapshot: .zsk/raws/prepare/design/figma-product/source.md
+modules:
+  root: .zsk/modules
+  index: .zsk/modules/index.md
+  registry: []
+
+# Demo login bootstrap. Keep real credentials in local env files; put only env
+# key names here, then run `zsk demo auth -m <module>` once to save storageState.
+# automation:
+#   demo:
+#     auth:
+#       required: true
+#       loginUrl: http://localhost:3000/login
+#       storageState: .zsk/modules/{module}/_playwright/.auth/user.json
+#       envFiles:
+#         - ~/.zshrc
+#       env:
+#         username: DEMO_USERNAME
+#         password: DEMO_PASSWORD
+#       selectors:
+#         username: input[name="username"]
+#         password: input[type="password"]
+#         submit: button[type="submit"]
+
+# Current prepare implementation compatibility tree. New resource preparation
+# should prefer providers/resources/routes above as the stable config surface.
+sources: {}
 
 customize:
   roles: .zsk/roles.yaml

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

@@ -0,0 +1,127 @@
+# Config Schema
+
+`.zsk/config.yaml` is the project control surface. It should describe intent,
+not runtime results.
+
+## Top-Level Blocks
+
+| Block | Purpose |
+| --- | --- |
+| `project` | Stable project identity. |
+| `template` | ZSK template id and version. |
+| `providers` | Connection profiles such as Jira, Confluence, GitHub, GitLab, Figma, or MCP-backed tools. |
+| `resources` | Resource intents to prepare, such as repositories, issues, documents, designs, or command/MCP outputs. |
+| `routes` | Delivery rules from prepared resources to module or shared consumption surfaces. |
+| `modules` | Module discovery settings and optional module registry entries. |
+| `customize` / `staffing` | Pointers to role, workflow, provider, or gate policy files. |
+| `sources` | Compatibility source tree used by the current prepare implementation until the Resource Preparation Module fully owns `resources`. |
+
+## Materialization
+
+The workspace does not pre-create resource directories.
+
+- `resources` entries produce `.zsk/raws/**` snapshots after sync.
+- `routes` entries may update `.zsk/modules/<module>/_issues/**`,
+  `.zsk/modules/<module>/sources.yaml`, or other controlled artifacts.
+- `zsk prepare sync` writes `.zsk/evidence/prepare/sync-report.md`.
+- Missing provider credentials or route conflicts must be visible in the report
+  with a clear state, reason, output path, and next action.
+
+## Resource Output
+
+Default raw output is derived from `type + id`, but a resource may override it
+with `output.rawPath`.
+
+```yaml
+resources:
+  - id: my-bugs
+    type: issues
+    provider: jira
+```
+
+Default output:
+
+```text
+.zsk/raws/issues/my-bugs/
+```
+
+Only configured resources with produced snapshots create directories.
+
+## Credential References
+
+`.zsk/config.yaml` stores env var names only. Put the values in the runtime
+environment, for example by exporting them from `~/.zshrc` before launching the
+shell that runs `zsk`.
+
+```yaml
+providers:
+  jira:
+    type: issues
+    adapter: jira
+    baseUrl: https://jira.example.com
+    auth:
+      env: ACCESS_TOKEN
+  confluence:
+    type: document
+    adapter: confluence
+    baseUrl: https://confluence.example.com
+    auth:
+      usernameEnv: CONFLUENCE_USER
+      passwordEnv: CONFLUENCE_PASSWORD
+```
+
+## Adapter Fallbacks
+
+`source.adapter` is reserved for built-in source adapters: `jira`,
+`confluence`, `gitlab`, and `figma`. Runtime tools such as `playwright_cli`,
+`playwright_mcp`, `browser_use`, and `computer_use` are fallback or observation
+surfaces, not provider adapters.
+
+Use `fallback` when a source may need a runtime-assisted acquisition path:
+
+```yaml
+sources:
+  product:
+    prd:
+      type: prd
+      origin:
+        kind: url
+        url: https://example.com/prd
+      fallback:
+        acquisition: [playwright_cli]
+        observation: [computer_use]
+```
+
+Compatibility note: if an older config puts `playwright_cli` or `computer_use`
+under `adapter`, config check accepts it with a warning and treats it as a
+fallback alias. `computer_use` remains observation-only; prepare sync will not
+silently launch a Computer Use session.
+
+## Demo Auth
+
+Authenticated demos should configure login resources by reference. Keep real
+credentials in local env files such as `~/.zshrc`; put only env key names in
+`.zsk/config.yaml`.
+
+```yaml
+automation:
+  demo:
+    auth:
+      required: true
+      loginUrl: http://localhost:3000/login
+      storageState: .zsk/modules/{module}/_playwright/.auth/user.json
+      envFiles:
+        - ~/.zshrc
+      env:
+        username: DEMO_USERNAME
+        password: DEMO_PASSWORD
+      selectors:
+        username: input[name="username"]
+        password: input[type="password"]
+        submit: button[type="submit"]
+```
+
+`zsk demo auth -m <module>` writes a module-local Playwright login helper that
+loads those env files, fills configured fields when selectors are available,
+then saves reusable `storageState`. Generated demo specs reuse the same
+`storageState` and fail fast if they are redirected back to a login page.

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

@@ -19,9 +19,10 @@ Use this layer to answer three questions before execution:
 | 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/roles.yaml` | Project staffing policy and role pool overrides |
+| `.zsk/docs/` | Project-level docs such as this file, `SYSTEM-SPEC.md`, `CONFIG-SCHEMA.md`, and `SECURITY.md` |
 | `.zsk/modules/{module}/` | Module `module.yaml`, `proposal.md`, `spec.md`, `design.md`, `tasks.md` |
-| `.zsk/raws/` | Immutable raw fact sources and manifest/index files |
+| `.zsk/raws/` | Config-driven Resource Snapshot Library |
 | `.zsk/modules/{module}/_issues/` | Module-private issue records, created on demand |
 | `.zsk/modules/{module}/_evidence/` | Module-private evidence, screenshots, traces, logs, and verification artifacts, created on demand |
 | `.zsk/modules/{module}/_playwright/` | Module-specific Playwright specs, plans, auth state, results, reports, and execution records, created on demand |
@@ -33,8 +34,8 @@ Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are not default write tar
 
 1. `.zsk/config.yaml`
 2. `.zsk/docs/SYSTEM-SPEC.md`
-3. Project resource origins listed under `.zsk/config.yaml#sources`
-4. `.zsk/raws/manifest.json` and `.zsk/raws/index.md`
+3. Project provider/resource/route intent in `.zsk/config.yaml`
+4. Materialized resource snapshots under `.zsk/raws/**`
 5. `.zsk/modules/{module}/module.yaml`
 6. `.zsk/modules/{module}/spec.md`
 7. `.zsk/modules/{module}/design.md`
@@ -53,21 +54,23 @@ Every module stage document is a handoff contract:
 
 If a document cannot answer its stage questions, stop and record the missing source, decision, blocker, or issue instead of filling the template.
 
-## Preproposal Raw Artifacts
+## Resource Snapshot Contract
 
-`preproposal` may create living raw artifacts under `.zsk/raws/prepare/**` when a
-brief request lacks reviewed product, roadmap, UX, design-source, or source
-readiness material.
+`prepare sync` materializes configured resources under `.zsk/raws/**`; init does
+not create resource subdirectories or empty indexes.
 
-- Product direction and roadmap seeds live under `.zsk/raws/prepare/product/**`.
-- UX readiness and interaction handoff live under `.zsk/raws/prepare/ux/**`.
-- Design-source needs and provider source maps live under `.zsk/raws/prepare/design/**`.
-- Checkpoint review evidence lives under `.zsk/evidence/preproposal/{run}/`.
+Default resource output is derived from `type + id`, for example:
 
-Module `proposal.md`, `spec.md`, `design.md`, and `tasks.md` should reference
-reviewed revisions from these raw artifacts instead of copying their full
-contents. A later interaction change updates the raw artifact first, then routes
-impact to the affected module stage.
+| Resource | Default Snapshot Path |
+| --- | --- |
+| `type: repository`, `id: core-api` | `.zsk/raws/repositories/core-api/` |
+| `type: issues`, `id: my-bugs` | `.zsk/raws/issues/my-bugs/` |
+| `type: document`, `id: role-prd` | `.zsk/raws/document/role-prd/` |
+
+Each snapshot directory should contain a human-readable `snapshot.md`, redacted
+`metadata.yaml`, ignored `source.json`, and ignored `assets/` when raw payloads
+or exports exist. Directory-style resources such as git submodules may also
+contain a `repository/` checkout.
 
 ## Prepare Capture Strategy
 
@@ -76,16 +79,18 @@ not a requirement author, interaction designer, code designer, or task planner.
 
 Use this order for source capture:
 
-1. Register stable origins in `.zsk/config.yaml#sources`.
+1. Register provider profiles, resource intents, and routes in `.zsk/config.yaml`.
 2. Run `zsk prepare plan` to classify ready, stale, blocked, and ambiguous
    sources before writing snapshots.
 3. Run `zsk prepare auth-check` for private URLs so credentials are verified
-   without writing source content.
+   without writing source content. The command reads exported env vars such as
+   `ACCESS_TOKEN`, `CONFLUENCE_USER`, and `CONFLUENCE_PASSWORD`; it never reads
+   `~/.zshrc` directly or prints secret values.
 4. Run `zsk prepare sync` for local/provider/export sources, adding
    `--allow-network`, `--browser`, and `--auth-state` only when that acquisition
    is intentional.
-5. Review `.zsk/evidence/prepare/{run}/adapter-results/` and
-   `downstream-impact.md` before downstream stages consume the snapshot.
+5. Review `.zsk/evidence/prepare/sync-report.md` before downstream stages
+   consume the snapshot.
 
 For Figma or similar design tools, prefer provider API/export payloads, raw node
 exports, screenshots/assets, and local design-source maps over a bare page URL.
@@ -98,7 +103,7 @@ narrower page/frame split is justified in the raw artifact.
 
 ## Maintenance Checklist
 
-- Update `.zsk/config.yaml` when paths, tools, or source origins change.
+- Update `.zsk/config.yaml` when providers, resources, routes, modules, paths, or tools change.
 - Keep project-wide reusable rules in `.zsk/docs/SYSTEM-SPEC.md`.
 - Keep module-specific decisions in `.zsk/modules/{module}/`.
 - Keep shared raw source facts under `.zsk/raws/`.

package/templates/project-init/.zsk/docs/README.md

@@ -0,0 +1,10 @@
+# ZSK Docs
+
+Project-wide governance documents live here.
+
+- `PROJECT-CONFIG.md` explains workspace layout and source authority.
+- `SYSTEM-SPEC.md` records project-wide operating rules.
+- `CONFIG-SCHEMA.md` explains the local config shape used by this project.
+- `SECURITY.md` records raw payload, credential, and commit policy.
+
+Keep module-specific proposal/spec/design/tasks under `.zsk/modules/<module>/`.

package/templates/project-init/.zsk/docs/SECURITY.md

@@ -0,0 +1,34 @@
+# Security
+
+`prepare sync` can touch private provider data. Keep security rules visible in
+the project, not only in implementation.
+
+## Credentials
+
+- Do not write tokens, cookies, passwords, or authorization headers in
+  `.zsk/config.yaml`.
+- Reference credentials by environment variable or global profile.
+- Shell startup files such as `~/.zshrc` may export those variables, but ZSK
+  only reads the already exported `process.env` values. It does not parse shell
+  startup files or persist their values.
+- For Jira, use a token env such as `ACCESS_TOKEN`.
+- For Confluence instances that do not support access tokens, use Basic auth
+  env names such as `CONFLUENCE_USER` and `CONFLUENCE_PASSWORD`.
+- Readiness reports may say that an env var or profile is present, but must not
+  print secret values.
+
+## Raw Payloads
+
+- `source.json` is ignored by default.
+- `assets/` is ignored by default.
+- `snapshot.md`, `metadata.yaml`, and `sync-report.md` must be redacted before
+  write.
+- `output.commitRaw: true` is required before raw payloads become commit
+  candidates.
+
+## Redaction
+
+Provider payloads must pass through a sanitizer before writing `source.json`,
+`snapshot.md`, `metadata.yaml`, or reports. At minimum, redact credential-shaped
+fields such as `token`, `cookie`, `authorization`, `password`, and provider
+session headers.

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

@@ -6,7 +6,7 @@ This document captures project-wide rules that should guide module work.
 
 The `.zsk/` workspace is this project's Halcyon layer. It keeps AI execution grounded by separating:
 
-- raw facts under `paths.raws`;
+- config-declared resource snapshots under `paths.raws`;
 - project-wide rules under `paths.docs`;
 - module-owned stage contracts under `paths.modules`;
 - runtime evidence under module `_evidence` or shared `paths.evidence`;
@@ -19,17 +19,17 @@ Agents must use the smallest sufficient lane: read local sources first, run dete
 
 - `paths.docs` stores project-level docs only.
 - `paths.modules` stores module source-of-truth docs.
-- `paths.raws` stores immutable shared source snapshots and manually provided fact sources.
-- `preproposal` may add candidate/generated product, roadmap, UX, and design-source readiness resources under `paths.raws` only when provenance, assumptions, review checkpoint status, and blockers are explicit. When a target module is specified, raw topics default to the module id and must name any narrower page/frame split rationale.
+- `paths.raws` stores shared Resource Snapshots produced from configured resources.
+- Raw resource directories are not pre-created. A child directory under `paths.raws` must correspond to a configured resource output and a real sync result.
 - Module `_issues` stores module-specific actionable issue records; `paths.issues` is created on demand only for shared/global indexes or cross-module issues.
 - Module `_evidence` stores module-specific runtime evidence and verification artifacts; `paths.evidence` is created on demand only for shared/global evidence.
 - Module `_playwright` stores module-specific Playwright specs, plans, auth state, results, reports, and execution records; `paths.playwright` is created on demand only for shared Playwright assets.
 
-Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are legacy or export surfaces, not default zsk write targets.
+Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are 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.raws`, normally `.zsk/raws/qa/testing`. Module-derived test plans and Playwright specs belong under module `_playwright` unless they are intentionally shared under `paths.playwright`.
+Original QA, acceptance, release, and manually supplied test cases belong in configured resources and may be snapshotted under `paths.raws`. Module-derived test plans and Playwright specs belong under module `_playwright` unless they are intentionally shared under `paths.playwright`.
 
 ## Completion Feedback
 
@@ -44,9 +44,16 @@ Runtime evidence should be linked from docs, not embedded in docs.
 
 ZSK stage documents are decision artifacts. They are complete only when the next stage can act without hidden chat context.
 
+Every stage document must include `Output Quality Check` near the top, after the
+title/summary and before the body. The block is a compact quality status, not a
+log. It uses stable fields in order: `status`, `owner`, `source_basis`,
+`blocking_items`, and `next_action`; optional fields are `waiver` and
+`updated_at`. Valid statuses are `PASS`, `NEEDS_CLARIFICATION`,
+`NEEDS_REPAIR`, `BLOCKED`, and `WAIVED`.
+
 | Stage | Document Mode | Must Prove |
 | --- | --- | --- |
-| `prepare` | Evidence report | Source origins, freshness, conflicts, and raw snapshot paths are known before planning. |
+| `prepare` | Evidence report | Provider readiness, resource freshness, route results, conflicts, and raw snapshot paths are known before planning. |
 | `preproposal` | Decision brief | Product direction, MVP/phase split, UX/design readiness, assumptions, risks, and readiness review are complete before proposal when no reviewed source pack exists. |
 | `proposal` | Decision brief | Problem, user/business outcome, scope, non-goals, risks, and success criteria are explicit. |
 | `spec` | Behavior contract | FR/NFR, scenarios, edge cases, and acceptance criteria are observable and source-linked. |
@@ -61,16 +68,21 @@ ZSK stage documents are decision artifacts. They are complete only when the next
 Each stage document must separate facts, decisions, assumptions, open questions,
 evidence, and next action. Do not leave template filler, untraceable "best
 practice" claims, vague tasks, or unresolved contradictions in a stage artifact.
-Each stage challenge must also align terminology against project context,
+Each `Output Quality Check` must also align terminology against project context,
 configured raw sources, existing artifact IDs, and implementation names when
 implementation-facing work is touched. Conflicting, overloaded, stale, or
 translated terms must be recorded as a blocker or repaired by the owning stage.
 
+When `Output Quality Check` is `NEEDS_CLARIFICATION`, the owning stage uses
+Clarification Prelude: ask one question, show a separate recommendation, refine
+one `待写入确认表达：`, write the accepted expression to `CLAR`, update the stage
+artifact and any reusable `CONTEXT.md` term, then stop after minimal validation.
+
 ## Lifecycle Ownership
 
 | Artifact / Decision | Owning Stage | Notes |
 | --- | --- | --- |
-| Source origins, acquisition plan, auth readiness, raw snapshots, manifest/index, adapter results, downstream impact evidence | `prepare` | Capture-only stage. It may classify sources as ready/stale/blocked/gap, but it does not invent requirements, interactions, architecture, or tasks. |
+| Provider profiles, resource intents, acquisition plan, auth readiness, raw snapshots, route results, sync report, and downstream impact evidence | `prepare` | Capture-only stage. It may classify resources as ready/stale/blocked/conflict/gap, but it does not invent requirements, interactions, architecture, or tasks. |
 | Product direction, roadmap, UX readiness, interaction handoff, design-source map | `preproposal` | Living raw artifacts. They may change after initial review, but each revision records source, status, impact, and affected downstream stages. |
 | Scope, non-goals, success criteria, high-level risks | `proposal` | Freezes the smallest useful problem/scope boundary before behavior is specified. |
 | FR, NFR, acceptance criteria, scenarios, edge cases | `spec` | Creates observable behavior contracts from proposal/source evidence. Missing quality targets remain `未指定` instead of invented. |

package/templates/project-init/.zsk/evidence/README.md

@@ -0,0 +1,15 @@
+# Shared Evidence
+
+Use this directory for shared evidence and reports that are not owned by a single
+module.
+
+`zsk prepare sync` writes human-readable preparation reports here, such as:
+
+```text
+.zsk/evidence/prepare/sync-report.md
+.zsk/evidence/prepare/blocked-resources.md
+```
+
+Runtime state, temporary files, traces, videos, and raw provider payloads must
+stay out of committed evidence unless a workflow explicitly promotes a redacted
+artifact.

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

@@ -0,0 +1,10 @@
+# Global Issues
+
+Use this directory for global or cross-module issues:
+
+- missing provider credentials;
+- blocked resource preparation;
+- route conflicts across multiple modules;
+- architecture or governance blockers that are not owned by one module.
+
+Module-specific work belongs in `.zsk/modules/<module>/_issues/**`.

package/templates/project-init/.zsk/modules/README.md

@@ -0,0 +1,19 @@
+# Modules
+
+Modules are explicit business or delivery surfaces. `zsk init` does not create a
+fake default module.
+
+Create a module with:
+
+```bash
+zsk module init -m <module-id> --name "<Module Name>"
+```
+
+Module-local generated/manual artifacts use controlled underscore directories:
+
+- `_issues/` for module task cards and routed external issues.
+- `_evidence/` for module verification evidence.
+- `_playwright/` for module UI automation plans, specs, auth state, results, and
+  reports.
+
+These directories are created only when a real module and artifact exist.

package/templates/project-init/.zsk/modules/index.md

@@ -1,7 +1,11 @@
-# Module Index
+# Modules
 
-Generated and refreshed as modules are added.
+No modules are declared yet.
 
-| Module | Status | Notes |
-| --- | --- | --- |
-|  |  |  |
+Add modules in `.zsk/config.yaml` or run:
+
+```bash
+zsk module init -m <module-id> --name "<Module Name>"
+```
+
+This file is the module registry view. It is not a placeholder module.

package/templates/project-init/.zsk/raws/README.md

@@ -0,0 +1,34 @@
+# Raw Resource Snapshots
+
+`.zsk/raws` is the Resource Snapshot Library.
+
+This directory is config-driven. Do not create empty resource type directories
+because an adapter exists. A child directory is created only when:
+
+1. `.zsk/config.yaml` declares a resource, and
+2. `zsk prepare sync` produces a snapshot for that resource.
+
+## Snapshot Contract
+
+```text
+.zsk/raws/<resource-kind>/<resource-key>/
+  snapshot.md
+  metadata.yaml
+  source.json
+  assets/
+```
+
+`snapshot.md` is the human-readable summary. `metadata.yaml` stores provenance,
+freshness, hashes, provider readiness, and sync state. `source.json` and
+`assets/` hold raw or semi-raw provider payloads and are ignored by default.
+
+Directory-style resources, such as git submodules, may use:
+
+```text
+.zsk/raws/repositories/<resource-key>/
+  repository/
+  snapshot.md
+  metadata.yaml
+```
+
+Generated raw indexes are created by sync only after real snapshots exist.