@captain_z/zsk-skills 1.8.3 → 1.8.5

package/README.md

@@ -2,20 +2,20 @@
 
 ZNorth Standard Kit 的可安装 skill 内容包。安装面现在只保留从根级 `skills/` 生成的 **core harness-first skills**；旧 `.best-practices/` 不再批量生成独立 installable skills，而是作为参考源按 skill 携带相关子集。
 
-包内共有 **23 颗 installable skills**，全部来自根级 `skills/`。
+包内共有 **24 颗 installable skills**，全部来自根级 `skills/`。
 
 ## 合规审查（ARCHITECTURE §4.4 硬指标）
 
 | 检查项                                                                                   | 结果    | 说明                                                  |
 | ---------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
-| 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 |
+| 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 行                                                                          | ✓ 23/23 | core 由 `lint:harness` 强制                           |
+| 单文件 ≤ 300 行                                                                          | ✓ 24/24 | core 由 `lint:harness` 强制                           |
 
 当前 `max-lines` 已由 `tools/lint-frontmatter.ts` 作为 error 强制；新增或修改 skill 不应超过 300 行。
 
@@ -36,10 +36,10 @@ Profile 是流程组合策略，不是新的 skill。Atomic skills 仍然平铺
 | --- | ---: | --- |
 | `zsk-entry` | 2 | 只装 `zskplan` / `zsk` 两个主入口，由它们按 harness 调度 |
 | `zsk-lite` | 11 | 小修、小项目、脚本、低风险任务 |
-| `zsk-sdlc` | 20 | 标准工程交付；需求、实现、审查、验证、验收、归档 |
-| `zsk-frontend` | 21 | UI/UX/browser-facing 交付；强化 demo、视觉证据、前端质量门禁 |
-| `zsk-enterprise` | 21 | 高治理交付；要求 deploy、验收、归档、审计证据 |
-| `sdlc-only` | 23 | 旧入口兼容；安装全部 core skills |
+| `zsk-sdlc` | 21 | 标准工程交付；需求、实现、审查、验证、验收、归档 |
+| `zsk-frontend` | 22 | UI/UX/browser-facing 交付；强化 demo、视觉证据、前端质量门禁 |
+| `zsk-enterprise` | 22 | 高治理交付；要求 deploy、验收、归档、审计证据 |
+| `sdlc-only` | 24 | 旧入口兼容；安装全部 core skills |
 
 ## Skill 搭配流程图
 
@@ -82,7 +82,7 @@ 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` | 非交互安装 11 颗常用 skills |
-| CI 安装标准 SDLC profile | `npx @captain_z/zsk add zsk-sdlc --target=~/.claude/skills --yes` | 非交互安装 20 颗标准 workflow 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,8 +113,8 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 
 | 领域              | skill 数 | 职责                                       |
 | ----------------- | -------- | ------------------------------------------ |
-| `skills/`         | 23       | harness-first 默认工作流入口               |
-| **总计**          | **23**   |                                            |
+| `skills/`         | 24       | harness-first 默认工作流入口               |
+| **总计**          | **24**   |                                            |
 
 ## 安装套件（bundles.yaml）
 
@@ -122,12 +122,12 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 | ------------------------------ | ------ | --------------------------------------------- |
 | `zsk-entry`                    | 2      | 只安装 ZSK / ZSK Plan 两个主入口 |
 | `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` |
+| `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: 24 skills -->
@@ -139,7 +139,7 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
 ### `<slug>/` — Core · harness-first 默认工作流入口 (24)
 
 - **`zskplan`**
-  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.
+  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.
@@ -154,7 +154,7 @@ Skills 负责更需要判断的部分：理解 SRS、PRD、API 契约、Figma/Mo
   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.
+  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.

package/acceptance/SKILL.md

