litura-app 0.1.0

package/review-model.js

@@ -0,0 +1,38 @@
+import { completeText } from './pi.js';
+import { mergeReviewFindings, parseReviewResponse, validateReviewFindings } from './review.js';
+
+async function requestReviewPass({ systemPrompt, userPrompt, allowedCodes, source, selection, attempts }) {
+  let lastError;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      const raw = await completeText({
+        systemPrompt,
+        userPrompt: attempt === 0
+          ? userPrompt
+          : `${userPrompt}\n\n---\n\nRESPONSE RETRY: ${lastError.message}. Return the valid JSON array required by the system prompt, even when it is empty.`,
+        selection,
+        maxTokens: 4000,
+        signal: AbortSignal.timeout(90_000),
+      });
+      const findings = parseReviewResponse(raw);
+      validateReviewFindings(findings, allowedCodes, source);
+      return findings;
+    } catch (error) {
+      lastError = error;
+      if (attempt + 1 < attempts) {
+        await new Promise(resolve => setTimeout(resolve, 300 * (attempt + 1)));
+      }
+    }
+  }
+  throw lastError;
+}
+
+export async function requestReview({ systemPrompt, userPrompt, prompts, selection, attempts = 3 }) {
+  const requests = prompts ?? [{ systemPrompt, userPrompt }];
+  const groups = await Promise.all(requests.map(prompt => requestReviewPass({
+    ...prompt,
+    selection,
+    attempts,
+  })));
+  return mergeReviewFindings(groups);
+}

package/review-prompt.js

