codictator 0.0.0-stage → 0.1.2

package/dist/features/testing/trace.js

@@ -0,0 +1,110 @@
+// SPEC §4.10.1: the SPEC trace. Every acceptance test carries a reference
+// matching config.spec.refPattern; every reference resolves to a heading or
+// an EC row; every code task lists references its declared tests cite. The
+// spec index is caller-supplied data (the loader owns the SPEC files), so
+// this module never reads the filesystem.
+import { globMatch } from "../../kernel/index.js";
+export const DEFAULT_REF_PATTERN = "\\[(§[\\d.]+(?: EC-\\d+)?)\\]";
+function parseInner(raw) {
+    const match = /^§([\d.]+)(?: EC-(\d+))?$/.exec(raw);
+    if (match === null) {
+        return undefined;
+    }
+    const section = match[1] ?? "";
+    const ecText = match[2];
+    return {
+        section,
+        ec: ecText === undefined ? undefined : Number.parseInt(ecText, 10),
+        raw,
+    };
+}
+// SPEC §4.10.1: config.spec.refPattern finds references in test titles.
+export function parseSpecRefs(title, refPattern = DEFAULT_REF_PATTERN) {
+    const refs = [];
+    const pattern = new RegExp(refPattern, "g");
+    let match = pattern.exec(title);
+    while (match !== null) {
+        const parsed = parseInner(match[1] ?? "");
+        if (parsed !== undefined) {
+            refs.push(parsed);
+        }
+        match = pattern.exec(title);
+    }
+    return refs;
+}
+function nearestSections(wanted, known) {
+    const scored = [...known]
+        .map((section) => {
+        let shared = 0;
+        while (shared < wanted.length &&
+            shared < section.length &&
+            wanted[shared] === section[shared]) {
+            shared += 1;
+        }
+        return { section, shared };
+    })
+        .sort((a, b) => b.shared - a.shared || (a.section < b.section ? -1 : 1));
+    return scored
+        .slice(0, 3)
+        .map((entry) => `§${entry.section}`)
+        .join(", ");
+}
+function nearestEcs(wanted, known) {
+    return [...known]
+        .sort((a, b) => Math.abs(a - wanted) - Math.abs(b - wanted) || a - b)
+        .slice(0, 3)
+        .map((ec) => `EC-${ec}`)
+        .join(", ");
+}
+function traceFinding(path, message, remediation) {
+    return { ruleId: "core/spec-trace", path, message, remediation };
+}
+// SPEC §4.10.1 core/spec-trace: acceptance tests trace; references resolve;
+// remediation lists the nearest existing ids.
+export function checkSpecTrace(tests, spec, acceptanceGlobs = ["tests/acceptance/**"], refPattern = DEFAULT_REF_PATTERN) {
+    const findings = [];
+    for (const test of tests) {
+        if (!acceptanceGlobs.some((glob) => globMatch(glob, test.path))) {
+            continue;
+        }
+        const refs = parseSpecRefs(test.title, refPattern);
+        if (refs.length === 0) {
+            findings.push(traceFinding(test.path, `acceptance test without a SPEC reference: ${test.title}`, `Give the test in ${test.path} a literal SPEC reference, e.g. [§4.10 EC-4].`));
+            continue;
+        }
+        for (const ref of refs) {
+            if (!spec.headings.has(ref.section)) {
+                findings.push(traceFinding(test.path, `SPEC reference to unknown section: ${ref.raw}`, `Point ${test.path} at an existing section. Nearest: ${nearestSections(ref.section, spec.headings)}.`));
+                continue;
+            }
+            if (ref.ec !== undefined) {
+                const rows = spec.ecRows.get(ref.section) ?? new Set();
+                if (!rows.has(ref.ec)) {
+                    findings.push(traceFinding(test.path, `SPEC reference to unknown EC row: ${ref.raw}`, `Point ${test.path} at an existing EC row. Nearest: ${nearestEcs(ref.ec, rows)}.`));
+                }
+            }
+        }
+    }
+    return findings;
+}
+// SPEC §4.10.1 planning gate: every code task lists spec references, each
+// cited by at least one declared test; zero declared tests blocks.
+export function checkPlanningGate(task) {
+    const findings = [];
+    if (task.type !== "code" && task.type !== "fix") {
+        return findings;
+    }
+    if (task.declaredTests.length === 0) {
+        findings.push(traceFinding("(task)", `code task declares zero tests`, "Declare at least one test for the code task before planning it."));
+    }
+    if (task.specRefs.length === 0) {
+        findings.push(traceFinding("(task)", `code task lists zero SPEC references`, "List at least one SPEC reference on the code task."));
+    }
+    for (const test of task.declaredTests) {
+        const cites = parseSpecRefs(test.title).some((ref) => task.specRefs.includes(ref.raw));
+        if (!cites) {
+            findings.push(traceFinding(test.path, `declared test cites none of the task references: ${test.title}`, `Cite one of ${task.specRefs.join(", ")} in ${test.path}.`));
+        }
+    }
+    return findings;
+}

