@captain_z/zsk-skills 1.8.1 → 1.8.2

package/acceptance/SKILL.md

@@ -27,8 +27,8 @@ doNotUseWhen:
 positiveExamples:
   - Run zsk:acceptance with the required inputs and produce the documented
     acceptance artifacts.
-  - Continue the workflow at acceptance after the prerequisite evidence and
-    blockers are resolved.
+  - Run this skill only for its owned outputs after prerequisites are present;
+    let workflow skills decide subsequent stage routing.
 negativeExamples:
   - Use zsk:acceptance to skip missing prerequisites or hide unresolved blockers.
   - Run acceptance for generic chat, unrelated implementation, or another ZSK
@@ -79,9 +79,11 @@ 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.
+- 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.
 - Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
+- Learning authority: reusable ZSK core learning must target the canonical ZSK source repo `.zsk/learning/proposals/`; project-local learning may stay in the current project.
 
 When a `harness/` directory is installed beside this file, treat it as the local contract source:
 

package/acceptance/harness/THIS_SKILL.md

@@ -35,6 +35,20 @@ This file is generated for the installed skill. Read it before executing this sk
 - `documentation feedback`
 - `accept/reject evidence`
 
+## Collaboration Discipline
+
+- Own only this skill's required outputs; do not redefine upstream artifacts or approve downstream work on another skill's behalf.
+- Before handoff, confirm required inputs were consumed, outputs are complete or explicitly BLOCKED, and the next consumer can act without chat memory.
+- If another stage is missing, stale, contradictory, or under-specified, record a blocker, issue, or documentation feedback instead of silently fixing it inside this skill.
+
+## Best-Practice Baseline
+
+- Judge lifecycle function, not terminology: accept equivalent project artifacts only when they satisfy the same responsibility, handoff, and evidence need.
+- Treat missing mandatory artifacts, mandatory evidence, required owners, required gates, or downstream-consumable outputs as FAIL or BLOCKED.
+- Write unsupplied numeric thresholds, quality bars, SLOs, coverage targets, and business targets as `未指定`; suggestions must be labeled separately from current policy.
+- Avoid provider lock-in: do not assume Jira, Confluence, Figma, GitHub, GitLab, Linear, Notion, browser tooling, or any platform unless configured sources or evidence identify it.
+- For each required output or finding, name owner, dependency, acceptance condition, verification evidence, and next action.
+
 ## Document Quality Standard
 
 - Document mode: `decisionRecord`
@@ -53,6 +67,14 @@ This file is generated for the installed skill. Read it before executing this sk
 - Links each important claim to a source artifact, command output, issue, scenario, or human decision.
 - States what is out of scope so later stages do not silently expand work.
 - Makes the next stage executable without requiring hidden context from chat.
+- Includes a Project Rules Gate that cites PROJECT-CONFIG.md and SYSTEM-SPEC.md constraints, impacts, and blockers.
+- Confirms upstream/downstream consistency before handoff: inputs consumed, outputs complete or blocked, and next consumer can act without chat memory.
+- Accepts different project methods and artifact names only when they provide an equivalent control point with evidence.
+- Uses PASS, FAIL, BLOCKED, or N/A only with evidence; missing mandatory evidence remains a failure, not an assumption.
+- Records numeric targets or thresholds as `未指定` when the project has not supplied them; never invents thresholds to make an output look complete.
+- 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.
 - Links verify report, demo evidence, accepted criteria, and residual risks.
 - Records documentation feedback or no-update rationale for confirmed learnings.
 
@@ -78,10 +100,16 @@ This file is generated for the installed skill. Read it before executing this sk
 ## Document Anti-Patterns
 
 - Template-shaped filler that does not resolve a decision.
+- Skipping PROJECT-CONFIG.md or SYSTEM-SPEC.md, or treating their project rules as optional suggestions.
 - Untraceable claims such as 'should work', 'best practice', or 'user friendly' without evidence or criteria.
 - Mixing raw source facts, decisions, runtime evidence, and tasks in one undifferentiated section.
 - Skipping unresolved contradictions instead of recording a blocker, risk, or question.
 - Optimizing wording while leaving acceptance, evidence, ownership, or next action ambiguous.
