@captain_z/zsk-skills 1.8.2 → 1.8.4

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

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

package/acceptance/harness/profiles/enterprise.yaml

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

package/acceptance/harness/profiles/frontend.yaml

@@ -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:
@@ -24,6 +24,7 @@ stages:
     - acceptance
     - archive
   optional:
+    - preproposal
     - deploy
     - defect
   sideChannel:
@@ -48,6 +49,10 @@ flow:
     - acceptance
     - archive
   optionalInsertions:
+    preproposal:
+      after: prepare
+      before: proposal
+      when: A UI/UX request lacks reviewed product direction, roadmap/decomposition, UX flows, or design-source readiness.
     deploy:
       after: commit
       before: ready
@@ -77,7 +82,6 @@ strictness:
 
 bestPractices:
   required:
-    - design-handoff.md
     - frontend.md
     - quality.md
   recommended:

package/acceptance/harness/profiles/sdlc.yaml

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

package/acceptance/harness/workflow/completion-contract.yaml

@@ -1,16 +1,17 @@
 version: 1
 defaults:
-  required: [artifact, evidence, issue_sync, documentation_feedback]
+  required: [artifact, evidence, issue_sync, documentation_feedback, context_record]
   rules:
     artifact: "Every skill run must declare produced artifacts and write them to project-template paths, not only to chat."
     evidence: "Every pass/fail or completion claim must link local evidence."
     issue_sync: "Actionable findings must classify scope, update the concrete issue in module-private or shared/global/public storage, and refresh module/global issue indexes."
     documentation_feedback: "Confirmed learnings must update spec/design/task docs or record a no-update rationale."
+    context_record: "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."
     execution: "Completion work may be done by a skill-local script or by the agent's normal file-editing tools, but the harness contract decides the required outputs."
     stage_gate: "Downstream progression requires a recorded gate assessment or explicit N/A rationale; non-blocking quality gaps need risk acceptance before continuing."
     durable_dispatch: "Dispatched lanes must leave a durable ledger and packet statuses; stale or timed-out lanes require fallback evidence before completion."
   scopeRouting:
-    moduleFinal: ".zsk/modules/{module}/{stage}.md"
+    moduleFinal: ".zsk/modules/{module}/{stage}.md; proposal/spec/design/tasks may upgrade to .zsk/modules/{module}/{stage}/index.md when the stage artifact needs split child docs"
     modulePrivate:
       issues: ".zsk/modules/{module}/_issues/"
       evidence: ".zsk/modules/{module}/_evidence/"
@@ -23,6 +24,11 @@ defaults:
       issues: ".zsk/issues/global/"
       evidence: ".zsk/evidence/global/"
       playwright: ".zsk/playwright/global/"
+      context: ".zsk/docs/CONTEXT.md"
+    context:
+      module: ".zsk/modules/{module}/CONTEXT.md"
+      project: ".zsk/docs/CONTEXT.md"
+      zskCore: "CONTEXT.md in the canonical ZSK source checkout"
     public:
       issues: ".zsk/issues/public/"
       evidence: ".zsk/evidence/public/"
@@ -40,27 +46,53 @@ outputs:
       - ".zsk/raws/manifest.json"
       - ".zsk/docs/SYSTEM-SPEC.md"
     feedbackTargets: [".zsk/docs/SYSTEM-SPEC.md", ".zsk/config.yaml"]