@@ -0,0 +1,93 @@
+export const REVIEW_CODES = [
+  'level-1-whole-essay',
+  'level-2-introduction',
+  'level-3-index-discussion',
+  'level-4-fractal-structure',
+  'level-5-point-placement',
+  'level-6-key-terms',
+  'level-7-paragraph-flow',
+  'generic-prose',
+];
+
+export function reviewCodesForPass(targeted, phase) {
+  return phase === 'global' ? REVIEW_CODES.slice(0, 4)
+    : phase === 'local' ? REVIEW_CODES.slice(targeted ? 5 : 4) : REVIEW_CODES;
+}
+
+export function buildReviewTask({ targeted = false, phase = 'all' } = {}) {
+  const allowedCodes = reviewCodesForPass(targeted, phase);
+  const scope = targeted
+    ? 'Audit ONLY the passages under PASSAGES TO AUDIT. The draft is context you must read but must not flag. ' +
+      'Every quote must be copied from those passages. For structure, use only level-6-key-terms, ' +
+      'level-7-paragraph-flow, or generic-prose; reserve larger structural findings for a full review. '
+    : '';
+  const phaseScope = phase === 'global'
+    ? 'This is the global structure pass. Use only levels 1 through 4; do not report paragraph-level or generic-prose findings. '
+    : phase === 'local'
+      ? `This is the local prose and paragraph pass. Use only ${allowedCodes.join(', ')}; do not diagnose whole-essay structure. `
+      : '';
+  const globalRules = phase === 'local' ? '' :
+    'A recommendation introduced with should or must but no destabilizing problem or cost is a clear level-2-introduction failure. ' +
+    'At level 2, cost means the consequence of the opening problem for the reader or subject; do not require an obstacle, objection, or implementation cost for the recommendation. Assess the opening unit as a whole, not every later recommendation paragraph as a new introduction. ' +
+    'At level 3, an enumeration is an index only when its wording promises the structure or contents that follow. A list whose items are all developed in the immediately following sentence or clauses has kept its local promise; do not require the rest of the essay to use that list as its outline. ' +
+    'Do not use level 3 or 4 for one isolated unrelated sentence inside an otherwise relevant paragraph; the local pass handles that as level 7. Reserve level 4 for a whole paragraph or section that fails to support its containing unit. ' +
+    'Final whole-essay check: when a title recommends an action but the ending says that action remains undecided or unavailable, report level-1-whole-essay because the opening problem remains unresolved. ';
+  const localRules = phase === 'global' ? '' :
+    'Run these three local diagnostic passes unless the genre is excluded; do not return [] merely because grammar is clean. ' +
+    'At level 5, mechanically locate the main claim of every explanatory paragraph with at least five sentences. If it is neither the first nor the last sentence, report level-5-point-placement even when the paragraph is otherwise coherent. ' +
+    'In an argumentative paragraph, treat its primary should or must recommendation as the main claim; do not mistake an earlier descriptive topic sentence for that claim. ' +
+    'At level 6, list the central terms established by an opening and verify that the discussion carries them through repetition, a clear synonym, a pronoun, or an unambiguous conceptual continuation. Report an unannounced replacement term only when it makes the referent or organising promise unclear. Terms introduced and explained inside the same opening unit are fulfilled locally; do not require them to recur later unless the draft explicitly announces them as continuing threads. ' +
+    'If a missing term is itself an item in an explicit opening index, omit the level-6 finding because the global pass handles the broken promise at level 3. ' +
+    'At level 7, compare every pair of consecutive sentence themes. If a sentence introduces an unrelated subject with no shared term, pronoun, synonym, or conceptual bridge, report level-7-paragraph-flow even in a three-sentence paragraph. A clear contrast, cause and effect, example, general-to-specific move, instruction, or catalogue supplies a conceptual bridge without repeated wording. ' +
+    'An unexplained switch to a different entity or domain is a clear level-7 failure; do not assume intentional disorientation unless the draft signals a narrative or artistic purpose. ' +
+    'Before reporting level 7, test the ideas rather than vocabulary: a move from a misuse or problem to its proper use or remedy, or from a claim to an instruction about the same activity, is a conceptual bridge. ' +
+    'In aphoristic, historical, or deliberately list-like prose, do not flag a grammatical subject change by itself when the ideas remain plainly related. If an unrelated passage forms a whole paragraph or section rather than one sentence, omit level 7 because the global pass handles it at level 4. ' +
+    'Final local check before answering: in every five-sentence-or-longer argumentative paragraph, a should/must recommendation with at least two sentences before and after it requires level-5-point-placement. ';
+
+  return (
+    'You are a sharp human editor auditing a draft for writing and reader-structure problems. ' +
+    scope +
+    phaseScope +
+    'Detect only; do not rewrite the draft, score it, or guess who wrote it. ' +
+    'Inspect only the levels assigned to this pass, in order. Definitions of other levels below are for disambiguation, never permission to report them. When one break could fit several levels, ' +
+    'use the earliest affected level: if a final paragraph changes subject instead of resolving the opening problem, always use level-1-whole-essay, never level-4-fractal-structure; ' +
+    'if an explicit opening index promises items the discussion omits, use level-3-index-discussion rather than level-4-fractal-structure or level-6-key-terms. ' +
+    'Use exactly one code for each finding: ' +
+    'level-1-whole-essay for a misleading title, an essay that does not make readers care, or an ending that fails to resolve the opening problem; ' +
+    'level-2-introduction for missing common ground, a weak or unfair status quo, no destabilizing problem or cost, or no clear point/solution; ' +
+    'level-3-index-discussion when a paragraph or section opening fails to set expectations or its discussion breaks that promise; ' +
+    'level-4-fractal-structure when a section or paragraph does not support the point of its containing unit; ' +
+    'level-5-point-placement when a unit has no point, buries it in the middle, or states it at both beginning and end; ' +
+    'level-6-key-terms when central terms announced by an opening disappear, arrive unannounced, or fail to form a coherent thematic string; ' +
+    'level-7-paragraph-flow for an abrupt old-to-new information break. Constant-topic, linking, super-theme, and preview-and-develop are all valid flows; ' +
+    'generic-prose for throat-clearing, vague attribution, empty puffery, faux insight, generic filler, binary contrast, robotic rhythm, repetitive recap, dramatic fragmentation, stacked hedging, clustered scare quotes or all-caps emphasis, or an abstraction given mind-like agency. ' +
+    'Apply essay and introduction codes only to argumentative or explanatory drafts with enough text to support the diagnosis. ' +
+    globalRules +
+    localRules +
+    'Do not force these patterns onto a short answer, list, reference material, dialogue, narrative turn, or intentional disorientation. ' +
+    'Do not flag polished grammar, formal vocabulary, proper names, quotations, or one isolated stylistic choice. ' +
+    'Passive voice is valid when the actor is unknown or irrelevant. Ordinary product verbs such as report shows, form submits, and filter narrows describe real behavior and are not mind-like agency. ' +
+    'Preserve unusual details, humor, uncertainty, bluntness, cadence, and useful roughness. ' +
+    'Prefer the most specific code and do not report the same underlying problem at several levels. ' +
+    'Before returning, deduplicate by cause: if a higher-level finding already explains a lower-level symptom, omit the lower-level finding. ' +
+    'A titleless single-paragraph excerpt is not a whole essay or a section, so do not assign levels 1, 2, or 4 to it. ' +
+    'A structural fix may tell the writer to move, connect, add, remove, or rename material; it need not be achievable by replacing the quote alone. ' +
+    'Return ONLY a JSON array of at most 8 objects with string fields code, quote, pattern, reason, fix. ' +
+    `code must be one of: ${allowedCodes.join(', ')}. ` +
+    'The response must be valid JSON: use double-quoted keys and strings and escape any quotation marks inside a string. ' +
+    'quote must be the shortest exact contiguous quote that identifies the problem. fix is a brief direction, not a rewrite. ' +
+    // The card is read at a glance while the draft stays on screen; a
+    // paragraph of explanation there is never read at all.
+    'Keep them short: pattern at most 4 words, reason at most 12 words, fix at most 12 words. ' +
+    'No preamble, no restating the quote, no hedging — name the problem and the move. ' +
+    'Use the language of the draft for pattern, reason, and fix. Return [] when there are no strong findings.'
+  );
+}
+
+export function buildReviewUser({ document, target = '', context = '' }) {
+  return [
+    context ? `VOICE OR REFERENCE CONTEXT (do not audit):\n${context}` : '',
+    `${target ? 'DRAFT (context only)' : 'DRAFT TO AUDIT'}:\n${document}`,
+    target ? `PASSAGES TO AUDIT:\n${target}` : '',
+  ].filter(Boolean).join('\n\n---\n\n');
+}

