create-yss-spec 3.4.7 → 3.4.9

package/template/.agents/skills/mapstruct/SKILL.md

@@ -6,7 +6,7 @@ description: "实现或排查 MapStruct DTO、PO、Domain 映射及 Lombok 集
 
 ## YSS 阶段 7 执行结果
 
-- Java、依赖与处理器版本来自工程基线，不从下面通用示例推断。三个新后端 Profile 为 Java 8；MVC 的 wire/internal 转换在 server，core/service 不依赖 client，Repository 不依赖上层 DTO。采用 Spring Bean 和构造器注入，显式映射或忽略字段；禁止通过全局 IGNORE 掩盖合同字段遗漏。
+- Java、依赖与处理器版本来自工程基线，不从下面通用示例推断。Java 语法、API、处理器与测试工具均消费批准的精确平台配置；MVC 的 wire/internal 转换在 server，core/service 不依赖 client，Repository 不依赖上层 DTO。采用 Spring Bean 和构造器注入，显式映射或忽略字段；禁止通过全局 IGNORE 掩盖合同字段遗漏。
 - 消费批准后的 Slice Contract/work unit，只为合同中的 DTO/VO/PO/Domain 转换生成 Mapper/Convertor。
 - 受控生成必须记录 source/target、忽略字段、更新语义、Lombok processor 配置和 mapper 行为测试。
 - 按 `yss-implementation-contract-compiler` 的统一 Execution Result 返回生成/源文件、测试和实际验证；未映射字段、反射/BeanUtils 退化或越界路径返回 `violation`。
