@agent-plan/core 0.2.22 → 0.2.23

package/dist/plan-store.js

@@ -14,9 +14,10 @@ const PLANNER_GITIGNORE = [
     "generated/",
     "",
 ].join("\n");
-import { CodebaseProfileSchema, FeatureSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, TaskPauseSnapshotSchema, ProjectSchema, RequirementsDocumentSchema, ResumeFocusSchema, ActivityLogSchema, TimestampSchema, } from "./schema.js";
+import { CodebaseProfileSchema, FeatureSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, TaskPauseSnapshotSchema, ProjectSchema, RequirementsDocumentSchema, ResumeFocusSchema, ActivityLogSchema, TimestampSchema, WorkDeviationSchema, } from "./schema.js";
 import { createFeatureId, createPhaseId, createRequirementId, createShortId, createStatusLogEntryId, createTaskId, formatPhaseRef, isLegacyPhaseId } from "./naming.js";
 import { deriveParentDisplay, fromCanonicalStatus } from "./display-status.js";
+import { loadExtensionRules, PLANNER_EXTENSION_RULES } from "./planner-rules.js";
 function nowISO() {
     return new Date().toISOString();
 }
@@ -417,6 +418,41 @@ export async function migrateToGlobalSequence(store) {
         return { migrated: true, phases: newPhases.length, tasks: numberedTasks.length, features: newFeatures.length };
     });
 }