+  preproposal:
+    artifacts:
+      - ".zsk/raws/prepare/product/{topic}/product-brief.md"
+      - ".zsk/raws/prepare/product/{topic}/roadmap.md"
+      - ".zsk/raws/prepare/ux/{topic}/ux-readiness.md"
+      - ".zsk/raws/prepare/ux/{topic}/interaction-handoff.md when UI, UX, or design-source interaction is triggered"
+      - ".zsk/raws/prepare/ux/{module}/interaction-handoff.md when a target module and UI, UX, or design-source interaction are triggered"
+      - ".zsk/raws/prepare/design/{topic}/design-source-needs.md"
+      - ".zsk/raws/prepare/design/{topic}/design-source-map.md when provider-backed design sources such as Figma are used"
+      - ".zsk/raws/prepare/design/{module}/design-source-map.md when a target module uses provider-backed design sources such as Figma"
+      - ".zsk/evidence/preproposal/{run}/checkpoint-product-review.md"
+      - ".zsk/evidence/preproposal/{run}/checkpoint-roadmap-review.md"
+      - ".zsk/evidence/preproposal/{run}/checkpoint-ux-review.md"
+      - ".zsk/evidence/preproposal/{run}/checkpoint-interaction-review.md when interaction handoff is triggered"
+      - ".zsk/evidence/preproposal/{run}/readiness-review.md"
+    feedbackTargets: [".zsk/raws/manifest.json", ".zsk/raws/index.md", ".zsk/evidence/preproposal/{run}/readiness-review.md"]
   proposal:
     artifacts:
       - ".zsk/modules/{module}/proposal.md"
-    feedbackTargets: [".zsk/modules/{module}/proposal.md"]
+      - ".zsk/modules/{module}/proposal/index.md when split child docs are required"
+    feedbackTargets: [".zsk/modules/{module}/proposal.md", ".zsk/modules/{module}/proposal/index.md"]
   spec:
     artifacts:
       - ".zsk/modules/{module}/spec.md"
-    feedbackTargets: [".zsk/modules/{module}/spec.md", ".zsk/docs/SYSTEM-SPEC.md"]
+      - ".zsk/modules/{module}/spec/index.md when split child docs are required"
+    feedbackTargets: [".zsk/modules/{module}/spec.md", ".zsk/modules/{module}/spec/index.md", ".zsk/docs/SYSTEM-SPEC.md"]
   design:
     artifacts:
       - ".zsk/modules/{module}/design.md"
-    feedbackTargets: [".zsk/modules/{module}/design.md"]
+      - ".zsk/modules/{module}/design/index.md when split child docs are required"
+    feedbackTargets: [".zsk/modules/{module}/design.md", ".zsk/modules/{module}/design/index.md"]
   task:
     artifacts:
       - ".zsk/modules/{module}/tasks.md"
+      - ".zsk/modules/{module}/tasks/index.md when split child docs are required"
       - ".zsk/modules/{module}/_playwright/specs/"
-    feedbackTargets: [".zsk/modules/{module}/tasks.md", ".zsk/modules/{module}/design.md"]
+    feedbackTargets: [".zsk/modules/{module}/tasks.md", ".zsk/modules/{module}/tasks/index.md", ".zsk/modules/{module}/design.md", ".zsk/modules/{module}/design/index.md"]
   coding:
     artifacts:
       - "implementation files"
     feedbackTargets: [".zsk/modules/{module}/tasks.md"]
+  fix:
+    artifacts:
+      - ".zsk/modules/{module}/_issues/"
+      - ".zsk/issues/{shared|global|public}/"
+      - "implementation files or no-code blocker rationale"
+    feedbackTargets: [".zsk/modules/{module}/tasks.md", ".zsk/modules/{module}/review.md", ".zsk/modules/{module}/verify.md"]
   smoke:
     artifacts:
       - ".zsk/modules/{module}/smoke.md"
@@ -70,7 +102,9 @@ outputs:
     artifacts:
       - ".zsk/modules/{module}/review.md"
       - ".zsk/modules/{module}/_issues/"
-    feedbackTargets: [".zsk/modules/{module}/review.md", ".zsk/modules/{module}/design.md", ".zsk/modules/{module}/tasks.md"]
+      - ".zsk/evidence/preproposal/{run}/checkpoint-*.md when reviewing preproposal checkpoints"
+      - ".zsk/evidence/{shared|global|public}/review/{run}/ when reviewing explicit shared/global/public targets"
+    feedbackTargets: [".zsk/modules/{module}/review.md", ".zsk/modules/{module}/design.md", ".zsk/modules/{module}/tasks.md", ".zsk/evidence/preproposal/{run}/readiness-review.md"]
   commit:
     artifacts:
       - ".zsk/modules/{module}/commit.md"

package/acceptance/harness/workflow/skill-io-contract.yaml

@@ -28,8 +28,29 @@ 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.
   - "TDD first for testable behavior: tests and scenarios must be accurate and
     traceable to PRD/SRS, spec/design, task, issue, or accepted clarification."
