@captain_z/zsk-skills 1.5.1 → 1.6.1

package/README.md

@@ -2,38 +2,97 @@
 
 ZNorth Standard Kit 的可安装 skill 内容包。安装面现在只保留从根级 `skills/` 生成的 **core harness-first skills**；旧 `.best-practices/` 不再批量生成 installable skills，只作为扁平参考资料。
 
-包内共有 **18 颗 installable skills**，全部来自根级 `skills/`。
+包内共有 **19 颗 installable skills**，全部来自根级 `skills/`。
 
 ## 合规审查（ARCHITECTURE §4.4 硬指标）
 
 | 检查项                                                                                   | 结果    | 说明                                                  |
 | ---------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
-| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 18/18 | core 由 root `skills/` 生成 |
-| `name` 以 `zsk:` 前缀，扁平 slug                                                         | ✓ 18/18 | 安装面统一命名空间                                    |
-| `description` 有触发语义                                                                 | ✓ 18/18 | core 使用 `Use when...` + triggers |
-| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 18/18 | stage/utility · core |
-| `triggers` 数组非空                                                                      | ✓ 18/18 | 至少含 slug 和 `zsk:<slug>` |
+| 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 |
 | 无硬编码项目名 / 技术栈（统一 `{{config.*}}` 占位符）                                    | ✓       | harness-neutral                                       |
 | `related:` 相对路径合法                                                                  | ✓       | core 不依赖参考层生成物                               |
-| 单文件 ≤ 300 行                                                                          | ✓ 18/18 | core 由 `lint:harness` 强制                           |
+| 单文件 ≤ 300 行                                                                          | ✓ 19/19 | core 由 `lint:harness` 强制                           |
 
 当前 `max-lines` 已由 `tools/lint-frontmatter.ts` 作为 error 强制；新增或修改 skill 不应超过 300 行。
 
 ## 使用方法通则
 
-zsk skill 是 LLM **按需自动触发**的资产：
+zsk skill 是 LLM **按需自动触发**的资产。用户通常只做两件事：先安装 skill，再在业务项目里用 `zsk init` 建知识工作区。
 
-1. **安装**：`npx @captain_z/zsk add` → 选精简 bundle（或 custom 多选）+ 目标路径（`~/.claude/skills/` / `~/.codex/skills/` / 自定义）→ 落盘
+1. **安装**：`npx @captain_z/zsk add` → 选 profile bundle（或 custom 多选）+ 目标路径（`~/.claude/skills/` / `~/.codex/skills/` / 自定义）→ 落盘
 2. **自动发现**：LLM（Claude Code / Codex / Gemini CLI）会话启动时扫描 skill 目录，读取每份 `SKILL.md` 的 frontmatter
 3. **自动触发**：遇到匹配 `description` 或 `triggers` 的任务时，LLM 载入对应 SKILL.md 的完整内容
