universal-dev-standards 6.12.0 → 6.13.0-beta.1

package/bundled/ai/standards/developer-memory.ai.yaml

@@ -13,8 +13,8 @@ standard:
     - "Respect noise control levels and cooldown periods"
 
   meta:
-    version: "1.1.0"
-    updated: "2026-06-18"
+    version: "1.2.0"
+    updated: "2026-09-25"
     source: core/developer-memory.md
     description: Structured system for capturing, retrieving, and surfacing developer experience insights across conversations and projects
 
@@ -128,6 +128,20 @@ standard:
           trigger: "confidence < 0.2 OR 180+ days unsurfaced with confidence < 0.5"
         - type: staleness
           trigger: "versioned type with outdated version_bound"
+        - type: code-reference
+          trigger: "recalled memory cites a file path or symbol (function/class) that no longer exists at that location, or has moved"
+          timing: "runs before proactive-surfacing (check before a memory is shown, not after)"
+          scope: "file paths and symbol names (functions/classes) only; file:line is out of scope (line numbers drift on unrelated edits — different staleness semantics; see DEC-115 OQ-1)"
+          modes:
+            degraded:
+              when: "no graph engine configured (any tool, no setup — the default)"
+              how: "the assistant verifies the referenced path/symbol itself (Glob/Grep/Read) before using the memory — same mechanism as the memory-as-hint-not-conclusion rule"
+              source: "knowledge-graph-memory 1.0.0 §2.1 Degraded Mode"
+            engine:
+              when: "a graph engine is indexed (e.g. EngramGraph)"
+              how: "engine query (e.g. `egr refs check`) reports each citation's state: present / moved (with new location) / missing / unresolvable"
+              source: "knowledge-graph-memory 1.0.0 §2.2 Service Mode"
+          unresolvable_rule: "unresolvable (e.g. a cross-repo reference outside the indexed scope) MUST NOT be treated as present or missing — surface it as its own state"
         - type: revision
           trigger: "2+ needs-revision feedback"
 
@@ -135,6 +149,11 @@ standard:
     - id: proactive-surfacing
       trigger: conversation start or matching code pattern/error/decision detected
       instruction: >
+        Before surfacing, run the code-reference staleness check
+        (review.checks type: code-reference) on each candidate memory's
+        cited file path / symbol. Do not surface a memory whose citation
+        resolves to missing without flagging it as stale; unresolvable is
+        not the same as present or missing.
         Surface top 3 relevant memories when relevance > 0.7.
         Max 5 per trigger. Cooldown 7 days per entry.
         If > 5 matches, summarize into grouped insight.
@@ -225,3 +244,6 @@ standard:
     Category: {category} | Tags: {tags}
     Insight: {insight}
     Context: {context}
+
+  related_standards:
+    - knowledge-graph-memory

package/bundled/ai/standards/turn-completion-integrity.ai.yaml

@@ -3,8 +3,8 @@
 
 id: turn-completion-integrity
 meta:
-  version: "1.3.0"
-  updated: "2026-09-08"
+  version: "1.4.0"
+  updated: "2026-09-25"
   source: core/turn-completion-integrity.md
   description: An agent must not end a turn having stated a next action it did not take; enforced at turn end, not by instruction
   related:
@@ -117,6 +117,36 @@ enforcement:
   severity: warning
   timeout_ms: 2000
 
+# The check is enforced only where an adapter exists AND a hook is wired into
+# that harness's own config. This is separate from `enforcement:` above, which
+# only describes the Claude Code entry the generic installer walks — Codex and
+# Gemini CLI are installed by their own installCodexHooks/installGeminiHooks
+# functions (cli/src/installers/hooks-installer.js), each writing that
+# harness's own config file and output contract.
+supported_harnesses:
+  - harness: claude-code
+    event: Stop
+    config_file: ".claude/settings.json"
+    block_shape: '{"decision":"block","reason":...}, exit 0; silence allows'
+    script: scripts/hooks/check-turn-completion.mjs
+  - harness: codex
+    event: Stop
+    config_file: ".codex/hooks.json"
+    block_shape: '{"decision":"block","reason":...}, exit 0 — plain text or empty stdout documented as invalid for this event'
+    script: scripts/hooks/check-turn-completion-codex.mjs
+    known_limit: "R9 (human-directed stop exemption) is best-effort — Codex gives the assistant's last message directly but not the human's; a failed transcript read leaves the human side empty rather than skipping detection"
+  - harness: gemini-cli
+    event: AfterAgent
+    config_file: ".gemini/settings.json"
+    block_shape: '{"decision":"deny","reason":...}, exit 0 — the documented preferred path over exit code 2'
+    script: scripts/hooks/check-turn-completion-gemini.mjs
+  - harness: cursor
+    status: evaluated-not-supported
+    reason: "Whether Cursor's stop hook can actually block a turn was unresolved as of writing; shipping an adapter against an unverified contract repeats the exact failure R3 exists to prevent"
+  - harness: any-other
+    status: inactive
+    reason: "Same silent-by-default failure as an unsupported language (R8). uds init --with-hooks reports which harnesses it wired a hook into."
+
 checklist:
   - The check runs at turn end, not as an instruction to the agent
   - Every failure path exits without blocking
@@ -129,3 +159,5 @@ checklist:
   - The check recognises its own block message and does not read it as the human's
   - The check recognises the itemized blocker ending R2 defines, and does not block it
   - The attribution search excludes the check's own headings and scaffolding
+  - Each supported harness's block contract is verified against that harness's own docs, not assumed from another harness
+  - The installer only writes a harness's hook config for a harness the adopter selected

package/bundled/core/developer-memory.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/developer-memory.md)
 
-**Version**: 1.1.1
-**Last Updated**: 2026-06-18
+**Version**: 1.2.0
+**Last Updated**: 2026-09-25
 **Applicability**: All software projects using AI assistants
 **Scope**: universal
 **Owning Spec**: XSPEC-291 (developer-memory has no dedicated feature XSPEC; XSPEC-291 owns it)
@@ -250,6 +250,26 @@ recorded so each value is auditable rather than arbitrary.
 | `validity.type == "versioned"` AND version is outdated | Flag as stale |
 | `validity.type == "temporal"` AND `expires_at` passed | Flag as expired |
 | `validity.type == "evergreen"` | Skip version check |
+| Recalled memory cites a file path or symbol (function/class) that no longer exists at that location, or has moved | Flag as `code-reference` stale — see below |
+
+#### Code-Reference Staleness (`code-reference`)
+
+Code moves; a memory recorded against an old location does not update itself. This check catches the case where the memory's insight is still true but its citation — a file path, or a function/class name — is not.
+
+This reuses the **two operating modes [Knowledge Graph Memory](knowledge-graph-memory.md) §2 already defines**, rather than inventing a third:
+
+| Mode | When | How |
+|------|------|-----|
+| Degraded (no graph engine) | Any tool, no extra setup — the default | Before using a memory, the assistant confirms the cited path/symbol still exists itself (`Glob`/`Grep`/`Read`) — the same mechanism already required by §5 Memory Verification Principle |
+| Engine (a graph engine is indexed, e.g. [EngramGraph](https://github.com/AsiaOstrich/EngramGraph)'s `egr refs check`) | When available | The engine reports each citation's state: `present` / `moved` (with its new location) / `missing` / `unresolvable` |
+
+> A correct implementation produces the same answer shape in both modes (Knowledge Graph Memory §2.2) — engine mode is faster and more complete, not different in kind.
+
+**`unresolvable` MUST NOT be treated as `present` or `missing`.** It means the checker could not determine an answer for that citation (e.g. a cross-repo reference outside the indexed scope, per Knowledge Graph Memory §2.2's cross-domain caveat) — that uncertainty must reach the assistant as its own state, not collapse silently into a false positive (treated as still valid) or a false negative (treated as gone).
+
+**Timing**: this check runs as part of `proactive-surfacing` (§4.1) — before a memory is shown, not after. A memory whose citation resolves to `missing` is not silently surfaced as if nothing changed.
+
+**Scope (first batch)**: file paths and symbol names (function/class names) only. `file:line` references are explicitly **out of scope** — a line number drifts on every unrelated edit to the file, which is a different kind of staleness from "this file/symbol no longer exists" (see DEC-115 OQ-1; revisited by 2027-01-31).
 
 #### Revision Suggestions
 
@@ -280,6 +300,7 @@ recorded so each value is auditable rather than arbitrary.
 | Cooldown period | 7 days per entry | Prevent repetitive suggestions |
 | Max per trigger | 3–5 entries | Information overload prevention |
 | Overflow handling | AI summarizes into grouped insight | When > 5 matches found |
+| Code-reference check | Run before surfacing (§3.4 `code-reference` staleness, degraded or engine mode) | Do not surface a memory whose file/symbol citation no longer resolves without flagging it |
 
 #### Surfacing Format
 
@@ -541,6 +562,7 @@ by_category:
 - [AI Instruction Standards](ai-instruction-standards.md) — Token-efficient format for memory system instructions
 - [AI-Friendly Architecture](ai-friendly-architecture.md) — Project structure enabling memory integration
 - [Documentation Writing Standards](documentation-writing-standards.md) — Writing quality for memory entries
+- [Knowledge Graph Memory](knowledge-graph-memory.md) — Source of the degraded/engine dual-mode reused by `code-reference` staleness (§3.4)
 
 ---
 
@@ -587,10 +609,44 @@ If user feedback reveals:
 
 ---
 
+## 11. Tool Adoption Example: Code-Reference Check (Non-Normative)
+
+This section illustrates one way to wire the `code-reference` staleness check (§3.4) into a tool's own automation. It is documentation only — UDS does not ship this hook, and `uds init`/`uds update` do not install it.
+
+### Claude Code
+
+Claude Code's automatic memory lives outside the repo, at `~/.claude/projects/<project-path>/memory/`. A `SessionStart` hook can run the check against that directory before the session's first memory surfacing, falling back to degraded mode when no graph engine is present:
+
+```bash
+#!/usr/bin/env bash
+# Illustrative only — not installed by any UDS command.
+MEMORY_DIR="$HOME/.claude/projects/$(pwd | tr '/' '-')/memory"
+
+if command -v egr >/dev/null 2>&1 && [ -f .engram/graph.db ]; then
+  # Engine mode (§3.4): egr resolves each cited path/symbol.
+  egr refs check "$MEMORY_DIR"
+else
+  # Degraded mode (§3.4): no engine configured — nothing to run up
+  # front; the assistant verifies each citation itself before use (§5).
+  echo "[developer-memory] no graph engine detected; degraded mode applies"
+fi
+```
+
+### Other Tools
+
+A tool without a session-start hook still satisfies this standard through either:
+
+- a rule in the repo's own instruction file (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.clinerules`, `.windsurfrules`, `copilot-instructions.md`, `GEMINI.md`, `.roo/rules/`, etc.) instructing the assistant to verify a memory's cited path/symbol before relying on it; or
+- a pre-commit check that scans the repo's own instruction file(s) for citations that no longer resolve.
+
+---
+
 ## Version History
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.2.0 | 2026-09-25 | Added: `code-reference` staleness check to Review (§3.4) — a memory citing a moved/missing file path or symbol is flagged before surfacing; reuses Knowledge Graph Memory's degraded/engine dual mode instead of inventing a third; `unresolvable` may not be read as present or missing; scope is file paths and symbol names only (`file:line` explicitly out of scope, DEC-115 OQ-1); §11 adds a non-normative Claude Code adoption example (DEC-115-L1) |
+| 1.1.1 | 2026-06-18 | Added: `Owning Spec` header pointing to XSPEC-291 (patch, no behavioral change; XSPEC-291 §11 disposition) |
 | 1.1.0 | 2026-06-18 | Added: rationale column + configurable note to Retirement Suggestions thresholds (XSPEC-292 T8) |
 | 1.0.0 | 2026-02-07 | Initial standard: schema, 4 operations, proactive protocol, noise control, architecture decision (Always-On Protocol) |
 

package/bundled/core/turn-completion-integrity.md

@@ -2,8 +2,8 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/turn-completion-integrity.md)
 
-**Version**: 1.3.0
-**Last Updated**: 2026-09-08
+**Version**: 1.4.0
+**Last Updated**: 2026-09-25
 **Applicability**: Any harness where an agent ends a turn and hands control back to a human
 **Scope**: universal
 **Industry Standards**: none claimed — derived from observed failures, see Evidence
@@ -146,6 +146,38 @@ prevent, one level up.
 
 ---
 
+## Supported harnesses
+
+The check is enforced only where a harness adapter exists and a hook is
+actually wired into that harness's own config. As of v1.4.0:
+
+| Harness | Event | Config file | Block contract |
+|---|---|---|---|
+| Claude Code | Stop | `.claude/settings.json` | stdout `{"decision":"block","reason":...}`, exit 0; silence allows |
+| Codex | Stop | `.codex/hooks.json` | stdout `{"decision":"block","reason":...}`, exit 0 — plain text or empty stdout is documented as invalid for this event |
+| Gemini CLI | AfterAgent | `.gemini/settings.json` | stdout `{"decision":"deny","reason":...}`, exit 0 — the documented preferred path over exit code 2 |
+
+Codex's R9 exemption is best-effort, not silent failure: Codex's Stop payload
+gives the assistant's final message directly but not the human's, so reading
+the human side requires parsing a transcript file whose exact schema was not
+confirmed against a real installation at the time this table was written. A
+failed parse leaves the human side empty — detection still runs on the
+assistant's message, only the R9 exemption for that one turn may be missed.
+
+Cursor was evaluated and is not supported: whether its stop hook can actually
+block a turn in the way this standard requires was unresolved as of this
+writing, and shipping an adapter against an unverified contract would repeat
+the exact failure R3 exists to prevent — an enforcement mechanism nobody has
+confirmed enforces anything.
+
+On any harness not in the table above, the check is inactive — the same
+silent-by-default failure as an unsupported language (R8). `uds init
+--with-hooks` reports which harnesses it wired a hook into; it does not
+enumerate the rest here, because that list is a citation waiting to go stale
+the next time a harness is added or dropped.
+
+---
+
 ## What the detector matches
 
 The shape is: **a first-person future marker, then an action verb, in the same
@@ -194,3 +226,5 @@ only because a corpus existed; the two that shipped were the ones no case covere
 - [ ] The check recognises its own block message and does not read it as the human's
 - [ ] The check recognises the itemized blocker ending R2 defines, and does not block it
 - [ ] The attribution search excludes the check's own headings and scaffolding
+- [ ] Each supported harness's block contract (config file, event, output shape) is verified against that harness's own docs, not assumed from another harness
+- [ ] The installer only writes a harness's hook config for a harness the adopter selected

package/bundled/hooks/check-turn-completion-codex.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * UDS Hook: Turn Completion Integrity — Codex adapter
+ *
+ * Runs at turn end. Blocks when the agent's final message states a first-person
+ * commitment to a next action that the turn then ended without taking.
+ *
+ * Contract (Codex Stop hook — https://developers.openai.com/codex/hooks,
+ * fetched 2026-09-25, cross-checked against the same content served at
+ * https://learn.chatgpt.com/docs/hooks):
+ *   config  — <repo>/.codex/hooks.json (or ~/.codex/hooks.json), a dedicated
+ *             file, NOT config.toml's [hooks] table. Codex runs matching
+ *             hooks from every location that defines them, so this adapter
+ *             deliberately touches only hooks.json.
+ *   stdin   — JSON with session_id, transcript_path (string|null), cwd,
+ *             hook_event_name, turn_id, stop_hook_active, permission_mode,
+ *             and last_assistant_message (string|null) — the agent's final
+ *             text for this turn, given directly, no transcript parse needed.
+ *   output  — "Stop expects JSON on stdout when it exits 0. Plain text output
+ *             is invalid for this event." Block: {"decision":"block","reason":
+ *             "..."}. Allow: any other JSON (this adapter always writes "{}"
+ *             so stdout is valid JSON on every path, including R5 failures).
+ *
+ * R9 (exempt a human-directed stop) is best-effort here. Codex's Stop payload
+ * gives the assistant's last message directly but not the human's; this
+ * adapter tries transcript_path for it (rollout.jsonl), tolerantly, because
+ * its exact schema was not confirmed against a real Codex install at
+ * authoring time. If that read fails or the field is null, the user side is
+ * treated as empty — which means R9 cannot exempt that turn, not that the
+ * check goes silent (last_assistant_message still drives detection). This is
+ * the documented gap in core/turn-completion-integrity.md's Codex section.
+ *
+ * Judgement (packs, cooldown, rolling window, self-echo) lives in
+ * turn-completion/engine.mjs and is shared with every other adapter; this
+ * file only reads Codex's stdin shape and writes Codex's output shape.
+ *
+ * Usage: node check-turn-completion-codex.mjs  (reads stdin)
+ *        node check-turn-completion-codex.mjs --self-test
+ *        node check-turn-completion-codex.mjs --languages
+ *
+ * @see core/turn-completion-integrity.md
+ */
+import { readFileSync } from 'node:fs';
+import { decide, isSelfEcho, runSelfTest, printLanguages } from './turn-completion/engine.mjs';
+
+/**
+ * Best-effort extraction of the human's last message from a Codex transcript.
+ * Tolerant of several plausible JSONL shapes because the exact rollout.jsonl
+ * schema was not confirmed against a real install; any failure returns '',
+ * which is the same as "cannot tell" (R5) — it does not stop
+ * last_assistant_message from still being checked.
+ */
+function bestEffortLastUserMessage(transcriptPath) {
+  if (typeof transcriptPath !== 'string' || !transcriptPath) return '';
+  try {
+    let user = '';
+    for (const line of readFileSync(transcriptPath, 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      let ev;
+      try { ev = JSON.parse(line); } catch { continue; }
+      // Try a few plausible shapes rather than committing to one: a nested
+      // { message: { role, content } } (Claude-Code-style rollout entry), or
+      // a flat { role, content }.
+      const msg = (ev && ev.message) || ev;
+      if (!msg || msg.role !== 'user') continue;
+      const c = msg.content;
+      const text = typeof c === 'string'
+        ? c
+        : Array.isArray(c)
+          ? c.filter((p) => p && (p.type === 'text' || typeof p.text === 'string')).map((p) => p.text || '').join('\n')
+          : '';
+      if (text && text.trim() && !isSelfEcho(text)) user = text;
+    }
+    return user;
+  } catch {
+    return '';
+  }
+}
+
+async function main() {
+  let out = {};
+  try {
+    const raw = readFileSync(0, 'utf8');
+    const data = JSON.parse(raw);
+    if (data && typeof data === 'object' && data.stop_hook_active !== true) {
+      const assistantText = typeof data.last_assistant_message === 'string' ? data.last_assistant_message : '';
+      const userText = bestEffortLastUserMessage(data.transcript_path);
+      const verdict = await decide({
+        sessionId: data.session_id,
+        assistantText,
+        userText,
+      });
+      if (verdict.fire) out = { decision: 'block', reason: verdict.reason };
+    }
+  } catch {
+    /* R5: fail open — stdout stays valid JSON, turn ends */
+  }
+  process.stdout.write(JSON.stringify(out));
+}
+
+const arg = process.argv[2];
+if (arg === '--self-test') {
+  process.exit((await runSelfTest('turn-completion-codex')) ? 0 : 1);
+} else if (arg === '--languages') {
+  await printLanguages();
+} else {
+  try {
+    await main();
+  } catch {
+    // R5, belt and braces: main() already guards its own body, but a Codex
+    // Stop hook must exit 0 with valid JSON on stdout no matter what, and an
+    // uncaught throw here would instead crash with a non-zero exit and a
+    // stack trace on stderr.
+    process.stdout.write('{}');
+  }
+}

package/bundled/hooks/check-turn-completion-gemini.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * UDS Hook: Turn Completion Integrity — Gemini CLI adapter
+ *
+ * Runs once per turn, after the model's final response. Blocks when that
+ * response states a first-person commitment to a next action that the turn
+ * then ended without taking.
+ *
+ * Contract (Gemini CLI AfterAgent hook — https://geminicli.com/docs/hooks/reference/
+ * and https://geminicli.com/docs/hooks/, fetched 2026-09-25):
+ *   config  — .gemini/settings.json (project) / ~/.gemini/settings.json
+ *             (user) / /etc/gemini-cli/settings.json (system), under a
+ *             "hooks" key shared with the rest of Gemini CLI's settings.
+ *             Project settings take precedence over user, which take
+ *             precedence over system. AfterAgent does not use matchers
+ *             (matchers apply only to Tool hooks).
+ *   stdin   — JSON with session_id, transcript_path, cwd, hook_event_name,
+ *             timestamp, prompt, prompt_response, stop_hook_active.
+ *             `prompt` is the human message that started THIS turn and
+ *             `prompt_response` is the agent's final text for it — both given
+ *             directly, so R9 (exempt a human-directed stop) needs no
+ *             transcript parsing here, unlike the Codex adapter.
+ *   output  — exit codes are shared across every Gemini CLI hook type: "0:
+ *             stdout is parsed as JSON. Preferred for all logic. 2: System
+ *             Block, stderr is the rejection reason." AfterAgent's own JSON
+ *             shape: {"decision":"deny","reason":"..."} rejects the response
+ *             and forces a retry, with reason "sent to the agent as a new
+ *             prompt". This adapter uses the preferred exit-0 + JSON path,
+ *             not exit code 2, and always writes valid JSON on stdout
+ *             (including on every R5 failure path) so exit 0 is never
+ *             ambiguous with "nothing to say".
+ *
+ * Judgement (packs, cooldown, rolling window, self-echo) lives in
+ * turn-completion/engine.mjs and is shared with every other adapter; this
+ * file only reads Gemini CLI's stdin shape and writes Gemini CLI's output
+ * shape.
+ *
+ * Usage: node check-turn-completion-gemini.mjs  (reads stdin)
+ *        node check-turn-completion-gemini.mjs --self-test
+ *        node check-turn-completion-gemini.mjs --languages
+ *
+ * @see core/turn-completion-integrity.md
+ */
+import { readFileSync } from 'node:fs';
+import { decide, runSelfTest, printLanguages } from './turn-completion/engine.mjs';
+
+async function main() {
+  let out = {};
+  try {
+    const raw = readFileSync(0, 'utf8');
+    const data = JSON.parse(raw);
+    if (data && typeof data === 'object' && data.stop_hook_active !== true) {
+      const assistantText = typeof data.prompt_response === 'string' ? data.prompt_response : '';
+      const userText = typeof data.prompt === 'string' ? data.prompt : '';
+      const verdict = await decide({
+        sessionId: data.session_id,
+        assistantText,
+        userText,
+      });
+      if (verdict.fire) out = { decision: 'deny', reason: verdict.reason };
+    }
+  } catch {
+    /* R5: fail open — stdout stays valid JSON, turn ends */
+  }
+  process.stdout.write(JSON.stringify(out));
+}
+
+const arg = process.argv[2];
+if (arg === '--self-test') {
+  process.exit((await runSelfTest('turn-completion-gemini')) ? 0 : 1);
+} else if (arg === '--languages') {
+  await printLanguages();
+} else {
+  try {
+    await main();
+  } catch {
+    // R5, belt and braces — see check-turn-completion-codex.mjs for why this
+    // outer guard exists alongside main()'s own.
+    process.stdout.write('{}');
+  }
+}