+- Passing because a familiar term appears while the equivalent lifecycle function is absent.
+- Inventing project policy, quality thresholds, source mappings, or platform behavior without configured evidence.
+- Treating missing evidence as low risk when the stage output depends on that evidence.
+- Letting a delayed subagent packet block indefinitely instead of marking it stale and falling back or re-emitting.
+- Claiming tests prove behavior when they have no traceable basis, no meaningful assertion, or only prove implementation details.
 - Accepting without verification evidence.
 - Letting residual risks remain ownerless.
 

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

@@ -16,6 +16,16 @@ Default project paths:
 
 Root `docs/`, `.raws/`, `.issues/`, `.playwright/`, and `plans/` are not default write targets for ZSK skills. Use explicit export, promote, import, or migration commands when project-facing root documentation is needed.
 
+## Learning Output Authority
+
+Learning artifacts must be written according to what they are meant to change:
+
+- Project-local learning that only affects the current business/product project may use the current project's `.zsk/learning/proposals/`, created lazily.
+- Reusable ZSK core learning that would change ZSK skills, harness contracts, templates, packs, CLI behavior, defaults, or installer behavior must be written to the canonical ZSK source checkout: `<zsk-core>/.zsk/learning/proposals/`.
+- Resolve `<zsk-core>` from explicit configuration/environment first: `ZSK_LEARNING_REPO`, then `ZSK_CORE_REPO`. If neither is set, the current repository qualifies only when it contains `skills/`, `harness/`, and `packages/cli/`.
+- If no canonical ZSK source checkout is available or writable, do not create a substitute core-learning proposal in the consuming project. Record `BLOCKED` with the missing root, intended proposal title, source evidence, and next action.
+- `zsk init` must not create `.zsk/learning/`; learning directories remain lazy outputs created by `learn` or `archive` only when a concrete proposal is written.
+
 ## Scope Routing Rule
 
 Before any skill writes an artifact, classify its scope:

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

@@ -2,6 +2,107 @@
 
 Every ZSK skill is an expert role, not a loose prompt. Before acting, the skill must identify its responsibility, required inputs, required outputs, forbidden scope, expert checks, and evidence obligations from `harness/THIS_SKILL.md`, `workflow/skill-io-contract.yaml`, and this file.
 
