@voybio/ace-swarm 2.4.4 → 2.4.6

package/dist/orchestrator-supervisor.js

@@ -116,7 +116,7 @@ export function markTaskStepStatus(plan, stepId, status, patch = {}) {
 export function applyBridgeResultToStep(plan, stepId, result) {
     const nextStatus = result.status === "completed"
         ? "done"
-        : result.status === "needs_input" || result.status === "max_turns"
+        : result.status === "needs_input" || result.status === "max_turns" || result.status === "blocked"
             ? "blocked"
             : "failed";
     return withDerivedStatus({

package/dist/plan-proposal.d.ts

@@ -9,6 +9,13 @@ export interface ContractArtifactExpectation {
     path: string;
     required?: boolean;
     evidence_ref_kind?: "artifact" | "diff" | "hash" | "test" | "gate";
+    /**
+     * True when the deterministic scaffold invented this path to satisfy
+     * `validatePlan`'s `contract_artifacts` rule, rather than a planner naming
+     * evidence it commits to producing. Scaffolded expectations must never become
+     * success-contract obligations — see `compileSuccessContract` in goal-engine.ts.
+     */
+    scaffolded?: boolean;
 }
 export interface PlanProposalStep {
     role: string;

package/dist/plan-proposal.js

@@ -50,17 +50,31 @@ function enrichContractStep(step) {
             (inferExpectedOutputClass(step) === "structural_edit_plan" ? true : undefined),
     };
 }
+/**
+ * Placeholder evidence for the deterministic scaffold. `validatePlan`'s
+ * `contract_artifacts` rule requires every code/structural step to name its
+ * evidence before execution, and that rule backs the fallback planner behind
+ * `run_orchestrator` — returning `undefined` here makes ACE emit plans its own
+ * validator rejects.
+ *
+ * The scaffold cannot know what a step will produce, so every path it invents is
+ * marked `scaffolded`. That flag is what keeps them out of the success contract:
+ * a fixed, workspace-shared path like `agent-state/SPEC_CONTRACT.json` is checked
+ * with `existsSync`, so once any goal writes it, a later goal's contract would be
+ * satisfied by a file that goal never touched. See F1 in
+ * REVIEW_MITIGATIONS_CLOSEOUT_2026-07-10.md.
+ */
 function scaffoldArtifactExpectations(step) {
     const expected = inferExpectedOutputClass(step);
     if (expected !== "code_artifact" && expected !== "structural_edit_plan")
         return undefined;
     if (step.role === "spec") {
-        return [{ path: "agent-state/SPEC_CONTRACT.json", required: false, evidence_ref_kind: "artifact" }];
+        return [{ path: "agent-state/SPEC_CONTRACT.json", required: false, evidence_ref_kind: "artifact", scaffolded: true }];
     }
     if (step.role === "docs") {
-        return [{ path: "agent-state", required: false, evidence_ref_kind: "artifact" }];
+        return [{ path: "agent-state", required: false, evidence_ref_kind: "artifact", scaffolded: true }];
     }
-    return [{ path: "workspace-artifact", required: false, evidence_ref_kind: "artifact" }];
+    return [{ path: "workspace-artifact", required: false, evidence_ref_kind: "artifact", scaffolded: true }];
 }
 function isCodeMutatingStep(step) {
     if (step.role === "coders" || step.role === "builder" || step.role === "astgrep")
@@ -481,7 +495,12 @@ function compileGoalScaffold(task, plan_id) {
             ? "implementation"
             : rawKind;
         const role = roleForClauseKind(kind);
-        const stepId = `goal-${role}-${index + 1}`;
+        // Namespaced by position, not by role: `goal-${role}-${index+1}` collides with
+        // the ship-boundary phase ids below (a `release` clause at index 0 produced
+        // `goal-release-1`, the same id as the Phase 7 release step). `publicStepLabels`
+        // is keyed by id, so the later push silently re-pointed this step's dependants
+        // at the wrong label and closed a cycle in the plan DAG.
+        const stepId = `goal-exec-${index + 1}`;
         const dependency = index === 0 ? specId : executionStepIds[index - 1];
         scaffoldSteps.push({
             id: stepId,
@@ -626,6 +645,15 @@ function compileGoalScaffold(task, plan_id) {
             }),
         });
     }
+    // Ids are the only key `publicStepLabels` has; a duplicate silently rewrites a
+    // dependency to point at the wrong step, which is how the ship-boundary scaffold
+    // grew a cycle. Fail loudly here rather than emit an unrunnable plan.
+    const duplicateIds = scaffoldSteps
+        .map((step) => step.id)
+        .filter((id, index, all) => all.indexOf(id) !== index);
+    if (duplicateIds.length > 0) {
+        throw new Error(`compileGoalScaffold produced duplicate step ids: ${[...new Set(duplicateIds)].join(", ")}`);
+    }
     const publicStepLabels = new Map();
     scaffoldSteps.forEach((step, index) => {
         publicStepLabels.set(step.id, `step-${index + 1}`);
@@ -806,6 +834,48 @@ function validatePlanShape(plan_id, proposal) {
             softFindings.push(`stop_conditions: step(s) ${missingStopConditions.join(", ")} have no stop conditions`);
         }
     }
+    // 5b. The step graph must be a DAG over known labels. A dangling or cyclic
+    // `depends_on` yields a plan where some step is never ready, and the goal engine
+    // reads "no ready step" as "waiting on external state" and backs off forever.
+    {
+        const labels = proposal.steps.map((_, index) => `step-${index + 1}`);
+        const indexByLabel = new Map(labels.map((label, index) => [label, index]));
+        const unknown = [];
+        for (const [index, step] of proposal.steps.entries()) {
+            for (const dependency of step.depends_on ?? []) {
+                if (!indexByLabel.has(dependency))
+                    unknown.push(`${labels[index]}→${dependency}`);
+            }
+        }
+        if (unknown.length > 0) {
+            blockingFindings.push(`plan_dag: step(s) depend on unknown labels ${unknown.join(", ")}`);
+        }
+        // Iterative Kahn's algorithm; any step left with unresolved deps sits on a cycle.
+        const resolved = new Set();
+        for (let pass = 0; pass < proposal.steps.length; pass += 1) {
+            let advanced = false;
+            for (const [index, step] of proposal.steps.entries()) {
+                if (resolved.has(index))
+                    continue;
+                const ready = (step.depends_on ?? []).every((dependency) => {
+                    const target = indexByLabel.get(dependency);
+                    return target === undefined || resolved.has(target);
+                });
+                if (ready) {
+                    resolved.add(index);
+                    advanced = true;
+                }
+            }
+            if (!advanced)
+                break;
+        }
+        const cyclic = labels.filter((_, index) => !resolved.has(index));
+        if (cyclic.length > 0) {
+            blockingFindings.push(`plan_dag: dependency cycle among step(s) ${cyclic.join(", ")}`);
+        }
+        // Deliberately does not touch `passingChecks`: `score` is `passingChecks / 6`,
+        // and a structural invariant is not a quality point.
+    }
     // 6. Contract-class artifact expectations: code and structural edits must say
     // what artifact evidence can prove them before execution.
     {

package/dist/playbook-adaptation.d.ts

@@ -0,0 +1,37 @@
+import { type EvalRunner, type ModelScorecard } from "./eval-harness.js";
+export interface AdaptationReport {
+    model: string;
+    generated_at: string;
+    epochs: number;
+    baseline: ModelScorecard;
+    adapted: ModelScorecard;
+    /** One scorecard per epoch, each measured against the playbook as of that epoch. */
+    epoch_scorecards: ModelScorecard[];
+    band_deltas: Array<{
+        band: string;
+        baseline_passed: number;
+        baseline_total: number;
+        adapted_passed: number;
+        adapted_total: number;
+        delta: number;
+    }>;
+    playbook_stats: {
+        added: number;
+        merged: number;
+        tagged: number;
+        quarantined: number;
+        pruned: number;
+    };
+    report_path: string;
+}
+export interface RunAdaptationCycleInput {
+    model: string;
+    batteryPath: string;
+    workspaceRoot: string;
+    epochs?: number;
+    modelClass?: string;
+    runner?: EvalRunner;
+    outputDir?: string;
+}
+export declare function runAdaptationCycle(input: RunAdaptationCycleInput): Promise<AdaptationReport>;
+//# sourceMappingURL=playbook-adaptation.d.ts.map

package/dist/playbook-adaptation.js

@@ -0,0 +1,159 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readBridgeTrace } from "./bridge-trace.js";
+import { loadBattery, makeLiveRunner, runBattery, scorecardToMarkdown, } from "./eval-harness.js";
+import { reflectDeterministic } from "./experience-reflector.js";
+import { curate } from "./playbook-curator.js";
+import { PlaybookRepository } from "./store/repositories/playbook-repository.js";
+function roleForTask(task) {
+    if (task.band === "orchestrated")
+        return "orchestrator";
+    return "coders";
+}
+function withEnvs(vars, fn) {
+    const previous = new Map(Object.keys(vars).map((k) => [k, process.env[k]]));
+    Object.assign(process.env, vars);
+    return fn().finally(() => {
+        for (const [k, v] of previous) {
+            if (v === undefined)
+                delete process.env[k];
+            else
+                process.env[k] = v;
+        }
+    });
+}
+// Every measured run has implicit per-run curation disabled: the harness's own
+// reflect loop is the sole writer, so `playbook_stats` is exact and the baseline
+// is a real control. See local-model-runtime.ts `reflectRunIntoPlaybook`.
+const MEASURE_OFF = { ACE_PLAYBOOK: "0", ACE_PLAYBOOK_REFLECT: "0" };
+const MEASURE_ON = { ACE_PLAYBOOK: "1", ACE_PLAYBOOK_REFLECT: "0" };
+function captureRunner(runner, sink) {
+    return async (task, model, workspaceRoot) => {
+        const outcome = await runner(task, model, workspaceRoot);
+        sink.set(task.id, outcome);
+        return outcome;
+    };
+}
+function bandDeltas(baseline, adapted) {
+    const bands = [...new Set([...baseline.tasks.map((t) => t.band), ...adapted.tasks.map((t) => t.band)])].sort();
+    return bands.map((band) => {
+        const before = baseline.tasks.filter((task) => task.band === band);
+        const after = adapted.tasks.filter((task) => task.band === band);
+        const baselinePassed = before.filter((task) => task.success).length;
+        const adaptedPassed = after.filter((task) => task.success).length;
+        return {
+            band,
+            baseline_passed: baselinePassed,
+            baseline_total: before.length,
+            adapted_passed: adaptedPassed,
+            adapted_total: after.length,
+            delta: adaptedPassed - baselinePassed,
+        };
+    });
+}
+function renderAdaptationMarkdown(report) {
+    return [
+        `# Playbook Adaptation Report — ${report.model}`,
+        "",
+        `- generated: ${report.generated_at}`,
+        `- epochs: ${report.epochs}`,
+        `- baseline: ${report.baseline.summary.passed}/${report.baseline.summary.total} (${(report.baseline.summary.success_rate * 100).toFixed(1)}%)`,
+        `- adapted: ${report.adapted.summary.passed}/${report.adapted.summary.total} (${(report.adapted.summary.success_rate * 100).toFixed(1)}%)`,
+        `- playbook: added=${report.playbook_stats.added} merged=${report.playbook_stats.merged} tagged=${report.playbook_stats.tagged} quarantined=${report.playbook_stats.quarantined} pruned=${report.playbook_stats.pruned}`,
+        "",
+        "## Epochs",
+        "",
+        "| epoch | passed | total | success rate |",
+        "| --- | ---: | ---: | ---: |",
+        `| baseline | ${report.baseline.summary.passed} | ${report.baseline.summary.total} | ${(report.baseline.summary.success_rate * 100).toFixed(1)}% |`,
+        ...report.epoch_scorecards.map((card, index) => `| ${index + 1} | ${card.summary.passed} | ${card.summary.total} | ${(card.summary.success_rate * 100).toFixed(1)}% |`),
+        "",
+        "## Band Deltas",
+        "",
+        "| band | baseline | adapted | delta |",
+        "| --- | ---: | ---: | ---: |",
+        ...report.band_deltas.map((row) => `| ${row.band} | ${row.baseline_passed}/${row.baseline_total} | ${row.adapted_passed}/${row.adapted_total} | ${row.delta} |`),
+        "",
+        "## Baseline",
+        "",
+        scorecardToMarkdown(report.baseline).trimEnd(),
+        "",
+        "## Adapted",
+        "",
+        scorecardToMarkdown(report.adapted).trimEnd(),
+        "",
+    ].join("\n");
+}
+export async function runAdaptationCycle(input) {
+    const battery = loadBattery(input.batteryPath);
+    const epochs = Math.max(1, Math.min(input.epochs ?? 1, 3));
+    const runner = input.runner ?? makeLiveRunner(input.workspaceRoot);
+    const baselineOutcomes = new Map();
+    const baseline = await withEnvs(MEASURE_OFF, () => runBattery({
+        battery,
+        model: input.model,
+        runner: captureRunner(runner, baselineOutcomes),
+        workspaceRoot: input.workspaceRoot,
+    }));
+    const repo = new PlaybookRepository(input.workspaceRoot);
+    const stats = { added: 0, merged: 0, tagged: 0, quarantined: 0, pruned: 0 };
+    const epochScorecards = [];
+    let current = baseline;
+    let currentOutcomes = baselineOutcomes;
+    for (let epoch = 0; epoch < epochs; epoch += 1) {
+        // 1. Learn from the most recent run's failures and traps.
+        for (const score of current.tasks.filter((s) => !s.success || s.trap)) {
+            const task = battery.tasks.find((candidate) => candidate.id === score.task_id);
+            const outcome = currentOutcomes.get(score.task_id);
+            if (!task || !outcome)
+                continue;
+            const trace = outcome.trace.length > 0
+                ? outcome.trace
+                : readBridgeTrace(input.workspaceRoot, outcome.result.bridge_id);
+            const ops = reflectDeterministic({
+                trace,
+                result: outcome.result,
+                role: roleForTask(task),
+                model: input.model,
+                modelClass: input.modelClass ?? "small_local",
+            });
+            const cur = await curate(repo, ops, { workspaceRoot: input.workspaceRoot });
+            stats.added += cur.added;
+            stats.merged += cur.merged;
+            stats.tagged += cur.tagged;
+            stats.quarantined += cur.quarantined;
+            stats.pruned += cur.pruned;
+        }
+        // 2. Re-measure against the updated playbook. This is what makes an epoch an
+        //    epoch: without it, `--epochs N` just re-reflects one cached trace N times
+        //    and silently biases pruneOverflow's utility sort via observed_count.
+        const epochOutcomes = new Map();
+        current = await withEnvs(MEASURE_ON, () => runBattery({
+            battery,
+            model: input.model,
+            runner: captureRunner(runner, epochOutcomes),
+            workspaceRoot: input.workspaceRoot,
+        }));
+        currentOutcomes = epochOutcomes;
+        epochScorecards.push(current);
+    }
+    const adapted = current;
+    const generated = new Date().toISOString();
+    const reportBase = {
+        model: input.model,
+        generated_at: generated,
+        epochs,
+        baseline,
+        adapted,
+        epoch_scorecards: epochScorecards,
+        band_deltas: bandDeltas(baseline, adapted),
+        playbook_stats: stats,
+    };
+    const outDir = input.outputDir ?? join(input.workspaceRoot, "agent-state", "eval");
+    mkdirSync(outDir, { recursive: true });
+    const safeModel = input.model.replace(/[^a-zA-Z0-9_.-]/g, "_");
+    const path = join(outDir, `adaptation-${safeModel}-${generated.replace(/[:.]/g, "-")}.md`);
+    writeFileSync(path, renderAdaptationMarkdown(reportBase));
+    return { ...reportBase, report_path: path };
+}
+//# sourceMappingURL=playbook-adaptation.js.map

package/dist/playbook-curator.d.ts

@@ -0,0 +1,16 @@
+import type { PlaybookConfig, PlaybookDeltaOp, PlaybookRepository } from "./store/repositories/playbook-repository.js";
+export interface CuratorConfig extends PlaybookConfig {
+    dedup_jaccard?: number;
+    quarantine_harmful_min?: number;
+    quarantine_retire_after_days?: number;
+    workspaceRoot?: string;
+}
+export interface CurateResult {
+    added: number;
+    merged: number;
+    tagged: number;
+    quarantined: number;
+    pruned: number;
+}
+export declare function curate(repo: PlaybookRepository, ops: PlaybookDeltaOp[], config?: CuratorConfig): Promise<CurateResult>;
+//# sourceMappingURL=playbook-curator.d.ts.map

package/dist/playbook-curator.js

@@ -0,0 +1,106 @@
+import { calculateJaccard, getShingles } from "./semantic-hash.js";
+import { appendStatusEventSafe } from "./status-events.js";
+function scopeEqualOrBroader(candidate, incoming) {
+    return Object.entries(candidate).every(([key, value]) => value === undefined || incoming[key] === value);
+}
+function mergeEvidence(a, b) {
+    return [...new Set([...a, ...b])].slice(0, 5);
+}
+function applyLifecycle(bullet, config, now = new Date()) {
+    let next = bullet;
+    let quarantined = false;
+    const harmfulMin = config.quarantine_harmful_min ?? 3;
+    if (next.status === "active" && next.harmful_count >= harmfulMin && next.harmful_count > next.helpful_count) {
+        next = { ...next, status: "quarantined" };
+        quarantined = true;
+    }
+    if (next.status === "quarantined" && config.quarantine_retire_after_days !== undefined) {
+        const ageMs = now.getTime() - new Date(next.updated_at).getTime();
+        if (ageMs >= config.quarantine_retire_after_days * 24 * 60 * 60 * 1000) {
+            next = { ...next, status: "retired" };
+        }
+    }
+    return { bullet: next, quarantined };
+}
+export async function curate(repo, ops, config = {}) {
+    const result = { added: 0, merged: 0, tagged: 0, quarantined: 0, pruned: 0 };
+    const threshold = config.dedup_jaccard ?? 0.85;
+    for (const op of ops) {
+        if (op.type === "TAG") {
+            const bullet = repo.getBullet(op.bullet_id);
+            if (!bullet)
+                continue;
+            const applied = applyLifecycle({
+                ...bullet,
+                helpful_count: bullet.helpful_count + (op.tag === "helpful" ? 1 : 0),
+                harmful_count: bullet.harmful_count + (op.tag === "harmful" ? 1 : 0),
+            }, config);
+            repo.saveBullet(applied.bullet);
+            result.tagged += 1;
+            if (applied.quarantined)
+                result.quarantined += 1;
+            continue;
+        }
+        const incomingShingles = getShingles(op.content, 3);
+        const match = repo
+            .listBullets({ section: op.section, status: "active" })
+            .filter((bullet) => scopeEqualOrBroader(bullet.scope, op.scope))
+            .map((bullet) => ({
+            bullet,
+            score: calculateJaccard(getShingles(bullet.content, 3), incomingShingles),
+        }))
+            .sort((a, b) => b.score - a.score)[0];
+        if (match && match.score >= threshold) {
+            repo.saveBullet({
+                ...match.bullet,
+                observed_count: match.bullet.observed_count + 1,
+                evidence_refs: mergeEvidence(match.bullet.evidence_refs, op.evidence_refs),
+            });
+            result.merged += 1;
+        }
+        else {
+            const add = repo.applyDeltaOps([op], {
+                ...config,
+                max_active_total: Number.MAX_SAFE_INTEGER,
+                max_active_per_section: Number.MAX_SAFE_INTEGER,
+            });
+            result.added += add.added;
+        }
+    }
+    result.pruned += pruneOverflow(repo, config);
+    const eventWorkspaceRoot = config.workspaceRoot ?? repo.root;
+    await appendStatusEventSafe({
+        event_type: "PLAYBOOK_CURATED",
+        source_module: "capability-build",
+        status: "done",
+        summary: `Playbook curated: added=${result.added} merged=${result.merged} tagged=${result.tagged} quarantined=${result.quarantined} pruned=${result.pruned}`,
+        payload: { ...result },
+    }, eventWorkspaceRoot ? { workspaceRoot: eventWorkspaceRoot } : {});
+    return result;
+}
+function pruneOverflow(repo, config) {
+    const maxTotal = config.max_active_total ?? 200;
+    const maxPerSection = config.max_active_per_section ?? 64;
+    const active = repo.listBullets({ status: "active" });
+    const toRetire = new Set();
+    const utilitySort = (a, b) => (a.helpful_count - a.harmful_count) - (b.helpful_count - b.harmful_count) ||
+        a.observed_count - b.observed_count ||
+        (a.updated_at < b.updated_at ? -1 : 1);
+    for (const section of ["strategies", "tool_usage", "failure_modes", "verification", "env_facts"]) {
+        const sectionActive = active.filter((bullet) => bullet.section === section).sort(utilitySort);
+        for (const bullet of sectionActive.slice(0, Math.max(0, sectionActive.length - maxPerSection))) {
+            toRetire.add(bullet.bullet_id);
+        }
+    }
+    const remaining = active.filter((bullet) => !toRetire.has(bullet.bullet_id)).sort(utilitySort);
+    for (const bullet of remaining.slice(0, Math.max(0, remaining.length - maxTotal))) {
+        toRetire.add(bullet.bullet_id);
+    }
+    for (const bulletId of toRetire) {
+        const bullet = repo.getBullet(bulletId);
+        if (bullet)
+            repo.saveBullet({ ...bullet, status: "retired" });
+    }
+    return toRetire.size;
+}
+//# sourceMappingURL=playbook-curator.js.map

package/dist/playbook-llm-reflector.d.ts

@@ -0,0 +1,26 @@
+import { type RunLocalModelTaskOptions } from "./local-model-runtime.js";
+import type { BridgeResult } from "./model-bridge.js";
+import { type PlaybookDeltaOp } from "./store/repositories/playbook-repository.js";
+import { type JobHandler } from "./job-worker.js";
+export declare const PLAYBOOK_DELTA_JSON_SCHEMA: Record<string, unknown>;
+export interface PlaybookReflectPayload {
+    run_id: string;
+    role: string;
+    model: string;
+    model_class: string;
+    result?: BridgeResult;
+    max_ops_per_run?: number;
+}
+export declare function validateLlmDeltaOps(input: {
+    parsed: unknown;
+    payload: PlaybookReflectPayload;
+    maxOpsPerRun?: number;
+}): PlaybookDeltaOp[];
+export declare function createPlaybookReflectJobHandler(options: {
+    workspaceRoot: string;
+    runTask?: (options: RunLocalModelTaskOptions) => Promise<{
+        result: BridgeResult;
+    }>;
+}): JobHandler;
+export declare function registerPlaybookReflectJobHandler(workspaceRoot: string): void;
+//# sourceMappingURL=playbook-llm-reflector.d.ts.map

package/dist/playbook-llm-reflector.js

@@ -0,0 +1,157 @@
+import { readBridgeTrace } from "./bridge-trace.js";
+import { appendStatusEventSafe } from "./status-events.js";
+import { curate } from "./playbook-curator.js";
+import { runLocalModelTask } from "./local-model-runtime.js";
+import { PlaybookRepository, } from "./store/repositories/playbook-repository.js";
+import { registerJobHandler, } from "./job-worker.js";
+export const PLAYBOOK_DELTA_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        reasoning: { type: "string" },
+        operations: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    type: { type: "string", enum: ["ADD"] },
+                    section: {
+                        type: "string",
+                        enum: ["strategies", "tool_usage", "failure_modes", "verification", "env_facts"],
+                    },
+                    content: { type: "string", maxLength: 400 },
+                },
+                required: ["type", "section", "content"],
+            },
+        },
+    },
+    required: ["operations"],
+};
+const PLAYBOOK_SECTIONS = new Set([
+    "strategies",
+    "tool_usage",
+    "failure_modes",
+    "verification",
+    "env_facts",
+]);
+function parsePayload(value) {
+    const runId = typeof value.run_id === "string" ? value.run_id.trim() : "";
+    const role = typeof value.role === "string" ? value.role.trim() : "";
+    const model = typeof value.model === "string" ? value.model.trim() : "";
+    const modelClass = typeof value.model_class === "string" ? value.model_class.trim() : "";
+    if (!runId || !role || !model || !modelClass) {
+        throw new Error("playbook.reflect requires run_id, role, model, and model_class.");
+    }
+    return {
+        run_id: runId,
+        role,
+        model,
+        model_class: modelClass,
+        result: value.result && typeof value.result === "object" ? value.result : undefined,
+        max_ops_per_run: typeof value.max_ops_per_run === "number" && Number.isFinite(value.max_ops_per_run)
+            ? Math.max(0, Math.floor(value.max_ops_per_run))
+            : 3,
+    };
+}
+function hasExecutionEvidence(trace, result) {
+    return trace.some((line) => (line.tool_calls ?? []).length > 0) || Boolean(result?.reason_code);
+}
+function parseReflectorJson(text) {
+    const trimmed = text.trim();
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start === -1 || end < start)
+        throw new Error("reflector output did not contain JSON.");
+    return JSON.parse(trimmed.slice(start, end + 1));
+}
+export function validateLlmDeltaOps(input) {
+    const record = input.parsed && typeof input.parsed === "object" ? input.parsed : {};
+    const operations = Array.isArray(record.operations) ? record.operations : [];
+    const max = input.maxOpsPerRun ?? input.payload.max_ops_per_run ?? 3;
+    const ops = [];
+    for (const raw of operations) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const op = raw;
+        if (op.type !== "ADD")
+            continue;
+        if (typeof op.section !== "string" || !PLAYBOOK_SECTIONS.has(op.section))
+            continue;
+        const content = typeof op.content === "string" ? op.content.replace(/\s+/g, " ").trim() : "";
+        if (!content || content.length > 400)
+            continue;
+        ops.push({
+            type: "ADD",
+            section: op.section,
+            scope: { role: input.payload.role, model_class: input.payload.model_class, model: input.payload.model },
+            content,
+            evidence_refs: [`agent-state/bridge-traces/${input.payload.run_id}.ndjson`],
+            provenance: { source: "llm_reflector", run_id: input.payload.run_id },
+        });
+        if (ops.length >= max)
+            break;
+    }
+    return ops;
+}
+function buildReflectorPrompt(payload, traceLines) {
+    return [
+        "Reflect on this ACE run and propose only durable playbook ADD operations.",
+        "Return JSON only with shape: {\"reasoning\":\"short\",\"operations\":[{\"type\":\"ADD\",\"section\":\"verification\",\"content\":\"...\"}]}",
+        "Do not alter gates, contracts, files, or source. Content must be imperative and <=400 chars.",
+        "",
+        `run_id: ${payload.run_id}`,
+        `role: ${payload.role}`,
+        `model: ${payload.model}`,
+        `model_class: ${payload.model_class}`,
+        "",
+        "result:",
+        JSON.stringify(payload.result ?? {}, null, 2),
+        "",
+        "trace:",
+        JSON.stringify(traceLines.slice(-8), null, 2),
+    ].join("\n");
+}
+export function createPlaybookReflectJobHandler(options) {
+    return async ({ job }) => {
+        let payload;
+        try {
+            payload = parsePayload(job.payload ?? {});
+            const trace = readBridgeTrace(options.workspaceRoot, payload.run_id);
+            if (!hasExecutionEvidence(trace, payload.result)) {
+                return { success: true, evidence_ref: `agent-state/bridge-traces/${payload.run_id}.ndjson` };
+            }
+            const runTask = options.runTask ?? runLocalModelTask;
+            const reflection = await runTask({
+                task: buildReflectorPrompt(payload, trace),
+                role: "qa",
+                workspaceRoot: options.workspaceRoot,
+                model: payload.model,
+                modelClass: payload.model_class,
+                maxTurns: 1,
+                toolScope: [],
+            });
+            const parsed = parseReflectorJson(reflection.result.summary);
+            const ops = validateLlmDeltaOps({ parsed, payload });
+            if (ops.length > 0) {
+                await curate(new PlaybookRepository(options.workspaceRoot), ops);
+            }
+            return { success: true, evidence_ref: `agent-state/bridge-traces/${payload.run_id}.ndjson` };
+        }
+        catch (error) {
+            await appendStatusEventSafe({
+                source_module: "capability-build",
+                event_type: "PLAYBOOK_REFLECT_FAILED",
+                status: "fail",
+                summary: `LLM playbook reflector failed: ${error instanceof Error ? error.message : String(error)}`,
+                payload: {
+                    job_id: job.job_id,
+                    kind: job.kind,
+                },
+            }).catch(() => undefined);
+            return { success: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    };
+}
+export function registerPlaybookReflectJobHandler(workspaceRoot) {
+    registerJobHandler("playbook.reflect", createPlaybookReflectJobHandler({ workspaceRoot }));
+}
+//# sourceMappingURL=playbook-llm-reflector.js.map

package/dist/public-surface.d.ts

@@ -21,6 +21,8 @@ export interface PublicSurfaceAuditResult {
     surfaces: PublicSurfaceEntry[];
     emitted_events: string[];
     report_path: string;
+    artifact_path: string;
+    written_path?: string;
 }
 export declare function auditPublicSurface(options?: {
     write_artifact?: boolean;