renor 0.0.0-stage → 0.2.0

package/lib/review-rules-cli.mjs

@@ -0,0 +1,144 @@
+/**
+ * `renor review-rules`: the owner's standing rules for a review prompt (default), a marked section of a guidelines file
+ * (--export), or proposed rules from past reviews (--propose, which never reaches Renor).
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { GATEWAY_URL } from './constants.mjs'
+import { connect } from './mcp-client.mjs'
+import { fetchRules } from './review-rules-source.mjs'
+import {
+  DEFAULT_EXPORT_MAX_TOKENS, DEFAULT_MAX_TOKENS, buildReviewRulesBlock, formatProposals, proposeRules, renderRulesSection, updateMarkedSection,
+} from './review-rules.mjs'
+
+export const REVIEW_RULES_HELP = `renor review-rules — the owner's standing rules from Renor, for a code review.
+
+Usage
+  gh pr diff 123 | npx renor review-rules        Print the rules that bear on the diff, to put at the top of a review prompt
+  npx renor review-rules --diff change.patch     The same, from a file
+  npx renor review-rules --export [REVIEW.md]    Write the rules into one marked section of REVIEW.md (or AGENTS.md)
+  npx renor review-rules --propose reviews/      Propose rules from recurring findings in past reviews (Markdown); saves nothing
+
+Options
+  --diff <file|->       The diff to match rules against (default: standard input when it is not a terminal)
+  --max-tokens <n>      Cap the block at about n tokens (default ${DEFAULT_MAX_TOKENS}; ${DEFAULT_EXPORT_MAX_TOKENS} for --export)
+  --url <url>           Renor's MCP address (default RENOR_URL, else ${GATEWAY_URL}); a local engine is http://127.0.0.1:3471/mcp
+  --rules-file <json>   Read the rules from a JSON file (an array of rules) instead of Renor
+  --min-reviews <n>     --propose: how many reviews a finding must recur in (default 2)
+  --json                Print JSON (the block, or the proposals) instead of text
+
+The key is RENOR_API_KEY (an API key from https://app.renor.cloud). Every call to Renor is a read.`
+
+export function parseReviewRules(argv) {
+  const options = { diff: null, maxTokens: null, url: null, rulesFile: null, export: null, propose: null, minReviews: 2, json: false, help: false, unknown: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    const value = () => {
+      const eq = arg.indexOf('=')
+      return eq > 0 ? arg.slice(eq + 1) : argv[++i]
+    }
+    const name = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg
+    if (name === '--diff') options.diff = value()
+    else if (name === '--max-tokens') options.maxTokens = Number(value())
+    else if (name === '--url') options.url = value()
+    else if (name === '--rules-file') options.rulesFile = value()
+    else if (name === '--min-reviews') options.minReviews = Number(value())
+    else if (name === '--propose') options.propose = value()
+    else if (name === '--export') {
+      if (arg.includes('=')) options.export = value()
+      else options.export = argv[i + 1] && !argv[i + 1].startsWith('-') ? argv[++i] : ''
+    } else if (arg === '--json') options.json = true
+    else if (arg === '-h' || arg === '--help') options.help = true
+    else options.unknown.push(arg)
+  }
+  return options
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+/** The rules: from --rules-file, or from Renor. */
+async function loadRules(options, { env, diff, err, fetchImpl }) {
+  if (options.rulesFile) return JSON.parse(readFileSync(options.rulesFile, 'utf8'))
+  const url = options.url || env.RENOR_URL || GATEWAY_URL
+  const token = env.RENOR_API_KEY || ''
+  if (!token && url === GATEWAY_URL) throw new Error('Set RENOR_API_KEY to an API key from https://app.renor.cloud (or pass --url for a local engine, or --rules-file).')
+  const client = await connect({ url, token, fetchImpl })
+  return fetchRules(client, { diff, warn: (message) => err.write(`renor review-rules: ${message}\n`) })
+}
+
+/**
+ * Runs `renor review-rules` with `argv` (the words after the command). Returns the exit code. `io` is for tests:
+ * { env, out, err, stdin: () => string, stdinIsTTY, cwd, fetchImpl }.
+ */
+export async function reviewRules(argv, io = {}) {
+  const env = io.env || process.env
+  const out = io.out || process.stdout
+  const err = io.err || process.stderr
+  const cwd = io.cwd || process.cwd()
+  const options = parseReviewRules(argv)
+  if (options.help) {
+    out.write(REVIEW_RULES_HELP + '\n')
+    return 0
+  }
+  if (options.unknown.length > 0) {
+    err.write(`Unknown option: ${options.unknown.join(' ')}\n\n${REVIEW_RULES_HELP}\n`)
+    return 2
+  }
+  if (options.maxTokens !== null && !(Number.isInteger(options.maxTokens) && options.maxTokens > 0)) {
+    err.write('--max-tokens takes a whole number above 0\n')
+    return 2
+  }
+
+  if (options.propose !== null) {
+    // Reads the folder only: no connection to Renor is opened in this mode, so it cannot save anything there.
+    const dir = options.propose || '.'
+    const reviews = readdirSync(dir).filter((name) => name.toLowerCase().endsWith('.md')).sort()
+      .map((name) => ({ name, text: readFileSync(join(dir, name), 'utf8') }))
+    const proposals = proposeRules(reviews, { minReviews: Number.isInteger(options.minReviews) && options.minReviews > 0 ? options.minReviews : 2 })
+    out.write(options.json ? JSON.stringify(proposals, null, 2) + '\n' : formatProposals(proposals, reviews.length))
+    return 0
+  }
+
+  let diff = ''
+  if (options.diff === '-') diff = (io.stdin || readStdin)()
+  else if (options.diff) diff = readFileSync(options.diff, 'utf8')
+  else if (options.export === null && !(io.stdinIsTTY ?? process.stdin.isTTY)) diff = (io.stdin || readStdin)()
+  if (options.export === null && diff.trim() === '') {
+    err.write('No diff: pipe one in (gh pr diff 123 | npx renor review-rules) or pass --diff <file>.\n')
+    return 2
+  }
+
+  const rules = await loadRules(options, { env, diff, err, fetchImpl: io.fetchImpl })
+
+  if (options.export !== null) {
+    const target = options.export || (existsSync(join(cwd, 'REVIEW.md')) || !existsSync(join(cwd, 'AGENTS.md')) ? 'REVIEW.md' : 'AGENTS.md')
+    const path = join(cwd, target)
+    const before = existsSync(path) ? readFileSync(path, 'utf8') : ''
+    const { section, included, omitted } = renderRulesSection({ rules, diff, maxTokens: options.maxTokens ?? DEFAULT_EXPORT_MAX_TOKENS })
+    const after = updateMarkedSection(before, section)
+    if (after === before) {
+      out.write(`${target}: unchanged (${included.length} rule(s)).\n`)
+      return 0
+    }
+    writeFileSync(path, after)
+    out.write(`${target}: wrote ${included.length} rule(s) into the Renor section${omitted.length ? `; ${omitted.length} more did not fit --max-tokens` : ''}. Nothing outside the section changed.\n`)
+    return 0
+  }
+
+  const { block, included, omitted } = buildReviewRulesBlock({ rules, diff, maxTokens: options.maxTokens ?? DEFAULT_MAX_TOKENS })
+  if (options.json) {
+    out.write(JSON.stringify({ block, included: included.map((rule) => rule.id), omitted: omitted.map((rule) => rule.id) }, null, 2) + '\n')
+    return 0
+  }
+  out.write(block)
+  err.write(block
+    ? `renor review-rules: ${included.length} rule(s) quoted${omitted.length ? `, ${omitted.length} left out by --max-tokens` : ''}.\n`
+    : 'renor review-rules: no current rule bears on this diff; nothing printed.\n')
+  return 0
+}

