psyclaw 0.24.0

package/dist/src/workflows/expert-review.d.ts

@@ -0,0 +1,140 @@
+import { Type } from "typebox";
+/** The smallest independent panel used for a bounded manuscript review. */
+export type ExpertReviewRole = "methodologist" | "evidence-critic" | "writing-editor" | "devil-advocate" | "ethics-reviewer" | "reproducibility-reviewer";
+export type ExpertReviewSeverity = "block" | "major" | "minor" | "note";
+export type ExpertReviewDisposition = "accept" | "revise" | "reject" | "uncertain";
+export interface ExpertReviewFinding {
+    id: string;
+    severity: ExpertReviewSeverity;
+    rule: string;
+    message: string;
+    /** A finding must point to an input, claim, or artifact when one exists. */
+    refs: string[];
+    disposition: ExpertReviewDisposition;
+}
+export interface ExpertReviewOpinion {
+    schemaVersion: "psyclaw/expert-review-opinion/v1";
+    runId: string;
+    taskId: string;
+    dispatchId: string;
+    expertId: string;
+    role: ExpertReviewRole;
+    outcome: "complete" | "blocked" | "uncertain";
+    summary: string;
+    findings: ExpertReviewFinding[];
+    /** Empty is valid only when the expert explicitly reports no findings. */
+    evidenceRefs: string[];
+}
+export interface ExpertReviewContract {
+    schemaVersion: "psyclaw/expert-review/v1";
+    runId: string;
+    subject: {
+        kind: "manuscript" | "artifact" | "workflow";
+        ref: string;
+    };
+    inputRefs: string[];
+    experts: {
+        expertId: string;
+        role: ExpertReviewRole;
+        taskId: string;
+    }[];
+    requiredRoles: ExpertReviewRole[];
+    minOpinions: number;
+    independent: true;
+    output: {
+        artifactPath: string;
+        verdictPath: string;
+    };
+}
+export interface ExpertReviewResult {
+    schemaVersion: "psyclaw/expert-review-result/v1";
+    runId: string;
+    verdict: "pass" | "blocked" | "uncertain";
+    opinions: ExpertReviewOpinion[];
+    findings: ExpertReviewFinding[];
+    unresolvedRoles: ExpertReviewRole[];
+    /** Aggregation is a report only; it never upgrades an unsupported finding. */
+    blockReasons: string[];
+}
+export declare const ExpertReviewOpinionSchema: Type.TObject<{
+    schemaVersion: Type.TLiteral<"psyclaw/expert-review-opinion/v1">;
+    runId: Type.TString;
+    taskId: Type.TString;
+    dispatchId: Type.TString;
+    expertId: Type.TString;
+    role: Type.TUnion<[Type.TLiteral<"methodologist">, Type.TLiteral<"evidence-critic">, Type.TLiteral<"writing-editor">, Type.TLiteral<"devil-advocate">, Type.TLiteral<"ethics-reviewer">, Type.TLiteral<"reproducibility-reviewer">]>;
+    outcome: Type.TUnion<[Type.TLiteral<"complete">, Type.TLiteral<"blocked">, Type.TLiteral<"uncertain">]>;
+    summary: Type.TString;
+    findings: Type.TArray<Type.TObject<{
+        id: Type.TString;
+        severity: Type.TUnion<[Type.TLiteral<"block">, Type.TLiteral<"major">, Type.TLiteral<"minor">, Type.TLiteral<"note">]>;
+        rule: Type.TString;
+        message: Type.TString;
+        refs: Type.TArray<Type.TString>;
+        disposition: Type.TUnion<[Type.TLiteral<"accept">, Type.TLiteral<"revise">, Type.TLiteral<"reject">, Type.TLiteral<"uncertain">]>;
+    }>>;
+    evidenceRefs: Type.TArray<Type.TString>;
+}>;
+export declare const ExpertReviewContractSchema: Type.TObject<{
+    schemaVersion: Type.TLiteral<"psyclaw/expert-review/v1">;
+    runId: Type.TString;
+    subject: Type.TObject<{
+        kind: Type.TUnion<[Type.TLiteral<"manuscript">, Type.TLiteral<"artifact">, Type.TLiteral<"workflow">]>;
+        ref: Type.TString;
+    }>;
+    inputRefs: Type.TArray<Type.TString>;
+    experts: Type.TArray<Type.TObject<{
+        expertId: Type.TString;
+        role: Type.TUnion<[Type.TLiteral<"methodologist">, Type.TLiteral<"evidence-critic">, Type.TLiteral<"writing-editor">, Type.TLiteral<"devil-advocate">, Type.TLiteral<"ethics-reviewer">, Type.TLiteral<"reproducibility-reviewer">]>;
+        taskId: Type.TString;
+    }>>;
+    requiredRoles: Type.TArray<Type.TUnion<[Type.TLiteral<"methodologist">, Type.TLiteral<"evidence-critic">, Type.TLiteral<"writing-editor">, Type.TLiteral<"devil-advocate">, Type.TLiteral<"ethics-reviewer">, Type.TLiteral<"reproducibility-reviewer">]>>;
+    minOpinions: Type.TInteger;
+    independent: Type.TLiteral<true>;
+    output: Type.TObject<{
+        artifactPath: Type.TString;
+        verdictPath: Type.TString;
+    }>;
+}>;
+export declare const ExpertReviewResultSchema: Type.TObject<{
+    schemaVersion: Type.TLiteral<"psyclaw/expert-review-result/v1">;
+    runId: Type.TString;
+    verdict: Type.TUnion<[Type.TLiteral<"pass">, Type.TLiteral<"blocked">, Type.TLiteral<"uncertain">]>;
+    opinions: Type.TArray<Type.TObject<{
+        schemaVersion: Type.TLiteral<"psyclaw/expert-review-opinion/v1">;
+        runId: Type.TString;
+        taskId: Type.TString;
+        dispatchId: Type.TString;
+        expertId: Type.TString;
+        role: Type.TUnion<[Type.TLiteral<"methodologist">, Type.TLiteral<"evidence-critic">, Type.TLiteral<"writing-editor">, Type.TLiteral<"devil-advocate">, Type.TLiteral<"ethics-reviewer">, Type.TLiteral<"reproducibility-reviewer">]>;
+        outcome: Type.TUnion<[Type.TLiteral<"complete">, Type.TLiteral<"blocked">, Type.TLiteral<"uncertain">]>;
+        summary: Type.TString;
+        findings: Type.TArray<Type.TObject<{
+            id: Type.TString;
+            severity: Type.TUnion<[Type.TLiteral<"block">, Type.TLiteral<"major">, Type.TLiteral<"minor">, Type.TLiteral<"note">]>;
+            rule: Type.TString;
+            message: Type.TString;
+            refs: Type.TArray<Type.TString>;
+            disposition: Type.TUnion<[Type.TLiteral<"accept">, Type.TLiteral<"revise">, Type.TLiteral<"reject">, Type.TLiteral<"uncertain">]>;
+        }>>;
+        evidenceRefs: Type.TArray<Type.TString>;
+    }>>;
+    findings: Type.TArray<Type.TObject<{
+        id: Type.TString;
+        severity: Type.TUnion<[Type.TLiteral<"block">, Type.TLiteral<"major">, Type.TLiteral<"minor">, Type.TLiteral<"note">]>;
+        rule: Type.TString;
+        message: Type.TString;
+        refs: Type.TArray<Type.TString>;
+        disposition: Type.TUnion<[Type.TLiteral<"accept">, Type.TLiteral<"revise">, Type.TLiteral<"reject">, Type.TLiteral<"uncertain">]>;
+    }>>;
+    unresolvedRoles: Type.TArray<Type.TUnion<[Type.TLiteral<"methodologist">, Type.TLiteral<"evidence-critic">, Type.TLiteral<"writing-editor">, Type.TLiteral<"devil-advocate">, Type.TLiteral<"ethics-reviewer">, Type.TLiteral<"reproducibility-reviewer">]>>;
+    blockReasons: Type.TArray<Type.TString>;
+}>;
+export declare function validateExpertReviewContract(value: unknown): ExpertReviewContract;
+export declare function validateExpertReviewOpinion(value: unknown): ExpertReviewOpinion;
+export declare function validateExpertReviewResult(value: unknown): ExpertReviewResult;
+/**
+ * Deterministically combines independent opinions. It does not infer a
+ * finding from a vote and never upgrades an uncertain or blocked opinion.
+ */
+export declare function aggregateExpertReview(contractValue: unknown, opinionValues: readonly unknown[]): ExpertReviewResult;