package/dist/features/workflow/index.d.ts

@@ -0,0 +1,14 @@
+import type { CheckContext, Finding } from "../engine/index.ts";
+import { type PhaseGateDetail } from "./phases.ts";
+import { type ReviewCheckDetail, type ReviewFindingsFile } from "./review.ts";
+import type { TaskRecord } from "./tasks.ts";
+export { checkReviewCap, DEFAULT_MAX_REPEATS, escalationMessage, } from "./loop.ts";
+export { isMandatoryPhase, MANDATORY_PHASES, validatePhaseOrder, } from "./phases.ts";
+export type { ReviewFinding, ReviewSeverity } from "./review.ts";
+export type { AgentRole, ChangeClass, ReviewRound, TaskEscalation, TaskGreenProof, TaskPhase, TaskProof, TaskRecord, TaskTestRef, TaskType, } from "./tasks.ts";
+export { isTaskId, mergeTaskRecords, resolveActiveTask, roleForAsset, TASK_LOCK_PATH, taskIdFor, validateTaskRecord, } from "./tasks.ts";
+export { checkWriteWithinPlan, classifyChange, type WriteCheckOptions, } from "./writes.ts";
+export type { PhaseGateDetail, ReviewCheckDetail, ReviewFindingsFile };
+export declare function checkPhaseGate(task: TaskRecord, phase: string, detail?: PhaseGateDetail): Promise<Array<Finding>>;
+export declare function checkReview(ctx: CheckContext, findings: ReviewFindingsFile, detail?: ReviewCheckDetail): Promise<Array<Finding>>;
+export declare function checkLoop(ctx: CheckContext, attempts: number, maxRepeats?: number): Promise<Array<Finding>>;

package/dist/features/workflow/index.js

@@ -0,0 +1,19 @@
+import { checkLoop as checkLoopImpl, DEFAULT_MAX_REPEATS } from "./loop.js";
+import { checkPhaseGate as checkPhaseGateImpl, } from "./phases.js";
+import { checkReview as checkReviewImpl, } from "./review.js";
+export { checkReviewCap, DEFAULT_MAX_REPEATS, escalationMessage, } from "./loop.js";
+export { isMandatoryPhase, MANDATORY_PHASES, validatePhaseOrder, } from "./phases.js";
+export { isTaskId, mergeTaskRecords, resolveActiveTask, roleForAsset, TASK_LOCK_PATH, taskIdFor, validateTaskRecord, } from "./tasks.js";
+export { checkWriteWithinPlan, classifyChange, } from "./writes.js";
+// SPEC §4.12.2: phase gate evaluation for the task state machine.
+export function checkPhaseGate(task, phase, detail) {
+    return checkPhaseGateImpl(task, phase, detail ?? {});
+}
+// SPEC §4.12.4: review gate verdicts.
+export function checkReview(ctx, findings, detail) {
+    return checkReviewImpl(ctx, findings, detail ?? {});
+}
+// SPEC §4.12.5: loop breaker escalation.
+export function checkLoop(ctx, attempts, maxRepeats) {
+    return checkLoopImpl(ctx, attempts, maxRepeats ?? DEFAULT_MAX_REPEATS);
+}

package/dist/features/workflow/loop.d.ts

