universal-dev-standards 5.17.0 → 6.1.0

package/bundled/core/feature-discovery-standards.md

@@ -0,0 +1,191 @@
+# Feature Discovery Standards
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-05-13
+> **AI-optimized version**: `ai/standards/feature-discovery-standards.ai.yaml`
+> **Spec**: XSPEC-202 (cross-project/specs/XSPEC-202-feature-discovery-standards.md); related: XSPEC-199/200/201 (migration completeness protocol suite)
+
+**Scope**: universal
+**Applicability**: Any legacy-system migration, refactor, or reverse-engineering effort that must produce an exhaustive feature list before change
+
+## Overview
+
+This standard defines a language-agnostic methodology for **exhaustive feature discovery**
+in legacy systems. Its pipeline position is the first of three stages:
+
+```
+feature-discovery-standards (FIND) → feature-manifest-standard (REPRESENT) → behavior-snapshot (VERIFY)
+```
+
+The methodology rests on one non-negotiable idea, **Deterministic-First**, and provides:
+a **Software Form Taxonomy** to pick the right extraction strategy per system type,
+**five static foundations** to run against source alone, a **dynamic observation
+protocol** for systems that can be executed, a **human observation protocol** as last
+resort, and a **cross-layer validation matrix** that merges every foundation's output
+into confidence-scored feature candidates.
+
+## Core Principle: Deterministic-First
+
+> AI cannot tell you what it doesn't know it doesn't know. RAG solves "find details
+> about a known feature." It does NOT solve "discover that this feature exists."
+> Exhaustive feature discovery requires deterministic tools (grep/AST/log/schema) —
+> not AI inference.
+
+- **Blocking rule**: if deterministic extraction artifacts are absent when entering the
+  Discovery Phase, the AI MUST output `[BLOCKED] Missing deterministic extraction
+  artifacts. Run extraction tools first before AI analysis.` and MUST NOT proceed.
+- **RAG prohibition**: during the Discovery Phase, AI is PROHIBITED from generating the
+  feature list through inference or RAG retrieval alone — because AI will not report
+  what it doesn't know it missed; only deterministic tools produce exhaustive lists.
+- **AI's permitted role in Discovery**: classify extracted items into feature
+  categories, assign confidence scores to candidates, and fill in business-purpose
+  descriptions for confirmed entries. AI must NOT generate the initial feature list.
+
+## Software Form Taxonomy
+
+Identify the software's form **before** choosing an extraction strategy. If ambiguous,
+check the detection signals below or ask the user to confirm.
+
+| Form | Key Entry Points | Primary Detection Signal | Fastest Extraction Tool |
+|------|-------------------|---------------------------|--------------------------|
+| **web** | Route definitions, HTTP handlers, middleware | `routes/`/`app/Http/` dir; express/fastify/hono/django/flask/fastapi deps | `grep` route definitions; DB schema extraction; access-log analysis |
+| **cli** | `main()` + arg-parser registrations, shell completions | argparse/click/cobra/clap/typer import; `cmd/` dir; no listen calls | Run `--help` recursively; `grep -rE 'ArgumentParser\|click\.command\|cobra\.Command'` |
+| **gui** | Menu/button handlers, UI definition files | `.ui`/`.fxml`/`.xib`/`.storyboard` files; `QMainWindow`/`JFrame`/`Activity` subclasses | `find . -name '*.ui' -o -name '*.fxml'`; grep event-listener patterns |
+| **daemon** | `main()` + event loop, signal handlers, socket bind/listen | systemd `.service` unit; `signal()`/`bind()`/`listen()` calls; no UI imports | `grep -rE 'signal\(\|SIGTERM\|SIGUSR'`; parse config schema |
+| **library** | Public API surface, header files, `index.d.ts`/`__init__.py` exports | No `main()`; `package.json` `exports`; header files with public markers | `cat index.d.ts` / `__init__.py`; `nm <binary> \| grep ' T '`; analyze existing tests as API spec |
+| **mobile** | Activity/Fragment (Android), UIViewController/SwiftUI View (iOS), deep links, push handlers | `AndroidManifest.xml`; `Info.plist`; `extends Activity`; `UIApplicationDelegate` | `grep android:name` in manifest; `grep CFBundleURLTypes` in Info.plist |
+| **embedded** | Interrupt handlers (ISR), main control loop, protocol parsers, watchdog/timer handlers | `ISR()` macro; `HAL_` prefix functions; no OS process model | `grep -rE 'ISR\(\|__interrupt\|_irq_handler'`; parse linker script (`.ld`) |
+
+## Five Static Foundations
+
+Apply to **all** software forms when git history, access logs, and runtime execution are
+unavailable. Execute in order 1→5 — do not skip any foundation even if earlier ones seem
+comprehensive, since each catches a different category of feature. **Any item appearing
+in any foundation is a confirmed feature candidate**; merge results into the cross-layer
+validation matrix before writing `feature-manifest.yaml`.
+
+| Order | Foundation | What It Catches | Output |
+|-------|-----------|------------------|--------|
+| 1 | **Entry Points** | Direct feature invocation points — the most reliable foundation | Entry point inventory (file:line, handler name, interaction type) |
+| 2 | **Call Graph** | Hidden logic reachable from entry points (nested logic, utility wrappers) | Call graph + dead-code candidate list |
+| 3 | **String Mining** | UI strings, error messages, log calls — features and boundary conditions | String corpus, fed to AI for classification *after* collection |
+| 4 | **Resource Files** | i18n/l10n keys, icons, config schemas, templates — often the most complete inventory | Resource inventory (i18n keys, icon names, config options, template names) |
+| 5 | **External Interfaces** | File I/O, network calls, process execution, env vars — frequently missed because they read as utility code | External interface inventory |
+
+Notes that matter in practice:
+
+- **Call Graph dead code**: functions unreachable from any entry point are dead-code
+  candidates OR dynamic-dispatch targets (virtual functions, reflection). Flag for
+  human review — do not silently exclude.
+- **String Mining value**: each unique error message is a boundary condition and a test
+  scenario.
+- **Resource Files i18n value**: i18n file keys are often the most complete inventory of
+  all UI elements — each key maps to one visible feature element.
+
+## Dynamic Observation Protocol
+
+Use whenever the legacy system can be executed — even partially, even in a degraded/dev
+mode — with a person familiar with the system available to demonstrate realistic usage.
+Running the system once with tracing enabled produces a definitive reachability map that
+static analysis cannot match; **prefer dynamic observation over static analysis when
+available** (static foundations remain required — dynamic observation complements, not
+replaces them).
+
+- **Linux**: `strace -f -o trace.log` (syscalls), `ltrace -f -o ltrace.log` (library
+  calls), `lsof -p <pid>` (open files/sockets), `tcpdump -i any -w net.pcap` (network).
+- **macOS**: `fswatch` (filesystem events), `dtrace` (syscall probes), `tcpdump`.
+- **Windows**: Process Monitor / Sysinternals ProcMon (file/registry/network/process),
+  WireShark (network).
+- **Universal code coverage**: gcov/lcov (C/C++), coverage.py (Python), JaCoCo (Java),
+  nyc/c8 (JS/TS), `go test -coverprofile` (Go) — code coverage with **real usage
+  scenarios** produces a definitive map of reachable code.
+
+Recommended workflow: (1) have a domain expert demonstrate a complete typical workday,
+(2) run strace/coverage in parallel during the demonstration, (3) replay the
+demonstration 3 times for edge cases, (4) analyze the trace for system calls, files
+accessed, and URLs called.
+
+## Human Observation Protocol
+
+Last resort — required when the system cannot run, domain experts are unavailable for
+tracing, or features are triggered only by rare business events.
+
+- **User Demo Recording**: have 1-2 heavy users screen-record (with audio) a full
+  typical workday; review for interactions not captured elsewhere; pay special attention
+  to keyboard shortcuts, context menus, and power-user workflows.
+- **Support Ticket Mining**: search 6-12 months of support tickets/Jira/GitHub issues;
+  each recurring issue type is a boundary condition or edge-case feature; tickets
+  requesting "restore old behavior" are high-risk migration targets; group by frequency.
+- **Internal Knowledge Mining**: internal wiki/Confluence, Slack/Teams history, email
+  threads about system behavior, old (even informal) release notes.
+
+**Confidence assignment**:
+
+| State | Confidence | Meaning | Action |
+|-------|-----------|---------|--------|
+| Human-observed, unverified | 0.7 | Confirmed by user observation, not yet located in source | Add to manifest at 0.7; find source code before AC generation |
+| Human-observed, code-located | 1.0 | Confirmed by user AND verified in code | Upgrade to 1.0 after locating the code |
+
+## Cross-Layer Validation Matrix
+
+After running all applicable foundations, merge results into this matrix. **Any item
+with at least one checkmark is a confirmed feature candidate** for the manifest; items
+with zero checkmarks across all applicable layers are dead-code candidates — flag for
+human review, never silently exclude.
+
+| Column | Source |
+|--------|--------|
+| Entry Point | Foundation 1: Entry Points |
+| DB/Schema | Foundation 1 (web): DB schema; data file for other forms |
+| Log/Dynamic | Access log (web) or dynamic observation trace |
+| UI/Resource | Foundation 3 (String Mining) + Foundation 4 (Resource Files) |
+| Notification/External | Foundation 5: External Interfaces |
+| Git/History | `git log --grep` / commit history, if available |
+| Human | Human observation protocol |
+
+```
+confidence = (columns_with_checkmark) / (columns_applicable_to_this_form)
+Minimum to include in feature-manifest: ≥ 1 checkmark in any column
+Confidence < 0.5: flag for human review before AC generation
+Confidence < 0.3: require human confirmation before including in manifest
+```
+
+Example:
+
+| Feature Candidate | Entry Point | DB/Schema | Log/Dynamic | UI/Resource | Notification/Ext | Git/History | Human | Confidence |
+|---|---|---|---|---|---|---|---|---|
+| UserLogin | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 1.0 |
+| MonthlyReconcile | ❌ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | 0.71 |
+| AdminUserDelete | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ | 0.57 |
+
+Each confirmed row becomes an `FM-NNN` entry per `feature-manifest-standard`; the
+confidence value from this matrix becomes the manifest's `confidence` field.
+
+## Rules
+
+| Rule | Trigger | Instruction | Priority |
+|------|---------|--------------|----------|
+| `deterministic-first` | Starting feature discovery for any legacy system | Require deterministic extraction results before generating any feature list; if absent, output `[BLOCKED]` and list applicable tools for the detected form | required |
+| `no-rag-for-discovery` | Feature discovery phase | Do NOT use RAG/long-context inference alone to generate the initial feature list; RAG is permitted only to fill in details of already-identified features | required |
+| `identify-form-first` | Starting feature discovery | Identify the software form using detection signals before selecting an extraction strategy; ask the user to confirm if ambiguous | required |
+| `apply-all-static-foundations` | Source-only analysis (no git, no log, no runtime) | Execute all five static foundations in order; merge all candidate lists into the cross-layer matrix | required |
+| `prefer-dynamic-observation` | Legacy system can be executed in any environment | Prefer dynamic observation (strace/coverage + expert demo) over static analysis alone; static foundations remain required | recommended |
+| `human-observation-for-gaps` | A feature candidate cannot be confirmed by any tool-based foundation | Escalate to human observation; assign confidence 0.7 for human-observed/code-unverified; never include confidence < 0.3 without explicit human confirmation | required |
+| `matrix-before-manifest` | Generating `feature-manifest.yaml` | Complete the cross-layer validation matrix first; only ≥1-checkmark items become `FM-NNN` entries; zero-checkmark items go to a separate `dead_code_candidates` list | required |
+| `dead-code-handling` | Call graph analysis reveals unreachable code | Never silently exclude unreachable functions; list as `dead_code_candidates`; account for dynamic dispatch; require human confirmation before classifying as dead code | required |
+
+## Related Standards
+
+- `feature-manifest-standard` — represents confirmed candidates as `FM-NNN` entries
+- `behavior-snapshot` — verifies the manifest against observed runtime behavior
+- `reverse-engineering-standards` — broader legacy reverse-engineering process this
+  standard feeds into
+- `anti-hallucination` — the deterministic-first / no-inference-alone discipline this
+  standard applies to feature discovery specifically
+- `acceptance-criteria-traceability` — confirmed features become AC-traceable units
+- `refactoring-standards` — discovery precedes any refactor of legacy code
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-05-13 | Initial — Deterministic-First principle, Software Form Taxonomy (7 forms), five static foundations, dynamic/human observation protocols, cross-layer validation matrix (XSPEC-202) |

