@captain_z/zsk-skills 1.8.6 → 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` 可以把它作为阶段未收口的证据。
 
 ## 领域总览
 
@@ -135,78 +140,97 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 ## Skill 清单（core skills）
 
 > 内容由 `tools/catalog.ts` 从 `packages/skills/*/SKILL.md` frontmatter 生成。重生成：`pnpm catalog`。
+> 默认 profile bundles 只安装 entry 和保留的一等 stage；capability / gate / mode 由 `zskplan` / `zsk` 内部调度或通过 custom/legacy 明确安装。Legacy aliases 仍保留 24 个 skill 以兼容旧安装。
+
+### Entry Skills (2)
 
-### `<slug>/` — Core · harness-first 默认工作流入口 (24)
+用户默认只需要理解的入口。
 
-- **`zskplan`**
+- **`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`**
+- **`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.
 
-- **`dispatch`**
-  At task intake, asks OMX to assign subagents to the right zsk skill from request, state, evidence, and blockers.
+### Stage Skills (11)
 
-- **`flow`**
-  Starts or resumes delivery by reading state, resources, and blockers, then selecting the next legal stage.
+有独立产物边界、质量门禁和下游消费关系的一等阶段。
 
-- **`prepare`**
+- **`prepare`** · type: capability · keep-stage
   After project init, collects resource origins, snapshots evidence, and updates config/manifests before proposal/spec.
 
-- **`preproposal`**
+- **`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`**
+- **`proposal`** · type: capability · keep-stage
   Before spec, frames the problem, scope, non-goals, success criteria, stakeholders, risks, and resource gaps.
 
-- **`spec`**
+- **`spec`** · type: capability · keep-stage
   After proposal, defines sourced FR/NFR, acceptance criteria, scenarios, edge cases, and open gaps.
 
-- **`design`**
+- **`design`** · type: capability · keep-stage
   After spec freeze, maps behavior to interfaces, data flow, rollout plan, risks, and implementation surfaces.
 
-- **`task`**
+- **`task`** · type: capability · keep-stage
   After design approval, creates executable tasks with dependencies, FR/AC coverage, owners, and evidence hooks.
 
-- **`coding`**
+- **`coding`** · type: capability · keep-stage
   For approved tasks, implements small scoped diffs with tests, evidence, and blocker reporting.
 
-- **`smoke`**
-  After coding, proves changed behavior locally with targeted tests and relevant lint/typecheck/build evidence.
+- **`demo`** · type: capability · keep-stage
+  Before formal testing, runs planned demos and captures evidence without making acceptance claims.
 
-- **`review`**
-  After smoke or explicit path targeting, reviews implementation or local targets against scope, contracts, evidence, security, maintainability, and ZSK boundaries.
+- **`verify`** · type: capability · keep-stage
+  Independently verifies fixes or acceptance criteria against a stated claim, target version, and linked evidence.
 
-- **`commit`**
-  After smoke and review pass, prepares a scoped commit with intent, evidence, and clean staging.
+- **`acceptance`** · type: capability · keep-stage
+  After independent verify passes, records accept/reject decision, linked evidence, and residual-risk owner.
 
-- **`demo`**
-  Before formal testing, runs planned demos and captures evidence without making acceptance claims.
+- **`archive`** · type: capability · keep-stage
+  After acceptance, closes the iteration by preserving artifacts, decisions, issues, and learning proposals.
 
-- **`defect`**
-  After formal QA reports findings, normalizes defects with repro, evidence, FR/AC links, and fix routing.
+### Capabilities (6)
 
-- **`ready`**
-  Before independent verification, prepares a handoff with issue mappings, evidence, version, and regression notes.
+可被多个阶段复用的内部能力；默认由入口或阶段调度。
 
-- **`verify`**
-  Independently verifies fixes or acceptance criteria against a stated claim, target version, and linked evidence.
+- **`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.
 
-- **`acceptance`**
-  After independent verify passes, records accept/reject decision, linked evidence, and residual-risk owner.
+- **`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.
 
-- **`deploy`**
-  After review, deploys to non-production or demo targets with version, smoke evidence, and rollback owner.
+- **`defect`** · type: capability · downshift-to-capability
+  After formal QA reports findings, normalizes defects with repro, evidence, FR/AC links, and fix routing.
 
-- **`archive`**
-  After acceptance, closes the iteration by preserving artifacts, decisions, issues, and learning proposals.
+- **`deploy`** · type: capability · downshift-to-capability
+  After review, deploys to non-production or demo targets with version, smoke evidence, and rollback owner.
 
-- **`learn`**
+- **`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`**
+- **`issue`** · type: utility · keep-capability
   Tracks defects, blockers, questions, and risks with taxonomy, severity, owner, reproduction, and evidence.
 
-- **`fix`**
+### Gates (3)
+
+阶段内部的质量检查点或发布检查点。
+
+- **`smoke`** · type: capability · downshift-to-gate
+  After coding, proves changed behavior locally with targeted tests and relevant lint/typecheck/build evidence.
+
+- **`commit`** · type: capability · downshift-to-gate
+  After smoke and review pass, prepares a scoped commit with intent, evidence, and clean staging.
+
+- **`ready`** · type: capability · downshift-to-gate
+  Before independent verification, prepares a handoff with issue mappings, evidence, version, and regression notes.
+
+### Modes (2)
+
+入口或阶段内部的执行模式。
+
+- **`flow`** · type: workflow · downshift-to-mode
+  Starts or resumes delivery by reading state, resources, and blockers, then selecting the next legal stage.
+
+- **`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,35 +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.
-- 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.
-- Context recording: durable terminology, naming, decomposition, and load-bearing clarification decisions must update the nearest `CONTEXT.md`, 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: reusable ZSK core learning must target the canonical ZSK source repo `.zsk/learning/proposals/`; project-local learning may stay in the current project.
-
-When a `harness/` directory is installed beside this file, treat it as the local contract source:
-
-- Read `harness/THIS_SKILL.md` before executing this skill.
-- Read `harness/workflow/skill-io-contract.yaml` for this skill's required inputs, outputs, tools, and capabilities.
-- Read `harness/workflow/skill-quality-standards.yaml` for this skill's document mode, must-answer questions, quality checkpoints, and anti-patterns.
-- Read `harness/workflow/state-machine.yaml` and `harness/constraints/stage-gates.md` before moving between stages.
-- Read `harness/constraints/skill-role-contract.md` before planning or reviewing expert work.
-- Read `harness/constraints/filesystem-boundaries.md` before creating any project artifact.
-- Record durable project/module language in `.zsk/modules/{module}/CONTEXT.md` or `.zsk/docs/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.
+## 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/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
 
@@ -8,6 +8,15 @@ This file is generated for the installed skill. Read it before executing this sk
 - Stage/type: `acceptance`
 - Purpose: After independent verify passes, records accept/reject decision, linked evidence, and residual-risk owner.
 
+## Skill Classification
+
+- Target primary: `stage`
+- Disposition: `keep-stage`
+- Stage eligible: `true`
+- Facets: `acceptance`, `quality-assessment`
+- Rationale: Records final accept/reject decision, linked evidence, and residual risks.
+- Migration: Keep as governance stage for standard/enterprise workflows; allow lite profiles to fold it into verify.
+
 ## Required Inputs
 
 - `verify-report`
@@ -53,6 +62,7 @@ This file is generated for the installed skill. Read it before executing this sk
 - Treat missing mandatory artifacts, mandatory evidence, required owners, required gates, or downstream-consumable outputs as FAIL or BLOCKED.
 - Write unsupplied numeric thresholds, quality bars, SLOs, coverage targets, and business targets as `未指定`; suggestions must be labeled separately from current policy.
 - Avoid provider lock-in: do not assume Jira, Confluence, Figma, GitHub, GitLab, Linear, Notion, browser tooling, or any platform unless configured sources or evidence identify it.
+- Path privacy is a hard portability requirement: reusable project docs must use repo-relative or `.zsk/...` paths and must not contain personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...`.
 - For each required output or finding, name owner, dependency, acceptance condition, verification evidence, and next action.
 
 ## Industry Best-Practice Anchors
@@ -105,8 +115,12 @@ This file is generated for the installed skill. Read it before executing this sk
 - Every stage output must include a concise `Output Quality Check` near the top with fields in order: status, owner, source_basis, blocking_items, next_action, and optional waiver/updated_at.
 - When an existing stage artifact is present, the active skill must update its own Output Quality Check before downstream handoff: derive the check from that skill's responsibility, required inputs, required outputs, must-answer questions, quality checkpoints, current artifact, upstream sources, and downstream consumer; classify sourced, accepted, assumed, conflicting, missing, and N/A claims, then repair or block through the owning stage.
 - Keep Clarification Prelude skill-local: ask, repair, or block only on load-bearing questions the active skill owns; route upstream or downstream findings to the owning stage instead of absorbing another skill's responsibility.
+- Apply `harness/contracts/requirements-grilling.yaml` for proposal-bound clarification: high-impact ambiguity blocks and asks one question, medium ambiguity may proceed with accepted recommendation, and low-impact ambiguity is recorded as an assumption.
+- Before asking a clarification question, prove question quality: source summary, unresolved decision, impact tier, downstream consumer, and why sources cannot answer it.
+- Apply `harness/contracts/readiness-packs.yaml` when producing or consuming upstream source handoffs: stable source lanes and pack types stay provider-agnostic, provider metadata stays under providerRefs, and local evidence stays under sourceRefs.
 - Every Output Quality Check must align terminology against CONTEXT.md/CONTEXT-MAP.md when present, SYSTEM-SPEC.md, configured raw sources, current artifact identifiers, and code/component/API names when implementation-facing work is touched.
-- Record durable terminology, naming, decomposition, and load-bearing clarification decisions in the nearest CONTEXT.md, or write `Context update: N/A` with rationale.
+- Record durable terminology, naming, decomposition, and load-bearing clarification decisions in the nearest Context Record target (`.zsk/modules/{module}/CONTEXT.md`, `.zsk/CONTEXT.md`, or source repo `CONTEXT.md`), or write `Context update: N/A` with rationale.
+- Keep proposal, spec, design, tasks, Context Records, handoffs, archives, issues, and evidence summaries portable: use repo-relative or `.zsk/...` paths, and do not write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs.
 - Preserve upstream/downstream stage ownership; do not silently rewrite another skill's artifact.
 - 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.
@@ -120,7 +134,8 @@ This file is generated for the installed skill. Read it before executing this sk
 - When behavior is testable, define or consume a traceable test basis before claiming implementation, smoke, review, verify, or acceptance success.
 - When external facts, SDKs, APIs, regulations, market context, or dependency behavior are freshness-sensitive, retrieve current authoritative references or record why local sources are sufficient.
 - When an artifact becomes too large for one reviewable file, split it into `{stage}/index.md` plus linked child Markdown files while preserving the full stage contract.
-- When clarification, grilling, architecture review, artifact repair, or task decomposition introduces a term or naming decision future stages must reuse, update module-local or project-level CONTEXT.md before handoff.
+- When clarification, grilling, architecture review, artifact repair, or task decomposition introduces a term or naming decision future stages must reuse, update module-local or project-level Context Record before handoff.
+- When absolute local paths appear in raw source metadata, copy only portable aliases into downstream design/spec/task docs unless the absolute path is explicitly required as raw acquisition provenance.
 - 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.
 
@@ -197,6 +212,7 @@ This file is generated for the installed skill. Read it before executing this sk
 - Running a generic grill or cross-stage rewrite instead of the active skill's own Output Quality Check and Clarification Prelude.
 - Letting terminology, naming, or decomposition decisions live only in chat instead of CONTEXT.md.
 - Running stage-specific questioning without checking whether the artifact uses the same terms as upstream sources, downstream consumers, and implementation surfaces.
+- Asking a clarification question that does not name the affected output, recommended answer, accepted tradeoff, and recording destination.
 - Letting a delayed subagent packet block indefinitely instead of marking it stale and falling back or re-emitting.
 - Claiming tests prove behavior when they have no traceable basis, no meaningful assertion, or only prove implementation details.
 - Accepting without verification evidence.

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

@@ -3,10 +3,10 @@
 Default project paths:
 
 - `.zsk/`: the only default ZSK-managed workspace root.
-- `.zsk/docs/`: project-level docs such as `SYSTEM-SPEC.md` and `PROJECT-CONFIG.md`.
+- `.zsk/CONTEXT.md`: canonical project-wide Context Record for cross-module terminology, naming decisions, decomposition rationale, and accepted clarifications.
+- `.zsk/docs/`: project-level docs such as `SYSTEM-SPEC.md` and `PROJECT-CONFIG.md`; `.zsk/docs/CONTEXT.md` is deprecated compatibility output only, not a canonical write target.
 - `.zsk/modules/{module}/`: module config and stage artifacts.
 - `.zsk/modules/{module}/CONTEXT.md`: module-local domain language, naming decisions, decomposition rationale, and accepted clarifications that later stages must reuse.
-- `.zsk/docs/CONTEXT.md`: project-wide domain language and cross-module terms when a term is not owned by one module.
 - `.zsk/raws/`: raw external source snapshots, manifests, imported test cases, market/product research sources, and design/API assets.
 - `.zsk/raws/prepare/**`: reusable source lanes. `preproposal` may add generated or candidate intake clarity, product, roadmap, UX, and design-source readiness resources here only when they are labeled with provenance, review checkpoint status, assumptions, and blockers.
 - `.zsk/evidence/preproposal/{run}/`: checkpoint review evidence for product direction, roadmap/decomposition, UX/design-readiness, and final readiness before formal proposal.
@@ -14,7 +14,7 @@ Default project paths:
 - `.zsk/modules/{module}/_evidence/`: module-private reusable runtime or research evidence, created on demand.
 - `.zsk/modules/{module}/_playwright/`: module-specific Playwright specs, test plans, auth state, execution records, reports, and results, created on demand.
 - `.zsk/issues/`, `.zsk/evidence/`, `.zsk/playwright/`: shared/global artifacts only, created on demand when the asset is intentionally cross-module.
-- `.zsk/learning/proposals/`: reusable improvement proposals and learning records, created lazily only when learn/archive writes an actual proposal.
+- `.zsk/learning/proposals/`: ZSK core learning proposal path. This path belongs in the canonical ZSK source checkout, not in consuming business/product projects.
 - `.zsk/plans/`: ZSK plan artifacts, created lazily only when `zskplan` or `zsk` freezes an executable route.
 - `skills/{slug}/`: zsk source skill directories.
 - `harness/`: zsk source governance contracts.
@@ -29,22 +29,33 @@ stage repair, or task decomposition must be recorded in the nearest
 `CONTEXT.md`.
 
 - Module-local terms and decisions go to `.zsk/modules/{module}/CONTEXT.md`.
-- Cross-module or project-wide terms go to `.zsk/docs/CONTEXT.md`.
+- Cross-module or project-wide terms go to `.zsk/CONTEXT.md`.
+- `.zsk/docs/CONTEXT.md` may exist only as a deprecated mirror or migration compatibility path; do not write it as the canonical Context Record.
 - ZSK core terms go to the source repo `CONTEXT.md`.
 - If no update is needed, the stage handoff records a no-update rationale.
 - Do not use `CONTEXT.md` for transient notes, raw evidence, task execution
   logs, or unresolved speculation; record those in the owning artifact, issue,
   evidence directory, or learning proposal.
 
+## Path Privacy And Portability
+
+Project-facing ZSK artifacts must stay portable across machines and reviewers.
+
+- Use workspace-relative or repo-relative paths such as `.zsk/modules/{module}/design.md`, `src/components/...`, or configured `sourceRefs` in stage artifacts, Context Records, handoffs, archives, issues, and evidence summaries.
+- Do not write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs, especially proposal, spec, design, tasks, Context Records, and handoffs.
+- If an absolute local path is unavoidable for raw acquisition provenance, keep it inside raw/evidence metadata and also provide a portable alias such as `<workspace>/...`, `$HOME/...`, `.zsk/...`, or a repo-relative path.
+- Before finalizing or handing off a design/spec/task document, replace local machine paths with portable references and keep user names out of copied path strings unless the user explicitly requires audit provenance.
+
 ## Learning Output Authority
 
 Learning artifacts must be written according to what they are meant to change:
 
-- Project-local learning that only affects the current business/product project may use the current project's `.zsk/learning/proposals/`, created lazily.
-- Reusable ZSK core learning that would change ZSK skills, harness contracts, templates, packs, CLI behavior, defaults, or installer behavior must be written to the canonical ZSK source checkout: `<zsk-core>/.zsk/learning/proposals/`.
+- Project-specific delivery experience stays in the current project as module archives, `.zsk/docs/SYSTEM-SPEC.md` feedback, module `_issues`, or shared/global/public issue buckets.
+- Learning proposals always belong to the canonical ZSK source checkout: `<zsk-core>/.zsk/learning/proposals/`.
+- Consuming business/product projects must not create `.zsk/learning/` or `.zsk/learning/proposals/` for learn/archive output.
 - Resolve `<zsk-core>` from explicit configuration/environment first: `ZSK_LEARNING_REPO`, then `ZSK_CORE_REPO`. If neither is set, the current repository qualifies only when it contains `skills/`, `harness/`, and `packages/cli/`.
-- If no canonical ZSK source checkout is available or writable, do not create a substitute core-learning proposal in the consuming project. Record `BLOCKED` with the missing root, intended proposal title, source evidence, and next action.
-- `zsk init` must not create `.zsk/learning/`; learning directories remain lazy outputs created by `learn` or `archive` only when a concrete proposal is written.
+- If no canonical ZSK source checkout is available or writable, do not create a substitute learning proposal in the consuming project. Record `BLOCKED` with the missing root, intended proposal title, source evidence, and next action.
+- `zsk init` must not create `.zsk/learning/`; in non-ZSK projects the learn directory remains absent.
 
 ## Scope Routing Rule
 

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

@@ -121,7 +121,7 @@ Every actionable issue should record:
 - suspected root cause and confidence;
 - affected spec/design/task/implementation/test artifact;
 - whether the fix needs Documentation Feedback in module docs;
-- whether a durable learning proposal is needed under `.zsk/learning/proposals`;
+- whether a durable ZSK learning proposal is needed under `<zsk-core>/.zsk/learning/proposals/`, or whether the finding should stay as project archive/docs feedback or an issue;
 - regression guard: test, scenario, lint rule, checklist, or explicit waiver.
 
 ## Issue-Driven Fix Route