@@ -26,3 +26,5 @@ description: "实现或排查 MapStruct DTO、PO、Domain 映射及 Lombok 集
 按变更验证字段覆盖、null、更新和边界值；处理器调整需实际编译。不要把所有参考示例当作必跑清单。
 
 查第三方行为时使用 `yss-research`，来源为 [MapStruct 官方文档](https://mapstruct.org/documentation/stable/reference/html/)；不假定某个 MCP 工具已安装。
+
+聚合重建使用领域工厂或有测试的显式映射方法；MapStruct 只承担机械映射，不得为处理器增加破坏不变量的 setter。该方式不豁免字段覆盖、null 语义和往返一致性验证。

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

@@ -23,4 +23,4 @@ The two branches produce very different artifacts — getting this wrong wastes
 3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
 4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.
 5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
-6. **Capture it when done.** Fold any validated decision into the real code, then capture the prototype itself as a **primary source**: commit it to a throwaway branch, out of main, and leave a context pointer to that branch on the implementation issue. Capture the answer too — the verdict and the question it settled — in the issue or a commit. The main branch keeps only the validated decision.
+6. **Capture the evidence.** Save the prototype and the question, inputs, observed result and limitations in the authorized local output location. Return validated decisions to the current design owner. Production implementation still requires its approved contract; Git commit/push and tracker publication each require applicable authorization. An experiment does not authorize those actions.

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

@@ -19,7 +19,7 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 - `docs/.scratch/<feature>/design/<feature>-interaction-spec.md` or prototype link.
 - State matrix, preferably based on `docs/design/templates/state-matrix-template.md`.
 - Existing OpenAPI Draft only if the review is checking alignment; do not require OpenAPI before product design.
-- `docs/.scratch/<feature>/verification/prototype-evidence.yaml` may be created as a pending schema v3 record, but档位构建与浏览器验证属于后续 `check.prototype-verified`。
+- `docs/.scratch/<feature>/verification/prototype-evidence.yaml` may be created as a pending Prototype Evidence schema v4 record from `docs/design/templates/prototype-evidence-template.yaml`, but档位构建与浏览器验证属于后续 `check.prototype-verified`。
 
 ## Review Gates
 

package/template/.agents/skills/resolving-merge-conflicts/SKILL.md

@@ -7,8 +7,8 @@ description: "Use when you need to resolve an in-progress git merge/rebase confl
 
 2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.
 
-3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. If the intents cannot be reconciled safely, report the conflicting decision. Abort only when the user has authorized it; do not discard work to hide a conflict.
 
 4. Discover the project's **automated checks** and run them — typically typecheck, then tests, then format. Fix anything the merge broke.
 
-5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.
+5. **Return the resolved files and verification.** Preserve the initial index and unrelated dirty files. Stage only the explicitly authorized conflict paths, never the entire working tree. Commit, or continue a merge/rebase when that creates commits, only with current authorization covering that action; otherwise leave the resolution ready for review and report the next command.

package/template/.agents/skills/tdd/SKILL.md

@@ -35,4 +35,4 @@ When the shape of that interface is itself in question — how deep the module i
 
 - **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
 - **One slice at a time.** One seam, one test, one minimal implementation per cycle.
-- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.
+- **Refactoring follows evidence.** The implementer performs necessary in-scope refactoring with green behavior tests. The independent Reviewer reads and reports findings; it does not edit the implementation or review its own changes. The implementer fixes findings, then returns the changed candidate for fresh review.

package/template/.agents/skills/to-questionnaire/SKILL.md

@@ -8,9 +8,11 @@ Turn something the user can't answer alone into a **questionnaire** — a Markdo
 
 **Grill the send, not the subject.** Interview the user only about the _send_, which they can always answer: who it goes to, and what they need back. The questions in the document then target the **gap** between what the recipient knows and what the user needs.
 
-1. **Who is it going to?** Ask, in one exchange, the recipient's role, expertise, and relationship to the user. This fixes the questionnaire's tone and how much context it must carry. Done when you know who the recipient is and what they know that the user doesn't.
+Reuse the recipient, purpose and constraints already provided. Ask only for missing information that changes the questionnaire; when both are known, draft directly.
 
-2. **What do you need back?** Ask, in one exchange, the specific decisions or facts the user can't resolve alone and needs from this person. Done when you have a concrete list of what the user must walk away able to do or decide.
+1. **Who is it going to?** If missing, ask for the recipient's role, expertise, and relationship to the user. This fixes the questionnaire's tone and how much context it must carry. Done when you know who the recipient is and what they know that the user doesn't.
+
+2. **What do you need back?** If missing, ask for the specific decisions or facts the user can't resolve alone and needs from this person. Done when you have a concrete list of what the user must walk away able to do or decide.
 
 3. **Write the questionnaire.** Draft questions aimed at the gap from steps 1–2, following the Document structure below. Write it to `to-questionnaire-<slug>.md` in the current directory (slug from the topic) and report the path. Done when the file exists and every item the user named in step 2 is covered by a question.
 

package/template/.agents/skills/to-spec/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: to-spec
-description: Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
+description: 显式将已确认讨论综合为 Spec 草稿；经主控预检后按配置持久化并回交验收。
 disable-model-invocation: true
 ---
 
-This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user — just synthesize what you already know.
+This explicit compatibility entry synthesizes confirmed context into a Spec draft. Before formal writes, the active lifecycle orchestrator checks repository identity, Plan → Spec entry evidence, allowed paths and current decisions. Template-source maintenance creates no product Spec. Reuse confirmed inputs and seams; ask only for a material missing decision. Return the draft to the orchestrator for validation and acceptance without approving it.
 
 If the issue tracker or triage label vocabulary is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
@@ -14,7 +14,7 @@ If the issue tracker or triage label vocabulary is missing, tell the user to run
 
 2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
 
-Check with the user that these seams match their expectations.
+Reuse already confirmed seams; ask only when a seam is new or materially changed.
 
 3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-human` triage label. Spec drafts need a human baseline approval before they are `approved`, and before implementation tickets may become `ready-for-agent`. Do not label the Spec itself `ready-for-agent`.
 

package/template/.agents/skills/to-tickets/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # To Tickets
 
-Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it.
+Break an explicitly requested, confirmed plan or Spec into tracer-bullet Ticket drafts. Before any formal write, return to the active lifecycle orchestrator for repository identity, current inputs, allowed paths and applicable gates. Template-source maintenance does not create product Tickets. The explicit entry may write its prepared artifacts only within that preflight contract and returns them to the orchestrator for validation and acceptance; it cannot approve a Slice Contract or decide readiness.
 
 If the issue tracker or triage label vocabulary is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
@@ -35,7 +35,7 @@ Break the work into **tracer bullet** tickets.
 
 </vertical-slice-rules>
 
-Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no blockers can start immediately.
+Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no dependency edges still needs a current approved Slice Contract and all applicable implementation gates before it can start.
 
 **Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there.
 
@@ -53,14 +53,14 @@ Ask the user:
 - Are the blocking edges correct — does each ticket only depend on tickets that genuinely gate it?
 - Should any tickets be merged or split further?
 
-Iterate until the user approves the breakdown.
+Reuse an existing approval that covers this same breakdown. Ask only about unresolved scope, granularity or dependency decisions; return accepted drafts and evidence to the orchestrator.
 
 ### 5. Publish the tickets to the configured tracker
 
 Publish the approved tickets. **How** depends on the tracker `/setup-matt-pocock-skills` configured — the tickets are the same either way, only the shape of the blocking edges changes:
 
 - **Local files** → write one file per ticket under `docs/.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` in dependency order (blockers first). Each file's "Blocked by" lists the numbers/titles it depends on. Use the per-ticket file template below — one ticket per file, never a single combined file.
-- **A real issue tracker (GitHub, Linear, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real identifiers. Use the platform's native blocking / sub-issue relationship where it has one; otherwise set each ticket's "Blocked by" to the blocking issues. Apply the `ready-for-agent` triage label unless instructed otherwise — the tickets are agent-grabbable by construction.
+- **A real issue tracker (GitHub, Linear, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real identifiers. Use the platform's native blocking / sub-issue relationship where it has one; otherwise set each ticket's "Blocked by" to the blocking issues. Keep drafts `ready-for-human`. Only the orchestrator may mark a narrow slice `ready-for-agent` after checking its current approved contract and applicable gates. Publishing to a remote tracker requires explicit authorization for that action.
 
 Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom.
 
@@ -72,9 +72,9 @@ Do NOT close or modify any parent issue.
 
 **What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective — not a layer-by-layer implementation list.
 
-**Blocked by:** the numbers/titles of the tickets that gate this one, or "None — can start immediately".
+**Blocked by:** the numbers/titles of the tickets that gate this one, or "None — readiness still requires contract and gate verification".
 
-**Status:** ready-for-agent
+**Status:** ready-for-human
 
 - [ ] Acceptance criterion 1
 - [ ] Acceptance criterion 2
@@ -98,7 +98,7 @@ The end-to-end behaviour this ticket makes work, from the user's perspective —
 
 ## Blocked by
 
-- A reference to each blocking ticket, or "None — can start immediately".
+- A reference to each blocking ticket, or "None — readiness still requires contract and gate verification".
 
 </issue-template>
 

package/template/.agents/skills/using-git-worktrees/SKILL.md

@@ -83,7 +83,7 @@ Follow this priority order. Explicit user preference always beats observed files
 git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
 ```
 
-**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
+**If NOT ignored:** Add the chosen directory to .gitignore within the authorized setup scope, verify it is ignored, then proceed. Leave that edit uncommitted unless Git commit authorization already covers it.
 
 **Why critical:** Prevents accidentally committing worktree contents to repository.
 
@@ -97,15 +97,17 @@ git worktree add "$path" -b "$BRANCH_NAME"
 cd "$path"
 ```
 
-**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
+**Isolation failure:** If worktree creation is blocked, report the actual error and preserve the current checkout. Use another already authorized isolated location when available; ask only if proceeding would change the requested isolation boundary. Do not silently begin implementation in the original checkout.
 
 ## Step 2: Project Setup
 
 Auto-detect and run appropriate setup:
 
 ```bash
-# Node.js
-if [ -f package.json ]; then npm install; fi
+# Node.js: inspect packageManager, lockfile and project instructions first.
+# In a pnpm project, use the recorded version and frozen lockfile:
+# pnpm install --frozen-lockfile
+# Use npm/yarn only when the repository actually declares them.
 
 # Rust
 if [ -f Cargo.toml ]; then cargo build; fi
@@ -124,10 +126,10 @@ Run tests to ensure workspace starts clean:
 
 ```bash
 # Use project-appropriate command
-npm test / cargo test / pytest / go test ./...
+pnpm test / cargo test / pytest / go test ./... # select the declared project runner
 ```
 
-**If tests fail:** Report failures, ask whether to proceed or investigate.
+**If tests fail:** Record the existing failure and investigate within the authorized scope. Ask only if a new decision or access is needed; do not label the baseline clean.
 
 **If tests pass:** Report ready.
 
@@ -151,9 +153,9 @@ Ready to implement <feature-name>
 | `worktrees/` exists | Use it (verify ignored) |
 | Both exist | Use `.worktrees/` |
 | Neither exists | Check instruction file, then default `.worktrees/` |
-| Directory not ignored | Add to .gitignore + commit |
-| Permission error on create | Sandbox fallback, work in place |
-| Tests fail during baseline | Report failures + ask |
+| Directory not ignored | Add to .gitignore; commit only when authorized |
+| Permission error on create | Report failure; preserve the requested isolation boundary |
+| Tests fail during baseline | Record failures; continue authorized diagnosis |
 | No package.json/Cargo.toml | Skip dependency install |
 
 ## Common Mistakes
@@ -181,7 +183,7 @@ Ready to implement <feature-name>
 ### Proceeding with failing tests
 
 - **Problem:** Can't distinguish new bugs from pre-existing issues
-- **Fix:** Report failures, get explicit permission to proceed
+- **Fix:** Distinguish baseline failures from new defects; ask only for a missing decision
 
 ## Red Flags
 
@@ -191,7 +193,7 @@ Ready to implement <feature-name>
 - Skip Step 1a by jumping straight to Step 1b's git commands
 - Create worktree without verifying it's ignored (project-local)
 - Skip baseline test verification
-- Proceed with failing tests without asking
+- Claim a clean baseline when checks failed
 
 **Always:**
 - Run Step 0 detection first

package/template/.agents/skills/wait-what/SKILL.md

@@ -4,4 +4,4 @@ description: "Stop. That last message did not land: re-pitch it."
 disable-model-invocation: true
 ---
 
-Wait, I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from the repository-root `CONTEXT.md`. When the repository has multiple bounded contexts, resolve the term by its `<ContextId>/<EnglishIdentifier>` reference and the `适用限界上下文` column in that single glossary.
+用用户当前使用的语言，补足刚才说明所缺的背景并重新解释。保持简明、具体，复用仓库根目录唯一 `CONTEXT.md` 的词汇；跨业务责任区按 `<ContextId>/<EnglishIdentifier>` 定位。只改表达，不启动完整生命周期或重建上下文。

package/template/.agents/skills/wayfinder/SKILL.md

@@ -20,6 +20,8 @@ Every map and ticket is an issue, so it has a **name** — its title. In everyth
 
 The map is a single issue on this repo's issue tracker, labelled `wayfinder:map` — the canonical artifact. Its tickets are child issues of the map.
 
+Return the decision map to the active orchestrator for formal asset/state acceptance. Explicit invocation does not authorize remote publication or Git commits; preserve those action boundaries.
+
 The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
 
 **Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
@@ -54,7 +56,7 @@ The whole map at low resolution, loaded once per session. Open tickets are **not
 
 ### Tickets
 
-Each ticket is a **child issue** of the map; the tracker's issue id is its identity. Its body is the question, sized to one 100K token agent session:
+Each ticket is a **child issue** of the map; the tracker's issue id is its identity. Its body is the question, bounded by a coherent decision and the current runtime/context capacity:
 
 ```markdown
 ## Question
@@ -102,7 +104,7 @@ Ruling something out of scope is a scoping act, not a step on the route. When a
 
 ## Invocation
 
-Two modes. Either way, **never resolve more than one ticket per session** — with the exception of research tickets.
+Two modes. Keep each decision traceable and stop at a real dependency, decision or context boundary; related small tickets may share a session when their evidence remains clear.
 
 ### Chart the map
 

package/template/.agents/skills/writing-for-agents/SKILL.md

@@ -3,79 +3,15 @@ name: writing-for-agents
 description: Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
 ---
 
-Reference for writing any document an agent consumes — a skill, an `AGENTS.md` / `CLAUDE.md`, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable — the agent taking the same _process_ every run, not producing the same output.
+# Writing for Agents
 
-When the document you're writing is a skill, read [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) for frontmatter, invocation choice, and router skills.
+Write instructions that help an Agent make the right decision in the intended task. Preserve the host repository's authority, user authorization and existing conventions.
 
-## Context pointers
+- Put the distinguishing trigger first. Separate source facts, mandatory boundaries and optional methods.
+- Keep necessary inputs, branch choices, fragile invariants, stopping conditions and completion evidence visible.
+- Link conditional detail at its decision point. Explain when to load it; do not make every task load every reference.
+- Prefer outcomes and criteria for flexible work. Use exact steps for genuinely fragile operations, not arbitrary counts or a desired writing length.
+- Remove duplicated generic advice only when the remaining instruction preserves the real decision boundary.
+- Verify changed triggers and behavior with representative requests, neighboring non-triggers and applicable authorization counterexamples; structural checks do not prove Agent behavior.
 
-A **context pointer** is a reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. A skill's description is one; a line in `AGENTS.md` naming a doc is the same object. The pointer's _wording_, not its target, decides when the agent reaches the material — and how reliably. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.
-
-A pointer does two jobs — state what the material is, and list the **branches** that should trigger reaching it (a branch is a distinct case the document handles, so different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it earns even harder pruning than the body:
-
-- **Front-load the leading word** — the pointer is where it does its triggering work.
-- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice; collapse them and keep only genuinely distinct branches.
-- **Cut identity the body already carries.**
-
-## The two loads
-
-Every document and pointer you add spends one of two budgets:
-
-- **Context load** — the cost of always-loaded material on the agent's window: an `AGENTS.md` line, a skill description, anything sitting in context every turn, spending tokens and attention whether or not it fires.
-- **Cognitive load** — the cost on the human: which documents exist and when to reach for each. The human is the index. Not a cost to minimise — it is the price of human agency; spend it where human judgement matters, remove it where it does not.
-
-Material reached only through a pointer escapes context load at the price of the pointer's own line; material with no pointer at all rides entirely on cognitive load.
-
-## Information hierarchy
-
-A document is built from two content types — **steps** (the ordered actions the agent performs) and **reference** (definitions, rules, facts consulted on demand) — that mix freely: all steps (a recipe), all reference (a review's rules, this skill), or both. The core decision is where each piece sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
-
-1. **In-file step** — the primary tier: what the agent does, in order.
-2. **In-file reference** — consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell.
-3. **Disclosed reference** — pushed out into a separate file, reached by a context pointer, loaded only when the pointer fires. Spans a sibling file in the same folder through fully external reference that lives anywhere and any document can point at.
-
-Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
-
-**Progressive disclosure** is the move down the ladder — out of the main file and behind a pointer — so the top stays legible. Not primarily a token optimisation: it is how the hierarchy is protected. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. When a document has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one.
-
-**Co-location** is the within-file companion: where the ladder decides _how far down_ a piece sits, co-location decides _what sits beside it_ once there. Keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it. The test: the document should read like documentation written for the agent — grouped material reads that way; scattered material does not. (Distinct from duplication: that repeats one meaning in two places; scattering fragments one meaning across many.)
-
-**Sprawl** is the failure mode here: a document simply too long, even when every line is live and unique. Attention thins across the excess, and every extra line is one more to keep relevant. The cure is the ladder: disclose reference behind pointers, and split by branch or sequence so each path carries only what it needs.
-
-## Steps and completion criteria
-
-Every step ends on a **completion criterion** — the condition that tells the agent the work is done. Two properties make it a lever:
-
-- **Clarity** — can the agent tell done from not-done? A vague bound ("understanding reached") invites **premature completion**: ending the step before it is genuinely done, attention slipping to _being done_. The visible steps still ahead — the **post-completion steps** — supply the pull; the criterion's clarity is the resistance. Defend in order: **sharpen the bound first** (local and cheap); only if it is irreducibly fuzzy _and_ you observe the rush, hide the later steps by splitting the sequence — and hiding only works across a real context boundary (a hand-off or a subagent dispatch; an inline call leaves the later steps in context and clears nothing).
-- **Demand** — how much it requires. "Every modified model accounted for" forces thorough work where "produce a change list" does not. Demand drives **legwork** — the digging the agent does within the work, latent in the wording rather than written as its own step — and it is not step-bound: "every rule applied" binds a body of flat reference just as "every step done" binds a sequence, which is how an all-reference document still carries an exhaustiveness bar.
-
-The strongest criteria are both checkable and exhaustive.
-
-## When to split
-
-Splitting one document into two spends one of the two loads, so split only when the cut earns it:
-
-- **By sequence** — split a run of steps where the post-completion steps tempt the agent to rush the one in front of it. Keeping them out of view drives more legwork on the current task. Beware the reverse: merging sequences exposes each step's later steps to what follows, inviting premature completion.
-- **By invocation** — skill-specific: see [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md).
-
-## Leading words
-
-A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the document (_lesson_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free; reach for an existing word first.
-
-It anchors twice. In the body, _execution_: the agent reaches for the same behaviour every time the word appears, and inside flat reference it focuses attention on a class of thing to look for. In a pointer, _invocation_: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the material and reaches it more reliably.
-
-Hunt for opportunities to refactor with leading words. A triad spelled out at three sites, a pointer spending a sentence to gesture at one idea — each is a passage begging to collapse into a single token:
-
-- "fast, deterministic, low-overhead" → _tight_ (a _tight_ loop).
-- "a loop you believe in" → _red_ — a fuzzy gate becomes a binary observable state (the loop goes _red_ on the bug, or it doesn't).
-
-You win twice: fewer tokens, and a sharper hook for the agent to hang its thinking on. Assume every document is carrying restatements that leading words retire — go find them.
-
-**Negation** is the failure mode beside this lever: steering by prohibition drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; the negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Prompt the **positive** — state the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
-
-## Pruning
-
-- Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit. **Duplication** — the same meaning in more than one place — costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank. (The accidental inverse of a leading word, which repeats a token on purpose, never the meaning.)
-- The **environment** is a source of truth too — `package.json` scripts, config files, the directory layout, `--help` output — and a document that restates it is a **cache**: a copy of a lookup, earning its load only when the lookup is expensive. Cache what the agent cannot find by looking: the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave the one-file, one-command lookups to the environment, where they cannot go stale.
-- Check every line for **relevance**: does it still bear on what the document does? A line loses relevance by never bearing on the task (mere exposition, or a branch that should be disclosed) or by going stale as the behaviour or world it describes changes. Shorter documents are easier to keep relevant. Without a pruning discipline the default fate is **sediment**: stale layers that settle because adding feels safe and removing feels risky, until you must core down through them to find what is still live.
-- Hunt **no-ops** sentence by sentence: an instruction the model already obeys by default pays load to say nothing. The test — does it change behaviour versus the default? — is model-relative, not reader-relative: two people disagreeing about a no-op disagree about the default, and settle it by running the document, not by debate. When a sentence fails, delete the whole sentence rather than trim words from it. The test also grades leading words: a word too weak to beat the default (_be thorough_ when the agent is already thorough-ish) is a no-op, and the fix is a stronger word (_relentless_), not a different technique.
+When editing skill metadata or invocation policy, read [skill mechanics](SKILL-MECHANICS.md). When deciding how to split a long document or repair an unreliable context pointer, read [writing principles and examples](references/writing-principles.md). These references do not impose a uniform writing length or override project governance.

package/template/.agents/skills/writing-for-agents/references/writing-principles.md

@@ -0,0 +1,76 @@
+Reference for writing any document an agent consumes — a skill, an `AGENTS.md` / `CLAUDE.md`, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable — the agent taking the same _process_ every run, not producing the same output.
+
+When the document you're writing is a skill, read [`SKILL-MECHANICS.md`](../SKILL-MECHANICS.md) for frontmatter, invocation choice, and router skills.
+
+## Context pointers
+
+A **context pointer** is a reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. A skill's description is one; a line in `AGENTS.md` naming a doc is the same object. The pointer's _wording_, not its target, decides when the agent reaches the material — and how reliably. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.
+
+A pointer does two jobs — state what the material is, and list the **branches** that should trigger reaching it (a branch is a distinct case the document handles, so different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it earns even harder pruning than the body:
+
+- **Front-load the leading word** — the pointer is where it does its triggering work.
+- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice; collapse them and keep only genuinely distinct branches.
+- **Cut identity the body already carries.**
+
+## The two loads
+
+Every document and pointer you add spends one of two budgets:
+
+- **Context load** — the cost of always-loaded material on the agent's window: an `AGENTS.md` line, a skill description, anything sitting in context every turn, spending tokens and attention whether or not it fires.
+- **Cognitive load** — the cost on the human: which documents exist and when to reach for each. The human is the index. Not a cost to minimise — it is the price of human agency; spend it where human judgement matters, remove it where it does not.
+
+Material reached only through a pointer escapes context load at the price of the pointer's own line; material with no pointer at all rides entirely on cognitive load.
+
+## Information hierarchy
+
+A document is built from two content types — **steps** (the ordered actions the agent performs) and **reference** (definitions, rules, facts consulted on demand) — that mix freely: all steps (a recipe), all reference (a review's rules, this skill), or both. The core decision is where each piece sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
+
+1. **In-file step** — the primary tier: what the agent does, in order.
+2. **In-file reference** — consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell.
+3. **Disclosed reference** — pushed out into a separate file, reached by a context pointer, loaded only when the pointer fires. Spans a sibling file in the same folder through fully external reference that lives anywhere and any document can point at.
+
+Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
+
+**Progressive disclosure** is the move down the ladder — out of the main file and behind a pointer — so the top stays legible. Not primarily a token optimisation: it is how the hierarchy is protected. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. When a document has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one.
+
+**Co-location** is the within-file companion: where the ladder decides _how far down_ a piece sits, co-location decides _what sits beside it_ once there. Keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it. The test: the document should read like documentation written for the agent — grouped material reads that way; scattered material does not. (Distinct from duplication: that repeats one meaning in two places; scattering fragments one meaning across many.)
+
+**Sprawl** is the failure mode here: a document simply too long, even when every line is live and unique. Attention thins across the excess, and every extra line is one more to keep relevant. The cure is the ladder: disclose reference behind pointers, and split by branch or sequence so each path carries only what it needs.
+
+## Steps and completion criteria
+
+Every step ends on a **completion criterion** — the condition that tells the agent the work is done. Two properties make it a lever:
+
+- **Clarity** — can the agent tell done from not-done? A vague bound ("understanding reached") invites **premature completion**: ending the step before it is genuinely done, attention slipping to _being done_. The visible steps still ahead — the **post-completion steps** — supply the pull; the criterion's clarity is the resistance. Defend in order: **sharpen the bound first** (local and cheap); only if it is irreducibly fuzzy _and_ you observe the rush, hide the later steps by splitting the sequence — and hiding only works across a real context boundary (a hand-off or a subagent dispatch; an inline call leaves the later steps in context and clears nothing).
+- **Demand** — how much it requires. "Every modified model accounted for" forces thorough work where "produce a change list" does not. Demand drives **legwork** — the digging the agent does within the work, latent in the wording rather than written as its own step — and it is not step-bound: "every rule applied" binds a body of flat reference just as "every step done" binds a sequence, which is how an all-reference document still carries an exhaustiveness bar.
+
+The strongest criteria are both checkable and exhaustive.
+
+## When to split
+
+Splitting one document into two spends one of the two loads, so split only when the cut earns it:
+
+- **By sequence** — split a run of steps where the post-completion steps tempt the agent to rush the one in front of it. Keeping them out of view drives more legwork on the current task. Beware the reverse: merging sequences exposes each step's later steps to what follows, inviting premature completion.
+- **By invocation** — skill-specific: see [`SKILL-MECHANICS.md`](../SKILL-MECHANICS.md).
+
+## Leading words
+
+A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the document (_lesson_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free; reach for an existing word first.
+
+It anchors twice. In the body, _execution_: the agent reaches for the same behaviour every time the word appears, and inside flat reference it focuses attention on a class of thing to look for. In a pointer, _invocation_: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the material and reaches it more reliably.
+
+Hunt for opportunities to refactor with leading words. A triad spelled out at three sites, a pointer spending a sentence to gesture at one idea — each is a passage begging to collapse into a single token:
+
+- "fast, deterministic, low-overhead" → _tight_ (a _tight_ loop).
+- "a loop you believe in" → _red_ — a fuzzy gate becomes a binary observable state (the loop goes _red_ on the bug, or it doesn't).
+
+You win twice: fewer tokens, and a sharper hook for the agent to hang its thinking on. Assume every document is carrying restatements that leading words retire — go find them.
+
+**Negation** is the failure mode beside this lever: steering by prohibition drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; the negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Prompt the **positive** — state the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
+
+## Pruning
+
+- Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit. **Duplication** — the same meaning in more than one place — costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank. (The accidental inverse of a leading word, which repeats a token on purpose, never the meaning.)
+- The **environment** is a source of truth too — `package.json` scripts, config files, the directory layout, `--help` output — and a document that restates it is a **cache**: a copy of a lookup, earning its load only when the lookup is expensive. Cache what the agent cannot find by looking: the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave the one-file, one-command lookups to the environment, where they cannot go stale.
+- Check every line for **relevance**: does it still bear on what the document does? A line loses relevance by never bearing on the task (mere exposition, or a branch that should be disclosed) or by going stale as the behaviour or world it describes changes. Shorter documents are easier to keep relevant. Without a pruning discipline the default fate is **sediment**: stale layers that settle because adding feels safe and removing feels risky, until you must core down through them to find what is still live.
+- Hunt **no-ops** sentence by sentence: an instruction the model already obeys by default pays load to say nothing. The test — does it change behaviour versus the default? — is model-relative, not reader-relative: two people disagreeing about a no-op disagree about the default, and settle it by running the document, not by debate. When a sentence fails, delete the whole sentence rather than trim words from it. The test also grades leading words: a word too weak to beat the default (_be thorough_ when the agent is already thorough-ish) is a no-op, and the fix is a stronger word (_relentless_), not a different technique.

package/template/.agents/skills/yss-api-integration/SKILL.md

@@ -43,7 +43,7 @@ description: "在 Vue3 YSS UI 中对接 Orval API；核验生成方法、mutator
 1. 读取 `yss-openapi-governance` 产出的 OpenAPI Freeze 记录和 `docs/.scratch/<feature>/api/<feature>-json-export.md`；确认 YAML SHA-256、JSON SHA-256、Redocly CLI 版本、lockfile 引用和 JSON 校验均通过。治理 JSON 的唯一产物路径是 `docs/.scratch/<feature>/api/<feature>.json`。
 2. JSON 导出由 `yss-openapi-governance` 负责。`api-integration` 只接受该 skill 留下的派生记录；记录中的锁定 `redocly bundle` 命令是治理导出证据，不是前端集成任意重跑的入口。
 3. **受控交接**：若前端实现仓库需要本地输入，批准的 Cross-repo 子合同或项目脚本只能将上述治理 JSON 原样物化为 `<frontend>/openapi/openapi.json`；物化后的 SHA-256 必须与派生记录一致。禁止从 URL、Draft YAML、后端运行时或任意本地文件临时替换输入。
-4. `api-integration` 只核对 JSON 派生记录、交接路径和 SHA-256，并把原始 JSON 交给既有前端代码生成流程；本 Harness 不读取或修改目标前端的生成器配置，不在此仓库执行生成，也不建立生成 CI 门禁。若 JSON SHA 与派生记录不一致，停止交接并回到治理流程。
+4. `api-integration` 只核对 JSON 派生记录、交接路径和 SHA-256，并把原始 JSON 交给既有前端代码生成流程；本 Harness 可只读核对目标前端的生成器配置与真实导出，但不修改该配置，不在此仓库执行生成，也不建立生成 CI 门禁。若 JSON SHA 与派生记录不一致，停止交接并回到治理流程。
 5. 目标前端项目在需要时手动运行其既有生成命令、类型检查和受影响组件 / API 测试；将实际命令、结果、生成输入 SHA 和偏离写入 `YSS Skill Execution Result`。
 
 ## 真实 mutator 响应契约
@@ -174,7 +174,7 @@ await pageQualityRule(query, { signal: controller.signal, timeout: 120000 });
 
 ## 失败兜底策略
 
-- 生成导出与 skill 示例不同时，以生成文件为准并更新生成脚本，禁止绕过类型检查猜名调用。
+- 生成导出与 skill 示例不同时，以生成文件为准；仅在已授权的生成链维护范围内更新生成脚本，禁止绕过类型检查猜名调用。
 - 接口字段不稳定时，在 Hook API 边界做最小映射，不把兼容逻辑散落到模板。
 - HTTP 200 Blob 业务错误时，先修复后端状态码或 mutator 统一解析，禁止在业务 Hook 重复实现。
 

package/template/.agents/skills/yss-application/SKILL.md

@@ -29,7 +29,11 @@ Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事
 
 1. 按 `architecture_identity.architecture_profile` 选择且只选择对应 Profile reference；Profile 未登记、与 Manifest 不一致或成熟度不满足当前任务时返回 `blocked`。
 2. `target-domain-model` 才执行 Domain Service / Gateway、跨聚合编排和下述 DDD 产物规则；`layered-mvc-service` 与 `mvc-data-analysis-v1` 分别按其 service/core Profile 承载用例、规则和事务，不加载 DDD Gateway。
+<a id="application.use-case"></a>
+<!-- yss-rule {"id":"application.use-case","when":"application","level":"mandatory","evidence":"code-and-verification"} -->
 3. 确认 Use Case、Application/service/core 边界与事务边界已在批准合同中写明。
+<a id="application.mapping"></a>
+<!-- yss-rule {"id":"application.mapping","when":"application","level":"mandatory","evidence":"code-and-verification"} -->
 4. Web DTO 到内部 Command/Result 的转换归 Web 边界，持久化转换归 Repository/Infrastructure；用例层确有独立模型转换时才加载 `mapstruct`，并统一 Spring Bean 与构造器注入。
 5. DDD 的详细包结构、注解、示例和旧架构阻断边界见 `references/application-layer-guide.md`；MVC 不读取该 guide。
 
@@ -53,10 +57,18 @@ Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事
 ## 阶段 7 合同
 
 - 只消费批准后的 `Slice Implementation Contract` 和当前 `work_unit`。
+<a id="application.behavior-tests"></a>
+<!-- yss-rule {"id":"application.behavior-tests","when":"application","level":"mandatory","evidence":"code-and-verification"} -->
 - AppService 骨架可 `controlled-generation`；用例编排、事务、幂等、权限和失败行为必须 `behavior-tdd`。
 - 按 `yss-implementation-contract-compiler/references/yss-skill-execution-result.md` 返回统一 `YSS Skill Execution Result`。
+<a id="application.impacts"></a>
+<!-- yss-rule {"id":"application.impacts","when":"application","level":"mandatory","evidence":"code-and-verification"} -->
 - 发现新 API、权限、状态机或跨上下文影响时填入 `new_impacts` 并暂停。
 
 ## 按需读取
 
 - 分层开发规范：`references/application-layer-guide.md`
+
+## 既有工程与条件适用
+
+只读审计不要求先补批准 Slice；业务 Spec 缺失须记录。整改消费批准 Slice、已确认行为 seam 与登记的 Application/service/core 映射，不要求生成 Manifest。事务、幂等、提交后副作用按实际用例评估；未命中不创建空事务、空端口或空恢复实现。DDD 的领域规则归 Domain，MVC 规则允许留在已登记 service/core。

package/template/.agents/skills/yss-application/references/application-layer-guide.md

@@ -85,3 +85,10 @@ public interface QualityTemplateApplicationConvertor {
 ## 8. 旧架构边界
 
 检测到 AppService 接收 client Cmd、返回 client VO、调用返回 VO 的 Domain Gateway 或位于 `core/service` 时，返回 `unsupported`，不得由新 scaffold 或本指南自动改写。旧项目继续按原工程维护；现代化改造必须单独立项、先评估再逐切片迁移。
+
+## 事务与外部副作用
+
+- 合同标明需要原子提交的数据库写入及所属用例；事务从 Application 公共代理 seam 进入。无需原子写入的查询或纯计算不强制增加事务注解。
+- Repository 参与既有事务，不另行决定业务提交边界。多表聚合保存的回滚测试从用例入口注入中途失败，不能只验证单个 Mapper。
+- Redis、邮件、HTTP 调用不因数据库事务自动获得原子性。按批准合同选择提交后缓存失效、可重试事件或 outbox；需要持久重试时不能只依赖内存事件。
+- 幂等键、重复请求结果、重试范围及失败恢复来自合同；不在技能中默认引入分布式事务或通用重试。测试覆盖回滚不发布、提交后失败及重复消费。

package/template/.agents/skills/yss-audit-log/SKILL.md

@@ -19,7 +19,7 @@ description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订
 2. 涉及真实类名、配置项、订阅器或排障时，先读 `references/source-index.md`，再定位源码或文档。
 3. 优先检查项目里是否已有注解、配置项和订阅器实现，再决定改法。
 4. 只给出与当前问题直接相关的接入点：注解、配置、切面链路、`CurrentUserProvider` 和订阅器扩展。
-5. 需要看实现细节时，再读取 `assets/` 下源码，不要先讲整套组件原理。
+5. 实现细节以所选平台线的当前源码为准。`assets/` 是 Boot 2 / Java 8 历史快照，仅在旧工程比对或迁移诊断时读取；不能作为 Boot 3 的实现模板或 freshness 证据。
 
 ## 源码索引
 
@@ -62,6 +62,8 @@ description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订
 
 ## 按需读取
 
+以下 `assets/*.java` 均为 `boot2-java8` 历史资料，含 javax 与旧中文 SpEL key。Boot 3 使用其平台索引定位当前 jakarta / args / result 源码；不要修改历史资料来冒充新平台源码。
+
 - 源码索引：`references/source-index.md`
 - 审计切面与 SpEL 解析：`assets/AuditLogAspect.java`
 - 异步发布链路：`assets/YssAuditPublishService.java`

package/template/.agents/skills/yss-audit-log/assets/AuditLogAspect.java

@@ -1,3 +1,4 @@
+// Historical boot2-java8 reference only; not a boot3-java17 implementation template.
 package com.yss.cloud.audit.configuration;
 
 import cn.hutool.jwt.JWT;

package/template/.agents/skills/yss-audit-log/assets/YssAuditLogPrintSubscriberImpl.java

@@ -1,3 +1,4 @@
+// Historical boot2-java8 reference only; not a boot3-java17 implementation template.
 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with

package/template/.agents/skills/yss-audit-log/assets/YssAuditLogSysManagerSubscriberImpl.java

@@ -1,3 +1,4 @@
+// Historical boot2-java8 reference only; not a boot3-java17 implementation template.
 package com.yss.cloud.audit.subscriber.impl;
 
 import com.yss.cloud.audit.subscriber.YssAuditSubscriber;

package/template/.agents/skills/yss-audit-log/assets/YssAuditPublishService.java

@@ -1,3 +1,4 @@
+// Historical boot2-java8 reference only; not a boot3-java17 implementation template.
 package com.yss.cloud.audit.subscriber;
 
 import com.yss.cloud.audit.configuration.AuditConfigurationProperties;