codex-workflow-v2 2.0.0-alpha.2 → 2.0.0-alpha.4

package/dist/src/ulid.js.map

@@ -1 +1 @@
-{"version":3,"file":"ulid.js","sourceRoot":"","sources":["../../src/ulid.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,QAAQ,GAAG,kCAAkC,CAAC;AAEpD,SAAS,MAAM,CAAC,KAAa,EAAE,MAAc;IAC3C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC;QAChD,KAAK,KAAK,EAAE,CAAC;IACf,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACzC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAC/B,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,KAAK,MAAM,IAAI,IAAI,MAAM;QAAE,WAAW,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5E,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAA8B,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAC7E,OAAO,GAAG,MAAM,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;AACxC,CAAC"}
+{"version":3,"file":"ulid.js","sourceRoot":"","sources":["../../src/ulid.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,QAAQ,GAAG,kCAAkC,CAAC;AAEpD,SAAS,MAAM,CAAC,KAAa,EAAE,MAAc;IAC3C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC;QAChD,KAAK,KAAK,EAAE,CAAC;IACf,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACzC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAC/B,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,KAAK,MAAM,IAAI,IAAI,MAAM;QAAE,WAAW,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5E,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAsC,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACrF,OAAO,GAAG,MAAM,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;AACxC,CAAC"}

package/dist/src/version.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "codex-workflow-v2";
-export declare const PACKAGE_VERSION = "2.0.0-alpha.2";
+export declare const PACKAGE_VERSION = "2.0.0-alpha.4";

package/dist/src/version.js

@@ -1,3 +1,3 @@
 export const PACKAGE_NAME = 'codex-workflow-v2';
-export const PACKAGE_VERSION = '2.0.0-alpha.2';
+export const PACKAGE_VERSION = '2.0.0-alpha.4';
 //# sourceMappingURL=version.js.map

package/dist/src/workflow.d.ts

@@ -1,4 +1,4 @@
-import { type ContextEnvelope, type DiscoveryState, type MilestonePlanInput, type MilestoneState, type KnowledgeSelection, type GraphBinding, type GraphKind, type GraphMode, type GraphRefreshEvidence, type GraphRefreshRequest, type ProjectKnowledgeMap, type ReviewInput, type TaskPlanInput, type TaskState, type WriterLease, type WorkflowRole, type WorkspaceOwner } from './contracts.js';
+import { type ContextEnvelope, type DelegationGrant, type DelegationGrantGate, type DelegationPolicyInput, type DiscoveryState, type MilestonePlanInput, type MilestoneState, type KnowledgeSelection, type GraphBinding, type GraphKind, type GraphMode, type GraphRefreshEvidence, type GraphRefreshRequest, type ProjectKnowledgeMap, type ReviewInput, type TaskPlanInput, type TaskState, type WriterLease, type WorkflowRole, type WorkspaceOwner } from './contracts.js';
 import { type RepositoryIdentity } from './repository.js';
 import { WriterLockManager } from './state/lock.js';
 import { FileStateStore } from './state/store.js';
@@ -29,6 +29,9 @@ export declare class WorkflowService {
     private readonly now;
     constructor(store?: FileStateStore, now?: () => Date);
     context(repository: string): WorkflowContext;
+    prepareDelegation(repository: string, input: DelegationPolicyInput): DelegationGrantGate;
+    grantDelegation(repository: string, input: DelegationPolicyInput, confirmationCode: string): DelegationGrant;
+    revokeDelegation(repository: string, grantId: string, expectedRevision: number, actor: string, reason: string): DelegationGrant;
     startDiscovery(repository: string, input: DiscoveryInput): DiscoveryState;
     updateDiscovery(repository: string, discoveryId: string, expectedRevision: number, patch: DiscoveryPatch): DiscoveryState;
     materializeTask(repository: string, discoveryId: string, expectedRevision: number, title: string, baseBranch?: string, milestoneId?: string | null): {
@@ -42,13 +45,13 @@ export declare class WorkflowService {
         milestoneRoot: string;
     };
     setMilestonePlan(repository: string, milestoneId: string, expectedRevision: number, plan: MilestonePlanInput): MilestoneState;
-    authorizeMilestone(repository: string, milestoneId: string, expectedRevision: number, actor: string, reason?: string): MilestoneState;
+    authorizeMilestone(repository: string, milestoneId: string, expectedRevision: number, actor: string, reason?: string, delegationGrantId?: string | null): MilestoneState;
     validateMilestone(repository: string, milestoneId: string, expectedRevision: number): MilestoneState;
-    acceptMilestone(repository: string, milestoneId: string, expectedRevision: number, actor: string): MilestoneState;
+    acceptMilestone(repository: string, milestoneId: string, expectedRevision: number, actor: string, confirmationCode: string, delegationGrantId?: string | null): MilestoneState;
     cancelMilestone(repository: string, milestoneId: string, expectedRevision: number, reason: string): MilestoneState;
     setTaskPlan(repository: string, taskId: string, expectedRevision: number, plan: TaskPlanInput): TaskState;
     rebindTaskKnowledge(repository: string, taskId: string, expectedRevision: number): TaskState;
-    authorizeTask(repository: string, taskId: string, expectedRevision: number, actor: string, reason?: string): TaskState;
+    authorizeTask(repository: string, taskId: string, expectedRevision: number, actor: string, reason?: string, delegationGrantId?: string | null): TaskState;
     startTask(repository: string, taskId: string, expectedRevision: number, workspaceOwner: WorkspaceOwner): TaskState;
     runStep(repository: string, taskId: string, stepId: string, expectedRevision: number, owner: string, writerToken: string | null): {
         task: TaskState;
@@ -60,7 +63,7 @@ export declare class WorkflowService {
     submitTask(repository: string, taskId: string, expectedRevision: number, writerToken: string): TaskState;
     recordReview(repository: string, taskId: string, expectedRevision: number, review: ReviewInput): TaskState;
     setTaskResult(repository: string, taskId: string, expectedRevision: number, summary: string, limitations: string[]): TaskState;
-    acceptTask(repository: string, taskId: string, expectedRevision: number, actor: string): TaskState;
+    acceptTask(repository: string, taskId: string, expectedRevision: number, actor: string, delegationGrantId?: string | null): TaskState;
     syncTaskBase(repository: string, taskId: string, expectedRevision: number): TaskState;
     mergeTask(repository: string, taskId: string, expectedRevision: number, writerToken: string): TaskState;
     confirmExternalMerge(repository: string, taskId: string, expectedRevision: number, writerToken: string): TaskState;
@@ -69,11 +72,12 @@ export declare class WorkflowService {
         discoveries: DiscoveryState[];
         tasks: TaskState[];
         milestones: MilestoneState[];
+        delegations: DelegationGrant[];
     };
     scanKnowledgeMap(repository: string): ProjectKnowledgeMap;
     showKnowledgeMap(repository: string): ProjectKnowledgeMap;
     knowledgeMapStatus(repository: string): ProjectKnowledgeMap;
-    approveKnowledgeMap(repository: string, expectedRevision: number, selections: KnowledgeSelection[], actor: string): ProjectKnowledgeMap;
+    approveKnowledgeMap(repository: string, expectedRevision: number, selections: KnowledgeSelection[], actor: string, delegationGrantId?: string | null): ProjectKnowledgeMap;
     reconcileKnowledgeMap(repository: string, expectedRevision: number): ProjectKnowledgeMap;
     graphRefreshRequest(repository: string, graphKind: GraphKind, mode?: GraphMode): GraphRefreshRequest;
     graphStatus(repository: string, graphKind: GraphKind, mode?: GraphMode): {
@@ -83,6 +87,10 @@ export declare class WorkflowService {
     bindGraph(repository: string, expectedRevision: number | null, request: GraphRefreshRequest, evidence: GraphRefreshEvidence): GraphBinding;
     recordGraphFallback(repository: string, graphKind: GraphKind, mode: GraphMode, expectedRevision: number | null, reason: string): GraphBinding;
     next(repository: string): Record<string, unknown>;
+    private delegatedAuthorization;
+    private nextForTaskWithDelegation;
+    private delegatedApprovalOptions;
+    private assertDelegationScopeExists;
     private assertExecutionAuthorizationFresh;
     private assertMilestoneAuthorizationFresh;
     private readGraphBindingOrNull;

package/dist/src/workflow.js

@@ -1,7 +1,9 @@
 import { appendFileSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { PROTOCOL_VERSION, STATE_SCHEMA_VERSION, } from './contracts.js';
 import { renderBrief, renderPlan, renderResult } from './artifacts.js';
+import { assertDelegationCanAuthorize, delegationCanAuthorize, prepareDelegationGrantGate, } from './delegation.js';
 import { assessDiscovery, mergeUnique } from './domain/discovery.js';
 import { pathAllowed, validatePlan } from './domain/validation.js';
 import { WorkflowError } from './errors.js';
@@ -29,6 +31,70 @@ export class WorkflowService {
             locks: new WriterLockManager(this.store.lockRoot(identity.projectId), this.now),
         };
     }
+    prepareDelegation(repository, input) {
+        const { identity } = this.context(repository);
+        const gate = prepareDelegationGrantGate(identity.projectId, input, this.now());
+        this.assertDelegationScopeExists(identity.projectId, gate.policy);
+        return gate;
+    }
+    grantDelegation(repository, input, confirmationCode) {
+        const { identity } = this.context(repository);
+        const gate = prepareDelegationGrantGate(identity.projectId, input, this.now());
+        this.assertDelegationScopeExists(identity.projectId, gate.policy);
+        if (confirmationCode.trim() !== gate.confirmationCode) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Delegation confirmation does not match the exact project and policy.', { projectId: identity.projectId, policyHash: gate.policyHash });
+        }
+        const duplicate = this.store.listDelegations(identity.projectId)
+            .find((grant) => grant.policyHash === gate.policyHash);
+        if (duplicate) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'This exact delegation policy was already issued.', {
+                grantId: duplicate.id,
+                status: duplicate.status,
+            });
+        }
+        const timestamp = this.now().toISOString();
+        return this.store.writeDelegation({
+            schemaVersion: STATE_SCHEMA_VERSION,
+            revision: 0,
+            id: createEntityId('DGR', this.now().getTime()),
+            projectId: identity.projectId,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            kind: 'delegation-grant',
+            status: 'active',
+            principal: gate.policy.principal,
+            delegate: gate.policy.delegate,
+            scope: gate.policy.scope,
+            transitions: gate.policy.transitions,
+            expiresAt: gate.policy.expiresAt,
+            policyHash: gate.policyHash,
+            revokedAt: null,
+            revokedBy: null,
+            revokeReason: null,
+        }, null);
+    }
+    revokeDelegation(repository, grantId, expectedRevision, actor, reason) {
+        const { identity } = this.context(repository);
+        const grant = this.store.readDelegation(identity.projectId, grantId);
+        assertExpectedRevision(grant, expectedRevision);
+        if (grant.status !== 'active') {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Delegation ${grantId} is already ${grant.status}.`);
+        }
+        if (actor.trim() !== grant.principal) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Only the recorded principal may revoke a delegation.', {
+                principal: grant.principal,
+            });
+        }
+        if (!reason.trim())
+            throw new WorkflowError('INVALID_ARGUMENT', 'Delegation revocation requires a reason.');
+        return this.store.writeDelegation({
+            ...grant,
+            status: 'revoked',
+            revokedAt: this.now().toISOString(),
+            revokedBy: grant.principal,
+            revokeReason: reason.trim(),
+        }, expectedRevision);
+    }
     startDiscovery(repository, input) {
         if (!input.goal.trim())
             throw new WorkflowError('INVALID_ARGUMENT', 'Discovery requires a substantive goal.');
@@ -265,7 +331,7 @@ export class WorkflowService {
         this.store.publishArtifact(stagedPlan);
         return saved;
     }
-    authorizeMilestone(repository, milestoneId, expectedRevision, actor, reason = '') {
+    authorizeMilestone(repository, milestoneId, expectedRevision, actor, reason = '', delegationGrantId = null) {
         const { identity } = this.context(repository);
         const milestone = this.store.readMilestone(identity.projectId, milestoneId);
         assertExpectedRevision(milestone, expectedRevision);
@@ -277,6 +343,7 @@ export class WorkflowService {
         if (planHash !== milestone.planHash) {
             throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone Plan changed after it was recorded.');
         }
+        const delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'milestone.execution_authorize', actor, milestone);
         const event = {
             kind: 'execution',
             decision: 'approved',
@@ -288,6 +355,8 @@ export class WorkflowService {
             evidenceHash: null,
             headCommit: runGit(identity.repositoryRoot, ['rev-parse', milestone.baseBranch]),
             reason,
+            authorizationMode: delegation ? 'delegated' : 'human',
+            ...(delegation ? { delegation } : {}),
         };
         return this.store.writeMilestone({ ...milestone, status: 'active', planHash, authorizations: [...milestone.authorizations, event] }, expectedRevision);
     }
@@ -295,8 +364,8 @@ export class WorkflowService {
         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.`);
+        if (!['active', 'awaiting_final_acceptance'].includes(milestone.status)) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${milestoneId} cannot be validated while ${milestone.status}.`);
         }
         this.assertMilestoneAuthorizationFresh(milestone);
         if (currentBranch(identity.repositoryRoot) !== milestone.baseBranch || !isClean(identity.repositoryRoot)) {
@@ -354,7 +423,7 @@ export class WorkflowService {
         this.store.publishArtifact(stagedResult);
         return saved;
     }
-    acceptMilestone(repository, milestoneId, expectedRevision, actor) {
+    acceptMilestone(repository, milestoneId, expectedRevision, actor, confirmationCode, delegationGrantId = null) {
         const { identity } = this.context(repository);
         const milestone = this.store.readMilestone(identity.projectId, milestoneId);
         assertExpectedRevision(milestone, expectedRevision);
@@ -372,17 +441,31 @@ export class WorkflowService {
         if (evidence.headCommit !== currentHead || resultHash !== milestone.resultHash || evidenceHash !== milestone.evidenceHash) {
             throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone validation evidence is stale.');
         }
+        const normalizedActor = actor.trim();
+        if (!normalizedActor) {
+            throw new WorkflowError('INVALID_ARGUMENT', 'Milestone final acceptance requires an explicit actor.');
+        }
+        const gate = milestoneFinalAcceptanceGate(milestone, currentHead);
+        if (confirmationCode.trim() !== gate.confirmationCode) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone final acceptance confirmation does not match the current validated state.', {
+                milestoneId,
+                revision: milestone.revision,
+            });
+        }
+        const delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'milestone.final_accept', normalizedActor, milestone);
         const event = {
             kind: 'final_acceptance',
             decision: 'approved',
-            actor: actor.trim() || 'user',
+            actor: normalizedActor,
             recordedAt: this.now().toISOString(),
             briefHash: null,
             planHash: milestone.planHash,
             resultHash,
             evidenceHash,
             headCommit: currentHead,
-            reason: '',
+            reason: `Confirmed with ${gate.confirmationCode}.`,
+            authorizationMode: delegation ? 'delegated' : 'human',
+            ...(delegation ? { delegation } : {}),
         };
         return this.store.writeMilestone({
             ...milestone,
@@ -547,7 +630,7 @@ export class WorkflowService {
         this.store.publishArtifact(stagedPlan);
         return saved;
     }
-    authorizeTask(repository, taskId, expectedRevision, actor, reason = '') {
+    authorizeTask(repository, taskId, expectedRevision, actor, reason = '', delegationGrantId = null) {
         const { identity } = this.context(repository);
         const task = this.store.readTask(identity.projectId, taskId);
         assertExpectedRevision(task, expectedRevision);
@@ -558,6 +641,7 @@ export class WorkflowService {
         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 delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'task.execution_authorize', actor, task);
         const event = {
             kind: 'execution',
             decision: 'approved',
@@ -569,6 +653,8 @@ export class WorkflowService {
             evidenceHash: null,
             headCommit: null,
             reason,
+            authorizationMode: delegation ? 'delegated' : 'human',
+            ...(delegation ? { delegation } : {}),
         };
         return this.store.writeTask({ ...task, status: 'ready', briefHash, planHash, authorizations: [...task.authorizations, event] }, expectedRevision);
     }
@@ -883,7 +969,7 @@ export class WorkflowService {
         this.store.publishArtifact(stagedResult);
         return saved;
     }
-    acceptTask(repository, taskId, expectedRevision, actor) {
+    acceptTask(repository, taskId, expectedRevision, actor, delegationGrantId = null) {
         const { identity } = this.context(repository);
         const task = this.store.readTask(identity.projectId, taskId);
         assertExpectedRevision(task, expectedRevision);
@@ -898,6 +984,7 @@ export class WorkflowService {
         this.assertReviewFresh(identity.repositoryRoot, task);
         const resultHash = this.store.hashArtifact(root, 'result.md');
         const evidenceHash = this.store.hashArtifact(root, 'evidence.json');
+        const delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'task.final_accept', actor, task);
         const event = {
             kind: 'final_acceptance',
             decision: 'approved',
@@ -909,6 +996,8 @@ export class WorkflowService {
             evidenceHash,
             headCommit: headCommit(identity.repositoryRoot),
             reason: '',
+            authorizationMode: delegation ? 'delegated' : 'human',
+            ...(delegation ? { delegation } : {}),
         };
         return this.store.writeTask({
             ...task,
@@ -1012,6 +1101,7 @@ export class WorkflowService {
             discoveries: this.store.listDiscoveries(identity.projectId),
             tasks: this.store.listTasks(identity.projectId),
             milestones: this.store.listMilestones(identity.projectId),
+            delegations: this.store.listDelegations(identity.projectId),
         };
     }
     scanKnowledgeMap(repository) {
@@ -1037,12 +1127,21 @@ export class WorkflowService {
         const scanned = scanProjectKnowledge(identity.repositoryRoot, identity.projectId, this.now());
         return inspectKnowledgeMap(current, scanned);
     }
-    approveKnowledgeMap(repository, expectedRevision, selections, actor) {
+    approveKnowledgeMap(repository, expectedRevision, selections, actor, delegationGrantId = null) {
         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 delegation = this.delegatedAuthorization(identity.projectId, delegationGrantId, 'project_memory.approve', actor, inspected);
         const approved = applyKnowledgeSelections(inspected, selections, actor, this.now());
+        if (!approved.approval) {
+            throw new WorkflowError('STATE_CORRUPT', 'Knowledge Map approval was not recorded.');
+        }
+        approved.approval = {
+            ...approved.approval,
+            authorizationMode: delegation ? 'delegated' : 'human',
+            ...(delegation ? { delegation } : {}),
+        };
         return this.store.writeKnowledgeMap(approved, expectedRevision);
     }
     reconcileKnowledgeMap(repository, expectedRevision) {
@@ -1078,19 +1177,26 @@ export class WorkflowService {
     }
     next(repository) {
         const status = this.status(repository);
-        const activeTask = status.tasks.find((task) => !['merged', 'cancelled'].includes(task.status));
+        const repositoryRoot = resolveRepositoryIdentity(repository).repositoryRoot;
+        const milestonesById = new Map(status.milestones.map((milestone) => [milestone.id, milestone]));
+        const activeTask = status.tasks.find((task) => taskIsActionableFromRepositoryNext(task, milestonesById));
         if (activeTask) {
             if (!taskCanRebindKnowledge(activeTask) && activeTask.status !== 'planning') {
-                return nextForTask(activeTask);
+                return this.nextForTaskWithDelegation(status.projectId, activeTask);
             }
             const knowledgeMap = this.knowledgeMapStatus(repository);
             if (knowledgeMap.status !== 'active' || !knowledgeMap.approval) {
+                const action = knowledgeMap.status === 'stale' ? 'project-memory reconcile' : 'project-memory approve';
+                const delegatedApprovalOptions = action === 'project-memory approve'
+                    ? this.delegatedApprovalOptions(status.projectId, 'project_memory.approve', knowledgeMap)
+                    : [];
                 return {
                     scope: 'project-memory',
                     status: knowledgeMap.status,
-                    action: knowledgeMap.status === 'stale' ? 'project-memory reconcile' : 'project-memory approve',
+                    action,
                     revision: knowledgeMap.revision,
                     taskId: activeTask.id,
+                    ...(delegatedApprovalOptions.length > 0 ? { delegatedApprovalOptions } : {}),
                 };
             }
             const knowledgeMapHash = hashKnowledgeMap(knowledgeMap);
@@ -1108,16 +1214,56 @@ export class WorkflowService {
                     knowledgeMapHash,
                 };
             }
-            return nextForTask(activeTask);
+            return this.nextForTaskWithDelegation(status.projectId, activeTask);
         }
         const activeMilestone = status.milestones.find((milestone) => !['accepted', 'cancelled'].includes(milestone.status));
         if (activeMilestone) {
+            if (activeMilestone.status === 'awaiting_final_acceptance') {
+                const root = this.store.milestoneRoot(activeMilestone.projectId, activeMilestone.id);
+                const evidence = JSON.parse(readFileSync(path.join(root, 'evidence.json'), 'utf8'));
+                if (!evidence.headCommit || !activeMilestone.resultHash || !activeMilestone.evidenceHash) {
+                    throw new WorkflowError('STATE_CORRUPT', `Milestone ${activeMilestone.id} has incomplete final evidence.`);
+                }
+                const currentHead = headCommit(repositoryRoot);
+                const resultHash = this.store.hashArtifact(root, 'result.md');
+                const evidenceHash = this.store.hashArtifact(root, 'evidence.json');
+                if (currentBranch(repositoryRoot) !== activeMilestone.baseBranch ||
+                    !isClean(repositoryRoot) ||
+                    evidence.headCommit !== currentHead ||
+                    resultHash !== activeMilestone.resultHash ||
+                    evidenceHash !== activeMilestone.evidenceHash) {
+                    return {
+                        scope: 'milestone',
+                        id: activeMilestone.id,
+                        status: activeMilestone.status,
+                        action: 'restore clean base, then milestone validate',
+                        revision: activeMilestone.revision,
+                        reason: 'final validation evidence is stale',
+                    };
+                }
+                const delegatedApprovalOptions = this.delegatedApprovalOptions(status.projectId, 'milestone.final_accept', activeMilestone);
+                return {
+                    scope: 'milestone',
+                    id: activeMilestone.id,
+                    status: activeMilestone.status,
+                    action: delegatedApprovalOptions.length > 0
+                        ? 'milestone accept using delegated approval or await explicit human final acceptance'
+                        : 'await explicit human final acceptance',
+                    revision: activeMilestone.revision,
+                    requiredHumanGate: milestoneFinalAcceptanceGate(activeMilestone, evidence.headCommit),
+                    ...(delegatedApprovalOptions.length > 0 ? { delegatedApprovalOptions } : {}),
+                };
+            }
+            const delegatedApprovalOptions = activeMilestone.status === 'awaiting_execution_authorization'
+                ? this.delegatedApprovalOptions(status.projectId, 'milestone.execution_authorize', activeMilestone)
+                : [];
             return {
                 scope: 'milestone',
                 id: activeMilestone.id,
                 status: activeMilestone.status,
                 action: nextForMilestone(activeMilestone),
                 revision: activeMilestone.revision,
+                ...(delegatedApprovalOptions.length > 0 ? { delegatedApprovalOptions } : {}),
             };
         }
         const activeDiscovery = status.discoveries.find((discovery) => !['materialized', 'abandoned'].includes(discovery.status));
@@ -1132,6 +1278,51 @@ export class WorkflowService {
         }
         return { scope: 'repository', status: 'idle', action: 'discovery start' };
     }
+    delegatedAuthorization(projectId, grantId, transition, actor, target) {
+        if (!grantId) {
+            if (actor.trim().startsWith('agent:')) {
+                throw new WorkflowError('TRANSITION_BLOCKED', 'An agent actor requires an explicit delegated approval grant.');
+            }
+            return null;
+        }
+        const grant = this.store.readDelegation(projectId, grantId);
+        return assertDelegationCanAuthorize(grant, transition, actor, target, this.now());
+    }
+    nextForTaskWithDelegation(projectId, task) {
+        const transition = task.status === 'awaiting_execution_authorization'
+            ? 'task.execution_authorize'
+            : task.status === 'awaiting_final_acceptance'
+                ? 'task.final_accept'
+                : null;
+        const delegatedApprovalOptions = transition
+            ? this.delegatedApprovalOptions(projectId, transition, task)
+            : [];
+        return {
+            ...nextForTask(task),
+            ...(delegatedApprovalOptions.length > 0 ? { delegatedApprovalOptions } : {}),
+        };
+    }
+    delegatedApprovalOptions(projectId, transition, target) {
+        return this.store.listDelegations(projectId)
+            .filter((grant) => delegationCanAuthorize(grant, transition, target, this.now()))
+            .map((grant) => ({
+            grantId: grant.id,
+            principal: grant.principal,
+            delegate: grant.delegate,
+            transition,
+            scope: grant.scope,
+            expiresAt: grant.expiresAt,
+            policyHash: grant.policyHash,
+        }));
+    }
+    assertDelegationScopeExists(projectId, policy) {
+        if (policy.scope.kind === 'task') {
+            this.store.readTask(projectId, policy.scope.id);
+            return;
+        }
+        if (policy.scope.kind === 'milestone')
+            this.store.readMilestone(projectId, policy.scope.id);
+    }
     assertExecutionAuthorizationFresh(task) {
         const root = this.store.taskRoot(task.projectId, task.id);
         const authorization = [...task.authorizations]
@@ -1363,13 +1554,50 @@ function taskCanRebindKnowledge(task) {
         'awaiting_final_acceptance',
     ].includes(task.status);
 }
+function taskIsActionableFromRepositoryNext(task, milestonesById) {
+    if (task.status === 'merged' || task.status === 'cancelled')
+        return false;
+    if (!task.milestoneId)
+        return true;
+    const milestone = milestonesById.get(task.milestoneId);
+    if (!milestone)
+        return false;
+    if (taskHasStarted(task))
+        return !['accepted', 'cancelled'].includes(milestone.status);
+    const membership = milestone.memberships.find((candidate) => candidate.taskId === task.id);
+    return milestone.status === 'active' && membership?.disposition === 'required';
+}
+function milestoneFinalAcceptanceGate(milestone, headCommit) {
+    if (!milestone.resultHash || !milestone.evidenceHash) {
+        throw new WorkflowError('STATE_CORRUPT', `Milestone ${milestone.id} has no final acceptance artifacts.`);
+    }
+    const binding = [
+        'milestone-final-acceptance-v1',
+        milestone.id,
+        String(milestone.revision),
+        milestone.planHash ?? '',
+        milestone.resultHash,
+        milestone.evidenceHash,
+        headCommit,
+    ].join('\0');
+    return {
+        kind: 'milestone_final_acceptance',
+        milestoneId: milestone.id,
+        revision: milestone.revision,
+        planHash: milestone.planHash,
+        resultHash: milestone.resultHash,
+        evidenceHash: milestone.evidenceHash,
+        headCommit,
+        confirmationCode: `MSA-${createHash('sha256').update(binding).digest('hex').slice(0, 24).toUpperCase()}`,
+    };
+}
 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',
+        awaiting_final_acceptance: 'await explicit human final acceptance',
         accepted: 'none',
         blocked: 'milestone plan-set or milestone cancel',
         cancelled: 'none',