@agent-plan/core 0.2.20 → 0.2.22-next.0

package/dist/plan-store.js

@@ -14,9 +14,10 @@ const PLANNER_GITIGNORE = [
     "generated/",
     "",
 ].join("\n");
-import { CodebaseProfileSchema, FeatureSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, 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`.
@@ -1362,6 +1495,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 };
@@ -1598,15 +1770,13 @@ export class PlanStore {
         const hasDeferred = meaningful.some((s) => s === "deferred");
         if (hasActive)
             return "in-progress";
-        // If completed work exists and the ONLY remaining meaningful work is deferred,
-        // surface deferred instead of implying active execution.
         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.
         if (hasDone)
             return "in-progress";
-        // No progress at all ⇒ surface the stall / not-started state (blocked > waiting > deferred > planned).
+        // No progress at all ⇒ surface the stall / not-started state.
         if (hasBlocked)
             return "blocked";
         if (hasWaiting)
@@ -1634,7 +1804,6 @@ export class PlanStore {
         const hasDeferred = meaningful.some((s) => s === "deferred");
         if (hasActive)
             return "in-progress";
-        // Same rule as phases: done + deferred-only remainder is deferred, not active.
         if (hasDone && !hasPlanned && !hasBlocked && !hasWaiting && hasDeferred)
             return "deferred";
         if (hasDone)
@@ -1730,22 +1899,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();
     }
-    /** Mark an approved/active deviation as resolved or canceled while retaining its audit record. */
+    /** 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,
-                resolvedAt: state === "resolved" || state === "canceled" ? timestamp : deviation.resolvedAt,
-            }),
-        }));
+        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 () => {
@@ -1772,7 +1942,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();
@@ -1884,10 +2056,82 @@ 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) };
     }
+    /** Save a durable resume checkpoint without introducing a separate canonical task status. */
+    async pauseTask(phaseId, taskId, input) {
+        const snapshot = TaskPauseSnapshotSchema.parse(input);
+        let paused;
+        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 !== "in-progress") {
+                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}`,
+                `What was being done: ${snapshot.whatWasBeingDone}`,
+                `Resume location: ${snapshot.resumeLocation}`,
+                `How to resume: ${snapshot.howToResume}`,
+            ].join("\n");
+            paused = {
+                ...task,
+                status: "planned",
+                pauseSnapshot: snapshot,
+                pauseHistory: [...task.pauseHistory, snapshot],
+                statusLog: [...task.statusLog, {
+                        id: createStatusLogEntryId(),
+                        date: snapshot.pausedAt,
+                        fromStatus: "in-progress",
+                        toStatus: "planned",
+                        title: "in-progress → planned (checkpoint saved)",
+                        description,
+                    }],
+                updatedAt: snapshot.pausedAt,
+            };
+            phase.tasks = phase.tasks.map((candidate) => candidate.id === taskId ? paused : candidate);
+            return phase;
+        });
+        return paused;
+    }
+    /** 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.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 = {
+                ...task,
+                status: "in-progress",
+                pauseSnapshot: null,
+                startedAt: task.startedAt || timestamp,
+                statusLog: [...task.statusLog, {
+                        id: createStatusLogEntryId(),
+                        date: timestamp,
+                        fromStatus: task.status,
+                        toStatus: "in-progress",
+                        title: `${task.status} → in-progress (resume checkpoint)`,
+                        description: `Resumed from ${snapshot.resumeLocation}. ${snapshot.howToResume}`,
+                    }],
+                updatedAt: timestamp,
+            };
+            phase.tasks = phase.tasks.map((candidate) => candidate.id === taskId ? resumed : candidate);
+            return phase;
+        });
+        return resumed;
+    }
     // ── Phase-scoped handoff (entity field, harness-agnostic) ────────────
     /** Get the handoff text for a phase ("" if none). Throws if phase missing. */
     async getPhaseHandoff(phaseId) {
@@ -2104,16 +2348,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; read the task description and notes (and parent phase/feature) before starting work; cite entities with composite IDs, not bare UUIDs.",
+    // Comportamento atteso 2-5
+    "When you begin work: read the relevant planner entities (feature_get/phase_get/task_get/handoff_show), read the relevant documents, and 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,58 @@
+/**
+ * T307 (P072/F005) — tracked, deduplicated parent read-enforcement.
+ *
+ * Analogous to the existing NO ACTIVE TASK advisory: an in-memory, per-session
+ * record of which feature/phase refs the agent has actually read (via the
+ * feature/phase/task get/show tools). Starting, resuming, or switching a task
+ * checks that the target's parent feature + phase are in the read set; a missing
+ * read yields an unavoidable (non-blocking) advisory instead of a silent skip.
+ *
+ * Dedupe: reading a phase (or any task inside it) records both its phase and
+ * feature, so 10 sibling tasks need a single feature + phase read. Switching to
+ * a different phase/feature naturally fails (that phase is not recorded). A
+ * pause invalidates the set, so resuming forces a fresh read.
+ *
+ * T319 (P072/F005) extends the set with requirements: starting/resuming/switching
+ * also requires the requirements linked to the phase (and, when present, the
+ * feature) to have been explicitly read. Requirements are NOT auto-recorded by a
+ * phase/feature/task read (per project decision: explicit separate read); they
+ * are recorded only via the requirement list tool (markRequirementRead). An empty
+ * linked-requirement list means nothing is required.
+ */
+/** Record that a feature was read. Does NOT imply any phase was read. */
+export declare function markFeatureRead(featureId: string): void;
+/** Record that a phase (and, when known, its feature) was read. */
+export declare function markPhaseRead(phaseId: string, featureId?: string): void;
+/** Record that a task (and, by context, its parent phase + feature) was read. */
+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;
+/**
+ * Whether the target task's parent feature + phase have both been read.
+ * `featureId` is optional: an orphan phase (no feature) only requires the phase.
+ */
+export declare function hasReadParents(featureId: string | undefined, phaseId: string): boolean;
+/** Whether every linked requirement (phase + feature) has been explicitly read. */
+export declare function hasReadRequirements(requirementIds: string[]): boolean;
+/** Clear the read set (e.g. on pause, so resuming forces a fresh read). */
+export declare function invalidateReads(): void;
+/**
+ * Non-blocking advisory (mirrors the NO ACTIVE TASK pattern): empty when the
+ * target's parent feature + phase have both been read, otherwise a loud
+ * READ REQUIRED notice the agent cannot silently skip.
+ */
+export declare function parentReadAdvisory(featureId: string | undefined, phaseId: string): string;
+/**
+ * Non-blocking advisory (mirrors parentReadAdvisory): empty when every linked
+ * requirement (phase + feature) has been explicitly read, otherwise a loud
+ * REQUIREMENTS READ REQUIRED notice. An empty list means the phase/feature has
+ * no linked requirements, so nothing is required.
+ */
+export declare function requirementReadAdvisory(requirementIds: string[]): string;
+/** Snapshot for diagnostics/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;;;;;;;;;;;;;;;;;;;;GAoBG;AAUH,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAGvE;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAGvF;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAItF;AAED,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAErE;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,MAAM,CAKxE;AAED,sCAAsC;AACtC,wBAAgB,oBAAoB,IAAI;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAEvG"}