@captain_z/zsk-skills 1.8.7 → 1.8.9

package/README.md

@@ -9,7 +9,7 @@ ZNorth Standard Kit 的可安装 skill 内容包。安装面现在只保留从
 | 检查项                                                                                   | 结果    | 说明                                                  |
 | ---------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
 | frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 24/24 | core 由 root `skills/` 生成 |
-| `name` 使用裸 slug，扁平且不含连字符                                                       | ✓ 24/24 | LLM 原生 skill 入口保持简洁；CLI 选择层使用 `zsk:<slug>` |
+| `name` 使用 `zsk-<slug>` 公共命名空间，目录同名且只含小写/数字/连字符                         | ✓ 24/24 | 避免和其它 skill 仓库裸名冲突；CLI 选择层继续使用 `zsk:<slug>` |
 | `description` 简洁表达职责和使用时机                                                       | ✓ 24/24 | 面向索引阅读；triggers 留给机器使用 |
 | `category` / `domain` / `tier` 枚举值合法                                                | ✓ 24/24 | stage/utility · core |
 | `triggers` 数组非空                                                                      | ✓ 24/24 | 至少含裸 slug |
@@ -30,33 +30,33 @@ zsk skill 是 LLM **按需自动触发**的资产。用户通常只做两件事
 
 ## Profile 选择
 
-Profile 是流程组合策略，不是新的 skill。Atomic skills 仍然平铺在 `skills/`，profile 只决定默认安装集合、阶段顺序、可选节点和严格度。
+Profile 是流程组合策略，不是新的 skill。Atomic skills 仍然平铺在 `skills/`，profile 只决定默认安装集合、阶段顺序、可选节点和严格度。Workflow 负责编排、约束、签字、角色投入和多角度会诊；单个 skill 只负责自己的职责、非目标、输出质量、证据、风险和置信度。
 
 | profile | skills | 适用场景 |
 | --- | ---: | --- |
 | `zsk-entry` | 2 | 只装 `zskplan` / `zsk` 两个主入口，由它们按 harness 调度 |
-| `zsk-lite` | 11 | 小修、小项目、脚本、低风险任务 |
-| `zsk-sdlc` | 21 | 标准工程交付；需求、实现、审查、验证、验收、归档 |
-| `zsk-frontend` | 22 | UI/UX/browser-facing 交付；强化 demo、视觉证据、前端质量门禁 |
-| `zsk-enterprise` | 22 | 高治理交付；要求 deploy、验收、归档、审计证据 |
+| `zsk-lite` | 4 | 小修、小项目、脚本、低风险任务；只暴露入口和 coding/verify |
+| `zsk-sdlc` | 12 | 标准工程交付；安装入口 + 一等阶段，capability/gate 由 workflow 调度 |
+| `zsk-frontend` | 13 | UI/UX/browser-facing 交付；基于 SDLC 阶段面加装 demo |
+| `zsk-enterprise` | 12 | 高治理交付；deploy/audit/review 由 profile gate/capability 开启 |
 | `sdlc-only` | 24 | 旧入口兼容；安装全部 core skills |
 
 ## Skill 搭配流程图
 
-`dispatch` 是 ZSK 给 OMX 的调度适配入口；`flow` 是恢复下一合法阶段的状态机入口；profile 决定主线顺序、可选节点和严格度，其他 skill 按阶段负责一段明确产物。遇到缺资料、缺证据、缺 owner 或发现缺陷时，阶段不会静默跳过，而是写 issue 或回到前置阶段补齐。
+`dispatch` 是 ZSK 给 OMX 的调度适配入口；`flow` 是恢复下一合法阶段的状态机入口；profile 决定主线顺序、可选节点和严格度，其他 skill 按阶段负责一段明确产物。遇到缺资料、缺证据、缺 owner 或发现缺陷时，workflow 决定是否降级、补资源、回退或阻塞；skill 本身记录 gap、影响和下一步，不把 sibling skill 的产物当作缺一不可的硬前置。
 
 ```mermaid
 flowchart TD
   Start([开始或恢复工作]) --> Dispatch[zsk:dispatch<br/>让 OMX 按 ZSK workflow 调度]
   Dispatch --> Flow[zsk:flow<br/>读取状态与资源]
-  Flow --> Prepare[zsk:prepare<br/>收集 SRS/PRD/API/设计/测试来源]
+  Flow --> Prepare[zsk:prepare<br/>计划并选择性同步资源]
   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/>阻塞式实现审查]
+  Smoke --> Review[zsk:review<br/>目标审查/多角度可选]
   Review --> Commit[zsk:commit<br/>review 后 scoped commit]
   Commit --> Ready[zsk:ready<br/>整理待验收证据]
   Ready --> Verify[zsk:verify<br/>独立验证 claim]
@@ -75,16 +75,21 @@ flowchart TD
   Commit -.需要演示.-> Demo
 ```
 
