@captain_z/zsk-skills 1.8.0 → 1.8.1

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.
+  - Continue the workflow at acceptance after the prerequisite evidence and
+    blockers are resolved.
+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,6 +79,7 @@ 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.
+- 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.
 
@@ -66,10 +87,11 @@ When a `harness/` directory is installed beside this file, treat it as the local
 
 - 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,33 @@ This file is generated for the installed skill. Read it before executing this sk
 - `documentation feedback`
 - `accept/reject evidence`
 
+## 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.
+- 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 +75,16 @@ 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.
+- 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.
+- 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 +98,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,29 @@ 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.
+
+## 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

@@ -9,8 +9,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 +21,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 +35,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:
@@ -53,6 +72,7 @@ For `DEEP` review, dispatch at least three independent expert lanes when subagen
 - Neither entry point may skip a selected skill's own contract, forbidden scope, required inputs, issue routing, or evidence gate.
 - 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,7 +82,7 @@ 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;
+- 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;
 - write reusable improvement proposals under `.zsk/learning/proposals/`;
 - group accepted proposals into one optimization batch with target files, regression prompts, risks, and review status.
 

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/workflow/completion-contract.yaml

@@ -4,9 +4,27 @@ defaults:
   rules:
     artifact: "Every skill run must declare produced artifacts and write them to project-template paths, not only to chat."
     evidence: "Every pass/fail or completion claim must link local evidence."
-    issue_sync: "Actionable findings must update the concrete issue plus module/global issue indexes."
+    issue_sync: "Actionable findings must classify scope, update the concrete issue in module-private or shared/global/public storage, and refresh module/global issue indexes."
     documentation_feedback: "Confirmed learnings must update spec/design/task docs or record a no-update rationale."
     execution: "Completion work may be done by a skill-local script or by the agent's normal file-editing tools, but the harness contract decides the required outputs."
+  scopeRouting:
+    moduleFinal: ".zsk/modules/{module}/{stage}.md"
+    modulePrivate:
+      issues: ".zsk/modules/{module}/_issues/"
+      evidence: ".zsk/modules/{module}/_evidence/"
+      playwright: ".zsk/modules/{module}/_playwright/"
+    shared:
+      issues: ".zsk/issues/shared/"
+      evidence: ".zsk/evidence/shared/"
+      playwright: ".zsk/playwright/shared/"
+    global:
+      issues: ".zsk/issues/global/"
+      evidence: ".zsk/evidence/global/"
+      playwright: ".zsk/playwright/global/"
+    public:
+      issues: ".zsk/issues/public/"
+      evidence: ".zsk/evidence/public/"
+      playwright: ".zsk/playwright/public/"
 execution:
   owner: harness
   implementationSurfaces:
@@ -17,7 +35,7 @@ execution:
 outputs:
   prepare:
     artifacts:
-      - ".zsk/resources/manifest.json"
+      - ".zsk/raws/manifest.json"
       - ".zsk/docs/SYSTEM-SPEC.md"
     feedbackTargets: [".zsk/docs/SYSTEM-SPEC.md", ".zsk/config.yaml"]
   proposal:
@@ -35,7 +53,7 @@ outputs:
   task:
     artifacts:
       - ".zsk/modules/{module}/tasks.md"
-      - ".zsk/playwright/{module}/specs/"
+      - ".zsk/modules/{module}/_playwright/specs/"
     feedbackTargets: [".zsk/modules/{module}/tasks.md", ".zsk/modules/{module}/design.md"]
   coding:
     artifacts:
@@ -44,12 +62,12 @@ outputs:
   smoke:
     artifacts:
       - ".zsk/modules/{module}/smoke.md"
-      - ".zsk/issues/{module}/"
+      - ".zsk/modules/{module}/_issues/"
     feedbackTargets: [".zsk/modules/{module}/smoke.md", ".zsk/modules/{module}/spec.md"]
   review:
     artifacts:
       - ".zsk/modules/{module}/review.md"
-      - ".zsk/issues/{module}/"
+      - ".zsk/modules/{module}/_issues/"
     feedbackTargets: [".zsk/modules/{module}/review.md", ".zsk/modules/{module}/design.md", ".zsk/modules/{module}/tasks.md"]
   commit:
     artifacts:
@@ -63,12 +81,12 @@ outputs:
     artifacts:
       - ".zsk/modules/{module}/demo-outline.md"
       - ".zsk/modules/{module}/demo-report.md"
-      - ".zsk/playwright/{module}/specs/"
-      - ".zsk/issues/{module}/"
+      - ".zsk/modules/{module}/_playwright/specs/"
+      - ".zsk/modules/{module}/_issues/"
     feedbackTargets: [".zsk/modules/{module}/demo-outline.md", ".zsk/modules/{module}/spec.md", ".zsk/modules/{module}/design.md", ".zsk/modules/{module}/tasks.md"]
   defect:
     artifacts:
-      - ".zsk/issues/{module}/"
+      - ".zsk/modules/{module}/_issues/"
     feedbackTargets: [".zsk/modules/{module}/spec.md", ".zsk/modules/{module}/design.md", ".zsk/modules/{module}/tasks.md"]
   ready:
     artifacts:
@@ -77,12 +95,12 @@ outputs:
   verify:
     artifacts:
       - ".zsk/modules/{module}/verify.md"
-      - ".zsk/issues/{module}/"
+      - ".zsk/modules/{module}/_issues/"
     feedbackTargets: [".zsk/modules/{module}/verify.md", ".zsk/modules/{module}/spec.md"]
   acceptance:
     artifacts:
       - ".zsk/modules/{module}/acceptance.md"
-      - ".zsk/issues/{module}/"
+      - ".zsk/modules/{module}/_issues/"
     feedbackTargets: [".zsk/modules/{module}/acceptance.md", ".zsk/modules/{module}/spec.md", ".zsk/modules/{module}/design.md", ".zsk/modules/{module}/tasks.md"]
   archive:
     artifacts:
@@ -91,7 +109,7 @@ outputs:
     feedbackTargets: [".zsk/modules/{module}/archive.md", ".zsk/learning/proposals/"]
 postRun:
   issueIndexes:
-    module: ".zsk/issues/{module}/index.md"
+    module: ".zsk/modules/{module}/_issues/index.md"
     global: ".zsk/issues/index.md"
     refreshWhen: ["issue_create", "issue_status_update", "verification_result", "acceptance_decision"]
   docsFeedback:
@@ -99,4 +117,6 @@ postRun:
     targets: ["spec", "design", "tasks", "SYSTEM-SPEC", "learning-proposal"]
   learning:
     proposalPath: ".zsk/learning/proposals/"
+    createPolicy: "lazy; do not create during zsk init or unrelated stages"
+    createWhen: "only when learn/archive writes a concrete reusable improvement proposal"
     promoteBy: "harness/learning/promotion-rules.yaml"

package/acceptance/harness/workflow/skill-io-contract.yaml

@@ -9,15 +9,23 @@ principles:
     authorized; fall back to Playwright MCP/ARIA/CDP or documented manual
     evidence when Computer Use is unavailable; use Browser Use only on runtimes
     that explicitly support it and have permission.
-  - Every actionable finding becomes a persisted issue plus module/global index
+  - Every actionable finding classifies scope first, then becomes a persisted
+    module-private or shared/global/public issue plus bucket/global index
     updates.
   - Follow best practices through the smallest sufficient local design; do not
     add speculative abstractions, scripts, files, or gates.
-  - Use only related bundled best-practice references for the active skill; when
-    they are missing, incomplete, stale, too generic, or version-sensitive for
-    the concrete stack, prefer Context7 MCP when available, otherwise consult
-    official/current web references and local package docs/types, then record
-    source links plus adaptation rationale.
+  - "Run dynamic state awareness before role work: identify the current stage,
+    role, project type, language, framework, SDKs, runtime tools, domain,
+    business context, and freshness-sensitive decisions from local files and
+    configured sources."
+  - Use local and bundled references first. Search Context7 or the web only when
+    local best-practice coverage or factual context is missing, incomplete,
+    stale, too generic, version-sensitive, or market/time-sensitive for the role
+    and stage.
+  - For product, research, strategy, or BRD/proposal work, dynamically retrieve
+    current market, competitor, persona, pricing, regulation, benchmark, and
+    trend sources when local sources are absent or stale; record source dates
+    and how the evidence changes the recommendation.
   - "Do not decide from uncertainty: summarize conflicting or missing facts and
     ask, or record a resource gap."
   - "TDD first for testable behavior: tests and scenarios must be accurate and
@@ -28,20 +36,46 @@ toolPolicy:
     - git
     - package-manager
     - configured-cli
+  environmentAwareness:
+    - project-config
+    - module-docs
+    - manifests
+    - lockfiles
+    - package-manifests
+    - imports
+    - framework-config
+    - runtime-config
+    - existing-docs
+    - git-history
   sourceRetrieval:
+    - configured-sources
+    - raw-manifest
     - direct-http
     - local-files
     - git
     - local-package-docs
     - context7-mcp
-    - figma-mcp
+    - provider-mcp
+    - current-web-search
   bestPracticeRetrieval:
     - bundled-related-references
+    - project-stack-detection
+    - local-package-docs
     - context7-mcp
     - official-docs
     - current-web-search
-    - local-package-docs
     - user-supplied-reference
+  productResearchRetrieval:
+    - configured-sources
+    - current-web-search
+    - official-statistics
+    - regulator-sources
+    - industry-reports
+    - competitor-sites
+    - pricing-pages
+    - app-store-reviews
+    - analyst-reports
+    - user-research-repositories
   uiUnderstanding:
     - computer-use
     - playwright-mcp
@@ -55,6 +89,14 @@ toolPolicy:
     - playwright-library
   fallbackOnly:
     - browser-use
+    - provider-mcp
+  providerMcpWhen:
+    - a project explicitly configures a provider MCP and its transport is healthy
+    - local files, git, raw manifests, Context7, official docs, or direct HTTP
+      cannot provide the needed provider-specific fact
+    - the provider MCP is optional; if unavailable, failing, or unconfigured,
+      record the gap and continue with another approved evidence source instead
+      of blocking or requiring installation
   browserUseWhen:
     - the current runtime supports Browser Use and permissions are available
     - Playwright auth state, Playwright MCP/ARIA/CDP, Computer Use, and
@@ -76,11 +118,30 @@ toolPolicy:
       first unless the user or project config already provides an exact Context7
       id
   docsFallbackWhen:
+    - local bundled references are absent, incomplete, stale, too generic, or
+      version-sensitive for the current role/stage
     - Context7 MCP is unavailable, unconfigured, rate-limited, or lacks the
       target library/version
     - use the official project documentation site, package repository docs,
       package README, changelog, installed types, lockfile version, or current
       web search with source links
+  productResearchWhen:
+    - proposal, BRD, product strategy, product research, positioning, roadmap,
+      pricing, market sizing, persona, or competitive-analysis work depends on
+      current external facts
+    - local SRS/PRD/customer notes do not contain enough evidence to judge
+      value, feasibility, target users, differentiation, pricing, or risk
+    - existing market or best-practice references are stale or not tied to the
+      target market/segment
+    - the result must distinguish sourced market evidence from product decisions
+      and assumptions
+  noSearchWhen:
+    - local configured sources and bundled references are sufficient, current,
+      and specific to the role/stage
+    - the task is purely local implementation or verification and external facts
+      would not change the result
+    - network access is unavailable and equivalent local package
+      docs/types/source evidence exist
   scriptWhen:
     - the update is mechanical, repeatable, or index-like
     - the output shape is schema-bound

package/acceptance/harness/workflow/skill-quality-standards.yaml

@@ -0,0 +1,55 @@
+version: 1
+framework:
+  intent: Make every ZSK stage produce a decision-grade document, not a chat
+    summary or empty template.
+  industryAnchors:
+    - "Diataxis: choose the document mode by reader need: task guidance,
+      reference, explanation, or learning."
+    - "Developer documentation style guides: optimize for the reader, clarity,
+      consistency, active language, and project-specific terminology."
+    - "Definition of Done: completion requires shared, visible, measurable
+      quality criteria."
+    - "Review workflows: a stage is not complete until another reader can
+      inspect artifacts, evidence, decisions, and unresolved risks."
+  documentModes:
+    decisionBrief: Frames a decision with context, options, recommendation, risks,
+      and success criteria.
+    contract: States observable behavior, constraints, interfaces, and acceptance
+      conditions.
+    executionPlan: Turns approved decisions into ordered, owned, verifiable work.
+    evidenceReport: Records what was run, what happened, what failed, and what remains risky.
+    decisionRecord: Preserves the reason for an irreversible or future-relevant choice.
+defaults:
+  qualityCheckpoints:
+    - 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.
+  antiPatterns:
+    - Template-shaped filler that does not resolve a decision.
+    - 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.
+stages:
+  acceptance:
+    documentMode: decisionRecord
+    purpose: Record the accept/reject business decision and residual-risk ownership.
+    mustAnswer:
+      - Is the verified work accepted, rejected, or conditionally accepted?
+      - Which evidence and issues support the decision?
+      - Who owns residual risks and documentation feedback?
+    qualityCheckpoints:
+      - Links verify report, demo evidence, accepted criteria, and residual
+        risks.
+      - Records documentation feedback or no-update rationale for confirmed
+        learnings.
+    antiPatterns:
+      - Accepting without verification evidence.
+      - Letting residual risks remain ownerless.