+/** Map legacy/removed status strings to their canonical replacements before
+ * schema validation. Canonical task status "paused" was removed from the
+ * domain; persisted entities (tasks, statusLog entries) may still carry it.
+ * Rewriting on read keeps legacy data loadable without a one-time migration
+ * pass, and the normalized value is persisted on the next save. Scoped to
+ * status-bearing fields so unrelated string values are never touched. */
+function migrateLegacyStatuses(value) {
+    if (Array.isArray(value))
+        return value.map(migrateLegacyStatuses);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            if ((key === "status" || key === "fromStatus" || key === "toStatus") && child === "paused") {
+                out[key] = "planned";
+            }
+            else {
+                out[key] = migrateLegacyStatuses(child);
+            }
+        }
+        return out;
+    }
+    return value;
+}
+/** Walk up from `path` to find the owning `.planner` root, so crash-recovery
+ *  can locate `.local/backups/<rel>.bak` without every readJson caller threading
+ *  `root`. Returns undefined if no `.planner` ancestor exists. */
+function findPlannerRoot(path) {
+    let dir = dirname(path);
+    while (dir !== dirname(dir)) {
+        if (basename(dir) === ".planner")
+            return dir;
+        dir = dirname(dir);
+    }
+    return undefined;
+}
 async function readJson(path, schema) {
     let backupTried = false;
     let backupFailed = false;
@@ -424,20 +460,36 @@ async function readJson(path, schema) {
     try {
         const raw = await readFile(path, "utf-8");
         rawPreview = raw.slice(0, 240);
-        return schema.parse(JSON.parse(raw));
+        return schema.parse(migrateLegacyStatuses(JSON.parse(raw)));
     }
     catch (cause) {
-        // Try the .bak backup before giving up (recover from external-write corruption).
+        // Recover from the previous-version backup before giving up:
+        //  1) legacy inline `<file>.bak` (next to the source), then
+        //  2) the relocated `.planner/.local/backups/<rel>.bak` (P043).
         backupTried = true;
-        try {
-            const bak = await readFile(`${path}.bak`, "utf-8");
-            rawPreview = bak.slice(0, 240);
-            return schema.parse(JSON.parse(bak));
-        }
-        catch {
-            backupFailed = true;
-            // fall through to original error
-        }
+        const tryBackup = async (bakPath) => {
+            try {
+                const bak = await readFile(bakPath, "utf-8");
+                rawPreview = bak.slice(0, 240);
+                return schema.parse(migrateLegacyStatuses(JSON.parse(bak)));
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const inline = await tryBackup(`${path}.bak`);
+        if (inline !== undefined)
+            return inline;
+        let local;
+        const plannerRoot = findPlannerRoot(path);
+        if (plannerRoot) {
+            const rel = path.slice(plannerRoot.length).replace(/^\//, "");
+            local = await tryBackup(join(plannerRoot, ".local", "backups", rel + ".bak"));
+        }
+        if (local !== undefined)
+            return local;
+        backupFailed = true;
+        // fall through to original error
         const details = {
             path,
             operation: "readJson",
@@ -518,11 +570,43 @@ export class PlanStore {
     normalizeTasks(tasks) {
         // Numbers are a STABLE global sequence (assigned once at create from project.nextTaskNumber).
         // Do NOT renumber here — renumbering would break references after deletions.
-        const normalized = tasks.map((task) => task.description && !task.descriptionUpdatedAt
-            ? { ...task, descriptionUpdatedAt: task.createdAt }
-            : task);
+        const normalized = tasks.map((task) => {
+            const descriptionUpdatedAt = task.description && !task.descriptionUpdatedAt
+                ? task.createdAt
+                : task.descriptionUpdatedAt;
+            const normalizedStatus = task.status === "paused" ? "planned" : task.status;
+            const pauseSnapshot = this.isTerminalTaskStatus(normalizedStatus) ? null : task.pauseSnapshot;
+            const statusLog = (task.statusLog ?? []).map((entry) => ({
+                ...entry,
+                fromStatus: entry.fromStatus === "paused" ? "planned" : entry.fromStatus,
+                toStatus: entry.toStatus === "paused" ? "planned" : entry.toStatus,
+            }));
+            if (descriptionUpdatedAt !== task.descriptionUpdatedAt
+                || normalizedStatus !== task.status
+                || pauseSnapshot !== task.pauseSnapshot
+                || statusLog.some((entry, index) => entry !== task.statusLog[index])) {
+                return { ...task, descriptionUpdatedAt, status: normalizedStatus, pauseSnapshot, statusLog };
+            }
+            return task;
+        });
         return { tasks: normalized, changed: normalized.some((task, index) => task !== tasks[index]) };
     }
+    isTerminalTaskStatus(status) {
+        return status === "done" || status === "canceled" || status === "rejected";
+    }
+    async pruneObsoleteWorkDeviations() {
+        const phases = await this.loadAllPhases();
+        const taskStatusById = new Map(phases.flatMap((phase) => phase.tasks.map((task) => [task.id, task.status])));
+        const current = await this.loadWorkDeviations();
+        const next = current.filter((deviation) => {
+            const resumeStatus = taskStatusById.get(deviation.resumeTaskId);
+            return Boolean(resumeStatus) && !this.isTerminalTaskStatus(resumeStatus);
+        });
+        if (next.length === current.length)
+            return;
+        await this.saveWorkDeviations(next);
+        await this.refreshResume();
+    }
     /** Stamp description edits independently from generic entity mutations.
      * Legacy entities cannot reveal their historical description-edit time, so
      * their creation time is the earliest truthful fallback. */
@@ -734,8 +818,28 @@ export class PlanStore {
         return join(this.localRoot(), "activity.json");
     }
     localRoot() {
+        // Worktree-local, git-ignored runtime state. The shared-vs-local boundary
+        // and the invariants every harness relies on are documented in
+        // packages/plan-core/docs/runtime-boundaries.md.
         return join(this.root, ".local");
     }
+    deviationsPath() {
+        return join(this.localRoot(), "deviations.json");
+    }
+    /** Runtime work deviations, persisted in worktree-local `.local/deviations.json`
+     *  (never in shared `project.json`). Falls back to `[]` on a missing/corrupt file. */
+    async loadWorkDeviations() {
+        try {
+            return await readJson(this.deviationsPath(), WorkDeviationSchema.array());
+        }
+        catch {
+            return [];
+        }
+    }
+    async saveWorkDeviations(deviations) {
+        await atomicWriteJson(this.deviationsPath(), deviations, this.root);
+        await this.maybeAutoSync();
+    }
     timestampPath() {
         return join(this.localRoot(), "timestamp.json");
     }
@@ -822,6 +926,9 @@ export class PlanStore {
         };
         await atomicWriteJson(this.manifestPath(), manifest, this.root);
         await atomicWriteJson(this.timestampPath(), { updatedAt: manifest.updatedAt }, this.root);
+        // Seed the worktree-local runtime-deviation store (T299). Empty for new
+        // projects; migrateWorkDeviations (loadProject) backfills legacy data.
+        await atomicWriteJson(this.deviationsPath(), [], this.root);
         await this.saveProject({
             name: projectName,
             goal: "",
@@ -860,6 +967,11 @@ export class PlanStore {
             guardBypassUntil: "",
         });
         await this.writeGenerated();
+        // Write the STATIC planner extension rules. Content is fixed (no timestamps,
+        // no dynamic data) so the file is identical across worktrees/branches and
+        // never causes git conflicts. The canonical source is plan-core; this file
+        // is the per-project copy / override point, loaded at planner startup.
+        await writeFile(join(this.root, "rules.json"), JSON.stringify({ extensionRules: PLANNER_EXTENSION_RULES }, null, 2), "utf-8");
         // Write a README stub
         const readme = [
             "# Project Plan",
@@ -884,6 +996,15 @@ export class PlanStore {
         // - generated/: auto-regenerated markdown views (derived from JSON; churn)
         await writeFile(join(this.root, ".gitignore"), PLANNER_GITIGNORE, "utf-8");
     }
+    /**
+     * Planner extension rules — the agent-behavior contract for every project
+     * using the extension. Loaded from the static .planner/rules.json if present,
+     * otherwise the canonical code set. Static (no timestamps), safe across
+     * worktrees/branches.
+     */
+    async extensionRules() {
+        return loadExtensionRules(this.root);
+    }
     /** Idempotently ensure `.planner/.gitignore` ignores `.local/` (and the
      *  canonical transient/derived patterns). Projects initialized before the
      *  `.local/` move either have no `.planner/.gitignore` or one with stale
@@ -924,7 +1045,19 @@ export class PlanStore {
         return timestamp ? { ...manifest, updatedAt: timestamp.updatedAt } : manifest;
     }
     async loadProject() {
-        return readJson(this.projectPath(), ProjectSchema);
+        const project = await readJson(this.projectPath(), ProjectSchema);
+        // One-time migration (T299): move runtime workDeviations from the shared
+        // project.json into worktree-local .local/deviations.json, then clear them
+        // in project.json so runtime state never churns shared metadata.
+        // Idempotent: a non-empty .local file is never overwritten.
+        if (project.workDeviations.length > 0 && (await this.loadWorkDeviations()).length === 0) {
+            await this.saveWorkDeviations(project.workDeviations);
+            await atomicUpdateJson(this.projectPath(), ProjectSchema, (p) => ({ ...p, workDeviations: [] }), this.root);
+        }
+        // Read-view merge: readers keep using `project.workDeviations`, but the
+        // values now come from worktree-local storage.
+        const deviations = await this.loadWorkDeviations();
+        return { ...project, workDeviations: deviations };
     }
     /**
      * Reserve immutable human identifiers without touching tracked `project.json`.
@@ -1144,12 +1277,13 @@ export class PlanStore {
     async refreshResume(notes, lastSessionSummary) {
         const workspace = await this.loadAll();
         const inProgressPhases = workspace.phases.filter((p) => p.status === "in-progress");
+        const activePhase = workspace.phases.find((phase) => phase.tasks.some((task) => task.status === "in-progress"));
         const inProgressTasks = workspace.phases.flatMap((p) => p.tasks.filter((t) => t.status === "in-progress"));
         const blockedTasks = workspace.phases.flatMap((p) => p.tasks.filter((t) => t.status === "blocked"));
         const existing = await this.loadResume();
         const resume = {
             updatedAt: nowISO(),
-            currentPhaseId: inProgressPhases[0]?.id ?? existing?.currentPhaseId ?? "",
+            currentPhaseId: activePhase?.id ?? (existing?.currentPhaseId || inProgressPhases[0]?.id || ""),
             inProgressTaskIds: inProgressTasks.map((t) => t.id),
             nextSteps: existing?.nextSteps ?? [],
             nextStepsUpdatedAt: existing?.nextStepsUpdatedAt ?? "",
@@ -1362,6 +1496,45 @@ export class PlanStore {
                     catch { /* ignore */ }
                 }
             }
+            const backupsRoot = join(this.root, ".local", "backups");
+            const walkBackups = async (dir) => {
+                let entries = [];
+                try {
+                    entries = await readdir(dir);
+                }
+                catch {
+                    return;
+                }
+                for (const name of entries) {
+                    const full = join(dir, name);
+                    let st;
+                    try {
+                        st = await stat(full);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (st.isDirectory()) {
+                        await walkBackups(full);
+                        continue;
+                    }
+                    if (!name.endsWith(".json.bak"))
+                        continue;
+                    const rel = full.slice(backupsRoot.length).replace(/^\//, "");
+                    const mainPath = join(this.root, rel.slice(0, -".bak".length));
+                    try {
+                        await stat(mainPath);
+                    }
+                    catch {
+                        try {
+                            await unlink(full);
+                            removed += 1;
+                        }
+                        catch { /* ignore */ }
+                    }
+                }
+            };
+            await walkBackups(backupsRoot);
         }
         catch { /* best-effort */ }
         return { removed };
@@ -1592,18 +1765,13 @@ export class PlanStore {
             return "done";
         const hasDone = meaningful.some((s) => s === "done");
         const hasActive = meaningful.some((s) => s === "in-progress");
-        const hasPaused = meaningful.some((s) => s === "paused");
         const hasPlanned = meaningful.some((s) => s === "planned");
         const hasBlocked = meaningful.some((s) => s === "blocked");
         const hasWaiting = meaningful.some((s) => s === "waiting");
         const hasDeferred = meaningful.some((s) => s === "deferred");
         if (hasActive)
             return "in-progress";
-        // If completed work exists and the ONLY remaining meaningful work is paused
-        // or deferred, do not imply active execution.
-        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && !hasDeferred && hasPaused)
-            return "paused";
-        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && !hasPaused && hasDeferred)
+        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && hasDeferred)
             return "deferred";
         // Partial completion with remaining planned/blocked/waiting work still means
         // the phase has genuinely started and is not terminal yet.
@@ -1616,8 +1784,6 @@ export class PlanStore {
             return "waiting";
         if (hasDeferred)
             return "deferred";
-        if (hasPaused)
-            return "paused";
         return "planned";
     }
     deriveFeatureStatus(featureId, phases) {
@@ -1633,17 +1799,13 @@ export class PlanStore {
             return "done";
         const hasDone = meaningful.some((s) => s === "done");
         const hasActive = meaningful.some((s) => s === "discovery" || s === "in-progress");
-        const hasPaused = meaningful.some((s) => s === "paused");
         const hasPlanned = meaningful.some((s) => s === "planned");
         const hasBlocked = meaningful.some((s) => s === "blocked");
         const hasWaiting = meaningful.some((s) => s === "waiting");
         const hasDeferred = meaningful.some((s) => s === "deferred");
         if (hasActive)
             return "in-progress";
-        // Same rule as phases: done + paused/deferred-only remainder is non-active.
-        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && !hasDeferred && hasPaused)
-            return "paused";
-        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && !hasPaused && hasDeferred)
+        if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && hasDeferred)
             return "deferred";
         if (hasDone)
             return "in-progress";
@@ -1654,8 +1816,6 @@ export class PlanStore {
             return "waiting";
         if (hasDeferred)
             return "deferred";
-        if (hasPaused)
-            return "paused";
         return "planned";
     }
     async syncStatuses() {
@@ -1740,24 +1900,23 @@ export class PlanStore {
     }
     /** Persist an explicitly approved work deviation without coupling it to a harness. */
     async addWorkDeviation(deviation) {
-        return this.updateProject((project) => ({
-            ...project,
-            workDeviations: [...project.workDeviations, deviation],
-        }));
+        const deviations = [...(await this.loadWorkDeviations()), deviation];
+        await this.saveWorkDeviations(deviations);
+        return this.loadProject();
     }
     /** Advance a deviation while retaining its complete audit and return stack. */
     async setWorkDeviationState(id, state, timestamp = nowISO()) {
-        return this.updateProject((project) => ({
-            ...project,
-            workDeviations: project.workDeviations.map((deviation) => deviation.id !== id ? deviation : {
-                ...deviation,
-                state,
-                activatedAt: state === "active" ? timestamp : deviation.activatedAt,
-                resumeRequiredAt: state === "resume-required" ? timestamp : deviation.resumeRequiredAt,
-                resolvedAt: state === "resolved" || state === "canceled" ? timestamp : deviation.resolvedAt,
-                resumedAt: state === "resumed" ? timestamp : deviation.resumedAt,
-            }),
-        }));
+        const deviations = await this.loadWorkDeviations();
+        const next = deviations.map((deviation) => deviation.id !== id ? deviation : {
+            ...deviation,
+            state,
+            activatedAt: state === "active" ? timestamp : deviation.activatedAt,
+            resumeRequiredAt: state === "resume-required" ? timestamp : deviation.resumeRequiredAt,
+            resolvedAt: state === "resolved" || state === "canceled" ? timestamp : deviation.resolvedAt,
+            resumedAt: state === "resumed" ? timestamp : deviation.resumedAt,
+        });
+        await this.saveWorkDeviations(next);
+        return this.loadProject();
     }
     async updateFeatures(updater) {
         const updated = await this.withFeaturesLock(async () => {
@@ -1784,7 +1943,9 @@ export class PlanStore {
         return updated;
     }
     async saveProject(project) {
-        const parsed = ProjectSchema.parse(project);
+        // Runtime workDeviations live in .local/deviations.json (T299); never
+        // persist them here so shared project.json stays stable across worktrees.
+        const parsed = ProjectSchema.parse({ ...project, workDeviations: [] });
         await atomicWriteJson(this.projectPath(), parsed, this.root);
         await this.touchTimestamp();
         await this.maybeAutoSync();
@@ -1896,11 +2057,12 @@ export class PlanStore {
                 ? { ...timestamped, featureId: resolvedFeatureId }
                 : timestamped;
             return this.normalizePhaseDocument(normalizedInput).phase;
-        });
+        }, this.root);
+        await this.pruneObsoleteWorkDeviations();
         await this.maybeAutoSync();
         return { ...raw, status: this.derivePhaseStatus(raw.tasks) };
     }
-    /** Pause active work with a mandatory durable checkpoint. */
+    /** Save a durable resume checkpoint without introducing a separate canonical task status. */
     async pauseTask(phaseId, taskId, input) {
         const snapshot = TaskPauseSnapshotSchema.parse(input);
         let paused;
@@ -1909,7 +2071,7 @@ export class PlanStore {
             if (!task)
                 throw new PlanStoreError(`Task ${taskId} does not belong to phase ${phaseId}.`);
             if (task.status !== "in-progress") {
-                throw new PlanStoreError(`Task ${taskId} cannot be paused from ${task.status}; only in-progress work can be paused.`);
+                throw new PlanStoreError(`Task ${taskId} cannot be checkpointed from ${task.status}; only in-progress work can capture a pause snapshot.`);
             }
             const description = [
                 `Reason: ${snapshot.reason}`,
@@ -1919,15 +2081,15 @@ export class PlanStore {
             ].join("\n");
             paused = {
                 ...task,
-                status: "paused",
+                status: "planned",
                 pauseSnapshot: snapshot,
                 pauseHistory: [...task.pauseHistory, snapshot],
                 statusLog: [...task.statusLog, {
                         id: createStatusLogEntryId(),
                         date: snapshot.pausedAt,
                         fromStatus: "in-progress",
-                        toStatus: "paused",
-                        title: "in-progress → paused",
+                        toStatus: "planned",
+                        title: "in-progress → planned (checkpoint saved)",
                         description,
                     }],
                 updatedAt: snapshot.pausedAt,
@@ -1937,15 +2099,18 @@ export class PlanStore {
         });
         return paused;
     }
-    /** Resume a paused task without resetting its original startedAt. */
+    /** Resume a checkpointed task without resetting its original startedAt. */
     async resumeTask(phaseId, taskId, timestamp = nowISO()) {
         let resumed;
         await this.updatePhase(phaseId, (phase) => {
             const task = phase.tasks.find((candidate) => candidate.id === taskId);
             if (!task)
                 throw new PlanStoreError(`Task ${taskId} does not belong to phase ${phaseId}.`);
-            if (task.status !== "paused") {
-                throw new PlanStoreError(`Task ${taskId} cannot be resumed from ${task.status}; only paused work can be resumed.`);
+            if (!task.pauseSnapshot) {
+                throw new PlanStoreError(`Task ${taskId} has no saved checkpoint to resume.`);
+            }
+            if (task.status === "done" || task.status === "canceled" || task.status === "rejected") {
+                throw new PlanStoreError(`Task ${taskId} cannot be resumed from ${task.status}.`);
             }
             const snapshot = task.pauseSnapshot;
             resumed = {
@@ -1956,12 +2121,10 @@ export class PlanStore {
                 statusLog: [...task.statusLog, {
                         id: createStatusLogEntryId(),
                         date: timestamp,
-                        fromStatus: "paused",
+                        fromStatus: task.status,
                         toStatus: "in-progress",
-                        title: "paused → in-progress",
-                        description: snapshot
-                            ? `Resumed from ${snapshot.resumeLocation}. ${snapshot.howToResume}`
-                            : "Paused task resumed.",
+                        title: `${task.status} → in-progress (resume checkpoint)`,
+                        description: `Resumed from ${snapshot.resumeLocation}. ${snapshot.howToResume}`,
                     }],
                 updatedAt: timestamp,
             };
@@ -2186,16 +2349,16 @@ export class PlanStore {
         await this.unlinkPhaseFiles(phaseId);
         await this.touchTimestamp();
     }
-    /** Remove a phase file AND its inline .bak backup. atomicUpdateJson (used by
-     *  updatePhase without root) writes the backup inline at phases/<id>.json.bak,
-     *  and readJson falls back to `${path}.bak` on a missing main file — so a
-     *  delete that leaves the .bak behind would RESURRECT the deleted phase on
-     *  the next read. Feature backups (written with root) live under
-     *  .local/backups/ and are never read by readJson, so only the inline .bak
-     *  needs removing here. */
+    /** Remove a phase file and BOTH of its previous-version backups: the legacy
+     *  inline `phases/<id>.json.bak` (kept for backward compat) and the relocated
+     *  `.local/backups/phases/<id>.json.bak` (written once updatePhase passes root,
+     *  per P043). Leaving either behind would RESURRECT the deleted phase on the
+     *  next read, since readJson falls back to both locations. */
     async unlinkPhaseFiles(phaseId) {
-        await unlink(this.phasePath(phaseId)).catch(() => { });
-        await unlink(`${this.phasePath(phaseId)}.bak`).catch(() => { });
+        const phaseFile = this.phasePath(phaseId);
+        await unlink(phaseFile).catch(() => { });
+        await unlink(`${phaseFile}.bak`).catch(() => { });
+        await unlink(join(this.root, ".local", "backups", "phases", `${phaseId}.json.bak`)).catch(() => { });
     }
     // ── Workspace-level operations ─────────────────────────────────────
     /** Load the full workspace (manifest + phases + project + requirements + features) */

package/dist/planner-rules.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Canonical planner extension rules — the agent-behavior contract that applies
+ * to EVERY project using the Agent Plan extension (Pi, MCP / Claude Code / Codex,
+ * future harnesses). These are STATIC: no timestamps, no dynamic content, so the
+ * same text seeds every .planner/ and never diverges across worktrees or
+ * branches (no conflict from date/timestamp changes).
+ *
+ * AGENTS.md governs ONLY the development of the agent-plan extension and must
+ * not duplicate these rules.
+ */
+export declare const PLANNER_EXTENSION_RULES: string[];
+export interface ExtensionRulesFile {
+    extensionRules: string[];
+}
+/**
+ * Load the effective extension rules for a planner root. Returns the project's
+ * own .planner/rules.json (static, user-overridable) when present and non-empty,
+ * otherwise the canonical code set. Never returns timestamps or dynamic data.
+ */
+export declare function loadExtensionRules(plannerRoot: string): Promise<string[]>;
+//# sourceMappingURL=planner-rules.d.ts.map

package/dist/planner-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-rules.d.ts","sourceRoot":"","sources":["../src/planner-rules.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,EA2B3C,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAW/E"}

package/dist/planner-rules.js

@@ -0,0 +1,58 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Canonical planner extension rules — the agent-behavior contract that applies
+ * to EVERY project using the Agent Plan extension (Pi, MCP / Claude Code / Codex,
+ * future harnesses). These are STATIC: no timestamps, no dynamic content, so the
+ * same text seeds every .planner/ and never diverges across worktrees or
+ * branches (no conflict from date/timestamp changes).
+ *
+ * AGENTS.md governs ONLY the development of the agent-plan extension and must
+ * not duplicate these rules.
+ */
+export const PLANNER_EXTENSION_RULES = [
+    // §1 — source of truth
+    "Keep the planner as the single operational source of truth while working: read the relevant planner state before starting; update it when an activity starts, changes state, blocks, or concludes; and record next steps, blockers, and decisions in the relevant planner entities. Never leave work only in the conversation.",
+    // §2 — task lifecycle
+    "Respect the task lifecycle strictly. Always call task_start before touching code, and task_complete when a deliverable is done. Sync state changes (start/complete/block) to the planner at the exact moment they happen — never batch updates at session end. If the extension reports 'no active task', immediately start the correct task. A task marked in-progress means you are actually working on it; if you stop, close or block it with a motivation in statusLog. Derived feature/phase status is computed from tasks, not stored in JSON.",
+    // §3 — markdown not source of truth
+    "Do not treat markdown as the source of truth for the plan. The plan's primary source is structured data in .planner/; markdown is a generated, human/agent-readable view.",
+    // §5 — plan location
+    "The plan lives in .planner/ within the target project. Whether .planner/ is git-tracked is at the project's discretion.",
+    // §6 — discuss per phase
+    "Discuss the plan per phase: clarify objective, scope, non-scope, dependencies, risks, and outcomes before working a phase; detail implementation when the phase is actually worked, not up front.",
+    // §7 — naming
+    "Naming: phases and tasks use global project-wide numbering (P001, T001, …) with a slug derived from the title. Numbers are assigned once at creation from a monotonic global counter and never reused (deletes leave gaps).",
+    // §8 — status changes & motivation
+    "Every task status change is recorded in an incremental statusLog. Motivation is mandatory for blocked/canceled/rejected/deferred/waiting and for returning to planned from a non-planned status; not required for done or for normal in-progress-from-planned. Use task_update (not task_start/task_complete) for non-lifecycle status changes, with an exhaustive motivation.",
+    // §10 — references
+    "Reference entities with human, unique, composite IDs — Feature 'F001 - Name', Phase 'P001(F001) - Title', Task 'T003 - Number'. Short forms P003/T007 and the 5-char global shortId (e.g. UUXD1) are also valid. Never reference raw UUIDs. To locate an entity, use the compact list tools (feature_list/phase_list/task_list), not by reading .planner/*.json files.",
+    // §12 — handoff
+    "Handoff is per-phase (phase.handoff), not a file. Write it only on explicit user request; on resume, read it then clear it before starting work. A pending handoff never blocks task_start. Do not leave a handoff stale after processing it.",
+    // §12 — operational hygiene
+    "Operational hygiene: start the task (task_start) before thinking about implementation; complete it (task_complete) as part of delivering the deliverable, not after; motivate every block so a third party can understand the impediment.",
+    // Avvio del planner
+    "The planner and Web UI never start automatically. Do not start the Web UI or show its URL unless the user runs load/recap/web-status. The Web UI URL appears only in the recap after load, or on explicit web status.",
+    // Regola dettagli
+    "Write relevant points (decisions, constraints, current state, file:line refs, edge cases) into the task/phase/feature description or notes as soon as they emerge. Before starting, resuming, or switching to a task, read task_get(full=true), then its parent phase_get(full=true), then its parent feature_get(full=true), in that exact order; read linked requirements explicitly when present. Cite entities with composite IDs, not bare UUIDs.",
+    // Expected operational behavior
+    "When you begin work, task_start and task_switch enforce the required ordered full reads. Read any relevant phase handoff as additional context, then update the planner before and after significant changes. If you change an architectural decision, document it explicitly.",
+];
+/**
+ * Load the effective extension rules for a planner root. Returns the project's
+ * own .planner/rules.json (static, user-overridable) when present and non-empty,
+ * otherwise the canonical code set. Never returns timestamps or dynamic data.
+ */
+export async function loadExtensionRules(plannerRoot) {
+    try {
+        const raw = await readFile(join(plannerRoot, "rules.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed.extensionRules) && parsed.extensionRules.length > 0) {
+            return parsed.extensionRules.filter((r) => typeof r === "string" && r.length > 0);
+        }
+    }
+    catch {
+        // Missing or malformed rules.json → fall back to the canonical code set.
+    }
+    return PLANNER_EXTENSION_RULES;
+}

package/dist/read-tracking.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Per-session, ordered context-read enforcement for agent lifecycle operations.
+ *
+ * An agent must read the exact task, then its parent phase, then its parent
+ * feature with full=true before it can start, resume, or switch to that task.
+ * Compact list/identity reads never count. The state is process-local and is
+ * cleared on pause, switch, and session startup by the harness adapters.
+ *
+ * Linked requirements remain a separate explicit-read gate. They are recorded
+ * only through the requirement list tool and never by an entity read.
+ */
+export type ContextReadEligibility = {
+    eligible: boolean;
+    reason: string;
+};
+/** Record a full feature read. */
+export declare function markFeatureRead(featureId: string): void;
+/** Record a full phase read. The parent feature is intentionally not implied. */
+export declare function markPhaseRead(phaseId: string, _featureId?: string): void;
+/** Record a full task read. Its parent phase and feature are intentionally not implied. */
+export declare function markTaskRead(taskId: string, _phaseId?: string, _featureId?: string): void;
+/** Record that a requirement was explicitly read via the requirement list tool. */
+export declare function markRequirementRead(requirementId: string): void;
+/**
+ * Verify the required task(full) → phase(full) → feature(full) order for one
+ * exact task lineage. Orphan phases do not require a feature read.
+ */
+export declare function contextReadEligibility(taskId: string, phaseId: string, featureId?: string): ContextReadEligibility;
+/**
+ * Legacy parent-read check retained for callers that only need to know whether
+ * both parent entities have been read. Lifecycle gates must use
+ * contextReadEligibility so the task and ordering cannot be bypassed.
+ */
+export declare function hasReadParents(featureId: string | undefined, phaseId: string): boolean;
+/** Whether every linked requirement has been explicitly read. */
+export declare function hasReadRequirements(requirementIds: string[]): boolean;
+/** Clear all read state so later lifecycle work requires fresh context. */
+export declare function invalidateReads(): void;
+/** Compatibility advisory for non-lifecycle callers. */
+export declare function parentReadAdvisory(featureId: string | undefined, phaseId: string): string;
+/** Advisory text for the separate linked-requirements gate. */
+export declare function requirementReadAdvisory(requirementIds: string[]): string;
+/** Snapshot for diagnostics and tests. */
+export declare function readTrackingSnapshot(): {
+    features: string[];
+    phases: string[];
+    requirements: string[];
+};
+//# sourceMappingURL=read-tracking.d.ts.map

package/dist/read-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-tracking.d.ts","sourceRoot":"","sources":["../src/read-tracking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAeF,kCAAkC;AAClC,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAExE;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzF;AAED,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,sBAAsB,CAmBlH;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAItF;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAErE;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,IAAI,IAAI,CAQtC;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzF;AAED,+DAA+D;AAC/D,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,MAAM,CAKxE;AAED,0CAA0C;AAC1C,wBAAgB,oBAAoB,IAAI;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAMvG"}