package/dist/src/workflows/expert-review.js

@@ -0,0 +1,111 @@
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+const Role = Type.Union([
+    Type.Literal("methodologist"),
+    Type.Literal("evidence-critic"),
+    Type.Literal("writing-editor"),
+    Type.Literal("devil-advocate"),
+    Type.Literal("ethics-reviewer"),
+    Type.Literal("reproducibility-reviewer"),
+]);
+const Finding = Type.Object({
+    id: Type.String({ minLength: 1 }),
+    severity: Type.Union([Type.Literal("block"), Type.Literal("major"), Type.Literal("minor"), Type.Literal("note")]),
+    rule: Type.String({ minLength: 1 }),
+    message: Type.String({ minLength: 1 }),
+    refs: Type.Array(Type.String()),
+    disposition: Type.Union([Type.Literal("accept"), Type.Literal("revise"), Type.Literal("reject"), Type.Literal("uncertain")]),
+}, { additionalProperties: false });
+export const ExpertReviewOpinionSchema = Type.Object({
+    schemaVersion: Type.Literal("psyclaw/expert-review-opinion/v1"),
+    runId: Type.String({ minLength: 1 }), taskId: Type.String({ minLength: 1 }), dispatchId: Type.String({ minLength: 1 }),
+    expertId: Type.String({ minLength: 1 }), role: Role,
+    outcome: Type.Union([Type.Literal("complete"), Type.Literal("blocked"), Type.Literal("uncertain")]),
+    summary: Type.String({ minLength: 1 }), findings: Type.Array(Finding), evidenceRefs: Type.Array(Type.String()),
+}, { additionalProperties: false });
+export const ExpertReviewContractSchema = Type.Object({
+    schemaVersion: Type.Literal("psyclaw/expert-review/v1"), runId: Type.String({ minLength: 1 }),
+    subject: Type.Object({ kind: Type.Union([Type.Literal("manuscript"), Type.Literal("artifact"), Type.Literal("workflow")]), ref: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+    inputRefs: Type.Array(Type.String()),
+    experts: Type.Array(Type.Object({ expertId: Type.String({ minLength: 1 }), role: Role, taskId: Type.String({ minLength: 1 }) }, { additionalProperties: false }), { minItems: 1 }),
+    requiredRoles: Type.Array(Role, { minItems: 1 }), minOpinions: Type.Integer({ minimum: 1 }), independent: Type.Literal(true),
+    output: Type.Object({ artifactPath: Type.String({ minLength: 1 }), verdictPath: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+}, { additionalProperties: false });
+export const ExpertReviewResultSchema = Type.Object({
+    schemaVersion: Type.Literal("psyclaw/expert-review-result/v1"), runId: Type.String({ minLength: 1 }),
+    verdict: Type.Union([Type.Literal("pass"), Type.Literal("blocked"), Type.Literal("uncertain")]),
+    opinions: Type.Array(ExpertReviewOpinionSchema), findings: Type.Array(Finding), unresolvedRoles: Type.Array(Role), blockReasons: Type.Array(Type.String()),
+}, { additionalProperties: false });
+const contractValidator = Compile(ExpertReviewContractSchema);
+const opinionValidator = Compile(ExpertReviewOpinionSchema);
+const resultValidator = Compile(ExpertReviewResultSchema);
+export function validateExpertReviewContract(value) {
+    if (!contractValidator.Check(value))
+        throw new Error("invalid psyclaw/expert-review/v1 contract");
+    const contract = value;
+    const expertRoles = new Set(contract.experts.map((expert) => expert.role));
+    if (contract.minOpinions > contract.experts.length)
+        throw new Error("minOpinions exceeds configured experts");
+    if (contract.requiredRoles.some((role) => !expertRoles.has(role)))
+        throw new Error("required role has no configured expert");
+    if (new Set(contract.requiredRoles).size !== contract.requiredRoles.length)
+        throw new Error("duplicate required role");
+    if (new Set(contract.experts.map((expert) => expert.expertId)).size !== contract.experts.length)
+        throw new Error("duplicate expertId");
+    return contract;
+}
+export function validateExpertReviewOpinion(value) {
+    if (!opinionValidator.Check(value))
+        throw new Error("invalid psyclaw/expert-review-opinion/v1 opinion");
+    return value;
+}
+export function validateExpertReviewResult(value) {
+    if (!resultValidator.Check(value))
+        throw new Error("invalid psyclaw/expert-review-result/v1 result");
+    return value;
+}
+/**
+ * Deterministically combines independent opinions. It does not infer a
+ * finding from a vote and never upgrades an uncertain or blocked opinion.
+ */
+export function aggregateExpertReview(contractValue, opinionValues) {
+    const contract = validateExpertReviewContract(contractValue);
+    const opinions = opinionValues.map(validateExpertReviewOpinion);
+    const blockReasons = [];
+    const configured = new Map(contract.experts.map((expert) => [expert.expertId, expert]));
+    const seen = new Set();
+    for (const opinion of opinions) {
+        if (opinion.runId !== contract.runId)
+            blockReasons.push(`opinion ${opinion.expertId} belongs to another run`);
+        const expert = configured.get(opinion.expertId);
+        if (!expert)
+            blockReasons.push(`unconfigured expert: ${opinion.expertId}`);
+        else if (expert.role !== opinion.role || expert.taskId !== opinion.taskId)
+            blockReasons.push(`opinion identity mismatch: ${opinion.expertId}`);
+        if (seen.has(opinion.expertId))
+            blockReasons.push(`duplicate opinion: ${opinion.expertId}`);
+        seen.add(opinion.expertId);
+        if (opinion.outcome === "blocked")
+            blockReasons.push(`expert blocked: ${opinion.expertId}`);
+    }
+    const roles = new Set(opinions.map((opinion) => opinion.role));
+    const unresolvedRoles = contract.requiredRoles.filter((role) => !roles.has(role));
+    if (opinions.length < contract.minOpinions)
+        blockReasons.push("minimum opinion count not met");
+    if (unresolvedRoles.length > 0)
+        blockReasons.push(`missing required roles: ${unresolvedRoles.join(", ")}`);
+    const findings = opinions.flatMap((opinion) => opinion.findings);
+    if (findings.some((finding) => finding.severity === "block"))
+        blockReasons.push("blocking finding reported");
+    const uncertain = opinions.some((opinion) => opinion.outcome === "uncertain") || findings.some((finding) => finding.disposition === "uncertain");
+    return {
+        schemaVersion: "psyclaw/expert-review-result/v1",
+        runId: contract.runId,
+        verdict: blockReasons.length > 0 ? "blocked" : uncertain ? "uncertain" : "pass",
+        opinions,
+        findings,
+        unresolvedRoles,
+        blockReasons,
+    };
+}
+//# sourceMappingURL=expert-review.js.map

package/dist/src/workflows/expert-review.js.map

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

package/dist/src/workflows/institutional-fulltext.d.ts

@@ -0,0 +1,16 @@
+import type { InstitutionalRequestPlan, LiteratureRequestMode, MetadataCandidate, VerifiedFulltextRecord } from "../literature/contracts.js";
+import { type WorkflowResult, type WorkflowSpec } from "./spec.js";
+export declare const institutionalFulltextSpec: WorkflowSpec;
+export declare function runInstitutionalFulltext(root: string, identifier?: string): Promise<WorkflowResult>;
+export declare function recordVerifiedInstitutionalFulltext(root: string, options: {
+    path: string;
+    expected: MetadataCandidate;
+    observed: MetadataCandidate;
+    approved: boolean;
+    retrievedAt?: string;
+}): Promise<VerifiedFulltextRecord>;
+export declare function makeInstitutionalRequestPlan(target: string, options?: {
+    mode?: LiteratureRequestMode;
+    apiUrl?: string;
+    allowedDomains?: string[];
+}): InstitutionalRequestPlan;

package/dist/src/workflows/institutional-fulltext.js

@@ -0,0 +1,110 @@
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { appendEvidence, readProject } from "../research/ledger.js";
+import { assertSafeProjectPath } from "../project/paths.js";
+import { crossCheckMetadata, detectFulltext, sha256Bytes } from "../literature/metadata.js";
+import { allParadigms, finalizeWorkflow } from "./spec.js";
+export const institutionalFulltextSpec = {
+    id: "institutional-fulltext",
+    version: "1.0.0",
+    description: "Prepare an auditable, human-approved browser workflow for retrieving institutionally authorized full text.",
+    paradigms: allParadigms,
+    steps: [
+        { id: "identify", role: "researcher", effect: "read", description: "normalize the DOI, publisher URL, or title supplied by the researcher" },
+        { id: "browse", role: "researcher", effect: "read", description: "use the user's already authenticated browser session" },
+        { id: "approve-download", role: "verifier", effect: "write", description: "ask for confirmation before downloading a licensed full text" },
+        { id: "validate", role: "verifier", effect: "read", description: "verify PDF signature, title/DOI, size, and SHA-256" },
+        { id: "ledger", role: "writer", effect: "write", description: "import the verified local PDF as evidence" },
+    ],
+    requiredArtifacts: ["institutional-fulltext-plan.json", "institutional-fulltext-plan.md"],
+};
+export async function runInstitutionalFulltext(root, identifier = "") {
+    const project = await readProject(root);
+    const target = identifier.trim() || project.goal;
+    const isUrl = /^https?:\/\//i.test(target);
+    const isDoi = /^10\.\d{4,9}\//i.test(target);
+    const plan = {
+        schemaVersion: "psyclaw/institutional-fulltext-plan/v1",
+        documentVersion: "1.0.0",
+        target: { value: target, kind: isUrl ? "publisher-url" : isDoi ? "doi" : "title-or-query" },
+        bridge: {
+            adapter: "playwright-mcp",
+            mode: "existing-chrome-tab",
+            credentialPolicy: "user-authenticated-session-only",
+            network: "publisher-domain-only",
+        },
+        steps: [
+            { id: "identify", action: "resolve DOI/title and verify publisher page" },
+            { id: "authenticate", action: "user completes institutional login, VPN, or proxy in the visible browser" },
+            { id: "confirm", action: "human confirms the exact article and download action" },
+            { id: "download", action: "save PDF under data/clean or an approved evidence staging path" },
+            { id: "validate", action: "check PDF magic bytes, non-HTML content, title/DOI match, size, and SHA-256" },
+            { id: "record", action: "import verified file with psyclaw evidence add and retain source receipt" },
+        ],
+        stopConditions: [
+            "login page, CAPTCHA, or access denied",
+            "publisher page does not match the requested work",
+            "download is HTML, truncated, or hash changes",
+            "the action would bypass access controls or violate the user's authorization",
+        ],
+        approval: { requiredBefore: ["download", "record"], actor: "human", status: "pending" },
+    };
+    const markdown = [
+        "# Institutional Full Text Plan",
+        "",
+        `Target: ${target}`,
+        `Bridge: ${plan.bridge.adapter} (${plan.bridge.mode})`,
+        "",
+        "## Human Gate",
+        "",
+        "The user must complete institutional authentication in the visible browser and confirm the exact article before download.",
+        "",
+        "## Steps",
+        "",
+        ...plan.steps.map((step, index) => `${index + 1}. **${step.id}** — ${step.action}`),
+        "",
+        "## Stop Conditions",
+        "",
+        ...plan.stopConditions.map((item) => `- ${item}`),
+        "",
+        "## Next Action",
+        "",
+        "Open the plan in the workbench, connect the approved browser bridge, and request human confirmation before the download step.",
+        "",
+    ].join("\n");
+    return finalizeWorkflow(root, institutionalFulltextSpec, {
+        gates: [{ gateId: "institutional-fulltext:human-approval", ok: false, severity: "block", reason: "human must confirm the authenticated article and download" }],
+        outputs: [
+            { path: "institutional-fulltext-plan.json", contents: `${JSON.stringify(plan, null, 2)}\n` },
+            { path: "institutional-fulltext-plan.md", contents: markdown },
+        ],
+        completed: ["target normalized", "browser bridge and validation plan prepared"],
+    });
+}
+export async function recordVerifiedInstitutionalFulltext(root, options) {
+    if (!options.approved)
+        throw new Error("human approval is required before ledger record");
+    const safe = await assertSafeProjectPath(root, options.path);
+    const bytes = await readFile(safe);
+    const contentType = detectFulltext(bytes);
+    if (contentType === "unknown")
+        throw new Error("full text is neither PDF nor HTML");
+    const crossCheck = crossCheckMetadata(options.expected, options.observed);
+    if (!crossCheck.match)
+        throw new Error(`metadata cross-check failed: ${crossCheck.reasons.join("; ")}`);
+    const hash = sha256Bytes(bytes);
+    const evidence = { id: `institutional:${hash.slice(0, 16)}`, source: { kind: "file", locator: resolve(root, options.path), title: options.observed.title ?? basename(options.path) }, level: "fulltext", retrievedAt: options.retrievedAt ?? new Date().toISOString(), sha256: hash, accessStatus: "verified", locators: [{ kind: "file", value: options.path }, ...(crossCheck.normalizedDoi ? [{ kind: "doi", value: crossCheck.normalizedDoi }] : [])] };
+    await appendEvidence(root, evidence);
+    return { evidence, crossCheck, contentType, sha256: hash, approval: "approved" };
+}
+export function makeInstitutionalRequestPlan(target, options = {}) {
+    const value = target.trim();
+    const doi = /^10\.\d{4,9}\//i.test(value);
+    const url = /^https?:\/\//i.test(value);
+    const mode = options.mode ?? "browser";
+    const plan = { schemaVersion: "psyclaw/institutional-request-plan/v1", mode, target: { value, kind: url ? "publisher-url" : doi ? "doi" : "title-or-query" }, allowedDomains: options.allowedDomains ?? [], approval: { required: true, before: ["network", "download", "ledger-record"], status: "pending" }, stopConditions: ["authentication, CAPTCHA, or access denied", "domain is not allowlisted", "request would bypass access controls", "response is HTML login page or metadata does not match"] };
+    if (mode === "api")
+        plan.api = { method: "GET", url: options.apiUrl ?? value, headers: { Accept: "application/pdf, text/html, application/json" }, response: "pdf-or-html" };
+    return plan;
+}
+//# sourceMappingURL=institutional-fulltext.js.map

package/dist/src/workflows/institutional-fulltext.js.map

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

package/dist/src/workflows/literature-review.d.ts

@@ -0,0 +1,3 @@
+import { type WorkflowResult, type WorkflowSpec } from "./spec.js";
+export declare const literatureReviewSpec: WorkflowSpec;
+export declare function runLiteratureReview(root: string): Promise<WorkflowResult>;

package/dist/src/workflows/literature-review.js

@@ -0,0 +1,76 @@
+import { checkEvidenceSufficiency } from "../core/evidence-policy.js";
+import { loadLedger, readProject } from "../research/ledger.js";
+import { buildKnowledgeMap } from "../knowledge-map/index.js";
+import { allParadigms, finalizeWorkflow } from "./spec.js";
+export const literatureReviewSpec = {
+    id: "literature-review",
+    version: "1.0.0",
+    description: "Aggregate the evidence ledger into a review matrix with conflicts and gaps.",
+    paradigms: allParadigms,
+    steps: [
+        { id: "capture", role: "researcher", effect: "read", description: "load sources and claims" },
+        { id: "audit", role: "critic", effect: "read", description: "evidence sufficiency and conflict disclosure" },
+        { id: "write", role: "writer", effect: "write", description: "write review matrix and markdown" },
+    ],
+    requiredArtifacts: ["literature-review.md", "review-matrix.json", "knowledge-map.json"],
+};
+export async function runLiteratureReview(root) {
+    const project = await readProject(root);
+    const ledger = await loadLedger(root);
+    const gates = checkEvidenceSufficiency({ ...ledger, paradigm: project.paradigm });
+    if (ledger.evidence.length === 0) {
+        gates.push({ gateId: "review:sources", ok: false, severity: "block", reason: "no sources recorded" });
+    }
+    const matrix = {
+        schemaVersion: "psyclaw/review-matrix/v1",
+        sources: ledger.evidence.map((item) => ({
+            id: item.id,
+            locator: item.source.locator,
+            level: item.level,
+            accessStatus: item.accessStatus,
+        })),
+        claims: ledger.claims.map((item) => ({
+            id: item.id,
+            kind: item.kind,
+            status: item.status,
+            evidenceIds: item.evidenceIds,
+        })),
+        conflicts: ledger.links
+            .filter((link) => link.relation === "contradicts")
+            .map((link) => ({ claimId: link.claimId, evidenceId: link.evidenceId })),
+        gaps: gates.filter((gate) => !gate.ok).map((gate) => gate.reason),
+    };
+    const knowledgeMap = buildKnowledgeMap(ledger.evidence, ledger.claims);
+    const markdown = [
+        "# Literature Review",
+        "",
+        `Research goal: ${project.goal}`,
+        "",
+        "## Sources",
+        "",
+        ...(matrix.sources.length ? matrix.sources.map((item) => `- [${item.level}] ${item.locator}`) : ["- None"]),
+        "",
+        "## Claims",
+        "",
+        ...(matrix.claims.length ? matrix.claims.map((item) => `- (${item.kind}) ${item.status}: ${item.id}`) : ["- None"]),
+        "",
+        "## Conflicts",
+        "",
+        ...(matrix.conflicts.length ? matrix.conflicts.map((item) => `- ${item.claimId} vs ${item.evidenceId}`) : ["- None"]),
+        "",
+        "## Gaps",
+        "",
+        ...(matrix.gaps.length ? matrix.gaps.map((item) => `- ${item}`) : ["- None"]),
+        "",
+    ].join("\n");
+    return finalizeWorkflow(root, literatureReviewSpec, {
+        gates,
+        outputs: [
+            { path: "literature-review.md", contents: markdown },
+            { path: "review-matrix.json", contents: `${JSON.stringify(matrix, null, 2)}\n` },
+            { path: "knowledge-map.json", contents: `${JSON.stringify(knowledgeMap, null, 2)}\n` },
+        ],
+        completed: ["sources loaded", "claims aggregated", "conflicts and gaps disclosed"],
+    });
+}
+//# sourceMappingURL=literature-review.js.map

package/dist/src/workflows/literature-review.js.map

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

package/dist/src/workflows/meta-analysis.d.ts

@@ -0,0 +1,38 @@
+import { type StageRunner } from "../run.js";
+import { type WorkflowResult, type WorkflowSpec } from "./spec.js";
+export declare const metaAnalysisSpec: WorkflowSpec;
+export interface MetaStudy {
+    id: string;
+    title: string;
+    authors: string[];
+    year?: number;
+    venue?: string;
+    doi?: string;
+    citations?: number;
+}
+/** Search OpenAlex for studies matching the target (real network; injectable for tests). */
+export declare function searchOpenAlex(target: string, nStudies: number, fetchFn?: typeof fetch): Promise<MetaStudy[]>;
+export interface EffectRow {
+    studyId: string;
+    effectSize: number;
+    standardError: number;
+    n?: number;
+}
+/** Parse a CSV with at least `study_id,effect_size,standard_error`. */
+export declare function parseEffectCsv(text: string): EffectRow[];
+export declare function loadEffectDataset(root: string): Promise<EffectRow[] | undefined>;
+/** R metafor script that computes the random-effects model, I², Egger's test, and the forest plot. */
+export declare function metaforScript(datasetPath: string): string;
+export interface MetaAnalysisOptions {
+    target: string;
+    nStudies: number;
+    fetchFn?: typeof fetch;
+    runner?: StageRunner;
+}
+/**
+ * Real meta-analysis pipeline. Statistics are never computed in core: the
+ * audit stage writes an R (metafor) script and the brief records what was
+ * found and what must run externally. Effect sizes come from the project's
+ * dataset; without one the workflow blocks honestly instead of faking numbers.
+ */
+export declare function runMetaAnalysis(root: string, options: MetaAnalysisOptions): Promise<WorkflowResult>;