@captain_z/zsk 1.8.6 → 1.8.7

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

@@ -13,10 +13,14 @@ declares a durable entry source and the sync run produces a snapshot.
 | --- | --- | --- | --- |
 | `.zsk/config.yaml` | config | init/user | commit |
 | `.zsk/roles.yaml` | staffing policy | init/user | commit |
+| `.zsk/team.yaml` | talent pool | init/user | commit |
+| `.zsk/work.yaml` | work provider mapping | init/user | commit |
+| `.zsk/work.jsonl` | work event ledger | task/issue/dispatch/work sync/status import | commit when created |
+| `.zsk/CONTEXT.md` | project context | init/user/stages | commit |
 | `.zsk/docs/**` | governance docs | init/user | commit |
-| `.zsk/templates/**` | reusable templates | init | commit |
+| `.zsk/templates/config.examples.yaml` | config examples | init | commit |
+| `.zsk/templates/issue-card.md` | issue template | init | commit |
 | `.zsk/raws/README.md` | resource snapshot contract | init | commit |
-| `.zsk/evidence/prepare/README.md` | prepare collaboration contract | init | commit |
 | `.zsk/evidence/prepare/<run>/config-draft.yaml` | discovered source draft | prepare draft/plan/run | commit for review |
 | `.zsk/evidence/prepare/<run>/source-promotion-suggestions.md` | human review queue | prepare draft/plan/run | commit for review |
 | `.zsk/raws/**/snapshot.md` | generated summary | prepare sync | commit |
@@ -26,32 +30,112 @@ declares a durable entry source and the sync run produces a snapshot.
 | `.zsk/modules/index.md` | module registry view | init/module add | commit |
 | `.zsk/modules/<module>/**` | module work surface | module add/user | commit |
 | `.zsk/modules/<module>/_issues/**` | module task cards | prepare sync/user | commit |
-| `.zsk/issues/**` | global/cross-module issues | init/prepare/user | commit |
+| `.zsk/issues/**` | global/cross-module issues | issue/prepare/user | commit |
 | `.zsk/evidence/prepare/sync-report.md` | prepare report | prepare sync | commit |
+| `.zsk/plans/<run>/workflow-graph.{json,yaml,md}` | workflow graph | workflow plan/zskplan | commit |
+| `.zsk/plans/current-workflow-graph.json` | workflow resume pointer | workflow plan/advance/mark | commit |
 | `.zsk/runs/**` | runtime state | commands | ignore |
 | `.zsk/state/**` | runtime state | commands | ignore |
 | `.zsk/tmp/**` | temporary files | commands | ignore |
 
+## Lazy Roots
+
+`zsk init` does not create these roots. They appear only when an owning command
+has real content to write:
+
+| Path | Created When |
+| --- | --- |
+| `.zsk/issues/**` | A shared/global issue is created. |
+| `.zsk/evidence/**` | Prepare, demo, verify, or review writes shared evidence. |
+| `.zsk/resources/**` | A future registry/stage-pack layer earns a separate root. Current resource snapshots use `.zsk/raws/**`. |
+| `.zsk/plans/**` | `zsk workflow plan` or `zskplan` writes a workflow graph or plan artifact. |
+| `.zsk/playwright/**` | Shared Playwright config/auth/helper assets are required. Prefer module `_playwright` first. |
+
 ## Rules
 
 - Raw snapshots live under `.zsk/raws/**`.
+- Project-wide terminology, naming decisions, and cross-module decomposition
+  rationale live in `.zsk/CONTEXT.md`.
 - Module work lives under `.zsk/modules/**`.
+- Module-local terminology and decomposition rationale live in
+  `.zsk/modules/<module>/CONTEXT.md`.
 - Module-local issues live under `.zsk/modules/<module>/_issues/**`.
-- Global or cross-module blockers live under `.zsk/issues/**`.
+- Global or cross-module blockers live under `.zsk/issues/**` only after a
+  scope decision proves they are not module-local.
+- Module templates are owned by `zsk module init`; do not maintain duplicate
+  copies under `.zsk/templates/module/**`.
 - Provider connections are declared once in `.zsk/config.yaml`.
 - `.zsk/config.yaml` should keep durable entry sources, not every child page,
   node, issue, or file found during prepare.
 - Discovered child sources go through `config-draft.yaml` and
   `source-promotion-suggestions.md`; only human-approved entries are promoted
   back into `.zsk/config.yaml`.