+## Method-Neutral Best-Practice Baseline
+
+ZSK skills must work across project types, team methods, tools, and platforms. A skill must judge the lifecycle function, not the label.
+
+- Equivalent artifacts are accepted only with evidence. For example, a project may use use cases instead of user stories, an architecture note instead of a formal C4 diagram, or a release checklist instead of a named release skill, but the artifact must still satisfy the same responsibility and handoff need.
+- Missing mandatory artifacts, mandatory evidence, required owners, required gates, or required downstream-consumable outputs are `FAIL` or `BLOCKED`, not a soft recommendation.
+- Numeric thresholds, quality bars, SLOs, coverage targets, or business targets that are not supplied by project config, docs, or accepted decisions must be written as `未指定`. A skill may propose suggested values separately, but must not present them as current policy.
+- Every required output or finding needs an owner, dependency, acceptance condition, verification evidence, and next action.
+- Security, privacy, data safety, release readiness, test traceability, and continuous improvement are lifecycle concerns. They are N/A only when the project context proves they do not apply.
+
+## Cross-Project Portability Rule
+
+Core skills and harness rules must be generic by default.
+
+- Do not hardcode Jira, Confluence, Figma, GitHub, GitLab, Linear, Notion, browser tooling, design tooling, or any provider as the only valid path.
+- Detect source/provider behavior from `.zsk/config.yaml`, source URLs, local manifests, exports, and user-approved auth/session evidence.
+- When a provider is unsupported, prefer generic fetch, Playwright/browser capture, local export ingestion, or a clearly blocked adapter request rather than silently dropping the source.
+- If source-to-lane mapping is uncertain, record a question or blocker and ask before choosing. Do not invent that a URL is product, design, QA, backend, or UX without evidence.
+
+## Learning Output Authority
+
+Learning output has two different authorities:
+
+- Project-specific delivery learning stays with the current project: module archives, `.zsk/docs/SYSTEM-SPEC.md`, module `_issues`, shared/global issue buckets, or project-local `.zsk/learning/proposals/` when the proposal only affects that project.
+- Reusable ZSK core learning belongs to the canonical ZSK source repository: `<zsk-core>/.zsk/learning/proposals/`, because it is intended to change ZSK skills, harness, templates, packs, CLI behavior, or defaults.
+
+Resolve `<zsk-core>` in this order:
+
+1. Explicit environment/configured root such as `ZSK_LEARNING_REPO` or `ZSK_CORE_REPO`.
+2. The current repository if it is recognizably the ZSK source repo, containing `skills/`, `harness/`, and `packages/cli/`.
+3. Otherwise `BLOCKED`: report the missing canonical ZSK source root and do not scatter reusable core-learning notes into the consuming project.
+
+## Skill Responsibility Matrix
+
+Each skill owns one stage contract. Workflow skills may route or schedule work, but ordinary stage skills must not hardcode the next stage, redefine upstream facts, or accept downstream work on behalf of another skill.
+
+| Skill | Owns | Does Not Own | Consistency / Handoff |
+| --- | --- | --- | --- |
+| `prepare` | Source discovery, configured origin validation, raws snapshots, manifest, source gaps | Product interpretation, requirements decisions, design choices | Hands source manifest, raws indexes, conflicts, and blockers to `proposal` / `spec`; asks before uncertain source-to-lane mapping |
+| `proposal` | Problem, goal, scope, non-goals, stakeholders, risks, success metrics, decision request | Detailed behavior, architecture, task breakdown, implementation | Every goal and metric must trace to sources or accepted assumptions; hands bounded scope to `spec` |
+| `spec` | FR/NFR, acceptance criteria, scenarios, edge cases, constraints, traceability | Architecture, file/module design, implementation tasks | Every P0/P1 requirement must trace to proposal/source and be testable; hands behavior contract to `design` and `task` |
+| `design` | Architecture, interfaces, data/state flow, design views/diagrams, ADRs or equivalent decisions, tradeoffs, rollout and verification surfaces | Rewriting requirements, task sequencing, coding, decorative diagrams | Every design decision and diagram must trace to spec/AC/NFR, ADR, risk, or verification need; hands implementation map to `task` |
+| `task` | Kiro-style nested checkbox task groups/subtasks, owners, dependencies, scope/files, evidence hooks, coverage matrix | Changing proposal/spec/design intent, coding, review approval | Every task group must align to proposal/spec/design IDs; every subtask must be executable and evidence-backed before `coding` |
+| `coding` | Scoped implementation, changed tests, implementation notes, local validation evidence | Requirements changes, broad refactors, final approval | Every diff maps to task IDs and preserves upstream intent; hands changed files and evidence to `smoke` / `review` |
+| `smoke` | Smallest credible local proof of changed behavior, failure classification, smoke issues | Full acceptance, final verification, release approval | Hands command/scenario evidence and failures to `review`, `defect`, or `ready` |
+| `review` | Scope drift, correctness, maintainability, security, test adequacy, harness compliance findings | Implementing fixes, independent verification, business acceptance | Findings must reference files/artifacts and route fix work to `issue` / `defect` / `coding`; no PASS without evidence adequacy |
+| `commit` | Scoped staging, Lore commit message, commit evidence, known verification gaps | Feature validation, release readiness | Hands immutable change intent and tested/not-tested evidence to `deploy` / `archive` |
+| `deploy` | Release target, deployment command, environment/version, health checks, rollback owner | Product acceptance, postmortem, unrelated infra changes | Hands runtime URL/version, smoke evidence, and rollback path to `demo`, `verify`, or `archive` |
+| `demo` | Source-backed user-visible flow rehearsal, scenario evidence, demo issues | Formal testing, acceptance, invented flows | Consumes spec/design/task case skeletons; routes gaps to `defect` or upstream docs feedback |
+| `defect` | Reproducible defect records, severity, dedupe, fix route | Fix implementation, broad redesign | Links failures to FR/AC/evidence and hands fix route to `coding` / `ready` |
+| `ready` | Verification handoff, issue-evidence matrix, exact claim and version | Fixing defects, independent pass/fail decision | Hands replayable claims and evidence paths to `verify` |
+| `verify` | Independent replay, pass/fail decision, issue status update, regression evidence | Implementation, business acceptance, release changes | Verifies against ready/spec/AC with fresh evidence; hands decision to `acceptance` |
+| `acceptance` | Accept/reject decision, residual risk, business/user confirmation, documentation feedback | New verification, implementation fixes | Hands accepted state, waived risks, or rejection reasons to `archive` / `issue` |
+| `archive` | Final artifact preservation, closed issue audit, learning proposals, release notes | Changing delivered scope, reopening decisions without issue evidence | Preserves decisions/evidence and promotes reusable gaps to `learn` |
+| `learn` | Learning proposal intake, pattern comparison, optimization batch planning, reusable ZSK core proposal routing | Unreviewed mutation of core skills/harness/templates, scattering core learning into consuming projects | Writes project-local learning only for project-specific change; writes reusable core learning to canonical ZSK source repo proposals; requires review/regression before promotion |
+| `issue` | Persistent issue/defect/risk/question records, indexes, owner/status/evidence fields | Resolving the issue by assertion, replacing review/verify | Provides the shared feedback and closure ledger for all stages |
+| `dispatch` | Runtime staffing plan, active roles, write scopes, evidence obligations, durable emit packets, packet status ledger | Business or technical stage output | Supports any stage skill from the resource pool; stale or delayed packets fall back to leader-sequential role simulation |
+| `flow` | Next legal stage decision from state, resources, blockers, profile, and stage-entry quality assessment | Stage artifact production | Routes only when gates allow; reports blockers or quality-confirmation needs instead of forcing progression |
+| `zskplan` | Route freeze, selected skills, output map, expert lane plan, evidence plan, blockers | Implementation and verification | Produces the plan contract that `zsk` executes |
+| `zsk` | End-to-end execution loop, skill dispatch, expert lane integration, validation/fix loop | Skipping selected skill contracts or evidence gates | Executes the frozen or inferred route until complete or blocked |
+
+## Collaboration Consistency Gate
+
+Before a skill reports `PASS`, `READY`, `DONE`, or an unblocked handoff, it must prove the following chain remains intact:
+
+```text
+prepare sources
+-> proposal goals / scope / success metrics
+-> spec FR / AC / NFR / scenarios
+-> design decisions / ADRs / interfaces / data flow
+-> task checkbox groups / subtasks / evidence hooks
+-> coding diff / changed tests
+-> smoke or demo evidence
+-> review findings
+-> ready claim
+-> verify result
+-> acceptance decision
+-> archive / learn
+```
+
+Consistency checks:
+
+- Upstream input exists, is current enough for the decision, and is explicitly referenced.
+- Current-stage required outputs are complete or marked `BLOCKED` with owner, missing input, impact, and next action.
+- Downstream consumers can use the output without hidden chat memory.
+- Facts, decisions, assumptions, open questions, and evidence are separated.
+- 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.
+
+## Kiro-Style Task Handoff
+
+`task` must use nested Markdown checkboxes as the primary execution surface:
+
+```md
+- [ ] 1. <task group>
+  - [ ] 1.1 <subtask>
+  - [ ] 1.2 <subtask>
+```
+
+Metadata belongs under the relevant checkbox item, not in a detached table alone. Each task group needs proposal/spec/design alignment, owner, dependencies, scope/files, expected output, evidence, and stop condition. Each subtask needs at least source ID, owner, scope/files, expected output, acceptance, and evidence. A task artifact without this hierarchy is not execution-ready.
+
 ## Role Completeness
 
 Each skill run must cover its whole declared role:
