create-yss-spec 3.4.8 → 3.4.10

package/README.md

@@ -2,7 +2,7 @@
 
 用于初始化、接管已有项目并持续同步 `yss-spec-project-template` 研发管理资产的 npm CLI。
 
-源码候选版本：`3.4.6`。当前固定模板身份、来源状态和摘要见 `template.snapshot.json`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准，并用 `create-yss-spec --version` 核对当前执行版本。
+源码候选版本：`3.4.9`。当前固定模板身份、来源状态和摘要见 `template.snapshot.json`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准，并用 `create-yss-spec --version` 核对当前执行版本。
 
 ## 本版模板能力
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "3.4.8",
+  "version": "3.4.10",
   "description": "Initialize a YSS spec project template repository",
   "main": "src/api/index.js",
   "repository": {

package/src/template/attach-planner.js

@@ -41,6 +41,11 @@ function classifyAttachOperations({
       continue;
     }
 
+    if (operation.relativePath === "docs/agents/issue-tracker.md") {
+      matched.push({ ...operation, reason: "project-owned-tracker-configuration" });
+      continue;
+    }
+
     const currentHash = getFileHash(operation);
     if (currentHash === operation.desiredHash) {
       matched.push(operation);

package/src/template/sync-planner.js

@@ -47,6 +47,11 @@ function classifySyncOperations({
       continue;
     }
 
+    if (operation.relativePath === "docs/agents/issue-tracker.md") {
+      unchanged.push({ ...operation, reason: "project-owned-tracker-configuration" });
+      continue;
+    }
+
     const currentHash = getFileHash(operation);
 
     if (operation.safeSectionMerge && currentHash !== operation.desiredHash) {

package/template/.agents/skills/.strategic-design-skills-manifest.json

@@ -3,28 +3,28 @@
   "source": "iloveZzz/yss-harness-design-agent",
   "source_type": "git-submodule",
   "source_root": ".agents/skills",
-  "source_revision": "77a94e9fc8087f6c46f8dcfe30e362ee84b1f86a",
+  "source_revision": "9e17922a0a718e5bd1845ddab11850a2f43becad",
   "adaptation_ref": "docs/agents/strategic-design-skills-integration.md",
   "skills": [
     {
       "upstream": "prototype-review",
       "canonical": "prototype-review",
-      "upstream_hash": "9206df8b6c555c1af1351e425c5ec99ec2a40263c6861607f1418b9c520873ab"
+      "upstream_hash": "6df02dd4de236a749a80efd5eba46d18be7979849af2a9af28636906ccfcb2a0"
     },
     {
       "upstream": "yss-prototype-stage",
       "canonical": "yss-prototype-stage",
-      "upstream_hash": "8256a1edfeb203f4de27d190210b0ba5593f8f74e0f3655b62b146daff2105a8"
+      "upstream_hash": "6e1bcdf107d95c11faee2b988e4e0c36b8e5b76f6b40312a206b83733a96b0fc"
     },
     {
       "upstream": "yss-design-system",
       "canonical": "yss-design-system",
-      "upstream_hash": "c917ecf40a67c52f0fa7894fbdfbf827cc1ed6aff1037be2911377387fede1a0"
+      "upstream_hash": "e156229435c35827c48d3699b021e5e171ec565c2bf91cc91cbb033bf7802d7c"
     },
     {
       "upstream": "yss-stage-decision",
       "canonical": "yss-stage-decision",
-      "upstream_hash": "46a9be287963eff0e71f8106b5d31311e43aabbd1117d7bc3d2d8666a0a99474"
+      "upstream_hash": "f7f765e20f4dca6aca667be03e2b9a7f2a8acc3510eefba88306961882d86ed4"
     }
   ],
   "source_state": "committed",

package/template/.agents/skills/alibaba-java-code-style/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: alibaba-java-code-style
-description: Apply Alibaba Java Development Manual conventions when implementing, refactoring, or reviewing Java/JVM code, Spring-style services, MyBatis/ORM mappings, SQL, Maven dependencies, unit tests, exception/logging behavior, security checks, and design documentation. Use when the user asks for Java code规范, 阿里规范, P3C-style review, Java code style, or compliance with Alibaba Java coding guidelines.
+description: 应用阿里巴巴 Java 手册审查或实现 Java 代码；按当前项目框架与数据库基线选择适用规范。
 ---
 
 # Alibaba Java Code Style
@@ -16,7 +16,7 @@ This skill distills the provided `阿里巴巴 Java 开发手册` 1.4.0 PDF into
 2. Apply mandatory rules first, then use recommended rules to improve maintainability, performance, and readability.
 3. When reviewing, report mandatory violations as findings. Mention recommended violations when they create real risk or are already in the changed area.
 4. When implementing, prefer the repository's existing framework helpers and code generation skills over inventing new local infrastructure.
-5. If a rule touches a project safety boundary such as auth, payment, encryption, raw SQL, database migration scripts, or public base library API changes, produce a draft or `TODO-HUMAN-REVIEW` rather than silently finalizing risky code.
+5. For auth, payment, encryption, SQL, migrations or public-library changes, check the current contract and actual authorization. Continue an already authorized repair with its required verification; produce a draft or `TODO-HUMAN-REVIEW` only for a real missing decision or approval, and identify that gap.
 
 ## Core Priorities
 

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

@@ -37,7 +37,7 @@ Use this bounded path for ordinary generation. Do not read the optional Viewer R
 
 1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question.
 2. Read one matching schema in `schemas/`, `schemas/common.schema.json`, and one matching JSON example in `examples/`. Read only those files. Fresh authorship means new stable IDs, domain wording, and layout; use the example for field shape, not facts. New workflow sources use `schema_version: 2` and its readable layout contract; keep `schema_version: 1` only when preserving an existing workflow's fixed geometry. When real product identity matters, query `node bin/archify.mjs brands "<name>" --json`; read `references/brand-marks.md` only for an unknown brand with a user-provided URL.
-3. Artifact first: the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; apply at most one diagnosed geometry control per repair.
+3. After required source and schema checks, write an early candidate; do not block necessary fact or permission checks merely to make the next tool action a write. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; apply at most one diagnosed geometry control per repair.
 4. Validate after every candidate edit and immediately before handoff:
 
    ```bash
@@ -93,24 +93,7 @@ Read Mermaid for topology and meaning, then author fresh Archify JSON; do not me
 
 ## Authoring invariants
 
-- One obvious main path; side branches leave the nearest main-path node. Remove low-value edges before adding routing controls.
-- Omit `meta.visual_preset` by default so every diagram opens in `classic`, regardless of whether its resolved color mode is light or dark. Color mode and visual preset are independent: switching Light / Dark must preserve the current preset. Set `signal-flow`, `blueprint`, or `editorial` only when the user explicitly requests that visual style.
-- Omit `meta.subtitle` by default. Never invent a subtitle that restates the title, nodes, or cards; include one short supporting line only when the user explicitly asks for it.
-- Treat the standalone desktop viewer as a first-screen artifact by default, not a shallow strip. Generate one responsive artifact for laptops and external displays—never device-specific HTML or alternate topology. The viewer may adapt only the outer reading width from the live viewport height; it must preserve the authored SVG/viewBox, proportions, semantic geometry, and normal document flow. On a wide or tall desktop, use enough authored vertical rhythm that the diagram panel and its necessary conclusion cards occupy the screen as a balanced whole; runtime scaling cannot repair an over-compressed Y layout or an undersized explicit `meta.viewBox`. Before handoff, open the real HTML at 1440×900, 1600×1000, and 1920×1080; additionally check 2048×1320 whenever the composition is intended for a large desktop display. Require `document.documentElement.scrollWidth <= window.innerWidth` and `scrollHeight <= window.innerHeight` at every checked size, while visually checking that the diagram remains comfortably readable and vertically balanced at the largest checked viewport. Repair overflow by removing only genuinely redundant content or compacting spacing before shrinking nodes, labels, or the main panel. If the largest viewport still has a conspicuous empty lower band at the viewer's width cap, redistribute authored Y positions and increase the viewBox height proportionally; do not add filler copy or decorative cards. Never counterfeit a pass with `overflow: hidden`, clipped content, an internal diagram scroller, stretched SVG height, or smaller typography. Narrow/mobile layouts may scroll vertically when containment requires it.
-- Omit `meta.legend` for the truthful `auto` default. When needed, use only `mode: auto|all|hidden` and renderer-supported `entries.<kind>.label|visible`; labels never change semantics.
-- Choose one primary authored language from an explicit user choice; otherwise follow the request or conversation's dominant language. `meta.locale` controls only renderer-owned Viewer UI: use `"en"` or `"zh-CN"` for the corresponding supported primary language. For every other language, omit `meta.locale` and explicitly disclose that the fixed Viewer UI and `<html lang>` fall back to English. The renderer never translates authored content. See `references/authoring-contract.md` for details.
-- Preserve exact product names, code identifiers, commands, protocols, API paths, and environment names. They may remain English inside localized copy, but never justify leaving the surrounding explanatory prose in another language.
-- Brand identity is optional and explicit. Put a canonical built-in ID in `brand` when the node names that real product. If no preset matches and the user supplied the official HTTP(S) URL, first run `node bin/archify.mjs brands capture "<url>" --json`, then author the returned digest-pinned `brand` object. Render and validate never perform an unpinned capture. Otherwise omit `brand`. Never infer a brand from a vague role such as "database", and never let a badge replace the semantic `type`, label, or relationship facts.
-- For sequence diagrams, omit `meta.column_fit` for the stable `fixed` layout. Set it to `"spread"` when a wide viewBox would otherwise leave unused horizontal space or when meaningful participant labels do not fit the fixed boxes; do not shorten semantic labels before trying `spread`.
-- Component types are `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`; variants are `default`, `emphasis`, `security`, and `dashed`.
-- Relationship labels are semantic data. When one collides, move the label, adjust the route or spacing, then shorten the wording while preserving meaning. Omit only wording that is already fully implied by both endpoints and contains no protocol, action, direction, synchronous/asynchronous behavior, or cross-boundary mechanism. Preserve every meaningful label; deleting it is not a geometry repair. If a relationship starts unlabeled because its endpoints fully imply it, explain why the wording is redundant; this is a semantic authoring choice, not a geometry repair.
-- Omit `meta.engineering_profile` by default. Region, cluster, and security boundary wording do not by themselves enable it. Enable `deployment-ownership` only when the user explicitly asks for a production deployment topology, ownership handoff, or fail-closed deployment review and the source facts are known. Once enabled, must not remove the engineering profile merely to pass validation; repair the facts or report the diagnostics truthfully.
-- Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; follow the label-preserving repair order.
-- Automatic routes own their endpoint sides. A side is a direction contract: the first and final segment must leave/enter perpendicular to that side.
-- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle. It skips single relationships and explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes. Near parallel ports use an outside bridge so automatic routing cannot create a sub-8px segment or sub-16px interior turn. Architecture separately keeps unobstructed facing automatic ports (`left`/`right` or `top`/`bottom`) on one shared axis when their offset is under 16px and both ports retain corner clearance. If exactly one endpoint was spread, only the unshared endpoint may move onto that axis; if both endpoints were spread, keep the outside bridge so competing ports remain distinct.
-- Never accept an edge crossing an unrelated opaque node, an ambiguous shared corridor, or a relationship label masking another route.
-
-Read `references/authoring-contract.md` only when you need field enums, spacing math, geometry repair rules, repository evidence, or mode-specific placement.
+Keep typed source and rendered output consistent; stable IDs and source facts must be traceable. Edges may not cross unrelated opaque nodes, share ambiguous corridors or hide labels. When placing nodes, choosing routes or repairing geometry, read [geometry and routing](references/geometry-and-routing.md). Validate the actual output before delivery.
 
 ## Delivery
 

package/template/.agents/skills/archify/references/geometry-and-routing.md

@@ -0,0 +1,20 @@
+## Authoring invariants
+
+- One obvious main path; side branches leave the nearest main-path node. Remove low-value edges before adding routing controls.
+- Omit `meta.visual_preset` by default so every diagram opens in `classic`, regardless of whether its resolved color mode is light or dark. Color mode and visual preset are independent: switching Light / Dark must preserve the current preset. Set `signal-flow`, `blueprint`, or `editorial` only when the user explicitly requests that visual style.
+- Omit `meta.subtitle` by default. Never invent a subtitle that restates the title, nodes, or cards; include one short supporting line only when the user explicitly asks for it.
+- Treat the standalone desktop viewer as a first-screen artifact by default, not a shallow strip. Generate one responsive artifact for laptops and external displays—never device-specific HTML or alternate topology. The viewer may adapt only the outer reading width from the live viewport height; it must preserve the authored SVG/viewBox, proportions, semantic geometry, and normal document flow. On a wide or tall desktop, use enough authored vertical rhythm that the diagram panel and its necessary conclusion cards occupy the screen as a balanced whole; runtime scaling cannot repair an over-compressed Y layout or an undersized explicit `meta.viewBox`. Before handoff, open the real HTML at 1440×900, 1600×1000, and 1920×1080; additionally check 2048×1320 whenever the composition is intended for a large desktop display. Require `document.documentElement.scrollWidth <= window.innerWidth` and `scrollHeight <= window.innerHeight` at every checked size, while visually checking that the diagram remains comfortably readable and vertically balanced at the largest checked viewport. Repair overflow by removing only genuinely redundant content or compacting spacing before shrinking nodes, labels, or the main panel. If the largest viewport still has a conspicuous empty lower band at the viewer's width cap, redistribute authored Y positions and increase the viewBox height proportionally; do not add filler copy or decorative cards. Never counterfeit a pass with `overflow: hidden`, clipped content, an internal diagram scroller, stretched SVG height, or smaller typography. Narrow/mobile layouts may scroll vertically when containment requires it.
+- Omit `meta.legend` for the truthful `auto` default. When needed, use only `mode: auto|all|hidden` and renderer-supported `entries.<kind>.label|visible`; labels never change semantics.
+- Choose one primary authored language from an explicit user choice; otherwise follow the request or conversation's dominant language. `meta.locale` controls only renderer-owned Viewer UI: use `"en"` or `"zh-CN"` for the corresponding supported primary language. For every other language, omit `meta.locale` and explicitly disclose that the fixed Viewer UI and `<html lang>` fall back to English. The renderer never translates authored content. See `references/authoring-contract.md` for details.
+- Preserve exact product names, code identifiers, commands, protocols, API paths, and environment names. They may remain English inside localized copy, but never justify leaving the surrounding explanatory prose in another language.
+- Brand identity is optional and explicit. Put a canonical built-in ID in `brand` when the node names that real product. If no preset matches and the user supplied the official HTTP(S) URL, first run `node bin/archify.mjs brands capture "<url>" --json`, then author the returned digest-pinned `brand` object. Render and validate never perform an unpinned capture. Otherwise omit `brand`. Never infer a brand from a vague role such as "database", and never let a badge replace the semantic `type`, label, or relationship facts.
+- For sequence diagrams, omit `meta.column_fit` for the stable `fixed` layout. Set it to `"spread"` when a wide viewBox would otherwise leave unused horizontal space or when meaningful participant labels do not fit the fixed boxes; do not shorten semantic labels before trying `spread`.
+- Component types are `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`; variants are `default`, `emphasis`, `security`, and `dashed`.
+- Relationship labels are semantic data. When one collides, move the label, adjust the route or spacing, then shorten the wording while preserving meaning. Omit only wording that is already fully implied by both endpoints and contains no protocol, action, direction, synchronous/asynchronous behavior, or cross-boundary mechanism. Preserve every meaningful label; deleting it is not a geometry repair. If a relationship starts unlabeled because its endpoints fully imply it, explain why the wording is redundant; this is a semantic authoring choice, not a geometry repair.
+- Omit `meta.engineering_profile` by default. Region, cluster, and security boundary wording do not by themselves enable it. Enable `deployment-ownership` only when the user explicitly asks for a production deployment topology, ownership handoff, or fail-closed deployment review and the source facts are known. Once enabled, must not remove the engineering profile merely to pass validation; repair the facts or report the diagnostics truthfully.
+- Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; follow the label-preserving repair order.
+- Automatic routes own their endpoint sides. A side is a direction contract: the first and final segment must leave/enter perpendicular to that side.
+- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle. It skips single relationships and explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes. Near parallel ports use an outside bridge so automatic routing cannot create a sub-8px segment or sub-16px interior turn. Architecture separately keeps unobstructed facing automatic ports (`left`/`right` or `top`/`bottom`) on one shared axis when their offset is under 16px and both ports retain corner clearance. If exactly one endpoint was spread, only the unshared endpoint may move onto that axis; if both endpoints were spread, keep the outside bridge so competing ports remain distinct.
+- Never accept an edge crossing an unrelated opaque node, an ambiguous shared corridor, or a relationship label masking another route.
+
+Read `references/authoring-contract.md` only when you need field enums, spacing math, geometry repair rules, repository evidence, or mode-specific placement.

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

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: Use when the user wants to review a branch, PR, committed candidate, uncommitted work-in-progress changes, or changes since a fixed point. For YSS implementation, Standards must load Slice contract required_skills plus specialist check inputs such as alibaba-java-code-style and yss-ui; do not add a second generic review skill.
+description: 审查分支、PR、固定候选或工作树改动，按仓库规范、Spec 及适用 UI 还原要求报告有证据的缺陷。
 ---
 
 Review of a pinned candidate against a fixed point on two core axes, plus UI fidelity when UI is in scope:
@@ -21,39 +21,9 @@ If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-
 
 ## Process
 
-### 1. Pin the fixed point and candidate
+### 1. 固定候选
 
-Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
-
-Choose one candidate mode from the request or an upstream review contract:
-
-- **Committed candidate** — review committed branch/PR state. Capture `git diff <fixed-point>...HEAD` and `git log <fixed-point>..HEAD --oneline`.
-- **Worktree candidate** — review work in progress without requiring a commit. Resolve `<merge-base>` with `git merge-base <fixed-point> HEAD`, then capture:
-  - `git diff --no-ext-diff --binary --full-index <merge-base>` for committed, staged and unstaged tracked content as it exists in the working tree;
-  - `git ls-files -z --others --exclude-standard` for NUL-delimited raw untracked paths;
-  - each untracked file's content, using `git diff --no-index --no-ext-diff --binary --full-index -- /dev/null <path>` when a diff representation is useful. Exit code `1` from this command means a difference was found, not that review failed;
-  - `git log <fixed-point>..HEAD --oneline` for the committed portion of the candidate.
-
-Record one **candidate manifest** before review:
-
-```yaml
-review_mode: committed # or worktree
-review_base_ref: <fixed-point>
-merge_base: <resolved-sha>
-implementation_candidate_ref: HEAD # or working-tree
-candidate_snapshot_ref: <immutable-commit-or-captured-snapshot>
-candidate_digest: <sha256-or-immutable-tree-id>
-tracked_diff_command: <command>
-untracked_inventory_command: <command-or-null>
-untracked_files: []
-commit_list_command: <command>
-```
-
-For a Committed candidate, resolve `HEAD` to an immutable commit and tree before review. Its manifest must include `merge_base`, `tracked_diff_command` and `commit_list_command`. For a Worktree candidate, the manifest must additionally include `untracked_inventory_command`, `untracked_diff_command` and the exact `untracked_files` inventory.
-
-For a Worktree candidate, capture the tracked binary diff and every untracked file's bytes once into an immutable snapshot, compute `candidate_digest`, and make that **captured candidate** available to the assigned reviewer(s). The following is normative, not illustrative: use the `yss-worktree-candidate-v1` byte stream. Start with ASCII `YSS-WORKTREE-CANDIDATE-V1` followed by one NUL byte. Append one tracked record: byte `0x54`, unsigned 64-bit big-endian binary-diff byte length, then the exact stdout bytes from `git diff --no-ext-diff --binary --full-index <merge-base>`. Then append one untracked record for each NUL-delimited raw path from `git ls-files -z --others --exclude-standard`, sorted bytewise by the raw path: byte `0x55`, unsigned 64-bit big-endian path length, raw path bytes, unsigned 32-bit big-endian `lstat` mode, entry-kind byte (`0x52` regular or `0x4c` symlink), unsigned 64-bit big-endian content length, then raw regular-file bytes or raw symlink-target bytes. Other entry kinds block capture. This is the sole length-prefixed framing and bytewise path order for the digest. SHA-256 is calculated over exactly this stream. New captures use a previously nonexistent directory under `.template-source/evidence/maintenance/`, land atomically, and store exactly `candidate-manifest.yaml`, `candidate.bin` and `tracked.diff`; `candidate.bin` already contains every untracked byte, so do not duplicate hundreds of `untracked-content/000xxx` files. Explicit exclusions are fail-closed to `.template-source/evidence/maintenance/` evidence and cannot exclude implementation or authority assets. Historical per-file snapshots remain readable. Every assigned reviewer must consume the captured stream and must not independently treat a live worktree as the reviewed candidate.
-
-Before going further, confirm the fixed point and merge-base resolve. A committed candidate must have a non-empty committed diff. A Worktree candidate is non-empty when either its tracked diff or untracked inventory is non-empty. A bad ref, missing candidate part or empty candidate should fail here — not during professional review. Do not silently downgrade Worktree review to `HEAD`-only review.
+开始审查前按 [候选捕获合同](references/candidate-capture.md) 选择 committed/worktree 模式，固定比较基点、内容摘要和未跟踪文件。保持只读；候选变化使相关审查失效。
 
 ### 2. Identify the spec source
 

package/template/.agents/skills/code-review/references/candidate-capture.md

@@ -0,0 +1,33 @@
+### 1. Pin the fixed point and candidate
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
+
+Choose one candidate mode from the request or an upstream review contract:
+
+- **Committed candidate** — review committed branch/PR state. Capture `git diff <fixed-point>...HEAD` and `git log <fixed-point>..HEAD --oneline`.
+- **Worktree candidate** — review work in progress without requiring a commit. Resolve `<merge-base>` with `git merge-base <fixed-point> HEAD`, then capture:
+  - `git diff --no-ext-diff --binary --full-index <merge-base>` for committed, staged and unstaged tracked content as it exists in the working tree;
+  - `git ls-files -z --others --exclude-standard` for NUL-delimited raw untracked paths;
+  - each untracked file's content, using `git diff --no-index --no-ext-diff --binary --full-index -- /dev/null <path>` when a diff representation is useful. Exit code `1` from this command means a difference was found, not that review failed;
+  - `git log <fixed-point>..HEAD --oneline` for the committed portion of the candidate.
+
+Record one **candidate manifest** before review:
+
+```yaml
+review_mode: committed # or worktree
+review_base_ref: <fixed-point>
+merge_base: <resolved-sha>
+implementation_candidate_ref: HEAD # or working-tree
+candidate_snapshot_ref: <immutable-commit-or-captured-snapshot>
+candidate_digest: <sha256-or-immutable-tree-id>
+tracked_diff_command: <command>
+untracked_inventory_command: <command-or-null>
+untracked_files: []
+commit_list_command: <command>
+```
+
+For a Committed candidate, resolve `HEAD` to an immutable commit and tree before review. Its manifest must include `merge_base`, `tracked_diff_command` and `commit_list_command`. For a Worktree candidate, the manifest must additionally include `untracked_inventory_command`, `untracked_diff_command` and the exact `untracked_files` inventory.
+
+For a Worktree candidate, capture the tracked binary diff and every untracked file's bytes once into an immutable snapshot, compute `candidate_digest`, and make that **captured candidate** available to the assigned reviewer(s). The following is normative, not illustrative: use the `yss-worktree-candidate-v1` byte stream. Start with ASCII `YSS-WORKTREE-CANDIDATE-V1` followed by one NUL byte. Append one tracked record: byte `0x54`, unsigned 64-bit big-endian binary-diff byte length, then the exact stdout bytes from `git diff --no-ext-diff --binary --full-index <merge-base>`. Then append one untracked record for each NUL-delimited raw path from `git ls-files -z --others --exclude-standard`, sorted bytewise by the raw path: byte `0x55`, unsigned 64-bit big-endian path length, raw path bytes, unsigned 32-bit big-endian `lstat` mode, entry-kind byte (`0x52` regular or `0x4c` symlink), unsigned 64-bit big-endian content length, then raw regular-file bytes or raw symlink-target bytes. Other entry kinds block capture. This is the sole length-prefixed framing and bytewise path order for the digest. SHA-256 is calculated over exactly this stream. New captures use a previously nonexistent directory under `.template-source/evidence/maintenance/`, land atomically, and store exactly `candidate-manifest.yaml`, `candidate.bin` and `tracked.diff`; `candidate.bin` already contains every untracked byte, so do not duplicate hundreds of `untracked-content/000xxx` files. Explicit exclusions are fail-closed to `.template-source/evidence/maintenance/` evidence and cannot exclude implementation or authority assets. Historical per-file snapshots remain readable. Every assigned reviewer must consume the captured stream and must not independently treat a live worktree as the reviewed candidate.
+
+Before going further, confirm the fixed point and merge-base resolve. A committed candidate must have a non-empty committed diff. A Worktree candidate is non-empty when either its tracked diff or untracked inventory is non-empty. A bad ref, missing candidate part or empty candidate should fail here — not during professional review. Do not silently downgrade Worktree review to `HEAD`-only review.

package/template/.agents/skills/code-review/references/yss-review-standards.md

@@ -71,11 +71,9 @@ YSS 页面模块约定（YTable、YFormily、页面骨架等）走 Standards，
 `contract_digest`、候选摘要、`reviewer` / `implementer` 的 actor_id / runtime_id / instance_id，
 并分别记录 `axes.Standards` 和 `axes.Spec`。自审不能用不同角色名替代不同执行实例。
 
-复用 `constraint_results`，每个适用技能至少一项包含 `axis: Standards`、`skill`、`constraint`、
-`status`、`rule_ref`、规则文件 SHA-256 `rule_digest`、`code_ref`、`evidence_ref`、证据 SHA-256
-`evidence_digest`。按原文定位具体规则，禁止仅写“符合规范”。无持久化影响时 Repository/MyBatis
-可写有原因的 not-applicable；合同必需技能不得豁免。`findings` 的阻断项必须关闭；建议可绑定
-`follow_up_ref` 进入待办。修复后重新捕获候选，重验受影响规则及依赖，并显式重绑复用证据。
+复用 `constraint_results`，按派生覆盖清单逐条包含 `constraint_id`、`applicability_basis`、`axis: Standards`、`skill`、`constraint`、`status`、`rule_ref/rule_digest`、`code_ref`、`evidence_ref/evidence_digest`。每个适用技能还须完成 full-text 项并保留具体 `review_notes`。漏技能、漏规则、重复项、过期证据均不能完成。无分页等需求只豁免对应条件规则，不豁免整个适用技能。
+
+后端输入必须增加 `scope_kind: change`、`standards_coverage_ref/digest`；`committed` 候选还绑定 `review_base_ref`。只读存量基线使用 `scope_kind: baseline`，允许无 Slice/无 diff，成功仅为 audited，不能关闭实现审查。详细输入、未知类型与全文核对规则见 `yss-backend-spec-review/references/standards-coverage.md`。未提供结构化覆盖的历史报告只能阅读，不作为新完成证据。
 
 工作树候选复用现有 packed candidate 工具；审查证据可排除，业务文件不可排除。已提交候选绑定
 不可变 tree ID，并核对当前清洁 checkout。读取结构化结果不会代替 Reviewer 的实际规则判断。

package/template/.agents/skills/codebase-design/SKILL.md

@@ -9,7 +9,7 @@ Design **deep modules**: a lot of behaviour behind a small interface, placed at
 
 ## Glossary
 
-Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+Use these terms to distinguish concepts in deep-module analysis. Preserve the project's authoritative CONTEXT vocabulary and existing component/service/API/boundary names; this analytical vocabulary does not rename domain concepts.
 
 **Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
 
@@ -62,7 +62,7 @@ When designing an interface, ask:
 - **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
 - **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
 - **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
-- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+- **Use variation as evidence for a seam.** Two real adapters are strong evidence, not a mandatory count. A single adapter can still protect an external dependency, a test seam or an explicit change boundary; avoid speculative abstraction without such a reason.
 
 ## Designing for testability
 

package/template/.agents/skills/competitive-intelligence/SKILL.md

@@ -47,7 +47,7 @@ Use this skill when competitive or market facts are needed to shape product Plan
 5. Hand off to lifecycle assets:
    - Update Plan findings in `docs/.scratch/<feature>/plan/`.
    - Create or update a competitor matrix in `docs/.scratch/<feature>/plan/reports/`.
-   - Feed stable user, pain, MVP, non-goal, and success criteria into `grill-with-docs` and `to-spec`.
+   - Return stable user, pain, MVP, non-goal and success criteria to the current lifecycle/strategic owner for its native Plan and Spec work units. Compatibility entries remain explicit-user-only.
    - Record uncertain claims as assumptions, not requirements.
 
 ## Output Shape

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

@@ -15,6 +15,10 @@ This skill has you show commands, outputs and captured artifacts. **Redact every
 
 If the redacted output is not enough to diagnose the bug, say so and ask the user.
 
+## Simple fixes and complex investigations
+
+When a bounded defect has confirmed inputs and a known public seam, run a direct reproducer, make the authorized minimal fix and run the regression check. Do not restart an interview, minimize an already minimal case, or invent extra hypotheses. Use the phases below when the cause, environment or reproduction is uncertain.
+
 ## Phase 1 — Build a feedback loop
 
 **This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
@@ -83,11 +87,11 @@ Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer movin
 
 Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
 
-Do not proceed until you have reproduced **and** minimised.
+Minimize further only while it removes meaningful uncertainty. Preserve representative conditions; do not spend effort proving every remaining element essential when the cause can already be tested directly.
 
 ## Phase 3 — Hypothesise
 
-Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+Generate enough competing falsifiable hypotheses to distinguish plausible causes. For a clear, bounded defect one directly testable hypothesis can be sufficient; complex or ambiguous failures need alternatives, without a fixed count.
 
 Each hypothesis must be **falsifiable**: state the prediction it makes.
 

package/template/.agents/skills/formily-foundation/SKILL.md

@@ -79,7 +79,7 @@ const schema: ISchema = {
           'x-component': 'FormGrid',
           'x-component-props': { maxColumns: 3, minColumns: 1, minWidth: 260 },
           properties: {
-            name: { type: 'string', title: '名称', 'x-decorator': 'FormItem', 'x-component': 'Input', required: true },
+            name: { type: 'string', title: '名称', 'x-decorator': 'FormItem', 'x-component': 'Input', required: true, 'x-validator': [{ required: true, whitespace: true, message: '请输入名称' }] },
             submit: {
               type: 'void',
               'x-component': 'Submit',

package/template/.agents/skills/formily-step-flow/SKILL.md

@@ -100,6 +100,7 @@ const step1Schema = createStepSchema({
     type: 'string',
     title: '任务名称',
     required: true,
+    'x-validator': [{ required: true, whitespace: true, message: '请输入任务名称' }],
     'x-decorator': 'FormItem',
     'x-component': 'Input',
   },
@@ -173,7 +174,7 @@ const submitAll = async () => {
 </template>
 ```
 
-复杂页面把 schema、类型与步骤 hook 分别拆到 `constant.ts`、`hooks/useStepFlow.ts`，保持 `index.vue` 在 150 行以内。
+当 schema、步骤状态和页面编排难以独立理解或验证时，分别拆到 `constant.ts`、`hooks/useStepFlow.ts`；以职责清晰和状态可测试为准，不按固定行数拆分。
 
 ## 交付检查清单
 
@@ -191,4 +192,4 @@ const submitAll = async () => {
 - 状态串联错误时先收敛为单一 `reactive` 数据源，再检查每步 `v-model` 路径。
 - 确认页为空时检查是否错误绑定了独立 `step3`，应改为前序数据的 `computed` 聚合。
 - API 调用 reject 时只在 `finally` 恢复 loading，不重复弹出错误提示。
-- 步骤过多或主组件超过 150 行时，按阶段拆子组件和 `useStepXxx` hook。
+- 步骤职责交叉或状态难以验证时，按业务阶段拆子组件和 `useStepXxx` hook。

package/template/.agents/skills/frontend-commit/SKILL.md

@@ -15,7 +15,7 @@ description: "为前端改动生成提交信息、审查原子提交或修复 Gi
 ## 不适用场景
 
 - yss-ui 组件库仓库自身的提交与发版：回到 yss-ui 源仓库使用其 `categories.library` 提交流程；该类 skill 不随业务模板分发。
-- Java、Spring Boot、Maven、Gradle 后端仓库：使用 `../java-backend-commit/SKILL.md`。
+- Java、Spring Boot、Maven、Gradle 后端仓库：回交目标后端 profile 的 `java-backend-commit`；本 profile 不臆造跨目录链接。
 - 仅请求代码实现，不涉及提交信息或 `git commit` 操作。
 - 无代码改动，或改动内容与提交请求不匹配。
 - 合并提交、发布提交和自动依赖机器人提交：遵循仓库专用流程，不套用本技能的常规消息模板。
@@ -65,15 +65,15 @@ git ls-files --others --exclude-standard
 
 - type 默认从 `feat/fix/docs/style/refactor/perf/test/chore/revert/build/ci` 中选择，但仓库枚举优先。
 - scope 优先级为：仓库枚举 → monorepo 包或应用 → 业务模块 → 共享能力。使用小写 kebab-case；不要机械地以 `views`、`hooks` 或文件名作为 scope。
-- 标题使用英文 type/scope、ASCII `:` 和中文摘要；描述行为或价值，不写“修改文件”“更新代码”或单个文件名。
-- 默认将完整 header 控制在 72 个字符内；仓库存在更严格限制时服从仓库。标题末尾不加句号，不用 emoji 或全角冒号。
+- 标题使用仓库确定的 type/scope、分隔符和语言；无既定规则时默认英文 type/scope、ASCII `:` 和中文摘要；描述行为或价值，不写“修改文件”“更新代码”或单个文件名。
+- 默认将完整 header 控制在 72 个字符内；仓库配置了其他限制时服从该配置。标题末尾不加句号，不用 emoji 或全角冒号。
 - 简单单文件变更可以没有 body；多文件、非显然修复、重要功能或行为变化使用 body 解释做了什么、为什么以及如何验证。
 - 仅对真实不兼容变更使用 `!` 和 `BREAKING CHANGE:`；仅在已知编号或仓库要求时加入工单、DCO、`Signed-off-by` 等 footer，禁止编造。
 
 ### 4. 验证并提交
 
 1. 根据变更范围运行仓库已有的最小充分检查，例如相关单元测试、类型检查、lint 和构建检查；优先使用仓库脚本与当前包管理器。
-2. 通过 stdin 校验完整候选消息，而不只校验 header。使用仓库本地 commitlint 命令；退出码为 0 才继续。
+2. 通过 stdin 校验完整候选消息，而不只校验 header。仅在仓库实际采用 commitlint 时使用其本地命令并要求退出码 0；否则按现有 hook/贡献指南验证，不安装新工具。
 3. 仅暂存属于当前原子提交的明确路径或安全 hunks，再重新检查 `git diff --cached --check`、`--name-status` 和完整 staged diff。
 4. 执行正常 `git commit`，允许 hooks 运行。
 5. hook 若格式化或修改文件，重新检查 staged 与 working tree，确认实际提交内容没有漂移。
@@ -102,9 +102,9 @@ feat(data-push): 优化推送任务数据源与调度规则展示
 
 ## 交付检查清单
 
-- [ ] type 与 scope 通过仓库 resolved commitlint 校验，完整消息经 stdin 校验退出码为 0。
+- [ ] 完整消息通过仓库实际采用的提交校验；采用 commitlint 时记录 stdin 校验退出码 0。
 - [ ] scope 来自仓库枚举、包名或业务模块，未使用 `views`、`hooks`、`utils` 或文件名兜底。
-- [ ] 标题为英文 type/scope + ASCII 冒号 + 中文摘要，完整 header 不超过 72 字符。
+- [ ] 标题语言、type/scope 和长度符合仓库配置；无配置时才使用本技能回退格式。
 - [ ] 暂存区只包含当前原子提交的文件；lockfile 与对应 manifest 同提交。
 - [ ] 已运行与变更范围匹配的最小充分检查（相关测试、类型检查、lint）。
 - [ ] 提交后已核对 `git show --stat` 与 `git status --short`，并向用户报告 hash 与剩余改动。

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

@@ -23,6 +23,6 @@ Format a round like so:
 
 Each round the user answers reshapes the tree — settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
 
-Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it — don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report — ask the rest of the frontier now. The _decisions_ are the user's — put each to them and wait.
+Finding _facts_ is your job, never the user's. When a frontier question needs an environment fact, look it up directly; delegate only when an independent bounded investigation can run usefully alongside other work — don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report — ask the rest of the frontier now. The _decisions_ are the user's — put each to them and wait.
 
-The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.
+Stop when decisions material to the agreed scope are settled, remaining uncertainty is explicit and the next action is authorized. Reuse existing confirmations; do not traverse irrelevant branches or re-ask settled questions. New material decisions still require a real user response.

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

@@ -4,7 +4,7 @@ description: "Implement a piece of work based on a spec or set of tickets."
 disable-model-invocation: true
 ---
 
-Implement the work described by the user in the spec or tickets.
+This is an explicit compatibility entry. Before implementation, return to the active lifecycle orchestrator to verify repository identity, registered implementation paths, a current approved Slice Implementation Contract and applicable gates. Reuse existing approved inputs; do not restart planning merely because this entry was invoked. Implement only that contract and return artifacts, actual verification, drift and new impacts for acceptance. Do not approve the contract or upgrade Ticket state yourself. Template-source changes follow the template maintenance route instead of creating product assets.
 
 Use /tdd where possible, at pre-agreed seams.
 

package/template/.agents/skills/implementation-repo-onboarding/SKILL.md

@@ -22,13 +22,13 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 4. 识别技术栈、包管理器、CI、测试命令、构建命令、OpenAPI 接入和设计 token 接入。
 5. 判定实现位置与 `repository_scope`：`external-repository` 记录真实项目根；`harness-apps` 与 `git-submodule` 只能使用 `apps/backend/<project>/` 或 `apps/frontend/<project>/`。`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径必须标记为阻断。gitlink（mode `160000`）必须登记为 `git-submodule` 和 `layout_policy: git-submodule-harness-apps`，不得写成 `harness-apps`。必须对照工作树：`git ls-files --stage`、`.gitmodules` 与声明 scope 不一致时阻断；缺少 `git_entry_mode: 160000` 不得把挂载点当普通目录。
 6. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。`git-submodule` 必填 `gitmodules_name`、`gitlink_path`、`git_entry_mode`、`superproject_git_url` 和 `checkout_state`。`harness-apps` / `external-repository` 这些字段填 `不适用`。
-7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。命中交付预检时，登记和工程基线补齐后重跑 `prepare`；将结构化诊断的责任来源和恢复入口纳入缺口清单，在初始化或构建前关闭当前阶段阻断。后续阶段证据尚未形成不能被当作本阶段失败；其他技术栈/不涉及该交付协议的接入记录不适用原因，不能冒充后端 v2 正例。空 gitlink、detached HEAD、`--force` 覆盖挂载点或缺少递归检出凭据时标记阻断。写入前必须看 `inspectWorkingTreeScope` / `implementationWriteViolation`：只接受对象结果且 `.writable === true` 才可写；字符串、`null` 或 `.writable !== true` 一律不可写。即使已正确登记为 `git-submodule`，空 gitlink 或 detached HEAD 也必须 `.writable === false`，不得当普通目录写文件或脚手架。
+7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。命中交付预检时，登记和工程基线补齐后重跑 `prepare`；将结构化诊断的责任来源和恢复入口纳入缺口清单，在初始化或构建前关闭当前阶段阻断。后续阶段证据尚未形成不能被当作本阶段失败；其他技术栈/不涉及该交付协议的接入记录不适用原因，不能冒充后端 v2 正例。空 gitlink、detached HEAD、`--force` 覆盖挂载点或缺少递归检出凭据时标记阻断。需要转入已授权写入时，先按 [写范围核验](references/write-scope.md) 检查工具对象结果；只有 `.writable === true` 可写，其他形态或状态一律阻断。
 
 ## Baseline Checks
 
 | repo_role | 必查项 |
 |---|---|
-| backend | 构建工具、模块结构、测试命令、OpenAPI 产出、YSS DDD 基线、数据库 / 迁移红线 |
+| backend | 构建工具、模块结构、测试命令、OpenAPI 产出、已登记 DDD 或分层 MVC 对应的 YSS 工程基线、数据库 / 迁移红线 |
 | frontend | 包管理器、框架、路由、YSS UI / Ant Design、Orval / API client、设计 token、lint / type-check / build |
 | fullstack | 前后端边界、契约生成方式、独立测试命令、CI 阶段拆分 |
 | other | owner、构建 / 测试 / 发布命令、与 Harness change 的关系 |
@@ -39,7 +39,7 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 - 不把实现仓库源码复制进 Harness 仓库；`git-submodule` 只能形成 gitlink，不能 copy / subtree 冒充。
 - 不把缺失命令编造为已存在；找不到时标记 `unknown` 或 `需人工确认`。
 - 不得把 `app/backend/`、`app/frontend/` 或 `apps/backend/`、`apps/frontend/` 容器根登记为可生成项目根。
-- 触碰认证、授权、SQL、迁移、加密、公共基础库 API 时标记 `TODO-HUMAN-REVIEW`。
+- 认证、授权、SQL、迁移、加密、公共基础库 API 按实际影响记录审批和证据缺口；仅缺少必要批准时标记 `TODO-HUMAN-REVIEW`，已有授权不因关键词重新审批。
 
 ## Output
 

package/template/.agents/skills/implementation-repo-onboarding/references/write-scope.md

@@ -0,0 +1,5 @@
+# 实现仓库写范围核验
+
+从只读接入进入已授权写入时读取。
+
+写入前必须看 `inspectWorkingTreeScope` / `implementationWriteViolation`：只接受对象结果且 `.writable === true` 才可写；字符串、`null` 或 `.writable !== true` 一律不可写。即使已正确登记为 `git-submodule`，空 gitlink 或 detached HEAD 也必须 `.writable === false`，不得当普通目录写文件或脚手架。

package/template/.agents/skills/improve-codebase-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: improve-codebase-architecture
-description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+description: 显式分析代码结构的维护成本、模块边界与可测试性，提出有证据的重构候选。
 disable-model-invocation: true
 ---
 
@@ -10,7 +10,7 @@ Surface architectural friction and propose **deepening opportunities** — refac
 
 This command is _informed_ by the project's domain model and built on a shared design vocabulary:
 
-- Run the `/codebase-design` skill for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
+- Run the `/codebase-design` skill for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use this analysis vocabulary without overriding CONTEXT or the project's component/service/API terminology.
 - The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
 
 ## Process
@@ -24,7 +24,7 @@ This command is _informed_ by the project's domain model and built on a shared d
 
 Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
 
-Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
+Inspect the bounded area directly; delegate an independent reading task only when useful parallel work exists. Note evidence of friction:
 
 - Where does understanding one concept require bouncing between many small modules?
 - Where are modules **shallow** — interface nearly as complex as the implementation?
@@ -34,11 +34,15 @@ Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics — e
 
 Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
 
-### 2. Present candidates as an HTML report
+### 2. Present candidates in the requested format
+
+Default to concise Markdown with grounded paths, tradeoffs and a small diagram when useful. Use the HTML branch below only when requested or when interaction materially aids comparison. Local/offline delivery uses bundled assets, not mandatory CDN dependencies.
+
+#### Optional HTML report
 
 Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.
 
-The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+When an online HTML report is explicitly selected, Tailwind and Mermaid are optional tools for layout and diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
 
 For each candidate, render a card with:
 
@@ -57,7 +61,7 @@ End the report with a **Top recommendation** section: which candidate you'd tack
 
 See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
 
-Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+Do NOT propose interfaces yet. After presenting candidates, ask which unresolved design direction to explore only if that choice has not already been made.
 
 ### 3. Grilling loop
 

package/template/.agents/skills/java-backend-commit/SKILL.md

@@ -14,8 +14,8 @@ description: "为 Java 后端改动生成提交信息、审查原子提交或修
 
 ## 不适用场景
 
-- Vue、React 等前端或微前端仓库：使用 `../frontend-commit/SKILL.md`。
-- yss-ui 组件库仓库自身的提交与发版：使用 `../commit-linting/SKILL.md`。
+- Vue、React 等前端或微前端仓库：在目标前端 profile 使用已安装的 `frontend-commit`；本 profile 不臆造跨目录链接。
+- yss-ui 组件库仓库自身的提交与发版：遵循目标组件库已安装的提交规范；不存在对应 skill 时读取其贡献指南和 hooks。
 - 仅请求代码实现，不涉及提交信息或 `git commit` 操作。
 - 无代码改动，或改动内容与提交请求不匹配。
 - 合并提交、发布提交、自动依赖机器人提交和数据库基线发布：遵循仓库专用流程，不套用本技能的常规模板。
@@ -66,8 +66,8 @@ git ls-files --others --exclude-standard
 
 - type 默认从 `feat/fix/docs/style/refactor/perf/test/chore/revert/build/ci` 中选择，但仓库枚举优先。
 - scope 优先级为：仓库枚举 → Maven artifactId 或 Gradle 子项目 → 服务或限界上下文 → 跨模块能力。使用小写 kebab-case；不要仅使用 `controller`、`service`、`repository` 或类名。
-- 标题使用英文 type/scope、ASCII `:` 和中文摘要；描述业务、调用方或运维可感知的结果，不写“修改代码”或单个 Java 类名。
-- 默认将完整 header 控制在 72 个字符内；仓库存在更严格限制时服从仓库。标题末尾不加句号，不用 emoji 或全角冒号。
+- 标题使用仓库确定的 type/scope、分隔符和语言；无既定规则时默认英文 type/scope、ASCII `:` 和中文摘要；描述业务、调用方或运维可感知的结果，不写“修改代码”或单个 Java 类名。
+- 默认将完整 header 控制在 72 个字符内；仓库配置了其他限制时服从该配置。标题末尾不加句号，不用 emoji 或全角冒号。
 - 简单单文件变更可以没有 body；跨层实现、数据迁移、并发或事务修复、重要功能和行为变化使用 body 解释做了什么、为什么以及如何验证。
 - REST/GraphQL/RPC 契约、事件格式、公共 Java API、配置语义或数据库兼容性发生真实破坏时，使用 `!` 和 `BREAKING CHANGE:` 并写迁移方式。
 - 仅在已知编号或仓库要求时加入工单、DCO、`Signed-off-by` 等 footer，禁止编造；不要因为 Spring 项目采用 DCO 就推断所有 Java 项目都必须签署。
@@ -106,7 +106,7 @@ fix(settlement): 修复重复回调导致结算流水重复入账的问题
 
 - [ ] type 与 scope 通过仓库校验规则，完整消息经仓库命令校验通过。
 - [ ] scope 来自仓库枚举、构建模块或业务域，未使用 `controller`、`service`、`repository` 或类名兜底。
-- [ ] 标题为英文 type/scope + ASCII 冒号 + 中文摘要，完整 header 不超过 72 字符。
+- [ ] 标题语言、type/scope 和长度符合仓库配置；无配置时才使用本技能回退格式。
 - [ ] 提交可独立理解、构建和回滚；数据库迁移与对应实体、查询和测试同提交。
 - [ ] 暂存区不包含 `target/`、`build/`、日志或本地运行产物。
 - [ ] 已使用仓库 wrapper 运行与变更范围匹配的最小充分检查。

package/template/.agents/skills/llm-wiki/SKILL.md

@@ -48,7 +48,7 @@ node <skill-root>/scripts/extract.mjs skill-names --in <live-lock.json> --out <w
 
 1. Detect: `<wiki-root>/wiki/index.md` + `CLAUDE.md` (or `AGENTS.md`) means a wiki exists. Default wiki-root is repo-root `wiki/`. If `yss-project.yaml` is `repository_mode: template-source`, wiki-root is `.template-source/wiki`.
 2. If the user is asking a repository question, load [query.md](references/query.md) and stop. Do not lint, ingest, or append `log.md`.
-3. Load the mode algorithm: [compile.md](references/compile.md) for init/refresh/rebuild, [ingest.md](references/ingest.md) for ingest. For init/rebuild corpus choice, load [discover.md](discover.md). For writing, load [writing.md](references/writing.md). For checks, load [lint.md](references/lint.md).
+3. Load the mode algorithm: [compile.md](references/compile.md) for init/refresh/rebuild, [ingest.md](references/ingest.md) for ingest. For init/rebuild corpus choice, load [discover.md](references/discover.md). For writing, load [writing.md](references/writing.md). For checks, load [lint.md](references/lint.md).
 4. **Fact order:** called code > table comments / config defaults > stale raw copies. After writing, re-read live sources for a sample of claims (`N = min(5, changed pages)`).
 5. Run structural lint and advise. Append `log.md`. Stop.