@@ -82,8 +82,11 @@ This core skill is governed by the ZSK harness. Enforce these rules even when on
 - Constraint levels: hard requirements and triggered conditional requirements are blocking; advisory guidance may be skipped only with rationale and no broken hard/conditional gate.
 - Required outputs: every output declared in the skill I/O contract is mandatory unless recorded as evidence-backed N/A or BLOCKED with owner, impact, and next action.
 - Collaboration: ordinary stage skills own their declared outputs and handoff quality; workflow skills own route selection. Do not hardcode the next stage inside a stage skill.
+- Output Quality Check: every stage output must expose status, owner, source basis, blocking item links, and next action near the top of the artifact; route cross-stage gaps to their owning stage instead of running a generic grill.
+- Clarification Prelude: ask exactly one load-bearing question with a separate recommendation only after local sources cannot produce a safe expression; persist confirmed expressions through CLAR, the owning artifact, and required CONTEXT.md updates.
 - Dynamic state awareness: identify the active role/stage, project type, stack, runtime, domain, target users/market, and freshness-sensitive decisions before selecting practices or retrieval sources.
 - Filesystem boundaries: write ZSK-managed outputs only under the configured `.zsk` workspace paths.
+- Context recording: durable terminology, naming, decomposition, and load-bearing clarification decisions must update the nearest `CONTEXT.md`, or the handoff must record `Context update: N/A` with rationale.
 - Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
 - Learning authority: reusable ZSK core learning must target the canonical ZSK source repo `.zsk/learning/proposals/`; project-local learning may stay in the current project.
 
@@ -95,7 +98,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

@@ -84,6 +84,17 @@ This file is generated for the installed skill. Read it before executing this sk
 - Document mode: `decisionRecord`
 - Purpose: Record the accept/reject business decision and residual-risk ownership.
 
+## Output Quality Rubric
+
+- `output_goal`: Record the accept/reject business decision and residual-risk ownership.
+- `downstream_consumer`: Next legal ZSK stage or reviewer.
+- `required_inputs`: verify-report, demo-report, residual-risks, linked-issues
+- `required_outputs`: acceptance-decision, confirmed-doc-feedback, residual-risk-list
+- `must_answer_questions`: Is the verified work accepted, rejected, or conditionally accepted? / Which evidence and issues support the decision? / Who owns residual risks and documentation feedback?
+- `quality_checks`: Links verify report, demo evidence, accepted criteria, and residual risks. / Records documentation feedback or no-update rationale for confirmed learnings.
+- `anti_patterns`: Accepting without verification evidence. / Letting residual risks remain ownerless.
+- `stop_condition`: `Output Quality Check` is PASS, WAIVED with accepted risk, or BLOCKED/NEEDS_CLARIFICATION/NEEDS_REPAIR with owner, impact, and next action.
+
 ## Hard Requirements
 
 - Read the required inputs for the active skill, or stop as BLOCKED with owner, missing input, impact, and next action.
@@ -91,6 +102,11 @@ This file is generated for the installed skill. Read it before executing this sk
 - 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.
+- Every stage output must include a concise `Output Quality Check` near the top with fields in order: status, owner, source_basis, blocking_items, next_action, and optional waiver/updated_at.
+- When an existing stage artifact is present, the active skill must update its own Output Quality Check before downstream handoff: derive the check from that skill's responsibility, required inputs, required outputs, must-answer questions, quality checkpoints, current artifact, upstream sources, and downstream consumer; classify sourced, accepted, assumed, conflicting, missing, and N/A claims, then repair or block through the owning stage.
+- Keep Clarification Prelude skill-local: ask, repair, or block only on load-bearing questions the active skill owns; route upstream or downstream findings to the owning stage instead of absorbing another skill's responsibility.
+- Every Output Quality Check must align terminology against CONTEXT.md/CONTEXT-MAP.md when present, SYSTEM-SPEC.md, configured raw sources, current artifact identifiers, and code/component/API names when implementation-facing work is touched.
+- Record durable terminology, naming, decomposition, and load-bearing clarification decisions in the nearest CONTEXT.md, or write `Context update: N/A` with rationale.
 - 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.