-4. **手动触发**（可选）：会话中显式说 "用 `zsk:spec`"、"走 `zsk:standard-dev-flow` 工作流"，LLM 直接载入指定 skill
+4. **手动触发**（可选）：会话中显式说 "用 `zsk:dispatch` 调度"、"用 `zsk:spec` 写规格"，LLM 直接载入指定 skill
+
+## Profile 选择
+
+Profile 是流程组合策略，不是新的 skill。Atomic skills 仍然平铺在 `skills/`，profile 只决定默认安装集合、阶段顺序、可选节点和严格度。
+
+| 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 |
+
+## Skill 搭配流程图
+
+`dispatch` 是 ZSK 给 OMX 的调度适配入口；`flow` 是恢复下一合法阶段的状态机入口；profile 决定主线顺序、可选节点和严格度，其他 skill 按阶段负责一段明确产物。遇到缺资料、缺证据、缺 owner 或发现缺陷时，阶段不会静默跳过，而是写 issue 或回到前置阶段补齐。
+
+```mermaid
+flowchart TD
+  Start([开始或恢复工作]) --> Dispatch[zsk:dispatch<br/>让 OMX 按 ZSK workflow 调度]
+  Dispatch --> Flow[zsk:flow<br/>读取状态与资源]
+  Flow --> Prepare[zsk:prepare<br/>收集 SRS/PRD/API/设计/测试来源]
+  Prepare --> Proposal[zsk:proposal<br/>定义 why / scope / non-goals]
+  Proposal --> Spec[zsk:spec<br/>写 FR/NFR/AC/场景]
+  Spec --> Design[zsk:design<br/>映射接口/数据流/风险]
+  Design --> Task[zsk:task<br/>拆任务与证据钩子]
+  Task --> Coding[zsk:coding<br/>小步实现]
+  Coding --> Smoke[zsk:smoke<br/>本地证明变更可运行]
+  Smoke --> Review[zsk:review<br/>阻塞式实现审查]
+  Review --> Commit[zsk:commit<br/>review 后 scoped commit]
+  Commit --> Ready[zsk:ready<br/>整理待验收证据]
+  Ready --> Verify[zsk:verify<br/>独立验证 claim]
+  Verify --> Acceptance[zsk:acceptance<br/>业务接受或拒绝]
+  Acceptance --> Archive[zsk:archive<br/>归档产物与学习反馈]
+
+  Coding -.发现问题.-> Issue[zsk:issue<br/>缺陷/阻塞/风险/问题]
+  Smoke -.失败.-> Issue
+  Review -.拒绝.-> Issue
+  Verify -.不通过.-> Issue
+  Issue --> Coding
+  Commit -.需要环境.-> Deploy[zsk:deploy<br/>部署到非生产/演示环境]
+  Deploy -.进入验证.-> Ready
+  Demo[zsk:demo<br/>正式测试前演示] --> Defect[zsk:defect<br/>QA 缺陷归类与复现]
+  Defect --> Coding
+  Commit -.需要演示.-> Demo
+```
+
+## 常见用法
+
+| 目标 | 推荐说法或命令 | 结果 |
+| --- | --- | --- |
+| 安装默认 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 |
+| 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:flow` 继续" | 读取配置、阶段文档和 blocker，选择合法下一阶段 |
+| 明确进入某阶段 | "用 `zsk:spec` 写模块规格" | 只载入对应 stage contract |
 
 **典型消费路径**（production，安装后）：
 
 - `~/.claude/skills/zsk-<slug>/SKILL.md` — Claude Code / flat target
 - `~/.codex/skills/zsk-<slug>/SKILL.md` — Codex / flat target
 - `./.claude-plugin/skills/<slug>/SKILL.md` + `commands/<slug>.md` — Claude plugin local target
-- `@captain_z/zsk-skills/core/<slug>/SKILL.md` — 通过 npm 读
+- `@captain_z/zsk-skills/<slug>/SKILL.md` — 通过 npm 读
 
 仓库根还发布 `.claude-plugin/plugin.json` 和 `.claude-plugin/marketplace.json`，用于 Claude Code `/plugin marketplace add codeshareman/zsk` + `/plugin install zsk@zsk`；根级 `skills/` 同时兼容 `npx skills add codeshareman/zsk`。
 
@@ -41,9 +100,9 @@ zsk skill 是 LLM **按需自动触发**的资产：
 
 `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` 做确定性校验。
 
-Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Modao、测试资产和设计资产，发现模块边界，做跨事实源冲突分析，优先用 Playwright CLI/MCP 验证运行时行为，仅在结构化自动化不足时使用 Browser Use / Computer Use，并把问题写入配置的 issue 根。Skills 必须通过 `.zsk/config.yaml` 和 `docs/{module}/module.yaml` 解析路径，不能硬编码 `.raws`、`docs` 或 `.issues`。
+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`。
 
