@useorgx/openclaw-plugin 0.4.8 → 0.7.0

package/dist/paths.js

@@ -1,13 +1,32 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 function normalizeDirOverride(value) {
-    const trimmed = (value ?? "").trim();
+    let trimmed = (value ?? "").trim();
     if (!trimmed)
         return null;
-    if (trimmed.includes("\0"))
+    // `.env` values are often quoted; normalize them before validation.
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        trimmed = trimmed.slice(1, -1).trim();
+        if (!trimmed)
+            return null;
+    }
+    // Reject control characters to avoid malformed or ambiguous filesystem paths.
+    if (/[\u0000-\u001f\u007f]/.test(trimmed))
+        return null;
+    // Reject common escaped/encoded null-byte sequences as well.
+    if (/\\0|\\x00|\\u0000|%00/i.test(trimmed))
         return null;
     return trimmed;
 }
+function resolveOverridePath(override) {
+    if (override === "~")
+        return homedir();
+    if (override.startsWith("~/") || override.startsWith("~\\")) {
+        return resolve(homedir(), override.slice(2));
+    }
+    return resolve(override);
+}
 /**
  * Root directory for persistent OrgX plugin files.
  *
@@ -17,7 +36,7 @@ function normalizeDirOverride(value) {
 export function getOrgxPluginConfigDir() {
     const override = normalizeDirOverride(process.env.ORGX_OPENCLAW_PLUGIN_CONFIG_DIR);
     if (override)
-        return resolve(override);
+        return resolveOverridePath(override);
     return join(homedir(), ".config", "useorgx", "openclaw-plugin");
 }
 export function getOrgxPluginConfigPath(filename) {
@@ -32,7 +51,7 @@ export function getOrgxPluginConfigPath(filename) {
 export function getOpenClawDir() {
     const override = normalizeDirOverride(process.env.OPENCLAW_HOME);
     if (override)
-        return resolve(override);
+        return resolveOverridePath(override);
     return join(homedir(), ".openclaw");
 }
 /**
@@ -44,6 +63,6 @@ export function getOpenClawDir() {
 export function getOrgxOutboxDir() {
     const override = normalizeDirOverride(process.env.ORGX_OUTBOX_DIR);
     if (override)
-        return resolve(override);
+        return resolveOverridePath(override);
     return join(getOpenClawDir(), "orgx-outbox");
 }

package/dist/reporting/rollups.d.ts

@@ -18,3 +18,56 @@ export declare function computeWorkstreamRollup(taskStatuses?: unknown[]): TaskS
     status: WorkstreamRollupStatus;
     progressPct: number;
 };
+export type TaskCompletionReadiness = "ready" | "needs_proof" | "needs_review";
+export interface TaskCompletionReadinessResult {
+    ready: boolean;
+    status: TaskCompletionReadiness;
+    hasArtifact: boolean;
+    hasSchemaValidatedArtifact: boolean;
+    hasQualityScore: boolean;
+    qualityScore: number | null;
+    qualityThreshold: number;
+    missingItems: string[];
+    warnings: string[];
+}
+/**
+ * Evaluate whether a task has sufficient proof chain evidence to be marked
+ * complete. In phase 1 this is advisory (warn-only); callers decide whether
+ * to hard-block or soft-warn based on workspace config.
+ */
+export declare function computeTaskCompletionReadiness(input: {
+    artifacts?: Array<{
+        schema_validated?: boolean;
+        atomic_unit_type?: string;
+    }>;
+    qualityScore?: number | null;
+    qualityThreshold?: number;
+    hasOutcomeEvent?: boolean;
+}): TaskCompletionReadinessResult;
+export type LifecycleState = 'Queued' | 'Dispatching' | 'In Progress' | 'Blocked' | 'Completed' | 'Paused' | 'Failed';
+/**
+ * Derive an honest lifecycle state for an entity based on its raw status
+ * and child statuses. This is the authoritative backend derivation —
+ * the dashboard mirrors this logic in status-taxonomy.ts.
+ */
+export declare function deriveLifecycleState(rawStatus: unknown, childStatuses?: unknown[]): LifecycleState;
+/**
+ * Compute cascaded progress: parent progress derived from child task states.
+ * Returns a percentage (0–100) representing weighted completion.
+ */
+export declare function cascadeProgressFromChildren(childStatuses: unknown[]): number;
+export type EvalPassRateDriftResult = {
+    alert: boolean;
+    baselinePassRate: number;
+    rollingPassRate7d: number;
+    dropPct: number;
+    thresholdDropPct: number;
+    baselineSamples: number;
+    rollingSamples: number;
+};
+export declare function detectEvalPassRateDrift(input: {
+    passRates: unknown[];
+    thresholdDropPct?: number;
+    rollingWindowDays?: number;
+    baselineWindowDays?: number;
+}): EvalPassRateDriftResult | null;

