@captain_z/zsk-skills 1.8.2 → 1.8.3

package/README.md

@@ -2,20 +2,20 @@
 
 ZNorth Standard Kit 的可安装 skill 内容包。安装面现在只保留从根级 `skills/` 生成的 **core harness-first skills**；旧 `.best-practices/` 不再批量生成独立 installable skills，而是作为参考源按 skill 携带相关子集。
 
-包内共有 **22 颗 installable skills**，全部来自根级 `skills/`。
+包内共有 **23 颗 installable skills**，全部来自根级 `skills/`。
 
 ## 合规审查（ARCHITECTURE §4.4 硬指标）
 
 | 检查项                                                                                   | 结果    | 说明                                                  |
 | ---------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
-| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 22/22 | core 由 root `skills/` 生成 |
-| `name` 使用裸 slug，扁平且不含连字符                                                       | ✓ 22/22 | LLM 原生 skill 入口保持简洁；CLI 选择层使用 `zsk:<slug>` |
-| `description` 简洁表达职责和使用时机                                                       | ✓ 22/22 | 面向索引阅读；triggers 留给机器使用 |
-| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 22/22 | stage/utility · core |
-| `triggers` 数组非空                                                                      | ✓ 22/22 | 至少含裸 slug |
+| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 23/23 | core 由 root `skills/` 生成 |
+| `name` 使用裸 slug，扁平且不含连字符                                                       | ✓ 23/23 | LLM 原生 skill 入口保持简洁；CLI 选择层使用 `zsk:<slug>` |
+| `description` 简洁表达职责和使用时机                                                       | ✓ 23/23 | 面向索引阅读；triggers 留给机器使用 |
+| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 23/23 | stage/utility · core |
+| `triggers` 数组非空                                                                      | ✓ 23/23 | 至少含裸 slug |
 | 无硬编码项目名 / 技术栈（统一 `{{config.*}}` 占位符）                                    | ✓       | harness-neutral                                       |
 | `related:` 相对路径合法                                                                  | ✓       | core 不依赖参考层生成物                               |
-| 单文件 ≤ 300 行                                                                          | ✓ 22/22 | core 由 `lint:harness` 强制                           |
+| 单文件 ≤ 300 行                                                                          | ✓ 23/23 | core 由 `lint:harness` 强制                           |
 
 当前 `max-lines` 已由 `tools/lint-frontmatter.ts` 作为 error 强制；新增或修改 skill 不应超过 300 行。
 
@@ -35,11 +35,11 @@ Profile 是流程组合策略，不是新的 skill。Atomic skills 仍然平铺
 | profile | skills | 适用场景 |
 | --- | ---: | --- |
 | `zsk-entry` | 2 | 只装 `zskplan` / `zsk` 两个主入口，由它们按 harness 调度 |
-| `zsk-lite` | 10 | 小修、小项目、脚本、低风险任务 |
-| `zsk-sdlc` | 19 | 标准工程交付；需求、实现、审查、验证、验收、归档 |
-| `zsk-frontend` | 20 | UI/UX/browser-facing 交付；强化 demo、视觉证据、前端质量门禁 |
-| `zsk-enterprise` | 20 | 高治理交付；要求 deploy、验收、归档、审计证据 |
-| `sdlc-only` | 22 | 旧入口兼容；安装全部 core skills |
+| `zsk-lite` | 11 | 小修、小项目、脚本、低风险任务 |
+| `zsk-sdlc` | 20 | 标准工程交付；需求、实现、审查、验证、验收、归档 |
+| `zsk-frontend` | 21 | UI/UX/browser-facing 交付；强化 demo、视觉证据、前端质量门禁 |
+| `zsk-enterprise` | 21 | 高治理交付；要求 deploy、验收、归档、审计证据 |
+| `sdlc-only` | 23 | 旧入口兼容；安装全部 core skills |
 
 ## Skill 搭配流程图
 
@@ -81,8 +81,8 @@ flowchart TD
 | --- | --- | --- |
 | 安装默认 core skills | `npx @captain_z/zsk add` | 交互选择 target 和 bundle |
 | CI 安装 ZSK 主入口 | `npx @captain_z/zsk add zsk-entry --target=~/.claude/skills --yes` | 非交互安装 `zskplan` / `zsk` 两个入口 |
-| CI 安装轻量 profile | `npx @captain_z/zsk add zsk-lite --target=~/.claude/skills --yes` | 非交互安装 10 颗常用 skills |
-| CI 安装标准 SDLC profile | `npx @captain_z/zsk add zsk-sdlc --target=~/.claude/skills --yes` | 非交互安装 19 颗标准 workflow skills |
+| CI 安装轻量 profile | `npx @captain_z/zsk add zsk-lite --target=~/.claude/skills --yes` | 非交互安装 11 颗常用 skills |
+| CI 安装标准 SDLC profile | `npx @captain_z/zsk add zsk-sdlc --target=~/.claude/skills --yes` | 非交互安装 20 颗标准 workflow skills |
 | Claude plugin 安装 | `/plugin marketplace add codeshareman/zsk` 后 `/plugin install zsk@zsk` | 使用 `/zsk:<slug>` 命令面 |
 | GitHub skills 管理器安装 | `npx skills add codeshareman/zsk` | 从仓库根 `skills/` 安装；不要加 `@` |
 | 只想让 ZSK 自己规划和执行 | "用 `zsk:zskplan` 规划" / "用 `zsk:zsk` 继续" | 计划写入 `.zsk/plans/`，执行产物写入 `.zsk` |
