@captain_z/zsk-skills 1.8.0 → 1.8.2

package/README.md

@@ -101,9 +101,9 @@ flowchart TD
 
 ## 和项目知识工作区的关系
 
-`zsk init` 生成的 `.zsk/config.yaml`、`.zsk/docs/SYSTEM-SPEC.md`、`.zsk/resources/`、`.zsk/modules/`、`.zsk/issues/`、`.zsk/evidence/`、`.zsk/playwright/` 和 `.zsk/plans/` 是默认项目上下文。CLI 负责创建最小骨架、使用 package-owned schema 校验、刷新 `.zsk/resources/manifest.json`，并通过 `zsk config check` / `zsk check` 做确定性校验。
+`zsk init` 生成的 `.zsk/config.yaml`、`.zsk/docs/SYSTEM-SPEC.md`、`.zsk/raws/`、`.zsk/modules/`、`.zsk/issues/`、`.zsk/evidence/`、`.zsk/playwright/` 和 `.zsk/plans/` 是默认项目上下文。CLI 负责创建最小骨架、使用 package-owned schema 校验、刷新 `.zsk/raws/manifest.json`，并通过 `zsk config check` / `zsk check` 做确定性校验。
 
-Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Modao、测试资产和设计资产，发现模块边界，做跨事实源冲突分析，并把问题写入配置的 issue 根。运行时验证默认用 Playwright 产生可复现 evidence；登录态优先转成 Playwright `storageState`；视觉/当前页面判断优先 Computer Use；没有 Computer Use 的运行时用 Playwright MCP/ARIA/CDP、手工证据或可用的 Browser Use 兼容处理。Skills 必须通过 `.zsk/config.yaml` 和 `.zsk/modules/{module}/module.yaml` 解析路径，不能硬编码 `.zsk/resources`、root `docs`、root `.issues`、root `.playwright` 或 root `plans`。
+Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Modao、测试资产和设计资产，发现模块边界，做跨事实源冲突分析，并把问题写入配置的 issue 根。运行时验证默认用 Playwright 产生可复现 evidence；登录态优先转成 Playwright `storageState`；视觉/当前页面判断优先 Computer Use；没有 Computer Use 的运行时用 Playwright MCP/ARIA/CDP、手工证据或可用的 Browser Use 兼容处理。Skills 必须通过 `.zsk/config.yaml` 和 `.zsk/modules/{module}/module.yaml` 解析路径，不能硬编码 `.zsk/raws`、root `docs`、root `.issues`、root `.playwright` 或 root `plans`。
 
 每个 skill/stage 的输入、输出、工具/能力、脚本策略和运行时 UI 观察策略由 harness 的 `skill-io-contract.yaml` 约束；完成后的产物路径、issue 索引同步和确认后的文档反哺由 `completion-contract.yaml` 约束。缺少 Documentation Feedback 时，`zsk check` 可以把它作为阶段未收口的证据。
 

package/acceptance/SKILL.md

@@ -13,6 +13,26 @@ category: stage
 tier: core
 triggers:
   - acceptance
+useWhen:
+  - "Use when the workflow is ready for this responsibility: After independent
+    verify passes, records accept/reject decision, linked evidence, and
+    residual-risk owner."
+  - Use when the user invokes zsk:acceptance or asks for acceptance outputs
+    after prerequisites are present.
+doNotUseWhen:
+  - Do not use when required inputs, prior-stage evidence, or configured sources
+    for acceptance are missing.
+  - Do not use to bypass stage gates, perform another skill's responsibility, or
+    make unsupported completion claims.
+positiveExamples:
+  - Run zsk:acceptance with the required inputs and produce the documented
+    acceptance artifacts.
+  - Run this skill only for its owned outputs after prerequisites are present;
+    let workflow skills decide subsequent stage routing.
+negativeExamples:
+  - Use zsk:acceptance to skip missing prerequisites or hide unresolved blockers.
+  - Run acceptance for generic chat, unrelated implementation, or another ZSK
+    stage's work.
 ---
 
 # Acceptance
@@ -59,17 +79,21 @@ This core skill is governed by the ZSK harness. Enforce these rules even when on
 - Source of truth: read configured resources before inventing intent; record conflicts instead of choosing silently.
 - Issue taxonomy: route demo, smoke, review, test, verify, and acceptance findings to the correct issue type.
 - Skill role: execute the full expert role, including all relevant lanes; partial single-angle execution is a failing result.
