@agent-plan/core 0.2.24 → 0.2.26

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
- * every entity's updatedAt 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 = () => ({
@@ -77,53 +77,98 @@ 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: "" };
 }
-function validSessionInfo(entity, sessionId) {
+function entityRevision(entity, kind) {
+    if ((kind === "phase" || kind === "feature") && entity.descriptionUpdatedAt?.trim()) {
+        return entity.descriptionUpdatedAt;
+    }
+    return entity.updatedAt;
+}
+function storedReadState(entity, sessionId, kind) {
     const entry = entity?.sessionInfo?.find((candidate) => candidate.sessionId === sessionId);
-    return Boolean(entity && entry && entity.updatedAt <= entry.createdAt);
+    if (!entity || !entry)
+        return "missing";
+    return entityRevision(entity, kind) <= entry.createdAt ? "valid" : "stale";
+}
+function validSessionInfo(entity, sessionId, kind = "requirement") {
+    return storedReadState(entity, sessionId, kind) === "valid";
 }
 function persistedEligibility(input) {
-    if (!validSessionInfo(input.task, input.sessionId) || !validSessionInfo(input.phase, input.sessionId))
+    if (!validSessionInfo(input.task, input.sessionId, "task") || !validSessionInfo(input.phase, input.sessionId, "phase"))
         return false;
-    if (input.featureId && !validSessionInfo(input.feature, input.sessionId))
+    if (input.featureId && !validSessionInfo(input.feature, input.sessionId, "feature"))
         return false;
     const requirementIds = input.requirementIds ?? [];
     return requirementIds.every((id) => validSessionInfo(input.requirements?.find((requirement) => requirement.id === id), input.sessionId));
 }
-function hasStoredSessionAttestation(input) {
-    const entities = [input.task, input.phase, input.feature, ...(input.requirements ?? [])];
-    return entities.some((entity) => entity?.sessionInfo?.some((entry) => entry.sessionId === input.sessionId));
+function requiredReadReason(requiredReads) {
+    const labels = requiredReads.map((read) => `${read.kind} ${read.id} (${read.state})`);
+    return `Read required context only for: ${labels.join(", ")}. Perform only these reads, in any order within the current session, then retry.`;
 }
 /**
- * Evaluate exact in-memory read ordering first, then a persisted attestation
- * for the same session and current entity revisions. A previously persisted
- * but now stale attestation always wins over stale in-memory ordering.
+ * 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 ordered = orderedEligibility(input.sessionId, input.taskId, input.phaseId, input.featureId);
-    if (ordered.eligible)
-        return ordered;
-    if (input.task && input.phase && persistedEligibility(input))
-        return { eligible: true, reason: "" };
-    if (input.task && input.phase && hasStoredSessionAttestation(input)) {
-        return { eligible: false, reason: "Context changed since the last session read; reread the exact task, phase, feature, and linked requirements." };
+    const state = stateFor(input.sessionId);
+    const requiredReads = [];
+    const taskStored = storedReadState(input.task, input.sessionId, "task");
+    const taskSequence = state.tasks.get(input.taskId);
+    const taskReady = taskStored === "valid" || taskSequence !== undefined;
+    if (!taskReady) {
+        requiredReads.push({ kind: "task", id: input.taskId, state: taskStored === "stale" ? "stale" : "missing" });
+    }
+    const phaseStored = storedReadState(input.phase, input.sessionId, "phase");
+    const phaseSequence = state.phases.get(input.phaseId);
+    const phaseReady = phaseStored === "valid" || phaseSequence !== undefined;
+    if (!phaseReady) {
+        requiredReads.push({
+            kind: "phase",
+            id: input.phaseId,
+            state: phaseStored === "stale" ? "stale" : "missing",
+        });
     }
-    return ordered;
+    if (input.featureId) {
+        const featureStored = storedReadState(input.feature, input.sessionId, "feature");
+        const featureSequence = state.features.get(input.featureId);
+        const featureReady = featureStored === "valid" || featureSequence !== undefined;
+        if (!featureReady) {
+            requiredReads.push({
+                kind: "feature",
+                id: input.featureId,
+                state: featureStored === "stale" ? "stale" : "missing",
+            });
+        }
+    }
+    if (requiredReads.length === 0)
+        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) {
@@ -169,7 +214,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,CA4OhH"}
+{"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,CA6OhH"}

package/dist/recap.js

@@ -63,13 +63,11 @@ export async function buildRecap(st, web = {}, opts = {}) {
     const featureAddCmd = cmd("/planner feature add", "planner-feature-add");
     const phaseAddCmd = cmd("/planner phase add", "planner-phase-add");
     const handoffShowCmd = cmd("/planner handoff show", "planner-handoff-show");
-    const featureShowCmd = cmd("/planner feature show", "planner-feature-show");
-    const phaseShowCmd = cmd("/planner phase show", "planner-phase-show");
-    const taskShowCmd = cmd("/planner task show", "planner-task-show");
     const lines = [];
     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)`);
@@ -78,9 +76,7 @@ export async function buildRecap(st, web = {}, opts = {}) {
         const pr = formatPhaseRef(focusPhase.number, focusFeature?.number);
         const tr = tref(focusTask.task.number);
         lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${fr} — ${focusFeature?.name ?? "?"} / ${pr} — ${focusPhase.title} / ${tr} — ${focusTask.task.title} (in-progress)`);
-        lines.push("", italian
-            ? `Questo task è in-progress (lavoro iniziato in una sessione precedente). Prima di continuare, rileggi il contesto completo: ${taskShowCmd} ${tr} (full=true), ${phaseShowCmd} ${pr} (full=true), ${featureShowCmd} ${fr} (full=true).`
-            : `⚠️ This task is in-progress (work started in a previous session). Before continuing, re-read the full context in this order: ${taskShowCmd} ${tr} (full=true), ${phaseShowCmd} ${pr} (full=true), ${featureShowCmd} ${fr} (full=true).`);
+        lines.push("", `Continue with ${taskStartCmd} ${tr}. If context reads are required, follow only the missing or stale reads in its nextActions, then retry.`);
     }
     else if (pendingResume) {
         const feature = feats.find((entry) => entry.id === pendingResume.phase.featureId);

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;IAgMvC,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("---");

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

@@ -0,0 +1,18 @@
+import type { MacroTask, RequirementStatus } from "./schema.js";
+export interface MacroTaskMutationInput {
+    /** Existing persisted ID only. Omit it for a new macro task. */
+    id?: string;
+    title: string;
+    description?: string;
+    status: RequirementStatus;
+}
+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,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAMhE,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,iBAAiB,CAAC;CAC3B;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 REQUIREMENT_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 (!REQUIREMENT_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,
+        };
+    });
+}