agent-bober 0.17.1 → 0.19.0

package/dist/seo/analyzer.js

@@ -0,0 +1,265 @@
+/**
+ * SeoAnalyzer — LLM-grounded synthesis of `SeoFinding[]` via the
+ * provider-agnostic adapter layer (spec-20260715-ultimate-seo-suite,
+ * Sprint 10; arch-20260715-ultimate-seo-agents-skills-architecture.md:242-276).
+ *
+ * The `llm`/`model` are CONSTRUCTOR-injected (mirrors
+ * `SeoPlaybookRetriever(index)`, retriever.ts:121, and
+ * `getGroundingVerdict({llm,model})`, grounding-critic.ts:170-177) — the
+ * real client is built by the Sprint 11 runner via `createClient`
+ * (providers/factory.ts:192); tests inject a scripted fake, never a real
+ * provider.
+ *
+ * Defensive parse (3-tier extraction + zod `safeParse`, copied from
+ * `validateGroundingVerdict`, grounding-critic.ts:40-88) NEVER throws on a
+ * parse failure — it returns `{ findings: [], parsed: false }`
+ * (fail-closed, sc-10-2). A TRANSPORT error from `llm.chat` is a different
+ * failure mode and is left to propagate (mirrors
+ * grounding-critic.test.ts:273-289) — it is not caught here.
+ *
+ * `now` is injected (Sprint 10 nonGoal: "Analyzer must not read the clock
+ * or the filesystem for time") — this file never constructs a Date object
+ * and never looks up the current wall-clock time itself.
+ *
+ * `context` is typed as `SeoRetrieveResult` (retriever.ts:22-25), the
+ * concrete type that already carries `promptFragment` — NOT a
+ * `SeoPlaybookContext` (that name appears in the architecture prose but no
+ * such type exists in the codebase; see the sprint briefing §0).
+ */
+import { z } from "zod";
+import { AiVisibilityScorer } from "./ai-visibility-scorer.js";
+// -- Model-facing finding schema (defensive, never trusts the LLM blindly) --
+const SeoFindingEvidenceSchema = z.object({
+    metric: z.string(),
+    value: z.string(),
+    source: z.string(),
+    url: z.string(),
+});
+/**
+ * What we require the MODEL to emit per finding. `workflow` is deliberately
+ * excluded — the analyzer stamps `input.workflow` onto every finding itself
+ * rather than trusting the model to echo it back correctly. `severity` is a
+ * strict 1..5 literal union: an out-of-range value (e.g. `7`) fails
+ * validation rather than silently producing an out-of-range `SeoFinding`.
+ */
+const SeoModelFindingSchema = z.object({
+    recommendation: z.string().min(1),
+    playbookRef: z.string().min(1),
+    citationUrl: z.string(),
+    evidence: z.array(SeoFindingEvidenceSchema).default([]),
+    severity: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4), z.literal(5)]),
+    humanApprovalRequired: z.boolean(),
+    confidence: z.enum(["firm", "tentative"]),
+});
+const SeoFindingsContainerSchema = z.object({
+    findings: z.array(SeoModelFindingSchema),
+});
+// -- Prompt construction ------------------------------------------------
+const SEO_FINDING_JSON_SHAPE = `{
+  "findings": [
+    {
+      "recommendation": "<concrete, actionable recommendation>",
+      "playbookRef": "<the playbookId (from the playbook context above) this recommendation is grounded in>",
+      "citationUrl": "<REQUIRED absolute http(s) URL to a primary source backing this recommendation>",
+      "evidence": [ { "metric": "<name>", "value": "<observed value>", "source": "<data source>", "url": "<source url>" } ],
+      "severity": 1,
+      "humanApprovalRequired": false,
+      "confidence": "firm"
+    }
+  ]
+}`;
+function describeDataOutcome(label, outcome) {
+    if (outcome === undefined)
+        return `${label}: not requested.`;
+    switch (outcome.kind) {
+        case "disabled":
+            return `${label}: disabled (no data source configured for this capability).`;
+        case "abstain":
+            return `${label}: abstained — ${outcome.reason}.`;
+        case "data":
+            return (`${label} (source: ${outcome.provenance.source}, retrieved: ${outcome.provenance.retrievedAt}):\n` +
+                JSON.stringify(outcome.rows));
+        default: {
+            const _exhaustive = outcome;
+            return _exhaustive;
+        }
+    }
+}
+/**
+ * Runs `AiVisibilityScorer.aggregate` ONLY when the outcome is a live
+ * ai-visibility arm — i.e. `kind === "data"` AND
+ * `provenance.source === "ai-visibility"` (the ONLY producer of that stamp
+ * is the live adapter, `ai-visibility-adapter.ts:136`; NOT the decoy
+ * `QuotaRequest.source` at `ai-visibility-adapter.ts:116`). Every other
+ * outcome (local-export, disabled, abstain, undefined) falls through to the
+ * UNCHANGED `describeDataOutcome` path — byte-identical to pre-change
+ * (sc-5-4, ADR-5 byte-identical-when-off guarantee).
+ */
+function describeAiVisibility(outcome) {
+    if (outcome?.kind === "data" && outcome.provenance.source === "ai-visibility") {
+        const metrics = new AiVisibilityScorer().aggregate(outcome.rows);
+        return (`AI Visibility (source: ${outcome.provenance.source}, retrieved: ${outcome.provenance.retrievedAt}):\n` +
+            JSON.stringify(metrics));
+    }
+    return describeDataOutcome("AI Visibility", outcome);
+}
+function buildDataBundleSummary(data) {
+    return [
+        describeDataOutcome("Search Analytics", data.searchAnalytics),
+        describeDataOutcome("URL Inspection", data.urlInspection),
+        describeDataOutcome("SERP", data.serp),
+        describeDataOutcome("Keywords", data.keywords),
+        describeDataOutcome("Backlinks", data.backlinks),
+        describeAiVisibility(data.aiVisibility),
+        describeDataOutcome("Link Graph", data.linkGraph),
+    ].join("\n\n");
+}
+/** Prompt = the retriever's `promptFragment` + the serialized `DataOutcome` bundle + an explicit output contract. */
+function buildSystemPrompt(input) {
+    return [
+        `You are an SEO analysis engine for the "${input.workflow}" workflow, target "${input.target}".`,
+        `Current reference date/time (for freshness judgments only): ${input.now}.`,
+        `Ground every recommendation in the playbook context and the gathered data below — never invent data.`,
+        `--- Playbook context ---`,
+        input.context.promptFragment,
+        `--- Gathered data ---`,
+        buildDataBundleSummary(input.data),
+        `--- Output contract ---`,
+        `Output ONLY a single JSON object (no prose, no markdown fences, no tool calls) with EXACTLY this shape:`,
+        SEO_FINDING_JSON_SHAPE,
+        `Rules:`,
+        `- EVERY finding MUST have a non-empty, well-formed http(s) "citationUrl" pointing to a primary ` +
+            `source (an official search-engine/platform documentation page, or a first-party data point ` +
+            `already present in the gathered data above). A finding without a well-formed citationUrl will ` +
+            `be dropped before it reaches any human or report.`,
+        `- Set "humanApprovalRequired": true for any tactic that touches policy compliance or spend ` +
+            `(paid links, ad/budget spend, live-API-cost actions, or anything that could trigger a manual ` +
+            `search-engine action).`,
+        `- "severity" must be an integer from 1 (informational) to 5 (critical).`,
+        `- If the evidence is thin or indirect, set "confidence": "tentative" rather than overstating certainty.`,
+        `- If there is nothing actionable in the data above, return {"findings": []}.`,
+    ].join("\n\n");
+}
+function parseFindingsContainer(rawText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText.trim());
+    }
+    catch {
+        // Tier 2: extract from a fenced ```json ... ``` block.
+        const fenceMatch = /```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/.exec(rawText);
+        if (fenceMatch) {
+            try {
+                parsed = JSON.parse(fenceMatch[1].trim());
+            }
+            catch {
+                // fall through to tier 3
+            }
+        }
+        // Tier 3: take the first { ... last } span.
+        if (parsed === undefined) {
+            const braceStart = rawText.indexOf("{");
+            const braceEnd = rawText.lastIndexOf("}");
+            if (braceStart !== -1 && braceEnd > braceStart) {
+                try {
+                    parsed = JSON.parse(rawText.slice(braceStart, braceEnd + 1));
+                }
+                catch {
+                    return { ok: false, error: `No valid JSON object found in response. Raw: ${rawText.slice(0, 200)}` };
+                }
+            }
+            else {
+                return { ok: false, error: `No JSON object found in response. Raw: ${rawText.slice(0, 200)}` };
+            }
+        }
+    }
+    const result = SeoFindingsContainerSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+        return { ok: false, error: issues };
+    }
+    return { ok: true, findings: result.data.findings };
+}
+// -- Assembly -------------------------------------------------------------
+/**
+ * Maps one model-emitted finding onto a full `SeoFinding`, stamping the
+ * caller-known `workflow` and applying defense-in-depth for
+ * `humanApprovalRequired`: OR the model's value with a lookup — a finding
+ * grounded in a `playbookRef` whose matching `SeoSignature.policyClass` is
+ * `"human-approve"` is always flagged for human approval, even if the model
+ * forgot to set the flag itself.
+ *
+ * Applies the same signature-driven-override idiom to `confidence`
+ * (spec-20260717-seo-improver-builder, Sprint 3, ADR-2): a finding grounded
+ * in a signature whose `liveWeightStatus` is `"documented-only"` cannot be
+ * emitted as `"firm"` — it is downgraded to `"tentative"`, because
+ * "documented" guidance is not (yet) corroborated by a live ranking signal.
+ * This is DOWNGRADE-ONLY: `"live-corroborated"`/`"unknown"` never change
+ * `confidence`, and there is no branch that upgrades `"tentative"` ->
+ * `"firm"`.
+ */
+function toSeoFinding(modelFinding, workflow, signaturesByPlaybookId) {
+    const signature = signaturesByPlaybookId.get(modelFinding.playbookRef);
+    const humanApprovalRequired = modelFinding.humanApprovalRequired || signature?.policyClass === "human-approve";
+    const confidence = signature?.liveWeightStatus === "documented-only" && modelFinding.confidence === "firm"
+        ? "tentative"
+        : modelFinding.confidence;
+    return {
+        recommendation: modelFinding.recommendation,
+        workflow,
+        playbookRef: modelFinding.playbookRef,
+        citationUrl: modelFinding.citationUrl,
+        evidence: modelFinding.evidence,
+        severity: modelFinding.severity,
+        humanApprovalRequired,
+        confidence,
+    };
+}
+function collectDataProvenance(data) {
+    const provenance = [];
+    for (const outcome of [
+        data.searchAnalytics,
+        data.urlInspection,
+        data.serp,
+        data.keywords,
+        data.backlinks,
+        data.aiVisibility,
+        data.linkGraph,
+    ]) {
+        if (outcome?.kind === "data")
+            provenance.push(outcome.provenance);
+    }
+    return provenance;
+}
+// -- SeoAnalyzer ------------------------------------------------------------
+export class SeoAnalyzer {
+    llm;
+    model;
+    constructor(llm, model) {
+        this.llm = llm;
+        this.model = model;
+    }
+    /**
+     * Never throws on a PARSE failure (returns `parsed: false` with empty
+     * findings). Does NOT catch a transport error from `llm.chat` — that
+     * rejects the returned promise, distinct from a parse failure.
+     */
+    async analyze(input) {
+        const { workflow, target, context, data } = input;
+        const response = await this.llm.chat({
+            model: this.model,
+            system: buildSystemPrompt(input),
+            messages: [{ role: "user", content: "Produce the findings JSON now." }],
+            jsonObjectMode: true,
+        });
+        const dataProvenance = collectDataProvenance(data);
+        const parsedResult = parseFindingsContainer(response.text);
+        if (!parsedResult.ok) {
+            return { workflow, target, findings: [], parsed: false, dataProvenance };
+        }
+        const signaturesByPlaybookId = new Map(context.signatures.map((s) => [s.playbookId, s]));
+        const findings = parsedResult.findings.map((f) => toSeoFinding(f, workflow, signaturesByPlaybookId));
+        return { workflow, target, findings, parsed: true, dataProvenance };
+    }
+}
+//# sourceMappingURL=analyzer.js.map

package/dist/seo/analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.js","sourceRoot":"","sources":["../../src/seo/analyzer.ts"],"names":[],"mappings":"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"}

package/dist/seo/benchmark/harness.d.ts

@@ -0,0 +1,56 @@
+import type { Finding } from "../../hub/finding.js";
+import type { SeoReport, SeoWorkflow } from "../types.js";
+/** One labelled benchmark case (mirrors a `corpus/manifest.json` entry). */
+export interface SeoBenchmarkCase {
+    /** Stable id, unique in the corpus. */
+    id: string;
+    label: "known-good" | "known-bad";
+    workflow: SeoWorkflow;
+    target: string;
+    /** Written to a temp `<projectRoot>/<id>/imports/<file>` dir before the run. */
+    imports: Array<{
+        file: string;
+        content: string;
+    }>;
+    /** The recorded raw text the `ScriptedClient` returns (a `{"findings":[...]}` JSON string, or garbage to prove fail-closed parsing). */
+    analyzerResponse: string;
+    expected: {
+        /** Each expected finding names its `playbookRef` and whether it should survive the citation gate. */
+        findings: Array<{
+            playbookRef: string;
+            cited: boolean;
+        }>;
+        droppedUncited: number;
+        verdict: "pass" | "blocked";
+    };
+}
+export interface CorpusMetrics {
+    /** ΣTP/(ΣTP+ΣFP) across every case, matched by the `playbook:<ref>` tag. */
+    findingPrecision: number;
+    /** ΣTP/(ΣTP+ΣFN) across every case. */
+    findingRecall: number;
+    /** Σ correctlyDropped / Σ expectedDropped — how well the uncited-drop count matches expectation. */
+    uncitedDropRecall: number;
+    /** INVARIANT: MUST be 0 — count of emitted findings lacking a well-formed `cite:` evidence entry. */
+    uncitedReachedSink: number;
+    /** INVARIANT: MUST be 0 — count of emitted findings whose text matches a never-encode tactic pattern. */
+    neverEncodeEmitted: number;
+    cases: Array<{
+        id: string;
+        emitted: Finding[];
+        report?: SeoReport;
+        exitCode: 0 | 2;
+    }>;
+}
+/**
+ * Run the real `SeoWorkflowRunner` over `corpus`, offline and deterministic
+ * (both egress axes off, an injected `ScriptedClient`-backed analyzer, and a
+ * capturing sink standing in for the hub). Writes each case's inline
+ * `imports[]` under `<projectRoot>/<id>/imports/` before running so
+ * `LocalExportSource` reads real files (no fs mocks, principle L44).
+ *
+ * NEVER throws: `SeoWorkflowRunner.run` itself never throws (runner.ts:256),
+ * and every step here is either that call or pure aggregation.
+ */
+export declare function runBenchmark(corpus: SeoBenchmarkCase[], projectRoot: string): Promise<CorpusMetrics>;
+//# sourceMappingURL=harness.d.ts.map

package/dist/seo/benchmark/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../../src/seo/benchmark/harness.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAMpD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAsB1D,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,YAAY,GAAG,WAAW,CAAC;IAClC,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,wIAAwI;IACxI,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE;QACR,qGAAqG;QACrG,QAAQ,EAAE,KAAK,CAAC;YAAE,WAAW,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,OAAO,CAAA;SAAE,CAAC,CAAC;QACzD,cAAc,EAAE,MAAM,CAAC;QACvB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;KAC7B,CAAC;CACH;AAiBD,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,oGAAoG;IACpG,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qGAAqG;IACrG,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yGAAyG;IACzG,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAC;QAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAA;KAAE,CAAC,CAAC;CACvF;AAyDD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA6D1G"}

package/dist/seo/benchmark/harness.js

@@ -0,0 +1,172 @@
+/**
+ * SeoWorkflowRunner benchmark harness (spec-20260715-ultimate-seo-suite,
+ * Sprint 13, sc-13-1..sc-13-4). Mirrors the shape of the security benchmark
+ * (`src/orchestrator/security-knowledge/benchmark/harness.ts`'s pure
+ * `measure()`), but is RICHER: this harness actually RUNS the real
+ * `SeoWorkflowRunner.run` (async, fs) per labelled corpus case rather than
+ * calling an injected pure finder/verifier function directly. Every case
+ * injects `dataSource` + `analyzer` + `findingSink` (Pattern A, `runner.ts`)
+ * so `selectSource`/`buildDefaultAnalyzer`/`createClient` and the real
+ * `FactStore` are never touched — the whole run is offline and
+ * credential-free (nonGoal: "offline fixtures only").
+ *
+ * Not wired into `SeoWorkflowRunner`, the CLI, or any evaluator gate
+ * (nonGoal: "do not gate the pipeline on a precision/recall threshold this
+ * sprint") — this is a leaf measurement module consumed only by
+ * `harness.test.ts`.
+ *
+ * Clock discipline: `BENCHMARK_NOW` is a fixed constant threaded into every
+ * case's `now` — this file never constructs a `Date` for wall-clock
+ * purposes and never calls `Math.random`.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createDefaultConfig } from "../../config/schema.js";
+import { SeoAnalyzer } from "../analyzer.js";
+import { SeoWorkflowRunner } from "../runner.js";
+import { LocalExportSource } from "../sources/local-export.js";
+// -- ScriptedClient (recorded analyzer response; NO network) --------------
+//
+// Mirrors `src/seo/analyzer.test.ts:11-21` / `src/seo/runner.test.ts:46-56`.
+// Records every `ChatParams` it receives and replays `case.analyzerResponse`
+// verbatim — this is the deterministic "recorded LLM response" a benchmark
+// needs: no network call, no provider key, reproducible across runs.
+class ScriptedClient {
+    responses;
+    calls = [];
+    idx = 0;
+    constructor(responses) {
+        this.responses = responses;
+    }
+    async chat(params) {
+        this.calls.push(params);
+        const text = this.responses[Math.min(this.idx, this.responses.length - 1)] ?? "";
+        this.idx += 1;
+        return { text, toolCalls: [], stopReason: "end", usage: { inputTokens: 3, outputTokens: 5 } };
+    }
+}
+// -- Emitted-text never-encode guard ---------------------------------------
+//
+// A documented mirror of the widened `FORBIDDEN_ACTION_PATTERNS`
+// (`src/seo/skills-content.test.ts`) — scanned over EMITTED (sink-reached)
+// findings rather than skill signatures. Deliberately test-local per the
+// briefing (do not import a `.test.ts` const into this build file).
+const NEVER_ENCODE_EMIT_PATTERNS = [
+    /\bplace\b[^.]*\b(parasite|high-?authority host|third-?party host)/i,
+    /\b(?:buy(?:ing)?|purchas(?:e|ing))\b[^.]*\blinks?\b/i,
+    /\bregister(ing)?\b[^.]*\bexpired domain/i,
+    /\bgenerate\b[^.]*\bmass\b[^.]*\bpages\b/i,
+    /\b(?:mass[-\s]?generat(?:e|ing)|generat(?:e|ing)[-\s]?mass)\b/i,
+    /\bpoison/i,
+];
+const BENCHMARK_NOW = "2026-07-16T00:00:00.000Z"; // FIXED — never new Date()
+// -- Matching + invariant helpers (pure) -----------------------------------
+function extractPlaybookRef(finding) {
+    const tag = finding.tags.find((t) => t.startsWith("playbook:"));
+    return tag?.slice("playbook:".length);
+}
+/** True when `finding` lacks a well-formed absolute http(s) `cite:` evidence entry (uncited-drop invariant scan). */
+function lacksWellFormedCitation(finding) {
+    const citeEntry = finding.evidence.find((e) => e.startsWith("cite:"));
+    if (!citeEntry)
+        return true;
+    try {
+        const parsed = new URL(citeEntry.slice("cite:".length));
+        return parsed.protocol !== "http:" && parsed.protocol !== "https:";
+    }
+    catch {
+        return true;
+    }
+}
+/** True when `finding`'s title+evidence text matches a never-encode tactic pattern. */
+function matchesNeverEncode(finding) {
+    const text = `${finding.title} ${finding.evidence.join(" ")}`;
+    return NEVER_ENCODE_EMIT_PATTERNS.some((p) => p.test(text));
+}
+/**
+ * Score one case's emitted findings against its `expected.findings` by
+ * `playbookRef`, matching a multiset (each expected-cited entry consumes at
+ * most one emitted finding with the same ref). Pure and total.
+ */
+function scoreCase(caseDef, emitted) {
+    const remainingRefs = emitted.map((f) => extractPlaybookRef(f));
+    const expectedCitedRefs = caseDef.expected.findings.filter((f) => f.cited).map((f) => f.playbookRef);
+    let tp = 0;
+    for (const ref of expectedCitedRefs) {
+        const idx = remainingRefs.indexOf(ref);
+        if (idx !== -1) {
+            tp += 1;
+            remainingRefs.splice(idx, 1);
+        }
+    }
+    return { tp, fp: remainingRefs.length, fn: expectedCitedRefs.length - tp };
+}
+const rate = (numerator, denominator) => (denominator === 0 ? 0 : numerator / denominator);
+// -- runBenchmark -------------------------------------------------------
+/**
+ * Run the real `SeoWorkflowRunner` over `corpus`, offline and deterministic
+ * (both egress axes off, an injected `ScriptedClient`-backed analyzer, and a
+ * capturing sink standing in for the hub). Writes each case's inline
+ * `imports[]` under `<projectRoot>/<id>/imports/` before running so
+ * `LocalExportSource` reads real files (no fs mocks, principle L44).
+ *
+ * NEVER throws: `SeoWorkflowRunner.run` itself never throws (runner.ts:256),
+ * and every step here is either that call or pure aggregation.
+ */
+export async function runBenchmark(corpus, projectRoot) {
+    let tpSum = 0;
+    let fpSum = 0;
+    let fnSum = 0;
+    let correctlyDroppedSum = 0;
+    let expectedDroppedSum = 0;
+    let uncitedReachedSink = 0;
+    let neverEncodeEmitted = 0;
+    const cases = [];
+    for (const caseDef of corpus) {
+        const caseRoot = join(projectRoot, caseDef.id);
+        const importsDir = join(caseRoot, "imports");
+        await mkdir(importsDir, { recursive: true });
+        for (const file of caseDef.imports) {
+            await writeFile(join(importsDir, file.file), file.content, "utf-8");
+        }
+        const dataSource = new LocalExportSource(importsDir);
+        const analyzer = new SeoAnalyzer(new ScriptedClient([caseDef.analyzerResponse]), "benchmark-model");
+        const emitted = [];
+        const findingSink = async (finding) => {
+            emitted.push(finding);
+        };
+        const outcome = await new SeoWorkflowRunner().run({
+            projectRoot: caseRoot,
+            config: createDefaultConfig("seo-benchmark", "brownfield"),
+            workflow: caseDef.workflow,
+            target: caseDef.target,
+            now: BENCHMARK_NOW,
+            dataSource,
+            analyzer,
+            findingSink,
+        });
+        const { tp, fp, fn } = scoreCase(caseDef, emitted);
+        tpSum += tp;
+        fpSum += fp;
+        fnSum += fn;
+        const actualDropped = outcome.report?.droppedUncited ?? 0;
+        correctlyDroppedSum += Math.min(actualDropped, caseDef.expected.droppedUncited);
+        expectedDroppedSum += caseDef.expected.droppedUncited;
+        for (const finding of emitted) {
+            if (lacksWellFormedCitation(finding))
+                uncitedReachedSink += 1;
+            if (matchesNeverEncode(finding))
+                neverEncodeEmitted += 1;
+        }
+        cases.push({ id: caseDef.id, emitted, report: outcome.report, exitCode: outcome.exitCode });
+    }
+    return {
+        findingPrecision: rate(tpSum, tpSum + fpSum),
+        findingRecall: rate(tpSum, tpSum + fnSum),
+        uncitedDropRecall: rate(correctlyDroppedSum, expectedDroppedSum),
+        uncitedReachedSink,
+        neverEncodeEmitted,
+        cases,
+    };
+}
+//# sourceMappingURL=harness.js.map

package/dist/seo/benchmark/harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.js","sourceRoot":"","sources":["../../../src/seo/benchmark/harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAG/D,4EAA4E;AAC5E,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,2EAA2E;AAC3E,qEAAqE;AACrE,MAAM,cAAc;IAGW;IAFpB,KAAK,GAAiB,EAAE,CAAC;IAC1B,GAAG,GAAG,CAAC,CAAC;IAChB,YAA6B,SAAmB;QAAnB,cAAS,GAAT,SAAS,CAAU;IAAG,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,MAAkB;QAC3B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACjF,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACd,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC;IAChG,CAAC;CACF;AAuBD,6EAA6E;AAC7E,EAAE;AACF,iEAAiE;AACjE,2EAA2E;AAC3E,yEAAyE;AACzE,oEAAoE;AACpE,MAAM,0BAA0B,GAAa;IAC3C,oEAAoE;IACpE,sDAAsD;IACtD,0CAA0C;IAC1C,0CAA0C;IAC1C,gEAAgE;IAChE,WAAW;CACZ,CAAC;AAgBF,MAAM,aAAa,GAAG,0BAA0B,CAAC,CAAC,2BAA2B;AAE7E,6EAA6E;AAE7E,SAAS,kBAAkB,CAAC,OAAgB;IAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IAChE,OAAO,GAAG,EAAE,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC;AAED,qHAAqH;AACrH,SAAS,uBAAuB,CAAC,OAAgB;IAC/C,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QACxD,OAAO,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,SAAS,kBAAkB,CAAC,OAAgB;IAC1C,MAAM,IAAI,GAAG,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IAC9D,OAAO,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAChB,OAAyB,EACzB,OAAkB;IAElB,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,MAAM,iBAAiB,GAAG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAErG,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;YACf,EAAE,IAAI,CAAC,CAAC;YACR,aAAa,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,aAAa,CAAC,MAAM,EAAE,EAAE,EAAE,iBAAiB,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;AAC7E,CAAC;AAED,MAAM,IAAI,GAAG,CAAC,SAAiB,EAAE,WAAmB,EAAU,EAAE,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,WAAW,CAAC,CAAC;AAEnH,0EAA0E;AAE1E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAA0B,EAAE,WAAmB;IAChF,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,mBAAmB,GAAG,CAAC,CAAC;IAC5B,IAAI,kBAAkB,GAAG,CAAC,CAAC;IAC3B,IAAI,kBAAkB,GAAG,CAAC,CAAC;IAC3B,IAAI,kBAAkB,GAAG,CAAC,CAAC;IAC3B,MAAM,KAAK,GAA2B,EAAE,CAAC;IAEzC,KAAK,MAAM,OAAO,IAAI,MAAM,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QAC/C,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC7C,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7C,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACnC,MAAM,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACtE,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,IAAI,WAAW,CAAC,IAAI,cAAc,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;QACpG,MAAM,OAAO,GAAc,EAAE,CAAC;QAC9B,MAAM,WAAW,GAAmB,KAAK,EAAE,OAAO,EAAE,EAAE;YACpD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC,CAAC;QAEF,MAAM,OAAO,GAAG,MAAM,IAAI,iBAAiB,EAAE,CAAC,GAAG,CAAC;YAChD,WAAW,EAAE,QAAQ;YACrB,MAAM,EAAE,mBAAmB,CAAC,eAAe,EAAE,YAAY,CAAC;YAC1D,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,GAAG,EAAE,aAAa;YAClB,UAAU;YACV,QAAQ;YACR,WAAW;SACZ,CAAC,CAAC;QAEH,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACnD,KAAK,IAAI,EAAE,CAAC;QACZ,KAAK,IAAI,EAAE,CAAC;QACZ,KAAK,IAAI,EAAE,CAAC;QAEZ,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,cAAc,IAAI,CAAC,CAAC;QAC1D,mBAAmB,IAAI,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;QAChF,kBAAkB,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;QAEtD,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;YAC9B,IAAI,uBAAuB,CAAC,OAAO,CAAC;gBAAE,kBAAkB,IAAI,CAAC,CAAC;YAC9D,IAAI,kBAAkB,CAAC,OAAO,CAAC;gBAAE,kBAAkB,IAAI,CAAC,CAAC;QAC3D,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED,OAAO;QACL,gBAAgB,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC;QAC5C,aAAa,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC;QACzC,iBAAiB,EAAE,IAAI,CAAC,mBAAmB,EAAE,kBAAkB,CAAC;QAChE,kBAAkB;QAClB,kBAAkB;QAClB,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/seo/builder/approved-finding.d.ts

@@ -0,0 +1,115 @@
+/**
+ * ApprovedFinding — the structural safety boundary between the hub and the
+ * Sprint-12 `SeoBuilder` (spec-20260717-seo-improver-builder, Sprint 11;
+ * ADR-4, `.bober/architecture/arch-20260716-seo-improver-builder-extension-adr-4.md`).
+ *
+ * Constructible ONLY via `ApprovedFinding.from(...)` — the sole factory,
+ * itself never throwing — which asserts the hub Finding is human-approved
+ * AND carries a well-formed `cite:` evidence URL before minting an instance.
+ * A raw/dropped/downgraded/uncited `SeoFinding` has NO public path into this
+ * type: a dropped finding never reached the hub as an approved action, so no
+ * `ApprovedFinding` can exist for it (resurrection structurally impossible,
+ * sc-11-1/sc-11-2).
+ *
+ * Schema-vs-contract reconciliation (see the Sprint-11 briefing §0): the
+ * canonical hub `FindingSchema.status` (`../hub/finding.js:23`) is
+ * `z.enum(["open","in-progress","snoozed","done","dropped"])` — there is NO
+ * `"approved"` status, so `finding.status === "approved"` against a raw
+ * `Finding` is a TS2367 compile error. Mirroring the do-bridge port-local
+ * pattern (`../do-bridge/finding-port.ts:10-19`, "the hub schema is NOT
+ * modified"), `ApprovedHubFindingSchema` below WIDENS the status union
+ * locally — `../hub/finding.ts` stays byte-identical. Likewise `Finding` has
+ * no top-level `citationUrl`; the SEO citation round-trips inside
+ * `evidence[]` as a `cite:<url>` string (encoded at
+ * `../hub-emitter.ts:76`, decode precedent at `../benchmark/harness.ts:112-121`)
+ * — `extractCitationUrl` below decodes exactly what the emitter encoded.
+ */
+import { z } from "zod";
+/**
+ * Builder-local widened view of the hub `Finding` shape — adds `"approved"`
+ * to the status union WITHOUT mutating the canonical `FindingSchema`
+ * (mirrors `../../do-bridge/finding-port.ts:10-19`). Every other field is
+ * reused verbatim via `.extend()`.
+ */
+export declare const ApprovedHubFindingSchema: z.ZodObject<{
+    id: z.ZodString;
+    domain: z.ZodString;
+    title: z.ZodString;
+    kind: z.ZodEnum<["action", "watch", "risk", "question"]>;
+    urgency: z.ZodNumber;
+    severity: z.ZodNumber;
+    evidence: z.ZodArray<z.ZodString, "many">;
+    surfacedAt: z.ZodString;
+    dueBy: z.ZodOptional<z.ZodString>;
+    tags: z.ZodArray<z.ZodString, "many">;
+    estDurationMin: z.ZodOptional<z.ZodNumber>;
+    calendarSafeTitle: z.ZodOptional<z.ZodString>;
+    promotesTo: z.ZodOptional<z.ZodString>;
+} & {
+    status: z.ZodEnum<["open", "in-progress", "snoozed", "done", "dropped", "approved"]>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    domain: string;
+    title: string;
+    kind: "action" | "watch" | "risk" | "question";
+    status: "open" | "in-progress" | "snoozed" | "done" | "dropped" | "approved";
+    urgency: number;
+    severity: number;
+    evidence: string[];
+    surfacedAt: string;
+    tags: string[];
+    dueBy?: string | undefined;
+    estDurationMin?: number | undefined;
+    calendarSafeTitle?: string | undefined;
+    promotesTo?: string | undefined;
+}, {
+    id: string;
+    domain: string;
+    title: string;
+    kind: "action" | "watch" | "risk" | "question";
+    status: "open" | "in-progress" | "snoozed" | "done" | "dropped" | "approved";
+    urgency: number;
+    severity: number;
+    evidence: string[];
+    surfacedAt: string;
+    tags: string[];
+    dueBy?: string | undefined;
+    estDurationMin?: number | undefined;
+    calendarSafeTitle?: string | undefined;
+    promotesTo?: string | undefined;
+}>;
+export type ApprovedHubFinding = z.infer<typeof ApprovedHubFindingSchema>;
+/**
+ * A hub Finding a human has approved, carrying a decoded, well-formed
+ * citation. The private constructor + private brand field together make
+ * this type NOMINAL: a structurally-similar plain object (e.g. a raw
+ * `SeoFinding` literal) is never assignable, and `new ApprovedFinding(...)`
+ * is unreachable outside this module. `ApprovedFinding.from` is the ONLY
+ * public construction path.
+ */
+export declare class ApprovedFinding {
+    /** The hub Finding id this instance was derived from (provenance). */
+    readonly sourceFindingId: string;
+    readonly title: string;
+    /** Extracted from the `cite:` evidence entry — never invented. */
+    readonly sourceCitationUrl: string;
+    readonly severity: 1 | 2 | 3 | 4 | 5;
+    /** From the `playbook:` tag; empty string if the tag is absent. */
+    readonly playbookRef: string;
+    /** From the `workflow:` tag; empty string if the tag is absent. */
+    readonly workflow: string;
+    private readonly __brand;
+    private constructor();
+    /** Debug representation; also reads `__brand` so it is not flagged unused under `noUnusedLocals`. */
+    toString(): string;
+    /**
+     * The ONLY way to build an `ApprovedFinding`. Returns `null` — NEVER
+     * throws — when `finding.status !== "approved"` or the `cite:` evidence
+     * entry is missing/malformed. This is the single gate ADR-4's Risk
+     * section calls out: "if the adapter itself trusts an un-approved
+     * Finding, the guarantee leaks" — so both checks happen here, in the one
+     * place an `ApprovedFinding` can be minted.
+     */
+    static from(finding: ApprovedHubFinding): ApprovedFinding | null;
+}
+//# sourceMappingURL=approved-finding.d.ts.map

package/dist/seo/builder/approved-finding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approved-finding.d.ts","sourceRoot":"","sources":["../../../src/seo/builder/approved-finding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAgD1E;;;;;;;GAOG;AACH,qBAAa,eAAe;IAQxB,sEAAsE;IACtE,QAAQ,CAAC,eAAe,EAAE,MAAM;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,kEAAkE;IAClE,QAAQ,CAAC,iBAAiB,EAAE,MAAM;IAClC,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;IACpC,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAZ3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IAEtD,OAAO;IAaP,qGAAqG;IACrG,QAAQ,IAAI,MAAM;IAIlB;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,GAAG,eAAe,GAAG,IAAI;CAsBjE"}