@renseiai/agentfactory 0.8.12 → 0.8.14

package/dist/src/merge-queue/strategies/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Merge Strategy Types
+ *
+ * Pluggable interface for merge strategies (rebase, merge, squash).
+ * Each strategy encapsulates how a PR branch is integrated into the target branch.
+ */
+/** Context passed to every merge strategy operation */
+export interface MergeContext {
+    /** Path to the bare repository */
+    repoPath: string;
+    /** Path to the worktree used for merge operations */
+    worktreePath: string;
+    /** Branch being merged (PR branch) */
+    sourceBranch: string;
+    /** Branch being merged into (e.g. main) */
+    targetBranch: string;
+    /** Pull request number */
+    prNumber: number;
+    /** Git remote name (default 'origin') */
+    remote: string;
+}
+/** Result of the prepare step */
+export interface PrepareResult {
+    /** Whether preparation succeeded */
+    success: boolean;
+    /** Error message if preparation failed */
+    error?: string;
+    /** HEAD SHA after preparation */
+    headSha?: string;
+}
+/** Result of the execute (merge) step */
+export interface MergeResult {
+    /** Outcome of the merge attempt */
+    status: 'success' | 'conflict' | 'error';
+    /** SHA of the merge result commit */
+    mergedSha?: string;
+    /** List of files with conflicts (when status is 'conflict') */
+    conflictFiles?: string[];
+    /** Human-readable conflict details */
+    conflictDetails?: string;
+    /** Error message (when status is 'error') */
+    error?: string;
+}
+/**
+ * Pluggable merge strategy interface.
+ *
+ * Lifecycle:
+ *   1. prepare() — fetch latest refs and check out the working branch
+ *   2. execute() — perform the merge/rebase/squash operation
+ *   3. finalize() — push the result to the remote
+ */
+export interface MergeStrategy {
+    /** Strategy identifier */
+    readonly name: 'rebase' | 'merge' | 'squash';
+    /** Fetch latest refs and check out the working branch */
+    prepare(ctx: MergeContext): Promise<PrepareResult>;
+    /** Perform the merge operation */
+    execute(ctx: MergeContext): Promise<MergeResult>;
+    /** Push the result to the remote */
+    finalize(ctx: MergeContext): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/merge-queue/strategies/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/merge-queue/strategies/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAA;IACpB,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAA;IACpB,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAA;CACf;AAED,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,mCAAmC;IACnC,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,CAAA;IACxC,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,sCAAsC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;IAC5C,yDAAyD;IACzD,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAClD,kCAAkC;IAClC,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAChD,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3C"}

package/dist/src/merge-queue/strategies/types.js

@@ -0,0 +1,7 @@
+/**
+ * Merge Strategy Types
+ *
+ * Pluggable interface for merge strategies (rebase, merge, squash).
+ * Each strategy encapsulates how a PR branch is integrated into the target branch.
+ */
+export {};

package/dist/src/orchestrator/completion-contracts.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Completion Contracts
+ *
+ * Typed definitions of what each work type must produce before a session
+ * is considered successful. The orchestrator validates these after the
+ * agent session ends and runs deterministic backstop actions for any
+ * missing fields that can be recovered programmatically.
+ *
+ * Design principles:
+ * - Contracts are provider-agnostic (same expectations regardless of LLM)
+ * - Fields marked `backstopCapable` can be filled by deterministic code
+ * - Fields not backstop-capable require agent judgment (flagged for follow-up)
+ * - Contracts drive both validation AND recovery
+ */
+import type { AgentWorkType } from './work-types.js';
+/** A field the agent session should produce */
+export type CompletionFieldType = 'pr_url' | 'branch_pushed' | 'commits_present' | 'work_result' | 'issue_updated' | 'comment_posted' | 'sub_issues_created' | 'pr_merged';
+/** A single required or optional field in a completion contract */
+export interface CompletionField {
+    type: CompletionFieldType;
+    /** Human-readable description for diagnostic messages */
+    label: string;
+    /**
+     * Whether the orchestrator can fill this field deterministically
+     * after the session ends (e.g., push a branch, create a PR).
+     * Fields that require agent judgment (work_result) are NOT backstop-capable.
+     */
+    backstopCapable: boolean;
+}
+export interface CompletionContract {
+    workType: AgentWorkType;
+    /** Fields that MUST be present for the session to be considered complete */
+    required: CompletionField[];
+    /** Fields that SHOULD be present but won't block completion */
+    optional: CompletionField[];
+}
+export interface CompletionValidationResult {
+    /** Whether all required fields are satisfied */
+    satisfied: boolean;
+    /** Required fields that are present */
+    presentFields: CompletionFieldType[];
+    /** Required fields that are missing */
+    missingFields: CompletionFieldType[];
+    /** Missing fields that the backstop can fill deterministically */
+    backstopRecoverable: CompletionFieldType[];
+    /** Missing fields that require agent judgment or manual intervention */
+    manualRequired: CompletionFieldType[];
+}
+/** Structured data extracted from the agent session */
+export interface SessionOutputs {
+    prUrl?: string;
+    branchPushed?: boolean;
+    commitsPresent?: boolean;
+    workResult?: 'passed' | 'failed' | 'unknown';
+    issueUpdated?: boolean;
+    commentPosted?: boolean;
+    subIssuesCreated?: boolean;
+    prMerged?: boolean;
+}
+/** Record of a deterministic action taken by the backstop */
+export interface BackstopAction {
+    field: CompletionFieldType;
+    action: string;
+    success: boolean;
+    detail?: string;
+}
+/** Result of running the backstop */
+export interface BackstopResult {
+    /** Actions the backstop attempted */
+    actions: BackstopAction[];
+    /** Whether all required fields are now satisfied */
+    fullyRecovered: boolean;
+    /** Fields that still need manual intervention */
+    remainingGaps: CompletionFieldType[];
+}
+/**
+ * Get the completion contract for a work type.
+ * Returns undefined for unknown work types (caller should treat as no contract).
+ */
+export declare function getCompletionContract(workType: AgentWorkType): CompletionContract | undefined;
+/**
+ * Validate session outputs against a completion contract.
+ */
+export declare function validateCompletion(contract: CompletionContract, outputs: SessionOutputs): CompletionValidationResult;
+/**
+ * Format missing fields into a human-readable diagnostic message.
+ */
+export declare function formatMissingFields(contract: CompletionContract, validation: CompletionValidationResult): string;
+//# sourceMappingURL=completion-contracts.d.ts.map

package/dist/src/orchestrator/completion-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-contracts.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/completion-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAMpD,+CAA+C;AAC/C,MAAM,MAAM,mBAAmB,GAC3B,QAAQ,GACR,eAAe,GACf,iBAAiB,GACjB,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,oBAAoB,GACpB,WAAW,CAAA;AAEf,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAA;IACzB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAA;CACzB;AAMD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,aAAa,CAAA;IACvB,4EAA4E;IAC5E,QAAQ,EAAE,eAAe,EAAE,CAAA;IAC3B,+DAA+D;IAC/D,QAAQ,EAAE,eAAe,EAAE,CAAA;CAC5B;AAMD,MAAM,WAAW,0BAA0B;IACzC,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAA;IAClB,uCAAuC;IACvC,aAAa,EAAE,mBAAmB,EAAE,CAAA;IACpC,uCAAuC;IACvC,aAAa,EAAE,mBAAmB,EAAE,CAAA;IACpC,kEAAkE;IAClE,mBAAmB,EAAE,mBAAmB,EAAE,CAAA;IAC1C,wEAAwE;IACxE,cAAc,EAAE,mBAAmB,EAAE,CAAA;CACtC;AAMD,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAMD,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,mBAAmB,CAAA;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,oDAAoD;IACpD,cAAc,EAAE,OAAO,CAAA;IACvB,iDAAiD;IACjD,aAAa,EAAE,mBAAmB,EAAE,CAAA;CACrC;AAwID;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,kBAAkB,GAAG,SAAS,CAE7F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,cAAc,GACtB,0BAA0B,CA0B5B;AA4BD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,EAAE,0BAA0B,GACrC,MAAM,CA6BR"}

package/dist/src/orchestrator/completion-contracts.js

@@ -0,0 +1,228 @@
+/**
+ * Completion Contracts
+ *
+ * Typed definitions of what each work type must produce before a session
+ * is considered successful. The orchestrator validates these after the
+ * agent session ends and runs deterministic backstop actions for any
+ * missing fields that can be recovered programmatically.
+ *
+ * Design principles:
+ * - Contracts are provider-agnostic (same expectations regardless of LLM)
+ * - Fields marked `backstopCapable` can be filled by deterministic code
+ * - Fields not backstop-capable require agent judgment (flagged for follow-up)
+ * - Contracts drive both validation AND recovery
+ */
+// ---------------------------------------------------------------------------
+// Shared field definitions (DRY)
+// ---------------------------------------------------------------------------
+const FIELD = {
+    prUrl: {
+        type: 'pr_url',
+        label: 'Pull request URL',
+        backstopCapable: true,
+    },
+    branchPushed: {
+        type: 'branch_pushed',
+        label: 'Branch pushed to remote',
+        backstopCapable: true,
+    },
+    commitsPresent: {
+        type: 'commits_present',
+        label: 'Commits on branch',
+        backstopCapable: false,
+    },
+    workResult: {
+        type: 'work_result',
+        label: 'Structured work result (passed/failed)',
+        backstopCapable: false,
+    },
+    issueUpdated: {
+        type: 'issue_updated',
+        label: 'Issue description updated',
+        backstopCapable: false,
+    },
+    commentPosted: {
+        type: 'comment_posted',
+        label: 'Comment posted to issue',
+        backstopCapable: false,
+    },
+    subIssuesCreated: {
+        type: 'sub_issues_created',
+        label: 'Sub-issues created',
+        backstopCapable: false,
+    },
+    prMerged: {
+        type: 'pr_merged',
+        label: 'Pull request merged',
+        backstopCapable: false,
+    },
+};
+// ---------------------------------------------------------------------------
+// Per-work-type contract definitions
+// ---------------------------------------------------------------------------
+const CONTRACTS = {
+    // --- Code-producing work types ---
+    development: {
+        workType: 'development',
+        required: [FIELD.commitsPresent, FIELD.branchPushed, FIELD.prUrl],
+        optional: [],
+    },
+    inflight: {
+        workType: 'inflight',
+        required: [FIELD.commitsPresent, FIELD.branchPushed, FIELD.prUrl],
+        optional: [],
+    },
+    // --- Result-sensitive work types ---
+    qa: {
+        workType: 'qa',
+        required: [FIELD.workResult, FIELD.commentPosted],
+        optional: [],
+    },
+    'qa-coordination': {
+        workType: 'qa-coordination',
+        required: [FIELD.workResult, FIELD.commentPosted],
+        optional: [],
+    },
+    acceptance: {
+        workType: 'acceptance',
+        required: [FIELD.workResult],
+        optional: [FIELD.prMerged],
+    },
+    'acceptance-coordination': {
+        workType: 'acceptance-coordination',
+        required: [FIELD.workResult],
+        optional: [FIELD.prMerged],
+    },
+    // --- Coordination work types ---
+    coordination: {
+        workType: 'coordination',
+        required: [FIELD.commitsPresent, FIELD.branchPushed, FIELD.prUrl, FIELD.workResult],
+        optional: [],
+    },
+    'inflight-coordination': {
+        workType: 'inflight-coordination',
+        required: [FIELD.commitsPresent, FIELD.branchPushed, FIELD.prUrl, FIELD.workResult],
+        optional: [],
+    },
+    // --- Triage/analysis work types ---
+    refinement: {
+        workType: 'refinement',
+        required: [FIELD.commentPosted],
+        optional: [FIELD.issueUpdated],
+    },
+    'refinement-coordination': {
+        workType: 'refinement-coordination',
+        required: [FIELD.commentPosted],
+        optional: [],
+    },
+    research: {
+        workType: 'research',
+        required: [FIELD.issueUpdated],
+        optional: [FIELD.commentPosted],
+    },
+    // --- Issue creation work types ---
+    'backlog-creation': {
+        workType: 'backlog-creation',
+        required: [FIELD.subIssuesCreated],
+        optional: [FIELD.commentPosted],
+    },
+    // --- Merge work types ---
+    merge: {
+        workType: 'merge',
+        required: [FIELD.prMerged],
+        optional: [],
+    },
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Get the completion contract for a work type.
+ * Returns undefined for unknown work types (caller should treat as no contract).
+ */
+export function getCompletionContract(workType) {
+    return CONTRACTS[workType];
+}
+/**
+ * Validate session outputs against a completion contract.
+ */
+export function validateCompletion(contract, outputs) {
+    const presentFields = [];
+    const missingFields = [];
+    const backstopRecoverable = [];
+    const manualRequired = [];
+    for (const field of contract.required) {
+        if (isFieldPresent(field.type, outputs)) {
+            presentFields.push(field.type);
+        }
+        else {
+            missingFields.push(field.type);
+            if (field.backstopCapable) {
+                backstopRecoverable.push(field.type);
+            }
+            else {
+                manualRequired.push(field.type);
+            }
+        }
+    }
+    return {
+        satisfied: missingFields.length === 0,
+        presentFields,
+        missingFields,
+        backstopRecoverable,
+        manualRequired,
+    };
+}
+/**
+ * Check whether a specific field is present in the session outputs.
+ */
+function isFieldPresent(fieldType, outputs) {
+    switch (fieldType) {
+        case 'pr_url':
+            return !!outputs.prUrl;
+        case 'branch_pushed':
+            return !!outputs.branchPushed;
+        case 'commits_present':
+            return !!outputs.commitsPresent;
+        case 'work_result':
+            return outputs.workResult === 'passed' || outputs.workResult === 'failed';
+        case 'issue_updated':
+            return !!outputs.issueUpdated;
+        case 'comment_posted':
+            return !!outputs.commentPosted;
+        case 'sub_issues_created':
+            return !!outputs.subIssuesCreated;
+        case 'pr_merged':
+            return !!outputs.prMerged;
+        default:
+            return false;
+    }
+}
+/**
+ * Format missing fields into a human-readable diagnostic message.
+ */
+export function formatMissingFields(contract, validation) {
+    const lines = [
+        `Session completion check for ${contract.workType}:`,
+    ];
+    if (validation.satisfied) {
+        lines.push('All required outputs are present.');
+        return lines.join('\n');
+    }
+    lines.push('');
+    lines.push('Missing required outputs:');
+    for (const fieldType of validation.missingFields) {
+        const field = contract.required.find(f => f.type === fieldType);
+        const recoverable = validation.backstopRecoverable.includes(fieldType);
+        lines.push(`  - ${field?.label ?? fieldType}${recoverable ? ' (auto-recoverable)' : ' (requires manual action)'}`);
+    }
+    if (validation.backstopRecoverable.length > 0) {
+        lines.push('');
+        lines.push(`The orchestrator will attempt to recover ${validation.backstopRecoverable.length} field(s) automatically.`);
+    }
+    if (validation.manualRequired.length > 0) {
+        lines.push('');
+        lines.push(`${validation.manualRequired.length} field(s) require manual intervention or re-triggering the agent.`);
+    }
+    return lines.join('\n');
+}

package/dist/src/orchestrator/completion-contracts.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=completion-contracts.test.d.ts.map

package/dist/src/orchestrator/completion-contracts.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-contracts.test.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/completion-contracts.test.ts"],"names":[],"mappings":""}

package/dist/src/orchestrator/completion-contracts.test.js

@@ -0,0 +1,195 @@
+import { describe, it, expect } from 'vitest';
+import { getCompletionContract, validateCompletion, formatMissingFields, } from './completion-contracts.js';
+describe('getCompletionContract', () => {
+    it('returns a contract for development work type', () => {
+        const contract = getCompletionContract('development');
+        expect(contract).toBeDefined();
+        expect(contract.workType).toBe('development');
+        expect(contract.required.map(f => f.type)).toContain('pr_url');
+        expect(contract.required.map(f => f.type)).toContain('branch_pushed');
+        expect(contract.required.map(f => f.type)).toContain('commits_present');
+    });
+    it('returns a contract for qa work type', () => {
+        const contract = getCompletionContract('qa');
+        expect(contract).toBeDefined();
+        expect(contract.required.map(f => f.type)).toContain('work_result');
+        expect(contract.required.map(f => f.type)).toContain('comment_posted');
+    });
+    it('returns a contract for acceptance work type', () => {
+        const contract = getCompletionContract('acceptance');
+        expect(contract).toBeDefined();
+        expect(contract.required.map(f => f.type)).toContain('work_result');
+    });
+    it('returns a contract for refinement work type', () => {
+        const contract = getCompletionContract('refinement');
+        expect(contract).toBeDefined();
+        expect(contract.required.map(f => f.type)).toContain('comment_posted');
+    });
+    it('returns a contract for research work type', () => {
+        const contract = getCompletionContract('research');
+        expect(contract).toBeDefined();
+        expect(contract.required.map(f => f.type)).toContain('issue_updated');
+    });
+    it('returns a contract for backlog-creation work type', () => {
+        const contract = getCompletionContract('backlog-creation');
+        expect(contract).toBeDefined();
+        expect(contract.required.map(f => f.type)).toContain('sub_issues_created');
+    });
+    it('returns a contract for coordination work type', () => {
+        const contract = getCompletionContract('coordination');
+        expect(contract).toBeDefined();
+        const required = contract.required.map(f => f.type);
+        expect(required).toContain('pr_url');
+        expect(required).toContain('work_result');
+    });
+    it('returns a contract for merge work type', () => {
+        const contract = getCompletionContract('merge');
+        expect(contract).toBeDefined();
+        expect(contract.required.map(f => f.type)).toContain('pr_merged');
+    });
+    it('returns contracts for all coordination variants', () => {
+        expect(getCompletionContract('qa-coordination')).toBeDefined();
+        expect(getCompletionContract('acceptance-coordination')).toBeDefined();
+        expect(getCompletionContract('inflight-coordination')).toBeDefined();
+        expect(getCompletionContract('refinement-coordination')).toBeDefined();
+    });
+});
+describe('validateCompletion', () => {
+    it('marks satisfied when all required fields present (development)', () => {
+        const contract = getCompletionContract('development');
+        const outputs = {
+            prUrl: 'https://github.com/org/repo/pull/1',
+            branchPushed: true,
+            commitsPresent: true,
+        };
+        const result = validateCompletion(contract, outputs);
+        expect(result.satisfied).toBe(true);
+        expect(result.missingFields).toHaveLength(0);
+    });
+    it('detects missing PR URL (development)', () => {
+        const contract = getCompletionContract('development');
+        const outputs = {
+            branchPushed: true,
+            commitsPresent: true,
+        };
+        const result = validateCompletion(contract, outputs);
+        expect(result.satisfied).toBe(false);
+        expect(result.missingFields).toContain('pr_url');
+        expect(result.backstopRecoverable).toContain('pr_url');
+    });
+    it('detects missing branch push (development)', () => {
+        const contract = getCompletionContract('development');
+        const outputs = {
+            prUrl: 'https://github.com/org/repo/pull/1',
+            branchPushed: false,
+            commitsPresent: true,
+        };
+        const result = validateCompletion(contract, outputs);
+        expect(result.satisfied).toBe(false);
+        expect(result.missingFields).toContain('branch_pushed');
+        expect(result.backstopRecoverable).toContain('branch_pushed');
+    });
+    it('marks commits_present as not backstop-capable', () => {
+        const contract = getCompletionContract('development');
+        const outputs = {
+            prUrl: 'https://github.com/org/repo/pull/1',
+            branchPushed: true,
+            commitsPresent: false,
+        };
+        const result = validateCompletion(contract, outputs);
+        expect(result.satisfied).toBe(false);
+        expect(result.manualRequired).toContain('commits_present');
+        expect(result.backstopRecoverable).not.toContain('commits_present');
+    });
+    it('marks satisfied for QA with work result passed', () => {
+        const contract = getCompletionContract('qa');
+        const outputs = {
+            workResult: 'passed',
+            commentPosted: true,
+        };
+        const result = validateCompletion(contract, outputs);
+        expect(result.satisfied).toBe(true);
+    });
+    it('marks satisfied for QA with work result failed', () => {
+        const contract = getCompletionContract('qa');
+        const outputs = {
+            workResult: 'failed',
+            commentPosted: true,
+        };
+        const result = validateCompletion(contract, outputs);
+        expect(result.satisfied).toBe(true);
+    });
+    it('marks unsatisfied for QA with unknown work result', () => {
+        const contract = getCompletionContract('qa');
+        const outputs = {
+            workResult: 'unknown',
+            commentPosted: true,
+        };
+        const result = validateCompletion(contract, outputs);
+        expect(result.satisfied).toBe(false);
+        expect(result.missingFields).toContain('work_result');
+        expect(result.manualRequired).toContain('work_result');
+    });
+    it('marks unsatisfied for QA without comment', () => {
+        const contract = getCompletionContract('qa');
+        const outputs = {
+            workResult: 'passed',
+            commentPosted: false,
+        };
+        const result = validateCompletion(contract, outputs);
+        expect(result.satisfied).toBe(false);
+        expect(result.missingFields).toContain('comment_posted');
+    });
+    it('marks satisfied for refinement with comment posted', () => {
+        const contract = getCompletionContract('refinement');
+        const outputs = {
+            commentPosted: true,
+        };
+        const result = validateCompletion(contract, outputs);
+        expect(result.satisfied).toBe(true);
+    });
+    it('marks satisfied for backlog-creation with sub-issues', () => {
+        const contract = getCompletionContract('backlog-creation');
+        const outputs = {
+            subIssuesCreated: true,
+        };
+        const result = validateCompletion(contract, outputs);
+        expect(result.satisfied).toBe(true);
+    });
+    it('handles empty outputs gracefully', () => {
+        const contract = getCompletionContract('development');
+        const outputs = {};
+        const result = validateCompletion(contract, outputs);
+        expect(result.satisfied).toBe(false);
+        expect(result.missingFields).toHaveLength(3);
+    });
+});
+describe('formatMissingFields', () => {
+    it('formats satisfied contract', () => {
+        const contract = getCompletionContract('development');
+        const validation = validateCompletion(contract, {
+            prUrl: 'https://github.com/org/repo/pull/1',
+            branchPushed: true,
+            commitsPresent: true,
+        });
+        const message = formatMissingFields(contract, validation);
+        expect(message).toContain('All required outputs are present');
+    });
+    it('formats missing fields with recovery info', () => {
+        const contract = getCompletionContract('development');
+        const validation = validateCompletion(contract, {
+            commitsPresent: true,
+        });
+        const message = formatMissingFields(contract, validation);
+        expect(message).toContain('Missing required outputs');
+        expect(message).toContain('auto-recoverable');
+        expect(message).toContain('Pull request URL');
+        expect(message).toContain('Branch pushed to remote');
+    });
+    it('formats manual-required fields', () => {
+        const contract = getCompletionContract('qa');
+        const validation = validateCompletion(contract, {});
+        const message = formatMissingFields(contract, validation);
+        expect(message).toContain('requires manual action');
+    });
+});

package/dist/src/orchestrator/index.d.ts

@@ -21,6 +21,10 @@ export { getAgentDir, getStatePath, getHeartbeatPath, getTodosPath, isHeartbeatF
 export { getLogAnalysisConfig, isSessionLoggingEnabled, isAutoAnalyzeEnabled, } from './log-config.js';
 export { SessionLogger, createSessionLogger, readSessionMetadata, readSessionEvents, } from './session-logger.js';
 export { parseWorkResult } from './parse-work-result.js';
+export { getCompletionContract, validateCompletion, formatMissingFields, } from './completion-contracts.js';
+export type { CompletionContract, CompletionField, CompletionFieldType, CompletionValidationResult, SessionOutputs, BackstopAction, BackstopResult, } from './completion-contracts.js';
+export { runBackstop, collectSessionOutputs, formatBackstopComment, } from './session-backstop.js';
+export type { SessionContext, BackstopOptions, BackstopRunResult, } from './session-backstop.js';
 export { LogAnalyzer, createLogAnalyzer } from './log-analyzer.js';
 export { ArtifactTracker, } from './artifact-tracker.js';
 export type { TrackedFileAction, TrackedFile, ArtifactIndex, } from './artifact-tracker.js';

package/dist/src/orchestrator/index.d.ts.map

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

package/dist/src/orchestrator/index.js

@@ -20,6 +20,9 @@ export { getLogAnalysisConfig, isSessionLoggingEnabled, isAutoAnalyzeEnabled, }
 export { SessionLogger, createSessionLogger, readSessionMetadata, readSessionEvents, } from './session-logger.js';
 // Work Result Parser (for QA/acceptance pass/fail detection)
 export { parseWorkResult } from './parse-work-result.js';
+// Completion Contracts & Session Backstop
+export { getCompletionContract, validateCompletion, formatMissingFields, } from './completion-contracts.js';
+export { runBackstop, collectSessionOutputs, formatBackstopComment, } from './session-backstop.js';
 // Log Analyzer
 export { LogAnalyzer, createLogAnalyzer } from './log-analyzer.js';
 // Artifact Tracker (for context window management)