@@ -104,6 +120,7 @@ This file is generated for the installed skill. Read it before executing this sk
 - When behavior is testable, define or consume a traceable test basis before claiming implementation, smoke, review, verify, or acceptance success.
 - When external facts, SDKs, APIs, regulations, market context, or dependency behavior are freshness-sensitive, retrieve current authoritative references or record why local sources are sufficient.
 - When an artifact becomes too large for one reviewable file, split it into `{stage}/index.md` plus linked child Markdown files while preserving the full stage contract.
+- When clarification, grilling, architecture review, artifact repair, or task decomposition introduces a term or naming decision future stages must reuse, update module-local or project-level CONTEXT.md before handoff.
 - When 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.
 
@@ -112,6 +129,7 @@ This file is generated for the installed skill. Read it before executing this sk
 - 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.
@@ -134,8 +152,12 @@ 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.
-- 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.
+- Names `Output Quality Check` status as PASS, NEEDS_CLARIFICATION, NEEDS_REPAIR, BLOCKED, or WAIVED when a stage artifact is produced, consumed, or improved.
+- Keeps Output Quality Check summary-level: status, owner, source basis, blocking item links, and next action only; long criteria output belongs in verbose evidence.
+- Runs or references the stage-entry quality gate before downstream handoff; gate assess maps Output Quality Check status instead of inventing a new quality judgment.
 - 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.
@@ -171,6 +193,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 Output Quality Check and Clarification Prelude.
+- Letting terminology, naming, or decomposition decisions live only in chat instead of CONTEXT.md.
+- Running stage-specific questioning without checking whether the artifact uses the same terms as upstream sources, downstream consumers, and implementation surfaces.
 - 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.
@@ -206,6 +232,7 @@ This file is generated for the installed skill. Read it before executing this sk
 ## Completion Checklist
 
 - Required outputs above are produced or explicitly blocked.
+- Output Quality Check is updated with status, owner, source basis, blocking item links, and next action.
 - Evidence is linked and reproducible.
 - Issues and indexes are updated when actionable findings exist.
 - Documentation Feedback is recorded when confirmed behavior changes or gaps are found.

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

@@ -5,8 +5,10 @@ Default project paths:
 - `.zsk/`: the only default ZSK-managed workspace root.
 - `.zsk/docs/`: project-level docs such as `SYSTEM-SPEC.md` and `PROJECT-CONFIG.md`.
 - `.zsk/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 product, roadmap, UX, and design-source readiness resources here only when they are labeled with provenance, review checkpoint status, assumptions, and blockers.
+- `.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.
@@ -19,6 +21,21 @@ Default project paths:
 
 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:
@@ -45,4 +62,4 @@ This rule applies to every underscore module directory, not only `_issues`. For
 
 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.