-每个阶段都要把确认过的决策、约束、例外和验证结果写回持久文件。缺少 Documentation Feedback 时，`zsk check` 可以把它作为阶段未收口的证据。
+每个 skill/stage 的输入、输出、工具/能力、脚本策略和 Browser Use 策略由 harness 的 `skill-io-contract.yaml` 约束；完成后的产物路径、issue 索引同步和确认后的文档反哺由 `completion-contract.yaml` 约束。缺少 Documentation Feedback 时，`zsk check` 可以把它作为阶段未收口的证据。
 
 ## 领域总览
 
@@ -51,95 +110,84 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 
 | 领域              | skill 数 | 职责                                       |
 | ----------------- | -------- | ------------------------------------------ |
-| `core/`           | 18       | harness-first 默认工作流入口               |
-| **总计**          | **18**   |                                            |
+| `skills/`         | 19       | harness-first 默认工作流入口               |
+| **总计**          | **19**   |                                            |
 
 ## 安装套件（bundles.yaml）
 
 | name                           | skills | 场景                                          |
 | ------------------------------ | ------ | --------------------------------------------- |
-| `sdlc-only`                    | 18     | 精简 core 生命周期 |
-| `frontend-project`（推荐）     | 18     | 同 core；前端专项规则从 `.best-practices/` 按需读取 |
-| `frontend-with-design-handoff` | 18     | 同 core；设计交付规则从 `.best-practices/` 按需读取 |
+| `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` |
 | `custom`                       | 交互   | 通过 `zsk add` 任意多选                       |
 
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 18 skills -->
+<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 19 skills -->
 
-## Skill 清单（core）
+## Skill 清单（core skills）
 
-> 内容由 `tools/catalog.ts` 从 `packages/skills/core/*/SKILL.md` frontmatter 生成。重生成：`pnpm catalog`。
+> 内容由 `tools/catalog.ts` 从 `packages/skills/*/SKILL.md` frontmatter 生成。重生成：`pnpm catalog`。
 
-### `core/` — Core · harness-first 默认工作流入口 (18)
+### `<slug>/` — Core · harness-first 默认工作流入口 (19)
 
-- **`zsk:acceptance`** *[stage · core]*
-  Use when independent verify has passed and a product/business acceptance decision is required; blocks closure without linked evidence, residual-risk owner, and explicit accept/reject status.
-  触发：`acceptance` · `zsk:acceptance`
+- **`dispatch`**
+  At task intake, asks OMX to assign subagents to the right zsk skill from request, state, evidence, and blockers.
 
-- **`zsk:archive`** *[stage · core]*
-  Use when accepted work must be closed and preserved; archives artifacts, decisions, issues, and learning proposals without deleting current docs or mutating standards silently.
-  触发：`archive` · `zsk:archive`
+- **`flow`**
+  Starts or resumes delivery by reading state, resources, and blockers, then selecting the next legal stage.
 
-- **`zsk:coding`** *[stage · core]*
-  Use when approved tasks are ready for implementation; requires small auditable diffs, existing-pattern reuse, tests/evidence, and blocker reporting instead of scope rewriting.
-  触发：`coding` · `zsk:coding`
+- **`prepare`**
+  After project init, collects resource origins, snapshots evidence, and updates config/manifests before proposal/spec.
 
-- **`zsk:commit`** *[stage · core]*
-  Use only after self-test and review pass; prepares a scoped commit with intent and evidence, and forbids staging unrelated dirty files or continuing implementation.
-  触发：`commit` · `zsk:commit`
+- **`proposal`**
+  Before spec, frames the problem, scope, non-goals, success criteria, stakeholders, risks, and resource gaps.
 
-- **`zsk:demo`** *[stage · core]*
-  Use before formal testing to prove the changed user flow can be demonstrated; requires planned scenarios, demo-only issue separation, evidence, and no acceptance claims.
-  触发：`demo` · `zsk:demo`
+- **`spec`**
+  After proposal, defines sourced FR/NFR, acceptance criteria, scenarios, edge cases, and open gaps.
 
-- **`zsk:deploy`** *[stage · core]*
-  Use when reviewed work must be deployed to a non-production/demo environment; requires URL/version, smoke evidence, rollback owner, and explicit production-authority guard.
-  触发：`deploy` · `zsk:deploy`
+- **`design`**
+  After spec freeze, maps behavior to interfaces, data flow, rollout plan, risks, and implementation surfaces.
 
