@inixiative/foundry-core 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/foundry-core",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/adapters/markdown-docs.ts

@@ -209,6 +209,8 @@ export interface InstructionFile {
   readonly path: string;
   /** Text with block-level HTML comments removed, as Claude Code injects it. */
   readonly content: string;
+  /** The file's text as read, when stripping comments changed it (`content` is the stripped form). */
+  readonly raw?: string;
   /** Import hops from the file the chain started at (0 for that file). */
   readonly depth: number;
   /** The file whose `@path` loaded this one. */
@@ -395,8 +397,15 @@ export async function readInstructionFile(
       return;
     }
     seen.add(real);
-    const content = stripInstructionComments(await Bun.file(real).text());
-    files.push({ path: file, content, depth, ...(importedBy ? { importedBy } : {}) });
+    const raw = await Bun.file(real).text();
+    const content = stripInstructionComments(raw);
+    files.push({
+      path: file,
+      content,
+      ...(raw !== content ? { raw } : {}),
+      depth,
+      ...(importedBy ? { importedBy } : {}),
+    });
     if (depth >= maxDepth) return;
     for (const target of instructionImports(content)) {
       const next = resolveInstructionImport(target, file, options.home);

package/src/adapters/markdown-hierarchy.ts

@@ -617,7 +617,8 @@ export async function discoverHierarchy(
         continue;
       }
       if (statSync(real).size > INSTRUCTION_FILE_LIMIT) continue;
-      let content = readFileSync(unit.path, 'utf8');
+      const raw = readFileSync(unit.path, 'utf8');
+      let content = raw;
       if (unit.source.maxLines !== undefined)
         content = content.split('\n').slice(0, unit.source.maxLines).join('\n');
       if (unit.source.maxBytes !== undefined)
@@ -625,7 +626,14 @@ export async function discoverHierarchy(
       const final = tierOf(unit.path, node);
       seen.add(real);
       kept.set(real, { path: unit.path, node: final.id, index: files.length });
-      files.push({ path: unit.path, content, depth: 0, node: final.id, tier: final.tier });
+      files.push({
+        path: unit.path,
+        content,
+        ...(raw !== content ? { raw } : {}),
+        depth: 0,
+        node: final.id,
+        tier: final.tier,
+      });
       continue;
     }
     const allowed =
@@ -665,7 +673,13 @@ export async function discoverHierarchy(
       // Every file keeps the narrower tier of its node and any node owning its path, found or imported.
       const final = tierOf(file.path, node);
       kept.set(realOf(file.path), { path: file.path, node: final.id, index: files.length });
-      files.push({ ...file, content, node: final.id, tier: final.tier });
+      files.push({
+        ...file,
+        content,
+        ...(content !== file.content ? { raw: file.raw ?? file.content } : {}),
+        node: final.id,
+        tier: final.tier,
+      });
     }
   }
   return { files, duplicates, refused, probes: [...probes] };
@@ -850,7 +864,7 @@ export function dedupeHierarchy<F extends HierarchyFile>(
         continue;
       }
       const content = cut(file.content.split('\n'), dropped);
-      if (content.trim()) keep.unshift({ ...file, content });
+      if (content.trim()) keep.unshift({ ...file, content, raw: file.raw ?? file.content });
     }
     out = keep;
   }

package/src/context-layer.ts