package/lib/review-rules-source.mjs

@@ -0,0 +1,83 @@
+/**
+ * Where `renor review-rules` gets the owner's rules: Renor's own read tools, over MCP, hosted or local. No engine tool was
+ * added for this; the existing ones are enough:
+ *
+ *   memory_map (no query)     the newest facts, history included: the subjects that hold a rule-like predicate
+ *   get_context (the diff)    current facts the diff's words reach, beyond the newest ones: more such subjects
+ *   retrieve_memory (subject) each subject's facts, every one marked current or superseded, with its event id and date,
+ *                             its value whole (get_context may cut a value, and gives no id)
+ *   memory_map (rule words)   plain-words memories that hold "always", "never", "prefer", "rule", ...
+ *   read_memory (id)          each such memory's full text, and whether a later correction replaced it
+ *
+ * Only `current: true` facts and memories nobody replaced are kept, so a superseded value never reaches the block. Every
+ * call is a read: nothing here saves, retires or changes anything in Renor.
+ */
+import { diffFiles, isRulePredicate, looksLikeRule, terms } from './review-rules.mjs'
+
+const RULE_WORDS = 'rule always never must prefer avoid policy decision decided convention guideline'
+
+/** The question get_context is asked: the changed files and the diff's most frequent words, inside its 1000-character limit. */
+export function contextQuery(diff) {
+  const counts = new Map()
+  for (const line of String(diff || '').split('\n')) {
+    if (!/^[+-]/.test(line) || /^(\+\+\+|---) /.test(line)) continue
+    for (const t of terms(line.slice(1))) counts.set(t, (counts.get(t) || 0) + 1)
+  }
+  const top = [...counts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 30).map(([t]) => t)
+  return `Standing rules, preferences and decisions for a code review of changes to ${diffFiles(diff).slice(0, 20).join(', ')}. Topics: ${top.join(' ')}`.slice(0, 1000)
+}
+
+const day = (iso) => (typeof iso === 'string' ? iso.slice(0, 10) : undefined)
+
+/**
+ * fetchRules(client, { diff?, maxSubjects = 40, maxMemories = 40, warn? }) → Rule[]
+ *
+ * `client.callTool(name, args)` answers a Renor tool's JSON (mcp-client.mjs). A tool that fails is skipped with a warning
+ * (`warn(message)`), so one refused read leaves the rest of the rules; nothing is guessed in its place.
+ */
+export async function fetchRules(client, { diff = '', maxSubjects = 40, maxMemories = 40, warn = () => {} } = {}) {
+  const call = async (name, args) => {
+    try {
+      return await client.callTool(name, args)
+    } catch (error) {
+      warn(`${name} failed: ${error instanceof Error ? error.message : String(error)}`)
+      return null
+    }
+  }
+
+  const subjects = []
+  const addSubject = (subject) => {
+    if (typeof subject === 'string' && subject.trim() !== '' && !subjects.includes(subject)) subjects.push(subject)
+  }
+  const map = await call('memory_map', { limit: 200 })
+  for (const fact of map?.facts || []) if (isRulePredicate(fact.predicate)) addSubject(fact.subject)
+  if (String(diff).trim() !== '') {
+    const context = await call('get_context', { query: contextQuery(diff), max_tokens: 4000 })
+    for (const fact of context?.facts || []) if (isRulePredicate(fact.predicate) && fact.untrusted !== true) addSubject(fact.subject)
+  }
+
+  const rules = []
+  const seen = new Set()
+  for (const subject of subjects.slice(0, maxSubjects)) {
+    const read = await call('retrieve_memory', { subject })
+    for (const fact of read?.facts || []) {
+      if (fact.current !== true || fact.validTo || fact.untrusted === true || !isRulePredicate(fact.predicate)) continue
+      if (!fact.eventId || seen.has(fact.eventId)) continue
+      seen.add(fact.eventId)
+      rules.push({ id: fact.eventId, date: day(fact.validFrom), text: fact.object, kind: 'fact', subject, predicate: fact.predicate, scope: fact.scope, current: true })
+    }
+  }
+
+  const found = await call('memory_map', { query: RULE_WORDS, limit: 200 })
+  const candidates = (found?.memories || []).filter((memory) => memory.untrusted !== true && memory.origin !== 'import')
+  for (const memory of candidates.slice(0, maxMemories)) {
+    if (seen.has(memory.id)) continue
+    const read = await call('read_memory', { id: memory.id })
+    if (!read || read.ok === false || read.replaced || read.textTruncated || typeof read.text !== 'string') continue
+    const detail = read.memory || memory
+    if (detail.untrusted === true || detail.origin === 'import' || !looksLikeRule(read.text)) continue
+    seen.add(memory.id)
+    rules.push({ id: memory.id, date: day(detail.session_date || detail.at), text: read.text, kind: 'memory', current: true })
+  }
+  return rules
+}