package/review.js

@@ -0,0 +1,265 @@
+import { REVIEW_CODES } from './review-prompt.js';
+
+export function parseReviewResponse(raw) {
+  const match = raw.match(/\[[\s\S]*\]/);
+  if (!match && /^\s*no (?:strong )?findings?\.?\s*$/i.test(raw)) return [];
+  if (!match) throw new Error('No findings array in response');
+  const value = JSON.parse(match[0]);
+  if (!Array.isArray(value)) throw new Error('Expected findings array');
+  return value.map(item => {
+    if (!item || typeof item !== 'object') throw new Error('Each finding must be an object');
+    const fields = ['quote', 'pattern', 'reason', 'fix'];
+    if (!fields.every(key => typeof item[key] === 'string' && item[key].trim())) {
+      throw new Error('Each finding needs non-empty quote, pattern, reason, and fix strings');
+    }
+    const finding = Object.fromEntries(fields.map(key => [key, item[key].trim()]));
+    const code = String(item.code ?? '').trim();
+    return { code: REVIEW_CODES.includes(code) ? code : 'unclassified', ...finding };
+  }).slice(0, 8);
+}
+
+export function validateReviewFindings(findings, allowedCodes = REVIEW_CODES, source) {
+  for (const finding of findings) {
+    if (!allowedCodes.includes(finding.code)) throw new Error(`Code ${finding.code} is outside this pass; allowed: ${allowedCodes.join(', ')}`);
+    if (source !== undefined && !source.includes(finding.quote)) throw new Error('Quote must be copied exactly from the passages being audited');
+  }
+}
+
+export function mergeReviewFindings(groups) {
+  const findings = groups.flat();
+  const promises = findings.filter(finding => finding.code === 'level-3-index-discussion');
+  const seen = [];
+  return findings.filter(finding => {
+    // Both passes can diagnose the same opening list. Its broken promise owns
+    // the finding; retain key-term findings elsewhere in the document.
+    if (finding.code === 'level-6-key-terms' && promises.some(promise =>
+      promise.quote.includes(finding.quote) || finding.quote.includes(promise.quote))) return false;
+    if (seen.some(other => other.code === finding.code &&
+      (other.quote.includes(finding.quote) || finding.quote.includes(other.quote)))) return false;
+    seen.push(finding);
+    return true;
+  }).slice(0, 8);
+}
+
+// ─── Local style scoring ─────────────────────────────────────────────────────
+//
+//  A cheap, deterministic read on how much a passage smells of AI, computed
+//  without a model call. Two uses: a live readout for the writer, and a filter
+//  that keeps obviously-clean sentences from costing a review request.
+//
+//  Word lists and anchors below are heuristics, not trained thresholds.
+
+const TELL_WORDS_STRONG = [
+  'delve', 'delves', 'delving', 'tapestry', 'testament', 'underscore', 'underscores',
+  'underscoring', 'leverage', 'leverages', 'leveraging', 'multifaceted', 'realm',
+  'interplay', 'seamless', 'seamlessly', 'groundbreaking', 'nestled',
+];
+
+const TELL_WORDS_WEAK = [
+  'crucial', 'pivotal', 'vibrant', 'robust', 'foster', 'fosters', 'fostering',
+  'enhance', 'enhances', 'enhancing', 'showcase', 'showcases', 'showcasing',
+  'garner', 'bolster', 'utilize', 'utilizes', 'moreover', 'furthermore', 'notably',
+  'transformative', 'innovative', 'boasts', 'renowned', 'breathtaking', 'stunning',
+];
+
+const TELL_PHRASES = [
+  /\bin today'?s [a-z-]+ world\b/i,
+  /\bat the end of the day\b/i,
+  /\bexperts? (?:agree|say|believe)\b/i,
+  /\bstudies show\b/i,
+  /\bit is important to note\b/i,
+  /\bnot (?:just|only)\b[^.!?]{0,60}\bbut\b/i,
+  /\b(?:serves|stands) as a\b/i,
+  /\bplays? a (?:vital|crucial|pivotal|key|significant) role\b/i,
+  /\bat its core\b/i,
+  /\bthe real question is\b/i,
+  /\blet'?s (?:dive|explore|break this down)\b/i,
+  /\bhere'?s what you need to know\b/i,
+  /\ba testament to\b/i,
+  /\bevolving landscape\b/i,
+  /\bin order to\b/i,
+  /\bdue to the fact that\b/i,
+  /\b(?:dashboard|data|design|roadmap|platform|system|tool|app|algorithm) (?:understands?|knows?|decides?|wants?|believes?|cares?)\b/i,
+  /\b(?:could|may|might|arguably|potentially|possibly)(?:\s+\w+){0,2}\s+(?:potentially|possibly|arguably|perhaps|may|might)\b/i,
+  /(?:["“][^"”\n]{1,24}["”][\s,]*){3,}|\b[A-Z]{3,}(?:\s+[A-Z]{3,}){2,}\b/,
+];
+
+const WORD_RE = /\p{L}[\p{L}\p{N}'’-]*/gu;
+
+// The word lists are English. On a Cyrillic or other non-Latin draft they would
+// report zero tells, so callers must not gate on a score that cannot see them.
+export function isLatinScript(text) {
+  const letters = text.match(/\p{L}/gu) ?? [];
+  if (!letters.length) return true;
+  return letters.filter(ch => /[\p{Script=Latin}]/u.test(ch)).length / letters.length > 0.5;
+}
+
+function splitAllSentences(text) {
+  return text.split(/(?<=[.!?…])\s+|\n+/).map(part => part.trim()).filter(Boolean);
+}
+
+export function styleMetrics(text) {
+  const words = (text.match(WORD_RE) ?? []).map(word => word.toLowerCase());
+  const sentences = splitAllSentences(text);
+  const lengths = sentences.map(sentence => (sentence.match(WORD_RE) ?? []).length).filter(Boolean);
+
+  const mean = lengths.length ? lengths.reduce((a, b) => a + b, 0) / lengths.length : 0;
+  const variance = lengths.length > 1
+    ? lengths.reduce((a, b) => a + (b - mean) ** 2, 0) / lengths.length
+    : 0;
+  // Coefficient of variation of sentence length. Human prose swings; AI prose
+  // settles into an even mid-length cadence.
+  const burstiness = mean ? Math.sqrt(variance) / mean : 0;
+
+  // Moving-average type-token ratio: lexical variety that does not sag purely
+  // because the text got longer, unlike raw TTR.
+  const window = 50;
+  let diversity;
+  if (words.length <= window) {
+    diversity = words.length ? new Set(words).size / words.length : 0;
+  } else {
+    let sum = 0;
+    for (let i = 0; i + window <= words.length; i++) {
+      sum += new Set(words.slice(i, i + window)).size / window;
+    }
+    diversity = sum / (words.length - window + 1);
+  }
+
+  let repetition = 0;
+  if (words.length >= 3) {
+    const grams = [];
+    for (let i = 0; i + 3 <= words.length; i++) grams.push(words.slice(i, i + 3).join(' '));
+    repetition = 1 - new Set(grams).size / grams.length;
+  }
+
+  const strongHits = words.filter(word => TELL_WORDS_STRONG.includes(word));
+  const weakHits = words.filter(word => TELL_WORDS_WEAK.includes(word));
+  // The matched text itself, not the pattern — a score the writer cannot trace
+  // back to words in their own draft is just a number to argue with.
+  const phraseHits = TELL_PHRASES.map(pattern => text.match(pattern)?.[0]).filter(Boolean);
+  const strong = strongHits.length;
+  const weak = weakHits.length;
+  const phrases = phraseHits.length;
+  const tells = strong + weak + phrases;
+  const hits = [...new Set([...phraseHits, ...strongHits, ...weakHits].map(hit => hit.trim()))];
+  // Phrases weigh most: "in today's fast-paced world" is a whole tell, `robust`
+  // on its own is barely one.
+  const tellDensity = words.length ? (strong * 2 + weak + phrases * 4) / words.length : 0;
+
+  return { words: words.length, sentences: lengths.length, burstiness, diversity, repetition, tells, tellDensity, hits };
+}
+
+const ANCHORS = { burstinessHuman: 0.6, diversityLow: 0.3, diversityHigh: 0.72, repetitionMax: 0.18, tellMax: 0.05 };
+const WEIGHTS = { tells: 0.45, burstiness: 0.25, diversity: 0.17, repetition: 0.13 };
+
+// 0 = reads clean, 100 = every axis maxed. Structural axes need a paragraph to
+// mean anything, so on short passages the score leans on the lexical axis alone.
+export function styleScore(text) {
+  const metrics = styleMetrics(text);
+  if (!metrics.words) return { ...metrics, score: 0, structural: false };
+
+  const clamp = value => Math.max(0, Math.min(1, value));
+  const lexical = clamp(metrics.tellDensity / ANCHORS.tellMax);
+  const structural = metrics.words >= 40 && metrics.sentences >= 3;
+
+  if (!structural) {
+    return { ...metrics, score: Math.round(100 * lexical), structural };
+  }
+
+  const raw =
+    WEIGHTS.tells * lexical +
+    WEIGHTS.burstiness * clamp((ANCHORS.burstinessHuman - metrics.burstiness) / ANCHORS.burstinessHuman) +
+    WEIGHTS.diversity * clamp((ANCHORS.diversityHigh - metrics.diversity) / (ANCHORS.diversityHigh - ANCHORS.diversityLow)) +
+    WEIGHTS.repetition * clamp(metrics.repetition / ANCHORS.repetitionMax);
+  return { ...metrics, score: Math.round(100 * raw), structural };
+}
+
+// ── Rewrite scope ──
+//
+//  A short selection sent alongside a whole draft reads to the model as "clean
+//  this up", and it returns a rewritten draft that cannot be substituted back.
+//  Marking the span and bounding the answer keeps a replacement a replacement.
+//
+export const SELECT_OPEN  = '⟦';
+export const SELECT_CLOSE = '⟧';
+
+export const SELECT_SLOT = '___';
+
+// The client sends the caret-accurate offset; a bare quote may occur more than
+// once, so fall back to the first match only when the offset does not fit.
+function selectionAt(document, selected, from) {
+  if (!selected) return -1;
+  return Number.isInteger(from) && document.slice(from, from + selected.length) === selected
+    ? from
+    : document.indexOf(selected);
+}
+
+export function markSelection(document, selected, from) {
+  const at = selectionAt(document, selected, from);
+  if (at < 0) return document;
+  return document.slice(0, at) + SELECT_OPEN + selected + SELECT_CLOSE + document.slice(at + selected.length);
+}
+
+// The sentence with the selection cut out. Scope alone is not enough: told only
+// to keep it short, the model returns wording that repeats what already follows
+// ("experts agree" → "collaboration is key" in front of "collaboration is key").
+// Shown the gap it has to fill, it stops writing the neighbours.
+export function selectionSlot(document, selected, from) {
+  const at = selectionAt(document, selected, from);
+  if (at < 0) return null;
+  const end = at + selected.length;
+  const sentence = completedSentences(document).find(item => item.from <= at && item.to >= end)
+    ?? { from: Math.max(0, at - 90), to: Math.min(document.length, end + 90) };
+  return document.slice(sentence.from, at).trimStart() + SELECT_SLOT + document.slice(end, sentence.to).trimEnd();
+}
+
+// Room to rephrase, not to absorb the sentences around it.
+export const variantLimit = selected => Math.max(selected.length * 3, selected.length + 60);
+
+export function parseVariants(raw) {
+  const match = raw.match(/\[[\s\S]*\]/);
+  if (!match) throw new Error('No JSON array in response');
+  const variants = JSON.parse(match[0]);
+  if (!Array.isArray(variants) || variants.length < 3) throw new Error('Expected 3 variants');
+  return variants.slice(0, 3).map(String);
+}
+
+// Models restate the last words before continuing ("…the queue" → "queue began
+// draining"). Asking them not to is unreliable; cutting the overlap is not.
+export function trimOverlap(prefix, suggestion) {
+  const max = Math.min(prefix.length, suggestion.length, 60);
+  for (let n = max; n >= 3; n--) {
+    if (prefix.slice(-n).toLowerCase() === suggestion.slice(0, n).toLowerCase()) {
+      return suggestion.slice(n);
+    }
+  }
+  return suggestion;
+}
+
+// Sentences that are finished, with offsets. A trailing fragment with no
+// terminal punctuation is still being typed and is deliberately left out.
+// ponytail: naive split, "т.д." and "Dr." break it — swap in Intl.Segmenter
+// if false splits ever cost a real review.
+export function completedSentences(document) {
+  return [...document.matchAll(/[^.!?…\n]*[.!?…]+["'»”’)\]]*/g)]
+    .map(match => ({ text: match[0].trim(), from: match.index, to: match.index + match[0].length }))
+    .filter(sentence => sentence.text.length > 0);
+}
+
+// Anchor each quote to a free spot in the document. `occupied` holds ranges
+// already carrying a finding — incremental reviews must not double-mark them.
+export function locateFindings(document, findings, occupied = []) {
+  const taken = occupied.map(({ from, to }) => ({ from, to }));
+  const located = [];
+  for (const finding of findings) {
+    let from = document.indexOf(finding.quote);
+    while (from >= 0 && taken.some(range => from < range.to && from + finding.quote.length > range.from)) {
+      from = document.indexOf(finding.quote, from + 1);
+    }
+    if (from < 0) continue;
+    const range = { ...finding, from, to: from + finding.quote.length };
+    taken.push(range);
+    located.push(range);
+  }
+  return located.sort((a, b) => a.from - b.from);
+}

package/style.md

@@ -0,0 +1,150 @@
+# Writing style guide
+
+Write so the text reads like a person wrote it, not a chatbot. Never change what
+the text claims. Never add a fact, name, number, date, quote, or citation that
+is not already in the draft or the user's material.
+
+Pattern list adapted from Wikipedia's "Signs of AI writing" (WikiProject AI
+Cleanup), which catalogues tells found in real AI edits.
+Additional copy-pattern categories are inspired by the MIT-licensed
+[anti-slop](https://github.com/miqdadbadjuber/anti-slop) project.
+
+## Patterns to avoid
+
+**Inflated importance.** stands as, serves as, is a testament to, plays a vital
+/ crucial / pivotal role, underscores its significance, marks a turning point,
+evolving landscape, leaves an indelible mark. Ordinary facts get described as
+historic shifts.
+
+**Shallow -ing tails.** A clause bolted onto a plain fact to make it sound
+deep: highlighting, underscoring, ensuring, reflecting, symbolizing,
+showcasing, fostering, contributing to.
+
+**Sales language.** boasts, vibrant, rich (figurative), nestled, in the heart
+of, breathtaking, stunning, renowned, must-visit, commitment to, groundbreaking.
+
+**Vague attribution.** experts agree, studies show, industry reports, observers
+have noted, some critics argue. Name a real source from the material or drop
+the claim. Never invent one.
+
+**Avoiding plain verbs.** Prefer is, are, has. Replace serves as, stands as,
+represents, features, boasts with the simple verb.
+
+**Not X but Y.** "not just innovative, but transformative", "not only… but
+also…", and clipped negative endings like "no guessing" instead of a full
+clause.
+
+**Forced triples.** Three parallel items where two or four would be honest.
+Same for three parallel clauses inside one sentence.
+
+**False ranges.** "from X to Y" where X and Y are not the ends of any range.
+
+**Filler openers and announcements.** Let's dive in, here's what you need to
+know, it is important to note that, in order to, due to the fact that, at this
+point in time. State the point instead of announcing it.
+
+**Fake candour.** Honestly? Look. Here's the thing. Let's be honest. Real talk.
+Used as a staged pause before an ordinary claim.
+
+**Pretend depth.** at its core, the real question is, what really matters,
+fundamentally, the deeper issue. Also formulaic sayings: "X is the language of
+Y", "X is not a tool but a mirror", "the currency of".
+
+**Straw objections.** "This isn't really about…", "Don't get me wrong",
+"A tempting approach would be…" — answering an objection nobody raised, or
+raising an option nobody would pick, then dropping it.
+
+**Dramatic fragmentation.** A row of short punchy fragments used for drama. One
+short sentence for emphasis is fine.
+
+**Stacked qualifiers.** could potentially possibly, might arguably, in some
+cases it may. Keep a qualifier only when the meaning needs it.
+
+**Mind-reading objects.** A dashboard may show or filter; it does not
+understand, want, believe, care, or decide. Name the person making the choice,
+unless the verb describes an ordinary product action.
+
+**Manufactured emphasis.** Several ALL-CAPS words, repeated scare quotes, or
+decorative emoji do not make a weak sentence stronger. Preserve real dialogue,
+titles, acronyms, and one deliberate accent.
+
+**Generic positive endings.** "The future looks bright", "exciting times
+ahead", "a step in the right direction". End on the last concrete fact.
+
+**Chatbot residue.** I hope this helps, Certainly!, Great question, Would you
+like me to…, as of my last update, while specific details are limited.
+
+**Overused words.** delve, tapestry, testament, underscore, leverage, seamless,
+multifaceted, realm, interplay, crucial, pivotal, vibrant, robust, foster,
+enhance, showcase, garner, bolster, utilize, moreover, furthermore. These are
+tells when they cluster, not one at a time.
+
+**Repetition handled by rule.** Cycling synonyms for the same subject
+(protagonist / main character / central figure), or several sentences opening
+with the same subject. Fix the pattern, not the word.
+
+## What not to flag
+
+These are not evidence on their own. Flag them only when several real tells
+appear together.
+
+- Clean grammar and consistent style. That is editing, not AI.
+- Formal or academic vocabulary outside the overused list above.
+- A single em dash. Many writers use them constantly.
+- Curly quotes. macOS, Word, and most editors insert them automatically.
+- One "however" or "additionally". The tell is the pile-up.
+- One short sentence used for emphasis.
+- Repetition that builds deliberate rhythm.
+- Passive voice when the actor is unknown or beside the point.
+- Ordinary product verbs such as "the report shows" or "the form submits".
+- "Honestly" or "look" inside a sentence, as opposed to a staged opener.
+- Missing citations. Most writing is unsourced.
+- Scope notes, safety warnings, real corrections, and answers to named
+  objections. These carry information.
+- Watched phrases inside quotations, titles, or proper names, where the phrase
+  is being discussed rather than used.
+
+## What to preserve
+
+- Concrete, odd, specific details. A street name, an exact figure, a strange
+  aside.
+- Mixed feelings and unresolved tension. "I think it's good and it still
+  bothers me."
+- Uncertainty the writer actually holds.
+- Humour, bluntness, and mild rudeness.
+- Dated references, slang, and in-jokes tied to a moment.
+- Self-interruptions and parentheticals.
+- Uneven rhythm. Real writing alternates short and long sentences; AI drifts
+  toward an even mid-length cadence.
+
+## Keep the reader oriented
+
+Open each paragraph or section by setting expectations for what follows, then
+keep that promise. Carry its central terms through the sentences that develop
+them; do not announce a subject and quietly switch to another.
+
+Put familiar information before new information when that makes the connection
+between sentences easier to follow. A paragraph may hold one subject steady,
+pick up the previous sentence's new information as the next subject, or preview
+several subjects and develop them in order. Use whichever movement fits the
+material rather than forcing one pattern everywhere.
+
+Make a unit's main point once, near its beginning or its end. Do not bury it in
+the middle or repeat it as a recap. For argumentative and explanatory writing,
+show the reader the problem and its cost before presenting the point or
+solution, and let the ending resolve the problem opened at the start.
+
+These are diagnostics, not templates. Do not force essay structure onto a short
+answer, a list, reference material, dialogue, or a passage whose deliberate
+disorientation is part of its voice.
+
+## Removing tells is only half the job
+
+Text stripped of AI patterns can still read as flat. Where the genre allows —
+essays, posts, opinion, personal writing — let the writer's voice through.
+Keep reference, technical, and legal text neutral. Never invent a fact or an
+experience to make prose feel personal.
+
+If the user supplies a sample of their own writing, it outranks every rule
+here. Match its sentence length, vocabulary, punctuation habits, and quirks
+rather than correcting them.