codex-workflow-v2 2.0.0-alpha.1

package/dist/src/workflow.js

@@ -0,0 +1,1276 @@
+import { appendFileSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { PROTOCOL_VERSION, STATE_SCHEMA_VERSION, } from './contracts.js';
+import { renderBrief, renderPlan, renderResult } from './artifacts.js';
+import { assessDiscovery, mergeUnique } from './domain/discovery.js';
+import { pathAllowed, validatePlan } from './domain/validation.js';
+import { WorkflowError } from './errors.js';
+import { bindGraphEvidence, createGraphRefreshRequest, fallbackGraphBinding, inspectGraphBinding, validateGraphRequestCurrent, } from './graph.js';
+import { applyKnowledgeSelections, hashKnowledgeMap, inspectKnowledgeMap, normalizeRelativePath, reconcileKnowledgeMap, scanProjectKnowledge, selectKnowledgeSources, } from './memory.js';
+import { commitStep, mergeTaskBranch, runChecks, startLocalTaskBranch, syncBaseIntoTask, validateTaskHistory, } from './git.js';
+import { changedFiles, currentBranch, gitIsAncestor, headCommit, isClean, resolveRepositoryIdentity, runGit, } from './repository.js';
+import { WriterLockManager } from './state/lock.js';
+import { FileStateStore } from './state/store.js';
+import { createEntityId } from './ulid.js';
+import { PACKAGE_VERSION } from './version.js';
+export class WorkflowService {
+    store;
+    now;
+    constructor(store = new FileStateStore(), now = () => new Date()) {
+        this.store = store;
+        this.now = now;
+    }
+    context(repository) {
+        const identity = resolveRepositoryIdentity(repository);
+        this.store.registerProject(identity);
+        return {
+            identity,
+            store: this.store,
+            locks: new WriterLockManager(this.store.lockRoot(identity.projectId), this.now),
+        };
+    }
+    startDiscovery(repository, input) {
+        if (!input.goal.trim())
+            throw new WorkflowError('INVALID_ARGUMENT', 'Discovery requires a substantive goal.');
+        const { identity } = this.context(repository);
+        const timestamp = this.now().toISOString();
+        const initial = {
+            schemaVersion: STATE_SCHEMA_VERSION,
+            revision: 0,
+            id: createEntityId('DISC', this.now().getTime()),
+            projectId: identity.projectId,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            kind: 'discovery',
+            status: 'needs_discovery',
+            goal: input.goal.trim(),
+            outcome: input.outcome?.trim() || null,
+            facts: mergeUnique([], input.facts ?? []),
+            decisions: mergeUnique([], input.decisions ?? []),
+            assumptions: mergeUnique([], input.assumptions ?? []),
+            unknowns: mergeUnique([], input.unknowns ?? []),
+            blockingUnknowns: mergeUnique([], input.blockingUnknowns ?? []),
+            scope: mergeUnique([], input.scope ?? []),
+            outOfScope: mergeUnique([], input.outOfScope ?? []),
+            constraints: mergeUnique([], input.constraints ?? []),
+            acceptance: mergeUnique([], input.acceptance ?? []),
+            materializedEntityId: null,
+        };
+        initial.status = assessDiscovery(initial).status;
+        return this.store.writeDiscovery(initial, null);
+    }
+    updateDiscovery(repository, discoveryId, expectedRevision, patch) {
+        const { identity } = this.context(repository);
+        const current = this.store.readDiscovery(identity.projectId, discoveryId);
+        if (current.status === 'materialized' || current.status === 'abandoned') {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Discovery ${discoveryId} is ${current.status}.`);
+        }
+        const resolved = new Set(patch.resolveUnknowns ?? []);
+        const updated = {
+            ...current,
+            goal: patch.goal?.trim() || current.goal,
+            outcome: patch.outcome?.trim() || current.outcome,
+            facts: mergeUnique(current.facts, patch.facts ?? []),
+            decisions: mergeUnique(current.decisions, patch.decisions ?? []),
+            assumptions: mergeUnique(current.assumptions, patch.assumptions ?? []),
+            unknowns: mergeUnique(current.unknowns, patch.unknowns ?? []).filter((value) => !resolved.has(value)),
+            blockingUnknowns: mergeUnique(current.blockingUnknowns, patch.blockingUnknowns ?? []).filter((value) => !resolved.has(value)),
+            scope: mergeUnique(current.scope, patch.scope ?? []),
+            outOfScope: mergeUnique(current.outOfScope, patch.outOfScope ?? []),
+            constraints: mergeUnique(current.constraints, patch.constraints ?? []),
+            acceptance: mergeUnique(current.acceptance, patch.acceptance ?? []),
+        };
+        updated.status = assessDiscovery(updated).status;
+        return this.store.writeDiscovery(updated, expectedRevision);
+    }
+    materializeTask(repository, discoveryId, expectedRevision, title, baseBranch = 'main', milestoneId = null) {
+        const { identity } = this.context(repository);
+        const discovery = this.store.readDiscovery(identity.projectId, discoveryId);
+        assertExpectedRevision(discovery, expectedRevision);
+        const readiness = assessDiscovery(discovery);
+        if (!readiness.ready || discovery.status !== 'ready_to_materialize') {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Discovery is not ready to materialize.', {
+                missing: readiness.missing,
+            });
+        }
+        if (!title.trim())
+            throw new WorkflowError('INVALID_ARGUMENT', 'Task title is required.');
+        if (milestoneId) {
+            const milestone = this.store.readMilestone(identity.projectId, milestoneId);
+            if (milestone.status === 'accepted' || milestone.status === 'cancelled') {
+                throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} is ${milestone.status}.`);
+            }
+            if (milestone.baseBranch !== baseBranch) {
+                throw new WorkflowError('TRANSITION_BLOCKED', 'Task and Milestone must use the same base branch.', {
+                    taskBaseBranch: baseBranch,
+                    milestoneBaseBranch: milestone.baseBranch,
+                });
+            }
+        }
+        const taskId = createEntityId('TASK', this.now().getTime());
+        const taskRoot = this.store.taskRoot(identity.projectId, taskId);
+        const briefHash = this.store.writeArtifact(taskRoot, 'brief.md', renderBrief(discovery, title.trim()));
+        const timestamp = this.now().toISOString();
+        const task = {
+            schemaVersion: STATE_SCHEMA_VERSION,
+            revision: 0,
+            id: taskId,
+            projectId: identity.projectId,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            kind: 'task',
+            status: 'planning',
+            title: title.trim(),
+            slug: slugify(title),
+            discoveryId,
+            milestoneId,
+            repositoryRoot: identity.repositoryRoot,
+            baseBranch,
+            baseCommit: null,
+            taskBranch: null,
+            workspaceOwner: null,
+            briefHash,
+            planHash: null,
+            resultHash: null,
+            evidenceHash: null,
+            requirements: discovery.acceptance.map((_, index) => `REQ-${String(index + 1).padStart(3, '0')}`),
+            acceptance: discovery.acceptance.map((_, index) => `AC-${String(index + 1).padStart(3, '0')}`),
+            risks: discovery.assumptions,
+            knowledgeImpact: null,
+            knowledgeImpactReason: null,
+            knowledgeTargets: [],
+            knowledgeMapRevision: null,
+            knowledgeMapHash: null,
+            graphUse: null,
+            steps: [],
+            authorizations: [],
+            review: emptyReview(),
+            blockReason: null,
+            mergedCommit: null,
+            systemCommits: [],
+        };
+        const savedTask = this.store.writeTask(task, null);
+        const savedDiscovery = this.store.writeDiscovery({ ...discovery, status: 'materialized', materializedEntityId: taskId }, expectedRevision);
+        return { discovery: savedDiscovery, task: savedTask, taskRoot };
+    }
+    materializeMilestone(repository, discoveryId, expectedRevision, title, baseBranch = 'main') {
+        const { identity } = this.context(repository);
+        const discovery = this.store.readDiscovery(identity.projectId, discoveryId);
+        assertExpectedRevision(discovery, expectedRevision);
+        const readiness = assessDiscovery(discovery);
+        if (!readiness.ready || discovery.status !== 'ready_to_materialize') {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Discovery is not ready to materialize.', {
+                missing: readiness.missing,
+            });
+        }
+        if (!title.trim())
+            throw new WorkflowError('INVALID_ARGUMENT', 'Milestone title is required.');
+        const id = createEntityId('MS', this.now().getTime());
+        const timestamp = this.now().toISOString();
+        const milestone = {
+            schemaVersion: STATE_SCHEMA_VERSION,
+            revision: 0,
+            id,
+            projectId: identity.projectId,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            kind: 'milestone',
+            status: 'planning',
+            title: title.trim(),
+            discoveryId,
+            outcome: discovery.outcome ?? '',
+            successSignal: '',
+            acceptance: discovery.acceptance,
+            baseBranch,
+            taskIds: [],
+            memberships: [],
+            checks: [],
+            membershipRevision: 0,
+            authorizations: [],
+            planHash: null,
+            resultHash: null,
+            evidenceHash: null,
+            acceptedHead: null,
+            cancellationReason: null,
+        };
+        const savedMilestone = this.store.writeMilestone(milestone, null);
+        const savedDiscovery = this.store.writeDiscovery({ ...discovery, status: 'materialized', materializedEntityId: id }, expectedRevision);
+        return {
+            discovery: savedDiscovery,
+            milestone: savedMilestone,
+            milestoneRoot: this.store.milestoneRoot(identity.projectId, id),
+        };
+    }
+    setMilestonePlan(repository, milestoneId, expectedRevision, plan) {
+        const { identity } = this.context(repository);
+        const milestone = this.store.readMilestone(identity.projectId, milestoneId);
+        assertExpectedRevision(milestone, expectedRevision);
+        if (!['planning', 'awaiting_execution_authorization', 'active', 'blocked'].includes(milestone.status)) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Cannot update Milestone Plan while ${milestone.status}.`);
+        }
+        validateMilestonePlan(plan);
+        const taskIds = plan.memberships.map((membership) => membership.taskId);
+        if (new Set(taskIds).size !== taskIds.length) {
+            throw new WorkflowError('INVALID_ARGUMENT', 'Milestone memberships must have unique Task IDs.');
+        }
+        for (const membership of plan.memberships) {
+            const task = this.store.readTask(identity.projectId, membership.taskId);
+            if (task.milestoneId !== milestoneId) {
+                throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} is not linked to Milestone ${milestoneId}.`);
+            }
+        }
+        const nextIds = new Set(taskIds);
+        for (const existing of milestone.memberships) {
+            if (nextIds.has(existing.taskId))
+                continue;
+            const task = this.store.readTask(identity.projectId, existing.taskId);
+            if (taskHasStarted(task)) {
+                throw new WorkflowError('TRANSITION_BLOCKED', `Started Task ${task.id} cannot be removed from a Milestone.`);
+            }
+        }
+        const root = this.store.milestoneRoot(identity.projectId, milestoneId);
+        const normalized = {
+            outcome: plan.outcome.trim(),
+            successSignal: plan.successSignal.trim(),
+            acceptance: [...plan.acceptance],
+            memberships: plan.memberships.map((membership) => ({
+                ...membership,
+                reason: membership.reason.trim(),
+            })),
+            checks: [...plan.checks],
+        };
+        const stagedPlan = this.store.stageArtifact(root, 'plan.json', JSON.stringify(normalized, null, 2));
+        const authorizations = milestone.authorizations.map((authorization) => authorization.kind === 'execution' && authorization.decision === 'approved'
+            ? { ...authorization, decision: 'superseded' }
+            : authorization);
+        const saved = this.store.writeMilestone({
+            ...milestone,
+            status: 'awaiting_execution_authorization',
+            outcome: normalized.outcome,
+            successSignal: normalized.successSignal,
+            acceptance: normalized.acceptance,
+            taskIds,
+            memberships: normalized.memberships,
+            checks: normalized.checks,
+            membershipRevision: milestone.membershipRevision + 1,
+            authorizations,
+            planHash: stagedPlan.hash,
+            resultHash: null,
+            evidenceHash: null,
+            acceptedHead: null,
+            cancellationReason: null,
+        }, expectedRevision);
+        this.store.publishArtifact(stagedPlan);
+        return saved;
+    }
+    authorizeMilestone(repository, milestoneId, expectedRevision, actor, reason = '') {
+        const { identity } = this.context(repository);
+        const milestone = this.store.readMilestone(identity.projectId, milestoneId);
+        assertExpectedRevision(milestone, expectedRevision);
+        if (milestone.status !== 'awaiting_execution_authorization' || !milestone.planHash) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} is not awaiting authorization.`);
+        }
+        const root = this.store.milestoneRoot(identity.projectId, milestoneId);
+        const planHash = this.store.hashArtifact(root, 'plan.json');
+        if (planHash !== milestone.planHash) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone Plan changed after it was recorded.');
+        }
+        const event = {
+            kind: 'execution',
+            decision: 'approved',
+            actor: actor.trim() || 'user',
+            recordedAt: this.now().toISOString(),
+            briefHash: null,
+            planHash,
+            resultHash: null,
+            evidenceHash: null,
+            headCommit: runGit(identity.repositoryRoot, ['rev-parse', milestone.baseBranch]),
+            reason,
+        };
+        return this.store.writeMilestone({ ...milestone, status: 'active', planHash, authorizations: [...milestone.authorizations, event] }, expectedRevision);
+    }
+    validateMilestone(repository, milestoneId, expectedRevision) {
+        const { identity } = this.context(repository);
+        const milestone = this.store.readMilestone(identity.projectId, milestoneId);
+        assertExpectedRevision(milestone, expectedRevision);
+        if (milestone.status !== 'active') {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} is not active.`);
+        }
+        this.assertMilestoneAuthorizationFresh(milestone);
+        if (currentBranch(identity.repositoryRoot) !== milestone.baseBranch || !isClean(identity.repositoryRoot)) {
+            throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Milestone validation requires a clean base branch checkout.', {
+                expectedBranch: milestone.baseBranch,
+                actualBranch: currentBranch(identity.repositoryRoot),
+                changedFiles: changedFiles(identity.repositoryRoot),
+            });
+        }
+        const incomplete = milestone.memberships.filter((membership) => {
+            if (membership.disposition !== 'required')
+                return false;
+            return this.store.readTask(identity.projectId, membership.taskId).status !== 'merged';
+        });
+        if (incomplete.length > 0) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Required Milestone Tasks are not merged.', {
+                taskIds: incomplete.map((membership) => membership.taskId),
+            });
+        }
+        const checks = runChecks(identity.repositoryRoot, milestone.checks);
+        const baseHead = headCommit(identity.repositoryRoot);
+        const root = this.store.milestoneRoot(identity.projectId, milestoneId);
+        const stagedEvidence = this.store.stageArtifact(root, 'evidence.json', JSON.stringify({
+            milestoneId,
+            baseBranch: milestone.baseBranch,
+            headCommit: baseHead,
+            generatedAt: this.now().toISOString(),
+            membershipRevision: milestone.membershipRevision,
+            memberships: milestone.memberships,
+            checks,
+        }, null, 2));
+        if (checks.some((check) => !check.passed)) {
+            const saved = this.store.writeMilestone({ ...milestone, status: 'blocked', evidenceHash: stagedEvidence.hash }, expectedRevision);
+            this.store.publishArtifact(stagedEvidence);
+            return saved;
+        }
+        const result = [
+            `# Milestone result: ${milestone.title}`,
+            '',
+            `Outcome: ${milestone.outcome}`,
+            '',
+            `Validated base: ${milestone.baseBranch}@${baseHead}`,
+            '',
+            'All required memberships are merged and all Milestone checks passed.',
+            '',
+        ].join('\n');
+        const stagedResult = this.store.stageArtifact(root, 'result.md', result);
+        const saved = this.store.writeMilestone({
+            ...milestone,
+            status: 'awaiting_final_acceptance',
+            evidenceHash: stagedEvidence.hash,
+            resultHash: stagedResult.hash,
+        }, expectedRevision);
+        this.store.publishArtifact(stagedEvidence);
+        this.store.publishArtifact(stagedResult);
+        return saved;
+    }
+    acceptMilestone(repository, milestoneId, expectedRevision, actor) {
+        const { identity } = this.context(repository);
+        const milestone = this.store.readMilestone(identity.projectId, milestoneId);
+        assertExpectedRevision(milestone, expectedRevision);
+        if (milestone.status !== 'awaiting_final_acceptance' || !milestone.resultHash || !milestone.evidenceHash) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} is not ready for acceptance.`);
+        }
+        if (currentBranch(identity.repositoryRoot) !== milestone.baseBranch || !isClean(identity.repositoryRoot)) {
+            throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Milestone acceptance requires a clean base branch checkout.');
+        }
+        const root = this.store.milestoneRoot(identity.projectId, milestoneId);
+        const evidence = JSON.parse(readFileSync(path.join(root, 'evidence.json'), 'utf8'));
+        const currentHead = headCommit(identity.repositoryRoot);
+        const resultHash = this.store.hashArtifact(root, 'result.md');
+        const evidenceHash = this.store.hashArtifact(root, 'evidence.json');
+        if (evidence.headCommit !== currentHead || resultHash !== milestone.resultHash || evidenceHash !== milestone.evidenceHash) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone validation evidence is stale.');
+        }
+        const event = {
+            kind: 'final_acceptance',
+            decision: 'approved',
+            actor: actor.trim() || 'user',
+            recordedAt: this.now().toISOString(),
+            briefHash: null,
+            planHash: milestone.planHash,
+            resultHash,
+            evidenceHash,
+            headCommit: currentHead,
+            reason: '',
+        };
+        return this.store.writeMilestone({
+            ...milestone,
+            status: 'accepted',
+            resultHash,
+            evidenceHash,
+            acceptedHead: currentHead,
+            authorizations: [...milestone.authorizations, event],
+        }, expectedRevision);
+    }
+    cancelMilestone(repository, milestoneId, expectedRevision, reason) {
+        if (!reason.trim())
+            throw new WorkflowError('INVALID_ARGUMENT', 'Milestone cancellation requires a reason.');
+        const { identity } = this.context(repository);
+        const milestone = this.store.readMilestone(identity.projectId, milestoneId);
+        assertExpectedRevision(milestone, expectedRevision);
+        if (['accepted', 'cancelled'].includes(milestone.status)) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} is ${milestone.status}.`);
+        }
+        return this.store.writeMilestone({ ...milestone, status: 'cancelled', cancellationReason: reason.trim() }, expectedRevision);
+    }
+    setTaskPlan(repository, taskId, expectedRevision, plan) {
+        validatePlan(plan);
+        const { identity } = this.context(repository);
+        const knowledgeMap = this.assertKnowledgeMapBinding(identity.repositoryRoot, identity.projectId, plan.knowledgeMapRevision, plan.knowledgeMapHash);
+        this.validateKnowledgeTargets(knowledgeMap, plan);
+        const task = this.store.readTask(identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        if (!['planning', 'awaiting_execution_authorization', 'needs_fix'].includes(task.status)) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Cannot update Plan while Task is ${task.status}.`);
+        }
+        for (const requirement of task.requirements) {
+            if (!plan.requirements.includes(requirement)) {
+                throw new WorkflowError('TRANSITION_BLOCKED', `Plan omits Task requirement ${requirement}.`);
+            }
+        }
+        for (const acceptance of task.acceptance) {
+            if (!plan.acceptance.includes(acceptance)) {
+                throw new WorkflowError('TRANSITION_BLOCKED', `Plan omits Task acceptance ${acceptance}.`);
+            }
+        }
+        const root = this.store.taskRoot(identity.projectId, taskId);
+        const stagedPlan = this.store.stageArtifact(root, 'plan.md', renderPlan(task, plan));
+        const authorizations = task.authorizations.map((authorization) => authorization.kind === 'execution' && authorization.decision === 'approved'
+            ? { ...authorization, decision: 'superseded' }
+            : authorization);
+        const completedIds = task.steps
+            .filter((candidate) => candidate.status === 'completed')
+            .map((candidate) => candidate.id);
+        const plannedSteps = plan.steps.map((step) => preserveCompletedStep(task, step) ?? ({
+            ...step,
+            status: dependenciesComplete(step, completedIds) ? 'planned' : 'blocked',
+            evidence: null,
+        }));
+        if (task.status === 'needs_fix' &&
+            task.review.status === 'failed' &&
+            plannedSteps.every((step) => step.status === 'completed')) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'A failed review requires at least one new or changed remediation Step.');
+        }
+        const saved = this.store.writeTask({
+            ...task,
+            status: 'awaiting_execution_authorization',
+            planHash: stagedPlan.hash,
+            requirements: plan.requirements,
+            acceptance: plan.acceptance,
+            risks: plan.risks,
+            knowledgeImpact: plan.knowledgeImpact,
+            knowledgeImpactReason: plan.knowledgeImpactReason,
+            knowledgeTargets: plan.knowledgeTargets,
+            knowledgeMapRevision: plan.knowledgeMapRevision,
+            knowledgeMapHash: plan.knowledgeMapHash,
+            graphUse: plan.graphUse,
+            steps: plannedSteps,
+            authorizations,
+            review: emptyReview(),
+            resultHash: null,
+            evidenceHash: null,
+            blockReason: null,
+        }, expectedRevision);
+        this.store.publishArtifact(stagedPlan);
+        return saved;
+    }
+    authorizeTask(repository, taskId, expectedRevision, actor, reason = '') {
+        const { identity } = this.context(repository);
+        const task = this.store.readTask(identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        if (task.status !== 'awaiting_execution_authorization' || !task.planHash) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Task ${taskId} is not awaiting execution authorization.`);
+        }
+        this.assertTaskKnowledgeBinding(identity.repositoryRoot, task);
+        const root = this.store.taskRoot(identity.projectId, taskId);
+        const briefHash = this.store.hashArtifact(root, 'brief.md');
+        const planHash = this.store.hashArtifact(root, 'plan.md');
+        const event = {
+            kind: 'execution',
+            decision: 'approved',
+            actor: actor.trim() || 'user',
+            recordedAt: this.now().toISOString(),
+            briefHash,
+            planHash,
+            resultHash: null,
+            evidenceHash: null,
+            headCommit: null,
+            reason,
+        };
+        return this.store.writeTask({ ...task, status: 'ready', briefHash, planHash, authorizations: [...task.authorizations, event] }, expectedRevision);
+    }
+    startTask(repository, taskId, expectedRevision, workspaceOwner) {
+        const { identity } = this.context(repository);
+        const task = this.store.readTask(identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        if (task.status !== 'ready')
+            throw new WorkflowError('TRANSITION_BLOCKED', `Task ${taskId} is ${task.status}.`);
+        this.assertExecutionAuthorizationFresh(task);
+        if (task.milestoneId) {
+            const milestone = this.store.readMilestone(identity.projectId, task.milestoneId);
+            const membership = milestone.memberships.find((candidate) => candidate.taskId === taskId);
+            if (milestone.status !== 'active' || membership?.disposition !== 'required') {
+                throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone-linked Task requires an active, authorized membership.', {
+                    milestoneId: milestone.id,
+                    milestoneStatus: milestone.status,
+                    disposition: membership?.disposition ?? null,
+                });
+            }
+        }
+        if (!isClean(identity.repositoryRoot)) {
+            throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Task start requires a clean checkout.', {
+                changedFiles: changedFiles(identity.repositoryRoot),
+            });
+        }
+        const branch = `codex/task-${task.id.slice(5, 15).toLowerCase()}-${task.slug}`;
+        let baseCommit;
+        let taskBranch;
+        if (workspaceOwner === 'local') {
+            baseCommit = startLocalTaskBranch(identity.repositoryRoot, branch, task.baseBranch);
+            taskBranch = branch;
+        }
+        else {
+            baseCommit = runGit(identity.repositoryRoot, ['rev-parse', task.baseBranch]);
+            taskBranch = currentBranch(identity.repositoryRoot);
+            if (!taskBranch || taskBranch === task.baseBranch) {
+                throw new WorkflowError('GIT_PRECONDITION_FAILED', `Externally owned execution requires a dedicated branch different from ${task.baseBranch}.`);
+            }
+            if (headCommit(identity.repositoryRoot) !== baseCommit) {
+                throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Externally owned execution branch must start at the recorded base commit.', { baseCommit, headCommit: headCommit(identity.repositoryRoot) });
+            }
+        }
+        return this.store.writeTask({ ...task, baseCommit, taskBranch, workspaceOwner, blockReason: null }, expectedRevision);
+    }
+    runStep(repository, taskId, stepId, expectedRevision, owner, writerToken) {
+        const context = this.context(repository);
+        const task = this.store.readTask(context.identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        if (!['ready', 'in_progress', 'needs_fix'].includes(task.status)) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Task ${taskId} cannot run a Step while ${task.status}.`);
+        }
+        this.assertExecutionAuthorizationFresh(task);
+        const knowledgeMap = this.assertTaskKnowledgeBinding(context.identity.repositoryRoot, task);
+        assertTaskBranch(context.identity.repositoryRoot, task);
+        const step = requireStep(task, stepId);
+        if (!['planned', 'failed'].includes(step.status)) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `${stepId} cannot start from ${step.status}.`);
+        }
+        const dirty = changedFiles(context.identity.repositoryRoot);
+        if (step.status === 'planned' && dirty.length > 0) {
+            throw new WorkflowError('GIT_PRECONDITION_FAILED', `${stepId} must start from a clean checkout.`, {
+                changedFiles: dirty,
+            });
+        }
+        const dirtyOutsideStep = dirty.filter((file) => !pathAllowed(file, step.allowedWrites));
+        if (step.status === 'failed' && dirtyOutsideStep.length > 0) {
+            throw new WorkflowError('GIT_PRECONDITION_FAILED', `${stepId} retry has changes outside allowedWrites.`, {
+                changedFiles: dirtyOutsideStep,
+            });
+        }
+        const incompleteDependencies = step.dependencies.filter((dependency) => requireStep(task, dependency).status !== 'completed');
+        if (incompleteDependencies.length > 0) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `${stepId} has incomplete dependencies.`, {
+                incompleteDependencies,
+            });
+        }
+        const existing = context.locks.inspect(taskId);
+        let acquiredHere = false;
+        const lease = existing
+            ? writerToken
+                ? context.locks.heartbeat(taskId, writerToken)
+                : (() => {
+                    throw new WorkflowError('LOCKED', `${taskId} already has a writer.`, { owner: existing.owner });
+                })()
+            : (() => {
+                acquiredHere = true;
+                return context.locks.acquire(taskId, owner.trim() || 'worker');
+            })();
+        const steps = task.steps.map((candidate) => candidate.id === stepId ? { ...candidate, status: 'in_progress' } : candidate);
+        let saved;
+        try {
+            saved = this.store.writeTask({ ...task, status: 'in_progress', steps, blockReason: null }, expectedRevision);
+        }
+        catch (error) {
+            if (acquiredHere)
+                context.locks.release(taskId, lease.token);
+            throw error;
+        }
+        return {
+            task: saved,
+            lease,
+            envelope: {
+                protocolVersion: PROTOCOL_VERSION,
+                packageVersion: PACKAGE_VERSION,
+                role: 'worker',
+                objective: step.objective,
+                inputs: [
+                    path.join(this.store.taskRoot(task.projectId, task.id), 'brief.md'),
+                    path.join(this.store.taskRoot(task.projectId, task.id), 'plan.md'),
+                ],
+                allowedReads: [identityRelative(context.identity.repositoryRoot, '.')],
+                allowedWrites: step.allowedWrites,
+                commands: step.checks,
+                forbiddenScope: step.forbiddenScope,
+                resultSchema: {
+                    type: 'object',
+                    required: ['summary', 'changedFiles', 'checks'],
+                    properties: {
+                        summary: { type: 'string' },
+                        changedFiles: { type: 'array', items: { type: 'string' } },
+                        checks: { type: 'array', items: { type: 'string' } },
+                    },
+                },
+                stopConditions: [
+                    'Required change falls outside allowedWrites.',
+                    'Implementation requires changing Brief, Plan, or acceptance.',
+                    'A configured check cannot be run or interpreted safely.',
+                ],
+                contextBudget: 'medium',
+                taskId,
+                stepId,
+                expectedRevision: saved.revision,
+                writerToken: lease.token,
+                knowledgeMap: knowledgeSummary(knowledgeMap),
+                knowledgeSources: selectKnowledgeSources(knowledgeMap, 'worker', task.knowledgeTargets.map((target) => target.path)),
+            },
+        };
+    }
+    taskContext(repository, taskId, role) {
+        const { identity } = this.context(repository);
+        const task = this.store.readTask(identity.projectId, taskId);
+        const knowledgeMap = task.knowledgeMapRevision === null
+            ? this.requireActiveKnowledgeMap(identity.repositoryRoot, identity.projectId)
+            : this.assertTaskKnowledgeBinding(identity.repositoryRoot, task);
+        const root = this.store.taskRoot(task.projectId, task.id);
+        const common = {
+            protocolVersion: PROTOCOL_VERSION,
+            packageVersion: PACKAGE_VERSION,
+            role,
+            inputs: [path.join(root, 'brief.md'), ...(task.planHash ? [path.join(root, 'plan.md')] : [])],
+            allowedReads: [identity.repositoryRoot, root],
+            allowedWrites: [],
+            commands: [],
+            forbiddenScope: ['Production file changes unless a Worker envelope explicitly permits them.'],
+            stopConditions: ['A required decision is absent from the approved Brief or Plan.'],
+            contextBudget: 'medium',
+            taskId,
+            stepId: 'STEP-000-CONTEXT',
+            expectedRevision: task.revision,
+            writerToken: null,
+            knowledgeMap: knowledgeSummary(knowledgeMap),
+            knowledgeSources: selectKnowledgeSources(knowledgeMap, role, task.knowledgeTargets.map((target) => target.path)),
+        };
+        if (role === 'technical-planner') {
+            return {
+                ...common,
+                objective: `Produce an execution-ready Plan for ${task.title}.`,
+                resultSchema: {
+                    type: 'object',
+                    required: ['objective', 'requirements', 'acceptance', 'risks', 'steps'],
+                },
+            };
+        }
+        if (role === 'independent-reviewer') {
+            return {
+                ...common,
+                objective: `Review ${task.title} against Brief, Plan, diff, checks, and evidence without modifying files.`,
+                inputs: [...common.inputs, ...(task.evidenceHash ? [path.join(root, 'evidence.json')] : [])],
+                resultSchema: {
+                    type: 'object',
+                    required: ['status', 'reviewer', 'summary', 'findings'],
+                },
+                stopConditions: [
+                    ...common.stopConditions,
+                    'The checkout is dirty or the evidence does not identify the reviewed commit.',
+                    'Read-only reviewer isolation cannot be established; return unverified.',
+                ],
+            };
+        }
+        return {
+            ...common,
+            objective: `Coordinate the next valid state transition for ${task.title}.`,
+            resultSchema: { type: 'object', required: ['recommendedAction', 'reason'] },
+        };
+    }
+    completeStep(repository, taskId, stepId, expectedRevision, writerToken, notes) {
+        const context = this.context(repository);
+        context.locks.heartbeat(taskId, writerToken);
+        const task = this.store.readTask(context.identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        assertTaskBranch(context.identity.repositoryRoot, task);
+        const step = requireStep(task, stepId);
+        if (task.status !== 'in_progress' || step.status !== 'in_progress') {
+            throw new WorkflowError('TRANSITION_BLOCKED', `${stepId} is not in progress.`);
+        }
+        const checks = runChecks(context.identity.repositoryRoot, step.checks);
+        const failed = checks.filter((check) => !check.passed);
+        if (failed.length > 0) {
+            const steps = task.steps.map((candidate) => candidate.id === stepId ? { ...candidate, status: 'failed' } : candidate);
+            return this.store.writeTask({ ...task, status: 'needs_fix', steps, blockReason: `${stepId} checks failed.` }, expectedRevision);
+        }
+        const committed = commitStep(context.identity.repositoryRoot, task.id, step.id, step.title, step.allowedWrites);
+        const evidence = {
+            recordedAt: this.now().toISOString(),
+            commitSha: committed.commitSha,
+            changedFiles: committed.files,
+            checks,
+            notes,
+        };
+        const completedIds = new Set([
+            ...task.steps.filter((candidate) => candidate.status === 'completed').map((candidate) => candidate.id),
+            stepId,
+        ]);
+        const steps = task.steps.map((candidate) => {
+            if (candidate.id === stepId)
+                return { ...candidate, status: 'completed', evidence };
+            if (candidate.status === 'blocked' && dependenciesComplete(candidate, completedIds)) {
+                return { ...candidate, status: 'planned' };
+            }
+            return candidate;
+        });
+        return this.store.writeTask({ ...task, status: 'in_progress', steps, blockReason: null }, expectedRevision);
+    }
+    submitTask(repository, taskId, expectedRevision, writerToken) {
+        const context = this.context(repository);
+        context.locks.heartbeat(taskId, writerToken);
+        const task = this.store.readTask(context.identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        assertTaskBranch(context.identity.repositoryRoot, task);
+        if (!['in_progress', 'ready'].includes(task.status)) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Task ${taskId} cannot be submitted while ${task.status}.`);
+        }
+        if (!isClean(context.identity.repositoryRoot)) {
+            throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Task submission requires a clean checkout.');
+        }
+        const incomplete = task.steps.filter((step) => step.status !== 'completed' && step.status !== 'skipped');
+        if (incomplete.length > 0) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Task has incomplete Steps.', {
+                steps: incomplete.map((step) => `${step.id}:${step.status}`),
+            });
+        }
+        validateTaskHistory(context.identity.repositoryRoot, task);
+        const root = this.store.taskRoot(task.projectId, task.id);
+        const stagedEvidence = this.store.stageArtifact(root, 'evidence.json', JSON.stringify({
+            taskId: task.id,
+            headCommit: headCommit(context.identity.repositoryRoot),
+            generatedAt: this.now().toISOString(),
+            steps: task.steps.map((step) => ({ id: step.id, evidence: step.evidence })),
+            systemCommits: task.systemCommits,
+        }, null, 2));
+        const saved = this.store.writeTask({ ...task, status: 'validating', evidenceHash: stagedEvidence.hash, review: emptyReview(), blockReason: null }, expectedRevision);
+        this.store.publishArtifact(stagedEvidence);
+        return saved;
+    }
+    recordReview(repository, taskId, expectedRevision, review) {
+        const { identity } = this.context(repository);
+        const task = this.store.readTask(identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        const retryingUnverified = task.status === 'blocked' && task.review.status === 'unverified';
+        if (task.status !== 'validating' && !retryingUnverified) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Task ${taskId} is not ready for review.`);
+        }
+        validateReviewInput(review);
+        assertTaskBranch(identity.repositoryRoot, task);
+        if (!isClean(identity.repositoryRoot)) {
+            throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Review requires a clean Task checkout.');
+        }
+        const root = this.store.taskRoot(task.projectId, task.id);
+        const recorded = {
+            ...review,
+            recordedAt: this.now().toISOString(),
+            headCommit: headCommit(identity.repositoryRoot),
+            briefHash: this.store.hashArtifact(root, 'brief.md'),
+            planHash: this.store.hashArtifact(root, 'plan.md'),
+            evidenceHash: this.store.hashArtifact(root, 'evidence.json'),
+        };
+        const status = recorded.status === 'passed' ? 'validating' : recorded.status === 'failed' ? 'needs_fix' : 'blocked';
+        const saved = this.store.writeTask({ ...task, status, review: recorded, blockReason: recorded.status === 'passed' ? null : recorded.summary }, expectedRevision);
+        if (recorded.findings.length > 0) {
+            const file = path.join(this.store.taskRoot(task.projectId, task.id), 'findings.jsonl');
+            for (const finding of recorded.findings) {
+                appendFileSync(file, `${JSON.stringify({ ...finding, recordedAt: recorded.recordedAt })}\n`, {
+                    encoding: 'utf8',
+                    mode: 0o600,
+                });
+            }
+        }
+        return saved;
+    }
+    setTaskResult(repository, taskId, expectedRevision, summary, limitations) {
+        const { identity } = this.context(repository);
+        const task = this.store.readTask(identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        if (task.status !== 'validating' || task.review.status !== 'passed') {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Result requires a passing independent review.');
+        }
+        this.assertReviewFresh(identity.repositoryRoot, task);
+        const root = this.store.taskRoot(task.projectId, task.id);
+        const stagedResult = this.store.stageArtifact(root, 'result.md', renderResult(task, summary, limitations));
+        const saved = this.store.writeTask({ ...task, status: 'awaiting_final_acceptance', resultHash: stagedResult.hash, blockReason: null }, expectedRevision);
+        this.store.publishArtifact(stagedResult);
+        return saved;
+    }
+    acceptTask(repository, taskId, expectedRevision, actor) {
+        const { identity } = this.context(repository);
+        const task = this.store.readTask(identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        if (task.status !== 'awaiting_final_acceptance' || !task.resultHash || !task.evidenceHash) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Task ${taskId} is not ready for final acceptance.`);
+        }
+        const root = this.store.taskRoot(task.projectId, task.id);
+        assertTaskBranch(identity.repositoryRoot, task);
+        if (!isClean(identity.repositoryRoot)) {
+            throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Final acceptance requires a clean Task checkout.');
+        }
+        this.assertReviewFresh(identity.repositoryRoot, task);
+        const resultHash = this.store.hashArtifact(root, 'result.md');
+        const evidenceHash = this.store.hashArtifact(root, 'evidence.json');
+        const event = {
+            kind: 'final_acceptance',
+            decision: 'approved',
+            actor: actor.trim() || 'user',
+            recordedAt: this.now().toISOString(),
+            briefHash: task.briefHash,
+            planHash: task.planHash,
+            resultHash,
+            evidenceHash,
+            headCommit: headCommit(identity.repositoryRoot),
+            reason: '',
+        };
+        return this.store.writeTask({
+            ...task,
+            status: task.workspaceOwner === 'external' ? 'ready_to_merge' : 'merging',
+            resultHash,
+            evidenceHash,
+            authorizations: [...task.authorizations, event],
+        }, expectedRevision);
+    }
+    syncTaskBase(repository, taskId, expectedRevision) {
+        const { identity } = this.context(repository);
+        const task = this.store.readTask(identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        if (task.status !== 'merging' || task.workspaceOwner !== 'local' || !task.taskBranch || !task.baseCommit) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Base sync is available only for an accepted local Task.');
+        }
+        const currentBase = runGit(identity.repositoryRoot, ['rev-parse', task.baseBranch]);
+        if (currentBase === task.baseCommit) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Base branch has not advanced; synchronization is unnecessary.');
+        }
+        const synced = syncBaseIntoTask(identity.repositoryRoot, task.taskBranch, task.baseBranch);
+        const checks = runChecks(identity.repositoryRoot, [...new Set(task.steps.flatMap((step) => step.checks))]);
+        const failed = checks.filter((check) => !check.passed);
+        if (failed.length > 0) {
+            return this.store.writeTask({
+                ...task,
+                status: 'needs_fix',
+                baseCommit: synced.baseCommit,
+                systemCommits: [...task.systemCommits, synced.syncCommit],
+                review: emptyReview(),
+                resultHash: null,
+                blockReason: 'Checks failed after synchronizing the base branch.',
+            }, expectedRevision);
+        }
+        const root = this.store.taskRoot(task.projectId, task.id);
+        const stagedEvidence = this.store.stageArtifact(root, 'evidence.json', JSON.stringify({
+            taskId: task.id,
+            headCommit: headCommit(identity.repositoryRoot),
+            generatedAt: this.now().toISOString(),
+            reason: 'base-sync',
+            checks,
+            steps: task.steps.map((step) => ({ id: step.id, evidence: step.evidence })),
+            systemCommits: [...task.systemCommits, synced.syncCommit],
+        }, null, 2));
+        const authorizations = task.authorizations.map((authorization) => authorization.kind === 'final_acceptance' && authorization.decision === 'approved'
+            ? { ...authorization, decision: 'superseded' }
+            : authorization);
+        const saved = this.store.writeTask({
+            ...task,
+            status: 'validating',
+            baseCommit: synced.baseCommit,
+            systemCommits: [...task.systemCommits, synced.syncCommit],
+            evidenceHash: stagedEvidence.hash,
+            review: emptyReview(),
+            resultHash: null,
+            authorizations,
+            blockReason: 'Base changed; validation, review, and final acceptance must be repeated.',
+        }, expectedRevision);
+        this.store.publishArtifact(stagedEvidence);
+        return saved;
+    }
+    mergeTask(repository, taskId, expectedRevision, writerToken) {
+        const context = this.context(repository);
+        const task = this.store.readTask(context.identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        if (task.status !== 'merging' || task.workspaceOwner !== 'local' || !task.taskBranch || !task.baseCommit) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Task ${taskId} is not ready for a local merge.`);
+        }
+        const currentBase = runGit(context.identity.repositoryRoot, ['rev-parse', task.baseBranch]);
+        if (currentBase !== task.baseCommit) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Base branch advanced after Task start.', {
+                recordedBase: task.baseCommit,
+                currentBase,
+                next: 'task sync-base',
+            });
+        }
+        const mergedCommit = mergeTaskBranch(context.identity.repositoryRoot, task.taskBranch, task.baseBranch);
+        const saved = this.store.writeTask({ ...task, status: 'merged', mergedCommit, blockReason: null }, expectedRevision);
+        context.locks.release(taskId, writerToken);
+        return saved;
+    }
+    confirmExternalMerge(repository, taskId, expectedRevision, writerToken) {
+        const context = this.context(repository);
+        const task = this.store.readTask(context.identity.projectId, taskId);
+        assertExpectedRevision(task, expectedRevision);
+        if (task.status !== 'ready_to_merge' || task.workspaceOwner !== 'external') {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Task ${taskId} is not awaiting external merge confirmation.`);
+        }
+        const taskHead = finalAcceptedHead(task);
+        if (!gitIsAncestor(context.identity.repositoryRoot, taskHead, task.baseBranch)) {
+            throw new WorkflowError('GIT_PRECONDITION_FAILED', `Accepted Task head is not merged into ${task.baseBranch}.`);
+        }
+        const saved = this.store.writeTask({ ...task, status: 'merged', mergedCommit: runGit(context.identity.repositoryRoot, ['rev-parse', task.baseBranch]) }, expectedRevision);
+        context.locks.release(taskId, writerToken);
+        return saved;
+    }
+    status(repository) {
+        const { identity } = this.context(repository);
+        return {
+            projectId: identity.projectId,
+            discoveries: this.store.listDiscoveries(identity.projectId),
+            tasks: this.store.listTasks(identity.projectId),
+            milestones: this.store.listMilestones(identity.projectId),
+        };
+    }
+    scanKnowledgeMap(repository) {
+        const { identity } = this.context(repository);
+        const scanned = scanProjectKnowledge(identity.repositoryRoot, identity.projectId, this.now());
+        try {
+            const current = this.store.readKnowledgeMap(identity.projectId);
+            return inspectKnowledgeMap(current, scanned);
+        }
+        catch (error) {
+            if (!(error instanceof WorkflowError) || error.code !== 'NOT_FOUND')
+                throw error;
+            return this.store.writeKnowledgeMap(scanned, null);
+        }
+    }
+    showKnowledgeMap(repository) {
+        const { identity } = this.context(repository);
+        return this.store.readKnowledgeMap(identity.projectId);
+    }
+    knowledgeMapStatus(repository) {
+        const { identity } = this.context(repository);
+        const current = this.store.readKnowledgeMap(identity.projectId);
+        const scanned = scanProjectKnowledge(identity.repositoryRoot, identity.projectId, this.now());
+        return inspectKnowledgeMap(current, scanned);
+    }
+    approveKnowledgeMap(repository, expectedRevision, selections, actor) {
+        const { identity } = this.context(repository);
+        const current = this.store.readKnowledgeMap(identity.projectId);
+        assertExpectedRevision(current, expectedRevision);
+        const inspected = inspectKnowledgeMap(current, scanProjectKnowledge(identity.repositoryRoot, identity.projectId, this.now()));
+        const approved = applyKnowledgeSelections(inspected, selections, actor, this.now());
+        return this.store.writeKnowledgeMap(approved, expectedRevision);
+    }
+    reconcileKnowledgeMap(repository, expectedRevision) {
+        const { identity } = this.context(repository);
+        const current = this.store.readKnowledgeMap(identity.projectId);
+        assertExpectedRevision(current, expectedRevision);
+        const scanned = scanProjectKnowledge(identity.repositoryRoot, identity.projectId, this.now());
+        return this.store.writeKnowledgeMap(reconcileKnowledgeMap(current, scanned), expectedRevision);
+    }
+    graphRefreshRequest(repository, graphKind, mode = 'moderate') {
+        const { identity } = this.context(repository);
+        return createGraphRefreshRequest(identity.repositoryRoot, identity.projectId, graphKind, mode, this.now());
+    }
+    graphStatus(repository, graphKind, mode = 'moderate') {
+        const { identity } = this.context(repository);
+        const request = createGraphRefreshRequest(identity.repositoryRoot, identity.projectId, graphKind, mode, this.now());
+        const binding = this.readGraphBindingOrNull(identity.projectId, graphKind);
+        return { request, binding: binding ? inspectGraphBinding(binding, request) : null };
+    }
+    bindGraph(repository, expectedRevision, request, evidence) {
+        const { identity } = this.context(repository);
+        const currentRequest = createGraphRefreshRequest(identity.repositoryRoot, identity.projectId, request.graphKind, request.mode, this.now());
+        validateGraphRequestCurrent(request, currentRequest);
+        const existing = this.readGraphBindingOrNull(identity.projectId, request.graphKind);
+        const binding = bindGraphEvidence(identity.projectId, request, evidence, existing, this.now());
+        return this.store.writeGraphBinding(binding, expectedRevision);
+    }
+    recordGraphFallback(repository, graphKind, mode, expectedRevision, reason) {
+        const { identity } = this.context(repository);
+        const request = createGraphRefreshRequest(identity.repositoryRoot, identity.projectId, graphKind, mode, this.now());
+        const existing = this.readGraphBindingOrNull(identity.projectId, graphKind);
+        return this.store.writeGraphBinding(fallbackGraphBinding(identity.projectId, request, reason, existing, this.now()), expectedRevision);
+    }
+    next(repository) {
+        const status = this.status(repository);
+        const activeTask = status.tasks.find((task) => !['merged', 'cancelled'].includes(task.status));
+        if (activeTask)
+            return nextForTask(activeTask);
+        const activeMilestone = status.milestones.find((milestone) => !['accepted', 'cancelled'].includes(milestone.status));
+        if (activeMilestone) {
+            return {
+                scope: 'milestone',
+                id: activeMilestone.id,
+                status: activeMilestone.status,
+                action: nextForMilestone(activeMilestone),
+                revision: activeMilestone.revision,
+            };
+        }
+        const activeDiscovery = status.discoveries.find((discovery) => !['materialized', 'abandoned'].includes(discovery.status));
+        if (activeDiscovery) {
+            return {
+                scope: 'discovery',
+                id: activeDiscovery.id,
+                status: activeDiscovery.status,
+                action: activeDiscovery.status === 'ready_to_materialize' ? 'discovery materialize' : 'discovery update',
+                readiness: assessDiscovery(activeDiscovery),
+            };
+        }
+        return { scope: 'repository', status: 'idle', action: 'discovery start' };
+    }
+    assertExecutionAuthorizationFresh(task) {
+        const root = this.store.taskRoot(task.projectId, task.id);
+        const authorization = [...task.authorizations]
+            .reverse()
+            .find((event) => event.kind === 'execution' && event.decision === 'approved');
+        if (!authorization)
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Execution authorization is missing.');
+        const briefHash = this.store.hashArtifact(root, 'brief.md');
+        const planHash = this.store.hashArtifact(root, 'plan.md');
+        if (authorization.briefHash !== briefHash || authorization.planHash !== planHash) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Execution authorization is stale.', {
+                authorizedBriefHash: authorization.briefHash,
+                currentBriefHash: briefHash,
+                authorizedPlanHash: authorization.planHash,
+                currentPlanHash: planHash,
+            });
+        }
+    }
+    assertMilestoneAuthorizationFresh(milestone) {
+        const authorization = [...milestone.authorizations]
+            .reverse()
+            .find((event) => event.kind === 'execution' && event.decision === 'approved');
+        if (!authorization)
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone authorization is missing.');
+        const planHash = this.store.hashArtifact(this.store.milestoneRoot(milestone.projectId, milestone.id), 'plan.json');
+        if (authorization.planHash !== planHash || milestone.planHash !== planHash) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone authorization is stale.');
+        }
+    }
+    readGraphBindingOrNull(projectId, graphKind) {
+        try {
+            return this.store.readGraphBinding(projectId, graphKind);
+        }
+        catch (error) {
+            if (error instanceof WorkflowError && error.code === 'NOT_FOUND')
+                return null;
+            throw error;
+        }
+    }
+    requireActiveKnowledgeMap(repositoryRoot, projectId) {
+        const current = this.store.readKnowledgeMap(projectId);
+        const inspected = inspectKnowledgeMap(current, scanProjectKnowledge(repositoryRoot, projectId, this.now()));
+        if (inspected.status !== 'active' || !inspected.approval) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Project Knowledge Map is not active.', {
+                status: inspected.status,
+                gaps: inspected.gaps,
+                conflicts: inspected.conflicts,
+            });
+        }
+        return inspected;
+    }
+    assertKnowledgeMapBinding(repositoryRoot, projectId, revision, mapHash) {
+        const map = this.requireActiveKnowledgeMap(repositoryRoot, projectId);
+        const currentHash = hashKnowledgeMap(map);
+        if (map.revision !== revision || currentHash !== mapHash || map.approval?.mapHash !== currentHash) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Task Plan is bound to a stale Project Knowledge Map.', {
+                expectedRevision: revision,
+                actualRevision: map.revision,
+                expectedHash: mapHash,
+                actualHash: currentHash,
+            });
+        }
+        return map;
+    }
+    assertTaskKnowledgeBinding(repositoryRoot, task) {
+        if (task.knowledgeMapRevision === null || !task.knowledgeMapHash) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} has no Project Knowledge Map binding.`);
+        }
+        return this.assertKnowledgeMapBinding(repositoryRoot, task.projectId, task.knowledgeMapRevision, task.knowledgeMapHash);
+    }
+    validateKnowledgeTargets(map, plan) {
+        const known = new Set(map.entries.map((entry) => `${entry.category}\0${entry.path}`));
+        for (const target of plan.knowledgeTargets) {
+            const normalized = normalizeRelativePath(target.path);
+            if (normalized !== target.path) {
+                throw new WorkflowError('TRANSITION_BLOCKED', `Knowledge target path is not normalized: ${target.path}`);
+            }
+            if (plan.knowledgeImpact !== 'create' && !known.has(`${target.category}\0${target.path}`)) {
+                throw new WorkflowError('TRANSITION_BLOCKED', `Knowledge target is not present in the approved map: ${target.path}`);
+            }
+            for (const requirement of target.requirementIds) {
+                if (!plan.requirements.includes(requirement)) {
+                    throw new WorkflowError('TRANSITION_BLOCKED', `Knowledge target references unknown requirement ${requirement}.`);
+                }
+            }
+        }
+    }
+    assertReviewFresh(repositoryRoot, task) {
+        const root = this.store.taskRoot(task.projectId, task.id);
+        const current = {
+            headCommit: headCommit(repositoryRoot),
+            briefHash: this.store.hashArtifact(root, 'brief.md'),
+            planHash: this.store.hashArtifact(root, 'plan.md'),
+            evidenceHash: this.store.hashArtifact(root, 'evidence.json'),
+        };
+        const stale = Object.entries(current).filter(([key, value]) => task.review[key] !== value);
+        if (stale.length > 0) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Independent review is stale.', {
+                stale: stale.map(([key]) => key),
+            });
+        }
+    }
+}
+function emptyReview() {
+    return {
+        status: 'pending',
+        reviewer: '',
+        recordedAt: null,
+        headCommit: null,
+        briefHash: null,
+        planHash: null,
+        evidenceHash: null,
+        summary: '',
+        findings: [],
+    };
+}
+function slugify(value) {
+    const slug = value
+        .normalize('NFKD')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 40);
+    return slug || 'task';
+}
+function requireStep(task, stepId) {
+    const step = task.steps.find((candidate) => candidate.id === stepId);
+    if (!step)
+        throw new WorkflowError('NOT_FOUND', `Step not found: ${stepId}`);
+    return step;
+}
+function dependenciesComplete(step, completed) {
+    const completedIds = new Set(completed);
+    return step.dependencies.every((dependency) => completedIds.has(dependency));
+}
+function identityRelative(repositoryRoot, value) {
+    return path.resolve(repositoryRoot, value);
+}
+function finalAcceptedHead(task) {
+    const event = [...task.authorizations]
+        .reverse()
+        .find((authorization) => authorization.kind === 'final_acceptance' && authorization.decision === 'approved');
+    if (!event?.headCommit)
+        throw new WorkflowError('STATE_CORRUPT', 'Final acceptance has no head commit.');
+    return event.headCommit;
+}
+function assertExpectedRevision(record, expectedRevision) {
+    if (record.revision !== expectedRevision) {
+        throw new WorkflowError('STATE_CONFLICT', `State revision conflict for ${record.id}`, {
+            expectedRevision,
+            actualRevision: record.revision,
+        });
+    }
+}
+function assertTaskBranch(repositoryRoot, task) {
+    if (!task.taskBranch)
+        throw new WorkflowError('STATE_CORRUPT', `Task ${task.id} has no execution branch.`);
+    const branch = currentBranch(repositoryRoot);
+    if (branch !== task.taskBranch) {
+        throw new WorkflowError('GIT_PRECONDITION_FAILED', `Expected Task branch ${task.taskBranch}, found ${branch ?? 'detached HEAD'}.`);
+    }
+}
+function preserveCompletedStep(task, next) {
+    const previous = task.steps.find((candidate) => candidate.id === next.id && candidate.status === 'completed');
+    if (!previous)
+        return null;
+    const comparable = ({ status: _status, evidence: _evidence, ...definition }) => definition;
+    return JSON.stringify(comparable(previous)) === JSON.stringify(next) ? previous : null;
+}
+function validateReviewInput(review) {
+    if (!review.reviewer.trim())
+        throw new WorkflowError('INVALID_ARGUMENT', 'Review requires reviewer identity.');
+    if (!review.summary.trim())
+        throw new WorkflowError('INVALID_ARGUMENT', 'Review requires a summary.');
+    if (review.status === 'pending') {
+        throw new WorkflowError('INVALID_ARGUMENT', 'Recorded review status cannot be pending.');
+    }
+    if (review.status === 'passed' && review.findings.length > 0) {
+        throw new WorkflowError('INVALID_ARGUMENT', 'A passing review cannot contain findings.');
+    }
+    if (review.status === 'failed' && review.findings.length === 0) {
+        throw new WorkflowError('INVALID_ARGUMENT', 'A failed review requires at least one finding.');
+    }
+}
+function validateMilestonePlan(plan) {
+    if (!plan.outcome.trim())
+        throw new WorkflowError('INVALID_ARGUMENT', 'Milestone outcome is required.');
+    if (!plan.successSignal.trim())
+        throw new WorkflowError('INVALID_ARGUMENT', 'Milestone success signal is required.');
+    if (plan.acceptance.length === 0 || plan.acceptance.some((value) => !value.trim())) {
+        throw new WorkflowError('INVALID_ARGUMENT', 'Milestone acceptance must contain substantive entries.');
+    }
+    if (plan.memberships.length === 0) {
+        throw new WorkflowError('INVALID_ARGUMENT', 'Milestone requires at least one Task membership.');
+    }
+    for (const membership of plan.memberships) {
+        if (!membership.taskId.trim())
+            throw new WorkflowError('INVALID_ARGUMENT', 'Milestone membership requires Task ID.');
+        if (membership.disposition !== 'required' && !membership.reason.trim()) {
+            throw new WorkflowError('INVALID_ARGUMENT', `Milestone ${membership.disposition} membership requires a reason.`);
+        }
+    }
+    if (plan.checks.length === 0 || plan.checks.some((value) => !value.trim())) {
+        throw new WorkflowError('INVALID_ARGUMENT', 'Milestone requires at least one cross-Task check.');
+    }
+}
+function taskHasStarted(task) {
+    return task.workspaceOwner !== null || [
+        'in_progress',
+        'validating',
+        'needs_fix',
+        'awaiting_final_acceptance',
+        'merging',
+        'ready_to_merge',
+        'merged',
+    ].includes(task.status);
+}
+function nextForMilestone(milestone) {
+    const actions = {
+        planning: 'milestone plan-set',
+        awaiting_execution_authorization: 'milestone authorize',
+        active: 'complete required Tasks, then milestone validate',
+        validating: 'milestone validate',
+        awaiting_final_acceptance: 'milestone accept',
+        accepted: 'none',
+        blocked: 'milestone plan-set or milestone cancel',
+        cancelled: 'none',
+    };
+    return actions[milestone.status];
+}
+function nextForTask(task) {
+    const actionByStatus = {
+        planning: 'task plan-set',
+        awaiting_execution_authorization: 'task authorize',
+        ready: task.workspaceOwner ? 'task run' : 'task start',
+        in_progress: 'task run or task submit',
+        validating: task.review.status === 'passed' ? 'task result-set' : 'task review-record',
+        needs_fix: task.steps.some((step) => step.status === 'failed') ? 'task run' : 'task plan-set',
+        awaiting_final_acceptance: 'task accept',
+        merging: 'task merge',
+        ready_to_merge: 'task merge-confirm',
+        merged: 'none',
+        blocked: task.review.status === 'unverified' ? 'task review-record' : 'doctor',
+        cancelled: 'none',
+    };
+    return { scope: 'task', id: task.id, status: task.status, action: actionByStatus[task.status], revision: task.revision };
+}
+function knowledgeSummary(map) {
+    return {
+        revision: map.revision,
+        hash: hashKnowledgeMap(map),
+        status: map.status,
+    };
+}
+//# sourceMappingURL=workflow.js.map