@s_s/harmonia 1.2.0 → 1.3.0

package/build/core/registry.js

@@ -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/
  *       └── ...
  */
@@ -84,6 +89,9 @@ export async function registerProject(projectName, projectDir, workflow) {
         createdAt: new Date().toISOString(),
         currentIteration: 0,
         totalIterations: 0,
+        currentPatch: 0,
+        totalPatches: 0,
+        activeContext: '',
     };
     // Create project data directory under global dir
     const dataDir = getProjectDataDir(projectName);
@@ -143,10 +151,61 @@ export async function startIteration(projectName) {
     const newIteration = entry.totalIterations + 1;
     entry.currentIteration = newIteration;
     entry.totalIterations = newIteration;
+    entry.activeContext = `iter-${newIteration}`;
     // Create iteration directory with docs subdirectory
     const iterDir = getIterationDir(projectName, newIteration);
     await mkdir(join(iterDir, 'docs'), { recursive: true });
     await writeRegistry(registry);
     return newIteration;
 }
+/**
+ * Get the patch directory for a specific project patch.
+ * Pure path concatenation — does NOT check if the directory exists.
+ */
+export function getPatchDir(projectName, patch) {
+    return join(getProjectDataDir(projectName), `patch-${patch}`);
+}
+/**
+ * Start a new patch for a project.
+ * Creates the patch directory (with docs/ subdirectory) and updates the registry.
+ *
+ * @returns The new patch number
+ */
+export async function startPatch(projectName) {
+    const registry = await readRegistry();
+    const entry = registry.projects[projectName];
+    if (!entry) {
+        throw new Error(`Project "${projectName}" not found in registry.`);
+    }
+    const newPatch = entry.totalPatches + 1;
+    entry.currentPatch = newPatch;
+    entry.totalPatches = newPatch;
+    entry.activeContext = `patch-${newPatch}`;
+    // Create patch directory with docs subdirectory
+    const patchDir = getPatchDir(projectName, newPatch);
+    await mkdir(join(patchDir, 'docs'), { recursive: true });
+    await writeRegistry(registry);
+    return newPatch;
+}
+/**
+ * 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 function resolveContextDir(projectName, activeContext) {
+    if (!activeContext)
+        return null;
+    const iterMatch = activeContext.match(/^iter-(\d+)$/);
+    if (iterMatch) {
+        const num = parseInt(iterMatch[1], 10);
+        return { dir: getIterationDir(projectName, num), type: 'iteration', number: num };
+    }
+    const patchMatch = activeContext.match(/^patch-(\d+)$/);
+    if (patchMatch) {
+        const num = parseInt(patchMatch[1], 10);
+        return { dir: getPatchDir(projectName, num), type: 'patch', number: num };
+    }
+    return null;
+}
 //# sourceMappingURL=registry.js.map

package/build/core/registry.js.map

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

package/build/core/reviews.d.ts

@@ -1,26 +1,27 @@
 /**
- * Document review state management — <data_dir>/<project_name>/iter-<n>/reviews.json
+ * Document review state management — <context_dir>/reviews.json
  *
  * Tracks which documents are pending review, approved, or rejected.
+ * All public functions accept an optional contextDir parameter.
  */
 import type { DocReviewState } from './types.js';
 /**
- * Read the reviews state for a project iteration.
+ * Read the reviews state for a project context.
  */
-export declare function readReviews(projectName: string, iteration: number): Promise<Record<string, DocReviewState>>;
+export declare function readReviews(projectName: string, iteration: number, contextDir?: string): Promise<Record<string, DocReviewState>>;
 /**
  * Submit a document for review. Sets status to "pending".
  */
-export declare function submitForReview(projectName: string, iteration: number, docId: string): Promise<DocReviewState>;
+export declare function submitForReview(projectName: string, iteration: number, docId: string, contextDir?: string): Promise<DocReviewState>;
 /**
  * Approve or reject a document review.
  */
