@captain_z/zsk-skills 1.8.5 → 1.8.7

package/README.md

@@ -135,78 +135,97 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 ## Skill 清单（core skills）
 
 > 内容由 `tools/catalog.ts` 从 `packages/skills/*/SKILL.md` frontmatter 生成。重生成：`pnpm catalog`。
+> 默认 profile bundles 只安装 entry 和保留的一等 stage；capability / gate / mode 由 `zskplan` / `zsk` 内部调度或通过 custom/legacy 明确安装。Legacy aliases 仍保留 24 个 skill 以兼容旧安装。
 
-### `<slug>/` — Core · harness-first 默认工作流入口 (24)
+### Entry Skills (2)
 
-- **`zskplan`**
+用户默认只需要理解的入口。
+
+- **`zskplan`** · keep-entry
   Use as the ZSK-aware RalphPlan-style planning entrypoint that clarifies vague intake, then freezes scope, module decomposition, skill route, expert lanes, Playwright/evidence paths, and stop conditions under .zsk.
 
-- **`zsk`**
+- **`zsk`** · keep-entry
   Use as the ZSK-aware Ralph-style execution loop that follows ZSK plans, dispatches expert lanes, verifies, fixes, and writes only .zsk outputs.
 
-- **`dispatch`**
-  At task intake, asks OMX to assign subagents to the right zsk skill from request, state, evidence, and blockers.
+### Stage Skills (11)
 
-- **`flow`**
-  Starts or resumes delivery by reading state, resources, and blockers, then selecting the next legal stage.
+有独立产物边界、质量门禁和下游消费关系的一等阶段。
 
-- **`prepare`**
+- **`prepare`** · keep-stage
   After project init, collects resource origins, snapshots evidence, and updates config/manifests before proposal/spec.
 
-- **`preproposal`**
+- **`preproposal`** · keep-stage
   Before proposal, turns a one-sentence or vague intake brief into a clear, reviewed product, roadmap, UX, and readiness raw resource pack.
 
-- **`proposal`**
+- **`proposal`** · keep-stage
   Before spec, frames the problem, scope, non-goals, success criteria, stakeholders, risks, and resource gaps.
 
-- **`spec`**
+- **`spec`** · keep-stage
   After proposal, defines sourced FR/NFR, acceptance criteria, scenarios, edge cases, and open gaps.
 
-- **`design`**
+- **`design`** · keep-stage
   After spec freeze, maps behavior to interfaces, data flow, rollout plan, risks, and implementation surfaces.
 
-- **`task`**
+- **`task`** · keep-stage
   After design approval, creates executable tasks with dependencies, FR/AC coverage, owners, and evidence hooks.
 
-- **`coding`**
+- **`coding`** · keep-stage
   For approved tasks, implements small scoped diffs with tests, evidence, and blocker reporting.
 
-- **`smoke`**
-  After coding, proves changed behavior locally with targeted tests and relevant lint/typecheck/build evidence.
+- **`demo`** · keep-stage
+  Before formal testing, runs planned demos and captures evidence without making acceptance claims.
 
-- **`review`**
-  After smoke or explicit path targeting, reviews implementation or local targets against scope, contracts, evidence, security, maintainability, and ZSK boundaries.
+- **`verify`** · keep-stage
+  Independently verifies fixes or acceptance criteria against a stated claim, target version, and linked evidence.
 
-- **`commit`**
-  After smoke and review pass, prepares a scoped commit with intent, evidence, and clean staging.
+- **`acceptance`** · keep-stage
+  After independent verify passes, records accept/reject decision, linked evidence, and residual-risk owner.
 
-- **`demo`**
-  Before formal testing, runs planned demos and captures evidence without making acceptance claims.
+- **`archive`** · keep-stage
+  After acceptance, closes the iteration by preserving artifacts, decisions, issues, and learning proposals.
 
-- **`defect`**
-  After formal QA reports findings, normalizes defects with repro, evidence, FR/AC links, and fix routing.
+### Capabilities (6)
 
-- **`ready`**
-  Before independent verification, prepares a handoff with issue mappings, evidence, version, and regression notes.
+可被多个阶段复用的内部能力；默认由入口或阶段调度。
 
-- **`verify`**
-  Independently verifies fixes or acceptance criteria against a stated claim, target version, and linked evidence.
+- **`dispatch`** · downshift-to-capability
+  At task intake, asks OMX to assign subagents to the right zsk skill from request, state, evidence, and blockers.
 
-- **`acceptance`**
-  After independent verify passes, records accept/reject decision, linked evidence, and residual-risk owner.
+- **`review`** · downshift-to-capability
+  After smoke or explicit path targeting, reviews implementation or local targets against scope, contracts, evidence, security, maintainability, and ZSK boundaries.
 
-- **`deploy`**
-  After review, deploys to non-production or demo targets with version, smoke evidence, and rollback owner.
+- **`defect`** · downshift-to-capability
+  After formal QA reports findings, normalizes defects with repro, evidence, FR/AC links, and fix routing.
 
-- **`archive`**
-  After acceptance, closes the iteration by preserving artifacts, decisions, issues, and learning proposals.
+- **`deploy`** · downshift-to-capability
+  After review, deploys to non-production or demo targets with version, smoke evidence, and rollback owner.
 