package/dist/reporting/rollups.js

@@ -82,3 +82,151 @@ export function computeWorkstreamRollup(taskStatuses = []) {
         progressPct,
     };
 }
+function normalizePassRate(value) {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n))
+        return null;
+    if (n < 0)
+        return 0;
+    if (n <= 1)
+        return n;
+    if (n <= 100)
+        return n / 100;
+    return 1;
+}
+function average(values) {
+    if (values.length <= 0)
+        return 0;
+    const total = values.reduce((sum, value) => sum + value, 0);
+    return total / values.length;
+}
+/**
+ * Evaluate whether a task has sufficient proof chain evidence to be marked
+ * complete. In phase 1 this is advisory (warn-only); callers decide whether
+ * to hard-block or soft-warn based on workspace config.
+ */
+export function computeTaskCompletionReadiness(input) {
+    const artifacts = Array.isArray(input.artifacts) ? input.artifacts : [];
+    const qualityThreshold = typeof input.qualityThreshold === "number" && Number.isFinite(input.qualityThreshold)
+        ? input.qualityThreshold
+        : 4;
+    const qualityScore = typeof input.qualityScore === "number" && Number.isFinite(input.qualityScore)
+        ? input.qualityScore
+        : null;
+    const hasArtifact = artifacts.length > 0;
+    const hasSchemaValidatedArtifact = artifacts.some((a) => a.schema_validated === true && typeof a.atomic_unit_type === "string");
+    const hasQualityScore = qualityScore !== null;
+    const qualityMeetsThreshold = qualityScore !== null && qualityScore >= qualityThreshold;
+    const missingItems = [];
+    const warnings = [];
+    if (!hasArtifact) {
+        missingItems.push("No artifact registered for this task.");
+    }
+    else if (!hasSchemaValidatedArtifact) {
+        warnings.push("Artifact(s) present but none pass domain schema validation.");
+    }
+    if (!hasQualityScore) {
+        missingItems.push("No quality score recorded.");
+    }
+    else if (!qualityMeetsThreshold) {
+        missingItems.push(`Quality score ${qualityScore} below threshold ${qualityThreshold}.`);
+    }
+    if (input.hasOutcomeEvent === false) {
+        warnings.push("No outcome event recorded (L5 Impact not met).");
+    }
+    const ready = hasArtifact && hasQualityScore && qualityMeetsThreshold;
+    let status;
+    if (ready) {
+        status = "ready";
+    }
+    else if (hasArtifact && hasQualityScore) {
+        status = "needs_review";
+    }
+    else {
+        status = "needs_proof";
+    }
+    return {
+        ready,
+        status,
+        hasArtifact,
+        hasSchemaValidatedArtifact,
+        hasQualityScore,
+        qualityScore,
+        qualityThreshold,
+        missingItems,
+        warnings,
+    };
+}
+/**
+ * Derive an honest lifecycle state for an entity based on its raw status
+ * and child statuses. This is the authoritative backend derivation —
+ * the dashboard mirrors this logic in status-taxonomy.ts.
+ */
+export function deriveLifecycleState(rawStatus, childStatuses) {
+    const s = classifyTaskState(rawStatus);
+    if (s === 'done')
+        return 'Completed';
+    if (s === 'blocked')
+        return 'Blocked';
+    if (!childStatuses || childStatuses.length === 0) {
+        if (s === 'active')
+            return 'In Progress';
+        return 'Queued';
+    }
+    const counts = summarizeTaskStatuses(childStatuses);
+    if (counts.total > 0 && counts.done >= counts.total)
+        return 'Completed';
+    if (counts.blocked > 0 && counts.active === 0 && counts.done < counts.total)
+        return 'Blocked';
+    if (counts.active > 0 || counts.done > 0)
+        return 'In Progress';
+    return 'Queued';
+}
+/**
+ * Compute cascaded progress: parent progress derived from child task states.
+ * Returns a percentage (0–100) representing weighted completion.
+ */
+export function cascadeProgressFromChildren(childStatuses) {
+    if (!Array.isArray(childStatuses) || childStatuses.length === 0)
+        return 0;
+    const counts = summarizeTaskStatuses(childStatuses);
+    return toPercent(counts.done, counts.total);
+}
+export function detectEvalPassRateDrift(input) {
+    const thresholdDropPct = typeof input.thresholdDropPct === "number" && Number.isFinite(input.thresholdDropPct) && input.thresholdDropPct >= 0
+        ? input.thresholdDropPct
+        : 5;
+    const rollingWindowDays = typeof input.rollingWindowDays === "number" && Number.isFinite(input.rollingWindowDays) && input.rollingWindowDays > 0
+        ? Math.floor(input.rollingWindowDays)
+        : 7;
+    const baselineWindowDays = typeof input.baselineWindowDays === "number" &&
+        Number.isFinite(input.baselineWindowDays) &&
+        input.baselineWindowDays > 0
+        ? Math.floor(input.baselineWindowDays)
+        : rollingWindowDays;
+    const normalizedPassRates = (Array.isArray(input.passRates) ? input.passRates : [])
+        .map(normalizePassRate)
+        .filter((value) => value != null);
+    const requiredSamples = rollingWindowDays + baselineWindowDays;
+    if (normalizedPassRates.length < requiredSamples)
+        return null;
+    const rollingStart = normalizedPassRates.length - rollingWindowDays;
+    const baselineEnd = rollingStart;
+    const baselineStart = Math.max(0, baselineEnd - baselineWindowDays);
+    const rollingSlice = normalizedPassRates.slice(rollingStart);
+    const baselineSlice = normalizedPassRates.slice(baselineStart, baselineEnd);
+    if (rollingSlice.length <= 0 || baselineSlice.length <= 0)
+        return null;
+    const baselinePassRate = average(baselineSlice);
+    const rollingPassRate7d = average(rollingSlice);
+    const dropPct = Number(((baselinePassRate - rollingPassRate7d) * 100).toFixed(2));
+    return {
+        alert: dropPct > thresholdDropPct,
+        baselinePassRate: Number(baselinePassRate.toFixed(4)),
+        rollingPassRate7d: Number(rollingPassRate7d.toFixed(4)),
+        dropPct,
+        thresholdDropPct,
+        baselineSamples: baselineSlice.length,
+        rollingSamples: rollingSlice.length,
+    };
+}