@@ -109,8 +109,55 @@ export interface ContextSource {
    * Must be cheap: it runs before every assembly.
    */
   changed?(): boolean;
+  /**
+   * What the last load was made of, in order: glue text and attributed parts whose concatenation is
+   * exactly the loaded text. Absent when the source cannot attribute its text.
+   */
+  segments?(): readonly SourceSegment[] | undefined;
+}
+
+/**
+ * One attributed piece of composed text. `subject` names where it came from (`file:<path>`,
+ * `prompt:agent:<id>`, `source-content:<id>`). `retrieved` marks text chosen per message (it is not
+ * a slow-moving source). `raw` is the source's own text when the composed `text` is a cleaned or
+ * trimmed form of it (comments stripped, a duplicate section removed).
+ */
+export interface SourcePart {
+  readonly subject: string;
+  readonly text: string;
+  readonly retrieved?: boolean;
+  readonly raw?: string;
+  /** The ladder rung of a file part, and its corpus tier. */
+  readonly node?: string;
+  readonly tier?: string;
+}
+
+/** Glue text (headings, separators) or an attributed part. */
+export type SourceSegment = string | SourcePart;
+
+/** What a composed agent call was made of, slot by slot (in memory; persisted as version ids). */
+export interface CompositionSnapshot {
+  /** The role composed for (an agent id). */
+  readonly role?: string;
+  readonly instructions: readonly SourceSegment[];
+  readonly domainKnowledge: readonly SourceSegment[];
+  /** What the composer left out of each slot, and why (excluded by role, a duplicate, refused, over budget). */
+  readonly omitted?: {
+    readonly instructions: readonly OmittedSource[];
+    readonly domainKnowledge: readonly OmittedSource[];
+  };
 }
 
