@captain_z/zsk-skills 1.7.0 → 1.8.1

package/README.md

@@ -1,21 +1,21 @@
 # @captain_z/zsk-skills
 
-ZNorth Standard Kit 的可安装 skill 内容包。安装面现在只保留从根级 `skills/` 生成的 **core harness-first skills**；旧 `.best-practices/` 不再批量生成 installable skills，只作为扁平参考资料。
+ZNorth Standard Kit 的可安装 skill 内容包。安装面现在只保留从根级 `skills/` 生成的 **core harness-first skills**；旧 `.best-practices/` 不再批量生成独立 installable skills，而是作为参考源按 skill 携带相关子集。
 
-包内共有 **19 颗 installable skills**，全部来自根级 `skills/`。
+包内共有 **22 颗 installable skills**，全部来自根级 `skills/`。
 
 ## 合规审查（ARCHITECTURE §4.4 硬指标）
 
 | 检查项                                                                                   | 结果    | 说明                                                  |
 | ---------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
-| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 19/19 | core 由 root `skills/` 生成 |
-| `name` 使用裸 slug，扁平且不含连字符                                                       | ✓ 19/19 | LLM 原生 skill 入口保持简洁；CLI 选择层使用 `zsk:<slug>` |
-| `description` 简洁表达职责和使用时机                                                       | ✓ 19/19 | 面向索引阅读；triggers 留给机器使用 |
-| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 19/19 | stage/utility · core |
-| `triggers` 数组非空                                                                      | ✓ 19/19 | 至少含裸 slug |
+| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 22/22 | core 由 root `skills/` 生成 |
+| `name` 使用裸 slug，扁平且不含连字符                                                       | ✓ 22/22 | LLM 原生 skill 入口保持简洁；CLI 选择层使用 `zsk:<slug>` |
+| `description` 简洁表达职责和使用时机                                                       | ✓ 22/22 | 面向索引阅读；triggers 留给机器使用 |
+| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 22/22 | stage/utility · core |
+| `triggers` 数组非空                                                                      | ✓ 22/22 | 至少含裸 slug |
 | 无硬编码项目名 / 技术栈（统一 `{{config.*}}` 占位符）                                    | ✓       | harness-neutral                                       |
 | `related:` 相对路径合法                                                                  | ✓       | core 不依赖参考层生成物                               |
-| 单文件 ≤ 300 行                                                                          | ✓ 19/19 | core 由 `lint:harness` 强制                           |
+| 单文件 ≤ 300 行                                                                          | ✓ 22/22 | core 由 `lint:harness` 强制                           |
 
 当前 `max-lines` 已由 `tools/lint-frontmatter.ts` 作为 error 强制；新增或修改 skill 不应超过 300 行。
 
@@ -34,11 +34,12 @@ Profile 是流程组合策略，不是新的 skill。Atomic skills 仍然平铺
 
 | profile | skills | 适用场景 |
 | --- | ---: | --- |
-| `zsk-lite` | 7 | 小修、小项目、脚本、低风险任务 |
-| `zsk-sdlc` | 16 | 标准工程交付；需求、实现、审查、验证、验收、归档 |
-| `zsk-frontend` | 17 | UI/UX/browser-facing 交付；强化 demo、视觉证据、前端质量门禁 |
-| `zsk-enterprise` | 17 | 高治理交付；要求 deploy、验收、归档、审计证据 |
-| `sdlc-only` | 19 | 旧入口兼容；安装全部 core skills |
+| `zsk-entry` | 2 | 只装 `zskplan` / `zsk` 两个主入口，由它们按 harness 调度 |
+| `zsk-lite` | 10 | 小修、小项目、脚本、低风险任务 |
+| `zsk-sdlc` | 19 | 标准工程交付；需求、实现、审查、验证、验收、归档 |
+| `zsk-frontend` | 20 | UI/UX/browser-facing 交付；强化 demo、视觉证据、前端质量门禁 |
+| `zsk-enterprise` | 20 | 高治理交付；要求 deploy、验收、归档、审计证据 |
+| `sdlc-only` | 22 | 旧入口兼容；安装全部 core skills |
 
 ## Skill 搭配流程图
 
