patina-cli 3.11.0 → 4.0.0

package/src/ouroboros.js

@@ -3,6 +3,31 @@ import { scoreText, scoreMPS, scoreFidelity, combinedScore } from './scoring.js'
 import { buildPrompt } from './prompt-builder.js';
 import { createLogger } from './logger.js';
 
+/**
+ * Run the iterative Ouroboros rewrite-and-score loop.
+ *
+ * @param {object} options Ouroboros options.
+ * @param {object} options.config Effective config with ouroboros settings.
+ * @param {object[]} options.patterns Loaded pattern packs.
+ * @param {object|null} options.profile Parsed profile.
+ * @param {object|null} options.voice Parsed voice guide.
+ * @param {object|null} [options.voiceSample] Optional voice sample payload.
+ * @param {object|null} options.scoring Parsed scoring guide.
+ * @param {string} options.text Source text to improve.
+ * @param {string} [options.apiKey] Provider API key.
+ * @param {string} [options.baseURL] Provider base URL.
+ * @param {string} [options.model] Model id.
+ * @param {Function} [options.callLLM] LLM implementation.
+ * @param {Function} [options.now] Clock returning epoch milliseconds.
+ * @param {Function} [options.sleep] Sleep helper for tests.
+ * @param {AbortSignal} [options.signal] External cancellation signal.
+ * @param {number} [options.timeout] Per-attempt backend timeout in milliseconds.
+ * @param {object} [options.logger] patina logger.
+ * @returns {Promise<{finalText: string, finalScore: number, iterations: number, reason: string, log: object[]}>} Final text and iteration log.
+ * @throws {Error} When model calls or scoring fail outside handled schema fallbacks.
+ * @example
+ * const result = await runOuroboros({ config, patterns, profile, voice, scoring, text });
+ */
 export async function runOuroboros({
   config,
   patterns,
@@ -18,6 +43,7 @@ export async function runOuroboros({
   now,
   sleep,
   signal,
+  timeout,
   logger = createLogger(),
 }) {
   const ouroborosConfig = config.ouroboros || {};
@@ -40,6 +66,7 @@ export async function runOuroboros({
     now,
     sleep,
     signal,
+    timeout,
     logger,
   });
 
@@ -98,6 +125,7 @@ export async function runOuroboros({
       now,
       sleep,
       signal,
+      timeout,
     });
 
     const scoreResult = await scoreText({
@@ -111,6 +139,7 @@ export async function runOuroboros({
       now,
       sleep,
       signal,
+      timeout,
       logger,
     });
 
@@ -134,6 +163,7 @@ export async function runOuroboros({
         now,
         sleep,
         signal,
+        timeout,
         logger,
       }),
       scoreFidelity({
@@ -146,6 +176,7 @@ export async function runOuroboros({
         now,
         sleep,
         signal,
+        timeout,
         logger,
       }),
     ]);

package/src/output.js

@@ -1,9 +1,33 @@
+// @ts-check
 import { createLogger } from './logger.js';
-
+import { analyzeText } from './features/index.js';
+import { TRANSLATIONESE_RULES } from './features/translationese.js';
+
+/**
+ * Format a raw backend result for CLI output mode and requested format.
+ *
+ * @param {string|object} result Backend result or structured mode result.
+ * @param {string} mode Output mode: rewrite, diff, audit, score, or ouroboros.
+ * @param {object} [parsed={}] Parsed CLI options.
+ * @param {object} [opts={}] Formatting options.
+ * @param {object|null} [opts.tone] Tone metadata to append.
+ * @param {object} [opts.logger] Logger for output warnings.
+ * @param {object} [opts.env] Environment map for color decisions.
+ * @param {object} [opts.stdout] Stdout-like stream for color decisions.
+ * @param {string} [opts.auditBackstop] Deterministic audit-mode section to append before the tone footer.
+ * @returns {string} User-facing formatted output.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const output = formatOutput('[BODY]Hi[/BODY]', 'rewrite');
+ */
 export function formatOutput(result, mode, parsed = {}, opts = {}) {
   const tone = opts.tone || null;
   const format = parsed.format || 'markdown';
-  const body = renderFormattedBody(result, mode, parsed, opts);
+  let body = renderFormattedBody(result, mode, parsed, opts);
+
+  if (mode === 'audit' && format !== 'json' && opts.auditBackstop) {
+    body += opts.auditBackstop;
+  }
 
   if (format === 'json') {
     return formatJsonOutput({ result, mode, body, tone, gate: parsed.gate });
@@ -18,11 +42,10 @@ export function formatOutput(result, mode, parsed = {}, opts = {}) {
 
 function renderFormattedBody(result, mode, parsed = {}, opts = {}) {
   let body = renderBody(result);
-  // Only rewrite and ouroboros emit [BODY]/[VARIANT n] tags; diff/audit/score
+  // Only rewrite and ouroboros emit [BODY] tags; diff/audit/score
   // emit tables and don't need the extraction step.
   if (mode === 'rewrite' || mode === 'ouroboros') {
-    const variants = extractVariants(body);
-    body = variants.length > 0 ? formatVariants(variants, body) : stripSelfAudit(body, { logger: opts.logger });
+    body = stripSelfAudit(body, { logger: opts.logger });
   }
   if (mode === 'diff') {
     body = colorizeDiff(body, { parsed, env: opts.env, stdout: opts.stdout });
@@ -54,39 +77,18 @@ function colorizeDiff(body, { parsed = {}, env = process.env, stdout = process.s
   }).join('\n');
 }
 
+/**
+ * @param {object} [options]
+ * @param {object} [options.parsed]
+ * @param {boolean} [options.parsed.noColor]
+ * @param {Record<string, string|undefined>} [options.env]
+ * @param {object} [options.stdout]
+ * @param {boolean} [options.stdout.isTTY]
+ */
 function shouldColorDiff({ parsed = {}, env = process.env, stdout = process.stdout } = {}) {
   return !parsed.noColor && env.NO_COLOR === undefined && stdout?.isTTY === true;
 }
 
-// v3.11 Phase 3.1: extract [VARIANT n]...[/VARIANT] blocks from a model
-// response. Returns an array of { id, text } sorted by id, empty if no
-// variant tags are present.
-export function extractVariants(body) {
-  if (!body) return [];
-  const re = /\[VARIANT\s*(\d+)\]\s*\n([\s\S]*?)\n\s*\[\/VARIANT\]/g;
-  const out = [];
-  let m;
-  while ((m = re.exec(body)) !== null) {
-    const id = parseInt(m[1], 10);
-    const text = m[2].trim();
-    if (text) out.push({ id, text });
-  }
-  out.sort((a, b) => a.id - b.id);
-  return out;
-}
-
-function formatVariants(variants, raw) {
-  // Surface each variant with a labeled header so users can copy whichever
-  // voice they want. Strip [SELF_AUDIT] and any tail metadata that follows
-  // the last [/VARIANT] block, but preserve the YAML footer if present.
-  const lastClose = raw.lastIndexOf('[/VARIANT]');
-  const tail = lastClose >= 0
-    ? raw.slice(lastClose + '[/VARIANT]'.length).replace(/\[SELF_AUDIT\][\s\S]*?\[\/SELF_AUDIT\]/g, '').trim()
-    : '';
-  const blocks = variants.map(({ id, text }) => `## Variant ${id}\n\n${text}`);
-  const merged = blocks.join('\n\n');
-  return tail ? `${merged}\n\n${tail}` : merged;
-}
 
 // v3.11 Phase 1.3: parse the model's score table and check that the Weight
 // column matches the config-supplied category-weights. case-02 found that
@@ -95,6 +97,16 @@ function formatVariants(variants, raw) {
 //
 // Returns an array of human-readable warning strings (empty if everything
 // matches). Caller is responsible for emitting to stderr.
+/**
+ * Validate that a model-emitted score table used configured category weights.
+ *
+ * @param {string} output Score-mode markdown output.
+ * @param {object} configWeights Expected category weight map.
+ * @returns {string[]} Human-readable warnings for missing, mismatched, or unexpected categories.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const warnings = validateScoreWeights('| content | 0.4 | 1 | 10 | 4 |', { content: 0.4 });
+ */
 export function validateScoreWeights(output, configWeights) {
   if (!output || !configWeights || Object.keys(configWeights).length === 0) {
     return [];
@@ -201,6 +213,17 @@ function normalizeCategoryName(raw) {
 // We extract the body block and drop the audit so callers get clean text.
 // If the model didn't honor the tags (older runs, mocked tests, etc.), we
 // fall back to returning the full output untouched.
+/**
+ * Remove SELF_AUDIT blocks and unwrap the BODY block from rewrite output.
+ *
+ * @param {string} body Raw model response.
+ * @param {object} [options] Strip options.
+ * @param {object} [options.logger] Logger for malformed output warnings.
+ * @returns {string} Clean user-facing body text.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const clean = stripSelfAudit('[BODY]Hello[/BODY]\n[SELF_AUDIT]ok[/SELF_AUDIT]');
+ */
 export function stripSelfAudit(body, { logger = createLogger() } = {}) {
   if (!body) return body;
   const bodyOpen = body.indexOf('[BODY]');
@@ -209,7 +232,7 @@ export function stripSelfAudit(body, { logger = createLogger() } = {}) {
     const stripped = removeSelfAuditBlocks(body).trim();
     if (stripped !== body.trim()) {
       logger.warn('output.missing_body_tags', {
-        message: `[patina] warning: model output omitted [BODY] tags (${body.length} chars); stripped [SELF_AUDIT]. Re-run with --prompt-mode strict if the output looks wrong.`,
+        message: `[patina] warning: model output omitted [BODY] tags (${body.length} chars); stripped [SELF_AUDIT]. Try a different backend if the output looks wrong.`,
       });
       return stripped;
     }
@@ -233,9 +256,6 @@ function renderBody(result) {
     return String(result.raw).trim();
   }
 
-  if (result?.type === 'max-mode') {
-    return formatMaxModeOutput(result);
-  }
 
   return String(result).trim();
 }
@@ -282,24 +302,6 @@ function formatJsonOutput({ result, mode, body, tone, gate }) {
   const scoreDetails = extractScoreDetails(result);
   if (scoreDetails) payload.scores = scoreDetails;
 
-  if (result?.type === 'max-mode') {
-    payload.max = {
-      allFailed: Boolean(result.allFailed),
-      mpsFallback: Boolean(result.mpsFallback),
-      best: result.best ? {
-        model: result.best.model,
-        aiScore: result.best.aiScore ?? null,
-        mps: result.best.mps ?? null,
-      } : null,
-      candidates: result.candidates.map((candidate) => ({
-        model: candidate.model,
-        ok: Boolean(candidate.ok),
-        aiScore: candidate.aiScore ?? null,
-        mps: candidate.mps ?? null,
-        error: candidate.error ?? null,
-      })),
-    };
-  }
 
   return JSON.stringify(payload, null, 2);
 }
@@ -436,45 +438,55 @@ function normalizeFooterTail(lines) {
     .trim();
 }
 
-function formatMaxModeOutput(result) {
-  const { candidates, best } = result;
+/**
+ * Build a deterministic "backstop" section for audit mode. The LLM audit is
+ * model-dependent (a weak model silently drops 번역투/calques); these signals are
+ * computed deterministically so they appear regardless of which model ran. ko
+ * translationese rules are listed even below the hot-density gate, because audit
+ * is a hint surface, not a verdict.
+ *
+ * @param {string} text Source text.
+ * @param {object} [opts]
+ * @param {string} [opts.lang]
+ * @param {string} [opts.repoRoot]
+ * @returns {string} Markdown section (empty string when nothing fired).
+ */
+export function buildDeterministicAuditBackstop(text, opts = {}) {
+  const lang = opts.lang ?? 'ko';
+  const str = typeof text === 'string' ? text : '';
+  /** @type {Array<{signal:string,label:string,severity:string,location:string}>} */
+  const rows = [];
 
-  let output = '## MAX Mode Results\n\n';
-  if (result.timedOut) {
-    output += '⚠ MAX wall-clock timeout reached; showing partial results.\n\n';
-  }
-  output += '| Model | AI Score | MPS | Status |\n';
-  output += '|-------|----------|-----|--------|\n';
-
-  for (const c of candidates) {
-    const status = c.ok ? (c.model === best?.model ? '✅ best' : '✅') : '❌ failed';
-    const score = c.aiScore ?? '--';
-    const mps = c.mps ?? '--';
-    output += `| ${c.model} | ${score} | ${mps} | ${status} |\n`;
+  // ko translationese — per-rule, with matched samples (model-independent).
+  if (lang === 'ko' && str) {
+    for (const rule of TRANSLATIONESE_RULES) {
+      const matches = str.match(rule.re());
+      if (matches && matches.length) {
+        const samples = [...new Set(matches.map((m) => m.trim()).filter(Boolean))].slice(0, 4);
+        rows.push({ signal: `번역투: ${rule.id}`, label: rule.label, severity: rule.strong ? 'MEDIUM' : 'LOW', location: samples.join(', ') });
+      }
+    }
   }
 
-  output += `\n**Best: ${best?.model || 'none'}**\n\n`;
-
-  if (result.allFailed) {
-    output += '> No MAX candidate produced a scoreable result. Exit code: 4.\n\n';
-  } else if (result.mpsFallback) {
-    output += '⚠ No candidate passed MPS ≥ 70 — selecting by highest MPS (fallback)\n\n';
-    output += '> Exit code: 4.\n\n';
+  // markup leakage (near-proof) + density-gated discourse tells — language-agnostic.
+  const a = analyzeText(str, { lang, repoRoot: opts.repoRoot });
+  for (const h of a.markupLeakage?.hits ?? []) {
+    rows.push({ signal: 'markup-leakage', label: h.label, severity: 'HIGH', location: (h.samples ?? []).join(', ') });
   }
-
-  if (best?.result) {
-    output += '### Final Text\n\n';
-    output += best.result.trim();
-    output += '\n\n';
+  if (a.discourseTells?.fakeCandor?.hot) {
+    rows.push({ signal: 'discourse: fake-candor', label: '친근함 위장 도입부', severity: 'MEDIUM', location: (a.discourseTells.fakeCandor.hits ?? []).join(', ') });
   }
-
-  for (const c of candidates) {
-    if (c.model !== best?.model && c.ok && c.result) {
-      output += `\n<details>\n<summary>${c.model} result</summary>\n\n`;
-      output += c.result.trim();
-      output += '\n</details>\n';
-    }
+  if (a.discourseTells?.thematicBreaks?.hot) {
+    rows.push({ signal: 'discourse: thematic-breaks', label: '장식용 구분선 남용', severity: 'LOW', location: `${a.discourseTells.thematicBreaks.count}개` });
   }
 
-  return output;
+  if (rows.length === 0) return '';
+  const lines = [
+    '## 결정적 신호 (deterministic backstop — 모델과 무관하게 항상 검사)',
+    '',
+    '| 신호 | 설명 | 심각도 | 위치 |',
+    '|------|------|--------|------|',
+    ...rows.map((r) => `| ${r.signal} | ${r.label} | ${r.severity} | ${r.location} |`),
+  ];
+  return `\n\n${lines.join('\n')}`;
 }

package/src/prompt-builder.js

@@ -1,23 +1,41 @@
-export function buildPrompt({
-  config,
-  patterns,
-  profile,
-  voice,
-  voiceSample,
-  scoring,
-  text,
-  mode = 'rewrite',
-  tone = null,
-  promptMode = 'strict',
-  variants = 1,
-}) {
-  // v3.11+ prompt-mode dispatch (case-04 hypothesis test). minimal prompt
-  // strips pattern definitions/examples and uses a casual instruction; only
-  // applies to rewrite mode where voice prior matters most. Profile body is
-  // still passed through (Round 2 found Gemini ignored casual-conversation
-  // when the profile was dropped).
+// @ts-check
+/**
+ * Build the LLM prompt for rewrite, diff, audit, score, or ouroboros mode.
+ *
+ * @param {object} options Prompt inputs.
+ * @param {object} options.config Effective patina config.
+ * @param {object[]} options.patterns Loaded pattern packs.
+ * @param {object|null} options.profile Parsed profile document.
+ * @param {object|null} options.voice Parsed voice guide.
+ * @param {object|null} [options.voiceSample] Optional voice sample payload.
+ * @param {object|null} options.scoring Parsed scoring guide.
+ * @param {string} options.text Input text.
+ * @param {string} [options.mode=rewrite] Output mode.
+ * @param {object|null} [options.tone=null] Tone resolution metadata.
+ * @returns {string} Complete prompt text.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const prompt = buildPrompt({ config, patterns, profile, voice, scoring, text: 'Draft' });
+ */
+export function buildPrompt(options) {
+  const {
+    config,
+    patterns,
+    profile,
+    voice,
+    voiceSample,
+    scoring,
+    text,
+    mode = 'rewrite',
+    tone = null,
+  } = options;
+  const promptMode = /** @type {any} */ (options).promptMode || 'strict';
+  // v3.11+ internal backend prompt-style dispatch. The compact prompt strips
+  // pattern definitions/examples and uses a casual instruction; it only applies
+  // to rewrite mode where voice prior matters most. Profile body is still passed
+  // through (Round 2 found Gemini ignored casual-conversation when omitted).
   if (promptMode === 'minimal' && mode === 'rewrite') {
-    return buildMinimalPrompt({ config, patterns, profile, voiceSample, text, tone, variants });
+    return buildMinimalPrompt({ config, patterns, profile, voiceSample, text, tone });
   }
 
   const lang = config.language || 'ko';
@@ -100,7 +118,7 @@ export function buildPrompt({
   prompt += `Process the following text according to the output mode "${mode}".\n\n`;
 
   if (mode === 'rewrite') {
-    prompt += buildRewriteInstructions(structurePacks, lexicalPacks, { variants });
+    prompt += buildRewriteInstructions(structurePacks, lexicalPacks, { lang });
   } else if (mode === 'diff') {
     prompt += buildDiffInstructions();
   } else if (mode === 'audit') {
@@ -117,7 +135,7 @@ export function buildPrompt({
   return prompt;
 }
 
-function buildRewriteInstructions(structurePacks, lexicalPacks, { includeSelfAudit = true, variants = 1 } = {}) {
+function buildRewriteInstructions(structurePacks, lexicalPacks, { includeSelfAudit = true, lang = 'ko' } = {}) {
   const phaseCount = includeSelfAudit ? 3 : 2;
   let inst = `Follow the ${phaseCount}-Phase pipeline:\n\n`;
 
@@ -145,6 +163,11 @@ function buildRewriteInstructions(structurePacks, lexicalPacks, { includeSelfAud
   inst += `4. Match profile tone\n`;
   inst += `5. Inject personality per voice guidelines\n`;
   inst += `6. Respect blocklist/allowlist and pattern overrides\n\n`;
+  const cjkGuard = buildCjkClauseRewriteGuard(lang);
+  if (cjkGuard) {
+    inst += `${cjkGuard}\n`;
+  }
+
 
   if (includeSelfAudit) {
     inst += `### Phase 3: Self-Audit\n\n`;
@@ -153,7 +176,7 @@ function buildRewriteInstructions(structurePacks, lexicalPacks, { includeSelfAud
     inst += `3. Ensure Phase 1 corrections were not reverted in Phase 2\n`;
     inst += `4. Final check: meaning preserved?\n\n`;
 
-    inst += buildOutputFormatBlock({ variants });
+    inst += buildOutputFormatBlock();
   } else {
     // Self-audit suppressed: external evaluators (scoreText, scoreMPS,
     // scoreFidelity) handle AI-tell detection, polarity, and meaning checks
@@ -165,50 +188,55 @@ function buildRewriteInstructions(structurePacks, lexicalPacks, { includeSelfAud
   return inst;
 }
 
-// v3.11: emit the strict-mode output-format block. Single-variant uses
-// [BODY]/[/BODY]; --variants > 1 uses [VARIANT n]/[/VARIANT] blocks.
-function buildOutputFormatBlock({ variants = 1 } = {}) {
-  const isVariants = variants > 1;
-  const tag = isVariants ? '[VARIANT n]/[/VARIANT]' : '[BODY]/[/BODY]';
-  const itemDesc = isVariants
-    ? `Produce ${variants} stylistic VARIANTS of the rewrite, each wrapped in ` +
-      `\`[VARIANT n]\`/\`[/VARIANT]\` tags where n is 1..${variants}. Each ` +
-      `variant must preserve all facts, numbers, and causation, but differ in ` +
-      `voice (e.g., V1 casual conversational, V2 direct/punchy, V3 measured/` +
-      `professional). No headings, no preamble inside the tags.`
-    : `The rewritten text wrapped in \`[BODY]\`/\`[/BODY]\` tags. The body ` +
-      `block must contain ONLY the user-facing rewrite — no headings, no ` +
-      `Phase labels, no preamble like "잔여 AI 티" or "최종 결과물".`;
-  const auditDesc = isVariants
-    ? `(brief: what differs across variants, residual AI signals, applied patterns)`
-    : `(brief: what still looks AI-written, which patterns were applied). ` +
-      `This block is for downstream review — patina strips it before showing the user`;
-
-  let exampleBody = '';
-  if (isVariants) {
-    for (let i = 1; i <= variants; i++) {
-      exampleBody += `[VARIANT ${i}]\n<rewritten text — voice ${i}>\n[/VARIANT]\n\n`;
-    }
-  } else {
-    exampleBody = `[BODY]\n<rewritten text>\n[/BODY]\n\n`;
-  }
-
+function buildOutputFormatBlock() {
   return (
     `### Output format (STRICT — v3.11)\n\n` +
     `Produce output in this exact order, with no other text outside the tagged blocks:\n\n` +
-    `1. ${itemDesc}\n` +
-    `2. Self-audit notes wrapped in \`[SELF_AUDIT]\`/\`[/SELF_AUDIT]\` tags ${auditDesc}.\n` +
+    `1. The rewritten text wrapped in \`[BODY]\`/\`[/BODY]\` tags. The body ` +
+      `block must contain ONLY the user-facing rewrite — no headings, no ` +
+      `Phase labels, no preamble like "잔여 AI 티" or "최종 결과물".\n` +
+    `2. Self-audit notes wrapped in \`[SELF_AUDIT]\`/\`[/SELF_AUDIT]\` tags ` +
+      `(brief: what still looks AI-written, which patterns were applied). ` +
+      `This block is for downstream review — patina strips it before showing the user.\n` +
     `3. The Phase 6 YAML footer if tone resolution requires it.\n\n` +
-    `Example shape (uses ${tag}):\n\n` +
+    `Example shape (uses [BODY]/[/BODY]):\n\n` +
     '```\n' +
-    exampleBody +
-    `[SELF_AUDIT]\n- ${isVariants ? 'voice axis' : 'residual signals'}: ...\n` +
-    `- ${isVariants ? 'residual signals' : 'patterns applied'}: ...\n[/SELF_AUDIT]\n\n` +
+    `[BODY]\n<rewritten text>\n[/BODY]\n\n` +
+    `[SELF_AUDIT]\n- residual signals: ...\n` +
+    `- patterns applied: ...\n[/SELF_AUDIT]\n\n` +
     `---\ntone: ...\ntone_source: ...\ntone_evidence: [...]\ntone_confidence: ...\n---\n` +
     '```\n'
   );
 }
 
+function buildCjkClauseRewriteGuard(lang) {
+  if (!['ko', 'zh', 'ja'].includes(lang)) return '';
+
+  const shared = [
+    `### CJK clause-level rewrite guard`,
+    ``,
+    `For Korean, Chinese, and Japanese, do not fix AI tells by swapping punctuation or single tokens in place. Read the full sentence, then rewrite the affected clause or sentence so the clause relationship is idiomatic in the target language.`,
+    `- If the suspect segment uses connective punctuation (em dash, colon, semicolon, slash, comma splice, parenthetical aside), choose a natural clause structure, sentence split, or connective phrase; do not replace every mark 1:1 with a comma or parentheses.`,
+    `- If a calque/translationese phrase is attached to punctuation, fix both together at clause level. Preserve who did what, polarity, conditions, numbers, and causation.`,
+  ];
+
+  if (lang === 'ko') {
+    shared.push(
+      `- Korean examples: write "TUI 없이 완전 자율로 설치하려면 ..." rather than "무 TUI ..."; write "끝난 것 같아요"만으로는 부족한, 결과를 끝까지 확인해야 하는 열린 작업 rather than "끝난 것 같아요"로는 부족한 열린 작업.`
+    );
+  } else if (lang === 'zh') {
+    shared.push(
+      `- Chinese example: "不用 TUI 就能全自动安装时，打开自律模式参数" is preferable to a literal "无 TUI 设置"; an em dash should become a causal, contrastive, or appositive clause only when that relation is present.`
+    );
+  } else if (lang === 'ja') {
+    shared.push(
+      `- Japanese example: "TUIなしで完全自律インストールにしたい場合は..." is preferable to a literal calque; an em dash should become a natural 接続, 説明節, or sentence split only when the relation is present.`
+    );
+  }
+
+  return `${shared.join('\n')}\n`;
+}
+
 function buildDiffInstructions() {
   return `Show what changed and why, pattern by pattern. For each change use this exact label format:\n\n` +
     `Pattern: N. Pattern Name\n` +
@@ -271,6 +299,15 @@ function buildScoreInstructions(config, lang, text = '') {
 
 // v3.11 Phase 3.2 helper: classify a text as "short" for scoring boost.
 // Threshold: ≤200 non-whitespace chars OR ≤3 non-empty paragraphs.
+/**
+ * Classify whether text should use the short-text scoring boost.
+ *
+ * @param {string} text Text to inspect.
+ * @returns {boolean} True when text is <=200 non-whitespace chars or <=3 paragraphs.
+ * @throws {Error} Propagates validation, filesystem, network, or dependency failures when the underlying operation cannot complete.
+ * @example
+ * const short = isShortText('A short note.');
+ */
 export function isShortText(text) {
   if (!text) return true;
   const stripped = text.replace(/\s+/g, '');
@@ -284,7 +321,7 @@ export function isShortText(text) {
 // model's natural voice prior isn't overridden by analytical framing. Only
 // invoked for rewrite mode; score/audit/diff/ouroboros stay on the strict
 // path because they need precise pattern references.
-function buildMinimalPrompt({ config, patterns, profile, voiceSample, text, tone, variants = 1 }) {
+function buildMinimalPrompt({ config, patterns, profile, voiceSample, text, tone }) {
   const lang = config.language || 'ko';
   const activePatterns = patterns.filter((p) => !p.isScoreOnly);
 
@@ -302,6 +339,10 @@ function buildMinimalPrompt({ config, patterns, profile, voiceSample, text, tone
     : `This text reads like AI. Rewrite it so it sounds like a real person wrote it. If you spot any of the phrases below, swap them out for something natural. Don't over-paraphrase — keep the meaning, numbers, and causation intact.`;
 
   let prompt = `${instruction}\n\n`;
+  const cjkGuard = buildCjkClauseRewriteGuard(lang);
+  if (cjkGuard) {
+    prompt += `${cjkGuard}\n`;
+  }
 
   if (watchWords.length > 0) {
     prompt += lang === 'ko' ? `## AI 신호 어휘 (참고)\n\n` : `## AI signal words (reference)\n\n`;
@@ -328,16 +369,9 @@ function buildMinimalPrompt({ config, patterns, profile, voiceSample, text, tone
   }
 
   prompt += lang === 'ko' ? `## 출력 형식\n\n` : `## Output format\n\n`;
-  if (variants > 1) {
-    prompt += `1. ${variants}개 voice variant를 각각 \`[VARIANT 1]\` ~ \`[VARIANT ${variants}]\` ` +
-      `태그 안에. 사실·숫자·인과관계는 동일하되 voice만 다르게 (예: V1 캐주얼 대화체, V2 직설·짧은 문장, V3 정중·차분).\n`;
-    prompt += `2. \`[SELF_AUDIT]\` ... \`[/SELF_AUDIT]\` 안에 짧게: variant별 voice 차이, 남은 AI 신호.\n`;
-    prompt += `3. 톤 정보가 있으면 마지막에 YAML 푸터.\n\n`;
-  } else {
-    prompt += `1. 다듬은 본문을 \`[BODY]\` ... \`[/BODY]\` 안에. 본문만, 머리말·메타·"최종 결과물" 같은 라벨 없이.\n`;
-    prompt += `2. \`[SELF_AUDIT]\` ... \`[/SELF_AUDIT]\` 안에 짧게: 어떤 부분 손봤는지, 남은 AI 신호 있는지.\n`;
-    prompt += `3. 톤 정보가 있으면 마지막에 YAML 푸터: \`---\\ntone: ...\\ntone_source: ...\\ntone_evidence: [...]\\ntone_confidence: ...\\n---\`\n\n`;
-  }
+  prompt += `1. 다듬은 본문을 \`[BODY]\` ... \`[/BODY]\` 안에. 본문만, 머리말·메타·"최종 결과물" 같은 라벨 없이.\n`;
+  prompt += `2. \`[SELF_AUDIT]\` ... \`[/SELF_AUDIT]\` 안에 짧게: 어떤 부분 손봤는지, 남은 AI 신호 있는지.\n`;
+  prompt += `3. 톤 정보가 있으면 마지막에 YAML 푸터: \`---\\ntone: ...\\ntone_source: ...\\ntone_evidence: [...]\\ntone_confidence: ...\\n---\`\n\n`;
 
   prompt += lang === 'ko' ? `## 입력\n\n${text}\n\n` : `## Input\n\n${text}\n\n`;
   prompt += lang === 'ko' ? `## 출력\n\n` : `## Output\n\n`;
@@ -385,6 +419,7 @@ function buildOuroborosInstructions(config, structurePacks, lexicalPacks) {
   const fidelityFloor = ouroboros['fidelity-floor'] ?? 70;
   const mpsFloor = ouroboros['mps-floor'] ?? 70;
 
+  const lang = config.language || 'ko';
   let inst = `Iterative self-improvement loop:\n\n`;
   inst += `1. Measure initial AI-likeness score\n`;
   inst += `2. If score ≤ ${targetScore}, stop immediately\n`;
@@ -403,7 +438,7 @@ function buildOuroborosInstructions(config, structurePacks, lexicalPacks) {
   // Skip Phase 3 self-audit: each iteration runs through external evaluators
   // (scoreText, scoreMPS, scoreFidelity) in src/ouroboros.js, so an in-prompt
   // self-audit duplicates work and inflates token cost.
-  inst += buildRewriteInstructions(structurePacks, lexicalPacks, { includeSelfAudit: false });
+  inst += buildRewriteInstructions(structurePacks, lexicalPacks, { includeSelfAudit: false, lang });
 
   return inst;
 }