create-yss-spec 3.5.6 → 3.5.9

package/template/.codex/skills/product-design/references/critical-overrides.md

@@ -8,10 +8,8 @@ These rules override generic assistant defaults for Product Design work.
 
 ## Saved User Context
 
-- If `user-context.md` exists, use it by default.
-- Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets to ground Product Design work.
-- Ideation, prototypes, audits, clones, and critiques should match the saved product context unless the user asks for something different.
-- When a workflow needs visual grounding, attach or include relevant saved screenshots, reference images, tokens, design language, and component references in ImageGen, ideation, prototype, audit, and critique work.
+- Follow [User Context](../skills/user-context/SKILL.md#saved-user-context) for saved sources and preferences. Use its [conditional Preflight](../skills/user-context/SKILL.md#preflight) when saved context is needed, and reuse the loaded result while its state paths, digests, and relevant scope are unchanged.
+- Inspect only references needed for the current task. When visual grounding is needed, include the relevant saved images, tokens, design language, and component references in the current workflow; user-requested changes still take precedence.
 
 ## Design Brief Gate
 
@@ -19,7 +17,8 @@ These rules override generic assistant defaults for Product Design work.
 - `$get-context` can run in question mode or playback mode. If required product, visual, or interactivity details are missing, ask for them. If those details are already present, play back the brief in a pithy format before moving to the next workflow.
 - Do not proceed to ideation or implementation until the brief has been played back and either confirmed by the user or already confirmed earlier in the thread.
 - A confirmed design brief is not a visual target. Use the confirmed brief as input to `$ideate` unless the user has already provided a concrete visual source such as a URL, screenshot, image, mockup, or Figma frame.
-- After the user approves the design brief and the next step is an involved app, prototype, clone, redesign, or build, send one short expectation-setting note before starting work. Say that involved builds often take about 10-15 minutes, ambitious builds can take longer, and invite the user to grab coffee or tend to other work while Product Design keeps moving. Simpler static prototypes can be faster, often 5-10 minutes. Keep it warm and lightly playful, not apologetic or over-explanatory. Skip this note for tiny static changes, quick audits, simple research, setup-only, or share-only requests.
+- Reuse a brief already confirmed in the current thread while its scope and inputs remain current; missing or changed decisions still require a real user response.
+- After the user approves the brief and the next step is an involved app, prototype, clone, redesign, or build, briefly explain the next work, its checks, and any material uncertainty. Give a time estimate only with a stated basis, scope, and conditions. Skip this note for tiny static changes, quick audits, simple research, setup-only, or share-only requests.
 
 ## How to communicate
 

package/template/.codex/skills/product-design/skills/audit/SKILL.md

@@ -23,11 +23,9 @@ The output is not a loose opinion. The output is:
 
 ## User Context
 
-Before starting, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+When the workflow needs saved product or design context, load [$user-context](../user-context/SKILL.md) and follow its [conditional Preflight](../user-context/SKILL.md#preflight). Reuse the loaded result while its state paths, digests, and relevant scope are unchanged.
 
-Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets as grounding material when relevant.
-
-Do not inspect every saved reference. Inspect only what the current task needs.
+Use relevant saved sources and preferences as grounding material under [Saved User Context](../user-context/SKILL.md#saved-user-context). Inspect only references needed for the current task.
 
 ## Route
 

package/template/.codex/skills/product-design/skills/get-context/SKILL.md

@@ -27,15 +27,13 @@ Hard boundary: do not implement UI, scaffold a prototype, start a server, or cre
 
 ## User Context
 
-Before starting, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+When the workflow needs saved product or design context, load [$user-context](../user-context/SKILL.md) and follow its [conditional Preflight](../user-context/SKILL.md#preflight). Reuse the loaded result while its state paths, digests, and relevant scope are unchanged.
 
-Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets as grounding material when relevant.
-
-Do not inspect every saved reference. Inspect only what the current task needs.
+Use relevant saved sources and preferences as grounding material under [Saved User Context](../user-context/SKILL.md#saved-user-context). Inspect only references needed for the current task.
 
 ## Get Context Script
 
-The following three questions should be answered by the user. Adapt the questions based on what the user has provided so far in the conversation. If some or all fields are already known, skip the questions and summarize the design brief in your own words.
+Resolve the product goal, visual source or direction, and interactivity level. Reuse supplied details and current confirmations; ask only about missing decisions. If the fields are known, summarize the design brief in your own words.
 
 The questions to answer are:
 
@@ -67,14 +65,14 @@ Interactivity level: full working form states, or a faster mostly-static mock?
 
 ## Final message
 
-1. Before proceeding to `$ideate`, `$prototype`, `$url-to-code`, or `$image-to-code`, confirm the design brief by explaining it back to the user in a pithy format as a `final` message.
+1. Reuse the exact brief already confirmed in the current thread while its scope and inputs remain current. Otherwise, before proceeding to `$ideate`, `$prototype`, `$url-to-code`, or `$image-to-code`, explain the brief back to the user as a concise `final` message for confirmation.
 
 2. Proceed only after the user confirms the design brief, unless the current thread already contains confirmation of that exact brief. If the user provides feedback, continue to refine the design brief with them.
 
-3. After the user confirms the design brief, send one short expectation-setting note before starting an involved app, prototype, clone, redesign, or build. Example confirmation message with expectations setting:
+3. After the user confirms the design brief, send a short note before starting an involved app, prototype, clone, redesign, or build. Explain the next work and how it will be checked; state any material uncertainty. Give a time estimate only when it has a stated basis, scope, and conditions. For example:
 
 ```text
-Lovely, brief locked. This kind of build usually takes about 10-15 minutes, and ambitious ones can take longer. Good moment to grab coffee or tend to something else; I'll keep moving and bring the prototype back when it is ready.
+The brief is confirmed. I'll build the agreed screens, verify their states, and compare the rendered result with the selected design before handing it back.
 ```
 
 Do not send this note for tiny static changes, quick audits, simple research, setup-only, or share-only requests.

package/template/.codex/skills/product-design/skills/ideate/SKILL.md

@@ -16,7 +16,7 @@ Follow the shared Product Design routing guidance in [$index](../index/SKILL.md)
 
 ## User Context
 
-Before starting, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+When the workflow needs saved product or design context, load [$user-context](../user-context/SKILL.md) and follow its [conditional Preflight](../user-context/SKILL.md#preflight). Reuse the loaded result while its state paths, digests, and relevant scope are unchanged.
 
 Attach provided product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets to the Image Gen generations to align them to the design brief.
 
@@ -53,7 +53,7 @@ Before generating images:
 - If useful local design context exists and the user has not asked for a new style, stay within that existing direction.
 - If no useful design context exists, or the user asks for broad exploration, vary both concept and visual system.
 - For a specific component or existing surface, vary structure, interaction, hierarchy, and emphasis before varying brand style.
-- For a broad product idea, explore three meaningfully different product directions.
+- For a broad product idea, explore meaningfully different product directions using the user's requested count; default to three when exploration is needed.
 
 5. Choose target dimensions before Image Gen.
 
@@ -80,7 +80,7 @@ Before generating images:
 
 8. Attach images and mocks provided by the user to the Image Gen call along with your design brief.
 
-9. Generate 3 independent options that have distinct information hierarchy, layout strategy, interaction model, or product framing.
+9. Generate the requested number of independent options (default three when exploration is needed), with distinct information hierarchy, layout strategy, interaction model, or product framing.
 
 Rules you must follow:
 

package/template/.codex/skills/product-design/skills/image-to-code/SKILL.md

@@ -14,11 +14,9 @@ You're tasked with translating the visual target image into a high-quality, inte
 
 ## User Context
 
-Before starting, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+When the workflow needs saved product or design context, load [$user-context](../user-context/SKILL.md) and follow its [conditional Preflight](../user-context/SKILL.md#preflight). Reuse the loaded result while its state paths, digests, and relevant scope are unchanged.
 
-Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets as grounding material when relevant.
-
-Do not inspect every saved reference. Inspect only what the current task needs.
+Use relevant saved sources and preferences as grounding material under [Saved User Context](../user-context/SKILL.md#saved-user-context). Inspect only references needed for the current task.
 
 ## Workflow
 
@@ -51,7 +49,7 @@ CRITICAL: THIS IS NOT GUIDANCE. THIS IS A CHECKLIST TO COMPLETE.
     - If text is part of an image asset, keep it in the image asset. Examples include full bleed hero images, signs, posters, packaging, storefronts, article art, and illustrations where the type belongs to the visual itself. Do not crop the background image and recreate that text with transparent text boxes, HTML, CSS, or separate overlay layers unless the source clearly shows editable UI text sitting on top of the image.
     - Do not use generic placeholders where the reference implies custom visual content.
     - Generated assets must share the same art direction, palette, rendering style, and design language as the reference mockup.
-    - The built-in Image Gen tool does not support transparent images; post-process generated assets when transparency is required.
+    - When transparency is required, use the current image tool's documented transparent-background parameter and inspect the actual output. The current built-in Image Gen contract supports `transparent_background: true` for transparent generation, background removal, or cutouts; preserve existing transparency in edits unless the user asks to change it. If another runtime lacks that parameter, report its capability limit and use only the options supported by its actual tool contract.
 
 5. Define all sections of the page. For each section, meticulously measure the layout, spacing between elements, and the size and space of the elements themselves.
 

package/template/.codex/skills/product-design/skills/index/SKILL.md

@@ -71,7 +71,7 @@ Use this close:
 Want to onboard Product Design with your context? Send product URLs, Figma files, screenshots, codebase paths, Storybook links, tokens, brand assets, or preferred share targets, and I'll save them for future work.
 ```
 
-Before routing to Product Design workflows, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+When routing needs saved product or design context, load [$user-context](../user-context/SKILL.md) and follow its [conditional Preflight](../user-context/SKILL.md#preflight). Reuse the loaded result while its state paths, digests, and relevant scope are unchanged; inspect only references needed for the current task.
 
 ## Browser Annotation Updates
 

package/template/.codex/skills/product-design/skills/prototype/SKILL.md

@@ -26,11 +26,9 @@ Select the best workflow from the following options to solve the user's request
 
 ## User Context
 
-Before starting, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+When the workflow needs saved product or design context, load [$user-context](../user-context/SKILL.md) and follow its [conditional Preflight](../user-context/SKILL.md#preflight). Reuse the loaded result while its state paths, digests, and relevant scope are unchanged.
 
-Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets as grounding material when relevant.
-
-Do not inspect every saved reference. Inspect only what the current task needs.
+Use relevant saved sources and preferences as grounding material under [Saved User Context](../user-context/SKILL.md#saved-user-context). Inspect only references needed for the current task.
 
 ## Setup Is Not Prototype Work
 

package/template/.codex/skills/product-design/skills/research/SKILL.md

@@ -23,11 +23,9 @@ Both modes remain UX research workflows. Do not import academic-paper writing, p
 
 ## User Context
 
-Before starting, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+When the workflow needs saved product or design context, load [$user-context](../user-context/SKILL.md) and follow its [conditional Preflight](../user-context/SKILL.md#preflight). Reuse the loaded result while its state paths, digests, and relevant scope are unchanged.
 
-Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets as grounding material when relevant.
-
-Do not inspect every saved reference. Inspect only what the current task needs.
+Use relevant saved sources and preferences as grounding material under [Saved User Context](../user-context/SKILL.md#saved-user-context). Inspect only references needed for the current task.
 
 ## Contract
 
@@ -87,10 +85,10 @@ Default to an in-chat research brief unless the user asks for another format.
 
 Include:
 
-- Executive read: the core story in 5-7 sentences.
+- Executive read: the core problem, conclusion, and evidence limits, with enough context for the current decision.
 - Ranked UX problems: for each problem, include the problem, user goal, surface, what breaks, evidence, severity, frequency signal, confidence, and recommended product move.
 - Source map: what was searched, what each source contributed, and where signal was weak.
-- Opportunity map: group recommendations into fix this week, fix this quarter, and needs deeper research.
+- Opportunity map: organize recommendations by supported priority, dependencies, and questions needing deeper research. Use scheduling dates only when supplied or confirmed; do not turn research recommendations into delivery commitments.
 
 When the user explicitly asks to persist an `evidence-audited` result, create two adjacent files named `<slug>-research-brief.md` and `<slug>-evidence.yaml`. Start from [research-brief-template.md](assets/research-brief-template.md) and [evidence-template.yaml](assets/evidence-template.yaml), then run:
 

package/template/.codex/skills/product-design/skills/research/assets/research-brief-template.md

@@ -10,7 +10,7 @@
 
 ## Executive Read
 
-Summarize the product story in 5–7 sentences.
+Summarize the core problem, conclusion, and evidence limits, with enough context for the current decision.
 
 ## Ranked UX Problems
 
@@ -22,9 +22,9 @@ Explain what was searched, what each source class contributed, exclusions, faile
 
 ## Opportunity Map
 
-### Fix This Week
+Group recommendations by supported priority, dependencies, and unresolved research. Include scheduling dates only when supplied or confirmed; recommendations do not establish delivery commitments.
 
-### Fix This Quarter
+### Recommended Actions
 
 ### Needs Deeper Research
 

package/template/.codex/skills/product-design/skills/share/SKILL.md

@@ -14,11 +14,9 @@ Deploy the user's runnable prototype so they can share it with others.
 
 ## User Context
 
-Before starting, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+When the workflow needs saved product or design context, load [$user-context](../user-context/SKILL.md) and follow its [conditional Preflight](../user-context/SKILL.md#preflight). Reuse the loaded result while its state paths, digests, and relevant scope are unchanged.
 
-Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets as grounding material when relevant.
-
-Do not inspect every saved reference. Inspect only what the current task needs.
+Use relevant saved sources and preferences as grounding material under [Saved User Context](../user-context/SKILL.md#saved-user-context). Inspect only references needed for the current task.
 
 ## Workflow
 

package/template/.codex/skills/product-design/skills/url-to-code/SKILL.md

@@ -14,11 +14,9 @@ Clone `<target-url>` as a real interactive, frontend-only local app or website.
 
 ## User Context
 
-Before starting, load [$user-context](../user-context/SKILL.md) and run its preflight script when local shell access is available.
+When the workflow needs saved product or design context, load [$user-context](../user-context/SKILL.md) and follow its [conditional Preflight](../user-context/SKILL.md#preflight). Reuse the loaded result while its state paths, digests, and relevant scope are unchanged.
 
-Use saved product URLs, Figma files, screenshots, reference images, codebase paths, Storybook, tokens, design systems, brand assets, component refs, browser preferences, and share targets as grounding material when relevant.
-
-Do not inspect every saved reference. Inspect only what the current task needs.
+Use relevant saved sources and preferences as grounding material under [Saved User Context](../user-context/SKILL.md#saved-user-context). Inspect only references needed for the current task.
 
 ## Workflow
 

package/template/.codex/skills/product-design/skills/user-context/SKILL.md

@@ -143,5 +143,5 @@ Keep saved context curated. Prefer a few high-value references over a dump of ev
 ## Read
 
 - Do not treat `status: not provided` as a fact.
-- Read through `scripts/user_context_preflight.py` when local shell access is available.
+- Read saved context through the conditional [Preflight](#preflight) above when local shell access is available; reuse its loaded result while the state paths, digests, and relevant scope are unchanged.
 - Use saved context as default grounding, then inspect only what the current task needs.

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

@@ -19,9 +19,9 @@ See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking g
 
 A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
 
-**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+**Test only at pre-agreed seams.** Before writing tests, first read the current approved contract (the Slice Implementation Contract for YSS implementation), its public seam references and the applicable user-decision evidence. Reuse confirmed seams covered by the same valid contract/decision version, scope and basis without asking the user again; follow the existing user-decision protocol selected by root `AGENTS.md` and the lifecycle owner when checking approval continuation.
 
-Ask: "What's the public interface, and which seams should we test?"
+If a seam is missing, newly introduced or materially changed, the contract is `stale`, or confirmation cannot be proved from readable evidence, stop tests and implementation that depend on that seam and return to the lifecycle owner to update the contract and obtain any required decision. Independent work may continue. Elapsed time and unrelated file changes do not expire seam confirmation; changed relevant inputs require freshness and scope checks under the same protocol. No test is written at an unconfirmed seam. Agreeing seams directs testing effort to critical paths and complex logic.
 
 When the shape of that interface is itself in question — how deep the module is, where the seam belongs, what the interface should expose — use the `/codebase-design` skill for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run.
 

package/template/.codex/skills/theme-token-usage/SKILL.md

@@ -20,12 +20,12 @@ description: "实现或修复 Vue3 YSS UI 主题、交互状态色与动态换
 
 ## 开发前检查
 
-1. 读取当前微应用的 `packages/src/styles/variables.less`、主题 store/config 和相近页面，确认真实 Token 名称与运行时同步逻辑。
+1. 从目标工程实际的主题入口、store/config 和相近页面定位 Token 声明与同步逻辑；`variables.less` 只作为存在时的路径线索。当前 bundled 骨架使用 `packages/src/config/theme.json`、`packages/src/store/theme.ts`、`packages/src/styles/index.less` 与 `ThemeScope.vue`。
 2. 确认主应用传入的 `colorPrimary` 最终是否同步到 Ant Design ConfigProvider、YSS CSS 变量和 VXE 变量。
 3. 搜索本次改动涉及的硬编码色值，覆盖 SFC style、`style.less`、内联 `style`、`:style`、TS 配置、SVG `fill/stroke`。
 4. 区分“主题消费代码”和“主题定义代码”；禁止机械替换主题源文件中的合法默认色板。
 
-> 变量在 `:root` 中声明，不代表它会随运行时主题更新。必须同时检查主题同步代码是否写入该变量。
+> 变量在 `:root` 或应用容器中声明，不代表它会随运行时主题更新。必须同时检查主题同步代码是否写入该变量，以及消费节点是否处于相同作用域。
 
 ## Token 选择
 
@@ -65,8 +65,9 @@ box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, tran
 
 ## 标准代码骨架
 
+下面只说明语义 Token 的消费方式；变量名称、fallback 与默认值须先核对目标工程。主题已由应用入口注入时，不另加不存在的 Less 导入。
+
 ```less
-@import url('@/styles/variables.less');
 
 .module-card {
   color: var(--text-color, rgba(0, 0, 0, 0.88));
@@ -94,7 +95,7 @@ box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, tran
 }
 ```
 
-仅在 JS、图表或 Canvas 必须读取计算后色值时，优先使用 Ant Design Vue `theme.useToken()`；若消费微应用 CSS 变量，则通过 `getComputedStyle(document.documentElement)` 读取，不复制默认色板到业务常量。
+仅在 JS、图表或 Canvas 必须读取计算后色值时，优先使用当前 ConfigProvider 内的 Ant Design Vue `theme.useToken()`。消费 CSS 变量时，对实际获得主题变量的应用容器或其消费节点调用 `getComputedStyle()`；当前 bundled 微应用只向自己的容器同步变量，不读取或写入宿主 `documentElement`。只有已核验主题同步到文档根节点的独立应用，才从该根节点读取。不复制默认色板到业务常量。
 
 ## 验证流程
 
@@ -117,7 +118,7 @@ box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color, #3371ff) 15%, tran
 
 ## 失败兜底策略
 
-- 找不到 Token 时，先查项目 `variables.less`、主题 store/config 和 `llms-full.txt`；禁止猜测变量名。
+- 找不到 Token 时，先查项目实际主题入口、store/config 和匹配版本的文档；`variables.less` 存在时才读取，禁止猜测变量名或创建同名文件充当输入。
 - 只有颜色值但没有语义 Token 时，先在统一主题源补充语义变量和运行时同步，再在页面消费。
 - 第三方组件不跟随主题时，优先通过 ConfigProvider/component token 或其官方 CSS 变量桥接；最后才使用受控的深度样式覆盖。
 - 浏览器目标不支持 `color-mix()` 时，在主题层生成并同步明确的透明态变量；不要在各页面散落固定透明色。

package/template/.codex/skills/wayfinder/references/chart-map.md

@@ -7,8 +7,8 @@
 User invokes with a loose idea.
 
 1. **Name the destination.** Run a `/grilling` and `/domain-modeling` session to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first.
-2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
+2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. If no open decision remains and the work fits one session, return the settled destination, scope and evidence to the active orchestrator. Continue within the existing authorization; ask only for a missing real decision or new authorization.
 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
 4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
-5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/yss-research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket. `/research` remains only as a deprecated compatibility alias.
+5. **Dispatch research.** Route independent research tickets to `yss-research` when the runtime supports delegation; otherwise research in the current session. Follow the registered task-package and evidence contracts, and link the resulting sources from the ticket. Read-only intake uses schema v2 with empty write scope; formal research requires a new owner-issued task package. Template maintenance evidence stays in the registered external maintenance directory. Research does not require creating a Git branch.
 6. Stop — charting is one session's work; it hand-resolves nothing.

package/template/.codex/skills/wayfinder/references/ticket-types.md

@@ -6,7 +6,7 @@
 
 Every ticket is either **HITL** — human in the loop, worked _with_ a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
 
-- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/yss-research` **subagent** (`/research` is a deprecated alias). Use when knowledge outside the current working directory is required.
+- **Research** (AFK): Reading documentation, third-party APIs, or local resources to surface a fact a decision waits on. Route to `yss-research`, delegating independent reading when supported. Use when a decision needs evidence unavailable in the current inputs; local evidence and external sources follow the same source policy.
 - **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
 - **Grilling** (HITL): Conversation. The default case. Always invoke the /grilling and /domain-modeling skills.
 - **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.

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

@@ -5,24 +5,22 @@ description: "在 Vue3 YSS UI 中对接 Orval API；核验生成方法、mutator
 
 # API 集成 Skill
 
-本目录是 API 集成的 canonical 技能；历史名称 `api-integration` 仅通过注册表和 实现合同编译器 alias 解析，不再维护第二份内容。
+本技能的 canonical 名称为 `yss-api-integration`。历史名称 `api-integration` 只由注册表与实现合同编译器解析，不维护第二份内容。
 
-目录、frontmatter、注册表 ID 和 实现合同编译器 canonical 闭包键均为 `yss-api-integration`；历史名称 `api-integration` 只在注册表和 实现合同编译器 alias 表中解析为本技能。
-
-## 📋 目标
+## 目标
 
 帮助 AI 正确使用基于 **Orval** 生成的 API 客户端：
 
-- ✅ 正确导入 API 函数
-- ✅ 统一错误处理与 Toast 门禁
-- ✅ Loading 状态管理
-- ✅ 长整型 ID 精度保持
-- ✅ TypeScript 类型安全
+- 正确导入 API 函数
+- 统一错误处理与 Toast 门禁
+- Loading 状态管理
+- 长整型 ID 精度保持
+- TypeScript 类型安全
 
-## 🔍 前置条件
+## 前置条件
 
 1. **契约状态已明确**：
-   - 已有生成客户端：可以直接集成。
+   - 已有生成客户端：先核验冻结契约、JSON 派生记录和真实导出，输入当前且一致时可以直接集成。
    - 新增或变更 API：必须先在 `docs/.scratch/<feature>/api/<feature>.yaml` 形成 OpenAPI Draft，经工程基线 / 架构 / Spec Delta 设计和设计审查后 Freeze。冻结的 OpenAPI YAML 是唯一权威，JSON 仅为它的受控派生物。
    - 如果接口尚未冻结、JSON 派生记录缺失或生成函数不存在，先回到 `yss-product-lifecycle` / `yss-openapi-governance`，不要手写临时路径、DTO 或响应结构。
 2. **API 已生成**：在目标前端实现仓库中，按其既有的手动代码生成命令（例如 `pnpm generate:api`）刷新 API；本 Harness 不配置、不执行该命令，也不把它加入 CI。
@@ -41,9 +39,9 @@ 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` 命令是治理导出证据，不是前端集成任意重跑的入口。
+2. JSON 导出由 `yss-openapi-governance` 负责。`yss-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. `yss-api-integration` 只核对 JSON 派生记录、交接路径和 SHA-256，并把原始 JSON 交给既有前端代码生成流程；本 Harness 可只读核对目标前端的生成器配置与真实导出，但不修改该配置，不在此仓库执行生成，也不建立生成 CI 门禁。若 JSON SHA 与派生记录不一致，停止交接并回到治理流程。
 5. 目标前端项目在需要时手动运行其既有生成命令、类型检查和受影响组件 / API 测试；将实际命令、结果、生成输入 SHA 和偏离写入 `YSS Skill Execution Result`。
 
 ## 真实 mutator 响应契约
@@ -81,44 +79,9 @@ pnpm generate:api
 - 不得根据文档示例假定工厂一定名为 `getApi()`；Orval `title` 配置会影响真实名称。
 - 请求/响应 DTO 必须从当前生成的 `schemas` 导入，禁止重复声明。
 
-## 标准代码骨架
-
-以微应用的真实 `getApiApi()` 产物为例：
-
-```typescript
-import { reactive, ref } from 'vue';
-import { getApiApi } from '@/api/generated/quality';
-import type { QualityBusinessRuleVO, QualityRulePage } from '@/api/generated/quality/schemas';
-
-const { pageQualityRule } = getApiApi();
-
-/** 管理质量规则列表请求和分页状态。 */
-export const useQualityRuleList = () => {
-  const loading = ref(false);
-  const dataList = ref<QualityBusinessRuleVO[]>([]);
-  const query = reactive<QualityRulePage>({ pageIndex: 1, pageSize: 20, ruleName: '' });
-  const total = ref(0);
-
-  /** 加载规则列表。 */
-  const fetchData = async (): Promise<void> => {
-    loading.value = true;
-    try {
-      const res = await pageQualityRule(query);
-      dataList.value = res.data ?? [];
-      total.value = res.totalCount ?? 0;
-    } catch {
-      dataList.value = [];
-      total.value = 0;
-    } finally {
-      loading.value = false;
-    }
-  };
-
-  return { loading, dataList, query, total, fetchData };
-};
-```
+## 按需示例
 
-> 如果所在项目已生成 `pageQualityRule` 具名导出，直接导入该函数，删除上面的工厂实例行。
+首次组织列表请求或需比较具名导出与工厂导出时，读取 [Orval 列表示例](references/orval-list-example.md)。示例中的业务名称与响应字段仅作已核验版本的用法说明，目标工程仍消费自己的冻结 DTO 和真实导出。
 
 ## 长整型与数值类型
 

package/template/.codex/skills/yss-api-integration/references/orval-list-example.md

@@ -0,0 +1,38 @@
+## 标准代码骨架
+
+以微应用的真实 `getApiApi()` 产物为例：
+
+```typescript
+import { reactive, ref } from 'vue';
+import { getApiApi } from '@/api/generated/quality';
+import type { QualityBusinessRuleVO, QualityRulePage } from '@/api/generated/quality/schemas';
+
+const { pageQualityRule } = getApiApi();
+
+/** 管理质量规则列表请求和分页状态。 */
+export const useQualityRuleList = () => {
+  const loading = ref(false);
+  const dataList = ref<QualityBusinessRuleVO[]>([]);
+  const query = reactive<QualityRulePage>({ pageIndex: 1, pageSize: 20, ruleName: '' });
+  const total = ref(0);
+
+  /** 加载规则列表。 */
+  const fetchData = async (): Promise<void> => {
+    loading.value = true;
+    try {
+      const res = await pageQualityRule(query);
+      dataList.value = res.data ?? [];
+      total.value = res.totalCount ?? 0;
+    } catch {
+      dataList.value = [];
+      total.value = 0;
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  return { loading, dataList, query, total, fetchData };
+};
+```
+
+> 如果所在项目已生成 `pageQualityRule` 具名导出，直接导入该函数，删除上面的工厂实例行。

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

@@ -1,17 +1,23 @@
 ---
 name: yss-application
-description: Use when implementing YSS application use cases, transaction boundaries, cross-aggregate orchestration, idempotency, or application-level DTO conversion.
+description: 实现或排查 YSS 用例编排、事务边界、跨聚合协作、幂等和用例层模型转换；按已登记 DDD 或 MVC 架构执行。
 ---
 
 # yss-application
 
-## 架构分流（先执行）
+## 任务分流
 
-读取当前合同的 architecture_identity 并与工程基线、仓库登记及 Manifest 核对；再且只读取 `references/profiles/<architecture_profile>.md`。生成式分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；既有工程分支为 existing-domain-driven-maven、existing-layered-mvc-maven。成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其旧分层 guide；组件、安全、批准合同、允许路径及执行证据规则仍共用。
+- 只读审计先读取实际用例、工程登记和可读契约；不要求先补批准 Slice 或生成 Manifest，业务 Spec 缺失须记录。
+- 整改消费批准且当前的 Slice、已确认行为 seam 与登记的 Application/service/core 映射，保持允许写范围。
+- 新工程按生成式 Profile 消费脚手架来源，骨架生成不替代业务实现合同。
+
+## 架构分流
+
+将 `architecture_identity` 与当前工程基线和仓库登记核对；仅生成式来源核对脚手架 Manifest，既有来源使用登记及独立工程观测。再且只读取 `references/profiles/<architecture_profile>.md`。生成式分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；既有分支为 existing-domain-driven-maven、existing-layered-mvc-maven。成熟度以注册表为准，不能把 draft 称为受支持。
 
 以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
 
-Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事务边界和跨聚合流程，不承载核心领域规则。
+DDD 用例层协调 Domain 与 Gateway，定义事务边界和跨聚合流程，不承载核心领域规则。MVC 不执行 DDD 专属规则，也不加载其分层 guide；组件、安全、批准合同、允许路径及执行证据规则共用。
 
 ## 何时使用
 
@@ -71,4 +77,4 @@ Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事
 
 ## 既有工程与条件适用
 
-只读审计不要求先补批准 Slice；业务 Spec 缺失须记录。整改消费批准 Slice、已确认行为 seam 与登记的 Application/service/core 映射，不要求生成 Manifest。事务、幂等、提交后副作用按实际用例评估；未命中不创建空事务、空端口或空恢复实现。DDD 的领域规则归 Domain，MVC 规则允许留在已登记 service/core。
+事务、幂等、提交后副作用按实际用例评估；未命中不创建空事务、空端口或空恢复实现。DDD 的领域规则归 Domain，MVC 规则允许留在已登记 service/core。

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

@@ -7,6 +7,10 @@ description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订
 
 用于处理 `yss-component-audit-log` 的接入、排障和代码修改。
 
+## 平台与源码门禁
+
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-audit-log` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
+
 ## 何时使用
 
 - 用户要求接入或修改审计日志。
@@ -31,13 +35,15 @@ description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订
 
 ## 接入检查清单
 
+下述 Boot 3 要点是所登记平台基线的核验项；只有匹配源码门禁通过，才能作为当前精确结论。索引或源码漂移时将受影响结论标为待核验并停止精确接入指导，不借历史快照补齐。
+
 - 启动类是否启用了类似 `@EnableAuditLog` 的能力。
 - 目标方法是否是可被 AOP 代理拦截的 Spring Bean 方法。
 - `@AuditLog` 是否标在正确的方法上。
 - `boot3-java17` 的 SpEL 根上下文只暴露 ASCII key：`args` 和 `result`；例如 `#{args[0]}`、`#{result[name]}`。方法参数名不会自动进入上下文。
 - `args` 仅在 `@AuditLog(isNeedArgs = true)` 时写入，`result` 仅在 `isNeedResult = true` 时写入；表达式引用未启用的 key 属于配置错误，必须由组件 seam 测试覆盖。
 - `boot3-java17` 不再使用中文 context key，也不得把 Boot 2 的历史模板直接复制到 Boot 3。处理旧模板时先读取所选平台线索引并显式迁移。
-- `yss.audit.enabled` 是否开启；`sendSysManageEnabled` 与 `auditLogPrintEnabled` 在当前实现中不会自动阻止订阅器注册，需按源码验证，不能假设开关生效。
+- 按匹配源码核验 `yss.audit.enabled`、`sendSysManageEnabled` 与 `auditLogPrintEnabled` 是否控制订阅器注册及投递，不能从字段名或历史快照推断开关生效。
 - 审计身份由 `CurrentUserProvider` 提供；不得在审计切面中重新解析 Header 或未验签 JWT。
 
 ## 排障顺序
@@ -51,7 +57,7 @@ description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订
 7. 异步线程池或事件发布异常是否被吞掉。
 8. 参数位置、返回值字段、异常分支是否满足摘要模板。
 
-`boot3-java17` 审计切面当前是 `@AfterReturning`，只记录成功返回；异常审计、参数脱敏、队列满丢弃、线程池关闭、重试和幂等必须单独设计并测试。组件测试至少覆盖 `#{result[name]}`、`args` / `result` 资源写入和可信身份来源。
+核验 `boot3-java17` 审计切面的 advice 与成功/异常边界；所登记平台基线使用 `@AfterReturning` 记录成功返回，源码漂移时该结论待核验。异常审计、参数脱敏、队列满丢弃、线程池关闭、重试和幂等须按当前组件能力及批准设计单独核验和测试，不能由旧基线推断已覆盖。组件测试至少覆盖 `#{result[name]}`、`args` / `result` 资源写入和可信身份来源。
 
 ## 修改约束
 
@@ -68,7 +74,3 @@ description: "接入或排查 YSS AuditLog 的 SpEL 摘要、异步发布、订
 - 审计切面与 SpEL 解析：`assets/AuditLogAspect.java`
 - 异步发布链路：`assets/YssAuditPublishService.java`
 - 默认订阅器：`assets/YssAuditLogPrintSubscriberImpl.java`、`assets/YssAuditLogSysManagerSubscriberImpl.java`
-
-## 平台与源码门禁
-
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-audit-log --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。

package/template/.codex/skills/yss-audit-log/references/README.md

@@ -1,6 +1,6 @@
-# 参考资料
+# Boot 2 历史审计资料
 
-本文档详细介绍了 `yss-component-audit-log` 组件的核心类和配置类。
+本文件说明 `assets/` 中的 `boot2-java8` 历史快照，仅用于旧工程比对与迁移诊断，不作为当前 Boot 3 实现模板或 freshness 证据。当前平台任务从 [平台索引](source-index.md) 定位匹配源码并执行共享门禁；[入口](../SKILL.md) 中的身份、SpEL 和异步边界同样须与所选平台当前源码核对。
 
 ## 核心类 (Core Classes)
 
@@ -17,7 +17,7 @@
   1. **解析注解**: 获取 `@AuditLog` 中的操作类型、描述、资源类型等信息。
   2. **SpEL 解析**: 如果 `summary` 中包含 `#{...}` 表达式，会解析方法参数和返回值，动态生成日志内容。
   3. **构建消息**:
-     - 收集用户信息（从 JWT 解析）。
+     - 历史快照使用 `AuthUserInfoUtil.currentUserJson()`；特定 `Principal` 返回分支还解析 `id_token`。这段历史行为不构成可信认证依据，不能迁入 Boot 3 的 `CurrentUserProvider` 链路。
      - 收集请求信息（URL, IP, User-Agent）。
      - 收集参数和结果（根据 `isNeedArgs` 和 `isNeedResult` 配置）。
   4. **发布消息**: 调用 `YssAuditPublishService.publish` 将构建好的 `AuditMessage` 发布出去。
@@ -41,14 +41,14 @@
 **位置**: `../assets/YssAuditLogPrintSubscriberImpl.java`
 
 - **功能**: 简单的控制台日志打印，用于开发调试。
-- **开关**: 通过 `yss.audit.auditLogPrintEnabled` 控制。
+- **配置核验**: 历史订阅器快照自身不检查 `auditLogPrintEnabled`。开关是否控制注册或投递须检查实际工程的配置装配，不能从字段名推断生效。
 
 #### YssAuditLogSysManagerSubscriberImpl.java
 
 **位置**: `../assets/YssAuditLogSysManagerSubscriberImpl.java`
 
 - **功能**: 调用 `YssDmSystemManageFeign` 将审计日志发送到系统管理服务进行持久化存储。
-- **开关**: 通过 `yss.audit.sendSysManageEnabled` 控制。
+- **配置核验**: 历史订阅器快照自身不检查 `sendSysManageEnabled`。按实际工程核验配置装配及投递；当前平台行为不由这份快照证明。
 
 ## 关键注解