@captain_z/zsk-skills 1.8.2 → 1.8.4

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/`。
+包内共有 **24 颗 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`） | ✓ 24/24 | core 由 root `skills/` 生成 |
+| `name` 使用裸 slug，扁平且不含连字符                                                       | ✓ 24/24 | LLM 原生 skill 入口保持简洁；CLI 选择层使用 `zsk:<slug>` |
+| `description` 简洁表达职责和使用时机                                                       | ✓ 24/24 | 面向索引阅读；triggers 留给机器使用 |
+| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 24/24 | stage/utility · core |
+| `triggers` 数组非空                                                                      | ✓ 24/24 | 至少含裸 slug |
 | 无硬编码项目名 / 技术栈（统一 `{{config.*}}` 占位符）                                    | ✓       | harness-neutral                                       |
 | `related:` 相对路径合法                                                                  | ✓       | core 不依赖参考层生成物                               |
-| 单文件 ≤ 300 行                                                                          | ✓ 22/22 | core 由 `lint:harness` 强制                           |
+| 单文件 ≤ 300 行                                                                          | ✓ 24/24 | 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` | 21 | 标准工程交付；需求、实现、审查、验证、验收、归档 |
+| `zsk-frontend` | 22 | UI/UX/browser-facing 交付；强化 demo、视觉证据、前端质量门禁 |
+| `zsk-enterprise` | 22 | 高治理交付；要求 deploy、验收、归档、审计证据 |
+| `sdlc-only` | 24 | 旧入口兼容；安装全部 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` | 非交互安装 21 颗标准 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/`         | 24       | harness-first 默认工作流入口               |
+| **总计**          | **24**   |                                            |
 
 ## 安装套件（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`（推荐）             | 21     | 标准工程交付；完整需求、实现、审查、验证、验收、归档链路 |
