universal-dev-standards 6.0.0 → 6.1.1

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/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/multi-environment-e2e-testing.md

@@ -0,0 +1,195 @@
+# Multi-Environment E2E Testing Standards
+
+> **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-05-13
+> **AI-optimized version**: `ai/standards/multi-environment-e2e-testing.ai.yaml`
+> **Spec**: XSPEC-204 (UDS Issue #94, #95)
+
+**Scope**: universal
+**Applicability**: Any project whose E2E tests must run against more than one deployment
+target (local, local-IIS, UAT, PRD, etc.)
+
+## Overview
+
+This standard defines how to configure E2E tests across multiple deployment targets. Its
+core principle is **Executable Environment Documentation**: *the run command IS the
+documentation*. Each environment gets one entry-point script that self-checks its own
+prerequisites and runs the correct test subset — so the script itself becomes the
+authoritative environment setup guide, instead of scattered knowledge in a README, a
+wiki page, and verbal tribal knowledge.
+
+> **Anti-pattern**: manually editing `BASE_URL` in `.env` before test runs. This breaks
+> other developers' configs and cannot be committed without affecting everyone.
+
+## Test Framework Multi-Environment Config
+
+**Rule**: `BASE_URL` is baked into the test-project config, not read from `.env`. If
+`BASE_URL` comes from `.env`, developers must edit `.env` before running against a
+specific environment — a race condition in teams, and a source of accidental commits of
+the wrong URL.
+
+Playwright — one config, one project per environment:
+
+```ts
+// playwright.config.ts
+const ENVS = {
+  'local-iis':         'http://localhost/corp',
+  'local-iis-express': 'http://localhost:18080/lotest',
+  'uat':               'http://portal_uat.example.com/app',
+  'prd':               'https://app.example.com',
+} as const;
+
+export default defineConfig({
+  projects: Object.entries(ENVS).map(([name, url]) => ({
+    name,
+    use: { browserName: 'chromium', baseURL: url },
+  })),
+});
+```
+
+Cypress — pass the target via `--env target=uat`, defaulting to `local`:
+
+```ts
+// cypress.config.ts
+const ENVS = {
+  'local':  { baseUrl: 'http://localhost:3000' },
+  'uat':    { baseUrl: 'http://uat.example.com' },
+  'prd':    { baseUrl: 'https://app.example.com' },
+};
+```
+
+Rules:
+
+- One test config file; distinguish environments via project name or a `--project` /
+  `--env` flag.
+- No environment-specific `playwright.config.*.ts` / `cypress.config.*.ts` files.
+- `BASE_URL` is never sourced from `.env` for E2E test configs.
+
+## Runner Script Pattern
+
+**Rule**: each environment has one entry-point script,
+`scripts/run-tests-<env>.(ps1|sh)`, that self-checks prerequisites before invoking the
+test runner. Prerequisite checks typically cover: Docker/container runtime, application
+health endpoint, database connectivity (if separate from the app), and any other
+required environment-specific services.
+
+```bash
+#!/bin/bash
+# scripts/run-tests-local.sh
+
+# 1. Check Docker
+if ! docker info > /dev/null 2>&1; then
+  echo "ERROR: Docker is not running." >&2
+  exit 1
+fi
+
+# 2. Check App
+if ! curl -s -f http://localhost:3000/health > /dev/null 2>&1; then
+  echo "ERROR: App not responding at http://localhost:3000" >&2
+  exit 1
+fi
+
+npx playwright test --project=local "$@"
+```
+
+(The PowerShell equivalent follows the same three steps: check Docker, check the app
+health endpoint, then run `npx playwright test --project=<env>`.)
+
+## Environment Capability Matrix
+
+**Rule**: projects with external dependencies (HTTP services, IdP, payment, messaging)
+MUST maintain an environment capability matrix committed to the repository —
+`docs/testing/environment-capability-matrix.md` or inline in the testing README. Update
+it whenever a new external service dependency is added.
+
+```
+## Environment Capability Matrix
+
+| Service / Feature | local-dev | local-iis | UAT | PRD |
+|-------------------|:---------:|:---------:|:---:|:---:|
+| Auth / SAML       | ⚠️ Keycloak stub | ✅ Keycloak local | ✅ Keycloak UAT | ✅ Enterprise IdP |
+| SMS Gateway       | ⚠️ stub-server | ⚠️ stub-server | ⚠️ stub-server / ❌ | ✅ Real Gateway + billing |
+| Payment / Finance | ⚠️ stub-server | ⚠️ stub-server | ⚠️ partial | ✅ Real + reconciliation |
+| Background Jobs   | ✅ in-process | ✅ in-process | ✅ | ✅ |
+| File Storage      | ✅ local | ✅ local | ✅ blob | ✅ blob |
+
+Legend: ✅ Full verification possible · ⚠️ Flow passes but through a stub (real-world
+dimensions NOT verified) · ❌ Cannot test in this environment
+
+### Dimensions NOT verifiable in UAT (must defer to PRD smoke)
+- SMS: billing correctness, carrier delivery confirmation, DR reporting
+- Payment: real debit/credit, bank reconciliation, card validation
+```
+
+## CI Gate Mapping
+
+**Rule**: map each CI/CD stage to the environment(s) it must pass, and document which
+gate must pass before each deployment stage.
+
+```yaml
+# .github/workflows/ci.yml or .gitlab-ci.yml
+e2e-smoke-gate:       # Must pass → any deployment
+  runs-on: ubuntu-latest
+  script: scripts/run-tests-local.sh --grep smoke
+
+e2e-uat-gate:         # Must pass → PRD deployment
+  environment: uat
+  script: scripts/run-tests-uat.sh
+  only: [tags, release-branches]
+
+e2e-prd-smoke:        # Must pass → mark release as stable
+  environment: prd
+  script: scripts/run-tests-prd-smoke.sh
+  only: [tags]
+```
+
+| Deployment Stage | Required Gates |
+|-------------------|-----------------|
+| Before staging deploy | unit tests, integration tests, e2e-smoke-gate |
+| Before UAT deploy | all staging gates, e2e-uat-gate (if a UAT environment is available) |
+| Before PRD deploy | e2e-uat-gate, sign-off from capability-matrix review |
+| After PRD deploy | e2e-prd-smoke, within 10 minutes of deploy |
+
+## Credential Handling
+
+**Rule**: separate what goes into git from what stays gitignored.
+
+- **Commit to git**: base URLs per environment (non-secret, team-shared), test
+  usernames for non-PRD environments, feature flags and test configuration,
+  self-check scripts with no credentials embedded.
+- **Gitignore**: passwords and secrets, API keys and tokens, `.env.test.local`
+  (personal overrides).
+- **CI secrets**: PRD test passwords are passed via CI secret variables (GitHub
+  Secrets / GitLab CI Variables) — never committed.
+
+```
+# Test credentials
+.env.test.local
+tests/fixtures/auth-secrets.json
+# Base URLs and non-secrets are committed; see playwright.config.ts
+```
+
+## Rules
+
+| Rule | Trigger | Instruction | Priority |
+|------|---------|--------------|----------|
+| `base-url-in-config` | Setting up E2E tests for a project with multiple environments | Define all environment `BASE_URL`s in the test framework config as named projects; do not rely on `.env` for `BASE_URL` | required |
+| `one-runner-per-env` | Adding a new deployment target | Create `scripts/run-tests-<env>.(ps1\|sh)` with self-checking prerequisite steps; verify all required services before invoking the test runner | required |
+| `capability-matrix-required` | Feature has external service dependencies (SMS, payment, IdP, file storage) | Create or update the environment capability matrix; mark ✅/⚠️/❌ per service × environment; list dimensions not verifiable in UAT as "PRD-only smoke" | required |
+| `ci-gate-mapping` | Defining CI/CD pipeline stages | Map each CI gate to the environment(s) it must pass; the E2E gate must specify which environment it targets | required |
+
+## Relationship to Other Standards
+
+- **`deployment-standards`** — extends: adds the environment dimension to CI gates and
+  deployment readiness.
+- **`test-completeness-dimensions`** — complements: adds dimension 11, Environment
+  Verifiability.
+- **`verification-evidence`** — complements: evidence must specify which environment it
+  was collected from.
+- **`mock-boundary`** — complements: the capability matrix references Level 2 stub-server
+  usage.
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-05-13 | Initial — executable environment documentation principle, framework config, runner scripts, capability matrix, CI gate mapping, credential handling (XSPEC-204) |

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/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