@captain_z/zsk-skills 1.8.4 → 1.8.6

package/acceptance/SKILL.md

@@ -82,7 +82,8 @@ 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.
-- 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.
+- 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.

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,9 +102,10 @@ 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.
-- 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.
+- 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.
@@ -143,9 +155,9 @@ This file is generated for the installed skill. Read it before executing this sk
 - 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.
+- 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.
@@ -182,7 +194,7 @@ This file is generated for the installed skill. Read it before executing this sk
 - 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.
+- 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.
@@ -220,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/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

@@ -55,7 +55,7 @@ Each skill owns one stage contract. Workflow skills may route or schedule work,
 | --- | --- | --- | --- |
 | `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` |
+| `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` | 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 |
@@ -107,7 +107,7 @@ 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
+## 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
@@ -115,13 +115,22 @@ 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,
+`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.
@@ -141,19 +150,22 @@ 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;
+- 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 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.
+- 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:
 
@@ -167,7 +179,7 @@ Examples:
 ## 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
+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.

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

@@ -3,20 +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, ask only after checking local and configured sources; ask one blocking question at a time and include the recommended answer plus tradeoff.
-- If an existing stage artifact is unclear, preserve it as a source instead of discarding it. The owning stage must run its own Stage Challenge Gate, derive the challenge focus from its active skill contract, and classify each important claim as sourced, accepted, assumed, conflicting, or missing before repairing or blocking.
+- 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

@@ -22,32 +22,62 @@ The harness computes gate status. Skills may propose outputs and record evidence
 ## 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.
-
-## Stage Artifact Clarity Gate
-
-- This gate applies to 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.
-- When the artifact already exists but is unclear, incomplete, contradictory, placeholder-like, or too weak for its downstream consumer, the workflow must route to the owning stage for that skill's Stage Challenge Gate instead of skipping ahead, discarding the artifact, running a generic grill, or silently rewriting it from another stage.
-- The clarity pass must derive its challenge focus from the active skill contract: responsibility, required inputs, required outputs, must-answer questions, quality checkpoints, current artifact, upstream sources, and downstream consumer.
-- The clarity pass must apply the active skill's bundled related best-practice
+- 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 clarity pass must align terminology against project sources before asking
+- 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 clarity pass must classify important claims as sourced, accepted, assumed, conflicting, missing, or N/A; it must name the skill-local challenge focus, 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; if only one answer blocks direction, ask one blocking question with a recommended answer and tradeoff.
-- Durable terminology, naming, decomposition rationale, and load-bearing clarification decisions found during the clarity pass must update the nearest `CONTEXT.md`, or the handoff must record `Context update: N/A` with rationale.
-- Clarity status is `PASS`, `NEEDS_REPAIR`, `BLOCKED`, or `WAIVED`. `NEEDS_REPAIR` cannot progress downstream without an explicit risk acceptance; `BLOCKED` must include owner, missing input, impact, and next action.
+- 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
 
@@ -111,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/workflow/skill-io-contract.yaml

@@ -28,21 +28,23 @@ principles:
     and how the evidence changes the recommendation.
   - "Do not decide from uncertainty: summarize conflicting or missing facts and
     ask, or record a resource gap."
-  - For vague intake, answer discoverable questions from local sources first,
-    then ask one blocking question at a time with a recommended answer and
-    tradeoff.
+  - For vague intake or stage-output ambiguity, answer discoverable questions
+    from local sources first, then ask one blocking question at a time with a
+    separate recommended answer.
   - "TDD first for testable behavior: tests and scenarios must be accurate and
     traceable to PRD/SRS, spec/design, task, issue, or accepted clarification."
+  - Each stage skill owns an `Output Quality Check` near the top of its output.
+    The check states status, owner, source basis, blocking items, and next
+    action before gate/dispatch.
   - When an existing stage artifact is unclear, incomplete, contradictory, or
-    too weak for its downstream consumer, route to the owning stage's
-    skill-local Stage Challenge Gate before downstream work; preserve the
-    artifact, derive challenge focus from the active skill's contract, classify
-    gaps, repair what sources support, and ask only one blocking question when
-    needed.
-  - "A Stage Challenge Gate is not a generic grill: proposal challenges problem
-    and scope, spec challenges behavior contracts, design challenges
-    implementation mapping, task challenges execution readiness, and later
-    evidence stages challenge the claim they own."
+    too weak for its downstream consumer, route to the owning stage's Output
+    Quality Check and Clarification Prelude before downstream work; preserve the
+    artifact, derive the check from the active skill's contract, classify gaps,
+    repair what sources support, and ask only one blocking question when needed.
+  - "Clarification Prelude is not a generic grill: first execution may create an
+    initial draft from confirmed upstream artifacts, while later executions
+    refine one clarification unit at a time until the stage output is directly
+    usable downstream."
   - When clarification, grilling, architecture review, stage repair, or task
     decomposition creates or sharpens project/module terminology, naming,
     decomposition rationale, or load-bearing decisions, update the nearest

package/acceptance/harness/workflow/skill-quality-standards.yaml

@@ -74,6 +74,15 @@ framework:
       apply, cites the evidence or project rule, and does not hide a missing
       mandatory input.
 defaults:
+  outputQualityRubricFields:
+    - output_goal
+    - downstream_consumer
+    - required_inputs
+    - required_outputs
+    - must_answer_questions
+    - quality_checks
+    - anti_patterns
+    - stop_condition
   hardRequirements:
     - Read the required inputs for the active skill, or stop as BLOCKED with
       owner, missing input, impact, and next action.
@@ -85,17 +94,21 @@ defaults:
       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,
+    - "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 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
+    - "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.
@@ -162,13 +175,15 @@ defaults:
       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.
+    - 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;
-      below-threshold but non-blocking gaps require explicit risk acceptance
-      instead of silent progression.
+      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."
@@ -197,7 +212,7 @@ defaults:
     - 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.
+      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

package/acceptance/harness/workflow/stage-contracts.yaml

@@ -9,9 +9,9 @@ contracts:
     optionalResources: [target-module, module-docs, module-context, project-config, system-spec, existing-product-design, existing-roadmap, existing-ux-design, design-sources, market-research, user-research, stakeholder-notes, resource-manifest]
     outputs: [preproposal-raw-pack, module-scoped-raw-pack-when-targeted, intake-clarity-brief, accepted-clarifications, product-brief, roadmap-decomposition, ux-flow-seeds, interaction-handoff-when-triggered, module-scoped-interaction-handoff-when-targeted, design-source-needs, design-source-map-when-triggered, assumptions-ledger, risk-ledger, scenario-seeds, checkpoint-review-evidence, readiness-handoff]
   proposal:
-    requiredResources: [project-config, system-spec, requirements]
-    optionalResources: [reviewed-preproposal-raw-pack, market-research, competitor-research, pricing-research, user-personas, user-research, business-model, regulatory-sources]
-    outputs: [project-rules-gate, proposal]
+    requiredResources: [project-config, system-spec, resource-manifest, raw-source-library]
+    optionalResources: [module-source-map, module-context, reviewed-preproposal-raw-pack, requirements, customer-notes, issue-exports, market-research, competitor-research, pricing-research, user-personas, user-research, business-model, regulatory-sources]
+    outputs: [project-rules-gate, source-basis, terminology-basis, proposal]
   spec:
     requiredResources: [project-config, system-spec, requirements, proposal]
     optionalResources: [market-research, user-personas, pricing-research, competitor-research]
@@ -45,8 +45,8 @@ contracts:
     outputs: [deployment, runtime-evidence]
   demo:
     requiredResources: [spec, design, deployment, playwright-case-skeletons]
-    optionalResources: [api-contracts, design-sources, design-assets, test-cases]
-    outputs: [demo-outline, demo-report, demo-issues, demo-scenarios, synthesized-playwright-cases]
+    optionalResources: [api-contracts, design-sources, design-assets, test-cases, demo-auth-state]
+    outputs: [demo-outline, demo-report, demo-issues, demo-scenarios, demo-auth-state, synthesized-playwright-cases]
   defect:
     requiredResources: [demo-report]
     outputs: [defects]

package/archive/SKILL.md

@@ -77,7 +77,8 @@ 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.
-- 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.
+- 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.

package/archive/harness/THIS_SKILL.md

@@ -86,6 +86,17 @@ This file is generated for the installed skill. Read it before executing this sk
 - Document mode: `decisionRecord`
 - Purpose: Close the iteration by preserving artifacts, decisions, issues, and learning proposals.
 
+## Output Quality Rubric
+
+- `output_goal`: Close the iteration by preserving artifacts, decisions, issues, and learning proposals.
+- `downstream_consumer`: Next legal ZSK stage or reviewer.
+- `required_inputs`: acceptance-decision, final-artifacts, closed-issues, learning-candidates
+- `required_outputs`: archive-record, learning-proposals, release-notes
+- `must_answer_questions`: What was delivered, where are final artifacts, and which issues changed state? / What decisions should future agents not re-litigate? / Which reusable gaps deserve learning proposals?
+- `quality_checks`: Indexes final artifacts, closed/open issues, evidence, decisions, and learning candidates. / Distinguishes accepted behavior from future improvement ideas.
+- `anti_patterns`: Archiving chat summaries instead of durable artifact links. / Promoting one-off preferences into core rules without review.
+- `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.
@@ -93,9 +104,10 @@ 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.
-- 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.
+- 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.
 - Index final artifacts, accepted/rejected decisions, closed/open issues, evidence, residual risks, and learning candidates.
@@ -145,9 +157,9 @@ This file is generated for the installed skill. Read it before executing this sk
 - 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.
+- 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.
 - Indexes final artifacts, closed/open issues, evidence, decisions, and learning candidates.
@@ -186,7 +198,7 @@ This file is generated for the installed skill. Read it before executing this sk
 - 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.
+- 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.
@@ -225,6 +237,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.