brainclaw 0.29.2 → 1.5.4

package/dist/core/io.js

@@ -22,9 +22,11 @@ const ENTITY_DIR_MAP = {
     'instructions': 'memory/instructions',
     // coordination/ — Agent↔Project: active work state
     'plans': 'coordination/plans',
+    'sequences': 'coordination/sequences',
     'claims': 'coordination/claims',
     'handoffs': 'coordination/handoffs',
     'sessions': 'coordination/sessions',
+    // Shared root: pending candidate JSONs live at inbox/, agent messages at inbox/{agent}/.
     'inbox': 'coordination/inbox',
     'inbox/accepted': 'coordination/inbox/accepted',
     'inbox/rejected': 'coordination/inbox/rejected',
@@ -32,6 +34,9 @@ const ENTITY_DIR_MAP = {
     'runtime-hosts': 'coordination/runtime-hosts',
     'runtime-private': 'coordination/runtime-private',
     'surface-tasks': 'coordination/surface-tasks',
+    'assignments': 'coordination/assignments',
+    'runs': 'coordination/runs',
+    'actions': 'coordination/actions',
     // discovery/ — Project entity: what's available
     'bootstrap': 'discovery/bootstrap',
     'bootstrap/seeds': 'discovery/bootstrap/seeds',
@@ -78,25 +83,97 @@ export function memoryPath(filename, cwd, preferredDirName) {
     return path.join(memoryDir(cwd, preferredDirName), filename);
 }
 export function storeLockPath(cwd, preferredDirName) {
-    return memoryPath(STORE_LOCK_BASENAME, cwd, preferredDirName);
+    const root = cwd ?? process.cwd();
+    const dirName = preferredDirName ?? MEMORY_DIR;
+    // Keep the store-wide lock alongside the store root so it survives
+    // upgrade park/swap renames. Writers and upgrade/rollback all share
+    // this stable target.
+    return path.join(root, `${dirName}${STORE_LOCK_BASENAME}`);
 }
 export function memoryExists(cwd, preferredDirName) {
     return fs.existsSync(memoryDir(cwd, preferredDirName));
 }
+/**
+ * Read the project vision from the first available source:
+ * 1. PROJECT.md at workspace root (human-written, canonical)
+ * 2. .brainclaw/project.md first non-header paragraph (legacy project.md export)
+ * Returns undefined if no vision is found.
+ */
+export function readProjectVision(cwd = process.cwd(), thresholdLines = 20) {
+    // 1. PROJECT.md at workspace root — canonical source
+    const projectMdPath = path.join(cwd, 'PROJECT.md');
+    if (fs.existsSync(projectMdPath)) {
+        try {
+            const content = fs.readFileSync(projectMdPath, 'utf-8').trim();
+            if (content) {
+                const lines = content.split('\n');
+                if (lines.length <= thresholdLines) {
+                    return content;
+                }
+                return `> **Project Domain Rules**\n> This project maintains detailed domain rules and architecture externally to avoid context bloat.\n> You MUST read \`PROJECT.md\` in the workspace root to understand the project constraints, tech stack, and conventions before coding.`;
+            }
+        }
+        catch { /* fall through */ }
+    }
+    // 2. .brainclaw/project.md — extract description from first paragraph after title
+    const legacyPath = path.join(cwd, MEMORY_DIR, 'project.md');
+    if (fs.existsSync(legacyPath)) {
+        try {
+            const content = fs.readFileSync(legacyPath, 'utf-8');
+            const vision = extractVisionFromProjectMd(content);
+            if (vision)
+                return vision;
+        }
+        catch { /* fall through */ }
+    }
+    return undefined;
+}
+/**
+ * Extract the vision paragraph from the legacy .brainclaw/project.md format.
+ * Looks for a description/vision section or the first non-header, non-list paragraph.
+ */
+function extractVisionFromProjectMd(content) {
+    const lines = content.split('\n');
+    // Look for a line that starts with a descriptive phrase, skip headers and list items
+    const descriptionLines = [];
+    let inSection = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip empty lines, markdown headers, sentinel lines, and list items at start
+        if (!trimmed) {
+            if (inSection && descriptionLines.length > 0)
+                break; // end of paragraph
+            continue;
+        }
+        if (trimmed.startsWith('#') || trimmed.startsWith('>') || trimmed.startsWith('- **['))
+            continue;
+        if (trimmed.startsWith('- (none)'))
+            continue;
+        // Found a content line
+        inSection = true;
+        descriptionLines.push(trimmed);
+    }
+    return descriptionLines.length > 0 ? descriptionLines.join('\n') : undefined;
+}
+/**
+ * Canonical list of entity-aligned subdirectories expected under `.brainclaw/`.
+ * Exposed so doctor + repair flows can audit presence without duplicating the
+ * list (pln#397 stp_b5337e30).
+ */
+export const REQUIRED_ENTITY_SUBDIRS = [
+    'memory/constraints', 'memory/decisions', 'memory/traps', 'memory/instructions',
+    'coordination/plans', 'coordination/sequences', 'coordination/claims', 'coordination/handoffs', 'coordination/sessions',
+    'coordination/inbox',
+    'discovery',
+    'agents',
+];
 export function ensureMemoryDir(cwd, preferredDirName) {
     const dir = memoryDir(cwd, preferredDirName);
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
     // Ensure entity-aligned subdirectories exist
-    const entityDirs = [
-        'memory/constraints', 'memory/decisions', 'memory/traps', 'memory/instructions',
-        'coordination/plans', 'coordination/claims', 'coordination/handoffs', 'coordination/sessions',
-        'coordination/inbox',
-        'discovery',
-        'agents',
-    ];
-    for (const subdir of entityDirs) {
+    for (const subdir of REQUIRED_ENTITY_SUBDIRS) {
         const p = path.join(dir, subdir);
         if (!fs.existsSync(p)) {
             fs.mkdirSync(p, { recursive: true });
@@ -104,8 +181,10 @@ export function ensureMemoryDir(cwd, preferredDirName) {
     }
 }
 export function withStoreLock(cwd = process.cwd(), fn, preferredDirName) {
-    ensureMemoryDir(cwd, preferredDirName);
-    return withLock(storeLockPath(cwd, preferredDirName), fn);
+    return withLock(storeLockPath(cwd, preferredDirName), () => {
+        ensureMemoryDir(cwd, preferredDirName);
+        return fn();
+    });
 }
 /** Check if a path is a file, or a directory with at least one entry. */
 function hasContent(p) {

package/dist/core/lock.js

@@ -37,8 +37,12 @@ function tryCreateLock(lockPath) {
         return true;
     }
     catch (err) {
-        if (err instanceof Error && 'code' in err && err.code === 'EEXIST')
-            return false;
+        if (err instanceof Error && 'code' in err) {
+            const code = err.code;
+            if (code === 'EEXIST' || code === 'EPERM' || code === 'EACCES') {
+                return false;
+            }
+        }
         throw err;
     }
 }

package/dist/core/loops/brief-assembly.js

@@ -0,0 +1,213 @@
+/**
+ * pln#492 phase 2.d.1 — Critic brief assembly (pure function).
+ *
+ * Builds the message a slot receives when its phase fires. Honours the
+ * phase's `context_filter` so the critic sees adversarial memory only
+ * (traps + feedback + runtime_notes + critique_history), the proposal
+ * sees positive context (decisions + constraints + plans + project_vision),
+ * and revision/synthesis see the full bundle via the '*' wildcard.
+ *
+ * BM25 ranking, top-K, and the underlying memory store are injected via
+ * `BriefMemoryProvider` so this module stays testable in isolation. The
+ * dispatch wire-up (phase 2.d.2) plugs in a real provider backed by
+ * bclaw_search.
+ *
+ * The bundle is capped at `maxChars` (default 48 000 ≈ 12 000 tokens at
+ * ~4 chars/token English) to mitigate trp#179 (oversized payloads on
+ * multi-trap projects forcing agents back to CLI fallbacks). Truncation
+ * is greedy by category-then-item order, with a "(memory bundle truncated
+ * — N items dropped)" tail so the operator can see when content was
+ * dropped.
+ */
+const DEFAULT_MAX_CHARS = 48_000;
+const DEFAULT_TOP_K_PER_CATEGORY = 8;
+/**
+ * Concrete categories the wildcard '*' resolves to. Excludes loop-internal
+ * categories (critique_history / revision_history / synthesis_artifact)
+ * because those are sourced from the thread itself, not from the memory
+ * provider.
+ */
+const WILDCARD_USER_FACING_CATEGORIES = [
+    'traps',
+    'feedback',
+    'runtime_notes',
+    'decisions',
+    'constraints',
+    'handoffs',
+    'plans',
+    'candidates',
+    'project_vision',
+];
+const LOOP_INTERNAL_CATEGORIES = new Set([
+    'critique_history',
+    'revision_history',
+    'synthesis_artifact',
+]);
+export function buildIdeationBrief(input) {
+    const { thread, slotRole, memoryProvider, maxChars = DEFAULT_MAX_CHARS, topKPerCategory = DEFAULT_TOP_K_PER_CATEGORY, } = input;
+    const proposal = findProposalArtifact(thread);
+    const proposalText = proposal?.body?.trim() ?? '(no proposal seed found)';
+    // Resolve which memory categories the current phase wants. If the
+    // current phase has no context_filter, fall back to '*' (full bundle).
+    const currentPhaseDef = thread.phases.find((p) => p.name === thread.current_phase);
+    const requestedCategories = currentPhaseDef?.context_filter ?? ['*'];
+    const userFacingCategories = expandUserFacingCategories(requestedCategories);
+    const includesLoopInternal = requestedCategories.some((c) => c === '*' || LOOP_INTERNAL_CATEGORIES.has(c));
+    const fetchedItemsByCategory = new Map();
+    const categoriesUsed = [];
+    for (const category of userFacingCategories) {
+        const items = memoryProvider.fetch(category, proposalText, topKPerCategory);
+        if (items.length > 0) {
+            fetchedItemsByCategory.set(category, items);
+            categoriesUsed.push(category);
+        }
+    }
+    // Loop-internal categories: pulled from thread.artifacts directly.
+    // critique_history → all critique artifacts in iterations < current.
+    // revision_history → all revision artifacts in iterations < current.
+    // synthesis_artifact → the most recent synthesis output (if any).
+    const priorArtifactsBlock = includesLoopInternal
+        ? renderPriorArtifactsBlock(thread, requestedCategories)
+        : '';
+    const header = renderHeader(thread, slotRole, currentPhaseDef?.name ?? thread.current_phase);
+    const proposalBlock = renderProposalBlock(proposalText);
+    const memoryBlock = renderMemoryBlock(fetchedItemsByCategory);
+    const closing = renderClosingInstructions(slotRole, thread.current_phase);
+    // Compose with truncation. The proposal seed and header are fixed;
+    // memory + prior artifacts share the remaining budget. Memory before
+    // prior-artifacts so the critic always sees fresh adversarial pressure.
+    const fixedParts = [header, proposalBlock, closing];
+    const fixedSize = fixedParts.reduce((n, s) => n + s.length, 0);
+    const remainingBudget = Math.max(0, maxChars - fixedSize);
+    const { text: truncatedMemory, truncated, droppedItems, includedItems } = truncateToBudget([memoryBlock, priorArtifactsBlock].filter((s) => s.length > 0), fetchedItemsByCategory, remainingBudget);
+    const text = [header, proposalBlock, truncatedMemory, closing]
+        .filter((s) => s.length > 0)
+        .join('\n\n');
+    return { text, truncated, includedItems, droppedItems, categoriesUsed };
+}
+/* ─────────────────────── helpers ─────────────────────── */
+function findProposalArtifact(thread) {
+    // Prefer the most recent proposal artifact (in case revisions added
+    // updated proposal artifacts later).
+    for (let i = thread.artifacts.length - 1; i >= 0; i--) {
+        const a = thread.artifacts[i];
+        if (a.type === 'proposal')
+            return a;
+    }
+    return undefined;
+}
+function expandUserFacingCategories(requested) {
+    if (requested.includes('*')) {
+        return [...WILDCARD_USER_FACING_CATEGORIES];
+    }
+    // Drop loop-internal categories — they're handled separately.
+    return requested.filter((c) => !LOOP_INTERNAL_CATEGORIES.has(c) && c !== '*');
+}
+function renderHeader(thread, slotRole, phase) {
+    const lines = [
+        `# ideation_loop brief`,
+        `loop: ${thread.id}`,
+        `phase: ${phase}`,
+        `iteration: ${thread.iteration_count}`,
+        `slot: ${slotRole}`,
+        `title: ${thread.title}`,
+    ];
+    if (thread.goal)
+        lines.push(`goal: ${thread.goal}`);
+    return lines.join('\n');
+}
+function renderProposalBlock(proposalText) {
+    return `## proposal\n\n${proposalText}`;
+}
+function renderMemoryBlock(byCategory) {
+    if (byCategory.size === 0)
+        return '';
+    const sections = ['## memory bundle (BM25-ranked, filtered by phase context)'];
+    for (const [category, items] of byCategory) {
+        sections.push(`### ${category}`);
+        for (const item of items) {
+            sections.push(`- [${item.id}] ${item.text}`);
+        }
+    }
+    return sections.join('\n');
+}
+function renderPriorArtifactsBlock(thread, requested) {
+    // Critique history is the most useful loop-internal feed for the
+    // critique phase: round 2+ critics see what was already raised so they
+    // do not duplicate. revision_history gives them the proposer's response.
+    const wantsCritique = requested.includes('*') || requested.includes('critique_history');
+    const wantsRevision = requested.includes('*') || requested.includes('revision_history');
+    const wantsSynthesis = requested.includes('*') || requested.includes('synthesis_artifact');
+    const sections = [];
+    if (wantsCritique) {
+        const priorCritique = thread.artifacts.filter((a) => a.type === 'critique' && (a.iteration ?? 0) < thread.iteration_count);
+        if (priorCritique.length > 0) {
+            const lines = ['### critique_history (prior iterations)'];
+            for (const a of priorCritique) {
+                lines.push(`- [${a.artifact_id}] (iter ${a.iteration ?? 0}) ${truncateLine(a.body)}`);
+            }
+            sections.push(lines.join('\n'));
+        }
+    }
+    if (wantsRevision) {
+        const priorRevision = thread.artifacts.filter((a) => a.phase === 'revision' && (a.iteration ?? 0) < thread.iteration_count);
+        if (priorRevision.length > 0) {
+            const lines = ['### revision_history (prior iterations)'];
+            for (const a of priorRevision) {
+                lines.push(`- [${a.artifact_id}] (iter ${a.iteration ?? 0}) ${truncateLine(a.body)}`);
+            }
+            sections.push(lines.join('\n'));
+        }
+    }
+    if (wantsSynthesis) {
+        const synthesis = [...thread.artifacts]
+            .reverse()
+            .find((a) => a.phase === 'synthesis' && a.type === 'plan_draft');
+        if (synthesis) {
+            sections.push(`### synthesis_artifact\n- [${synthesis.artifact_id}] ${truncateLine(synthesis.body)}`);
+        }
+    }
+    if (sections.length === 0)
+        return '';
+    return ['## prior loop artifacts', ...sections].join('\n\n');
+}
+function renderClosingInstructions(slotRole, phase) {
+    return [
+        `## what to produce`,
+        `- Phase "${phase}" expects you to act in role "${slotRole}".`,
+        `- Emit findings as LoopArtifacts via bclaw_loop intent='complete_turn' or 'add_artifact'.`,
+        `- Cite the memory ids you relied on so the synthesis can audit coverage.`,
+    ].join('\n');
+}
+function truncateLine(s, maxLen = 200) {
+    if (!s)
+        return '(no body)';
+    return s.length > maxLen ? `${s.slice(0, maxLen)}…` : s;
+}
+/**
+ * Greedy truncation of the variable parts (memory bundle + prior artifacts)
+ * to fit the remaining budget. We count items so the caller can warn about
+ * dropped content.
+ */
+function truncateToBudget(blocks, byCategory, budget) {
+    const totalItems = [...byCategory.values()].reduce((n, arr) => n + arr.length, 0);
+    if (blocks.length === 0) {
+        return { text: '', truncated: false, includedItems: 0, droppedItems: 0 };
+    }
+    const joined = blocks.join('\n\n');
+    if (joined.length <= budget) {
+        return { text: joined, truncated: false, includedItems: totalItems, droppedItems: 0 };
+    }
+    // Truncate hard at the budget boundary, append a tail noting the cut.
+    const tail = '\n\n_(memory bundle truncated to fit the brief size cap; some items were dropped — re-run with a smaller proposal or a per-category top-K to surface the missing ones)_';
+    const headRoom = Math.max(0, budget - tail.length);
+    const truncatedHead = joined.slice(0, headRoom);
+    const text = truncatedHead + tail;
+    // Approximate dropped item count: count "- [id]" markers in the
+    // dropped tail vs total.
+    const droppedTail = joined.slice(headRoom);
+    const droppedItems = (droppedTail.match(/^- \[/gm) ?? []).length;
+    const includedItems = Math.max(0, totalItems - droppedItems);
+    return { text, truncated: true, includedItems, droppedItems };
+}
+//# sourceMappingURL=brief-assembly.js.map

package/dist/core/loops/facade-schema.js

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+import { LOOP_KINDS, LOOP_STATUSES, LoopLinksSchema, LoopPhaseSchema, LoopRefSchema, LoopSlotSchema, REVIEW_MODES, StopConditionSchema, } from './types.js';
+/**
+ * `bclaw_loop(intent)` request schemas — one per intent, unioned into a
+ * discriminated schema. Mirrors the BclawLoopInput type from the v8 RFC.
+ */
+const CallerEnvelopeFields = {
+    agent: z.string().optional(),
+    agentId: z.string().optional(),
+    client_request_id: z.string().min(1).optional(),
+};
+/**
+ * Slot input shape for `bclaw_loop(intent='open')`. Loosens the persisted
+ * `LoopSlotSchema` (which requires server-assigned fields like `slot_id`
+ * and `status`) so callers only need to supply `role` plus any optional
+ * hints. Exported so it can be consumed both by `BclawLoopOpenSchema`
+ * below AND by the build-time MCP schema generator (pln#494 phase 2).
+ */
+export const LoopSlotInputSchema = LoopSlotSchema.partial().extend({
+    role: z.string().min(1),
+});
+export const BclawLoopOpenSchema = z.object({
+    intent: z.literal('open'),
+    kind: z.enum(LOOP_KINDS),
+    title: z.string().min(1),
+    goal: z.string().optional(),
+    phases: z.array(LoopPhaseSchema).optional(),
+    slots: z.array(LoopSlotInputSchema).optional(),
+    linked: LoopLinksSchema.optional(),
+    stop_condition: StopConditionSchema.optional(),
+    mode: z.enum(REVIEW_MODES).optional(),
+    // Opt-in acknowledgement that the caller will drive dispatch manually.
+    // Absent (or false) → handler rejects with a pointer to bclaw_coordinate,
+    // because a loop opened without a follow-up turn/claim/inbox never runs.
+    // See pln#461.
+    allow_orphan: z.boolean().optional(),
+    ...CallerEnvelopeFields,
+});
+export const BclawLoopGetSchema = z.object({
+    intent: z.literal('get'),
+    loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    include_events: z.boolean().optional(),
+    ...CallerEnvelopeFields,
+});
+export const BclawLoopListSchema = z.object({
+    intent: z.literal('list'),
+    kind: z.enum(LOOP_KINDS).optional(),
+    status: z.enum(LOOP_STATUSES).optional(),
+    limit: z.number().int().positive().optional(),
+    offset: z.number().int().nonnegative().optional(),
+    ...CallerEnvelopeFields,
+});
+export const BclawLoopTurnSchema = z.object({
+    intent: z.literal('turn'),
+    loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    slot_id: z.string().optional(),
+    role: z.string().optional(),
+    input: z.string().optional(),
+    assignment_id: z.string().optional(),
+    dispatch: z.boolean().optional(),
+    expected_version: z.number().int().nonnegative().optional(),
+    ...CallerEnvelopeFields,
+});
+export const BclawLoopCompleteTurnSchema = z.object({
+    intent: z.literal('complete_turn'),
+    loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    slot_id: z.string().min(1),
+    outcome: z.enum(['done', 'failed', 'cancelled']).optional(),
+    failure_reason: z.string().optional(),
+    artifact: z
+        .object({
+        phase: z.string().min(1),
+        type: z.string().min(1),
+        body: z.string().optional(),
+        ref: LoopRefSchema.optional(),
+    })
+        .optional(),
+    expected_version: z.number().int().nonnegative().optional(),
+    ...CallerEnvelopeFields,
+});
+export const BclawLoopAdvanceSchema = z.object({
+    intent: z.literal('advance'),
+    loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    to_phase: z.string().optional(),
+    reason: z.string().optional(),
+    force: z.boolean().optional(),
+    expected_version: z.number().int().nonnegative().optional(),
+    ...CallerEnvelopeFields,
+});
+export const BclawLoopAddArtifactSchema = z.object({
+    intent: z.literal('add_artifact'),
+    loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    artifact: z.object({
+        phase: z.string().min(1),
+        type: z.string().min(1),
+        body: z.string().optional(),
+        produced_by: z.string().optional(),
+        ref: LoopRefSchema.optional(),
+    }),
+    expected_version: z.number().int().nonnegative().optional(),
+    ...CallerEnvelopeFields,
+});
+export const BclawLoopPauseSchema = z.object({
+    intent: z.literal('pause'),
+    loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    reason: z.string().optional(),
+    expected_version: z.number().int().nonnegative().optional(),
+    ...CallerEnvelopeFields,
+});
+export const BclawLoopResumeSchema = z.object({
+    intent: z.literal('resume'),
+    loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    expected_version: z.number().int().nonnegative().optional(),
+    ...CallerEnvelopeFields,
+});
+export const BclawLoopCloseSchema = z.object({
+    intent: z.literal('close'),
+    loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    status: z.enum(['completed', 'cancelled', 'blocked']),
+    reason: z.string().optional(),
+    expected_version: z.number().int().nonnegative().optional(),
+    ...CallerEnvelopeFields,
+});
+export const BclawLoopRequestSchema = z.discriminatedUnion('intent', [
+    BclawLoopOpenSchema,
+    BclawLoopGetSchema,
+    BclawLoopListSchema,
+    BclawLoopTurnSchema,
+    BclawLoopCompleteTurnSchema,
+    BclawLoopAdvanceSchema,
+    BclawLoopAddArtifactSchema,
+    BclawLoopPauseSchema,
+    BclawLoopResumeSchema,
+    BclawLoopCloseSchema,
+]);
+export const BCLAW_LOOP_INTENTS = [
+    'open',
+    'get',
+    'list',
+    'turn',
+    'complete_turn',
+    'advance',
+    'add_artifact',
+    'pause',
+    'resume',
+    'close',
+];
+//# sourceMappingURL=facade-schema.js.map

package/dist/core/loops/index.js

@@ -0,0 +1,7 @@
+export * from './types.js';
+export { closeLoop, ensureLoopsDir, generateLoopId, generateMutationId, generateSlotId, getLoop, listLoopEvents, listLoops, openLoop, } from './store.js';
+export { add_artifact, advance, complete_turn, evaluatePhaseAdvanceGate, evaluateStopCondition, pause, resume, turn, } from './verbs.js';
+export { decideNextPhase, artifactsInIteration, noNewCritiqueInIteration, hasCriticSignalInIteration, } from './iteration-engine.js';
+export { buildIdeationBrief, } from './brief-assembly.js';
+export { acquireLock, hashRequest, recordConflict, withLoopLock, DEFAULT_MAX_MUTATION_DURATION_MS, IDEMPOTENCY_TTL_MS, LEASE_GRACE_MS, LEASE_WINDOW_MS, IdempotencyKeyReusedError, IdempotencyOwnerMismatchError, LockLostError, LockTimeoutError, VersionConflictError, } from './lock.js';
+//# sourceMappingURL=index.js.map

package/dist/core/loops/iteration-engine.js

@@ -0,0 +1,139 @@
+/**
+ * pln#492 phase 2.b — Finite state machine for ideation_loop iteration.
+ *
+ * The driver consults this module before mutating phase state on a loop
+ * with an `iteration` block. The engine is pure: it inspects a thread +
+ * its protocol shape and returns a structured decision. Applying the
+ * decision (mutating thread, appending events, persisting) is the
+ * advance() verb's job.
+ *
+ * Naming the engine an FSM in the file structure is a deliberate
+ * implementation discipline (stp_af207293 in pln#492): states = phases,
+ * transitions = exit_when conditions + cycle membership, guards = phase
+ * advance_gate, actions = system event emissions.
+ */
+/**
+ * Decide the next phase given the current thread state and the protocol.
+ *
+ * Throws if `current_phase` is not in `protocol.phases`. Throws if there
+ * is no successor (last phase + no iteration block). Callers that want
+ * to handle "already at end" should check beforehand.
+ */
+export function decideNextPhase(thread, protocol) {
+    const phaseNames = protocol.phases.map((p) => p.name);
+    const currentIndex = phaseNames.indexOf(thread.current_phase);
+    if (currentIndex < 0) {
+        throw new Error(`decideNextPhase: current_phase "${thread.current_phase}" not in protocol.phases`);
+    }
+    const cycle = protocol.iteration?.cycle ?? [];
+    const inCycle = cycle.includes(thread.current_phase);
+    // Path 1 — current phase is not in the iteration cycle. Linear advance.
+    if (!inCycle) {
+        if (currentIndex + 1 >= phaseNames.length) {
+            throw new Error(`advance: already at last phase "${thread.current_phase}"`);
+        }
+        return {
+            kind: 'advance_to',
+            target: phaseNames[currentIndex + 1],
+            iteration: thread.iteration_count,
+        };
+    }
+    // Path 2 — current phase is inside the cycle. Two sub-cases:
+    //   2a. Not at the end of the cycle yet → step within cycle.
+    //   2b. At the end of the cycle → either iterate, exit by exit_when, or
+    //       exit by max_iterations.
+    const cycleIndex = cycle.indexOf(thread.current_phase);
+    const atCycleEnd = cycleIndex === cycle.length - 1;
+    if (!atCycleEnd) {
+        return {
+            kind: 'advance_to',
+            target: cycle[cycleIndex + 1],
+            iteration: thread.iteration_count,
+        };
+    }
+    // 2b — end of cycle. Compute the post-cycle target (phase after the
+    // last cycle phase in the protocol order). We use the protocol's
+    // declared phase order, not the cycle, because the cycle may be a
+    // sub-sequence of phases (e.g. [critique, revision] within
+    // [proposal, critique, revision, synthesis]).
+    const lastCyclePhaseIndex = phaseNames.indexOf(cycle[cycle.length - 1]);
+    if (lastCyclePhaseIndex < 0 || lastCyclePhaseIndex + 1 >= phaseNames.length) {
+        throw new Error(`decideNextPhase: cycle's last phase "${cycle[cycle.length - 1]}" has no post-cycle successor`);
+    }
+    const postCycleTarget = phaseNames[lastCyclePhaseIndex + 1];
+    const iterationBlock = protocol.iteration;
+    if (!iterationBlock) {
+        // Defensive: `inCycle` was true so iteration should be set. If we
+        // got here despite that, fall through to a linear advance.
+        return {
+            kind: 'advance_to',
+            target: postCycleTarget,
+            iteration: thread.iteration_count,
+        };
+    }
+    // Evaluate exit_when on the just-finished iteration. The current
+    // iteration_count is the one that just completed (the engine has not
+    // yet incremented).
+    if (iterationBlock.exit_when === 'critic_signal' &&
+        hasCriticSignalInIteration(thread, thread.iteration_count)) {
+        return {
+            kind: 'exit_cycle',
+            target: postCycleTarget,
+            iteration: thread.iteration_count,
+            reason: 'critic_signal',
+        };
+    }
+    if (iterationBlock.exit_when === 'no_new_critique_artifacts' &&
+        noNewCritiqueInIteration(thread, thread.iteration_count)) {
+        return {
+            kind: 'exit_cycle',
+            target: postCycleTarget,
+            iteration: thread.iteration_count,
+            reason: 'no_new_critique_artifacts',
+        };
+    }
+    // Cap check. If incrementing iteration_count would exceed the cap,
+    // exit via max_iterations. (iteration_count is 0-indexed; cap=3 means
+    // iterations 0, 1, 2 are allowed; refusing iteration 3 → exit.)
+    if (thread.iteration_count + 1 >= iterationBlock.max_iterations) {
+        return {
+            kind: 'max_iterations',
+            target: postCycleTarget,
+            iteration: thread.iteration_count + 1,
+            max: iterationBlock.max_iterations,
+        };
+    }
+    // Otherwise iterate: cycle back to the first phase of the cycle and
+    // bump iteration_count.
+    return {
+        kind: 'iterate_to',
+        target: cycle[0],
+        iteration: thread.iteration_count + 1,
+    };
+}
+/**
+ * Returns the artifacts produced in a specific iteration window. If an
+ * artifact has no `iteration` field (legacy, non-iterating loops, or
+ * pre-phase-2.b data), it is treated as belonging to iteration 0 so
+ * existing review_loop usage is unaffected.
+ */
+export function artifactsInIteration(thread, iteration) {
+    return thread.artifacts.filter((a) => (a.iteration ?? 0) === iteration);
+}
+/**
+ * `exit_when='no_new_critique_artifacts'` predicate: true when the
+ * just-completed iteration produced no critique-typed artifacts. Used
+ * by `decideNextPhase` at the cycle boundary.
+ */
+export function noNewCritiqueInIteration(thread, iteration) {
+    return !thread.artifacts.some((a) => (a.iteration ?? 0) === iteration && a.type === 'critique');
+}
+/**
+ * `exit_when='critic_signal'` predicate: true when the iteration
+ * contains a `type='critic_signal'` artifact (any subtype/body). The
+ * critic emits this when it judges the proposal sufficient.
+ */
+export function hasCriticSignalInIteration(thread, iteration) {
+    return thread.artifacts.some((a) => (a.iteration ?? 0) === iteration && a.type === 'critic_signal');
+}
+//# sourceMappingURL=iteration-engine.js.map