@captain_z/zsk-skills 1.8.9 → 1.8.10

package/README.md

@@ -2,20 +2,20 @@
 
 ZNorth Standard Kit 的可安装 skill 内容包。安装面现在只保留从根级 `skills/` 生成的 **core harness-first skills**；旧 `.best-practices/` 不再批量生成独立 installable skills，而是作为参考源按 skill 携带相关子集。
 
-包内共有 **24 颗 installable skills**，全部来自根级 `skills/`。
+包内共有 **26 颗 installable skills**，全部来自根级 `skills/`。其中 legacy full-core profile 继续保留 24 颗生命周期 skill；`check` / `health` 是可选诊断能力，适合通过 custom、单颗安装或 GitHub skill 管理器引入。
 
 ## 合规审查（ARCHITECTURE §4.4 硬指标）
 
 | 检查项                                                                                   | 结果    | 说明                                                  |
 | ---------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
-| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 24/24 | core 由 root `skills/` 生成 |
-| `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 |
+| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 26/26 | core 由 root `skills/` 生成 |
+| `name` 使用公共命名，目录同名且只含小写/数字/连字符                         | ✓ 26/26 | 主入口为 `zskplan` / `zsk`；其它 skill 使用 `zsk-<slug>` 避免裸名冲突；CLI 选择层继续兼容 `zsk:<slug>` |
+| `description` 简洁表达职责和使用时机                                                       | ✓ 26/26 | 面向索引阅读；triggers 留给机器使用 |
+| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 26/26 | stage/utility · core |
+| `triggers` 数组非空                                                                      | ✓ 26/26 | 至少含裸 slug |
 | 无硬编码项目名 / 技术栈（统一 `{{config.*}}` 占位符）                                    | ✓       | harness-neutral                                       |
 | `related:` 相对路径合法                                                                  | ✓       | core 不依赖参考层生成物                               |
-| 单文件 ≤ 300 行                                                                          | ✓ 24/24 | core 由 `lint:harness` 强制                           |
+| 单文件 ≤ 300 行                                                                          | ✓ 26/26 | core 由 `lint:harness` 强制                           |
 
 当前 `max-lines` 已由 `tools/lint-frontmatter.ts` 作为 error 强制；新增或修改 skill 不应超过 300 行。
 
@@ -87,23 +87,25 @@ Direct review 只需要明确 review target（代码 diff、本地路径、stage
 | 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` | 非交互安装 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` | 从仓库安装 `zsk-<slug>` 公共命名空间；不要加 `@` |
+| Claude plugin 分层安装 | `/plugin marketplace add codeshareman/zsk` 后 `/plugin install zsk-entry@zsk` | 在 Claude 内按 profile 安装 ZSK skills |
+| Claude plugin 全量兼容 | `/plugin install zsk@zsk` | 安装 24 颗 core skills，保留给旧工作流或高级用法 |
+| GitHub skills 管理器安装 | `npx skills add codeshareman/zsk` | 从仓库安装公共命名的 ZSK skills 或单颗 skill；不要加 `@` |
+| Skill 质量 dry-run | `npx @captain_z/zsk skills dry-run --min-score=90` | 不调用 LLM、不写项目；模拟每颗 skill 的输入、输出、质量检查、stop condition 和专属场景断言；总分、`qualityItems[]` 和 `scenarioChecks[]` 单项都必须达到阈值 |
 | 准备项目资源 | `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` |
+| 只想让 ZSK 自己规划和执行 | "用 `zskplan` 规划" / "用 `zsk` 继续" | 计划写入 `.zsk/plans/`，执行产物写入 `.zsk` |
 | 不确定该用哪个阶段 skill | "用 `zsk:dispatch` 调度" | 让 OMX 围绕 ZSK skills 分配 subagents |
 | 恢复一个项目的下一步 | "用 `zsk:flow` 继续" | 读取配置、阶段文档和 blocker，选择合法下一阶段 |
 | 明确进入某阶段 | "用 `zsk:spec` 写模块规格" | 只载入对应 stage contract |
 
-**典型消费路径**（production，安装后）：
+**典型消费路径**（production，安装后）。`<public-name>` 表示 `zskplan` / `zsk` 两个裸入口，或其它 skill 的 `zsk-<slug>`：
 
-- `~/.claude/skills/zsk-<slug>/SKILL.md` — Claude Code / flat target
-- `~/.codex/skills/zsk-<slug>/SKILL.md` — Codex / flat target
+- `~/.claude/skills/<public-name>/SKILL.md` — Claude Code / flat target
+- `~/.codex/skills/<public-name>/SKILL.md` — Codex / flat target
 - `./.claude-plugin/skills/<slug>/SKILL.md` + `commands/<slug>.md` — Claude plugin local target
-- `skills/.curated/zsk-<slug>/SKILL.md` — `npx skills` / Claude plugin marketplace repository target
-- `@captain_z/zsk-skills/zsk-<slug>/SKILL.md` — 通过 npm 读
+- `skills/.curated/<public-name>/SKILL.md` — `npx skills` / Claude plugin marketplace repository target
+- `@captain_z/zsk-skills/<public-name>/SKILL.md` — 通过 npm 读
 
-仓库根还发布 `.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`。
+仓库根还发布 `.claude-plugin/plugin.json` 和 `.claude-plugin/marketplace.json`，用于 Claude Code `/plugin marketplace add codeshareman/zsk` 后按 profile 安装 `zsk-entry@zsk`、`zsk-lite@zsk`、`zsk-sdlc@zsk`、`zsk-frontend@zsk` 或 `zsk-enterprise@zsk`；`zsk@zsk` 保留为全量兼容入口。根级 `skills/.curated/` 同时兼容 `npx skills add codeshareman/zsk`。
 
 ## 和项目知识工作区的关系
 
@@ -119,8 +121,8 @@ Skills 负责更需要判断的部分：理解已同步的 SRS、PRD、API 契
 
 | 领域              | skill 数 | 职责                                       |
 | ----------------- | -------- | ------------------------------------------ |
-| `skills/`         | 24       | harness-first 默认工作流入口               |
-| **总计**          | **24**   |                                            |
+| `skills/`         | 26       | harness-first 默认工作流入口与可选诊断能力 |
+| **总计**          | **26**   |                                            |
 
 ## 安装套件（bundles.yaml）
 
@@ -136,21 +138,21 @@ Skills 负责更需要判断的部分：理解已同步的 SRS、PRD、API 契
 | `frontend-with-design-handoff` | 24     | 旧入口兼容；推荐改用 `zsk-frontend` |
 | `custom`                       | 交互   | 通过 `zsk add` 任意多选                       |
 
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 24 skills -->
+<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 26 skills -->
 
 ## Skill 清单（core skills）
 
-> 内容由 `tools/catalog.ts` 从 `packages/skills/zsk-*/SKILL.md` frontmatter 生成。重生成：`pnpm catalog`。
+> 内容由 `tools/catalog.ts` 从 `packages/skills/<public-name>/SKILL.md` frontmatter 生成；`zsk` / `zskplan` 为裸入口，其它 skill 使用 `zsk-<slug>`。重生成：`pnpm catalog`。
 > 默认 profile bundles 只安装 entry 和保留的一等 stage；capability / gate / mode 由 `zskplan` / `zsk` 内部调度或通过 custom/legacy 明确安装。Legacy aliases 仍保留 24 个 skill 以兼容旧安装。
 
 ### Entry Skills (2)
 
 用户默认只需要理解的入口。
 
-- **`zsk-zskplan`** · type: workflow · 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-zsk`** · type: workflow · 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)
@@ -190,7 +192,7 @@ Skills 负责更需要判断的部分：理解已同步的 SRS、PRD、API 契
 - **`zsk-archive`** · type: capability · keep-stage
   After acceptance, closes the iteration by preserving artifacts, decisions, issues, and learning proposals.
 
