@captain_z/zsk-skills 1.7.0 → 1.8.0

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/resources/`、`.zsk/modules/`、`.zsk/issues/`、`.zsk/evidence/`、`.zsk/playwright/` 和 `.zsk/plans/` 是默认项目上下文。CLI 负责创建最小骨架、使用 package-owned schema 校验、刷新 `.zsk/resources/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/resources`、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

@@ -40,7 +40,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,6 +58,8 @@ 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.
+- 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:
@@ -65,7 +67,9 @@ 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/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 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.
 

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,45 @@ 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`
+
+## Related Best-Practice Concerns
+
+- `SDLC traceability`
+- `quality evidence`
+- `system constraints`
+
+## 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`
+
 ## 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.
+- 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.
 
 ## Hard Stops
 
@@ -48,6 +75,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/` 同步生成 |
+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.
 
-## 为什么不再分组
+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,16 @@
+# 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/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.
+- `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.

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

@@ -2,28 +2,28 @@
 
 `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. 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.
 
 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/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.
 - 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/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 |
 
-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/issues/{module}/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 preserve the `{module}/{type}/` shape.
 
 ## Required Fields
 
@@ -79,7 +79,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 the issue under `.zsk/issues/{module}/` 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

@@ -0,0 +1,69 @@
+# Skill Role Contract
+
+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.
+
+## Role Completeness
+
+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;
+- keep all ZSK-managed artifacts under `.zsk` paths from the completion contract;
+- 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.
+
+## Forbidden Behavior
+
+- Do not create new project roots, ad hoc docs folders, loose evidence folders, or hidden state outside `.zsk`.
+- 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 silently cross into another skill's responsibility; route or record the handoff.
+- Do not claim PASS, READY, DONE, or ACCEPTED without linked evidence.
+
+## Expert Lane Rule
+
+When a skill has multiple expert concerns, it must execute all relevant lanes. If Codex native subagents or OMX team/runtime surfaces are available and the lanes are independent, dispatch bounded expert subagents and integrate their findings. If subagents are unavailable, run the same lanes sequentially and say so in the evidence.
+
+The lead skill remains accountable for the final verdict. Subagent output is supporting evidence, not an automatic pass.
+
+## Review-Specific Minimum
+
+`review` must always cover these lanes before a PASS verdict:
+
+- scope and requirement drift;
+- execution-path correctness;
+- tests and evidence adequacy;
+- security, auth, permissions, privacy, and data safety;
+- architecture, maintainability, API contracts, and dependency boundaries;
+- frontend, accessibility, React/Vue/framework, visual, and i18n checks when UI is touched;
+- performance, concurrency, migration, and rollout checks when touched;
+- ZSK harness compliance, output paths, issue taxonomy, and documentation feedback.
+
+For `DEEP` review, dispatch at least three independent expert lanes when subagents are available: architecture/API, security/data, and tests/evidence. Add frontend/performance specialists when the diff touches those domains.
+
+## ZSK Entry Points
+
+`zskplan` and `zsk` are ZSK-aware RalphPlan/Ralph-style user surfaces, not shortcuts around the harness.
+
+- `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.
+- 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.
+- A ZSK loop may not stop at "implemented" when review, Playwright, test, or configured validation evidence is required by the plan.
+
+## Learning Skill
+
+`learn` is a controlled self-learning loop:
+
+- 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/`;
+- 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

@@ -3,8 +3,8 @@
 Resource priority is:
 
 1. explicit project `.zsk/config.yaml`
-2. module docs under `docs/{module}/`
-3. raw sources under `.raws/`
+2. module docs and stage artifacts under `.zsk/modules/{module}/`
+3. raw source snapshots under `.zsk/resources/`
 4. code and runtime evidence
 5. user-provided clarification
 
@@ -17,3 +17,14 @@ 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.
+- 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.
+- 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.
+- 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 no authoritative reference can be retrieved, mark the item as a resource gap instead of guessing.