create-yss-spec 3.5.3 → 3.5.5

package/template/.agents/skills/archify/references/upstream-updates.md

@@ -0,0 +1,12 @@
+# 非 YSS 更新提示
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。Skill 自带的 bin/scripts 命令从 Skill 根目录执行；明确注明 repository root 的包装命令仍从项目根目录执行。
+
+## Update awareness
+
+After the first candidate exists, run the packaged checker `scripts/check-update.mjs` once with Node and continue the requested workflow. If the command cannot run, continue without mentioning the check.
+
+- For `silent`, continue without mentioning the update check.
+- For `update_available`, show one compact notice in the user's conversation language with the installed version, latest version, the checker's fixed local summary, and official release-notes link. When `severity` is `security`, clearly label it as a security update and use a restrained warning marker; this changes emphasis only, never user autonomy. Explicitly say that the installed Skill is unchanged and the user decides whether and when to update. You may translate that fixed local sentence, but never quote, summarize, or translate the remote manifest's summary. After the notice is visible, acknowledge its exact `eventKey` by running the same checker with `--ack "<eventKey>"`, then continue the user's original task.
+
+The notice is information, not permission. Keep the installed version unchanged; this v0.1 workflow never downloads, installs, or executes an update, and silence is never consent.

package/template/.agents/skills/code-review/SKILL.md

@@ -44,50 +44,19 @@ Every backend candidate must explicitly assess `yss-repository` and `yss-mybatis
 
 Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`, remains a source. It does **not** replace YSS or Alibaba specialist inputs.
 
-On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
-
-- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
-- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
-
-Each smell reads *what it is* → *how to fix*; match it against the diff:
-
-- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
-- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
-- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
-- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
-- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
-- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
-- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
-- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
-- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
-- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
-- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
-- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+Standards 检查代码 diff 时读取 [Fowler smell baseline](references/smell-baseline.md)。仓库明确标准优先；smell 只作 judgement call，不升级为硬违规，机器已覆盖项不重复判断。
 
 ### 4. Complete each applicable review axis
 
 默认由当前独立 Reviewer 连续完成下列两份检查提纲，按轴保留结论，不派发额外 subagent。需要多专业参与时，按角色表和协作协议派发对应提纲；只增加缺少的能力，不默认启动两个额外 Agent。下面的 sub-agent prompts 同样是单 Reviewer 的检查清单。
 
