@osovv/vv-opencode 0.21.0 → 0.24.1

package/dist/plugins/workflow/protocol.js

@@ -0,0 +1,188 @@
+// FILE: src/plugins/workflow/protocol.ts
+// VERSION: 0.1.2
+// START_MODULE_CONTRACT
+//   PURPOSE: Define the tracked subagent result protocol, strict top-block parsing rules, and work-item header extraction.
+//   SCOPE: Tracked agent/status constants, status validation per agent, strict result-block parsing, protocol error reporting, and VVOC_WORK_ITEM_ID header parsing.
+//   DEPENDS: [none]
+//   LINKS: [M-WORKFLOW-PROTOCOL]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   TrackedAgentName - Tracked subagent names used by workflow enforcement.
+//   VVocStatus - Union of all supported protocol statuses.
+//   ParsedResultBlock - Parsed strict top-block fields from tracked subagent output.
+//   ProtocolErrorCode - Stable machine-readable protocol error codes.
+//   ProtocolError - Structured protocol error payload.
+//   ProtocolResult - Deterministic success/failure wrapper for parsing and validation operations.
+//   TRACKED_SUBAGENT_NAMES - Ordered tracked subagent names.
+//   ALLOWED_STATUSES - Allowed VVOC_STATUS values per tracked subagent.
+//   parseResultBlock - Parses strict top-block protocol fields from tracked subagent output.
+//   validateStatusForAgent - Validates VVOC_STATUS against tracked agent allowances.
+//   parseWorkItemHeader - Extracts and validates the top-line VVOC_WORK_ITEM_ID prompt header.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v0.1.2 - Rejected duplicate strict top-block protocol fields to keep parse outcomes deterministic.]
+//   LAST_CHANGE: [v0.1.1 - Enforced case-sensitive status validation and strict top-block line validation for protocol-only fields.]
+//   LAST_CHANGE: [v0.1.0 - Added workflow protocol grammar, strict top-block parser, per-agent status validation, and prompt-header extraction.]
+// END_CHANGE_SUMMARY
+export const TRACKED_SUBAGENT_NAMES = [
+    "vv-implementer",
+    "vv-spec-reviewer",
+    "vv-code-reviewer",
+];
+export const ALLOWED_STATUSES = {
+    "vv-implementer": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"],
+    "vv-spec-reviewer": ["PASS", "FAIL", "NEEDS_CONTEXT"],
+    "vv-code-reviewer": ["PASS", "FAIL", "NEEDS_CONTEXT"],
+};
+const WORK_ITEM_HEADER_RE = /^VVOC_WORK_ITEM_ID:\s*(wi-\d+)\s*$/;
+function createProtocolError(code, message) {
+    return {
+        ok: false,
+        error: {
+            code,
+            message,
+        },
+    };
+}
+function splitTopBlock(text) {
+    const lines = text.replace(/\r\n/g, "\n").split("\n");
+    const firstMeaningfulIndex = lines.findIndex((line) => line.trim().length > 0);
+    if (firstMeaningfulIndex < 0)
+        return [];
+    const block = [];
+    for (let index = firstMeaningfulIndex; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        if (line.trim().length === 0) {
+            break;
+        }
+        block.push(line.trim());
+    }
+    return block;
+}
+function readTopBlockField(topBlockLines, field) {
+    const fieldPattern = new RegExp(`^${field}\\s*:\\s*(.+)$`);
+    for (const line of topBlockLines) {
+        const match = fieldPattern.exec(line);
+        if (!match) {
+            continue;
+        }
+        const value = match[1]?.trim() ?? "";
+        return value || undefined;
+    }
+    return undefined;
+}
+function validateTopBlockLines(topBlockLines) {
+    const allowedFields = new Set(["VVOC_WORK_ITEM_ID", "VVOC_STATUS", "VVOC_ROUTE"]);
+    const seenFields = new Set();
+    for (const line of topBlockLines) {
+        const match = /^([A-Z_]+)\s*:\s*(.+)$/.exec(line);
+        if (!match) {
+            return createProtocolError("UNEXPECTED_TOP_BLOCK_LINE", `UNEXPECTED_TOP_BLOCK_LINE: strict top block contains a non-protocol line \`${line}\``);
+        }
+        const field = match[1] ?? "";
+        if (!allowedFields.has(field)) {
+            return createProtocolError("UNEXPECTED_TOP_BLOCK_LINE", `UNEXPECTED_TOP_BLOCK_LINE: strict top block field \`${field}\` is not recognized`);
+        }
+        if (seenFields.has(field)) {
+            return createProtocolError("DUPLICATE_TOP_BLOCK_FIELD", `DUPLICATE_TOP_BLOCK_FIELD: strict top block repeats field \`${field}\``);
+        }
+        seenFields.add(field);
+    }
+    return { ok: true, value: true };
+}
+// START_CONTRACT: validateStatusForAgent
+//   PURPOSE: Validate that the provided VVOC_STATUS value is allowed for a tracked subagent.
+//   INPUTS: { agent: TrackedAgentName - tracked subagent name, status: string - candidate status value }
+//   OUTPUTS: { ProtocolResult<VVocStatus> - normalized status success or protocol validation error }
+//   SIDE_EFFECTS: [none]
+//   LINKS: [M-WORKFLOW-PROTOCOL]
+// END_CONTRACT: validateStatusForAgent
+export function validateStatusForAgent(agent, status) {
+    const normalized = status.trim();
+    const allowed = ALLOWED_STATUSES[agent];
+    const allKnownStatuses = new Set(Object.values(ALLOWED_STATUSES).flatMap((entries) => [...entries]));
+    if (!allKnownStatuses.has(normalized)) {
+        return createProtocolError("UNKNOWN_STATUS", `UNKNOWN_STATUS: ${normalized || "<empty>"} is not a recognized VVOC_STATUS`);
+    }
+    if (!allowed.some((entry) => entry === normalized)) {
+        return createProtocolError("STATUS_NOT_ALLOWED", `STATUS_NOT_ALLOWED: ${normalized} is not allowed for ${agent}`);
+    }
+    return {
+        ok: true,
+        value: normalized,
+    };
+}
+// START_CONTRACT: parseResultBlock
+//   PURPOSE: Parse strict top-block workflow protocol fields from tracked subagent output.
+//   INPUTS: { agent: TrackedAgentName - tracked subagent source, output: string - subagent textual output, expectedWorkItemId?: string - optional ID to match against parsed output }
+//   OUTPUTS: { ProtocolResult<ParsedResultBlock> - parsed protocol fields or protocol error }
+//   SIDE_EFFECTS: [none]
+//   LINKS: [M-WORKFLOW-PROTOCOL]
+// END_CONTRACT: parseResultBlock
+// START_BLOCK_PARSE_RESULT
+export function parseResultBlock(options) {
+    const topBlockLines = splitTopBlock(options.output);
+    const topBlockValidation = validateTopBlockLines(topBlockLines);
+    if (!topBlockValidation.ok) {
+        return topBlockValidation;
+    }
+    const workItemId = readTopBlockField(topBlockLines, "VVOC_WORK_ITEM_ID");
+    if (!workItemId) {
+        return createProtocolError("MISSING_WORK_ITEM_ID", "MISSING_WORK_ITEM_ID: strict top block must include VVOC_WORK_ITEM_ID");
+    }
+    if (!/^wi-\d+$/.test(workItemId)) {
+        return createProtocolError("MISSING_WORK_ITEM_ID", `MISSING_WORK_ITEM_ID: invalid work item id format ${workItemId}`);
+    }
+    if (options.expectedWorkItemId && options.expectedWorkItemId !== workItemId) {
+        return createProtocolError("WORK_ITEM_MISMATCH", `WORK_ITEM_MISMATCH: expected ${options.expectedWorkItemId} but parsed ${workItemId}`);
+    }
+    const rawStatus = readTopBlockField(topBlockLines, "VVOC_STATUS");
+    if (!rawStatus) {
+        return createProtocolError("MISSING_STATUS", "MISSING_STATUS: strict top block must include VVOC_STATUS");
+    }
+    const statusValidation = validateStatusForAgent(options.agent, rawStatus);
+    if (!statusValidation.ok) {
+        return statusValidation;
+    }
+    const route = readTopBlockField(topBlockLines, "VVOC_ROUTE");
+    if (options.agent === "vv-implementer" && !route) {
+        return createProtocolError("MISSING_ROUTE", "MISSING_ROUTE: vv-implementer output must include VVOC_ROUTE");
+    }
+    return {
+        ok: true,
+        value: {
+            agent: options.agent,
+            workItemId,
+            status: statusValidation.value,
+            ...(route ? { route } : {}),
+        },
+    };
+}
+// END_BLOCK_PARSE_RESULT
+// START_CONTRACT: parseWorkItemHeader
+//   PURPOSE: Extract VVOC_WORK_ITEM_ID from the first meaningful line of a tracked subagent prompt header.
+//   INPUTS: { promptText: string - full prompt text }
+//   OUTPUTS: { ProtocolResult<string> - parsed work item ID or protocol error }
+//   SIDE_EFFECTS: [none]
+//   LINKS: [M-WORKFLOW-PROTOCOL]
+// END_CONTRACT: parseWorkItemHeader
+export function parseWorkItemHeader(promptText) {
+    const lines = promptText.replace(/\r\n/g, "\n").split("\n");
+    const firstMeaningfulLine = lines.find((line) => line.trim().length > 0)?.trim();
+    if (!firstMeaningfulLine) {
+        return createProtocolError("MISSING_WORK_ITEM_HEADER", "MISSING_WORK_ITEM_HEADER: prompt must begin with VVOC_WORK_ITEM_ID header");
+    }
+    const match = WORK_ITEM_HEADER_RE.exec(firstMeaningfulLine);
+    if (!match) {
+        return createProtocolError("MALFORMED_WORK_ITEM_HEADER", `MALFORMED_WORK_ITEM_HEADER: first meaningful line must match \`VVOC_WORK_ITEM_ID: wi-<n>\` but received \`${firstMeaningfulLine}\``);
+    }
+    return {
+        ok: true,
+        value: match[1],
+    };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/plugins/workflow/protocol.js.map

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

package/dist/plugins/workflow/state.d.ts

@@ -0,0 +1,79 @@
+import type { TrackedAgentName } from "./protocol.js";
+export type WorkItemState = "open" | "awaiting_implementer" | "awaiting_spec_review" | "awaiting_code_review" | "needs_context" | "blocked" | "ready_to_close" | "closed";
+export type WorkItemRecord = {
+    sessionId: string;
+    workItemId: string;
+    key: string;
+    title: string;
+    state: WorkItemState;
+    specReviewCount: number;
+    codeReviewCount: number;
+    createdAt: string;
+    updatedAt: string;
+    closedAt?: string;
+};
+export type OpenWorkItemResult = {
+    ok: true;
+    reused: boolean;
+    record: WorkItemRecord;
+    header: string;
+} | {
+    ok: false;
+    errorCode: "WORK_ITEM_KEY_CONFLICT";
+    message: string;
+    existingWorkItemId: string;
+};
+export type CloseWorkItemResult = {
+    ok: true;
+    record: WorkItemRecord;
+    header: string;
+} | {
+    ok: false;
+    errorCode: "WORK_ITEM_NOT_FOUND" | "WORK_ITEM_ALREADY_CLOSED";
+    message: string;
+};
+export type TransitionWorkItemStateResult = {
+    ok: true;
+    record: WorkItemRecord;
+} | {
+    ok: false;
+    errorCode: "WORK_ITEM_NOT_FOUND" | "WORK_ITEM_ALREADY_CLOSED" | "INVALID_STATE_TRANSITION" | "MISSING_TRANSITION_ACTOR";
+    message: string;
+};
+export type WorkItemStore = {
+    openWorkItem: (input: {
+        sessionId: string;
+        key: string;
+        title: string;
+    }) => OpenWorkItemResult;
+    getWorkItem: (sessionId: string, workItemId: string) => WorkItemRecord | undefined;
+    listWorkItems: (sessionId: string, options?: {
+        includeClosed?: boolean;
+    }) => WorkItemRecord[];
+    closeWorkItem: (sessionId: string, workItemId: string) => CloseWorkItemResult;
+    transitionWorkItemState: (input: {
+        sessionId: string;
+        workItemId: string;
+        state: WorkItemState;
+        actor?: TrackedAgentName;
+    }) => TransitionWorkItemStateResult;
+    getReviewRound: (record: Pick<WorkItemRecord, "specReviewCount" | "codeReviewCount">) => number;
+};
+export declare function getReviewRound(record: Pick<WorkItemRecord, "specReviewCount" | "codeReviewCount">): number;
+export declare function createWorkItemStore(): WorkItemStore;
+export declare function openWorkItem(store: WorkItemStore, input: {
+    sessionId: string;
+    key: string;
+    title: string;
+}): OpenWorkItemResult;
+export declare function getWorkItem(store: WorkItemStore, sessionId: string, workItemId: string): WorkItemRecord | undefined;
+export declare function listWorkItems(store: WorkItemStore, sessionId: string, options?: {
+    includeClosed?: boolean;
+}): WorkItemRecord[];
+export declare function closeWorkItem(store: WorkItemStore, sessionId: string, workItemId: string): CloseWorkItemResult;
+export declare function transitionWorkItemState(store: WorkItemStore, input: {
+    sessionId: string;
+    workItemId: string;
+    state: WorkItemState;
+    actor?: TrackedAgentName;
+}): TransitionWorkItemStateResult;

package/dist/plugins/workflow/state.js

@@ -0,0 +1,307 @@
+// FILE: src/plugins/workflow/state.ts
+// VERSION: 0.1.2
+// START_MODULE_CONTRACT
+//   PURPOSE: Manage in-memory workflow work-item state scoped by session with idempotent open semantics.
+//   SCOPE: Session-scoped work-item storage, id generation, idempotent open-by-key, state transitions, review counters, and close/list/get operations.
+//   DEPENDS: [src/plugins/workflow/protocol.ts]
+//   LINKS: [M-WORKFLOW-STATE]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   WorkItemState - Allowed lifecycle states for a tracked work item.
+//   WorkItemRecord - Canonical in-memory state record for a work item.
+//   WorkItemStore - Store interface exposing deterministic workflow state operations.
+//   OpenWorkItemResult - Structured open operation result with idempotency and conflict signaling.
+//   CloseWorkItemResult - Structured close operation result.
+//   TransitionWorkItemStateResult - Structured transition operation result.
+//   createWorkItemStore - Creates a new in-memory store instance.
+//   openWorkItem - Opens an item idempotently by (sessionId, key).
+//   getWorkItem - Fetches an item by session and work-item id.
+//   listWorkItems - Lists session items with optional closed inclusion.
+//   closeWorkItem - Closes an existing open item.
+//   transitionWorkItemState - Applies deterministic state transitions and increments review counters.
+//   getReviewRound - Computes review round as max(specReviewCount, codeReviewCount).
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v0.1.2 - Required actor metadata for tracked transitions so reviewer counters cannot be bypassed by actor-less updates.]
+//   LAST_CHANGE: [v0.1.1 - Enforced deterministic transition invariants with sticky hard-stop states and optional closed-item listing support.]
+//   LAST_CHANGE: [v0.1.0 - Added session-scoped in-memory workflow state store with idempotent open, transitions, close/list/get, and review-round helpers.]
+// END_CHANGE_SUMMARY
+function createRecordLookupKey(sessionId, workItemId) {
+    return `${sessionId}::${workItemId}`;
+}
+function cloneRecord(record) {
+    return {
+        ...record,
+    };
+}
+function createHeader(workItemId) {
+    return `VVOC_WORK_ITEM_ID: ${workItemId}`;
+}
+function toIsoNow() {
+    return new Date().toISOString();
+}
+function openWorkItemInStore(store, input) {
+    const sessionIndex = store.keyIndexBySession.get(input.sessionId) ??
+        (() => {
+            const index = new Map();
+            store.keyIndexBySession.set(input.sessionId, index);
+            return index;
+        })();
+    const existingId = sessionIndex.get(input.key);
+    if (existingId) {
+        const existing = store.records.get(createRecordLookupKey(input.sessionId, existingId));
+        if (!existing) {
+            sessionIndex.delete(input.key);
+        }
+        else if (existing.title !== input.title) {
+            return {
+                ok: false,
+                errorCode: "WORK_ITEM_KEY_CONFLICT",
+                message: `WORK_ITEM_KEY_CONFLICT: key ${input.key} is already associated with a different title`,
+                existingWorkItemId: existing.workItemId,
+            };
+        }
+        else {
+            return {
+                ok: true,
+                reused: true,
+                record: cloneRecord(existing),
+                header: createHeader(existing.workItemId),
+            };
+        }
+    }
+    const workItemId = `wi-${store.nextId}`;
+    store.nextId += 1;
+    const now = toIsoNow();
+    const record = {
+        sessionId: input.sessionId,
+        workItemId,
+        key: input.key,
+        title: input.title,
+        state: "open",
+        specReviewCount: 0,
+        codeReviewCount: 0,
+        createdAt: now,
+        updatedAt: now,
+    };
+    sessionIndex.set(input.key, workItemId);
+    store.records.set(createRecordLookupKey(input.sessionId, workItemId), record);
+    return {
+        ok: true,
+        reused: false,
+        record: cloneRecord(record),
+        header: createHeader(workItemId),
+    };
+}
+function getWorkItemInStore(store, sessionId, workItemId) {
+    const record = store.records.get(createRecordLookupKey(sessionId, workItemId));
+    return record ? cloneRecord(record) : undefined;
+}
+function isTransitionAllowed(fromState, toState) {
+    const allowed = {
+        open: ["awaiting_spec_review", "needs_context", "blocked"],
+        awaiting_implementer: ["awaiting_spec_review", "needs_context", "blocked"],
+        awaiting_spec_review: ["awaiting_code_review", "awaiting_implementer", "needs_context"],
+        awaiting_code_review: ["ready_to_close", "awaiting_implementer", "needs_context"],
+        ready_to_close: [],
+        needs_context: [],
+        blocked: [],
+        closed: [],
+    };
+    return allowed[fromState].includes(toState);
+}
+function getAllowedActorForState(state) {
+    if (state === "open" || state === "awaiting_implementer") {
+        return "vv-implementer";
+    }
+    if (state === "awaiting_spec_review") {
+        return "vv-spec-reviewer";
+    }
+    if (state === "awaiting_code_review") {
+        return "vv-code-reviewer";
+    }
+    return undefined;
+}
+function listWorkItemsInStore(store, sessionId, options = {}) {
+    const includeClosed = options.includeClosed === true;
+    return [...store.records.values()]
+        .filter((record) => record.sessionId === sessionId && (includeClosed || record.state !== "closed"))
+        .sort((left, right) => {
+        const leftNumber = Number(left.workItemId.slice("wi-".length));
+        const rightNumber = Number(right.workItemId.slice("wi-".length));
+        return leftNumber - rightNumber;
+    })
+        .map((record) => cloneRecord(record));
+}
+function closeWorkItemInStore(store, sessionId, workItemId) {
+    const lookupKey = createRecordLookupKey(sessionId, workItemId);
+    const existing = store.records.get(lookupKey);
+    if (!existing) {
+        return {
+            ok: false,
+            errorCode: "WORK_ITEM_NOT_FOUND",
+            message: `WORK_ITEM_NOT_FOUND: no work item ${workItemId} for session ${sessionId}`,
+        };
+    }
+    if (existing.state === "closed") {
+        return {
+            ok: false,
+            errorCode: "WORK_ITEM_ALREADY_CLOSED",
+            message: `WORK_ITEM_ALREADY_CLOSED: ${workItemId} is already closed`,
+        };
+    }
+    const now = toIsoNow();
+    const updated = {
+        ...existing,
+        state: "closed",
+        closedAt: now,
+        updatedAt: now,
+    };
+    store.records.set(lookupKey, updated);
+    return {
+        ok: true,
+        record: cloneRecord(updated),
+        header: createHeader(workItemId),
+    };
+}
+function transitionWorkItemStateInStore(store, input) {
+    const lookupKey = createRecordLookupKey(input.sessionId, input.workItemId);
+    const existing = store.records.get(lookupKey);
+    if (!existing) {
+        return {
+            ok: false,
+            errorCode: "WORK_ITEM_NOT_FOUND",
+            message: `WORK_ITEM_NOT_FOUND: no work item ${input.workItemId} for session ${input.sessionId}`,
+        };
+    }
+    if (existing.state === "closed") {
+        return {
+            ok: false,
+            errorCode: "WORK_ITEM_ALREADY_CLOSED",
+            message: `WORK_ITEM_ALREADY_CLOSED: ${input.workItemId} is already closed`,
+        };
+    }
+    const allowedActor = getAllowedActorForState(existing.state);
+    if (allowedActor && !input.actor) {
+        return {
+            ok: false,
+            errorCode: "MISSING_TRANSITION_ACTOR",
+            message: `MISSING_TRANSITION_ACTOR: state ${existing.state} requires actor metadata`,
+        };
+    }
+    if (input.actor && allowedActor && input.actor !== allowedActor) {
+        return {
+            ok: false,
+            errorCode: "INVALID_STATE_TRANSITION",
+            message: `INVALID_STATE_TRANSITION: actor ${input.actor} is not allowed for state ${existing.state}`,
+        };
+    }
+    if (!isTransitionAllowed(existing.state, input.state)) {
+        return {
+            ok: false,
+            errorCode: "INVALID_STATE_TRANSITION",
+            message: `INVALID_STATE_TRANSITION: cannot transition from ${existing.state} to ${input.state}`,
+        };
+    }
+    const updated = {
+        ...existing,
+        state: input.state,
+        updatedAt: toIsoNow(),
+        specReviewCount: input.actor === "vv-spec-reviewer" ? existing.specReviewCount + 1 : existing.specReviewCount,
+        codeReviewCount: input.actor === "vv-code-reviewer" ? existing.codeReviewCount + 1 : existing.codeReviewCount,
+    };
+    store.records.set(lookupKey, updated);
+    return {
+        ok: true,
+        record: cloneRecord(updated),
+    };
+}
+// START_CONTRACT: getReviewRound
+//   PURPOSE: Compute deterministic review round from reviewer counters.
+//   INPUTS: { record: Pick<WorkItemRecord, "specReviewCount" | "codeReviewCount"> - review counters }
+//   OUTPUTS: { number - max(specReviewCount, codeReviewCount) }
+//   SIDE_EFFECTS: [none]
+//   LINKS: [M-WORKFLOW-STATE]
+// END_CONTRACT: getReviewRound
+export function getReviewRound(record) {
+    return Math.max(record.specReviewCount, record.codeReviewCount);
+}
+// START_CONTRACT: createWorkItemStore
+//   PURPOSE: Create a session-scoped in-memory work-item store with deterministic operation behavior.
+//   INPUTS: { none }
+//   OUTPUTS: { WorkItemStore - operation surface for open/get/list/close/transition operations }
+//   SIDE_EFFECTS: [none]
+//   LINKS: [M-WORKFLOW-STATE]
+// END_CONTRACT: createWorkItemStore
+export function createWorkItemStore() {
+    const data = {
+        nextId: 1,
+        records: new Map(),
+        keyIndexBySession: new Map(),
+    };
+    return {
+        openWorkItem: (input) => openWorkItemInStore(data, input),
+        getWorkItem: (sessionId, workItemId) => getWorkItemInStore(data, sessionId, workItemId),
+        listWorkItems: (sessionId, options) => listWorkItemsInStore(data, sessionId, options),
+        closeWorkItem: (sessionId, workItemId) => closeWorkItemInStore(data, sessionId, workItemId),
+        transitionWorkItemState: (input) => transitionWorkItemStateInStore(data, input),
+        getReviewRound,
+    };
+}
+// START_CONTRACT: openWorkItem
+//   PURPOSE: Open a work item idempotently by (sessionId, key) while enforcing key/title consistency.
+//   INPUTS: { store: WorkItemStoreData - backing store, input: { sessionId, key, title } - open parameters }
+//   OUTPUTS: { OpenWorkItemResult - success with record/header or WORK_ITEM_KEY_CONFLICT }
+//   SIDE_EFFECTS: [Mutates in-memory work-item store]
+//   LINKS: [M-WORKFLOW-STATE]
+// END_CONTRACT: openWorkItem
+export function openWorkItem(store, input) {
+    return store.openWorkItem(input);
+}
+// START_CONTRACT: getWorkItem
+//   PURPOSE: Return a work item by session and work-item id.
+//   INPUTS: { store: WorkItemStoreData - backing store, sessionId: string - session scope, workItemId: string - work item id }
+//   OUTPUTS: { WorkItemRecord | undefined - matching record when present }
+//   SIDE_EFFECTS: [none]
+//   LINKS: [M-WORKFLOW-STATE]
+// END_CONTRACT: getWorkItem
+export function getWorkItem(store, sessionId, workItemId) {
+    return store.getWorkItem(sessionId, workItemId);
+}
+// START_CONTRACT: listWorkItems
+//   PURPOSE: List session work items with optional closed-item inclusion.
+//   INPUTS: { store: WorkItemStoreData - backing store, sessionId: string - session scope, options?: { includeClosed?: boolean } - list behavior options }
+//   OUTPUTS: { WorkItemRecord[] - records sorted by numeric work-item id }
+//   SIDE_EFFECTS: [none]
+//   LINKS: [M-WORKFLOW-STATE]
+// END_CONTRACT: listWorkItems
+export function listWorkItems(store, sessionId, options) {
+    return store.listWorkItems(sessionId, options);
+}
+// START_CONTRACT: closeWorkItem
+//   PURPOSE: Close an existing open work item and stamp closedAt.
+//   INPUTS: { store: WorkItemStoreData - backing store, sessionId: string - session scope, workItemId: string - target id }
+//   OUTPUTS: { CloseWorkItemResult - success with updated record/header or failure code }
+//   SIDE_EFFECTS: [Mutates in-memory work-item store]
+//   LINKS: [M-WORKFLOW-STATE]
+// END_CONTRACT: closeWorkItem
+export function closeWorkItem(store, sessionId, workItemId) {
+    return store.closeWorkItem(sessionId, workItemId);
+}
+// START_CONTRACT: transitionWorkItemState
+//   PURPOSE: Update work-item state deterministically and maintain reviewer counters.
+//   INPUTS: { store: WorkItemStoreData - backing store, input: { sessionId, workItemId, state, actor? } - transition payload }
+//   OUTPUTS: { TransitionWorkItemStateResult - success with updated record or failure code }
+//   SIDE_EFFECTS: [Mutates in-memory work-item store]
+//   LINKS: [M-WORKFLOW-STATE]
+// END_CONTRACT: transitionWorkItemState
+// START_BLOCK_TRANSITION_STATE
+export function transitionWorkItemState(store, input) {
+    return store.transitionWorkItemState(input);
+}
+// END_BLOCK_TRANSITION_STATE
+//# sourceMappingURL=state.js.map

