onto-mcp 0.3.0

package/dist/core-runtime/review/citation-audit.js

@@ -0,0 +1,204 @@
+/**
+ * Citation audit — Phase 3-4 (A5), fabrication post-flight detection.
+ *
+ * # What this module is
+ *
+ * Given a synthesize output and the raw text of participating lens outputs,
+ * extracts "significant quoted strings" from the synthesize output and checks
+ * whether each one appears as a substring of AT LEAST ONE lens output. Quotes
+ * that match nothing AND carry an **attribution pattern** (`axiology: "..."`,
+ * `Axiology said "..."`, etc.) are flagged as potential fabrications. Quotes
+ * without an attribution pattern are surfaced separately as advisory
+ * (`quotes_unmatched_meta`) — they may be taxonomy labels (`"conditional
+ * consensus"`), concept names, or paraphrased references rather than
+ * fabrications.
+ *
+ * # Why it exists
+ *
+ * Phase 3-4 A3 benchmark (2026-04-17) demonstrated that inline mode + path-only
+ * packet caused Qwen3-30B-A3B to emit a quoted axiology finding
+ * (`Axiology said "Naming alignment between value, activity, and concept is
+ * not yet resolved"`) that grep returned 0 matches for across all three lens
+ * outputs. The model hallucinated a citation to support its deliberation.
+ * The same run also produced 3 quoted taxonomy labels that substring-matched
+ * no lens but were not fabrications. Without attribution classification those
+ * three labels produced noise warnings and diluted operator attention to the
+ * real fabrication.
+ *
+ * A4 (PR #74) blocks the known precondition (`Tools: required` + inline) at
+ * executor entry; the audit here is a **defense-in-depth** layer that catches
+ * fabrications from:
+ *   - packets that don't declare `Tools: required`
+ *   - partially-inlined packets where some lens content is embedded and some
+ *     is referenced by path
+ *   - native-mode runs where the model read a file but still made up a quote
+ *   - future prompt regressions that could reintroduce fabrication
+ *
+ * # What it does NOT do
+ *
+ * - It does not block execution. The audit is **warning-only** per the A5
+ *   design: an unmatched quote is a suspicion, not a proof.
+ * - It does not parse semantic meaning. Only literal substring matching.
+ * - It does not audit LENS outputs. Lens outputs don't cite each other; they
+ *   cite the review target.
+ *
+ * # Grammar
+ *
+ * Quotes are extracted from:
+ *   - `"..."` — straight double-quoted strings
+ *   - `` `...` `` — backtick-quoted (markdown code spans)
+ *
+ * Strings shorter than `minQuoteLength` (default 20) are skipped as noise.
+ *
+ * # Attribution classification
+ *
+ * A quote is attribution-style when any of the following patterns appears
+ * within the preceding `ATTRIBUTION_CONTEXT_WINDOW` characters (up to the
+ * previous sentence boundary):
+ *
+ *   - `<lens>:` / `**<lens>**:` / `*<lens>*:` — colon-style attribution
+ *   - `per <lens>` / `from <lens>` / `according to <lens>`
+ *   - `<Lens> said|reports|notes|claims|states|asserts|finds`
+ *   - `<Lens> lens said|...`
+ *   - `cited from <lens>` / `cited_lens_output <lens>`
+ *
+ * The `<lens>` token is any of the nine review lenses or `synthesize`.
+ * Case-insensitive.
+ */
+const DEFAULT_MIN_QUOTE_LENGTH = 20;
+const ATTRIBUTION_CONTEXT_WINDOW = 120;
+const LENS_IDS = [
+    "logic",
+    "structure",
+    "dependency",
+    "semantics",
+    "pragmatics",
+    "evolution",
+    "coverage",
+    "conciseness",
+    "axiology",
+    "synthesize",
+];
+const LENS_ALT = LENS_IDS.join("|");
+const ATTRIBUTION_REGEXES = [
+    // `axiology:` / `**axiology**:` / `*axiology*:`
+    // The markdown-emphasis variant uses its own asterisk anchors, so `\b` only
+    // guards the bare form. Without the split alternation we'd fail because
+    // `\b` does not exist between start-of-slice and `*` (both non-word).
+    new RegExp(`(?:\\*{1,2}(${LENS_ALT})\\*{1,2}|\\b(${LENS_ALT}))\\s*:\\s*$`, "i"),
+    // `per axiology` / `from axiology` / `according to axiology`
+    new RegExp(`\\b(?:per|from|according\\s+to)\\s+(${LENS_ALT})\\b[^"\`]*$`, "i"),
+    // `Axiology said` / `logic lens reports` / `semantics claims`
+    new RegExp(`\\b(${LENS_ALT})(?:\\s+lens)?\\s+(?:said|reports?|notes?|claims?|states?|asserts?|finds?)\\b[^"\`]*$`, "i"),
+    // `cited from logic` / `cited_lens_output axiology`
+    new RegExp(`\\b(?:cited\\s+from|cited_lens_output)\\s+(${LENS_ALT})\\b[^"\`]*$`, "i"),
+];
+/**
+ * Return the substring of `text` immediately preceding `offset`, cut back to
+ * the previous sentence boundary (period, newline, start of text) and capped
+ * at `ATTRIBUTION_CONTEXT_WINDOW` characters. This is the "same sentence"
+ * window the attribution classifier examines.
+ */
+function precedingContext(text, offset) {
+    const start = Math.max(0, offset - ATTRIBUTION_CONTEXT_WINDOW);
+    let slice = text.slice(start, offset);
+    // Cut back to the last sentence boundary within the window so attribution
+    // claims in the preceding sentence don't spill into this one's classification.
+    const boundary = Math.max(slice.lastIndexOf("."), slice.lastIndexOf("\n"), slice.lastIndexOf("?"), slice.lastIndexOf("!"));
+    if (boundary >= 0)
+        slice = slice.slice(boundary + 1);
+    return slice;
+}
+function classifyAttribution(precedingText) {
+    for (const re of ATTRIBUTION_REGEXES) {
+        const m = precedingText.match(re);
+        if (m) {
+            const lens = m.slice(1).find((g) => typeof g === "string" && g.length > 0);
+            return lens
+                ? { is_attribution: true, attributed_lens: lens.toLowerCase() }
+                : { is_attribution: true };
+        }
+    }
+    return { is_attribution: false };
+}
+/**
+ * Extract significant quoted strings from free-form markdown text, keeping
+ * per-quote attribution classification.
+ *
+ * De-duplicates identical quote *texts*. When the same text appears multiple
+ * times with different attribution, the first occurrence's classification is
+ * kept — matching the "any attribution → warning-worthy" spirit of the audit.
+ * (Detailed per-occurrence introspection is out of scope here.)
+ */
+export function extractSignificantQuotes(text, options) {
+    const min = options?.minQuoteLength ?? DEFAULT_MIN_QUOTE_LENGTH;
+    const out = [];
+    const seen = new Set();
+    const doubleRe = /"([^"\n]+(?:\n[^"\n]+)?)"/g;
+    for (const m of text.matchAll(doubleRe)) {
+        const body = (m[1] ?? "").trim();
+        if (body.length < min)
+            continue;
+        if (seen.has(body))
+            continue;
+        seen.add(body);
+        const offset = m.index ?? 0;
+        const preceding = precedingContext(text, offset);
+        const { is_attribution, attributed_lens } = classifyAttribution(preceding);
+        out.push({
+            text: body,
+            offset,
+            is_attribution,
+            ...(attributed_lens !== undefined ? { attributed_lens } : {}),
+        });
+    }
+    const backtickRe = /`([^`\n]+)`/g;
+    for (const m of text.matchAll(backtickRe)) {
+        const body = (m[1] ?? "").trim();
+        if (body.length < min)
+            continue;
+        if (seen.has(body))
+            continue;
+        seen.add(body);
+        const offset = m.index ?? 0;
+        const preceding = precedingContext(text, offset);
+        const { is_attribution, attributed_lens } = classifyAttribution(preceding);
+        out.push({
+            text: body,
+            offset,
+            is_attribution,
+            ...(attributed_lens !== undefined ? { attributed_lens } : {}),
+        });
+    }
+    out.sort((a, b) => a.offset - b.offset);
+    return out;
+}
+/**
+ * Run citation audit: extract significant quotes from synthesize output,
+ * classify by attribution, then substring-match against each lens content.
+ */
+export function auditCitations(synthesizeText, lensContents, options) {
+    const min = options?.minQuoteLength ?? DEFAULT_MIN_QUOTE_LENGTH;
+    const quotes = extractSignificantQuotes(synthesizeText, { minQuoteLength: min });
+    const unmatched_strict = [];
+    const unmatched_meta = [];
+    let attribution_count = 0;
+    for (const q of quotes) {
+        if (q.is_attribution)
+            attribution_count += 1;
+        const matched = lensContents.some((content) => content.includes(q.text));
+        if (matched)
+            continue;
+        if (q.is_attribution)
+            unmatched_strict.push(q.text);
+        else
+            unmatched_meta.push(q.text);
+    }
+    return {
+        quotes_checked: quotes.length,
+        quotes_unmatched: unmatched_strict,
+        quotes_unmatched_meta: unmatched_meta,
+        attribution_count,
+        min_quote_length: min,
+    };
+}

package/dist/core-runtime/review/citation-audit.test.js

@@ -0,0 +1,165 @@
+import { describe, it, expect } from "vitest";
+import { auditCitations, extractSignificantQuotes } from "./citation-audit.js";
+describe("extractSignificantQuotes", () => {
+    it("extracts double-quoted strings above threshold", () => {
+        const text = 'The lens said "Top-level value lacks operational backing" in evidence.';
+        const quotes = extractSignificantQuotes(text);
+        expect(quotes.map((q) => q.text)).toContain("Top-level value lacks operational backing");
+    });
+    it("extracts backtick code spans above threshold", () => {
+        const text = "The evidence is at `src/core-runtime/scope-runtime/state-machine.ts` in the module.";
+        const quotes = extractSignificantQuotes(text);
+        expect(quotes.map((q) => q.text)).toContain("src/core-runtime/scope-runtime/state-machine.ts");
+    });
+    it("skips quotes below threshold (default 20)", () => {
+        const text = 'The status is "performed" for now, file `x.ts`.';
+        const quotes = extractSignificantQuotes(text).map((q) => q.text);
+        expect(quotes).not.toContain("performed");
+        expect(quotes).not.toContain("x.ts");
+    });
+    it("respects a custom threshold", () => {
+        const text = "File `x.ts` matters.";
+        const quotes = extractSignificantQuotes(text, { minQuoteLength: 3 });
+        expect(quotes.map((q) => q.text)).toContain("x.ts");
+    });
+    it("de-duplicates identical quotes", () => {
+        const text = '"Declaration without operational backing" appears here and "Declaration without operational backing" again.';
+        const quotes = extractSignificantQuotes(text);
+        expect(quotes.filter((q) => q.text === "Declaration without operational backing").length).toBe(1);
+    });
+    it("handles multi-line quote bodies (single newline tolerated)", () => {
+        const text = '"Line one of a long citation\nthat wraps across one linebreak"';
+        const quotes = extractSignificantQuotes(text);
+        expect(quotes[0]?.text.includes("Line one")).toBe(true);
+    });
+    it("does not extract from triple-backtick code fences as code spans", () => {
+        const text = "Before\n```ts\nconst x = 1;\n```\nAfter";
+        const quotes = extractSignificantQuotes(text);
+        expect(quotes.length).toBe(0);
+    });
+    it("returns empty array when no quoted strings present", () => {
+        const text = "Pure prose with no quotations or backtick spans above threshold.";
+        expect(extractSignificantQuotes(text)).toEqual([]);
+    });
+});
+describe("attribution classification", () => {
+    it("classifies `<lens>:` colon attribution", () => {
+        const text = 'axiology: "Declaration without operational grounding detected"';
+        const [q] = extractSignificantQuotes(text);
+        expect(q?.is_attribution).toBe(true);
+        expect(q?.attributed_lens).toBe("axiology");
+    });
+    it("classifies `**<lens>**:` bold attribution", () => {
+        const text = '**logic**: "Circular dependency across module boundary"';
+        const [q] = extractSignificantQuotes(text);
+        expect(q?.is_attribution).toBe(true);
+        expect(q?.attributed_lens).toBe("logic");
+    });
+    it("classifies verb attribution (said / reports / claims)", () => {
+        const texts = [
+            'Axiology said "purpose-value misalignment in executor"',
+            "Logic reports \"tier-level equivalence cannot be decided\"",
+            'Semantics claims "synonymous terms not consolidated"',
+        ];
+        for (const text of texts) {
+            const [q] = extractSignificantQuotes(text);
+            expect(q?.is_attribution).toBe(true);
+        }
+    });
+    it("classifies `<Lens> lens said` phrasing", () => {
+        const text = 'Coverage lens notes "sub-area missing from scope"';
+        const [q] = extractSignificantQuotes(text);
+        expect(q?.is_attribution).toBe(true);
+        expect(q?.attributed_lens).toBe("coverage");
+    });
+    it("classifies `per <lens>` / `from <lens>` / `according to <lens>` prefix", () => {
+        const texts = [
+            'per logic, "tier-equivalence can be demonstrated structurally"',
+            'from structure: "isolated node in dependency graph found"',
+            'according to pragmatics: "usage context narrows applicability"',
+        ];
+        for (const text of texts) {
+            const [q] = extractSignificantQuotes(text);
+            expect(q?.is_attribution).toBe(true);
+        }
+    });
+    it("does NOT classify a bare quote without a nearby lens reference", () => {
+        const text = 'The synthesis includes a "conditional consensus" section per the canonical taxonomy.';
+        const [q] = extractSignificantQuotes(text);
+        expect(q?.is_attribution).toBe(false);
+        expect(q?.attributed_lens).toBeUndefined();
+    });
+    it("does NOT leak attribution across sentence boundaries", () => {
+        // Lens reference is in the previous sentence; quote here is a bare concept
+        // label, not an attributed citation.
+        const text = 'Axiology covered the purpose axis. Elsewhere the report discusses "conditional consensus" as a taxonomy label.';
+        const quotes = extractSignificantQuotes(text);
+        const taxonomy = quotes.find((q) => q.text === "conditional consensus");
+        expect(taxonomy?.is_attribution).toBe(false);
+    });
+});
+describe("auditCitations", () => {
+    it("flags an attribution-style fabrication in quotes_unmatched (the A3 case)", () => {
+        const synthesize = "### Disagreement\n" +
+            '- Axiology said "Naming alignment between value, activity, and concept is not yet resolved".';
+        const axiologyLens = "Findings: Top-level value 시간/비용 최소화 lacks operational backing in executor.";
+        const depLens = "Authority chain integrity circular between core-lexicon.yaml and .onto/principles/.";
+        const structLens = "Naming alignment resolved as of W-A-77.";
+        const result = auditCitations(synthesize, [axiologyLens, depLens, structLens]);
+        expect(result.quotes_checked).toBe(1);
+        expect(result.attribution_count).toBe(1);
+        expect(result.quotes_unmatched).toContain("Naming alignment between value, activity, and concept is not yet resolved");
+        expect(result.quotes_unmatched_meta).toEqual([]);
+    });
+    it("routes non-attribution unmatched quotes to quotes_unmatched_meta (taxonomy labels)", () => {
+        const synthesize = 'The section is titled "conditional consensus" per the canonical taxonomy, and separately "cross-process deliberation" appears as a meta-concept.';
+        const lensA = "Irrelevant lens body without any taxonomy phrase.";
+        const result = auditCitations(synthesize, [lensA]);
+        // Both taxonomy labels are above threshold 20 and unmatched.
+        expect(result.quotes_unmatched).toEqual([]);
+        expect(result.quotes_unmatched_meta.length).toBeGreaterThanOrEqual(1);
+        // Neither was an attribution citation.
+        expect(result.attribution_count).toBe(0);
+    });
+    it("passes an attribution-style quote that substring-matches a lens", () => {
+        const synthesize = 'axiology: "Top-level value 시간/비용 최소화 lacks operational backing"';
+        const lensContent = "Findings: Top-level value 시간/비용 최소화 lacks operational backing in executor selection.";
+        const result = auditCitations(synthesize, [lensContent]);
+        expect(result.quotes_checked).toBe(1);
+        expect(result.attribution_count).toBe(1);
+        expect(result.quotes_unmatched).toEqual([]);
+        expect(result.quotes_unmatched_meta).toEqual([]);
+    });
+    it("matches against any lens (disjunction)", () => {
+        const synthesize = 'logic: "unique phrase of sufficient length here"';
+        const lensA = "not related content at all";
+        const lensB = "some prose containing unique phrase of sufficient length here inside it";
+        const result = auditCitations(synthesize, [lensA, lensB]);
+        expect(result.quotes_unmatched).toEqual([]);
+        expect(result.quotes_unmatched_meta).toEqual([]);
+    });
+    it("reports empty unmatched lists when no quotes present", () => {
+        const result = auditCitations("Pure synthesis prose.", ["some lens content"]);
+        expect(result.quotes_checked).toBe(0);
+        expect(result.quotes_unmatched).toEqual([]);
+        expect(result.quotes_unmatched_meta).toEqual([]);
+        expect(result.attribution_count).toBe(0);
+    });
+    it("includes min_quote_length in result for traceability", () => {
+        const result = auditCitations("", [], { minQuoteLength: 30 });
+        expect(result.min_quote_length).toBe(30);
+    });
+    it("uses default threshold 20 when options omitted", () => {
+        const result = auditCitations("", []);
+        expect(result.min_quote_length).toBe(20);
+    });
+    it("empty lens pool: attribution unmatched → strict, non-attribution → meta", () => {
+        const synthesize = 'logic: "attribution style phrase of sufficient length for threshold"\n' +
+            'Separately, "non-attributed taxonomy label phrase here" appears.';
+        const result = auditCitations(synthesize, []);
+        expect(result.quotes_checked).toBe(2);
+        expect(result.attribution_count).toBe(1);
+        expect(result.quotes_unmatched).toContain("attribution style phrase of sufficient length for threshold");
+        expect(result.quotes_unmatched_meta).toContain("non-attributed taxonomy label phrase here");
+    });
+});

package/dist/core-runtime/review/controlled-lens-deliberation.js

@@ -0,0 +1,125 @@
+function fencedBlock(label, content) {
+    return [`### ${label}`, "", content.trim() || "(empty)"].join("\n");
+}
+export function buildLensControlledDeliberationPrompt(args) {
+    const otherBlocks = args.other_outputs
+        .map((other) => fencedBlock(`${other.lens_id} primary output (${other.output_path})`, other.content))
+        .join("\n\n---\n\n");
+    return `# Controlled Lens Deliberation Prompt
+
+session_id: ${args.session_id}
+unit_id: deliberation-${args.lens_id}
+unit_kind: deliberation
+lens_id: ${args.lens_id}
+output_path: ${args.output_path}
+
+## Canonical Role
+You are the ${args.lens_id} lens participating in controlled lens deliberation.
+This is a fresh bounded context. You receive only your primary lens output and
+the other participating lens outputs. The teamlead controls this context; do not
+perform final synthesis and do not inspect extra repository files.
+
+## Own Primary Lens Output
+${fencedBlock(`${args.lens_id} primary output (${args.own_output.output_path})`, args.own_output.content)}
+
+## Other Participating Lens Outputs
+${otherBlocks || "(none)"}
+
+## Issue Artifact Context
+${args.issue_artifact_context?.trim() || "(none)"}
+
+## Task
+Re-evaluate your lens position against the other lens outputs.
+
+- Identify where another lens changes, strengthens, or weakens your conclusion.
+- If no other lens output is provided, state that no cross-lens contest is
+  available and preserve your bounded primary position.
+- Use the issue artifact context to focus on root-cause issue clusters and planned contested points.
+- Identify direct disagreements and state whether your lens concedes, narrows,
+  or maintains its position.
+- Preserve evidence limitations explicitly.
+- Do not decide the final review outcome. The teamlead deliberation result will
+  resolve or preserve contested points after reading every lens response.
+
+## Required Output Sections
+Use exactly these heading names:
+
+\`\`\`
+## Re-evaluation Summary
+## Accepted From Other Lenses
+## Contested Points
+## Position Changes
+## Final Lens Position
+\`\`\`
+
+Write only the markdown body for your deliberation response.`;
+}
+export function buildTeamleadControlledDeliberationPrompt(args) {
+    const primaryBlocks = args.lens_outputs
+        .map((lens) => fencedBlock(`${lens.lens_id} primary output (${lens.output_path})`, lens.content))
+        .join("\n\n---\n\n");
+    const responseBlocks = args.lens_deliberation_responses
+        .map((response) => fencedBlock(`${response.lens_id} deliberation response (${response.response_path})`, response.content))
+        .join("\n\n---\n\n");
+    return `# Teamlead Controlled Deliberation Prompt
+
+session_id: ${args.session_id}
+unit_id: controlled-deliberation
+unit_kind: deliberation
+output_path: ${args.output_path}
+
+## Canonical Role
+You are the teamlead-controlled deliberation resolver. Your job is to derive the
+controlled deliberation result from lens primary outputs and lens deliberation
+responses. You are not the final synthesize actor.
+
+## Inputs In Scope
+Only the material below is in scope.
+
+## Primary Lens Outputs
+${primaryBlocks}
+
+## Lens Deliberation Responses
+${responseBlocks}
+
+## Issue Artifact Context
+${args.issue_artifact_context?.trim() || "(none)"}
+
+## Task
+Resolve contested points when the lens deliberation responses provide enough
+reason to converge. Preserve unresolved disagreement when the responses do not
+justify convergence. Do not invent a new lens perspective.
+If only one lens participates, record that cross-lens disagreement is not
+applicable for this run and preserve the single lens position as bounded
+evidence, not as multi-lens consensus.
+Use the issue artifact context as the root-cause issue frame; preserve issue IDs
+and planned contested points when they are present.
+
+## Required Frontmatter
+Start the output with:
+
+\`\`\`
+---
+deliberation_status: performed
+---
+\`\`\`
+
+## Required Output Sections
+Use exactly these heading names. The final synthesize stage consumes this file
+as the authoritative deliberation result.
+
+\`\`\`
+## Consensus
+## Conditional Consensus
+## Disagreement
+## Deliberation Decision
+## Axiology-Proposed Additional Perspectives
+## Purpose Alignment Verification
+## Immediate Actions Required
+## Recommendations
+## Unique Finding Tagging
+\`\`\`
+
+The Deliberation Decision section must map every contested point to one of:
+resolved, narrowed, or unresolved-with-reason.`;
+}