-- **`zsk:design`** *[stage · core]*
-  Use after spec freeze to map behavior to implementation structure; requires interfaces/data flow/rollout/risks and rejects speculative architecture or invented design facts.
-  触发：`design` · `zsk:design`
+- **`task`**
+  After design approval, creates executable tasks with dependencies, FR/AC coverage, owners, and evidence hooks.
 
-- **`zsk:prepare-resources`** *[stage · core]*
-  Use after project init and before proposal/spec work to collect SRS, PRD, API, backend repository, design, and test resources; asks only for missing origins, chooses low-token acquisition tools, snapshots evidence, and updates config/manifests without inventing facts.
-  触发：`prepare-resources` · `zsk:prepare-resources`
+- **`coding`**
+  For approved tasks, implements small scoped diffs with tests, evidence, and blocker reporting.
 
-- **`zsk:proposal`** *[stage · core]*
-  Use before spec work to frame why/what/not-what; requires scope, non-goals, success criteria, stakeholders, risks, and explicit resource gaps instead of assumptions.
-  触发：`proposal` · `zsk:proposal`
+- **`smoke`**
+  After coding, proves changed behavior locally with targeted tests and relevant lint/typecheck/build evidence.
 
-- **`zsk:ready-for-verify`** *[stage · core]*
-  Use when fixed work is ready for independent verification; requires issue-to-evidence mapping, deployment/version notes, regression notes, and blocks vague handoffs.
-  触发：`ready-for-verify` · `zsk:ready-for-verify`
+- **`review`**
+  After smoke, reviews implementation against scope, specs, tasks, tests, security, maintainability, and evidence.
 
-- **`zsk:review`** *[stage · core]*
-  Use after self-test to run a blocking implementation review against scope, spec/design/tasks, tests, security, maintainability, and evidence; fails on hard stops, unapproved creep, or key test gaps.
-  触发：`review` · `zsk:review`
+- **`commit`**
+  After smoke and review pass, prepares a scoped commit with intent, evidence, and clean staging.
 
-- **`zsk:self-test`** *[stage · core]*
-  Use after coding and before review to prove changed behavior locally; requires targeted tests plus relevant lint/typecheck/build/smoke evidence and failure classification.
-  触发：`self-test` · `zsk:self-test`
+- **`demo`**
+  Before formal testing, runs planned demos and captures evidence without making acceptance claims.
 
-- **`zsk:spec`** *[stage · core]*
-  Use after proposal to define the behavioral contract; requires sourced FR/NFR, observable acceptance criteria, scenarios, edge cases, and unresolved resource gaps.
-  触发：`spec` · `zsk:spec`
+- **`defect`**
+  After formal QA reports findings, normalizes defects with repro, evidence, FR/AC links, and fix routing.
 
-- **`zsk:standard-dev-flow`** *[stage · core]*
-  Use when starting/resuming normal delivery; reads harness state/resources/blockers, selects the next legal stage, and stops on missing inputs or illegal transitions.
-  触发：`standard-dev-flow` · `zsk:standard-dev-flow`
+- **`ready`**
+  Before independent verification, prepares a handoff with issue mappings, evidence, version, and regression notes.
 
-- **`zsk:task`** *[stage · core]*
-  Use after design approval to create executable tasks; requires dependency order, FR/AC coverage, evidence hooks, owners, and blocks vague or unrelated work items.
-  触发：`task` · `zsk:task`
+- **`verify`**
+  Independently verifies fixes or acceptance criteria against a stated claim, target version, and linked evidence.
 
-- **`zsk:test-issue`** *[stage · core]*
-  Use after demo handoff when formal QA reports findings; requires Test Issue taxonomy, reproduction/evidence, FR/AC linkage, dedupe, and coding/verify routing.
-  触发：`test-issue` · `zsk:test-issue`
+- **`acceptance`**
+  After independent verify passes, records accept/reject decision, linked evidence, and residual-risk owner.
 
