@captain_z/zsk-skills 1.8.2 → 1.8.3

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

@@ -10,7 +10,7 @@ defaults:
     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/"
@@ -40,27 +40,48 @@ 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/design/{topic}/design-source-needs.md"
+      - ".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}/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 +91,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-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,61 @@ 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.
+    - 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.
+  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.
+    - 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.
@@ -59,6 +142,10 @@ defaults:
     - "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
@@ -85,6 +172,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: [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, product-brief, roadmap-decomposition, ux-flow-seeds, design-source-needs, 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]
+    outputs: [project-rules-gate, design, design-views, adr-decision-records, locator-strategy, 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]

package/archive/SKILL.md

@@ -74,6 +74,8 @@ This core skill is governed by the ZSK harness. Enforce these rules even when on
 - Source of truth: read configured resources before inventing intent; record conflicts instead of choosing silently.
 - Issue taxonomy: route demo, smoke, review, test, verify, and acceptance findings to the correct issue type.
 - Skill role: execute the full expert role, including all relevant lanes; partial single-angle execution is a failing result.
+- Constraint levels: hard requirements and triggered conditional requirements are blocking; advisory guidance may be skipped only with rationale and no broken hard/conditional gate.
+- Required outputs: every output declared in the skill I/O contract is mandatory unless recorded as evidence-backed N/A or BLOCKED with owner, impact, and next action.
 - Collaboration: ordinary stage skills own their declared outputs and handoff quality; workflow skills own route selection. Do not hardcode the next stage inside a stage skill.
 - Dynamic state awareness: identify the active role/stage, project type, stack, runtime, domain, target users/market, and freshness-sensitive decisions before selecting practices or retrieval sources.
 - Filesystem boundaries: write ZSK-managed outputs only under the configured `.zsk` workspace paths.

package/archive/harness/THIS_SKILL.md

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

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

@@ -6,11 +6,14 @@ Default project paths:
 - `.zsk/docs/`: project-level docs such as `SYSTEM-SPEC.md` and `PROJECT-CONFIG.md`.
 - `.zsk/modules/{module}/`: module config and stage artifacts.
 - `.zsk/raws/`: raw external source snapshots, manifests, imported test cases, market/product research sources, and design/API assets.
+- `.zsk/raws/prepare/**`: reusable source lanes. `preproposal` may add generated or candidate product, roadmap, UX, and design-source readiness resources here only when they are labeled with provenance, review checkpoint status, assumptions, and blockers.
+- `.zsk/evidence/preproposal/{run}/`: checkpoint review evidence for product direction, roadmap/decomposition, UX/design-readiness, and final readiness before formal proposal.
 - `.zsk/modules/{module}/_issues/`: module-private managed issue records and indexes, created on demand.
 - `.zsk/modules/{module}/_evidence/`: module-private reusable runtime or research evidence, created on demand.
 - `.zsk/modules/{module}/_playwright/`: module-specific Playwright specs, test plans, auth state, execution records, reports, and results, created on demand.
 - `.zsk/issues/`, `.zsk/evidence/`, `.zsk/playwright/`: shared/global artifacts only, created on demand when the asset is intentionally cross-module.
 - `.zsk/learning/proposals/`: reusable improvement proposals and learning records, created lazily only when learn/archive writes an actual proposal.
+- `.zsk/plans/`: ZSK plan artifacts, created lazily only when `zskplan` or `zsk` freezes an executable route.
 - `skills/{slug}/`: zsk source skill directories.
 - `harness/`: zsk source governance contracts.
 
@@ -40,4 +43,6 @@ Before any skill writes an artifact, classify its scope:
 
 This rule applies to every underscore module directory, not only `_issues`. For example, module-local issues go to `_issues`, module-local runtime evidence goes to `_evidence`, and module-local Playwright specs/auth/results go to `_playwright`. Use outer `.zsk/issues`, `.zsk/evidence`, or `.zsk/playwright` only after deciding the artifact is shared, global, or public. When scope is ambiguous, prefer module-private and record the reason or blocker before promoting outward.
 
-The skill that produces the final artifact for a module stage writes the formal report to `.zsk/modules/{module}/{stage}.md`. Supporting artifacts stay in the appropriate `_issues`, `_evidence`, or `_playwright` directory unless they are deliberately shared/global/public.
+The skill that produces the final artifact for a module stage writes the formal report to `.zsk/modules/{module}/{stage}.md`. For large `proposal`, `spec`, `design`, or `tasks` artifacts, the skill may upgrade the stage artifact to `.zsk/modules/{module}/{stage}/index.md` and split child Markdown files under the same stage directory. The `index.md` file remains the review entrypoint, must link every child document included in the logical artifact, and must preserve the same stage contract; splitting content does not weaken required gates. Supporting artifacts stay in the appropriate `_issues`, `_evidence`, or `_playwright` directory unless they are deliberately shared/global/public.
+
+`preproposal` is not a module-final stage. Its outputs are proposal-prep raw resources under `.zsk/raws/prepare/**` plus checkpoint evidence under `.zsk/evidence/preproposal/{run}/`. It must not create `.zsk/modules/{module}/proposal.md`, `spec.md`, `design.md`, or `tasks.md`; those remain owned by their formal stage skills.

package/archive/harness/constraints/issue-taxonomy.md

@@ -88,6 +88,22 @@ Every actionable issue should record:
 - whether a durable learning proposal is needed under `.zsk/learning/proposals`;
 - regression guard: test, scenario, lint rule, checklist, or explicit waiver.
 
+## Issue-Driven Fix Route
+
+`fix` is the dedicated skill and route name for "persisted issue -> root cause -> minimal change -> regression guard -> verification handoff". It is not a shortcut around `coding`, `smoke`, `review`, `ready`, or `verify`.
+
+Required fix-route ledger fields:
+
+- issue path or id;
+- reproduction/evidence basis;
+- root-cause hypothesis and confidence;
+- changed files or no-code rationale;
+- regression guard or explicit blocker;
+- documentation feedback target or no-update rationale;
+- next verification route and evidence command.
+
+Do not use `fix` for generic unanchored cleanup. If there is no persisted issue or accepted expected/actual clarification, create or update the issue first.
+
 ## Closure And Feedback Loop
 
 1. Create or update module-specific issues under `.zsk/modules/{module}/_issues/` as soon as the finding is actionable, using the type and prefix fields to preserve taxonomy.