-- Staffing policy lives in `.zsk/roles.yaml`; a specific run's chosen agents
-  belong in evidence, not in the template.
+- Talent pool policy lives in `.zsk/team.yaml`; roles, agents, and squads stay
+  provider-agnostic while provider-specific ids live under adapter references.
+  Dispatch maps staffing-plan roles to team roles through
+  `assignmentPolicy.dispatch.roleMappings`, then uses
+  `assignmentPolicy.dispatch.stageRoutes`, role `subagentTypes`, agent
+  `stages/modules/subagentTypes/capacity/priority`, and optional
+  `providerCatalogs` to select the most suitable expert. Project-specific
+  experts belong in `.zsk/team.yaml` or a configured provider catalog rather
+  than CLI code.
+- Work provider mapping lives in `.zsk/work.yaml`; Multica is a default adapter
+  reference, but `.zsk/work.jsonl` events stay generic for other providers.
+- `.zsk/work.jsonl` is lazy. Do not create an empty ledger; create it only when
+  a skill emits a real work event.
+- `zsk work emit-tasks` reads module `tasks.md` Kiro-style task groups and
+  subtasks, then appends generic `work.item.upserted` and parent-child
+  `work.item.linked` events to `.zsk/work.jsonl`. Use `--dry-run` first; it
+  never calls provider APIs or CLIs.
+- `zsk work sync --dry-run` writes a provider command plan from generic work
+  events. Assignment commands preserve role/stage/subagent/selection evidence
+  under command `metadata` for adapter-specific execution later. The plan is
+  reviewable evidence only; it does not call provider APIs or CLIs.
+- `zsk work import-experts --dry-run` previews normalization of a provider
+  expert export into the generic catalog shape. Without `--dry-run`, it writes
+  a local catalog only. Dispatch auto-discovers
+  `.zsk/providers/<provider>/experts.yaml` when present, so a Multica-style
+  talent export can enrich assignment without changing the work ledger schema.
+- `zsk workflow mark --status blocked` and blocked `zsk workflow advance`
+  decisions append generic `work.item.blocked` events. Provider updates still
+  require `zsk work sync --dry-run` review.
+- `zsk dispatch plan --item <id> --emit-work-assignments` appends generic
+  `work.assignment.requested` events for the bound work item from the staffing
+  plan, `.zsk/team.yaml` dispatch role mappings, stage routes, role
+  `subagentTypes`, local agent pool, and optional provider expert catalog; it
+  records the selection source, score, and reasons, and does not call provider
+  APIs or CLIs.
+- `zsk work assign --dry-run` previews a `work.assignment.requested` event and
+  provider assignment command plan from `.zsk/team.yaml` roles, agents, squads,
+  and `.zsk/work.yaml` project mapping.
+- `zsk work assign` without `--dry-run` appends only a generic local
+  `work.assignment.requested` event to `.zsk/work.jsonl`; provider assignment
+  remains behind `zsk work sync --dry-run`.
+- `zsk work import-status` may append `work.provider_status.imported` events
+  from provider exports. When a record explicitly links a local `issue.md`,
+  it also updates that issue status block and refreshes issue indexes. When a
+  record explicitly links a module `tasks.md`, it updates only a matching
+  `zsk-task-status` marker block. It never calls provider APIs or CLIs.
+- Dynamic workflow state lives in `.zsk/plans/**`. Use
+  `zsk workflow plan|next|advance|mark` to create, resume, or conservatively
+  advance it from existing local evidence; do not create a
+  separate top-level runs directory for stage routing.
+- Project-facing documents must use portable paths such as `.zsk/...`,
+  `src/...`, `$HOME/...`, or `<workspace>/...`; do not copy personal absolute
+  paths like `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or
+  `/private/var/...` into proposal, spec, design, tasks, Context Records,
+  handoffs, archives, issues, or evidence summaries.
 
 ## Next Steps
 
 1. Edit `.zsk/config.yaml`.
-2. Add modules with `zsk module init -m <module-id> --name "<Module Name>"`.
-3. Run `zsk config check`.
-4. Run `zsk prepare draft` or `zsk prepare plan` to review discovered source
+2. Review `.zsk/team.yaml` and `.zsk/work.yaml` before syncing or assigning
+   work to any external provider.
+3. Add modules with `zsk module init -m <module-id> --name "<Module Name>"`.
+4. Run `zsk config check`.
+5. Run `zsk workflow plan --goal "<goal>"` when a durable stage graph is useful.
+6. Run `zsk workflow advance` after a stage writes decisive local gate or
+   prepare evidence.
+7. Run `zsk prepare draft` or `zsk prepare plan` to review discovered source
    candidates before changing `.zsk/config.yaml`.
-5. Run `zsk prepare sync` when resource acquisition is intentionally allowed.
+8. Run `zsk prepare sync` when resource acquisition is intentionally allowed.

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

@@ -57,3 +57,5 @@ sources: {}
 
 customize:
   roles: .zsk/roles.yaml
+  team: .zsk/team.yaml
+  work: .zsk/work.yaml

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

@@ -13,7 +13,7 @@ not runtime results.
 | `resources` | Durable entry-source intents to prepare, such as repository roots, issue feeds, document entry pages, design entry nodes, 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. |
+| `customize` / `staffing` | Pointers to role, workflow, team, work-provider, or gate policy files. |
 | `sources` | Compatibility source tree for durable grouped prepare entries. Auto-discovered children stay in draft evidence until promoted. |
 
 ## Materialization
@@ -27,9 +27,21 @@ The workspace does not pre-create resource directories.
 - `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`.
+- `.zsk/work.jsonl` is created lazily only after a skill or future work sync
+  command emits a real provider-agnostic work event.
 - Missing provider credentials or route conflicts must be visible in the report
   with a clear state, reason, output path, and next action.
 
+## Work Management
+
+`customize.team` points to `.zsk/team.yaml`, the talent-pool file for roles,
+agents, squads, capacity hints, and assignment policy.
+
+`customize.work` points to `.zsk/work.yaml`, the provider mapping file for work
+items, project/module linkage, status mapping, sync policy, and adapter defaults.
+Multica is the default provider, but events remain provider-agnostic so another
+adapter can consume the same ledger later.
+
 ## Resource Output
 
 Default raw output is derived from `type + id`, but a resource may override it

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

@@ -20,8 +20,11 @@ Use this layer to answer three questions before execution:
 | --- | --- |
 | `.zsk/config.yaml` | Machine-readable project config and path authority |
 | `.zsk/roles.yaml` | Project staffing policy and role pool overrides |
+| `.zsk/team.yaml` | Talent pool: roles, agents, squads, and assignment policy |
+| `.zsk/work.yaml` | Work provider mapping, status mapping, sync policy, and adapter defaults |
+| `.zsk/work.jsonl` | Lazy append-only Work Event Ledger, created only after a real work event |
 | `.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/modules/{module}/` | Module `CONTEXT.md`, `module.yaml`, `proposal.md`, `spec.md`, `design.md`, `tasks.md` |
 | `.zsk/raws/` | Entry-driven Resource Snapshot Library |
 | `.zsk/evidence/prepare/{run}/config-draft.yaml` | Auto-discovered source candidate tree for review |
 | `.zsk/evidence/prepare/{run}/source-promotion-suggestions.md` | Human review queue for promoting candidates into config |
@@ -32,17 +35,29 @@ Use this layer to answer three questions before execution:
 
 Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are not default write targets. Use explicit export or migration tooling when you need project-root copies.
 
+## Path Privacy
+
+Stage documents, Context Records, handoffs, archives, issues, and evidence
+summaries should use `.zsk/...`, repo-relative, `$HOME/...`, or `<workspace>/...`
+references. Do not preserve personal home-directory absolute paths such as
+`/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or
+`/private/var/...` in reusable project docs. If raw acquisition metadata needs
+the original absolute path, keep it in raw/evidence metadata and provide a
+portable alias for downstream design/spec/task docs.
+
 ## Source Priorities
 
 1. `.zsk/config.yaml`
 2. `.zsk/docs/SYSTEM-SPEC.md`
 3. Project provider/entry-source/route intent in `.zsk/config.yaml`
