universal-dev-standards 6.8.0 → 6.10.0

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

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/**
+ * UDS Hook: Turn Completion Integrity
+ *
+ * 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 (Claude Code Stop hook):
+ *   stdin  — JSON with session_id, transcript_path, stop_hook_active
+ *   block  — print {"decision":"block","reason":"..."} on stdout, exit 0
+ *   allow  — print nothing, exit 0
+ *
+ * Every failure path allows. See core/turn-completion-integrity.md R5: a hook
+ * that can trap a session is worse than none, because the only recovery a human
+ * has is to disable it, and they will disable it permanently.
+ *
+ * Usage: node check-turn-completion.mjs  (reads stdin)
+ *        node check-turn-completion.mjs --self-test
+ *        node check-turn-completion.mjs --languages
+ *
+ * @see docs/specs/SPEC-HOOKS-001-core-standard-hooks.md
+ * @see core/turn-completion-integrity.md
+ */
+import { readFileSync, mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectCommitment, userAskedToStop } from './turn-completion/detect.mjs';
+
+export const VERSION = '1.1.0';
+
+const COOLDOWN_SEC = 120;
+// A cap counted per session with no reset is an off switch on a delay: it
+// disarms silently in exactly the long session where the rule matters most.
+// A rolling window bounds runaway loops just as well and recovers by itself.
+const MAX_BLOCKS_PER_WINDOW = 6;
+const WINDOW_SEC = 3600;
+
+const STATE_DIR = join(homedir(), '.uds', 'turn-completion');
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Locales this hook ships. The self-test fails if any of them will not load. */
+export const SHIPPED_LOCALES = ['en', 'zh-TW'];
+
+/**
+ * Load every shipped locale pack.
+ *
+ * At runtime a pack that fails to load is skipped (R5: a broken pack must not
+ * stop the turn from ending). 🔴 But that swallow is also how a shipping
+ * mistake hides: with zero packs loaded the hook runs, exits 0, and can never
+ * fire — the same shape as good behaviour. So `failed` is returned rather than
+ * discarded, and the self-test treats a non-empty `failed` as a failure.
+ * Caught while renaming the packs to .mjs: the loader still asked for .js.
+ */
+export async function loadPacks() {
+  const packs = [];
+  const failed = [];
+  for (const id of SHIPPED_LOCALES) {
+    try {
+      packs.push(await import(join(HERE, 'turn-completion', 'locales', `${id}.mjs`)));
+    } catch (e) {
+      failed.push({ id, why: String((e && e.message) || e) });
+    }
+  }
+  return { packs, failed };
+}
+
+/**
+ * 🔴 This hook's own block message enters the transcript as a user turn. On the
+ * next run it would therefore be read as "the human's last message", hiding the
+ * real one ("pause, I'm going home") and silently voiding the R9 exemption.
+ *
+ * Same family as the detector matching the prose that documents it — except
+ * here it reads its own output. The reason string carries this line so it can
+ * recognise itself.
+ */
+export const SELF_ECHO = 'UDS standard turn-completion-integrity (R1)';
+
+/** Plain text of a transcript message, or '' if it carries none. */
+function textOf(msg) {
+  const c = msg && msg.content;
+  if (typeof c === 'string') return c;
+  if (!Array.isArray(c)) return '';
+  // Tool results also arrive with role "user"; only text blocks are prose.
+  const parts = c.filter((p) => p && p.type === 'text').map((p) => p.text || '');
+  return parts.some((p) => p.trim()) ? parts.join('\n') : '';
+}
+
+/**
+ * Last assistant message and last human message in a Claude Code JSONL
+ * transcript. The human's message is needed because a turn that ends by their
+ * instruction looks, from the agent's words alone, exactly like one that ends
+ * on an abandoned commitment.
+ */
+export function lastMessages(transcriptPath) {
+  let assistant = '';
+  let user = '';
+  for (const line of readFileSync(transcriptPath, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    let ev;
+    try { ev = JSON.parse(line); } catch { continue; }
+    const msg = ev && ev.message;
+    if (!msg) continue;
+    const t = textOf(msg);
+    if (!t) continue;
+    if (msg.role === 'assistant') assistant = t;
+    else if (msg.role === 'user' && !t.includes(SELF_ECHO)) user = t;
+  }
+  return { assistant, user };
+}
+
+function readState(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return {}; }
+}
+
+function reason(packId, sentence) {
+  return [
+    'Your last message stated a next action, and then the turn ended without taking it.',
+    '',
+    `Detected by the ${packId} pack, in: "${sentence}"`,
+    '',
+    'UDS standard turn-completion-integrity (R1): a stated next action is not optional.',
+    '',
+    'Do one of these now:',
+    '  (a) take the action you just said you would take;',
+    '  (b) if it is actually blocked, say what blocks it and what you need, then do',
+    '      the next item that is not blocked;',
+    '  (c) if everything is done or blocked, list every remaining item WITH the',
+    '      person or input it waits on. That itemized list is the only shape of',
+    '      ending that R2 accepts — "the main parts are done" is not one.',
+  ].join('\n');
+}
+
+async function main() {
+  let raw = '';
+  try {
+    raw = readFileSync(0, 'utf8');
+  } catch {
+    return;
+  }
+
+  let data;
+  try { data = JSON.parse(raw); } catch { return; }
+  if (!data || typeof data !== 'object') return;
+  if (data.stop_hook_active === true) return;
+
+  const tp = data.transcript_path;
+  if (!tp || !existsSync(tp)) return;   // cannot tell is not the same as should block
+
+  const sid = String(data.session_id || 'unknown');
+  const statePath = join(STATE_DIR, `${sid}.json`);
+  const st = readState(statePath);
+  const now = Date.now() / 1000;
+
+  const stamps = (Array.isArray(st.stamps) ? st.stamps : [])
+    .filter((t) => typeof t === 'number' && now - t < WINDOW_SEC);
+  if (stamps.length >= MAX_BLOCKS_PER_WINDOW) return;
+  if (now - (st.last || 0) < COOLDOWN_SEC) return;
+
+  let msgs;
+  try { msgs = lastMessages(tp); } catch { return; }
+  if (!msgs.assistant.trim()) return;
+
+  const { packs } = await loadPacks();
+  if (packs.length === 0) return;
+
+  // The human asked for the turn to end. That is a legitimate ending, and the
+  // agent's own words cannot distinguish it from an abandoned commitment.
+  if (userAskedToStop(msgs.user, packs)) return;
+
+  const hit = detectCommitment(msgs.assistant, packs);
+  if (!hit.fired) return;
+
+  stamps.push(now);
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(statePath, JSON.stringify({ stamps, last: now }));
+  } catch {
+    /* state is an optimisation; failing to write it must not change the verdict */
+  }
+
+  process.stdout.write(JSON.stringify({
+    decision: 'block',
+    reason: reason(hit.packId, hit.sentence),
+  }));
+}
+
+async function selfTest() {
+  const { packs, failed } = await loadPacks();
+  let ok = failed.length === 0 && packs.length === SHIPPED_LOCALES.length;
+  console.log(`[turn-completion] v${VERSION} — packs: ${packs.map((p) => p.id).join(', ')}`
+    + ` (${packs.length}/${SHIPPED_LOCALES.length} shipped locales)`);
+  for (const f of failed) console.log(`  x   locale ${f.id} failed to load — ${f.why}`);
+
+  for (const pack of packs) {
+    for (const [want, label, text] of pack.corpus) {
+      // Run against ALL packs, which is the shipped configuration. A pack that
+      // is correct alone and wrong beside another is not correct.
+      const got = detectCommitment(text, packs).fired;
+      const good = got === want;
+      ok &&= good;
+      console.log(`  ${good ? 'OK ' : 'x  '} [${pack.id}] ${want ? 'must block' : 'must pass'} — ${label}`
+        + (good ? '' : `   (got: ${got ? 'block' : 'pass'})`));
+    }
+    for (const [want, label, text] of pack.stopCorpus || []) {
+      const got = userAskedToStop(text, packs);
+      const good = got === want;
+      ok &&= good;
+      console.log(`  ${good ? 'OK ' : 'x  '} [${pack.id}] user ${want ? 'IS' : 'is NOT'} asking to stop — ${label}`
+        + (good ? '' : `   (got: ${got ? 'exempt' : 'not exempt'})`));
+    }
+  }
+  // The block message must contain the marker, or the hook cannot tell its own
+  // output from the human's next instruction.
+  const selfRecognised = reason('en', 'x').includes(SELF_ECHO);
+  ok &&= selfRecognised;
+  console.log(`  ${selfRecognised ? 'OK ' : 'x  '} block message carries the self-echo marker`);
+
+  console.log(`[turn-completion] self-test ${ok ? 'passed' : 'FAILED'}`);
+  process.exit(ok ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--self-test') {
+  await selfTest();
+} else if (arg === '--languages') {
+  const { packs } = await loadPacks();
+  console.log(packs.map((p) => `${p.id} (${p.label})`).join('\n'));
+  console.log('\nThis check reads prose. If you work in a language not listed above,'
+    + '\nit is installed and running but cannot fire. See turn-completion-integrity R8.');
+} else {
+  try { await main(); } catch { /* R5 */ }
+}

package/bundled/hooks/inject-standards.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * UDS Hook-Based Standard Injection
+ * Claude Code UserPromptSubmit hook that reads the user's prompt,
+ * matches it against manifest.json domain triggers, and outputs
+ * matching standard file paths as additional context.
+ *
+ * Usage: Configured as a Claude Code hook in .claude/settings.json
+ *
+ * Performance target: < 500ms
+ * Error handling: failures are non-blocking (exit 0 with empty output)
+ */
+
+import { readFileSync, existsSync, appendFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function findManifest(cwd) {
+  const paths = [
+    join(cwd, '.standards', 'manifest.json'),
+    join(cwd, 'manifest.json'),
+  ];
+  for (const p of paths) {
+    try {
+      return JSON.parse(readFileSync(p, 'utf-8'));
+    } catch {
+      // continue
+    }
+  }
+  return null;
+}
+
+function matchDomains(prompt, manifest) {
+  const matched = new Set();
+  const promptLower = prompt.toLowerCase();
+
+  const allDomains = { ...(manifest.domains || {}) };
+
+  // Add custom domains from extensions
+  for (const ext of manifest.extensions || []) {
+    if (ext.type === 'custom-domain' && ext.domain && ext.triggers) {
+      allDomains[ext.domain] = {
+        _triggers: ext.triggers,
+        _standards: ext.standards || [],
+        _isCustom: true,
+      };
+    }
+  }
+
+  for (const [domainName, domainValue] of Object.entries(allDomains)) {
+    if (domainName === 'always-on') continue;
+
+    // Get triggers: from ai.yaml structure or custom domain
+    let triggers = [];
+    if (domainValue._isCustom) {
+      triggers = domainValue._triggers;
+    } else {
+      // Built-in domains don't store triggers in manifest.json,
+      // use the domain name and known command patterns
+      const domainTriggerMap = {
+        testing: ['test', 'coverage', '/tdd', '/bdd', '/atdd', '/coverage', '.test.', '.spec.'],
+        specification: ['/sdd', '/spec', '/derive', '/reverse', '/requirement', 'docs/specs/'],
+        quality: ['/code-review', '/refactor', '/check', 'code review', 'pull request', 'security', 'performance'],
+        documentation: ['/docs', '/changelog', '/generate-docs', 'readme', 'changelog', 'documentation'],
+        workflow: ['/release', '/commit', 'branch', 'merge', 'release', 'deploy', 'version'],
+        architecture: ['architecture', 'project setup', 'error handling', 'logging', 'project structure'],
+        enforcement: ['hook', 'enforce', 'validate', 'dangerous', 'security check', 'logging check'],
+      };
+      triggers = domainTriggerMap[domainName] || [domainName];
+    }
+
+    for (const trigger of triggers) {
+      const triggerLower = trigger.toLowerCase();
+      if (triggerLower.startsWith('/')) {
+        // Slash command match
+        if (promptLower.includes(triggerLower)) {
+          if (domainValue._isCustom) {
+            domainValue._standards.forEach(s => matched.add(s));
+          } else if (Array.isArray(domainValue)) {
+            domainValue.forEach(s => matched.add(s));
+          }
+          break;
+        }
+      } else if (triggerLower.includes('*')) {
+        // File pattern — check if prompt mentions matching files
+        const pattern = triggerLower.replace(/\*/g, '');
+        if (promptLower.includes(pattern)) {
+          if (domainValue._isCustom) {
+            domainValue._standards.forEach(s => matched.add(s));
+          } else if (Array.isArray(domainValue)) {
+            domainValue.forEach(s => matched.add(s));
+          }
+          break;
+        }
+      } else {
+        // Keyword match
+        if (promptLower.includes(triggerLower)) {
+          if (domainValue._isCustom) {
+            domainValue._standards.forEach(s => matched.add(s));
+          } else if (Array.isArray(domainValue)) {
+            domainValue.forEach(s => matched.add(s));
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  return [...matched];
+}
+
+async function main() {
+  try {
+    // Read stdin
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    const input = JSON.parse(Buffer.concat(chunks).toString());
+
+    const prompt = input.prompt || '';
+    const cwd = input.cwd || process.cwd();
+
+    if (!prompt) {
+      process.exit(0);
+    }
+
+    const manifest = findManifest(cwd);
+    if (!manifest) {
+      process.exit(0);
+    }
+
+    const matchedStandards = matchDomains(prompt, manifest);
+
+    // Record hook stats (silent, non-blocking)
+    try {
+      const configPath = join(cwd, '.uds', 'config.json');
+      let statsEnabled = false; // Default OFF — opt-in via .uds/config.json
+      try {
+        if (existsSync(configPath)) {
+          const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+          if (config.hookStats === true) statsEnabled = true;
+        }
+      } catch { /* default disabled */ }
+
+      if (statsEnabled) {
+        const statsDir = join(cwd, '.uds');
+        if (!existsSync(statsDir)) mkdirSync(statsDir, { recursive: true });
+        const statsPath = join(statsDir, 'hook-stats.jsonl');
+        const record = JSON.stringify({
+          timestamp: new Date().toISOString(),
+          matched_standards: matchedStandards.map(s => s.replace(/.*\//, '').replace('.ai.yaml', '')),
+          matched_count: matchedStandards.length,
+          total_available: Object.keys(manifest.domains || {}).length,
+          prompt_length: prompt.length
+        });
+        appendFileSync(statsPath, record + '\n');
+      }
+    } catch { /* silent failure — never block hook */ }
+
+    if (matchedStandards.length === 0) {
+      process.exit(0);
+    }
+
+    // Output as additional context
+    const context = [
+      '[UDS Context-Aware Loading] Matched standards for this prompt:',
+      ...matchedStandards.map(s => `  - ${s}`),
+      '',
+      'Load these standards if not already in context.',
+    ].join('\n');
+
+    process.stdout.write(context);
+    process.exit(0);
+  } catch {
+    // Non-blocking: exit 0 on any error
+    process.exit(0);
+  }
+}
+
+main();

package/bundled/hooks/telemetry-wrapper.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * UDS Hook Telemetry Wrapper
+ *
+ * Records hook execution telemetry to .standards/telemetry.jsonl.
+ * Format: {timestamp, standard_id, hook_type, result, duration_ms}
+ *
+ * If telemetryUpload=true and telemetryApiKey≠"" in .uds/config.json,
+ * also uploads the result to the remote telemetry server (opt-in).
+ *
+ * @see docs/specs/SPEC-TELEMETRY-001-hook-telemetry.md (REQ-1)
+ * @see docs/specs/SPEC-TELEMETRY-002-hook-upload.md
+ */
+
+import { existsSync, readFileSync, appendFileSync, mkdirSync, statSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+
+export const TELEMETRY_FILE = '.standards/telemetry.jsonl';
+const MAX_TELEMETRY_SIZE = 2 * 1024 * 1024; // 2MB
+
+/**
+ * Record a hook execution telemetry entry.
+ * @param {string} projectPath - Project root path
+ * @param {{ standard_id: string, hook_type: string, exitCode: number, duration_ms: number }} entry
+ */
+export function recordTelemetry(projectPath, entry) {
+  try {
+    const telPath = join(projectPath, TELEMETRY_FILE);
+    const dir = dirname(telPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    const record = {
+      timestamp: new Date().toISOString(),
+      standard_id: entry.standard_id,
+      hook_type: entry.hook_type,
+      result: entry.exitCode === 0 ? 'pass' : 'fail',
+      duration_ms: entry.duration_ms,
+    };
+
+    // Rotation: truncate if exceeding 2MB
+    if (existsSync(telPath)) {
+      try {
+        const size = statSync(telPath).size;
+        if (size > MAX_TELEMETRY_SIZE) {
+          const content = readFileSync(telPath, 'utf-8');
+          const lines = content.trim().split('\n');
+          const keepLines = lines.slice(Math.floor(lines.length / 2));
+          writeFileSync(telPath, keepLines.join('\n') + '\n');
+        }
+      } catch { /* ignore rotation errors */ }
+    }
+
+    appendFileSync(telPath, JSON.stringify(record) + '\n');
+  } catch {
+    // Silently ignore write failures
+  }
+}
+
+/**
+ * Upload hook result to remote telemetry server (opt-in via .uds/config.json).
+ * Silently fails — never blocks hook execution.
+ *
+ * @param {string} projectPath - Project root path
+ * @param {{ standard_id: string, hook_type: string, exitCode: number, duration_ms: number }} entry
+ * @returns {Promise<void>}
+ */
+export async function uploadTelemetry(projectPath, entry) {
+  try {
+    // Dynamic import to avoid blocking if CLI module not available in hook context
+    const { uploadHookTelemetry } = await import('../../cli/src/utils/telemetry-uploader.js');
+    await uploadHookTelemetry(projectPath, entry);
+  } catch {
+    // Silently ignore upload failures (AC-4: never block hook)
+  }
+}

package/bundled/hooks/turn-completion/detect.mjs

@@ -0,0 +1,99 @@
+/**
+ * Shared text preparation and pack runner for the turn-completion check.
+ *
+ * The language-specific part lives in ./locales/<id>.js. This file holds only
+ * what is true of every language, so that adding a language cannot accidentally
+ * change the behaviour of the ones already shipped.
+ *
+ * @see core/turn-completion-integrity.md (R7)
+ */
+
+/**
+ * Remove the parts of a message that quote a pattern rather than enact it.
+ *
+ * Every exclusion here was added because its absence produced a false block:
+ * a detector reliably matches the text that documents it. Fenced code, inline
+ * backticks and markdown table rows are all places where an example of a
+ * commitment gets written down without anyone committing to anything.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function stripNonProse(text) {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .split('\n')
+    .filter((line) => !line.trimStart().startsWith('|'))
+    .filter((line) => !line.trimStart().startsWith('>'))
+    .join('\n')
+    .replace(/`[^`\n]*`/g, ' ');
+}
+
+/** Split into paragraphs on blank lines. */
+export function splitParagraphs(text) {
+  return text.split(/\n\s*\n/).filter((p) => p.trim());
+}
+
+/**
+ * Split into sentences.
+ *
+ * Judgement is made per sentence, never per paragraph: a negated clause
+ * followed by a real commitment produces exactly one paragraph-level match,
+ * and the negation swallows the commitment.
+ */
+export function splitSentences(text) {
+  return text.split(/[.!?。！？\n]+/).filter((s) => s.trim());
+}
+
+/**
+ * Did the human ask for the turn to end?
+ *
+ * 🔴 The check reads only the agent's final message, so a turn that ends
+ * because the human said "pause, I'm going home" is indistinguishable from one
+ * that ends on an abandoned commitment — the agent's words are the same in both.
+ * Measured 2026-09-08: the first real firing after shipping was exactly this.
+ *
+ * A user-directed stop is the one legitimate ending the message-only design
+ * cannot represent, so the check has to look at the other side of the exchange.
+ *
+ * @param {string} text - the human's most recent message
+ * @param {Array<{isStopRequest: (t: string) => boolean}>} packs
+ * @returns {boolean}
+ */
+export function userAskedToStop(text, packs) {
+  if (!text || !text.trim()) return false;
+  return packs.some((p) => typeof p.isStopRequest === 'function' && p.isStopRequest(text));
+}
+
+/**
+ * Run every locale pack over one message.
+ *
+ * All packs run, and any one of them firing is enough. A bilingual transcript
+ * is the normal case, not the exception, and asking the adopter to configure
+ * which language they write in is a knob that will be set wrong.
+ *
+ * @param {string} text - the assistant's final message
+ * @param {Array<{id: string, isCommitment: (s: string) => boolean, isAsking: (t: string) => boolean}>} packs
+ * @returns {{ fired: boolean, packId: string|null, sentence: string|null }}
+ */
+export function detectCommitment(text, packs) {
+  const body = stripNonProse(text);
+
+  for (const paragraph of splitParagraphs(body)) {
+    // A commitment that shares a paragraph with a request for information is
+    // conditional ("give me X and I will do Y"), not an unkept promise.
+    // Stopping there is correct behaviour, and blocking it teaches the adopter
+    // to uninstall the hook.
+    const asking = packs.some((p) => p.isAsking(paragraph));
+    if (asking) continue;
+
+    for (const sentence of splitSentences(paragraph)) {
+      for (const pack of packs) {
+        if (pack.isCommitment(sentence)) {
+          return { fired: true, packId: pack.id, sentence: sentence.trim().slice(0, 160) };
+        }
+      }
+    }
+  }
+  return { fired: false, packId: null, sentence: null };
+}