@s_s/harmonia 1.2.0 → 1.3.0

package/build/core/dispatch.d.ts

@@ -1,41 +1,44 @@
 /**
  * Dispatch & Session tracking — manages:
- *   <data_dir>/<project_name>/iter-<n>/sessions.json
- *   <data_dir>/<project_name>/iter-<n>/dispatches.json
+ *   <context_dir>/sessions.json
+ *   <context_dir>/dispatches.json
+ *
+ * context_dir is typically iter-<n>/ or patch-<n>/ under the project data dir.
+ * All public functions accept an optional contextDir parameter.
  *
  * Sessions represent agent instances (can be reused across dispatches).
  * Dispatches represent individual task assignments to a role.
  * Relationship: Session 1:N Dispatch (a persistent session can receive multiple dispatches).
  */
 import type { AgentType, SessionRecord, SessionStatus, DispatchRecord, DispatchStatus } from './types.js';
-export declare function readSessions(projectName: string, iteration: number): Promise<SessionRecord[]>;
-export declare function createSession(projectName: string, iteration: number, role: string, agentType?: AgentType, label?: string): Promise<SessionRecord>;
+export declare function readSessions(projectName: string, iteration: number, contextDir?: string): Promise<SessionRecord[]>;
+export declare function createSession(projectName: string, iteration: number, role: string, agentType?: AgentType, label?: string, contextDir?: string): Promise<SessionRecord>;
 export declare function updateSession(projectName: string, iteration: number, sessionId: string, updates: {
     status?: SessionStatus;
     agentSessionId?: string;
     agentType?: AgentType;
     label?: string;
-}): Promise<SessionRecord>;
+}, contextDir?: string): Promise<SessionRecord>;
 /**
  * Find an idle session for a given role (for session reuse).
  * Returns the most recently active idle session, or null if none found.
  */
-export declare function findIdleSession(projectName: string, iteration: number, role: string): Promise<SessionRecord | null>;
+export declare function findIdleSession(projectName: string, iteration: number, role: string, contextDir?: string): Promise<SessionRecord | null>;
 /**
  * Find a session by its agent session ID (for correlating external sessions).
  */
-export declare function findSessionByAgentId(projectName: string, iteration: number, role: string, agentSessionId: string): Promise<SessionRecord | null>;
-export declare function readDispatches(projectName: string, iteration: number): Promise<DispatchRecord[]>;
-export declare function createDispatch(projectName: string, iteration: number, role: string, taskBrief: string, expectedOutputs: string[], sessionId?: string): Promise<DispatchRecord>;
+export declare function findSessionByAgentId(projectName: string, iteration: number, role: string, agentSessionId: string, contextDir?: string): Promise<SessionRecord | null>;
+export declare function readDispatches(projectName: string, iteration: number, contextDir?: string): Promise<DispatchRecord[]>;
+export declare function createDispatch(projectName: string, iteration: number, role: string, taskBrief: string, expectedOutputs: string[], sessionId?: string, contextDir?: string): Promise<DispatchRecord>;
 export declare function updateDispatch(projectName: string, iteration: number, dispatchId: string, updates: {
     status?: DispatchStatus;
     sessionId?: string;
     note?: string;
-}): Promise<DispatchRecord>;
+}, contextDir?: string): Promise<DispatchRecord>;
 /**
  * Get a single dispatch record by ID.
  */