@@ -79,11 +80,13 @@ flowchart TD
 | 目标 | 推荐说法或命令 | 结果 |
 | --- | --- | --- |
 | 安装默认 core skills | `npx @captain_z/zsk add` | 交互选择 target 和 bundle |
-| CI 安装轻量 profile | `npx @captain_z/zsk add zsk-lite --target=~/.claude/skills --yes` | 非交互安装 7 颗常用 skills |
-| CI 安装标准 SDLC profile | `npx @captain_z/zsk add zsk-sdlc --target=~/.claude/skills --yes` | 非交互安装 16 颗标准 workflow skills |
+| CI 安装 ZSK 主入口 | `npx @captain_z/zsk add zsk-entry --target=~/.claude/skills --yes` | 非交互安装 `zskplan` / `zsk` 两个入口 |
+| CI 安装轻量 profile | `npx @captain_z/zsk add zsk-lite --target=~/.claude/skills --yes` | 非交互安装 10 颗常用 skills |
+| CI 安装标准 SDLC profile | `npx @captain_z/zsk add zsk-sdlc --target=~/.claude/skills --yes` | 非交互安装 19 颗标准 workflow skills |
 | Claude plugin 安装 | `/plugin marketplace add codeshareman/zsk` 后 `/plugin install zsk@zsk` | 使用 `/zsk:<slug>` 命令面 |
 | GitHub skills 管理器安装 | `npx skills add codeshareman/zsk` | 从仓库根 `skills/` 安装；不要加 `@` |
-| 不确定该用哪个 skill | "用 `zsk:dispatch` 调度" | 让 OMX 围绕 ZSK skills 分配 subagents |
+| 只想让 ZSK 自己规划和执行 | "用 `zsk:zskplan` 规划" / "用 `zsk:zsk` 继续" | 计划写入 `.zsk/plans/`，执行产物写入 `.zsk` |
+| 不确定该用哪个阶段 skill | "用 `zsk:dispatch` 调度" | 让 OMX 围绕 ZSK skills 分配 subagents |
 | 恢复一个项目的下一步 | "用 `zsk:flow` 继续" | 读取配置、阶段文档和 blocker，选择合法下一阶段 |
 | 明确进入某阶段 | "用 `zsk:spec` 写模块规格" | 只载入对应 stage contract |
 
@@ -98,41 +101,48 @@ flowchart TD
 
 ## 和项目知识工作区的关系
 
