universal-dev-standards 6.7.5 → 6.9.0

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 };
+}

package/bundled/hooks/turn-completion/locales/en.mjs

@@ -0,0 +1,159 @@
+/**
+ * English locale pack for the turn-completion check.
+ *
+ * Design note — why there is no verb whitelist.
+ * The Traditional Chinese detector this was derived from was defeated twice by
+ * its own lesson: version one enumerated phrases and missed a phrase; version
+ * two enumerated verbs and missed a verb. Swapping a phrase list for a verb
+ * list is still enumeration, one layer down.
+ *
+ * English gets the inverted shape: take whatever word follows the future
+ * marker and treat it as an action UNLESS it is in a small, closed list of
+ * verbs that describe rather than do. The blacklist can be enumerated honestly
+ * because "verbs that are not work" is a bounded set; "verbs that are work" is
+ * not.
+ *
+ * @see core/turn-completion-integrity.md
+ */
+
+/** Verbs that report, decide-not-to, or legitimately wait. Following one is not a commitment to work. */
+const NON_ACTION = new Set([
+  // describing rather than doing
+  'say', 'says', 'said', 'note', 'noted', 'mention', 'explain', 'describe',
+  'report', 'summarize', 'summarise', 'list', 'show', 'tell', 'clarify',
+  'quote', 'point', 'highlight', 'flag', 'call', 'answer', 'respond', 'reply',
+  // stating a belief, not an action
+  'know', 'think', 'assume', 'believe', 'remember', 'recommend', 'suggest', 'propose',
+  // a legitimate stop: the next move is not the agent's
+  'wait', 'hold', 'pause', 'defer', 'stop', 'skip', 'leave', 'need', 'want', 'require',
+]);
+
+/** Reported speech: a reporting verb governing a clause. "when I say I will do X" is narration. */
+const REPORTED_SPEECH =
+  /\b(say|says|said|saying|note|noted|noting|mention|mentioned|tell|told|report|reported|write|wrote|claim|claimed|promise|promised)\b\s+(that\s+)?(I|you|we|it|he|she|they)\b/i;
+
+const NEGATION = /\b(not|never|no longer|neither|nor)\b/i;
+
+/**
+ * A reporting verb sitting between "I" and the future marker means the sentence
+ * describes a commitment rather than making one: "when I say I will do X".
+ * Dropping this check let exactly that sentence block on the first corpus run.
+ */
+const REPORTING =
+  /\b(say|says|said|saying|note|noted|mention|mentioned|tell|told|report|reported|write|wrote|claim|claimed|promise|promised|explain|explained)\b/i;
+
+/** Requests for information from the human. A commitment beside one is conditional. */
+const ASKING =
+  /(\bshould I\b|\bdo you want\b|\bwould you like\b|\bwhich (one|file|option)\b|\blet me know\b|\btell me\b|\bgive me\b|\bpaste\b|\bwaiting on you\b|\byour call\b|\bup to you\b|\?)/i;
+
+/**
+ * Expand contractions so the patterns below never have to fight an apostrophe.
+ * Both the ASCII and typographic apostrophes appear in real transcripts.
+ */
+export function normalize(text) {
+  return text
+    .replace(/[‘’]/g, "'")
+    .replace(/\bI'll\b/gi, 'I will')
+    .replace(/\bI'm\b/gi, 'I am')
+    .replace(/\bI've\b/gi, 'I have')
+    .replace(/\bwon't\b/gi, 'will not')
+    .replace(/\bcan't\b/gi, 'can not')
+    .replace(/n't\b/gi, ' not');
+}
+
+const FUTURE = '(?:will|am going to|going to|am about to|about to)';
+// Adverbs and filler between the future marker and the verb it governs.
+const FILLER = "(?:not|never|also|then|now|next|first|just|be|still|already|soon|finally|quickly|\\w+ly)";
+const COMMIT = new RegExp(
+  `\\bI\\b([^.!?\\n]{0,10}?)\\b${FUTURE}\\b((?:\\s+${FILLER}\\b|\\s*,)*)\\s+([a-z][a-z-]*)`,
+  'gi'
+);
+const LET_ME = /\blet me\b\s+((?:(?:just|now|first|quickly|\w+ly)\s+)*)([a-z][a-z-]*)/gi;
+
+/** Does this sentence contain an unconditional first-person commitment to a next action? */
+export function isCommitment(sentence) {
+  const s = normalize(sentence);
+
+  for (const re of [COMMIT, LET_ME]) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(s)) !== null) {
+      const isLetMe = re === LET_ME;
+      const gap = isLetMe ? '' : m[1];
+      const filler = isLetMe ? m[1] : m[2];
+      const verb = (isLetMe ? m[2] : m[3]).toLowerCase();
+
+      if (NON_ACTION.has(verb)) continue;
+      if (NEGATION.test(gap) || NEGATION.test(filler)) continue;
+      if (REPORTING.test(gap)) continue;
+      // A reporting verb governing a clause anywhere earlier in the sentence
+      // means this is narration about a commitment, not a commitment.
+      if (REPORTED_SPEECH.test(s.slice(0, m.index + 2))) continue;
+      return true;
+    }
+  }
+  return false;
+}
+
+export function isAsking(text) {
+  return ASKING.test(normalize(text));
+}
+
+/**
+ * The human asking for the turn to end. Deliberately narrow: a false positive
+ * here disables the check for the rest of the session, which is worse than a
+ * missed block. It must read as an instruction to stop, not a mention of
+ * stopping.
+ */
+const STOP_REQUEST =
+  /(\blet's (stop|pause|pick this up later)\b|\b(pause|stop) (here|for now|there)\b|\bhold (on|off)\b|\bthat's (enough|it) for (now|today)\b|\b(done|enough) for (now|today)\b|\bwrap (it |this )?up\b|\bcontinue (this )?later\b|\bpick (this|it) up (tomorrow|later)\b|\btake a break\b|\bI'?m (heading|going) (home|out)\b|\bgood ?night\b)/i;
+
+export function isStopRequest(text) {
+  return STOP_REQUEST.test(normalize(text));
+}
+
+export const id = 'en';
+export const label = 'English';
+
+/**
+ * The corpus. This is the pack's contract: it runs in CI, and a pack whose
+ * corpus does not pass is not shipped. Cases marked `true` must block; cases
+ * marked `false` must let the turn end.
+ */
+export const corpus = [
+  [true, 'plain commitment', 'I will update the remaining two files.'],
+  [true, 'contraction + filler', "I'll go ahead and rewrite the detector."],
+  [true, 'going to', "Next I'm going to run the test suite."],
+  [true, 'let me', 'Let me fix the exclusion and re-run the corpus.'],
+  [true, 'about to', "I'm about to move on to the next item in the same class."],
+  [true, 'negation then a real commitment in the next sentence',
+    'I will not touch that config. I will wire the gate into CI next.'],
+  [false, 'past tense report', 'I said I would fix it, and the commit is pushed.'],
+  [false, 'negation', "I won't be changing that config."],
+  [false, 'asking', 'Should I update the remaining files, or leave them?'],
+  [false, 'narrating the pattern', 'The hook fires when I say I will do something and then stop.'],
+  // Only REPORTED_SPEECH catches this one: the gap between "I" and "will" is
+  // empty, so the gap-level reporting check cannot see the "said that".
+  // Added after mutation testing showed REPORTED_SPEECH could be deleted with
+  // the corpus staying green — an unproven guard is indistinguishable from a
+  // dead one.
+  [false, 'third-person reported speech', 'You said that I will handle the merge.'],
+  [false, 'reporting verb as the action', "I'll explain why the exclusion exists."],
+  [false, 'legitimate stop: the next move is the human\'s', 'I will wait for your key before deploying.'],
+  [false, 'conditional: asking in the same paragraph',
+    'Tell me which file you meant and I will check it.'],
+];
+
+/**
+ * Messages from the human, and whether each one ends the turn by request.
+ * Marked `true` must exempt; marked `false` must NOT — a message that merely
+ * mentions stopping is not an instruction to stop.
+ */
+export const stopCorpus = [
+  [true, 'plain pause', "Let's pause here, I'm heading home."],
+  [true, 'enough for today', "That's enough for today, we can continue later."],
+  [true, 'hold on', 'Hold on, I need to step out.'],
+  [false, 'mentions stopping but is not one', 'Explain why the hook stops the turn.'],
+  [false, 'asks for work', 'Stop using the hardcoded list and walk the registry instead.'],
+  [false, 'ordinary instruction', 'Fix the detector and push it.'],
+];