-- **`learn`**
+- **`learn`** · downshift-to-capability
   Use after repeated friction or supplied public skill/harness references to learn, compare, record gaps, and prepare one reviewed ZSK optimization batch.
 
-- **`issue`**
+- **`issue`** · keep-capability
   Tracks defects, blockers, questions, and risks with taxonomy, severity, owner, reproduction, and evidence.
 
-- **`fix`**
+### Gates (3)
+
+阶段内部的质量检查点或发布检查点。
+
+- **`smoke`** · downshift-to-gate
+  After coding, proves changed behavior locally with targeted tests and relevant lint/typecheck/build evidence.
+
+- **`commit`** · downshift-to-gate
+  After smoke and review pass, prepares a scoped commit with intent, evidence, and clean staging.
+
+- **`ready`** · downshift-to-gate
+  Before independent verification, prepares a handoff with issue mappings, evidence, version, and regression notes.
+
+### Modes (2)
+
+入口或阶段内部的执行模式。
+
+- **`flow`** · downshift-to-mode
+  Starts or resumes delivery by reading state, resources, and blockers, then selecting the next legal stage.
+
+- **`fix`** · downshift-to-mode
   For persisted issues, diagnoses root cause, applies the smallest scoped correction, adds a regression guard, updates the issue, and hands off verification.
 

package/acceptance/SKILL.md

@@ -84,11 +84,21 @@ This core skill is governed by the ZSK harness. Enforce these rules even when on
 - Collaboration: ordinary stage skills own their declared outputs and handoff quality; workflow skills own route selection. Do not hardcode the next stage inside a stage skill.
 - Output Quality Check: every stage output must expose status, owner, source basis, blocking item links, and next action near the top of the artifact; route cross-stage gaps to their owning stage instead of running a generic grill.
 - Clarification Prelude: ask exactly one load-bearing question with a separate recommendation only after local sources cannot produce a safe expression; persist confirmed expressions through CLAR, the owning artifact, and required CONTEXT.md updates.
+- Requirements Grilling Readiness: for preproposal/proposal clarification, follow `harness/contracts/requirements-grilling.yaml`; high-impact ambiguity asks one question and may block, medium ambiguity may proceed with accepted recommendation, and low-impact ambiguity is recorded without blocking.
+- Stage Output Readiness: for spec/design output quality, follow `harness/contracts/stage-output-readiness.yaml`; spec protects observable behavior contracts, design protects task-ready implementation decisions, and accepted reusable consensus must persist to Context Records.
+- Clarification quality: before asking, name source basis, unresolved decision, impact tier, downstream consumer, why sources cannot answer, recommended answer, accepted tradeoff, and Context update target or N/A rationale.
+- Readiness Packs: follow `harness/contracts/readiness-packs.yaml` when source lanes, product packs, UX supplements, QA case packs, defect packs, or readiness handoffs are produced or consumed; keep provider metadata under `providerRefs` and local evidence under `sourceRefs`.
+- Dispatch Runtime: follow `harness/contracts/dispatch-runtime.yaml` when planning subagent, OMX, provider-lane, or sequential dispatch; every emitted packet needs durable status, heartbeat/timeout policy, and fallback evidence.
 - Dynamic state awareness: identify the active role/stage, project type, stack, runtime, domain, target users/market, and freshness-sensitive decisions before selecting practices or retrieval sources.
 - Filesystem boundaries: write ZSK-managed outputs only under the configured `.zsk` workspace paths.
-- Context recording: durable terminology, naming, decomposition, and load-bearing clarification decisions must update the nearest `CONTEXT.md`, or the handoff must record `Context update: N/A` with rationale.
+- Path privacy: do not write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs; use repo-relative, `.zsk/...`, `$HOME/...`, or `<workspace>/...` references instead.
+- Repository layout: edit canonical source roots first, regenerate derived surfaces, and keep local runtime state out of Git unless it is intentional evidence.
+- Workspace layout: keep init surfaces shallow; materialize lazy roots such as `.zsk/issues`, `.zsk/evidence`, `.zsk/resources`, `.zsk/plans`, and `.zsk/playwright` only when an owning output exists.
+- Profile strategy: profiles select workflow strategy, strictness, capabilities, gates, evidence, and tools; flat bundles are only the install adapter.
+- Work management: emit provider-agnostic work events to `.zsk/work.jsonl` only after real task/issue/assignment/status changes; keep Multica or future providers behind adapters.
+- Context recording: durable terminology, naming, decomposition, and load-bearing clarification decisions must update the nearest Context Record target, or the handoff must record `Context update: N/A` with rationale.
 - Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
-- Learning authority: reusable ZSK core learning must target the canonical ZSK source repo `.zsk/learning/proposals/`; project-local learning may stay in the current project.
+- Learning authority: learning proposals must target the canonical ZSK source repo `.zsk/learning/proposals/`; consuming projects keep experience in archives, docs feedback, or issues and must not create `.zsk/learning/`.
 
 When a `harness/` directory is installed beside this file, treat it as the local contract source:
 
@@ -96,9 +106,10 @@ When a `harness/` directory is installed beside this file, treat it as the local
 - Read `harness/workflow/skill-io-contract.yaml` for this skill's required inputs, outputs, tools, and capabilities.
 - Read `harness/workflow/skill-quality-standards.yaml` for this skill's document mode, must-answer questions, quality checkpoints, and anti-patterns.
 - Read `harness/workflow/state-machine.yaml` and `harness/constraints/stage-gates.md` before moving between stages.