+Direct review 只需要明确 review target（代码 diff、本地路径、stage 文档或可检测变更）。缺少 spec/design/tasks/smoke/signoff/专家面板时，`review` 应记录为 N/A、风险或 confidence gap，并继续做目标审查；只有 workflow profile 明确启用 strict gate 时，才由 workflow 把这些缺口升级为阻塞。
+
+每个 stage 输出都应包含 `Output Quality Check`：质量分、置信度、证据、缺口/不确定性、漂移信号、下一步。若缺口属于本 skill 职责内，应先做 bounded ReAct 修复；若属于 workflow 编排、资源准备或外部决策，则交给 workflow 路由。
+
 ## 常见用法
 
 | 目标 | 推荐说法或命令 | 结果 |
 | --- | --- | --- |
 | 安装默认 core skills | `npx @captain_z/zsk add` | 交互选择 target 和 bundle |
 | 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` | 非交互安装 11 颗常用 skills |
-| CI 安装标准 SDLC profile | `npx @captain_z/zsk add zsk-sdlc --target=~/.claude/skills --yes` | 非交互安装 21 颗标准 workflow skills |
+| CI 安装轻量 profile | `npx @captain_z/zsk add zsk-lite --target=~/.claude/skills --yes` | 非交互安装 4 颗入口/执行 skills |
+| CI 安装标准 SDLC profile | `npx @captain_z/zsk add zsk-sdlc --target=~/.claude/skills --yes` | 非交互安装 12 颗标准 entry/stage skills |
 | Claude plugin 安装 | `/plugin marketplace add codeshareman/zsk` 后 `/plugin install zsk@zsk` | 使用 `/zsk:<slug>` 命令面 |
-| GitHub skills 管理器安装 | `npx skills add codeshareman/zsk` | 从仓库根 `skills/` 安装；不要加 `@` |
+| GitHub skills 管理器安装 | `npx skills add codeshareman/zsk` | 从仓库安装 `zsk-<slug>` 公共命名空间；不要加 `@` |
+| 准备项目资源 | `npx @captain_z/zsk prepare draft && npx @captain_z/zsk prepare plan && npx @captain_z/zsk prepare sync --all` | 先审查建议，再同步确认后的 `.zsk/raws/**` snapshot |
 | 只想让 ZSK 自己规划和执行 | "用 `zsk:zskplan` 规划" / "用 `zsk:zsk` 继续" | 计划写入 `.zsk/plans/`，执行产物写入 `.zsk` |
 | 不确定该用哪个阶段 skill | "用 `zsk:dispatch` 调度" | 让 OMX 围绕 ZSK skills 分配 subagents |
 | 恢复一个项目的下一步 | "用 `zsk:flow` 继续" | 读取配置、阶段文档和 blocker，选择合法下一阶段 |
@@ -95,17 +100,18 @@ flowchart TD
 - `~/.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/<slug>/SKILL.md` — 通过 npm 读
+- `skills/.curated/zsk-<slug>/SKILL.md` — `npx skills` / Claude plugin marketplace repository target
+- `@captain_z/zsk-skills/zsk-<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`。
+仓库根还发布 `.claude-plugin/plugin.json` 和 `.claude-plugin/marketplace.json`，用于 Claude Code `/plugin marketplace add codeshareman/zsk` + `/plugin install zsk@zsk`；根级 `skills/.curated/` 同时兼容 `npx skills add codeshareman/zsk`。
 
 ## 和项目知识工作区的关系
 
-`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` 做确定性校验。
+`zsk init` 生成的 `.zsk/config.yaml`、`.zsk/CONTEXT.md`、`.zsk/docs/SYSTEM-SPEC.md`、`.zsk/raws/`、`.zsk/modules/`、`.zsk/issues/`、`.zsk/evidence/`、`.zsk/playwright/` 和 `.zsk/plans/` 是默认项目上下文。CLI 负责创建最小骨架、使用 package-owned schema 校验、通过 `zsk prepare draft` / `zsk prepare plan` 生成可审查建议，并通过 `zsk prepare sync` 选择性刷新 `.zsk/raws/manifest.json`、snapshot 和 readiness evidence。`zsk config check` / `zsk check` 做确定性校验。
 
-Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Modao、测试资产和设计资产，发现模块边界，做跨事实源冲突分析，并把问题写入配置的 issue 根。运行时验证默认用 Playwright 产生可复现 evidence；登录态优先转成 Playwright `storageState`；视觉/当前页面判断优先 Computer Use；没有 Computer Use 的运行时用 Playwright MCP/ARIA/CDP、手工证据或可用的 Browser Use 兼容处理。Skills 必须通过 `.zsk/config.yaml` 和 `.zsk/modules/{module}/module.yaml` 解析路径，不能硬编码 `.zsk/raws`、root `docs`、root `.issues`、root `.playwright` 或 root `plans`。
+Skills 负责更需要判断的部分：理解已同步的 SRS、PRD、API 契约、Figma/Modao、测试资产和设计资产，发现模块边界，做跨事实源冲突分析，并把问题写入配置的 issue 根。运行时验证默认用 Playwright 产生可复现 evidence；登录态优先转成 Playwright `storageState`；视觉/当前页面判断优先 Computer Use；没有 Computer Use 的运行时用 Playwright MCP/ARIA/CDP、手工证据或可用的 Browser Use 兼容处理。Skills 必须通过 `.zsk/config.yaml` 和 `.zsk/modules/{module}/module.yaml` 解析路径，不能硬编码 `.zsk/raws`、root `docs`、root `.issues`、root `.playwright` 或 root `plans`。
 
-每个 skill/stage 的输入、输出、工具/能力、脚本策略和运行时 UI 观察策略由 harness 的 `skill-io-contract.yaml` 约束；完成后的产物路径、issue 索引同步和确认后的文档反哺由 `completion-contract.yaml` 约束。缺少 Documentation Feedback 时，`zsk check` 可以把它作为阶段未收口的证据。
+每个 skill/stage 的输入、输出、工具/能力、脚本策略和运行时 UI 观察策略由 harness 的 `skill-io-contract.yaml` 约束；完成后的产物路径、issue 索引同步和确认后的文档反哺由 `completion-contract.yaml` 约束；质量评分、角色/人员建议和 direct review 降级规则由 `quality-roles.yaml`、`skill-classification.yaml` 和 `workflow-orchestration-policy.yaml` 共同说明。缺少 Documentation Feedback 时，`zsk check` 可以把它作为阶段未收口的证据。
 
 ## 领域总览
 
@@ -121,10 +127,10 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 | name                           | skills | 场景                                          |
 | ------------------------------ | ------ | --------------------------------------------- |
 | `zsk-entry`                    | 2      | 只安装 ZSK / ZSK Plan 两个主入口 |
-| `zsk-lite`                     | 11     | 小型低风险任务；ZSK 入口 + fix/coding → smoke → review → commit |
-| `zsk-sdlc`（推荐）             | 21     | 标准工程交付；完整需求、实现、审查、验证、验收、归档链路 |
-| `zsk-frontend`                 | 22     | 前端/视觉/browser-facing 任务；强化 demo 和前端质量门禁 |
-| `zsk-enterprise`               | 22     | 高治理交付；要求 deploy、验收、归档、审计证据 |
+| `zsk-lite`                     | 4      | 小型低风险任务；入口 + coding/verify，review/smoke/commit 作为 workflow capability |
+| `zsk-sdlc`（推荐）             | 12     | 标准工程交付；安装入口 + 一等阶段 |
+| `zsk-frontend`                 | 13     | 前端/视觉/browser-facing 任务；强化 demo 和 evidence |
+| `zsk-enterprise`               | 12     | 高治理交付；deploy/audit/review 由 profile gate/capability 开启 |
 | `sdlc-only`                    | 24     | 旧入口兼容；安装全部 core skills |
 | `frontend-project`             | 24     | 旧入口兼容；推荐改用 `zsk-frontend` |
 | `frontend-with-design-handoff` | 24     | 旧入口兼容；推荐改用 `zsk-frontend` |
@@ -134,98 +140,98 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 
 ## Skill 清单（core skills）
 
-> 内容由 `tools/catalog.ts` 从 `packages/skills/*/SKILL.md` frontmatter 生成。重生成：`pnpm catalog`。
+> 内容由 `tools/catalog.ts` 从 `packages/skills/zsk-*/SKILL.md` frontmatter 生成。重生成：`pnpm catalog`。
 > 默认 profile bundles 只安装 entry 和保留的一等 stage；capability / gate / mode 由 `zskplan` / `zsk` 内部调度或通过 custom/legacy 明确安装。Legacy aliases 仍保留 24 个 skill 以兼容旧安装。
 
 ### Entry Skills (2)
 
 用户默认只需要理解的入口。
 
-- **`zskplan`** · keep-entry
+- **`zsk-zskplan`** · type: workflow · keep-entry
   Use as the ZSK-aware RalphPlan-style planning entrypoint that clarifies vague intake, then freezes scope, module decomposition, skill route, expert lanes, Playwright/evidence paths, and stop conditions under .zsk.
 
-- **`zsk`** · keep-entry
+- **`zsk-zsk`** · type: workflow · keep-entry
   Use as the ZSK-aware Ralph-style execution loop that follows ZSK plans, dispatches expert lanes, verifies, fixes, and writes only .zsk outputs.
 
 ### Stage Skills (11)
 
 有独立产物边界、质量门禁和下游消费关系的一等阶段。
 
-- **`prepare`** · keep-stage
+- **`zsk-prepare`** · type: capability · keep-stage
   After project init, collects resource origins, snapshots evidence, and updates config/manifests before proposal/spec.
 
-- **`preproposal`** · keep-stage
+- **`zsk-preproposal`** · type: capability · keep-stage
   Before proposal, turns a one-sentence or vague intake brief into a clear, reviewed product, roadmap, UX, and readiness raw resource pack.
 
-- **`proposal`** · keep-stage
+- **`zsk-proposal`** · type: capability · keep-stage
   Before spec, frames the problem, scope, non-goals, success criteria, stakeholders, risks, and resource gaps.
 
-- **`spec`** · keep-stage
+- **`zsk-spec`** · type: capability · keep-stage
   After proposal, defines sourced FR/NFR, acceptance criteria, scenarios, edge cases, and open gaps.
 
-- **`design`** · keep-stage
+- **`zsk-design`** · type: capability · keep-stage
   After spec freeze, maps behavior to interfaces, data flow, rollout plan, risks, and implementation surfaces.
 
-- **`task`** · keep-stage
+- **`zsk-task`** · type: capability · keep-stage
   After design approval, creates executable tasks with dependencies, FR/AC coverage, owners, and evidence hooks.
 
-- **`coding`** · keep-stage
+- **`zsk-coding`** · type: capability · keep-stage
   For approved tasks, implements small scoped diffs with tests, evidence, and blocker reporting.
 
-- **`demo`** · keep-stage
+- **`zsk-demo`** · type: capability · keep-stage
   Before formal testing, runs planned demos and captures evidence without making acceptance claims.
 
-- **`verify`** · keep-stage
+- **`zsk-verify`** · type: capability · keep-stage
   Independently verifies fixes or acceptance criteria against a stated claim, target version, and linked evidence.
 
-- **`acceptance`** · keep-stage
+- **`zsk-acceptance`** · type: capability · keep-stage
   After independent verify passes, records accept/reject decision, linked evidence, and residual-risk owner.
 
-- **`archive`** · keep-stage
+- **`zsk-archive`** · type: capability · keep-stage
   After acceptance, closes the iteration by preserving artifacts, decisions, issues, and learning proposals.
 
 ### Capabilities (6)
 
 可被多个阶段复用的内部能力；默认由入口或阶段调度。
 
-- **`dispatch`** · downshift-to-capability
+- **`zsk-dispatch`** · type: workflow · downshift-to-capability
   At task intake, asks OMX to assign subagents to the right zsk skill from request, state, evidence, and blockers.
 
-- **`review`** · downshift-to-capability
+- **`zsk-review`** · type: capability · downshift-to-capability
   After smoke or explicit path targeting, reviews implementation or local targets against scope, contracts, evidence, security, maintainability, and ZSK boundaries.
 
-- **`defect`** · downshift-to-capability
+- **`zsk-defect`** · type: capability · downshift-to-capability
   After formal QA reports findings, normalizes defects with repro, evidence, FR/AC links, and fix routing.
 
-- **`deploy`** · downshift-to-capability
+- **`zsk-deploy`** · type: capability · downshift-to-capability
   After review, deploys to non-production or demo targets with version, smoke evidence, and rollback owner.
 
-- **`learn`** · downshift-to-capability
+- **`zsk-learn`** · type: capability · downshift-to-capability
   Use after repeated friction or supplied public skill/harness references to learn, compare, record gaps, and prepare one reviewed ZSK optimization batch.
 
-- **`issue`** · keep-capability
+- **`zsk-issue`** · type: utility · keep-capability
   Tracks defects, blockers, questions, and risks with taxonomy, severity, owner, reproduction, and evidence.
 
 ### Gates (3)
 
 阶段内部的质量检查点或发布检查点。
 
-- **`smoke`** · downshift-to-gate
+- **`zsk-smoke`** · type: capability · downshift-to-gate
   After coding, proves changed behavior locally with targeted tests and relevant lint/typecheck/build evidence.
 
-- **`commit`** · downshift-to-gate
+- **`zsk-commit`** · type: capability · downshift-to-gate
   After smoke and review pass, prepares a scoped commit with intent, evidence, and clean staging.
 
-- **`ready`** · downshift-to-gate
+- **`zsk-ready`** · type: capability · downshift-to-gate
   Before independent verification, prepares a handoff with issue mappings, evidence, version, and regression notes.
 
 ### Modes (2)
 
 入口或阶段内部的执行模式。
 
-- **`flow`** · downshift-to-mode
+- **`zsk-flow`** · type: workflow · downshift-to-mode
   Starts or resumes delivery by reading state, resources, and blockers, then selecting the next legal stage.
 
-- **`fix`** · downshift-to-mode
+- **`zsk-fix`** · type: workflow · downshift-to-mode
   For persisted issues, diagnoses root cause, applies the smallest scoped correction, adds a regression guard, updates the issue, and hands off verification.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@captain_z/zsk-skills",
-  "version": "1.8.7",
+  "version": "1.8.9",
   "description": "ZNorth Standard Kit — core harness-first skill content package",
   "license": "MIT",
   "files": [

package/zsk-acceptance/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: zsk-acceptance
+description: After independent verify passes, records accept/reject decision,
+  linked evidence, and residual-risk owner.
+kind: workflow-node
+skillType: capability
+pack: core
+stage: acceptance
+requires:
+  - constraints.evidence-rules
+  - constraints.stage-gates
+domain: core
+category: stage
+tier: core
+triggers:
+  - acceptance
+useWhen:
+  - "Use when the workflow is ready for this responsibility: After independent
+    verify passes, records accept/reject decision, linked evidence, and
+    residual-risk owner."
+  - Use when the user invokes zsk:acceptance or asks for acceptance outputs
+    after prerequisites are present.
+doNotUseWhen:
+  - Do not use when required inputs, prior-stage evidence, or configured sources
+    for acceptance are missing.
+  - Do not use to bypass stage gates, perform another skill's responsibility, or
+    make unsupported completion claims.
+positiveExamples:
+  - Run zsk:acceptance with the required inputs and produce the documented
+    acceptance artifacts.
+  - Run this skill only for its owned outputs after prerequisites are present;
+    let workflow skills decide subsequent stage routing.
+negativeExamples:
+  - Use zsk:acceptance to skip missing prerequisites or hide unresolved blockers.
+  - Run acceptance for generic chat, unrelated implementation, or another ZSK
+    stage's work.
+---
+
+# Acceptance
+
+Use this stage after independent `verify` has passed and the product/business owner needs an acceptance decision. Acceptance is not another implementation review; it decides whether the delivered change is fit to close, reject, or archive with explicit residual risk.
+
+## Inputs
+
+- `verify-report` with linked evidence and unresolved findings.
+- `demo-report` when the change has user-visible behavior.
+- Linked issue records, waivers, and regression notes.
+- Proposal/spec/design/task artifacts for the accepted scope.
+
+## Procedure
+
+1. Re-check the accepted scope against proposal and spec, not against late wish-list items.
+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. 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 `.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
+
+- `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.
+
+## Skill Quality Contract
+
+This is the default direct-run quality contract for this skill. It is generated from the canonical harness contracts so standalone skill use stays high quality without loading full workflow gates.
+
+### Responsibility
+
+- Own: Record the accept/reject business decision and residual-risk ownership.
+- Stage/type: `acceptance` / `capability`
+- Output goal: Record the accept/reject business decision and residual-risk ownership.
+- Downstream consumer: The next legal workflow stage, reviewer, or human decision maker.
+- Stop condition: Required outputs are complete, explicitly N/A, or BLOCKED/NEEDS_CLARIFICATION with owner, impact, and next action.
+- Document mode: decisionRecord
+
+### Non-goals
+
+- Do not route, approve, staff, gate, or sequence peer skills from this skill.
+- Do not redefine upstream intent or accept downstream work on another skill's behalf.
+- Workflow-owned constraint, not this skill's local responsibility: sequencing.
+- Workflow-owned constraint, not this skill's local responsibility: routing.
+- Workflow-owned constraint, not this skill's local responsibility: staffing.
+- Workflow-owned constraint, not this skill's local responsibility: gates.
+- Workflow-owned constraint, not this skill's local responsibility: approvals.
+- Workflow-owned constraint, not this skill's local responsibility: signoffs.
+- Workflow-owned constraint, not this skill's local responsibility: cross-skill arbitration.
+- Workflow-owned constraint, not this skill's local responsibility: downstream acceptance.
+
+### Inputs And Outputs
+
+Direct mode starts from the user's explicit target. Workflow-only artifacts, approvals, signoffs, validation packets, and peer-skill outputs are optional context unless a workflow, strict profile, or local instruction explicitly makes them required.
+
+**Direct hard inputs**
+
+- explicit-skill-target
+
+**Direct optional context**
+
+- workflow-packet
+- upstream-artifacts
+- validation-packet
+- anchor-packet
+- gate-evidence
+- peer-skill-artifacts
+
+**Declared skill inputs**
+
+- verify-report
+- demo-report
+- residual-risks
+- linked-issues
+
+**Required outputs**
+
+- acceptance-decision
+- confirmed-doc-feedback
+- residual-risk-list
+
+### Quality Rubric
+
+**Rubric fields**
+
+- output_goal
+- downstream_consumer
+- required_inputs
+- required_outputs
+- must_answer_questions
+- quality_checks
+- anti_patterns
+- stop_condition
+
+**Hard acceptance rules**
+
+- Record accept, reject, or conditional acceptance decision with linked verify/demo evidence.
+- Name accepted criteria, residual risks, owners, and documentation feedback or no-update rationale.
+- Do not accept without verification evidence unless explicitly blocked and risk-accepted.
+
+**Conditional acceptance rules**
+
+- When residual risks affect security, privacy, permissions, data, release, or compliance, require owner and follow-up issue.
+- When business/user confirmation is missing, mark acceptance BLOCKED instead of inferred.
+
+**Must-answer questions**
+
+- Is the verified work accepted, rejected, or conditionally accepted?
+- Which evidence and issues support the decision?
+- Who owns residual risks and documentation feedback?
+
+**Quality checks**
+
+- Links verify report, demo evidence, accepted criteria, and residual risks.
+- Records documentation feedback or no-update rationale for confirmed learnings.
+
+**Anti-pattern scan**
+
+- Accepting without verification evidence.
+- Letting residual risks remain ownerless.
+
+### Output Acceptance Checklist
+
+Before claiming completion, internally check these items and surface any failure as NEEDS_REPAIR, NEEDS_CLARIFICATION, or BLOCKED. Missing workflow context lowers confidence; it does not block direct mode unless it is also a direct hard input.
+
+- Every required output is present, explicitly N/A, or blocked with owner, impact, and next action.
+- Every must-answer question is answered from evidence, accepted assumption, or explicit unknown.
+- Hard acceptance rules pass; conditional rules are checked when their trigger is touched.
+- Quality checks have evidence, not only narrative confidence.
+- Anti-pattern scan is clean, or each remaining risk is named with a concrete follow-up.
+- The answer stays inside this skill's responsibility and does not route, approve, staff, gate, or sequence peer skills.
+
+### Quality Scoring
+
+Before final handoff, score the work toward a target of 100. Do not inflate the score to hide missing evidence; if the score cannot reach 100, state the gap and why it remains.
+
+- Responsibility fit: 20 points.
+- Input coverage and blocker clarity: 20 points.
+- Required output completeness: 20 points.
+- Evidence trust and test correctness: 15 points.
+- Downstream actionability: 15 points.
+- Simplicity, locality, and token discipline: 10 points.
+
+Report the score and confidence when producing a durable artifact, making a recommendation, claiming completion, or ending below 100. For trivial command-style outputs, keep the response lightweight but still do the internal check.
+
+### Completion Report
+
+For non-trivial work, include this compact completion signal in the final response or artifact handoff:
+
+- Quality score: 0-100, with confidence high/medium/low.
+- Evidence: commands, files, artifacts, source references, or explicit human decisions that support the claim.
+- Gaps: missing inputs, weak tests, unresolved decisions, or workflow-only context that reduced confidence.
+- Next action: none, or the smallest owner/action needed to reach 100.
+
+### Fast Failure Signals
+
+Stop early and report the cause instead of spending more tokens when any of these is true:
+
+- A direct hard input is missing, stale, contradictory, or not discoverable from local context.
+- The required output would require owning another skill's responsibility or a workflow gate.
+- Evidence is untrusted: skipped tests, mock-only critical path, placeholder output, stale artifacts, or unrelated green checks.
+- The user goal, source evidence, and current artifact contradict each other in a way that changes scope or acceptance.
+
+### Repair Loop
+
+- Inspect: compare the current output against responsibility, direct hard inputs, required outputs, rubric, and evidence.
+- Act: repair the smallest failing dimension first; do not add workflow ceremony to compensate for weak skill output.
+- Verify: rerun or recheck the evidence that supports the repaired claim.
+- Iterate toward 100, but cap local repair at two focused loops. If quality still falls short, return NEEDS_REPAIR, NEEDS_CLARIFICATION, or BLOCKED with owner, impact, and next action instead of burning tokens indefinitely.
+
+### Test And Evidence Integrity
+
+- Treat passing tests as evidence, not proof. Verify that tests assert user-visible or contract-visible behavior, include meaningful failure modes, and do not only exercise mocks or implementation details.
+- When test correctness cannot be trusted, lower confidence and name the missing integration, smoke, manual, negative, boundary, or regression evidence.
+- Never claim PASS, DONE, READY, or acceptance from placeholder output, skipped checks, stale artifacts, or unrelated green tests.
+
+## Policy Contract
+
+This compact policy is the default single-skill contract. It keeps direct skill runs lightweight; full harness resources are loaded only by a process-level flow, strict profile, or explicit local instruction.
+
+When a `harness/` directory is installed beside this file:
+
+- Read `harness/POLICY.md` as the default local policy.
+- Load `harness/THIS_SKILL.md`, `harness/workflow/skill-io-contract.yaml`, or `harness/constraints/*` only when a process-level flow, strict profile, or local instruction explicitly requires full contract enforcement.
+
+Execution discipline:
+
+- Follow the active repository `AGENTS.md` and any nearer project instructions first.
+- Load the smallest context needed to make a correct decision; prefer local source, existing artifacts, and focused reads over broad contract loading.
+- Produce verifiable outputs: do not claim PASS, DONE, READY, or completion without linked evidence from commands, artifacts, issue state, scenarios, or accepted human decisions.
+- Stay inside this skill's responsibility; do not redefine upstream artifacts or approve downstream work on another skill's behalf.
+- Do not route, sequence, or invoke peer skills from a single-skill run unless the user explicitly asked for a workflow.
+- Treat required inputs as mode-specific: direct single-skill targets may block when missing, while workflow-only gates, signoffs, peer-skill artifacts, validation packets, and anchors are optional context unless a process-level flow, strict profile, or explicit local instruction declares them required.
+- If an actually required input is missing, stale, contradictory, or outside this skill's remit, report BLOCKED or NEEDS_CLARIFICATION with owner, impact, and next action instead of guessing.
+- Path privacy: do not write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs; use repo-relative, `.zsk/...`, `$HOME/...`, or `<workspace>/...` references instead.
+- Context recording: durable terminology, naming, decomposition, and load-bearing clarification decisions must update the nearest Context Record target, or the handoff must record `Context update: N/A` with rationale.
+- Record durable project/module language in `.zsk/modules/{module}/CONTEXT.md` or `.zsk/CONTEXT.md` before relying on it downstream.
+- Learning authority: learning proposals must target the canonical ZSK source repo `.zsk/learning/proposals/`; consuming projects keep experience in archives, docs feedback, or issues and must not create `.zsk/learning/`.

package/zsk-acceptance/harness/POLICY.md

@@ -0,0 +1,22 @@
+# ZSK Skill Policy Contract
+
+This compact policy is the default single-skill contract. It keeps direct skill runs lightweight; full harness resources are loaded only by a process-level flow, strict profile, or explicit local instruction.
+
+When a `harness/` directory is installed beside this file:
+
+- Read `harness/POLICY.md` as the default local policy.
+- Load `harness/THIS_SKILL.md`, `harness/workflow/skill-io-contract.yaml`, or `harness/constraints/*` only when a process-level flow, strict profile, or local instruction explicitly requires full contract enforcement.
+
+Execution discipline:
+
+- Follow the active repository `AGENTS.md` and any nearer project instructions first.
+- Load the smallest context needed to make a correct decision; prefer local source, existing artifacts, and focused reads over broad contract loading.
+- Produce verifiable outputs: do not claim PASS, DONE, READY, or completion without linked evidence from commands, artifacts, issue state, scenarios, or accepted human decisions.
+- Stay inside this skill's responsibility; do not redefine upstream artifacts or approve downstream work on another skill's behalf.
+- Do not route, sequence, or invoke peer skills from a single-skill run unless the user explicitly asked for a workflow.
+- Treat required inputs as mode-specific: direct single-skill targets may block when missing, while workflow-only gates, signoffs, peer-skill artifacts, validation packets, and anchors are optional context unless a process-level flow, strict profile, or explicit local instruction declares them required.
+- If an actually required input is missing, stale, contradictory, or outside this skill's remit, report BLOCKED or NEEDS_CLARIFICATION with owner, impact, and next action instead of guessing.
+- Path privacy: do not write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs; use repo-relative, `.zsk/...`, `$HOME/...`, or `<workspace>/...` references instead.
+- Context recording: durable terminology, naming, decomposition, and load-bearing clarification decisions must update the nearest Context Record target, or the handoff must record `Context update: N/A` with rationale.
+- Record durable project/module language in `.zsk/modules/{module}/CONTEXT.md` or `.zsk/CONTEXT.md` before relying on it downstream.
+- Learning authority: learning proposals must target the canonical ZSK source repo `.zsk/learning/proposals/`; consuming projects keep experience in archives, docs feedback, or issues and must not create `.zsk/learning/`.

package/zsk-acceptance/harness/README.md

@@ -0,0 +1,16 @@
+# 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. This generated harness is an install artifact, not the source of truth.
+
+Roles:
+
+- Root `harness/` in the ZSK repository is the canonical source for constraints, workflow state, evidence, issue taxonomy, and promotion rules.
+- `skills/<skill>/harness/POLICY.md` is the default standalone policy: AGENTS.md precedence, minimal context, verifiable output, and single-skill boundaries.
+- `skills/<skill>/harness/THIS_SKILL.md` is the full skill-specific contract for workflow or strict-profile runs: 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 explicit full-contract runs 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`.
+
+Read `POLICY.md` for a direct skill run. Read `THIS_SKILL.md` and the constraint/workflow files it names only when full contract enforcement is explicitly required.