@agent-plan/core 0.2.25 → 0.2.26

package/dist/plan-store.js

@@ -1,5 +1,5 @@
 import { access, copyFile, mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve, sep } from "node:path";
 import { randomUUID } from "node:crypto";
 import { z, ZodError } from "zod";
 /** Canonical `.planner/.gitignore` content (P042 spec): ignore the `.local/`
@@ -14,11 +14,13 @@ const PLANNER_GITIGNORE = [
     "generated/",
     "",
 ].join("\n");
-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 { CodebaseProfileSchema, FeatureSchema, FeaturesDocumentSchema, ManifestSchema, PhaseSchema, TaskPauseSnapshotSchema, ProjectSchema, RequirementsDocumentSchema, IdeaSchema, IdeasDocumentSchema, ResumeFocusSchema, ActivityLogSchema, TimestampSchema, WorkDeviationSchema, } from "./schema.js";
+import { createFeatureId, createIdeaId, createPhaseId, createRequirementId, createShortId, createStatusLogEntryId, createTaskId, formatFeatureRef, formatIdeaRef, formatPhaseRef, formatThreeDigitNumber, isLegacyPhaseId } from "./naming.js";
 import { deriveParentDisplay, fromCanonicalStatus } from "./display-status.js";
 import { loadExtensionRules, PLANNER_EXTENSION_RULES } from "./planner-rules.js";
-import { applyHandoffContextSync, auditPhaseHandoff, } from "./handoff-context.js";
+import { loadProjectGrillMeSkill, syncProjectGrillMeSkill, syncProjectPlannerSkill } from "./planner-skill.js";
+import { applyLegacyProjectContextMigration, plannerSessionPreparationResult, previewLegacyProjectContextMigration, } from "./project-context-migration.js";
+import { applyHandoffContextSync, auditPhaseHandoff, handoffContentHash, HandoffContractError, } from "./handoff-context.js";
 function nowISO() {
     return new Date().toISOString();
 }
@@ -89,7 +91,7 @@ const CROSS_PROCESS_LOCK_RETRY_MS = 10;
 /** Allocation registry is deliberately outside the versioned plan. Git worktrees
  * share their common git dir, so reservations are serialized across branches
  * without rewriting project.json or unrelated planner entities. */