+- Read `harness/contracts/dispatch-runtime.yaml`, `harness/contracts/profile-strategy.yaml`, `harness/contracts/readiness-packs.yaml`, `harness/contracts/requirements-grilling.yaml`, `harness/contracts/skill-classification.yaml`, `harness/contracts/stage-output-readiness.yaml`, `harness/contracts/work-management.yaml`, `harness/contracts/workspace-layout.yaml`, and `harness/contracts/repository-layout.yaml` before changing dispatch/subagent behavior, install surfaces, source readiness packs, proposal-bound clarification, spec/design readiness, work sync, staffing/talent routing, workspace paths, or repo directory roles.
 - Read `harness/constraints/skill-role-contract.md` before planning or reviewing expert work.
 - Read `harness/constraints/filesystem-boundaries.md` before creating any project artifact.
-- Record durable project/module language in `.zsk/modules/{module}/CONTEXT.md` or `.zsk/docs/CONTEXT.md` before relying on it downstream.
+- Record durable project/module language in `.zsk/modules/{module}/CONTEXT.md` or `.zsk/CONTEXT.md` before relying on it downstream.
 - Read `harness/constraints/evidence-rules.md` and `harness/workflow/completion-contract.yaml` before claiming READY / PASS / DONE.
 - Read `harness/constraints/issue-taxonomy.md` before creating or updating blockers, risks, defects, or questions.
 - Apply the related best-practice concerns listed in `harness/THIS_SKILL.md`; read bundled `harness/best-practices/` files first when they are listed for the current skill. Search Context7 or the web only when local guidance or local facts are missing, incomplete, stale, too generic, version-sensitive, market-sensitive, or role-incomplete. Record source links, source dates when relevant, and adaptation rationale in the evidence or learning proposal.

package/acceptance/harness/THIS_SKILL.md

@@ -8,6 +8,15 @@ This file is generated for the installed skill. Read it before executing this sk
 - Stage/type: `acceptance`
 - Purpose: After independent verify passes, records accept/reject decision, linked evidence, and residual-risk owner.
 
+## Skill Classification
+
+- Target primary: `stage`
+- Disposition: `keep-stage`
+- Stage eligible: `true`
+- Facets: `acceptance`, `quality-assessment`
+- Rationale: Records final accept/reject decision, linked evidence, and residual risks.
+- Migration: Keep as governance stage for standard/enterprise workflows; allow lite profiles to fold it into verify.
+
 ## Required Inputs
 
 - `verify-report`
@@ -53,6 +62,7 @@ This file is generated for the installed skill. Read it before executing this sk
 - Treat missing mandatory artifacts, mandatory evidence, required owners, required gates, or downstream-consumable outputs as FAIL or BLOCKED.
 - Write unsupplied numeric thresholds, quality bars, SLOs, coverage targets, and business targets as `未指定`; suggestions must be labeled separately from current policy.
 - Avoid provider lock-in: do not assume Jira, Confluence, Figma, GitHub, GitLab, Linear, Notion, browser tooling, or any platform unless configured sources or evidence identify it.