+`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

@@ -31,6 +31,7 @@ Indexes are part of the contract:
 | Defect | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `DEFECT` | Formal QA |
 | Verify Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `VER` | Fix verification |
 | Acceptance Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `ACC` | Business/product acceptance |
+| Clarification Issue | `.zsk/modules/{module}/_issues/{prefix}-0001-slug/` | `CLAR` | Clarification Prelude |
 
 Stage directories such as `.zsk/modules/{module}/_issues/demo/index.md` may exist as stage views or evidence buckets. They are not the authoritative status indexes.
 
@@ -58,6 +59,41 @@ If `paths.issues` is customized, it must still stay under `.zsk/` and is reserve
 - `regression_guard`
 - `confirmed_at` or `confirmation_required`
 
+Clarification issues extend the common fields with:
+
+- `owning_stage`
+- `owning_skill`
+- `question`
+- `recommended_answer`
+- `accepted_answer`
+- `recommendation_delta`
+- `impact_if_unconfirmed`
+- `confirmation_required`
+- `clarification_status`
+- `updated_artifacts`
+- `source_basis`
+
+`recommended_answer` stores the recommendation exactly as shown to the user; do
+not rewrite it after the user answers. `accepted_answer` stores the final
+confirmed expression. If the accepted expression differs from the recommendation,
+record `recommendation_delta` so downstream skills do not revert the user's
+decision back to the recommendation.
+
+Clarification status is a strict state machine:
+
+- `pending_question`: one load-bearing question is ready to ask.
+- `pending_expression`: the user answered and the skill must present or refine
+  `待写入确认表达：`.
+- `confirmed`: the user accepted the expression, but it is not yet written into
+  the owning artifacts.
+- `applied`: the expression was written into the `CLAR`, owning stage artifact,
+  and required `CONTEXT.md` target.
+- `closed`: the smallest useful gate validation passed after application.
+
+`confirmed` is not enough to continue downstream. Gate/dispatch may resume only
+after the `CLAR` reaches `applied`, and closure requires linked validation
+evidence.
+
 ## Severity
 
 - `P0`: blocks core path, data safety, security, or test handoff.

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

@@ -54,12 +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` | 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` |
+| `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, source basis, terminology basis, decision request | Detailed behavior, architecture, task breakdown, implementation | When `proposal.md` is missing, synthesizes it from module-linked `.zsk/raws/**`, module context, and accepted terms; 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, 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` |
+| `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, 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` |
+| `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` |
@@ -107,13 +107,128 @@ 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.
 
+## Output Quality Check And Clarification Prelude
+
+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.
+
+`Output Quality Check` is the public quality entrypoint for the stage artifact,
+not a second gate log. The active skill must keep a concise block near the top of
+the artifact with `status`, `owner`, `source_basis`, `blocking_items`, and
+`next_action`. It auto-identifies what to check 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.
+
+`Clarification Prelude` is the interactive path used only when the check finds a
+load-bearing decision that local sources cannot resolve. It asks one question,
+shows one separate recommendation, turns the answer into `待写入确认表达：`, and
+waits for confirmation before writing to the `CLAR`, owning artifact, and
+necessary `CONTEXT.md`. It is not a generic grilling session and it is not gate
+evidence.
+
+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 `Output Quality Check` status as `PASS`, `NEEDS_CLARIFICATION`,
+  `NEEDS_REPAIR`, `BLOCKED`, or `WAIVED`;
+- keep `blocking_items` summary-level and link to `CLAR`, issues, stage body, or
+  verbose evidence for details;
+- 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 through `CLAR` when the missing answer
+  changes scope, behavior, design, task order, acceptance, terminology, or
+  verification;
+- write confirmed expressions back to the owning stage artifact and nearest
+  `CONTEXT.md` when they create durable language or module boundaries;
+- report 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 Prelude, Output Quality Check, 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-specialist lanes own user journey, IA/navigation seeds, interaction states, usability/accessibility risks, and design-source needs.
+- 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.
 

package/acceptance/harness/constraints/source-of-truth.md

@@ -3,18 +3,24 @@
 Resource priority is:
 
 1. explicit project `.zsk/config.yaml`
-2. module docs and stage artifacts under `.zsk/modules/{module}/`
-3. raw source snapshots under `.zsk/raws/`
+2. raw source snapshots under `.zsk/raws/`
+3. module docs and stage artifacts under `.zsk/modules/{module}/`
 4. code and runtime evidence
 5. user-provided clarification
 
 When sources conflict, the stage artifact must record the conflict instead of silently choosing the most convenient value.
 
+`.zsk/raws/**` is the reusable source library for project knowledge and terminology. Requirements, SRS, PRD, customer notes, issue exports, market research, design notes, and provider captures are raw resource categories inside that library, not mandatory separate filenames. A missing module `proposal.md` is not a missing proposal input; the proposal skill must synthesize or repair the proposal from module-linked raw sources, module context, and accepted project terms when those sources are sufficient.
+
 ## Strict Fact Source Discipline
 
 - Requirements, behavior, scenario order, acceptance criteria, and test expectations must trace back to PRD/SRS, spec, design, task, raw source, code, runtime evidence, or user clarification.
 - Do not invent missing requirements, UI behavior, business rules, edge cases, or test expectations from preference or convention.
+- Do not ask for terminology, target users, module boundaries, or product goals until `.zsk/raws/**`, raw manifest/index, module context, and accepted `CONTEXT.md` terms have been checked.
 - If the facts are incomplete, ambiguous, conflicting, or insufficient to decide, stop the stage decision and ask for clarification after summarizing the known sources and tradeoffs.
+- For vague intake or stage-output ambiguity, ask only after checking local and configured sources; ask one blocking question at a time and put the recommended answer in a separate recommendation block.
+- If an existing stage artifact is unclear, preserve it as a source instead of discarding it. The owning stage must update its `Output Quality Check`, derive the check from its active skill contract, and classify each important claim as sourced, accepted, assumed, conflicting, or missing before repairing or blocking.
+- If the missing decision is load-bearing and cannot be resolved from sources, create exactly one current `CLAR` through Clarification Prelude. Do not batch-persist speculative questions.
 - If asking is blocked, record a resource gap or issue instead of silently choosing a path.
 - Best practices may shape implementation, but they cannot override project facts or accepted design documents.
 - Before applying a role, run dynamic state awareness: identify the current stage, role, project type, domain, language, framework, SDKs, runtime tools, target market, and freshness-sensitive decisions from local config, module docs, manifests, lockfiles, imports, raw sources, and existing evidence.

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

@@ -14,24 +14,78 @@ The harness computes gate status. Skills may propose outputs and record evidence
 
 - For testable behavior changes, `task` should define the test/scenario hook before `coding`.
 - `coding` should start by creating or updating the targeted test/scenario when one does not already cover the behavior.
+- `coding` must run vertical TDD cycles: one behavior -> one failing test or changed test expectation -> minimal implementation -> passing evidence -> next behavior. Do not batch all tests first or all implementation first.
+- Each cycle records behavior id, source task/AC/issue, RED evidence or an explicit reason RED cannot be observed, GREEN evidence, changed files, and refactor evidence when a refactor occurs.
 - `smoke`, `review`, and `verify` must reject tests that cannot be traced to PRD/SRS, spec/design, task, issue, or accepted user clarification.
 - If the test contract is unclear, the stage is `blocked` until the uncertainty is clarified or recorded as a resource gap.
 
 ## Stage Entry Quality Gate
 
 - 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.
+- The assessment is a lightweight consistency check over the stage document's `Output Quality Check`; default evidence is limited to `summary.json` and `summary.md` with status, blocker count, next action, and artifact links.
+- Detailed scoring, criteria rows, trace output, and long diagnostics are generated only for an explicit verbose/debug run.
+- Gate criteria follow the harness constraint levels only to validate consistency: 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.
+- For `proposal`, the current module `proposal.md` is the stage output, not an entry prerequisite. Gate assessment may use project rules and the raw source manifest/library as the entry basis; absence of the current proposal artifact routes to initial draft generation instead of blocking by itself.
 - 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.
+- If a stage document exists but lacks `Output Quality Check`, `gate assess` must return a minimal `BLOCKED` result that routes back to the owning stage skill. It must not synthesize a quality judgment or emit a large practice log on behalf of the stage.
+
+## Output Quality Check
+
+- `Output Quality Check` is the single public quality status block for every stage-owned artifact: preproposal raw pack, proposal, spec, design, tasks, implementation handoff, smoke/demo/review/ready/verify reports, acceptance, archive, issue, and learning outputs.
+- Every stage skill's stop condition is high-quality output, not file existence or a passing command. The stage output is complete only when its `Output Quality Check` satisfies that skill's rubric and downstream consumer.
+- The block must appear near the top of the stage document, after title/summary and before the main body.
+- The block uses a stable Markdown template with this minimum field order: `status`, `owner`, `source_basis`, `blocking_items`, `next_action`. Optional fields are `waiver` and `updated_at`.
+- `source_basis` is a compact link list to upstream artifacts, raw sources, CLAR issues, other issue records, evidence, or code facts. It is not a long citation log.
+- `blocking_items` is a compact navigation list: item type, short title, link, and status. Detailed explanation belongs in the linked `CLAR`, issue, stage body, or verbose evidence.
+- Status values are exactly `PASS`, `NEEDS_CLARIFICATION`, `NEEDS_REPAIR`, `BLOCKED`, and `WAIVED`.
+- Status mapping is deterministic: `PASS -> READY`, `NEEDS_CLARIFICATION -> NEEDS_CONFIRMATION`, `NEEDS_REPAIR -> BLOCKED`, `BLOCKED -> BLOCKED`, and `WAIVED -> WAIVED`.
+- `PASS` means the current stage output satisfies the stage rubric stop condition and has no downstream-blocking clarification, repair, or blocker.
+- `NEEDS_CLARIFICATION` means a load-bearing user confirmation is missing and the owning stage must run Clarification Prelude for the linked `CLAR`.
+- `NEEDS_REPAIR` means local/configured sources are sufficient and the owning stage must repair the document without asking the user.
+- `BLOCKED` means a required source, tool, permission, or upstream artifact is missing so the skill can neither repair nor safely clarify. It must state blocker, owner, impact, and unblock condition.
+- `WAIVED` is allowed only for explicit human acceptance of non-blocking quality risk. It must record risk, impact, acceptor/time, and follow-up. Blocking gaps cannot be waived.
+- Each stage's output quality rubric lives in `harness/workflow/skill-quality-standards.yaml` with a common structure: `output_goal`, `downstream_consumer`, `required_inputs`, `required_outputs`, `must_answer_questions`, `quality_checks`, `anti_patterns`, and `stop_condition`.
+- The internal check method may challenge the active artifact against the active skill contract: responsibility, required inputs, required outputs, must-answer questions, quality checkpoints, current artifact, upstream sources, and downstream consumer. This is an implementation method of `Output Quality Check`, not a separate public gate concept.
+- The check must apply the active skill's bundled related best-practice
+  files and quality standards when their domain is touched. If the bundled
+  references are missing, stale, too generic, version-sensitive, or not matched
+  to the current stack/domain, record the gap and retrieve official/current
+  references before issuing a best-practice challenge.
+- The check must align terminology against project sources before asking
+  or repairing: `CONTEXT.md` / `CONTEXT-MAP.md` when present, `SYSTEM-SPEC.md`,
+  configured raw sources, current stage artifact identifiers, and existing
+  code/component/API names when the skill touches implementation-facing work.
+  Conflicting or overloaded terms must be classified as conflicting/missing and
+  routed to the owning stage instead of silently renaming them.
+- The check must classify important claims as sourced, accepted, assumed, conflicting, missing, or N/A; it must name downstream consumer, required outputs, source links, blockers, and next action.
+- The owning stage may patch or split its own artifact when local/configured sources support the repair. If the missing fact belongs to an upstream stage, record upstream feedback or route to that stage.
+- Durable terminology, naming, decomposition rationale, and load-bearing clarification decisions found during the check must update the nearest `CONTEXT.md`, or the handoff must record `Context update: N/A` with rationale.
+
+## Clarification Prelude
+
+- `Clarification Prelude` runs before gate/dispatch when a stage skill needs user confirmation for a load-bearing decision. It is the interactive clarification layer for module stage output quality; it is not gate evidence and not a generic grill.
+- First execution of a stage skill uses `initial-draft`: when the owning stage artifact does not exist, the skill generates an initial output from confirmed upstream artifacts. For `proposal`, confirmed upstream artifacts include `.zsk/raws/manifest.json`, `.zsk/raws/index.md` when present, module-linked `.zsk/raws/**`, module context, and accepted `CONTEXT.md` terminology. If it hits a source-undiscoverable decision that would change the stage direction, it creates one `CLAR` and asks.
+- Later executions use `clarify/refine`: when the owning stage artifact exists, the skill processes exactly one clarification unit per run, either confirming/applying one `pending_expression` or asking the single highest-impact `pending_question`.
+- After `initial-draft`, the skill performs one `clarify/refine` scan before gate/dispatch. If a key ambiguity remains, it asks one question and stops. If not, it updates `Output Quality Check` and only then proceeds to minimal gate/dispatch.
+- Candidate questions discovered during scanning are not persisted in bulk. Create a `CLAR` only when that question is about to be shown to the user.
+- A `CLAR` is used only for load-bearing questions: module boundary, stage conclusion, interface/behavior contract, task order, acceptance standard, terminology, or naming. Ordinary open questions are non-blocking follow-up items.
+- Before asking, the skill must read local sources first: module artifacts, `CONTEXT.md`, raw sources, existing issues, and code facts. It asks only when those sources cannot produce a safe expression or when sources conflict.
+- If sources conflict, ask the user to choose one conflict decision; do not silently merge contradictory authorities.
+- User-facing format is fixed: a `问题：` block containing only one clear question, then a separate `推荐：` block containing only the recommended answer.
+- After the user answers, the skill writes a separate `待写入确认表达：` block. If the user replies `ok`, `OK`, `是`, `对`, or `好`, treat it as confirmation. If the user corrects it, refine the same expression instead of moving to a new question.
+- A confirmed expression must be clear enough to write into the owning stage artifact: terminology consistent, stage/module boundary explicit, decision and non-goal clear, downstream stage directly reusable, and confirmation source traceable.
+- Confirmation is not chat memory. The owning skill writes the accepted expression to the linked `CLAR`, the owning stage artifact, and the nearest `CONTEXT.md` when the decision creates reusable terminology, naming, or module boundaries.
+- After applying one confirmed expression, the current run performs the smallest useful gate validation and stops. The next clarification belongs to the next execution of the same owning stage skill.
 
 ## Preproposal Checkpoint Gate
 
 - Use `preproposal` when a brief request lacks reviewed product direction, roadmap/decomposition, UX/design-readiness, or source-readiness material for `proposal`.
+- Intake clarity runs before product work. It must inspect available sources first, separate known facts from inferred assumptions and gaps, and ask at most one blocking question with a recommended answer when the answer would materially change direction.
 - 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.
+- UX/design-readiness checkpoint must pass before readiness handoff. It reviews user journey, IA/navigation seeds, interaction handoff when triggered, interaction states, accessibility/usability risks, source maps, 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.
@@ -87,10 +141,10 @@ The harness computes gate status. Skills may propose outputs and record evidence
 
 - `blocked`: required resource or evidence is missing.
 - `ready`: resources are present and current enough to run the stage.
+- `needs-confirmation`: an `Output Quality Check` has `NEEDS_CLARIFICATION` or a linked `CLAR` requires user confirmation.
 - `passed`: output exists and gate checks passed.
 - `failed`: stage ran but produced blocking findings.
 - `paused`: resumable session state exists, used by interruptible demo.
 - `terminated`: session intentionally stopped; follow-up owner is required.
-- `needs-confirmation`: required artifacts exist, but quality score/gaps require human decision before proceeding.
 - `waived`: explicit human risk acceptance allows progression despite non-blocking quality gaps; waiver evidence must be linked.
 - `stale`: a dispatched packet missed its heartbeat/deadline and must fall back or be re-emitted.

package/acceptance/harness/profiles/frontend.yaml

@@ -1,9 +1,9 @@
 name: zsk-frontend
-description: Frontend delivery profile with design, demo, and visual quality gates.
+description: Frontend delivery profile with code design, demo, and visual quality gates.
 extends: zsk-sdlc
 purpose: >
   Use for UI, UX, visual, interaction, accessibility, and browser-facing work
-  where design handoff, demo evidence, and frontend quality checks matter.
+  where preproposal readiness, demo evidence, and frontend quality checks matter.
 
 stages:
   required:
@@ -82,7 +82,6 @@ strictness:
 
 bestPractices:
   required:
-    - design-handoff.md
     - frontend.md
     - quality.md
   recommended: