universal-dev-standards 5.14.0 → 5.15.1

package/bin/uds.js

@@ -175,6 +175,7 @@ program
   .option('--migrate', 'Migrate legacy manifest to hash-based tracking')
   .option('--offline', 'Skip npm registry check for CLI updates')
   .option('--force', 'Bypass UDS source-repo self-adoption guard (DEC-044 / XSPEC-071)')
+  .option('--i18n', 'Run i18n lint rules (XSPEC-239) across canonical + locale variants')
   .action(checkCommand);
 
 program
@@ -207,6 +208,7 @@ program
   .option('--plan', 'Show reconciliation plan without executing (like terraform plan)')
   .option('--force', 'Force update all files, ignoring hash comparison')
   .option('--rollback', 'Rollback to the most recent backup')
+  .option('--locale <locale>', 'Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env')
   .action(updateCommand);
 
 program

package/bundled/ai/standards/ai-instruction-standards.ai.yaml

@@ -3,10 +3,10 @@
 
 id: ai-instruction-standards
 meta:
-  version: "1.0.0"
-  updated: "2026-01-14"
+  version: "1.1.0"
+  updated: "2026-05-28"
   source: core/ai-instruction-standards.md
-  description: Best practices for creating AI instruction files with universal vs project-specific separation
+  description: Best practices for creating AI instruction files (root and skill level) with universal/project-specific separation and i18n strategy
 
 supported_tools:
   - tool: Claude Code
@@ -117,6 +117,26 @@ rules:
       grep -n "npm\|yarn\|pip\|cargo" CLAUDE.md | head -20
     priority: required
 
+  - id: i18n-canonical-english-only
+    trigger: editing canonical AI instruction file
+    instruction: Keep description and metadata in English; localize via locales/{lang}/ variants
+    priority: required
+
+  - id: i18n-locale-must-match-language
+    trigger: creating or editing locale variant
+    instruction: Description must be in the locale's language; include source/source_version/translation_version frontmatter
+    priority: required
+
+  - id: i18n-l3-template-language-controls-output
+    trigger: writing output templates / examples
+    instruction: L3 templates determine AI output language; localize L3 in locale variants, never in canonical
+    priority: required
+
+  - id: i18n-no-manual-canonical-edits-by-adopters
+    trigger: adopter wants to customize an installed instruction file
+    instruction: Use uds install --locale or overlays; do not modify canonical files in-place
+    priority: required
+
 maintenance_checklist:
   - item: Universal sections contain no project-specific paths, commands, or versions
     required: true
@@ -127,6 +147,173 @@ maintenance_checklist:
   - item: Format matches existing sections
     required: true
 