@@ -70,6 +171,8 @@ For `DEEP` review, dispatch at least three independent expert lanes when subagen
 - `zskplan` freezes the route and writes the plan artifact under `.zsk/plans/`: selected skills, required inputs, `.zsk` output map, expert lanes, subagent plan, Playwright/auth/evidence plan, fix loop, blockers, and stop condition.
 - `zsk` executes the frozen or inferred route: it selects the legal skill, dispatches required expert lanes, integrates results, writes only `.zsk` artifacts, validates, fixes, and repeats until the plan is complete or blocked.
 - Neither entry point may skip a selected skill's own contract, forbidden scope, required inputs, issue routing, or evidence gate.
+- Before entering a downstream stage, the workflow must evaluate required upstream artifact quality or record why the gate is N/A. Below-threshold quality gaps require an explicit risk acceptance; missing mandatory artifacts remain blocked.
+- Every emitted subagent packet must be durable: `runId`, `packetId`, heartbeat/deadline policy, status path, write scope, evidence obligation, stop condition, and fallback route. Stale packets must be completed by fallback evidence or re-emitted; they cannot count as completed work.
 - When no frozen route exists, `zsk` must perform the `zskplan` route-freeze work first and state the resulting plan.
 - Plans, Playwright specs, auth state, runtime execution JSON, traces, reports, reusable evidence, issues, and learning proposals must use the configured `.zsk` workspace paths.
 - Module-local runtime/supporting artifacts use module-private `_issues`, `_evidence`, and `_playwright`; shared, global, or public artifacts use the corresponding outer `.zsk/{kind}` scope bucket.