@@ -0,0 +1,5 @@
+import type { CheckContext, Finding } from "../engine/index.ts";
+export declare const DEFAULT_MAX_REPEATS = 3;
+export declare function escalationMessage(ruleId: string, attempts: number): string;
+export declare function checkLoop(ctx: CheckContext, attempts: number, maxRepeats?: number): Promise<Array<Finding>>;
+export declare function checkReviewCap(completedRounds: number, maxRounds?: number): Promise<Array<Finding>>;

package/dist/features/workflow/loop.js

@@ -0,0 +1,36 @@
+export const DEFAULT_MAX_REPEATS = 3;
+export function escalationMessage(ruleId, attempts) {
+    return (`escalation: ${ruleId} blocked ${String(attempts)} times with no intervening allow. ` +
+        "Stop and give the human a summary of the rule, the attempts and the conflict.");
+}
+// SPEC §4.12.7 EC-7: the fourth consecutive block escalates, and every
+// tool call for the task stays blocked until a human runs task ack.
+// SPEC §4.12.7 EC-8: the ack itself is human-only, so the shell guard
+// blocks agents there; this check returns no finding for low counts.
+export async function checkLoop(ctx, attempts, maxRepeats = DEFAULT_MAX_REPEATS) {
+    void ctx;
+    if (attempts <= maxRepeats) {
+        return [];
+    }
+    return [
+        {
+            ruleId: "core/loop-breaker",
+            message: escalationMessage("core/loop-breaker", attempts),
+            remediation: "Run codictator task ack <id> --note ... to clear the escalation; task ack is human-only.",
+        },
+    ];
+}
+// SPEC §4.12.4 cap: reaching the review-round cap escalates through the
+// same path; the floor never moves, only the attempt stops.
+export async function checkReviewCap(completedRounds, maxRounds = 3) {
+    if (completedRounds < maxRounds) {
+        return [];
+    }
+    return [
+        {
+            ruleId: "core/review-round-cap",
+            message: escalationMessage("core/review-round-cap", completedRounds),
+            remediation: "Run codictator task ack <id> --note ... to clear the escalation; task ack is human-only.",
+        },
+    ];
+}

package/dist/features/workflow/phases.d.ts

@@ -0,0 +1,10 @@
+import type { Finding } from "../engine/index.ts";
+import type { TaskRecord } from "./tasks.ts";
+export declare const MANDATORY_PHASES: ReadonlyArray<string>;
+export declare function isMandatoryPhase(value: string): boolean;
+export declare function validatePhaseOrder(order: ReadonlyArray<string>): boolean;
+export interface PhaseGateDetail {
+    readonly openTasks?: ReadonlyArray<string>;
+    readonly phaseOrder?: ReadonlyArray<string>;
+}
+export declare function checkPhaseGate(task: TaskRecord, phase: string, detail?: PhaseGateDetail): Promise<Array<Finding>>;

package/dist/features/workflow/phases.js

