wogiflow 2.26.2 → 2.29.0

package/scripts/flow-figma-extract.js

@@ -83,7 +83,7 @@ class FigmaExtractor {
   }
 
   parseNodes(nodes, parent = null) {
-    for (const [nodeId, nodeData] of Object.entries(nodes)) {
+    for (const [_nodeId, nodeData] of Object.entries(nodes)) {
       const node = nodeData.document || nodeData;
       this.parseNode(node, parent);
     }
@@ -445,7 +445,7 @@ class FigmaExtractor {
 // ============================================================
 
 async function main() {
-  const [,, input, ...args] = process.argv;
+  const [,, input, ..._args] = process.argv;
 
   const extractor = new FigmaExtractor();
 

package/scripts/flow-figma-generate.js

@@ -21,7 +21,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const {
   detectFramework } = require('./flow-figma-index');
-const { getProjectRoot,
+const { _getProjectRoot,
   getConfig,
   addRequestLogEntry,
   addAppMapComponent,

package/scripts/flow-gate-confidence.js

@@ -523,7 +523,7 @@ const VALID_DECISIONS = ['auto-apply', 'approved', 'blocked'];
  * @param {Object} params - Decision parameters
  * @throws {Error} If decision is not a valid type
  */
-function recordDecision({ _analysisId, decision, outcome }) {
+function recordDecision({ _analysisId, decision, _outcome }) {
   // Validate decision type to prevent silent failures
   if (!VALID_DECISIONS.includes(decision)) {
     throw new Error(`Invalid decision type: ${decision}. Must be one of: ${VALID_DECISIONS.join(', ')}`);

package/scripts/flow-health.js

@@ -1089,6 +1089,11 @@ function main() {
     }
   }
 
+  // B7 (wf-c3b5afab): Surface gate miss-rate summary — rubber-stamping visibility
+  console.log('');
+  printSection('Checking gate telemetry...');
+  printGateMissRateSummary();
+
   // Summary
   console.log('');
   console.log('========================');
@@ -1106,6 +1111,52 @@ function main() {
   return { issues, warnings };
 }
 
+// B7 (wf-c3b5afab): One-line surface of gates above the miss-rate threshold.
+// Uses the same threshold as flow-session-end's watch section (>=10%).
+const GATE_MISS_RATE_THRESHOLD = 0.10;
+const GATE_MISS_WINDOW = '7d';
+
+function loadGateStatsForHealth() {
+  let getGateStats;
+  try {
+    ({ getGateStats } = require('./flow-gate-telemetry'));
+  } catch (err) {
+    if (process.env.DEBUG) console.error(`[DEBUG] Gate telemetry: ${err.message}`);
+    return null;
+  }
+  try {
+    return getGateStats({ since: GATE_MISS_WINDOW });
+  } catch (err) {
+    if (process.env.DEBUG) console.error(`[DEBUG] Gate telemetry stats: ${err.message}`);
+    return null;
+  }
+}
+
+function printGateMissRateSummary(stats = loadGateStatsForHealth()) {
+  const perGate = stats && stats.perGate ? stats.perGate : null;
+  const gates = perGate ? Object.keys(perGate) : [];
+  if (!perGate || gates.length === 0) {
+    console.log(`  ${color('dim', 'No telemetry yet (baseline)')}`);
+    return;
+  }
+
+  const over = gates.filter(id => {
+    const g = perGate[id];
+    return g.verdicts && g.verdicts.PASS > 0 && g.missRate >= GATE_MISS_RATE_THRESHOLD;
+  });
+
+  if (over.length === 0) {
+    success(`Gate missRate: 0 gates above ${(GATE_MISS_RATE_THRESHOLD * 100).toFixed(0)}% threshold`);
+    return;
+  }
+
+  warn(`Gate missRate: ${over.length} gate(s) above ${(GATE_MISS_RATE_THRESHOLD * 100).toFixed(0)}% threshold (see /wogi-gate-stats)`);
+  for (const id of over.slice(0, 3)) {
+    const g = perGate[id];
+    console.log(`    ${color('dim', `${id}: ${(g.missRate * 100).toFixed(1)}% miss (${g.missedAfterPass}/${g.verdicts.PASS})`)}`);
+  }
+}
+
 // ============================================================
 // Deep Audit (v1.0.4)
 // ============================================================
@@ -1390,4 +1441,4 @@ function checkCompletionClaimHonesty() {
   return hits;
 }
 
-module.exports = { checkMcpScopes, normalizeMcpConfig, checkAntiDeferralCompliance, checkCompletionClaimHonesty };
+module.exports = { checkMcpScopes, normalizeMcpConfig, checkAntiDeferralCompliance, checkCompletionClaimHonesty, printGateMissRateSummary, GATE_MISS_RATE_THRESHOLD };

package/scripts/flow-hooks.js

@@ -165,7 +165,7 @@ function installClaudeCodeHooks(adapter, hooksConfig) {
  * Install hooks for all configured targets
  */
 function setupHooks(options = {}) {
-  const { target, force } = options;
+  const { target, _force } = options;
 
   console.log(color('cyan', '🪝 Setting Up CLI Hooks'));
   console.log('');

package/scripts/flow-id.js

@@ -55,19 +55,35 @@ function generatePlanId(title) {
 }
 
 /**
- * Check if a string is a valid task ID (old or new format)
- * @returns {{ valid: boolean, format: 'hash' | 'legacy' | null }}
+ * Check if a string is a valid task ID.
+ * @returns {{ valid: boolean, format: 'hash' | 'slug' | 'legacy' | null }}
+ *
+ * Accepted formats:
+ *   - 'hash'   — wf-XXXXXXXX (8-char hex, produced by generateTaskId)
+ *   - 'slug'   — wf-<alphanum>[<alphanum or hyphen>]*<alphanum>, 5-64 chars total.
+ *                For manager-dispatched descriptive IDs (e.g. wf-ttp-gate-2a,
+ *                wf-auth-me-customer-capabilities). Path-safe: no '.', no '/',
+ *                no '\\', no whitespace — safe to interpolate into file paths.
+ *   - 'legacy' — TASK-NNN / BUG-NNN (grandfathered)
  */
 function validateTaskId(id) {
   if (!id || typeof id !== 'string') {
     return { valid: false, format: null };
   }
 
-  // New hash-based format: wf-XXXXXXXX
+  // Hash format: wf-XXXXXXXX
   if (/^wf-[a-f0-9]{8}$/i.test(id)) {
     return { valid: true, format: 'hash' };
   }
 
+  // Slug format: wf-<start-alphanum><0-60 alphanum-or-hyphen><end-alphanum>.
+  // Min 5 chars ("wf-ab"), max 64 chars. Start+end must be alphanum so the ID
+  // never begins or ends with '-'. No dots or path separators allowed — this
+  // keeps `path.join(DIR, `.routing-receipt-${id}`)` safe from traversal.
+  if (/^wf-[a-z0-9][a-z0-9-]{0,60}[a-z0-9]$/i.test(id)) {
+    return { valid: true, format: 'slug' };
+  }
+
   // Legacy formats: TASK-XXX, BUG-XXX
   if (/^(TASK|BUG)-\d{3,}$/i.test(id)) {
     return { valid: true, format: 'legacy' };

package/scripts/flow-instruction-richness.js

@@ -834,7 +834,7 @@ this without guessing anything. Local LLM tokens are FREE - don't hold back!
  * @returns {string|null} Formatted type hints
  */
 function generateTypeHints(projectRoot, options = {}) {
-  const { maxTypes = 10, taskDescription = '' } = options;
+  const { maxTypes = 10, _taskDescription = '' } = options;
   const typeHints = [];
 
   // Common type file locations

package/scripts/flow-knowledge-router.js

@@ -280,7 +280,7 @@ async function storeSkillLearning(correction, route, context) {
   };
 }
 
-async function storeProjectDecision(correction, _route, context) {
+async function storeProjectDecision(correction, _route, _context) {
   const decisionsPath = PATHS.decisions;
 
   let content = '';

package/scripts/flow-knowledge-sync.js

@@ -415,7 +415,7 @@ function printStatus(driftStatus) {
     { key: 'testing', name: 'Testing (testing.md)', file: getSpecFilePath('testing', { warnOnOld: false, preferNew: true }) }
   ];
 
-  for (const { key, name, file } of categories) {
+  for (const { key, name, _file } of categories) {
     const status = driftStatus.categories[key];
     printSection(name);
 

package/scripts/flow-logic-adversary.js

@@ -55,6 +55,21 @@ const gateTelemetry = require('./flow-gate-telemetry');
 const RUBRIC_DIR = path.join(PATHS.workflow, 'rubrics');
 const DEFAULT_RUBRIC = 'logic-constitution-v3';
 const CALIBRATION_PATH = path.join(PATHS.state, 'adversary-calibration.json');
+const PERSONAS_DIR = path.join(PATHS.workflow, 'agents', 'personas');
+
+// Persona library — see .workflow/agents/personas/README.md
+// Story: wf-258f558c (A2). Keys map to .md filenames (minus extension).
+const PERSONA_LIBRARY = ['scale-skeptic', 'security-hawk', 'simplicity-champion', 'platform-rigor', 'user-advocate'];
+
+// Trigger patterns — if the plan/title/taskId mentions any of these, auto-pick the persona.
+// Order matters: earlier entries win when multiple triggers match.
+const PERSONA_TRIGGERS = [
+  { persona: 'security-hawk',      patterns: [/\bauth\b/i, /\bsecret\b/i, /\btoken\b/i, /\bcredential/i, /rm\s+-rf/i, /--force/i, /destructive/i, /\bshell\s+inject/i, /\bexecSync\b/, /\.env\b/] },
+  { persona: 'platform-rigor',     patterns: [/\bPreToolUse\b/, /\bPostToolUse\b/, /\bSessionStart\b/, /\bMCP\b/, /\bsubagent\b/i, /\bvalidator\b/i, /\bvalidateTaskId\b/, /\bconfig\s+key\b/i] },
+  { persona: 'scale-skeptic',      patterns: [/\bparallel\b/i, /\bconcurrent/i, /\bworktree/i, /\bdispatch/i, /\bqueue\b/i, /\bworker\b/i, /\brace\s+condition/i, /\bTOCTOU\b/i, /\bboundary\b/i] },
+  { persona: 'user-advocate',      patterns: [/\bUI\b/, /\buser-facing\b/i, /\bonboarding/i, /\bjourney/i, /\berror\s+message/i, /\bempty\s+state/i, /\bcli\s+output/i] },
+  { persona: 'simplicity-champion', patterns: [/\bframework\b/i, /\bpluggable/i, /\bfuture-proof/i, /\bextensibility/i, /\bgeneric\b/i, /\babstraction\b/i, /\brefactor\b/i] },
+];
 
 const VALID_OVERALL_VERDICTS = new Set([
   'PASS',
@@ -106,6 +121,50 @@ function loadCalibration() {
   return Array.isArray(parsed.examples) ? parsed.examples : [];
 }
 
+// ============================================================
+// Persona library (wf-258f558c / A2)
+// ============================================================
+
+function _getPersonasConfig() {
+  const cfg = getConfig();
+  return cfg.intentGroundedReasoning?.logicAdversary?.personas || cfg.adversary?.personas || {};
+}
+
+/**
+ * Load a persona amplifier file.
+ * @param {string} key - persona slug (must be in PERSONA_LIBRARY)
+ * @returns {string} markdown content, or empty string when missing
+ */
+function loadPersona(key) {
+  if (!key || !PERSONA_LIBRARY.includes(key)) return '';
+  const p = path.join(PERSONAS_DIR, `${key}.md`);
+  return fileExists(p) ? readFile(p) : '';
+}
+
+/**
+ * Pick a persona based on plan/title content. Falls back to taskId-hash rotation.
+ * @param {object} opts
+ * @param {string} [opts.taskId]
+ * @param {string} [opts.plan]
+ * @param {string} [opts.title]
+ * @returns {string} persona key (always one of PERSONA_LIBRARY)
+ */
+function pickPersona({ taskId, plan, title } = {}) {
+  const haystack = [title || '', plan || ''].join('\n').slice(0, 4000);
+  if (haystack.trim().length > 0) {
+    for (const trigger of PERSONA_TRIGGERS) {
+      for (const pattern of trigger.patterns) {
+        if (pattern.test(haystack)) return trigger.persona;
+      }
+    }
+  }
+  // Rotate by taskId hash to ensure library coverage over time.
+  const source = taskId || haystack || Date.now().toString();
+  let h = 0;
+  for (let i = 0; i < source.length; i++) h = (h * 31 + source.charCodeAt(i)) >>> 0;
+  return PERSONA_LIBRARY[h % PERSONA_LIBRARY.length];
+}
+
 // ============================================================
 // Intent artifact detection
 // ============================================================
@@ -187,9 +246,21 @@ function buildAdversaryPrompt(opts) {
   const personaPath = path.join(PATHS.workflow, 'agents', 'logic-adversary.md');
   const personaContent = fileExists(personaPath) ? readFile(personaPath) : '';
 
-  // System prompt — persona + rubric + calibration + degraded-mode notes
+  // Persona-library pick (wf-258f558c / A2). An amplification layer on top of the base persona.
+  // Config toggle: adversary.personas.enabled (default true). Orchestrator may override via opts.persona.
+  const personasEnabled = _getPersonasConfig().enabled !== false;
+  const personaKey = personasEnabled
+    ? (opts.persona || pickPersona({ taskId: opts.taskId, plan: opts.plan, title: opts.title }))
+    : null;
+  const amplifierContent = personaKey ? loadPersona(personaKey) : '';
+
+  // System prompt — base persona + persona amplifier + rubric + calibration + degraded-mode notes
   const systemParts = [];
   systemParts.push(personaContent || '# Persona\nYou are the Logic Adversary. See the rubric below.');
+  if (amplifierContent) {
+    systemParts.push('\n# Persona amplifier (stacks on top of base persona)\n');
+    systemParts.push(amplifierContent);
+  }
   systemParts.push('\n# Rubric (Logic Constitution)\n');
   systemParts.push(rubric.content);
 
@@ -691,4 +762,8 @@ module.exports = {
   VALID_PRINCIPLE_VERDICTS,
   DEFAULT_RUBRIC,
   DEFAULT_MODEL_PAIRING,
+  pickPersona,
+  loadPersona,
+  PERSONA_LIBRARY,
+  PERSONA_TRIGGERS,
 };

package/scripts/flow-logic-rules.js

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+
+/**
+ * Wogi Flow - Logic Rules (Cross-Cutting)
+ *
+ * Cross-cutting business-logic rules that span multiple features/pages.
+ *
+ * Problem solved (2026-04-24 workspace failure catalog, point 4):
+ *   Owner says "every person in the system needs a seat — remove contact-person
+ *   blocks." A dossier captures that for ONE feature. But the rule applies
+ *   everywhere. Next session, Claude edits a different page and reintroduces
+ *   the pattern. Feature-scoped memory doesn't catch it.
+ *
+ * How it works:
+ *   - Rules live in <dossier-dir>/_logic-rules.md, one "## RULE: <id>" per rule
+ *   - Each rule declares: statement, applies-to (file globs / keywords),
+ *     enforcement-grep (regex to detect violations anywhere)
+ *   - listRules() parses all rules from the canonical file(s)
+ *   - matchRulesForFiles(files) returns rules scoped to those files
+ *   - checkPropagation(rule, originFiles) greps the repo for other places
+ *     the rule should apply but the origin task may have missed
+ *   - detectViolations() scans the entire repo for grep patterns that should
+ *     not appear — surfaces drift at session-start or /wogi-health
+ *
+ * Workspace-mode:
+ *   Workspace-level rules live at WOGI_WORKSPACE_ROOT/.workspace/dossiers/
+ *     _logic-rules.md (cross-repo).
+ *   Per-repo rules live at <repo>/.workflow/dossiers/_logic-rules.md.
+ *   Both are merged at read time; workspace shadows repo on id collision.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+const { PATHS } = require('./flow-utils');
+const { getDossierRoots, DOSSIER_DIRNAME: _DOSSIER_DIRNAME } = require('./flow-feature-dossier');
+
+const LOGIC_RULES_FILENAME = '_logic-rules.md';
+
+function getRulesPaths() {
+  const out = [];
+  for (const root of getDossierRoots()) {
+    const p = path.join(root.dir, LOGIC_RULES_FILENAME);
+    if (fs.existsSync(p)) out.push({ path: p, root: root.kind });
+  }
+  return out;
+}
+
+/**
+ * Parse a logic-rules markdown file.
+ * Format:
+ *   ## RULE: <id>
+ *   <!-- id: <id> --> (optional, id taken from heading if absent)
+ *   <!-- status: active|deprecated -->
+ *   <!-- created: YYYY-MM-DD -->
+ *   **Statement**: ...
+ *   **Why**: ...
+ *   **Applies to**:
+ *     - pattern: src/**\/Customer*
+ *     - keyword: contact person
+ *   **Enforcement grep**: `regex`
+ *   **Origin**: wf-xxxxxxxx
+ */
+function parseRulesFile(raw, rootKind) {
+  const rules = [];
+  // Strip fenced code blocks so example rules in docs aren't parsed as real rules.
+  const stripped = raw.replace(/```[\s\S]*?```/g, '');
+  const sectionRegex = /\n##\s+RULE:\s*([^\n]+)\n([\s\S]*?)(?=\n##\s+RULE:|\n##\s+[^R]|$)/gi;
+  let m;
+  while ((m = sectionRegex.exec('\n' + stripped)) !== null) {
+    const headingId = m[1].trim();
+    const body = m[2];
+    const idMatch = body.match(/<!--\s*id:\s*([^>]+)-->/);
+    const id = (idMatch ? idMatch[1].trim() : headingId).replace(/\s+/g, '-').toLowerCase();
+    const statusMatch = body.match(/<!--\s*status:\s*([^>]+)-->/);
+    const createdMatch = body.match(/<!--\s*created:\s*([^>]+)-->/);
+    const statement = extractBoldField(body, 'Statement');
+    const why = extractBoldField(body, 'Why');
+    const origin = extractBoldField(body, 'Origin');
+    const grepMatch = body.match(/\*\*Enforcement\s*grep\*\*\s*:\s*`([^`]+)`/i);
+    const appliesSection = body.match(/\*\*Applies\s*to\*\*\s*:\s*\n([\s\S]*?)(?=\n\*\*|\n$|$)/i);
+
+    const patterns = [];
+    const keywords = [];
+    const components = [];
+    if (appliesSection) {
+      for (const line of appliesSection[1].split('\n')) {
+        const kv = line.trim().match(/^-\s*([a-zA-Z-]+):\s*(.+)$/);
+        if (!kv) continue;
+        const kind = kv[1].toLowerCase();
+        const value = kv[2].trim();
+        if (kind === 'pattern' || kind === 'file' || kind === 'filepattern') patterns.push(value);
+        else if (kind === 'keyword') keywords.push(value.toLowerCase());
+        else if (kind === 'component') components.push(value);
+      }
+    }
+
+    rules.push({
+      id,
+      status: statusMatch ? statusMatch[1].trim() : 'active',
+      created: createdMatch ? createdMatch[1].trim() : null,
+      statement: statement || '',
+      why: why || '',
+      origin: origin || '',
+      enforcementGrep: grepMatch ? grepMatch[1] : null,
+      appliesTo: { patterns, keywords, components },
+      _root: rootKind
+    });
+  }
+  return rules;
+}
+
+function extractBoldField(body, name) {
+  const re = new RegExp(`\\*\\*${name}\\*\\*\\s*:\\s*(.+?)(?=\\n\\*\\*|\\n$|$)`, 'is');
+  const m = body.match(re);
+  if (!m) return '';
+  return m[1].trim().replace(/\n+/g, ' ');
+}
+
+function listRules() {
+  const all = [];
+  const seen = new Map();
+  for (const { path: p, root } of getRulesPaths()) {
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf-8'); } catch (_err) { continue; }
+    const rules = parseRulesFile(raw, root);
+    for (const r of rules) {
+      if (seen.has(r.id) && root !== 'workspace') continue;
+      seen.set(r.id, r);
+    }
+  }
+  for (const r of seen.values()) all.push(r);
+  return all;
+}
+
+function globToRegex(pat) {
+  const escaped = pat
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '.__DBLSTAR__')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\.__DBLSTAR__/g, '.*')
+    .replace(/\?/g, '[^/]');
+  return new RegExp(`^${escaped}$`, 'i');
+}
+
+function matchRulesForFiles(files = [], extraKeywords = []) {
+  if (!Array.isArray(files)) files = [files];
+  const lowerFiles = files.map(f => String(f).toLowerCase());
+  const lowerKw = extraKeywords.map(k => String(k).toLowerCase());
+  const rules = listRules();
+  const matched = [];
+  for (const rule of rules) {
+    if (rule.status !== 'active') continue;
+    let scoreHit = false;
+    const reasons = [];
+    for (const pat of rule.appliesTo.patterns) {
+      const re = globToRegex(pat);
+      for (const f of lowerFiles) {
+        if (re.test(f)) {
+          scoreHit = true;
+          reasons.push(`file-match: ${pat}`);
+          break;
+        }
+      }
+    }
+    for (const kw of rule.appliesTo.keywords) {
+      if (lowerKw.some(k => k.includes(kw))) {
+        scoreHit = true;
+        reasons.push(`keyword: ${kw}`);
+      }
+    }
+    if (scoreHit) matched.push({ ...rule, reasons });
+  }
+  return matched;
+}
+
+/**
+ * Propagation check: given a rule and the files just touched,
+ * grep the repo for other places the rule's enforcement pattern appears.
+ * Surface hits as "rule applies here too, did you miss it?"
+ */
+function checkPropagation(rule, originFiles = []) {
+  if (!rule.enforcementGrep) return { rule: rule.id, checked: false, otherHits: [] };
+  const normalizedOrigin = new Set(originFiles.map(f => path.normalize(f)));
+  try {
+    const out = execSync(
+      `git grep -lE ${JSON.stringify(rule.enforcementGrep)} -- . ':(exclude).workflow' ':(exclude).workspace' ':(exclude)node_modules' ':(exclude).git' 2>/dev/null || true`,
+      { cwd: PATHS.root, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    const files = out.split('\n').filter(Boolean);
+    const otherHits = files.filter(f => !normalizedOrigin.has(path.normalize(f)));
+    return { rule: rule.id, checked: true, pattern: rule.enforcementGrep, otherHits };
+  } catch (_err) {
+    return { rule: rule.id, checked: false, otherHits: [] };
+  }
+}
+
+function detectViolations() {
+  const rules = listRules();
+  const report = [];
+  for (const rule of rules) {
+    if (rule.status !== 'active') continue;
+    if (!rule.enforcementGrep) continue;
+    try {
+      const out = execSync(
+        `git grep -nE ${JSON.stringify(rule.enforcementGrep)} -- . ':(exclude).workflow' ':(exclude).workspace' ':(exclude)node_modules' ':(exclude).git' 2>/dev/null || true`,
+        { cwd: PATHS.root, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      const lines = out.split('\n').filter(Boolean);
+      if (lines.length > 0) {
+        report.push({
+          rule: rule.id,
+          statement: rule.statement,
+          pattern: rule.enforcementGrep,
+          hits: lines.length,
+          sample: lines.slice(0, 5)
+        });
+      }
+    } catch (_err) { /* skip */ }
+  }
+  return report;
+}
+
+function buildRulesInjection(matches) {
+  if (!matches || matches.length === 0) return null;
+  const blocks = matches.slice(0, 6).map(rule => {
+    let b = `### Logic Rule: ${rule.id}\n`;
+    b += `**Statement**: ${rule.statement}\n`;
+    if (rule.why) b += `**Why**: ${rule.why}\n`;
+    b += `**Matched via**: ${rule.reasons.join(', ')}\n`;
+    if (rule.enforcementGrep) b += `**Enforcement grep**: \`${rule.enforcementGrep}\`\n`;
+    if (rule.origin) b += `**Origin**: ${rule.origin}\n`;
+    return b;
+  });
+  return [
+    '## Cross-Cutting Logic Rules (auto-loaded)',
+    '',
+    'Active logic rules scoped to the files you are touching. Violating these introduces regressions the owner has already corrected. Run propagation check (`flow logic-rules propagate <rule-id>`) if your change implements or reinforces one of these rules.',
+    '',
+    blocks.join('\n---\n\n')
+  ].join('\n');
+}
+
+// ============================================================
+// CLI
+// ============================================================
+
+function printHelp() {
+  console.log(`Usage: flow logic-rules <command> [args]
+
+Commands:
+  list                             List all rules with status
+  show <id>                        Show a single rule
+  match --files "a,b" [--keywords "k1,k2"]
+                                   Show rules that scope to these files/keywords
+  propagate <id> [--origin "a,b"]
+                                   Find other places this rule's pattern appears
+  scan                             Detect violations across the whole repo
+  inject --files "a,b" [--keywords "k1,k2"]
+                                   Print phase-injection block
+  help                             Show this help
+
+Examples:
+  flow logic-rules list
+  flow logic-rules match --files "src/pages/Customer.tsx"
+  flow logic-rules propagate every-person-needs-seat --origin "src/pages/Customer.tsx"
+  flow logic-rules scan
+`);
+}
+
+function parseArgs(args) {
+  const out = { _: [], flags: {} };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith('--')) { out.flags[key] = next; i++; }
+      else { out.flags[key] = true; }
+    } else { out._.push(a); }
+  }
+  return out;
+}
+
+function cliMain(argv) {
+  const [cmd, ...rest] = argv;
+  const { _: positional, flags } = parseArgs(rest);
+
+  if (!cmd || cmd === 'help' || cmd === '--help') return printHelp();
+
+  if (cmd === 'list') {
+    const rules = listRules();
+    if (rules.length === 0) {
+      console.log('(no rules — edit .workflow/dossiers/_logic-rules.md to add)');
+      return;
+    }
+    for (const r of rules) {
+      console.log(`${r.id}  [${r.status}]  ${r.statement.slice(0, 80)}`);
+    }
+    return;
+  }
+
+  if (cmd === 'show') {
+    const id = positional[0];
+    const rules = listRules();
+    const r = rules.find(x => x.id === id);
+    if (!r) { console.error(`rule not found: ${id}`); process.exit(1); }
+    console.log(JSON.stringify(r, null, 2));
+    return;
+  }
+
+  if (cmd === 'match') {
+    const files = flags.files ? String(flags.files).split(',').map(s => s.trim()) : [];
+    const kw = flags.keywords ? String(flags.keywords).split(',').map(s => s.trim()) : [];
+    const matches = matchRulesForFiles(files, kw);
+    if (matches.length === 0) { console.log('(no matches)'); return; }
+    for (const m of matches) {
+      console.log(`${m.id}  [${m.reasons.join(', ')}]  ${m.statement.slice(0, 80)}`);
+    }
+    return;
+  }
+
+  if (cmd === 'propagate') {
+    const id = positional[0];
+    if (!id) { console.error('rule id required'); process.exit(1); }
+    const rules = listRules();
+    const r = rules.find(x => x.id === id);
+    if (!r) { console.error(`rule not found: ${id}`); process.exit(1); }
+    const origin = flags.origin ? String(flags.origin).split(',').map(s => s.trim()) : [];
+    const report = checkPropagation(r, origin);
+    if (!report.checked) { console.log('(no enforcement grep to propagate)'); return; }
+    if (report.otherHits.length === 0) {
+      console.log(`propagation: clean (pattern /${report.pattern}/ only appears in origin files)`);
+    } else {
+      console.log(`PROPAGATION: pattern /${report.pattern}/ also appears in:`);
+      for (const f of report.otherHits) console.log(`  ${f}`);
+      process.exit(2);
+    }
+    return;
+  }
+
+  if (cmd === 'scan') {
+    const report = detectViolations();
+    if (report.length === 0) { console.log('no violations'); return; }
+    console.log(`${report.length} rule violation(s):`);
+    for (const v of report) {
+      console.log(`\n${v.rule}: ${v.statement}`);
+      console.log(`  pattern: /${v.pattern}/  hits: ${v.hits}`);
+      for (const s of v.sample) console.log(`    ${s}`);
+    }
+    process.exit(2);
+  }
+
+  if (cmd === 'inject') {
+    const files = flags.files ? String(flags.files).split(',').map(s => s.trim()) : [];
+    const kw = flags.keywords ? String(flags.keywords).split(',').map(s => s.trim()) : [];
+    const matches = matchRulesForFiles(files, kw);
+    const block = buildRulesInjection(matches);
+    if (block) console.log(block);
+    return;
+  }
+
+  console.error(`unknown command: ${cmd}`);
+  printHelp();
+  process.exit(1);
+}
+
+if (require.main === module) {
+  try { cliMain(process.argv.slice(2)); }
+  catch (err) { console.error(err.message); process.exit(1); }
+}
+
+module.exports = {
+  listRules,
+  parseRulesFile,
+  matchRulesForFiles,
+  checkPropagation,
+  detectViolations,
+  buildRulesInjection
+};