@@ -83,7 +186,10 @@ For `DEEP` review, dispatch at least three independent expert lanes when subagen
 - ingest user-supplied public skill or harness references, including URLs, repos, markdown, examples, screenshots, or pasted excerpts;
 - compare external patterns against current ZSK contracts, source rights, project constraints, and regression needs;
 - record module-local delivery-impacting problems under module `_issues`, or outer `.zsk/issues/{shared|global|public}` only when the issue scope is not owned by one module;
-- write reusable improvement proposals under `.zsk/learning/proposals/`;
+- classify the learning target as project-local, optional-pack, team-local, or reusable ZSK core before writing;
+- write project-local proposals under the current project's `.zsk/learning/proposals/` only when the proposal affects that project alone;
+- write reusable ZSK core proposals under the canonical ZSK source repo `.zsk/learning/proposals/`, resolved by `ZSK_LEARNING_REPO`, `ZSK_CORE_REPO`, or a recognized ZSK source checkout;
+- if the canonical ZSK source repo cannot be resolved or is not writable, report `BLOCKED` with the missing root, intended proposal name, evidence, and next action instead of writing core learning into the consuming project;
 - group accepted proposals into one optimization batch with target files, regression prompts, risks, and review status.
 
 `learn` must not mutate core skills, harness constraints, packs, templates, or generated artifacts from one unreviewed incident. It must not copy external skills or harnesses wholesale; it adapts principles and testable constraints into ZSK proposals with source notes. Promotion requires review evidence and regression prompts.

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

@@ -17,6 +17,31 @@ The harness computes gate status. Skills may propose outputs and record evidence
 - `smoke`, `review`, and `verify` must reject tests that cannot be traced to PRD/SRS, spec/design, task, issue, or accepted user clarification.
 - If the test contract is unclear, the stage is `blocked` until the uncertainty is clarified or recorded as a resource gap.
 
+## Stage Entry Quality Gate
+
+- Before a downstream stage starts, the harness must assess the required upstream artifacts for that stage with `zsk gate assess --stage <stage>`.
+- The assessment must write a score, PASS/FAIL criteria, blockers, gaps, and next action under `.zsk/evidence/gates/`.
+- 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.
+
+## Test Correctness Gate
+
+- A passing test suite is not sufficient evidence when the tests do not prove the intended behavior.
+- New or changed behavior needs a traceable test basis: PRD/SRS, spec acceptance criteria, design decision, task, issue, or accepted user clarification.
+- Tests must include the meaningful negative, boundary, and regression cases implied by the acceptance criteria. If a case is intentionally omitted, record the omitted case, reason, risk, and owner.
+- For TDD work, prefer a red/green proof or equivalent evidence that the new test fails without the fix. If that is impractical, review must explain the substitute 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.
+
+## 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.
+- Dispatch must write an emit ledger under `.zsk/evidence/dispatch/{run}/emit-ledger.json` plus per-packet status files.
+- Long-running packets must heartbeat before their deadline. A pending or running packet with no heartbeat past deadline becomes `stale`.
+- Stale packets do not block forever. The lead-integrator must either fall back to leader-sequential execution for that lane or re-emit a new bounded packet.
+- A stale, failed, blocked, or waived packet cannot be counted as completed evidence unless the lead-integrator records the fallback result or accepted risk.
+
 ## Gate Status
 
 - `blocked`: required resource or evidence is missing.