package/lib/review-rules.mjs

@@ -0,0 +1,390 @@
+/**
+ * The owner's standing rules in every review: the pure core of `renor review-rules`. Nothing here touches the network or
+ * the disk; the CLI (review-rules-cli.mjs) fetches rules from Renor (review-rules-source.mjs) and hands them in.
+ *
+ * A rule, as every function here takes it:
+ *   { id, date, text, kind: 'fact' | 'memory', subject?, predicate?, scope?, current?, replaced?, untrusted? }
+ * `id` is the Renor memory id (a fact's event id, `mem_…`, or a note's id from memory_map), `date` the day it was saved
+ * (YYYY-MM-DD), `text` the stored words, quoted byte for byte. `current: false` (a superseded fact), `replaced: true` (a
+ * note a later correction replaced) and `untrusted: true` (an import, or a reserved source) are never quoted.
+ *
+ * The plain function to run on a private set (firstmate's laptop gate) is `buildReviewRulesBlock({ rules, diff, maxTokens })`.
+ */
+
+/**
+ * The predicate words a standing rule, preference or decision is saved under. The first group is the engine's own
+ * GOVERNANCE_PREDICATES (engine/src/mvp/agentMemory.ts), the words its facts lane reads as a standing rule; the second is
+ * what a preference is saved under. A predicate counts when it is one of these or has one as a word (`test_policy`,
+ * `ui preference`).
+ */
+export const RULE_PREDICATE_WORDS = [
+  'rule', 'rules', 'policy', 'policies', 'decision', 'decisions', 'guideline', 'guidelines',
+  'constraint', 'constraints', 'requirement', 'requirements', 'must', 'convention', 'conventions',
+  'principle', 'principles', 'guardrail', 'guardrails', 'permission', 'permissions', 'approval', 'approvals',
+  'preference', 'preferences', 'prefer', 'prefers', 'preferred', 'style', 'avoid', 'never', 'always', 'standard', 'standards',
+]
+
+export function isRulePredicate(predicate) {
+  if (typeof predicate !== 'string') return false
+  return predicate.toLowerCase().split(/[^\p{L}\p{N}]+/u).some((word) => word !== '' && RULE_PREDICATE_WORDS.includes(word))
+}
+
+/** Whether a plain-words memory reads as a standing rule, preference or decision rather than a note of what happened. */
+export function looksLikeRule(text) {
+  if (typeof text !== 'string') return false
+  if (/^\s*(rule|preference|decision|policy|convention|guideline|standing rule)s?\s*[:\-—]/i.test(text)) return true
+  return /\b(always|never|must|must not|do not|don't|prefer|prefers|avoid|decided)\b/i.test(text)
+}
+
+/** About how many tokens a text costs: one per four UTF-8 bytes, rounded up (o200k averages a little over that on English). */
+export function estimateTokens(text) {
+  return Math.ceil(Buffer.byteLength(text, 'utf8') / 4)
+}
+
+const STOP_WORDS = new Set(('the a an and or but if then else for to of in on at by with from as is are was were be been it its this that these '
+  + 'those not no do does did done can could should would will shall may might must always never only also any all each every '
+  + 'one two our we you your they them their there here what when where which who why how than too very more most such into '
+  + 'out over under about after before again just use used using new old get set add const let var return true false null '
+  + 'undefined import export function class type interface diff git index file files line lines same like way thing').split(' '))
+
+/** Words of a text, for matching: lower case, camelCase and snake_case split, stop words and one- or two-letter words out, light stemming. */
+export function terms(text) {
+  const words = String(text)
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}]+/u)
+  const out = []
+  for (const word of words) {
+    if (word.length < 3 || STOP_WORDS.has(word) || /^\d+$/.test(word)) continue
+    const stemmed = stem(word)
+    if (!STOP_WORDS.has(stemmed)) out.push(stemmed)
+  }
+  return out
+}
+
+/** A doubled final consonant left by cutting -ing or -ed (`logg`, `mapp`) back to one, as the plain word has it. */
+const undouble = (word) => (word.length >= 4 && /([b-df-hj-np-tv-z])\1$/.test(word) && !/(ss|ll|ff|zz)$/.test(word) ? word.slice(0, -1) : word)
+
+function stem(word) {
+  if (word.length > 5 && word.endsWith('ing')) return undouble(word.slice(0, -3))
+  if (word.length > 4 && word.endsWith('ies')) return word.slice(0, -3) + 'y'
+  if (word.length > 4 && word.endsWith('ed')) return undouble(word.slice(0, -2))
+  if (word.length > 4 && word.endsWith('es') && /(ss|x|ch|sh)es$/.test(word)) return word.slice(0, -2)
+  if (word.length > 3 && word.endsWith('s') && !word.endsWith('ss')) return word.slice(0, -1)
+  return word
+}
+
+/** The language a file extension names, as a rule would say it. */
+const LANGUAGES = { ts: 'typescript', tsx: 'typescript', mts: 'typescript', cts: 'typescript', js: 'javascript', jsx: 'javascript', mjs: 'javascript', cjs: 'javascript', py: 'python', rs: 'rust', go: 'golang', sql: 'sql', md: 'markdown', css: 'css' }
+
+function pathTerms(path) {
+  const ext = /\.([a-z]+)$/i.exec(path)?.[1]?.toLowerCase()
+  const language = ext && LANGUAGES[ext]
+  return terms(language ? `${path} ${language}` : path)
+}
+
+/**
+ * The diff's words, path words apart: `{ paths: Set, body: Set }`. Only changed lines (+/-) and file names count, never
+ * context lines. Two things a rule names that no word of the diff says are added as words: an added line indented with a
+ * tab (`tab`, `indentation`), and a gendered pronoun in an added line (`pronoun`).
+ */
+export function diffTerms(diff) {
+  const paths = new Set()
+  const body = new Set()
+  for (const line of String(diff || '').split('\n')) {
+    let m
+    if ((m = /^diff --git a\/(.*) b\/(.*)$/.exec(line))) {
+      for (const t of pathTerms(m[1]).concat(pathTerms(m[2]))) paths.add(t)
+    } else if ((m = /^(?:\+\+\+|---) (?:[ab]\/)?(.*)$/.exec(line))) {
+      if (m[1] !== '/dev/null') for (const t of pathTerms(m[1])) paths.add(t)
+    } else if (/^[+-]/.test(line)) {
+      for (const t of terms(line.slice(1))) body.add(t)
+      if (line[0] === '+' && line[1] === '\t') body.add('tab').add(stem('indentation'))
+      if (line[0] === '+' && /\b(he|she|him|her|his|hers)\b/i.test(line.slice(1))) body.add(stem('pronoun'))
+    }
+  }
+  return { paths, body }
+}
+
+/** The changed files of a diff, in order. */
+export function diffFiles(diff) {
+  const files = []
+  for (const line of String(diff || '').split('\n')) {
+    const m = /^diff --git a\/(.*) b\/(.*)$/.exec(line)
+    if (m && !files.includes(m[2])) files.push(m[2])
+  }
+  return files
+}
+
+/**
+ * The subjects a rule can name that make it bear on every review: a rule about reviews, PRs or the code as a whole. Such a
+ * rule is kept even when no word of the diff matches it, and then ranks after every rule that one did.
+ */
+const GENERAL_SUBJECTS = new Set(['review', 'reviews', 'code review', 'code reviews', 'reviewer', 'reviewers', 'pr', 'prs',
+  'pull request', 'pull requests', 'code', 'codebase', 'all code', 'everything', 'general', 'repo', 'repository'])
+
+/** Whether a rule may be quoted at all: current, not replaced, not untrusted, with an id and words. */
+export function quotable(rule) {
+  return Boolean(rule && typeof rule.id === 'string' && rule.id !== '' && typeof rule.text === 'string' && rule.text.trim() !== ''
+    && rule.current !== false && rule.replaced !== true && rule.untrusted !== true)
+}
+
+/**
+ * Every quotable rule with its relevance to `diff`, most relevant first; a rule the diff does not bear on is left out.
+ *
+ * A shared word weighs more the fewer rules have it (so `migration` outweighs `test` when most rules mention tests). A word
+ * of a changed file's path counts double, and so does a word of a fact's predicate that is not itself a rule word (the
+ * `migration` of `migration_rule`): the predicate names what the rule is about. A rule whose score is under `minShare` of
+ * the best rule's is left out, so one coincidental word (`default`, `tenant`) does not bring in an unrelated rule; a rule
+ * about reviews or the code as a whole (GENERAL_SUBJECTS) is always kept, after the matched ones. Ties go to the newer
+ * rule, then the id, so the order is stable. Without a diff every quotable rule is kept, newest first.
+ */
+export function rankRules(rules, diff, { minShare = 0.3 } = {}) {
+  const usable = dedupe(rules.filter(quotable))
+  const ruleTerms = usable.map((rule) => new Set(terms([rule.subject, rule.predicate, rule.text].filter(Boolean).join(' '))))
+  const topicTerms = usable.map((rule) => new Set(terms(rule.predicate || '').filter((t) => !RULE_PREDICATE_WORDS.includes(t))))
+  const df = new Map()
+  for (const set of ruleTerms) for (const t of set) df.set(t, (df.get(t) || 0) + 1)
+  const n = usable.length
+  const haveDiff = typeof diff === 'string' && diff.trim() !== ''
+  const { paths, body } = diffTerms(diff)
+  const ranked = usable.map((rule, i) => {
+    let score = 0
+    const matched = []
+    if (haveDiff) {
+      for (const t of ruleTerms[i]) {
+        const weight = (paths.has(t) ? 2 : 0) + (body.has(t) ? 1 : 0)
+        if (weight === 0) continue
+        score += weight * (topicTerms[i].has(t) ? 2 : 1) * Math.log(1 + n / df.get(t))
+        matched.push(t)
+      }
+    }
+    const general = GENERAL_SUBJECTS.has(String(rule.subject || '').trim().toLowerCase())
+    return { rule, score, matched, general }
+  })
+  const best = Math.max(0, ...ranked.map((entry) => entry.score))
+  const kept = haveDiff
+    ? ranked.filter((entry) => entry.score > 0 && entry.score >= minShare * best).concat(
+      ranked.filter((entry) => entry.general && !(entry.score > 0 && entry.score >= minShare * best)).map((entry) => ({ ...entry, score: 0 })))
+    : ranked
+  return kept
+    .sort((a, b) => b.score - a.score || String(b.rule.date || '').localeCompare(String(a.rule.date || '')) || a.rule.id.localeCompare(b.rule.id))
+    .map(({ general: _general, ...entry }) => entry)
+}
+
+/** One rule per id; a second copy (the same fact found twice) is dropped. */
+function dedupe(rules) {
+  const seen = new Set()
+  return rules.filter((rule) => (seen.has(rule.id) ? false : (seen.add(rule.id), true)))
+}
+
+export const CITE_INSTRUCTION = 'When a finding rests on one of these rules, cite its id in that finding as "(rule <id>)", the id in brackets above the rule. '
+  + 'Cite a rule only for a finding it supports, and never quote a rule other than as written here.'
+
+const BLOCK_INTRO = 'The owner\'s standing rules that bear on this change, from Renor, most relevant first. Each is quoted exactly as it was saved, with the day it was saved and its memory id.'
+
+/** One rule as the block shows it: a header line, then the stored text, untouched (one line as a `>` quote, more in a fence). */
+export function formatRule(rule) {
+  const where = rule.kind === 'fact' && rule.subject ? ` · ${rule.subject} · ${rule.predicate}` : ''
+  const head = `[${rule.id}] saved ${rule.date || 'on an unknown day'}${where}`
+  if (!/[\r\n]/.test(rule.text)) return `${head}\n> ${rule.text}\n`
+  const longest = Math.max(0, ...[...rule.text.matchAll(/`+/g)].map((m) => m[0].length))
+  const fence = '`'.repeat(Math.max(3, longest + 1))
+  return `${head}\n${fence}\n${rule.text}${rule.text.endsWith('\n') ? '' : '\n'}${fence}\n`
+}
+
+/**
+ * Rules in rank order, as many as fit `maxTokens` with the frame around them. A rule that does not fit is skipped whole
+ * (never cut) and a later, shorter one may still fit. Returns `{ text, included, omitted }`; `text` is '' when no rule fits.
+ */
+function fitRules(ranked, { maxTokens, intro, outro }) {
+  const frame = `${intro}\n\n${outro}\n`
+  let used = estimateTokens(frame)
+  const included = []
+  const omitted = []
+  for (const entry of ranked) {
+    const piece = formatRule(entry.rule) + '\n'
+    const cost = estimateTokens(piece)
+    if (used + cost > maxTokens) {
+      omitted.push(entry.rule)
+      continue
+    }
+    used += cost
+    included.push(entry.rule)
+  }
+  if (included.length === 0) return { text: '', included, omitted }
+  return { text: `${intro}\n\n${included.map((rule) => formatRule(rule) + '\n').join('')}${outro}\n`, included, omitted }
+}
+
+export const DEFAULT_MAX_TOKENS = 600
+
+/**
+ * The block to put at the top of a review prompt.
+ *
+ * buildReviewRulesBlock({ rules: Rule[], diff: string, maxTokens?: number = 600 })
+ *   → { block: string, included: Rule[], omitted: Rule[], ranked: Array<{ rule, score, matched }> }
+ *
+ * `block` is '' when no current rule bears on the diff. Superseded, replaced and untrusted rules are never in it.
+ */
+export function buildReviewRulesBlock({ rules, diff, maxTokens = DEFAULT_MAX_TOKENS }) {
+  const ranked = rankRules(rules, diff)
+  const fitted = fitRules(ranked, { maxTokens, intro: BLOCK_INTRO, outro: CITE_INSTRUCTION })
+  return { block: fitted.text, included: fitted.included, omitted: fitted.omitted, ranked }
+}
+
+// --- --export: one marked section of a guidelines file -----------------------------------------------------------------
+
+export const SECTION_START = '<!-- renor:review-rules:start -->'
+export const SECTION_END = '<!-- renor:review-rules:end -->'
+const SECTION_NOTE = '<!-- Written by `npx renor review-rules --export`. Everything between these markers is replaced on the next export; edit the rules in Renor. -->'
+const SECTION_HEADING = '## The owner\'s standing rules (from Renor)'
+const SECTION_INTRO = 'Each rule is quoted exactly as the owner saved it in Renor, with the day it was saved and its memory id.'
+
+export const DEFAULT_EXPORT_MAX_TOKENS = 1500
+
+/** The section's text, markers included, with `\n` line ends. Same rules in, same bytes out: nothing in it depends on the clock. */
+export function renderRulesSection({ rules, diff, maxTokens = DEFAULT_EXPORT_MAX_TOKENS }) {
+  const ranked = rankRules(rules, diff)
+  const fitted = fitRules(ranked, { maxTokens, intro: `${SECTION_HEADING}\n\n${SECTION_INTRO}`, outro: CITE_INSTRUCTION })
+  const body = fitted.text || `${SECTION_HEADING}\n\nRenor holds no standing rule to list yet.\n`
+  return { section: `${SECTION_START}\n${SECTION_NOTE}\n\n${body}${SECTION_END}\n`, included: fitted.included, omitted: fitted.omitted }
+}
+
+/**
+ * `fileText` with its marked section replaced by `section`, or with `section` appended when it has none. Nothing outside
+ * the markers changes. Throws when the markers are not one well-formed pair, rather than guess which text is ours. The
+ * file's own line ending (CRLF or LF) is kept.
+ */
+export function updateMarkedSection(fileText, section) {
+  const crlf = /\r\n/.test(fileText)
+  const ours = crlf ? section.replace(/\n/g, '\r\n') : section
+  const eol = crlf ? '\r\n' : '\n'
+  const lineStarts = (marker) => {
+    const at = []
+    const re = new RegExp(`(^|\\n)${marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[ \\t]*(\\r?\\n|$)`, 'g')
+    let m
+    while ((m = re.exec(fileText))) {
+      at.push({ index: m.index + m[1].length, end: m.index + m[0].length })
+      re.lastIndex = m.index + m[0].length - m[2].length
+    }
+    return at
+  }
+  const starts = lineStarts(SECTION_START)
+  const ends = lineStarts(SECTION_END)
+  if (starts.length === 0 && ends.length === 0) {
+    if (fileText === '') return ours
+    const sep = fileText.endsWith(eol + eol) ? '' : fileText.endsWith(eol) ? eol : eol + eol
+    return fileText + sep + ours
+  }
+  if (starts.length !== 1 || ends.length !== 1 || ends[0].index < starts[0].index) {
+    throw new Error(`the file has ${starts.length} start and ${ends.length} end marker(s) for the Renor rules section; expected one pair, start first. Fix it by hand, then export again.`)
+  }
+  // The section is replaced through the end marker's line end; a file whose end marker is its last line, with no line
+  // end, keeps having none after it.
+  const tail = fileText.slice(ends[0].end)
+  const endHadEol = /\r?\n$/.test(fileText.slice(ends[0].index, ends[0].end))
+  const replacement = endHadEol ? ours : ours.replace(/\r?\n$/, '')
+  return fileText.slice(0, starts[0].index) + replacement + tail
+}
+
+// --- --propose: recurring findings of past reviews ---------------------------------------------------------------------
+
+/** The findings of one review: its list items and its bold-led lines, with their text as written. */
+export function findingsOf(text) {
+  const out = []
+  for (const raw of String(text).split(/\r?\n/)) {
+    const m = /^\s*(?:[-*+]|\d+[.)])\s+(.*\S)\s*$/.exec(raw) || /^\s*(\*\*.*\S)\s*$/.exec(raw)
+    if (!m) continue
+    const finding = m[1]
+    if (terms(cleanFinding(finding)).length < 3) continue
+    out.push(finding)
+  }
+  return out
+}
+
+/** A finding without its severity tag, emphasis, `file:line` references or code spans: the words a rule would keep. */
+export function cleanFinding(finding) {
+  return finding
+    .replace(/\[(?:P\d|nit|blocker|major|minor)\]/gi, '')
+    .replace(/`[^`]*`/g, '')
+    .replace(/\b[\w./-]+\.[a-z]{1,5}(?::\d+(?:-\d+)?)?\b/gi, '')
+    .replace(/[*_]+/g, '')
+    .replace(/\s+/g, ' ')
+    .replace(/^[\s:.\-—]+|[\s:—-]+$/g, '')
+    .trim()
+}
+
+/**
+ * Recurring findings across past reviews, as proposed rules for the owner to approve. Reads only what it is given and
+ * saves nothing anywhere.
+ *
+ * proposeRules(reviews: Array<{ name, text }>, { minReviews = 2, similarity = 0.5 })
+ *   → Array<{ rule, reviews: string[], findings: Array<{ review, text }>, shared: string[] }>, most reviews first
+ *
+ * Two findings are the same finding when they share at least `minShared` words and at least `similarity` of the shorter
+ * one's words (findings that chain this way are one group); a group counts when its findings come from at least
+ * `minReviews` different reviews. Words are matched as written, so two findings that say one thing in different words stay
+ * apart: this proposes what recurs in so many words, and the owner judges the rest.
+ */
+export function proposeRules(reviews, { minReviews = 2, similarity = 0.33, minShared = 2 } = {}) {
+  const items = []
+  for (const review of reviews) {
+    for (const text of findingsOf(review.text)) items.push({ review: review.name, text, terms: new Set(terms(cleanFinding(text))) })
+  }
+  const parent = items.map((_, i) => i)
+  const find = (i) => (parent[i] === i ? i : (parent[i] = find(parent[i])))
+  const sim = (a, b) => {
+    let shared = 0
+    for (const t of a) if (b.has(t)) shared++
+    return shared >= minShared ? shared / Math.min(a.size, b.size) : 0
+  }
+  for (let i = 0; i < items.length; i++) {
+    for (let j = i + 1; j < items.length; j++) {
+      if (sim(items[i].terms, items[j].terms) >= similarity) parent[find(i)] = find(j)
+    }
+  }
+  const groups = new Map()
+  items.forEach((item, i) => {
+    const root = find(i)
+    if (!groups.has(root)) groups.set(root, [])
+    groups.get(root).push(item)
+  })
+  const proposals = []
+  for (const group of groups.values()) {
+    const names = [...new Set(group.map((item) => item.review))].sort()
+    if (names.length < minReviews) continue
+    // The finding closest to all the others speaks for the group; ties go to the shorter one.
+    const central = group
+      .map((item) => ({ item, total: group.reduce((sum, other) => sum + (other === item ? 0 : sim(item.terms, other.terms)), 0) }))
+      .sort((a, b) => b.total - a.total || a.item.text.length - b.item.text.length)[0].item
+    const counts = new Map()
+    for (const item of group) for (const t of item.terms) counts.set(t, (counts.get(t) || 0) + 1)
+    const surface = surfaceWords(group.map((item) => cleanFinding(item.text)).join(' '))
+    const shared = [...counts].filter(([, c]) => c * 2 >= group.length).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([t]) => surface.get(t) || t)
+    proposals.push({ rule: cleanFinding(central.text), reviews: names, findings: group.map(({ review, text }) => ({ review, text })), shared })
+  }
+  return proposals.sort((a, b) => b.reviews.length - a.reviews.length || b.findings.length - a.findings.length || a.rule.localeCompare(b.rule))
+}
+
+/** Each stem of a text, mapped to the first word it was cut from, so a proposal shows `enabled`, not `enabl`. */
+function surfaceWords(text) {
+  const map = new Map()
+  for (const word of text.toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+    const [t] = terms(word)
+    if (t && !map.has(t)) map.set(t, word)
+  }
+  return map
+}
+
+/** Proposals as the owner reads them in the terminal. */
+export function formatProposals(proposals, totalReviews) {
+  if (proposals.length === 0) return `No finding recurs across ${totalReviews} review(s); nothing to propose.\n`
+  const lines = [`${proposals.length} finding(s) recur across ${totalReviews} review(s). Nothing was saved. To make one a standing rule, tell your agent "Remember this review rule: …" in the words you approve.`, '']
+  proposals.forEach((p, i) => {
+    lines.push(`${i + 1}. Proposed rule, in one review's words: ${p.rule}`)
+    lines.push(`   Seen in ${p.reviews.length} reviews (${p.reviews.join(', ')}), ${p.findings.length} finding(s). Shared words: ${p.shared.slice(0, 8).join(', ')}`)
+    for (const f of p.findings) lines.push(`   - ${f.review}: ${f.text}`)
+    lines.push('')
+  })
+  return lines.join('\n')
+}