-4. Prepare drafts and promotion suggestions under `.zsk/evidence/prepare/{run}/`
-5. Materialized resource snapshots under `.zsk/raws/**`
-6. `.zsk/modules/{module}/module.yaml`
-7. `.zsk/modules/{module}/spec.md`
-8. `.zsk/modules/{module}/design.md`
-9. Runtime evidence under module `_evidence` / `_playwright` or shared `.zsk/evidence` / `.zsk/playwright`
+4. Talent and work-provider policy in `.zsk/team.yaml` and `.zsk/work.yaml`
+5. Prepare drafts and promotion suggestions under `.zsk/evidence/prepare/{run}/`
+6. Materialized resource snapshots under `.zsk/raws/**`
+7. `.zsk/modules/{module}/CONTEXT.md`
+8. `.zsk/modules/{module}/module.yaml`
+8. `.zsk/modules/{module}/spec.md`
+9. `.zsk/modules/{module}/design.md`
+10. Runtime evidence under module `_evidence` / `_playwright` or shared `.zsk/evidence` / `.zsk/playwright`
 
 When sources conflict, record the conflict under the module `_issues` directory, or shared `.zsk/issues` only for cross-module/global issues, and update the affected module docs with a Documentation Feedback note or an explicit no-update rationale.
 
@@ -118,6 +133,9 @@ narrower page/frame split is justified in the raw artifact.
 ## Maintenance Checklist
 
 - Update `.zsk/config.yaml` when providers, durable entry sources, routes, modules, paths, or tools change.
