universal-dev-standards 5.17.0 → 6.1.0

package/bundled/core/tech-debt-standards.md

@@ -54,7 +54,7 @@ Every technical debt item must be recorded in a registry with the following 11 f
 | 1 | **ID** | Unique identifier using `TD-NNN` format | TD-001 |
 | 2 | **Title** | Short descriptive title | "Monolithic auth module needs decomposition" |
 | 3 | **Type** | One of the 6 debt types above | Design |
-| 4 | **Source** | How the debt was introduced (deliberate/inadvertent) | Deliberate |
+| 4 | **Source** | How the debt was introduced (deliberate / inadvertent / incident-postmortem — see [postmortem-standards](postmortem-standards.md) action-item hand-off) | Deliberate (or `postmortem PM-042`) |
 | 5 | **Impact** | Business and technical impact description | "Slows feature development by ~2 days per sprint" |
 | 6 | **Estimated Cost** | Effort to resolve (story points or person-days) | 8 story points |
 | 7 | **Interest** | Ongoing cost of not resolving (see Interest Types) | 1 day/sprint additional debugging |

package/bundled/core/test-data-standards.md

@@ -296,8 +296,8 @@ ID?      → Hash / UUID / sequential
 
 - [Testing Standards](testing-standards.md) — Test levels, coverage, and quality requirements
 - [Security Standards](security-standards.md) — Data protection and PII handling
-- [Unit Testing Standards](unit-testing-standards.md) — Unit test patterns and best practices
-- [Integration Testing Standards](integration-testing-standards.md) — Integration test strategies
+- [Unit Testing Standards](../options/testing/unit-testing.md) — Unit test patterns and best practices
+- [Integration Testing Standards](../options/testing/integration-testing.md) — Integration test strategies
 
 ---
 

package/bundled/core/user-journey-testing.md

@@ -0,0 +1,102 @@
+# User Journey Testing Standard
+
+> **Language**: English | 繁體中文
+
+**Applicability**: Projects with multi-step, stateful user flows that span more than one user story
+**Scope**: universal
+
+---
+
+## Overview
+
+The User Journey Testing Standard defines the **TESTPLAN** format, which makes connected, sequential user journeys a first-class testing artifact. Where acceptance-criteria tests verify a single story in isolation, journey tests verify what AC tests cannot: **cross-story state continuity** — the chain of state that one step leaves behind for the next.
+
+A journey is described once in a human-readable `TESTPLAN-NNN.md` and mapped one-to-one onto automated E2E tests through shared `T-NNN` identifiers, so the plan and the executable suite never drift apart.
+
+## References
+
+| Standard/Source | Content |
+|----------------|---------|
+| journey-test-assistant (skill) | Generates TESTPLAN and journey E2E skeletons |
+| flow-based-testing | Flow archetypes that journeys instantiate |
+| e2e-testing (option) | End-to-end execution layer journeys map onto |
+
+---
+
+## Guidelines
+
+- Every project MUST have at least one `TESTPLAN-NNN.md` documenting the main user journey.
+- TESTPLAN steps MUST be sequential and stateful — each step depends on prior state.
+- Every TESTPLAN MUST define personas before test steps.
+- TESTPLAN and automated E2E tests MUST use the same `T-NNN` identifiers.
+- Journey E2E tests MUST skip gracefully when the environment is unavailable.
+- Journey tests cover what AC tests cannot: cross-story state continuity.
+
+---
+
+## TESTPLAN Format
+
+- **File naming**: `TESTPLAN-NNN-<project-slug>.md`
+- **Location**: `test-plans/`
+
+### Required Sections
+
+| Section | Description | Format |
+|---------|-------------|--------|
+| **Personas** | Define all test actors with their role and permissions | `\| Actor \| Role \| Key Permissions \|` |
+| **Environment** | List environment prerequisites and verification commands | — |
+| **Test Groups** | `T-NNN` numbered test groups with a sequential dependency chain | — |
+| **Execution Order** | Dependency diagram showing `T-NNN → T-NNN` relationships | — |
+
+### Step Markers
+
+| Marker | Meaning |
+|--------|---------|
+| `[UI]` | Browser-based action, verify visually |
+| `[API]` | `curl` / API client verification |
+| `[CHECK]` | Expected result to confirm |
+| `[SKIP-if]` | Conditional skip with reason |
+| `★` | High-risk step requiring confirmation |
+
+### Step Format
+
+Each step declares:
+
+- **step_id** — `T-NNN-M` (group-step format)
+- **operation** — what to do, annotated with a `[MARKER]`
+- **expected_result** — what should happen
+- **precondition** — state from a previous `T-NNN` that must be satisfied
+- **depends_on** — comma-separated `T-NNN` identifiers
+
+---
+
+## Automation Mapping
+
+- **Principle**: every `T-NNN` group maps to a `describe()` block; every step maps to an `it()`.
+- **File pattern**: `*.journey.spec.ts` or `*.journey.e2e.test.ts`.
+- **Shared state**: journey tests MUST use shared `let` variables across `it()` blocks so each step builds on previous results.
+- **Skip strategy**: guard with `describe.skipIf(!BASE_URL)` for environment-dependent tests.
+
+---
+
+## Journey Categories
+
+| ID | Description | Required For |
+|----|-------------|--------------|
+| `platform-admin-journey` | Platform admin setup: login → org → project → pipeline | enterprise, saas |
+| `member-journey` | Org member: join → project access → pipeline view | enterprise, saas |
+| `dev-journey` | Developer: new project → spec → pipeline → artifact | all |
+
+---
+
+## Rules
+
+| Rule | Trigger | Instruction | Priority |
+|------|---------|-------------|----------|
+| `testplan-required` | Creating a new project | Generate `TESTPLAN-001.md` with personas, environment, and main journey steps before writing code | required |
+| `journey-before-code` | Starting project implementation | Define the user journey test plan first; journey tests act as living acceptance criteria | recommended |
+| `sequential-state` | Writing journey E2E tests | Use shared state variables (`let token, orgSlug, projectSlug`) so each step builds on previous results | required |
+| `graceful-skip` | Writing journey E2E tests | Guard with `describe.skipIf(!process.env.JOURNEY_BASE_URL)` so tests are skipped in unit CI | required |
+| `t-nnn-alignment` | Writing any E2E test | Reference `T-NNN` identifiers from TESTPLAN in test descriptions for traceability | recommended |
+| `persona-first` | Writing TESTPLAN | Define all user personas before writing any test steps | required |
+| `dependency-chain` | Writing TESTPLAN | Each test group must declare its `depends_on` list so execution order is explicit | required |