@@ -0,0 +1,181 @@
+// SPEC §4.12.2: the seven mandatory phases in order.
+export const MANDATORY_PHASES = [
+    "discovery",
+    "planning",
+    "implementation",
+    "validation",
+    "review",
+    "record",
+    "integrate",
+];
+export function isMandatoryPhase(value) {
+    return MANDATORY_PHASES.includes(value);
+}
+function customPhasesOf(task) {
+    return task.customPhases ?? [];
+}
+function isKnownPhase(task, phase) {
+    return isMandatoryPhase(phase) || customPhasesOf(task).includes(phase);
+}
+// SPEC §4.12.2: the mandatory phases keep their relative order; removing
+// or reordering one is CDX-E105, as is inserting a custom phase before
+// discovery.
+export function validatePhaseOrder(order) {
+    let cursor = -1;
+    for (const mandatory of MANDATORY_PHASES) {
+        const at = order.indexOf(mandatory);
+        if (at < 0 || at <= cursor) {
+            return false;
+        }
+        cursor = at;
+    }
+    return true;
+}
+function e105UnknownPhase(phase) {
+    return {
+        ruleId: "core/workflow-gates",
+        code: "CDX-E105",
+        message: `unknown phase "${phase}"; the seven mandatory phases keep their order`,
+        remediation: "Declare the phase in config.workflow.phases after discovery, then re-run the gate.",
+    };
+}
+function e105PhaseOrder() {
+    return {
+        ruleId: "core/workflow-gates",
+        code: "CDX-E105",
+        message: "mandatory workflow phases removed or reordered; custom phases insert after discovery only",
+        remediation: "Restore the seven mandatory phases in order with custom phases after discovery.",
+    };
+}
+function e606TwoTasks(open, task) {
+    const listed = open.length > 0 ? open.join(", ") : `${task.id} and a second opener`;
+    return {
+        ruleId: "core/workflow-gates",
+        code: "CDX-E606",
+        message: `more than one open task on branch "${task.branch}": ${listed}`,
+        remediation: "Run codictator task status, close or merge the extra task, then retry.",
+    };
+}
+// SPEC §4.12.2 exit gates: the evidence each phase owes before the next
+// phase opens. Implementation and integrate owe no exit evidence.
+function missingExitEvidence(task, phase) {
+    switch (phase) {
+        case "discovery": {
+            const missing = [];
+            if (task.spec.length === 0) {
+                missing.push("spec refs");
+            }
+            if (task.type === "fix" && (task.diagnosis ?? "").length === 0) {
+                missing.push("diagnosis");
+            }
+            return missing;
+        }
+        case "planning": {
+            const missing = [];
+            if (task.files.allow.length === 0) {
+                missing.push("files.allow globs");
+            }
+            if (task.acceptanceCriteria.length === 0) {
+                missing.push("acceptance criteria");
+            }
+            if ((task.tests ?? []).length === 0) {
+                missing.push("declared tests");
+            }
+            if (task.redProof === undefined) {
+                missing.push("red proof");
+            }
+            return missing;
+        }
+        case "validation": {
+            return task.greenProof === undefined ? ["green proof"] : [];
+        }
+        case "review": {
+            return missingReviewEvidence(task);
+        }
+        case "record": {
+            const missing = [];
+            if (task.historyStaged !== true) {
+                missing.push("staged history entry");
+            }
+            if (task.type === "fix" && task.bugRowUpdated !== true) {
+                missing.push("bug row update");
+            }
+            return missing;
+        }
+        default: {
+            return [];
+        }
+    }
+}
+function missingReviewEvidence(task) {
+    const rounds = task.reviews ?? [];
+    if (rounds.length === 0) {
+        return ["completed review round"];
+    }
+    const last = rounds[rounds.length - 1];
+    if (last === undefined) {
+        return ["completed review round"];
+    }
+    const missing = [];
+    if (last.openBlockers > 0 || last.openMajors > 0) {
+        missing.push("zero open blocker/major findings");
+    }
+    const pending = (task.integrityExceptions ?? []).filter((id) => !last.acknowledgedExceptions.includes(id));
+    if (pending.length > 0) {
+        missing.push("acknowledged integrity exceptions");
+    }
+    return missing;
+}
+function e604MissingGate(task, missing) {
+    return {
+        ruleId: "core/workflow-gates",
+        code: "CDX-E604",
+        message: `phase gate evidence missing for ${task.phase}: ${missing.join(", ")}`,
+        remediation: `Run codictator task phase next to list the missing evidence for ${task.phase}.`,
+    };
+}
+// SPEC §4.12.2: advance only when the exit gate holds, else CDX-E604. A
+// change that touches code files is reclassified as code and owes every
+// gate; docs-only writes stay allowed but never waive code gates.
+export async function checkPhaseGate(task, phase, detail = {}) {
+    if (!isKnownPhase(task, phase)) {
+        return [e105UnknownPhase(phase)];
+    }
+    if (detail.phaseOrder !== undefined &&
+        !validatePhaseOrder(detail.phaseOrder)) {
+        return [e105PhaseOrder()];
+    }
+    // SPEC §4.12.7 EC-10: re-entering planning while planning is already
+    // active means a second writer opened planning on this branch. The
+    // caller-provided open-task list decides whenever it is present.
+    const open = detail.openTasks;
+    if (open !== undefined && open.length >= 2) {
+        return [e606TwoTasks(open, task)];
+    }
+    if (open === undefined && task.phase === "planning" && phase === "planning") {
+        return [e606TwoTasks([], task)];
+    }
+    if (phase !== task.phase) {
+        const missing = missingExitEvidence(task, task.phase);
+        if (missing.length > 0) {
+            return [e604MissingGate(task, missing)];
+        }
+        return [];
+    }
+    // Same-phase evaluation: implementation, validation and record writes
+    // are judged by the L1 write gate, not here; review re-entry owes a
+    // completed round before it can pass.
+    if (task.phase === "review") {
+        const missing = missingReviewEvidence(task);
+        if (missing.length > 0) {
+            return [
+                {
+                    ruleId: "core/review-gate",
+                    message: `review gate unmet in phase review: ${missing.join(", ")}`,
+                    remediation: "Run codictator review submit with a fresh reviewer session.",
+                },
+            ];
+        }
+    }
+    return [];
+}