+- Path privacy is a hard portability requirement: reusable project docs must use repo-relative or `.zsk/...` paths and must not contain personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...`.
 - For each required output or finding, name owner, dependency, acceptance condition, verification evidence, and next action.
 
 ## Industry Best-Practice Anchors
@@ -105,8 +115,12 @@ This file is generated for the installed skill. Read it before executing this sk
 - Every stage output must include a concise `Output Quality Check` near the top with fields in order: status, owner, source_basis, blocking_items, next_action, and optional waiver/updated_at.
 - When an existing stage artifact is present, the active skill must update its own Output Quality Check before downstream handoff: derive the check from that skill's responsibility, required inputs, required outputs, must-answer questions, quality checkpoints, current artifact, upstream sources, and downstream consumer; classify sourced, accepted, assumed, conflicting, missing, and N/A claims, then repair or block through the owning stage.
 - Keep Clarification Prelude skill-local: ask, repair, or block only on load-bearing questions the active skill owns; route upstream or downstream findings to the owning stage instead of absorbing another skill's responsibility.
+- Apply `harness/contracts/requirements-grilling.yaml` for proposal-bound clarification: high-impact ambiguity blocks and asks one question, medium ambiguity may proceed with accepted recommendation, and low-impact ambiguity is recorded as an assumption.
+- Before asking a clarification question, prove question quality: source summary, unresolved decision, impact tier, downstream consumer, and why sources cannot answer it.
+- Apply `harness/contracts/readiness-packs.yaml` when producing or consuming upstream source handoffs: stable source lanes and pack types stay provider-agnostic, provider metadata stays under providerRefs, and local evidence stays under sourceRefs.
 - Every Output Quality Check must align terminology against CONTEXT.md/CONTEXT-MAP.md when present, SYSTEM-SPEC.md, configured raw sources, current artifact identifiers, and code/component/API names when implementation-facing work is touched.
-- Record durable terminology, naming, decomposition, and load-bearing clarification decisions in the nearest CONTEXT.md, or write `Context update: N/A` with rationale.
+- Record durable terminology, naming, decomposition, and load-bearing clarification decisions in the nearest Context Record target (`.zsk/modules/{module}/CONTEXT.md`, `.zsk/CONTEXT.md`, or source repo `CONTEXT.md`), or write `Context update: N/A` with rationale.
+- Keep proposal, spec, design, tasks, Context Records, handoffs, archives, issues, and evidence summaries portable: use repo-relative or `.zsk/...` paths, and do not write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs.
 - Preserve upstream/downstream stage ownership; do not silently rewrite another skill's artifact.
 - Record accept, reject, or conditional acceptance decision with linked verify/demo evidence.
 - Name accepted criteria, residual risks, owners, and documentation feedback or no-update rationale.
@@ -120,7 +134,8 @@ This file is generated for the installed skill. Read it before executing this sk
 - When behavior is testable, define or consume a traceable test basis before claiming implementation, smoke, review, verify, or acceptance success.
 - When external facts, SDKs, APIs, regulations, market context, or dependency behavior are freshness-sensitive, retrieve current authoritative references or record why local sources are sufficient.
 - When an artifact becomes too large for one reviewable file, split it into `{stage}/index.md` plus linked child Markdown files while preserving the full stage contract.
-- When clarification, grilling, architecture review, artifact repair, or task decomposition introduces a term or naming decision future stages must reuse, update module-local or project-level CONTEXT.md before handoff.
+- When clarification, grilling, architecture review, artifact repair, or task decomposition introduces a term or naming decision future stages must reuse, update module-local or project-level Context Record before handoff.
+- When absolute local paths appear in raw source metadata, copy only portable aliases into downstream design/spec/task docs unless the absolute path is explicitly required as raw acquisition provenance.
 - When residual risks affect security, privacy, permissions, data, release, or compliance, require owner and follow-up issue.
 - When business/user confirmation is missing, mark acceptance BLOCKED instead of inferred.
 
@@ -197,6 +212,7 @@ This file is generated for the installed skill. Read it before executing this sk
 - Running a generic grill or cross-stage rewrite instead of the active skill's own Output Quality Check and Clarification Prelude.
 - Letting terminology, naming, or decomposition decisions live only in chat instead of CONTEXT.md.
 - Running stage-specific questioning without checking whether the artifact uses the same terms as upstream sources, downstream consumers, and implementation surfaces.
+- Asking a clarification question that does not name the affected output, recommended answer, accepted tradeoff, and recording destination.
 - Letting a delayed subagent packet block indefinitely instead of marking it stale and falling back or re-emitting.
 - Claiming tests prove behavior when they have no traceable basis, no meaningful assertion, or only prove implementation details.
 - Accepting without verification evidence.

package/acceptance/harness/constraints/filesystem-boundaries.md

@@ -3,10 +3,10 @@
 Default project paths:
 
 - `.zsk/`: the only default ZSK-managed workspace root.
-- `.zsk/docs/`: project-level docs such as `SYSTEM-SPEC.md` and `PROJECT-CONFIG.md`.
+- `.zsk/CONTEXT.md`: canonical project-wide Context Record for cross-module terminology, naming decisions, decomposition rationale, and accepted clarifications.
+- `.zsk/docs/`: project-level docs such as `SYSTEM-SPEC.md` and `PROJECT-CONFIG.md`; `.zsk/docs/CONTEXT.md` is deprecated compatibility output only, not a canonical write target.
 - `.zsk/modules/{module}/`: module config and stage artifacts.
 - `.zsk/modules/{module}/CONTEXT.md`: module-local domain language, naming decisions, decomposition rationale, and accepted clarifications that later stages must reuse.
-- `.zsk/docs/CONTEXT.md`: project-wide domain language and cross-module terms when a term is not owned by one module.
 - `.zsk/raws/`: raw external source snapshots, manifests, imported test cases, market/product research sources, and design/API assets.
 - `.zsk/raws/prepare/**`: reusable source lanes. `preproposal` may add generated or candidate intake clarity, product, roadmap, UX, and design-source readiness resources here only when they are labeled with provenance, review checkpoint status, assumptions, and blockers.
 - `.zsk/evidence/preproposal/{run}/`: checkpoint review evidence for product direction, roadmap/decomposition, UX/design-readiness, and final readiness before formal proposal.
@@ -14,7 +14,7 @@ Default project paths:
 - `.zsk/modules/{module}/_evidence/`: module-private reusable runtime or research evidence, created on demand.
 - `.zsk/modules/{module}/_playwright/`: module-specific Playwright specs, test plans, auth state, execution records, reports, and results, created on demand.
 - `.zsk/issues/`, `.zsk/evidence/`, `.zsk/playwright/`: shared/global artifacts only, created on demand when the asset is intentionally cross-module.
-- `.zsk/learning/proposals/`: reusable improvement proposals and learning records, created lazily only when learn/archive writes an actual proposal.
+- `.zsk/learning/proposals/`: ZSK core learning proposal path. This path belongs in the canonical ZSK source checkout, not in consuming business/product projects.
 - `.zsk/plans/`: ZSK plan artifacts, created lazily only when `zskplan` or `zsk` freezes an executable route.
 - `skills/{slug}/`: zsk source skill directories.
 - `harness/`: zsk source governance contracts.
@@ -29,22 +29,33 @@ stage repair, or task decomposition must be recorded in the nearest
 `CONTEXT.md`.
 
 - Module-local terms and decisions go to `.zsk/modules/{module}/CONTEXT.md`.
-- Cross-module or project-wide terms go to `.zsk/docs/CONTEXT.md`.
+- Cross-module or project-wide terms go to `.zsk/CONTEXT.md`.
+- `.zsk/docs/CONTEXT.md` may exist only as a deprecated mirror or migration compatibility path; do not write it as the canonical Context Record.
 - ZSK core terms go to the source repo `CONTEXT.md`.
 - If no update is needed, the stage handoff records a no-update rationale.
 - Do not use `CONTEXT.md` for transient notes, raw evidence, task execution
   logs, or unresolved speculation; record those in the owning artifact, issue,
   evidence directory, or learning proposal.
 
+## Path Privacy And Portability
+
+Project-facing ZSK artifacts must stay portable across machines and reviewers.
+
+- Use workspace-relative or repo-relative paths such as `.zsk/modules/{module}/design.md`, `src/components/...`, or configured `sourceRefs` in stage artifacts, Context Records, handoffs, archives, issues, and evidence summaries.
+- Do not write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs, especially proposal, spec, design, tasks, Context Records, and handoffs.
+- If an absolute local path is unavoidable for raw acquisition provenance, keep it inside raw/evidence metadata and also provide a portable alias such as `<workspace>/...`, `$HOME/...`, `.zsk/...`, or a repo-relative path.
+- Before finalizing or handing off a design/spec/task document, replace local machine paths with portable references and keep user names out of copied path strings unless the user explicitly requires audit provenance.
+
 ## Learning Output Authority
 
 Learning artifacts must be written according to what they are meant to change:
 
-- Project-local learning that only affects the current business/product project may use the current project's `.zsk/learning/proposals/`, created lazily.
-- Reusable ZSK core learning that would change ZSK skills, harness contracts, templates, packs, CLI behavior, defaults, or installer behavior must be written to the canonical ZSK source checkout: `<zsk-core>/.zsk/learning/proposals/`.
+- Project-specific delivery experience stays in the current project as module archives, `.zsk/docs/SYSTEM-SPEC.md` feedback, module `_issues`, or shared/global/public issue buckets.
+- Learning proposals always belong to the canonical ZSK source checkout: `<zsk-core>/.zsk/learning/proposals/`.
+- Consuming business/product projects must not create `.zsk/learning/` or `.zsk/learning/proposals/` for learn/archive output.
 - Resolve `<zsk-core>` from explicit configuration/environment first: `ZSK_LEARNING_REPO`, then `ZSK_CORE_REPO`. If neither is set, the current repository qualifies only when it contains `skills/`, `harness/`, and `packages/cli/`.
-- If no canonical ZSK source checkout is available or writable, do not create a substitute core-learning proposal in the consuming project. Record `BLOCKED` with the missing root, intended proposal title, source evidence, and next action.
-- `zsk init` must not create `.zsk/learning/`; learning directories remain lazy outputs created by `learn` or `archive` only when a concrete proposal is written.
+- If no canonical ZSK source checkout is available or writable, do not create a substitute learning proposal in the consuming project. Record `BLOCKED` with the missing root, intended proposal title, source evidence, and next action.
+- `zsk init` must not create `.zsk/learning/`; in non-ZSK projects the learn directory remains absent.
 
 ## Scope Routing Rule
 

package/acceptance/harness/constraints/issue-taxonomy.md

@@ -121,7 +121,7 @@ Every actionable issue should record:
 - suspected root cause and confidence;
 - affected spec/design/task/implementation/test artifact;
 - whether the fix needs Documentation Feedback in module docs;
-- whether a durable learning proposal is needed under `.zsk/learning/proposals`;
+- whether a durable ZSK learning proposal is needed under `<zsk-core>/.zsk/learning/proposals/`, or whether the finding should stay as project archive/docs feedback or an issue;
 - regression guard: test, scenario, lint rule, checklist, or explicit waiver.
 
 ## Issue-Driven Fix Route

package/acceptance/harness/constraints/skill-role-contract.md

@@ -33,19 +33,20 @@ Core skills and harness rules must be generic by default.
 - Detect source/provider behavior from `.zsk/config.yaml`, source URLs, local manifests, exports, and user-approved auth/session evidence.
 - When a provider is unsupported, prefer generic fetch, Playwright/browser capture, local export ingestion, or a clearly blocked adapter request rather than silently dropping the source.
 - If source-to-lane mapping is uncertain, record a question or blocker and ask before choosing. Do not invent that a URL is product, design, QA, backend, or UX without evidence.
+- Keep generated or curated project documents portable: proposal, spec, design, tasks, Context Records, handoffs, archives, issues, and evidence summaries must use repo-relative or `.zsk/...` paths instead of personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...`. Raw acquisition metadata may preserve absolute provenance only when paired with a portable alias.
 
 ## Learning Output Authority
 
-Learning output has two different authorities:
+Learning output has one proposal authority:
 
-- Project-specific delivery learning stays with the current project: module archives, `.zsk/docs/SYSTEM-SPEC.md`, module `_issues`, shared/global issue buckets, or project-local `.zsk/learning/proposals/` when the proposal only affects that project.
-- Reusable ZSK core learning belongs to the canonical ZSK source repository: `<zsk-core>/.zsk/learning/proposals/`, because it is intended to change ZSK skills, harness, templates, packs, CLI behavior, or defaults.
+- Project-specific delivery experience stays with the current project as module archives, `.zsk/docs/SYSTEM-SPEC.md`, module `_issues`, or shared/global issue buckets.
+- Learning proposals belong to the canonical ZSK source repository: `<zsk-core>/.zsk/learning/proposals/`, because learn output is intended to improve ZSK skills, harness, templates, packs, CLI behavior, defaults, or documented workflow guidance.
 
 Resolve `<zsk-core>` in this order:
 
 1. Explicit environment/configured root such as `ZSK_LEARNING_REPO` or `ZSK_CORE_REPO`.
 2. The current repository if it is recognizably the ZSK source repo, containing `skills/`, `harness/`, and `packages/cli/`.
-3. Otherwise `BLOCKED`: report the missing canonical ZSK source root and do not scatter reusable core-learning notes into the consuming project.
+3. Otherwise `BLOCKED`: report the missing canonical ZSK source root and do not scatter learning notes into the consuming project.
 
 ## Skill Responsibility Matrix
 
@@ -70,7 +71,7 @@ Each skill owns one stage contract. Workflow skills may route or schedule work,
 | `verify` | Independent replay, pass/fail decision, issue status update, regression evidence | Implementation, business acceptance, release changes | Verifies against ready/spec/AC with fresh evidence; hands decision to `acceptance` |
 | `acceptance` | Accept/reject decision, residual risk, business/user confirmation, documentation feedback | New verification, implementation fixes | Hands accepted state, waived risks, or rejection reasons to `archive` / `issue` |
 | `archive` | Final artifact preservation, closed issue audit, learning proposals, release notes | Changing delivered scope, reopening decisions without issue evidence | Preserves decisions/evidence and promotes reusable gaps to `learn` |
-| `learn` | Learning proposal intake, pattern comparison, optimization batch planning, reusable ZSK core proposal routing | Unreviewed mutation of core skills/harness/templates, scattering core learning into consuming projects | Writes project-local learning only for project-specific change; writes reusable core learning to canonical ZSK source repo proposals; requires review/regression before promotion |
+| `learn` | Learning proposal intake, pattern comparison, optimization batch planning, ZSK core proposal routing | Unreviewed mutation of core skills/harness/templates, scattering learning proposals into consuming projects | Writes learning proposals only to canonical ZSK source repo proposals; keeps project-specific delivery experience in archives/issues/docs; requires review/regression before promotion |
 | `issue` | Persistent issue/defect/risk/question records, indexes, owner/status/evidence fields, issue-driven fix ledger fields | Resolving the issue by assertion, replacing review/verify | Provides the shared feedback and closure ledger for all stages; issue-driven `fix` work remains open until smoke/review/verify evidence is linked |
 | `fix` | Issue-driven root-cause analysis, minimal correction route, regression guard, issue ledger update, smoke/review/verify handoff | Generic cleanup, new issue intake, broad redesign, independent verification or closure by assertion | Consumes a persisted issue or accepted expected/actual clarification; routes implementation through `coding` discipline and leaves closure to `verify` / `acceptance` |
 | `dispatch` | Runtime staffing plan, active roles, write scopes, evidence obligations, durable emit packets, packet status ledger | Business or technical stage output | Supports any stage skill from the resource pool; stale or delayed packets fall back to leader-sequential role simulation |
@@ -182,13 +183,15 @@ ZSK treats `CONTEXT.md` as durable project language, not chat memory. When a
 Clarification Prelude, Output Quality Check, architecture review, stage repair, or
 task decomposition creates or sharpens terminology, naming, module/decomposition
 rationale, accepted clarification, or a load-bearing "call this X, not Y"
-decision, the owning skill must update the nearest `CONTEXT.md` before handoff.
+decision, the owning skill must update the nearest Context Record target before
+handoff.
 
 Context targets:
 
 - module-local language and decomposition decisions:
   `.zsk/modules/{module}/CONTEXT.md`;
-- project-wide or cross-module language: `.zsk/docs/CONTEXT.md`;
+- project-wide or cross-module language: `.zsk/CONTEXT.md`;
+- deprecated project mirror during migration: `.zsk/docs/CONTEXT.md`;
 - reusable ZSK core language: the source repo `CONTEXT.md`.
 
 The update must separate accepted terms from rejected/ambiguous framings and
@@ -246,12 +249,23 @@ If a checkpoint repeatedly fails, the lead does not keep rewriting silently. It
 
 ```md
 - [ ] 1. <task group>
+  - Work item id: TASK-0001
+  - Status marker:
+    <!-- zsk-task-status:start TASK-0001 -->
+    - status: draft
+    - provider:
+    - provider_status:
+    - remote_id:
+    - updated_at:
+    <!-- zsk-task-status:end TASK-0001 -->
   - [ ] 1.1 <subtask>
   - [ ] 1.2 <subtask>
 ```
 
 Metadata belongs under the relevant checkbox item, not in a detached table alone. Each task group needs proposal/spec/design/ADR alignment, owner, dependencies, scope/files, expected output, evidence, and stop condition. Each subtask needs at least source ID, owner, scope/files, expected output, acceptance, and evidence. A task artifact without this hierarchy is not execution-ready.
 
+Provider-syncable task groups also need the stable `Work item id` and `zsk-task-status` marker block. Provider-syncable subtasks may declare their own `Work item id`; when omitted, `zsk work emit-tasks` derives a stable child id from the parent work item id and dotted subtask number, then emits a parent-child link event. Work status import may update only matching marker blocks, not surrounding task prose.
+
 ## Role Completeness
 
 Each skill run must cover its whole declared role:
@@ -348,11 +362,10 @@ For `DEEP` review, dispatch at least three independent expert lanes when subagen
 - ingest user-supplied public skill or harness references, including URLs, repos, markdown, examples, screenshots, or pasted excerpts;
 - compare external patterns against current ZSK contracts, source rights, project constraints, and regression needs;
 - record module-local delivery-impacting problems under module `_issues`, or outer `.zsk/issues/{shared|global|public}` only when the issue scope is not owned by one module;
-- classify the learning target as project-local, optional-pack, team-local, or reusable ZSK core before writing;
-- write project-local proposals under the current project's `.zsk/learning/proposals/` only when the proposal affects that project alone;
-- write reusable ZSK core proposals under the canonical ZSK source repo `.zsk/learning/proposals/`, resolved by `ZSK_LEARNING_REPO`, `ZSK_CORE_REPO`, or a recognized ZSK source checkout;
-- if the canonical ZSK source repo cannot be resolved or is not writable, report `BLOCKED` with the missing root, intended proposal name, evidence, and next action instead of writing core learning into the consuming project;
-- sync-check linked project-local and reusable core proposals together; if one side changes and the counterpart does not, record a no-update rationale in the edited proposal;
+- classify whether the learning should become a ZSK core proposal, optional-pack proposal, team convention, or project-local archive/issue/docs feedback before writing;
+- write learning proposals only under the canonical ZSK source repo `.zsk/learning/proposals/`, resolved by `ZSK_LEARNING_REPO`, `ZSK_CORE_REPO`, or a recognized ZSK source checkout;
+- keep project-specific delivery experience in the current project's archives, issues, or docs feedback; do not create `.zsk/learning/` in consuming projects;
+- if the canonical ZSK source repo cannot be resolved or is not writable, report `BLOCKED` with the missing root, intended proposal name, evidence, and next action instead of writing learning output into the consuming project;
 - group accepted proposals into one optimization batch with target files, regression prompts, risks, and review status.
 
 `learn` must not mutate core skills, harness constraints, packs, templates, or generated artifacts from one unreviewed incident. It must not copy external skills or harnesses wholesale; it adapts principles and testable constraints into ZSK proposals with source notes. Promotion requires review evidence and regression prompts.

package/acceptance/harness/constraints/stage-gates.md

@@ -61,7 +61,7 @@ The harness computes gate status. Skills may propose outputs and record evidence
   routed to the owning stage instead of silently renaming them.
 - The check must classify important claims as sourced, accepted, assumed, conflicting, missing, or N/A; it must name downstream consumer, required outputs, source links, blockers, and next action.
 - The owning stage may patch or split its own artifact when local/configured sources support the repair. If the missing fact belongs to an upstream stage, record upstream feedback or route to that stage.
-- Durable terminology, naming, decomposition rationale, and load-bearing clarification decisions found during the check must update the nearest `CONTEXT.md`, or the handoff must record `Context update: N/A` with rationale.
+- Durable terminology, naming, decomposition rationale, and load-bearing clarification decisions found during the check must update the nearest Context Record target (`.zsk/modules/{module}/CONTEXT.md`, `.zsk/CONTEXT.md`, or source repo `CONTEXT.md`), or the handoff must record `Context update: N/A` with rationale.
 
 ## Clarification Prelude
 
@@ -76,9 +76,21 @@ The harness computes gate status. Skills may propose outputs and record evidence
 - User-facing format is fixed: a `问题：` block containing only one clear question, then a separate `推荐：` block containing only the recommended answer.
 - After the user answers, the skill writes a separate `待写入确认表达：` block. If the user replies `ok`, `OK`, `是`, `对`, or `好`, treat it as confirmation. If the user corrects it, refine the same expression instead of moving to a new question.
 - A confirmed expression must be clear enough to write into the owning stage artifact: terminology consistent, stage/module boundary explicit, decision and non-goal clear, downstream stage directly reusable, and confirmation source traceable.
-- Confirmation is not chat memory. The owning skill writes the accepted expression to the linked `CLAR`, the owning stage artifact, and the nearest `CONTEXT.md` when the decision creates reusable terminology, naming, or module boundaries.
+- Confirmation is not chat memory. The owning skill writes the accepted expression to the linked `CLAR`, the owning stage artifact, and the nearest Context Record target when the decision creates reusable terminology, naming, or module boundaries.
 - After applying one confirmed expression, the current run performs the smallest useful gate validation and stops. The next clarification belongs to the next execution of the same owning stage skill.
 
+## Requirements Grilling Readiness Gate
+
+- Requirements grilling is the preproposal/proposal-specific use of Clarification Prelude. Its policy lives in `harness/contracts/requirements-grilling.yaml`.
+- `preproposal` is the primary grilling owner. It checks configured raws, module context, project rules, existing artifacts, and accepted Context Records before asking the user.
+- `proposal` is the consumer and escalator. It synthesizes from reviewed preproposal/raw-source material when possible and routes back only for high-impact requirements gaps.
+- High-impact ambiguity blocks and asks one question: target user/stakeholder, problem/outcome, scope boundary, success criteria, mutually exclusive direction, source authority conflict, or risk acceptance owner.
+- Medium-impact ambiguity may continue with an accepted recommendation or explicit assumption. Low-impact ambiguity is recorded as an assumption or follow-up and must not block downstream work.
+- Each run asks at most one user-facing question. The question must include a separate recommendation and tradeoff, then stop for the answer.
+- A high-impact grilling loop defaults to at most three rounds. If the question remains unresolved, create or update a tracked blocker with owner, missing input, impact, and next action instead of looping indefinitely.
+- The readiness handoff must preserve accepted clarifications, assumptions, open questions, source gaps, blockers, and Context Record updates so proposal does not depend on chat memory.
+- Accepted reusable grilling consensus is not complete while it lives only in chat or a transient handoff. If it changes terminology, naming, module boundary, scope boundary, non-goal, acceptance standard, source authority, or risk owner, `preproposal` must write it to the nearest Context Record target before handoff; otherwise the handoff must state `Context update: N/A` with rationale.
+
 ## Preproposal Checkpoint Gate
 
 - Use `preproposal` when a brief request lacks reviewed product direction, roadmap/decomposition, UX/design-readiness, or source-readiness material for `proposal`.

package/acceptance/harness/contracts/dispatch-runtime.yaml

@@ -0,0 +1,119 @@
+version: 1
+owner: harness
+purpose: >
+  Make subagent and provider-lane dispatch auditable without making the
+  workflow depend on any single runtime. Dispatch selects bounded execution
+  lanes; the selected stage skill still owns the artifact and completion claim.
+
+principles:
+  - dispatch is optional acceleration, not a stage-output owner
+  - every emitted lane has durable packet metadata and a status file
+  - pending, stale, blocked, failed, or timed-out packets cannot satisfy completion evidence
+  - native subagents, OMX lanes, provider lanes, and leader-sequential fallback share the same packet schema
+  - unavailable subagent surfaces produce a leader-sequential fallback record, not a workflow failure by themselves
+  - fallback preserves the same role, write scope, inputs, outputs, and evidence obligations
+
+surfaces:
+  auto:
+    meaning: Runtime chooses native-subagent, OMX, provider-lane, or sequential from project policy and availability.
+    mayDispatch: true
+  native-subagent:
+    meaning: Codex native child agents execute bounded independent lanes.
+    mayDispatch: true
+  omx:
+    meaning: OMX runtime lanes execute bounded independent packets.
+    mayDispatch: true
+  provider-lane:
+    meaning: External configured provider executes or tracks bounded packets through adapter events.
+    mayDispatch: true
+  sequential:
+    meaning: The leader executes the same role obligations without parallel runtime support.
+    mayDispatch: false
+
+requiredArtifacts:
+  - .zsk/evidence/dispatch/{run}/staffing-plan.json
+  - .zsk/evidence/dispatch/{run}/staffing-plan.md
+  - .zsk/evidence/dispatch/{run}/emit-packets.jsonl
+  - .zsk/evidence/dispatch/{run}/emit-ledger.json
+  - .zsk/evidence/dispatch/{run}/packet-status/
+
+staffingPlan:
+  requiredFields:
+    - runId
+    - stage
+    - skill
+    - module
+    - surface
+    - orchestration
+    - lanes
+  laneRequiredFields:
+    - packetId
+    - role
+    - writeScope
+    - requiredInputs
+    - requiredOutputs
+    - evidenceObligations
+    - heartbeatDeadline
+    - timeoutPolicy
+    - fallbackRoute
+    - statusPath
+
+packetStatus:
+  allowed:
+    - planned
+    - emitted
+    - running
+    - completed
+    - blocked
+    - failed
+    - stale
+    - waived
+    - fallback-ready
+    - fallback-completed
+  requiredFields:
+    - packetId
+    - status
+    - owner
+    - evidenceRefs
+    - fallbackRoute
+    - updatedAt
+  completionStatuses:
+    - completed
+    - fallback-completed
+    - waived
+  nonCompletionStatuses:
+    - planned
+    - emitted
+    - running
+    - blocked
+    - failed
+    - stale
+    - fallback-ready
+
+completionRules:
+  - every emitted packet must have a packet-status file
+  - completed or fallback-completed packets must include evidenceRefs
+  - waived packets must include riskAcceptance and owner
+  - stale, failed, blocked, or fallback-ready packets must include fallbackRoute and nextAction
+  - pending packet states cannot be counted as stage or workflow completion evidence
+  - leader-sequential fallback must preserve the original lane's role, writeScope, requiredInputs, requiredOutputs, and evidenceObligations
+  - dispatch evidence can support review and verify, but cannot replace smoke, review, verify, or acceptance artifacts
+
+stageOwnership:
+  dispatchMay:
+    - select roles and lanes
+    - declare write scopes and evidence obligations
+    - emit packets and local work assignment events
+    - mark stale packets and choose fallback route
+  dispatchMustNot:
+    - decide product scope
+    - write proposal/spec/design/task artifacts as dispatch output
+    - treat a provider status as verification proof
+    - let delayed packets block indefinitely
+
+qualityGates:
+  - completion-contract lists all required dispatch artifacts
+  - skill-io dispatch outputs include durable ledger and packet status files
+  - quality standards require fallback when subagents or OMX surfaces are unavailable
+  - examples include completed and stale/fallback packet paths
+  - provider-lane metadata remains adapter-specific and does not change packet schema