universal-dev-standards 6.14.0-beta.2 → 6.14.0-beta.4

package/bundled/skills/comprehension-ladder/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: comprehend
+scope: universal
+description: |
+  [UDS] Turn one hard-to-follow AI output into easier forms: controlled text, a Mermaid diagram, a single-file HTML explainer. All forms come from one shared outline, so the form changes and the facts do not.
+  Use when: an AI explanation, spec or code walk-through is too dense to judge, a non-specialist must approve something from it, you want a diagram or an offline explainer page of it.
+  Not for: writing new content or adding analysis — this skill only re-forms a text that exists; generating docs from source code — use /docgen; shortening a text for an expert reader — edit it directly.
+  Keywords: comprehension ladder, explainer, controlled language, Mermaid, HTML explainer, outline, plain language, understand AI output, 理解階梯, 受控語言, 流程圖, 解說頁, 換形式不換事實.
+allowed-tools: Read, Glob, Grep, Write
+argument-hint: "[text or file | 原文或檔案] [rungs: 1 | 2 | 3]"
+---
+
+# Comprehension Ladder | 理解階梯
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/comprehension-ladder/SKILL.md) | [简体中文](../../locales/zh-CN/skills/comprehension-ladder/SKILL.md)
+
+**Version**: 1.0.0 | **Last Updated**: 2026-10-05 | **Applicability**: Claude Code Skills
+
+Turn one AI output that is hard to follow into forms that are easier to follow. The form changes. The facts do not.
+
+## Purpose
+
+The slow step is no longer getting an answer. The slow step is understanding the answer and judging it. This skill helps with that step. It takes one source text and builds up to three forms of it, called rungs.
+
+This skill is written in controlled language, as described in [ai-response-navigation](../../core/ai-response-navigation.md) Rule 12. It follows its own guards.
+
+## The ladder
+
+There are exactly three rungs. Each rung is built from the same outline (see [The outline](#the-outline)). No rung adds anything to the outline.
+
+| Rung | Form | Best for | Output |
+|------|------|----------|--------|
+| 1 | Controlled text | Any source. Always the first rung. | Short sentences or numbered lines, in the chat or a file |
+| 2 | Mermaid diagram | A source with a flow, a time order, several parties, or 3 or more options | One Mermaid code block, plus a text list of items that cannot be drawn |
+| 3 | Single-file HTML explainer | A reader who must explore or approve | One `.html` file that opens offline |
+
+Ask which rungs the user wants. If the user does not say, build rung 1 and offer the other two.
+
+There is no video rung. Video needs a voice service, and it sends the source to a third party.
+
+## The three guards
+
+These three guards are **Required**. A rung that breaks one is not finished. Do not deliver it.
+
+| ID | Guard | Priority |
+|----|-------|----------|
+| G1 | `no-new-facts`: add no fact the source does not state | **Required** |
+| G2 | `keep-hedges`: keep every hedge. Do not turn an uncertain claim into a certain one | **Required** |
+| G3 | `trace-and-gaps`: give every item a source pointer and a "not covered" note | **Required** |
+
+G2 is the same rule as clause 12.1 in [ai-response-navigation](../../core/ai-response-navigation.md). The wording here is applied to this skill's three rungs.
+
+### G1 `no-new-facts` (Required)
+
+Every claim in every rung must come from the source. Do not add a cause, a number, a name, a date or a "confirmed". Do not add background that you know but the source does not say.
+
+**Good** — the source says: "Orders sometimes fail at the payment step."
+
+```text
+O1  Orders sometimes fail at the payment step.
+```
+
+**Bad** — the same source:
+
+```text
+O1  Orders fail at the payment step. This also breaks refunds.
+```
+
+The word "refunds" is a new fact. The word "sometimes" is gone as well, so G2 is broken too.
+
+### G2 `keep-hedges` (Required)
+
+A hedge tells the reader how far to trust a claim. Examples: might, could, probably, appears to, not yet confirmed, 可能, 推斷, 尚未確認. A hedge is information, not padding.
+
+- If the source says "might", the rung says "might".
+- Keep the hedge in the diagram too. Draw a hedged item with a dashed edge and keep the hedge word in its label.
+- Keep the hedge in the HTML too. Show a visible "not confirmed" badge on the item.
+- A hedge may go only when the source itself says the claim is now verified. Then state what was checked.
+
+**Good** — the source says: "The cause might be a cache that holds an old price list."
+
+```text
+O2  The cause might be a cache that holds an old price list.   [hedge: might]
+```
+
+**Bad** — the same source:
+
+```text
+O2  The cause is a cache that holds an old price list.
+```
+
+The bad version is shorter and easier to read. It is also untrue to the source. A reader who approves a fix on this line has been misled.
+
+### G3 `trace-and-gaps` (Required)
+
+Every item carries two notes:
+
+- **Source**: the place in the source where the item comes from. Use a paragraph and sentence number, or a file and line number, plus a quote of 12 words or fewer.
+- **Not covered**: what the item leaves out, or what it cannot prove. If the source says nothing more, write "Nothing further in the source."
+
+After the last item, add one list called **Left out of this outline**. It names every part of the source that became no item.
+
+**Good**
+
+```text
+O3  We have not yet reproduced this in staging.
+    Source: paragraph 1, sentence 3 — "not yet reproduced this in staging"
+    Not covered: Why it was not reproduced. The source gives no reason.
+```
+
+**Bad**
+
+```text
+O3  The problem was reproduced in staging.
+    Source: the report.
+```
+
+"The report" does not point to a place. The claim also reverses the source. There is no "not covered" note.
+
+## The outline
+
+The outline is the one shared source of truth. Build it before any rung. Never write a rung from the source directly.
+
+Each outline item has one id and one kind.
+
+| Kind | Meaning |
+|------|---------|
+| `claim` | A statement the source makes |
+| `mechanism` | A step, a cause, or a link between two things |
+| `uncertainty` | Something the source says is unknown or unconfirmed |
+| `example` | A case the source gives to show a claim |
+
+Write each item in this shape:
+
+```text
+O<number> | kind | text | hedge: <exact hedge words, or none>
+  Source: <pointer> — "<quote, 12 words or fewer>"
+  Not covered: <what the item leaves out>
+```
+
+Number the items in the order of the source. Never reuse a number. All three rungs use the same ids.
+
+## Workflow
+
+### Step 1 — Read the source
+
+Read the whole source. If the source is a file, read the file. Do not start the outline before you finish reading.
+
+### Step 2 — Build the outline
+
+Extract the items. One fact per item. Copy each hedge word exactly.
+
+### Step 3 — Trace every item
+
+Write the Source and Not covered notes for every item. Then write the **Left out of this outline** list.
+
+### Step 4 — Show the outline to the user
+
+Show the outline when it has more than 5 items, or when the user asks. Let the user remove or correct items. Do not render a rung from an outline the user has rejected.
+
+### Step 5 — Render the rungs
+
+Render each rung the user asked for. Follow the rules below for that rung.
+
+#### Rung 1: controlled text
+
+Follow [ai-response-navigation](../../core/ai-response-navigation.md) clause 12.2:
+
+- One idea per sentence. About 15 to 25 words in English, or about 25 to 40 characters in Chinese.
+- One name per thing. Do not vary a name for style.
+- Name who does what.
+- One step, one action. Put a procedure in a numbered list.
+- Use few semicolons.
+- Put units on numbers.
+
+Keep the item id at the start of each line, so the reader can find the item in the outline.
+
+#### Rung 2: Mermaid diagram
+
+1. Pick `flowchart TD` for steps and causes. Pick `flowchart LR` for parties and hand-offs.
+2. Draw one node for each `mechanism` item. Use the item id as the node id.
+3. Take the node label from the item text. Keep the hedge word in the label.
+4. Draw a hedged item as a dashed node or a dashed edge (`-.->`).
+5. Do not draw a node that has no outline id.
+6. List every item you did not draw, under the diagram, as text. Give each one a reason.
+
+```mermaid
+flowchart TD
+  O1["O1 Orders sometimes fail at payment"]
+  O2["O2 might: a cache holds an old price list"]
+  O1 -.-> O2
+```
+
+#### Rung 3: single-file HTML explainer
+
+The page must be one file. It must open offline. It must not load anything from the network.
+
+**Required** for the page:
+
+- All CSS is inside one `<style>` element.
+- All script, if any, is inside one inline `<script>` element. The page must work with script turned off.
+- No `http://`, `https://` or `//` URL in `src`, `href`, `action`, `@import` or `url()`. The only links allowed are `#` anchors inside the page.
+- No `<link>` element. No web font. No CDN. No external image.
+- No `fetch`, `XMLHttpRequest`, `WebSocket` or `import()` call.
+- Do not load the Mermaid library. Draw the diagram as inline SVG or as a styled list.
+- Escape every character of the source text that HTML treats as markup.
+
+The page holds, in this order:
+
+1. A title and one sentence that says what the source is.
+2. The diagram, if rung 2 was asked for.
+3. One card for each outline item. Each card shows the id, the text, a "not confirmed" badge if the item has a hedge, the Source, and the Not covered note.
+4. The **Left out of this outline** list.
+
+A minimal skeleton:
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Explainer: short name of the source</title>
+<style>
+  body { font: 16px/1.6 system-ui, sans-serif; max-width: 46rem; margin: 2rem auto; padding: 0 1rem; }
+  .card { border: 1px solid #8884; border-radius: 8px; padding: .75rem 1rem; margin: .75rem 0; }
+  .badge { background: #fd0; color: #000; border-radius: 4px; padding: 0 .4rem; font-size: .85em; }
+</style>
+</head>
+<body>
+<h1>Explainer</h1>
+<p>One sentence: what the source is.</p>
+<section class="card" id="O2">
+  <strong>O2</strong> The cause might be a cache that holds an old price list.
+  <span class="badge">not confirmed: might</span>
+  <p><em>Source:</em> paragraph 1, sentence 2</p>
+  <p><em>Not covered:</em> Which cache. The source does not say.</p>
+</section>
+</body>
+</html>
+```
+
+### Step 6 — Check before you deliver
+
+Run all five checks. Fix the rung and run them again if one fails.
+
+1. **Count**: the items in each rung equal the items in the outline, minus the items you listed as not drawn. A source with 5 steps gives 5 steps in every rung. Not 4. Not 6.
+2. **No new item**: every item in a rung has an outline id. Look for an item without one.
+3. **Hedge compare**: for each item with `hedge:` not `none`, the same hedge word is in every rung. The comparison is between the rung and the source. It works in any language.
+4. **Trace**: every item has a Source that points to a place and a Not covered note.
+5. **Offline** (rung 3 only): search the file for `http`, `//`, `<link`, `fetch(` and `XMLHttpRequest`. Each search must find nothing outside the text you quoted from the source.
+
+### Step 7 — Report
+
+End with this table. Never deliver a rung without it.
+
+| Item | Rung 1 | Rung 2 | Rung 3 | Hedge kept | Source | Not covered |
+|------|--------|--------|--------|------------|--------|-------------|
+| O1 | yes | yes | yes | n/a | para 1, s1 | The frequency of "sometimes" |
+
+If any guard check failed and you could not fix it, say which one and why. Do not report success.
+
+## When not to use this skill
+
+- The source has fewer than about 150 words. Rewrite it with [ai-response-navigation](../../core/ai-response-navigation.md) clause 12.2 and keep the hedges. Do not build rungs.
+- The reader is an expert and needs the dense form.
+- The task is to find new facts. This skill never does that.
+
+## Measuring whether it helps
+
+This skill is not proven to help. [eval-cases.md](eval-cases.md) holds 5 source texts, each with comprehension questions and an answer key, and a procedure that gives two numbers: the correct-answer rate before and after, and the number of guard violations. The run needs model calls and has not been done. Do not claim that this skill works until it is done.
+
+## Related
+
+- [ai-response-navigation](../../core/ai-response-navigation.md): Rule 12, controlled language. Clause 12.1 is the base of guard G2.
+- [documentation-guide](../documentation-guide/SKILL.md): where Mermaid diagrams belong in project docs.
+- [brainstorm-assistant](../brainstorm-assistant/SKILL.md): for the opposite direction, when you have no source yet.
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-10-05 | First release. Three rungs built from one outline. Three Required guards. Evaluation cases. Implements dev-platform XSPEC-450 / DEC-125 D4. |

package/bundled/skills/comprehension-ladder/eval-cases.md

@@ -0,0 +1,255 @@
+---
+scope: universal
+description: |
+  Evaluation cases and run procedure for the comprehension-ladder skill: 5 source texts with comprehension questions, answer keys and guard-violation checks. Not yet run.
+  Use when: you want to measure whether the comprehension-ladder skill helps readers, or to re-check its three guards.
+  Keywords: evaluation, eval cases, comprehension questions, answer key, guard violations, DEC-114.
+---
+
+# Comprehension Ladder: Evaluation Cases
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/comprehension-ladder/eval-cases.md) | [简体中文](../../locales/zh-CN/skills/comprehension-ladder/eval-cases.md)
+
+**Status: not run.** This file holds the cases and the procedure. No model has been called and no reader has answered. Until a run is done, do not say that the skill makes text easier to understand.
+
+All five source texts below are written for this evaluation. They describe no real customer, person or system.
+
+## What the run produces
+
+A run produces two numbers:
+
+1. **Correct-answer rate, before and after.** The share of questions answered correctly when the reader sees the original text (arm A, "before") and when the reader sees the skill's output (arm B, "after").
+2. **Guard violations.** The count of times the skill's output breaks guard G1, G2 or G3.
+
+A proposed pass line, to be agreed with the owner before the run: arm B is at least 10 percentage points above arm A, and guard violations equal 0. The 10 points are a starting value. They have not been calibrated.
+
+## Procedure
+
+### 1. Render
+
+For each case, run the skill on the source text. Ask for rung 1 and rung 2. Save the outline and both rungs. If you also want to test rung 3, ask for it and save the HTML file.
+
+Use the same model and the same settings for all five cases. Record the model name.
+
+### 2. Split the readers
+
+Use at least 6 readers. Readers can be people or models. People give stronger evidence. Models are a cheaper stand-in.
+
+Split the readers into two groups of equal size.
+
+| Case | Group 1 reads | Group 2 reads |
+|------|---------------|---------------|
+| 1 | A (original) | B (skill output) |
+| 2 | B | A |
+| 3 | A | B |
+| 4 | B | A |
+| 5 | A | B |
+
+Each reader sees each case once. This prevents a reader from learning the answers in one arm and carrying them to the other.
+
+A reader in arm B sees only the skill output. They do not see the original text.
+
+### 3. Ask the questions
+
+Give each reader the questions for the case. The reader answers from the text they were given. The reader may not use any other source.
+
+A reader may answer "the text does not say". That is a correct answer for the questions marked **not stated**.
+
+### 4. Grade the answers
+
+Grade each answer against the answer key below. An answer is correct only if it meets the "accept" rule. For questions marked **hedge**, an answer that states the claim as certain is wrong, even if the facts are right.
+
+Correct-answer rate = correct answers ÷ all answers, per arm.
+
+### 5. Count guard violations
+
+Check each rendered output against the source text. Count each of the following once per item.
+
+| Guard | One violation is |
+|-------|------------------|
+| G1 `no-new-facts` | An item or sentence that states something the source does not state. The "traps" list in each case names the most likely ones. |
+| G2 `keep-hedges` | An item whose source claim has a hedge, and whose output has no hedge, or a stronger one. The "hedge inventory" in each case lists the hedges. |
+| G3 `trace-and-gaps` | An item with no Source pointer, a pointer that does not lead to the claimed place, or no Not covered note. Also: the output has no "Left out of this outline" list. |
+
+Have a second person count the same outputs, and compare the two counts. If they differ, discuss each difference and record the final count.
+
+### 6. Report
+
+Fill in this table. Both numbers must be there.
+
+| Case | Arm A correct | Arm B correct | G1 | G2 | G3 |
+|------|---------------|---------------|----|----|----|
+| 1 | / | / | | | |
+| 2 | / | / | | | |
+| 3 | / | / | | | |
+| 4 | / | / | | | |
+| 5 | / | / | | | |
+| **Total** | **rate A** | **rate B** | | | |
+
+### Size of the run
+
+The size of the run, so the owner can decide the model and the cost before it starts:
+
+- Render step: 5 skill runs, plus 5 guard checks. That is 10 model calls.
+- Reader step, if readers are models: 5 cases × 2 arms × the number of readers per arm.
+- The questions are short. The longest input is one source text or one rendered output.
+
+The model choice and the budget are the owner's decision. They are not set here.
+
+---
+
+## Case 1: Stale search results
+
+**Type**: incident note with several hedges.
+
+### Source text
+
+> After last night's catalog import, the search page showed old product names for about 3 hours. The most likely cause is that the search index was not rebuilt after the import. We think the import job finished before the rebuild step was queued, but we have not checked the job logs yet. Customers could still buy the products. The team plans to add a rebuild step to the import job on Thursday, if the logs confirm the order of events. Nobody has measured how many customers saw the old names.
+
+### Questions and answer key
+
+| # | Question | Type | Accept |
+|---|----------|------|--------|
+| 1 | For how long did the search page show old names? | fact | About 3 hours |
+| 2 | What is the most likely cause, and is it confirmed? | hedge | The index was not rebuilt after the import. Not confirmed: "most likely" |
+| 3 | Have the job logs been checked? | fact | No. Not yet |
+| 4 | Could customers still buy the products during the problem? | fact | Yes |
+| 5 | When is the fix planned, and what does it depend on? | fact | Thursday. It depends on the logs confirming the order of events |
+| 6 | How many customers saw the old names? | not stated | The text does not say. Nobody has measured it |
+
+### Hedge inventory
+
+"about 3 hours", "most likely", "We think", "have not checked", "if the logs confirm", "Nobody has measured".
+
+### Traps (facts the source does not state)
+
+A number of affected customers. A statement that the cause is confirmed. A statement that the logs show the order of events. Any refund, revenue or ticket count.
+
+---
+
+## Case 2: Refund approval flow
+
+**Type**: process with a branch (a good fit for rung 2).
+
+### Source text
+
+> A customer requests a refund in the app. The system checks the order date. If the order is older than 30 days, the system rejects the request at once and shows the customer a message. If the order is 30 days old or less, the system sends the request to a support agent. The agent approves or rejects it within 2 working days. If the agent approves, the system sends the money back to the original payment method and emails the customer. A refund above NT$5,000 also needs a second approval from a team lead. The spec does not say how long the team lead has to respond.
+
+### Questions and answer key
+
+| # | Question | Type | Accept |
+|---|----------|------|--------|
+| 1 | What happens to a request for a 45-day-old order? | fact | Rejected at once. The customer sees a message |
+| 2 | What happens to a request for an order that is exactly 30 days old? | fact | It goes to a support agent ("30 days old or less") |
+| 3 | How long does the agent have to decide? | fact | 2 working days |
+| 4 | Where does the money go after an approval? | fact | The original payment method. The customer also gets an email |
+| 5 | Which refunds need a second approval, and from whom? | fact | Refunds above NT$5,000. From a team lead |
+| 6 | How long does the team lead have to respond? | not stated | The text does not say |
+
+### Hedge inventory
+
+None in the claims. The text states one gap: "The spec does not say how long the team lead has to respond." The output must keep that gap.
+
+### Traps
+
+A time limit for the team lead. A message text. A rule for refunds of exactly NT$5,000. A step that checks the customer's history.
+
+### Expected size
+
+The source holds 7 outline items of kind `mechanism` (request, date check, rejection, routing, agent decision, payment and email, lead approval) and 1 item of kind `uncertainty` (the missing time limit for the team lead). Every rung should show the same 8 items, or list the ones it did not draw.
+
+---
+
+## Case 3: Retry helper
+
+**Type**: code walk-through with numbers and two hedged points.
+
+### Source text
+
+> The function `fetchWithRetry` calls the payment API up to 4 times. The first call happens at once. After a failed call, it waits before the next one. The wait starts at 200 ms and doubles each time, so the waits are 200 ms, 400 ms and 800 ms. It retries only on network errors and on HTTP status 503. For any other status, such as 400, it stops and returns the error. If all 4 calls fail, it throws the last error. The code adds no random jitter, so many clients that fail together may retry together. We have not tested what happens when the API returns status 429.
+
+### Questions and answer key
+
+| # | Question | Type | Accept |
+|---|----------|------|--------|
+| 1 | What is the largest number of calls the function makes? | fact | 4 |
+| 2 | What are the waits between calls? | fact | 200 ms, 400 ms, 800 ms |
+| 3 | Which failures are retried? | fact | Network errors and HTTP status 503 |
+| 4 | What happens on status 400? | fact | It stops and returns the error |
+| 5 | The code adds no jitter. What could follow? | hedge | Many clients that fail together may retry together. It is a possibility, not a certainty |
+| 6 | What happens on status 429? | not stated | Not known. It has not been tested |
+
+### Hedge inventory
+
+"may retry together", "We have not tested".
+
+### Traps
+
+A behavior for status 429 (retry or no retry). A statement that clients do retry together. A maximum total wait time that the source does not give. A name for the API.
+
+---
+
+## Case 4: Where to store uploaded files
+
+**Type**: three options with trade-offs (a good fit for rung 2).
+
+### Source text
+
+> We compared three ways to store user uploads. Option A: keep the files on the app server's disk. It is the cheapest and needs no new tools. But the files are lost if the server is replaced, and two servers cannot share them. Option B: use object storage from a cloud provider. It costs about NT$600 per month for the current volume. The files survive a server change, and any server can read them. It needs a one-time access key setup. Option C: use a network file share. Servers can share the files, and no code change is needed. But it adds one more machine to maintain, and we think it will be slower under heavy load. We recommend Option B. We have not tested the speed of Option C.
+
+### Questions and answer key
+
+| # | Question | Type | Accept |
+|---|----------|------|--------|
+| 1 | Which option does the text say survives a server replacement? | fact | Option B. (The text says Option A does not. It does not say for Option C.) |
+| 2 | What does Option B cost? | fact | About NT$600 per month for the current volume |
+| 3 | Which option needs no code change? | fact | Option C |
+| 4 | Which option does the team recommend? | fact | Option B |
+| 5 | Is Option C slower under heavy load? | hedge | The team thinks so, but has not tested it |
+| 6 | What does Option C cost? | not stated | The text does not say |
+
+### Hedge inventory
+
+"about NT$600", "we think it will be slower", "We have not tested".
+
+### Traps
+
+A cost for Option A or Option C. A statement that Option C survives a server replacement. A statement that Option C is slower, without the hedge. A reason for the recommendation that the source does not give.
+
+---
+
+## Case 5: Session tokens in access logs
+
+**Type**: security finding with an unknown and a not-yet-rated risk.
+
+### Source text
+
+> During a review of the API gateway, we found that the access log can contain session tokens. A token appears in the log when a client sends it in the URL query string instead of the header. The mobile app, version 2.3, does this on the profile screen. Web clients use the header and are not affected. The logs are kept for 90 days, and 12 engineers can read them. We have not found evidence that anyone used a logged token. The risk is probably moderate, but we have not rated it formally. We propose two changes: move the token to the header in the mobile app, and mask query strings in the log. We do not know yet how many users run app version 2.3.
+
+### Questions and answer key
+
+| # | Question | Type | Accept |
+|---|----------|------|--------|
+| 1 | When does a token appear in the log? | fact | When a client sends it in the URL query string instead of the header |
+| 2 | Which clients are affected? | fact | The mobile app version 2.3, on the profile screen. Web clients are not affected |
+| 3 | How long are the logs kept, and who can read them? | fact | 90 days. 12 engineers |
+| 4 | Has anyone been shown to have misused a logged token? | hedge | No evidence was found. This is not the same as "nobody did" |
+| 5 | How serious is the risk? | hedge | Probably moderate. Not formally rated |
+| 6 | How many users run app version 2.3? | not stated | Not known yet |
+
+### Hedge inventory
+
+"can contain", "We have not found evidence", "probably moderate", "not rated it formally", "We do not know yet".
+
+### Traps
+
+A count of affected users. A statement that no token was misused. A formal risk rating (such as "high" or "medium"). A fix date. A statement that web clients are at risk.
+
+---
+
+## After a run
+
+- Record the date, the model name, the number of readers and who counted the violations.
+- Put the filled report table beside this file. Do not overwrite the cases.
+- If a guard violation count is above 0, fix the skill before you read anything into the correct-answer rate. A rung that adds a fact or drops a hedge can raise the rate and still mislead the reader.
+- If a source text turns out to be ambiguous, fix the text and the key together, and run that case again.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "6.14.0-beta.2",
+  "version": "6.14.0-beta.4",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",
@@ -74,7 +74,7 @@
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^5.0.0",
     "eslint": "10.10.0",
-    "globals": "17.11.0",
+    "globals": "17.12.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.3",
     "vite": "^8.3.0",

package/src/commands/check.js

@@ -1281,6 +1281,15 @@ export function checkPreCommitWiring(projectPath, msg) {
   const result = checkPreCommitHookWiring(projectPath);
   if (!result.relevant) return; // 沒有 UDS 管理的 hook
 
+  // 與 wiring 無關的獨立缺陷面：hook 即使已接上，仍可能請 npm 去解析裸名稱 `uds`
+  // ——npm registry 上那個名稱不是本專案。見 git-hooks.js buildPreCommitBlock。
+  if (result.legacyBareUds) {
+    console.log(chalk.yellow((msg.hookBareUdsTitle || '⚠ [pre-commit] {file} asks npm to run the bare name "uds", which on the npm registry is an unrelated package.')
+      .replace('{file}', result.hookFile)));
+    console.log(chalk.gray(msg.hookBareUdsFix || '  Fix: run `uds update`.'));
+    console.log();
+  }
+
   if (result.wired) {
     // 🔴 「已確認會執行」在 POSIX 上為真，在 Windows 上不一定——git for
     // Windows 沒有 POSIX 的 ENOEXEC → /bin/sh 後備機制，缺 shebang 的 hook