-### Capabilities (6)
+### Capabilities (7)
 
 可被多个阶段复用的内部能力；默认由入口或阶段调度。
 
@@ -212,7 +214,10 @@ Skills 负责更需要判断的部分：理解已同步的 SRS、PRD、API 契
 - **`zsk-issue`** · type: utility · keep-capability
   Tracks defects, blockers, questions, and risks with taxonomy, severity, owner, reproduction, and evidence.
 
-### Gates (3)
+- **`zsk-health`** · type: capability · keep-capability
+  Use when auditing ZSK agent, skill, workflow, harness, and installation health to find coupling, token waste, trigger overlap, stale generated surfaces, and output-quality gaps without owning product delivery.
+
+### Gates (4)
 
 阶段内部的质量检查点或发布检查点。
 
@@ -225,6 +230,9 @@ Skills 负责更需要判断的部分：理解已同步的 SRS、PRD、API 契
 - **`zsk-ready`** · type: capability · downshift-to-gate
   Before independent verification, prepares a handoff with issue mappings, evidence, version, and regression notes.
 
+- **`zsk-check`** · type: capability · downshift-to-gate
+  Before commit, push, release, or handoff, runs a lightweight readiness preflight over local changes and reports evidence, risks, and a clear ready/not-ready verdict without owning workflow gates.
+
 ### Modes (2)
 
 入口或阶段内部的执行模式。

