@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

package/tools/validate-trigger-column-vs-emits.js

@@ -0,0 +1,375 @@
+/**
+ * Trigger-Column ↔ Emits Bidirectional Validator (AS-series — run #43)
+ *
+ * Cross-checks the "Trigger examples" column in each pipeline's
+ * "Warning Prefix-Tag Convention" table against the actual
+ * `Append to {run_warnings}: \`[step-NN] ...\`` literals in that
+ * pipeline's `steps/step-NN.md` files.
+ *
+ * Why this exists:
+ *  - The convention table lists representative trigger examples per
+ *    `[step-NN]` row. Over time, new emit branches get added to step
+ *    files without back-porting an example into the column, and stale
+ *    examples linger in the column after the underlying emit is removed
+ *    or reworded.
+ *  - This validator catches both directions:
+ *      FORWARD : column fragment without any matching emit literal
+ *      REVERSE : emit literal without any matching column fragment
+ *
+ * Matching rule (fuzzy keyword set, per AR2/AQ1 framing):
+ *  - Tokenize the column fragment and the emit literal:
+ *      lowercase, strip backticks/curly-braces/punctuation,
+ *      split on whitespace.
+ *  - Drop stop-words, pure numbers, single-character tokens.
+ *  - Count overlap = |column_tokens ∩ emit_tokens|.
+ *  - Match if overlap >= 2 (two distinct content tokens shared) OR
+ *    if the column fragment (lowercased, whitespace-collapsed) appears
+ *    as a substring of the lowercased+collapsed emit (handles very
+ *    short fragments where the two-token threshold cannot be met).
+ *
+ * Scope (pipelines with a convention table):
+ *  - src/xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline/
+ *  - src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/
+ *
+ * Output (per pipeline):
+ *   [pipeline-name]
+ *     Forward (column → emits): N/M fragments matched
+ *       MISS: <column_fragment_text>
+ *     Reverse (emits → column): N/M emits matched
+ *       MISS: step-NN.md:LINE  <emit_literal>
+ *
+ * Exit codes:
+ *   0  both directions fully matched across all pipelines
+ *   1  any miss in either direction
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+
+// Pipelines to validate. Each entry: workflow.md path + steps dir.
+const PIPELINES = [
+  {
+    name: 'auto-requirements-pipeline',
+    workflowMd: 'src/xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline/workflow.md',
+    stepsDir: 'src/xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline/steps',
+  },
+  {
+    name: 'auto-story-pipeline',
+    workflowMd: 'src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/workflow.md',
+    stepsDir: 'src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/steps',
+  },
+];
+
+// Emit-literal regex. Permits inline qualifiers between `{run_warnings}` and
+// the `:` that introduces the literal (e.g., step-09 writes `Append to
+// \`{run_warnings}\` with canonical prefix tag: \`[step-09] ...\``). Mirrors
+// validate-warnings-samples.js PRODUCER_RE shape but with `[^:`]*` slack
+// between `\`` and `:` to tolerate the qualifier.
+const PRODUCER_RE = /[Aa]ppend to `\{run_warnings\}`[^:`]*:\s*`(\[step-\d{2}\][^`]+)`/g;
+
+// Stop-words removed from token sets before overlap counting.
+const STOP_WORDS = new Set([
+  'a',
+  'an',
+  'the',
+  'of',
+  'for',
+  'to',
+  'in',
+  'on',
+  'by',
+  'at',
+  'from',
+  'with',
+  'and',
+  'or',
+  'is',
+  'was',
+  'may',
+  'can',
+  'must',
+  'will',
+  'be',
+  'been',
+  'vs',
+  'etc',
+  'eg',
+  'ie',
+  'not',
+  'no',
+  'used',
+]);
+
+function readFile(relPath) {
+  return fs.readFileSync(path.join(PROJECT_ROOT, relPath), 'utf8');
+}
+
+function readLines(relPath) {
+  return readFile(relPath).split('\n');
+}
+
+// Normalize text for token extraction:
+//  - lowercase
+//  - strip backtick characters (but KEEP contents — column fragments
+//    routinely wrap file/var names like `pipeline-status.json` in backticks
+//    while the emit literal writes them bare, so dropping code-span text
+//    would systematically suppress overlap on identifiers)
+//  - drop curly-brace placeholders entirely (e.g., {var})
+//  - drop [step-NN] tags so the tag identity never inflates overlap
+//  - replace non-alphanumeric (except space) with space
+//  - collapse whitespace, drop stop-words, single chars, pure numbers
+function tokenize(text) {
+  let s = String(text).toLowerCase();
+  // Strip {var} placeholders BEFORE backticks so `{var}` doesn't leave `{var}`
+  // behind after backticks are removed.
+  s = s.replaceAll(/`\{[^}]*\}`/g, ' ');
+  s = s.replaceAll(/\{[^}]*\}/g, ' ');
+  // Remove backtick characters but keep enclosed text.
+  s = s.replaceAll('`', ' ');
+  // Strip [step-NN] tags so step-tag identity never inflates overlap.
+  s = s.replaceAll(/\[step-\d+\]/g, ' ');
+  // Replace anything not alphanumeric with space.
+  s = s.replaceAll(/[^\da-z]+/g, ' ');
+  const raw = s.split(/\s+/).filter(Boolean);
+  const tokens = new Set();
+  for (const t of raw) {
+    if (STOP_WORDS.has(t)) continue;
+    if (t.length < 2) continue;
+    if (/^\d+$/.test(t)) continue;
+    tokens.add(t);
+  }
+  return tokens;
+}
+
+// Normalize text for substring fallback:
+//  - lowercase, strip backticks/curlies/brackets,
+//  - collapse whitespace.
+function normalizeForSubstring(text) {
+  let s = String(text).toLowerCase();
+  s = s.replaceAll('`', '');
+  s = s.replaceAll(/\{[^}]*\}/g, ' ');
+  s = s.replaceAll(/\[step-\d+\]/g, ' ');
+  s = s.replaceAll(/\s+/g, ' ');
+  return s.trim();
+}
+
+function intersectionSize(setA, setB) {
+  let n = 0;
+  for (const x of setA) if (setB.has(x)) n++;
+  return n;
+}
+
+function tokensMatch(fragment, emit) {
+  const fragTokens = tokenize(fragment);
+  const emitTokens = tokenize(emit);
+  if (intersectionSize(fragTokens, emitTokens) >= 2) return true;
+  const fragNorm = normalizeForSubstring(fragment);
+  const emitNorm = normalizeForSubstring(emit);
+  if (fragNorm.length > 0 && emitNorm.includes(fragNorm)) return true;
+  return false;
+}
+
+// Parse the convention table from the workflow.md.
+// Returns: Map<stepTag, { fragments: string[], rowLine: number }>
+// `fragments` is the `;`-separated list extracted from the Trigger column,
+// with each fragment trimmed of whitespace. An empty/none cell yields [].
+function parseTriggerTable(workflowMdRelPath) {
+  const lines = readLines(workflowMdRelPath);
+  // Find the header row that contains a "Trigger" column.
+  let headerIdx = -1;
+  let headerCells = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.includes('|')) continue;
+    // Must look like a markdown table header (next line is a separator).
+    const next = lines[i + 1] || '';
+    if (!/^\s*\|?\s*:?-{2,}/.test(next)) continue;
+    const cells = splitTableRow(line);
+    const hasTrigger = cells.some((c) => /^trigger(s| examples)?$/i.test(c.trim()));
+    const hasPrefix = cells.some((c) => /prefix/i.test(c) || /tag/i.test(c));
+    if (hasTrigger && hasPrefix) {
+      headerIdx = i;
+      headerCells = cells.map((c) => c.trim());
+      break;
+    }
+  }
+  if (headerIdx === -1) return null;
+
+  // Column indices: prefix-tag column and trigger column.
+  const prefixCol = headerCells.findIndex((c) => /prefix|tag/i.test(c));
+  const triggerCol = headerCells.findIndex((c) => /^trigger(s| examples)?$/i.test(c));
+  if (prefixCol === -1 || triggerCol === -1) return null;
+
+  const result = new Map();
+  // Skip separator row.
+  for (let i = headerIdx + 2; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.includes('|')) break;
+    if (/^\s*$/.test(line)) break;
+    const cells = splitTableRow(line);
+    if (cells.length < Math.max(prefixCol, triggerCol) + 1) continue;
+    const prefixCell = cells[prefixCol].trim();
+    const triggerCell = cells[triggerCol].trim();
+    // Prefix cell looks like `` `[step-NN]` ``.
+    const tagMatch = prefixCell.match(/\[step-\d{2}\]/);
+    if (!tagMatch) continue;
+    const stepTag = tagMatch[0];
+    const fragments = splitTriggerFragments(triggerCell);
+    result.set(stepTag, { fragments, rowLine: i + 1 });
+  }
+  return result;
+}
+
+function splitTableRow(line) {
+  // Strip leading/trailing pipes, split on `|`. Allows escaped `\|` to pass
+  // through as a literal pipe.
+  let s = line.trim();
+  if (s.startsWith('|')) s = s.slice(1);
+  if (s.endsWith('|')) s = s.slice(0, -1);
+  // Split on `|` not preceded by a backslash.
+  const cells = [];
+  let buf = '';
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (ch === '\\' && s[i + 1] === '|') {
+      buf += '|';
+      i++;
+      continue;
+    }
+    if (ch === '|') {
+      cells.push(buf);
+      buf = '';
+      continue;
+    }
+    buf += ch;
+  }
+  cells.push(buf);
+  return cells;
+}
+
+function splitTriggerFragments(cellText) {
+  const t = cellText.trim();
+  if (t === '' || t === '(none)' || t === '—') return [];
+  // Split on `;` and trim each.
+  return t
+    .split(';')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+// Collect emit literals per step tag.
+// Returns: Map<stepTag, Array<{ literal, file, lineNumber }>>
+function collectEmits(stepsDirRelPath) {
+  const dirAbs = path.join(PROJECT_ROOT, stepsDirRelPath);
+  const files = fs
+    .readdirSync(dirAbs)
+    .filter((f) => f.endsWith('.md') && !f.endsWith('.bak'))
+    .sort();
+  const map = new Map();
+  for (const f of files) {
+    const relPath = path.join(stepsDirRelPath, f);
+    const lines = readLines(relPath);
+    for (const [idx, line] of lines.entries()) {
+      const re = new RegExp(PRODUCER_RE.source, 'g');
+      let m;
+      while ((m = re.exec(line)) !== null) {
+        const literal = m[1].trim();
+        const tagMatch = literal.match(/^\[step-\d{2}\]/);
+        if (!tagMatch) continue;
+        const tag = tagMatch[0];
+        if (!map.has(tag)) map.set(tag, []);
+        map.get(tag).push({
+          literal,
+          file: f,
+          lineNumber: idx + 1,
+        });
+      }
+    }
+  }
+  return map;
+}
+
+function validatePipeline(pipeline) {
+  const table = parseTriggerTable(pipeline.workflowMd);
+  if (!table) {
+    return {
+      name: pipeline.name,
+      skipped: true,
+      reason: 'No "Trigger" convention table found in workflow.md',
+    };
+  }
+  const emits = collectEmits(pipeline.stepsDir);
+
+  const forward = []; // per-fragment matches
+  const reverse = []; // per-emit matches
+
+  // Iterate over step tags present in either source so that "column lists
+  // a step tag with no emits" and "emits exist for a tag the column omits"
+  // are both surfaced.
+  const allTags = new Set([...table.keys(), ...emits.keys()]);
+  for (const tag of [...allTags].sort()) {
+    const fragments = (table.get(tag) || { fragments: [] }).fragments;
+    const tagEmits = emits.get(tag) || [];
+
+    // FORWARD: each column fragment should match at least one emit literal.
+    for (const frag of fragments) {
+      const matched = tagEmits.some((e) => tokensMatch(frag, e.literal));
+      forward.push({ tag, fragment: frag, matched });
+    }
+
+    // REVERSE: each emit literal should match at least one column fragment.
+    for (const e of tagEmits) {
+      const matched = fragments.some((frag) => tokensMatch(frag, e.literal));
+      reverse.push({ tag, emit: e, matched });
+    }
+  }
+
+  return { name: pipeline.name, table, emits, forward, reverse };
+}
+
+function main() {
+  let anyMiss = false;
+  console.log('');
+  console.log(`Validating trigger column ↔ emits (bidirectional) in: ${PROJECT_ROOT}`);
+  console.log('');
+
+  for (const pipeline of PIPELINES) {
+    const result = validatePipeline(pipeline);
+    console.log(`[${result.name}]`);
+    if (result.skipped) {
+      console.log(`  Skipped: ${result.reason}`);
+      console.log('');
+      continue;
+    }
+    const fwdTotal = result.forward.length;
+    const fwdMatched = result.forward.filter((f) => f.matched).length;
+    const revTotal = result.reverse.length;
+    const revMatched = result.reverse.filter((r) => r.matched).length;
+
+    console.log(`  Forward (column → emits): ${fwdMatched}/${fwdTotal} fragments matched`);
+    for (const f of result.forward) {
+      if (!f.matched) {
+        anyMiss = true;
+        console.log(`    MISS: ${f.tag}  ${f.fragment}`);
+      }
+    }
+    console.log(`  Reverse (emits → column): ${revMatched}/${revTotal} emits matched`);
+    for (const r of result.reverse) {
+      if (!r.matched) {
+        anyMiss = true;
+        console.log(`    MISS: ${r.emit.file}:${r.emit.lineNumber}  ${r.emit.literal}`);
+      }
+    }
+    console.log('');
+  }
+
+  if (anyMiss) {
+    console.log('FAIL: bidirectional trigger↔emit audit reported one or more misses.');
+    process.exit(1);
+  }
+  console.log('All trigger fragments and emit literals are bidirectionally covered.');
+}
+
+main();

package/tools/validate-warnings-samples.js

@@ -0,0 +1,261 @@
+/**
+ * Warnings Sample Validator (M-series — closes proposal (j) in pipeline-optimization-report.md;
+ *                            extended in N-series — closes the JSON-array sample footnote from
+ *                            run #11 §5.-8.)
+ *
+ * Scans producer-side `Append to {run_warnings}: [step-NN] ...` literals across the
+ * auto-story-pipeline and auto-requirements-pipeline step files, then verifies that
+ * the sample STORY_RESULT / pipeline-status warnings documented in
+ *   src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline-batch/workflow.md
+ *     (the K1 "Concrete examples" YAML block introduced in run #9)
+ *   src/xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline/steps/step-08-finalize.md
+ *     (the L6 "Example concrete value" JSON-array block introduced in run #10,
+ *      first covered by the validator in run #12)
+ * still correspond to actual producer literals after variable substitution.
+ *
+ * Why this exists:
+ * - K-series introduced concrete sample STORY_RESULT outputs to make the
+ *   prefix-tagged warnings contract testable. The samples are doc fixtures —
+ *   when the producer-side literals drift (e.g., wording change in step-NN.md),
+ *   the samples silently fall behind. This script catches that drift.
+ * - N-series (run #12) extends sample detection from YAML-list-only to also cover
+ *   JSON-array form (`"[step-NN] ...",` lines inside ```json blocks). Both K1
+ *   (YAML) and L6 (JSON) samples are now gated by the same producer index.
+ *
+ * Algorithm:
+ *  1. Scan all step files for ``Append to `{run_warnings}`: `[step-NN] ...` `` lines.
+ *     Extract the prefix-tagged template (with `{variable}` placeholders).
+ *  2. Compile each template into a regex by replacing `{var}` with `.+?`.
+ *  3. Scan known sample locations for warning strings of the form `[step-NN] ...`
+ *     in either YAML-list form (`- "[step-NN] ..."`) or JSON-array form
+ *     (`"[step-NN] ...",`). A sample matching both forms only counts once
+ *     (YAML form wins; JSON form is a fallback for non-list-prefixed lines).
+ *  4. For each sample, find the template with matching `[step-NN]` prefix whose
+ *     regex matches the sample after variable substitution. If none matches,
+ *     report a drift.
+ *
+ * Usage:
+ *   node tools/validate-warnings-samples.js            # warn-only (exit 0)
+ *   node tools/validate-warnings-samples.js --strict    # fail (exit 1) on any drift
+ *   node tools/validate-warnings-samples.js --verbose   # print every check
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+const VERBOSE = process.argv.includes('--verbose');
+const STRICT = process.argv.includes('--strict');
+
+// Step file directories that emit `{run_warnings}` appends.
+const PRODUCER_DIRS = [
+  'src/xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline/steps',
+  'src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/steps',
+];
+
+// Doc files that contain sample STORY_RESULT / pipeline-status JSON warnings to validate.
+const SAMPLE_FILES = [
+  'src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline-batch/workflow.md',
+  'src/xmc-skills/1-analysis/xiaoma-auto-requirements-pipeline/steps/step-08-finalize.md',
+];
+
+// Matches a producer append line like:
+//   - Append to `{run_warnings}`: `[step-05] Unresolved code-review findings for ...`
+// Case-insensitive on the verb because some inline prose uses lowercase "append to ...".
+//
+// AT3 (run #44) — closes deferred AS4: relax to tolerate an inline qualifier between
+// `{run_warnings}` and the `:` introducing the literal (e.g., step-09-finalize.md writes
+// `Append to \`{run_warnings}\` with canonical prefix tag: \`[step-09] ...\``). The slack
+// `[^:`]*` is identical to the sibling validator
+// `tools/validate-trigger-column-vs-emits.js` PRODUCER_RE (run #43 AS1), so both
+// validators now parse producer literals with the same lexicon.
+const PRODUCER_RE = /[Aa]ppend to `\{run_warnings\}`[^:`]*:\s*`(\[step-\d{2}\][^`]+)`/g;
+
+// Matches a sample warning string of the form `[step-NN] ...` inside YAML list items
+// like `  - "[step-05] CRITICAL finding for 1.3 unresolvable inline — routed to step-07 ..."`.
+// We only match lines that begin a YAML list item ("- ") to keep the scan precise and
+// avoid false positives from prose mentions like `e.g., [step-05] CRITICAL ...`.
+const SAMPLE_RE = /^\s*-\s+["'](\[step-\d{2}\][^"']+)["']/;
+
+// N-series: matches a sample warning string of the form `[step-NN] ...` inside JSON-array
+// elements like `  "[step-01] No src/ directory ...",` or the trailing entry without a
+// comma `  "[step-08] Implementation-readiness GAPS: ..."`. The line must start with
+// optional whitespace + a double-quote + `[step-NN]` (so prose like `"warnings":` or
+// `"warnings": "{run_warnings}"` is correctly ignored — those lines either don't open with
+// a quote-then-[step-NN] or carry a JSON key prefix).
+//
+// We anchor on `^\s*"` + capture up to the closing quote, then require either a trailing
+// comma+EOL or just EOL (no other characters). This rejects inline JSON values where the
+// string is embedded in a larger structure (e.g., `{"warnings": "[step-NN] ..."}` on a
+// single line), which would be ambiguous as a sample anyway.
+const JSON_SAMPLE_RE = /^\s*"(\[step-\d{2}\][^"]+)"\s*,?\s*$/;
+
+function listMdFiles(dirRelative) {
+  const dirAbs = path.join(PROJECT_ROOT, dirRelative);
+  if (!fs.existsSync(dirAbs)) return [];
+  return fs
+    .readdirSync(dirAbs)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => path.join(dirRelative, f));
+}
+
+function readFileLines(relPath) {
+  const abs = path.join(PROJECT_ROOT, relPath);
+  return fs.readFileSync(abs, 'utf8').split('\n');
+}
+
+function escapeRegex(text) {
+  return text.replaceAll(/[\\^$.*+?()[\]{}|]/g, String.raw`\$&`);
+}
+
+// Convert a producer template (with `{var}` placeholders) into a regex source
+// that matches concrete values in samples. `{anything}` becomes `.+?` (non-greedy).
+function templateToRegexSource(template) {
+  // Split on {variable} placeholders, escape literal text between them, join with .+?
+  const parts = template.split(/\{[a-zA-Z_][a-zA-Z0-9_]*\}/);
+  return parts.map(escapeRegex).join('.+?');
+}
+
+function collectProducers() {
+  // prefix tag -> array of { template, regex, file, lineNumber }
+  const producers = new Map();
+  const allFiles = PRODUCER_DIRS.flatMap(listMdFiles);
+
+  for (const relPath of allFiles) {
+    const lines = readFileLines(relPath);
+    for (const [idx, line] of lines.entries()) {
+      let m;
+      // Use a fresh global regex per line to avoid lastIndex state leak across files.
+      const re = new RegExp(PRODUCER_RE.source, 'g');
+      while ((m = re.exec(line)) !== null) {
+        const template = m[1].trim();
+        const prefixMatch = template.match(/^\[step-\d{2}\]/);
+        if (!prefixMatch) continue;
+        const prefix = prefixMatch[0];
+        const regex = new RegExp('^' + templateToRegexSource(template) + '$');
+        if (!producers.has(prefix)) producers.set(prefix, []);
+        producers.get(prefix).push({
+          template,
+          regex,
+          file: relPath,
+          lineNumber: idx + 1,
+        });
+      }
+    }
+  }
+  return producers;
+}
+
+function collectSamples() {
+  // [{ sample, file, lineNumber, form }] where form is "yaml" or "json"
+  const samples = [];
+  for (const relPath of SAMPLE_FILES) {
+    const lines = readFileLines(relPath);
+    for (const [idx, line] of lines.entries()) {
+      // Try YAML-list form first (M-series — original M1 scope).
+      const yamlMatch = line.match(SAMPLE_RE);
+      if (yamlMatch) {
+        samples.push({
+          sample: yamlMatch[1].trim(),
+          file: relPath,
+          lineNumber: idx + 1,
+          form: 'yaml',
+        });
+        continue;
+      }
+      // Fall back to JSON-array form (N-series — run #12 extension).
+      // A line cannot match both — JSON form requires the line to start with a quote,
+      // YAML form requires a leading `- `; they are mutually exclusive.
+      const jsonMatch = line.match(JSON_SAMPLE_RE);
+      if (jsonMatch) {
+        samples.push({
+          sample: jsonMatch[1].trim(),
+          file: relPath,
+          lineNumber: idx + 1,
+          form: 'json',
+        });
+      }
+    }
+  }
+  return samples;
+}
+
+function validate() {
+  const producers = collectProducers();
+  const samples = collectSamples();
+
+  const drifts = [];
+  let okCount = 0;
+  const formCounts = { yaml: 0, json: 0 };
+
+  for (const { sample, file, lineNumber, form } of samples) {
+    formCounts[form] = (formCounts[form] || 0) + 1;
+    const prefixMatch = sample.match(/^\[step-\d{2}\]/);
+    if (!prefixMatch) {
+      drifts.push({
+        kind: 'malformed-prefix',
+        sample,
+        file,
+        lineNumber,
+        detail: 'Sample warning does not start with a [step-NN] prefix tag.',
+      });
+      continue;
+    }
+    const prefix = prefixMatch[0];
+    const candidates = producers.get(prefix) || [];
+
+    if (candidates.length === 0) {
+      drifts.push({
+        kind: 'no-producer',
+        sample,
+        file,
+        lineNumber,
+        detail: `No producer site found for prefix ${prefix}. Either the prefix is wrong in the sample or the producer was removed.`,
+      });
+      continue;
+    }
+
+    const matched = candidates.find((c) => c.regex.test(sample));
+    if (matched) {
+      okCount++;
+      if (VERBOSE) {
+        console.log(`OK   ${file}:${lineNumber} (${form}) matches ${matched.file}:${matched.lineNumber}`);
+      }
+    } else {
+      drifts.push({
+        kind: 'template-drift',
+        sample,
+        file,
+        lineNumber,
+        detail: `Sample does not match any of the ${candidates.length} producer template(s) for ${prefix}. Producer literals:\n${candidates.map((c) => `      - ${c.file}:${c.lineNumber}: ${c.template}`).join('\n')}`,
+      });
+    }
+  }
+
+  console.log('');
+  console.log(`Validating run_warnings sample fidelity in: ${PROJECT_ROOT}`);
+  console.log(`Mode: ${STRICT ? 'STRICT (exit 1 on drift)' : 'WARN (exit 0)'}`);
+  console.log('');
+  console.log(
+    `Producer templates indexed: ${[...producers.values()].reduce((n, arr) => n + arr.length, 0)} across ${producers.size} prefix tag(s)`,
+  );
+  console.log(`Sample warnings checked:   ${samples.length} (yaml: ${formCounts.yaml || 0}, json: ${formCounts.json || 0})`);
+  console.log(`Matched:                   ${okCount}`);
+  console.log(`Drifts found:              ${drifts.length}`);
+  console.log('');
+
+  if (drifts.length > 0) {
+    console.log('Drift details:');
+    for (const d of drifts) {
+      console.log(`  [${d.kind}] ${d.file}:${d.lineNumber}`);
+      console.log(`    Sample : ${d.sample}`);
+      console.log(`    Reason : ${d.detail}`);
+      console.log('');
+    }
+    if (STRICT) process.exit(1);
+  } else {
+    console.log('All sample warnings trace back to a producer literal.');
+  }
+}
+
+validate();

package/tools/xiaoma-npx-wrapper.js

@@ -15,7 +15,7 @@ const isNpxExecution = __dirname.includes('_npx') || __dirname.includes('.npm');
 if (isNpxExecution) {
   // Running via npx - spawn child process to preserve user's working directory
   const args = process.argv.slice(2);
-  const xiaomaCliPath = path.join(__dirname, 'cli', 'xiaoma-cli.js');
+  const xiaomaCliPath = path.join(__dirname, 'installer', 'xiaoma-cli.js');
 
   if (!fs.existsSync(xiaomaCliPath)) {
     console.error('Error: Could not find xiaoma-cli.js at', xiaomaCliPath);
@@ -34,5 +34,5 @@ if (isNpxExecution) {
   }
 } else {
   // Local execution - use require
-  require('./cli/xiaoma-cli.js');
+  require('./installer/xiaoma-cli.js');
 }