@captain_z/zsk 1.8.5 → 1.8.7

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

@@ -1,11 +1,11 @@
 # ZSK Workspace
 
-This workspace is config-driven.
+This workspace is entry-driven and evidence-first.
 
-Do not create empty resource directories. `zsk init` creates the governance
-entrypoints only. Resource snapshot directories under `.zsk/raws/**` are created
-by `zsk prepare sync` only after `.zsk/config.yaml` declares a resource and the
-sync run produces a snapshot.
+Do not create empty resource directories. `zsk init` creates the governance and
+collaboration entrypoints only. Resource snapshot directories under
+`.zsk/raws/**` are created by `zsk prepare sync` only after `.zsk/config.yaml`
+declares a durable entry source and the sync run produces a snapshot.
 
 ## Working Model
 
@@ -13,9 +13,16 @@ 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/<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 |
 | `.zsk/raws/**/metadata.yaml` | generated provenance | prepare sync | commit |
 | `.zsk/raws/**/source.json` | raw provider payload | prepare sync | ignore by default |
@@ -23,26 +30,112 @@ 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/**`.
-- Provider connections, resource intents, and routes are declared in
-  `.zsk/config.yaml`.
-- Staffing policy lives in `.zsk/roles.yaml`; a specific run's chosen agents
-  belong in evidence, not in the template.
+- 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`.
+- 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 sync` when resource acquisition is intentionally allowed.
+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`.
+8. Run `zsk prepare sync` when resource acquisition is intentionally allowed.

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

@@ -12,12 +12,15 @@ template:
 mode: standard
 scale: auto
 
-# Provider connection profiles. Keep credentials out of this file; reference
-# environment variables or global profiles instead.
+# Provider connection profiles. Configure each platform once. 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.
+# Durable entry sources to prepare. Prefer one authority-bearing entry per
+# platform/domain, then let `zsk prepare draft|plan` discover child pages, files,
+# nodes, or issues into .zsk/evidence/prepare/*/config-draft.yaml and
+# source-promotion-suggestions.md. Do not hand-maintain every discovered child
+# in this file.
 resources: []
 
 # Routes map prepared resources into controlled consumption surfaces such as
@@ -47,9 +50,12 @@ modules:
 #         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.
+# Current prepare implementation compatibility tree. Use it for durable
+# grouped prepare entries only. Auto-discovered children should stay in
+# evidence/raw indexes until a human promotes them from config-draft.yaml.
 sources: {}
 
 customize:
   roles: .zsk/roles.yaml
+  team: .zsk/team.yaml
+  work: .zsk/work.yaml

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