-const AllocationKindSchema = z.enum(["feature", "phase", "task"]);
+const AllocationKindSchema = z.enum(["feature", "phase", "task", "idea"]);
 const AllocationRegistrySchema = z.object({
     version: z.literal(1),
     projectId: z.string().min(1),
@@ -584,7 +586,7 @@ export class PlanStore {
         // 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) => {
-            const descriptionUpdatedAt = task.description && !task.descriptionUpdatedAt
+            const descriptionUpdatedAt = (task.description || task.descriptionRef) && !task.descriptionUpdatedAt
                 ? task.createdAt
                 : task.descriptionUpdatedAt;
             const normalizedStatus = task.status === "paused" ? "planned" : task.status;
@@ -623,17 +625,56 @@ export class PlanStore {
     /** 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. */
-    stampDescriptionUpdatedAt(entity, previousDescription, timestamp) {
-        if (!entity.description)
+    stampDescriptionUpdatedAt(entity, previousDescription, previousDescriptionRef, timestamp) {
+        if (!entity.description && !entity.descriptionRef)
             return { ...entity, descriptionUpdatedAt: "" };
-        if (previousDescription === undefined || previousDescription !== entity.description) {
+        if (previousDescription === undefined
+            || previousDescription !== entity.description
+            || previousDescriptionRef !== entity.descriptionRef) {
             return { ...entity, descriptionUpdatedAt: timestamp };
         }
         return entity.descriptionUpdatedAt ? entity : { ...entity, descriptionUpdatedAt: entity.createdAt };
     }
+    stampProjectGuidelinesUpdatedAt(project, previousContent, timestamp) {
+        const nextContent = project.projectGuidelines.content.trim();
+        const nextGuidelines = {
+            content: nextContent,
+            updatedAt: project.projectGuidelines.updatedAt,
+            sessionInfo: project.projectGuidelines.sessionInfo,
+        };
+        if (!nextContent) {
+            return {
+                ...project,
+                projectGuidelines: {
+                    ...nextGuidelines,
+                    updatedAt: "",
+                    sessionInfo: [],
+                },
+            };
+        }
+        if (previousContent === undefined || previousContent !== nextContent) {
+            return {
+                ...project,
+                projectGuidelines: {
+                    ...nextGuidelines,
+                    updatedAt: timestamp,
+                },
+            };
+        }
+        if (nextGuidelines.updatedAt) {
+            return { ...project, projectGuidelines: nextGuidelines };
+        }
+        return {
+            ...project,
+            projectGuidelines: {
+                ...nextGuidelines,
+                updatedAt: timestamp,
+            },
+        };
+    }
     normalizeFeaturesDocument(doc) {
         // Numbers are a STABLE global sequence (assigned once at create from project.nextFeatureNumber).
-        const features = doc.features.map((feature) => feature.description && !feature.descriptionUpdatedAt
+        const features = doc.features.map((feature) => (feature.description || feature.descriptionRef) && !feature.descriptionUpdatedAt
             ? { ...feature, descriptionUpdatedAt: feature.createdAt }
             : feature);
         return { doc: { ...doc, features }, changed: features.some((feature, index) => feature !== doc.features[index]) };
@@ -642,7 +683,7 @@ export class PlanStore {
         const { tasks, changed } = this.normalizeTasks(phase.tasks);
         const nextTaskIds = tasks.map((task) => task.id);
         const taskIdsChanged = nextTaskIds.length !== phase.taskIds.length || nextTaskIds.some((id, index) => id !== phase.taskIds[index]);
-        const descriptionUpdatedAt = phase.description && !phase.descriptionUpdatedAt ? phase.createdAt : phase.descriptionUpdatedAt;
+        const descriptionUpdatedAt = (phase.description || phase.descriptionRef) && !phase.descriptionUpdatedAt ? phase.createdAt : phase.descriptionUpdatedAt;
         const descriptionTimestampChanged = descriptionUpdatedAt !== phase.descriptionUpdatedAt;
         return {
             phase: {
@@ -780,6 +821,9 @@ export class PlanStore {
     requirementsPath() {
         return join(this.root, "requirements.json");
     }
+    ideasPath() {
+        return join(this.root, "ideas.json");
+    }
     featuresPath() {
         return join(this.root, "features.json");
     }
@@ -946,6 +990,11 @@ export class PlanStore {
             name: projectName,
             goal: "",
             description: "",
+            projectGuidelines: {
+                content: "",
+                updatedAt: "",
+                sessionInfo: [],
+            },
             webPort: 0,
             scope: [],
             outOfScope: [],
@@ -967,6 +1016,7 @@ export class PlanStore {
             workDeviations: [],
         });
         await this.saveRequirements({ requirements: [] });
+        await this.saveIdeas({ nextIdeaNumber: 1, ideas: [] });
         await this.saveFeatures({ features: [] });
         await this.saveResume({
             updatedAt: nowISO(),
@@ -985,6 +1035,8 @@ export class PlanStore {
         // 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");
+        await this.syncPlannerSkill();
+        await this.syncGrillMeSkill();
         // Write a README stub
         const readme = [
             "# Project Plan",
@@ -994,8 +1046,11 @@ export class PlanStore {
             "## Structure",
             "",
             "- `manifest.json` — metadata",
+            "- `SKILL.md` — managed cross-harness planner operating guide",
+            "- `skills/grill-me/SKILL.md` — managed idea-discussion interview skill",
             "- `project.json` — scope, rules, stack, tools",
             "- `requirements.json` — requirements and macro-tasks",
+            "- `ideas.json` — top-level Ideas Inbox (excluded from work status derivation)",
             "- `phases/` — one JSON file per phase",
             "- `generated/` — auto-generated markdown views (under `.local/`)",
             "- `schema/plan.schema.json` — JSON Schema for tooling",
@@ -1018,6 +1073,22 @@ export class PlanStore {
     async extensionRules() {
         return loadExtensionRules(this.root);
     }
+    /**
+     * Create or safely refresh the project-local planner usage skill. Explicit
+     * planner-load surfaces call this so unmodified managed copies follow the
+     * installed Agent Plan version while project customizations are preserved.
+     */
+    async syncPlannerSkill() {
+        return syncProjectPlannerSkill(this.root);
+    }
+    /** Safely create or refresh the project-local grill-me skill for Ideas. */
+    async syncGrillMeSkill() {
+        return syncProjectGrillMeSkill(this.root);
+    }
+    /** Load grill-me instructions only when an Ideas discussion requests them. */
+    async ideaDiscussionSkill() {
+        return loadProjectGrillMeSkill(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
@@ -1077,7 +1148,7 @@ export class PlanStore {
      * Worktrees in the same clone share `.git/agent-plan/allocations`, guarded by
      * the same cross-process lock used for atomic writes. The registry reserves
      * numbers/short IDs before an entity file is written, so parallel branches
-     * cannot allocate the same F/P/T or shortId. Existing entities are never
+     * cannot allocate the same F/P/T/I or shortId. Existing entities are never
      * rewritten; cross-clone coordination requires a shared allocator service.
      */
     async allocateEntityIdentity(kind, entityId) {
@@ -1098,19 +1169,30 @@ export class PlanStore {
                 return { number: prior.number, shortId: prior.shortId };
             const phases = await this.loadAllPhases();
             const features = (await this.loadFeatures()).features;
+            const ideasDocument = await this.loadIdeas();
+            const ideas = ideasDocument.ideas;
             const canonical = kind === "feature"
                 ? features.map((feature) => ({ number: feature.number, shortId: feature.shortId }))
                 : kind === "phase"
                     ? phases.map((phase) => ({ number: phase.number, shortId: phase.shortId }))
-                    : phases.flatMap((phase) => phase.tasks.map((task) => ({ number: task.number, shortId: task.shortId })));
+                    : kind === "task"
+                        ? phases.flatMap((phase) => phase.tasks.map((task) => ({ number: task.number, shortId: task.shortId })))
+                        : ideas.map((idea) => ({ number: idea.number, shortId: idea.shortId }));
             const usedNumbers = new Set([...canonical.map((entry) => entry.number), ...registry.allocations.filter((entry) => entry.kind === kind).map((entry) => entry.number)]);
-            const counter = kind === "feature" ? project.nextFeatureNumber : kind === "phase" ? project.nextPhaseNumber : project.nextTaskNumber;
+            const counter = kind === "feature"
+                ? project.nextFeatureNumber
+                : kind === "phase"
+                    ? project.nextPhaseNumber
+                    : kind === "task"
+                        ? project.nextTaskNumber
+                        : ideasDocument.nextIdeaNumber;
             let number = Math.max(1, counter);
             while (usedNumbers.has(number))
                 number += 1;
             const allShortIds = new Set([
                 ...features.map((feature) => feature.shortId),
                 ...phases.flatMap((phase) => [phase.shortId, ...phase.tasks.map((task) => task.shortId)]),
+                ...ideas.map((idea) => idea.shortId),
                 ...registry.allocations.map((entry) => entry.shortId),
             ].filter(Boolean));
             const allocation = { kind, entityId, number, shortId: createShortId(allShortIds, `${kind}:${entityId}`) };
@@ -1124,6 +1206,7 @@ export class PlanStore {
     async allocFeatureNumber() { return this.allocateLegacyNumber("feature"); }
     async allocPhaseNumber() { return this.allocateLegacyNumber("phase"); }
     async allocTaskNumber() { return this.allocateLegacyNumber("task"); }
+    async allocIdeaNumber() { return this.allocateLegacyNumber("idea"); }
     async allocateLegacyNumber(kind) {
         const id = `legacy-${kind}-${randomUUID()}`;
         return (await this.allocateEntityIdentity(kind, id)).number;
@@ -1316,6 +1399,18 @@ export class PlanStore {
             return { requirements: [] };
         }
     }
+    async loadIdeas() {
+        try {
+            const document = await readJson(this.ideasPath(), IdeasDocumentSchema);
+            return {
+                ...document,
+                ideas: [...document.ideas].sort((left, right) => left.number - right.number || left.createdAt.localeCompare(right.createdAt)),
+            };
+        }
+        catch {
+            return { nextIdeaNumber: 1, ideas: [] };
+        }
+    }
     async linkedRequirementsForPhase(phaseId) {
         const requirements = await this.loadRequirements();
         return requirements.requirements.filter((requirement) => requirement.linkedPhaseIds.includes(phaseId));
@@ -1390,16 +1485,17 @@ export class PlanStore {
         return deriveParentDisplay(childStatuses);
     }
     async loadAll() {
-        const [manifest, project, requirements, phases] = await Promise.all([
+        const [manifest, project, requirements, ideas, phases] = await Promise.all([
             this.loadManifest(),
             this.loadProject(),
             this.loadRequirements(),
+            this.loadIdeas(),
             this.loadAllPhases(),
         ]);
         const rawFeatures = await this.loadRawFeatures();
         const features = rawFeatures.map((f) => ({ ...f, status: this.deriveFeatureStatus(f.id, phases) }));
         const normalized = this.normalizeStructureSnapshot({ features }, phases);
-        return { manifest, project, requirements, phases: normalized.phases, features: normalized.features };
+        return { manifest, project, requirements, ideas, phases: normalized.phases, features: normalized.features };
     }
     /** Migrate legacy non-feature-scoped phase ids to feature-scoped ids and repair
      *  dangling feature.phaseIds references. Idempotent. */
@@ -1907,10 +2003,50 @@ export class PlanStore {
     }
     // ── Savers ───────────────────────────────────────────────────────────
     async updateProject(updater) {
-        const updated = await atomicUpdateJson(this.projectPath(), ProjectSchema, updater, this.root);
+        const timestamp = nowISO();
+        const updated = await atomicUpdateJson(this.projectPath(), ProjectSchema, (current) => {
+            const previousGuidelines = current.projectGuidelines.content;
+            const candidate = updater(current);
+            return this.stampProjectGuidelinesUpdatedAt(candidate, previousGuidelines, timestamp);
+        }, this.root);
         await this.maybeAutoSync();
         return updated;
     }
+    /** Preview the explicit, lossless migration from legacy project rule and
+     * decision fields into Project Guidelines and structured accepted decisions. */
+    async previewLegacyProjectContextMigration() {
+        return previewLegacyProjectContextMigration(await readJson(this.projectPath(), ProjectSchema));
+    }
+    /** Prepare an explicit planner session before recap/context delivery.
+     * Ordinary entity reads remain non-mutating. */
+    async preparePlannerSession() {
+        return plannerSessionPreparationResult(await this.migrateLegacyProjectContext());
+    }
+    /** Apply and verify the legacy project-context migration. Callers must invoke
+     * this only from an explicit preparation or compatibility-recovery flow. */
+    async migrateLegacyProjectContext() {
+        const original = await readJson(this.projectPath(), ProjectSchema);
+        const acceptedAt = nowISO();
+        const expected = applyLegacyProjectContextMigration(original, acceptedAt);
+        if (!expected.applied)
+            return expected;
+        await this.updateProject(() => expected.project);
+        const persisted = await readJson(this.projectPath(), ProjectSchema);
+        const migratedDecisionIds = new Set(expected.preview.acceptedDecisionAdditions.map((decision) => decision.id));
+        const persistedDecisionIds = new Set(persisted.acceptedDecisions.map((decision) => decision.id));
+        const verified = persisted.projectGuidelines.content === expected.preview.resultingGuidelinesContent
+            && persisted.globalRules.length === 0
+            && persisted.workflowRules.beforePhaseStart.length === 0
+            && persisted.workflowRules.beforeTaskStart.length === 0
+            && persisted.workflowRules.afterPhaseComplete.length === 0
+            && persisted.decisions.length === 0
+            && [...migratedDecisionIds].every((id) => persistedDecisionIds.has(id));
+        if (!verified) {
+            await atomicWriteJson(this.projectPath(), ProjectSchema.parse(original), this.root);
+            throw new PlanStoreError("Legacy project-context migration failed persisted read-back verification; the original project was restored.");
+        }
+        return { applied: true, preview: expected.preview, project: persisted };
+    }
     /** Persist an explicitly approved work deviation without coupling it to a harness. */
     async addWorkDeviation(deviation) {
         const deviations = [...(await this.loadWorkDeviations()), deviation];
@@ -1938,10 +2074,11 @@ export class PlanStore {
             // Updaters commonly mutate `current` in place, so snapshot descriptions
             // before invoking them rather than comparing object references afterward.
             const previousDescriptions = new Map(current.features.map((feature) => [feature.id, feature.description]));
+            const previousDescriptionRefs = new Map(current.features.map((feature) => [feature.id, feature.descriptionRef]));
             const timestamp = nowISO();
             const candidate = updater(current);
             const stamped = {
-                features: candidate.features.map((feature) => this.stampDescriptionUpdatedAt(feature, previousDescriptions.get(feature.id), timestamp)),
+                features: candidate.features.map((feature) => this.stampDescriptionUpdatedAt(feature, previousDescriptions.get(feature.id), previousDescriptionRefs.get(feature.id), timestamp)),
             };
             const upd = this.normalizeFeaturesDocument(stamped).doc;
             await this.saveFeaturesRaw(upd);
@@ -1955,6 +2092,135 @@ export class PlanStore {
         await this.maybeAutoSync();
         return updated;
     }
+    async ensureIdeasFileForWrite() {
+        try {
+            await access(this.ideasPath());
+        }
+        catch {
+            await atomicWriteJson(this.ideasPath(), IdeasDocumentSchema.parse({ nextIdeaNumber: 1, ideas: [] }), this.root);
+        }
+    }
+    async updateIdeas(updater) {
+        await this.ensureIdeasFileForWrite();
+        const updated = await atomicUpdateJson(this.ideasPath(), IdeasDocumentSchema, (current) => {
+            const candidate = IdeasDocumentSchema.parse(updater(current));
+            const maxNumber = candidate.ideas.reduce((max, idea) => Math.max(max, idea.number), 0);
+            return {
+                ...candidate,
+                nextIdeaNumber: Math.max(candidate.nextIdeaNumber, maxNumber + 1),
+                ideas: [...candidate.ideas].sort((left, right) => left.number - right.number || left.createdAt.localeCompare(right.createdAt)),
+            };
+        }, this.root);
+        await this.touchTimestamp();
+        await this.maybeAutoSync();
+        return updated;
+    }
+    async createIdea(input, timestamp = nowISO()) {
+        const id = createIdeaId();
+        const { number, shortId } = await this.allocateEntityIdentity("idea", id);
+        const idea = IdeaSchema.parse({
+            id,
+            number,
+            shortId,
+            title: input.title.trim(),
+            description: input.description?.trim() ?? "",
+            promotion: null,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+        });
+        await this.updateIdeas((document) => ({
+            nextIdeaNumber: Math.max(document.nextIdeaNumber, number + 1),
+            ideas: [...document.ideas, idea],
+        }));
+        return idea;
+    }
+    async updateIdea(ideaId, input, timestamp = nowISO()) {
+        let updated;
+        await this.updateIdeas((document) => {
+            const existing = document.ideas.find((idea) => idea.id === ideaId);
+            if (!existing)
+                throw new PlanStoreError(`Idea ${ideaId} not found.`);
+            updated = IdeaSchema.parse({
+                ...existing,
+                ...(input.title !== undefined ? { title: input.title.trim() } : {}),
+                ...(input.description !== undefined ? { description: input.description.trim() } : {}),
+                updatedAt: timestamp,
+            });
+            return {
+                ...document,
+                ideas: document.ideas.map((idea) => idea.id === ideaId ? updated : idea),
+            };
+        });
+        return updated;
+    }
+    async deleteIdea(ideaId) {
+        let deleted = false;
+        await this.updateIdeas((document) => {
+            deleted = document.ideas.some((idea) => idea.id === ideaId);
+            return deleted
+                ? { ...document, ideas: document.ideas.filter((idea) => idea.id !== ideaId) }
+                : document;
+        });
+        return deleted;
+    }
+    async resolveIdeaPromotionTarget(targetType, targetId) {
+        const phases = await this.loadAllPhases();
+        const features = (await this.loadFeatures()).features;
+        if (targetType === "feature") {
+            const feature = features.find((candidate) => candidate.id === targetId);
+            if (!feature)
+                throw new PlanStoreError(`Idea promotion target feature ${targetId} not found.`);
+            return formatFeatureRef(feature.number);
+        }
+        if (targetType === "phase") {
+            const phase = phases.find((candidate) => candidate.id === targetId);
+            if (!phase)
+                throw new PlanStoreError(`Idea promotion target phase ${targetId} not found.`);
+            const feature = features.find((candidate) => candidate.id === phase.featureId);
+            return formatPhaseRef(phase.number, feature?.number);
+        }
+        for (const phase of phases) {
+            const task = phase.tasks.find((candidate) => candidate.id === targetId);
+            if (!task)
+                continue;
+            const feature = features.find((candidate) => candidate.id === phase.featureId);
+            return `${formatPhaseRef(phase.number, feature?.number)}/T${formatThreeDigitNumber(task.number)}`;
+        }
+        throw new PlanStoreError(`Idea promotion target task ${targetId} not found.`);
+    }
+    async promoteIdea(ideaId, input) {
+        const targetRef = await this.resolveIdeaPromotionTarget(input.targetType, input.targetId);
+        const promotedAt = input.promotedAt ?? nowISO();
+        let promoted;
+        await this.updateIdeas((document) => {
+            const existing = document.ideas.find((idea) => idea.id === ideaId);
+            if (!existing)
+                throw new PlanStoreError(`Idea ${ideaId} not found.`);
+            if (existing.promotion) {
+                if (existing.promotion.targetType === input.targetType && existing.promotion.targetId === input.targetId) {
+                    promoted = existing;
+                    return document;
+                }
+                throw new PlanStoreError(`Idea ${formatIdeaRef(existing.number)} is already promoted to ${existing.promotion.targetRef}.`);
+            }
+            const promotion = {
+                targetType: input.targetType,
+                targetId: input.targetId,
+                targetRef,
+                promotedAt,
+            };
+            promoted = IdeaSchema.parse({
+                ...existing,
+                promotion,
+                updatedAt: promotedAt,
+            });
+            return {
+                ...document,
+                ideas: document.ideas.map((idea) => idea.id === ideaId ? promoted : idea),
+            };
+        });
+        return promoted;
+    }
     /**
      * Persist completion of one full task → phase → feature → requirements read
      * sequence. Session metadata is deliberately the only changed entity field:
@@ -2039,10 +2305,26 @@ export class PlanStore {
             return { phase, ...(feature ? { feature } : {}), requirements, createdAt };
         });
     }
+    async recordProjectGuidelinesRead(input) {
+        const sessionId = input.sessionId.trim();
+        if (!sessionId)
+            throw new PlanStoreError("Project-guidelines attestation requires a non-empty sessionId.");
+        const createdAt = TimestampSchema.parse(input.createdAt ?? nowISO());
+        const updated = await atomicUpdateJson(this.projectPath(), ProjectSchema, (project) => {
+            if (!project.projectGuidelines.content.trim())
+                return project;
+            const result = upsertSessionInfo(project.projectGuidelines, sessionId, createdAt);
+            return result.changed ? { ...project, projectGuidelines: result.entity } : project;
+        }, this.root);
+        await this.maybeAutoSync();
+        return updated;
+    }
     async saveProject(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: [] });
+        const previous = await readJson(this.projectPath(), ProjectSchema).catch(() => null);
+        const stamped = this.stampProjectGuidelinesUpdatedAt(project, previous?.projectGuidelines.content, nowISO());
+        const parsed = ProjectSchema.parse({ ...stamped, workDeviations: [] });
         await atomicWriteJson(this.projectPath(), parsed, this.root);
         await this.touchTimestamp();
         await this.maybeAutoSync();
@@ -2051,9 +2333,10 @@ export class PlanStore {
         await this.withFeaturesLock(async () => {
             await this.migrateLegacy();
             const previousDescriptions = new Map((await this.loadRawFeatures()).map((feature) => [feature.id, feature.description]));
+            const previousDescriptionRefs = new Map((await this.loadRawFeatures()).map((feature) => [feature.id, feature.descriptionRef]));
             const timestamp = nowISO();
             await this.saveFeaturesRaw({
-                features: features.features.map((feature) => this.stampDescriptionUpdatedAt(feature, previousDescriptions.get(feature.id), timestamp)),
+                features: features.features.map((feature) => this.stampDescriptionUpdatedAt(feature, previousDescriptions.get(feature.id), previousDescriptionRefs.get(feature.id), timestamp)),
             });
         });
         await this.touchTimestamp();
@@ -2089,7 +2372,7 @@ export class PlanStore {
             await this.migrateLegacy();
             const previous = await readJson(this.featurePath(feature.id), FeatureSchema).catch(() => null);
             await mkdir(this.featuresDir(), { recursive: true });
-            const parsed = FeatureSchema.parse(this.stampDescriptionUpdatedAt(feature, previous?.description, nowISO()));
+            const parsed = FeatureSchema.parse(this.stampDescriptionUpdatedAt(feature, previous?.description, previous?.descriptionRef, nowISO()));
             await atomicWriteJson(this.featurePath(parsed.id), parsed, this.root);
         });
         await this.touchTimestamp();
@@ -2100,6 +2383,16 @@ export class PlanStore {
         await atomicWriteJson(this.requirementsPath(), parsed, this.root);
         await this.touchTimestamp();
     }
+    async saveIdeas(ideas) {
+        const parsed = IdeasDocumentSchema.parse(ideas);
+        const maxNumber = parsed.ideas.reduce((max, idea) => Math.max(max, idea.number), 0);
+        await atomicWriteJson(this.ideasPath(), {
+            ...parsed,
+            nextIdeaNumber: Math.max(parsed.nextIdeaNumber, maxNumber + 1),
+            ideas: [...parsed.ideas].sort((left, right) => left.number - right.number || left.createdAt.localeCompare(right.createdAt)),
+        }, this.root);
+        await this.touchTimestamp();
+    }
     async savePhase(phase) {
         const previous = await this.loadPhase(phase.id).catch(() => null);
         const timestamp = nowISO();
@@ -2119,8 +2412,9 @@ export class PlanStore {
             ? { ...phase, featureId: resolvedFeatureId }
             : phase;
         const previousTaskDescriptions = new Map((previous?.tasks ?? []).map((task) => [task.id, task.description]));
-        const timestamped = this.stampDescriptionUpdatedAt(normalizedInput, previous?.description, timestamp);
-        timestamped.tasks = timestamped.tasks.map((task) => this.stampDescriptionUpdatedAt(task, previousTaskDescriptions.get(task.id), timestamp));
+        const previousTaskDescriptionRefs = new Map((previous?.tasks ?? []).map((task) => [task.id, task.descriptionRef]));
+        const timestamped = this.stampDescriptionUpdatedAt(normalizedInput, previous?.description, previous?.descriptionRef, timestamp);
+        timestamped.tasks = timestamped.tasks.map((task) => this.stampDescriptionUpdatedAt(task, previousTaskDescriptions.get(task.id), previousTaskDescriptionRefs.get(task.id), timestamp));
         const parsed = PhaseSchema.parse(this.normalizePhaseDocument(timestamped).phase);
         await mkdir(this.phasesDir(), { recursive: true });
         await atomicWriteJson(this.phasePath(parsed.id), parsed, this.root);
@@ -2140,11 +2434,13 @@ export class PlanStore {
             const current = { ...rawPhase, status: this.derivePhaseStatus(rawPhase.tasks) };
             // The updater may mutate `current`, therefore snapshot descriptions first.
             const previousDescription = current.description;
+            const previousDescriptionRef = current.descriptionRef;
             const previousTaskDescriptions = new Map(current.tasks.map((task) => [task.id, task.description]));
+            const previousTaskDescriptionRefs = new Map(current.tasks.map((task) => [task.id, task.descriptionRef]));
             const timestamp = nowISO();
             const next = updater(current);
-            const timestamped = this.stampDescriptionUpdatedAt(next, previousDescription, timestamp);
-            timestamped.tasks = timestamped.tasks.map((task) => this.stampDescriptionUpdatedAt(task, previousTaskDescriptions.get(task.id), timestamp));
+            const timestamped = this.stampDescriptionUpdatedAt(next, previousDescription, previousDescriptionRef, timestamp);
+            timestamped.tasks = timestamped.tasks.map((task) => this.stampDescriptionUpdatedAt(task, previousTaskDescriptions.get(task.id), previousTaskDescriptionRefs.get(task.id), timestamp));
             const resolvedFeatureId = resolveStoredFeatureId(features, timestamped.featureId);
             // Referential integrity: reject orphan featureId.
             if (timestamped.featureId && timestamped.featureId.trim() && !resolvedFeatureId) {
@@ -2235,6 +2531,36 @@ export class PlanStore {
     async getPhaseHandoff(phaseId) {
         return (await this.loadPhase(phaseId)).handoff;
     }
+    async validateHandoffSupportingDocuments(documents) {
+        const docsRoot = resolve(this.root, "docs");
+        const verified = [];
+        const seen = new Set();
+        for (const document of documents) {
+            const normalizedPath = document.path.trim().replace(/\\/g, "/");
+            if (!/^\.planner\/docs\/.+\.md$/i.test(normalizedPath) || normalizedPath.includes("/../")) {
+                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document path must be a Markdown file under .planner/docs/: ${document.path}`, { path: document.path });
+            }
+            if (seen.has(normalizedPath)) {
+                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document appears more than once: ${normalizedPath}`, { path: normalizedPath });
+            }
+            seen.add(normalizedPath);
+            const target = resolve(this.root, normalizedPath.slice(".planner/".length));
+            if (!target.startsWith(`${docsRoot}${sep}`)) {
+                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document escapes .planner/docs/: ${normalizedPath}`, { path: normalizedPath });
+            }
+            const content = await readFile(target, "utf8").catch(() => null);
+            if (content === null || !content.trim()) {
+                throw new HandoffContractError("HANDOFF_SUPPORTING_DOCUMENT_INVALID", `Supporting document is missing or empty: ${normalizedPath}`, { path: normalizedPath });
+            }
+            verified.push({
+                path: normalizedPath,
+                description: document.description.trim(),
+                contentHash: handoffContentHash(content),
+                contentLength: content.length,
+            });
+        }
+        return verified;
+    }
     /** Audit one exact phase before preparing a handoff refresh. */
     async preparePhaseHandoff(phaseId) {
         const phase = await this.loadPhase(phaseId);
@@ -2259,25 +2585,46 @@ export class PlanStore {
             if (featureIndex < 0)
                 throw new PlanStoreError(`Parent feature ${originalPhase.featureId} not found for phase ${phaseId}.`);
             const timestamp = nowISO();
-            const applied = applyHandoffContextSync(originalPhase, originalFeatures.features[featureIndex], input, timestamp);
-            const nextFeatures = structuredClone(originalFeatures);
-            nextFeatures.features[featureIndex] = applied.feature;
+            const verifiedSupportingDocuments = await this.validateHandoffSupportingDocuments(input.supportingDocuments ?? []);
+            const verifiedInput = { ...input, verifiedSupportingDocuments };
+            const originalFeature = originalFeatures.features[featureIndex];
+            const applied = applyHandoffContextSync(originalPhase, originalFeature, verifiedInput, timestamp);
             try {
-                await this.saveFeatures(nextFeatures);
+                // Keep the transaction granular: only the parent feature and target phase
+                // belong to this handoff refresh. Rewriting the whole feature document can
+                // disturb unrelated feature containment metadata.
+                await this.saveFeature(applied.feature);
                 await this.savePhase(applied.phase);
+                const phase = await this.loadPhase(phaseId);
+                const feature = (await this.loadFeatures()).features.find((candidate) => candidate.id === originalPhase.featureId);
+                const persistedHash = handoffContentHash(phase.handoff);
+                if (phase.handoff !== applied.phase.handoff
+                    || !phase.handoffAudit
+                    || phase.handoffAudit.contentHash !== persistedHash
+                    || phase.handoffAudit.contentLength !== phase.handoff.length) {
+                    throw new HandoffContractError("HANDOFF_PERSISTENCE_VERIFICATION_FAILED", "The persisted handoff did not match the verified content. The write was rolled back.", { expectedHash: applied.phase.handoffAudit?.contentHash ?? "", actualHash: persistedHash });
+                }
+                return {
+                    phase,
+                    feature,
+                    updatedTaskIds: applied.updatedTaskIds,
+                    handoffUpdatedAt: phase.handoffUpdatedAt,
+                    handoffAudit: phase.handoffAudit,
+                };
             }
             catch (error) {
                 const rollbackErrors = [];
-                await this.saveFeatures(originalFeatures).catch((rollbackError) => rollbackErrors.push(rollbackError));
-                await this.savePhase(originalPhase).catch((rollbackError) => rollbackErrors.push(rollbackError));
+                // Restore the exact parsed snapshots directly. Going through saveFeature /
+                // savePhase would restamp description freshness against the failed write.
+                await atomicWriteJson(this.featurePath(originalFeature.id), FeatureSchema.parse(originalFeature), this.root)
+                    .catch((rollbackError) => rollbackErrors.push(rollbackError));
+                await atomicWriteJson(this.phasePath(originalPhase.id), PhaseSchema.parse(originalPhase), this.root)
+                    .catch((rollbackError) => rollbackErrors.push(rollbackError));
                 if (rollbackErrors.length > 0) {
                     throw new AggregateError([error, ...rollbackErrors], "Handoff refresh failed and rollback was incomplete.");
                 }
                 throw error;
             }
-            const phase = await this.loadPhase(phaseId);
-            const feature = (await this.loadFeatures()).features.find((candidate) => candidate.id === originalPhase.featureId);
-            return { phase, feature, updatedTaskIds: applied.updatedTaskIds, handoffUpdatedAt: phase.handoffUpdatedAt };
         });
     }
     /** Set the handoff text for a phase + stamp handoffUpdatedAt. A completed or
@@ -2293,7 +2640,7 @@ export class PlanStore {
             await this.clearPhaseHandoff(phaseId, "superseded");
         }
         const now = new Date().toISOString();
-        await this.updatePhase(phaseId, (current) => ({ ...current, handoff: normalized, handoffUpdatedAt: now }));
+        await this.updatePhase(phaseId, (current) => ({ ...current, handoff: normalized, handoffUpdatedAt: now, handoffAudit: null }));
     }
     /** Mark the phase handoff as read/acknowledged on recap (sets handoffReadAt).
      *  Does NOT clear it: read/load/show are non-mutating resume operations. */
@@ -2384,7 +2731,7 @@ export class PlanStore {
     }
     /** List only active/pending phase handoffs, newest first. Handoffs from
      * phases where every task is done/canceled are archived before returning. */
-    async listHandoffs() {
+    async listHandoffs(options = {}) {
         await this.archiveStaleHandoffs();
         const phases = await this.loadAllPhases();
         const features = await this.loadFeatures();
@@ -2405,7 +2752,11 @@ export class PlanStore {
                 compositeRef: formatPhaseRef(p.number, fnum),
                 updatedAt: p.handoffUpdatedAt || p.updatedAt,
                 firstLine: handoffFirstLine(p.handoff),
-                content: p.handoff,
+                ...(options.includeContent ? { content: p.handoff } : {}),
+                auditVersion: p.handoffAudit?.version ?? null,
+                contentLength: p.handoff.length,
+                contentHash: p.handoffAudit?.contentHash ?? handoffContentHash(p.handoff),
+                verifiedAt: p.handoffAudit?.verifiedAt ?? "",
             });
         }
         out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
@@ -2503,14 +2854,15 @@ export class PlanStore {
         await unlink(join(this.root, ".local", "backups", "phases", `${phaseId}.json.bak`)).catch(() => { });
     }
     // ── Workspace-level operations ─────────────────────────────────────
-    /** Load the full workspace (manifest + phases + project + requirements + features) */
+    /** Load the full workspace, including the rollup-independent Ideas Inbox. */
     async loadWorkspace() {
         const manifest = await this.loadManifest();
         const phases = await this.loadAllPhases();
         const project = await this.loadProject();
         const features = await this.loadFeatures();
         const requirements = await this.loadRequirements();
-        return { manifest, phases, project, features, requirements };
+        const ideas = await this.loadIdeas();
+        return { manifest, phases, project, features, requirements, ideas };
     }
     // ── Markdown generation ────────────────────────────────────────────
     /** Load all data, render markdown, and write into generated/. Skips files