+- Update `.zsk/team.yaml` when role, agent, squad, capacity, or assignment policy changes.
+- Update `.zsk/work.yaml` when provider, project/module mapping, status mapping, or sync policy changes.
+- Do not create `.zsk/work.jsonl` manually; skills or future work sync commands create it when they emit real work events.
 - Review `config-draft.yaml` and `source-promotion-suggestions.md` before
   promoting discovered child resources into `.zsk/config.yaml`.
 - Keep project-wide reusable rules in `.zsk/docs/SYSTEM-SPEC.md`.

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

@@ -93,6 +93,7 @@ artifact and any reusable `CONTEXT.md` term, then stop after minimal validation.
 | FR, NFR, acceptance criteria, scenarios, edge cases | `spec` | Creates observable behavior contracts from proposal/source evidence. Missing quality targets remain `未指定` instead of invented. |
 | ADR / decision records for architecture, interfaces, state/data flow, storage, migration, dependency, rollback, integration, security, permission, privacy, or public API decisions | `design` | Required only for design-significant decisions. N/A must cite why no such decision exists. |
 | Proposal/spec/design/ADR alignment and executable work | `task` | Preserves FR/AC/NFR/ADR traceability into task groups, subtasks, evidence, and stop conditions. |
+| Provider-agnostic work items, assignment requests, provider comments, and status sync | `task`, `issue`, `dispatch`, `coding`, `verify` | `task` may create or update work items but must not auto-start provider agents. Dispatch owns assignment requests. Verify owns final verified/done claims. |
 
 Downstream stages consume reviewed upstream revisions. They may report gaps, but
 must not silently rewrite another stage's source of truth.

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