package/dist/plugins/workflow/state.js.map

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

package/dist/plugins/workflow/system-instruction.md

@@ -0,0 +1,14 @@
+<workflow_protocol>
+Workflow tracking is active for vv-managed review loops.
+
+For tracked subagents (`vv-implementer`, `vv-spec-reviewer`, `vv-code-reviewer`):
+
+1. Open work items first with `work_item_open`.
+2. Reuse the returned `VVOC_WORK_ITEM_ID`.
+3. Put that header as the first line in tracked subagent prompts.
+4. Treat `NEEDS_CONTEXT` as a hard stop.
+5. Use `work_item_list` to inspect workflow state before retrying.
+6. Avoid free-form review loops without explicit work-item identity.
+
+Use `work_item_close` explicitly when a work item is complete.
+</workflow_protocol>

package/dist/plugins/workflow/tooling.d.ts

@@ -0,0 +1,26 @@
+import { type WorkItemStore } from "./state.js";
+export type WorkflowToolContext = {
+    sessionId: string;
+};
+export type WorkflowToolDefinition<TArgs, TResult> = {
+    name: string;
+    description: string;
+    execute: (args: TArgs, context: WorkflowToolContext) => TResult;
+};
+type OpenInputItem = {
+    key: string;
+    title: string;
+};
+type OpenArgs = {
+    items: OpenInputItem[];
+};
+type ListArgs = {
+    includeClosed?: boolean;
+};
+type CloseArgs = {
+    workItemId: string;
+};
+export declare function createWorkItemOpenTool(store: WorkItemStore): WorkflowToolDefinition<OpenArgs, Record<string, unknown>>;
+export declare function createWorkItemListTool(store: WorkItemStore): WorkflowToolDefinition<ListArgs, Record<string, unknown>>;
+export declare function createWorkItemCloseTool(store: WorkItemStore): WorkflowToolDefinition<CloseArgs, Record<string, unknown>>;
+export {};