package/package.json

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

package/{zsk-zsk → zsk}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: zsk-zsk
+name: zsk
 description: Use as the ZSK-aware Ralph-style execution loop that follows ZSK
   plans, dispatches expert lanes, verifies, fixes, and writes only .zsk outputs.
 kind: workflow
@@ -23,7 +23,7 @@ useWhen:
   - "Use when the workflow is ready for this responsibility: Use as the
     ZSK-aware Ralph-style execution loop that follows ZSK plans, dispatches
     expert lanes, verifies, fixes, and writes only .zsk outputs."
-  - Use when the user invokes zsk:zsk or asks for zsk workflow outputs after
+  - Use when the user invokes zsk or asks for zsk workflow outputs after
     prerequisites are present.
 doNotUseWhen:
   - Do not use when required inputs, prior-stage evidence, or configured sources
@@ -31,12 +31,12 @@ doNotUseWhen:
   - Do not use to bypass stage gates, perform another skill's responsibility, or
     make unsupported completion claims.
 positiveExamples:
-  - Run zsk:zsk with the required inputs and produce the documented zsk workflow
+  - Run zsk with the required inputs and produce the documented zsk workflow
     artifacts.
   - Continue the workflow at zsk workflow after the prerequisite evidence and
     blockers are resolved.
 negativeExamples:
-  - Use zsk:zsk to skip missing prerequisites or hide unresolved blockers.
+  - Use zsk to skip missing prerequisites or hide unresolved blockers.
   - Run zsk workflow for generic chat, unrelated implementation, or another ZSK
     stage's work.
 ---

package/zsk/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/harness/constraints/evidence-rules.md

@@ -0,0 +1,33 @@
+# Evidence Rules
+
+Every pass/fail claim must link to evidence.
+
+Accepted evidence types:
+
+- document section
+- test output
+- lint/typecheck/build output
+- screenshot
+- Playwright trace
+- UI observation note from Computer Use, Playwright MCP/ARIA/CDP, compatible Browser Use, or documented manual evidence
+- network log
+- console log
+- deploy URL
+- issue record
+- sign-off record
+
+Demo evidence produced by manual execution, Playwright, Computer Use, Playwright MCP/ARIA/CDP, or compatible Browser Use must be normalized into the same report and issue taxonomy.
+
+## Test Evidence Discipline
+
+- TDD is the default for behavior changes: write or update the smallest accurate failing test/scenario before implementation when a testable contract exists.
+- Test cases must match the requirement, function point, scenario, and expected behavior from PRD/SRS, spec/design, task, accepted issue, or user clarification.
+- Do not write tests from guesses, convenient implementation details, brittle selectors, or generic best-practice expectations that are not in the facts.
+- Before using a test as evidence, verify that it fails for the right reason before the fix when practical, and passes for the intended reason after the fix.
+- Every generated or updated test should link to its source requirement, scenario contract, issue, or design/spec row.
+
+## Traceability Discipline
+
+- Important requirements and function points should carry a visible chain: source requirement -> spec/design contract -> task -> test/scenario -> evidence -> issue/acceptance status.
+- If a chain is incomplete, mark the missing link and its impact instead of presenting the output as complete.
+- Review, verify, and acceptance should check traceability before approving the next stage.

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