package/bundled/core/user-story-mapping.md

@@ -0,0 +1,96 @@
+# User Story Mapping Standards
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-06-17
+> **AI-optimized version**: `ai/standards/user-story-mapping.ai.yaml`
+> **Spec**: XSPEC-069 (cross-project/specs/XSPEC-069-uds-product-layer-pack.md)
+
+**Scope**: universal
+
+## Overview
+
+This standard defines how teams construct and use **story maps** to plan product
+releases. It covers the three-layer story-map structure (Backbone activities,
+Walking Skeleton sub-tasks, Detail Stories), the MVP horizontal-slice rule,
+INVEST compliance per story, and Given/When/Then acceptance criteria tied to
+measurable product metrics. It prevents incomplete MVPs and ensures every story is
+testable and traceable.
+
+It is part of the **product-layer pack** (XSPEC-069), sitting between
+`prd-standards` (upstream intent) and `requirement-engineering` (downstream INVEST
+stories), with acceptance criteria tied to `product-metrics-standards`.
+
+> **Scope.** This standard defines the *story-map structure and MVP-slicing
+> discipline*. Concrete planning tooling (Miro/Jira) is an adoption choice.
+
+## Requirements
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | Story-map three layers (backbone, walking skeleton, detail stories) | MUST |
+| REQ-002 | MVP horizontal-slice rule (no vertical-slice MVP) | MUST |
+| REQ-003 | Story INVEST compliance | MUST |
+| REQ-004 | Acceptance-criteria format (Given/When/Then, metric-tied) | MUST |
+
+### REQ-001 — Story Map Three Layers
+
+Every story map MUST be structured in three horizontal layers: (1) **Backbone**
+(top row) — user activities at the highest abstraction representing the complete
+end-to-end journey, each a verb phrase from the user's perspective; the backbone
+must represent the full journey, not only implemented features. (2) **Walking
+Skeleton** (middle row) — the minimum sub-tasks to make each backbone activity
+functional, organized vertically under each backbone item. (3) **Detail Stories**
+(bottom rows) — specific stories for variations, enhancements, and edge cases,
+prioritized vertically within each column (higher = higher priority).
+
+### REQ-002 — MVP Horizontal Slice Rule
+
+The MVP release boundary MUST be a **horizontal slice** across the story map,
+covering all backbone activities at the walking-skeleton level. An MVP covering
+only a subset of backbone activities (a **vertical slice** that perfects one
+activity while others are absent or non-functional) is PROHIBITED, because it
+cannot be evaluated end-to-end by users. **Exception**: single-activity products
+(e.g. a focused utility) are exempt if the full value proposition is delivered by
+that one activity; exceptions MUST be documented with rationale in the story map.
+
+### REQ-003 — Story INVEST Compliance
+
+Every story in the map MUST comply with the INVEST criteria from
+`requirement-engineering`: **I**ndependent, **N**egotiable, **V**aluable,
+**E**stimable, **S**mall (fits within one sprint at most; split if larger),
+**T**estable (objectively verifiable acceptance criteria exist). Stories that fail
+INVEST must be refined before entering a sprint; the assessment MUST be performed
+during backlog-refinement sessions.
+
+### REQ-004 — Acceptance Criteria Format
+
+Every story MUST have at least one acceptance criterion in **Given/When/Then**
+format, tied to a measurable product outcome from the `product-metrics-standards`
+hierarchy where applicable. Stories with criteria that cannot be objectively
+verified (e.g. "the page looks good") are non-compliant. Acceptance criteria MUST
+be written before development begins and MUST NOT be modified after it starts
+without PM and dev-lead sign-off (same revision policy as PRD changes).
+
+## Anti-Patterns
+
+- Vertical MVP slicing: perfecting one activity while other backbone activities are absent.
+- Stories without acceptance criteria entering development (no clear definition of done).
+- Backbone activities mapped to system components instead of actual user goals.
+- Story map used only for planning then discarded, not kept as a living tool.
+- Detail stories added directly without backbone and walking-skeleton context.
+
+## Integration with Existing Standards
+
+- **`prd-standards`** — PRD scope is realized as a story map and MVP slice.
+- **`requirement-engineering`** — stories follow the INVEST criteria defined there.
+- **`product-metrics-standards`** — acceptance criteria tie to a North Star driver.
+- **`acceptance-criteria-traceability`** — GWT criteria provide the AC traceability spine.
+
+## Related Specs
+
+- XSPEC-069 — UDS product-layer pack (this standard's source)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-06-17 | Initial — REQ-001~004: three-layer map, MVP horizontal-slice rule, INVEST compliance, GWT acceptance criteria (XSPEC-069) |

package/bundled/core/verification-evidence.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/verification-evidence.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-03-20
+**Version**: 1.2.0
+**Last Updated**: 2026-07-17
 **Applicability**: All AI-assisted development workflows
 **Scope**: universal
 **Inspired by**: [Superpowers](https://github.com/obra/superpowers) — verification-before-completion (MIT)
@@ -12,9 +12,19 @@
 
 ## Purpose
 
-Establish an "Iron Law" that no task can be claimed as complete without verification evidence. This standard prevents AI agents from hallucinating success and ensures every completion claim is backed by executable proof.
+Establish an "Iron Law" that no task can be claimed as complete without verification evidence, and ensure that the evidence itself holds up. This standard guards two distinct failures:
 
-建立「鐵律」：無驗證證據不可聲稱完成。防止 AI 代理虛構成功結果，確保每個完成聲明都有可執行的證據支持。
+1. **Claiming success without evidence** — the agent asserts what it never checked (the Iron Law).
+2. **Evidence that does not support its claim** — the agent *did* check, and the checking tool silently did not work (Evidence Validity, added in v1.2.0).
+
+The first is a form of hallucination. **The second is not** — nothing was invented; a real command produced a real output that meant something other than what it appeared to mean. Both end in the same place: a completion claim that isn't true.
+
+建立「鐵律」：無驗證證據不可聲稱完成——並確保**證據本身站得住腳**。本標準防兩種不同的失敗：
+
+1. **無證據就宣稱成功**——代理斷言它從未查過的事（Iron Law）。
+2. **證據撐不起它的主張**——代理**確實查了**，而查詢工具靜默地沒有運作（證據有效性，v1.2.0 新增）。
+
+前者是幻覺的一種，**後者不是**——沒有任何東西被捏造，是一個真實的指令產生了真實的輸出，而那個輸出的意思不是它看起來的意思。兩者殊途同歸：一個不成立的完成聲明。
 
 ---
 
@@ -25,7 +35,10 @@ Establish an "Iron Law" that no task can be claimed as complete without verifica
 | Verification Evidence | A structured record of a verification command's execution and result |
 | Iron Law | The absolute rule: no evidence = no completion claim |
 | RED-GREEN Cycle | Proving a bug fix by showing the test fails before and passes after the fix |
-| Exit Code | The numeric return value of a command (0 = success, non-zero = failure) |
+| Exit Code | The numeric return value of a command. **`0 = success` is the tool's convention, not a guarantee** — see Evidence Validity |
+| Environment Layer | Which environment the evidence was collected from (`local` / `uat` / `prd`) |
+| Evidence Validity | Whether the evidence *itself* is trustworthy — i.e. whether the verification command actually ran and actually measured what it claims |
+| Silent Tool Failure | A verification command that fails to run, or runs without measuring anything, yet produces output indistinguishable from a genuine result |
 
 ---
 
@@ -39,6 +52,18 @@ An agent saying "it's done" is not evidence. The verification must be independen
 
 代理聲稱「已完成」不是證據。驗證必須是可獨立執行且產生可觀察輸出的。
 
+### Non-Evidence Claims
+
+None of the following constitute verification evidence:
+
+| Claim | Why it isn't evidence |
+|-------|----------------------|
+| "Done." | No observable output |
+| "It should work now." | No verification was executed |
+| "I changed the code." | A modification is not a verification |
+| "The tests should pass." | A prediction is not a fact |
+| "The command returned 0." | Only if the command could have measured the claim — see Evidence Validity |
+
 ---
 
 ## Evidence Format
@@ -50,7 +75,8 @@ Every verification must produce a structured evidence record:
   "command": "pnpm test -- --filter core",
   "exit_code": 0,
   "output": "Tests: 47 passed, 0 failed\nDuration: 3.2s",
-  "timestamp": "2026-03-20T14:30:00Z"
+  "timestamp": "2026-03-20T14:30:00Z",
+  "environment_layer": "local"
 }
 ```
 
@@ -59,9 +85,44 @@ Every verification must produce a structured evidence record:
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `command` | string | Yes | The actual verification command executed |
-| `exit_code` | number | Yes | Command exit code (0 = success) |
+| `exit_code` | number | Yes | Command exit code. **Interpret via Evidence Validity — this field is a claim, not a fact** |
 | `output` | string | Yes | Command output (truncated to 2000 chars, preserving key info) |
 | `timestamp` | string | Yes | Execution time in ISO 8601 format |
+| `environment_layer` | string | Conditional | Which layer the evidence came from (`local` / `uat` / `prd`). **Required for any AC with an external service dependency** (SMS, payment, IdP); when absent, the AC's verification level is treated as local-only |
+
+---
+
+## Evidence Types
+
+| Type | Applies to | Example |
+|------|-----------|---------|
+| **Test result** | Feature work, bug fixes | `npm test` output |
+| **Type check** | Statically typed codebases | `pnpm tsc --noEmit` reporting no errors |
+| **Build success** | Compilation, packaging | `npm run build` exiting 0 |
+| **Lint clean** | Code quality | `npm run lint` reporting no errors |
+| **RED-GREEN** | Bug fixes | Failing before the fix → passing after |
+| **Health probe** | Deployed services | `curl https://<service>/health` — declare `environment_layer`; a probe against `localhost` verifies the local process, not the deployment |
+| **Manual verification** | UI changes, visual behaviour | Screenshot or screen recording |
+
+---
+
+## Environment Layers
+
+> **Iron Law (Environment)**: before acceptance, establish *which dimensions of this flow this environment layer is capable of verifying at all*.
+
+驗收前必須確認「此環境層次能驗證此流程的哪些維度」。
+
+A passing test proves nothing about a dimension the environment cannot exercise. A `local` run with a mocked payment gateway does not verify the payment integration — it verifies the mock. Evidence must therefore declare where it was collected.
+
+| Layer | Meaning |
+|-------|---------|
+| `local` | Developer machine or CI; external dependencies typically mocked or stubbed |
+| `uat` | Staging environment with real (or sandbox) external services |
+| `prd` | Production |
+
+For an AC that depends on an external service, `local`-only evidence is **insufficient**: either supply `uat`/`prd` evidence, or declare the gap explicitly. See VE-005 / VE-006.
+
+> The declaration goes in the project's **Environment Stratification Responsibility Matrix** (`docs/testing/environment-stratification-matrix.md` or the test plan) — a per-project deliverable defined by the `deployment-standards` standard, which answers "which test flows can be fully verified in which environment?". Mark the un-verifiable combinations ⚠️/❌ there rather than leaving them implied by a passing local run.
 
 ---
 
@@ -107,12 +168,63 @@ The evidence record must include both RED and GREEN phases.
 
 ---
 
+## Evidence Validity
+
+> **The evidence can lie. Verify the evidence, not just the claim.**
+
+證據本身會騙人。要驗的不只是「有沒有證據」，還有「這個證據成不成立」。
+
+The Iron Law stops an agent from claiming success **without** evidence. It does not stop the opposite failure: the agent *does* run a verification, the command *does* return, `exit_code` *is* `0` — **and the output is meaningless**, because the command never actually measured anything.
+
+This is not hallucination. Hallucination is inventing what you did not check. This is the reverse: **you checked, and the checking tool lied to you.** The `anti-hallucination` standard does not cover it — every prohibition there is a form of "don't make things up", and here nothing was made up.
+
+### The four validity rules
+
+**1. `exit_code = 0` means success only for tools that return 0 on success.**
+
+The convention is near-universal, which is exactly why it goes unquestioned. When a tool fails **by design** in the situation under test, its non-zero exit code carries no information about the artefact — read the *output* instead. The inverse holds too: a non-zero exit code does not establish that the thing under test is broken.
+
+**2. "Empty output" / "not found" / `0` is not the same as "it isn't there."**
+
+Before concluding absence, establish that the query tool *ran successfully*: it was not `command not found`, it was not denied permission, its arguments were not consumed by an intervening shell. **Verify the query tool works before trusting the query's silence.**
+
+**3. Commands that test for existence must not discard stderr.**
+
+Suppressing stderr (`2>/dev/null` and equivalents) silences precisely the channel that would have reported "this tool is broken". The failure then wears the same clothes as a true negative.
+
+**4. A pipeline's exit code does not belong to any single stage in it.**
+
+With `set -o pipefail`, `producer | grep -q pattern` inherits a non-zero from `producer` regardless of whether `grep` matched. When the decision depends on content, **capture the output first, then evaluate it** — do not let a pipeline collapse two questions into one number.
+
+### Evidence of the failure mode
+
+The following are real verification commands run by an AI agent on 2026-07-17, each of which produced a confident, wrong conclusion that was then reported as fact:
+
+| Verification command | `exit_code` | Output | Ground truth |
+|---|:---:|---|---|
+| `sudo -n find /backup/immich -type f 2>/dev/null \| wc -l` | **0** | `0` | `sudo` failed for lack of a tty, `2>/dev/null` ate the error, empty input made `wc -l` print `0`. **31 files existed.** Reported as "the backups are empty" |
+| `gpg --list-packets <valid-file.gpg>` | **≠ 0** | Well-formed packet listing | The host holds no private key **by design**; gpg always exits non-zero here. **The file was valid.** Acted on by deleting a good encrypted backup |
+| `gpg … \| grep -q "tag=1"` under `pipefail` | **≠ 0** | grep *did* match | The pipeline inherited gpg's non-zero; the match was irrelevant. **Deleted a good backup a second time** |
+| `grep -c "${VAR}/path" file` over SSH in double quotes | **0** | `0` | `${VAR}` was expanded by the *local* shell to an empty string; the remote grep searched for the wrong text |
+| `gpg --import key.asc 2>/dev/null` | — | (empty) | gpg **was not installed**; `command not found` went to the suppressed stderr |
+| `until ! ssh host 'systemctl is-active svc'; do …` | — | loop exited | **A failed SSH connection and a finished service produce the same exit code.** The "result" read afterwards was a stale value from a previous run |
+| `du -sh /data/*` as an unprivileged user | **0** | `4.0K` | Unreadable directories were reported as near-empty rather than as errors |
+| `case "$tag" in *M*)` searching for monthly snapshots | **0** | (no match) | The tag's actual value was `monthly` — no capital `M`. Nearly became "there are no monthly snapshots" |
+
+**Four of these had `exit_code = 0` and were false; two had `exit_code ≠ 0` and were true.** The field was unreliable in both directions — and in both of the non-zero cases, following VE-002 ("mark verification failed, trigger fix loop") destroyed a healthy artefact.
+
+> **Provenance**: all instances come from a single day's work by a single agent (Claude Opus 4.8), recorded in AsiaOstrich XSPEC-340. The sample is dense but narrow. It is offered as evidence rather than proof — though note that every failure above originates in the *semantics of the tools* (sudo, gpg, pipefail, POSIX exit codes), not in any property of the model, so any agent driving the same tools is exposed to the same traps.
+
+---
+
 ## Trust Rules
 
 | Rule | Description |
 |------|-------------|
 | Agent says "done" but no `verification_evidence` | Mark as **unverified** |
-| `verification_evidence` exists but `exit_code ≠ 0` | Mark as **verification failed** |
+| `verification_evidence` exists but `exit_code ≠ 0` | Mark as **verification failed** — **unless** the tool is known to exit non-zero in the state under test (Evidence Validity rule 1), in which case judge by output |
+| `exit_code = 0` but the command could not have measured the claim | Mark as **unverified** — a passing command that ran in the wrong place, or never ran at all, is not evidence |
+| Evidence asserts absence (`0`, empty, "not found") | Mark as **unverified** until the query tool is shown to have executed successfully |
 | Multiple verification steps | **All** steps must pass |
 | Agent provides evidence for wrong command | Mark as **unverified** |
 
@@ -123,9 +235,15 @@ The evidence record must include both RED and GREEN phases.
 | ID | Trigger | Action | Priority |
 |----|---------|--------|----------|
 | VE-001 | Agent reports success without verification_evidence | Downgrade to `done_with_concerns` | Critical |
-| VE-002 | `exit_code ≠ 0` in evidence | Mark verification failed, trigger fix loop | High |
+| VE-002 | `exit_code ≠ 0` in evidence | Mark verification failed, trigger fix loop — **after** confirming the tool returns 0 on success in this state (see VE-007) | High |
 | VE-003 | Bug fix without RED-GREEN cycle | Request both RED and GREEN evidence | High |
 | VE-004 | Output exceeds 2000 chars | Truncate but preserve error messages and summary lines | Medium |
+| VE-005 | AC has an external service dependency (SMS, payment, IdP) | Evidence must declare `environment_layer`; local-only evidence is insufficient | Required |
+| VE-006 | AC with external dependency marked done, no `environment_layer` | Downgrade to `done_with_concerns`; require the layer declaration or a ⚠️/❌ entry in the environment-stratification-matrix | High |
+| VE-007 | The verification tool exits non-zero in the state under test **by design** | VE-002 does not apply. Judge by output content; **do not trigger a fix loop against a healthy artefact** | Critical |
+| VE-008 | Evidence claims absence (`0`, empty output, "not found") | Invalid until the query tool is shown to have run successfully. Re-run without stderr suppression | High |
+| VE-009 | An existence/absence check suppresses stderr (`2>/dev/null` or equivalent) | Evidence does not stand. Re-run with stderr visible | High |
+| VE-010 | Evidence's `exit_code` comes from a pipeline (esp. under `pipefail`) | The code attributes to no single stage. Capture the output and evaluate content instead | Medium |
 
 ---
 
@@ -163,10 +281,52 @@ message: "I've completed the task and everything should work now."
 # ❌ No verification_evidence — violates Iron Law
 ```
 
+### Bad: Evidence That Cannot Support Its Claim
+
+```yaml
+claim: "The backup directory is empty — backups are not running."
+verification_evidence:
+  - command: "sudo -n find /backup/immich -type f 2>/dev/null | wc -l"
+    exit_code: 0
+    output: "0"
+    timestamp: "2026-07-17T13:05:00Z"
+# ❌ Passes the Iron Law: evidence exists, exit_code is 0, output is concrete.
+# ❌ Violates VE-008, VE-009, VE-010:
+#      - claims absence without showing the query tool ran (VE-008)
+#      - suppresses the stderr that said "sudo: a terminal is required" (VE-009)
+#      - the exit code is the pipeline's, i.e. `wc -l`'s — `find` never ran (VE-010)
+#    31 files were present. Directory listed as empty because nothing looked.
+```
+
+### Good: The Same Check, Made Valid
+
+```yaml
+claim: "The backup directory holds 31 files."
+verification_evidence:
+  - command: "ssh host 'sudo find /backup/immich -type f | wc -l'"   # stderr not suppressed
+    exit_code: 0
+    output: "31"
+    timestamp: "2026-07-17T13:07:00Z"
+    environment_layer: "prd"
+# ✅ stderr would have surfaced a sudo/permission failure instead of printing 0
+# ✅ single-quoted so ${...} is not expanded by the local shell before transit
+```
+
+---
+
+## Related Standards
+
+- [Anti-Hallucination](anti-hallucination.md) — the complementary standard. It prevents *fabricated* claims (asserting what was never checked); Evidence Validity covers the opposite failure — claims that **were** checked, by a tool that silently did not work.
+- [Systematic Debugging](systematic-debugging.md) — how to investigate once evidence shows a real failure
+- [Checkin Standards](checkin-standards.md) — where completion claims are gated
+- [Test Governance](test-governance.md) — which tests are required, and therefore which evidence must exist
+- [Testing Standards](testing-standards.md) — how the tests that produce most evidence are written
+- [Agent Dispatch](agent-dispatch.md) — delegated work returns claims that need this standard applied to them
+- [Deployment Standards](deployment-standards.md) — defines the Environment Stratification Responsibility Matrix referenced by VE-005 / VE-006
+
 ---
 
 ## References
 
 - **Superpowers**: [verification-before-completion](https://github.com/obra/superpowers) (MIT)
 - **Test-Driven Development**: RED-GREEN-REFACTOR cycle
-- **Anti-Hallucination**: Complementary standard for preventing fabricated claims

package/bundled/core/verification-oracle.md

@@ -0,0 +1,167 @@
+# Verification Oracle Standards
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-06-17
+> **AI-optimized version**: `ai/standards/verification-oracle.ai.yaml`
+> **Spec**: XSPEC-256 (cross-project/specs/XSPEC-256-verification-oracle.md)
+
+**Scope**: universal
+
+## Overview
+
+A **test oracle** is the source of truth that decides whether software output is *correct*.
+Software without an oracle cannot be said to be "right" — you cannot even state whether it
+is right or wrong. This standard makes the **ground-truth oracle a first-class artifact**
+and turns "correct" from a one-time acceptance state into a **maintained invariant**
+re-verified on every change (DEC-077).
+
+It is the **correctness** member of the governance-gate family — alongside
+`license-compliance` (XSPEC-193, *licensing*) and `model-provenance` (XSPEC-255, *source*) —
+which all share the same shape: **registry/check → fail-closed gate → audit evidence →
+human-escalation ceiling**. The three are profiles of one mechanism over three axes:
+**licensing / provenance / correctness**.
+
+> **Scope.** This standard defines the *correctness oracle mechanism* (registry, grading,
+> gate timing, re-verification, evidence, escalation) and the acceptance evidence it
+> produces. The **oracle content (the correct answers) belongs to the customer** — it is
+> their domain, their ground truth (DEC-075 neutral mechanism / DEC-063 customer-owned
+> output). Enforcement engine wiring (e.g. VibeOps pipeline gates) is a downstream
+> adoption concern, not part of this standard.
+
+## The Oracle-ability Spectrum
+
+Not every requirement has a ready oracle. Grade each high-stakes feature by how readily its
+oracle exists — this drives cost, beachhead selection, and when a human must step in.
+
+| Tier | Oracle shape | Readiness / cost |
+|------|--------------|------------------|
+| 1 | Known-correct output of a legacy system | Most ready, cheapest (parity-provable) |
+| 2 | A batch of hand-computed / existing correct outputs | Ready (reproduce + scale) |
+| 3 | Regulation / formula (rules exist, examples missing) | Needs co-derived worked examples + sign-off (ATDD) |
+| 4 | Vague requirement (oracle must be *mined* from interviews) | Most expensive — the "translation problem" |
+
+## Requirements
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | Ground-truth registry as a first-class artifact, bound to AC | MUST |
+| REQ-002 | Oracle-ability grading (Tier 1–4) for every high-stakes feature | MUST |
+| REQ-003 | Fail-closed verification gate before ship | MUST |
+| REQ-004 | Sustained re-verification on every change (correctness as CI invariant) | MUST |
+| REQ-005 | Auditable verification evidence (N/N reproduced, no drift, trace) | MUST |
+| REQ-006 | Self-serve frontier ceiling — escalate when no oracle / unverifiable high-stakes | MUST |
+| REQ-007 | Oracle content sovereignty — content owned by customer, mechanism neutral | SHOULD |
+
+### REQ-001 — Ground-Truth Registry
+
+The correct answers a customer provides become a first-class artifact. Each ground-truth
+case carries an **input scenario + expected correct output**, and is **bound to the
+acceptance criterion** it proves (`acceptance-criteria-traceability`). At minimum the
+mechanism MUST support numeric and structured-output comparison, with per-field exemptions
+(e.g. `ignore_fields` for timestamps/ids). Example: a billing case "given orders + org
+state → the *correct* charge amount", not merely "the endpoint returns HTTP 200".
+
+### REQ-002 — Oracle-ability Grading
+
+Every high-stakes feature MUST be tagged with its oracle Tier (1–4, table above).
+A **Tier-4 (must-mine) feature MUST have a defined hand-off point** to an oracle-manufacturing
+flow (interview / Prototype Probe; XSPEC-252) that pulls the expensive end toward Tier 1–2.
+Beachhead selection SHOULD prefer Tier 1–2 features where the oracle is already ready.
+
+### REQ-003 — Fail-Closed Verification Gate
+
+Before a system may enter UAT/ship, it MUST **exactly reproduce every registered
+ground-truth case**. A non-reproduction MUST **block ship or escalate** — never silently
+pass (mirrors `license-compliance` blocklist and `model-provenance` denylist). The gate
+plugs into existing reviewer/QA gates and the audit logger.
+
+### REQ-004 — Sustained Re-Verification (the soul of this standard)
+
+On **every change / regeneration**, the full oracle suite MUST be re-run, making "correct"
+a **CI-grade invariant** rather than a one-time acceptance. **Drift** (was-correct, now-wrong)
+MUST be detected and **blocked**. This is the mechanization of DEC-077's "changed and still
+correct, and provably correct the whole time" — the differentiator a "generate-once, never
+re-verify" competitor cannot match.
+
+### REQ-005 — Audit Evidence
+
+Each verification run MUST emit an auditable report: *"this delivery reproduced N/N
+ground-truth cases, no drift, trace attached."* It plugs into the audit logger / hash chain,
+the `model-provenance` source evidence (XSPEC-255), and the telemetry allowlist (DEC-066).
+**This report is the outward proof of the correctness/governance moat** and a compliance
+artifact for the customer.
+
+### REQ-006 — Self-Serve Frontier Ceiling
+
+Where there is **no oracle** (correctness is not decidable) or a **high-stakes but
+unverifiable** path, the system MUST NOT let self-serve silently pass. It MUST flag
+"a human must decide / an oracle must be supplied here" and **escalate** (DEC-076 ceiling).
+Defining correctness and signing off acceptance are **human judgments** (customer / legal /
+regulator) — a product-enforced governance gate, not a consultant trap.
+
+### REQ-007 — Oracle Content Sovereignty
+
+The verification *mechanism* is domain-neutral (DEC-075); the *correct answers* are owned by
+the customer (DEC-063). Adopters SHOULD keep registries customer-scoped and isolated
+(see `model-provenance` / `license-compliance` per-customer salt patterns, DEC-064).
+
+## Principles
+
+| ID | Principle |
+|----|-----------|
+| P-1 | Oracle First — no oracle, no "correct"; grade oracle-ability before claiming correctness |
+| P-2 | Maintained Invariant — re-verify on every change; drift is a blocking event (DEC-077) |
+| P-3 | Fail-Closed — non-reproduction blocks or escalates; never silent pass |
+| P-4 | Evidence-Based — every verdict carries a reproducible trace (N/N + diff + audit id) |
+| P-5 | Human Ceiling — unverifiable high-stakes escalates to a human (DEC-076) |
+| P-6 | Content Sovereignty — mechanism neutral, correct answers owned by the customer |
+
+## Gate Timing
+
+```
+spec(SDD) → generate → [oracle verification gate]  ← REQ-003 fail-closed, pre-ship
+                              │
+        on every change ─────┤ → re-run full oracle suite  ← REQ-004 drift block
+                              ↓
+                    audit evidence report  ← REQ-005 (outward moat proof)
+                              │
+   no oracle / unverifiable ──┴──→ escalate to human  ← REQ-006 ceiling
+```
+
+## Relationship to the Governance-Gate Family
+
+| Profile | Standard | Axis | Registry/Check | Block trigger |
+|---------|----------|------|----------------|---------------|
+| Licensing | `license-compliance` (XSPEC-193) | legal | blocklist/allowlist/greylist | prohibited license |
+| Provenance | model-provenance (XSPEC-255, planned sibling) | source | model source policy | denied source |
+| **Correctness** | **`verification-oracle` (XSPEC-256)** | **correct** | **ground-truth registry** | **non-reproduction / drift** |
+
+All three: fail-closed + audit evidence + customer override telemetered + human-escalation ceiling.
+
+## Integration with Existing Standards
+
+- **`acceptance-criteria-traceability`** — oracle cases bind to AC; reproduction becomes a
+  form of AC coverage.
+- **`verification-evidence`** — the oracle report is a kind of verification evidence (N/N
+  reproduction + no-drift + trace).
+- **`test-governance`** — the oracle suite is governed test policy; the gate is a governed gate.
+- **`behavior-snapshot`** — a parity/snapshot gate is REQ-003/REQ-004 instantiated for the
+  refactor/migration case; a snapshot is itself an oracle, so the skeleton may be shared.
+
+## Related Specs
+
+- XSPEC-256 — Verification Oracle complete spec (this standard's source)
+- DEC-077 — Correctness as a maintained invariant (mother decision)
+- DEC-075 — VibeOps domain-neutral positioning (neutral mechanism)
+- DEC-076 — Self-serve customization north star (oracle = self-serve ceiling)
+- DEC-063 — Legal & compliance strategy (customer-owned output / high-stakes)
+- DEC-066 — Telemetry-driven product evolution (audit/telemetry)
+- XSPEC-193 / XSPEC-255 — sibling governance-gate profiles (licensing / provenance)
+- XSPEC-252 — Domain pack requirement translation (oracle manufacturing, Tier-4 hand-off)
+- XSPEC-188 — UAT ship-decision dashboard (business-level UAT anchors)
+- XSPEC-201 — Refactor/migration completeness (behavior-snapshot = an oracle instance)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-06-17 | Initial — REQ-001~007: ground-truth registry, oracle-ability grading, fail-closed gate, sustained re-verification, audit evidence, self-serve ceiling, content sovereignty (XSPEC-256) |