package/dist/features/workflow/review.d.ts

@@ -0,0 +1,25 @@
+import type { CheckContext, Finding } from "../engine/index.ts";
+export type ReviewSeverity = "blocker" | "major" | "minor" | "nit";
+export interface ReviewFinding {
+    readonly id: string;
+    readonly severity: string;
+    readonly path: string;
+    readonly line?: number;
+    readonly message: string;
+}
+export interface ReviewFindingsFile {
+    readonly version: 1;
+    readonly findings: ReadonlyArray<ReviewFinding>;
+    readonly tree?: string;
+    readonly reviewerSession?: string;
+    readonly identity?: "observed" | "declared";
+    readonly round?: number;
+}
+export interface ReviewCheckDetail {
+    readonly authorSessions?: ReadonlyArray<string>;
+    readonly reviewerSessions?: ReadonlyArray<string>;
+    readonly tree?: string;
+    readonly maxRounds?: number;
+    readonly completedRounds?: number;
+}
+export declare function checkReview(ctx: CheckContext, file: ReviewFindingsFile, detail?: ReviewCheckDetail): Promise<Array<Finding>>;

package/dist/features/workflow/review.js

@@ -0,0 +1,112 @@
+const SEVERITIES = ["blocker", "major", "minor", "nit"];
+function malformedReason(file) {
+    if (!Array.isArray(file.findings)) {
+        return "findings is not a list";
+    }
+    const seen = new Set();
+    for (const finding of file.findings) {
+        if (typeof finding.id !== "string" ||
+            typeof finding.severity !== "string" ||
+            typeof finding.path !== "string" ||
+            typeof finding.message !== "string" ||
+            finding.id.length === 0 ||
+            finding.message.length === 0) {
+            return "a finding misses id, severity, path or message";
+        }
+        if (!SEVERITIES.includes(finding.severity)) {
+            return `severity "${finding.severity}" is not blocker, major, minor or nit`;
+        }
+        if (seen.has(finding.id)) {
+            return `duplicate finding id "${finding.id}"`;
+        }
+        seen.add(finding.id);
+    }
+    // SPEC §4.12.4 Bind/Submit: a submittable round binds the staged tree
+    // and the reviewer session. An empty findings list is a pass only once
+    // bound; without either the round cannot be recorded.
+    if (file.tree === undefined || file.reviewerSession === undefined) {
+        return "the round binds no staged tree or reviewer session";
+    }
+    return undefined;
+}
+// SPEC §4.12.4: review submit refuses a reviewer from the author sessions
+// or from any earlier round (CDX-E605). Identity comes from the recorded
+// tool event; without an adapter the round is marked declared.
+function freshnessRefusal(file, detail) {
+    const reviewer = file.reviewerSession;
+    if (reviewer === undefined) {
+        return {
+            ruleId: "core/review-gate",
+            code: "CDX-E605",
+            message: "reviewer session unknown; reviewer freshness cannot be proven",
+            remediation: "Re-submit with --session from a fresh session that wrote no task file.",
+        };
+    }
+    const authors = detail.authorSessions ?? [];
+    const earlier = detail.reviewerSessions ?? [];
+    if (authors.includes(reviewer) || earlier.includes(reviewer)) {
+        return {
+            ruleId: "core/review-gate",
+            code: "CDX-E605",
+            message: `reviewer session "${reviewer}" is not fresh`,
+            remediation: "Re-submit from a fresh session that wrote no task file and ran no earlier round.",
+        };
+    }
+    return undefined;
+}
+// SPEC §4.12.4 gate: last round tree equals staged, zero open
+// blocker/major, exceptions acknowledged, rounds under the cap.
+export async function checkReview(ctx, file, detail = {}) {
+    const findings = [];
+    const malformed = malformedReason(file);
+    if (malformed !== undefined) {
+        findings.push({
+            ruleId: "core/review-gate",
+            code: "CDX-E607",
+            message: `review findings file invalid: ${malformed}; the round is not recorded`,
+            remediation: "Submit findings as { id, severity, path, line?, message } bound to the staged tree and reviewer session.",
+        });
+    }
+    const refusal = freshnessRefusal(file, detail);
+    if (refusal !== undefined) {
+        findings.push(refusal);
+    }
+    const openBlockers = Array.isArray(file.findings)
+        ? file.findings.filter((entry) => entry.severity === "blocker" || entry.severity === "major")
+        : [];
+    if (openBlockers.length > 0 && malformed === undefined) {
+        const first = openBlockers[0];
+        const location = first?.path === undefined
+            ? {}
+            : {
+                path: first.path,
+                ...(first.line === undefined ? {} : { line: first.line }),
+            };
+        findings.push({
+            ruleId: "core/review-gate",
+            ...location,
+            message: `${String(openBlockers.length)} open blocker/major findings; only a code change starts a new round`,
+            remediation: "Fix the blocker or major finding with a code change, then submit a new round.",
+        });
+    }
+    if (detail.tree !== undefined &&
+        file.tree !== undefined &&
+        detail.tree !== file.tree) {
+        findings.push({
+            ruleId: "core/review-gate",
+            message: "stale review: the index tree changed after the round was submitted",
+            remediation: "Submit a new review round against the current staged tree.",
+        });
+    }
+    const maxRounds = detail.maxRounds ?? 3;
+    const completed = detail.completedRounds ?? 0;
+    if (completed >= maxRounds) {
+        findings.push({
+            ruleId: "core/review-round-cap",
+            message: `review round cap reached (${String(completed)} of ${String(maxRounds)}); escalation recorded`,
+            remediation: "Stop and give a human the summary; run codictator task ack --note ... (human-only) to clear it.",
+        });
+    }
+    void ctx;
+    return findings;
+}