@@ -0,0 +1,76 @@
+# Filesystem Boundaries
+
+Default project paths:
+
+- `.zsk/`: the only default ZSK-managed workspace root.
+- `.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/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.
+- `.zsk/modules/{module}/_issues/`: module-private managed issue records and indexes, created on demand.
+- `.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/`: 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.
+
+Root `docs/`, `.raws/`, `.issues/`, `.playwright/`, and `plans/` are not default write targets for ZSK skills. Use explicit export, promote, import, or migration commands when project-facing root documentation is needed.
+
+## Context Recording Authority
+
+Every durable terminology, naming, decomposition, or load-bearing clarification
+created during a Clarification Loop, artifact clarity pass, architecture review,
+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/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-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 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
+
+Before any skill writes an artifact, classify its scope:
+
+| Scope | Meaning | Default target |
+| --- | --- | --- |
+| module-final | Formal stage output for one module | `.zsk/modules/{module}/` |
+| module-private | Working, runtime, evidence, issue, or generated artifact for one module | `.zsk/modules/{module}/_{kind}/` |
+| shared | Reused by multiple modules but not public-facing | `.zsk/{kind}/shared/` or the configured shared root |
+| global | Project-wide artifact with no owning module | `.zsk/{kind}/global/` or `.zsk/docs/` for formal docs |
+| public | Intentionally publishable/exportable artifact | `.zsk/{kind}/public/` until explicitly exported |
+
+This rule applies to every underscore module directory, not only `_issues`. For example, module-local issues go to `_issues`, module-local runtime evidence goes to `_evidence`, and module-local Playwright specs/auth/results go to `_playwright`. Use outer `.zsk/issues`, `.zsk/evidence`, or `.zsk/playwright` only after deciding the artifact is shared, global, or public. When scope is ambiguous, prefer module-private and record the reason or blocker before promoting outward.
+
+The skill that produces the final artifact for a module stage writes the formal report to `.zsk/modules/{module}/{stage}.md`. For large `proposal`, `spec`, `design`, or `tasks` artifacts, the skill may upgrade the stage artifact to `.zsk/modules/{module}/{stage}/index.md` and split child Markdown files under the same stage directory. The `index.md` file remains the review entrypoint, must link every child document included in the logical artifact, and must preserve the same stage contract; splitting content does not weaken required gates. Supporting artifacts stay in the appropriate `_issues`, `_evidence`, or `_playwright` directory unless they are deliberately shared/global/public.
+
+`preproposal` is not a module-final stage. Its outputs are intake clarity and proposal-prep raw resources under `.zsk/raws/prepare/**` plus checkpoint evidence under `.zsk/evidence/preproposal/{run}/`. When a target module is specified, use the module id as the default raw topic, for example `.zsk/raws/prepare/ux/{module}/interaction-handoff.md`, and record any narrower page/frame split rationale in the raw artifact. It must not create `.zsk/modules/{module}/proposal.md`, `spec.md`, `design.md`, or `tasks.md`; those remain owned by their formal stage skills.

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

@@ -0,0 +1,150 @@
+# Issue Taxonomy
+
+`zsk:issue` is the cross-stage issue utility. Stage skills call it, but issue paths and fields are defined here.
+
+Issue records are persistent tracking artifacts. Module-specific findings default to the module-private `.zsk/modules/{module}/_issues/` directory. Use the configured issue root from `.zsk/config.yaml` `paths.issues` only for shared/global or intentionally cross-module issues; the default shared root is `.zsk/issues/`. Do not keep actionable findings only in chat, transient task notes, or demo reports.
+
+Issue placement must follow the same scope routing rule as every other underscore artifact:
+
+| Issue scope | Use when | Directory |
+| --- | --- | --- |
+| module | One module owns the finding, fix, and verification | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` |
+| shared | Multiple modules reuse the same issue, fixture, dependency, or evidence chain | `.zsk/issues/shared/{prefix}-0001-slug/` |
+| global | Project/process/release/harness issue has no single owning module | `.zsk/issues/global/{prefix}-0001-slug/` |
+| public | Issue is intentionally publishable or external-facing | `.zsk/issues/public/{prefix}-0001-slug/` |
+
+When an issue starts shared/global/public and later gets assigned to one module, move or link it into that module's `_issues` directory and leave a backlink in the outer issue record. When a module issue becomes cross-module, promote it to the appropriate outer scope and leave a backlink in the original module issue.
+
+Indexes are part of the contract:
+
+- `.zsk/modules/{module}/_issues/index.md` tracks every issue for that module and its status.
+- `.zsk/issues/index.md` tracks each module and total/open/closed issue counts across module-private and shared issues.
+- Creating or updating an issue must refresh both indexes.
+
+## Types
+
+| Type | Concrete Issue Directory | Prefix | Typical Source |
+| --- | --- | --- | --- |
+| Demo Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `DEMO` | Development demo |
+| Smoke Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `SMOKE` | Developer smoke |
+| Review Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `REV` | Code/design review |
+| Defect | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `DEFECT` | Formal QA |
+| Verify Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `VER` | Fix verification |
+| Acceptance Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `ACC` | Business/product acceptance |
+| Clarification Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `CLAR` | Clarification Prelude |
+
+Stage directories such as `.zsk/modules/{module}/_issues/demo/index.md` may exist as stage views or evidence buckets. They are not the authoritative status indexes.
+
+If `paths.issues` is customized, it must still stay under `.zsk/` and is reserved for shared/global or cross-module issue records. Module-private issue paths remain under `.zsk/modules/{module}/_issues/`.
+
+## Required Fields
+
+- `id`
+- `type`
+- `severity`
+- `severity_rationale`
+- `status`
+- `owner`
+- `module`
+- `stage`
+- `environment`
+- `related_artifacts`
+- `steps`
+- `expected`
+- `actual`
+- `evidence`
+- `root_cause`
+- `fix_route`
+- `feedback_targets`
+- `regression_guard`
+- `confirmed_at` or `confirmation_required`
+
+Clarification issues extend the common fields with:
+
+- `owning_stage`
+- `owning_skill`
+- `question`
+- `recommended_answer`
+- `accepted_answer`
+- `recommendation_delta`
+- `impact_if_unconfirmed`
+- `confirmation_required`
+- `clarification_status`
+- `updated_artifacts`
+- `source_basis`
+
+`recommended_answer` stores the recommendation exactly as shown to the user; do
+not rewrite it after the user answers. `accepted_answer` stores the final
+confirmed expression. If the accepted expression differs from the recommendation,
+record `recommendation_delta` so downstream skills do not revert the user's
+decision back to the recommendation.
+
+Clarification status is a strict state machine:
+
+- `pending_question`: one load-bearing question is ready to ask.
+- `pending_expression`: the user answered and the skill must present or refine
+  `待写入确认表达：`.
+- `confirmed`: the user accepted the expression, but it is not yet written into
+  the owning artifacts.
+- `applied`: the expression was written into the `CLAR`, owning stage artifact,
+  and required `CONTEXT.md` target.
+- `closed`: the smallest useful gate validation passed after application.
+
+`confirmed` is not enough to continue downstream. Gate/dispatch may resume only
+after the `CLAR` reaches `applied`, and closure requires linked validation
+evidence.
+
+## Severity
+
+- `P0`: blocks core path, data safety, security, or test handoff.
+- `P1`: core behavior wrong, limited workaround, key AC/API mismatch.
+- `P2`: non-core path, edge state, visual, copy, or test inconvenience.
+- `P3`: improvement, documentation gap, or follow-up suggestion.
+
+## Intake Questions
+
+When evidence is incomplete, ask for the smallest missing set:
+
+1. Reproduction steps or triggering command.
+2. Current behavior / actual result.
+3. Expected behavior.
+4. Environment: branch, version, URL, browser/device, data account, feature flags.
+5. Severity and why it matters.
+6. Evidence links: logs, screenshots, traces, HAR, test output, source references.
+
+Do not ask for information already present in the failure output or artifacts.
+
+## Root Cause And Feedback
+
+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 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
+
+`fix` is the dedicated skill and route name for "persisted issue -> root cause -> minimal change -> regression guard -> verification handoff". It is not a shortcut around `coding`, `smoke`, `review`, `ready`, or `verify`.
+
+Required fix-route ledger fields:
+
+- issue path or id;
+- reproduction/evidence basis;
+- root-cause hypothesis and confidence;
+- changed files or no-code rationale;
+- regression guard or explicit blocker;
+- documentation feedback target or no-update rationale;
+- next verification route and evidence command.
+
+Do not use `fix` for generic unanchored cleanup. If there is no persisted issue or accepted expected/actual clarification, create or update the issue first.
+
+## Closure And Feedback Loop
+
+1. Create or update module-specific issues under `.zsk/modules/{module}/_issues/` as soon as the finding is actionable, using the type and prefix fields to preserve taxonomy.
+2. Fix and verify the issue with linked evidence.
+3. Wait for user/product confirmation when the outcome changes behavior, business flow, or acceptance semantics.
+4. After confirmation, update the relevant spec/design/task docs for anything the original artifacts did not cover or described too weakly.
+5. Close the issue only after the issue record links the verification evidence, confirmation, documentation feedback update or no-update rationale, and regression guard.
+6. Refresh the module index and global issue index after status changes.