@captain_z/zsk-skills 1.8.7 → 1.8.8

package/README.md

@@ -30,7 +30,7 @@ zsk skill 是 LLM **按需自动触发**的资产。用户通常只做两件事
 
 ## Profile 选择
 
-Profile 是流程组合策略，不是新的 skill。Atomic skills 仍然平铺在 `skills/`，profile 只决定默认安装集合、阶段顺序、可选节点和严格度。
+Profile 是流程组合策略，不是新的 skill。Atomic skills 仍然平铺在 `skills/`，profile 只决定默认安装集合、阶段顺序、可选节点和严格度。Workflow 负责编排、约束、签字、角色投入和多角度会诊；单个 skill 只负责自己的职责、非目标、输出质量、证据、风险和置信度。
 
 | profile | skills | 适用场景 |
 | --- | ---: | --- |
@@ -43,20 +43,20 @@ Profile 是流程组合策略，不是新的 skill。Atomic 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,6 +75,10 @@ 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 路由。
+
 ## 常见用法
 
 | 目标 | 推荐说法或命令 | 结果 |
@@ -85,6 +89,7 @@ flowchart TD
 | CI 安装标准 SDLC profile | `npx @captain_z/zsk add zsk-sdlc --target=~/.claude/skills --yes` | 非交互安装 21 颗标准 workflow skills |
 | Claude plugin 安装 | `/plugin marketplace add codeshareman/zsk` 后 `/plugin install zsk@zsk` | 使用 `/zsk:<slug>` 命令面 |
 | GitHub skills 管理器安装 | `npx skills add codeshareman/zsk` | 从仓库根 `skills/` 安装；不要加 `@` |
+| 准备项目资源 | `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，选择合法下一阶段 |
@@ -101,11 +106,11 @@ flowchart TD
 
 ## 和项目知识工作区的关系
 
-`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` 可以把它作为阶段未收口的证据。
 
 ## 领域总览
 
@@ -141,91 +146,91 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 
 用户默认只需要理解的入口。
 
-- **`zskplan`** · keep-entry
+- **`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`** · 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
+- **`prepare`** · type: capability · keep-stage
   After project init, collects resource origins, snapshots evidence, and updates config/manifests before proposal/spec.
 
-- **`preproposal`** · keep-stage
+- **`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
+- **`proposal`** · type: capability · keep-stage
   Before spec, frames the problem, scope, non-goals, success criteria, stakeholders, risks, and resource gaps.
 
-- **`spec`** · keep-stage
+- **`spec`** · type: capability · keep-stage
   After proposal, defines sourced FR/NFR, acceptance criteria, scenarios, edge cases, and open gaps.
 
-- **`design`** · keep-stage
+- **`design`** · type: capability · keep-stage
   After spec freeze, maps behavior to interfaces, data flow, rollout plan, risks, and implementation surfaces.
 
-- **`task`** · keep-stage
+- **`task`** · type: capability · keep-stage
   After design approval, creates executable tasks with dependencies, FR/AC coverage, owners, and evidence hooks.
 
-- **`coding`** · keep-stage
+- **`coding`** · type: capability · keep-stage
   For approved tasks, implements small scoped diffs with tests, evidence, and blocker reporting.
 
-- **`demo`** · keep-stage
+- **`demo`** · type: capability · keep-stage
   Before formal testing, runs planned demos and captures evidence without making acceptance claims.
 
-- **`verify`** · keep-stage
+- **`verify`** · type: capability · keep-stage
   Independently verifies fixes or acceptance criteria against a stated claim, target version, and linked evidence.
 
-- **`acceptance`** · keep-stage
+- **`acceptance`** · type: capability · keep-stage
   After independent verify passes, records accept/reject decision, linked evidence, and residual-risk owner.
 
-- **`archive`** · keep-stage
+- **`archive`** · type: capability · keep-stage
   After acceptance, closes the iteration by preserving artifacts, decisions, issues, and learning proposals.
 
 ### Capabilities (6)
 
 可被多个阶段复用的内部能力；默认由入口或阶段调度。
 
-- **`dispatch`** · downshift-to-capability
+- **`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
+- **`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
+- **`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
+- **`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
+- **`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
+- **`issue`** · type: utility · keep-capability
   Tracks defects, blockers, questions, and risks with taxonomy, severity, owner, reproduction, and evidence.
 
 ### Gates (3)
 
 阶段内部的质量检查点或发布检查点。
 
-- **`smoke`** · downshift-to-gate
+- **`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
+- **`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
+- **`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
+- **`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
+- **`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/acceptance/SKILL.md

@@ -3,6 +3,7 @@ name: 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:
@@ -70,46 +71,176 @@ Use this stage after independent `verify` has passed and the product/business ow
 - Updated spec/design/task documentation feedback or explicit no-update rationale.
 - Archive readiness or rejection route.
 
