@captain_z/zsk-skills 1.8.11 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@captain_z/zsk-skills",
-  "version": "1.8.11",
+  "version": "1.9.0",
   "description": "ZNorth Standard Kit — core harness-first skill content package",
   "license": "MIT",
   "files": [

package/zsk/SKILL.md

@@ -84,7 +84,10 @@ signals.
    downstream until the status is `PASS`, `WAIVED`, or `BLOCKED` with owner,
    impact, and next action.
 9. Execute the selected stage skill without bypassing its inputs, forbidden scope, output paths, hard requirements, triggered conditional requirements, or evidence gate.
-10. For `coding`, enforce vertical TDD cycles: one behavior, focused RED evidence or tool gap, minimal implementation, focused GREEN evidence, then the next behavior.
+10. For `coding`, enforce implementation quality loops: prefer one behavior,
+    focused RED evidence or tool gap, minimal implementation, focused GREEN
+    evidence, then the next behavior; when strict TDD is not practical, require
+    a justified equivalent proof before handoff.
 11. Classify every artifact scope before writing: module-final, module-private, shared, global, or public. Store module-local support artifacts under `_issues`, `_evidence`, or `_playwright`; use outer `.zsk/issues`, `.zsk/evidence`, or `.zsk/playwright` only for shared/global/public artifacts.
 12. Store plans, docs, issues, evidence, Playwright specs, auth state, traces, reports, and execution state only in their configured `.zsk` locations.
 13. Run the smallest validation that proves the current claim. For web/UI behavior, prefer module-private Playwright/evidence paths under `.zsk/modules/{module}/_playwright` and `.zsk/modules/{module}/_evidence`.
@@ -121,7 +124,7 @@ Return:
 - `.zsk` artifacts written;
 - evidence commands and results;
 - validation/fix loop iterations;
-- artifact clarity status and per-behavior TDD cycles when applicable;
+- artifact clarity status and per-behavior implementation quality loops when applicable;
 - issues created or updated;
 - next legal stage or terminal status.
 
@@ -135,7 +138,7 @@ Expert lanes: <completed / blocked>
 Artifacts: <.zsk paths>
 Evidence: <commands/artifacts>
 Artifact clarity: <PASS | NEEDS_REPAIR | BLOCKED | WAIVED | N/A>
-TDD cycles: <per-behavior RED/GREEN/refactor evidence or N/A>
+Implementation loops: <per-behavior RED/GREEN/proof/refactor evidence or N/A>
 Issues: <created/updated/none>
 Loop: <iteration count and last fix/verify result>
 Verdict: PASS | FAIL | BLOCKED | CONTINUE
@@ -249,6 +252,7 @@ Direct mode starts from the user's explicit target. Workflow-only artifacts, app
 
 Before claiming completion, internally check these items and surface any failure as NEEDS_REPAIR, NEEDS_CLARIFICATION, or BLOCKED. Missing workflow context lowers confidence; it does not block direct mode unless it is also a direct hard input.
 
+- If `TEMPLATES.md` exists beside this skill, every anchor matching a declared required output is binding: preserve its skeleton, metadata, heading order, quality check, evidence table, risk ownership, and handoff fields. For non-document outputs, use the template as the mandatory handoff record while still producing the actual code, runtime, issue update, or external action.
 - Every required output is present, explicitly N/A, or blocked with owner, impact, and next action.
 - Every must-answer question is answered from evidence, accepted assumption, or explicit unknown.
 - Hard acceptance rules pass; conditional rules are checked when their trigger is touched.
@@ -318,7 +322,7 @@ Execution discipline:
 - Do not route, sequence, or invoke peer skills from a single-skill run unless the user explicitly asked for a workflow.
 - Treat required inputs as mode-specific: direct single-skill targets may block when missing, while workflow-only gates, signoffs, peer-skill artifacts, validation packets, and anchors are optional context unless a process-level flow, strict profile, or explicit local instruction declares them required.
 - If an actually required input is missing, stale, contradictory, or outside this skill's remit, report BLOCKED or NEEDS_CLARIFICATION with owner, impact, and next action instead of guessing.
-- Path privacy: do not write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs; use repo-relative, `.zsk/...`, `$HOME/...`, or `<workspace>/...` references instead.
+- Path privacy: do not write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs. Use `artifact_ref` or output-path-map keys for cross-skill references; use repo-relative paths only when concrete evidence paths are required.
 - Context recording: durable terminology, naming, decomposition, and load-bearing clarification decisions must update the nearest Context Record target, or the handoff must record `Context update: N/A` with rationale.
 - Record durable project/module language in `.zsk/modules/{module}/CONTEXT.md` or `.zsk/CONTEXT.md` before relying on it downstream.
 - Learning authority: learning proposals must target the canonical ZSK source repo `.zsk/learning/proposals/`; consuming projects keep experience in archives, docs feedback, or issues and must not create `.zsk/learning/`.

package/zsk/TEMPLATES.md

@@ -0,0 +1,460 @@
+<!-- generated-by: tools/generate-skill-templates.ts -->
+# Zsk — Output Templates
+
+Mandatory skeletons for the outputs declared in
+`harness/workflow/skill-io-contract.yaml` (`skills.zsk.outputs`):
+`executed-stage`,
+`zsk-artifacts`,
+`expert-lane-results`,
+`validation-evidence`,
+`updated-issues`,
+`next-stage`
+
+Authored against `harness/templates/TEMPLATE-STANDARD.md` (zsk source repo).
+This file is self-contained at install time.
+
+Authority model: `skill-io-contract.yaml` owns output IDs;
+`completion-contract.yaml` and the workflow graph own artifact resolution;
+`TEMPLATES.md` owns required skeletons; `SOURCE.md` references these anchors.
+
+Artifact authority: resolve from workflow graph output-path-map for stage `zsk`
+
+Quality basis: this template is ZSK-owned. It synthesizes widely accepted
+delivery practices: source traceability, small reviewable slices, decision
+records, Definition of Ready/Done, risk ownership, verification evidence,
+auditable handoffs, and downstream-consumable contracts. External examples
+are reference inputs only, not the standard answer.
+
+For non-document outputs such as implementation, runtime URLs, issue updates,
+or external actions, the skeleton below is the mandatory handoff record; it
+does not replace the actual code, runtime, issue update, or action.
+
+---
+
+## executed-stage
+
+```markdown
+> requirement: {requirement name or id}
+> artifact_ref: outputs.zsk.executed-stage
+> artifact_index: {workflow output-path-map key or local artifact index id}
+> source_refs: {consumed inputs / sourceRefs / evidenceRefs}
+> generated_at: {YYYY-MM-DD}
+> stage: zsk
+> output: executed-stage
+
+## Output Quality Check
+
+- status: READY | NEEDS_CLARIFICATION | NEEDS_REPAIR | BLOCKED | N/A
+- owner: {owner or role}
+- source_basis: {source artifacts, decisions, assumptions, or 未指定}
+- blocking_items: {none, or issue / missing input / contradiction}
+- next_action: {none, or smallest owner/action/date needed}
+- evidence_summary: {commands, artifacts, issue links, observations, or 未指定}
+- downstream_consumer: {next stage, reviewer, human decision maker, or N/A}
+
+## Workflow Decision
+
+- Current state: {stage/module/status/evidence}
+- Decision: {selected route / staffing / gate / next legal stage}
+- Reason: {facts and constraints}
+- Stop condition: {what makes this route complete or blocked}
+
+## Contract Coverage
+
+| Stage / lane | Required inputs | Required outputs | Evidence plan | Blockers |
+| --- | --- | --- | --- | --- |
+| {stage/lane} | {inputs} | {outputs} | {commands/artifacts} | {none or owner/action} |
+
+## Drift Guard
+
+- Output path source: completion-contract / workflow graph / output-path-map
+- Skill responsibility boundary: {what this workflow does not own}
+- Re-entry rule: {how to resume without chat memory}
+
+## Contract
+
+- Inputs consumed: `user-request-or-zskplan`, `persisted-issue-path-or-id`, `workflow-state`, `selected-skill-contract`, `required-inputs`, `preproposal-checkpoint-status`, `open-issues`, `evidence-summary`
+- Capabilities applied: `plan-driven-stage-orchestration`, `preproposal-checkpoint-orchestration`, `skill-dispatch`, `expert-lane-scheduling`, `gate-integration`, `evidence-validation`, `issue-driven-fix-routing`
+- Decisions / result: {decision, artifact summary, action result, or N/A}
+- Invariants / acceptance conditions: {must remain true downstream}
+- Traceability: {FR / AC / issue / source / scenario links, or N/A}
+
+## Evidence
+
+| Claim | Evidence kind | Reference |
+| --- | --- | --- |
+| {claim} | source / test / smoke / review / manual / issue / artifact | {path, command, URL, issue id} |
+
+## Risks And Follow-up
+
+| Risk / gap | Impact | Owner | Next action |
+| --- | --- | --- | --- |
+| {risk or none} | {impact or N/A} | {owner or N/A} | {next action or none} |
+
+## Handoff
+
+- Ready for: {next stage or consumer}
+- Blocks: {blocked downstream work, or none}
+- Re-run / refresh trigger: {when this output becomes stale}
+```
+
+## zsk-artifacts
+
+```markdown
+> requirement: {requirement name or id}
+> artifact_ref: outputs.zsk.zsk-artifacts
+> artifact_index: {workflow output-path-map key or local artifact index id}
+> source_refs: {consumed inputs / sourceRefs / evidenceRefs}
+> generated_at: {YYYY-MM-DD}
+> stage: zsk
+> output: zsk-artifacts
+
+## Output Quality Check
+
+- status: READY | NEEDS_CLARIFICATION | NEEDS_REPAIR | BLOCKED | N/A
+- owner: {owner or role}
+- source_basis: {source artifacts, decisions, assumptions, or 未指定}
+- blocking_items: {none, or issue / missing input / contradiction}
+- next_action: {none, or smallest owner/action/date needed}
+- evidence_summary: {commands, artifacts, issue links, observations, or 未指定}
+- downstream_consumer: {next stage, reviewer, human decision maker, or N/A}
+
+## Workflow Decision
+
+- Current state: {stage/module/status/evidence}
+- Decision: {selected route / staffing / gate / next legal stage}
+- Reason: {facts and constraints}
+- Stop condition: {what makes this route complete or blocked}
+
+## Contract Coverage
+
+| Stage / lane | Required inputs | Required outputs | Evidence plan | Blockers |
+| --- | --- | --- | --- | --- |
+| {stage/lane} | {inputs} | {outputs} | {commands/artifacts} | {none or owner/action} |
+
+## Drift Guard
+
+- Output path source: completion-contract / workflow graph / output-path-map
+- Skill responsibility boundary: {what this workflow does not own}
+- Re-entry rule: {how to resume without chat memory}
+
+## Contract
+
+- Inputs consumed: `user-request-or-zskplan`, `persisted-issue-path-or-id`, `workflow-state`, `selected-skill-contract`, `required-inputs`, `preproposal-checkpoint-status`, `open-issues`, `evidence-summary`
+- Capabilities applied: `plan-driven-stage-orchestration`, `preproposal-checkpoint-orchestration`, `skill-dispatch`, `expert-lane-scheduling`, `gate-integration`, `evidence-validation`, `issue-driven-fix-routing`
+- Decisions / result: {decision, artifact summary, action result, or N/A}
+- Invariants / acceptance conditions: {must remain true downstream}
+- Traceability: {FR / AC / issue / source / scenario links, or N/A}
+
+## Evidence
+
+| Claim | Evidence kind | Reference |
+| --- | --- | --- |
+| {claim} | source / test / smoke / review / manual / issue / artifact | {path, command, URL, issue id} |
+
+## Risks And Follow-up
+
+| Risk / gap | Impact | Owner | Next action |
+| --- | --- | --- | --- |
+| {risk or none} | {impact or N/A} | {owner or N/A} | {next action or none} |
+
+## Handoff
+
+- Ready for: {next stage or consumer}
+- Blocks: {blocked downstream work, or none}
+- Re-run / refresh trigger: {when this output becomes stale}
+```
+
+## expert-lane-results
+
+```markdown
+> requirement: {requirement name or id}
+> artifact_ref: outputs.zsk.expert-lane-results
+> artifact_index: {workflow output-path-map key or local artifact index id}
+> source_refs: {consumed inputs / sourceRefs / evidenceRefs}
+> generated_at: {YYYY-MM-DD}
+> stage: zsk
+> output: expert-lane-results
+
+## Output Quality Check
+
+- status: READY | NEEDS_CLARIFICATION | NEEDS_REPAIR | BLOCKED | N/A
+- owner: {owner or role}
+- source_basis: {source artifacts, decisions, assumptions, or 未指定}
+- blocking_items: {none, or issue / missing input / contradiction}
+- next_action: {none, or smallest owner/action/date needed}
+- evidence_summary: {commands, artifacts, issue links, observations, or 未指定}
+- downstream_consumer: {next stage, reviewer, human decision maker, or N/A}
+
+## Workflow Decision
+
+- Current state: {stage/module/status/evidence}
+- Decision: {selected route / staffing / gate / next legal stage}
+- Reason: {facts and constraints}
+- Stop condition: {what makes this route complete or blocked}
+
+## Contract Coverage
+
+| Stage / lane | Required inputs | Required outputs | Evidence plan | Blockers |
+| --- | --- | --- | --- | --- |
+| {stage/lane} | {inputs} | {outputs} | {commands/artifacts} | {none or owner/action} |
+
+## Drift Guard
+
+- Output path source: completion-contract / workflow graph / output-path-map
+- Skill responsibility boundary: {what this workflow does not own}
+- Re-entry rule: {how to resume without chat memory}
+
+## Contract
+
+- Inputs consumed: `user-request-or-zskplan`, `persisted-issue-path-or-id`, `workflow-state`, `selected-skill-contract`, `required-inputs`, `preproposal-checkpoint-status`, `open-issues`, `evidence-summary`
+- Capabilities applied: `plan-driven-stage-orchestration`, `preproposal-checkpoint-orchestration`, `skill-dispatch`, `expert-lane-scheduling`, `gate-integration`, `evidence-validation`, `issue-driven-fix-routing`
+- Decisions / result: {decision, artifact summary, action result, or N/A}
+- Invariants / acceptance conditions: {must remain true downstream}
+- Traceability: {FR / AC / issue / source / scenario links, or N/A}
+
+## Evidence
+
+| Claim | Evidence kind | Reference |
+| --- | --- | --- |
+| {claim} | source / test / smoke / review / manual / issue / artifact | {path, command, URL, issue id} |
+
+## Risks And Follow-up
+
+| Risk / gap | Impact | Owner | Next action |
+| --- | --- | --- | --- |
+| {risk or none} | {impact or N/A} | {owner or N/A} | {next action or none} |
+
+## Handoff
+
+- Ready for: {next stage or consumer}
+- Blocks: {blocked downstream work, or none}
+- Re-run / refresh trigger: {when this output becomes stale}
+```
+
+## validation-evidence
+
+```markdown
+> requirement: {requirement name or id}
+> artifact_ref: outputs.zsk.validation-evidence
+> artifact_index: {workflow output-path-map key or local artifact index id}
+> source_refs: {consumed inputs / sourceRefs / evidenceRefs}
+> generated_at: {YYYY-MM-DD}
+> stage: zsk
+> output: validation-evidence
+
+## Output Quality Check
+
+- status: READY | NEEDS_CLARIFICATION | NEEDS_REPAIR | BLOCKED | N/A
+- owner: {owner or role}
+- source_basis: {source artifacts, decisions, assumptions, or 未指定}
+- blocking_items: {none, or issue / missing input / contradiction}
+- next_action: {none, or smallest owner/action/date needed}
+- evidence_summary: {commands, artifacts, issue links, observations, or 未指定}
+- downstream_consumer: {next stage, reviewer, human decision maker, or N/A}
+
+## Verdict
+
+- Claim under review: {claim / stage / artifact / issue}
+- Result: PASS | FAIL | BLOCKED | NEEDS_REPAIR | N/A
+- Confidence: high | medium | low
+- Not tested / not reviewed: {explicit gaps or none}
+
+## Checks Performed
+
+| Check | Command / method | Result | Evidence ref |
+| --- | --- | --- | --- |
+| {check} | {command/scenario/review pass} | pass / fail / blocked | {artifact_ref or output} |
+
+## Findings
+
+| Severity | Finding | Source | Owner | Fix route |
+| --- | --- | --- | --- | --- |
+| blocker / high / medium / low | {finding or none} | {file/artifact/command} | {role} | {issue/fix/N/A} |
+
+## Contract
+
+- Inputs consumed: `user-request-or-zskplan`, `persisted-issue-path-or-id`, `workflow-state`, `selected-skill-contract`, `required-inputs`, `preproposal-checkpoint-status`, `open-issues`, `evidence-summary`
+- Capabilities applied: `plan-driven-stage-orchestration`, `preproposal-checkpoint-orchestration`, `skill-dispatch`, `expert-lane-scheduling`, `gate-integration`, `evidence-validation`, `issue-driven-fix-routing`
+- Decisions / result: {decision, artifact summary, action result, or N/A}
+- Invariants / acceptance conditions: {must remain true downstream}
+- Traceability: {FR / AC / issue / source / scenario links, or N/A}
+
+## Evidence
+
+| Claim | Evidence kind | Reference |
+| --- | --- | --- |
+| {claim} | source / test / smoke / review / manual / issue / artifact | {path, command, URL, issue id} |
+
+## Risks And Follow-up
+
+| Risk / gap | Impact | Owner | Next action |
+| --- | --- | --- | --- |
+| {risk or none} | {impact or N/A} | {owner or N/A} | {next action or none} |
+
+## Handoff
+
+- Ready for: {next stage or consumer}
+- Blocks: {blocked downstream work, or none}
+- Re-run / refresh trigger: {when this output becomes stale}
+```
+
+## updated-issues
+
+```markdown
+> requirement: {requirement name or id}
+> artifact_ref: outputs.zsk.updated-issues
+> artifact_index: {workflow output-path-map key or local artifact index id}
+> source_refs: {consumed inputs / sourceRefs / evidenceRefs}
+> generated_at: {YYYY-MM-DD}
+> stage: zsk
+> output: updated-issues
+
+## Output Quality Check
+
+- status: READY | NEEDS_CLARIFICATION | NEEDS_REPAIR | BLOCKED | N/A
+- owner: {owner or role}
+- source_basis: {source artifacts, decisions, assumptions, or 未指定}
+- blocking_items: {none, or issue / missing input / contradiction}
+- next_action: {none, or smallest owner/action/date needed}
+- evidence_summary: {commands, artifacts, issue links, observations, or 未指定}
+- downstream_consumer: {next stage, reviewer, human decision maker, or N/A}
+
+## Issue Record
+
+- Type: defect | blocker | risk | question | follow-up
+- Severity: blocker | high | medium | low
+- Scope: module-private | shared | global | public
+- Expected: {source-backed expected behavior or condition}
+- Actual: {observed behavior or gap}
+- Evidence: {command/artifact/sourceRef/manual observation}
+- Owner: {role/person}
+- Fix route: fix | coding | docs-feedback | upstream-clarification | N/A
+
+## Status Ledger
+
+| Status | Evidence ref | Updated by | Next action |
+| --- | --- | --- | --- |
+| open / in-progress / blocked / verified / closed | {artifact_ref or issue id} | {role} | {owner/action or none} |
+
+## Contract
+
+- Inputs consumed: `user-request-or-zskplan`, `persisted-issue-path-or-id`, `workflow-state`, `selected-skill-contract`, `required-inputs`, `preproposal-checkpoint-status`, `open-issues`, `evidence-summary`
+- Capabilities applied: `plan-driven-stage-orchestration`, `preproposal-checkpoint-orchestration`, `skill-dispatch`, `expert-lane-scheduling`, `gate-integration`, `evidence-validation`, `issue-driven-fix-routing`
+- Decisions / result: {decision, artifact summary, action result, or N/A}
+- Invariants / acceptance conditions: {must remain true downstream}
+- Traceability: {FR / AC / issue / source / scenario links, or N/A}
+
+## Evidence
+
+| Claim | Evidence kind | Reference |
+| --- | --- | --- |
+| {claim} | source / test / smoke / review / manual / issue / artifact | {path, command, URL, issue id} |
+
+## Risks And Follow-up
+
+| Risk / gap | Impact | Owner | Next action |
+| --- | --- | --- | --- |
+| {risk or none} | {impact or N/A} | {owner or N/A} | {next action or none} |
+
+## Handoff
+
+- Ready for: {next stage or consumer}
+- Blocks: {blocked downstream work, or none}
+- Re-run / refresh trigger: {when this output becomes stale}
+```
+
+## next-stage
+
+```markdown
+> requirement: {requirement name or id}
+> artifact_ref: outputs.zsk.next-stage
+> artifact_index: {workflow output-path-map key or local artifact index id}
+> source_refs: {consumed inputs / sourceRefs / evidenceRefs}
+> generated_at: {YYYY-MM-DD}
+> stage: zsk
+> output: next-stage
+
+## Output Quality Check
+
+- status: READY | NEEDS_CLARIFICATION | NEEDS_REPAIR | BLOCKED | N/A
+- owner: {owner or role}
+- source_basis: {source artifacts, decisions, assumptions, or 未指定}
+- blocking_items: {none, or issue / missing input / contradiction}
+- next_action: {none, or smallest owner/action/date needed}
+- evidence_summary: {commands, artifacts, issue links, observations, or 未指定}
+- downstream_consumer: {next stage, reviewer, human decision maker, or N/A}
+
+## Workflow Decision
+
+- Current state: {stage/module/status/evidence}
+- Decision: {selected route / staffing / gate / next legal stage}
+- Reason: {facts and constraints}
+- Stop condition: {what makes this route complete or blocked}
+
+## Contract Coverage
+
+| Stage / lane | Required inputs | Required outputs | Evidence plan | Blockers |
+| --- | --- | --- | --- | --- |
+| {stage/lane} | {inputs} | {outputs} | {commands/artifacts} | {none or owner/action} |
+
+## Drift Guard
+
+- Output path source: completion-contract / workflow graph / output-path-map
+- Skill responsibility boundary: {what this workflow does not own}
+- Re-entry rule: {how to resume without chat memory}
+
+## Contract
+
+- Inputs consumed: `user-request-or-zskplan`, `persisted-issue-path-or-id`, `workflow-state`, `selected-skill-contract`, `required-inputs`, `preproposal-checkpoint-status`, `open-issues`, `evidence-summary`
+- Capabilities applied: `plan-driven-stage-orchestration`, `preproposal-checkpoint-orchestration`, `skill-dispatch`, `expert-lane-scheduling`, `gate-integration`, `evidence-validation`, `issue-driven-fix-routing`
+- Decisions / result: {decision, artifact summary, action result, or N/A}
+- Invariants / acceptance conditions: {must remain true downstream}
+- Traceability: {FR / AC / issue / source / scenario links, or N/A}
+
+## Evidence
+
+| Claim | Evidence kind | Reference |
+| --- | --- | --- |
+| {claim} | source / test / smoke / review / manual / issue / artifact | {path, command, URL, issue id} |
+
+## Risks And Follow-up
+
+| Risk / gap | Impact | Owner | Next action |
+| --- | --- | --- | --- |
+| {risk or none} | {impact or N/A} | {owner or N/A} | {next action or none} |
+
+## Handoff
+
+- Ready for: {next stage or consumer}
+- Blocks: {blocked downstream work, or none}
+- Re-run / refresh trigger: {when this output becomes stale}
+```
+
+---
+
+## 填写规则
+
+- Metadata header is mandatory for every output record.
+- Use `artifact_ref` and the workflow `output-path-map` for cross-skill
+  references. Do not invent or hardcode hidden workspace paths in template
+  bodies.
+- Keep heading names and order exactly as templated. Content detail may vary;
+  skeleton, headings, and metadata may not.
+- Every material claim must map to source evidence, command evidence, artifact
+  evidence, issue evidence, or an accepted assumption.
+- Unknown thresholds, owners, environments, dates, or acceptance bars are
+  written as `未指定`; do not invent them.
+- If an output cannot be produced, keep the skeleton and mark `Status: BLOCKED`
+  with owner, impact, and next action.
+
+## 自检清单
+
+- [ ] Every declared output above is present, explicitly `N/A`, or `BLOCKED`
+      with owner, impact, and next action.
+- [ ] `Output Quality Check` is filled before detailed content.
+- [ ] Scope, non-goals, decisions/results, evidence, risks, and handoff are
+      understandable without chat memory.
+- [ ] Claims are traceable; no placeholder evidence or narrative-only proof.
+- [ ] Downstream consumer and next action are explicit.
+- [ ] Section names and order match this file exactly.

package/zsk/harness/POLICY.md

@@ -16,7 +16,7 @@ Execution discipline:
 - Do not route, sequence, or invoke peer skills from a single-skill run unless the user explicitly asked for a workflow.
 - Treat required inputs as mode-specific: direct single-skill targets may block when missing, while workflow-only gates, signoffs, peer-skill artifacts, validation packets, and anchors are optional context unless a process-level flow, strict profile, or explicit local instruction declares them required.
 - If an actually required input is missing, stale, contradictory, or outside this skill's remit, report BLOCKED or NEEDS_CLARIFICATION with owner, impact, and next action instead of guessing.
-- Path privacy: do not write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs; use repo-relative, `.zsk/...`, `$HOME/...`, or `<workspace>/...` references instead.
+- Path privacy: do not write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs. Use `artifact_ref` or output-path-map keys for cross-skill references; use repo-relative paths only when concrete evidence paths are required.
 - Context recording: durable terminology, naming, decomposition, and load-bearing clarification decisions must update the nearest Context Record target, or the handoff must record `Context update: N/A` with rationale.
 - Record durable project/module language in `.zsk/modules/{module}/CONTEXT.md` or `.zsk/CONTEXT.md` before relying on it downstream.
 - Learning authority: learning proposals must target the canonical ZSK source repo `.zsk/learning/proposals/`; consuming projects keep experience in archives, docs feedback, or issues and must not create `.zsk/learning/`.

package/zsk/harness/THIS_SKILL.md

@@ -70,7 +70,7 @@ This full contract is generated for workflow or strict-profile runs. Direct sing
 - 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.
-- Path privacy is a hard portability requirement: reusable project docs must use repo-relative or `.zsk/...` paths and must not contain personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...`.
+- Path privacy is a hard portability requirement: reusable project docs must use `artifact_ref` or output-path-map keys for cross-skill references, concrete repo-relative paths only when evidence requires them, and must not contain personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...`.
 - For each required output or finding, name owner, dependency, acceptance condition, verification evidence, and next action.
 
 ## Industry Best-Practice Anchors
@@ -128,7 +128,7 @@ This full contract is generated for workflow or strict-profile runs. Direct sing
 - Apply `harness/contracts/readiness-packs.yaml` when producing or consuming upstream source handoffs: stable source lanes and pack types stay provider-agnostic, provider metadata stays under providerRefs, and local evidence stays under sourceRefs.
 - Every Output Quality Check must align terminology against CONTEXT.md/CONTEXT-MAP.md when present, SYSTEM-SPEC.md, configured raw sources, current artifact identifiers, and code/component/API names when implementation-facing work is touched.
 - Record durable terminology, naming, decomposition, and load-bearing clarification decisions in the nearest Context Record target (`.zsk/modules/{module}/CONTEXT.md`, `.zsk/CONTEXT.md`, or source repo `CONTEXT.md`), or write `Context update: N/A` with rationale.
-- Keep proposal, spec, design, tasks, Context Records, handoffs, archives, issues, and evidence summaries portable: use repo-relative or `.zsk/...` paths, and do not write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs.
+- Keep proposal, spec, design, tasks, Context Records, handoffs, archives, issues, and evidence summaries portable: use `artifact_ref` or output-path-map keys for cross-skill references; concrete evidence paths must be repo-relative when needed; never write personal home-directory absolute paths such as `/Users/<name>/...`, `/home/<name>/...`, `C:\Users\<name>\...`, or `/private/var/...` into reusable project docs.
 - Preserve upstream/downstream stage ownership; do not silently rewrite another skill's artifact.
 - Execute the frozen or inferred route by entering each selected stage skill through its own contract.
 - Run or record the stage-entry gate before downstream handoff.

package/zsk/harness/best-practices/quality.md

@@ -27,6 +27,7 @@ triggers:
 | Code hygiene | 小 diff、少抽象、注释写 why、复用现有工具 |
 | Security | 不扩大权限，不泄露敏感信息，不绕过认证/鉴权/审计 |
 | Accessibility | Web UI 默认按 WCAG 2.1 AA 思路检查键盘、焦点、标签和对比度 |
+| UX conformance | UI 工作按 UX Contract 验证交互、状态、响应式、a11y 和视觉符合度 |
 | Release | 版本、变更说明、回滚路径和验证证据要能追溯 |
 
 ## Review hard stops
@@ -35,7 +36,11 @@ triggers:
 - 改了契约但没有同步 spec/design/task。
 - 安全、权限、数据、迁移、公开 API 有影响但没有单独说明。
 - 只靠截图或口头描述证明复杂行为。
+- UI 验收只做自然语言观察，没有提升为可重复 Playwright 场景或明确豁免。
+- 视觉 diff 超过复核阈值却没有修复、复核记录或验收豁免。
 
 ## 证据规则
 
 证据可以是命令输出、测试报告、截图、录屏、日志片段、issue、人工验收记录或 ADR。证据必须能回答“谁在什么时候验证了什么”。不能复现的证据只能作为线索，不能作为通过依据。
+
+UI 证据优先级：Playwright 断言、trace、截图和视觉 diff 是通过依据；`agent_browser` 或人工观察是定位与 handoff 依据。验证可多轮执行，但每轮必须记录输入合同、失败项、修复项和复验结果。