-`zsk init` 生成的 `.zsk/config.yaml`、`docs/SYSTEM-SPEC.md`、`.raws/`、`docs/` 和 `.issues/` 是默认项目上下文。CLI 负责创建最小骨架、使用 package-owned schema 校验、刷新 `{paths.raws}/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；Browser Use 用于复用已登录浏览器/profile/SSO 状态；Computer Use 只用于结构化 Web 自动化不可达或需要视觉/系统级判断的场景。Skills 必须通过 `.zsk/config.yaml` 和 `docs/{module}/module.yaml` 解析路径，不能硬编码 `.raws`、`docs` 或 `.issues`。
+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 的输入、输出、工具/能力、脚本策略和 Browser Use 策略由 harness 的 `skill-io-contract.yaml` 约束；完成后的产物路径、issue 索引同步和确认后的文档反哺由 `completion-contract.yaml` 约束。缺少 Documentation Feedback 时，`zsk check` 可以把它作为阶段未收口的证据。
+每个 skill/stage 的输入、输出、工具/能力、脚本策略和运行时 UI 观察策略由 harness 的 `skill-io-contract.yaml` 约束；完成后的产物路径、issue 索引同步和确认后的文档反哺由 `completion-contract.yaml` 约束。缺少 Documentation Feedback 时，`zsk check` 可以把它作为阶段未收口的证据。
 
 ## 领域总览
 
-包内只保留默认可安装的 core 领域。Frontend、quality、design-handoff 等内容仍在 `.best-practices/`，按需读取，不进入默认安装面。
+包内只保留默认可安装的 core 领域。Frontend、quality、design-handoff 等内容仍由根级 `.best-practices/` 维护，但会按相关性复制到各 skill 的 `harness/best-practices/`；它们不是单独可触发的 installable skills。
 
 | 领域              | skill 数 | 职责                                       |
 | ----------------- | -------- | ------------------------------------------ |
-| `skills/`         | 19       | harness-first 默认工作流入口               |
-| **总计**          | **19**   |                                            |
+| `skills/`         | 22       | harness-first 默认工作流入口               |
+| **总计**          | **22**   |                                            |
 
 ## 安装套件（bundles.yaml）
 
 | name                           | skills | 场景                                          |
 | ------------------------------ | ------ | --------------------------------------------- |
-| `zsk-lite`                     | 7      | 小型低风险任务；coding → smoke → review → commit |
-| `zsk-sdlc`（推荐）             | 16     | 标准工程交付；完整需求、实现、审查、验证、验收、归档链路 |
-| `zsk-frontend`                 | 17     | 前端/视觉/browser-facing 任务；强化 demo 和前端质量门禁 |
-| `zsk-enterprise`               | 17     | 高治理交付；要求 deploy、验收、归档、审计证据 |
-| `sdlc-only`                    | 19     | 旧入口兼容；安装全部 core skills |
-| `frontend-project`             | 19     | 旧入口兼容；推荐改用 `zsk-frontend` |
-| `frontend-with-design-handoff` | 19     | 旧入口兼容；推荐改用 `zsk-frontend` |
+| `zsk-entry`                    | 2      | 只安装 ZSK / ZSK Plan 两个主入口 |
+| `zsk-lite`                     | 10     | 小型低风险任务；ZSK 入口 + coding → smoke → review → commit |
+| `zsk-sdlc`（推荐）             | 19     | 标准工程交付；完整需求、实现、审查、验证、验收、归档链路 |
+| `zsk-frontend`                 | 20     | 前端/视觉/browser-facing 任务；强化 demo 和前端质量门禁 |
+| `zsk-enterprise`               | 20     | 高治理交付；要求 deploy、验收、归档、审计证据 |
+| `sdlc-only`                    | 22     | 旧入口兼容；安装全部 core skills |
+| `frontend-project`             | 22     | 旧入口兼容；推荐改用 `zsk-frontend` |
+| `frontend-with-design-handoff` | 22     | 旧入口兼容；推荐改用 `zsk-frontend` |
 | `custom`                       | 交互   | 通过 `zsk add` 任意多选                       |
 
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 19 skills -->
+<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 22 skills -->
 
 ## Skill 清单（core skills）
 
 > 内容由 `tools/catalog.ts` 从 `packages/skills/*/SKILL.md` frontmatter 生成。重生成：`pnpm catalog`。
 
-### `<slug>/` — Core · harness-first 默认工作流入口 (19)
+### `<slug>/` — Core · harness-first 默认工作流入口 (22)
+
+- **`zskplan`**
+  Use as the ZSK-aware RalphPlan-style planning entrypoint that freezes scope, skill route, expert lanes, Playwright/evidence paths, and stop conditions under .zsk.
+
+- **`zsk`**
+  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.
@@ -188,6 +198,9 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 - **`archive`**
   After acceptance, closes the iteration by preserving artifacts, decisions, issues, and learning proposals.
 
+- **`learn`**
+  Use after repeated friction or supplied public skill/harness references to learn, compare, record gaps, and prepare one reviewed ZSK optimization batch.
+
 - **`issue`**
   Tracks defects, blockers, questions, and risks with taxonomy, severity, owner, reproduction, and evidence.
 

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
@@ -40,7 +60,7 @@ Use this stage after independent `verify` has passed and the product/business ow
 - Do not accept work with missing verify evidence.
 - Do not hide product disagreement as a minor issue.
 - Do not mutate implementation or test files from this stage.
-- Do not leave confirmed issue learning only in `.issues`; accepted fixes must feed back into the relevant spec/design/task docs unless there is an explicit no-update rationale.
+- Do not leave confirmed issue learning only in `.zsk/issues`; accepted fixes must feed back into the relevant spec/design/task docs unless there is an explicit no-update rationale.
 - Keep the decision short, dated, and evidence-linked.
 
 ## Outputs
@@ -58,14 +78,20 @@ This core skill is governed by the ZSK harness. Enforce these rules even when on
 - Evidence rules: no PASS / DONE / READY claim without linked command, artifact, issue, scenario, or human decision evidence.
 - 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.
 
 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.
-- Read the relevant file under `harness/best-practices/` when the task touches SDLC, quality, frontend, design handoff, system constraints, or agent orchestration.
+- 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/README.md

@@ -2,103 +2,14 @@
 
 This harness bundle was embedded for `acceptance` so external installers such as `npx skills add codeshareman/zsk` install more than a bare `SKILL.md`.
 
-The local `SKILL.md` is the execution entrypoint. These files are the supporting contract for stage gates, evidence, issue taxonomy, workflow transitions, and compact best-practice references.
+The local `SKILL.md` is the execution entrypoint. This generated harness is an install artifact, not the source of truth.
 
----
-# zsk Harness
+Roles:
 
-`harness/` is the source of truth for workflow governance. Skills are execution surfaces, but the harness owns constraints, resources, templates, state transitions, evidence, issue taxonomy, completion outputs, and learning promotion rules.
+- Root `harness/` in the ZSK repository is the canonical source for constraints, workflow state, evidence, issue taxonomy, and promotion rules.
+- `skills/<skill>/harness/THIS_SKILL.md` is the skill-specific contract: responsibility, inputs, outputs, expert lanes, related best-practice concerns, and hard stops.
+- `skills/<skill>/harness/workflow/skill-io-contract.yaml` is filtered to this skill plus shared tool policy so installed standalone skills stay portable without carrying the whole catalog.
+- `skills/<skill>/harness/best-practices/` contains only the related reference files this skill needs. It is intentionally not a full copy of `.best-practices/`.
+- Root `.best-practices/` remains repository authoring/reference material. Durable runtime rules must be promoted into root `harness/` or `THIS_SKILL.md`.
 
-The harness should adapt best practices, not accumulate them. Prefer the smallest sufficient local design: no speculative abstractions, scripts, files, or workflow gates unless the current project need proves they are necessary.
-
-The harness-first build path is now wired: root `skills/` generates `capabilities/skills/`, then `packages/skills/`. `.best-practices/` is only a slim reference layer and is not part of default installation.
-
-## Authority
-
-Merge order:
-
-```text
-root harness
--> selected pack overlays
--> skill-local harness contract
--> project .zsk/config.yaml bindings
-```
-
-Root constraints can only be extended or tightened. Packs and skill-local contracts cannot weaken anti-patterns, stage gates, evidence rules, issue taxonomy, or filesystem boundaries.
-
-## Learning Loop
-
-The harness owns self-learning. Skills and stage templates may surface `Documentation Feedback`, but they must not directly mutate core constraints, templates, packs, or root skills.
-
-Flow:
-
-1. Stage work records reusable failures, template gaps, or skill gaps as documentation feedback.
-2. `archive` converts durable findings into learning proposals under `.zsk/learning/proposals`.
-3. Promotion follows `harness/learning/promotion-rules.yaml`.
-4. Accepted proposals patch the smallest target: constraint, template, resource map, root skill, optional pack, or project-only docs.
-5. Core promotion requires review plus regression evidence.
-
-Project-specific experience stays in module archives or `docs/SYSTEM-SPEC.md`. General zsk changes must be proposed, reviewed, and verified before becoming default behavior.
-
-## Skill Completion Contract
-
-`workflow/skill-io-contract.yaml` defines each skill's expected inputs, outputs, tools, capabilities, script policy, and Browser Use policy.
-
-`workflow/completion-contract.yaml` defines what each skill/stage must leave behind after execution:
-
-- produced artifacts and their project-template paths;
-- evidence required for completion claims;
-- issue persistence and module/global index refreshes;
-- documentation feedback targets after verified and confirmed fixes;
-- learning proposal handoff for reusable process improvements.
-
-This contract is harness-owned. Individual skills may name their outputs, but they should not redefine where persistent project artifacts, issue indexes, or confirmed documentation feedback are managed.
-
-File updates can be implemented in two ways:
-
-- repeatable mechanical updates should use CLI commands or skill-local scripts declared by the skill;
-- context-sensitive docs feedback can be written by the agent with normal file-editing tools.
-
-Both paths must satisfy the same harness completion contract before the skill is considered done.
-
-## Runtime Flow
-
-The harness treats skills as stage contracts, not free-form prompts. Profiles under `profiles/*.yaml` choose the stage sequence and strictness before optional gates are enforced:
-
-```text
-zsk-lite       small, low-risk changes
-zsk-sdlc       standard engineering delivery
-zsk-frontend   UI/UX/browser-facing delivery with demo and visual evidence
-zsk-enterprise governed delivery with deploy, acceptance, and archive evidence
-```
-
-The standard profile follows:
-
-```text
-dispatch
-  -> flow
-  -> prepare -> proposal -> spec -> design -> task
-  -> coding -> smoke -> review -> commit
-  -> ready -> verify -> acceptance -> archive
-```
-
-Supporting stages can branch from the main flow:
-
-- `issue` records blockers, risks, questions, and defects without bypassing gates.
-- `dispatch` tells OMX to schedule subagents around the active ZSK skill and harness gate.
-- `demo` proves a changed flow before formal QA.
-- `defect` turns QA findings into reproducible, FR/AC-linked work.
-- `commit` is allowed only after smoke and review pass.
-- `deploy` is optional in `zsk-sdlc`, required in `zsk-enterprise`, and usually sits between `commit` and `ready`.
-
-Every branch must return with evidence, status, and index updates required by `workflow/completion-contract.yaml`.
-
-## Quality Bar
-
-High-quality skill output means:
-
-- source-linked: important claims trace to PRD/SRS, spec/design, task, issue, code/runtime evidence, or user clarification;
-- accurate: tests and scenarios prove the intended behavior, not convenient implementation details;
-- complete enough: missing resources, uncertainty, and conflicts are named with impact;
-- concise: no generic filler, speculative abstraction, or extra structure beyond the smallest sufficient design;
-- reviewed: review/verify/acceptance check traceability, test adequacy, scope creep, and unresolved uncertainty before pass.
+Read `THIS_SKILL.md` first, then only the constraint/workflow files it names for the current task.

package/acceptance/harness/THIS_SKILL.md

@@ -28,18 +28,79 @@ This file is generated for the installed skill. Read it before executing this sk
 - Script policy: `optional`
 - Browser Use policy: `never`
 
+## Expert Lanes
+
+- `business decision`
+- `residual risk`
+- `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
+
+- `best-practices/sdlc.md`
+- `best-practices/quality.md`
+
+## Forbidden Scope
+
+- `creating ZSK-managed artifacts outside `.zsk` workspace paths`
+- `claiming completion without evidence`
+- `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.
 - `workflow/skill-io-contract.yaml` for the full machine-readable contract.
 - `workflow/state-machine.yaml` before moving to another stage.
+- `constraints/skill-role-contract.md` before planning or reviewing expert work.
+- `constraints/filesystem-boundaries.md` before creating any project artifact.
 - `constraints/stage-gates.md` before accepting or skipping prerequisites.
 - `constraints/evidence-rules.md` before claiming READY / PASS / DONE.
 - `workflow/completion-contract.yaml` before final response or handoff.
 - `constraints/issue-taxonomy.md` before creating defects, blockers, risks, or questions.
-- `best-practices/sdlc.md`
-- `best-practices/quality.md`
-- `best-practices/system.md`
+- `best-practices/sdlc.md` when its domain is touched by this task.
+- `best-practices/quality.md` when its domain is touched by this task.
+- 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
 
@@ -48,6 +109,7 @@ This file is generated for the installed skill. Read it before executing this sk
 - Evidence cannot be linked to command output, artifact, issue, scenario, or human decision.
 - The fix would widen scope beyond this skill's responsibility.
 - A blocker, risk, question, or defect needs persistent tracking.
+- The skill can only complete one convenient lane while other required expert lanes remain unchecked.
 
 ## Completion Checklist
 

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

@@ -1,52 +1,12 @@
-# .best-practices/
+# Scoped Best-Practice References
 
-这里是旧内容库收敛后的扁平参考层，不是默认安装清单。当前只保留 7 个可 lint 的参考文件。
+These references are bundled only for `acceptance` so standalone skill installs keep the related context this skill needs.
 
-## 现在怎么分工
+They are supporting guidance, not the source of truth. Runtime gates and hard constraints belong in `../THIS_SKILL.md` and `../constraints/`.
 
-| 路径 | 职责 | 维护规则 |
-| --- | --- | --- |
-| `skills/` | 默认安装的 core skills 源码 | 高频动作才放这里，`SKILL.md` 必须自带输入、流程、约束和输出 |
-| `harness/` | 状态机、门禁、资源、证据、issue taxonomy、自我学习提升规则 | 管全局约束，不复制每个 skill 的正文 |
-| `.best-practices/` | 少量可选参考资料 | 只保留领域总览和横切规则，分类写在 frontmatter |
-| `capabilities/skills/` | 生成缓存 | 只由脚本生成 core installable skills，不手改 |
-| `packages/skills/` | npm 发布包 | 由 `capabilities/skills/` 同步生成 |
+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:
 
-物理分组会带来两套同步成本：文件在哪个目录、frontmatter 又写哪个 domain。现在只保留一层文件，Agent 通过 frontmatter 判断领域，通过 `INDEX.md` 查目录。这样移动和删减都更轻。
-
-## 当前保留文件
-
-| 文件 | 职责 |
-| --- | --- |
-| `sdlc.md` | 交付阶段边界和门禁 |
-| `frontend.md` | 前端阶段补充和红线 |
-| `quality.md` | 跨栈质量原则和证据规则 |
-| `design-handoff.md` | SRS、低保真、高保真、测试用例等资源准备和设计还原 |
-| `system.md` | 项目宪法、ADR、配置和约束归属 |
-| `agent-orchestration.md` | 多 Agent 职责划分 |
-| `project-constraints-template.md` | 项目约束最小模板 |
-
-## 什么应该留在这里
-
-- 多个项目都会用到，但不值得装成默认 skill 的参考。
-- 能用一个领域总览讲清楚的规则。
-- 还没提升为 `skills/` 或 `harness/` 的候选约束。
-
-不再保留 `_legacy/`、领域子目录、大段参考归档和每个技术点一份文件。旧内容如果不能支撑当前 core skills、harness 或发布包，就删掉。
-
-## 写新资料的规则
-
-1. 先判断能否并入现有 7 个参考文件。
-2. 文件确实必须新增时，放在 `.best-practices/{slug}.md`。
-3. `name` 用 `zsk:{slug}`，必须和文件名一致。
-4. `domain` 写领域，比如 `sdlc`、`frontend`、`quality`、`design-handoff`、`system`、`meta`。
-5. 非 domain-index 文件必须在 `related` 里包含 `./agent-orchestration.md`。
-6. 默认执行约束不要只写在这里；高频约束要提升到 `skills/` 或 `harness/`。
-
-生成索引：
-
-```bash
-pnpm build:index
-```
+- `sdlc.md`
+- `quality.md`

package/acceptance/harness/constraints/evidence-rules.md

@@ -9,14 +9,14 @@ Accepted evidence types:
 - lint/typecheck/build output
 - screenshot
 - Playwright trace
-- Browser Use session note
+- UI observation note from Computer Use, Playwright MCP/ARIA/CDP, compatible Browser Use, or documented manual evidence
 - network log
 - console log
 - deploy URL
 - issue record
 - sign-off record
 
-Demo evidence produced by manual execution, Playwright, Browser Use, or Computer Use must be normalized into the same report and issue taxonomy.
+Demo evidence produced by manual execution, Playwright, Computer Use, Playwright MCP/ARIA/CDP, or compatible Browser Use must be normalized into the same report and issue taxonomy.
 
 ## Test Evidence Discipline
 

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

@@ -0,0 +1,33 @@
+# Filesystem Boundaries
+
+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/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 `.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:
 
-- `{paths.issues}/{module}/index.md` tracks every issue for that module and its status.
-- `{paths.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 | `.issues/{module}/{prefix}-0001-slug/` | `DEMO` | Development demo |
-| Smoke Issue | `.issues/{module}/{prefix}-0001-slug/` | `SMOKE` | Developer smoke |
-| Review Issue | `.issues/{module}/{prefix}-0001-slug/` | `REV` | Code/design review |
-| Defect | `.issues/{module}/{prefix}-0001-slug/` | `DEFECT` | Formal QA |
-| Verify Issue | `.issues/{module}/{prefix}-0001-slug/` | `VER` | Fix verification |
-| Acceptance Issue | `.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 `{paths.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, replace `.issues` with that configured root while preserving 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 `{paths.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.