+i18n:
+  scope:
+    description: |
+      Defines language-handling policy for AI instruction files at two levels:
+      root-level (CLAUDE.md, .cursorrules, etc.) and skill-level
+      (Claude Code SKILL.md, OpenCode plugin instructions, etc.)
+    levels:
+      - level: root
+        files:
+          - CLAUDE.md
+          - .cursorrules
+          - .windsurfrules
+          - .clinerules
+          - .github/copilot-instructions.md
+          - .opencode/instructions.md
+        i18n_pattern: single_file_with_inline_language_sections
+      - level: skill
+        files:
+          - .claude/skills/{name}/SKILL.md
+          - .opencode/plugins/{name}/instructions.md
+        i18n_pattern: canonical_plus_locale_variants
+
+  layered_strategy:
+    description: |
+      Every AI instruction file has 4 layers. L3 (output templates) is the only
+      layer that directly affects AI output language; L1/L2 are processing
+      instructions for the AI. Enforce L3 strictly, L1 as a clear convention.
+    layers:
+      - id: L1
+        name: metadata
+        content:
+          - YAML frontmatter description
+          - argument-hint
+          - allowed-tools
+        canonical_language: english
+        locale_language: must_match_locale
+        rationale: AI-trigger signal; English has highest training-data density and token efficiency
+        impact_on_ai_output: none
+      - id: L2
+        name: instructions
+        content:
+          - imperative rules for AI
+          - steps
+          - behavior rules
+        canonical_language: english
+        locale_language: locale_optional
+        rationale: AI reads English instructions most precisely
+        impact_on_ai_output: none
+      - id: L3
+        name: output_templates
+        content:
+          - example outputs
+          - response format templates
+          - scenario examples
+        canonical_language: english
+        locale_language: must_match_locale_mandatory
+        rationale: AI mirrors the language of templates it sees — this is the only layer that controls output language
+        impact_on_ai_output: direct
+      - id: L4
+        name: human_docs
+        content:
+          - maintainer comments
+          - contributor walkthroughs
+        canonical_language: english
+        locale_language: locale_recommended
+        rationale: Read by human maintainers, not by AI
+        impact_on_ai_output: none
+
+  file_structure:
+    canonical:
+      - core/{name}.md
+      - core/{name}.ai.yaml
+      - skills/{name}/SKILL.md
+    locale:
+      - locales/{lang}/core/{name}.md
+      - locales/{lang}/ai/standards/{name}.ai.yaml
+      - locales/{lang}/skills/{name}/SKILL.md
+    locale_naming: BCP_47   # zh-TW, zh-CN, ja, ko, en-US, etc.
+
+  locale_variant_frontmatter:
+    required_fields:
+      - field: name
+        value: same as canonical
+      - field: source
+        value: relative path to canonical file
+      - field: source_version
+        value: version of canonical at time of translation
+      - field: translation_version
+        value: version of this translation
+    drift_alert:
+      condition: source_version gap > 2 minor versions behind canonical
+      severity: warn
+
+  responsibility_boundaries:
+    - role: canonical_owner
+      owns:
+        - core/{name}.md
+        - core/{name}.ai.yaml
+        - skills/{name}/SKILL.md
+      duties:
+        - Keep L1/L2/L3/L4 in English
+        - Bump source_version on every breaking change
+    - role: locale_maintainer
+      owns:
+        - locales/{lang}/...
+      duties:
+        - Keep translation_version aligned with source_version
+        - Translate L1 (required), L2 (optional), L3 (required), L4 (recommended)
+    - role: adopter
+      owns:
+        - their own .claude/skills/, CLAUDE.md
+      duties:
+        - Install via uds install --locale {lang}
+        - Never manually modify canonical files
+        - Use overlays or locale variants for customization
+
+  chimera_prevention:
+    rules:
+      - id: canonical-description-must-be-ascii
+        trigger: canonical file with CJK in description field
+        severity: error
+        instruction: Canonical files must keep description in English; move localized description to locale variant
+      - id: locale-description-must-match-language
+        trigger: locale variant with ASCII-only description
+        severity: error
+        instruction: Locale variant description must use the locale's language
+      - id: locale-must-have-source-frontmatter
+        trigger: locale variant missing source/source_version/translation_version
+        severity: error
+        instruction: Add traceability frontmatter pointing to canonical
+      - id: canonical-l3-language-consistency
+        trigger: canonical L3 output template contains non-English example
+        severity: warn
+        instruction: Localize L3 templates in locale variants, not canonical
+      - id: adopter-must-match-installed-locale
+        trigger: adopter file in .claude/skills/ differs from both canonical and any locale variant
+        severity: warn
+        instruction: Use uds install --locale or overlays instead of manual canonical edits
+      - id: translation-drift-warn
+        trigger: translation_version lag > 2 minor versions behind source_version
+        severity: warn
+        instruction: Re-sync translation from current canonical version
+
+  installation_model:
+    cli: uds install --locale {lang}
+    locale_resolution_priority:
+      - --locale CLI flag
+      - .uds/install.yaml locale field
+      - environment variable UDS_LOCALE
+      - fallback to en
+    missing_locale_behavior:
+      action: fallback_to_canonical_with_warn
+      block_install: false
+      coverage_visibility: locales/COVERAGE.md
+
+  migration:
+    name: adopter_chimera_cleanup
+    steps:
+      - id: identify
+        description: Compare adopter files against UDS canonical and locale variants
+      - id: install_proper_variants
+        description: Run uds install --locale {lang} to replace chimera
+      - id: preserve_legitimate_customization
+        description: Extract project-specific (non-translation) customization into overlay or UDS-CUSTOMIZATION.md
+      - id: discard_pure_translations
+        description: Chimera changes that were only translations are superseded by locale variants
+
 quick_reference:
   content_types:
     columns: [Type, Contains, Example]