-- **`zsk:verify`** *[stage · core]*
-  Use when fixes or acceptance criteria need independent verification; requires a stated claim, versioned target, linked evidence, targeted rerun, and pass/fail route.
-  触发：`verify` · `zsk:verify`
+- **`deploy`**
+  After review, deploys to non-production or demo targets with version, smoke evidence, and rollback owner.
 
-- **`zsk:issue`** *[utility · core]*
-  Use when any stage finds a defect, blocker, question, or risk that needs tracking; requires taxonomy, severity, owner, reproduction/evidence, and no gate bypass.
-  触发：`issue` · `zsk:issue`
+- **`archive`**
+  After acceptance, closes the iteration by preserving artifacts, decisions, issues, and learning proposals.
+
+- **`issue`**
+  Tracks defects, blockers, questions, and risks with taxonomy, severity, owner, reproduction, and evidence.
 

package/{core/acceptance → acceptance}/SKILL.md

@@ -1,8 +1,7 @@
 ---
-name: zsk:acceptance
-description: Use when independent verify has passed and a product/business
-  acceptance decision is required; blocks closure without linked evidence,
-  residual-risk owner, and explicit accept/reject status.
+name: acceptance
+description: After independent verify passes, records accept/reject decision,
+  linked evidence, and residual-risk owner.
 kind: workflow-node
 pack: core
 stage: acceptance
@@ -14,7 +13,6 @@ category: stage
 tier: core
 triggers:
   - acceptance
-  - zsk:acceptance
 ---
 
 # Acceptance
@@ -34,28 +32,40 @@ Use this stage after independent `verify` has passed and the product/business ow
 2. Confirm P0/P1 acceptance criteria are verified or explicitly waived.
 3. Summarize residual risks, owners, and follow-up issues.
 4. Record one decision: `ACCEPT`, `ACCEPT_WITH_RISK`, `REJECT`, or `BLOCKED`.
-5. Route `ACCEPT*` to `archive`; route rejection to the earliest invalidated stage.
+5. For `ACCEPT*`, apply documentation feedback from linked issues: update module spec/design/task docs and project specs for behavior that was missing, ambiguous, or under-described.
+6. Route `ACCEPT*` to `archive`; route rejection to the earliest invalidated stage.
 
 ## Constraints
 
 - 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.
 - Keep the decision short, dated, and evidence-linked.
 
 ## Outputs
 
 - `acceptance` decision artifact.
 - Residual-risk list with owner and due date.
+- Updated spec/design/task documentation feedback or explicit no-update rationale.
 - Archive readiness or rejection route.
 
-## Installed Harness Contract
+## Harness Contract
 
-This core skill is generated from root `skills/acceptance/SKILL.md` and is governed by the zsk harness. Enforce these rules even when the full harness files are not present in the target:
+This core skill is governed by the ZSK harness. Enforce these rules even when only this `SKILL.md` is visible:
 
 - Stage gates: do not skip required inputs, illegal transitions, blockers, or evidence checks.
 - 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, self-test, review, test, verify, and acceptance findings to the correct issue type.
+- Issue taxonomy: route demo, smoke, review, test, verify, and acceptance findings to the correct issue type.
 - 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/state-machine.yaml` and `harness/constraints/stage-gates.md` before moving between stages.
+- 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.
+

package/acceptance/harness/README.md

@@ -0,0 +1,104 @@
+# Installed ZSK Harness Contract
+
+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.
+
+---
+# zsk Harness
+
+`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.
+
+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.

package/acceptance/harness/THIS_SKILL.md