+export interface OmittedSource {
+  readonly subject: string;
+  readonly reason: string;
+  readonly duplicateOf?: string;
+}
+
+/** The text a segment list composes. */
+export const segmentsText = (segments: readonly SourceSegment[]): string =>
+  segments.map((segment) => (typeof segment === 'string' ? segment : segment.text)).join('');
+
 /** Selection provenance carried on a layer instance for inspection. */
 export interface LayerSelectionState {
   readonly focusHash?: string;
@@ -320,6 +367,8 @@ export class ContextLayer {
   readonly perTurn: boolean;
 
   private _content: string = '';
+  /** Each source's text from the last warm, in source order; undefined after a manual `set`. */
+  private _loaded: string[] | undefined;
   private _state: LayerState = 'cold';
   private _hash: string = '';
   private _lastWarmed: number | null = null;
@@ -496,6 +545,32 @@ export class ContextLayer {
     return this._content;
   }
 
+  /**
+   * What the current content is made of: each source's segments (or the source's whole text as one
+   * part, `unattributed:<source id>`, when it cannot attribute it), joined as the content was. Content written with
+   * `set` is one part, `layer-content:<id>`. Concatenated, always exactly `content`.
+   */
+  segments(): SourceSegment[] {
+    const whole = (): SourceSegment[] =>
+      this._content ? [{ subject: `layer-content:${this.id}`, text: this._content }] : [];
+    const loaded = this._loaded;
+    if (!loaded || loaded.length !== this._sources.length) return whole();
+    const out: SourceSegment[] = [];
+    loaded.forEach((text, i) => {
+      if (i > 0) out.push('\n\n');
+      const source = this._sources[i]!;
+      const own = source.segments?.();
+      if (own && segmentsText(own) === text) out.push(...own);
+      else if (text)
+        out.push({
+          subject: `unattributed:${source.id}`,
+          text,
+          ...(source.focusable ? { retrieved: true } : {}),
+        });
+    });
+    return segmentsText(out) === this._content ? out : whole();
+  }
+
   get lastAccessed(): number | null {
     return this._lastAccessed;
   }
@@ -595,6 +670,7 @@ export class ContextLayer {
         }
 
         this._content = parts.join('\n\n');
+        this._loaded = parts;
         this._hash = computeHash(this._content);
         this._version = undefined; // even identical unversioned source bytes are a new write
         this._selection = reports.length
@@ -632,6 +708,7 @@ export class ContextLayer {
   set(content: string, author: string = 'system'): void {
     const previous = this._content;
     this._content = content;
+    this._loaded = undefined;
     this._hash = computeHash(content);
     this._selection = undefined; // manual content has no selection provenance
     this._version = undefined; // a new write carries no version until its owner marks it

package/src/feedback/correction.ts

@@ -31,6 +31,8 @@ export interface CorrectionEvent {
   readonly timestamp: string;
   /** What the agent said right before the correction ('' at the start of a session). */
   readonly before: string;
+  /** The person's previous message: what the agent was answering when it earned the correction. */
+  readonly ask?: string;
   /** The person's message. */
   readonly correction: string;
   /** The strongest signal, and every signal that fired. */
@@ -167,6 +169,7 @@ export function extractCorrections(
   const minScore = options.minScore ?? 0;
   const corrections: CorrectionEvent[] = [];
   let before = '';
+  let ask = '';
   let pendingInterruption = false;
   let secretsScrubbed = 0;
   // An identical message resent within ten minutes is one correction, not a repeat.
@@ -181,6 +184,8 @@ export function extractCorrections(
     if (!text.trim()) continue;
     const detection = detectCorrection(text, before, { interrupted: pendingInterruption });
     pendingInterruption = false;
+    const previousAsk = ask;
+    ask = text.trim();
     const key = text.toLowerCase().replace(/\s+/g, ' ').trim();
     const at = Date.parse(turn.timestamp);
     const sent = recent.get(key);
@@ -190,12 +195,14 @@ export function extractCorrections(
     // Scrub before truncating, so a cut can't leave part of a secret unmatched.
     const scrubbedBefore = scrubSecrets(before);
     const scrubbedText = scrubSecrets(text.trim());
-    secretsScrubbed += scrubbedBefore.hits + scrubbedText.hits;
+    const scrubbedAsk = scrubSecrets(previousAsk);
+    secretsScrubbed += scrubbedBefore.hits + scrubbedText.hits + scrubbedAsk.hits;
     const event = {
       ...(turn.id ? { messageId: turn.id } : {}),
       ...(turn.sourceRef ? { sourceRef: turn.sourceRef } : {}),
       timestamp: turn.timestamp,
       before: scrubbedBefore.text.slice(-2000),
+      ...(scrubbedAsk.text ? { ask: scrubbedAsk.text.slice(0, 4000) } : {}),
       correction: scrubbedText.text.slice(0, 4000),
       signal: detection.signal,
       signals: detection.signals,

package/src/feedback/experiment-gate.ts

@@ -0,0 +1,89 @@
+/**
+ * The experiment gate (`.claude/skills/experiment/SKILL.md`), shared by Foundry's eval scripts and
+ * Oracle's replay runner: a wide run (more than TINY_MOMENTS moments, or whatever else the caller
+ * counts as wide) needs `--experiment <design.md>` whose pre-registration sections are filled and
+ * whose `<design>.review.md` says `verdict: go` for this exact design (`design-sha256:` of its
+ * bytes). A tiny test runs without one.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const TINY_MOMENTS = 3;
+
+/** The `## ` headings of `.claude/skills/experiment/design.md`, every one required. */
+export const DESIGN_SECTIONS = [
+  'Question',
+  'Variable',
+  'Arms',
+  'Fixtures and power',
+  'Baseline',
+  'Gates',
+  'Cost ceiling and stop rules',
+  'Provenance',
+  'What would make the result wrong',
+] as const;
+
+export type ExperimentRecord = { design: string; designSha256: string; review: string };
+
+export const reviewPathOf = (design: string) => design.replace(/\.md$/, '.review.md');
+
+const sha256 = (path: string) => createHash('sha256').update(readFileSync(path)).digest('hex');
+
+/** Why the design may not run wide; empty when it may. */
+export const experimentProblems = (designPath: string): string[] => {
+  const design = resolve(designPath);
+  if (!design.endsWith('.md')) return [`${design}: the design is a .md file`];
+  if (!existsSync(design)) return [`${design}: no such design`];
+  const problems: string[] = [];
+  const text = readFileSync(design, 'utf8');
+  const sections = new Map<string, string>();
+  let current: string | undefined;
+  for (const line of text.split('\n')) {
+    const heading = /^##\s+(.+?)\s*$/.exec(line);
+    if (heading) {
+      current = heading[1]?.toLowerCase();
+      if (current) sections.set(current, sections.get(current) ?? '');
+    } else if (/^#\s/.test(line)) current = undefined;
+    else if (current) sections.set(current, `${sections.get(current) ?? ''}${line}\n`);
+  }
+  for (const name of DESIGN_SECTIONS) {
+    const body = sections.get(name.toLowerCase());
+    if (body === undefined) problems.push(`missing section "## ${name}"`);
+    else if (!body.replace(/<!--[\s\S]*?-->/g, '').trim())
+      problems.push(`section "## ${name}" is empty`);
+  }
+  if (text.includes('<fill')) problems.push('unfilled <fill: …> placeholders remain');
+  const review = reviewPathOf(design);
+  if (!existsSync(review)) return [...problems, `no adversarial review at ${review}`];
+  const reviewText = readFileSync(review, 'utf8');
+  if (!/^verdict:\s*go\s*$/im.test(reviewText))
+    problems.push(`${review} has no "verdict: go" line`);
+  const reviewed = /^design-sha256:\s*([0-9a-f]{64})\s*$/im.exec(reviewText)?.[1];
+  if (!reviewed) problems.push(`${review} has no "design-sha256: <hex>" line`);
+  else if (reviewed !== sha256(design))
+    problems.push('the design changed after its review (design-sha256 differs): review it again');
+  return problems;
+};
+
+/** Throws unless the run may go ahead; returns the provenance to record when a design was named. */
+export const requireExperiment = (
+  experiment: string | undefined,
+  wide: boolean,
+): ExperimentRecord | undefined => {
+  if (!experiment) {
+    if (!wide) return undefined;
+    throw Error(
+      `a wide run (more than ${TINY_MOMENTS} moments) needs --experiment <design.md> ` +
+        'with a reviewed pre-registration: see .claude/skills/experiment/SKILL.md',
+    );
+  }
+  const problems = experimentProblems(experiment);
+  if (problems.length)
+    throw Error(
+      `--experiment ${experiment} may not run:\n  - ${problems.join('\n  - ')}\n` +
+        'see .claude/skills/experiment/SKILL.md',
+    );
+  const design = resolve(experiment);
+  return { design, designSha256: sha256(design), review: reviewPathOf(design) };
+};

package/src/feedback/review-findings.ts

@@ -0,0 +1,237 @@
+import {
+  type Authorship,
+  CONCEPT_CLUSTERS,
+  type CorrectionTarget,
+  MISS_KINDS,
+  type MissKind,
+} from './warden-probes';
+
+// The Prospector's reading of written review: PR reviews and ticket comments where the person said the
+// work should have used, extended or ported something that already existed. Data and pure functions
+// only: callers fetch the text and make the model call.
+
+/** One piece of written review, with what it was about. */
+export interface ReviewMoment {
+  readonly id: string;
+  /** Where it was written, e.g. `PR #2116 (CHANGES_REQUESTED review, inline)` or `ZLT-4321 comment`. */
+  readonly where: string;
+  /** What the work was: PR title and description, or the issue's title and description. */
+  readonly work: string;
+  /** The code it was written on, when inline (path, line, diff hunk). */
+  readonly code?: string;
+  /** The message it replies to, when it is a reply. */
+  readonly replyTo?: string;
+  readonly text: string;
+  /** `directive`: a description the person wrote of work still to do (a ticket, a project), not a review of done work. */
+  readonly mode?: 'review' | 'directive';
+}
+
+export type FindingScope = 'architectural' | 'code';
+
+/** How much a finding counts in scoring: generic code-correctness findings are lightly down-weighted (Aron, 2026-10-15). */
+export const SCOPE_WEIGHT: Readonly<Record<FindingScope, number>> = {
+  architectural: 1,
+  code: 0.75,
+};
+
+/** One place the reviewer pushed toward something that already existed. */
+export interface ReviewFinding {
+  readonly target: CorrectionTarget;
+  /** The reviewer's own words that say it, verbatim, at most 300 characters. */
+  readonly excerpt: string;
+  /** `architectural`: about which system, primitive or boundary to build on; `code`: a generic code-correctness fix. */
+  readonly scope?: FindingScope;
+}
+
+export interface ReviewReading {
+  readonly findings: readonly ReviewFinding[];
+  /** The model's read of the voice: typed by a person, or written by an AI agent. A weak signal. */
+  readonly voice?: 'human' | 'agent';
+}
+
+/**
+ * Words a reuse finding almost always carries. A change-request review is read whole; everything else
+ * is read only when it matches (the method of Zealot's core-primitives findings, ZLT-5638).
+ */
+export const REUSE_HINT =
+  /\b(?:already (?:exists?|have|has|does|handles?|in|imported|installed|there)|existing|exists|re-?use|reimplement\w*|re-implement\w*|hand-?roll\w*|hand-?written|duplicat\w*|copy|copies|copied|parallel|second (?:copy|version|implementation)|third (?:copy|type system)|instead of|port(?:ed|ing)? (?:from|it|this|the)|from (?:the )?template|template'?s|primitive|extend(?:ing)? (?:the|it)|use (?:the |our )?[`\w]|we have|there'?s (?:a|an|already)|same (?:shape|thing|as)|like \w+ does|convention|pattern|wrapper|shared|generic|lodash|helper|util|registry|consolidate|fold (?:into|it)|one place|single source)\b/i;
+
+export const REVIEW_FINDINGS_PROMPT = `You read code review written by one reviewer, Aron, on pull requests and tickets. For each item, find every place where he says the work should have USED, EXTENDED or PORTED something that ALREADY EXISTS instead of what was built: a primitive (helper, wrapper, hook, component, class, module, package export, library already installed), a system (an existing subsystem or flow), a pattern (an established way the codebase does a thing, e.g. a route template or a module convention), or a rule (a standing convention or ruling, e.g. "no select on internal reads").
+
+A finding needs both: the existing thing, and what was done instead. Not findings: bug reports, missing tests, style nits, new requirements, questions, praise, status updates, an author's replies about what they fixed, and anything that points at something not yet built.
+
+For each finding:
+- name: the existing thing as the codebase names it, at most 80 characters (e.g. "paginate() + filterLens", "Skeleton component", "lodash omit", "PolymorphismRegistry"). Name the thing, not the advice.
+- kind: "primitive" | "system" | "pattern" | "rule"
+- concept: its concept cluster; use one of the given clusters when one fits, else a new short kebab-case cluster.
+- where: the file, package or doc it lives in, only when the item says so.
+- builtInstead: what the work did instead, one line, at most 160 characters. For a directive item, what the work would otherwise have built, or "" when the item doesn't say.
+- miss: why it was missed, judged from the item: "unaware" (didn't know it existed), "misfit" (knew it, worked around a gap instead of extending it), "wrapper" (wrapped it under a new name), "unclear".
+- excerpt: Aron's words that say it, verbatim, at most 300 characters.
+- scope: "architectural" when it is about which system, primitive, module boundary or pattern to build on; "code" when it is a generic code-correctness fix (a library call, a small helper, an idiom).
+
+Items marked "Mode: directive" are descriptions Aron wrote of work still to be done (a ticket, a project). There a finding is a place where he directs the work to use, extend or port something that already exists, by name.
+
+Also judge the voice of each item: "human" when it reads as typed by a person (terse, informal, lowercase, typos, first-person asides), "agent" when it reads as written by an AI coding agent (headed sections, bold labels, numbered findings, dense backticked citations, "Fixed in <sha>" replies, polished em-dash prose).
+
+Respond with JSON only: { "results": { "<id>": { "voice": "human" | "agent", "findings": [ { "name": string, "kind": string, "concept": string, "where"?: string, "builtInstead": string, "miss": string, "excerpt": string, "scope": "architectural" | "code" } ] } } } with "findings": [] when there are none.`;
+
+/** The reader's input for a batch of review moments. */
+export function reviewFindingMessages(
+  moments: readonly ReviewMoment[],
+): { role: 'system' | 'user'; content: string }[] {
+  const body = moments
+    .map((m) =>
+      [
+        `## ${m.id}`,
+        `Where: ${m.where}`,
+        ...(m.mode === 'directive' ? ['Mode: directive'] : []),
+        `### The work\n${m.work.slice(0, 1200)}`,
+        ...(m.code ? [`### Code it was written on\n${m.code.slice(-1500)}`] : []),
+        ...(m.replyTo ? [`### Replying to\n${m.replyTo.slice(0, 800)}`] : []),
+        `### Aron wrote\n${m.text.slice(0, 4000)}`,
+      ].join('\n'),
+    )
+    .join('\n\n');
+  return [
+    { role: 'system', content: REVIEW_FINDINGS_PROMPT },
+    {
+      role: 'user',
+      content: `Concept clusters: ${CONCEPT_CLUSTERS.join(', ')}\n\nRead each item below.\n\n${body}`,
+    },
+  ];
+}
+
+const KINDS = new Set(['primitive', 'system', 'pattern', 'rule']);
+const kebab = (text: string) =>
+  text
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+
+/** One reading per id; undefined when missing or malformed (the caller retries it alone). */
+export function parseReviewFindings(
+  content: string,
+  ids: readonly string[],
+): (ReviewReading | undefined)[] {
+  let results: Record<string, { voice?: unknown; findings?: unknown }> = {};
+  try {
+    results =
+      (
+        JSON.parse(content.slice(content.indexOf('{'), content.lastIndexOf('}') + 1)) as {
+          results?: typeof results;
+        }
+      ).results ?? {};
+  } catch {
+    return ids.map(() => undefined);
+  }
+  return ids.map((id) => {
+    const item = results[id];
+    if (!item || !Array.isArray(item.findings)) return undefined;
+    const findings: ReviewFinding[] = [];
+    for (const raw of item.findings as Record<string, unknown>[]) {
+      if (!raw || typeof raw.name !== 'string' || !raw.name.trim()) continue;
+      if (typeof raw.concept !== 'string' || !kebab(raw.concept)) continue;
+      const miss = MISS_KINDS.includes(raw.miss as MissKind) ? (raw.miss as MissKind) : 'unclear';
+      findings.push({
+        target: {
+          name: raw.name.trim().slice(0, 120),
+          kind: (KINDS.has(String(raw.kind)) ? raw.kind : 'pattern') as CorrectionTarget['kind'],
+          concept: kebab(raw.concept),
+          ...(typeof raw.where === 'string' && raw.where.trim()
+            ? { where: raw.where.trim().slice(0, 160) }
+            : {}),
+          ...(typeof raw.builtInstead === 'string' && raw.builtInstead.trim()
+            ? { builtInstead: raw.builtInstead.trim().slice(0, 240) }
+            : {}),
+          miss,
+        },
+        excerpt: typeof raw.excerpt === 'string' ? raw.excerpt.trim().slice(0, 300) : '',
+        ...(raw.scope === 'architectural' || raw.scope === 'code' ? { scope: raw.scope } : {}),
+      });
+    }
+    return {
+      findings,
+      ...(item.voice === 'human' || item.voice === 'agent' ? { voice: item.voice } : {}),
+    };
+  });
+}
+
+/** Markers an agent leaves in what it posts, and the trace of text typed into a web form. */
+export const AUTHORSHIP_MARKERS = {
+  /** An agent's signature line. */
+  footer:
+    /(?:generated (?:by|with) \[?claude|🤖 generated|co-authored-by: claude|^_?generated by .{0,40}_?$)/im,
+  /** Claude Code's terminal glyphs: an agent's output pasted in by hand. */
+  pasted: /(?:^|\n)\s*[⏺⎿]/,
+  /** CRLF line endings: typed (or edited) in the GitHub web UI; gh and the API post LF. */
+  webForm: /\r\n/,
+} as const;
+
+/** What the person's own sessions say about a comment: an agent posted it, or the person typed it. */
+export interface SessionEvidence {
+  readonly posted?: boolean;
+  /** The text appears in another tool call: a body file an agent drafted, or a quote. Weak. */
+  readonly drafted?: boolean;
+  readonly typed?: boolean;
+}
+
+/**
+ * Who wrote a comment posted under the person's account. Strong evidence decides; a model's read of
+ * the voice is the weak fallback, then plain style. A typed prompt outranks an agent posting it: the
+ * person dictated the words.
+ */
+export function authorshipOf(
+  text: string,
+  evidence: SessionEvidence = {},
+  voice?: 'human' | 'agent',
+): Authorship {
+  const signals: string[] = [];
+  if (evidence.typed) signals.push('session:typed');
+  if (evidence.posted) signals.push('session:posted');
+  if (evidence.drafted) signals.push('session:drafted');
+  if (AUTHORSHIP_MARKERS.footer.test(text)) signals.push('marker:footer');
+  if (AUTHORSHIP_MARKERS.pasted.test(text)) signals.push('marker:pasted');
+  if (AUTHORSHIP_MARKERS.webForm.test(text)) signals.push('marker:web-form');
+  const style = styleOf(text);
+  signals.push(`style:${style}`);
+  if (voice) signals.push(`voice:${voice}`);
+  if (evidence.typed) return { by: 'human', confidence: 'strong', signals };
+  if (evidence.posted || signals.includes('marker:footer') || signals.includes('marker:pasted'))
+    return { by: 'agent', confidence: 'strong', signals };
+  if (signals.includes('marker:web-form')) return { by: 'human', confidence: 'strong', signals };
+  // A draft can also be an agent quoting the person's comment back, so it only outweighs style.
+  return { by: evidence.drafted ? 'agent' : (voice ?? style), confidence: 'weak', signals };
+}
+
+/** Plain style: an agent's headings, bold labels, numbered findings and dense citations. */
+export function styleOf(text: string): 'human' | 'agent' {
+  let agent = 0;
+  if (/^#{1,4} /m.test(text)) agent += 2;
+  if (/\*\*[^*\n]{2,60}\*\*/.test(text)) agent++;
+  if (/^\s*\d+\. \*\*/m.test(text)) agent += 2;
+  if ((text.match(/`[^`\n]+`/g) ?? []).length >= 4) agent++;
+  if ((text.match(/—/g) ?? []).length >= 2) agent++;
+  if (/^(?:Fixed in|Addressed in|Done in) [0-9a-f]{7}/im.test(text)) agent += 2;
+  if (text.length > 900) agent++;
+  let human = 0;
+  if (/^[a-z]/.test(text.trim())) human += 2;
+  if (!/[.!?:`)]\s*$/.test(text.trim())) human++;
+  if (/\b(?:im|dont|cant|doesnt|isnt|wont|u|ur|pls|thx|lol|imo|tbh)\b/.test(text)) human += 2;
+  if (text.length < 200) human++;
+  return agent > human ? 'agent' : 'human';
+}
+
+/**
+ * A distinctive run of a comment that survives JSON and shell quoting unchanged, to find the session
+ * that posted it. Undefined when the text has no such run.
+ */
+export function evidenceSnippet(text: string, length = 48): string | undefined {
+  let best = '';
+  for (const run of text.split(/[^A-Za-z0-9 ,.;:()/_=+-]+/))
+    if (run.trim().length > best.length) best = run.trim();
+  if (best.length < Math.min(length, 32)) return undefined;
+  const start = Math.max(0, Math.floor((best.length - length) / 2));
+  return best.slice(start, start + length).trim();
+}