package/dist/features/workflow/tasks.d.ts

@@ -0,0 +1,73 @@
+export type TaskType = "feature" | "fix" | "refactor" | "docs" | "deps" | "chore";
+export type ChangeClass = "code" | "docs" | "refactor" | "deps" | "chore" | "guardrail";
+export type AgentRole = "planner" | "implementer" | "reviewer" | "qa";
+export interface TaskPhase {
+    readonly name: string;
+    readonly enteredAt: string;
+    readonly evidence: string;
+}
+export interface TaskTestRef {
+    readonly path: string;
+    readonly title: string;
+    readonly kind: string;
+}
+export interface TaskProof {
+    readonly commit: string;
+    readonly tree: string;
+    readonly failing: ReadonlyArray<string>;
+    readonly at: string;
+}
+export interface TaskGreenProof {
+    readonly at: string;
+    readonly tree: string;
+}
+export interface ReviewRound {
+    readonly round: number;
+    readonly tree: string;
+    readonly reviewerSession: string;
+    readonly identity: "observed" | "declared";
+    readonly openBlockers: number;
+    readonly openMajors: number;
+    readonly acknowledgedExceptions: ReadonlyArray<string>;
+    readonly at: string;
+}
+export interface TaskEscalation {
+    readonly at: string;
+    readonly ruleId: string;
+    readonly attempts: number;
+    readonly ackedBy?: string;
+    readonly note?: string;
+}
+export interface TaskRecord {
+    readonly version: 1;
+    readonly id: string;
+    readonly type: string;
+    readonly title: string;
+    readonly branch: string;
+    readonly phase: string;
+    readonly phases: ReadonlyArray<TaskPhase>;
+    readonly spec: ReadonlyArray<string>;
+    readonly acceptanceCriteria: ReadonlyArray<string>;
+    readonly files: {
+        readonly allow: ReadonlyArray<string>;
+    };
+    readonly customPhases?: ReadonlyArray<string>;
+    readonly tests?: ReadonlyArray<TaskTestRef>;
+    readonly diagnosis?: string;
+    readonly redProof?: TaskProof;
+    readonly greenProof?: TaskGreenProof;
+    readonly authorSessions?: ReadonlyArray<string>;
+    readonly roles?: Readonly<Record<string, AgentRole>>;
+    readonly reviews?: ReadonlyArray<ReviewRound>;
+    readonly integrityExceptions?: ReadonlyArray<string>;
+    readonly historyStaged?: boolean;
+    readonly bugRowUpdated?: boolean;
+    readonly escalations?: ReadonlyArray<TaskEscalation>;
+}
+export declare function isTaskId(value: string): boolean;
+export declare function taskIdFor(sequence: number): string;
+export declare function resolveActiveTask(tasks: ReadonlyArray<TaskRecord>, branch: string): TaskRecord | undefined;
+export declare const TASK_LOCK_PATH = ".codictator/state/task.lock";
+export declare function roleForAsset(asset: string): AgentRole | undefined;
+export declare function mergeTaskRecords(base: TaskRecord, head: TaskRecord, phaseOrder: ReadonlyArray<string>, evidenceOk?: (phase: string) => boolean): TaskRecord;
+export declare function validateTaskRecord(task: TaskRecord): Array<string>;