@@ -0,0 +1,58 @@
+# acceptance · Focused Harness Contract
+
+This file is generated for the installed skill. Read it before executing this skill.
+
+## Responsibility
+
+- Skill: `acceptance`
+- Stage/type: `acceptance`
+- Purpose: After independent verify passes, records accept/reject decision, linked evidence, and residual-risk owner.
+
+## Required Inputs
+
+- `verify-report`
+- `demo-report`
+- `residual-risks`
+- `linked-issues`
+
+## Required Outputs
+
+- `acceptance-decision`
+- `confirmed-doc-feedback`
+- `residual-risk-list`
+
+## Allowed Tools And Capabilities
+
+- Tools: `filesystem`, `issue-update`
+- Capabilities: `business-acceptance`, `documentation-feedback`
+- Script policy: `optional`
+- Browser Use policy: `never`
+
+## 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/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`
+
+## Hard Stops
+
+- Required input is missing, stale, or contradictory.
+- The requested work belongs to an earlier or later ZSK stage.
+- 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.
+
+## Completion Checklist
+
+- Required outputs above are produced or explicitly blocked.
+- Evidence is linked and reproducible.
+- Issues and indexes are updated when actionable findings exist.
+- Documentation Feedback is recorded when confirmed behavior changes or gaps are found.
+- Next ZSK stage is stated without bypassing the state machine.

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

@@ -0,0 +1,52 @@
+# .best-practices/
+
+这里是旧内容库收敛后的扁平参考层，不是默认安装清单。当前只保留 7 个可 lint 的参考文件。
+
+## 现在怎么分工
+
+| 路径 | 职责 | 维护规则 |
+| --- | --- | --- |
+| `skills/` | 默认安装的 core skills 源码 | 高频动作才放这里，`SKILL.md` 必须自带输入、流程、约束和输出 |
+| `harness/` | 状态机、门禁、资源、证据、issue taxonomy、自我学习提升规则 | 管全局约束，不复制每个 skill 的正文 |
+| `.best-practices/` | 少量可选参考资料 | 只保留领域总览和横切规则，分类写在 frontmatter |
+| `capabilities/skills/` | 生成缓存 | 只由脚本生成 core installable skills，不手改 |
+| `packages/skills/` | npm 发布包 | 由 `capabilities/skills/` 同步生成 |
+
+## 为什么不再分组
+
+物理分组会带来两套同步成本：文件在哪个目录、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
+```

package/acceptance/harness/best-practices/agent-orchestration.md

@@ -0,0 +1,45 @@
+---
+name: zsk:agent-orchestration
+description: Agent orchestration reference — main-agent ownership, when to delegate, role boundaries, write ownership, review integration, and fallback when delegation is unavailable.
+category: resource
+domain: system
+tier: core
+related:
+  - ./sdlc.md
+  - ./quality.md
+  - ./system.md
+triggers:
+  - "sub agent orchestration"
+  - "parallel agents"
+  - "agent responsibilities"
+  - "delegate tasks"
+---
+
+# Agent Orchestration
+
+主 Agent 对结果负责。Sub-Agent 只能承担明确范围内的探索、实现、审查或验证，不能替主 Agent 做最终放行。
+
+## 何时拆
+
+- 任务跨多个独立领域，比如前端、API、测试、安全。
+- diff 或计划跨 5 个以上文件。
+- 涉及权限、资金、数据一致性、迁移、公共 API、性能关键路径。
+- 用户明确要求并行、子代理、各司其职。
+
+## 角色边界
+
+| 角色 | 职责 | 禁止 |
+| --- | --- | --- |
+| Main | 目标理解、拆分、整合、最终判断 | 原样转述子结论就放行 |
+| Explorer | 只读扫描、证据定位、风险列表 | 修改文件 |
+| Worker | 在指定文件范围内实现 | 改未授权范围、回滚未知改动 |
+| Reviewer | 找缺陷、风险、测试缺口 | 直接替代实现或验收 |
+| Verifier | 跑验证、核证据 | 没跑就声称通过 |
+
+## 写权限规则
+
+并行 Worker 必须有明确 owned files/modules。遇到共享文件冲突、范围扩大、用户改动影响当前任务时，停止并回报主 Agent。
+
+## 降级规则
+
+如果当前平台不能派发 Sub-Agent，主 Agent 按同样角色顺序自查，并在最终输出中说明已降级为单 Agent 执行。