package/bundled/core/flaky-test-management.md

@@ -69,7 +69,7 @@ export default defineConfig({
 
 ## Related Standards
 
-- [Testing Standards](testing.md) — overall test pyramid
+- [Testing Standards](testing-standards.md) — overall test pyramid
 - [Test Governance Standards](test-governance.md) — CI policies
 
 

package/bundled/core/flow-based-testing.md

@@ -1,7 +1,7 @@
 # Flow-Based Testing
 
-**Version**: 1.3.0
-**Last Updated**: 2026-05-05
+**Version**: 1.3.1
+**Last Updated**: 2026-06-18
 **Applicability**: All software projects with multi-step workflows
 **Scope**: universal
 **Industry Standards**: ISO/IEC/IEEE 29119-4 (Test Techniques), ISTQB Foundation Syllabus
@@ -111,7 +111,7 @@ describe("Flow Branch: Quota exceeded path", () => {
 
 ## Relationship to Other Standards
 
-- **test-completeness-dimensions**: Dimensions 9 (Flow Completeness) and 10 (Branch Coverage) are defined here
+- **test-completeness-dimensions**: defines **8** dimensions. Flow Completeness and Branch Coverage (decision-table) are detailed in THIS standard — they are not numbered dimensions 9/10 there (which has only 8)
 - **behavior-driven-development**: BDD Scenario Outline tables map to decision table expansion
 - **mock-boundary**: Flow tests must respect mock boundary rules (no mocking own module logic)
 - **e2e-testing**: Journey tests run at ST or E2E level; flow tests can run at IT level with real DB

package/bundled/core/forward-derivation-standards.md

@@ -1,6 +1,6 @@
 # Forward Derivation Standards | 正向推演標準
 
-**Version**: 1.2.0
+**Version**: 1.3.0
 **Last Updated**: 2026-03-18
 **Applicability**: All projects using Spec-Driven Development
 **Scope**: uds-specific
@@ -213,13 +213,12 @@ Use these labels to indicate derivation certainty:
 # Generator: forward-derivation v1.0.0
 # Generated at: 2026-01-19T10:00:00Z
 
-@SPEC-001
 Feature: User Authentication
   As a user
   I want to login to the system
   So that I can access my dashboard
 
-  @AC-1 @happy-path
+  @SPEC-001 @AC-1 @happy-path
   Scenario: User login with valid credentials
     # [Source] From SPEC-001 AC-1
     Given a registered user with valid credentials
@@ -227,7 +226,7 @@ Feature: User Authentication
     Then the user is redirected to dashboard
     And a session token is created
 
-  @AC-2 @error-handling
+  @SPEC-001 @AC-2 @error-handling
   Scenario: Login fails with invalid credentials
     # [Source] From SPEC-001 AC-2
     Given a user with invalid credentials
@@ -824,6 +823,34 @@ Forward derivation maps to the **DERIVE** stage in the [Pipeline Integration Sta
 
 ---
 
+## Failure Handling & Recovery
+
+Forward derivation defines several gates (AC parse, count verification, skeleton
+validation, human review). This section defines what happens when a gate
+**fails** — the failure → rollback → retry/escalate → re-verify path — so a
+failed derivation never silently emits partial or hallucinated output.
+
+### Failure → Recovery Matrix
+
+| Failure | Detected at | Recovery action | Re-verify |
+|---------|-------------|-----------------|-----------|
+| **Parse error** — an AC is not in a supported format (GWT / bullet) | DERIVE (parse AC) | Abort generation for that AC; report `file:line` and the expected format; emit no skeleton for it. Re-queue once the SPEC is fixed. | Parse succeeds on the corrected AC |
+| **AC count mismatch** — generated test count ≠ AC count | Count verification | **[Anti-hallucination violation]** Roll back the whole batch and regenerate under strict 1:1 mapping. Never add or delete tests to "make the count match" — that hides the hallucination. | Count check passes (tests = ACs) |
+| **Skeleton does not parse/compile** | Skeleton validation | Roll back the offending file; regenerate with the correct language template. On a second failure, mark the AC `[BLOCKED]` and escalate to a human. | File parses/compiles |
+| **Human review rejection** — reviewer flags wrong logic or unfilled `[TODO]` | Human review gate | Record the rejection reason; regenerate only the rejected items with that feedback as an added constraint. Never auto-approve. | Reviewer accepts |
+| **Missing source attribution** — output lacks `@SPEC-XXX` / `@AC-N` | Any stage | Block the transition into TDD RED; re-emit with attribution. | Every output carries attribution |
+
+### Recovery Rules
+
+| Rule | Description | Severity |
+|------|-------------|----------|
+| **FD-FAIL-001** | A gate failure MUST halt progression — never enter TDD RED with an unresolved failure. | Required |
+| **FD-FAIL-002** | A count mismatch is a hard rollback, not a reconciliation; adding or deleting tests to match the count is forbidden (it masks hallucination). | Required |
+| **FD-FAIL-003** | Automated retries are bounded (max 2, for transient or template errors); on exhaustion mark the AC `[BLOCKED]` and escalate to a human. | Required |
+| **FD-FAIL-004** | Every recovery path ends by re-verifying the gate it failed — recovery is incomplete until the original check passes. | Required |
+
+---
+
 ## Anti-Patterns to Avoid
 
 ### Generation Anti-Patterns
@@ -874,7 +901,7 @@ Forward derivation maps to the **DERIVE** stage in the [Pipeline Integration Sta
 
 ### Skill References
 
-- [Forward Derivation Skill](../skills/forward-derivation/SKILL.md) - Detailed workflow implementation
+- [Forward Derivation Skill](../skills/spec-derivation/SKILL.md) - Detailed workflow implementation
 - [Spec-Driven Development Skill](../skills/spec-driven-dev/SKILL.md) - SDD workflow
 - [BDD Assistant Skill](../skills/bdd-assistant/SKILL.md) - Gherkin refinement
 - [TDD Assistant Skill](../skills/tdd-assistant/SKILL.md) - Test implementation
@@ -925,6 +952,7 @@ Forward derivation maps to the **DERIVE** stage in the [Pipeline Integration Sta
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.3.0 | 2026-06-18 | Added: Failure Handling & Recovery section — failure→rollback→retry/escalate→re-verify matrix + recovery rules FD-FAIL-001..004 (XSPEC-292 T7) |
 | 1.2.0 | 2026-03-18 | Added: Pipeline Integration section — auto-TDD transition, pipeline hooks, auto-TDD entry workflow |
 | 1.1.0 | 2026-01-25 | Added: Contract output (contract.json), Schema output (schema.json), /derive-contracts command for verification artifact generation |
 | 1.0.0 | 2026-01-19 | Initial release |

package/bundled/core/frontend-design-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/frontend-design-standards.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-04-13
+**Version**: 1.1.0
+**Last Updated**: 2026-07-10
 **Applicability**: All projects with frontend user interfaces
 **Scope**: universal
 **References**: [DEC-029](https://github.com/VoltAgent/awesome-design-md) (awesome-design-md, MIT), DEC-030 (OpenAI Frontend Guide)
@@ -41,8 +41,9 @@ The goal is to ensure AI agents produce consistent, high-quality UI across diffe
 13. [Spacing Scale](#spacing-scale)
 14. [UI Hard Constraints](#ui-hard-constraints)
 15. [Anti-patterns](#anti-patterns)
-16. [DESIGN.md File Placement](#designmd-file-placement)
-17. [Validation Checklist](#validation-checklist)
+16. [Optional Extension: Token Interpolation & Structured Components](#optional-extension-token-interpolation--structured-components)
+17. [DESIGN.md File Placement](#designmd-file-placement)
+18. [Validation Checklist](#validation-checklist)
 
 ---
 
@@ -417,6 +418,88 @@ Minimum required: at least 5 anti-patterns must be explicitly listed in every DE
 
 ---
 
+## Optional Extension: Token Interpolation & Structured Components
+
+> **Status**: Optional, Trial (added v1.1.0, 2026-07-10). Does **not** replace the mandatory 9-section structure or the governance-collapsed 5-token/4-role/7-step scales above — this is an additive machine-parseable layer for projects that want DESIGN.md itself to carry structured token references, not just prose. A DESIGN.md that omits this extension is still fully compliant.
+>
+> **Origin**: 2026-07-10 re-alignment review of [DEC-029](https://github.com/VoltAgent/awesome-design-md)'s upstream (grown from 4,385★ to 99,219★ and now officially the Google Stitch DESIGN.md format) found the upstream format evolved YAML frontmatter token dictionaries and `{category.token}` interpolation syntax, plus a structured `components:` binding block — capabilities this standard's original prose-only sections did not have. Adopted as an opt-in extension rather than a breaking change, consistent with this standard's deliberate 5-token governance collapse (adding more tokens is *not* the goal; making the 5 tokens *referenceable* is).
+
+### Token Registry (YAML Frontmatter)
+
+A DESIGN.md may optionally begin with a YAML frontmatter block declaring the semantic tokens from Sections 2/3/5 (and Section 4's border-radius scale) in machine-parseable key-value form, so tooling can resolve `{category.token}` references without re-parsing prose.
+
+```yaml
+---
+colors:
+  background: "#0A0A0A"
+  surface: "#1A1A1A"
+  primary-text: "#F5F5F5"
+  muted-text: "#888888"
+  accent: "#6366F1"
+typography:
+  display: { size: "48px", weight: 700, line-height: 1.1 }
+  headline: { size: "24px", weight: 600, line-height: 1.3 }
+  body: { size: "16px", weight: 400, line-height: 1.6 }
+  caption: { size: "13px", weight: 400, line-height: 1.4 }
+rounded:
+  sm: "4px"
+  md: "8px"
+  lg: "12px"
+  pill: "9999px"
+spacing:
+  sm: "8px"
+  md: "24px"
+  lg: "48px"
+---
+```
+
+**Rules**:
+- The frontmatter keys (`colors`, `typography`, `rounded`, `spacing`) map 1:1 to the token vocabularies already defined in Sections 2/3/5 — this block **restates** those tokens in parseable form, it does not introduce new ones. `colors` values must match the 5 mandatory semantic tokens (plus any optional extended tokens already in use).
+- Frontmatter is optional. A DESIGN.md without it is still valid; tooling that wants interpolation support requires it.
+
+### Interpolation Syntax
+
+Within the prose sections (particularly Section 4: Component Styling), `{category.token}` references the frontmatter registry instead of restating raw values:
+
+```markdown
+### Buttons
+- **Primary**: `{colors.accent}` background, `{colors.background}` text, `{rounded.md}` radius, `{spacing.sm}` padding
+```
+
+**Rules**:
+- Syntax is `{category.token}` — category matches a frontmatter top-level key, token matches a key within it.
+- A reference to a category/token not present in frontmatter is a validation error, not a silent fallback.
+- Interpolation is for **documentation/tooling clarity**, not a runtime templating engine — DESIGN.md remains a static specification file.
+
+### Structured Components Block (Optional)
+
+Section 4 (Component Styling) may optionally include a `components:` block that binds a component to its token references explicitly, instead of (or alongside) the prose format already in Section 4's example:
+
+```yaml
+components:
+  button-primary:
+    backgroundColor: "{colors.accent}"
+    textColor: "{colors.background}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.sm}"
+  card:
+    backgroundColor: "{colors.surface}"
+    rounded: "{rounded.lg}"
+    padding: "{spacing.md}"
+```
+
+**Rules**:
+- Every value must be a `{category.token}` reference — raw hex/px values inside `components:` are an anti-pattern (defeats the purpose of centralizing tokens).
+- This block is additive to, not a replacement for, Section 4's prose description — projects using this extension should still fill Section 4's prose fields for human readers.
+
+### Non-goals (explicitly not adopted from upstream)
+
+- **No lint CLI bundled with this standard** — the upstream ecosystem has a separate `@google/design.md` npm package for validation; this standard does not mandate or bundle a specific validator. Projects may adopt one independently.
+- **No framework-specific export formats** (React/Vue/CSS-in-JS generators) — stays framework-agnostic per this standard's Key Principles (semantic token naming, framework-agnostic).
+- **No expansion of the 5/4/7 token counts** — the interpolation syntax makes the existing tokens referenceable; it is not licence to add more tokens. Governance collapse (fewer tokens = more consistent AI output) remains the priority over granularity.
+
+---
+
 ## DESIGN.md File Placement
 
 DESIGN.md must be placed at the **project root directory**, at the same level as README.md.
@@ -472,3 +555,9 @@ Use this checklist to verify a DESIGN.md is compliant with this standard:
 - [ ] Style summary present (1–2 sentences)
 - [ ] Key constraints bullet list present
 - [ ] Tone defined
+
+### Token Interpolation Extension (Optional — v1.1.0)
+- [ ] If frontmatter token registry is used, all `colors` keys match the 5 mandatory semantic tokens
+- [ ] If `{category.token}` interpolation is used, every reference resolves to a frontmatter entry (no dangling references)
+- [ ] If `components:` block is used, every value is a `{category.token}` reference (no raw hex/px values)
+- [ ] Absence of this extension is **not** a compliance failure — it is optional

package/bundled/core/full-coverage-testing.md

@@ -160,6 +160,74 @@ CI reports AC coverage rate. If more than 20% of ACs lack `@ac`-tagged tests, a
 
 ---
 
+## Migration Error-Path Completeness (XSPEC-288)
+
+> Part of the [XSPEC-284](https://github.com/AsiaOstrich/universal-dev-standards) 9-axis migration completeness matrix (**axis ⑨ — error paths**). The three-path model above requires an error path **per function**; this section adds the **migration-specific** guarantee that legacy's error/degradation/fallback branches are **systematically** carried over — not merely sampled.
+
+### Why the three-path model alone is not enough for a migration
+
+The per-function error-path requirement and XSPEC-201's error-path snapshot only verify the error cases **you thought to enumerate**. In a rewrite the happy path is migrated because it has an explicit requirement, while error branches — scattered across `try/catch` layers, custom exception hierarchies, specific error codes, and degradation fallbacks — are **silently dropped in bulk**. A passing error-path sample does not prove **no branch was missed** (same blind-spot class as #134, occurring on the error-path layer). This section is the **systematic-enumeration + gap-analysis** layer above the snapshot mechanism.
+
+### Step 1 — Mechanized legacy exception / error-code list (derive, R1)
+
+Enumerate the legacy error surface **mechanically**, not from memory:
+
+| Source | Yields |
+|--------|--------|
+| `catch` / `except` / `rescue` blocks (grep) | every caught exception type + handler |
+| Custom exception / error class hierarchy | the declared error taxonomy |
+| Error/status codes (HTTP status, app error codes, error enums) | the response-code surface |
+| Error response shapes (serializers, error DTOs) | the on-the-wire error contract |
+
+The captured list is the **error-path to-verify checklist** — sourced from artifacts, not human recall.
+
+### Step 2 — Systematic missing-branch gap analysis (oracle, R2)
+
+For **each** legacy error branch from Step 1, verify the new system has a corresponding handler. A branch with no mapping is marked `not_implemented` (XSPEC-199) and **blocks**. The output is a **"missing error branch" gap report** over the full derived list — not a sample that happened to pass.
+
+```markdown
+## Error-Path Gap Report — <module>
+
+| Legacy branch (error type / code) | New-system handler | Status |
+|-----------------------------------|--------------------|--------|
+| PaymentDeclinedException → 402 | PaymentService.handleDecline | MAPPED |
+| GatewayTimeout → retry+fallback | (none found) | not_implemented — BLOCK |
+| ValidationError → 422 + field list | InputValidator | MAPPED |
+
+**Branches: N total · M mapped · K not_implemented (block if K>0)**
+```
+
+### Step 3 — Degradation / fallback parity (R3)
+
+Legacy degradation modes (fallback on external-service failure, retry, partial results) are easy to drop because they only run when something fails. Verify the new system preserves the corresponding degradation behavior, so the system is not "consistent on the happy path, wildly different on failure":
+
+- [ ] External-service-failure **fallback** behavior matches legacy
+- [ ] **Retry** policy (count, backoff, give-up) matches legacy
+- [ ] **Partial-result** handling matches legacy (returns what it can vs all-or-nothing)
+- [ ] **Circuit-breaker / timeout** degradation matches legacy
+
+### Step 4 — Error-response differential (oracle, R4)
+
+Extend [behavior-snapshot](behavior-snapshot.md) parity and XSPEC-284 R5 replay to cover the **error response**, not just the happy-path response. Compare new vs legacy on:
+
+- **Error code** (HTTP status, app error code)
+- **Message structure** (error DTO shape, field-level errors)
+- **HTTP status** mapping per error class
+
+This makes implicit error-path divergence self-report at cutover, the same way the happy-path snapshot does.
+
+**Gate timing**: pre-UAT (gap analysis + degradation parity) + cutover before/after (error-response differential).
+
+### Importance ranking (scope guidance)
+
+Not every legacy error branch must map at equal priority. Rank by **production-actual trigger frequency** (echoes #134 "production is the oracle"): branches that have actually fired in production logs are mapped first; never-fired latent branches are lower priority but still listed. A high-frequency production error branch with no new-system mapping is a hard block.
+
+### Completeness declaration (matrix alignment)
+
+Axis ⑨ is satisfied when this section declares all three: **derive** (Step 1 mechanized exception/error-code list), **oracle** (Step 2 systematic gap analysis + Step 4 error-response differential), and **gate timing** (pre-UAT + cutover before/after). Reuse XSPEC-201 error-path snapshot + the three-path model above — this section adds only systematic missing-branch analysis and the error-response differential, it does not rebuild a test framework.
+
+---
+
 ## Migration from Pyramid Model
 
 If your project previously used pyramid thresholds:
@@ -180,7 +248,11 @@ The ratchet starts at your current coverage. From that point on, it can only inc
 - `unit-testing.ai.yaml` — Unit test scope and organization
 - `integration-testing.ai.yaml` — Integration test patterns
 - `deployment-standards.ai.yaml` — Deploy gate requirements
+- `flaky-test-management.md` — Intermittent-failure handling: a test that flakes is **not** a passing test. Before a coverage figure counts toward a gate, intermittent failures MUST be quarantined / retry-budgeted / root-caused per that standard — otherwise "full coverage" hides non-deterministic gaps.
+- `behavior-snapshot.md` — Error-response differential oracle (Migration Error-Path Completeness, axis ⑨)
+- `migration-assistant` skill — Legacy exception/error-code derive + degradation parity (XSPEC-288)
 - XSPEC-178 — Full specification and implementation phases
+- XSPEC-288 — Migration Error-Path Completeness (axis ⑨ of XSPEC-284 matrix)
 
 
 **Scope**: universal

package/bundled/core/git-worktree.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/git-worktree.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-03-20
+**Version**: 1.1.0
+**Last Updated**: 2026-06-18
 **Applicability**: All projects using Git for version control
 **Scope**: universal
 **Inspired by**: [Superpowers](https://github.com/obra/superpowers) — using-git-worktrees (MIT)
@@ -59,7 +59,7 @@ pnpm install  # or npm install, pip install, etc.
 
 1. **Run the test suite** in the fresh worktree
 2. **Confirm all tests pass** — this verifies the environment is clean
-3. **If tests fail** — abort and report the environment issue (do not proceed)
+3. **If tests fail** — retry up to 2× with backoff to rule out transient flakes/timeouts; if they still fail, abort and report the environment issue (do not proceed)
 
 ```bash
 # Baseline verification
@@ -108,7 +108,7 @@ git worktree prune
 | ID | Trigger | Action | Priority |
 |----|---------|--------|----------|
 | GW-001 | Worktree directory not in `.gitignore` | Automatically add to `.gitignore` | Critical |
-| GW-002 | Baseline tests fail | Abort task, report environment issue | High |
+| GW-002 | Baseline tests fail | Retry up to 2× (exponential backoff) for transient failures; if persistent, abort task and report environment issue | High |
 | GW-003 | Abnormal exit during worktree operation | Ensure cleanup is executed | High |
 | GW-004 | Worktree exists after branch merge/delete | Prune stale worktree references | Medium |
 

package/bundled/core/guides/performance-guide.md

@@ -1,6 +1,6 @@
 # Performance Guide
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/core/guides/performance-guide.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/core/guides/performance-guide.md) | [简体中文](../../locales/zh-CN/core/guides/performance-guide.md)
 
 **Version**: 1.0.0
 **Last Updated**: 2026-01-29

package/bundled/core/guides/security-guide.md

@@ -1,6 +1,6 @@
 # Security Guide
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/core/guides/security-guide.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/core/guides/security-guide.md) | [简体中文](../../locales/zh-CN/core/guides/security-guide.md)
 
 **Version**: 1.0.0
 **Last Updated**: 2026-01-29

package/bundled/core/health-check-standards.md

@@ -12,7 +12,7 @@
 - **Readiness 僅檢關鍵依賴**：非關鍵依賴不納入，避免邊緣故障造成服務被下線
 - **慢啟動用 startup probe**：啟動完成後交棒給 liveness
 - **結構化 JSON 回應**：含 `status` / `dependencies` / `timestamp` / `version`
-- **作為 observability signal**：連續 fail 觸發 incident
+- **作為 observability signal**：連續 fail（達 probe threshold）依 [alerting-standards](alerting-standards.md) 觸發告警——由 alerting 定義觸發時機、嚴重性對映與路由（`HC-001 HEALTH_CHECK_FAILED` 為 alert 來源之一），health-check 只負責 emit signal、不自行決定通知對象
 
 ## Probe Types
 
@@ -68,7 +68,7 @@
 - AI-optimized: [ai/standards/health-check-standards.ai.yaml](../ai/standards/health-check-standards.ai.yaml)
 - XSPEC-067: DEC-043 Wave 1 Reliability Pack 跨專案規格
 - DEC-043: UDS 覆蓋完整性路線圖（驅動來源）
-- Related: `deployment-standards`, `circuit-breaker`, observability-standards (XSPEC-063 規劃中)
+- Related: `deployment-standards`, `circuit-breaker`, `alerting-standards`（probe 連續失敗 → 告警觸發與路由）, observability-standards (XSPEC-063 規劃中)
 - Industry: Kubernetes probes, Microsoft eShop health checks, Google SRE Book Ch.6