package/bundled/ai/standards/knowledge-graph-memory.ai.yaml

@@ -0,0 +1,83 @@
+# Knowledge Graph Memory Standards - AI Optimized
+# Source: core/knowledge-graph-memory.md
+
+standard:
+  id: knowledge-graph-memory
+  name: Knowledge Graph Memory Standards
+  description: Relationship schema for traversing specs, decisions, and code as a graph; complements vector memory with structural multi-hop queries, engine-optional with Markdown degradation
+  guidelines:
+    - "Express relationships as optional, additive YAML front-matter (related/impacts/impacted_by/supersedes/implements)"
+    - "Derive IMPACTS (Decision->Spec) and SUPERSEDES (Decision->Decision) edges from front-matter or [[ref]] links"
+    - "Support two modes: degraded (AI reads linked Markdown) and service (graph engine multi-hop query) with the same answer shape"
+    - "Keep the graph engine opt-in; always degrade gracefully to Markdown reading"
+    - "Treat vector/semantic memory as complementary (similarity) to graph traversal (structure), not replaced"
+
+  meta:
+    version: "1.0.0"
+    updated: "2026-05-30"
+    source: core/knowledge-graph-memory.md
+    description: Relationship schema for traversing specs, decisions, and code as a graph; complements vector memory with structural multi-hop queries, engine-optional with Markdown degradation
+
+  schema:
+    format: "YAML front-matter on spec/decision Markdown documents"
+    optional_fields:
+      - field: related
+        type: list
+        direction: undirected
+        description: "Loosely associated artifact ids"
+      - field: impacts
+        type: list
+        direction: "this(Decision) -> Spec"
+        description: "Specs this decision changes"
+      - field: impacted_by
+        type: list
+        direction: "Decision -> this(Spec)"
+        description: "Decisions that change this spec"
+      - field: supersedes
+        type: list
+        direction: "this(Decision) -> Decision"
+        description: "Decisions this one replaces"
+      - field: implements
+        type: list
+        direction: "code/spec -> Spec"
+        description: "Specs this artifact realises"
+    node_kinds:
+      - prefix: "XSPEC-* / SPEC-*"
+        kind: Spec
+      - prefix: "DEC-* / ADR-*"
+        kind: Decision
+      - prefix: "function / class / module"
+        kind: Code
+
+  edges:
+    - rule: "Decision impacts:[SPEC]  => IMPACTS (Decision -> Spec)"
+    - rule: "Spec impacted_by:[DEC]   => IMPACTS (Decision -> Spec)"
+    - rule: "Decision supersedes:[DEC] => SUPERSEDES (Decision -> Decision)"
+    - rule: "[[XSPEC-NNN]] link in a Decision body => IMPACTS (Decision -> Spec)"
+    idempotent: "Declaring a relationship from both ends yields one edge, not two"
+
+  modes:
+    degraded:
+      description: "No engine: AI reads the target doc, follows front-matter/[[ref]] links by reading files, assembles the chain manually"
+      always_available: true
+    service:
+      description: "Graph engine indexed: a single multi-hop query (impact-analysis {nodeId, maxHops}) returns the full cross-domain chain"
+      example_engine: "CodeSage (@asiaostrich/codesage)"
+
+  confidence:
+    optional: true
+    range: "0.1 - 1.0"
+    floor: 0.1
+    note: "Feedback signals (test pass/fail, human correction, status change) evolve confidence; floor prevents erasing important nodes (SAGE)"
+
+  rules:
+    - "Relationship fields are optional and additive; absence never breaks tooling"
+    - "Reference ids that do not exist yet become stub nodes, resolved when the target appears"
+    - "Declare each relationship from the owning side, but accept either"
+    - "Graph engine is opt-in; degrade gracefully to Markdown reading"
+    - "Vector/semantic memory is complementary, not replaced"
+
+  related_standards:
+    - project-context-memory
+    - developer-memory
+    - adr-standards

package/bundled/core/ai-instruction-standards.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/ai-instruction-standards.md) | [简体中文](../locales/zh-CN/core/ai-instruction-standards.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-01-14
+**Version**: 1.1.0
+**Last Updated**: 2026-05-28
 **Applicability**: All projects using AI coding assistants
 **Scope**: partial
 **Industry Standards**: None (Emerging AI tool practice)
@@ -12,20 +12,20 @@
 
 ## Purpose
 
-This standard defines best practices for creating and maintaining AI instruction files (also known as "system prompt files"). These files guide AI assistants in understanding project-specific conventions, standards, and workflows.
+This standard defines best practices for creating and maintaining AI instruction files (also known as "system prompt files"). These files guide AI assistants in understanding project-specific conventions, standards, and workflows. This v1.1.0 extends scope to skill-level instruction files (SKILL.md) and adds i18n strategy.
 
 ---
 
 ## Supported AI Tools
 
-| AI Tool | Instruction File | Format |
-|---------|-----------------|--------|
-| Claude Code | `CLAUDE.md` | Markdown |
-| Cursor | `.cursorrules` | Markdown |
-| Windsurf | `.windsurfrules` | Markdown |
-| Cline | `.clinerules` | Markdown |
-| GitHub Copilot | `.github/copilot-instructions.md` | Markdown |
-| OpenCode | `.opencode/instructions.md` | Markdown |
+| AI Tool | Instruction File | Format | Skill-Level Instruction |
+|---------|-----------------|--------|------------------------|
+| Claude Code | `CLAUDE.md` | Markdown | `.claude/skills/{name}/SKILL.md` |
+| Cursor | `.cursorrules` | Markdown | n/a |
+| Windsurf | `.windsurfrules` | Markdown | n/a |
+| Cline | `.clinerules` | Markdown | n/a |
+| GitHub Copilot | `.github/copilot-instructions.md` | Markdown | n/a |
+| OpenCode | `.opencode/instructions.md` | Markdown | n/a |
 
 ---
 
@@ -145,6 +145,130 @@ Use clear markers to distinguish content types:
 
 ---
 
+## Internationalization (i18n)
+
+AI instruction files often need to be available in multiple languages — both for international adopters and for projects with non-English-speaking maintainers. This section defines how to organize, validate, and install multi-language instruction files.
+
+### Scope of AI Instruction Files
+
+This standard covers instruction files at two levels:
+
+| Level | Examples | i18n Pattern |
+|-------|----------|--------------|
+| **Root-level** | `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.opencode/instructions.md` | Single file with inline language sections (e.g., `## 中文` / `## English`) |
+| **Skill-level** | Claude Code `.claude/skills/{name}/SKILL.md`, OpenCode plugin instructions | Canonical (English) + `locales/{lang}/` variants |
+
+> Note: skill-level multi-file structure is most relevant to Claude Code. Other tools use single root files; for them, only the layered language strategy (below) and the chimera-prevention rules apply.
+
+### Layered Language Strategy
+
+Every AI instruction file conceptually has **four layers**, each with different language responsibilities:
+
+| Layer | Content | Canonical (en) | Locale ({lang}) | Why |
+|-------|---------|---------------|----------------|-----|
+| **L1 — Metadata** | YAML frontmatter `description`, `argument-hint`, `allowed-tools` | **Must be English** | **Must match locale** | AI-trigger signal; English has highest training-data density and token efficiency |
+| **L2 — Instructions** | Imperative rules for the AI (steps, behavior, allowed-tools rationale) | **Must be English** | Locale language (optional; may stay English) | AI reads English instructions most precisely; locale only useful if maintainers need to read instructions in their language |
+| **L3 — Output Templates** | Example outputs, response formats, scenario templates | English (locale-pinned to English in canonical) | **Mandatory locale match** | **Only layer that directly controls AI output language** — AI inherits the language of templates it sees |
+| **L4 — Human Docs** | Comments for maintainers, walkthroughs, contributor notes | English | Locale language (strongly recommended) | Read by human maintainers, not by AI |
+
+**Critical insight**: L1 (description) is the trigger signal AI uses to decide *whether to invoke* a skill — it does **not** affect what the AI says afterwards. L3 (output templates) is the only layer that controls AI output language, because AI mirrors the language of templates it sees. **i18n enforcement should focus on L3 — strengthening L1 enforcement is a common mistake that solves the wrong problem.**
+
+### Canonical / Locale File Structure
+
+For UDS standards and skills with locale variants:
+
+```text
+core/{name}.md                              ← canonical (English) — single source of truth
+core/{name}.ai.yaml                         ← canonical structured (English)
+locales/{lang}/core/{name}.md               ← locale variant (matches lang)
+locales/{lang}/ai/standards/{name}.ai.yaml  ← locale .ai.yaml (matches lang)
+skills/{name}/SKILL.md                      ← canonical skill (English)
+locales/{lang}/skills/{name}/SKILL.md       ← locale skill variant
+```
+
+**Naming convention**: use BCP 47 language tags — `zh-TW`, `zh-CN`, `ja`, `ko`, `en-US`, etc.
+
+### Locale Variant Frontmatter Requirements
+
+Every locale variant must include traceability frontmatter so drift can be detected:
+
+```yaml
+---
+name: {same name as canonical}
+source: {relative path back to canonical}
+source_version: {version of canonical at time of translation}
+translation_version: {version of this translation}
+---
+```
+
+When canonical is updated (bumping `source_version`), locale maintainers should re-sync and bump `translation_version`. A `source_version` gap of more than 2 minor versions triggers a drift warning (see Chimera Prevention).
+
+### Responsibility Boundaries
+
+| Role | Owns | Must do |
+|------|------|---------|
+| **Canonical owner** | `core/{name}.md`, `core/{name}.ai.yaml`, `skills/{name}/SKILL.md` | Keep L1/L2/L3/L4 in English; bump `source_version` on every breaking change |
+| **Locale maintainer** | `locales/{lang}/...` files | Keep `translation_version` aligned with `source_version`; translate L1 (required) / L2 (optional) / L3 (required) / L4 (recommended) |
+| **Adopter (downstream project)** | Their own `.claude/skills/`, `CLAUDE.md`, etc. | Install via `uds install --locale {lang}`; **never** manually modify canonical files (always edit locale variants or use overlays) |
+
+### Chimera Prevention
+
+A **chimera** is a file that mixes languages in violation of layer rules. Common chimera patterns:
+
+| Pattern | Severity | Detection |
+|---------|----------|-----------|
+| Canonical file with CJK in `description` field | ❌ Error | Lint: `canonical:description-must-be-ascii` |
+| Locale variant with ASCII-only `description` field | ❌ Error | Lint: `locale:description-must-match-language` |
+| Locale variant missing `source:` frontmatter | ❌ Error | Lint: `locale:must-have-source-frontmatter` |
+| Canonical L3 output template containing non-English example response | ⚠️ Warn | Lint: `canonical:l3-language-consistency` |
+| Adopter file in `.claude/skills/` differs from both canonical and any locale variant | ⚠️ Warn | Sync check: `adopter:must-match-installed-locale` |
+| `translation_version` lag > 2 minor versions behind `source_version` | ⚠️ Warn | Drift check |
+
+Pre-commit / CI lint should enforce error-level rules; warn-level rules surface in dashboards but don't block.
+
+### Adopter Installation Model
+
+Adopters install instruction files via the UDS CLI:
+
+```bash
+uds install --locale zh-TW   # install skills + standards in Traditional Chinese
+```
+
+**Locale resolution order**:
+1. `--locale` CLI flag (highest priority)
+2. `.uds/install.yaml` field `locale:`
+3. Environment variable `UDS_LOCALE`
+4. Fallback: `en`
+
+**Missing locale fallback**: when a requested locale variant doesn't exist for a specific skill, the CLI:
+- Installs the canonical (English) file
+- Emits a WARN listing skills that fell back
+- Does **not** block installation
+
+This keeps installation usable for adopters even when locale coverage is incomplete. Adopters can consult `locales/COVERAGE.md` for the canonical list of what is and isn't translated.
+
+### Migration: Adopters With Existing Chimera
+
+If an adopter has already manually modified canonical files in their project (e.g. translated descriptions in `.claude/skills/`):
+
+1. **Identify the chimera**: compare adopter files against UDS canonical and canonical's locale variants.
+2. **Install proper variants**: run `uds install --locale {lang}` to replace chimera files with locale variants.
+3. **Preserve project-specific customization**: if the chimera contained legitimate project-specific customization (not just translation), extract it into an overlay or document it in the adopter's customization log (e.g. `UDS-CUSTOMIZATION.md`).
+4. **Discard pure translations**: chimera changes that were only translations should be discarded — the proper locale variant supersedes them.
+
+### Quick Reference
+
+| Action | When | Tool / File |
+|--------|------|-------------|
+| Add new language | Want to support a new locale | Create `locales/{lang}/...` mirroring canonical structure |
+| Update canonical | Improving English source | Bump `source_version`; notify locale maintainers |
+| Translate / sync locale | Adding or updating locale content | Bump `translation_version`; reference current `source_version` |
+| Check coverage | Periodic review | View auto-generated `locales/COVERAGE.md` |
+| Install with locale | Adopter setup or re-sync | `uds install --locale {lang}` |
+| Lint i18n rules | Before commit / in CI | `uds lint --i18n` |
+
+---
+
 ## Maintenance Checklist
 
 Before committing changes to AI instruction files:
@@ -199,6 +323,7 @@ Review each match to ensure it's in a project-specific section.
 | Version | Date | Changes |
 |---------|------|---------|
 | 1.0.0 | 2026-01-14 | Initial release |
+| 1.1.0 | 2026-05-28 | Add i18n section; extend scope to skill-level files |
 
 ---
 

package/bundled/core/knowledge-graph-memory.md

@@ -0,0 +1,119 @@
+# Knowledge Graph Memory Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/knowledge-graph-memory.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-05-30
+**Applicability**: Projects using AI assistants across code + specification/decision corpora
+**Scope**: uds-specific
+
+---
+
+## Purpose
+
+This standard defines a **relationship schema** so that specifications, decisions, and code can be traversed as a graph — answering questions like *"if I change `execute()`, which specs and decisions are affected?"*. It complements vector/semantic memory (which finds *similar* artifacts) with **structural traversal** (which finds *connected* artifacts).
+
+The schema is engine-agnostic: it is expressed as plain Markdown front-matter that an AI assistant can read directly (degraded mode), and that an optional graph engine (e.g. [CodeSage](https://github.com/AsiaOstrich/CodeSage)) can index for multi-hop queries (service mode).
+
+---
+
+## Quick Reference
+
+### Relationship Front-Matter Schema
+
+Add these optional fields to a spec/decision document's YAML front-matter:
+
+| Field | Type | Direction | Meaning |
+|-------|------|-----------|---------|
+| `related` | list of ids | undirected | Loosely associated artifacts |
+| `impacts` | list of spec ids | this → spec | This decision changes those specs |
+| `impacted_by` | list of decision ids | decision → this | Those decisions change this spec |
+| `supersedes` | list of decision ids | this → decision | This decision replaces those |
+| `implements` | list of spec ids | code/spec → spec | This artifact realises those specs |
+
+Ids are artifact identifiers (e.g. `XSPEC-205`, `DEC-062`, `ADR-001`). Inline `[[XSPEC-NNN]]` wiki-links in the body are an equivalent, lower-fidelity signal.
+
+### Node Kinds
+
+| Prefix | Node kind |
+|--------|-----------|
+| `XSPEC-*` / `SPEC-*` | Spec |
+| `DEC-*` / `ADR-*` | Decision |
+| function / class / module (from code) | Code node |
+
+---
+
+## 1. Schema
+
+### 1.1 Front-Matter Example
+
+```markdown
+---
+id: XSPEC-205
+title: Agent/Role Spec SDD Variant
+status: Implemented
+impacted_by: [DEC-062]
+related: [XSPEC-204]
+---
+```
+
+```markdown
+---
+id: DEC-069
+title: CodeSage Architecture
+date: 2026-05-27
+supersedes: [DEC-057]
+impacts: [XSPEC-237]
+---
+```
+
+### 1.2 Edge Derivation
+
+| Front-matter on doc | Derived edge |
+|---------------------|--------------|
+| Decision `impacts: [SPEC]` | `IMPACTS` (Decision → Spec) |
+| Spec `impacted_by: [DEC]` | `IMPACTS` (Decision → Spec) |
+| Decision `supersedes: [DEC]` | `SUPERSEDES` (Decision → Decision) |
+| `[[XSPEC-NNN]]` link in a Decision body | `IMPACTS` (Decision → Spec) |
+
+Edges are **idempotent**: declaring the same relationship from both ends (a decision's `impacts` and the spec's `impacted_by`) yields one edge, not two.
+
+---
+
+## 2. Two Operating Modes
+
+A consumer of this standard MUST work in both modes:
+
+### 2.1 Degraded Mode (no engine)
+
+The AI assistant reads the target document, follows its front-matter / `[[ref]]` links by reading the linked files, and assembles the impact chain manually. Always available; bounded by how many files the assistant can read.
+
+### 2.2 Service Mode (graph engine available)
+
+The corpus is indexed into a graph engine; the assistant issues a single multi-hop query (e.g. `impact-analysis { nodeId, maxHops }`) and receives the full chain — including cross-domain links (code → spec → decision) that degraded mode would miss.
+
+> A correct implementation produces the **same answer shape** in both modes; service mode is faster and more complete, not different in kind.
+
+---
+
+## 3. Confidence (optional)
+
+Nodes MAY carry a `confidence` in `[0.1, 1.0]`. Feedback signals (test pass/fail, human correction, status changes) evolve confidence so that reads can surface the most-reinforced artifacts first. Confidence has a floor (never zero) so a run of failures cannot erase an important node. This is the basis of self-evolving graph memory (SAGE).
+
+---
+
+## 4. Rules
+
+1. Relationship fields are **optional** and **additive** — absence never breaks tooling.
+2. Reference ids that do not (yet) exist are allowed; they become stub nodes resolved when the target document appears.
+3. Declare each relationship from the side that *owns* it (a decision owns `impacts`/`supersedes`; a spec owns `impacted_by`), but either side is accepted.
+4. The graph engine is **opt-in**. Tools MUST degrade gracefully to Markdown reading when no engine is configured.
+5. Vector/semantic memory is **complementary**, not replaced — use graph traversal for structure, vectors for similarity.
+
+---
+
+## Related Standards
+
+- [Project Context Memory](project-context-memory.md) — per-project long-term facts
+- [Developer Memory](developer-memory.md) — universal, transferable preferences
+- [ADR Standards](adr-standards.md) — decision record format that feeds Decision nodes