-export declare function resolveReview(projectName: string, iteration: number, docId: string, status: 'approved' | 'rejected', comment?: string): Promise<DocReviewState>;
+export declare function resolveReview(projectName: string, iteration: number, docId: string, status: 'approved' | 'rejected', comment?: string, contextDir?: string): Promise<DocReviewState>;
 /**
  * Get the review state for a specific document.
  */
-export declare function getDocReview(projectName: string, iteration: number, docId: string): Promise<DocReviewState | null>;
+export declare function getDocReview(projectName: string, iteration: number, docId: string, contextDir?: string): Promise<DocReviewState | null>;
 /**
- * Get all pending reviews for a project iteration.
+ * Get all pending reviews for a project context.
  */
-export declare function getPendingReviews(projectName: string, iteration: number): Promise<DocReviewState[]>;
+export declare function getPendingReviews(projectName: string, iteration: number, contextDir?: string): Promise<DocReviewState[]>;

package/build/core/reviews.js

@@ -1,21 +1,23 @@
 /**
- * Document review state management — <data_dir>/<project_name>/iter-<n>/reviews.json
+ * Document review state management — <context_dir>/reviews.json
  *
  * Tracks which documents are pending review, approved, or rejected.
+ * All public functions accept an optional contextDir parameter.
  */
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { getIterationDir } from './registry.js';
 const REVIEWS_FILE = 'reviews.json';