-## Harness Contract
-
-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, 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.
-- Constraint levels: hard requirements and triggered conditional requirements are blocking; advisory guidance may be skipped only with rationale and no broken hard/conditional gate.
-- Required outputs: every output declared in the skill I/O contract is mandatory unless recorded as evidence-backed N/A or BLOCKED with owner, impact, and next action.
-- Collaboration: ordinary stage skills own their declared outputs and handoff quality; workflow skills own route selection. Do not hardcode the next stage inside a stage skill.
-- Output Quality Check: every stage output must expose status, owner, source basis, blocking item links, and next action near the top of the artifact; route cross-stage gaps to their owning stage instead of running a generic grill.
-- Clarification Prelude: ask exactly one load-bearing question with a separate recommendation only after local sources cannot produce a safe expression; persist confirmed expressions through CLAR, the owning artifact, and required CONTEXT.md updates.
-- Requirements Grilling Readiness: for preproposal/proposal clarification, follow `harness/contracts/requirements-grilling.yaml`; high-impact ambiguity asks one question and may block, medium ambiguity may proceed with accepted recommendation, and low-impact ambiguity is recorded without blocking.
-- Stage Output Readiness: for spec/design output quality, follow `harness/contracts/stage-output-readiness.yaml`; spec protects observable behavior contracts, design protects task-ready implementation decisions, and accepted reusable consensus must persist to Context Records.
-- Clarification quality: before asking, name source basis, unresolved decision, impact tier, downstream consumer, why sources cannot answer, recommended answer, accepted tradeoff, and Context update target or N/A rationale.
-- Readiness Packs: follow `harness/contracts/readiness-packs.yaml` when source lanes, product packs, UX supplements, QA case packs, defect packs, or readiness handoffs are produced or consumed; keep provider metadata under `providerRefs` and local evidence under `sourceRefs`.
-- Dispatch Runtime: follow `harness/contracts/dispatch-runtime.yaml` when planning subagent, OMX, provider-lane, or sequential dispatch; every emitted packet needs durable status, heartbeat/timeout policy, and fallback evidence.
-- Dynamic state awareness: identify the active role/stage, project type, stack, runtime, domain, target users/market, and freshness-sensitive decisions before selecting practices or retrieval sources.
-- Filesystem boundaries: write ZSK-managed outputs only under the configured `.zsk` workspace paths.
-- 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.
-- Repository layout: edit canonical source roots first, regenerate derived surfaces, and keep local runtime state out of Git unless it is intentional evidence.
-- Workspace layout: keep init surfaces shallow; materialize lazy roots such as `.zsk/issues`, `.zsk/evidence`, `.zsk/resources`, `.zsk/plans`, and `.zsk/playwright` only when an owning output exists.
-- Profile strategy: profiles select workflow strategy, strictness, capabilities, gates, evidence, and tools; flat bundles are only the install adapter.
-- Work management: emit provider-agnostic work events to `.zsk/work.jsonl` only after real task/issue/assignment/status changes; keep Multica or future providers behind adapters.
-- 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.
-- Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
-- 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/`.
+## 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**
 
-When a `harness/` directory is installed beside this file, treat it as the local contract source:
+- Links verify report, demo evidence, accepted criteria, and residual risks.
+- Records documentation feedback or no-update rationale for confirmed learnings.
 
-- Read `harness/THIS_SKILL.md` before executing this skill.
-- Read `harness/workflow/skill-io-contract.yaml` for this skill's required inputs, outputs, tools, and capabilities.
-- Read `harness/workflow/skill-quality-standards.yaml` for this skill's document mode, must-answer questions, quality checkpoints, and anti-patterns.
-- Read `harness/workflow/state-machine.yaml` and `harness/constraints/stage-gates.md` before moving between stages.
-- Read `harness/contracts/dispatch-runtime.yaml`, `harness/contracts/profile-strategy.yaml`, `harness/contracts/readiness-packs.yaml`, `harness/contracts/requirements-grilling.yaml`, `harness/contracts/skill-classification.yaml`, `harness/contracts/stage-output-readiness.yaml`, `harness/contracts/work-management.yaml`, `harness/contracts/workspace-layout.yaml`, and `harness/contracts/repository-layout.yaml` before changing dispatch/subagent behavior, install surfaces, source readiness packs, proposal-bound clarification, spec/design readiness, work sync, staffing/talent routing, workspace paths, or repo directory roles.
-- Read `harness/constraints/skill-role-contract.md` before planning or reviewing expert work.
-- Read `harness/constraints/filesystem-boundaries.md` before creating any project artifact.
+**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.
-- Read `harness/constraints/evidence-rules.md` and `harness/workflow/completion-contract.yaml` before claiming READY / PASS / DONE.
-- Read `harness/constraints/issue-taxonomy.md` before creating or updating blockers, risks, defects, or questions.
-- Apply the related best-practice concerns listed in `harness/THIS_SKILL.md`; read bundled `harness/best-practices/` files first when they are listed for the current skill. Search Context7 or the web only when local guidance or local facts are missing, incomplete, stale, too generic, version-sensitive, market-sensitive, or role-incomplete. Record source links, source dates when relevant, and adaptation rationale in the evidence or learning proposal.
+- 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/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/acceptance/harness/README.md

@@ -7,9 +7,10 @@ The local `SKILL.md` is the execution entrypoint. This generated harness is an i
 Roles:
 
 - 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/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 `THIS_SKILL.md` first, then only the constraint/workflow files it names for the current task.
+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.

package/acceptance/harness/THIS_SKILL.md

@@ -1,6 +1,6 @@
 # acceptance · Focused Harness Contract
 
-This file is generated for the installed skill. Read it before executing this skill.
+This full contract is generated for workflow or strict-profile runs. Direct single-skill runs should start from `POLICY.md` and load this file only when full contract enforcement is explicitly required.
 
 ## Responsibility