package/dist/retro/domain-templates.d.ts

@@ -0,0 +1,45 @@
+type RetroFollowUp = {
+    title: string;
+    priority?: "p0" | "p1" | "p2";
+    reason?: string;
+};
+export type OrgxAgentRetroDomain = "engineering" | "product" | "design" | "marketing" | "sales" | "operations" | "orchestration" | "general";
+export declare function buildRetroTemplateForAgent(input: {
+    agentId: string | null | undefined;
+    success: boolean;
+    taskId: string | null | undefined;
+    runId: string;
+    errorMessage: string | null | undefined;
+}): {
+    domain: OrgxAgentRetroDomain;
+    summary: string;
+    whatWentWell: string[];
+    whatWentWrong: string[];
+    decisions: string[];
+    followUps: RetroFollowUp[];
+};
+/**
+ * Generate a structured retro using an LLM, falling back to the heuristic
+ * template produced by {@link buildRetroTemplateForAgent}.
+ *
+ * Caller: src/index.ts (~line 971) — `buildRetroTemplateForAgent` is invoked
+ * inside the session-stopped handler. Migrate that call site to use this
+ * function when ready to enable LLM-powered retros.
+ */
+export declare function buildRetroWithLlm(input: {
+    agentId: string | null | undefined;
+    success: boolean;
+    taskId: string | null | undefined;
+    runId: string;
+    errorMessage: string | null | undefined;
+    executionContext?: string | null;
+}): Promise<{
+    domain: OrgxAgentRetroDomain;
+    summary: string;
+    whatWentWell: string[];
+    whatWentWrong: string[];
+    decisions: string[];
+    followUps: RetroFollowUp[];
+    source: "llm" | "heuristic";
+}>;
+export {};