@@ -0,0 +1,218 @@
+# ZSK talent pool.
+#
+# Roles describe responsibility. Agents describe concrete execution capacity.
+# Squads group agents behind a leader for cross-functional or ambiguous work.
+# Provider-specific ids are adapter references, not ZSK role names.
+
+version: 1
+
+roles:
+  product-owner:
+    responsibilities:
+      - Own product outcome, scope, priority, and acceptance intent.
+      - Keep proposal/spec/task claims tied to sourced product evidence.
+    stages: [prepare, preproposal, proposal, spec, task, acceptance]
+    subagentTypes: [analyst]
+
+  business-analyst:
+    responsibilities:
+      - Convert product, policy, and workflow material into requirements and edge cases.
+      - Preserve open questions and conflicts as issues instead of assumptions.
+    stages: [prepare, preproposal, proposal, spec]
+    subagentTypes: [analyst]
+
+  researcher:
+    responsibilities:
+      - Gather and validate external or provider-backed evidence when local sources are insufficient.
+      - Record source freshness, uncertainty, and gaps.
+    stages: [prepare, preproposal, proposal]
+    subagentTypes: [researcher]
+
+  architect:
+    responsibilities:
+      - Own module boundaries, interfaces, data flow, integration risks, and ADR-worthy decisions.
+      - Keep implementation tasks aligned with design decisions.
+    stages: [design, task, review]
+    subagentTypes: [architect]
+
+  frontend-engineer:
+    responsibilities:
+      - Own browser-facing implementation, UI state, accessibility, and visual/runtime evidence.
+      - Preserve TDD and demo evidence for assigned work items.
+    stages: [task, coding, demo, smoke]
+    subagentTypes: [executor]
+
+  backend-engineer:
+    responsibilities:
+      - Own API, data, integration, permission, and service behavior.
+      - Preserve contract, migration, and rollback evidence for assigned work items.
+    stages: [task, coding, smoke]
+    subagentTypes: [executor]
+
+  test-engineer:
+    responsibilities:
+      - Define RED/GREEN/REFACTOR expectations, regression coverage, and verification strategy.
+      - Reject untestable acceptance criteria or missing evidence hooks.
+    stages: [spec, design, task, coding, smoke, verify]
+    subagentTypes: [test-engineer, verifier]
+
+  reviewer:
+    responsibilities:
+      - Review behavioral risk, maintainability, regressions, and missing evidence.
+      - Report findings without taking implementation ownership.
+    stages: [review]
+    subagentTypes: [code-reviewer, reviewer]
+
+  verifier:
+    responsibilities:
+      - Prove or block completion claims against acceptance criteria and fresh evidence.
+      - Keep provider done status separate from ZSK verified status.
+    stages: [verify, acceptance]
+    subagentTypes: [verifier]
+
+agents:
+  solo-lead:
+    roles: [product-owner, architect, reviewer, verifier]
+    route: leader-sequential
+    capacity: primary
+
+  product-agent:
+    roles: [product-owner, business-analyst, researcher]
+    stages: [prepare, preproposal, proposal, spec]
+    subagentTypes: [analyst, researcher]
+    route: native-or-provider
+    capacity: high
+    priority: 4
+    providerRefs:
+      multica:
+        agent: product-agent
+
+  architecture-agent:
+    roles: [architect, reviewer]
+    stages: [design, task, review]
+    subagentTypes: [architect, code-reviewer]
+    route: native-or-provider
+    capacity: high
+    priority: 4
+    providerRefs:
+      multica:
+        agent: architecture-agent
+
+  frontend-agent:
+    roles: [frontend-engineer, test-engineer]
+    stages: [task, coding, demo, smoke]
+    subagentTypes: [executor, test-engineer]
+    route: native-or-provider
+    capacity: high
+    priority: 4
+    providerRefs:
+      multica:
+        agent: frontend-agent
+
+  backend-agent:
+    roles: [backend-engineer, test-engineer]
+    stages: [task, coding, smoke]
+    subagentTypes: [executor, test-engineer]
+    route: native-or-provider
+    capacity: high
+    priority: 4
+    providerRefs:
+      multica:
+        agent: backend-agent
+
+  verification-agent:
+    roles: [test-engineer, reviewer, verifier]
+    stages: [smoke, review, verify, acceptance]
+    subagentTypes: [test-engineer, code-reviewer, verifier]
+    route: native-or-provider
+    capacity: high
+    priority: 4
+    providerRefs:
+      multica:
+        agent: verification-agent
+
+squads:
+  product:
+    leader: product-agent
+    members: [product-agent, architecture-agent, verification-agent]
+    useWhen:
+      - Product direction, resource readiness, or acceptance intent is unclear.
+      - External research or source conflict resolution is required.
+
+  design:
+    leader: architecture-agent
+    members: [architecture-agent, frontend-agent, backend-agent, verification-agent]
+    useWhen:
+      - Interfaces, data flow, UX, integration, security, or rollback decisions are coupled.
+      - A design decision affects more than one module or implementation lane.
+
+  delivery:
+    leader: solo-lead
+    members: [frontend-agent, backend-agent, verification-agent]
+    useWhen:
+      - Approved task work needs implementation, tests, and verification evidence.
+      - Multiple implementation lanes can proceed without write-scope conflict.
+
+# Optional provider expert catalogs can enrich the local talent pool without
+# making the work ledger provider-specific. A Multica export can be normalized
+# into a generic experts.yaml with id/providerAgent/roles/stages/modules.
+# `zsk work import-experts` writes `.zsk/providers/<provider>/experts.yaml`,
+# and dispatch auto-discovers that default path when the file exists.
+providerCatalogs:
+  # multica:
+  #   path: .zsk/providers/multica/experts.yaml
+
+assignmentPolicy:
+  defaultMode: squad-for-ambiguous-direct-for-clear
+  directWhen:
+    - Work item has a single module, clear role, clear write scope, and test contract.
+  squadWhen:
+    - Work item crosses product, design, implementation, or verification concerns.
+    - Required source, acceptance, or evidence ownership is uncertain.
+  neverAutoStartFromStages:
+    - task
+  requiresDispatchBeforeProviderAssignment: true
+  dispatch:
+    assignmentMode: agent
+    ownerRoleHints:
+      enabledForStaffingRoles: [executor, planner]
+    stageRoutes:
+      prepare:
+        roles: [product-owner, business-analyst, researcher, test-engineer]
+        subagentTypes: [analyst, researcher, test-engineer]
+      proposal:
+        roles: [product-owner, business-analyst, architect, researcher]
+        subagentTypes: [analyst, architect, researcher]
+      spec:
+        roles: [product-owner, business-analyst, architect, test-engineer]
+        subagentTypes: [analyst, architect, test-engineer]
+      design:
+        roles: [architect, frontend-engineer, backend-engineer, test-engineer]
+        subagentTypes: [architect, executor, test-engineer]
+      task:
+        roles: [architect, frontend-engineer, backend-engineer, test-engineer]
+        subagentTypes: [planner, architect, executor, test-engineer]
+      coding:
+        roles: [frontend-engineer, backend-engineer, test-engineer]
+        subagentTypes: [executor, test-engineer]
+      demo:
+        roles: [frontend-engineer, test-engineer]
+        subagentTypes: [executor, test-engineer]
+      review:
+        roles: [reviewer, architect, test-engineer]
+        subagentTypes: [code-reviewer, architect, test-engineer]
+      verify:
+        roles: [verifier, test-engineer]
+        subagentTypes: [verifier, test-engineer]
+    roleMappings:
+      auth-fetch-agent: [researcher]
+      design-specialist: [frontend-engineer]
+      executor: [frontend-engineer, backend-engineer]
+      lead-integrator: [verifier, architect, product-owner]
+      market-researcher: [researcher]
+      planner: [architect, product-owner]
+      qa-engineer: [test-engineer]
+      senior-engineering-reviewer: [reviewer]
+      technical-writer: [product-owner]
+      ue-a11y-reviewer: [reviewer, frontend-engineer]
+      ux-specialist: [frontend-engineer]

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