@@ -25,3 +50,6 @@ The harness computes gate status. Skills may propose outputs and record evidence
 - `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/completion-contract.yaml

@@ -7,6 +7,8 @@ defaults:
     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."
     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"
     modulePrivate:
@@ -107,6 +109,28 @@ outputs:
       - ".zsk/modules/{module}/archive.md"
       - ".zsk/learning/proposals/"
     feedbackTargets: [".zsk/modules/{module}/archive.md", ".zsk/learning/proposals/"]
+  learn:
+    artifacts:
+      - "<zsk-core>/.zsk/learning/proposals/ for reusable ZSK core improvements"
+      - ".zsk/learning/proposals/ only for project-local learning"
+      - ".zsk/issues/{shared|global|public}/ or .zsk/modules/{module}/_issues/ for delivery-impacting findings"
+    feedbackTargets:
+      - "<zsk-core>/.zsk/learning/proposals/"
+      - ".zsk/learning/proposals/"
+      - "harness/learning/promotion-rules.yaml"
+  dispatch:
+    artifacts:
+      - ".zsk/evidence/dispatch/{run}/staffing-plan.json"
+      - ".zsk/evidence/dispatch/{run}/staffing-plan.md"
+      - ".zsk/evidence/dispatch/{run}/emit-packets.jsonl"
+      - ".zsk/evidence/dispatch/{run}/emit-ledger.json"
+      - ".zsk/evidence/dispatch/{run}/packet-status/"
+    feedbackTargets: [".zsk/evidence/dispatch/{run}/staffing-plan.md"]
+  flow:
+    artifacts:
+      - ".zsk/evidence/gates/{run}/gate-assessment.json"
+      - ".zsk/evidence/gates/{run}/gate-assessment.md"
+    feedbackTargets: [".zsk/evidence/gates/{run}/gate-assessment.md"]
 postRun:
   issueIndexes:
     module: ".zsk/modules/{module}/_issues/index.md"
@@ -117,6 +141,9 @@ postRun:
     targets: ["spec", "design", "tasks", "SYSTEM-SPEC", "learning-proposal"]
   learning:
     proposalPath: ".zsk/learning/proposals/"
+    coreProposalPath: "<zsk-core>/.zsk/learning/proposals/"
+    coreRootResolution: "ZSK_LEARNING_REPO -> ZSK_CORE_REPO -> current checkout containing skills/, harness/, and packages/cli/ -> BLOCKED"
+    targetRule: "Project-local learning stays in the current project; reusable ZSK core learning must target the canonical ZSK source checkout."
     createPolicy: "lazy; do not create during zsk init or unrelated stages"
     createWhen: "only when learn/archive writes a concrete reusable improvement proposal"
     promoteBy: "harness/learning/promotion-rules.yaml"

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

@@ -30,6 +30,15 @@ principles:
     ask, or record a resource gap."
   - "TDD first for testable behavior: tests and scenarios must be accurate and
     traceable to PRD/SRS, spec/design, task, issue, or accepted clarification."
+  - 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.
+  - Before entering a downstream stage, assess upstream artifact quality and
+    record READY, NEEDS_CONFIRMATION, BLOCKED, or WAIVED with evidence instead
+    of relying on chat confidence.
+  - "Subagent dispatch is durable: every emit packet needs a status file,
+    heartbeat deadline, timeout policy, and fallback route so delayed lanes
+    cannot block the workflow indefinitely."
 toolPolicy:
   localFirst:
     - filesystem

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

@@ -11,6 +11,19 @@ framework:
       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: 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,
+      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."
   documentModes:
     decisionBrief: Frames a decision with context, options, recommendation, risks,
       and success criteria.
@@ -27,8 +40,29 @@ defaults:
       scenario, or human decision.
     - States what is out of scope so later stages do not silently expand work.
     - Makes the next stage executable without requiring hidden context from chat.
+    - Includes a Project Rules Gate that cites PROJECT-CONFIG.md and
+      SYSTEM-SPEC.md constraints, impacts, and blockers.
+    - "Confirms upstream/downstream consistency before handoff: inputs consumed,
+      outputs complete or blocked, and next consumer can act without chat
+      memory."
+    - Accepts different project methods and artifact names only when they
+      provide an equivalent control point with evidence.
+    - Uses PASS, FAIL, BLOCKED, or N/A only with evidence; missing mandatory
+      evidence remains a failure, not an assumption.
+    - Records numeric targets or thresholds as `未指定` when the project has not
+      supplied them; never invents thresholds to make an output look complete.
+    - 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."
   antiPatterns:
     - Template-shaped filler that does not resolve a decision.
+    - Skipping PROJECT-CONFIG.md or SYSTEM-SPEC.md, or treating their project
+      rules as optional suggestions.
     - Untraceable claims such as 'should work', 'best practice', or 'user
       friendly' without evidence or criteria.
     - Mixing raw source facts, decisions, runtime evidence, and tasks in one
@@ -37,6 +71,16 @@ defaults:
       or question.
     - Optimizing wording while leaving acceptance, evidence, ownership, or next
       action ambiguous.
+    - Passing because a familiar term appears while the equivalent lifecycle
+      function is absent.
+    - Inventing project policy, quality thresholds, source mappings, or platform
+      behavior without configured evidence.
+    - Treating missing evidence as low risk when the stage output depends on
+      that evidence.
+    - Letting a delayed subagent packet block indefinitely instead of marking it
+      stale and falling back or re-emitting.
+    - Claiming tests prove behavior when they have no traceable basis, no
+      meaningful assertion, or only prove implementation details.
 stages:
   acceptance:
     documentMode: decisionRecord

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

@@ -5,20 +5,20 @@ contracts:
     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]
   proposal:
-    requiredResources: [requirements]
+    requiredResources: [project-config, system-spec, requirements]
     optionalResources: [market-research, competitor-research, pricing-research, user-personas, user-research, business-model, regulatory-sources]
-    outputs: [proposal]
+    outputs: [project-rules-gate, proposal]
   spec:
-    requiredResources: [requirements, proposal]
+    requiredResources: [project-config, system-spec, requirements, proposal]
     optionalResources: [market-research, user-personas, pricing-research, competitor-research]
-    outputs: [spec, scenario-contracts]
+    outputs: [project-rules-gate, spec, scenario-contracts]
   design:
-    requiredResources: [spec, code]
+    requiredResources: [project-config, system-spec, spec, code]
     optionalResources: [api-contracts, design-sources, design-assets, user-personas, competitive-benchmarks]
-    outputs: [design, locator-strategy, playwright-scenario-plan]
+    outputs: [project-rules-gate, design, design-views, locator-strategy, playwright-scenario-plan]
   task:
-    requiredResources: [spec, design]
-    outputs: [tasks, playwright-case-skeletons, scenario-synthesis-plan]
+    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]
   coding:
     requiredResources: [tasks, code]
     outputs: [implementation]

package/archive/SKILL.md

@@ -26,8 +26,8 @@ doNotUseWhen:
 positiveExamples:
   - Run zsk:archive with the required inputs and produce the documented archive
     artifacts.
-  - Continue the workflow at archive after the prerequisite evidence and
-    blockers are resolved.
+  - Run this skill only for its owned outputs after prerequisites are present;
+    let workflow skills decide subsequent stage routing.
 negativeExamples:
   - Use zsk:archive to skip missing prerequisites or hide unresolved blockers.
   - Run archive for generic chat, unrelated implementation, or another ZSK
@@ -74,9 +74,11 @@ 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.
+- 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.
 - Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
+- Learning authority: reusable ZSK core learning must target the canonical ZSK source repo `.zsk/learning/proposals/`; project-local learning may stay in the current project.
 
 When a `harness/` directory is installed beside this file, treat it as the local contract source:
 

package/archive/harness/THIS_SKILL.md

@@ -35,6 +35,22 @@ This file is generated for the installed skill. Read it before executing this sk
 - `learning proposal extraction`
 - `release notes`
 
+## Collaboration Discipline
+
+- Own only this skill's required outputs; do not redefine upstream artifacts or approve downstream work on another skill's behalf.
+- Before handoff, confirm required inputs were consumed, outputs are complete or explicitly BLOCKED, and the next consumer can act without chat memory.
+- If another stage is missing, stale, contradictory, or under-specified, record a blocker, issue, or documentation feedback instead of silently fixing it inside this skill.
+
+## Best-Practice Baseline
+
+- Judge lifecycle function, not terminology: accept equivalent project artifacts only when they satisfy the same responsibility, handoff, and evidence need.
+- Treat missing mandatory artifacts, mandatory evidence, required owners, required gates, or downstream-consumable outputs as FAIL or BLOCKED.
+- Write unsupplied numeric thresholds, quality bars, SLOs, coverage targets, and business targets as `未指定`; suggestions must be labeled separately from current policy.
+- Avoid provider lock-in: do not assume Jira, Confluence, Figma, GitHub, GitLab, Linear, Notion, browser tooling, or any platform unless configured sources or evidence identify it.
+- For each required output or finding, name owner, dependency, acceptance condition, verification evidence, and next action.
+- 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.
+
 ## Document Quality Standard
 
 - Document mode: `decisionRecord`
@@ -53,6 +69,14 @@ This file is generated for the installed skill. Read it before executing this sk
 - Links each important claim to a source artifact, command output, issue, scenario, or human decision.
 - States what is out of scope so later stages do not silently expand work.
 - Makes the next stage executable without requiring hidden context from chat.
+- Includes a Project Rules Gate that cites PROJECT-CONFIG.md and SYSTEM-SPEC.md constraints, impacts, and blockers.
+- Confirms upstream/downstream consistency before handoff: inputs consumed, outputs complete or blocked, and next consumer can act without chat memory.
+- Accepts different project methods and artifact names only when they provide an equivalent control point with evidence.
+- Uses PASS, FAIL, BLOCKED, or N/A only with evidence; missing mandatory evidence remains a failure, not an assumption.
+- Records numeric targets or thresholds as `未指定` when the project has not supplied them; never invents thresholds to make an output look complete.
+- 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.
 - Indexes final artifacts, closed/open issues, evidence, decisions, and learning candidates.
 - Distinguishes accepted behavior from future improvement ideas.
 
@@ -80,10 +104,16 @@ This file is generated for the installed skill. Read it before executing this sk
 ## Document Anti-Patterns
 
 - Template-shaped filler that does not resolve a decision.
+- Skipping PROJECT-CONFIG.md or SYSTEM-SPEC.md, or treating their project rules as optional suggestions.
 - Untraceable claims such as 'should work', 'best practice', or 'user friendly' without evidence or criteria.
 - Mixing raw source facts, decisions, runtime evidence, and tasks in one undifferentiated section.
 - Skipping unresolved contradictions instead of recording a blocker, risk, or question.
 - Optimizing wording while leaving acceptance, evidence, ownership, or next action ambiguous.
+- Passing because a familiar term appears while the equivalent lifecycle function is absent.
+- Inventing project policy, quality thresholds, source mappings, or platform behavior without configured evidence.
+- Treating missing evidence as low risk when the stage output depends on that evidence.
+- Letting a delayed subagent packet block indefinitely instead of marking it stale and falling back or re-emitting.
+- Claiming tests prove behavior when they have no traceable basis, no meaningful assertion, or only prove implementation details.
 - Archiving chat summaries instead of durable artifact links.
 - Promoting one-off preferences into core rules without review.
 

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

@@ -16,6 +16,16 @@ Default project paths:
 
 Root `docs/`, `.raws/`, `.issues/`, `.playwright/`, and `plans/` are not default write targets for ZSK skills. Use explicit export, promote, import, or migration commands when project-facing root documentation is needed.
 
+## Learning Output Authority
+
+Learning artifacts must be written according to what they are meant to change:
+
+- Project-local learning that only affects the current business/product project may use the current project's `.zsk/learning/proposals/`, created lazily.
+- Reusable ZSK core learning that would change ZSK skills, harness contracts, templates, packs, CLI behavior, defaults, or installer behavior must be written to the canonical ZSK source checkout: `<zsk-core>/.zsk/learning/proposals/`.
+- Resolve `<zsk-core>` from explicit configuration/environment first: `ZSK_LEARNING_REPO`, then `ZSK_CORE_REPO`. If neither is set, the current repository qualifies only when it contains `skills/`, `harness/`, and `packages/cli/`.
+- If no canonical ZSK source checkout is available or writable, do not create a substitute core-learning proposal in the consuming project. Record `BLOCKED` with the missing root, intended proposal title, source evidence, and next action.
+- `zsk init` must not create `.zsk/learning/`; learning directories remain lazy outputs created by `learn` or `archive` only when a concrete proposal is written.
+
 ## Scope Routing Rule
 
 Before any skill writes an artifact, classify its scope: