wogiflow 2.26.2 → 2.29.0

package/scripts/flow-skeptical-evaluator.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Flow — Skeptical Evaluator (wf-15175dbc / B5).
+ *
+ * Validating-phase agent that reads the spec + delivery, then forces the AI
+ * through a field-by-field enumeration before letting a "done" claim stand.
+ *
+ * The evaluator composes a prompt with three enumeration passes:
+ *   1. UI-field enumeration  — for every modified UI surface, list every
+ *      input/select/textarea/custom field. Reuses the B3 template schema.
+ *   2. API-parameter enumeration — for every touched endpoint, list every
+ *      request/response field.
+ *   3. State-key enumeration — for every touched state file or config key,
+ *      list every entry.
+ *
+ * For each enumerated item, the evaluator demands a Tier classification
+ * (reuse flow-completion-truth-gate EVIDENCE_TIERS) and a confidencePct
+ * per the 95/85/75 rubric (wf-f14dcfeb / A4).
+ *
+ * Composition flow (orchestrator calls this, then invokes Agent tool with the prompt):
+ *   const { buildSkepticalPrompt, parseSkepticalOutput } = require('./flow-skeptical-evaluator');
+ *   const prompt = buildSkepticalPrompt({ specMarkdown, diffText, changedFiles, taskId });
+ *   // ... orchestrator invokes Agent tool with prompt ...
+ *   const result = parseSkepticalOutput(agentResponse, { taskId });
+ *
+ * Story: wf-15175dbc (B5)
+ * Epic: wf-34290000
+ */
+
+const path = require('node:path');
+
+const { PATHS } = require('./flow-paths');
+const { getConfig } = require('./flow-config-loader');
+const {
+  parseBELItems,
+  extractSpecStrings,
+  verifyBELAgainstDelivery,
+  verifySpecBundleCoverage,
+} = require('./flow-completion-truth-gate');
+
+const TEMPLATE_PATH = path.join(PATHS.workflow, 'templates', 'tier3-dom-field-inventory.md');
+
+function _isDisabled() {
+  const cfg = getConfig();
+  const igr = cfg.intentGroundedReasoning || {};
+  if (igr.enabled === false) return { disabled: true, reason: 'igr-disabled' };
+  const se = igr.skepticalEvaluator || {};
+  if (se.enabled === false) return { disabled: true, reason: 'skeptical-evaluator-disabled' };
+  return { disabled: false };
+}
+
+/**
+ * Build the system + user prompt for the skeptical evaluator sub-agent.
+ *
+ * @param {object} opts
+ * @param {string} opts.specMarkdown - spec file content
+ * @param {string} opts.diffText - git diff
+ * @param {string[]} [opts.changedFiles]
+ * @param {string} [opts.commitMessage]
+ * @param {string} [opts.taskId]
+ * @param {string} [opts.bundleText] - built-bundle text if available
+ * @returns {{ systemPrompt: string, userPrompt: string, preChecks: object, metadata: object }}
+ */
+function buildSkepticalPrompt(opts) {
+  if (!opts || typeof opts !== 'object') throw new TypeError('buildSkepticalPrompt: opts required');
+  if (typeof opts.specMarkdown !== 'string') throw new TypeError('buildSkepticalPrompt: specMarkdown required');
+
+  const dis = _isDisabled();
+  if (dis.disabled) {
+    return { systemPrompt: '', userPrompt: '', preChecks: {}, metadata: { skipped: true, reason: dis.reason, taskId: opts.taskId || null } };
+  }
+
+  const { specMarkdown, diffText = '', changedFiles = [], commitMessage = '', taskId = '', bundleText = '' } = opts;
+
+  // Run the mechanical pre-checks so the evaluator is grounded in data, not vibes.
+  const bel = verifyBELAgainstDelivery({ specMarkdown, diffText, changedFiles, commitMessage });
+  const bundle = verifySpecBundleCoverage({ specMarkdown, diffText, changedFiles, bundleText });
+  const belItems = parseBELItems(specMarkdown);
+  const specStrings = extractSpecStrings(specMarkdown);
+
+  const systemPrompt = [
+    '# Skeptical Evaluator',
+    '',
+    'You are the Skeptical Evaluator for WogiFlow\'s validating phase. Your job is to force field-by-field enumeration before a task can be marked "done". Your baseline stance: the claim is unverified until you see every field enumerated and classified.',
+    '',
+    '## Inputs you receive',
+    '',
+    '- The task spec (markdown)',
+    '- The unified diff',
+    '- Changed file paths',
+    '- Commit message (if any)',
+    '- Mechanical pre-check results from `flow-completion-truth-gate` (BEL grep, spec-bundle grep)',
+    '',
+    '## Mandatory enumeration passes',
+    '',
+    '### Pass 1 — UI-field enumeration',
+    'For every modified UI surface (form, filter, wizard, settings panel):',
+    '- List every `<input>`, `<select>`, `<textarea>`, or custom input component by its `name` / `data-testid`.',
+    '- For each: label, type, default, required, validation, visibility condition.',
+    '- Compare to the spec\'s AC. Flag vanished / modified / added fields.',
+    '',
+    'If no UI surfaces touched, state explicitly: "UI-field pass: N/A — no UI files modified."',
+    'Reference template: `' + path.relative(process.cwd(), TEMPLATE_PATH) + '`.',
+    '',
+    '### Pass 2 — API-parameter enumeration',
+    'For every touched API endpoint (request handler, route, or client call):',
+    '- List every request parameter (query, path, body field).',
+    '- List every response field.',
+    '- Compare to the spec\'s AC. Flag additions / removals / type changes.',
+    '',
+    'If no API work touched, state explicitly: "API-parameter pass: N/A."',
+    '',
+    '### Pass 3 — State-key enumeration',
+    'For every touched state file (JSON, YAML, TOML, .env) or config key:',
+    '- List every top-level key and each nested key the change introduces / removes.',
+    '- Compare to the spec\'s AC.',
+    '',
+    'If no state-file work touched, state explicitly: "State-key pass: N/A."',
+    '',
+    '## Evidence tier + confidence tier on every claim',
+    '',
+    'For every enumerated item you classify as preserved/modified/added/vanished, attach:',
+    '- `evidenceTier`: 0–4 per `scripts/flow-runtime-verification.js` EVIDENCE_TIERS',
+    '- `confidencePct`: exactly 95, 85, or 75 per `.workflow/rubrics/confidence-tiers.md`',
+    '- `evidenceNote`: one-line citation (file:line, grep result, or observation)',
+    '',
+    'Confidence 75 automatically flags the claim `UNVERIFIED`. Do not upgrade without evidence.',
+    '',
+    '## Output contract',
+    '',
+    'Return ONE JSON object with shape:',
+    '```json',
+    '{',
+    '  "taskId": "<id>",',
+    '  "uiFieldPass": { "ran": true|false, "reason": "...", "findings": [...] },',
+    '  "apiParameterPass": { ... },',
+    '  "stateKeyPass": { ... },',
+    '  "overallVerdict": "PASS" | "CONCERN" | "FAIL",',
+    '  "blockers": ["one string per blocking issue"],',
+    '  "unverifiedClaims": ["one string per claim at confidence 75"]',
+    '}',
+    '```',
+    '',
+    'No prose. No markdown fences around the JSON. Just the object.',
+  ].join('\n');
+
+  const userPrompt = [
+    '# Inputs',
+    '',
+    `- Task ID: ${taskId || '<unknown>'}`,
+    `- Changed files (${changedFiles.length}): ${changedFiles.slice(0, 20).join(', ')}${changedFiles.length > 20 ? ', ...' : ''}`,
+    '',
+    '## Spec',
+    '```markdown',
+    _truncate(specMarkdown, 12000),
+    '```',
+    '',
+    '## Unified diff',
+    '```',
+    _truncate(diffText, 12000),
+    '```',
+    '',
+    '## Commit message',
+    '```',
+    _truncate(commitMessage, 2000),
+    '```',
+    '',
+    '## Mechanical pre-checks (from flow-completion-truth-gate)',
+    '',
+    '### BEL grep',
+    `- items parsed: ${belItems.length}`,
+    `- ok: ${bel.ok}`,
+    `- uncovered: ${bel.uncoveredItems.length}`,
+    bel.uncoveredItems.length ? `- uncovered samples: ${bel.uncoveredItems.slice(0, 5).map((u) => u.text).join(' | ')}` : '',
+    '',
+    '### Spec-bundle coverage',
+    `- ok: ${bundle.ok}`,
+    ..._bundleSummaryLines(bundle),
+    '',
+    '## Extracted spec strings (reference)',
+    `- backtickIds (${specStrings.backtickIds.length}): ${specStrings.backtickIds.slice(0, 8).join(', ')}`,
+    `- filePaths (${specStrings.filePaths.length}): ${specStrings.filePaths.slice(0, 8).join(', ')}`,
+    `- constants (${specStrings.constants.length}): ${specStrings.constants.slice(0, 8).join(', ')}`,
+    `- routes (${specStrings.routes.length}): ${specStrings.routes.slice(0, 8).join(', ')}`,
+    '',
+    '## Your task',
+    '',
+    'Run the three enumeration passes described in the system prompt. Return the JSON object. Be skeptical — force a verdict on every field.',
+  ].filter(Boolean).join('\n');
+
+  return {
+    systemPrompt,
+    userPrompt,
+    preChecks: { bel, bundle, belItems, specStrings },
+    metadata: { taskId: taskId || null, changedFileCount: changedFiles.length },
+  };
+}
+
+function _truncate(text, cap) {
+  const s = String(text || '');
+  return s.length > cap ? s.slice(0, cap) + `\n\n[... truncated at ${cap} chars]` : s;
+}
+
+function _bundleSummaryLines(bundle) {
+  const out = [];
+  for (const [cat, v] of Object.entries(bundle.coverage || {})) {
+    if (v.total === 0) continue;
+    out.push(`  - ${cat}: ${v.hit}/${v.total} (need ${v.threshold.toFixed(2)})`);
+    if (v.missing && v.missing.length > 0) out.push(`      missing: ${v.missing.slice(0, 4).join(', ')}`);
+  }
+  return out;
+}
+
+/**
+ * Parse the sub-agent's JSON response.
+ * @param {string} response
+ * @param {object} [ctx]
+ * @returns {object}
+ */
+function parseSkepticalOutput(response, ctx = {}) {
+  if (typeof response !== 'string' || response.trim().length === 0) {
+    return { ok: false, reason: 'empty response', overallVerdict: 'FAIL' };
+  }
+  let parsed;
+  try {
+    // Try raw
+    parsed = JSON.parse(response);
+  } catch (_err) {
+    // Try extracting JSON object
+    const m = response.match(/\{[\s\S]*\}/);
+    if (!m) return { ok: false, reason: 'no JSON object found', overallVerdict: 'FAIL' };
+    try {
+      parsed = JSON.parse(m[0]);
+    } catch (err) {
+      return { ok: false, reason: `JSON parse failed: ${err.message}`, overallVerdict: 'FAIL' };
+    }
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return { ok: false, reason: 'response is not an object', overallVerdict: 'FAIL' };
+  }
+  const verdict = parsed.overallVerdict || 'FAIL';
+  return {
+    ok: verdict === 'PASS',
+    overallVerdict: verdict,
+    uiFieldPass: parsed.uiFieldPass || { ran: false },
+    apiParameterPass: parsed.apiParameterPass || { ran: false },
+    stateKeyPass: parsed.stateKeyPass || { ran: false },
+    blockers: Array.isArray(parsed.blockers) ? parsed.blockers : [],
+    unverifiedClaims: Array.isArray(parsed.unverifiedClaims) ? parsed.unverifiedClaims : [],
+    taskId: parsed.taskId || ctx.taskId || null,
+  };
+}
+
+module.exports = {
+  buildSkepticalPrompt,
+  parseSkepticalOutput,
+  TEMPLATE_PATH,
+};
+
+if (require.main === module) {
+  const cmd = process.argv[2];
+  if (cmd === 'prompt') {
+    const specFile = process.argv[3];
+    if (!specFile) { console.error('usage: flow-skeptical-evaluator prompt <spec.md>'); process.exit(2); }
+    const fs = require('node:fs');
+    const specMarkdown = fs.readFileSync(specFile, 'utf8');
+    const built = buildSkepticalPrompt({ specMarkdown, diffText: '', changedFiles: [], taskId: 'cli' });
+    console.log('--- SYSTEM ---\n' + built.systemPrompt + '\n--- USER ---\n' + built.userPrompt);
+  } else {
+    console.error('usage: flow-skeptical-evaluator prompt <spec.md>');
+    process.exit(2);
+  }
+}

package/scripts/flow-skill-generator.js

@@ -229,7 +229,7 @@ async function fetchDocsViaContext7(technology) {
 // SKILL FILE GENERATION
 // ============================================
 
-function generateSkillMd(tech, docs) {
+function _generateSkillMd(tech, docs) {
   const date = getTodayDate();
 
   return `---
@@ -595,7 +595,7 @@ This skill is loaded on-demand when:
  * v2.0 format includes: type, ecosystem, loadWith, tokenCost
  */
 function generateSkillsIndex(technologies, selections) {
-  const { getSkillType, getParentFramework, ECOSYSTEMS } = getTechOptions();
+  const { getSkillType, getParentFramework, _ECOSYSTEMS } = getTechOptions();
   const skills = {};
 
   // First pass: identify all technologies and their types
@@ -759,7 +759,7 @@ function migrateOldSkills(projectRoot) {
  * @param {Object} skillContext - Additional context { type, parentFramework, ecosystemSkills }
  */
 async function writeSkillFiles(tech, docs, projectRoot, skillContext = {}) {
-  const { getSkillType, getParentFramework } = getTechOptions();
+  const { getSkillType, _getParentFramework } = getTechOptions();
 
   const skillId = tech.value.toLowerCase().replace(/[^a-z0-9]/g, '-');
   const skillDir = path.join(projectRoot, '.claude', 'skills', skillId);

package/scripts/flow-skill-learn.js

@@ -29,9 +29,6 @@ function log(color, ...args) {
   console.log(colors[color] + args.join(' ') + colors.reset);
 }
 
-// Alias getConfig as loadConfig for minimal code changes
-const loadConfig = getConfig;
-
 function isLearningEnabled(config, trigger) {
   if (!config?.skillLearning?.enabled) return false;
   if (!config?.skillLearning?.autoExtract) return false;
@@ -81,7 +78,7 @@ function getChangedFiles(staged = false) {
   }
 }
 
-function getRecentCommitFiles(count = 1) {
+function _getRecentCommitFiles(count = 1) {
   try {
     const cmd = `git diff HEAD~${count} --name-only`;
     const output = execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
@@ -387,7 +384,7 @@ function formatSemanticChanges(semanticChanges) {
 
   const lines = [];
 
-  for (const { file, changes } of semanticChanges) {
+  for (const { _file, changes } of semanticChanges) {
     if (changes.length === 0) continue;
 
     for (const change of changes) {
@@ -714,7 +711,7 @@ async function main() {
     process.exit(0);
   }
 
-  const config = loadConfig();
+  const config = getConfig();
 
   if (!isLearningEnabled(config, options.trigger)) {
     if (options.verbose) {

package/scripts/flow-skill-manage.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+'use strict';
+
+/**
+ * Wogi Flow — Skill Proposal CLI
+ *
+ * Subcommands:
+ *   flow skill propose --name <n> --content <file> [--rationale <text>]
+ *   flow skill patch   --name <n> --content <file> [--rationale <text>]
+ *   flow skill remove  --name <n> [--rationale <text>]
+ *   flow skill promote <name> [--id <proposalId>]
+ *   flow skill reject  <name> [--id <proposalId>]
+ *   flow skill archive <name>
+ *   flow skill pending [--json]
+ *
+ * Writes are staged to .claude/skills/pending/ and .workflow/state/skill-proposals.json.
+ * Session-end hook surfaces pending proposals for user review.
+ */
+
+const store = require('../lib/skill-proposal-store');
+const { success, error: errorMsg, info, colors } = require('./flow-output');
+
+// ============================================================
+// Arg parsing
+// ============================================================
+
+function parseArgs(argv) {
+  // argv = [subcommand, ...rest]
+  const [subcommand, ...rest] = argv;
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '--name') {
+      flags.name = rest[++i];
+    } else if (a === '--content') {
+      flags.content = rest[++i];
+    } else if (a === '--find') {
+      flags.find = rest[++i];
+    } else if (a === '--replace') {
+      flags.replace = rest[++i];
+    } else if (a === '--rationale') {
+      flags.rationale = rest[++i];
+    } else if (a === '--id') {
+      flags.id = rest[++i];
+    } else if (a === '--json') {
+      flags.json = true;
+    } else if (a === '--proposed-by') {
+      flags.proposedBy = rest[++i];
+    } else if (a === '--help' || a === '-h') {
+      flags.help = true;
+    } else if (a && !a.startsWith('--')) {
+      positional.push(a);
+    }
+  }
+  return { subcommand, flags, positional };
+}
+
+function showHelp() {
+  console.log(`
+${colors.cyan}Wogi Flow — Skill Proposal CLI${colors.reset}
+
+Agent-staged skill changes. Proposals are reviewed at session-end and approved
+or rejected by the user. No auto-apply.
+
+Usage:
+  flow skill propose --name <n> --content <file> [--rationale <text>]
+  flow skill patch   --name <n> --content <file> [--rationale <text>]
+  flow skill patch   --name <n> --find <file> --replace <file> [--rationale <text>]
+  flow skill remove  --name <n> [--rationale <text>]
+  flow skill promote <name> [--id <proposalId>]
+  flow skill reject  <name> [--id <proposalId>]
+  flow skill archive <name>
+  flow skill pending [--json]
+
+Actions:
+  propose     Stage a new skill. Writes content to .claude/skills/pending/<n>.md
+  patch       Stage an edit to an existing skill. Use --content for full
+              replacement, or --find + --replace for fuzzy find-replace
+              (tolerates whitespace/line-ending drift; rejects low-confidence
+              matches below skills.fuzzyPatchThreshold, default 0.85).
+  remove      Stage a removal of an existing skill.
+  promote     Apply a pending proposal (user-only). Moves pending → active,
+              applies patch, or archives as appropriate.
+  reject      Discard a pending proposal; cleans up staged content.
+  archive     Direct archival of an active skill (no staging).
+  pending     List pending proposals. --json for machine-readable output.
+
+Examples:
+  flow skill propose --name react-hooks --content scratch/draft.md \\
+                     --rationale "capture hook patterns from recent session"
+  flow skill patch   --name react-hooks --content scratch/updated.md
+  flow skill remove  --name outdated-skill --rationale "superseded by newer skill"
+  flow skill promote react-hooks
+  flow skill reject  react-hooks
+`);
+}
+
+function printPending(list, asJson) {
+  if (asJson) {
+    process.stdout.write(JSON.stringify(list, null, 2) + '\n');
+    return;
+  }
+  if (list.length === 0) {
+    info('No pending skill proposals.');
+    return;
+  }
+  console.log(`${colors.cyan}Pending skill proposals (${list.length}):${colors.reset}\n`);
+  for (const p of list) {
+    const icon = p.action === 'propose' ? '+' : p.action === 'patch' ? '~' : '-';
+    console.log(`  ${colors.bold}${icon} ${p.skillName}${colors.reset} ${colors.dim}(${p.action}, ${p.id})${colors.reset}`);
+    console.log(`    proposedAt: ${p.proposedAt}  by: ${p.proposedBy}`);
+    if (p.contentPath) console.log(`    content:    ${p.contentPath}`);
+    if (p.rationale) console.log(`    rationale:  ${p.rationale}`);
+    console.log('');
+  }
+}
+
+// ============================================================
+// Subcommand handlers
+// ============================================================
+
+function runPropose(flags) {
+  const record = store.createProposal({
+    action: 'propose',
+    skillName: flags.name,
+    contentFile: flags.content,
+    rationale: flags.rationale,
+    proposedBy: flags.proposedBy,
+  });
+  success(`Staged propose '${record.skillName}' (${record.id})`);
+  console.log(`  content: ${record.contentPath}`);
+  console.log(`  review with: flow skill pending`);
+  return 0;
+}
+
+function runPatch(flags) {
+  const record = store.createProposal({
+    action: 'patch',
+    skillName: flags.name,
+    contentFile: flags.content,
+    findFile: flags.find,
+    replaceFile: flags.replace,
+    rationale: flags.rationale,
+    proposedBy: flags.proposedBy,
+  });
+  success(`Staged patch '${record.skillName}' (${record.id})`);
+  if (record.patchMode === 'fuzzy') {
+    console.log(`  mode:    fuzzy find/replace`);
+    console.log(`  find:    ${record.findPath}`);
+    console.log(`  replace: ${record.replacePath}`);
+  } else {
+    console.log(`  mode:    full replacement`);
+    console.log(`  content: ${record.contentPath}`);
+  }
+  return 0;
+}
+
+function runRemove(flags) {
+  const record = store.createProposal({
+    action: 'remove',
+    skillName: flags.name,
+    rationale: flags.rationale,
+    proposedBy: flags.proposedBy,
+  });
+  success(`Staged remove '${record.skillName}' (${record.id})`);
+  console.log(`  review with: flow skill pending`);
+  return 0;
+}
+
+function runPromote(flags, positional) {
+  const name = positional[0] || flags.name;
+  const id = flags.id;
+  if (!name && !id) throw new Error('promote requires a skill name or --id <proposalId>');
+  const applied = store.promoteProposal({ skillName: name, id });
+  success(`Promoted ${applied.action} '${applied.skillName}' (${applied.id})`);
+  return 0;
+}
+
+function runReject(flags, positional) {
+  const name = positional[0] || flags.name;
+  const id = flags.id;
+  if (!name && !id) throw new Error('reject requires a skill name or --id <proposalId>');
+  const rejected = store.rejectProposal({ skillName: name, id });
+  success(`Rejected ${rejected.action} '${rejected.skillName}' (${rejected.id})`);
+  return 0;
+}
+
+function runArchive(_flags, positional) {
+  const name = positional[0];
+  if (!name) throw new Error('archive requires a skill name');
+  const r = store.archiveSkill(name);
+  success(`Archived '${r.skillName}' → ${r.archivedPath}`);
+  return 0;
+}
+
+function runPending(flags) {
+  const list = store.listProposals({ status: 'pending' });
+  printPending(list, !!flags.json);
+  return 0;
+}
+
+// ============================================================
+// Main
+// ============================================================
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const { subcommand, flags, positional } = parseArgs(argv);
+
+  if (flags.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  try {
+    let code;
+    switch (subcommand) {
+      case 'propose':  code = runPropose(flags); break;
+      case 'patch':    code = runPatch(flags); break;
+      case 'remove':   code = runRemove(flags); break;
+      case 'promote':  code = runPromote(flags, positional); break;
+      case 'reject':   code = runReject(flags, positional); break;
+      case 'archive':  code = runArchive(flags, positional); break;
+      case 'pending':  code = runPending(flags); break;
+      default:
+        errorMsg(`Unknown subcommand: ${subcommand}`);
+        showHelp();
+        process.exit(1);
+    }
+    process.exit(code);
+  } catch (err) {
+    errorMsg(err.message);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { parseArgs, runPropose, runPatch, runRemove, runPromote, runReject, runArchive, runPending };

package/scripts/flow-spec-verifier.js

@@ -410,7 +410,7 @@ function isLikelyNewFile(content, filePath) {
  * @param {string} filePath - File path
  * @returns {string|null} Section name
  */
-function findFileSection(content, filePath) {
+function _findFileSection(content, filePath) {
   const lines = content.split('\n');
   let currentSection = null;
 

package/scripts/flow-standards-checker.js

@@ -1214,6 +1214,75 @@ Examples:
   process.exit(results.blocked ? 1 : 0);
 }
 
+// ============================================================================
+// Non-Negotiable Rules Validation (wf-d0adca72 / A5)
+// ============================================================================
+
+const NON_NEGOTIABLE_FRAGMENT_ID = 'non-negotiable-rules';
+const NON_NEGOTIABLE_FRAGMENT_PATH = '.workflow/prompts/fragments/non-negotiable-rules.md';
+const CITATION_FORMAT_REGEX = /\b[\w./-]+\.(?:js|ts|tsx|jsx|md|json|yaml|yml|py|go|rs|sh):\d+(?:-\d+)?\b/;
+
+/**
+ * Validate that the non-negotiable-rules fragment exists and is loadable.
+ * @returns {{ ok: boolean, reason?: string, path?: string }}
+ */
+function checkNonNegotiableFragment() {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const full = path.join(process.cwd(), NON_NEGOTIABLE_FRAGMENT_PATH);
+  if (!fs.existsSync(full)) {
+    return { ok: false, reason: `missing fragment: ${NON_NEGOTIABLE_FRAGMENT_PATH}`, path: full };
+  }
+  const content = fs.readFileSync(full, 'utf8');
+  const required = ['Evidence before claim', 'No silent scope changes', 'Route every request', 'filepath:line', 'Destructive operations', 'Do not invent artifacts'];
+  const missing = required.filter((r) => !content.includes(r));
+  if (missing.length > 0) {
+    return { ok: false, reason: `fragment missing required sections: ${missing.join(', ')}`, path: full };
+  }
+  return { ok: true, path: full };
+}
+
+/**
+ * Validate that a composed prompt includes the non-negotiable-rules block.
+ * @param {string} composedPrompt
+ * @returns {{ ok: boolean, reason?: string }}
+ */
+function checkComposedPromptHasNonNegotiables(composedPrompt) {
+  if (!composedPrompt || typeof composedPrompt !== 'string') {
+    return { ok: false, reason: 'composedPrompt must be a non-empty string' };
+  }
+  if (!composedPrompt.includes('Non-Negotiable Rules')) {
+    return { ok: false, reason: 'composed prompt missing "Non-Negotiable Rules" header — fragment not loaded' };
+  }
+  if (!composedPrompt.includes('filepath:line')) {
+    return { ok: false, reason: 'composed prompt missing citation-format rule' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Validate that a text body contains at least one filepath:line citation when it makes claims about code.
+ * Heuristic: if the text references code (function names with parens, paths with slashes, or quoted identifiers),
+ * it should cite at least one location in `path:line` format.
+ * @param {string} text
+ * @param {object} [opts]
+ * @param {boolean} [opts.requireCitation=true]
+ * @returns {{ ok: boolean, reason?: string, hasCitation: boolean }}
+ */
+function checkCitationFormat(text, { requireCitation = true } = {}) {
+  if (!text || typeof text !== 'string') {
+    return { ok: false, reason: 'text must be a non-empty string', hasCitation: false };
+  }
+  const hasCitation = CITATION_FORMAT_REGEX.test(text);
+  if (!requireCitation) return { ok: true, hasCitation };
+  // Make claim-about-code detection lightweight
+  const looksLikeCodeClaim = /\b(function|class|module|import|require|file|path)\b|`[^`]+`/.test(text);
+  if (looksLikeCodeClaim && !hasCitation) {
+    return { ok: false, reason: 'text references code but has no filepath:line citation', hasCitation: false };
+  }
+  return { ok: true, hasCitation };
+}
+
 // ============================================================================
 // Exports
 // ============================================================================
@@ -1221,6 +1290,12 @@ Examples:
 module.exports = {
   runStandardsCheck,
   formatStandardsResults,
+  checkNonNegotiableFragment,
+  checkComposedPromptHasNonNegotiables,
+  checkCitationFormat,
+  NON_NEGOTIABLE_FRAGMENT_ID,
+  NON_NEGOTIABLE_FRAGMENT_PATH,
+  CITATION_FORMAT_REGEX,
   parseDecisions,
   parseAppMap,
   parseFunctionMap,