package/dist/retro/domain-templates.js

@@ -0,0 +1,297 @@
+import { callLlmJson } from "../http/helpers/llm-client.js";
+const DOMAIN_TEMPLATES = {
+    engineering: {
+        summaryPrefix: "Engineering execution",
+        successWell: [
+            "Delivered implementation changes with focused validation evidence.",
+            "Kept execution scoped to the active slice and avoided unrelated churn.",
+        ],
+        successDecisions: ["No immediate intervention required; keep current engineering execution pattern."],
+        successFollowUps: [
+            {
+                title: "Capture engineering implementation notes for future retros",
+                priority: "p2",
+            },
+        ],
+        failureDecision: "Escalate blocker triage and assign root-cause owner before the next engineering run.",
+        failureFollowUpTitle: "Reproduce failure with a targeted engineering check and patch root cause",
+        failureFollowUpReason: "Engineering runs should converge quickly on reproducible failures and ship a corrective change.",
+    },
+    product: {
+        summaryPrefix: "Product execution",
+        successWell: [
+            "Clarified scope and acceptance criteria for the requested slice.",
+            "Converted ambiguous asks into concrete execution steps.",
+        ],
+        successDecisions: ["Proceed with the current product plan and track any open assumptions."],
+        successFollowUps: [{ title: "Log product assumptions and open questions", priority: "p2" }],
+        failureDecision: "Resolve product scope/acceptance ambiguity with a direct owner decision before retry.",
+        failureFollowUpTitle: "Resolve product requirement ambiguity before next run",
+        failureFollowUpReason: "Product loops fail when acceptance criteria and constraints remain underspecified.",
+    },
+    design: {
+        summaryPrefix: "Design execution",
+        successWell: [
+            "Produced design output aligned with existing system constraints.",
+            "Prioritized usability clarity over decorative changes.",
+        ],
+        successDecisions: ["Continue with the approved design direction and preserve current constraints."],
+        successFollowUps: [{ title: "Attach visual QA checklist for handoff", priority: "p2" }],
+        failureDecision: "Run a blocking UX triage decision and align acceptance checkpoints before rerun.",
+        failureFollowUpTitle: "Run design QA pass and fix blocking UX mismatches",
+        failureFollowUpReason: "Design regressions should be validated with explicit viewport and interaction checks.",
+    },
+    marketing: {
+        summaryPrefix: "Marketing execution",
+        successWell: [
+            "Delivered channel-ready messaging with clear audience targeting.",
+            "Maintained consistent narrative and measurable intent.",
+        ],
+        successDecisions: ["Keep the current campaign direction and monitor defined success signals."],
+        successFollowUps: [{ title: "Record campaign hypotheses and success metrics", priority: "p2" }],
+        failureDecision: "Decide on updated positioning hypothesis before the next marketing execution cycle.",
+        failureFollowUpTitle: "Diagnose marketing execution gap and tighten message-to-metric mapping",
+        failureFollowUpReason: "Marketing outcomes need explicit hypotheses, channel constraints, and measurable goals.",
+    },
+    sales: {
+        summaryPrefix: "Sales execution",
+        successWell: [
+            "Created actionable next steps tied to buyer-stage progression.",
+            "Preserved signal quality for follow-up actions and objections.",
+        ],
+        successDecisions: ["Continue with the current sales motion while maintaining pipeline signal quality."],
+        successFollowUps: [{ title: "Document discovery-to-close handoff notes", priority: "p2" }],
+        failureDecision: "Trigger a sales unblock decision on objection handling and next-step ownership.",
+        failureFollowUpTitle: "Rework sales motion to unblock stalled buyer progression",
+        failureFollowUpReason: "Sales stalls usually reflect missing objection handling or unclear next actions.",
+    },
+    operations: {
+        summaryPrefix: "Operations execution",
+        successWell: [
+            "Stabilized process flow with explicit ownership and runbook alignment.",
+            "Reduced operational risk through controlled scope and sequencing.",
+        ],
+        successDecisions: ["Keep current ops controls and apply runbook deltas from this run."],
+        successFollowUps: [{ title: "Add ops runbook delta from this run", priority: "p2" }],
+        failureDecision: "Escalate operational owner decision to remove the bottleneck before retrying.",
+        failureFollowUpTitle: "Patch operational bottleneck and update runbook controls",
+        failureFollowUpReason: "Operations failures should result in tighter runbooks and clearer owner accountability.",
+    },
+    orchestration: {
+        summaryPrefix: "Orchestration execution",
+        successWell: [
+            "Coordinated dependencies and sequencing across agents effectively.",
+            "Maintained clear control flow for decisions and handoffs.",
+        ],
+        successDecisions: ["Preserve current orchestration sequencing and monitor handoff latency."],
+        successFollowUps: [{ title: "Capture orchestration handoff timing insights", priority: "p2" }],
+        failureDecision: "Request an orchestration sequencing decision to unblock dependency handoffs.",
+        failureFollowUpTitle: "Unblock orchestration handoff failure and re-sequence dependent work",
+        failureFollowUpReason: "Orchestration errors should tighten dependency ordering and handoff contracts.",
+    },
+    general: {
+        summaryPrefix: "Execution",
+        successWell: ["Completed the requested run without runtime error."],
+        successDecisions: ["No immediate action required; continue with the current execution flow."],
+        successFollowUps: [],
+        failureDecision: "Request a human unblock decision before the next retry.",
+        failureFollowUpTitle: "Investigate OpenClaw session failure and unblock task",
+        failureFollowUpReason: "Session ended with error.",
+    },
+};
+function inferDomainFromAgentId(agentId) {
+    const normalized = String(agentId ?? "").trim().toLowerCase();
+    if (!normalized)
+        return "general";
+    const compact = normalized.replace(/[^a-z0-9]/g, "");
+    const tokenSet = new Set(normalized.split(/[^a-z0-9]+/g).filter(Boolean));
+    const hasToken = (...tokens) => tokens.some((token) => tokenSet.has(token));
+    const hasTokenPrefix = (...prefixes) => Array.from(tokenSet).some((token) => prefixes.some((prefix) => token.startsWith(prefix)));
+    if (normalized.includes("sentinel") ||
+        hasToken("sentinel", "watchdog") ||
+        hasTokenPrefix("sentinel", "watch")) {
+        return "orchestration";
+    }
+    if (normalized.includes("engineering") ||
+        normalized.includes("developer") ||
+        hasToken("eng", "dev", "frontend", "backend", "fullstack", "engineer") ||
+        compact.includes("engineering") ||
+        compact.includes("developer")) {
+        return "engineering";
+    }
+    if (normalized.includes("product") ||
+        hasToken("pm", "prod") ||
+        hasTokenPrefix("product", "pm") ||
+        compact.includes("productmanager")) {
+        return "product";
+    }
+    if (normalized.includes("design") || tokenSet.has("ux") || tokenSet.has("ui"))
+        return "design";
+    if (normalized.includes("marketing") ||
+        hasToken("mktg", "growth") ||
+        hasTokenPrefix("mkt", "market")) {
+        return "marketing";
+    }
+    if (normalized.includes("sales") || hasToken("sdr", "ae") || hasTokenPrefix("sales"))
+        return "sales";
+    if (normalized.includes("operations") ||
+        normalized.includes("platform") ||
+        hasToken("ops", "sre", "infra") ||
+        hasTokenPrefix("operat", "platform", "infra")) {
+        return "operations";
+    }
+    if (normalized.includes("orchestrat") ||
+        hasToken("coord", "router") ||
+        hasTokenPrefix("coordinat", "orchestrat", "route")) {
+        return "orchestration";
+    }
+    return "general";
+}
+function isSentinelAgentId(agentId) {
+    const normalized = String(agentId ?? "").trim().toLowerCase();
+    if (!normalized)
+        return false;
+    const compact = normalized.replace(/[^a-z0-9]/g, "");
+    if (normalized.includes("sentinel") || compact.includes("sentinel")) {
+        return true;
+    }
+    const tokenSet = new Set(normalized.split(/[^a-z0-9]+/g).filter(Boolean));
+    return tokenSet.has("watchdog") || Array.from(tokenSet).some((token) => token.startsWith("watch"));
+}
+export function buildRetroTemplateForAgent(input) {
+    const domain = inferDomainFromAgentId(input.agentId);
+    const isSentinel = isSentinelAgentId(input.agentId);
+    const template = DOMAIN_TEMPLATES[domain];
+    const errorMessage = input.errorMessage?.trim() || "Session ended with error.";
+    const summary = input.taskId
+        ? `${template.summaryPrefix} ${input.success ? "completed" : "blocked"} task ${input.taskId}.`
+        : `${template.summaryPrefix} run ${input.success ? "completed" : "blocked"} (session ${input.runId}).`;
+    if (input.success) {
+        return {
+            domain,
+            summary,
+            whatWentWell: template.successWell,
+            whatWentWrong: [],
+            decisions: template.successDecisions,
+            followUps: template.successFollowUps,
+        };
+    }
+    return {
+        domain,
+        summary,
+        whatWentWell: [],
+        whatWentWrong: [errorMessage],
+        decisions: [
+            isSentinel
+                ? "Sentinel: resolve decision to unblock dependency handoffs before retrying this run."
+                : template.failureDecision,
+        ],
+        followUps: [
+            {
+                title: template.failureFollowUpTitle,
+                priority: "p0",
+                reason: domain === "general"
+                    ? errorMessage
+                    : `${template.failureFollowUpReason} Error: ${errorMessage}`,
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// LLM-powered retro generation (falls back to heuristic template above)
+// ---------------------------------------------------------------------------
+const RETRO_SYSTEM_PROMPT = `You generate structured retrospectives for autonomous agent runs. Given the run context, produce a JSON object with these fields: domain (one of: engineering, product, design, marketing, sales, operations, orchestration, general), summary (1 sentence), whatWentWell (1-3 specific items), whatWentWrong (0-3 items, empty if success), decisions (1-2 actionable items), followUps (0-2 items, each with title, priority p0/p1/p2, and reason). Be specific to what actually happened — avoid generic template language.`;
+const VALID_DOMAINS = new Set([
+    "engineering",
+    "product",
+    "design",
+    "marketing",
+    "sales",
+    "operations",
+    "orchestration",
+    "general",
+]);
+const VALID_PRIORITIES = new Set(["p0", "p1", "p2"]);
+/**
+ * Generate a structured retro using an LLM, falling back to the heuristic
+ * template produced by {@link buildRetroTemplateForAgent}.
+ *
+ * Caller: src/index.ts (~line 971) — `buildRetroTemplateForAgent` is invoked
+ * inside the session-stopped handler. Migrate that call site to use this
+ * function when ready to enable LLM-powered retros.
+ */
+export async function buildRetroWithLlm(input) {
+    const lines = [
+        `Agent ID: ${input.agentId ?? "(unknown)"}`,
+        `Outcome: ${input.success ? "success" : "failure"}`,
+        `Task ID: ${input.taskId ?? "(none)"}`,
+        `Run ID: ${input.runId}`,
+    ];
+    if (input.errorMessage) {
+        lines.push(`Error: ${input.errorMessage}`);
+    }
+    if (input.executionContext) {
+        lines.push(`Execution context: ${input.executionContext}`);
+    }
+    const userPrompt = lines.join("\n");
+    function parseRetroJson(raw) {
+        try {
+            const obj = JSON.parse(raw);
+            if (typeof obj.domain !== "string" || !VALID_DOMAINS.has(obj.domain))
+                return null;
+            if (typeof obj.summary !== "string" || obj.summary.length === 0)
+                return null;
+            if (!Array.isArray(obj.whatWentWell) || !obj.whatWentWell.every((v) => typeof v === "string"))
+                return null;
+            if (!Array.isArray(obj.whatWentWrong) || !obj.whatWentWrong.every((v) => typeof v === "string"))
+                return null;
+            if (!Array.isArray(obj.decisions) || !obj.decisions.every((v) => typeof v === "string"))
+                return null;
+            if (!Array.isArray(obj.followUps))
+                return null;
+            const followUps = [];
+            for (const fu of obj.followUps) {
+                if (!fu || typeof fu !== "object")
+                    return null;
+                const rec = fu;
+                if (typeof rec.title !== "string" || rec.title.length === 0)
+                    return null;
+                const entry = { title: rec.title };
+                if (typeof rec.priority === "string" && VALID_PRIORITIES.has(rec.priority)) {
+                    entry.priority = rec.priority;
+                }
+                if (typeof rec.reason === "string") {
+                    entry.reason = rec.reason;
+                }
+                followUps.push(entry);
+            }
+            return {
+                domain: obj.domain,
+                summary: obj.summary,
+                whatWentWell: obj.whatWentWell,
+                whatWentWrong: obj.whatWentWrong,
+                decisions: obj.decisions,
+                followUps,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    function heuristicFallback() {
+        return buildRetroTemplateForAgent(input);
+    }
+    const response = await callLlmJson({
+        taskId: "retro",
+        systemPrompt: RETRO_SYSTEM_PROMPT,
+        userPrompt,
+        model: "openai/gpt-4.1-mini",
+        maxTokens: 512,
+        temperature: 0.2,
+        cacheTtlMs: 6 * 60 * 60_000, // 6 hours
+    }, parseRetroJson, heuristicFallback);
+    return {
+        ...response.result,
+        source: response.source,
+    };
+}

package/dist/retro/quality-rubric.d.ts

@@ -0,0 +1,33 @@
+import type { OrgxAgentDomain } from "../contracts/types.js";
+export type RetroQualityRubricInput = {
+    success: boolean;
+    hadError: boolean;
+    errorMessage?: string | null;
+    tokens?: number | null;
+    costUsd?: number | null;
+    decisionsCount?: number;
+    followUpsCount?: number;
+    whatWentWrongCount?: number;
+    /** Agent domain for domain-specific scoring modifiers */
+    domain?: OrgxAgentDomain | null;
+    /** Artifact metadata from the registered atomic unit */
+    artifactMetadata?: Record<string, unknown> | null;
+};
+export type RetroQualityRubricResult = {
+    score: number;
+    reasons: string[];
+};
+/**
+ * Compute domain-specific quality modifier based on artifact metadata.
+ * Returns delta (positive = bonus, negative = penalty) and reasons.
+ */
+export declare function computeDomainQualityModifier(domain: OrgxAgentDomain | null | undefined, artifactMetadata: Record<string, unknown> | null | undefined): {
+    delta: number;
+    reasons: string[];
+};
+export declare function computeRetroQualityRubricScore(input: RetroQualityRubricInput): RetroQualityRubricResult;
+export declare function computeRetroQualityWithLlm(input: RetroQualityRubricInput & {
+    executionContext?: string | null;
+}): Promise<RetroQualityRubricResult & {
+    source: "llm" | "heuristic";
+}>;