@@ -113,33 +113,33 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 
 | 领域              | skill 数 | 职责                                       |
 | ----------------- | -------- | ------------------------------------------ |
-| `skills/`         | 22       | harness-first 默认工作流入口               |
-| **总计**          | **22**   |                                            |
+| `skills/`         | 23       | harness-first 默认工作流入口               |
+| **总计**          | **23**   |                                            |
 
 ## 安装套件（bundles.yaml）
 
 | name                           | skills | 场景                                          |
 | ------------------------------ | ------ | --------------------------------------------- |
 | `zsk-entry`                    | 2      | 只安装 ZSK / ZSK Plan 两个主入口 |
-| `zsk-lite`                     | 10     | 小型低风险任务；ZSK 入口 + coding → smoke → review → commit |
-| `zsk-sdlc`（推荐）             | 19     | 标准工程交付；完整需求、实现、审查、验证、验收、归档链路 |
-| `zsk-frontend`                 | 20     | 前端/视觉/browser-facing 任务；强化 demo 和前端质量门禁 |
-| `zsk-enterprise`               | 20     | 高治理交付；要求 deploy、验收、归档、审计证据 |
-| `sdlc-only`                    | 22     | 旧入口兼容；安装全部 core skills |
-| `frontend-project`             | 22     | 旧入口兼容；推荐改用 `zsk-frontend` |
-| `frontend-with-design-handoff` | 22     | 旧入口兼容；推荐改用 `zsk-frontend` |
+| `zsk-lite`                     | 11     | 小型低风险任务；ZSK 入口 + fix/coding → smoke → review → commit |
+| `zsk-sdlc`（推荐）             | 20     | 标准工程交付；完整需求、实现、审查、验证、验收、归档链路 |
+| `zsk-frontend`                 | 21     | 前端/视觉/browser-facing 任务；强化 demo 和前端质量门禁 |
+| `zsk-enterprise`               | 21     | 高治理交付；要求 deploy、验收、归档、审计证据 |
+| `sdlc-only`                    | 23     | 旧入口兼容；安装全部 core skills |
+| `frontend-project`             | 23     | 旧入口兼容；推荐改用 `zsk-frontend` |
+| `frontend-with-design-handoff` | 23     | 旧入口兼容；推荐改用 `zsk-frontend` |
 | `custom`                       | 交互   | 通过 `zsk add` 任意多选                       |
 
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 22 skills -->
+<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 24 skills -->
 
 ## Skill 清单（core skills）
 
 > 内容由 `tools/catalog.ts` 从 `packages/skills/*/SKILL.md` frontmatter 生成。重生成：`pnpm catalog`。
 
-### `<slug>/` — Core · harness-first 默认工作流入口 (22)
+### `<slug>/` — Core · harness-first 默认工作流入口 (24)
 
 - **`zskplan`**
-  Use as the ZSK-aware RalphPlan-style planning entrypoint that freezes scope, skill route, expert lanes, Playwright/evidence paths, and stop conditions under .zsk.
+  Use as the ZSK-aware RalphPlan-style planning entrypoint that freezes scope, module decomposition, skill route, expert lanes, Playwright/evidence paths, and stop conditions under .zsk.
 
 - **`zsk`**
   Use as the ZSK-aware Ralph-style execution loop that follows ZSK plans, dispatches expert lanes, verifies, fixes, and writes only .zsk outputs.
@@ -153,6 +153,9 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 - **`prepare`**
   After project init, collects resource origins, snapshots evidence, and updates config/manifests before proposal/spec.
 
+- **`preproposal`**
+  Before proposal, turns a brief request into a reviewed product, roadmap, UX, and readiness raw resource pack.
+
 - **`proposal`**
   Before spec, frames the problem, scope, non-goals, success criteria, stakeholders, risks, and resource gaps.
 
@@ -172,7 +175,7 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
   After coding, proves changed behavior locally with targeted tests and relevant lint/typecheck/build evidence.
 
 - **`review`**
-  After smoke, reviews implementation against scope, specs, tasks, tests, security, maintainability, and evidence.
+  After smoke or explicit path targeting, reviews implementation or local targets against scope, contracts, evidence, security, maintainability, and ZSK boundaries.
 
 - **`commit`**
   After smoke and review pass, prepares a scoped commit with intent, evidence, and clean staging.
@@ -204,3 +207,6 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 - **`issue`**
   Tracks defects, blockers, questions, and risks with taxonomy, severity, owner, reproduction, and evidence.
 
+- **`fix`**
+  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

@@ -79,6 +79,8 @@ This core skill is governed by the ZSK harness. Enforce these rules even when on
 - 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.
 - 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.

package/acceptance/harness/THIS_SKILL.md

@@ -21,6 +21,12 @@ This file is generated for the installed skill. Read it before executing this sk
 - `confirmed-doc-feedback`
 - `residual-risk-list`
 
+## Required Output Enforcement
+
+- Every required output above is a hard requirement for this skill run.
+- If an output is not applicable, record `N/A` with evidence from scope, source, or project rules.
+- If an output cannot be produced, record `BLOCKED` with owner, missing input, impact, and next action.
+
 ## Allowed Tools And Capabilities
 
 - Tools: `filesystem`, `issue-update`
@@ -49,11 +55,67 @@ This file is generated for the installed skill. Read it before executing this sk
 - 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.
 - For each required output or finding, name owner, dependency, acceptance condition, verification evidence, and next action.
 