-export declare function getDispatch(projectName: string, iteration: number, dispatchId: string): Promise<DispatchRecord | null>;
+export declare function getDispatch(projectName: string, iteration: number, dispatchId: string, contextDir?: string): Promise<DispatchRecord | null>;
 /** Valid state transitions for dispatch status. */
 export declare const DISPATCH_TRANSITIONS: Record<DispatchStatus, DispatchStatus[]>;
 /**

package/build/core/dispatch.js

@@ -1,7 +1,10 @@
 /**
  * Dispatch & Session tracking — manages:
- *   <data_dir>/<project_name>/iter-<n>/sessions.json
- *   <data_dir>/<project_name>/iter-<n>/dispatches.json
+ *   <context_dir>/sessions.json
+ *   <context_dir>/dispatches.json
+ *
+ * context_dir is typically iter-<n>/ or patch-<n>/ under the project data dir.
+ * All public functions accept an optional contextDir parameter.
  *
  * Sessions represent agent instances (can be reused across dispatches).
  * Dispatches represent individual task assignments to a role.
@@ -12,24 +15,26 @@ import { join, dirname } from 'node:path';
 import { getIterationDir } from './registry.js';
 const SESSIONS_FILE = 'sessions.json';
 const DISPATCHES_FILE = 'dispatches.json';
-function sessionsPath(projectName, iteration) {
-    return join(getIterationDir(projectName, iteration), SESSIONS_FILE);
+function sessionsPath(projectName, iteration, contextDir) {
+    const base = contextDir ?? getIterationDir(projectName, iteration);
+    return join(base, SESSIONS_FILE);
 }
-function dispatchesPath(projectName, iteration) {
-    return join(getIterationDir(projectName, iteration), DISPATCHES_FILE);
+function dispatchesPath(projectName, iteration, contextDir) {
+    const base = contextDir ?? getIterationDir(projectName, iteration);
+    return join(base, DISPATCHES_FILE);
 }
 // ─── Session CRUD ───
-export async function readSessions(projectName, iteration) {
+export async function readSessions(projectName, iteration, contextDir) {
     try {
-        const content = await readFile(sessionsPath(projectName, iteration), 'utf-8');
+        const content = await readFile(sessionsPath(projectName, iteration, contextDir), 'utf-8');
         return JSON.parse(content);
     }
     catch {
         return [];
     }
 }
-async function writeSessions(projectName, iteration, sessions) {
-    const filePath = sessionsPath(projectName, iteration);
+async function writeSessions(projectName, iteration, sessions, contextDir) {
+    const filePath = sessionsPath(projectName, iteration, contextDir);
     await mkdir(dirname(filePath), { recursive: true });
     await writeFile(filePath, JSON.stringify(sessions, null, 2) + '\n', 'utf-8');
 }
@@ -37,8 +42,8 @@ function nextSessionId(sessions) {
     const num = sessions.length + 1;
     return `ses-${String(num).padStart(3, '0')}`;
 }
-export async function createSession(projectName, iteration, role, agentType, label) {
-    const sessions = await readSessions(projectName, iteration);
+export async function createSession(projectName, iteration, role, agentType, label, contextDir) {
+    const sessions = await readSessions(projectName, iteration, contextDir);
     const now = new Date().toISOString();
     const session = {
         id: nextSessionId(sessions),
@@ -50,11 +55,11 @@ export async function createSession(projectName, iteration, role, agentType, lab
         lastActiveAt: now,
     };
     sessions.push(session);
-    await writeSessions(projectName, iteration, sessions);
+    await writeSessions(projectName, iteration, sessions, contextDir);
     return session;
 }
-export async function updateSession(projectName, iteration, sessionId, updates) {
-    const sessions = await readSessions(projectName, iteration);
+export async function updateSession(projectName, iteration, sessionId, updates, contextDir) {
+    const sessions = await readSessions(projectName, iteration, contextDir);
     const session = sessions.find((s) => s.id === sessionId);
     if (!session) {
         throw new Error(`Session "${sessionId}" not found in project "${projectName}"`);
@@ -68,15 +73,15 @@ export async function updateSession(projectName, iteration, sessionId, updates)
     if (updates.label !== undefined)
         session.label = updates.label;
     session.lastActiveAt = new Date().toISOString();
-    await writeSessions(projectName, iteration, sessions);
+    await writeSessions(projectName, iteration, sessions, contextDir);
     return session;
 }
 /**
  * Find an idle session for a given role (for session reuse).
  * Returns the most recently active idle session, or null if none found.
  */