+- 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.
+- 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.
 - 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.
 
 When a `harness/` directory is installed beside this file, treat it as the local contract source:
 
 - Read `harness/THIS_SKILL.md` before executing this skill.
 - 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/constraints/skill-role-contract.md` before planning or reviewing expert work.
 - Read `harness/constraints/filesystem-boundaries.md` before creating any project artifact.
 - 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 only when they are listed for the current skill. If those references are insufficient, stale, or version-sensitive, prefer Context7 MCP when available; otherwise consult official/current web references and local package docs/types. Record source links plus adaptation rationale in the evidence or learning proposal.
+- 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

@@ -35,11 +35,55 @@ This file is generated for the installed skill. Read it before executing this sk
 - `documentation feedback`
 - `accept/reject evidence`
 
+## Collaboration Discipline
+
+- Own only this skill's required outputs; do not redefine upstream artifacts or approve downstream work on another skill's behalf.
+- Before handoff, confirm required inputs were consumed, outputs are complete or explicitly BLOCKED, and the next consumer can act without chat memory.
+- If another stage is missing, stale, contradictory, or under-specified, record a blocker, issue, or documentation feedback instead of silently fixing it inside this skill.
+
+## Best-Practice Baseline
+
+- Judge lifecycle function, not terminology: accept equivalent project artifacts only when they satisfy the same responsibility, handoff, and evidence need.
+- 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.
+- For each required output or finding, name owner, dependency, acceptance condition, verification evidence, and next action.
+
+## Document Quality Standard
+
+- Document mode: `decisionRecord`
+- Purpose: Record the accept/reject business decision and residual-risk ownership.
+
+## Must Answer
+
+- Is the verified work accepted, rejected, or conditionally accepted?
+- Which evidence and issues support the decision?
+- Who owns residual risks and documentation feedback?
+
+## Quality Checkpoints
+
+- Names the reader, stage, scope, and stop condition.
+- Separates facts, decisions, assumptions, open questions, and evidence.
+- Links each important claim to a source artifact, command output, issue, scenario, or human decision.
+- States what is out of scope so later stages do not silently expand work.
+- Makes the next stage executable without requiring hidden context from chat.
+- Includes a Project Rules Gate that cites PROJECT-CONFIG.md and SYSTEM-SPEC.md constraints, impacts, and blockers.
+- Confirms upstream/downstream consistency before handoff: inputs consumed, outputs complete or blocked, and next consumer can act without chat memory.
+- Accepts different project methods and artifact names only when they provide an equivalent control point with evidence.
+- Uses PASS, FAIL, BLOCKED, or N/A only with evidence; missing mandatory evidence remains a failure, not an assumption.
+- Records numeric targets or thresholds as `未指定` when the project has not supplied them; never invents thresholds to make an output look complete.
+- Names owner, dependency, acceptance condition, and verification evidence for every required output or blocker.
+- Runs or references the stage-entry quality gate before downstream handoff; below-threshold but non-blocking gaps require explicit risk acceptance instead of silent progression.
+- For testable work, verifies test correctness, not only test execution: traceable test basis, meaningful assertions, negative/boundary/regression coverage, and skipped/unrun checks called out.
+- Links verify report, demo evidence, accepted criteria, and residual risks.
+- Records documentation feedback or no-update rationale for confirmed learnings.
+
 ## Related Best-Practice Concerns
 
 - `SDLC traceability`
 - `quality evidence`
 - `system constraints`
+- `dynamic state awareness`
 
 ## Bundled Related Reference Files
 
@@ -53,6 +97,22 @@ This file is generated for the installed skill. Read it before executing this sk
 - `silently skipping required inputs or expert lanes`
 - `mutating core harness/templates/skills without a learning proposal and review`
 
+## Document Anti-Patterns
+
+- Template-shaped filler that does not resolve a decision.
+- Skipping PROJECT-CONFIG.md or SYSTEM-SPEC.md, or treating their project rules as optional suggestions.
+- Untraceable claims such as 'should work', 'best practice', or 'user friendly' without evidence or criteria.
+- Mixing raw source facts, decisions, runtime evidence, and tasks in one undifferentiated section.
+- Skipping unresolved contradictions instead of recording a blocker, risk, or question.
+- Optimizing wording while leaving acceptance, evidence, ownership, or next action ambiguous.
+- Passing because a familiar term appears while the equivalent lifecycle function is absent.
+- Inventing project policy, quality thresholds, source mappings, or platform behavior without configured evidence.
+- Treating missing evidence as low risk when the stage output depends on that evidence.
+- 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.
+- Letting residual risks remain ownerless.
+
 ## Must Read Before Acting
 
 - `profiles/*.yaml` to apply the active workflow profile before enforcing optional gates.
@@ -66,7 +126,9 @@ This file is generated for the installed skill. Read it before executing this sk
 - `constraints/issue-taxonomy.md` before creating defects, blockers, risks, or questions.
 - `best-practices/sdlc.md` when its domain is touched by this task.
 - `best-practices/quality.md` when its domain is touched by this task.
-- Context7 MCP when available for version-sensitive library/API/framework guidance; otherwise official/current web references and local package docs/types when bundled related references are missing, incomplete, stale, or too generic for the concrete stack. Record source links and adaptation rationale.
+- Dynamic state awareness before role work: identify the stage, role, project type, stack, runtime tools, domain, target users/market, freshness-sensitive decisions, and missing evidence.
+- Local-first best practices and facts: use configured sources, raw manifests, bundled references, local package docs/types, lockfiles, and existing project conventions when they are sufficient and current.
+- Context7/web fallback 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.
 
 ## Hard Stops
 

package/acceptance/harness/best-practices/README.md

@@ -4,7 +4,7 @@ These references are bundled only for `acceptance` so standalone skill installs
 
 They are supporting guidance, not the source of truth. Runtime gates and hard constraints belong in `../THIS_SKILL.md` and `../constraints/`.
 
-If these references are missing, incomplete, stale, too generic, or version-sensitive for the concrete stack, prefer Context7 MCP when available. If Context7 is unavailable or incomplete, consult official/current web references and local package docs/types. Record source links plus adaptation rationale in the evidence or learning proposal.
+Use these local references first when they are sufficient and current. If they are missing, incomplete, stale, too generic, version-sensitive, market-sensitive, or not matched to the active role/stage, use dynamic state awareness to choose the smallest useful retrieval path: Context7 MCP for library/framework guidance when available, official/current web references for technical facts, and authoritative current sources for product/market research. Record source links, source dates when relevant, and adaptation rationale in the evidence or learning proposal.
 
 Bundled files:
 

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

@@ -5,12 +5,39 @@ 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/modules/{module}/`: module config and stage artifacts.
-- `.zsk/resources/`: raw external source snapshots, manifests, imported test cases, and design/API assets.
-- `.zsk/issues/`: normalized managed issue records and indexes.
-- `.zsk/evidence/`: reusable runtime evidence that is not Playwright-owned.
-- `.zsk/playwright/{module}/`: Playwright specs, test plans, auth state, execution records, reports, and results.
-- `.zsk/plans/`: ZSK Plan artifacts, loop plans, and execution handoff plans.
+- `.zsk/raws/`: raw external source snapshots, manifests, imported test cases, market/product research sources, and design/API assets.
+- `.zsk/modules/{module}/_issues/`: module-private managed issue records and indexes, created on demand.
+- `.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.
 - `skills/{slug}/`: zsk source skill directories.
 - `harness/`: zsk source governance contracts.
 
 Root `docs/`, `.raws/`, `.issues/`, `.playwright/`, and `plans/` are not default write targets for ZSK skills. Use explicit export, promote, import, or migration commands when project-facing root documentation is needed.
+
+## 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/`.
+- 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.
+
+## Scope Routing Rule
+
+Before any skill writes an artifact, classify its scope:
+
+| Scope | Meaning | Default target |
+| --- | --- | --- |
+| module-final | Formal stage output for one module | `.zsk/modules/{module}/` |
+| module-private | Working, runtime, evidence, issue, or generated artifact for one module | `.zsk/modules/{module}/_{kind}/` |
+| shared | Reused by multiple modules but not public-facing | `.zsk/{kind}/shared/` or the configured shared root |
+| global | Project-wide artifact with no owning module | `.zsk/{kind}/global/` or `.zsk/docs/` for formal docs |
+| public | Intentionally publishable/exportable artifact | `.zsk/{kind}/public/` until explicitly exported |
+
+This rule applies to every underscore module directory, not only `_issues`. For example, module-local issues go to `_issues`, module-local runtime evidence goes to `_evidence`, and module-local Playwright specs/auth/results go to `_playwright`. Use outer `.zsk/issues`, `.zsk/evidence`, or `.zsk/playwright` only after deciding the artifact is shared, global, or public. When scope is ambiguous, prefer module-private and record the reason or blocker before promoting outward.
+
+The skill that produces the final artifact for a module stage writes the formal report to `.zsk/modules/{module}/{stage}.md`. Supporting artifacts stay in the appropriate `_issues`, `_evidence`, or `_playwright` directory unless they are deliberately shared/global/public.

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

@@ -2,28 +2,39 @@
 
 `zsk:issue` is the cross-stage issue utility. Stage skills call it, but issue paths and fields are defined here.
 
-Issue records are persistent tracking artifacts. Use the configured issue root from `.zsk/config.yaml` `paths.issues`; the default is `.zsk/issues/`. Do not keep actionable findings only in chat, transient task notes, or demo reports.
+Issue records are persistent tracking artifacts. Module-specific findings default to the module-private `.zsk/modules/{module}/_issues/` directory. Use the configured issue root from `.zsk/config.yaml` `paths.issues` only for shared/global or intentionally cross-module issues; the default shared root is `.zsk/issues/`. Do not keep actionable findings only in chat, transient task notes, or demo reports.
+
+Issue placement must follow the same scope routing rule as every other underscore artifact:
+
+| Issue scope | Use when | Directory |
+| --- | --- | --- |
+| module | One module owns the finding, fix, and verification | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` |
+| shared | Multiple modules reuse the same issue, fixture, dependency, or evidence chain | `.zsk/issues/shared/{prefix}-0001-slug/` |
+| global | Project/process/release/harness issue has no single owning module | `.zsk/issues/global/{prefix}-0001-slug/` |
+| public | Issue is intentionally publishable or external-facing | `.zsk/issues/public/{prefix}-0001-slug/` |
+
+When an issue starts shared/global/public and later gets assigned to one module, move or link it into that module's `_issues` directory and leave a backlink in the outer issue record. When a module issue becomes cross-module, promote it to the appropriate outer scope and leave a backlink in the original module issue.
 
 Indexes are part of the contract:
 
-- `.zsk/issues/{module}/index.md` tracks every issue for that module and its status.
-- `.zsk/issues/index.md` tracks each module and total/open/closed issue counts.
+- `.zsk/modules/{module}/_issues/index.md` tracks every issue for that module and its status.
+- `.zsk/issues/index.md` tracks each module and total/open/closed issue counts across module-private and shared issues.
 - Creating or updating an issue must refresh both indexes.
 
 ## Types
 
 | Type | Concrete Issue Directory | Prefix | Typical Source |
 | --- | --- | --- | --- |
-| Demo Issue | `.zsk/issues/{module}/{prefix}-0001-slug/` | `DEMO` | Development demo |
-| Smoke Issue | `.zsk/issues/{module}/{prefix}-0001-slug/` | `SMOKE` | Developer smoke |
-| Review Issue | `.zsk/issues/{module}/{prefix}-0001-slug/` | `REV` | Code/design review |
-| Defect | `.zsk/issues/{module}/{prefix}-0001-slug/` | `DEFECT` | Formal QA |
-| Verify Issue | `.zsk/issues/{module}/{prefix}-0001-slug/` | `VER` | Fix verification |
-| Acceptance Issue | `.zsk/issues/{module}/{prefix}-0001-slug/` | `ACC` | Business/product acceptance |
+| Demo Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `DEMO` | Development demo |
+| Smoke Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `SMOKE` | Developer smoke |
+| Review Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `REV` | Code/design review |
+| Defect | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `DEFECT` | Formal QA |
+| Verify Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `VER` | Fix verification |
+| Acceptance Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `ACC` | Business/product acceptance |
 
-Stage directories such as `.zsk/issues/{module}/demo/index.md` may exist as stage views or evidence buckets. They are not the authoritative status indexes.
+Stage directories such as `.zsk/modules/{module}/_issues/demo/index.md` may exist as stage views or evidence buckets. They are not the authoritative status indexes.
 
-If `paths.issues` is customized, it must still stay under `.zsk/` and preserve the `{module}/{type}/` shape.
+If `paths.issues` is customized, it must still stay under `.zsk/` and is reserved for shared/global or cross-module issue records. Module-private issue paths remain under `.zsk/modules/{module}/_issues/`.
 
 ## Required Fields
 
@@ -79,7 +90,7 @@ Every actionable issue should record:
 
 ## Closure And Feedback Loop
 
-1. Create or update the issue under `.zsk/issues/{module}/` as soon as the finding is actionable, using the type and prefix fields to preserve taxonomy.
+1. Create or update module-specific issues under `.zsk/modules/{module}/_issues/` as soon as the finding is actionable, using the type and prefix fields to preserve taxonomy.
 2. Fix and verify the issue with linked evidence.
 3. Wait for user/product confirmation when the outcome changes behavior, business flow, or acceptance semantics.
 4. After confirmation, update the relevant spec/design/task docs for anything the original artifacts did not cover or described too weakly.

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

@@ -2,6 +2,107 @@
 
 Every ZSK skill is an expert role, not a loose prompt. Before acting, the skill must identify its responsibility, required inputs, required outputs, forbidden scope, expert checks, and evidence obligations from `harness/THIS_SKILL.md`, `workflow/skill-io-contract.yaml`, and this file.
 
+## Method-Neutral Best-Practice Baseline
+
+ZSK skills must work across project types, team methods, tools, and platforms. A skill must judge the lifecycle function, not the label.
+
+- Equivalent artifacts are accepted only with evidence. For example, a project may use use cases instead of user stories, an architecture note instead of a formal C4 diagram, or a release checklist instead of a named release skill, but the artifact must still satisfy the same responsibility and handoff need.
+- Missing mandatory artifacts, mandatory evidence, required owners, required gates, or required downstream-consumable outputs are `FAIL` or `BLOCKED`, not a soft recommendation.
+- Numeric thresholds, quality bars, SLOs, coverage targets, or business targets that are not supplied by project config, docs, or accepted decisions must be written as `未指定`. A skill may propose suggested values separately, but must not present them as current policy.
+- Every required output or finding needs an owner, dependency, acceptance condition, verification evidence, and next action.
+- Security, privacy, data safety, release readiness, test traceability, and continuous improvement are lifecycle concerns. They are N/A only when the project context proves they do not apply.
+
+## Cross-Project Portability Rule
+
+Core skills and harness rules must be generic by default.
+
+- Do not hardcode Jira, Confluence, Figma, GitHub, GitLab, Linear, Notion, browser tooling, design tooling, or any provider as the only valid path.
+- 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.
+
+## Learning Output Authority
+
+Learning output has two different authorities:
+
+- 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.
+
+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.
+
+## Skill Responsibility Matrix
+
+Each skill owns one stage contract. Workflow skills may route or schedule work, but ordinary stage skills must not hardcode the next stage, redefine upstream facts, or accept downstream work on behalf of another skill.
+
+| Skill | Owns | Does Not Own | Consistency / Handoff |
+| --- | --- | --- | --- |
+| `prepare` | Source discovery, configured origin validation, raws snapshots, manifest, source gaps | Product interpretation, requirements decisions, design choices | Hands source manifest, raws indexes, conflicts, and blockers to `proposal` / `spec`; asks before uncertain source-to-lane mapping |
+| `proposal` | Problem, goal, scope, non-goals, stakeholders, risks, success metrics, decision request | Detailed behavior, architecture, task breakdown, implementation | Every goal and metric must trace to sources or accepted assumptions; hands bounded scope to `spec` |
+| `spec` | FR/NFR, acceptance criteria, scenarios, edge cases, constraints, traceability | Architecture, file/module design, implementation tasks | Every P0/P1 requirement must trace to proposal/source and be testable; hands behavior contract to `design` and `task` |
+| `design` | Architecture, interfaces, data/state flow, design views/diagrams, ADRs or equivalent decisions, tradeoffs, rollout and verification surfaces | Rewriting requirements, task sequencing, coding, decorative diagrams | Every design decision and diagram must trace to spec/AC/NFR, ADR, risk, or verification need; hands implementation map to `task` |
+| `task` | Kiro-style nested checkbox task groups/subtasks, owners, dependencies, scope/files, evidence hooks, coverage matrix | Changing proposal/spec/design intent, coding, review approval | Every task group must align to proposal/spec/design IDs; every subtask must be executable and evidence-backed before `coding` |
+| `coding` | Scoped implementation, changed tests, implementation notes, local validation evidence | Requirements changes, broad refactors, final approval | Every diff maps to task IDs and preserves upstream intent; hands changed files and evidence to `smoke` / `review` |
+| `smoke` | Smallest credible local proof of changed behavior, failure classification, smoke issues | Full acceptance, final verification, release approval | Hands command/scenario evidence and failures to `review`, `defect`, or `ready` |
+| `review` | Scope drift, correctness, maintainability, security, test adequacy, harness compliance findings | Implementing fixes, independent verification, business acceptance | Findings must reference files/artifacts and route fix work to `issue` / `defect` / `coding`; no PASS without evidence adequacy |
+| `commit` | Scoped staging, Lore commit message, commit evidence, known verification gaps | Feature validation, release readiness | Hands immutable change intent and tested/not-tested evidence to `deploy` / `archive` |
+| `deploy` | Release target, deployment command, environment/version, health checks, rollback owner | Product acceptance, postmortem, unrelated infra changes | Hands runtime URL/version, smoke evidence, and rollback path to `demo`, `verify`, or `archive` |
+| `demo` | Source-backed user-visible flow rehearsal, scenario evidence, demo issues | Formal testing, acceptance, invented flows | Consumes spec/design/task case skeletons; routes gaps to `defect` or upstream docs feedback |
+| `defect` | Reproducible defect records, severity, dedupe, fix route | Fix implementation, broad redesign | Links failures to FR/AC/evidence and hands fix route to `coding` / `ready` |
+| `ready` | Verification handoff, issue-evidence matrix, exact claim and version | Fixing defects, independent pass/fail decision | Hands replayable claims and evidence paths to `verify` |
+| `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 |
+| `issue` | Persistent issue/defect/risk/question records, indexes, owner/status/evidence fields | Resolving the issue by assertion, replacing review/verify | Provides the shared feedback and closure ledger for all stages |
+| `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 |
+| `flow` | Next legal stage decision from state, resources, blockers, profile, and stage-entry quality assessment | Stage artifact production | Routes only when gates allow; reports blockers or quality-confirmation needs instead of forcing progression |
+| `zskplan` | Route freeze, selected skills, output map, expert lane plan, evidence plan, blockers | Implementation and verification | Produces the plan contract that `zsk` executes |
+| `zsk` | End-to-end execution loop, skill dispatch, expert lane integration, validation/fix loop | Skipping selected skill contracts or evidence gates | Executes the frozen or inferred route until complete or blocked |
+
+## Collaboration Consistency Gate
+
+Before a skill reports `PASS`, `READY`, `DONE`, or an unblocked handoff, it must prove the following chain remains intact:
+
+```text
+prepare sources
+-> proposal goals / scope / success metrics
+-> spec FR / AC / NFR / scenarios
+-> design decisions / ADRs / interfaces / data flow
+-> task checkbox groups / subtasks / evidence hooks
+-> coding diff / changed tests
+-> smoke or demo evidence
+-> review findings
+-> ready claim
+-> verify result
+-> acceptance decision
+-> archive / learn
+```
+
+Consistency checks:
+
+- Upstream input exists, is current enough for the decision, and is explicitly referenced.
+- Current-stage required outputs are complete or marked `BLOCKED` with owner, missing input, impact, and next action.
+- Downstream consumers can use the output without hidden chat memory.
+- Facts, decisions, assumptions, open questions, and evidence are separated.
+- No skill silently changes another skill's artifact; it records a feedback item, issue, or blocker instead.
+- Workflow skills (`flow`, `zskplan`, `zsk`) choose the route. Stage skills state status, blockers, handoff needs, and next legal candidates only.
+
+## Kiro-Style Task Handoff
+
+`task` must use nested Markdown checkboxes as the primary execution surface:
+
+```md
+- [ ] 1. <task group>
+  - [ ] 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 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.
+
 ## Role Completeness
 
 Each skill run must cover its whole declared role:
@@ -9,8 +110,11 @@ Each skill run must cover its whole declared role:
 - read the required inputs or report `BLOCKED`;
 - produce every required output or explain why it is blocked;
 - apply the related best-practice files listed in `THIS_SKILL.md` when their domain is touched;
-- prefer Context7 MCP for version-sensitive library/API/framework guidance when available; if it is unavailable or incomplete, consult official/current web references and local package docs/types, then record source links and adaptation rationale;
+- run dynamic state awareness for the active role/stage: identify local project facts, stack, runtime, domain, target users, market context, freshness-sensitive decisions, and missing evidence before selecting practices or sources;
+- prefer local configured sources and bundled references when they are sufficient, current, and specific;
+- use Context7 MCP or official/current web references only when local references are missing, incomplete, stale, too generic, version-sensitive, market-sensitive, or role-incomplete; record source links, source dates when relevant, and adaptation rationale;
 - keep all ZSK-managed artifacts under `.zsk` paths from the completion contract;
+- classify artifact scope before writing: module-final, module-private, shared, global, or public;
 - state which checks were performed and which were intentionally waived.
 
 Partial execution is a failure. A skill must not pass after checking only one convenient angle when its role requires multiple angles.
@@ -18,8 +122,11 @@ Partial execution is a failure. A skill must not pass after checking only one co
 ## Forbidden Behavior
 
 - Do not create new project roots, ad hoc docs folders, loose evidence folders, or hidden state outside `.zsk`.
+- Do not write module-private working artifacts to outer `.zsk/issues`, `.zsk/evidence`, or `.zsk/playwright` without a shared/global/public scope decision.
 - Do not skip a declared input because it is inconvenient to locate.
 - Do not collapse a multi-lane expert task into a single generic pass.
+- Do not search the web when local evidence is already sufficient and current for the decision.
+- Do not treat market reports, competitor pages, or best-practice articles as product requirements; use them as evidence and recommendations unless accepted into PRD/spec.
 - Do not silently cross into another skill's responsibility; route or record the handoff.
 - Do not claim PASS, READY, DONE, or ACCEPTED without linked evidence.
 
@@ -29,6 +136,19 @@ When a skill has multiple expert concerns, it must execute all relevant lanes. I
 
 The lead skill remains accountable for the final verdict. Subagent output is supporting evidence, not an automatic pass.
 
+## Product / Research Minimum
+
+Proposal, BRD, product-manager, and product-research work must cover all relevant research lanes before recommending direction:
+
+- problem/value hypothesis and target customer;
+- market size, growth, geography, segment, and timing when the decision depends on external demand;
+- user personas, JTBD, pains, willingness to pay, and adoption constraints;
+- competitor/substitute analysis, positioning, differentiation, and pricing references;
+- regulatory, platform, operational, data, or go-to-market risks when touched;
+- confidence, source freshness, gaps, and what would change the recommendation.
+
+Use local SRS/PRD/customer notes first. If they are absent, stale, or insufficient for the proposal decision, retrieve current authoritative sources and cite the source date. The output must separate sourced findings, inferred recommendations, and unresolved assumptions.
+
 ## Review-Specific Minimum
 
 `review` must always cover these lanes before a PASS verdict:
@@ -51,8 +171,11 @@ For `DEEP` review, dispatch at least three independent expert lanes when subagen
 - `zskplan` freezes the route and writes the plan artifact under `.zsk/plans/`: selected skills, required inputs, `.zsk` output map, expert lanes, subagent plan, Playwright/auth/evidence plan, fix loop, blockers, and stop condition.
 - `zsk` executes the frozen or inferred route: it selects the legal skill, dispatches required expert lanes, integrates results, writes only `.zsk` artifacts, validates, fixes, and repeats until the plan is complete or blocked.
 - Neither entry point may skip a selected skill's own contract, forbidden scope, required inputs, issue routing, or evidence gate.
+- Before entering a downstream stage, the workflow must evaluate required upstream artifact quality or record why the gate is N/A. Below-threshold quality gaps require an explicit risk acceptance; missing mandatory artifacts remain blocked.
+- Every emitted subagent packet must be durable: `runId`, `packetId`, heartbeat/deadline policy, status path, write scope, evidence obligation, stop condition, and fallback route. Stale packets must be completed by fallback evidence or re-emitted; they cannot count as completed work.
 - When no frozen route exists, `zsk` must perform the `zskplan` route-freeze work first and state the resulting plan.
 - Plans, Playwright specs, auth state, runtime execution JSON, traces, reports, reusable evidence, issues, and learning proposals must use the configured `.zsk` workspace paths.
+- Module-local runtime/supporting artifacts use module-private `_issues`, `_evidence`, and `_playwright`; shared, global, or public artifacts use the corresponding outer `.zsk/{kind}` scope bucket.
 - A ZSK loop may not stop at "implemented" when review, Playwright, test, or configured validation evidence is required by the plan.
 
 ## Learning Skill
@@ -62,8 +185,11 @@ For `DEEP` review, dispatch at least three independent expert lanes when subagen
 - collect suggestions and evidence from user feedback, failed runs, review misses, and harness friction;
 - 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 delivery-impacting problems as `.zsk/issues` entries;
-- write reusable improvement proposals under `.zsk/learning/proposals/`;
+- 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;
 - 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/source-of-truth.md

@@ -4,7 +4,7 @@ Resource priority is:
 
 1. explicit project `.zsk/config.yaml`
 2. module docs and stage artifacts under `.zsk/modules/{module}/`
-3. raw source snapshots under `.zsk/resources/`
+3. raw source snapshots under `.zsk/raws/`
 4. code and runtime evidence
 5. user-provided clarification
 
@@ -17,14 +17,17 @@ When sources conflict, the stage artifact must record the conflict instead of si
 - If the facts are incomplete, ambiguous, conflicting, or insufficient to decide, stop the stage decision and ask for clarification after summarizing the known sources and tradeoffs.
 - If asking is blocked, record a resource gap or issue instead of silently choosing a path.
 - Best practices may shape implementation, but they cannot override project facts or accepted design documents.
+- Before applying a role, run dynamic state awareness: identify the current stage, role, project type, domain, language, framework, SDKs, runtime tools, target market, and freshness-sensitive decisions from local config, module docs, manifests, lockfiles, imports, raw sources, and existing evidence.
 - Use bundled skill-local best-practice files only when they are related to the active skill and touched domain.
-- If related local best-practice coverage is missing, incomplete, stale, too generic, or version-sensitive for the concrete stack, prefer Context7 MCP when available. If Context7 is unavailable, use official/current web references, package repository docs, package README/changelog, installed type definitions, and lockfile/package versions. Record source links, retrieval date when relevant, and adaptation rationale in the evidence, issue, or learning proposal.
+- Treat bundled references as local baselines, not complete coverage. If local best-practice coverage is missing, incomplete, stale, too generic, version-sensitive, or not matched to the role/stage, prefer Context7 MCP when available. If Context7 is unavailable, use official/current web references, package repository docs, package README/changelog, installed type definitions, lockfile/package versions, and current web search. Record source links, retrieval date when relevant, and adaptation rationale in the evidence, issue, or learning proposal.
+- For product-manager, product-research, BRD, proposal, market-analysis, persona, competitor, pricing, GTM, regulation, or benchmark work, local repository facts are often insufficient or stale. Search current authoritative or primary sources when they can materially affect the proposal or recommendation, then clearly separate sourced evidence, assumptions, and product decisions.
 - External best-practice references are advisory. They may justify implementation style, review criteria, or learning proposals, but they must not invent requirements, acceptance criteria, product behavior, or project policy.
 
 ## Documentation Retrieval Fallbacks
 
 - Context7 MCP is an accelerator, not a hard dependency. Missing Context7 must not block a skill when equivalent official or local references are available.
 - For library/API questions, first identify the concrete package and version from `package.json`, lockfiles, imports, installed package metadata, generated types, or project config.
+- For product/market questions, first identify the target customer, market, geography, segment, business model, timeframe, competitors, and decision to be made from the proposal and configured sources.
 - Prefer official documentation and source repositories over blogs, snippets, or model memory.
-- When using web search, restrict to official domains when possible and record the exact source used.
+- When using web search, prefer primary/authoritative sources: official docs, standards bodies, regulator/government statistics, company pricing/docs, app-store reviews, customer-facing pages, credible industry reports, and dated market data. Record the exact source and source date.
 - When no authoritative reference can be retrieved, mark the item as a resource gap instead of guessing.

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

@@ -17,6 +17,31 @@ The harness computes gate status. Skills may propose outputs and record evidence
 - `smoke`, `review`, and `verify` must reject tests that cannot be traced to PRD/SRS, spec/design, task, issue, or accepted user clarification.
 - If the test contract is unclear, the stage is `blocked` until the uncertainty is clarified or recorded as a resource gap.
 
+## Stage Entry Quality Gate
+
+- Before a downstream stage starts, the harness must assess the required upstream artifacts for that stage with `zsk gate assess --stage <stage>`.
+- The assessment must write a score, PASS/FAIL criteria, blockers, gaps, and next action under `.zsk/evidence/gates/`.
+- A score below the configured threshold is not an infinite hard stop by itself. If all required artifacts exist and only quality gaps remain, the stage may continue only after an explicit human risk acceptance is recorded with `--accept-risk`.
+- Missing required artifacts, placeholder-only upstream docs, missing project/system rules for governed stages, or missing mandatory test basis remain `BLOCKED`; a risk waiver must not convert those into PASS. Very short but non-placeholder artifacts are quality gaps, not hard blockers.
+- Thresholds are project policy. When no project threshold is configured, the CLI default is an advisory 9/10 gate; documents must still record unsupplied numeric thresholds as `未指定` instead of inventing policy.
+
+## Test Correctness Gate
+
+- A passing test suite is not sufficient evidence when the tests do not prove the intended behavior.
+- New or changed behavior needs a traceable test basis: PRD/SRS, spec acceptance criteria, design decision, task, issue, or accepted user clarification.
+- Tests must include the meaningful negative, boundary, and regression cases implied by the acceptance criteria. If a case is intentionally omitted, record the omitted case, reason, risk, and owner.
+- For TDD work, prefer a red/green proof or equivalent evidence that the new test fails without the fix. If that is impractical, review must explain the substitute evidence.
+- `smoke`, `review`, and `verify` must reject fake passes: skipped tests, tests with no assertions, tests that only assert mocks were called while ignoring user-visible behavior, tests that assert implementation details instead of contract behavior, or tests that pass because expected data is hardcoded to the implementation.
+- Every test report must distinguish passed, failed, skipped, flaky, unrun, and not-applicable checks. Skipped or unrun checks are not PASS.
+
+## Durable Dispatch Gate
+
+- Every dispatched role/subagent lane must have a durable emit packet with `runId`, `packetId`, write scope, evidence obligation, stop condition, status path, and fallback route.
+- Dispatch must write an emit ledger under `.zsk/evidence/dispatch/{run}/emit-ledger.json` plus per-packet status files.
+- Long-running packets must heartbeat before their deadline. A pending or running packet with no heartbeat past deadline becomes `stale`.
+- Stale packets do not block forever. The lead-integrator must either fall back to leader-sequential execution for that lane or re-emit a new bounded packet.
+- A stale, failed, blocked, or waived packet cannot be counted as completed evidence unless the lead-integrator records the fallback result or accepted risk.
+
 ## Gate Status
 
 - `blocked`: required resource or evidence is missing.
@@ -25,3 +50,6 @@ The harness computes gate status. Skills may propose outputs and record evidence
 - `failed`: stage ran but produced blocking findings.
 - `paused`: resumable session state exists, used by interruptible demo.
 - `terminated`: session intentionally stopped; follow-up owner is required.
+- `needs-confirmation`: required artifacts exist, but quality score/gaps require human decision before proceeding.
+- `waived`: explicit human risk acceptance allows progression despite non-blocking quality gaps; waiver evidence must be linked.
+- `stale`: a dispatched packet missed its heartbeat/deadline and must fall back or be re-emitted.