+## Industry Best-Practice Anchors
+
+- Diataxis (https://diataxis.fr/): choose document mode by reader need: task guidance, reference, explanation, or learning.
+- Google developer documentation style guide (https://developers.google.com/style): optimize for reader clarity, consistency, active language, examples, and project-specific terminology.
+- Definition of Done: completion requires shared, visible, measurable quality criteria.
+- Review workflows: a stage is not complete until another reader can inspect artifacts, evidence, decisions, and unresolved risks.
+- ISO/IEC/IEEE 12207 and 15288: lifecycle coverage should be method-neutral and accepted by equivalent artifacts or control points only when evidence exists.
+- ISO/IEC/IEEE 29148:2018 (https://www.iso.org/standard/72089.html): requirements work must produce traceable, testable information items, not only narrative intent.
+- ISO/IEC/IEEE 42010:2022 (https://www.iso.org/standard/74393.html), C4 (https://c4model.com/), and MADR (https://github.com/adr/madr): architecture/design work needs stakeholder concerns, viewpoints or equivalent views, context, rationale, tradeoffs, alternatives, consequences, and decision records.
+- ISO/IEC/IEEE 29119 (https://committee.iso.org/sites/jtc1sc7/home/projects/flagship-standards/isoiecieee-29119-series.html): testing needs test basis, traceability, coverage, entry/exit criteria, regression, defect closure, and reports.
+- Scrum Guide 2020 (https://scrumguides.org/scrum-guide.html): product work needs transparent product goals/backlog items, ordered value, inspection, and adaptation rather than one-shot requirements freezing.
+- ISO 9241-210:2019 (https://www.iso.org/standard/77520.html), confirmed current in 2025: human-centred design needs user/context understanding and design activities across the lifecycle of interactive systems.
+- GOV.UK Service Standard points 1 and 4 (https://www.gov.uk/service-manual/service-standard/point-1-understand-user-needs, https://www.gov.uk/service-manual/service-standard/point-4-make-the-service-simple-to-use): understand user needs before solutioning and test simplicity/usability with users.
+- Design Council Double Diamond / Framework for Innovation (https://www.designcouncil.org.uk/resources/the-double-diamond/): discovery, definition, development, and delivery may iterate when evidence changes the problem framing.
+- NIST SSDF (https://csrc.nist.gov/pubs/sp/800/218/final) and OWASP ASVS/SAMM (https://owasp.org/www-project-application-security-verification-standard/, https://owaspsamm.org/model/): security requirements, secure design, verification, and control evidence belong across the lifecycle.
+- DORA continuous delivery and metrics (https://dora.dev/capabilities/continuous-delivery/, https://dora.dev/guides/dora-metrics/): delivery design should preserve automated tests, deployment safety, observability, small batches, and measurable release outcomes.
+
+## Constraint Levels
+
+- `hard`: Mandatory stage contract. Missing, stale, contradictory, or placeholder-only evidence is FAIL/BLOCKED and cannot be waived by wording.
+- `conditional`: Mandatory when the trigger condition is touched by scope, sources, project rules, domain terms, or downstream evidence needs. If the condition applies, omission is FAIL/BLOCKED.
+- `advisory`: Best-practice guidance that improves quality, reviewability, or maintainability. It may be skipped only with a short rationale and no broken hard or conditional requirement.
+- `nA`: Allowed only when the artifact explains why the level or view does not apply, cites the evidence or project rule, and does not hide a missing mandatory input.
+
 ## Document Quality Standard
 
 - Document mode: `decisionRecord`
 - Purpose: Record the accept/reject business decision and residual-risk ownership.
 
+## Hard Requirements
+
+- Read the required inputs for the active skill, or stop as BLOCKED with owner, missing input, impact, and next action.
+- Produce every required output from the skill I/O contract, or mark the specific output BLOCKED with evidence.
+- Expose the required output contract in the artifact or handoff so the next skill can verify what was produced, blocked, or N/A.
+- Separate facts, decisions, assumptions, open questions, risks, blockers, and evidence.
+- Trace required claims to source artifacts, accepted decisions, scenarios, commands, issues, or human decisions.
+- 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.
+- Do not accept without verification evidence unless explicitly blocked and risk-accepted.
+
+## Conditional Requirements
+
+- When auth, permissions, privacy, security, tenancy, roles, data access, compliance, payment, migration, public API, or audit behavior is touched, produce the relevant control/traceability matrix or block with the missing source.
+- When architecture, interface, data-flow, storage, migration, dependency, rollback, integration, or cross-team ownership decisions are made, record ADR/decision-record entries with context, options, decision, consequences, rollback/migration notes, and linked requirements.
+- When UI-visible behavior is touched, include user-observable states, accessibility/locator strategy, scenario evidence needs, and stable test hooks.
+- 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 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.
+
+## Advisory Guidance
+
+- Prefer the smallest artifact that lets the next reader decide and act without chat memory.
+- Use tables, matrices, diagrams, or checklists only when they clarify ownership, traceability, risk, or execution.
+- Use project terminology and source identifiers consistently across proposal, spec, design, task, and evidence artifacts.
+- Record suggestions separately from current project policy, especially for thresholds that remain `未指定`.
+- Keep acceptance focused on decision and risk, not implementation recap.
+- Preserve rejection reasons in a form that can route back to issue/fix.
+
 ## Must Answer
 
 - Is the verified work accepted, rejected, or conditionally accepted?
@@ -75,6 +137,7 @@ This file is generated for the installed skill. Read it before executing this sk
 - Names owner, dependency, acceptance condition, and verification evidence for every required output or blocker.
 - Runs or references the stage-entry quality gate before downstream handoff; below-threshold but non-blocking gaps require explicit risk acceptance instead of silent progression.
 - For testable work, verifies test correctness, not only test execution: traceable test basis, meaningful assertions, negative/boundary/regression coverage, and skipped/unrun checks called out.
+- When proposal, spec, design, or tasks become too large for one reviewable file, the artifact may split to `{stage}/index.md` plus linked child Markdown files; the index remains the entrypoint and the full stage contract still applies.
 - Links verify report, demo evidence, accepted criteria, and residual risks.
 - Records documentation feedback or no-update rationale for confirmed learnings.
 
@@ -133,6 +196,7 @@ This file is generated for the installed skill. Read it before executing this sk
 ## Hard Stops
 
 - Required input is missing, stale, or contradictory.
+- A hard requirement or triggered conditional requirement cannot be satisfied with linked evidence.
 - The requested work belongs to an earlier or later ZSK stage.
 - Evidence cannot be linked to command output, artifact, issue, scenario, or human decision.
 - The fix would widen scope beyond this skill's responsibility.

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

@@ -6,11 +6,14 @@ Default project paths:
 - `.zsk/docs/`: project-level docs such as `SYSTEM-SPEC.md` and `PROJECT-CONFIG.md`.
 - `.zsk/modules/{module}/`: module config and stage artifacts.
 - `.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 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/`: reusable improvement proposals and learning records, created lazily only when learn/archive writes an actual proposal.
+- `.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.
 
@@ -40,4 +43,6 @@ Before any skill writes an artifact, classify its scope:
 
 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`. Supporting artifacts stay in the appropriate `_issues`, `_evidence`, or `_playwright` directory unless they are deliberately shared/global/public.
+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 proposal-prep raw resources under `.zsk/raws/prepare/**` plus checkpoint evidence under `.zsk/evidence/preproposal/{run}/`. 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/acceptance/harness/constraints/issue-taxonomy.md

@@ -88,6 +88,22 @@ Every actionable issue should record:
 - whether a durable learning proposal is needed under `.zsk/learning/proposals`;
 - 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.

package/acceptance/harness/constraints/skill-role-contract.md

@@ -12,6 +12,19 @@ ZSK skills must work across project types, team methods, tools, and platforms. A
 - Every required output or finding needs an owner, dependency, acceptance condition, verification evidence, and next action.
 - Security, privacy, data safety, release readiness, test traceability, and continuous improvement are lifecycle concerns. They are N/A only when the project context proves they do not apply.
 
+## Constraint Level Model
+
+Each skill must separate requirements by enforcement level before it claims PASS, READY, DONE, or an unblocked handoff.
+
+- **Hard requirements** are mandatory for the stage. Missing inputs, outputs, evidence, owners, gates, traceability, or blocking contradictions are `FAIL` or `BLOCKED`.
+- **Conditional requirements** are mandatory when the scope, sources, domain terms, project rules, or downstream evidence needs trigger them. When triggered, they have the same blocking force as hard requirements.
+- **Advisory guidance** improves reviewability or maintainability but cannot override missing hard or triggered conditional requirements. If skipped, record a short rationale.
+- **N/A** is valid only with evidence-backed rationale. It cannot hide a missing source, missing policy, or missing required output.
+
+Cross-cutting controls are conditional hard requirements, not optional polish. If auth, permissions, privacy, roles, tenancy, data access, audit, compliance, public APIs, payment, migration, or security behavior is touched, the owning stage must produce or consume the relevant traceability/control matrix. A missing matrix is a blocker unless the source/spec explicitly proves the control is out of scope.
+
+ADR/decision records are mandatory for design-significant decisions, not a stylistic preference. If a stage makes or consumes an architecture, interface, data-flow, storage, migration, dependency, rollback, integration, cross-team ownership, security, or permission-enforcement decision, it must record or cite an ADR/decision-record entry with context, options considered, decision, consequences, rollback or migration notes, and linked requirements/evidence. `task` must preserve ADR traceability into executable work.
+
 ## Cross-Project Portability Rule
 
 Core skills and harness rules must be generic by default.
@@ -41,10 +54,11 @@ Each skill owns one stage contract. Workflow skills may route or schedule work,
 | Skill | Owns | Does Not Own | Consistency / Handoff |
 | --- | --- | --- | --- |
 | `prepare` | Source discovery, configured origin validation, raws snapshots, manifest, source gaps | Product interpretation, requirements decisions, design choices | Hands source manifest, raws indexes, conflicts, and blockers to `proposal` / `spec`; asks before uncertain source-to-lane mapping |
+| `preproposal` | Proposal-prep raw resources: product direction, MVP/phase/module decomposition, UX/design-readiness seeds, assumptions, risks, scenario seeds, checkpoint review evidence | Formal module proposal/spec/design/tasks, formal test cases, implementation | Hands reviewed `.zsk/raws/prepare/**` resources and `.zsk/evidence/preproposal/**` checkpoint verdicts to `proposal`; product review must pass before roadmap, roadmap before UX, UX before readiness |
 | `proposal` | Problem, goal, scope, non-goals, stakeholders, risks, success metrics, decision request | Detailed behavior, architecture, task breakdown, implementation | Every goal and metric must trace to sources or accepted assumptions; hands bounded scope to `spec` |
-| `spec` | FR/NFR, acceptance criteria, scenarios, edge cases, constraints, traceability | Architecture, file/module design, implementation tasks | Every P0/P1 requirement must trace to proposal/source and be testable; hands behavior contract to `design` and `task` |
-| `design` | Architecture, interfaces, data/state flow, design views/diagrams, ADRs or equivalent decisions, tradeoffs, rollout and verification surfaces | Rewriting requirements, task sequencing, coding, decorative diagrams | Every design decision and diagram must trace to spec/AC/NFR, ADR, risk, or verification need; hands implementation map to `task` |
-| `task` | Kiro-style nested checkbox task groups/subtasks, owners, dependencies, scope/files, evidence hooks, coverage matrix | Changing proposal/spec/design intent, coding, review approval | Every task group must align to proposal/spec/design IDs; every subtask must be executable and evidence-backed before `coding` |
+| `spec` | FR/NFR, acceptance criteria, scenarios, edge cases, constraints, traceability, behavior-level control matrix when triggered | Architecture, file/module design, implementation tasks | Every P0/P1 requirement must trace to proposal/source and be testable; cross-cutting control behavior must trace to subject/action/resource/scope/source; hands behavior contract to `design` and `task` |
+| `design` | Architecture, interfaces, data/state flow, design views/diagrams, ADRs or equivalent decision records, tradeoffs, rollout and verification surfaces, control traceability matrix when triggered | Rewriting requirements, task sequencing, coding, decorative diagrams | Every design decision and diagram must trace to spec/AC/NFR, ADR, risk, or verification need; triggered controls must trace to enforcement/UI/API/state/test surfaces; hands implementation map to `task` |
+| `task` | Kiro-style nested checkbox task groups/subtasks, owners, dependencies, scope/files, evidence hooks, proposal/spec/design/ADR coverage matrix, control-row task coverage when triggered | Changing proposal/spec/design intent, coding, review approval | Every task group must align to proposal/spec/design/ADR IDs; every subtask must be executable and evidence-backed before `coding`; triggered control rows must map to implementation and evidence tasks |
 | `coding` | Scoped implementation, changed tests, implementation notes, local validation evidence | Requirements changes, broad refactors, final approval | Every diff maps to task IDs and preserves upstream intent; hands changed files and evidence to `smoke` / `review` |
 | `smoke` | Smallest credible local proof of changed behavior, failure classification, smoke issues | Full acceptance, final verification, release approval | Hands command/scenario evidence and failures to `review`, `defect`, or `ready` |
 | `review` | Scope drift, correctness, maintainability, security, test adequacy, harness compliance findings | Implementing fixes, independent verification, business acceptance | Findings must reference files/artifacts and route fix work to `issue` / `defect` / `coding`; no PASS without evidence adequacy |
@@ -57,11 +71,12 @@ Each skill owns one stage contract. Workflow skills may route or schedule work,
 | `acceptance` | Accept/reject decision, residual risk, business/user confirmation, documentation feedback | New verification, implementation fixes | Hands accepted state, waived risks, or rejection reasons to `archive` / `issue` |
 | `archive` | Final artifact preservation, closed issue audit, learning proposals, release notes | Changing delivered scope, reopening decisions without issue evidence | Preserves decisions/evidence and promotes reusable gaps to `learn` |
 | `learn` | Learning proposal intake, pattern comparison, optimization batch planning, reusable ZSK core proposal routing | Unreviewed mutation of core skills/harness/templates, scattering core learning into consuming projects | Writes project-local learning only for project-specific change; writes reusable core learning to canonical ZSK source repo proposals; requires review/regression before promotion |
-| `issue` | Persistent issue/defect/risk/question records, indexes, owner/status/evidence fields | Resolving the issue by assertion, replacing review/verify | Provides the shared feedback and closure ledger for all stages |
+| `issue` | Persistent issue/defect/risk/question records, indexes, owner/status/evidence fields, issue-driven fix ledger fields | Resolving the issue by assertion, replacing review/verify | Provides the shared feedback and closure ledger for all stages; issue-driven `fix` work remains open until smoke/review/verify evidence is linked |
+| `fix` | Issue-driven root-cause analysis, minimal correction route, regression guard, issue ledger update, smoke/review/verify handoff | Generic cleanup, new issue intake, broad redesign, independent verification or closure by assertion | Consumes a persisted issue or accepted expected/actual clarification; routes implementation through `coding` discipline and leaves closure to `verify` / `acceptance` |
 | `dispatch` | Runtime staffing plan, active roles, write scopes, evidence obligations, durable emit packets, packet status ledger | Business or technical stage output | Supports any stage skill from the resource pool; stale or delayed packets fall back to leader-sequential role simulation |
 | `flow` | Next legal stage decision from state, resources, blockers, profile, and stage-entry quality assessment | Stage artifact production | Routes only when gates allow; reports blockers or quality-confirmation needs instead of forcing progression |
-| `zskplan` | Route freeze, selected skills, output map, expert lane plan, evidence plan, blockers | Implementation and verification | Produces the plan contract that `zsk` executes |
-| `zsk` | End-to-end execution loop, skill dispatch, expert lane integration, validation/fix loop | Skipping selected skill contracts or evidence gates | Executes the frozen or inferred route until complete or blocked |
+| `zskplan` | Route freeze, governing-rule coverage, module decomposition, per-module stage route, selected skills, output map, expert lane plan, evidence plan, blockers | Implementation, verification, runtime dispatch, and final proposal/spec/design/task artifact authoring | Produces the plan contract that `zsk` executes; each planned stage skill still owns its artifact and gates |
+| `zsk` | Plan-driven stage orchestration, end-to-end execution loop, skill dispatch, expert lane integration, validation/fix loop | Skipping selected skill contracts or evidence gates | Executes the frozen or inferred route until complete or blocked |
 
 ## Collaboration Consistency Gate
 
@@ -69,6 +84,7 @@ Before a skill reports `PASS`, `READY`, `DONE`, or an unblocked handoff, it must
 
 ```text
 prepare sources
+-> preproposal product / roadmap / UX raw resources when needed
 -> proposal goals / scope / success metrics
 -> spec FR / AC / NFR / scenarios
 -> design decisions / ADRs / interfaces / data flow
@@ -91,6 +107,24 @@ Consistency checks:
 - No skill silently changes another skill's artifact; it records a feedback item, issue, or blocker instead.
 - Workflow skills (`flow`, `zskplan`, `zsk`) choose the route. Stage skills state status, blockers, handoff needs, and next legal candidates only.
 
+## Preproposal Team Simulation
+
+`preproposal` is one workflow-node with role lanes, not a set of standalone skills.
+
+- Product-owner and business-analyst lanes own product direction, user/problem framing, business process, scope options, non-goals, risks, and evidence gaps.
+- Planner and architect lanes own MVP/phase/module decomposition, dependency shape, boundary rationale, deferred work, and feasibility risks.
+- UX and design-specialist lanes own user journey, IA/navigation seeds, interaction states, usability/accessibility risks, and design-source needs.
+- QA and researcher lanes own scenario seeds, risk seeds, test-basis candidates, current external evidence when needed, and source gaps.
+- Verifier/lead-integrator owns checkpoint completeness, blocker creation, raw manifest/index update or no-update rationale, and readiness handoff.
+
+Checkpoint order is mandatory when dependencies exist:
+
+```text
+product review -> roadmap/decomposition review -> UX/design-readiness review -> readiness review -> proposal
+```
+
+If a checkpoint repeatedly fails, the lead does not keep rewriting silently. It creates or updates a blocker/issue with owner, missing input, impact, next action, and retry count. The default retry limit is 2 unless project config supplies a different policy; unsupplied project thresholds are still recorded as `未指定`.
+
 ## Kiro-Style Task Handoff
 
 `task` must use nested Markdown checkboxes as the primary execution surface:
@@ -101,7 +135,7 @@ Consistency checks:
   - [ ] 1.2 <subtask>
 ```
 
-Metadata belongs under the relevant checkbox item, not in a detached table alone. Each task group needs proposal/spec/design alignment, owner, dependencies, scope/files, expected output, evidence, and stop condition. Each subtask needs at least source ID, owner, scope/files, expected output, acceptance, and evidence. A task artifact without this hierarchy is not execution-ready.
+Metadata belongs under the relevant checkbox item, not in a detached table alone. Each task group needs proposal/spec/design/ADR alignment, owner, dependencies, scope/files, expected output, evidence, and stop condition. Each subtask needs at least source ID, owner, scope/files, expected output, acceptance, and evidence. A task artifact without this hierarchy is not execution-ready.
 
 ## Role Completeness
 
@@ -151,7 +185,9 @@ Use local SRS/PRD/customer notes first. If they are absent, stale, or insufficie
 
 ## Review-Specific Minimum
 
-`review` must always cover these lanes before a PASS verdict:
+`review` must classify the target mode before applying prerequisites. Supported modes include implementation/code-diff, preproposal/raw-source, `.zsk` workspace, stage/module doc, design/source target, and generic explicit path.
+
+Implementation/code-diff review covers these lanes before a PASS verdict:
 
 - scope and requirement drift;
 - execution-path correctness;
@@ -162,14 +198,25 @@ Use local SRS/PRD/customer notes first. If they are absent, stale, or insufficie
 - performance, concurrency, migration, and rollout checks when touched;
 - ZSK harness compliance, output paths, issue taxonomy, and documentation feedback.
 
+Preproposal/raw-source review must cover product direction, roadmap/decomposition, UX/design-readiness, assumptions/risks, source gaps, checkpoint order, readiness for proposal, and raw/evidence path placement. It must not fail merely because module `spec`, `design`, `tasks`, or `smoke` artifacts are absent.
+
+Stage/module doc review must cover the target stage contract, source traceability, required outputs, blockers, downstream handoff quality, and split-artifact index/child links when used.
+
+`.zsk` workspace review must cover config/filesystem correspondence, raws/source taxonomy, active module workspace, issue/evidence/playwright scope routing, learning proposal authority, and stale path references.
+
 For `DEEP` review, dispatch at least three independent expert lanes when subagents are available: architecture/API, security/data, and tests/evidence. Add frontend/performance specialists when the diff touches those domains.
 
 ## ZSK Entry Points
 
 `zskplan` and `zsk` are ZSK-aware RalphPlan/Ralph-style user surfaces, not shortcuts around the harness.
 
-- `zskplan` freezes the route and writes the plan artifact under `.zsk/plans/`: selected skills, required inputs, `.zsk` output map, expert lanes, subagent plan, Playwright/auth/evidence plan, fix loop, blockers, and stop condition.
-- `zsk` executes the frozen or inferred route: it selects the legal skill, dispatches required expert lanes, integrates results, writes only `.zsk` artifacts, validates, fixes, and repeats until the plan is complete or blocked.
+- `zskplan` freezes the route and writes the plan artifact under `.zsk/plans/`: governing-rule coverage, module decomposition, per-module stage route, selected skills, required inputs, `.zsk` output map, expert lanes, subagent plan, Playwright/auth/evidence plan, fix loop, blockers, and stop condition.
+- `zskplan` may plan `preproposal` and module-level `proposal`, `spec`, `design`, and `task` outputs from a simple proposal plus system/project rules. It must not dispatch those stages or author those final artifacts itself; `zsk` executes the plan and the selected stage skill must run with its own required inputs, forbidden scope, output contract, and evidence gate.
+- Until a plan artifact explicitly says `Ready for zsk: yes`, `zskplan` may write only the chosen `.zsk/plans/**` artifact. It must not mutate `skills/**`, `harness/**`, `packages/**`, `tools/**`, generated package assets, product code, or runtime evidence.
+- If `.zsk/docs/SYSTEM-SPEC.md` or `.zsk/docs/PROJECT-CONFIG.md` is missing, `zskplan` may plan a rule-bootstrap step from proposal evidence, configured sources, repo facts, and best-practice references. Derived rules must be labeled `inferred`, unsupplied thresholds must remain `未指定`, and mandatory unaccepted policy remains a blocker.
+- `zsk` executes the frozen or inferred route: it selects the legal module/stage pair and skill from the plan, dispatches required expert lanes, runs `preproposal`, `proposal`, `spec`, `design`, `task`, or later stage skills through their own contracts, integrates results, writes only `.zsk` artifacts, validates, fixes, and repeats until the plan is complete or blocked.
+- When the route includes `preproposal`, `zsk` must run the checkpoint review loop in order and preserve checkpoint verdicts before formal proposal starts.
+- `fix` is the dedicated issue-driven skill and route name. It requires a persisted issue path/id or equivalent accepted clarification, then routes through root-cause analysis, scoped `coding`, regression guard, issue update, `smoke`/`review`, `ready`, and `verify`. It is not generic repair and must not bypass downstream stage contracts.
 - Neither entry point may skip a selected skill's own contract, forbidden scope, required inputs, issue routing, or evidence gate.
 - Before entering a downstream stage, the workflow must evaluate required upstream artifact quality or record why the gate is N/A. Below-threshold quality gaps require an explicit risk acceptance; missing mandatory artifacts remain blocked.
 - Every emitted subagent packet must be durable: `runId`, `packetId`, heartbeat/deadline policy, status path, write scope, evidence obligation, stop condition, and fallback route. Stale packets must be completed by fallback evidence or re-emitted; they cannot count as completed work.
@@ -190,6 +237,7 @@ For `DEEP` review, dispatch at least three independent expert lanes when subagen
 - write project-local proposals under the current project's `.zsk/learning/proposals/` only when the proposal affects that project alone;
 - write reusable ZSK core proposals under the canonical ZSK source repo `.zsk/learning/proposals/`, resolved by `ZSK_LEARNING_REPO`, `ZSK_CORE_REPO`, or a recognized ZSK source checkout;
 - if the canonical ZSK source repo cannot be resolved or is not writable, report `BLOCKED` with the missing root, intended proposal name, evidence, and next action instead of writing core learning into the consuming project;
+- sync-check linked project-local and reusable core proposals together; if one side changes and the counterpart does not, record a no-update rationale in the edited proposal;
 - group accepted proposals into one optimization batch with target files, regression prompts, risks, and review status.
 
 `learn` must not mutate core skills, harness constraints, packs, templates, or generated artifacts from one unreviewed incident. It must not copy external skills or harnesses wholesale; it adapts principles and testable constraints into ZSK proposals with source notes. Promotion requires review evidence and regression prompts.

package/acceptance/harness/constraints/stage-gates.md

@@ -21,10 +21,38 @@ The harness computes gate status. Skills may propose outputs and record evidence
 
 - Before a downstream stage starts, the harness must assess the required upstream artifacts for that stage with `zsk gate assess --stage <stage>`.
 - The assessment must write a score, PASS/FAIL criteria, blockers, gaps, and next action under `.zsk/evidence/gates/`.
+- Gate criteria follow the harness constraint levels: hard requirements and triggered conditional requirements are blockers; advisory gaps may require confirmation but cannot be counted as satisfied evidence.
 - A score below the configured threshold is not an infinite hard stop by itself. If all required artifacts exist and only quality gaps remain, the stage may continue only after an explicit human risk acceptance is recorded with `--accept-risk`.
 - Missing required artifacts, placeholder-only upstream docs, missing project/system rules for governed stages, or missing mandatory test basis remain `BLOCKED`; a risk waiver must not convert those into PASS. Very short but non-placeholder artifacts are quality gaps, not hard blockers.
 - Thresholds are project policy. When no project threshold is configured, the CLI default is an advisory 9/10 gate; documents must still record unsupplied numeric thresholds as `未指定` instead of inventing policy.
 
+## Preproposal Checkpoint Gate
+
+- Use `preproposal` when a brief request lacks reviewed product direction, roadmap/decomposition, UX/design-readiness, or source-readiness material for `proposal`.
+- Product checkpoint must pass before roadmap/decomposition starts. It reviews target users, problem, outcome, scope options, non-goals, risks, assumptions, and source gaps.
+- Roadmap/decomposition checkpoint must pass before UX/detail work starts. It reviews MVP/1.0/2.0 or equivalent phase split, module boundaries, dependencies, deferred work, and merge/split/block rationale.
+- UX/design-readiness checkpoint must pass before readiness handoff. It reviews user journey, IA/navigation seeds, interaction states, accessibility/usability risks, and design-source needs.
+- Readiness checkpoint must pass before formal `proposal`. It verifies that `.zsk/raws/prepare/**` and `.zsk/evidence/preproposal/{run}/` contain enough reviewed raw material for proposal without chat memory.
+- A checkpoint failure loops only while the missing input is actionable. Repeated failures beyond the configured retry limit, or default 2 when no project policy exists, become a tracked blocker/issue with owner, missing source, impact, and next action.
+- Preproposal checkpoint reviews use the target-aware `review` skill. They must not require module `spec`, `design`, `tasks`, or `smoke` artifacts unless the explicit review target is an implementation/code-diff review.
+
+## Cross-Cutting Control Gate
+
+- Auth, permissions, privacy, roles, tenancy, data access, audit, compliance, public API, payment, migration, or security behavior triggers conditional hard requirements.
+- `spec` must describe triggered control behavior at product/contract level: subject/actor, action/capability, resource/data, scope, expected outcome, source rule, and AC/scenario.
+- `design` must map triggered controls to implementation surfaces: UI/API/state behavior, enforcement point, data flow, failure state, and test/evidence path.
+- `task` must map every triggered control row to implementation, test/scenario, docs/issue, and evidence tasks.
+- `review`, `ready`, and `verify` must reject missing or stale triggered control rows when the touched scope depends on them.
+- N/A is acceptable only when the artifact cites the source rule or scope decision proving the control is out of scope.
+
+## ADR / Decision Record Gate
+
+- Design-significant decisions require ADR/decision-record entries before task planning.
+- Triggering decisions include architecture, interface contracts, data/state flow, storage, migration, dependency choice, rollback, cross-system integration, cross-team ownership, security, permission enforcement, privacy, and public API behavior.
+- Each ADR/decision-record entry must include context, linked requirements/AC/NFR, options considered, decision, consequences, risks, rollback or migration notes, and verification/evidence path.
+- `task` must preserve ADR IDs or decision-record references in the proposal/spec/design/ADR alignment matrix and in affected task groups.
+- N/A is acceptable only when the design proves no design-significant decision was made beyond directly implementing the approved spec.
+
 ## Test Correctness Gate
 
 - A passing test suite is not sufficient evidence when the tests do not prove the intended behavior.
@@ -34,6 +62,19 @@ The harness computes gate status. Skills may propose outputs and record evidence
 - `smoke`, `review`, and `verify` must reject fake passes: skipped tests, tests with no assertions, tests that only assert mocks were called while ignoring user-visible behavior, tests that assert implementation details instead of contract behavior, or tests that pass because expected data is hardcoded to the implementation.
 - Every test report must distinguish passed, failed, skipped, flaky, unrun, and not-applicable checks. Skipped or unrun checks are not PASS.
 
+## Static Problems Gate
+
+- `coding` and `review` must not pass with ESLint or TypeScript diagnostics at either error or warning severity.
+- Treat VS Code Problems-equivalent diagnostics as blocking when they come from ESLint, TypeScript, or the configured project linter/typechecker for touched files.
+- If the project exposes lint/typecheck commands, run or cite fresh results before claiming `coding` ready-for-smoke or `review` pass. If the commands are unavailable, record `BLOCKED` or an explicit tool gap instead of downgrading warnings to nits.
+
+## Source Migration Sync Gate
+
+- When configured source origins move, source lanes are retired, or legacy/provenance raw paths are removed, the same pass must refresh current authority artifacts: `.zsk/config.yaml`, `.zsk/raws/manifest.json`, raw indexes, `.zsk/docs/PROJECT-CONFIG.md`, `.zsk/docs/SYSTEM-SPEC.md`, and affected source docs.
+- Run a stale-reference scan over current authority files for retired source keys, raw paths, module ids, and obsolete provenance wording. Immutable evidence snapshots may retain historical terms, but current docs and indexes need either an update or an explicit no-update rationale.
+- Current authority artifacts must not reference root `.raws/`, `.issues/`, or `.playwright/` paths unless the reference is explicitly waived with a rationale.
+- `zsk check` diagnostics should point to the intended migration target path instead of only saying a legacy path is invalid.
+
 ## Durable Dispatch Gate
 
 - Every dispatched role/subagent lane must have a durable emit packet with `runId`, `packetId`, write scope, evidence obligation, stop condition, status path, and fallback route.

package/acceptance/harness/profiles/enterprise.yaml

@@ -25,6 +25,7 @@ stages:
     - acceptance
     - archive
   optional:
+    - preproposal
     - demo
     - defect
   sideChannel:
@@ -49,6 +50,10 @@ flow:
     - acceptance
     - archive
   optionalInsertions:
+    preproposal:
+      after: prepare
+      before: proposal
+      when: Governance requires reviewed product, roadmap, UX, and readiness raw resources before formal proposal.
     demo:
       after: deploy
       before: ready

package/acceptance/harness/profiles/frontend.yaml

@@ -24,6 +24,7 @@ stages:
     - acceptance
     - archive
   optional:
+    - preproposal
     - deploy
     - defect
   sideChannel:
@@ -48,6 +49,10 @@ flow:
     - acceptance
     - archive
   optionalInsertions:
+    preproposal:
+      after: prepare
+      before: proposal
+      when: A UI/UX request lacks reviewed product direction, roadmap/decomposition, UX flows, or design-source readiness.
     deploy:
       after: commit
       before: ready

package/acceptance/harness/profiles/sdlc.yaml

@@ -22,6 +22,7 @@ stages:
     - acceptance
     - archive
   optional:
+    - preproposal
     - deploy
     - demo
     - defect
@@ -46,6 +47,10 @@ flow:
     - acceptance
     - archive
   optionalInsertions:
+    preproposal:
+      after: prepare
+      before: proposal
+      when: A brief request lacks reviewed product direction, roadmap/decomposition, UX readiness, or source-readiness raw material.
     deploy:
       after: commit
       before: ready