@@ -10,27 +10,43 @@ not runtime results.
 | `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. |
+| `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. |
-| `sources` | Compatibility source tree used by the current prepare implementation until the Resource Preparation Module fully owns `resources`. |
+| `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
 
 The workspace does not pre-create resource directories.
 
-- `resources` entries produce `.zsk/raws/**` snapshots after sync.
+- `resources` or durable `sources` entries produce `.zsk/raws/**` snapshots after sync.
+- `zsk prepare draft` writes candidate entries to
+  `.zsk/evidence/prepare/{run}/config-draft.yaml` and review guidance to
+  `source-promotion-suggestions.md`; it must not update `.zsk/config.yaml`.
 - `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
-with `output.rawPath`.
+with `output.rawPath`. Keep these entries at the authority-entry level; do not
+hand-maintain every child page, issue, Figma node, or file found under the entry.
 
 ```yaml
 resources:

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

@@ -20,9 +20,14 @@ 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/raws/` | Config-driven Resource Snapshot Library |
+| `.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 |
 | `.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 |
@@ -30,16 +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/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`
-8. Runtime evidence under module `_evidence` / `_playwright` or shared `.zsk/evidence` / `.zsk/playwright`
+3. Project provider/entry-source/route intent in `.zsk/config.yaml`
+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.
 
@@ -59,6 +77,14 @@ If a document cannot answer its stage questions, stop and record the missing sou
 `prepare sync` materializes configured resources under `.zsk/raws/**`; init does
 not create resource subdirectories or empty indexes.
 
+Configure durable entry sources in `.zsk/config.yaml`, not every child artifact
+found below an entry. For example, one Confluence space/page entry can be the
+authority for a product area; child pages discovered from that entry first land
+in `.zsk/evidence/prepare/{run}/config-draft.yaml` and
+`source-promotion-suggestions.md`. Promote a child into `.zsk/config.yaml` only
+after a human confirms it is stable, reusable, and worth tracking as an
+authority source.
+
 Default resource output is derived from `type + id`, for example:
 
 | Resource | Default Snapshot Path |
@@ -79,17 +105,20 @@ not a requirement author, interaction designer, code designer, or task planner.
 
 Use this order for source capture:
 
-1. Register provider profiles, resource intents, and routes in `.zsk/config.yaml`.
-2. Run `zsk prepare plan` to classify ready, stale, blocked, and ambiguous
+1. Register provider profiles, entry sources, and routes in `.zsk/config.yaml`.
+2. Run `zsk prepare draft` to write a candidate `config-draft.yaml` and
+   `source-promotion-suggestions.md`; review these before applying changes to
+   `.zsk/config.yaml`.
+3. 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
+4. Run `zsk prepare auth-check` for private URLs so credentials are verified
    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
+5. 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/sync-report.md` before downstream stages
+6. 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
@@ -103,7 +132,12 @@ narrower page/frame split is justified in the raw artifact.
 
 ## Maintenance Checklist
 
-- Update `.zsk/config.yaml` when providers, resources, routes, modules, paths, or tools change.
+- 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`.
 - Keep module-specific decisions in `.zsk/modules/{module}/`.
 - Keep shared raw source facts under `.zsk/raws/`.

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

@@ -6,10 +6,11 @@ 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:
 
-- config-declared resource snapshots under `paths.raws`;
+- config-declared entry sources and materialized 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`;
+- prepare drafts/promotion suggestions and runtime evidence under module
+  `_evidence` or shared `paths.evidence`;
 - issue records under module `_issues` or shared/global `paths.issues`;
 - Playwright plans/specs/results under module `_playwright` or shared `paths.playwright`.
 
@@ -19,8 +20,12 @@ 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 shared Resource Snapshots produced from configured resources.
+- `paths.raws` stores shared Resource Snapshots produced from configured entry sources.
 - 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.
+- `paths.evidence/prepare/{run}/config-draft.yaml` and
+  `source-promotion-suggestions.md` are the review queue for discovered child
+  sources. They do not change `.zsk/config.yaml` until a human promotes selected
+  entries.
 - 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.
@@ -82,12 +87,13 @@ artifact and any reusable `CONTEXT.md` term, then stop after minimal validation.
 
 | Artifact / Decision | Owning Stage | Notes |
 | --- | --- | --- |
-| 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. |
+| Provider profiles, durable entry-source intents, config drafts, source-promotion suggestions, 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. Auto-discovered children stay advisory until human promotion into config. |
 | 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. |
 | 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/raws/README.md

@@ -2,12 +2,17 @@
 
 `.zsk/raws` is the Resource Snapshot Library.
 
-This directory is config-driven. Do not create empty resource type directories
+This directory is entry-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
+1. `.zsk/config.yaml` declares a durable entry source, and
 2. `zsk prepare sync` produces a snapshot for that resource.
 
+Auto-discovered child pages, nodes, issues, and files should first appear in
+`.zsk/evidence/prepare/{run}/config-draft.yaml` and
+`source-promotion-suggestions.md`. Promote only human-confirmed authority
+sources back into `.zsk/config.yaml`.
+
 ## Snapshot Contract
 
 ```text

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]