+  - 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."
+  - 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
+    `CONTEXT.md` or record an evidence-backed no-update rationale.
+  - "For coding, use vertical TDD cycles for testable behavior: one behavior,
+    one failing test or changed test expectation, minimal implementation,
+    passing evidence, then the next behavior. Do not write all tests first and
+    then all code."
   - Stage skills own their declared outputs and handoff quality; workflow skills
     own route selection. Every handoff must preserve upstream/downstream
     consistency instead of relying on chat memory.

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

@@ -3,10 +3,11 @@ framework:
   intent: Make every ZSK stage produce a decision-grade document, not a chat
     summary or empty template.
   industryAnchors:
-    - "Diataxis: choose the document mode by reader need: task guidance,
-      reference, explanation, or learning."
-    - "Developer documentation style guides: optimize for the reader, clarity,
-      consistency, active language, and project-specific terminology."
+    - "Diataxis (https://diataxis.fr/): choose document mode by reader need:
+      task guidance, reference, explanation, or learning."
+    - "Google developer documentation style guide
+      (https://developers.google.com/style): optimize for reader clarity,
+      consistency, active language, examples, and project-specific terminology."
     - "Definition of Done: completion requires shared, visible, measurable
       quality criteria."
     - "Review workflows: a stage is not complete until another reader can
@@ -14,16 +15,44 @@ framework:
     - "ISO/IEC/IEEE 12207 and 15288: lifecycle coverage should be method-neutral
       and accepted by equivalent artifacts or control points only when evidence
       exists."
-    - "ISO/IEC/IEEE 29148: requirements work must produce traceable, testable
-      information items, not only narrative intent."
-    - "ISO/IEC/IEEE 42010, C4, and ADR practice: architecture and design
-      decisions need context, viewpoints or equivalent structure, rationale,
-      tradeoffs, alternatives, and consequences."
-    - "ISO/IEC/IEEE 29119 and ISTQB: testing needs test basis, traceability,
+    - "ISO/IEC/IEEE 29148:2018 (https://www.iso.org/standard/72089.html):
+      requirements work must produce traceable, testable information items, not
+      only narrative intent."
+    - "ISO/IEC/IEEE 42010:2022 (https://www.iso.org/standard/74393.html), C4
+      (https://c4model.com/), and MADR (https://github.com/adr/madr):
+      architecture/design work needs stakeholder concerns, viewpoints or
+      equivalent views, context, rationale, tradeoffs, alternatives,
+      consequences, and decision records."
+    - "ISO/IEC/IEEE 29119
+      (https://committee.iso.org/sites/jtc1sc7/home/projects/flagship-standards\
+      /isoiecieee-29119-series.html): testing needs test basis, traceability,
       coverage, entry/exit criteria, regression, defect closure, and reports."
-    - "NIST SSDF, OWASP ASVS/SAMM, DORA, Scrum, and SAFe: security, release
-      readiness, delivery metrics, and continuous improvement must remain part
-      of the lifecycle."
+    - "Scrum Guide 2020 (https://scrumguides.org/scrum-guide.html): product work
+      needs transparent product goals/backlog items, ordered value, inspection,
+      and adaptation rather than one-shot requirements freezing."
+    - "ISO 9241-210:2019 (https://www.iso.org/standard/77520.html), confirmed
+      current in 2025: human-centred design needs user/context understanding and
+      design activities across the lifecycle of interactive systems."
+    - "GOV.UK Service Standard points 1 and 4
+      (https://www.gov.uk/service-manual/service-standard/point-1-understand-us\
+      er-needs,
+      https://www.gov.uk/service-manual/service-standard/point-4-make-the-servi\
+      ce-simple-to-use): understand user needs before solutioning and test
+      simplicity/usability with users."
+    - "Design Council Double Diamond / Framework for Innovation
+      (https://www.designcouncil.org.uk/resources/the-double-diamond/):
+      discovery, definition, development, and delivery may iterate when evidence
+      changes the problem framing."
+    - "NIST SSDF (https://csrc.nist.gov/pubs/sp/800/218/final) and OWASP
+      ASVS/SAMM
+      (https://owasp.org/www-project-application-security-verification-standard\
+      /, https://owaspsamm.org/model/): security requirements, secure design,
+      verification, and control evidence belong across the lifecycle."
+    - "DORA continuous delivery and metrics
+      (https://dora.dev/capabilities/continuous-delivery/,
+      https://dora.dev/guides/dora-metrics/): delivery design should preserve
+      automated tests, deployment safety, observability, small batches, and
+      measurable release outcomes."
   documentModes:
     decisionBrief: Frames a decision with context, options, recommendation, risks,
       and success criteria.
@@ -32,7 +61,83 @@ framework:
     executionPlan: Turns approved decisions into ordered, owned, verifiable work.
     evidenceReport: Records what was run, what happened, what failed, and what remains risky.
     decisionRecord: Preserves the reason for an irreversible or future-relevant choice.
+  constraintLevels:
+    hard: Mandatory stage contract. Missing, stale, contradictory, or
+      placeholder-only evidence is FAIL/BLOCKED and cannot be waived by wording.
+    conditional: Mandatory when the trigger condition is touched by scope, sources,
+      project rules, domain terms, or downstream evidence needs. If the
+      condition applies, omission is FAIL/BLOCKED.
+    advisory: Best-practice guidance that improves quality, reviewability, or
+      maintainability. It may be skipped only with a short rationale and no
+      broken hard or conditional requirement.
+    nA: Allowed only when the artifact explains why the level or view does not
+      apply, cites the evidence or project rule, and does not hide a missing
+      mandatory input.
 defaults:
+  hardRequirements:
+    - Read the required inputs for the active skill, or stop as BLOCKED with
+      owner, missing input, impact, and next action.
+    - Produce every required output from the skill I/O contract, or mark the
+      specific output BLOCKED with evidence.
+    - Expose the required output contract in the artifact or handoff so the next
+      skill can verify what was produced, blocked, or N/A.
+    - Separate facts, decisions, assumptions, open questions, risks, blockers,
+      and evidence.
+    - Trace required claims to source artifacts, accepted decisions, scenarios,
+      commands, issues, or human decisions.
+    - "When an existing stage artifact is present, the active skill must run its
+      own Stage Challenge Gate before downstream handoff: derive the challenge
+      focus from that skill's responsibility, required inputs, required outputs,
+      must-answer questions, quality checkpoints, current artifact, upstream
+      sources, and downstream consumer; classify sourced, accepted, assumed,
+      conflicting, missing, and N/A claims, then repair or block through the
+      owning stage."
+    - "Keep Stage Challenge Gates skill-local: ask, repair, or block only on
+      questions the active skill owns; route upstream or downstream findings to
+      the owning stage instead of absorbing another skill's responsibility."
+    - Every Stage Challenge Gate must align terminology against
+      CONTEXT.md/CONTEXT-MAP.md when present, SYSTEM-SPEC.md, configured raw
+      sources, current artifact identifiers, and code/component/API names when
+      implementation-facing work is touched.
+    - "Record durable terminology, naming, decomposition, and load-bearing
+      clarification decisions in the nearest CONTEXT.md, or write `Context
+      update: N/A` with rationale."
+    - Preserve upstream/downstream stage ownership; do not silently rewrite
+      another skill's artifact.
+  conditionalRequirements:
+    - When auth, permissions, privacy, security, tenancy, roles, data access,
+      compliance, payment, migration, public API, or audit behavior is touched,
+      produce the relevant control/traceability matrix or block with the missing
+      source.
+    - When architecture, interface, data-flow, storage, migration, dependency,
+      rollback, integration, or cross-team ownership decisions are made, record
+      ADR/decision-record entries with context, options, decision, consequences,
+      rollback/migration notes, and linked requirements.
+    - When UI-visible behavior is touched, include user-observable states,
+      accessibility/locator strategy, scenario evidence needs, and stable test
+      hooks.
+    - When behavior is testable, define or consume a traceable test basis before
+      claiming implementation, smoke, review, verify, or acceptance success.
+    - When external facts, SDKs, APIs, regulations, market context, or
+      dependency behavior are freshness-sensitive, retrieve current
+      authoritative references or record why local sources are sufficient.
+    - When an artifact becomes too large for one reviewable file, split it into
+      `{stage}/index.md` plus linked child Markdown files while preserving the
+      full stage contract.
+    - When clarification, grilling, architecture review, artifact repair, or
+      task decomposition introduces a term or naming decision future stages must
+      reuse, update module-local or project-level CONTEXT.md before handoff.
+  advisoryGuidance:
+    - 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 `未指定`.
   qualityCheckpoints:
     - Names the reader, stage, scope, and stop condition.
     - Separates facts, decisions, assumptions, open questions, and evidence.
@@ -51,14 +156,26 @@ defaults:
       evidence remains a failure, not an assumption.
     - Records numeric targets or thresholds as `未指定` when the project has not
       supplied them; never invents thresholds to make an output look complete.
+    - "Records `Context update: <path>` or `Context update: N/A` so later stages
+      do not depend on hidden chat terminology."
+    - "Names terminology alignment status for the active artifact:
+      source-consistent, repaired, conflicting, missing, or N/A."
     - Names owner, dependency, acceptance condition, and verification evidence
       for every required output or blocker.
+    - Names existing stage artifact clarity status as PASS, NEEDS_REPAIR,
+      BLOCKED, or WAIVED when a prior artifact is being consumed or improved.
+    - Names the Stage Challenge Gate focus and shows it came from the active
+      skill contract rather than a generic grill.
     - Runs or references the stage-entry quality gate before downstream handoff;
       below-threshold but non-blocking gaps require explicit risk acceptance
       instead of silent progression.
     - "For testable work, verifies test correctness, not only test execution:
       traceable test basis, meaningful assertions, negative/boundary/regression
       coverage, and skipped/unrun checks called out."
+    - When proposal, spec, design, or tasks become too large for one reviewable
+      file, the artifact may split to `{stage}/index.md` plus linked child
+      Markdown files; the index remains the entrypoint and the full stage
+      contract still applies.
   antiPatterns:
     - Template-shaped filler that does not resolve a decision.
     - Skipping PROJECT-CONFIG.md or SYSTEM-SPEC.md, or treating their project
@@ -77,6 +194,15 @@ defaults:
       behavior without configured evidence.
     - Treating missing evidence as low risk when the stage output depends on
       that evidence.
+    - Discarding or rewriting an unclear existing stage artifact before
+      classifying what is sourced, accepted, assumed, conflicting, or missing.
+    - Running a generic grill or cross-stage rewrite instead of the active
+      skill's own Stage Challenge Gate.
+    - Letting terminology, naming, or decomposition decisions live only in chat
+      instead of CONTEXT.md.
+    - Running stage-specific questioning without checking whether the artifact
+      uses the same terms as upstream sources, downstream consumers, and
+      implementation surfaces.
     - Letting a delayed subagent packet block indefinitely instead of marking it
       stale and falling back or re-emitting.
     - Claiming tests prove behavior when they have no traceable basis, no
@@ -85,6 +211,21 @@ stages:
   acceptance:
     documentMode: decisionRecord
     purpose: Record the accept/reject business decision and residual-risk ownership.
+    hardRequirements:
+      - Record accept, reject, or conditional acceptance decision with linked
+        verify/demo evidence.
+      - Name accepted criteria, residual risks, owners, and documentation
+        feedback or no-update rationale.
+      - Do not accept without verification evidence unless explicitly blocked
+        and risk-accepted.
+    conditionalRequirements:
+      - 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.
+    advisoryGuidance:
+      - Keep acceptance focused on decision and risk, not implementation recap.
+      - Preserve rejection reasons in a form that can route back to issue/fix.
     mustAnswer:
       - Is the verified work accepted, rejected, or conditionally accepted?
       - Which evidence and issues support the decision?

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

@@ -4,30 +4,39 @@ contracts:
     requiredResources: [configured-sources, resource-manifest]
     optionalResources: [requirements, api-contracts, backend-repositories, design-sources, design-assets, test-cases, market-research, competitor-research, pricing-research, user-research]
     outputs: [resource-manifest, resource-gaps]
+  preproposal:
+    requiredResources: [brief-or-request, zsk-config]
+    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: [market-research, competitor-research, pricing-research, user-personas, user-research, business-model, regulatory-sources]
+    optionalResources: [reviewed-preproposal-raw-pack, market-research, competitor-research, pricing-research, user-personas, user-research, business-model, regulatory-sources]
     outputs: [project-rules-gate, proposal]
   spec:
     requiredResources: [project-config, system-spec, requirements, proposal]
     optionalResources: [market-research, user-personas, pricing-research, competitor-research]
-    outputs: [project-rules-gate, spec, scenario-contracts]
+    outputs: [project-rules-gate, spec, scenario-contracts, behavior-control-matrix-when-triggered]
   design:
     requiredResources: [project-config, system-spec, spec, code]
-    optionalResources: [api-contracts, design-sources, design-assets, user-personas, competitive-benchmarks]
-    outputs: [project-rules-gate, design, design-views, locator-strategy, playwright-scenario-plan]
+    optionalResources: [api-contracts, reviewed-preproposal-raw-pack, user-personas, competitive-benchmarks]
+    outputs: [project-rules-gate, design, design-views, adr-decision-records, locator-strategy, ui-implementation-mapping-when-triggered, control-traceability-matrix-when-triggered, playwright-scenario-plan]
   task:
     requiredResources: [project-config, system-spec, spec, design]
-    outputs: [project-rules-gate, kiro-style-nested-checkbox-todo-list, proposal-spec-design-alignment-matrix, tasks, playwright-case-skeletons, scenario-synthesis-plan]
+    outputs: [project-rules-gate, kiro-style-nested-checkbox-todo-list, proposal-spec-design-adr-alignment-matrix, control-row-task-coverage-when-triggered, tasks, playwright-case-skeletons, scenario-synthesis-plan]
   coding:
     requiredResources: [tasks, code]
     outputs: [implementation]
+  fix:
+    requiredResources: [persisted-issue, expected-actual-evidence, code]
+    optionalResources: [spec, design, tasks, smoke-report, review-report, verify-report]
+    outputs: [root-cause-note, scoped-correction, regression-guard, updated-issue-record, verification-handoff]
   smoke:
     requiredResources: [implementation]
     outputs: [smoke-report, runtime-evidence]
   review:
-    requiredResources: [implementation, smoke-report]
-    outputs: [review-report, review-issues]
+    requiredResources: [review-target-or-implementation, review-context]
+    optionalResources: [smoke-report, spec, design, tasks, tests, preproposal-raw-pack, source-manifest, stage-doc, code-diff]
+    outputs: [review-report, review-issues, blocking-findings, target-mode-verdict]
   commit:
     requiredResources: [review-report]
     outputs: [commit-evidence]

package/acceptance/harness/workflow/state-machine.yaml

@@ -1,11 +1,13 @@
 version: 1
 stages:
   - prepare
+  - preproposal
   - proposal
   - spec
   - design
   - task
   - coding
+  - fix
   - smoke
   - review
   - commit
@@ -18,8 +20,11 @@ stages:
   - archive
 transitions:
   prepare:
-    pass: [proposal]
+    pass: [preproposal, proposal]
     fail: [prepare]
+  preproposal:
+    pass: [proposal]
+    fail: [preproposal, prepare]
   proposal:
     pass: [spec]
   spec:
@@ -33,12 +38,16 @@ transitions:
     fail: [design]
   coding:
     pass: [smoke]
+    fail: [fix]
+  fix:
+    pass: [smoke, review, ready]
+    fail: [coding]
   smoke:
     pass: [review]
-    fail: [coding]
+    fail: [fix, coding]
   review:
-    pass: [commit]
-    fail: [coding]
+    pass: [commit, preproposal, proposal]
+    fail: [fix, coding, preproposal, proposal, spec, design, task]
   commit:
     pass: [deploy]
     fail: [coding]
@@ -57,7 +66,7 @@ transitions:
     pass: [verify]
   verify:
     pass: [acceptance]
-    fail: [coding, defect]
+    fail: [fix, coding, defect]
   acceptance:
     pass: [archive]
     fail: [spec, design, coding]