@@ -0,0 +1,75 @@
+# ZSK work management policy.
+#
+# This file maps provider-agnostic ZSK Work Events to external work systems.
+# Multica is the default adapter reference, but .zsk/work.jsonl remains generic
+# and can be translated to Jira, GitHub Issues, GitLab, Linear, or local Markdown.
+
+version: 1
+
+ledger:
+  path: .zsk/work.jsonl
+  format: jsonl
+  createWhen: first-work-event
+  providerAgnostic: true
+
+defaultProvider: multica
+
+providers:
+  multica:
+    adapter: multica
+    mode: dry-run-until-explicit-sync
+    workspace: "<workspace-slug>"
+    # Optional generic expert catalog exported or normalized from the provider.
+    # Dispatch also auto-discovers .zsk/providers/<provider>/experts.yaml when
+    # `zsk work import-experts` creates it.
+    # Prefer `.zsk/team.yaml providerCatalogs` when the catalog is part of the
+    # local talent-pool contract.
+    # expertCatalog:
+    #   path: .zsk/providers/multica/experts.yaml
+    commandPlan:
+      executable: multica
+      mode: dry-run-template
+    projectMapping:
+      strategy: module-to-project
+      projects: {}
+    statusMapping:
+      draft: backlog
+      ready: todo
+      implementing: in_progress
+      review: in_review
+      verified: done
+      blocked: blocked
+      cancelled: cancelled
+    assignment:
+      taskCreatesIssuesOnly: true
+      dispatchAssignsAgentsOrSquads: true
+      verifyControlsDone: true
+
+events:
+  accepted:
+    - work.item.upserted
+    - work.item.linked
+    - work.item.status_changed
+    - work.provider_status.imported
+    - work.assignment.requested
+    - work.assignment.accepted
+    - work.comment.added
+    - work.item.verified
+    - work.item.blocked
+
+syncPolicy:
+  idempotency:
+    localKey: workItem.id
+    remoteRefPath: externalRefs
+  dryRunFirst: true
+  createRemoteWhen:
+    - provider is configured
+    - work item has project, module, stage, local id, title, status, and source artifacts
+  updateRemoteWhen:
+    - local work item has an existing remote reference
+    - status, source links, assignment, comments, or evidence changed
+  neverSync:
+    - secrets
+    - raw credential values
+    - provider cookies
+    - private auth state paths

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

