create-yss-spec 3.4.8 → 3.4.9

package/template/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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/.codex/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;

package/template/.codex/skills/yss-backend-spec-review/SKILL.md

@@ -36,3 +36,9 @@ description: 审计既有 Java 后端工程对 YSS 技能规范和已批准业
 ## 输出与完成依据
 
 复用 `docs/templates/review-report-template.md`、当前 Slice 的 YSS Skill Execution Result 和 [审计与整改流程中的记录要求](references/remediation-workflow.md#证据与交接)。报告列明审查覆盖、Standards / Spec 分轴结论、修复前后 finding、候选/规则摘要、实际验证、独立 Reviewer 身份和剩余阻塞。只对本次覆盖且有证据的范围声明符合规范，不自动证明平台已认证或允许发布。
+
+## 必须评估、适用必审
+
+每次显式评估 Web、DTO、Domain、Application、Repository、MyBatis 六类职责；MVC 不套用 DDD，MyBatis 仅在实际使用时适用。使用 `scripts/backend-standards-coverage` 编译实际范围，合同漏列不能抵消真实影响。Java 规范通用，Validation/Exception/映射/注解处理及组件技能按事实追加。
+
+逐条消费 canonical 中 `yss-rule` 声明并返回稳定 `constraint_id`；未结构化条款仍由独立 Reviewer 全文核对。不能只写“本技能通过”。日常后端开发和存量整改共用该检查，详见 [覆盖协议](references/standards-coverage.md)。

package/template/.codex/skills/yss-backend-spec-review/references/check-inputs.md

@@ -7,14 +7,14 @@
 | 每个后端范围 | `alibaba-java-code-style`、工程基线、实际模块/包/类型 | Java 规范、敏感日志、实际依赖方向；测试对象必须存在 |
 | DDD 核心领域 | `yss-domain`、批准战术设计 | 创建/重建、不变量、领域错误、值对象及行为测试；领域规则不依赖框架 |
 | DDD Application 或 MVC service/core | `yss-application`、所选架构 Profile | 用例边界、事务、提交后副作用、幂等和失败恢复；不要求无事务需要的用例套空事务 |
-| 持久化 | `yss-repository`、`yss-mybatis` 及选定 Repository Profile | 聚合加载与展示查询、PO/Mapper/XML/SQL、主键/审计、分页/批量、绑定/参数化和映射完整性；基类按能力选择 |
+| 持久化 | `yss-repository` 及选定 Repository Profile；MyBatis 命中时加载 `yss-mybatis` | 聚合加载与展示查询、PO/Mapper/XML/SQL、主键/审计、分页/批量、绑定/参数化和映射完整性；基类按能力选择 |
 | HTTP 入口 | `yss-web-controller`、冻结 API | CRUD 与认证/回调/Cookie 等手工入口；Controller 不能绕过应用用例；异常翻译允许引用领域错误 |
 | wire / 参数 / 错误 | `yss-dto`、`yss-validation`、`yss-exception` | 真实响应/分页/错误协议、Bean Validation、命名空间、敏感字段与冻结 OpenAPI 一致 |
 | 映射 / 注解处理 | `mapstruct`、`lombok` | 显式字段策略、处理器版本、领域工厂重建；不强迫聚合开放 setter |
 | 实际组件调用 | Registry 中对应组件 Skill 与精确平台源码索引 | cache、userinfo、audit、ID、Excel、resilience 等按能力加载；不因“审查全面”要求安装不用的组件 |
 | 工程和平台 | `docs/engineering/backend-platforms.json`、当前工程基线、effective POM、依赖树 | 精确 JDK/Boot、父/BOM、starter、javax/jakarta 和源码索引；源码可编译不等于兼容认证 |
 
-每个后端范围显式评估 `yss-repository` / `yss-mybatis`。无持久化或 MyBatis 影响时分别说明原因；不可跳过适用项，也不可为了填表增加实现。MVC 不强制构造 DDD 聚合/Gateway；没有展示分页需求就不要求分页类。
+每个后端范围显式评估 `yss-web-controller` / `yss-dto` / `yss-domain` / `yss-application` / `yss-repository` / `yss-mybatis`。无持久化或 MyBatis 影响时分别说明原因；不可跳过适用项，也不可为了填表增加实现。MVC 不强制构造 DDD 聚合/Gateway；没有展示分页需求就不要求分页类。
 
 架构检查按已登记模块、包和实际注解/类型职责识别，不能只搜索 `rest`、`*Controller` 或某固定后缀。已有 ArchUnit 检查若命中零类，记录覆盖缺口；只运行空测试不能证明存量工程合规。
 

package/template/.codex/skills/yss-backend-spec-review/references/standards-coverage.md

@@ -0,0 +1,39 @@
+# 后端规范覆盖协议
+
+日常开发与既有整改使用同一 `scripts/backend-standards-coverage` 和 `backend-review.mjs`。本协议只派生检查输入，规范正文由工程锁定的 canonical Skill 唯一拥有，路由仍由技能注册表管理。不得浮动使用最新 Skill 替换工程锁定版本。
+
+## 输入与只读命令
+
+治理 root 必须提供工程实际锁定的 canonical 技能；平台、身份与职责来自登记的工程基线。`review_input.scope_kind` 明确区分 `baseline` / `change`，不与候选 `review_mode=worktree|committed` 混用。
+
+```sh
+scripts/backend-standards-coverage --root /governance --input /evidence/review-state.json
+scripts/backend-standards-coverage --root /governance --input /evidence/review-state.json --verify
+```
+
+第一条只输出派生 JSON，不写工程、不执行其构建命令、不批准合同；保存输出并绑定 `standards_coverage_ref` 与 SHA-256 `standards_coverage_digest`。第二条读取 `review_result_ref`，重算覆盖并核对已有独立审查。所有证据引用相对治理 root；`code_ref` 相对被审工程。证据放在工程源码范围外，避免报告把自身纳入摘要。
+
+- `baseline`：输入 `project_root`、`baseline_binding: {ref,digest}`，基线复用 `architecture_identity/source.roots/build_units.role_paths`；可以无 Slice、无 diff。未登记时可输出诊断，但未知身份、未解析类型和空业务范围不能声称合规。
+- `change`：保留批准 Slice、执行预检、工作单元与既有候选字段。`worktree` 从不可变候选读取 merge_base；`committed` 另给 40 位 `review_base_ref`。合同漏掉实际影响返回 drift/new_impacts，不能仅补审查输入掩盖合同缺口。
+- 基线盘点包括授权工程源根中的源码、测试、XML、配置和构建文件。变更模式轻量盘点完整源码，语义审查针对变更类型与依赖闭包；配置变化扩展影响。未触及的既有证据须明确复用依赖和摘要，不能只搬历史“通过”。
+- 源码扫描识别已知注解、局部组合注解和接口继承，并结合角色映射与依赖配置。它不是完整 Java 编译器：不确定的外部注解/父类型必须补 `responsibility_evidence: [{ref,digest}]`，记录 `source_ref/source_digest/roles/reason/evidence_ref/evidence_digest`。roles 使用工程角色或 `data`；证据来自真实类型、编译态 ArchUnit/运行时映射或独立核实，不能借此取消扫描已发现的职责。
+
+`skill_assessments` 必须显式评估六类职责；`issues` 与明确结构 `findings` 均保留，不能移除后伪造派生清单。输出绑定源码 HEAD、文件摘要/mode、规则文件摘要及 Skill lock 摘要；重算不一致则旧覆盖失效。`limitations` 必须随报告保留。源码和合成夹具通过不证明 HTTP wire、数据库方言或 Java 平台认证。
+
+## 规则所有权与结果
+
+强制条款使用同文件内 `<a id="稳定ID"></a>` 和 `<!-- yss-rule {"id":"稳定ID","when":"适用事实","level":"mandatory","evidence":"code-and-verification"} -->` 标记原文，不复制规则正文。允许条件由工具校验；新增条件先增加检测/保守处置和反例。历史 ID 不复用为另一种语义。
+
+继续使用 `constraint_results`，每项增加 `constraint_id` 和与派生结果一致的 `applicability_basis`，并保留 `axis/skill/constraint/status/rule_ref/rule_digest/code_ref/evidence_ref/evidence_digest`。机器重新读取所有标记，拒绝漏项、重复项、未知 ID、规则归属错误、漂移和虚假不适用。
+
+每个适用技能额外有 `<skill>.full-text` 项：Reviewer 阅读该技能和适用 references，使用 `review_notes` 记录具体判断及证据；尚未结构化的条款在原报告列出 findings。不允许把文本长度检查当作语义合规证明。结构化规则目前只是可检查的覆盖基线，全文审查仍强制。
+
+规则级不适用不同于技能级不适用。比如 Repository 适用而分页未命中时，相关条件规则允许 `not-applicable`，必须有理由、实际代码范围及可读证据；扫描已命中的强制规则不得豁免。无分页、事务、批量或特定组件需求时不建空实现。
+
+## 基线报告与完成边界
+
+独立 Reviewer 始终使用 `code-review`；baseline 结果也核对 reviewer/implementer 的不同 actor 与执行 instance，以及当前覆盖摘要。`candidate_digest` 为完整派生 inventory 的 SHA-256。机器验证含 command、exit_code、executed_at、candidate_digest 和日志摘要。
+
+`axes.Standards=passed` 必须覆盖所有适用规则。缺业务 Spec 则 `axes.Spec=missing_evidence`；要声明 Spec passed，另提供 `spec_binding.ref/digest/approval_ref`，批准必须绑定当前 Spec，并逐验收项给证据。基线成功仅返回 `status=audited, execution_allowed=false`，绝不关闭实现到交付的流转。
+
+历史报告可以阅读，新完成门禁要求覆盖字段；不批量伪造或升级历史审查。变更报告仍只消费已批准且当前的 Slice，并使用原候选协议。只读盘点发现违规后形成 finding 与整改计划，取得必要批准后才修改；旧 finding 不能因为重编译覆盖而被抹去。

package/template/.codex/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -25,11 +25,11 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 
 调用本技能前由生命周期编排器展示 `scripts/backend-platforms` 的精确版本清单及兼容状态，并通过 `gate.backend-architecture-platform-approved` 把架构、Spring Boot、Java 和 YSS 父 POM/BOM 合并展示、取得真实用户确认；生成器不提问、不猜版本、不使用 `x` 或 `latest`。已有批准且当前的选择展示摘要后复用；既有工程核验并复用登记值，不触发该门禁。
 
-- 候选平台：Boot 2.7.18 / Java 8，Boot 3.5.16 / Java 17 或 21，Boot 4.1.1 / Java 17 或 21。新 Boot 默认推荐 Java 17；候选不等于可生成。
+- 精确候选版本与可选状态只读取 `scripts/backend-platforms` 和共享平台清单，不在此复制版本表；候选不等于可生成。
 - 独立子项目可继承主项目组合或覆盖，必须逐项目确认（允许一次确认明确列出的项目）；同一 Maven Reactor 使用一个平台。
 - 只开放共享兼容清单中已有真实 YSS 构建、依赖和启动证据的组合。缺少兼容父 POM、BOM、starter 或相应能力证据即 `blocked`；不替换官方组件、不降级回退。
 - 新生成合同必须有 `platform_configuration` v2，与架构决策、Maven 坐标及兼容条目摘要一致。Boot、Java、YSS 坐标或依赖配方变化时回生命周期重新确认并编译合同；仅追加同配置验证记录不重复确认，仍核验证据有效性。
-- Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Boot 3.5 / 4.1 拒绝 Java 8/11。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
+- Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Java 下限和允许组合由当前平台条目决定。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
 - 平台候选维护验证产物标记 `platform_verification=candidate`，不能交给业务生成、升级完成等级或进入首切片验证。测试夹具不证明 YSS 兼容。
 
 版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `docs/engineering/backend-platforms.md`。
@@ -47,36 +47,7 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 
 ## 推荐命令
 
-```bash
-node scripts/generate_and_verify_scaffold.mjs \
-  --project-name my-service \
-  --base-package com.yss.myservice \
-  --group-id com.yss.datamiddle \
-  --project-version 1.0.0-SNAPSHOT \
-  --parent-group-id com.yss.datamiddle \
-  --parent-artifact-id yss-datamiddle-parent \
-  --parent-version 2.0.0-SNAPSHOT \
-  --yss-components-version 2.0.0-SNAPSHOT \
-  --output-dir /path/to/implementation-repo \
-  --contract-id <approved-scaffold-contract-id> \
-  --contract-version <current-version> \
-  --approval-ref <lifecycle-approval-ref> \
-  --compiler-draft-ref <compiler-draft-ref> \
-  --persisted-ref <persisted-contract-ref> \
-  --contract-file /path/to/persisted-scaffold-contract.json \
-  --evidence-dir /path/to/evidence/scaffold
-```
-
-完成批准的 golden first slice 后运行：
-
-```bash
-node scripts/run_first_slice_verification.mjs \
-  --project-root /path/to/implementation-repo/my-service \
-  --slice-contract-file /path/to/approved-slice-contract.yaml \
-  --contract-root /path/to/contract-repository \
-  --approval-ref docs/approved-checkpoint.yaml \
-  --evidence-dir /path/to/evidence/first-slice
-```
+输入和合同已核验后，按 [受控生成命令示例](references/command-examples.md) 组装当前参数；示例值不授予生成或覆盖权限。
 
 ## 生成结果应包含
 
@@ -95,7 +66,7 @@ node scripts/run_first_slice_verification.mjs \
 - 永不生成 `User CRUD` 示例；`--with-example` 已禁用，业务代码必须按批准的 Slice Implementation Contract 逐切片实现。
 - 若目标工程已经存在，直接返回 `unsupported`。旧项目继续按原工程维护；需要现代化时单独立项、先评估再逐切片迁移，不属于本 skill。
 - 输出目录必须显式指定；目标工程目录必须不存在，`--force` 永久拒绝。
-- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。`git-submodule` gitlink、空挂载点、detached HEAD 工作树不得覆盖生成，即使传入 `--force` 也不得当成普通目录，且不得走「请显式传入 `--force`」普通目录覆盖 / rename 路径。`--output-dir` 指向 detached HEAD 子仓时不得 mkdir、staging 或生成工程。先 `git submodule update --init` 并在子仓附加分支工作树内生成。生成器必须先调用 `gitSubmoduleScaffoldViolation`，再在 exists / `--force` / rename 之前调用 `refuseGitlinkAsRegularDirectory`。
+- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。`git-submodule` gitlink、空挂载点、detached HEAD 工作树不得覆盖生成，即使传入 `--force` 也不得当成普通目录，且不得走「请显式传入 `--force`」普通目录覆盖 / rename 路径。`--output-dir` 指向 detached HEAD 子仓时不得 mkdir、staging 或生成工程。先 `git submodule update --init` 并在子仓附加分支工作树内生成。维护生成器时按 [守卫顺序](references/generator-maintenance.md) 检查，不能将 gitlink 当普通目录。
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
 - 生成时的工程基线由本 skill 的 `references/engineering-baseline.md` 持有并绑定摘要；它不是独立 Skill。生成后必须回到 实现合同编译器，并按批准切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-mybatis`、`yss-web-controller`、`yss-dto`、`yss-exception`、`yss-validation`、`mapstruct`、`lombok`、`alibaba-java-code-style` 等实际命中的行为 skill。
@@ -103,7 +74,7 @@ node scripts/run_first_slice_verification.mjs \
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。
 - 脚手架合同必须携带 `contract_id`、`contract_version`、实现合同编译器 draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
-- 新脚手架只接受统一 Project Scaffold Contract schema v4，并必须以原始字节摘要绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和真实工程合同批准记录。API `required` 必须闭包绑定同一 OpenAPI YAML 字节的 Validation、独立 Review、Freeze 与工程批准；`not-applicable` 必须绑定评估、明确原因和证据且禁止空占位资产。历史 schema v3/v2 仅用于 Manifest 只读验证和补齐 API 对账后的恢复审计，不用于新生成。
+- 新脚手架只接受统一 Project Scaffold Contract schema v4，并必须以原始字节摘要绑定批准且当前的 Technical Design、Data Architecture Decision v1、API Contract Decision v1 和真实工程合同批准记录。API `required` 必须闭包绑定同一 OpenAPI YAML 字节的 Validation、独立 Review、Freeze 与工程批准；`not-applicable` 必须绑定评估、明确原因和证据且禁止空占位资产。历史 Manifest 只读审计见 [历史兼容边界](references/generator-maintenance.md)，不得用于新生成。
 - DDD 固定 `target-domain-model`、`mybatis-plus`、H2 验证、`web` DTO、`yss-internal`；平台与 Validation 命名空间由共享清单约束。普通 MyBatis、独立 client module、client-in-domain 和其他旧架构仍为 `unsupported`。
 - 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation`、实际输出路径和固定三条验证命令，不接受仅凭任意字符串引用的放行。
 - 生成项目必须写入 Manifest v4 `.yss/scaffold-generation.json`，记录技术、数据与 API 设计门禁、架构选择及 digest、生成器、合同 digest、Target Profile、模块闭包、模板 digest、下游完整 当前合同 freshness、generator-owned 文件 hash、严格 `generation_policy` 和完成等级；清单缺失或不一致时不得交给后续 实现合同编译器。

package/template/.codex/skills/yss-ddd-scaffold-generator/references/command-examples.md

@@ -0,0 +1,32 @@
+## 推荐命令
+
+```bash
+node scripts/generate_and_verify_scaffold.mjs \
+  --project-name my-service \
+  --base-package com.yss.myservice \
+  --group-id com.yss.datamiddle \
+  --project-version 1.0.0-SNAPSHOT \
+  --parent-group-id com.yss.datamiddle \
+  --parent-artifact-id yss-datamiddle-parent \
+  --parent-version 2.0.0-SNAPSHOT \
+  --yss-components-version 2.0.0-SNAPSHOT \
+  --output-dir /path/to/implementation-repo \
+  --contract-id <approved-scaffold-contract-id> \
+  --contract-version <current-version> \
+  --approval-ref <lifecycle-approval-ref> \
+  --compiler-draft-ref <compiler-draft-ref> \
+  --persisted-ref <persisted-contract-ref> \
+  --contract-file /path/to/persisted-scaffold-contract.json \
+  --evidence-dir /path/to/evidence/scaffold
+```
+
+完成批准的 golden first slice 后运行：
+
+```bash
+node scripts/run_first_slice_verification.mjs \
+  --project-root /path/to/implementation-repo/my-service \
+  --slice-contract-file /path/to/approved-slice-contract.yaml \
+  --contract-root /path/to/contract-repository \
+  --approval-ref docs/approved-checkpoint.yaml \
+  --evidence-dir /path/to/evidence/first-slice
+```

package/template/.codex/skills/yss-ddd-scaffold-generator/references/generator-maintenance.md

@@ -0,0 +1,7 @@
+# 生成器维护与历史审计
+
+仅维护生成器或审计历史 Manifest 时读取；正常新生成继续消费入口中的批准合同与当前 schema。
+
+生成器必须先调用 `gitSubmoduleScaffoldViolation`，再在 exists / `--force` / rename 之前调用 `refuseGitlinkAsRegularDirectory`。
+
+历史 schema v3/v2 仅用于 Manifest 只读验证和补齐 API 对账后的恢复审计，不用于新生成。

package/template/.codex/skills/yss-design-system/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-design-system
-description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格基线。涉及页面设计、原型评审、UI 实现、组件选型、主题 token、颜色排版间距、响应式验收、Ant Design/YSS UI 风格一致性、docs/design/design.md 更新或从外部设计系统引入规范时必须使用。
+description: 建立或核验 YSS 设计系统、主题 Token 与页面视觉一致性；用于设计规范变更、原型评审及按当前设计基线验收。
 ---
 
 # YSS Design System
@@ -18,7 +18,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 - Codex `$design-qa` 项目对照：`references/design-qa-theme.md`，不替代官方 `design-qa` 流程，也不改上游插件正文。
 - 原型阶段合同：`yss-prototype-stage`，用于统一 H1/H2 原型资产和浏览器验证证据。H1/H2 默认使用项目 Token 驱动的 HTML/CSS/JavaScript 离线原型。
 
-如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 Token，必须按 `DESIGN.md` → `docs/design/design.md` → `docs/design/tokens/*` 顺序读取；若要执行评审或实现检查，再读 `references/design-system.md`。
+如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 Token，必须按 `DESIGN.md` → `docs/design/design.md` 顺序读取，再按当前主题、密度与输出表面选择对应 Token 文件，不全量预读所有主题；若要执行评审或实现检查，再读 `references/design-system.md`。
 
 ## 使用流程
 

package/template/.codex/skills/yss-domain/SKILL.md

@@ -1,19 +1,21 @@
 ---
 name: yss-domain
-description: 用于构建或重构 YSS 领域层代码。当用户要求设计聚合、Entity、Domain Gateway、领域规则、状态流转或先做领域建模再补持久层时调用。
+description: 按已批准的 DDD 技术设计实现或重构领域行为、不变量、状态机与 Gateway；不负责起草领域设计。
 ---
 
 # yss-domain
 
 这是一个领域实现 skill。核心目标是消费已批准的战术模型，将领域行为落实为代码；`yss-technical-design` 组织 DDD 分支，由 `yss-tactical-design` 设计、`yss-product-lifecycle` 维护批准。
 
+既有工程先读取 `references/existing-project.md`，按登记的职责和批准边界审计或整改；只读审计不要求批准 Slice。
+
 本 skill 在新脚手架链路只支持 `domain-driven` / `target-domain-model`。`layered-mvc-service` 与 `mvc-data-analysis-v1` 是独立 MVC Profile，不是失败的 DDD 工程；它们不加载本 skill，也不生成 Domain Gateway。既有旧架构不在本链路内迁移。
 
 ## 何时使用
 
-- 用户要求先做 Domain、先抽象实体或聚合。
-- 用户要补 `Entity`、`Gateway`、领域规则或状态机。
-- 用户给出页面流程、业务规则、DDL，希望先沉淀领域模型。
+- 当前已批准的 DDD Slice Contract 要求实现或修复领域行为、不变量或状态机。
+- 在既有已确认领域边界内重构 Entity、Value Object、Domain Event 或 Gateway。
+- 需要从需求、页面或 DDL 决定聚合及领域边界时，回交 `yss-technical-design` / `yss-tactical-design`，不先写领域代码。
 
 ## 不适用
 
@@ -36,17 +38,27 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 
 ## 建模约束
 
+<a id="domain.dependencies"></a>
+<!-- yss-rule {"id":"domain.dependencies","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - Domain 层不依赖 Repository、Mapper、Controller。
+<a id="domain.behavior"></a>
+<!-- yss-rule {"id":"domain.behavior","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - 领域行为放在模型方法，不要放在 Web 层。
+<a id="domain.gateway"></a>
+<!-- yss-rule {"id":"domain.gateway","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - Gateway 只暴露领域能力，不暴露持久化细节。
 - 对关键状态流转给出明确方法，如 `publish()`、`cancel()`、`terminate()`。
+<a id="domain.invariants"></a>
+<!-- yss-rule {"id":"domain.invariants","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - 明确 Aggregate Root、Entity identity、Value Object、不变量、Domain Event 和一致性边界；没有业务行为时不要伪造富领域模型。
-- 发现旧架构时停止套用新脚手架合同并返回 `unsupported`；旧项目继续按原工程维护，现代化改造单独立项。
+- `unsupported` 只阻断不支持的生成方式。既有 DDD 按登记边界整改；目录差异不是领域违规。架构身份转换或公开契约迁移单独立项，MVC 不套用 DDD 规则。
 
 ## 质量要求
 
 - 命名体现业务语义，不照抄表名缩写。
 - 生成代码应可编译，且没有跨层依赖泄漏。
+<a id="domain.gateway-owner"></a>
+<!-- yss-rule {"id":"domain.gateway-owner","when":"domain","level":"mandatory","evidence":"code-and-verification"} -->
 - Domain Gateway interface 由本 skill 唯一拥有；Infrastructure 只能实现，不得由 `yss-repository` 反向创建或改写其签名。
 - 对不确定规则返回 `new_impacts` / `drift` 并暂停；不要把未批准假设或 TODO 写进实现冒充已确认事实。
 

package/template/.codex/skills/yss-domain/references/domain-layer-guide.md

@@ -1,6 +1,6 @@
 # YSS Domain Target Profile 指南
 
-本指南只定义新 DDD `target-domain-model`。历史 DTO/VO 型 Gateway、`core/client/repository` 和贫血对象均为 `unsupported`，不存在旧架构 Profile 或迁移分支。
+本指南的目录和生成布局只定义新 DDD `target-domain-model`。既有 DDD 通过 [既有工程边界](existing-project.md) 应用领域语义规则；历史目录或贫血对象不能单凭名称判违规。HTTP DTO/VO 穿入领域端口仍须按登记职责检查。架构迁移不属于生成器。
 
 ## 1. Domain 所有权
 
@@ -98,7 +98,7 @@ Web Exception Translator 再将它映射为批准的状态码、错误码和消
 - 消费批准且当前的 Tactical Design 与 Slice Implementation Contract。
 - 返回 YSS Skill Execution Result，包含 Domain 文件、行为测试、ArchUnit 结果及实际 `./mvnw ...` 证据。
 - 新聚合、不变量、状态机或跨上下文影响进入 `new_impacts` 并暂停。
-- 检测到旧架构时返回 `unsupported`；如需现代化，退出 scaffold 工作流并单独立项评估。
+- 旧布局不走 scaffold 生成分支；既有 DDD 按登记整改。需改变架构或公开契约时单独评估并批准。
 
 ## 聚合创建与重建
 

package/template/.codex/skills/yss-domain/references/existing-project.md

@@ -0,0 +1,5 @@
+# 既有领域工程
+
+只对 `existing-domain-driven-maven` 或登记为 DDD 的只读盘点范围应用领域语义。读取实际 build unit、role_paths、source roots 与工程基线；不要求 target 模块名、Entity 后缀或生成 Manifest。创建/重建、不变量、端口所有权和技术依赖边界仍按 domain-layer-guide 检查。MVC 不创建聚合或 Gateway。
+
+只读审计允许缺设计资产，但记录 missing_evidence。修改消费当前批准 Slice 和已确认行为 seam；不得从历史代码伪造业务规则批准。新增聚合、改变一致性或架构身份回设计与合同编译器。