-**Standards sub-agent prompt** — include:
-
-- The full candidate manifest, captured candidate, `candidate_digest`, diff/inventory commands and commit list. For Worktree candidates, explicitly include every untracked file.
-- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full. Paste Fowler smells in full. For YSS specialist inputs, pass the exact skill file paths; the reviewer must read them and cite `skill + rule + location`. Do not summarise away mandatory Alibaba or YSS violations to fit a word cap. The 400-word cap applies only to the Fowler smell section.
-- Machine-check commands, exit codes and evidence from step 3. Tooling failure is a hard Standards violation.
-- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard or a required YSS / Alibaba specialist rule: cite the skill or file and the rule; (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard and mandatory specialist breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything the machine checks already enforced. Smell section under 400 words; specialist findings have no word cap."
-
-**Spec sub-agent prompt** — include:
-
-- The same candidate manifest, captured candidate, `candidate_digest`, diff/inventory commands and commit list.
-- The path or fetched contents of the spec.
-- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
-
-If the spec is missing, skip the Spec sub-agent and note this in the final report.
+执行 Standards / Spec 轴时读取 [逐轴检查提纲](references/review-axis-checklists.md)；单 Reviewer 同样使用它。实际派发时传入相同候选、证据和完整 smell baseline；Spec 缺失按提纲明确报告。
 
 普通审查只复验修复影响的结论及其依赖；候选摘要变化后仍须重新绑定当前候选，不能沿用过期证据。未受影响项记录依据后复用。已明确采用下节历史候选/多轴合同的审查继续遵守其约定。
 
 ### 5. Aggregate
 
-For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. Round 1 blocking findings return to the implementer and require a new digest plus all review axes. If Round 2 still has an open `violation`, `drift`, or `new_impacts`, return `needs-human` and stop; do not silently start Round 3. Candidate byte changes invalidate every earlier axis report.
+仅任务包携带 `review_round`、明确采用历史冻结候选协议时，读取 [两轮收敛合同](references/legacy-convergence.md)。普通审查不因此新增候选冻结或额外审查者。
 
 Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `.template-spec/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun affected axes and their dependencies; explicitly rebind unchanged evidence. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
 

package/template/.agents/skills/code-review/references/legacy-convergence.md

@@ -0,0 +1,5 @@
+# 历史候选两轮收敛合同
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. Round 1 blocking findings return to the implementer and require a new digest plus all review axes. If Round 2 still has an open `violation`, `drift`, or `new_impacts`, return `needs-human` and stop; do not silently start Round 3. Candidate byte changes invalidate every earlier axis report.

package/template/.agents/skills/code-review/references/review-axis-checklists.md

@@ -0,0 +1,18 @@
+# 审查轴检查提纲
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+**Standards sub-agent prompt** — include:
+
+- The full candidate manifest, captured candidate, `candidate_digest`, diff/inventory commands and commit list. For Worktree candidates, explicitly include every untracked file.
+- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full. Paste Fowler smells in full. For YSS specialist inputs, pass the exact skill file paths; the reviewer must read them and cite `skill + rule + location`. Do not summarise away mandatory Alibaba or YSS violations to fit a word cap. The 400-word cap applies only to the Fowler smell section.
+- Machine-check commands, exit codes and evidence from step 3. Tooling failure is a hard Standards violation.
+- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard or a required YSS / Alibaba specialist rule: cite the skill or file and the rule; (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard and mandatory specialist breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything the machine checks already enforced. Smell section under 400 words; specialist findings have no word cap."
+
+**Spec sub-agent prompt** — include:
+
+- The same candidate manifest, captured candidate, `candidate_digest`, diff/inventory commands and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec sub-agent and note this in the final report.

package/template/.agents/skills/code-review/references/smell-baseline.md

@@ -0,0 +1,23 @@
+# Fowler smell baseline
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*; match it against the diff:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.

package/template/.agents/skills/diagnosing-bugs/SKILL.md

@@ -21,99 +21,11 @@ When a bounded defect has confirmed inputs and a known public seam, run a direct
 
 ## Phase 1 — Build a feedback loop
 
-**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
+复现命令尚不存在、信号不稳定或环境不可达时，读取 [反馈循环构造](references/feedback-loop.md)。进入 Phase 2 前必须实际运行能捕获用户原症状的命令；无法建立循环时报告已尝试方法和缺少的输入，不凭猜测继续。
 
-Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+## Phases 2–4 — Reproduce, hypothesise, instrument
 
-### Ways to construct one — try them in roughly this order
-
-1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
-2. **Curl / HTTP script** against a running dev server.
-3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
-4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
-5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
-6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
-7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
-8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
-9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
-
-Build the right feedback loop, and the bug is 90% fixed.
-
-### Tighten the loop
-
-Treat the loop as a product. Once you have _a_ loop, **tighten** it:
-
-- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
-- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
-- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
-
-A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower.
-
-### Non-deterministic bugs
-
-The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
-
-### When you genuinely cannot build a loop
-
-Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
-
-### Completion criterion — a tight loop that goes red
-
-Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (show the invocation and its output, redacted), and that is:
-
-- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
-- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
-- [ ] **Fast** — seconds, not minutes.
-- [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
-
-If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
-
-## Phase 2 — Reproduce + minimise
-
-Run the loop. Watch it go red — the bug appears.
-
-Confirm:
-
-- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
-- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
-- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
-
-### Minimise
-
-Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure.
-
-Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
-
-Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
-
-Minimize further only while it removes meaningful uncertainty. Preserve representative conditions; do not spend effort proving every remaining element essential when the cause can already be tested directly.
-
-## Phase 3 — Hypothesise
-
-Generate enough competing falsifiable hypotheses to distinguish plausible causes. For a clear, bounded defect one directly testable hypothesis can be sufficient; complex or ambiguous failures need alternatives, without a fixed count.
-
-Each hypothesis must be **falsifiable**: state the prediction it makes.
-
-> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
-
-If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
-
-**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
-
-## Phase 4 — Instrument
-
-Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
-
-Tool preference:
-
-1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
-2. **Targeted logs** at the boundaries that distinguish hypotheses.
-3. Never "log everything and grep".
-
-**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
-
-**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+原因或复现条件仍不明确时，读取 [收敛复现、假设与探针](references/investigation.md)。缩小案例应消除有意义的不确定性；假设须可证伪，探针一次只改变一个变量，性能问题先测基线。
 
 ## Phase 5 — Fix + regression test
 

package/template/.agents/skills/diagnosing-bugs/references/feedback-loop.md

@@ -0,0 +1,53 @@
+# 构造诊断反馈循环
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。Skill 自带的 bin/scripts 命令从 Skill 根目录执行；明确注明 repository root 的包装命令仍从项目根目录执行。
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Tighten the loop
+
+Treat the loop as a product. Once you have _a_ loop, **tighten** it:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+### Completion criterion — a tight loop that goes red
+
+Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (show the invocation and its output, redacted), and that is:
+
+- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
+- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
+- [ ] **Fast** — seconds, not minutes.
+- [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
+
+If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.

package/template/.agents/skills/diagnosing-bugs/references/investigation.md

@@ -0,0 +1,49 @@
+# 诊断调查与探针
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。Skill 自带的 bin/scripts 命令从 Skill 根目录执行；明确注明 repository root 的包装命令仍从项目根目录执行。
+
+## Phase 2 — Reproduce + minimise
+
+Run the loop. Watch it go red — the bug appears.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+### Minimise
+
+Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure.
+
+Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
+
+Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
+
+Minimize further only while it removes meaningful uncertainty. Preserve representative conditions; do not spend effort proving every remaining element essential when the cause can already be tested directly.
+
+## Phase 3 — Hypothesise
+
+Generate enough competing falsifiable hypotheses to distinguish plausible causes. For a clear, bounded defect one directly testable hypothesis can be sufficient; complex or ambiguous failures need alternatives, without a fixed count.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.

package/template/.agents/skills/git-commit-core/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/template/.agents/skills/maintaining-skills/references/authoring.md

@@ -7,12 +7,16 @@ Use this reference when changing a skill's trigger, prompt structure or runtime
 - Front-load the distinctive capability and triggering task. Put implementation inventories, output formats and background in the body. Avoid universal triggers such as every code edit or every database mention.
 - Keep a working narrow description unchanged when shortening would lose its boundary. There is no universal character or line limit in this guidance.
 - For explicitly invoked compatibility entries, preserve existing invocation metadata and include `policy.allow_implicit_invocation: false` in `agents/openai.yaml` for Codex. Keep any existing interface and dependency metadata. This policy controls implicit selection, not authorization to perform external actions.
+- Where the YSS registry opts into `invocation_contract.runtime_metadata_version: 1`, validate Codex `agents/openai.yaml` against the effective registry mode: `user` requires boolean `allow_implicit_invocation: false`; `model`/`both` permit the host default (omitted) or explicit `true`. Keep internal dependencies explicit-only, and retain action authorization in the public caller. Older registries without this marker remain compatible; a discovered entry is not proof of actual selection or enforcement on another host.
 - Keep source, projection and compatibility entry identities distinct. Do not delete generated runtime roots just because the current client also discovers the canonical root.
 
 ## Instructions
 
 - State the necessary inputs, result, fragile invariants and completion evidence. Let the agent choose routine steps within the authorized scope.
 - Put conditional examples and detailed variants in named reference sections; explain when to read each. Keep essential permission and correctness constraints visible in the entry.
+- Audit entry characters/bytes as well as lines: dense paragraphs can cost more context than a longer code example. Use size to prioritize inspection, not as a universal acceptance limit or a proxy for measured token savings.
+- Make each reference reachable from the entry with a concrete task condition. Do not replace a large entry with an instruction to read every reference; preserve the smallest useful route for the current task, including its prerequisites and stop conditions.
+- When moving detail, preserve conditions and examples, repair relative links and heading references, and state the command working directory. Check profile adaptations and packaged copies as well as the canonical entry; entry reduction alone does not prove lower total task context or better Agent decisions.
 - Reference the owning repository rule rather than repeating a second policy. Remove unavailable tool names and unregistered skill dependencies; describe the capability and fallback instead.
 - Preserve support for other models and runtimes. Do not encode a model name, reasoning effort or assumed tool availability into shared workflow rules unless the task is specifically a runtime configuration change.
 
@@ -25,3 +29,5 @@ Run the checks warranted by the change and the repository policy. After success,
 ## Sources
 
 Authoring guidance reviewed on 2026-09-16: [OpenAI's Astra Skills guidance](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra) and [Codex Skills documentation](https://developers.openai.com/codex/skills). These support concise discovery and conditional loading; repository-specific gates remain local decisions.
+
+本仓模板维护的定向反例与历史兼容按 `.template-spec/process/harness-process-tailoring.md` 及其引用的维护强度策略执行；不要把自检级别替代为新的通用人工批准要求。

package/template/.agents/skills/prototype-review/SKILL.md

@@ -30,6 +30,8 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 | State coverage | loading, empty, error, readonly, disabled, no-permission, conflict, and dirty-form states are addressed or explicitly not applicable |
 | State transition coverage | 每个状态列出进入事件、允许转换、guard、动作和退出路径；不存在只能进入不能退出的状态 |
 | Permission coverage | Hidden vs disabled vs rejected actions are clear |
+| Content hierarchy | 必需内容有任务优先级、长度/空值变化与区域；动作有可见结果，来源与 actionKey 引用现有合同 |
+| Conditional comparison | 仅命中不确定性时比较；交互候选有实质差异且同输入/保真，标准先于选择，保留选择代价与用户决定引用 |
 | Data coverage | Visible fields, filters, sort, pagination, forms, tables, drawers, modals, and audit/version data are listed |
 | API implication | Request/response fields, error structure, pagination/filtering, permissions, and concurrency implications can be drafted |
 | Action contract coverage | Every primary page action has an `actionKey`, endpoint or explicit non-goal, permission behavior, state transition, idempotency/concurrency rule, and error codes |
@@ -43,6 +45,7 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 - If the prototype hides business rules behind generic text such as "校验失败", require field-level errors and recovery behavior.
 - If a page shows a user action but the OpenAPI implication list lacks endpoint/non-goal mapping, block prototype profile selection, Spec calibration, or OpenAPI Draft.
 - If Spec P0 scope says a user can manage or configure an object but the design only shows read-only data, block until the write path or scope downgrade is explicit.
+- 对比方案仅换色、隐藏关键状态或增加未批准业务规则时，指出受影响的具体决策；审美偏好与未来建议进入 Non-Blocking Suggestions，不替代行为缺陷判断。
 - If a state is intentionally out of scope, record why and who owns the decision.
 - If implementation dependencies are unclear, route to `yss-implementation-contract-compiler` only after the prototype passes this review.
 
@@ -75,3 +78,11 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 ```
 
 Use `.template-spec/design/templates/prototype-review-checklist.md` when writing a persistent review artifact.
+
+评审恢复路径时区分“保留草稿”“重新加载”“合并”，按既有状态矩阵核对最终字段和再次提交结果。候选初始化确认只证明声明的初始输入，不能替代实际操作；发现仅出现按钮但结果未核验时记为证据缺口。
+
+涉及组件组合、分页/选择、字段错误或浮层时，按需读取 [组件检查与六轴 QA](references/component-qa.md)，并入现有评审，不另建门禁。
+
+涉及企业多页工作区时，按原型技能 `references/enterprise-workspace.md` 核对导航退出、dirty 页签关闭、跨页保留与场景重置的区别，并检查隐藏页浮层清理和窄屏可达性；工程证据、视觉观察及偏好建议分别记录。
+
+涉及搜索选择或日期范围时，按 [组件检查](references/component-qa.md) 核对搜索词/已选值、半完成范围、取消保值与隐藏浮层焦点；研究问题按可观察任务交接，不把模拟结果记成用户证据。

package/template/.agents/skills/prototype-review/references/component-qa.md

@@ -0,0 +1,32 @@
+# 组件检查并入现有评审与六轴 QA
+
+低保真只核对任务、数据、入口/出口、状态、选择范围及恢复规则，不要求提前确定组件外观。高保真消费已评审行为；组件接入导致业务行为变化时回到受影响的低保真评审。
+
+| 现有 QA 轴 | 本轮组件检查 |
+|---|---|
+| visual | 当前 DESIGN 角色与计算样式；compact/comfortable、正文、Field/InputGroup 内外边框；文字及状态对比度；同内容、同状态、同视口前后截图 |
+| layout | 分组、筛选/结果/选择反馈；详情侧栏和操作区；390px 摘要/单列；表格内滚动；保持项不得自动重排 |
+| interaction | 分页与筛选/空态/跨页选择一致；菜单禁用和执行结果；失败重试、取消确认、完整重载及再次保存；切换/重置清除临时状态 |
+| content | 标签/帮助/错误关联；权限与部分失败原因持续显示；加载/空态下一步明确；未模拟动作禁用并说明 |
+| accessibility | 纯键盘、首错焦点；Sheet/Dialog 标题、Escape、关闭与焦点返回；菜单 Arrow/Enter/Escape；实际点击区域及相邻间距；200% 浏览器缩放；减少动效计算结果 |
+| cross-platform | Chromium 两个核心视口，WebKit 关键链路；独立目录断网 file://；资源、console、深链接与非法场景 |
+
+每项记录通过/失败/未执行/有理由的不适用。行为缺陷（例如草稿丢失、禁用项能执行）必须修复；视觉观察绑定规范或保持项和证据；偏好建议保留为非阻断建议。控件高度、组件库默认能力、初始化消息或 smoke 通过均不能替代适用检查。工程结论与用户视觉确认分开。
+
+## Vue 与组件真实性
+
+核对 `component_basis=vue-shadcn-prebuilt`、固定 shadcn-vue revision、Vue/Reka 依赖和实际使用源码清单；不能把 React 或原生 select 称为 Vue 组件。产品下拉、菜单和浮层优先实测组件交互；原生例外记录目的。Select 验证键盘选中、Escape、焦点返回和触发器宽度；Sheet 验证完整标题说明、取消路径和来源焦点。场景切换后不得遗留 Teleport 浮层。Blocks 的新行为与依赖必须有当前任务依据。
+
+## 企业多页工作区
+
+并入既有六轴：visual 核对 workspace 角色与标题层级；layout 检查流式工作区、空详情不占位、主/详情/表格滚动和窄屏 Sheet；interaction 覆盖导航同步、页签去重/关闭回退、dirty 取消/放弃、跨页保留和全量重置；content 明确内存草稿与来源场景；accessibility 检查页签键盘、隐藏页及 Teleport 不可抢焦点、关闭与详情返回；cross-platform 复验桌面/平板/窄屏及离线。发现草稿丢失、非法入口回退或未执行关键链路时保持阻塞。
+
+页面 Tag 补查：导航语义和 aria-current、按钮不嵌套、当前/悬停/焦点区分、方向键不自动切页、Enter/空格激活、Delete 和关闭按钮触发同一草稿确认；溢出后当前 Tag 与焦点可见，窄屏菜单能访问全部打开页面。收起导航检查图标对齐、当前项、Tooltip 背景/箭头一致及切换后清理。页内 Tabs 保留标准键盘语义和无填充指示线，不能与页面 Tag 混用。源码与构建检查不能充当实际焦点、计算样式或视觉验收。
+
+## 搜索、日期与研究增量
+
+- interaction：搜索文字不冒充已选 ID；中文组合输入不误提交；同名 ID 可区分；加载/失败保留旧值与搜索词。未完成或逆序范围不能应用；取消/Escape 不修改正式值；清空与应用分开。跨页保留草稿与条件，隐藏 Teleport 不抢焦点。
+- layout/accessibility：单独记录 320 CSS px 重排及实际 200% 缩放；外围筛选、分页、浮层与主操作可达，二维表格例外不外扩；实测点击区域/间距及焦点遮挡。原触发器消失时应有明确逻辑后继。按 `yss-design-system/references/search-date-theme.md` 选择读屏检查并记录版本及未执行项。
+- content：设计疑问写成无提示任务和可复核结果。真实研究与教学模拟分开，缺参与者或轨迹不能宣称收益。工程报告只引用到同一份 design-qa。
+
+维持行为缺陷、规范/保持项对应的视觉观察、非阻断偏好建议三种结论。缺环境导致的必要检查未执行必须阻断对应验收；工具成功不能替代人工视觉批准。

package/template/.agents/skills/setup-matt-pocock-skills/SKILL.md

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Scaffold the per-repo configuration that the engineering skills assume:
 
-- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
+- **Issue tracker** — where issues live (Local Markdown by default; GitHub and GitLab require an explicit project choice)
 - **Triage labels** — the strings used for the five canonical triage roles
 - **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
 
@@ -31,42 +31,7 @@ Look at the current repo to understand its starting state. Read whatever exists;
 
 ### 2. Present findings and ask
 
-Summarise what's present and what's missing. Then take the sections in order — one section, one answer, then the next.
-
-Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip Section B entirely when `triage` isn't installed.
-
-**Section A — Issue tracker.**
-
-> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, and `to-spec` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `docs/.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
-
-Path resolution is configuration-first: every Local-aware skill must read the
-persisted `tracker.root` from `.template-spec/agents/issue-tracker.md` before resolving an
-artifact path. If the field is absent, use `docs/.scratch` as the default. Do
-not infer a tracker or replace the configured root from `git remote`; the legacy
-`.scratch/` and `docs/requirements/tickets/` roots are read-only migration
-sources.
-
-The supported tracker choices in this template are exactly `local-markdown`, `github`, and `gitlab`. A `git remote` may be displayed as code-host context only; it must not choose or rank a tracker. Ask for one explicit project choice, with Local Markdown as the template default:
-
-- **Local markdown (recommended)** — issues live as files under `docs/.scratch/<feature>/` in this repo.
-- **GitHub** — use GitHub Issues and the `gh` CLI only when the user explicitly selects GitHub.
-- **GitLab** — use GitLab Issues and the [`glab`](https://gitlab.com/gitlab-org/cli) CLI only when the user explicitly selects GitLab.
-
-Do not offer an `Other` tracker or write an unsupported platform into the project configuration; extending the YSS tracker contract must happen before adding another platform.
-
-Record the choice in `.template-spec/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later.
-
-**Section B — Triage label vocabulary.** Skip this section entirely if the `triage` skill isn't installed (exploration told you) — an uninstalled skill needs no labels.
-
-If it is installed, ask exactly one question:
-
-> Do you want to keep the default triage labels? (recommended: **yes**)
-
-The defaults are the five canonical roles, each label string equal to its name: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. On **yes**, write them as-is. Only if the user says no — usually because their tracker already uses other names (e.g. `bug:triage` for `needs-triage`) — collect the overrides so `triage` applies existing labels instead of creating duplicates.
-
-**Section C — Business vocabulary and decisions.** The layout does not branch: every YSS Git repository has exactly one case-sensitive `CONTEXT.md` at its root. Multiple business responsibility areas share that glossary and are distinguished by each business term's `适用业务责任区` and stable `<ContextId>/<EnglishIdentifier>` reference. ADRs live under root `docs/adr/` and are created lazily when the first qualifying decision is accepted.
-
-If the root `CONTEXT.md` is missing, initialize it with `context_schema_version: 1`, the process-term table (`术语 | 含义 | 英文标识 | 避免 / 备注`) and the business-term table (`术语 | 含义 | 英文标识 | 适用业务责任区 | 避免 / 备注`). Do not invent business terms during setup. If a lowercase, nested, duplicate, or mapped context layout exists, stop and report `migration-required`; do not preserve or extend it as a second supported layout.
+需要确认 tracker、triage 标签或根词汇布局时，读取 [配置决定](references/configuration-decisions.md)，按条件逐项确认。Tracker 只允许 `local-markdown`、`github`、`gitlab`；默认 Local Markdown，不从 remote 推断。嵌套、重复或大小写错误的 CONTEXT 布局返回 `migration-required`。
 
 ### 3. Confirm and edit
 
@@ -79,42 +44,7 @@ Let them edit before writing.
 
 ### 4. Write
 
-**Pick the file to edit:**
-
-- If `AGENTS.md` exists, edit it.
-- If it is missing, ask before creating it.
-
-If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
-
-The block:
-
-```markdown
-## Agent skills
-
-### Issue tracker
-
-[one-line summary of where issues are tracked]. See `.template-spec/agents/issue-tracker.md`.
-
-### Triage labels
-
-[one-line summary of the label vocabulary]. See `.template-spec/agents/triage-labels.md`.
-
-### Domain docs
-
-[one-line summary: one root `CONTEXT.md`, with bounded contexts represented inside its business glossary]. See 根 `CONTEXT.md` 的消费规则.
-```
-
-Include the `### Triage labels` sub-block, and write `.template-spec/agents/triage-labels.md`, only when `triage` is installed and Section B ran. When it isn't, both are omitted.
-
-Then write the docs files using the seed templates in this skill folder as a starting point:
-
-- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
-- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
-- [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
-- [triage-labels.md](./triage-labels.md) — label mapping (only if `triage` is installed)
-- 根 `CONTEXT.md` 文首合同与消费规则 — domain doc consumer rules + layout
-
-For an unsupported tracker request, stop and require a YSS tracker-contract extension; do not write an unsupported platform into `.template-spec/agents/issue-tracker.md`.
+草案已展示且用户确认后，读取 [配置写入与模板](references/write-configuration.md)。只更新已有区块并保留周围用户内容；不存在 AGENTS.md 时先取得创建授权。
 
 ### 5. Done
 

package/template/.agents/skills/setup-matt-pocock-skills/references/configuration-decisions.md

@@ -0,0 +1,42 @@
+# 工程技能配置决定
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+### 2. Present findings and ask
+
+Summarise what's present and what's missing. Then take the sections in order — one section, one answer, then the next.
+
+Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip Section B entirely when `triage` isn't installed.
+
+**Section A — Issue tracker.**
+
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, and `to-spec` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `docs/.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+
+Path resolution is configuration-first: every Local-aware skill must read the
+persisted `tracker.root` from `.template-spec/agents/issue-tracker.md` before resolving an
+artifact path. If the field is absent, use `docs/.scratch` as the default. Do
+not infer a tracker or replace the configured root from `git remote`; the legacy
+`.scratch/` and `docs/requirements/tickets/` roots are read-only migration
+sources.
+
+The supported tracker choices in this template are exactly `local-markdown`, `github`, and `gitlab`. A `git remote` may be displayed as code-host context only; it must not choose or rank a tracker. Ask for one explicit project choice, with Local Markdown as the template default:
+
+- **Local markdown (recommended)** — issues live as files under `docs/.scratch/<feature>/` in this repo.
+- **GitHub** — use GitHub Issues and the `gh` CLI only when the user explicitly selects GitHub.
+- **GitLab** — use GitLab Issues and the [`glab`](https://gitlab.com/gitlab-org/cli) CLI only when the user explicitly selects GitLab.
+
+Do not offer an `Other` tracker or write an unsupported platform into the project configuration; extending the YSS tracker contract must happen before adding another platform.
+
+Record the choice in `.template-spec/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later.
+
+**Section B — Triage label vocabulary.** Skip this section entirely if the `triage` skill isn't installed (exploration told you) — an uninstalled skill needs no labels.
+
+If it is installed, ask exactly one question:
+
+> Do you want to keep the default triage labels? (recommended: **yes**)
+
+The defaults are the five canonical roles, each label string equal to its name: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. On **yes**, write them as-is. Only if the user says no — usually because their tracker already uses other names (e.g. `bug:triage` for `needs-triage`) — collect the overrides so `triage` applies existing labels instead of creating duplicates.
+
+**Section C — Business vocabulary and decisions.** The layout does not branch: every YSS Git repository has exactly one case-sensitive `CONTEXT.md` at its root. Multiple business responsibility areas share that glossary and are distinguished by each business term's `适用业务责任区` and stable `<ContextId>/<EnglishIdentifier>` reference. ADRs live under root `docs/adr/` and are created lazily when the first qualifying decision is accepted.
+
+If the root `CONTEXT.md` is missing, initialize it with `context_schema_version: 1`, the process-term table (`术语 | 含义 | 英文标识 | 避免 / 备注`) and the business-term table (`术语 | 含义 | 英文标识 | 适用业务责任区 | 避免 / 备注`). Do not invent business terms during setup. If a lowercase, nested, duplicate, or mapped context layout exists, stop and report `migration-required`; do not preserve or extend it as a second supported layout.