@@ -1,21 +0,0 @@
-# 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/<run>/config-draft.yaml
-.zsk/evidence/prepare/<run>/source-promotion-suggestions.md
-.zsk/evidence/prepare/sync-report.md
-.zsk/evidence/prepare/blocked-resources.md
-```
-
-`config-draft.yaml` and `source-promotion-suggestions.md` are review artifacts.
-They do not mutate `.zsk/config.yaml`; selected entries must be applied only
-after human confirmation.
-
-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/evidence/prepare/README.md

@@ -1,22 +0,0 @@
-# Prepare Evidence
-
-Prepare runs write per-run artifacts here:
-
-```text
-.zsk/evidence/prepare/<run>/
-  repo-inventory.json
-  config-draft.yaml
-  source-promotion-suggestions.md
-  acquisition-plan.json
-  blocked-sources.md
-  correspondence-questions.md
-```
-
-Default collaboration rule:
-
-- `config-draft.yaml` is a candidate tree, not an applied config.
-- `source-promotion-suggestions.md` explains which candidates are ready or need
-  review.
-- `.zsk/config.yaml` changes only after human confirmation.
-- `sync-report.md` summarizes actual materialization results after
-  `zsk prepare sync`.

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

@@ -1,10 +0,0 @@
-# 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/templates/module/README.md

@@ -1,13 +0,0 @@
-# Module Template
-
-Copy this template through `zsk module init`; do not create real module
-directories by hand unless the same file contract is preserved.
-
-Required files:
-
-- `module.yaml`
-- `README.md`
-- `proposal.md`
-- `spec.md`
-- `design.md`
-- `tasks.md`

package/templates/project-init/.zsk/templates/module/design.md

@@ -1,22 +0,0 @@
-# Design
-
-## Output Quality Check
-
-status: NEEDS_CLARIFICATION
-owner: design
-source_basis: []
-blocking_items:
-  - Map approved behavior to implementation surfaces.
-next_action: Resolve Interface, data flow, rollout, and verification gaps.
-
-## Module
-
-## Interfaces
-
-## Implementation
-
-## Data Flow
-
-## Risks
-
-## Verification

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

@@ -1,15 +0,0 @@
-# yaml-language-server: $schema=__ZSK_MODULE_SCHEMA_URL__
-
-module:
-  id: "<module-id>"
-  name: "<Module Name>"
-
-outputs:
-  docs: .zsk/modules/<module-id>
-  issues: .zsk/modules/<module-id>/_issues
-
-tests:
-  raw_cases: []
-  derived_cases: []
-  automated:
-    e2e: []