@agent-plan/core 0.2.25 → 0.2.27

package/dist/read-tracking.js

@@ -1,10 +1,10 @@
 /**
- * Session-scoped, ordered context-read enforcement for agent lifecycle operations.
+ * Session-scoped context-read enforcement for agent lifecycle operations.
  *
- * The first complete read for a task must be task(full) → phase(full) →
- * feature(full), with linked requirements read independently. A persisted
- * sessionInfo attestation may satisfy later checks in the same session while
- * the entity's context revision remains at or before its attestation timestamp.
+ * Task/phase/feature reads and linked requirements remain explicit, but fresh
+ * in-session reads may be performed in any order. Persisted sessionInfo
+ * attestations may satisfy later checks while the entity's current revision
+ * remains at or before the attested timestamp.
  */
 const DEFAULT_SESSION_ID = "__default__";
 const newState = () => ({
@@ -51,6 +51,40 @@ export function markFeatureRead(featureId) {
 export function markFeatureReadForSessionId(sessionId, featureId) {
     markFeatureReadForSession(sessionId, featureId);
 }
+function deliveredAcceptedDecisionField(content, value) {
+    const lines = value.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    return lines.every((line) => content.includes(line));
+}
+/**
+ * Record a canonical feature/phase/task full read only after its visible tool
+ * content contains every field of every Accepted Decision. This prevents an
+ * adapter from certifying a title-only or otherwise incomplete decision read.
+ */
+export function markCanonicalFullReadForSessionId(sessionId, kind, entity, deliveredContent) {
+    const acceptedDecisions = entity.acceptedDecisions ?? [];
+    const omitted = [
+        ...(!deliveredContent.includes(`Accepted Decisions (${acceptedDecisions.length}):`) ? ["context-marker"] : []),
+        ...acceptedDecisions.flatMap((acceptedDecision) => [
+            ["id", acceptedDecision.id],
+            ["title", acceptedDecision.title],
+            ["decision", acceptedDecision.decision],
+            ["rationale", acceptedDecision.rationale],
+            ["implementationNotes", acceptedDecision.implementationNotes],
+            ["acceptedAt", acceptedDecision.acceptedAt],
+        ]
+            .filter(([, value]) => !deliveredAcceptedDecisionField(deliveredContent, value))
+            .map(([field]) => `${acceptedDecision.id}.${field}`)),
+    ];
+    if (omitted.length > 0) {
+        throw new Error(`Cannot attest ${kind} ${entity.id} as fully read: omitted Accepted Decision fields: ${omitted.join(", ")}.`);
+    }
+    if (kind === "feature")
+        markFeatureReadForSession(sessionId, entity.id);
+    else if (kind === "phase")
+        markPhaseReadForSession(sessionId, entity.id);
+    else
+        markTaskReadForSession(sessionId, entity.id);
+}
 /** Record a full phase read in the default compatibility session. */
 export function markPhaseRead(phaseId, _featureId) {
     markPhaseReadForSession(DEFAULT_SESSION_ID, phaseId);
@@ -77,19 +111,14 @@ export function markRequirementReadForSessionId(sessionId, requirementId) {
 }
 function orderedEligibility(sessionId, taskId, phaseId, featureId) {
     const state = stateFor(sessionId);
-    const taskSequence = state.tasks.get(taskId);
-    if (taskSequence === undefined) {
+    if (!state.tasks.has(taskId)) {
         return { eligible: false, reason: "Read this exact task with full=true first." };
     }
-    const phaseSequence = state.phases.get(phaseId);
-    if (phaseSequence === undefined || phaseSequence <= taskSequence) {
-        return { eligible: false, reason: "After reading the task, read its parent phase with full=true." };
+    if (!state.phases.has(phaseId)) {
+        return { eligible: false, reason: "Read this task's parent phase with full=true." };
     }
-    if (!featureId)
-        return { eligible: true, reason: "" };
-    const featureSequence = state.features.get(featureId);
-    if (featureSequence === undefined || featureSequence <= phaseSequence) {
-        return { eligible: false, reason: "After reading the phase, read its parent feature with full=true." };
+    if (featureId && !state.features.has(featureId)) {
+        return { eligible: false, reason: "Read this phase's parent feature with full=true." };
     }
     return { eligible: true, reason: "" };
 }
@@ -118,13 +147,14 @@ function persistedEligibility(input) {
 }
 function requiredReadReason(requiredReads) {
     const labels = requiredReads.map((read) => `${read.kind} ${read.id} (${read.state})`);
-    return `Read required context only for: ${labels.join(", ")}. Follow these reads in the listed order, then retry.`;
+    return `Read required context only for: ${labels.join(", ")}. Perform only these reads, in any order within the current session, then retry.`;
 }
 /**
- * Combine valid persisted attestations with fresh in-memory reads. The initial
- * uncached lineage still requires task → phase → feature ordering, while a
- * stale or missing individual entity can be reread without discarding valid
- * parent attestations from the same harness session.
+ * Combine valid persisted attestations with fresh in-memory reads. An entity read
+ * in the current session satisfies eligibility regardless of sequence order,
+ * so agents can read task, phase, and feature in any order; only persisted
+ * attestations are checked for revision freshness (stale) and missing entities
+ * remain reported as missing.
  */
 export function contextReadEligibilityForSession(input) {
     const state = stateFor(input.sessionId);
@@ -137,26 +167,23 @@ export function contextReadEligibilityForSession(input) {
     }
     const phaseStored = storedReadState(input.phase, input.sessionId, "phase");
     const phaseSequence = state.phases.get(input.phaseId);
-    const phaseReadInOrder = phaseSequence !== undefined
-        && (taskStored === "valid" || (taskSequence !== undefined && phaseSequence > taskSequence));
-    const phaseReady = phaseStored === "valid" || phaseReadInOrder;
+    const phaseReady = phaseStored === "valid" || phaseSequence !== undefined;
     if (!phaseReady) {
         requiredReads.push({
             kind: "phase",
             id: input.phaseId,
-            state: phaseStored === "stale" ? "stale" : phaseSequence !== undefined ? "out-of-order" : "missing",
+            state: phaseStored === "stale" ? "stale" : "missing",
         });
     }
     if (input.featureId) {
         const featureStored = storedReadState(input.feature, input.sessionId, "feature");
         const featureSequence = state.features.get(input.featureId);
-        const featureReadInOrder = featureSequence !== undefined
-            && (phaseStored === "valid" || (phaseReadInOrder && phaseSequence !== undefined && featureSequence > phaseSequence));
-        if (featureStored !== "valid" && !featureReadInOrder) {
+        const featureReady = featureStored === "valid" || featureSequence !== undefined;
+        if (!featureReady) {
             requiredReads.push({
                 kind: "feature",
                 id: input.featureId,
-                state: featureStored === "stale" ? "stale" : featureSequence !== undefined ? "out-of-order" : "missing",
+                state: featureStored === "stale" ? "stale" : "missing",
             });
         }
     }
@@ -164,6 +191,19 @@ export function contextReadEligibilityForSession(input) {
         return { eligible: true, reason: "" };
     return { eligible: false, reason: requiredReadReason(requiredReads), requiredReads };
 }
+export function projectGuidelinesReadStateForSession(project, sessionId) {
+    const guidelines = project.projectGuidelines;
+    const content = guidelines?.content?.trim() ?? "";
+    if (!content)
+        return "not-required";
+    const entry = guidelines?.sessionInfo?.find((candidate) => candidate.sessionId === sessionId);
+    if (!entry)
+        return "missing";
+    const updatedAt = guidelines?.updatedAt?.trim() ?? "";
+    if (updatedAt && updatedAt > entry.createdAt)
+        return "stale";
+    return "valid";
+}
 /** Return true only when the persisted attestation covers the current revisions. */
 export function hasValidSessionAttestation(input) {
     return persistedEligibility(input);
@@ -178,12 +218,27 @@ export function hasReadParents(featureId, phaseId) {
     return state.phases.has(phaseId) && (!featureId || state.features.has(featureId));
 }
 /**
- * Whether linked requirements are read in memory or have valid persisted
- * attestations for the current session and entity revisions.
+ * Report the exact linked requirements whose delivered read evidence is missing
+ * or stale for this session. A broad requirement inventory must not call the
+ * mark function; only a target-scoped response that actually includes the
+ * linked requirement records may create fresh in-memory evidence.
  */
-export function hasReadRequirementsForSession(sessionId, requirementIds, requirements = []) {
+export function requirementReadEligibilityForSession(sessionId, requirementIds, requirements = []) {
     const state = stateFor(sessionId);
-    return requirementIds.every((id) => state.requirements.has(id) || validSessionInfo(requirements.find((requirement) => requirement.id === id), sessionId));
+    const requiredReads = [];
+    for (const id of [...new Set(requirementIds)]) {
+        const stored = storedReadState(requirements.find((requirement) => requirement.id === id), sessionId, "requirement");
+        if (state.requirements.has(id) || stored === "valid")
+            continue;
+        requiredReads.push({ kind: "requirement", id, state: stored === "stale" ? "stale" : "missing" });
+    }
+    if (requiredReads.length === 0)
+        return { eligible: true, reason: "" };
+    return { eligible: false, reason: requiredReadReason(requiredReads), requiredReads };
+}
+/** Whether every linked requirement has fresh delivered read evidence. */
+export function hasReadRequirementsForSession(sessionId, requirementIds, requirements = []) {
+    return requirementReadEligibilityForSession(sessionId, requirementIds, requirements).eligible;
 }
 /** Legacy requirement check for the default compatibility session. */
 export function hasReadRequirements(requirementIds) {
@@ -208,7 +263,7 @@ export function parentReadAdvisory(featureId, phaseId) {
     const state = stateFor(DEFAULT_SESSION_ID);
     if (state.phases.has(phaseId) && (!featureId || state.features.has(featureId)))
         return "";
-    return "\n\n⚠️ READ REQUIRED before proceeding: read the parent phase and feature with full=true.";
+    return "\n\n⚠️ READ REQUIRED before proceeding: read only the missing parent phase and feature with full=true.";
 }
 /** Advisory text for the separate linked-requirements gate. */
 export function requirementReadAdvisory(requirementIds) {

package/dist/recap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recap.d.ts","sourceRoot":"","sources":["../src/recap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,KAAK,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,GAAE,YAAiB,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuOhH"}
+{"version":3,"file":"recap.d.ts","sourceRoot":"","sources":["../src/recap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,KAAK,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,GAAE,YAAiB,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4QhH"}

package/dist/recap.js

@@ -1,4 +1,5 @@
 import { formatPhaseRef, formatTwoDigitNumber } from "./naming.js";
+import { buildPhaseWorkMap } from "./task-context.js";
 const fref = (n) => `F${formatTwoDigitNumber(n)}`;
 const tref = (n) => `T${formatTwoDigitNumber(n)}`;
 /**
@@ -32,7 +33,8 @@ export async function buildRecap(st, web = {}, opts = {}) {
     const activeP = phases.filter((x) => x.status === "in-progress" || x.status === "discovery").length;
     const totalT = allTasks.length;
     const doneT = allTasks.filter(({ task }) => task.status === "done").length;
-    const activeT = allTasks.filter(({ task }) => task.status === "in-progress").length;
+    const activeTasks = allTasks.filter(({ task }) => task.status === "in-progress");
+    const activeT = activeTasks.length;
     const checkpointedTasks = allTasks.filter(({ task }) => !["done", "canceled", "rejected"].includes(task.status) && task.pauseSnapshot);
     const checkpointedT = checkpointedTasks.length;
     const pendingDeviation = [...plan.project.workDeviations]
@@ -50,8 +52,9 @@ export async function buildRecap(st, web = {}, opts = {}) {
     // Plan is fully complete: there is work and all of it is done, nothing active.
     // (totalT > 0 guards the empty/unstarted case from looking "complete".)
     const planComplete = totalT > 0 && doneT === totalT && doneP === totalP && doneF === totalF;
-    // Current focus = first in-progress task (and its phase/feature).
-    const focusTask = allTasks.find(({ task }) => task.status === "in-progress");
+    // Current focus is authoritative only when exactly one task is in progress.
+    // Multiple active tasks are an explicit conflict, never a reason to pick the first silently.
+    const focusTask = activeTasks.length === 1 ? activeTasks[0] : undefined;
     const focusPhase = focusTask?.phase;
     const focusFeature = focusPhase ? feats.find((x) => x.id === focusPhase.featureId) : undefined;
     const italian = (plan.project.chatLanguage || "").toLowerCase().includes("ital");
@@ -67,10 +70,20 @@ export async function buildRecap(st, web = {}, opts = {}) {
     lines.push(italian ? "## Ripresa planner" : "## Planner recap");
     const name = plan.project.name || "(unnamed project)";
     lines.push(`${italian ? "Progetto" : "Project"}: ${name}${plan.project.goal ? " — " + plan.project.goal : ""}`);
+    lines.push("", "## Project Guidelines", plan.project.projectGuidelines.content.trim() || "No project guidelines set.");
     lines.push(italian
         ? `Avanzamento: feature ${doneF}/${totalF} completate (${activeF} attive) · fasi ${doneP}/${totalP} completate (${activeP} attive) · task ${doneT}/${totalT} completati (${activeT} attivi, ${checkpointedT} con checkpoint)`
         : `Progress: Features ${doneF}/${totalF} done (${activeF} active) · Phases ${doneP}/${totalP} done (${activeP} active) · Tasks ${doneT}/${totalT} done (${activeT} active, ${checkpointedT} with checkpoints)`);
-    if (focusTask && focusPhase) {
+    if (activeTasks.length > 1) {
+        const conflicts = activeTasks.map(({ phase, task }) => {
+            const feature = feats.find((entry) => entry.id === phase.featureId);
+            return `${formatPhaseRef(phase.number, feature?.number)}/${tref(task.number)} — ${task.title}`;
+        });
+        lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${italian ? "CONFLITTO TASK ATTIVI" : "ACTIVE TASK CONFLICT"} — ${activeTasks.length} ${italian ? "task risultano in-progress" : "tasks are in progress"}: ${conflicts.join("; ")}`, "", italian
+            ? `Esegui ${cmd("task_recommend", "planner-task-recommend")} e riconcilia esplicitamente il conflitto prima di dichiarare un focus.`
+            : `Run ${cmd("task_recommend", "planner-task-recommend")} and explicitly reconcile the conflict before claiming a current focus.`);
+    }
+    else if (focusTask && focusPhase) {
         const fr = focusFeature ? fref(focusFeature.number) : "?";
         const pr = formatPhaseRef(focusPhase.number, focusFeature?.number);
         const tr = tref(focusTask.task.number);
@@ -89,7 +102,7 @@ export async function buildRecap(st, web = {}, opts = {}) {
     }
     else if (handoffs.length > 0) {
         const top = handoffs[0];
-        lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${italian ? "nessun task attivo" : "no active task"} · ${italian ? "handoff pendente più recente" : "most recent pending handoff"}: ${top.compositeRef} — "${top.firstLine}"`);
+        lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${italian ? "nessun task attivo (verificato dagli stati persistiti di tutti i task)" : "no active task (verified from all persisted task statuses)"} · ${italian ? "handoff pendente più recente" : "most recent pending handoff"}: ${top.compositeRef} — "${top.firstLine}" (${top.resumeReady ? "resume-ready" : italian ? "verifica read-back richiesta" : "read-back verification required"})`);
     }
     else if (planComplete) {
         lines.push(italian
@@ -97,7 +110,14 @@ export async function buildRecap(st, web = {}, opts = {}) {
             : "Current focus: plan complete — all features/phases/tasks are done.");
     }
     else {
-        lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${italian ? "nessun task attivo — rivedi il piano e scegli il prossimo task concreto" : "no active task — review the plan and pick the next concrete task"}`);
+        lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${italian ? "nessun task attivo (verificato dagli stati persistiti di tutti i task) — rivedi il piano e scegli il prossimo task concreto" : "no active task (verified from all persisted task statuses) — review the plan and pick the next concrete task"}`);
+    }
+    const orientation = focusTask ?? pendingResume ?? latestStandaloneCheckpoint;
+    if (orientation) {
+        const feature = feats.find((entry) => entry.id === orientation.phase.featureId);
+        lines.push("", buildPhaseWorkMap(orientation.phase, feature?.number, orientation.task.id, 4_000).content, italian
+            ? "Prima di proporre nuovo lavoro, rileggi la fase canonica e il task fratello pertinente: non duplicare capability già assegnate."
+            : "Before proposing new work, reread the canonical phase and the relevant sibling task: do not duplicate an already-owned capability.");
     }
     // Next step: the phase handoff (phase.handoff) is the authoritative,
     // actively-managed resume context. When a handoff is pending, point to it
@@ -119,9 +139,14 @@ export async function buildRecap(st, web = {}, opts = {}) {
             : `Resume advisory: evaluate the newest checkpoint, ${ref}, with ${taskStartCmd} before deciding whether to return to it or start other work.`);
     }
     else if (handoffs.length > 0) {
-        lines.push(italian
-            ? `Prossimo step: leggi l'handoff di fase pendente sotto (fonte autorevole, gestita attivamente). I nextSteps legacy di resume.json sono soppressi perché possono essere stale.`
-            : `Next step: read the pending phase handoff below (authoritative, actively maintained). Legacy resume.json nextSteps are suppressed because they may be stale.`);
+        const unverified = handoffs.filter((handoff) => !handoff.resumeReady);
+        lines.push(unverified.length > 0
+            ? (italian
+                ? `Prossimo step: ${unverified.length} handoff candidato richiede ancora verifica read-back; non trattarlo come completo o autorevole finché handoff_verify non restituisce resumeReady=true.`
+                : `Next step: ${unverified.length} handoff candidate still requires read-back verification; do not treat it as complete or authoritative until ${cmd("handoff_verify", "planner-handoff-verify")} returns resumeReady=true.`)
+            : (italian
+                ? `Prossimo step: leggi l'handoff di fase pendente sotto (fonte autorevole, gestita attivamente). I nextSteps legacy di resume.json sono soppressi perché possono essere stale.`
+                : `Next step: read the pending phase handoff below (authoritative, actively maintained). Legacy resume.json nextSteps are suppressed because they may be stale.`));
     }
     else if (!planComplete && resume?.nextSteps?.length) {
         lines.push(`${italian ? "Prossimo step" : "Next step"}: ${resume.nextSteps[0]}`);

package/dist/refs.d.ts

@@ -11,7 +11,12 @@
  *   - Compos: "P002(F001)"           -> phase.number with parent feature validation
  *   - Title:  exact match, then includes (backward-compat fallback)
  */
-import type { Phase, Feature } from "./schema.js";
+import type { Phase, Feature, Idea } from "./schema.js";
+/**
+ * Resolve an idea by UUID, I00x number, shortId, exact title, then title
+ * inclusion. Ideas are top-level and never require feature/phase context.
+ */
+export declare function findIdeaByRef(ideas: Idea[], ref: string): Idea | undefined;
 /**
  * Resolve a phase reference to a Phase. Returns `undefined` when not found or
  * when a composite (F00x) parent does not match the phase's featureId.

package/dist/refs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAKlD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV,KAAK,GAAG,SAAS,CAgCnB;AACD;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAiBxC,wBAAgB,aAAa,CAC3B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,SAAS,CA2D1C"}
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAMxD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAmB1E;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV,KAAK,GAAG,SAAS,CAgCnB;AACD;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAiBxC,wBAAgB,aAAa,CAC3B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,SAAS,CA2D1C"}

package/dist/refs.js

@@ -1,5 +1,30 @@
 // P00x  or  P00x(F00x)  — accept 1+ digits so "p1" == "p001".
 const PHASE_REF_RE = /^p(\d+)(?:\(f(\d+)\))?$/;
+const IDEA_REF_RE = /^i(\d+)$/;
+/**
+ * Resolve an idea by UUID, I00x number, shortId, exact title, then title
+ * inclusion. Ideas are top-level and never require feature/phase context.
+ */
+export function findIdeaByRef(ideas, ref) {
+    const normalized = ref.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    const byId = ideas.find((idea) => idea.id.toLowerCase() === normalized);
+    if (byId)
+        return byId;
+    const match = normalized.match(IDEA_REF_RE);
+    if (match) {
+        const number = parseInt(match[1], 10);
+        const byNumber = ideas.find((idea) => idea.number === number);
+        if (byNumber)
+            return byNumber;
+    }
+    const byShortId = ideas.find((idea) => idea.shortId.toLowerCase() === normalized);
+    if (byShortId)
+        return byShortId;
+    return ideas.find((idea) => idea.title.toLowerCase() === normalized)
+        ?? ideas.find((idea) => idea.title.toLowerCase().includes(normalized));
+}
 /**
  * Resolve a phase reference to a Phase. Returns `undefined` when not found or
  * when a composite (F00x) parent does not match the phase's featureId.

package/dist/renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,OAAO,EAAE,KAAK,EAAE,aAAa,EAAqB,MAAM,aAAa,CAAC;AAmBtG,qBAAa,YAAY;IACvB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM;IA2KvC,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAIjC,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,gBAAgB;IA6BxB,OAAO,CAAC,eAAe;IA2GvB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM;IAmDxD,mEAAmE;IACnE,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CAejD"}
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,OAAO,EAAQ,KAAK,EAAE,aAAa,EAAqB,MAAM,aAAa,CAAC;AAuB5G,qBAAa,YAAY;IACvB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM;IA+LvC,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAIjC,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,gBAAgB;IA6BxB,OAAO,CAAC,eAAe;IA2GvB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM;IAmDxD,mEAAmE;IACnE,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CAejD"}

package/dist/renderer.js

@@ -11,9 +11,12 @@ function phaseLabel(phase) {
 function taskLabel(task) {
     return `T${seq(task.number)} — ${task.title}`;
 }
+function ideaLabel(idea) {
+    return `I${seq(idea.number)} — ${idea.title}`;
+}
 export class PlanRenderer {
     renderPlan(plan) {
-        const { project, manifest, features, requirements, phases } = plan;
+        const { project, manifest, features, requirements, ideas, phases } = plan;
         const lines = [];
         lines.push(`# ${project.name} — Project Plan`);
         lines.push("");
@@ -72,6 +75,13 @@ export class PlanRenderer {
             lines.push(...renderAcceptedDecisions(project.acceptedDecisions));
             lines.push("");
         }
+        // ── Project Guidelines ──────────────────────────────────────────
+        if (project.projectGuidelines.content.trim()) {
+            lines.push("## Project Guidelines");
+            lines.push("");
+            lines.push(project.projectGuidelines.content.trim());
+            lines.push("");
+        }
         // ── Global Rules ─────────────────────────────────────────────────
         if (project.globalRules.length > 0) {
             lines.push("## Global Rules");
@@ -98,6 +108,19 @@ export class PlanRenderer {
             lines.push(bullet(wr.afterPhaseComplete));
             lines.push("");
         }
+        // ── Ideas Inbox ─────────────────────────────────────────────────
+        if (ideas.ideas.length > 0) {
+            lines.push("---");
+            lines.push("## Ideas Inbox");
+            lines.push("");
+            for (const idea of ideas.ideas) {
+                const promotion = idea.promotion ? ` → ${idea.promotion.targetRef}` : "";
+                lines.push(`- **${ideaLabel(idea)}**${promotion}`);
+                if (idea.description)
+                    lines.push(`  - ${idea.description}`);
+            }
+            lines.push("");
+        }
         // ── Features ────────────────────────────────────────────────────
         if (features.features.length > 0) {
             lines.push("---");
@@ -146,7 +169,6 @@ export class PlanRenderer {
                     lines.push(req.description);
                 }
                 lines.push("");
-                lines.push(`Status: ${statusBadge(req.status)}`);
                 if (req.linkedPhaseIds.length > 0) {
                     lines.push(`Phases: ${req.linkedPhaseIds.map((p) => `\`${p}\``).join(", ")}`);
                 }

package/dist/requirement-macro-tasks.d.ts

@@ -0,0 +1,18 @@
+import type { MacroTask, MacroTaskStatus } from "./schema.js";
+export interface MacroTaskMutationInput {
+    /** Existing persisted ID only. Omit it for a new macro task. */
+    id?: string;
+    title: string;
+    description?: string;
+    status: MacroTaskStatus;
+}
+export declare class RequirementMacroTaskError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reconciles user-authored macro-task fields while retaining all system-owned
+ * identity and timestamp values. The input array order is canonical, so a
+ * successful mutation also performs an explicit reorder atomically.
+ */
+export declare function reconcileRequirementMacroTasks(existing: readonly MacroTask[], inputs: readonly MacroTaskMutationInput[], timestamp: string): MacroTask[];
+//# sourceMappingURL=requirement-macro-tasks.d.ts.map

package/dist/requirement-macro-tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-macro-tasks.d.ts","sourceRoot":"","sources":["../src/requirement-macro-tasks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAM9D,MAAM,WAAW,sBAAsB;IACrC,gEAAgE;IAChE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,eAAe,CAAC;CACzB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAUD;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,SAAS,SAAS,EAAE,EAC9B,MAAM,EAAE,SAAS,sBAAsB,EAAE,EACzC,SAAS,EAAE,MAAM,GAChB,SAAS,EAAE,CA+Bb"}

package/dist/requirement-macro-tasks.js

@@ -0,0 +1,55 @@
+const MACRO_TASK_STATUSES = new Set([
+    "planned", "in-progress", "done", "blocked", "canceled", "rejected", "deferred", "waiting",
+]);
+export class RequirementMacroTaskError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RequirementMacroTaskError";
+    }
+}
+function nextMacroTaskId(used) {
+    for (let number = 1; number <= 999; number += 1) {
+        const candidate = `MT-${String(number).padStart(3, "0")}`;
+        if (!used.has(candidate))
+            return candidate;
+    }
+    throw new RequirementMacroTaskError("A requirement cannot contain more than 999 macro tasks.");
+}
+/**
+ * Reconciles user-authored macro-task fields while retaining all system-owned
+ * identity and timestamp values. The input array order is canonical, so a
+ * successful mutation also performs an explicit reorder atomically.
+ */
+export function reconcileRequirementMacroTasks(existing, inputs, timestamp) {
+    const existingById = new Map(existing.map((task) => [task.id, task]));
+    const usedIds = new Set(existingById.keys());
+    const seenIds = new Set();
+    return inputs.map((input, index) => {
+        const title = input.title.trim();
+        if (!title)
+            throw new RequirementMacroTaskError(`Macro task ${index + 1} requires a title.`);
+        if (!MACRO_TASK_STATUSES.has(input.status)) {
+            throw new RequirementMacroTaskError(`Macro task ${index + 1} has an invalid status: ${input.status}.`);
+        }
+        const requestedId = input.id?.trim();
+        if (requestedId && seenIds.has(requestedId)) {
+            throw new RequirementMacroTaskError(`Macro task ID ${requestedId} appears more than once.`);
+        }
+        if (requestedId)
+            seenIds.add(requestedId);
+        const previous = requestedId ? existingById.get(requestedId) : undefined;
+        if (requestedId && !previous) {
+            throw new RequirementMacroTaskError(`Macro task ID ${requestedId} is not owned by this requirement.`);
+        }
+        const id = previous?.id ?? nextMacroTaskId(usedIds);
+        usedIds.add(id);
+        return {
+            id,
+            title,
+            description: input.description?.trim() ?? "",
+            status: input.status,
+            createdAt: previous?.createdAt ?? timestamp,
+            updatedAt: timestamp,
+        };
+    });
+}

package/dist/runtime-diagnostics.d.ts

@@ -0,0 +1,34 @@
+import type { RuntimePackageVersion } from "./package-version.js";
+export declare const PLAN_SCHEMA_VERSION = 1;
+export declare const ALLOCATION_REGISTRY_VERSION = 1;
+export declare const SUPPORTED_ALLOCATION_KINDS: readonly ["feature", "phase", "task", "idea"];
+export type AllocationKind = typeof SUPPORTED_ALLOCATION_KINDS[number];
+export interface RuntimePackageDiagnostic {
+    name: string;
+    installedVersion: string;
+    loadedVersion: string;
+    runtimeState: "loaded";
+    versionSource: "loaded-package-manifest";
+    packageJsonPath?: string | undefined;
+}
+export interface RuntimeCapabilities {
+    planSchema: {
+        manifestSchemaVersion: typeof PLAN_SCHEMA_VERSION;
+    };
+    allocationRegistry: {
+        version: typeof ALLOCATION_REGISTRY_VERSION;
+        supportedKinds: readonly AllocationKind[];
+    };
+}
+export declare function runtimePackageDiagnostic(pkg: RuntimePackageVersion): RuntimePackageDiagnostic;
+export declare function runtimePackagesDiagnostic(packages: RuntimePackageVersion[]): Record<string, RuntimePackageDiagnostic>;
+export declare function runtimeCapabilities(): RuntimeCapabilities;
+export declare function isSupportedAllocationKind(kind: string): kind is AllocationKind;
+export declare function unsupportedAllocationKindDetails(kind: string): {
+    errorCode: "PLAN_UNSUPPORTED_ALLOCATION_KIND";
+    kind: string;
+    supportedKinds: readonly ["feature", "phase", "task", "idea"];
+    requiredCapability: string;
+    action: string;
+};
+//# sourceMappingURL=runtime-diagnostics.d.ts.map

package/dist/runtime-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-diagnostics.d.ts","sourceRoot":"","sources":["../src/runtime-diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAC7C,eAAO,MAAM,0BAA0B,+CAAgD,CAAC;AAExF,MAAM,MAAM,cAAc,GAAG,OAAO,0BAA0B,CAAC,MAAM,CAAC,CAAC;AAEvE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,QAAQ,CAAC;IACvB,aAAa,EAAE,yBAAyB,CAAC;IACzC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE;QACV,qBAAqB,EAAE,OAAO,mBAAmB,CAAC;KACnD,CAAC;IACF,kBAAkB,EAAE;QAClB,OAAO,EAAE,OAAO,2BAA2B,CAAC;QAC5C,cAAc,EAAE,SAAS,cAAc,EAAE,CAAC;KAC3C,CAAC;CACH;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,qBAAqB,GAAG,wBAAwB,CAS7F;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,qBAAqB,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAErH;AAED,wBAAgB,mBAAmB,IAAI,mBAAmB,CAUzD;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,cAAc,CAE9E;AAED,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM;;;;;;EAQ5D"}

package/dist/runtime-diagnostics.js

@@ -0,0 +1,39 @@
+export const PLAN_SCHEMA_VERSION = 1;
+export const ALLOCATION_REGISTRY_VERSION = 1;
+export const SUPPORTED_ALLOCATION_KINDS = ["feature", "phase", "task", "idea"];
+export function runtimePackageDiagnostic(pkg) {
+    return {
+        name: pkg.name,
+        installedVersion: pkg.version,
+        loadedVersion: pkg.version,
+        runtimeState: "loaded",
+        versionSource: "loaded-package-manifest",
+        ...(pkg.packageJsonPath ? { packageJsonPath: pkg.packageJsonPath } : {}),
+    };
+}
+export function runtimePackagesDiagnostic(packages) {
+    return Object.fromEntries(packages.map((pkg) => [pkg.name, runtimePackageDiagnostic(pkg)]));
+}
+export function runtimeCapabilities() {
+    return {
+        planSchema: {
+            manifestSchemaVersion: PLAN_SCHEMA_VERSION,
+        },
+        allocationRegistry: {
+            version: ALLOCATION_REGISTRY_VERSION,
+            supportedKinds: SUPPORTED_ALLOCATION_KINDS,
+        },
+    };
+}
+export function isSupportedAllocationKind(kind) {
+    return SUPPORTED_ALLOCATION_KINDS.includes(kind);
+}
+export function unsupportedAllocationKindDetails(kind) {
+    return {
+        errorCode: "PLAN_UNSUPPORTED_ALLOCATION_KIND",
+        kind,
+        supportedKinds: SUPPORTED_ALLOCATION_KINDS,
+        requiredCapability: "allocationRegistry.supportedKinds",
+        action: "Upgrade all Agent Plan packages and reload the harness so the loaded runtime supports this allocation kind before retrying the mutation.",
+    };
+}