-export async function findIdleSession(projectName, iteration, role) {
-    const sessions = await readSessions(projectName, iteration);
+export async function findIdleSession(projectName, iteration, role, contextDir) {
+    const sessions = await readSessions(projectName, iteration, contextDir);
     const idle = sessions
         .filter((s) => s.role === role && s.status === 'idle')
         .sort((a, b) => b.lastActiveAt.localeCompare(a.lastActiveAt));
@@ -85,22 +90,22 @@ export async function findIdleSession(projectName, iteration, role) {
 /**
  * Find a session by its agent session ID (for correlating external sessions).
  */
-export async function findSessionByAgentId(projectName, iteration, role, agentSessionId) {
-    const sessions = await readSessions(projectName, iteration);
+export async function findSessionByAgentId(projectName, iteration, role, agentSessionId, contextDir) {
+    const sessions = await readSessions(projectName, iteration, contextDir);
     return sessions.find((s) => s.role === role && s.agentSessionId === agentSessionId) ?? null;
 }
 // ─── Dispatch CRUD ───
-export async function readDispatches(projectName, iteration) {
+export async function readDispatches(projectName, iteration, contextDir) {
     try {
-        const content = await readFile(dispatchesPath(projectName, iteration), 'utf-8');
+        const content = await readFile(dispatchesPath(projectName, iteration, contextDir), 'utf-8');
         return JSON.parse(content);
     }
     catch {
         return [];
     }
 }
-async function writeDispatches(projectName, iteration, dispatches) {
-    const filePath = dispatchesPath(projectName, iteration);
+async function writeDispatches(projectName, iteration, dispatches, contextDir) {
+    const filePath = dispatchesPath(projectName, iteration, contextDir);
     await mkdir(dirname(filePath), { recursive: true });
     await writeFile(filePath, JSON.stringify(dispatches, null, 2) + '\n', 'utf-8');
 }
@@ -108,8 +113,8 @@ function nextDispatchId(dispatches) {
     const num = dispatches.length + 1;
     return `dispatch-${String(num).padStart(3, '0')}`;
 }
-export async function createDispatch(projectName, iteration, role, taskBrief, expectedOutputs, sessionId) {
-    const dispatches = await readDispatches(projectName, iteration);
+export async function createDispatch(projectName, iteration, role, taskBrief, expectedOutputs, sessionId, contextDir) {
+    const dispatches = await readDispatches(projectName, iteration, contextDir);
     const now = new Date().toISOString();
     const dispatch = {
         id: nextDispatchId(dispatches),
@@ -122,11 +127,11 @@ export async function createDispatch(projectName, iteration, role, taskBrief, ex
         ...(sessionId ? { sessionId } : {}),
     };
     dispatches.push(dispatch);
-    await writeDispatches(projectName, iteration, dispatches);
+    await writeDispatches(projectName, iteration, dispatches, contextDir);
     return dispatch;
 }
-export async function updateDispatch(projectName, iteration, dispatchId, updates) {
-    const dispatches = await readDispatches(projectName, iteration);
+export async function updateDispatch(projectName, iteration, dispatchId, updates, contextDir) {
+    const dispatches = await readDispatches(projectName, iteration, contextDir);
     const dispatch = dispatches.find((d) => d.id === dispatchId);
     if (!dispatch) {
         throw new Error(`Dispatch "${dispatchId}" not found in project "${projectName}"`);
@@ -143,14 +148,14 @@ export async function updateDispatch(projectName, iteration, dispatchId, updates
     if (updates.note !== undefined)
         dispatch.note = updates.note;
     dispatch.updatedAt = now;
-    await writeDispatches(projectName, iteration, dispatches);
+    await writeDispatches(projectName, iteration, dispatches, contextDir);
     return dispatch;
 }
 /**
  * Get a single dispatch record by ID.
  */
-export async function getDispatch(projectName, iteration, dispatchId) {
-    const dispatches = await readDispatches(projectName, iteration);
+export async function getDispatch(projectName, iteration, dispatchId, contextDir) {
+    const dispatches = await readDispatches(projectName, iteration, contextDir);
     return dispatches.find((d) => d.id === dispatchId) ?? null;
 }
 // ─── Dispatch State Machine ───

package/build/core/dispatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/core/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,MAAM,aAAa,GAAG,eAAe,CAAC;AACtC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAE1C,SAAS,YAAY,CAAC,WAAmB,EAAE,SAAiB;IACxD,OAAO,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,SAAS,CAAC,EAAE,aAAa,CAAC,CAAC;AACxE,CAAC;AAED,SAAS,cAAc,CAAC,WAAmB,EAAE,SAAiB;IAC1D,OAAO,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,SAAS,CAAC,EAAE,eAAe,CAAC,CAAC;AAC1E,CAAC;AAED,uBAAuB;AAEvB,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,WAAmB,EAAE,SAAiB;IACrE,IAAI,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,WAAW,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,EAAE,CAAC;IACd,CAAC;AACL,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,WAAmB,EAAE,SAAiB,EAAE,QAAyB;IAC1F,MAAM,QAAQ,GAAG,YAAY,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACtD,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACjF,CAAC;AAED,SAAS,aAAa,CAAC,QAAyB;IAC5C,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IAChC,OAAO,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAC/B,WAAmB,EACnB,SAAiB,EACjB,IAAY,EACZ,SAAqB,EACrB,KAAc;IAEd,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC5D,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAErC,MAAM,OAAO,GAAkB;QAC3B,EAAE,EAAE,aAAa,CAAC,QAAQ,CAAC;QAC3B,IAAI;QACJ,SAAS;QACT,MAAM,EAAE,QAAQ;QAChB,KAAK;QACL,SAAS,EAAE,GAAG;QACd,YAAY,EAAE,GAAG;KACpB,CAAC;IAEF,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvB,MAAM,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IACtD,OAAO,OAAO,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAC/B,WAAmB,EACnB,SAAiB,EACjB,SAAiB,EACjB,OAKC;IAED,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC;IAEzD,IAAI,CAAC,OAAO,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,YAAY,SAAS,2BAA2B,WAAW,GAAG,CAAC,CAAC;IACpF,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAClE,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS;QAAE,OAAO,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAC1F,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAC3E,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC/D,OAAO,CAAC,YAAY,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAEhD,MAAM,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IACtD,OAAO,OAAO,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACjC,WAAmB,EACnB,SAAiB,EACjB,IAAY;IAEZ,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,QAAQ;SAChB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC;SACrD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACtC,WAAmB,EACnB,SAAiB,EACjB,IAAY,EACZ,cAAsB;IAEtB,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC5D,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,cAAc,KAAK,cAAc,CAAC,IAAI,IAAI,CAAC;AAChG,CAAC;AAED,wBAAwB;AAExB,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,WAAmB,EAAE,SAAiB;IACvE,IAAI,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,WAAW,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;QAChF,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAqB,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,EAAE,CAAC;IACd,CAAC;AACL,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,WAAmB,EAAE,SAAiB,EAAE,UAA4B;IAC/F,MAAM,QAAQ,GAAG,cAAc,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACxD,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACnF,CAAC;AAED,SAAS,cAAc,CAAC,UAA4B;IAChD,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;IAClC,OAAO,YAAY,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AACtD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAChC,WAAmB,EACnB,SAAiB,EACjB,IAAY,EACZ,SAAiB,EACjB,eAAyB,EACzB,SAAkB;IAElB,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAChE,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAErC,MAAM,QAAQ,GAAmB;QAC7B,EAAE,EAAE,cAAc,CAAC,UAAU,CAAC;QAC9B,IAAI;QACJ,SAAS;QACT,MAAM,EAAE,YAAY;QACpB,eAAe;QACf,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,GAAG;QACd,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtC,CAAC;IAEF,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1B,MAAM,eAAe,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAC1D,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAChC,WAAmB,EACnB,SAAiB,EACjB,UAAkB,EAClB,OAIC;IAED,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,UAAU,CAAC,CAAC;IAE7D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,aAAa,UAAU,2BAA2B,WAAW,GAAG,CAAC,CAAC;IACtF,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAErC,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,QAAQ,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QACjC,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YAClG,QAAQ,CAAC,WAAW,GAAG,GAAG,CAAC;QAC/B,CAAC;IACL,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;QAAE,QAAQ,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAC5E,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;QAAE,QAAQ,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC7D,QAAQ,CAAC,SAAS,GAAG,GAAG,CAAC;IAEzB,MAAM,eAAe,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAC1D,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC7B,WAAmB,EACnB,SAAiB,EACjB,UAAkB;IAElB,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAChE,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,UAAU,CAAC,IAAI,IAAI,CAAC;AAC/D,CAAC;AAED,iCAAiC;AAEjC,mDAAmD;AACnD,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC1E,UAAU,EAAE,CAAC,SAAS,EAAE,WAAW,CAAC;IACpC,OAAO,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC;IAC7C,SAAS,EAAE,EAAE;IACb,MAAM,EAAE,EAAE;IACV,SAAS,EAAE,EAAE;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAoB,EAAE,EAAkB;IACtE,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAsB;IACnD,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;AACrD,CAAC"}
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../src/core/dispatch.ts"],"names":[],"mappings":"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"}

package/build/core/docs.d.ts

@@ -1,32 +1,36 @@
 /**
- * Document management — read/write files under <data_dir>/<project_name>/iter-<n>/docs/
+ * Document management — read/write files under <context_dir>/docs/
+ *
+ * context_dir is typically iter-<n>/ or patch-<n>/ under the project data dir.
+ * All public functions accept an optional contextDir parameter. When omitted,
+ * falls back to getIterationDir(projectName, iteration) for backward compat.
  *
  * Supports both .md and .html files based on doc format configuration.
  * Also supports step artifact files for sequential mode (e.g. prd.requirements.json).
  */
 import type { DocDefinition } from './types.js';
 /**
- * Write a document to <data_dir>/<project_name>/iter-<n>/docs/<docId>.<ext>
+ * Write a document to <context_dir>/docs/<docId>.<ext>
  */
-export declare function writeDoc(projectName: string, iteration: number, docId: string, content: string, docDef?: DocDefinition): Promise<string>;
+export declare function writeDoc(projectName: string, iteration: number, docId: string, content: string, docDef?: DocDefinition, contextDir?: string): Promise<string>;
 /**
- * Read a document from <data_dir>/<project_name>/iter-<n>/docs/<docId>.<ext>
+ * Read a document from <context_dir>/docs/<docId>.<ext>
  * Tries both .md and .html extensions.
  */
-export declare function readDoc(projectName: string, iteration: number, docId: string): Promise<string>;
+export declare function readDoc(projectName: string, iteration: number, docId: string, contextDir?: string): Promise<string>;
 /**
- * List all documents in <data_dir>/<project_name>/iter-<n>/docs/
+ * List all documents in <context_dir>/docs/
  */
-export declare function listDocs(projectName: string, iteration: number): Promise<string[]>;
+export declare function listDocs(projectName: string, iteration: number, contextDir?: string): Promise<string[]>;
 /**
- * Write a step artifact to <data_dir>/<project_name>/iter-<n>/docs/<docId>.<stepId>.<ext>
+ * Write a step artifact to <context_dir>/docs/<docId>.<stepId>.<ext>
  *
  * @param format - "json" or "md" (determines file extension)
  * @returns The file path written
  */
-export declare function writeStepArtifact(projectName: string, iteration: number, docId: string, stepId: string, content: string, format: 'json' | 'md'): Promise<string>;
+export declare function writeStepArtifact(projectName: string, iteration: number, docId: string, stepId: string, content: string, format: 'json' | 'md', contextDir?: string): Promise<string>;
 /**
- * Read a step artifact from <data_dir>/<project_name>/iter-<n>/docs/<docId>.<stepId>.<ext>
+ * Read a step artifact from <context_dir>/docs/<docId>.<stepId>.<ext>
  * Tries .json first, then .md.
  */
-export declare function readStepArtifact(projectName: string, iteration: number, docId: string, stepId: string): Promise<string>;
+export declare function readStepArtifact(projectName: string, iteration: number, docId: string, stepId: string, contextDir?: string): Promise<string>;

package/build/core/docs.js

@@ -1,5 +1,9 @@
 /**
- * Document management — read/write files under <data_dir>/<project_name>/iter-<n>/docs/
+ * Document management — read/write files under <context_dir>/docs/
+ *
+ * context_dir is typically iter-<n>/ or patch-<n>/ under the project data dir.
+ * All public functions accept an optional contextDir parameter. When omitted,
+ * falls back to getIterationDir(projectName, iteration) for backward compat.
  *
  * Supports both .md and .html files based on doc format configuration.
  * Also supports step artifact files for sequential mode (e.g. prd.requirements.json).
@@ -7,8 +11,9 @@
 import { mkdir, readFile, writeFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getIterationDir } from './registry.js';
-function docsDir(projectName, iteration) {
-    return join(getIterationDir(projectName, iteration), 'docs');
+function docsDir(projectName, iteration, contextDir) {
+    const base = contextDir ?? getIterationDir(projectName, iteration);
+    return join(base, 'docs');
 }
 /**
  * Get file extension for a doc based on its definition.
@@ -17,10 +22,10 @@ function getDocExtension(docDef) {
     return docDef?.format === 'html' ? '.html' : '.md';
 }
 /**
- * Write a document to <data_dir>/<project_name>/iter-<n>/docs/<docId>.<ext>
+ * Write a document to <context_dir>/docs/<docId>.<ext>
  */
-export async function writeDoc(projectName, iteration, docId, content, docDef) {
-    const dir = docsDir(projectName, iteration);
+export async function writeDoc(projectName, iteration, docId, content, docDef, contextDir) {
+    const dir = docsDir(projectName, iteration, contextDir);
     await mkdir(dir, { recursive: true });
     const ext = getDocExtension(docDef);
     const filePath = join(dir, `${docId}${ext}`);
@@ -28,11 +33,11 @@ export async function writeDoc(projectName, iteration, docId, content, docDef) {
     return filePath;
 }
 /**
- * Read a document from <data_dir>/<project_name>/iter-<n>/docs/<docId>.<ext>
+ * Read a document from <context_dir>/docs/<docId>.<ext>
  * Tries both .md and .html extensions.
  */
-export async function readDoc(projectName, iteration, docId) {
-    const dir = docsDir(projectName, iteration);
+export async function readDoc(projectName, iteration, docId, contextDir) {
+    const dir = docsDir(projectName, iteration, contextDir);
     // Try .md first, then .html
     for (const ext of ['.md', '.html']) {
         try {
@@ -45,10 +50,10 @@ export async function readDoc(projectName, iteration, docId) {
     throw new Error(`Document "${docId}" not found`);
 }
 /**
- * List all documents in <data_dir>/<project_name>/iter-<n>/docs/
+ * List all documents in <context_dir>/docs/
  */
-export async function listDocs(projectName, iteration) {
-    const dir = docsDir(projectName, iteration);
+export async function listDocs(projectName, iteration, contextDir) {
+    const dir = docsDir(projectName, iteration, contextDir);
     try {
         const files = await readdir(dir);
         return files.filter((f) => f.endsWith('.md') || f.endsWith('.html')).map((f) => f.replace(/\.(md|html)$/, ''));
@@ -59,13 +64,13 @@ export async function listDocs(projectName, iteration) {
 }
 // ─── Step Artifact I/O ───
 /**
- * Write a step artifact to <data_dir>/<project_name>/iter-<n>/docs/<docId>.<stepId>.<ext>
+ * Write a step artifact to <context_dir>/docs/<docId>.<stepId>.<ext>
  *
  * @param format - "json" or "md" (determines file extension)
  * @returns The file path written
  */
-export async function writeStepArtifact(projectName, iteration, docId, stepId, content, format) {
-    const dir = docsDir(projectName, iteration);
+export async function writeStepArtifact(projectName, iteration, docId, stepId, content, format, contextDir) {
+    const dir = docsDir(projectName, iteration, contextDir);
     await mkdir(dir, { recursive: true });
     const ext = format === 'json' ? '.json' : '.md';
     const filePath = join(dir, `${docId}.${stepId}${ext}`);
@@ -73,11 +78,11 @@ export async function writeStepArtifact(projectName, iteration, docId, stepId, c
     return filePath;
 }
 /**
- * Read a step artifact from <data_dir>/<project_name>/iter-<n>/docs/<docId>.<stepId>.<ext>
+ * Read a step artifact from <context_dir>/docs/<docId>.<stepId>.<ext>
  * Tries .json first, then .md.
  */
-export async function readStepArtifact(projectName, iteration, docId, stepId) {
-    const dir = docsDir(projectName, iteration);
+export async function readStepArtifact(projectName, iteration, docId, stepId, contextDir) {
+    const dir = docsDir(projectName, iteration, contextDir);
     for (const ext of ['.json', '.md']) {
         try {
             return await readFile(join(dir, `${docId}.${stepId}${ext}`), 'utf-8');

package/build/core/docs.js.map

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

package/build/core/issues.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Issue tracking — manages <data_dir>/<project_name>/issues.json
+ *
+ * Issues are project-level (not per-iteration/patch). They track problems
+ * discovered during testing or from user feedback, and can be linked to
+ * the patch or iteration that resolves them.
+ */
+import type { Issue, IssueResolvedBy, IssueSource, IssueStatus } from './types.js';
+/**
+ * Read all issues for a project. Returns empty array if file doesn't exist.
+ */
+export declare function readIssues(projectName: string): Promise<Issue[]>;
+/**
+ * Create a new issue. Auto-generates an incremental ID.
+ *
+ * @returns The created issue
+ */
+export declare function createIssue(projectName: string, title: string, description: string, source: IssueSource, iteration: number): Promise<Issue>;
+/**
+ * Update an existing issue.
+ * Supports partial updates: status, resolvedBy, closedAt.
+ *
+ * @returns The updated issue
+ */
+export declare function updateIssue(projectName: string, issueId: string, updates: {
+    status?: IssueStatus;
+    resolvedBy?: IssueResolvedBy;
+}): Promise<Issue>;
+export interface IssueFilters {
+    status?: IssueStatus;
+    source?: IssueSource;
+    iteration?: number;
+}
+/**
+ * List issues with optional filters.
+ */
+export declare function listIssues(projectName: string, filters?: IssueFilters): Promise<Issue[]>;

package/build/core/issues.js

@@ -0,0 +1,100 @@
+/**
+ * Issue tracking — manages <data_dir>/<project_name>/issues.json
+ *
+ * Issues are project-level (not per-iteration/patch). They track problems
+ * discovered during testing or from user feedback, and can be linked to
+ * the patch or iteration that resolves them.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getProjectDataDir } from './registry.js';
+const ISSUES_FILE = 'issues.json';
+function issuesPath(projectName) {
+    return join(getProjectDataDir(projectName), ISSUES_FILE);
+}
+/**
+ * Read all issues for a project. Returns empty array if file doesn't exist.
+ */
+export async function readIssues(projectName) {
+    try {
+        const content = await readFile(issuesPath(projectName), 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Write issues array to disk.
+ */
+async function writeIssues(projectName, issues) {
+    await writeFile(issuesPath(projectName), JSON.stringify(issues, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Create a new issue. Auto-generates an incremental ID.
+ *
+ * @returns The created issue
+ */
+export async function createIssue(projectName, title, description, source, iteration) {
+    const issues = await readIssues(projectName);
+    // Generate next ID
+    const maxNum = issues.reduce((max, iss) => {
+        const match = iss.id.match(/^issue-(\d+)$/);
+        return match ? Math.max(max, parseInt(match[1], 10)) : max;
+    }, 0);
+    const issue = {
+        id: `issue-${maxNum + 1}`,
+        title,
+        description,
+        source,
+        iteration,
+        status: 'open',
+        createdAt: new Date().toISOString(),
+    };
+    issues.push(issue);
+    await writeIssues(projectName, issues);
+    return issue;
+}
+/**
+ * Update an existing issue.
+ * Supports partial updates: status, resolvedBy, closedAt.
+ *
+ * @returns The updated issue
+ */
+export async function updateIssue(projectName, issueId, updates) {
+    const issues = await readIssues(projectName);
+    const issue = issues.find((i) => i.id === issueId);
+    if (!issue) {
+        throw new Error(`Issue "${issueId}" not found.`);
+    }
+    if (updates.status !== undefined) {
+        issue.status = updates.status;
+        if (updates.status === 'closed') {
+            issue.closedAt = new Date().toISOString();
+        }
+    }
+    if (updates.resolvedBy !== undefined) {
+        issue.resolvedBy = updates.resolvedBy;
+    }
+    await writeIssues(projectName, issues);
+    return issue;
+}
+/**
+ * List issues with optional filters.
+ */
+export async function listIssues(projectName, filters) {
+    let issues = await readIssues(projectName);
+    if (filters) {
+        if (filters.status) {
+            issues = issues.filter((i) => i.status === filters.status);
+        }
+        if (filters.source) {
+            issues = issues.filter((i) => i.source === filters.source);
+        }
+        if (filters.iteration !== undefined) {
+            issues = issues.filter((i) => i.iteration === filters.iteration);
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=issues.js.map

package/build/core/issues.js.map

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

package/build/core/registry.d.ts

@@ -13,6 +13,7 @@
  *   ├── overrides.json       # global overrides (optional)
  *   ├── my-app/
  *   │   ├── overrides.json   # project-level overrides (optional)
+ *   │   ├── issues.json      # project-level issue tracking (optional)
  *   │   ├── iter-1/
  *   │   │   ├── state.json
  *   │   │   ├── docs/
@@ -20,6 +21,10 @@
  *   │   │   └── ...
  *   │   ├── iter-2/
  *   │   │   └── ...
+ *   │   ├── patch-1/
+ *   │   │   ├── state.json   # type: "patch", clarify/design skipped
+ *   │   │   ├── docs/
+ *   │   │   └── ...
  *   └── another-project/
  *       └── ...
  */
@@ -34,6 +39,12 @@ export interface ProjectEntry {
     currentIteration: number;
     /** Total number of iterations created so far */
     totalIterations: number;
+    /** Currently active patch number (starts at 1, 0 means no patch started yet) */
+    currentPatch: number;
+    /** Total number of patches created so far */
+    totalPatches: number;
+    /** Active context identifier, e.g. "iter-1" or "patch-2". Empty string means no context. */
+    activeContext: string;
 }
 export interface Registry {
     projects: Record<string, ProjectEntry>;
@@ -93,3 +104,26 @@ export declare function getIterationDir(projectName: string, iteration: number):
  * @returns The new iteration number
  */
 export declare function startIteration(projectName: string): Promise<number>;
+/**
+ * Get the patch directory for a specific project patch.
+ * Pure path concatenation — does NOT check if the directory exists.
+ */
+export declare function getPatchDir(projectName: string, patch: number): string;
+/**
+ * Start a new patch for a project.
+ * Creates the patch directory (with docs/ subdirectory) and updates the registry.
+ *
+ * @returns The new patch number
+ */
+export declare function startPatch(projectName: string): Promise<number>;
+/**
+ * Resolve the active context directory for a project.
+ * Parses activeContext string (e.g. "iter-1", "patch-2") into an absolute path.
+ *
+ * @returns { dir: string, type: 'iteration' | 'patch', number: number } or null if no active context
+ */
+export declare function resolveContextDir(projectName: string, activeContext: string): {
+    dir: string;
+    type: 'iteration' | 'patch';
+    number: number;
+} | null;