+| `zsk-frontend`                 | 22     | 前端/视觉/browser-facing 任务；强化 demo 和前端质量门禁 |
+| `zsk-enterprise`               | 22     | 高治理交付；要求 deploy、验收、归档、审计证据 |
+| `sdlc-only`                    | 24     | 旧入口兼容；安装全部 core skills |
+| `frontend-project`             | 24     | 旧入口兼容；推荐改用 `zsk-frontend` |
+| `frontend-with-design-handoff` | 24     | 旧入口兼容；推荐改用 `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 clarifies vague intake, then 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 one-sentence or vague intake brief into a clear, 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,9 +79,13 @@ 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.
+- Stage Challenge Gate: when an existing stage artifact is present, the active skill must challenge only its own responsibility, required inputs, required outputs, must-answer questions, quality checkpoints, current artifact, upstream sources, and downstream consumer; route cross-stage gaps to their owning stage instead of running a generic grill.
 - 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.
 
@@ -93,7 +97,7 @@ When a `harness/` directory is installed beside this file, treat it as the local
 - 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.
-

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,73 @@ 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.
+- When an existing stage artifact is present, the active skill must run its own Stage Challenge Gate before downstream handoff: derive the challenge focus 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 Stage Challenge Gates skill-local: ask, repair, or block only on questions the active skill owns; route upstream or downstream findings to the owning stage instead of absorbing another skill's responsibility.
+- Every Stage Challenge Gate 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.
+- 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 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 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.
+- When a skill challenges an artifact, name any overloaded, translated, or conflicting term before asking the user or editing the artifact.
+- 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?
@@ -72,9 +140,14 @@ This file is generated for the installed skill. Read it before executing this sk
 - Accepts different project methods and artifact names only when they provide an equivalent control point with evidence.
 - Uses PASS, FAIL, BLOCKED, or N/A only with evidence; missing mandatory evidence remains a failure, not an assumption.
 - Records numeric targets or thresholds as `未指定` when the project has not supplied them; never invents thresholds to make an output look complete.
+- Records `Context update: <path>` or `Context update: N/A` so later stages do not depend on hidden chat terminology.
+- Names terminology alignment status for the active artifact: source-consistent, repaired, conflicting, missing, or N/A.
 - Names owner, dependency, acceptance condition, and verification evidence for every required output or blocker.
+- Names existing stage artifact clarity status as PASS, NEEDS_REPAIR, BLOCKED, or WAIVED when a prior artifact is being consumed or improved.
+- Names the Stage Challenge Gate focus and shows it came from the active skill contract rather than a generic grill.
 - 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.
 
@@ -108,6 +181,10 @@ This file is generated for the installed skill. Read it before executing this sk
 - Passing because a familiar term appears while the equivalent lifecycle function is absent.
 - Inventing project policy, quality thresholds, source mappings, or platform behavior without configured evidence.
 - Treating missing evidence as low risk when the stage output depends on that evidence.
+- Discarding or rewriting an unclear existing stage artifact before classifying what is sourced, accepted, assumed, conflicting, or missing.
+- Running a generic grill or cross-stage rewrite instead of the active skill's own Stage Challenge Gate.
+- 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.
 - 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.
@@ -133,6 +210,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

@@ -5,17 +5,37 @@ 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/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.
 - `.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.
 
 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/docs/CONTEXT.md`.
+- 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.
+
 ## Learning Output Authority
 
 Learning artifacts must be written according to what they are meant to change:
@@ -40,4 +60,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 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/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,11 +54,12 @@ 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` | Intake clarity, proposal-prep raw resources: product direction, MVP/phase/module decomposition, UX/design-readiness seeds, interaction handoff when triggered, candidate code component mapping when code exists, assumptions, risks, scenario seeds, checkpoint review evidence | Formal module proposal/spec/design/tasks, formal test cases, final implementation decisions | Hands reviewed `.zsk/raws/prepare/**` resources and `.zsk/evidence/preproposal/**` checkpoint verdicts to `proposal`; source-discoverable questions must be answered before asking the user; 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` |
-| `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` |
+| `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` | Code design: architecture, interfaces, data/state flow, implementation surfaces, design views/diagrams, ADRs or equivalent decision records, tradeoffs, rollout and verification surfaces, control traceability matrix when triggered | Rewriting requirements, authoring interaction handoff, deciding missing UX/Figma behavior, 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, vertical TDD cycles, changed tests, implementation notes, local validation evidence | Requirements changes, broad refactors, final approval | Every diff maps to task IDs and preserves upstream intent; each testable behavior records RED/GREEN evidence before the next behavior; 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 |
 | `commit` | Scoped staging, Lore commit message, commit evidence, known verification gaps | Feature validation, release readiness | Hands immutable change intent and tested/not-tested evidence to `deploy` / `archive` |
@@ -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,127 @@ 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.
 
+## Stage Artifact Clarity Pass
+
+Every stage owns clarity and repair for the artifacts it owns. If a stage artifact
+already exists but is unclear, incomplete, contradictory, placeholder-like, or too
+weak for the next consumer, the workflow must route to the owning stage instead
+of restarting from intake, skipping ahead, or letting a downstream skill repair
+upstream intent.
+
+This is a skill-local Stage Challenge Gate, not a generic grilling session. The
+active skill must auto-identify what to challenge from its own responsibility,
+required inputs, required outputs, must-answer questions, quality checkpoints,
+current artifact, upstream sources, and downstream consumer. It may surface
+upstream or downstream findings, but those findings are routed to the owning
+stage instead of being silently absorbed.
+
+The challenge basis is also skill-local: use this skill's `THIS_SKILL.md`,
+`skill-quality-standards.yaml`, bundled related best-practice files, and current
+official references when local references are incomplete or version-sensitive.
+Do not reuse another stage's checklist as the active challenge unless the finding
+is routed back to that owning stage.
+
+Every skill-local challenge also performs terminology alignment. Compare the
+artifact's domain terms, actor names, module names, stage IDs, FR/AC/NFR/ADR IDs,
+UI component names, route/API names, and source/provider labels against
+`CONTEXT.md` / `CONTEXT-MAP.md` when present, `.zsk/docs/SYSTEM-SPEC.md`,
+configured raw sources, and implementation names when the skill touches code or
+UI surfaces. If a term is overloaded, stale, translated inconsistently, or
+conflicts with upstream/downstream language, classify it explicitly and route the
+repair to the owning stage. Do not introduce a new canonical term only in chat.
+
+The owning stage must:
+
+- preserve the current artifact as evidence and avoid wholesale rewrite unless
+  the artifact is explicitly superseded;
+- state the Stage Challenge Gate focus for this skill, such as proposal
+  problem/scope clarity, spec behavior/AC traceability, design implementation
+  mapping, task execution readiness, or evidence-stage claim validity;
+- classify material claims as `sourced`, `accepted`, `assumed`, `conflicting`,
+  `missing`, or `N/A`;
+- classify terminology conflicts and accepted canonical names with source or
+  context references;
+- repair only the claims that local/configured sources, accepted decisions, or
+  current evidence support;
+- ask at most one blocking question when the missing answer changes scope,
+  behavior, design, task order, or verification;
+- report `Stage artifact clarity: PASS | NEEDS_REPAIR | BLOCKED | WAIVED`
+  with owner, missing input, impact, next action, and downstream consumer.
+
+Examples:
+
+- unclear `proposal` routes to `proposal` for problem/scope/non-goal repair;
+- unclear `spec` routes to `spec` for FR/AC/scenario/source-trace repair;
+- unclear `design` routes to `design` for interface, ADR, data-flow, or control
+  traceability repair;
+- unclear `tasks` routes to `task` for executable checkbox, ownership,
+  dependency, source-alignment, and evidence-hook repair.
+
+## Context Recording Discipline
+
+ZSK treats `CONTEXT.md` as durable project language, not chat memory. When a
+Clarification Loop, artifact clarity pass, architecture review, stage repair, or
+task decomposition creates or sharpens terminology, naming, module/decomposition
+rationale, accepted clarification, or a load-bearing "call this X, not Y"
+decision, the owning skill must update the nearest `CONTEXT.md` before handoff.
+
+Context targets:
+
+- module-local language and decomposition decisions:
+  `.zsk/modules/{module}/CONTEXT.md`;
+- project-wide or cross-module language: `.zsk/docs/CONTEXT.md`;
+- reusable ZSK core language: the source repo `CONTEXT.md`.
+
+The update must separate accepted terms from rejected/ambiguous framings and
+state the downstream impact. If no context update is needed, the handoff records
+`Context update: N/A` with a short reason. A downstream stage must not rely on a
+term that only exists in chat.
+
+## Coding TDD Cycle Discipline
+
+`coding` uses vertical TDD, not horizontal batching. For each testable behavior
+or defect slice:
+
+1. Select one behavior from task, AC, issue, or accepted clarification.
+2. Write or update one public-interface behavior test or scenario expectation.
+3. Run that focused test and record RED evidence. If RED cannot be observed
+   because the harness, fixture, or dependency is unavailable, record the tool
+   gap before implementation.
+4. Implement the smallest code change that can make this behavior pass.
+5. Run the focused test again and record GREEN evidence before starting another
+   behavior.
+6. Refactor only while GREEN, then rerun the affected focused test.
+
+The coding handoff must list cycles separately. A final full-suite result is
+useful only after the vertical cycles; it must not replace per-behavior evidence.
+
+## Preproposal Team Simulation
+
+`preproposal` is one workflow-node with role lanes, not a set of standalone skills.
+
+Before lane work begins, the lead-integrator owns intake clarity. A one-sentence
+or vague requirement must be restated as known facts, inferred assumptions,
+source gaps, non-goals, and at most one blocking question. The lead must inspect
+available repo docs, code, `.zsk` sources, glossary, and decision records before
+asking the user. Every blocking question includes the recommended answer and
+tradeoff, and accepted clarification is recorded as fact, decision, assumption,
+or open question.
+
+- 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-source lanes own user journey, IA/navigation seeds, interaction handoff when triggered, interaction states, usability/accessibility risks, provider-backed source maps, and design-source needs during `preproposal`.
+- 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 +238,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 +288,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 +301,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 +340,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.