package/dist/features/workflow/tasks.js

@@ -0,0 +1,80 @@
+// SPEC §4.12.1: ids are T-####, sequential per repo.
+const TASK_ID_PATTERN = /^T-\d{4}$/;
+export function isTaskId(value) {
+    return TASK_ID_PATTERN.test(value);
+}
+export function taskIdFor(sequence) {
+    return `T-${String(sequence).padStart(4, "0")}`;
+}
+// SPEC §4.12.1: a branch has at most one open task, which is the active
+// task for every hook on that branch, subagents included.
+export function resolveActiveTask(tasks, branch) {
+    for (const task of tasks) {
+        if (task.branch === branch) {
+            return task;
+        }
+    }
+    return undefined;
+}
+// SPEC §4.12.6: one lock serialises task-record writes on a machine.
+export const TASK_LOCK_PATH = ".codictator/state/task.lock";
+// SPEC §4.12.6: roles are recorded per session from the subagent or skill
+// name. The codictator-review asset marks reviewers; gates are the same
+// for every role, so the label only informs injection.
+const ROLE_ASSETS = [
+    ["codictator-review", "reviewer"],
+    ["review", "reviewer"],
+    ["qa", "qa"],
+    ["implement", "implementer"],
+    ["plan", "planner"],
+];
+export function roleForAsset(asset) {
+    const lowered = asset.toLowerCase();
+    for (const [fragment, role] of ROLE_ASSETS) {
+        if (lowered.includes(fragment)) {
+            return role;
+        }
+    }
+    return undefined;
+}
+// SPEC §4.12.6: on merge conflicts in a task record the later phase wins
+// only if its gate evidence verifies. Entry in phases[] is the evidence
+// of entry; per-gate evidence is verified by the caller through evidenceOk.
+export function mergeTaskRecords(base, head, phaseOrder, evidenceOk) {
+    const baseIndex = phaseOrder.indexOf(base.phase);
+    const headIndex = phaseOrder.indexOf(head.phase);
+    const headLater = headIndex > baseIndex;
+    const verified = evidenceOk === undefined
+        ? head.phases.some((entry) => entry.name === head.phase)
+        : evidenceOk(head.phase);
+    if (headLater && verified) {
+        return head;
+    }
+    return base;
+}
+// SPEC §4.12.1 + §4.12.2: the record is only writable through task commands;
+// direct writes are blocked (§4.14.3). Structural validation for new tasks.
+export function validateTaskRecord(task) {
+    const problems = [];
+    if (!isTaskId(task.id)) {
+        problems.push(`id "${task.id}" is not T-####`);
+    }
+    const types = [
+        "feature",
+        "fix",
+        "refactor",
+        "docs",
+        "deps",
+        "chore",
+    ];
+    if (!types.includes(task.type)) {
+        problems.push(`type "${task.type}" is not a task type`);
+    }
+    if (task.branch.length === 0) {
+        problems.push("branch is empty; a task binds to its branch");
+    }
+    if (task.title.length === 0) {
+        problems.push("title is empty");
+    }
+    return problems;
+}