universal-dev-standards 5.17.0 → 6.1.0

package/bundled/core/privacy-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/privacy-standards.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-04-01
+**Version**: 1.1.0
+**Last Updated**: 2026-06-18
 **Applicability**: All software projects handling personal data
 **Scope**: universal
 **Industry Standards**: GDPR, CCPA, Privacy by Design (Ann Cavoukian)
@@ -51,13 +51,23 @@ Classify all data by sensitivity level:
 ### Trigger Conditions
 
 A DPIA MUST be conducted when:
-- Processing personal data at large scale
+- Processing personal data at **large scale** (see quantified criterion below)
 - Systematic monitoring of public areas
 - Automated decision-making with legal effects
 - Processing special category data (health, biometric, genetic)
 - Combining datasets from different sources
 - Processing data of vulnerable individuals (children, employees)
 
+> **"Large scale" — quantified criterion** _(source: GDPR Art. 35; WP29 DPIA
+> Guidelines WP248rev.01)_. No single hard number defines "large scale"; assess
+> against four factors: (1) number of data subjects — an absolute count or a
+> proportion of the relevant population; (2) volume and range of data items;
+> (3) duration or permanence of the processing; (4) geographical extent. Treat
+> processing as large scale when it is significant on **two or more** factors.
+> **Exception**: one-off processing, a single individual's data, or an
+> individual practitioner's records are not "large scale" and do not trigger a
+> DPIA on this ground alone (the other triggers above may still apply).
+
 ### Simplified DPIA Template
 
 ```markdown
@@ -180,6 +190,7 @@ Is it personal data?
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-06-18 | Added: quantified "large scale" DPIA-trigger criterion (GDPR Art. 35 / WP29 WP248) + exception clause (XSPEC-292 T8) |
 | 1.0.0 | 2026-04-01 | Initial release |
 
 ---

package/bundled/core/product-metrics-standards.md

@@ -0,0 +1,100 @@
+# Product Metrics Framework Standards
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-06-17
+> **AI-optimized version**: `ai/standards/product-metrics-standards.ai.yaml`
+> **Spec**: XSPEC-069 (cross-project/specs/XSPEC-069-uds-product-layer-pack.md)
+
+**Scope**: universal
+
+## Overview
+
+This standard defines how teams **select, structure, and govern product metrics**.
+It covers a framework-selection matrix (AARRR for growth products, HEART for
+experience products, custom North Star for platforms), North Star criteria, a
+three-level metric hierarchy (North Star → L1 drivers → L2 diagnostics), and an
+anti-vanity rule that rejects metrics decoupled from revenue or retention impact.
+It aligns teams around metrics that drive meaningful product decisions rather than
+activity tracking.
+
+It is part of the **product-layer pack** (XSPEC-069). Its tracking requirements
+connect to the SRE observability primitives (`observability-standards`, `slo-sli`).
+
+> **Scope.** This standard defines *metric selection and governance*. Concrete
+> analytics tooling (Amplitude/Mixpanel) is an adoption choice. Service-level
+> reliability metrics live in `slo-sli`; this is the product-outcome view.
+
+## Requirements
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | Framework selection matrix (AARRR / HEART / custom North Star) | MUST |
+| REQ-002 | North Star criteria (leading, measurable, actionable, explainable) | MUST |
+| REQ-003 | Metric hierarchy (max three levels) | MUST |
+| REQ-004 | Anti-vanity rule | MUST |
+
+### REQ-001 — Framework Selection Matrix
+
+Teams MUST select a primary metrics framework appropriate to their product type:
+**Growth products** (consumer apps, marketplaces, viral products) → **AARRR**
+(Acquisition, Activation, Retention, Referral, Revenue); **Experience products**
+(productivity tools, B2B SaaS) → **HEART** (Happiness, Engagement, Adoption,
+Retention, Task Success); **Platform products** (developer platforms, APIs) →
+a **custom North Star** reflecting platform value delivered, supplemented by AARRR
+or HEART components. Framework selection MUST be documented in the PRD or product
+strategy document.
+
+### REQ-002 — North Star Criteria
+
+Every product MUST define exactly one North Star metric satisfying all four
+criteria: (1) **Leading indicator** — predicts future business health rather than
+measuring past outcomes; (2) **Measurable and trackable** — computable from
+available data with a defined cadence (weekly/monthly); (3) **Actionable by the
+team** — the product team has direct levers to influence it; (4) **Explainable in
+one sentence**. The North Star MUST be reviewed and reconfirmed at each annual
+product planning cycle.
+
+### REQ-003 — Metric Hierarchy
+
+Teams MUST structure metrics in a hierarchy of at most three levels. **Level 1
+(North Star)**: one metric for overall product value. **Level 2 (L1 drivers)**:
+3–5 metrics that directly influence the North Star, each with a documented causal
+hypothesis. **Level 3 (L2 diagnostics)**: per-feature/per-team metrics explaining
+movements in L1 drivers (max 3 per driver). Metrics beyond three levels are
+PROHIBITED — they indicate measurement fragmentation rather than focus.
+
+### REQ-004 — Anti-Vanity Rule
+
+Teams MUST apply the anti-vanity test before adding any metric to the official
+dashboard. A metric fails if it can increase while revenue and retention stay flat
+or decrease; such metrics MUST NOT appear in official product reviews or be used as
+feature success criteria. Common failures: total registered users (no active
+filter), raw pageviews (no session-quality filter), total API calls (no unique
+active-customer filter), press mentions, downloads without activation. When a
+vanity metric is useful operationally, it MUST be labeled "operational indicator,
+not success metric."
+
+## Anti-Patterns
+
+- Tracking vanity metrics (total signups, raw pageviews) as primary success indicators.
+- No North Star defined — teams optimize different local metrics, creating misalignment.
+- Conflicting team metrics where one team's optimization harms another's.
+- Metric hierarchy deeper than three levels — complexity without insight.
+- Changing the North Star quarterly, preventing year-over-year trend analysis.
+
+## Integration with Existing Standards
+
+- **`prd-standards`** — PRD success metrics are drawn from this hierarchy.
+- **`observability-standards` / `slo-sli`** — the *tracking* of product metrics
+  reuses the SRE metric/observability primitives; reliability SLOs stay in `slo-sli`.
+- **`user-story-mapping`** — story acceptance criteria tie to a North Star driver.
+
+## Related Specs
+
+- XSPEC-069 — UDS product-layer pack (this standard's source)
+- XSPEC-063 — SRE pack (`observability-standards`, `slo-sli`)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-06-17 | Initial — REQ-001~004: framework matrix, North Star criteria, metric hierarchy, anti-vanity rule (XSPEC-069) |

package/bundled/core/project-context-memory.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/project-context-memory.md)
 
-**Version**: 1.1.0
-**Last Updated**: 2026-03-16
+**Version**: 1.2.0
+**Last Updated**: 2026-06-18
 **Applicability**: All software projects using AI assistants
 **Scope**: uds-specific
 
@@ -200,6 +200,11 @@ Beta v5.1.0-beta.1 published on 2026-03-14.
 | `updated_at` > 7 days old | Flag as stale, ask to archive or resume |
 | All `remaining` steps completed | Suggest archiving the workflow state |
 
+> The 7-day staleness window is a UDS default, configurable per project. Basis:
+> a workflow state untouched for over a week is likely abandoned or superseded
+> in short-cycle development; it aligns with the developer-memory staleness
+> model. Lengthen it for long-running or part-time projects.
+
 ---
 
 ## 5. Comparison with Developer Memory
@@ -231,6 +236,7 @@ We use **Split-File Storage** (one Markdown file per topic) rather than a single
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.2.0 | 2026-06-18 | Added: rationale + configurable note for the 7-day staleness threshold (XSPEC-292 T8) |
 | 1.1.0 | 2026-03-16 | Add `workflow-state` type for cross-session state tracking |
 | 1.0.0 | 2026-02-09 | Initial standard definition |
 

package/bundled/core/prompt-regression.md

@@ -69,7 +69,7 @@ The comment is mandatory. PRs that update checksums without explanatory comments
 
 - [LLM Output Validation](llm-output-validation.md) — schema-level validation
 - [Adversarial Test](adversarial-test.md) — red-team corpus
-- [Testing Standards](testing.md) — overall testing pyramid
+- [Testing Standards](testing-standards.md) — overall testing pyramid
 
 
 **Scope**: universal

package/bundled/core/push-standards.md

@@ -0,0 +1,82 @@
+# Git Push Safety Gates
+
+> **Version**: 1.1.0 | **Status**: Active | **Updated**: 2026-07-09
+> **AI-optimized version**: `ai/standards/push-standards.ai.yaml`
+> **Spec**: XSPEC-081 (cross-project/specs/XSPEC-081-uds-push-skill.md)
+
+**Scope**: universal
+**Applicability**: Any project using Git, invoking the `/push` skill or an equivalent
+AI-assisted push workflow
+
+## Overview
+
+This standard defines the safety gates an AI assistant MUST apply around `git push`:
+protected-branch detection, force-push guardrails, pre-push quality gates, and a
+structured push-receipt audit trail. It is the safety layer that sits between "tests
+pass locally" and "code lands on a shared branch" — its job is to stop unsafe pushes
+before they happen and to leave a durable record of every push that does happen.
+
+## Configuration
+
+| Setting | Default | Notes |
+|---------|---------|-------|
+| `protected_branches` | `["main", "master", "release/*", "hotfix/*"]` | Branches requiring explicit confirmation before push |
+| `push_gates` | default: `["lint", "test"]`; optional: `["ac-coverage", "type-check", "security-scan"]` | Quality gates run before pushing |
+| `push_gates.test_scope` | `"full"` (choices: `"full"`, `"changed"`) | `"changed"` runs only tests affected by the diff via the project's test impact analysis tooling (e.g. `vitest --changed`), if configured. This is a fast local pre-check only — it does not replace the project's CI/full-suite run, which remains the authoritative gate |
+| `receipt.output` | `"console"` (choices: `console`, `file`, `both`) | Where the push receipt is written |
+| `receipt.file_path` | `~/.uds/push-history.jsonl` | Append-only JSON-lines history when `file` output is enabled |
+| `auto_pr` | `true` | Prompt to create a PR after pushing to a non-protected branch |
+| `repo_mode` | `"team"` (choices: `team`, `single-owner`) | `single-owner` skips PR prompts and reduces collaboration guardrails |
+
+## Rules
+
+| Rule | Trigger | Instruction | Priority |
+|------|---------|--------------|----------|
+| `detect-protected-branch` | Executing `/push` | Detect the target branch. If it matches any `protected_branches` pattern: display a warning with the branch name, show what commits will be pushed, require explicit user confirmation, and abort without pushing if not confirmed | required |
+| `force-push-guardrail` | Push with `--force` detected | Calculate commits that will be overwritten on the remote, show their count and authors, require the user to type a confirmation string (e.g. "yes, force push"), and record `force_push: true` in the receipt | required |
+| `pre-push-gates` | Before executing `git push` | Run all configured `push_gates` in sequence (lint, test, and any optional gates enabled); if any gate fails, abort the push, show which gate failed, and suggest a fix. The `test` gate respects `push_gates.test_scope`: `"full"` (default) runs the complete suite; `"changed"` runs only the diff-affected subset via the project's test impact tooling and does **not** count as a substitute for the project's own CI/full-suite run. With `--skip-gates`, push without gates and record `gates_skipped: true` | required |
+| `push-receipt` | After a successful push | Output a structured push receipt (see schema below); if `receipt.output` includes `file`, append it as a JSON line to `~/.uds/push-history.jsonl` | required |
+| `pr-integration` | After a successful push to a non-protected branch | If `auto_pr` is true AND `repo_mode` is `team`: check whether an open PR exists for this branch; if not, prompt the user to run `pr-automation-assistant`. Skip entirely if `auto_pr` is false or `repo_mode` is `single-owner` | suggested |
+| `single-owner-mode` | `repo_mode: single-owner` is configured | Skip all collaboration-specific steps: no PR prompts, reduced force-push warnings (still warn, but no confirmation text required). Protected-branch detection remains active regardless of `repo_mode` | recommended |
+
+## Push Receipt Schema
+
+Every successful push MUST produce a receipt with the following fields:
+
+| Field | Type | Description |
+|-------|------|--------------|
+| `branch` | string | Target branch name |
+| `commit_sha` | string | HEAD commit SHA (short) |
+| `gates_passed` | string[] | List of gates that ran and passed |
+| `gates_skipped` | boolean | Whether `--skip-gates` was used |
+| `force_push` | boolean | Whether this was a force push |
+| `timestamp` | ISO 8601 string | Push time |
+| `target_remote` | string | Remote the push was sent to |
+
+## Anti-Patterns
+
+- **Silent force-push** — overwriting remote history without showing the user which
+  commits/authors will be lost.
+- **Skipping gates without a trace** — running with `--skip-gates` but not recording
+  `gates_skipped: true`, which makes the receipt misleading.
+- **PR-prompting in single-owner repos** — nagging a single-owner repository to open a
+  PR against itself; `repo_mode: single-owner` exists precisely to suppress this.
+- **Protected-branch bypass** — treating `single-owner-mode` as a reason to also skip
+  protected-branch confirmation; the two are independent. Protected-branch detection
+  always stays active.
+
+## Related Standards
+
+- **`git-workflow`** — branching strategy this standard's protected-branch list assumes
+- **`checkin-standards`** — pre-commit quality gates that `push_gates` extends to the
+  pre-push moment
+- **`pr-automation-assistant`** (skill) — invoked by the `pr-integration` rule
+- **`audit-trail`** — the push receipt is a lightweight, project-local analogue of a
+  compliance-grade audit record
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-04-23 | Initial — protected-branch detection, force-push guardrail, pre-push gates, push receipt, PR integration, single-owner mode (XSPEC-081) |
+| v1.1.0 | 2026-07-09 | Add `push_gates.test_scope` (`full`/`changed`) — layered test gate exception so `test` can run a diff-affected subset locally without downgrading the project's authoritative full-suite gate (XSPEC-326) |

package/bundled/core/refactoring-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/refactoring-standards.md)
 
-**Version**: 2.1.0
-**Last Updated**: 2026-01-29
+**Version**: 2.2.0
+**Last Updated**: 2026-07-01
 **Applicability**: All software projects undertaking code improvement initiatives
 **Scope**: partial
 **Industry Standards**: ISO/IEC 25010 Maintainability
@@ -98,9 +98,12 @@ This standard defines comprehensive guidelines for code refactoring, covering ev
 |--------|--------|------|
 | **Cyclomatic Complexity** | < 10 per function | Static analysis |
 | **Cognitive Complexity** | Lower is better | SonarQube |
-| **Code Duplication** | < 3% | Static analysis |
+| **Code Duplication (textual)** | < 3% | Static analysis |
+| **Semantic Duplication** | 0 unmanaged domain facts | Golden / architecture test (see below) |
 | **Test Coverage** | ≥ 80% | Coverage tools |
 
+> **Textual vs. semantic duplication**: The `Code Duplication` metric only detects *textual* duplication (near-identical token sequences). It cannot detect *semantic* duplication — the same domain fact re-implemented in several places, or a derived aggregate persisted without an enforced binding to its source. Copies that are not byte-for-byte identical (paraphrased logic, a formula that is right in one place and wrong in another) pass static analysis while still drifting apart. Semantic duplication must be governed by golden tests and architecture tests (see [Semantic Duplication & Copy-Drift](#semantic-duplication--copy-drift)), not by the static-analysis threshold above.
+
 ### ISO/IEC 25010 Maintainability Goals
 
 | Sub-characteristic | Indicator | Goal |
@@ -113,6 +116,41 @@ This standard defines comprehensive guidelines for code refactoring, covering ev
 
 ---
 
+## Semantic Duplication & Copy-Drift
+
+Textual-duplication metrics catch copy-paste, but they miss the more dangerous case: the **same domain fact implemented in more than one place**. When those implementations are not byte-identical — a paraphrased classification, a formula that is correct in one call site and subtly wrong in another, a total that is stored separately from the rows it summarizes — they pass static analysis and then **drift apart independently**, producing bugs that look unrelated but share a single root cause.
+
+### Anti-pattern: Copy-Drift
+
+Copy-Drift occurs when either:
+
+- A single domain fact (a classification, a rule, a calculation) is **re-implemented at multiple call sites** instead of being computed by one shared unit; or
+- A **derived value is persisted** (a stored aggregate, counter, or denormalized field) **without an enforced relationship to its source**, so each write path can update it independently.
+
+Because the copies are not literally identical, textual-duplication tooling reports nothing. The divergence surfaces later as inconsistency: a list view disagreeing with a detail view, a stored counter double-counting because one update path's decrement branch was commented out, or the same formula giving different answers in different modules.
+
+### Pattern: Single Source of Truth / Derive-Don't-Duplicate
+
+- **One unit per fact.** Extract each domain fact into a **single** classifier / calculator / resolver. Every call site calls it — no re-implementations, no paraphrases.
+- **Derive, don't store.** Prefer computing the value on read over persisting a second copy. A value that is always derived cannot drift.
+- **If an aggregate must be stored**, treat it as a **projection of its detail rows**, and recompute it at a **single choke point** — for example a `SaveChanges` interceptor, or one shared `recompute()` function — so that *every* write path (including async jobs and failure write-backs) goes through the same recomputation and stays consistent. **Never** let an individual path apply an incremental `col = col + delta` adjustment to a stored aggregate; incremental adjustments are exactly how decrement/rollback branches get skipped and counters diverge.
+- **Lock it with tests.** Use a **golden test** to pin the single source of truth, and add an **architecture test** that fails if the rule is redefined anywhere else, so a future copy is rejected at CI rather than discovered in production.
+
+### Migration Corollary — Intentional-Divergence Registry
+
+When a new system **intentionally** diverges from legacy behavior, record it — otherwise a later "fix" will silently revert it. A common case during a port: a legacy *function* returns X, but the legacy *pipeline* downstream reconciles it to Y; the port folds that reconciliation into the single unit so the function now returns Y directly.
+
+- Register each intentional divergence in an **intentional-divergence registry** (legacy behavior, new behavior, rationale, owning fact).
+- Pin the new behavior with a **golden test** so a future "correction" back to legacy fails the build.
+- Feed the registry into any **differential test** against legacy so the divergence is treated as *expected*, not flagged as a regression.
+
+### Note for Adopters
+
+- Per-function legacy-vs-new diffing produces **candidates, not verdicts**. Every candidate must be adjudicated against the **entire** legacy pipeline (not just the one function) before it can be called a bug — the legacy pipeline may already reconcile the apparent difference downstream.
+- Extract legacy function bodies **programmatically / token-based** (not by hand) so you do not reintroduce transcription errors while investigating transcription errors.
+
+---
+
 ## PR Size Guidelines
 
 | Size | Lines Changed | Review Time | Recommendation |
@@ -157,6 +195,8 @@ This standard defines comprehensive guidelines for code refactoring, covering ev
 ## Related Standards
 
 - [Test-Driven Development](test-driven-development.md) - TDD cycle including refactoring phase
+- [Testing Standards](testing-standards.md) - Golden tests and architecture tests for locking a single source of truth
+- [Test Governance](test-governance.md) - Governing semantic-duplication and intentional-divergence checks in CI
 - [Code Review Checklist](code-review-checklist.md) - Refactoring PR review guidelines
 - [Commit Message Guide](commit-message-guide.md) - `refactor` commit type
 - [Code Check-in Standards](checkin-standards.md) - Pre-commit requirements
@@ -167,6 +207,7 @@ This standard defines comprehensive guidelines for code refactoring, covering ev
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 2.2.0 | 2026-07-01 | Added Semantic Duplication & Copy-Drift (issue #142): Copy-Drift anti-pattern, Single Source of Truth / Derive-Don't-Duplicate pattern, Intentional-Divergence Registry migration corollary; split duplication metric into textual vs. semantic |
 | 2.1.0 | 2026-01-29 | Refactored: Split into Rules + Guide, moved detailed patterns to guide |
 | 2.0.0 | 2026-01-21 | Major restructure: Added tactical strategies, Anti-Corruption Layer |
 | 1.0.0 | 2026-01-12 | Initial refactoring standards definition |

package/bundled/core/replay-test.md

@@ -83,7 +83,7 @@ describe("Guardian replay fixtures", () => {
 
 - [Adversarial Test Standards](adversarial-test.md) — red-team corpus
 - [Verification Evidence Standards](verification-evidence.md) — AC traceability
-- [Testing Standards](testing.md) — overall test pyramid
+- [Testing Standards](testing-standards.md) — overall test pyramid
 
 
 **Scope**: universal

package/bundled/core/requirement-engineering.md

@@ -1,7 +1,7 @@
 # Requirement Engineering Standards
 
-**Version**: 1.0.0
-**Last Updated**: 2026-01-28
+**Version**: 1.1.0
+**Last Updated**: 2026-07-10
 **Applicability**: All software projects
 **Scope**: universal
 **Industry Standards**: IEEE 830-1998, IEEE 29148-2018, SWEBOK v4.0

package/bundled/core/resource-cost-boundary.md

@@ -0,0 +1,180 @@
+# Resource / Cost Boundary Declaration Standards
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-06-17
+> **AI-optimized version**: `ai/standards/resource-cost-boundary.ai.yaml`
+> **Spec**: XSPEC-277 (cross-project/specs/XSPEC-277-resource-cost-boundary-standard.md)
+
+**Scope**: universal
+
+## Overview
+
+The resource consumption of an agentic / LLM execution unit (a pipeline run, an agent, a
+role) is **often implicit**: token usage, loop/iteration count, retry count, per-run cost
+ceiling, wall-clock, call rate. When those bounds are not **explicitly declared and
+enforced**, runaway loops and token burn are a known LLM-native failure mode — **cost burn**.
+
+This standard makes the **resource/cost boundary a first-class, machine-readable, fail-closed
+declaration**. Any LLM execution unit MUST declare its resource budget; a breach at runtime
+MUST fail-closed per the declared behaviour. It is the **cost dimension** of boundary
+materialization (XSPEC-276): the one dimension for which UDS has no existing standard, and
+which is concrete enough to be AI-executable — so it is split out as a narrow standard rather
+than bundled into the broader (and overlapping) boundary framework.
+
+> **Scope.** This standard defines the *declaration mechanism* (a budget taxonomy, a
+> machine-readable `resource_budget:` block, a fail-closed gate). The **budget values
+> belong to the adopter/customer** — they are a project decision. It standardizes *that*
+> bounds are declared and enforced, not *which* numbers. Enforcement-engine wiring (e.g. the
+> VibeOps proactive cost governance executor) is a downstream adoption concern; this standard
+> is the "declare what bounds" half, XSPEC-285 is the "enforce/govern" half.
+
+## Why a Standard (not a per-unit setting)
+
+VibeOps already has cost mechanisms, but **scattered and unstandardized** — each is a point
+mechanism with no single standard saying "every LLM execution unit MUST declare its resource
+boundary, and a breach MUST fail-closed." A new unit (a new agent/role) easily misses one
+budget → unbounded. This standard converges those point mechanisms onto one declaration.
+
+| Existing mechanism (becomes a reference implementation) | Budget kind |
+|---|---|
+| orchestrator quality profile `max_retries` / `max_retry_budget_usd` (per-task fix-loop) | retry / cost_usd |
+| BudgetGuard / PoC abort `max_cost_per_session_usd` / `min_cache_hit_ratio` (XSPEC-191) | cost_usd / rate |
+| Pareto Evolution Gate token-cost dimension (DEC-024) | token / cost_usd |
+| agent-loop `maxToolRounds` / `maxTotalTokens` | iteration / token |
+
+## Resource Budget Taxonomy
+
+| Kind | Bound | Typical breach |
+|------|-------|----------------|
+| `token` | input / output / total token ceiling | prompt/output explosion |
+| `iteration` | loop / iteration / tool-round upper bound | runaway loop |
+| `retry` | retry upper bound | unbounded re-attempt |
+| `cost_usd` | per-call / per-run / per-session cost ceiling | silent budget burn |
+| `wallclock` | timeout | hung run |
+| `rate` | call frequency | call storm |
+
+## Requirements
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | Resource budget taxonomy — declare bounds from a standard set of kinds | MUST |
+| REQ-002 | Machine-readable `resource_budget:` declaration (kind + limit + breach behaviour) | MUST |
+| REQ-003 | Fail-closed enforcement gate (undeclared → warn/block; runtime breach → abort) | MUST |
+| REQ-004 | Existing mechanisms converge as reference implementations (no re-invention) | SHOULD |
+| REQ-005 | Budget value sovereignty — mechanism standard, values owned by the adopter | SHOULD |
+
+### REQ-001 — Resource Budget Taxonomy
+
+Every LLM execution unit's resource bounds MUST be expressible from a standard set of kinds:
+`token` (input/output/total), `iteration` (loop/iteration/tool-round cap), `retry` (retry
+cap), `cost_usd` (per-call / per-run / per-session ceiling), `wallclock` (timeout), and
+`rate` (call frequency). A unit need not declare every kind, but the kinds it relies on for
+safety MUST be declared (an unbounded relied-upon kind is a violation).
+
+### REQ-002 — Machine-Readable Declaration
+
+A `resource_budget:` block MUST be declarable (embedded in a plan / agent / role config),
+with each entry carrying a **kind + limit value + breach behaviour** (`warn` / `abort`).
+The declaration is a first-class artifact the generator/runtime can read — not a scattered
+setting or an after-the-fact review note.
+
+```yaml
+resource_budget:
+  - kind: cost_usd        # per-run cost ceiling
+    scope: per_run
+    limit: 3.00
+    on_breach: abort
+  - kind: iteration       # tool-round / loop cap
+    limit: 60
+    on_breach: abort
+  - kind: retry
+    limit: 3
+    on_breach: warn
+  - kind: token
+    scope: total
+    limit: 400000
+    on_breach: abort
+```
+
+### REQ-003 — Fail-Closed Enforcement Gate
+
+A quality gate `check-resource-budget` MUST: (a) flag any LLM execution unit that does **not
+declare** a budget — `warn` by default, `block` in strict mode; and (b) on a **runtime
+breach**, fail-closed per the declared `on_breach` (`abort` halts the unit, `warn` records
+and continues). This mirrors the fail-closed posture of `capability-declaration`
+(XSPEC-037) and the governance-gate family — never a silent unbounded pass.
+
+### REQ-004 — Converge Existing Mechanisms
+
+Existing point mechanisms (orchestrator `max_retries` / `max_retry_budget_usd`, XSPEC-191
+BudgetGuard, DEC-024 Pareto token gate, XSPEC-270 right-sizing router) SHOULD be **mapped to
+this standard as reference implementations** — unified, not re-implemented. New units inherit
+the declaration habit rather than re-inventing a budget knob.
+
+### REQ-005 — Budget Value Sovereignty
+
+The declaration *mechanism* is standardized; the *budget values* (the actual ceilings) are
+owned by the adopter/customer (a project/economics decision). The standard mandates *that*
+bounds are declared and enforced, not *which* numbers.
+
+## Principles
+
+| ID | Principle |
+|----|-----------|
+| P-1 | Bounds are Explicit — resource budgets are declared, not implicit in someone's head |
+| P-2 | Machine-Readable — a generator/runtime can read the `resource_budget:` block first-class |
+| P-3 | Fail-Closed — undeclared relied-upon bound, or a runtime breach, blocks/aborts; never silent |
+| P-4 | No Re-Invention — existing point mechanisms converge as reference implementations |
+| P-5 | Value Sovereignty — mechanism standard, ceiling values owned by the adopter |
+
+## Gate Timing
+
+```
+plan / agent / role config (resource_budget: block)
+        │
+        ├─→ [check-resource-budget — declaration check]  ← REQ-003(a), pre-run
+        │         undeclared relied-upon bound ──→ warn (strict: block)
+        ↓
+   run (token / iteration / retry / cost / wallclock / rate metered)
+        │
+        └─→ runtime breach ──→ fail-closed per on_breach  ← REQ-003(b) (abort / warn)
+                                        │
+                                  record breach for audit / cost-governance executor (XSPEC-285)
+```
+
+## Boundaries with Adjacent Standards (admission condition 3)
+
+This standard collects **only the cost/resource dimension**, to avoid the overlap that kept
+the broader boundary framework (XSPEC-276) out of the standard library.
+
+| Adjacent standard | Its angle | Why distinct (<30% overlap) |
+|---|---|---|
+| `performance-standards` | latency / throughput *targets* | targets, not a fail-closed cost ceiling |
+| `model-selection` | choose a model *tier* | tier selection, not budget enforcement |
+| `capability-declaration` (XSPEC-037) | explicit capability + fail-closed | capability surface, not resource budget |
+
+## Integration with Existing Standards
+
+- **`performance-standards`** — performance sets latency/throughput targets; this standard
+  sets fail-closed resource ceilings. Adjacent, complementary, distinct.
+- **`model-selection`** — right-sizing picks a model tier; a `cost_usd` breach can *drive* a
+  downgrade (XSPEC-270 router), but the budget declaration is this standard's concern.
+- **`test-governance`** — `check-resource-budget` is a governed gate; budget declarations are
+  governed policy.
+- **`verification-evidence`** — a breach/no-breach run report is a kind of verification
+  evidence (budgets honoured + trace).
+
+## Related Specs
+
+- XSPEC-277 — Resource / Cost Boundary Declaration complete spec (this standard's source)
+- XSPEC-276 — LLM-native boundary materialization (parent lens; cost is the split-out dimension)
+- XSPEC-285 — VibeOps proactive cost governance (the enforcement/executor face of this standard)
+- XSPEC-191 — Unit-economics PoC / BudgetGuard (reference implementation)
+- XSPEC-270 — Model right-sizing router (cost-driven downgrade)
+- XSPEC-037 — Capability declaration (fail-closed posture this standard mirrors)
+- DEC-024 — Pareto evolution token-cost gate (reference implementation)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-06-17 | Initial — REQ-001~005: resource budget taxonomy, machine-readable `resource_budget:` declaration, fail-closed `check-resource-budget` gate, convergence of existing mechanisms as reference implementations, budget value sovereignty (XSPEC-277) |

package/bundled/core/reverse-engineering-standards.md

@@ -1,7 +1,7 @@
 # Reverse Engineering Standards | 反向工程標準
 
-**Version**: 1.0.0
-**Last Updated**: 2026-01-19
+**Version**: 1.2.0
+**Last Updated**: 2026-06-27
 **Applicability**: All projects requiring code-to-specification transformation
 **Scope**: uds-specific
 **Industry Standards**: IEEE 830-1998, SWEBOK v4.0 Chapter 9
@@ -51,10 +51,52 @@ This standard defines the principles, workflows, and best practices for reverse
 |-------|-------------|--------|-----------------|
 | **Code Scanning** | Analyze code structure, APIs, data models | Technical inventory | [Confirmed] |
 | **Test Analysis** | Parse existing tests for acceptance criteria | Draft acceptance criteria | [Confirmed]/[Inferred] |
+| **Implicit Rule Scan** | Scan non-HTTP persistence write paths for undocumented rules | Implicit-rule inventory + three-question answers | [Confirmed]/[Inferred]/[Unknown] |
 | **Gap Identification** | List unknowns requiring human input | Gap analysis document | [Unknown] items |
 | **Spec Generation** | Generate draft specification | Draft SPEC-XXX.md | Mixed certainty |
 | **Human Review** | Stakeholder validation and gap filling | Validated specification | [Confirmed] |
 
+> **Note (v1.2.0)**: An **Implicit Rule Scan** stage is inserted after Code Scanning / Test Analysis and before Gap Identification — see [Implicit Rule Scan (Non-HTTP Persistence Rules)](#implicit-rule-scan-non-http-persistence-rules) below. Standard code scanning extracts HTTP entry points and data models, but persistent field values are frequently written by **non-HTTP paths** (cron, queue, computed columns, triggers, ORM hooks) whose business rules are never documented — the highest-frequency source of missed logic in a cross-language rewrite or cross-DB migration.
+
+---
+
+## Implicit Rule Scan (Non-HTTP Persistence Rules)
+
+> **Workflow position**: after Code Scanning / Test Analysis, before Gap Identification.
+
+Code scanning extracts what is reachable through HTTP — routes, controllers, request handlers. But a persisted field's value is often decided **off the request path**: a nightly cron flips a status, a queue retry re-stamps a timestamp, a database trigger derives a total, an ORM lifecycle hook zeroes a counter. Those rules are rarely written down, so a rewrite that only mirrors the HTTP surface silently drops them. This stage mechanically derives every non-HTTP write path and locks each implicit rule as a verifiable artifact.
+
+### Derive (mechanical list source)
+
+Scan the legacy system for every **non-HTTP persistence write path** across four categories:
+
+1. **Scheduled** — crontab entries, scheduler config, `@Scheduled`-style annotations, batch jobs
+2. **Queue** — queue consumers, job handlers, background workers, message listeners
+3. **DB-layer** — triggers, computed/generated columns, `DEFAULT` expressions, check constraints
+4. **ORM lifecycle** — `beforeSave`/`afterSave`/observer/model-event hooks, middleware that mutates persistent state
+
+### Oracle (detect) — three questions per field
+
+For each persistent field written by a non-HTTP path, answer and lock **three questions**:
+
+| Question | What to capture |
+|----------|-----------------|
+| **When is it SET?** | The condition/trigger that first assigns the value |
+| **When is it OVERWRITTEN?** | Every later write — **including asynchronous overwrites** (links back to post-cutover aggregate reconciliation) |
+| **When is it RESET / zeroed?** | The conditions that clear or default the value back |
+
+- Extend the **Devil's Advocate** challenge from the HTTP layer to **cover non-HTTP paths**: apply the same five adversarial categories (boundary, ordering, concurrency, failure/retry, null/default) to cron conditions, queue retries, computed columns, and trigger logic.
+- Tag every extracted rule with a certainty level: `[Confirmed]` (with a `file:line` citation) / `[Inferred]` / `[Unknown]`. Every `[Unknown]` is handed to Gap Identification for a human — it is never guessed.
+- **Output**: lock each implicit rule as a **behavior-snapshot scenario** or a **reconciliation invariant** (e.g. `SUM(cost) GROUP BY status` must hold across cutover), so the rule becomes a re-runnable oracle rather than prose.
+
+### Gate timing
+
+Pre-flight (planning). Any non-HTTP write field whose three questions are unanswered is marked `not_implemented` and **blocks cutover** — an undeclared implicit rule is treated as a known omission risk, not an acceptable gap.
+
+### PHP-specific note: loose comparison / type juggling
+
+When scanning PHP write paths, additionally flag **loose-comparison / type-juggling** dependencies: `==` comparisons, the truthy/falsy behavior of `"0"` / `""` / `null` / `0`, and automatic string-to-number coercion. These have no direct equivalent under a strongly-typed target (e.g. C#/.NET), so the implicit rule they encode is a high-frequency source of silently-dropped logic during a cross-language rewrite. Mark each such site `[Confirmed]` with `file:line` and lock the intended semantics as an explicit rule.
+
 ---
 
 ## Core Principles
@@ -300,6 +342,26 @@ Use reverse-engineered specifications to identify test coverage gaps:
 
 ---
 
+## Failure Handling & Escalation
+
+Reverse engineering infers intent from existing code; some inputs cannot be
+analyzed safely. This section defines the failure → escalate → re-verify path so
+a low-confidence or unparseable input never produces a spec that looks
+authoritative.
+
+| Condition | Trigger | Action | Re-verify |
+|-----------|---------|--------|-----------|
+| **Parse failure** | Source cannot be parsed (unsupported language, broken syntax tree) | Mark the unit `[Unknown]` and report the language/file; escalate to a human domain expert. Emit no inferred behavior for it. | Source parses after tooling/fix |
+| **High unknown ratio** | `[Unknown]` items exceed the confidence threshold (default > 50% of behaviors) | Halt spec finalization; require a subject-matter-expert interview to fill `[Unknown]` items first. Do not ship a majority-guessed spec. | Unknown ratio below threshold |
+| **Contradicted inference** | Code contradicts a previously inferred behavior | Downgrade the item to `[Assumption]` and escalate to the code owner; never record a contradicted inference as `[Confirmed]`. | Owner confirms or corrects |
+| **Test-analysis failure** | Existing tests cannot be run/parsed for behavior extraction | Fall back to static analysis only; mark affected behaviors `[Inferred]` (lower certainty), never `[Confirmed]`. | — |
+
+**Rule RE-FAIL-001 (Required)**: A parse failure or an above-threshold
+`[Unknown]` ratio MUST block spec finalization and escalate to a human — never
+present a sub-threshold-confidence spec as authoritative.
+
+---
+
 ## Anti-Patterns to Avoid
 
 ### Code Analysis Anti-Patterns
@@ -383,6 +445,8 @@ Use reverse-engineered specifications to identify test coverage gaps:
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.2.0 | 2026-06-27 | Added: Implicit Rule Scan stage (non-HTTP persistence write-path extraction) — 4 derive categories + three-question oracle + non-HTTP Devil's Advocate + PHP type-juggling note + certainty/`file:line` (XSPEC-284 R4/AC-8) |
+| 1.1.0 | 2026-06-18 | Added: Failure Handling & Escalation section — parse failure / high-unknown-ratio / contradicted-inference escalation + rule RE-FAIL-001 (XSPEC-292 T7) |
 | 1.0.0 | 2026-01-19 | Initial release |
 
 ---