codex-workflow-v2 2.0.0-alpha.1

package/dist/src/contracts.d.ts

@@ -0,0 +1,313 @@
+export declare const STATE_SCHEMA_VERSION: 1;
+export declare const PROTOCOL_VERSION: 1;
+export type DiscoveryStatus = 'needs_discovery' | 'needs_clarification' | 'ready_to_materialize' | 'materialized' | 'abandoned';
+export type TaskStatus = 'planning' | 'awaiting_execution_authorization' | 'ready' | 'in_progress' | 'validating' | 'needs_fix' | 'awaiting_final_acceptance' | 'merging' | 'ready_to_merge' | 'merged' | 'blocked' | 'cancelled';
+export type MilestoneStatus = 'planning' | 'awaiting_execution_authorization' | 'active' | 'validating' | 'awaiting_final_acceptance' | 'accepted' | 'blocked' | 'cancelled';
+export type StepStatus = 'planned' | 'in_progress' | 'completed' | 'failed' | 'blocked' | 'skipped';
+export type WorkspaceOwner = 'local' | 'external';
+export type ReviewStatus = 'pending' | 'passed' | 'failed' | 'unverified';
+export type AuthorizationKind = 'execution' | 'final_acceptance' | 'exception';
+export type KnowledgeImpact = 'none' | 'update' | 'create' | 'retire';
+export type GraphUse = 'code-aware' | 'not-applicable';
+export type GraphKind = 'product' | 'workflow';
+export type GraphMode = 'moderate' | 'full';
+export type GraphBindingStatus = 'ready' | 'stale' | 'unavailable' | 'fallback';
+export type KnowledgeCategory = 'agent-guidance' | 'onboarding' | 'architecture' | 'decisions' | 'commands' | 'ownership' | 'testing' | 'operations' | 'domain';
+export type KnowledgeAuthority = 'canonical' | 'supporting';
+export type KnowledgeMapStatus = 'draft' | 'awaiting_approval' | 'active' | 'stale' | 'conflicted';
+export type WorkflowRole = 'scope-lead' | 'technical-planner' | 'delivery-coordinator' | 'worker' | 'independent-reviewer';
+export interface RevisionedRecord {
+    schemaVersion: typeof STATE_SCHEMA_VERSION;
+    revision: number;
+    id: string;
+    projectId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface DiscoveryState extends RevisionedRecord {
+    kind: 'discovery';
+    status: DiscoveryStatus;
+    goal: string;
+    outcome: string | null;
+    facts: string[];
+    decisions: string[];
+    assumptions: string[];
+    unknowns: string[];
+    blockingUnknowns: string[];
+    scope: string[];
+    outOfScope: string[];
+    constraints: string[];
+    acceptance: string[];
+    materializedEntityId: string | null;
+}
+export interface PlanStepInput {
+    id: string;
+    title: string;
+    objective: string;
+    requirements: string[];
+    dependencies: string[];
+    expectedOutputs: string[];
+    allowedWrites: string[];
+    forbiddenScope: string[];
+    checks: string[];
+}
+export interface TaskPlanInput {
+    objective: string;
+    requirements: string[];
+    acceptance: string[];
+    risks: string[];
+    knowledgeImpact: KnowledgeImpact;
+    knowledgeImpactReason: string;
+    knowledgeTargets: KnowledgeTarget[];
+    knowledgeMapRevision: number;
+    knowledgeMapHash: string;
+    graphUse: GraphUse;
+    steps: PlanStepInput[];
+}
+export interface KnowledgeTarget {
+    category: KnowledgeCategory;
+    path: string;
+    reason: string;
+    requirementIds: string[];
+}
+export interface KnowledgeSource {
+    id: string;
+    category: KnowledgeCategory;
+    path: string;
+    scope: string;
+    authority: KnowledgeAuthority;
+    contentHash: string;
+    discoveredBy: string;
+    lastVerifiedAt: string;
+}
+export interface KnowledgeGap {
+    category: KnowledgeCategory;
+    scope: string;
+    reason: string;
+}
+export interface KnowledgeConflict {
+    category: KnowledgeCategory;
+    scope: string;
+    sourceIds: string[];
+    reason: string;
+}
+export interface KnowledgeMapApproval {
+    mapHash: string;
+    actor: string;
+    approvedAt: string;
+}
+export interface ProjectKnowledgeMap extends RevisionedRecord {
+    kind: 'knowledge-map';
+    status: KnowledgeMapStatus;
+    entries: KnowledgeSource[];
+    gaps: KnowledgeGap[];
+    conflicts: KnowledgeConflict[];
+    approval: KnowledgeMapApproval | null;
+}
+export interface GraphBindingSnapshot {
+    projectKey: string | null;
+    rootFingerprint: string;
+    indexedHead: string | null;
+    packageVersion: string | null;
+    manifestHash: string | null;
+    mode: GraphMode;
+    status: GraphBindingStatus;
+    nodeCount: number | null;
+    edgeCount: number | null;
+    observedAt: string;
+    evidenceHash: string;
+    fallbackReason: string | null;
+}
+export interface GraphBinding extends RevisionedRecord, GraphBindingSnapshot {
+    kind: 'graph-binding';
+    graphKind: GraphKind;
+    provider: 'codebase-memory-mcp';
+    previous: GraphBindingSnapshot | null;
+}
+export interface GraphRefreshRequest {
+    protocolVersion: typeof PROTOCOL_VERSION;
+    requestId: string;
+    projectId: string;
+    graphKind: GraphKind;
+    sourceRoot: string;
+    rootFingerprint: string;
+    indexedHead: string | null;
+    packageVersion: string | null;
+    manifestHash: string | null;
+    mode: GraphMode;
+    persistence: false;
+    issuedAt: string;
+}
+export interface GraphRefreshEvidence {
+    requestId: string;
+    provider: 'codebase-memory-mcp';
+    projectKey: string;
+    rootFingerprint: string;
+    indexedHead: string | null;
+    packageVersion: string | null;
+    manifestHash: string | null;
+    mode: GraphMode;
+    status: 'ready' | 'stale' | 'unavailable';
+    nodeCount: number | null;
+    edgeCount: number | null;
+    observedAt: string;
+}
+export interface KnowledgeSelection {
+    sourceId: string;
+    authority: KnowledgeAuthority;
+}
+export interface StepEvidence {
+    recordedAt: string;
+    commitSha: string;
+    changedFiles: string[];
+    checks: Array<{
+        command: string;
+        passed: boolean;
+        exitCode: number;
+        output: string;
+    }>;
+    notes: string[];
+}
+export interface TaskStep extends PlanStepInput {
+    status: StepStatus;
+    evidence: StepEvidence | null;
+}
+export interface AuthorizationEvent {
+    kind: AuthorizationKind;
+    decision: 'approved' | 'rejected' | 'waived' | 'superseded';
+    actor: string;
+    recordedAt: string;
+    briefHash: string | null;
+    planHash: string | null;
+    resultHash: string | null;
+    evidenceHash: string | null;
+    headCommit: string | null;
+    reason: string;
+}
+export interface ReviewRecord {
+    status: ReviewStatus;
+    reviewer: string;
+    recordedAt: string | null;
+    headCommit: string | null;
+    briefHash: string | null;
+    planHash: string | null;
+    evidenceHash: string | null;
+    summary: string;
+    findings: Array<{
+        id: string;
+        severity: 'critical' | 'major' | 'minor';
+        requirement: string | null;
+        summary: string;
+        evidence: string;
+        requiredAction: string;
+    }>;
+}
+export type ReviewInput = Pick<ReviewRecord, 'status' | 'reviewer' | 'summary' | 'findings'>;
+export interface TaskState extends RevisionedRecord {
+    kind: 'task';
+    status: TaskStatus;
+    title: string;
+    slug: string;
+    discoveryId: string;
+    milestoneId: string | null;
+    repositoryRoot: string;
+    baseBranch: string;
+    baseCommit: string | null;
+    taskBranch: string | null;
+    workspaceOwner: WorkspaceOwner | null;
+    briefHash: string;
+    planHash: string | null;
+    resultHash: string | null;
+    evidenceHash: string | null;
+    requirements: string[];
+    acceptance: string[];
+    risks: string[];
+    knowledgeImpact: KnowledgeImpact | null;
+    knowledgeImpactReason: string | null;
+    knowledgeTargets: KnowledgeTarget[];
+    knowledgeMapRevision: number | null;
+    knowledgeMapHash: string | null;
+    graphUse: GraphUse | null;
+    steps: TaskStep[];
+    authorizations: AuthorizationEvent[];
+    review: ReviewRecord;
+    blockReason: string | null;
+    mergedCommit: string | null;
+    systemCommits: string[];
+}
+export interface MilestoneState extends RevisionedRecord {
+    kind: 'milestone';
+    status: MilestoneStatus;
+    title: string;
+    discoveryId: string;
+    outcome: string;
+    successSignal: string;
+    acceptance: string[];
+    baseBranch: string;
+    taskIds: string[];
+    memberships: MilestoneMembership[];
+    checks: string[];
+    membershipRevision: number;
+    authorizations: AuthorizationEvent[];
+    planHash: string | null;
+    resultHash: string | null;
+    evidenceHash: string | null;
+    acceptedHead: string | null;
+    cancellationReason: string | null;
+}
+export interface MilestoneMembership {
+    taskId: string;
+    disposition: 'required' | 'waived' | 'cancelled';
+    reason: string;
+}
+export interface MilestonePlanInput {
+    outcome: string;
+    successSignal: string;
+    acceptance: string[];
+    memberships: MilestoneMembership[];
+    checks: string[];
+}
+export interface ProjectRecord {
+    schemaVersion: typeof STATE_SCHEMA_VERSION;
+    projectId: string;
+    gitCommonDir: string;
+    repositoryRoots: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface WriterLease {
+    schemaVersion: typeof STATE_SCHEMA_VERSION;
+    entityId: string;
+    token: string;
+    owner: string;
+    pid: number;
+    hostname: string;
+    acquiredAt: string;
+    heartbeatAt: string;
+    expiresAt: string;
+}
+export interface ContextEnvelope {
+    protocolVersion: typeof PROTOCOL_VERSION;
+    packageVersion: string;
+    role: WorkflowRole;
+    objective: string;
+    inputs: string[];
+    allowedReads: string[];
+    allowedWrites: string[];
+    commands: string[];
+    forbiddenScope: string[];
+    resultSchema: Record<string, unknown>;
+    stopConditions: string[];
+    contextBudget: 'small' | 'medium' | 'large';
+    taskId: string;
+    stepId: string;
+    expectedRevision: number;
+    writerToken: string | null;
+    knowledgeMap: {
+        revision: number;
+        hash: string;
+        status: KnowledgeMapStatus;
+    };
+    knowledgeSources: string[];
+}
+export type EntityState = DiscoveryState | TaskState | MilestoneState | ProjectKnowledgeMap | GraphBinding;

package/dist/src/contracts.js

@@ -0,0 +1,3 @@
+export const STATE_SCHEMA_VERSION = 1;
+export const PROTOCOL_VERSION = 1;
+//# sourceMappingURL=contracts.js.map

package/dist/src/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/contracts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAU,CAAC;AAC/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAU,CAAC"}

package/dist/src/diagnostics.d.ts

@@ -0,0 +1,19 @@
+export interface DependencyDiagnostic {
+    packageFile: string;
+    declared: string | null;
+    exact: boolean;
+    current: boolean;
+}
+export declare function inspectLocalDependency(repositoryRoot: string): DependencyDiagnostic;
+export declare function integrationDiagnostics(repositoryRoot: string): {
+    package: {
+        name: string;
+        version: string;
+    };
+    localDependency: DependencyDiagnostic;
+    graphView: {
+        present: boolean;
+        current: boolean;
+        root: string;
+    };
+};

package/dist/src/diagnostics.js

@@ -0,0 +1,25 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { inspectGraphView } from './graph.js';
+import { PACKAGE_NAME, PACKAGE_VERSION } from './version.js';
+export function inspectLocalDependency(repositoryRoot) {
+    const packageFile = path.join(repositoryRoot, 'package.json');
+    if (!existsSync(packageFile))
+        return { packageFile, declared: null, exact: false, current: false };
+    const manifest = JSON.parse(readFileSync(packageFile, 'utf8'));
+    const declared = manifest.devDependencies?.[PACKAGE_NAME] ?? manifest.dependencies?.[PACKAGE_NAME] ?? null;
+    return {
+        packageFile,
+        declared,
+        exact: declared === PACKAGE_VERSION,
+        current: declared === PACKAGE_VERSION,
+    };
+}
+export function integrationDiagnostics(repositoryRoot) {
+    return {
+        package: { name: PACKAGE_NAME, version: PACKAGE_VERSION },
+        localDependency: inspectLocalDependency(repositoryRoot),
+        graphView: inspectGraphView(),
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/src/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAS7D,MAAM,UAAU,sBAAsB,CAAC,cAAsB;IAC3D,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;IAC9D,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACnG,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAG5D,CAAC;IACF,MAAM,QAAQ,GAAG,QAAQ,CAAC,eAAe,EAAE,CAAC,YAAY,CAAC,IAAI,QAAQ,CAAC,YAAY,EAAE,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC;IAC3G,OAAO;QACL,WAAW;QACX,QAAQ;QACR,KAAK,EAAE,QAAQ,KAAK,eAAe;QACnC,OAAO,EAAE,QAAQ,KAAK,eAAe;KACtC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,cAAsB;IAC3D,OAAO;QACL,OAAO,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE;QACzD,eAAe,EAAE,sBAAsB,CAAC,cAAc,CAAC;QACvD,SAAS,EAAE,gBAAgB,EAAE;KAC9B,CAAC;AACJ,CAAC"}

package/dist/src/domain/discovery.d.ts

@@ -0,0 +1,8 @@
+import type { DiscoveryState } from '../contracts.js';
+export interface DiscoveryReadiness {
+    ready: boolean;
+    status: 'needs_discovery' | 'needs_clarification' | 'ready_to_materialize';
+    missing: string[];
+}
+export declare function assessDiscovery(discovery: DiscoveryState): DiscoveryReadiness;
+export declare function mergeUnique(current: string[], additions: string[]): string[];

package/dist/src/domain/discovery.js

@@ -0,0 +1,25 @@
+export function assessDiscovery(discovery) {
+    const missing = [];
+    if (!discovery.goal.trim())
+        missing.push('goal');
+    if (!discovery.outcome?.trim())
+        missing.push('observable outcome');
+    if (discovery.scope.length === 0)
+        missing.push('scope');
+    if (discovery.acceptance.length === 0)
+        missing.push('acceptance scenario');
+    if (discovery.blockingUnknowns.length > 0)
+        missing.push('resolved blocking unknowns');
+    if (missing.length === 0)
+        return { ready: true, status: 'ready_to_materialize', missing };
+    const hasInitialUnderstanding = Boolean(discovery.goal.trim() && (discovery.outcome || discovery.scope.length > 0));
+    return {
+        ready: false,
+        status: hasInitialUnderstanding ? 'needs_clarification' : 'needs_discovery',
+        missing,
+    };
+}
+export function mergeUnique(current, additions) {
+    return [...new Set([...current, ...additions].map((value) => value.trim()).filter(Boolean))];
+}
+//# sourceMappingURL=discovery.js.map

package/dist/src/domain/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../../src/domain/discovery.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,eAAe,CAAC,SAAyB;IACvD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjD,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE;QAAE,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACnE,IAAI,SAAS,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,SAAS,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAC3E,IAAI,SAAS,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;IACtF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,sBAAsB,EAAE,OAAO,EAAE,CAAC;IAC1F,MAAM,uBAAuB,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,SAAS,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;IACpH,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,MAAM,EAAE,uBAAuB,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,iBAAiB;QAC3E,OAAO;KACR,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAiB,EAAE,SAAmB;IAChE,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC/F,CAAC"}

package/dist/src/domain/validation.d.ts

@@ -0,0 +1,3 @@
+import type { TaskPlanInput } from '../contracts.js';
+export declare function validatePlan(plan: TaskPlanInput): void;
+export declare function pathAllowed(file: string, patterns: string[]): boolean;

package/dist/src/domain/validation.js

@@ -0,0 +1,96 @@
+import { WorkflowError } from '../errors.js';
+export function validatePlan(plan) {
+    const issues = [];
+    if (!plan.objective.trim())
+        issues.push('Plan objective is required.');
+    if (plan.requirements.length === 0)
+        issues.push('At least one requirement is required.');
+    if (plan.acceptance.length === 0)
+        issues.push('At least one acceptance scenario is required.');
+    if (plan.steps.length === 0)
+        issues.push('At least one STEP-* is required.');
+    if (!plan.knowledgeImpactReason.trim())
+        issues.push('knowledgeImpactReason is required.');
+    if (!Number.isInteger(plan.knowledgeMapRevision) || plan.knowledgeMapRevision < 1) {
+        issues.push('knowledgeMapRevision must be a positive integer.');
+    }
+    if (!/^[a-f0-9]{64}$/.test(plan.knowledgeMapHash))
+        issues.push('knowledgeMapHash must be a SHA-256 hash.');
+    if (plan.knowledgeImpact === 'none' && plan.knowledgeTargets.length > 0) {
+        issues.push('knowledgeImpact none cannot declare knowledgeTargets.');
+    }
+    if (plan.knowledgeImpact !== 'none' && plan.knowledgeTargets.length === 0) {
+        issues.push(`knowledgeImpact ${plan.knowledgeImpact} requires at least one knowledgeTarget.`);
+    }
+    for (const target of plan.knowledgeTargets) {
+        if (!target.reason.trim())
+            issues.push(`Knowledge target ${target.path} requires a reason.`);
+        if (target.requirementIds.length === 0)
+            issues.push(`Knowledge target ${target.path} requires requirementIds.`);
+    }
+    const ids = new Set();
+    for (const step of plan.steps) {
+        if (!/^STEP-[0-9]{3}(?:-[A-Z0-9-]+)?$/.test(step.id))
+            issues.push(`Invalid Step id: ${step.id}`);
+        if (ids.has(step.id))
+            issues.push(`Duplicate Step id: ${step.id}`);
+        ids.add(step.id);
+        if (!step.title.trim() || !step.objective.trim())
+            issues.push(`${step.id} requires title and objective.`);
+        if (step.requirements.length === 0)
+            issues.push(`${step.id} must cover at least one requirement.`);
+        if (step.allowedWrites.length === 0)
+            issues.push(`${step.id} must declare allowedWrites.`);
+        if (step.expectedOutputs.length === 0)
+            issues.push(`${step.id} must declare expectedOutputs.`);
+        if (step.checks.length === 0)
+            issues.push(`${step.id} must declare at least one executable check.`);
+    }
+    for (const step of plan.steps) {
+        for (const dependency of step.dependencies) {
+            if (!ids.has(dependency))
+                issues.push(`${step.id} depends on missing ${dependency}.`);
+            if (dependency === step.id)
+                issues.push(`${step.id} cannot depend on itself.`);
+        }
+    }
+    const covered = new Set(plan.steps.flatMap((step) => step.requirements));
+    for (const requirement of plan.requirements) {
+        if (!covered.has(requirement))
+            issues.push(`Requirement is not covered by any Step: ${requirement}`);
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const byId = new Map(plan.steps.map((step) => [step.id, step]));
+    const visit = (stepId) => {
+        if (visited.has(stepId))
+            return;
+        if (visiting.has(stepId)) {
+            issues.push(`Step dependency cycle includes ${stepId}.`);
+            return;
+        }
+        visiting.add(stepId);
+        for (const dependency of byId.get(stepId)?.dependencies ?? [])
+            visit(dependency);
+        visiting.delete(stepId);
+        visited.add(stepId);
+    };
+    for (const step of plan.steps)
+        visit(step.id);
+    if (issues.length > 0)
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan is not execution-ready.', { issues });
+}
+export function pathAllowed(file, patterns) {
+    const normalized = file.replaceAll('\\', '/').replace(/^\.\//, '');
+    return patterns.some((pattern) => {
+        const candidate = pattern.replaceAll('\\', '/').replace(/^\.\//, '');
+        if (candidate.endsWith('/**'))
+            return normalized === candidate.slice(0, -3) || normalized.startsWith(candidate.slice(0, -2));
+        if (candidate.endsWith('/*')) {
+            const prefix = candidate.slice(0, -1);
+            return normalized.startsWith(prefix) && !normalized.slice(prefix.length).includes('/');
+        }
+        return normalized === candidate;
+    });
+}
+//# sourceMappingURL=validation.js.map

package/dist/src/domain/validation.js.map

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

package/dist/src/errors.d.ts

@@ -0,0 +1,6 @@
+export type WorkflowErrorCode = 'INVALID_ARGUMENT' | 'NOT_FOUND' | 'STATE_CONFLICT' | 'STATE_CORRUPT' | 'LOCKED' | 'LOCK_TOKEN_INVALID' | 'TRANSITION_BLOCKED' | 'GIT_PRECONDITION_FAILED' | 'COMMAND_FAILED';
+export declare class WorkflowError extends Error {
+    readonly code: WorkflowErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: WorkflowErrorCode, message: string, details?: Record<string, unknown>);
+}

package/dist/src/errors.js

@@ -0,0 +1,11 @@
+export class WorkflowError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'WorkflowError';
+        this.code = code;
+        this.details = details;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAoB;IACxB,OAAO,CAA0B;IAE1C,YAAY,IAAuB,EAAE,OAAe,EAAE,UAAmC,EAAE;QACzF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/dist/src/fs-utils.d.ts

@@ -0,0 +1,4 @@
+export declare function ensureDirectory(directory: string): void;
+export declare function readJson<T>(file: string): T;
+export declare function writeJsonAtomic(file: string, value: unknown): void;
+export declare function writeTextAtomic(file: string, content: string): void;

package/dist/src/fs-utils.js

@@ -0,0 +1,52 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { WorkflowError } from './errors.js';
+export function ensureDirectory(directory) {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (lstatSync(directory).isSymbolicLink()) {
+        throw new WorkflowError('STATE_CORRUPT', `State directory must not be a symlink: ${directory}`);
+    }
+}
+export function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new WorkflowError('STATE_CORRUPT', `Cannot read JSON state: ${file}`, {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+export function writeJsonAtomic(file, value) {
+    const directory = path.dirname(file);
+    ensureDirectory(directory);
+    if (existsSync(file) && lstatSync(file).isSymbolicLink()) {
+        throw new WorkflowError('STATE_CORRUPT', `Refusing to replace state symlink: ${file}`);
+    }
+    const temporary = path.join(directory, `.${path.basename(file)}.${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        chmodSync(temporary, 0o600);
+        renameSync(temporary, file);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+export function writeTextAtomic(file, content) {
+    const directory = path.dirname(file);
+    ensureDirectory(directory);
+    const temporary = path.join(directory, `.${path.basename(file)}.${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temporary, content.endsWith('\n') ? content : `${content}\n`, {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+        renameSync(temporary, file);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+//# sourceMappingURL=fs-utils.js.map

package/dist/src/fs-utils.js.map

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

package/dist/src/git.d.ts

@@ -0,0 +1,19 @@
+import type { TaskState } from './contracts.js';
+export declare function startLocalTaskBranch(repositoryRoot: string, branch: string, baseBranch: string): string;
+export interface CheckResult {
+    command: string;
+    passed: boolean;
+    exitCode: number;
+    output: string;
+}
+export declare function runChecks(repositoryRoot: string, commands: string[]): CheckResult[];
+export declare function commitStep(repositoryRoot: string, taskId: string, stepId: string, title: string, allowedWrites: string[]): {
+    commitSha: string;
+    files: string[];
+};
+export declare function mergeTaskBranch(repositoryRoot: string, taskBranch: string, baseBranch: string): string;
+export declare function syncBaseIntoTask(repositoryRoot: string, taskBranch: string, baseBranch: string): {
+    baseCommit: string;
+    syncCommit: string;
+};
+export declare function validateTaskHistory(repositoryRoot: string, task: TaskState): void;