-function reviewsPath(projectName, iteration) {
-    return join(getIterationDir(projectName, iteration), REVIEWS_FILE);
+function reviewsPath(projectName, iteration, contextDir) {
+    const base = contextDir ?? getIterationDir(projectName, iteration);
+    return join(base, REVIEWS_FILE);
 }
 /**
- * Read the reviews state for a project iteration.
+ * Read the reviews state for a project context.
  */
-export async function readReviews(projectName, iteration) {
+export async function readReviews(projectName, iteration, contextDir) {
     try {
-        const content = await readFile(reviewsPath(projectName, iteration), 'utf-8');
+        const content = await readFile(reviewsPath(projectName, iteration, contextDir), 'utf-8');
         const data = JSON.parse(content);
         return data.docs ?? {};
     }
@@ -26,8 +28,8 @@ export async function readReviews(projectName, iteration) {
 /**
  * Write reviews state to disk.
  */
-async function writeReviews(projectName, iteration, docs) {
-    const filePath = reviewsPath(projectName, iteration);
+async function writeReviews(projectName, iteration, docs, contextDir) {
+    const filePath = reviewsPath(projectName, iteration, contextDir);
     await mkdir(dirname(filePath), { recursive: true });
     const data = { docs };
     await writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
@@ -35,22 +37,22 @@ async function writeReviews(projectName, iteration, docs) {
 /**
  * Submit a document for review. Sets status to "pending".
  */
-export async function submitForReview(projectName, iteration, docId) {
-    const reviews = await readReviews(projectName, iteration);
+export async function submitForReview(projectName, iteration, docId, contextDir) {
+    const reviews = await readReviews(projectName, iteration, contextDir);
     const state = {
         docId,
         status: 'pending',
         submittedAt: new Date().toISOString(),
     };
     reviews[docId] = state;
-    await writeReviews(projectName, iteration, reviews);
+    await writeReviews(projectName, iteration, reviews, contextDir);
     return state;
 }
 /**
  * Approve or reject a document review.
  */
-export async function resolveReview(projectName, iteration, docId, status, comment) {
-    const reviews = await readReviews(projectName, iteration);
+export async function resolveReview(projectName, iteration, docId, status, comment, contextDir) {
+    const reviews = await readReviews(projectName, iteration, contextDir);
     const existing = reviews[docId];
     if (!existing) {
         throw new Error(`No review pending for document "${docId}". Submit it for review first.`);
@@ -63,21 +65,21 @@ export async function resolveReview(projectName, iteration, docId, status, comme
     if (comment) {
         existing.comment = comment;
     }
-    await writeReviews(projectName, iteration, reviews);
+    await writeReviews(projectName, iteration, reviews, contextDir);
     return existing;
 }
 /**
  * Get the review state for a specific document.
  */
-export async function getDocReview(projectName, iteration, docId) {
-    const reviews = await readReviews(projectName, iteration);
+export async function getDocReview(projectName, iteration, docId, contextDir) {
+    const reviews = await readReviews(projectName, iteration, contextDir);
     return reviews[docId] ?? null;
 }
 /**
- * Get all pending reviews for a project iteration.
+ * Get all pending reviews for a project context.
  */
-export async function getPendingReviews(projectName, iteration) {
-    const reviews = await readReviews(projectName, iteration);
+export async function getPendingReviews(projectName, iteration, contextDir) {
+    const reviews = await readReviews(projectName, iteration, contextDir);
     return Object.values(reviews).filter((r) => r.status === 'pending');
 }
 //# sourceMappingURL=reviews.js.map

package/build/core/reviews.js.map

@@ -1 +1 @@
-{"version":3,"file":"reviews.js","sourceRoot":"","sources":["../../src/core/reviews.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reviews.js","sourceRoot":"","sources":["../../src/core/reviews.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,MAAM,YAAY,GAAG,cAAc,CAAC;AAMpC,SAAS,WAAW,CAAC,WAAmB,EAAE,SAAiB,EAAE,UAAmB;IAC5E,MAAM,IAAI,GAAG,UAAU,IAAI,eAAe,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC7B,WAAmB,EACnB,SAAiB,EACjB,UAAmB;IAEnB,IAAI,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,EAAE,OAAO,CAAC,CAAC;QACzF,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAgB,CAAC;QAChD,OAAO,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,EAAE,CAAC;IACd,CAAC;AACL,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,YAAY,CACvB,WAAmB,EACnB,SAAiB,EACjB,IAAoC,EACpC,UAAmB;IAEnB,MAAM,QAAQ,GAAG,WAAW,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IACjE,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,IAAI,GAAgB,EAAE,IAAI,EAAE,CAAC;IACnC,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AAC7E,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACjC,WAAmB,EACnB,SAAiB,EACjB,KAAa,EACb,UAAmB;IAEnB,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IACtE,MAAM,KAAK,GAAmB;QAC1B,KAAK;QACL,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACxC,CAAC;IACF,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;IACvB,MAAM,YAAY,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAChE,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAC/B,WAAmB,EACnB,SAAiB,EACjB,KAAa,EACb,MAA+B,EAC/B,OAAgB,EAChB,UAAmB;IAEnB,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAEhC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,mCAAmC,KAAK,gCAAgC,CAAC,CAAC;IAC9F,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,aAAa,KAAK,uBAAuB,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IACjF,CAAC;IAED,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/C,IAAI,OAAO,EAAE,CAAC;QACV,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAC;IAC/B,CAAC;IAED,MAAM,YAAY,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAChE,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAC9B,WAAmB,EACnB,SAAiB,EACjB,KAAa,EACb,UAAmB;IAEnB,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IACtE,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACnC,WAAmB,EACnB,SAAiB,EACjB,UAAmB;IAEnB,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IACtE,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;AACxE,CAAC"}

package/build/core/state.d.ts

@@ -1,7 +1,11 @@
 /**
- * Project state management — manages <data_dir>/<project_name>/iter-<n>/state.json
+ * Project state management — manages state.json within iteration/patch directories.
+ *
+ * All functions accept an optional `contextDir` parameter. When provided, it is used
+ * directly as the directory containing state.json. When omitted, the directory is
+ * resolved from `getIterationDir(projectName, iteration)` for backward compatibility.
  */
-import type { PhaseStatus, ProjectScale, ProjectState, LoadedWorkflow } from './types.js';
+import type { ContextType, PhaseStatus, ProjectScale, ProjectState, LoadedWorkflow } from './types.js';
 /**
  * Error thrown when a tool requires scale but it hasn't been set yet.
  */
@@ -9,28 +13,32 @@ export declare class ScaleNotSetError extends Error {
     constructor(projectName: string);
 }
 /**
- * Initialize a new project state file for a specific iteration.
- * Note: directory creation is handled by registry.startIteration().
- * This only writes the state.json.
+ * Initialize a new project state file.
+ *
+ * For iteration mode (default): all phases start normally (first = in_progress, rest = pending).
+ * For patch mode: clarify/design are marked as "skipped", first non-skipped phase is in_progress,
+ * scale is set to "small" automatically.
+ *
+ * @param contextDir - Optional explicit directory. If omitted, uses getIterationDir().
  */
-export declare function initProjectState(projectName: string, projectDir: string, workflow: LoadedWorkflow, iteration: number): Promise<ProjectState>;
+export declare function initProjectState(projectName: string, projectDir: string, workflow: LoadedWorkflow, iteration: number, type?: ContextType, contextDir?: string): Promise<ProjectState>;
 /**
- * Read the current project state for a specific iteration.
+ * Read the current project state.
  */
-export declare function readState(projectName: string, iteration: number): Promise<ProjectState>;
+export declare function readState(projectName: string, iteration: number, contextDir?: string): Promise<ProjectState>;
 /**
- * Write project state to disk for a specific iteration.
+ * Write project state to disk.
  */
-export declare function writeState(projectName: string, iteration: number, state: ProjectState): Promise<void>;
+export declare function writeState(projectName: string, iteration: number, state: ProjectState, contextDir?: string): Promise<void>;
 /**
  * Update a specific phase's status.
  */
-export declare function updatePhaseStatus(projectName: string, iteration: number, phaseId: string, status: PhaseStatus, blockedReason?: string): Promise<ProjectState>;
+export declare function updatePhaseStatus(projectName: string, iteration: number, phaseId: string, status: PhaseStatus, blockedReason?: string, contextDir?: string): Promise<ProjectState>;
 /**
- * Check if a project state file exists for a specific iteration.
+ * Check if a project state file exists.
  */
-export declare function projectStateExists(projectName: string, iteration: number): Promise<boolean>;
+export declare function projectStateExists(projectName: string, iteration: number, contextDir?: string): Promise<boolean>;
 /**
  * Set the project scale. Scale is immutable once set.
  */
-export declare function setScale(projectName: string, iteration: number, scale: ProjectScale): Promise<ProjectState>;
+export declare function setScale(projectName: string, iteration: number, scale: ProjectScale, contextDir?: string): Promise<ProjectState>;

package/build/core/state.js

@@ -1,5 +1,9 @@
 /**
- * Project state management — manages <data_dir>/<project_name>/iter-<n>/state.json
+ * Project state management — manages state.json within iteration/patch directories.
+ *
+ * All functions accept an optional `contextDir` parameter. When provided, it is used
+ * directly as the directory containing state.json. When omitted, the directory is
+ * resolved from `getIterationDir(projectName, iteration)` for backward compatibility.
  */
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
@@ -14,48 +18,65 @@ export class ScaleNotSetError extends Error {
     }
 }
 const STATE_FILE = 'state.json';
-function statePath(projectName, iteration) {
-    return join(getIterationDir(projectName, iteration), STATE_FILE);
+function resolveDir(projectName, iteration, contextDir) {
+    return contextDir ?? getIterationDir(projectName, iteration);
 }
+function statePath(projectName, iteration, contextDir) {
+    return join(resolveDir(projectName, iteration, contextDir), STATE_FILE);
+}
+/** Phases to skip in patch mode (clarify and design) */
+const PATCH_SKIP_PHASES = new Set(['clarify', 'design']);
 /**
- * Initialize a new project state file for a specific iteration.
- * Note: directory creation is handled by registry.startIteration().
- * This only writes the state.json.
+ * Initialize a new project state file.
+ *
+ * For iteration mode (default): all phases start normally (first = in_progress, rest = pending).
+ * For patch mode: clarify/design are marked as "skipped", first non-skipped phase is in_progress,
+ * scale is set to "small" automatically.
+ *
+ * @param contextDir - Optional explicit directory. If omitted, uses getIterationDir().
  */
-export async function initProjectState(projectName, projectDir, workflow, iteration) {
+export async function initProjectState(projectName, projectDir, workflow, iteration, type = 'iteration', contextDir) {
     const now = new Date().toISOString();
     const phases = workflow.definition.phases;
-    const firstPhaseId = phases[0]?.id ?? '';
+    const isPatch = type === 'patch';
+    // Find the first non-skipped phase
+    const firstActiveIndex = isPatch ? phases.findIndex((p) => !PATCH_SKIP_PHASES.has(p.id)) : 0;
+    const firstPhaseId = phases[firstActiveIndex]?.id ?? phases[0]?.id ?? '';
     const state = {
         projectName,
         projectDir,
         workflow: workflow.definition.name,
+        type,
         iteration,
-        scale: null,
+        scale: isPatch ? 'small' : null,
         currentPhase: firstPhaseId,
-        phases: phases.map((p, i) => ({
-            id: p.id,
-            status: i === 0 ? 'in_progress' : 'pending',
-            ...(i === 0 ? { startedAt: now } : {}),
-        })),
+        phases: phases.map((p, i) => {
+            if (isPatch && PATCH_SKIP_PHASES.has(p.id)) {
+                return { id: p.id, status: 'skipped' };
+            }
+            if (i === firstActiveIndex) {
+                return { id: p.id, status: 'in_progress', startedAt: now };
+            }
+            return { id: p.id, status: 'pending' };
+        }),
         createdAt: now,
         updatedAt: now,
     };
-    await writeState(projectName, iteration, state);
+    await writeState(projectName, iteration, state, contextDir);
     return state;
 }
 /**
- * Read the current project state for a specific iteration.
+ * Read the current project state.
  */
-export async function readState(projectName, iteration) {
-    const content = await readFile(statePath(projectName, iteration), 'utf-8');
+export async function readState(projectName, iteration, contextDir) {
+    const content = await readFile(statePath(projectName, iteration, contextDir), 'utf-8');
     return JSON.parse(content);
 }
 /**
- * Write project state to disk for a specific iteration.
+ * Write project state to disk.
  */
-export async function writeState(projectName, iteration, state) {
-    const filePath = statePath(projectName, iteration);
+export async function writeState(projectName, iteration, state, contextDir) {
+    const filePath = statePath(projectName, iteration, contextDir);
     await mkdir(dirname(filePath), { recursive: true });
     state.updatedAt = new Date().toISOString();
     await writeFile(filePath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
@@ -63,8 +84,8 @@ export async function writeState(projectName, iteration, state) {
 /**
  * Update a specific phase's status.
  */
-export async function updatePhaseStatus(projectName, iteration, phaseId, status, blockedReason) {
-    const state = await readState(projectName, iteration);
+export async function updatePhaseStatus(projectName, iteration, phaseId, status, blockedReason, contextDir) {
+    const state = await readState(projectName, iteration, contextDir);
     const phase = state.phases.find((p) => p.id === phaseId);
     if (!phase) {
         throw new Error(`Phase "${phaseId}" not found in project state`);
@@ -86,6 +107,7 @@ export async function updatePhaseStatus(projectName, iteration, phaseId, status,
         state.currentPhase = phaseId;
     }
     // If completing a phase, auto-advance currentPhase to the next pending one
+    // (skip over phases that are already "skipped")
     if (status === 'completed') {
         const idx = state.phases.findIndex((p) => p.id === phaseId);
         const next = state.phases.find((p, i) => i > idx && p.status === 'pending');
@@ -95,15 +117,15 @@ export async function updatePhaseStatus(projectName, iteration, phaseId, status,
             state.currentPhase = next.id;
         }
     }
-    await writeState(projectName, iteration, state);
+    await writeState(projectName, iteration, state, contextDir);
     return state;
 }
 /**
- * Check if a project state file exists for a specific iteration.
+ * Check if a project state file exists.
  */
-export async function projectStateExists(projectName, iteration) {
+export async function projectStateExists(projectName, iteration, contextDir) {
     try {
-        await readFile(statePath(projectName, iteration), 'utf-8');
+        await readFile(statePath(projectName, iteration, contextDir), 'utf-8');
         return true;
     }
     catch {
@@ -113,13 +135,13 @@ export async function projectStateExists(projectName, iteration) {
 /**
  * Set the project scale. Scale is immutable once set.
  */
-export async function setScale(projectName, iteration, scale) {
-    const state = await readState(projectName, iteration);
+export async function setScale(projectName, iteration, scale, contextDir) {
+    const state = await readState(projectName, iteration, contextDir);
     if (state.scale !== null) {
         throw new Error(`Scale 已设定为 "${state.scale}"，不可更改。如需调整规模，请重新评估 PRD。`);
     }
     state.scale = scale;
-    await writeState(projectName, iteration, state);
+    await writeState(projectName, iteration, state, contextDir);
     return state;
 }
 //# sourceMappingURL=state.js.map

package/build/core/state.js.map

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

package/build/core/steps.d.ts

@@ -1,18 +1,19 @@
 /**
- * Step state management — manages <data_dir>/<project_name>/iter-<n>/steps.json
+ * Step state management — manages <context_dir>/steps.json
  *
  * Tracks which sequential steps have been completed for each document,
  * supporting the P3 Sequential mode feature.
+ * All public functions accept an optional contextDir parameter.
  */
 import type { DocStepState } from './types.js';
 /**
- * Read the steps state for a project iteration.
+ * Read the steps state for a project context.
  */
-export declare function readSteps(projectName: string, iteration: number): Promise<Record<string, DocStepState>>;
+export declare function readSteps(projectName: string, iteration: number, contextDir?: string): Promise<Record<string, DocStepState>>;
 /**
  * Get the step state for a specific document.
  */
-export declare function getDocStepState(projectName: string, iteration: number, docId: string): Promise<DocStepState | null>;
+export declare function getDocStepState(projectName: string, iteration: number, docId: string, contextDir?: string): Promise<DocStepState | null>;
 /**
  * Get the set of completed step IDs for a document.
  */
@@ -23,12 +24,12 @@ export declare function getCompletedStepIds(state: DocStepState | null): Set<str
  *
  * @returns The updated DocStepState
  */
-export declare function recordStepCompletion(projectName: string, iteration: number, docId: string, stepId: string, artifactPath: string, allStepIds: string[]): Promise<DocStepState>;
+export declare function recordStepCompletion(projectName: string, iteration: number, docId: string, stepId: string, artifactPath: string, allStepIds: string[], contextDir?: string): Promise<DocStepState>;
 /**
  * Mark a document as finalized (all steps completed + final doc written).
  */
-export declare function markFinalized(projectName: string, iteration: number, docId: string): Promise<DocStepState>;
+export declare function markFinalized(projectName: string, iteration: number, docId: string, contextDir?: string): Promise<DocStepState>;
 /**
  * Check if a document's sequential process is finalized.
  */
-export declare function isDocFinalized(projectName: string, iteration: number, docId: string): Promise<boolean>;
+export declare function isDocFinalized(projectName: string, iteration: number, docId: string, contextDir?: string): Promise<boolean>;

package/build/core/steps.js

@@ -1,22 +1,24 @@
 /**
- * Step state management — manages <data_dir>/<project_name>/iter-<n>/steps.json
+ * Step state management — manages <context_dir>/steps.json
  *
  * Tracks which sequential steps have been completed for each document,
  * supporting the P3 Sequential mode feature.
+ * All public functions accept an optional contextDir parameter.
  */
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { getIterationDir } from './registry.js';
 const STEPS_FILE = 'steps.json';
-function stepsPath(projectName, iteration) {
-    return join(getIterationDir(projectName, iteration), STEPS_FILE);
+function stepsPath(projectName, iteration, contextDir) {
+    const base = contextDir ?? getIterationDir(projectName, iteration);
+    return join(base, STEPS_FILE);
 }
 /**
- * Read the steps state for a project iteration.
+ * Read the steps state for a project context.
  */
-export async function readSteps(projectName, iteration) {
+export async function readSteps(projectName, iteration, contextDir) {
     try {
-        const content = await readFile(stepsPath(projectName, iteration), 'utf-8');
+        const content = await readFile(stepsPath(projectName, iteration, contextDir), 'utf-8');
         const data = JSON.parse(content);
         return data.docs ?? {};
     }
@@ -27,8 +29,8 @@ export async function readSteps(projectName, iteration) {
 /**
  * Write steps state to disk.
  */
-async function writeSteps(projectName, iteration, docs) {
-    const filePath = stepsPath(projectName, iteration);
+async function writeSteps(projectName, iteration, docs, contextDir) {
+    const filePath = stepsPath(projectName, iteration, contextDir);
     await mkdir(dirname(filePath), { recursive: true });
     const data = { docs };
     await writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
@@ -36,8 +38,8 @@ async function writeSteps(projectName, iteration, docs) {
 /**
  * Get the step state for a specific document.
  */
-export async function getDocStepState(projectName, iteration, docId) {
-    const docs = await readSteps(projectName, iteration);
+export async function getDocStepState(projectName, iteration, docId, contextDir) {
+    const docs = await readSteps(projectName, iteration, contextDir);
     return docs[docId] ?? null;
 }
 /**
@@ -54,8 +56,8 @@ export function getCompletedStepIds(state) {
  *
  * @returns The updated DocStepState
  */
-export async function recordStepCompletion(projectName, iteration, docId, stepId, artifactPath, allStepIds) {
-    const docs = await readSteps(projectName, iteration);
+export async function recordStepCompletion(projectName, iteration, docId, stepId, artifactPath, allStepIds, contextDir) {
+    const docs = await readSteps(projectName, iteration, contextDir);
     let state = docs[docId];
     if (!state) {
         state = {
@@ -86,28 +88,28 @@ export async function recordStepCompletion(projectName, iteration, docId, stepId
     };
     state.completedSteps.push(record);
     docs[docId] = state;
-    await writeSteps(projectName, iteration, docs);
+    await writeSteps(projectName, iteration, docs, contextDir);
     return state;
 }
 /**
  * Mark a document as finalized (all steps completed + final doc written).
  */
-export async function markFinalized(projectName, iteration, docId) {
-    const docs = await readSteps(projectName, iteration);
+export async function markFinalized(projectName, iteration, docId, contextDir) {
+    const docs = await readSteps(projectName, iteration, contextDir);
     const state = docs[docId];
     if (!state) {
         throw new Error(`No step state found for document "${docId}"`);
     }
     state.finalized = true;
     state.finalizedAt = new Date().toISOString();
-    await writeSteps(projectName, iteration, docs);
+    await writeSteps(projectName, iteration, docs, contextDir);
     return state;
 }
 /**
  * Check if a document's sequential process is finalized.
  */
-export async function isDocFinalized(projectName, iteration, docId) {
-    const state = await getDocStepState(projectName, iteration, docId);
+export async function isDocFinalized(projectName, iteration, docId, contextDir) {
+    const state = await getDocStepState(projectName, iteration, docId, contextDir);
     return state?.finalized ?? false;
 }
 //# sourceMappingURL=steps.js.map