@agent-plan/core 0.2.25 → 0.2.26

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

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

package/dist/planner-rules.js

@@ -10,8 +10,8 @@ import { join } from "node:path";
  * AGENTS.md governs ONLY the development of the agent-plan extension and must
  * not duplicate these rules.
  */
-const DETAIL_WRITING_RULE = "Write relevant points (decisions, constraints, current state, file:line refs, edge cases) into the task/phase/feature description or notes as soon as they emerge. For starting, resuming, or switching, call the lifecycle tool first so valid session attestations can be reused. If it denies the operation, perform only the missing or stale full reads listed in nextActions, in that exact order, then retry; read linked requirements explicitly only when requested. Cite entities with composite IDs, not bare UUIDs.";
-const EXPECTED_OPERATIONAL_RULE = "When you begin work, task_start and task_switch enforce session-scoped context reads and return precise missing/stale read actions when needed. Read any relevant phase handoff as additional context, then update the planner before and after significant changes. If you change an architectural decision, document it explicitly.";
+const DETAIL_WRITING_RULE = "Write relevant points (decisions, constraints, current state, file:line refs, edge cases) into the task/phase/feature description or notes as soon as they emerge. For starting, resuming, or switching, call the lifecycle tool first so valid session attestations can be reused. If it denies the operation, perform only the missing or stale full reads listed in nextActions, in any order within the current session, then retry; read linked requirements explicitly only when requested. Cite entities with composite IDs, not bare UUIDs.";
+const EXPECTED_OPERATIONAL_RULE = "When you begin work, task_start and task_switch enforce session-scoped context reads plus a Project Guidelines read when that project section exists and is missing or stale for the current session. Read any relevant phase handoff as additional context, then update the planner before and after significant changes. If you change an architectural decision, document it explicitly.";
 const LEGACY_DETAIL_WRITING_RULE = "Write relevant points (decisions, constraints, current state, file:line refs, edge cases) into the task/phase/feature description or notes as soon as they emerge. Before starting, resuming, or switching to a task, read task_get(full=true), then its parent phase_get(full=true), then its parent feature_get(full=true), in that exact order; read linked requirements explicitly when present. Cite entities with composite IDs, not bare UUIDs.";
 const LEGACY_EXPECTED_OPERATIONAL_RULE = "When you begin work, task_start and task_switch enforce the required ordered full reads. Read any relevant phase handoff as additional context, then update the planner before and after significant changes. If you change an architectural decision, document it explicitly.";
 export const PLANNER_EXTENSION_RULES = [
@@ -21,6 +21,8 @@ export const PLANNER_EXTENSION_RULES = [
     "Respect the task lifecycle strictly. Always call task_start before touching code, and task_complete with durable evidence of shipped work, verification (including partial verification), remaining/unverified work, files, and decisions when a deliverable is done. Never enter in-progress or done through task_update. Sync state changes (start/complete/block) to the planner at the exact moment they happen — never batch updates at session end. If task_start is denied, the task remains planned: satisfy the stated read prerequisites and retry, and never claim work started without an explicit successful start result. A task marked in-progress means you are actually working on it; if you stop, close or block it with a motivation in statusLog. Derived feature/phase status is computed from tasks, not stored in JSON.",
     // §3 — markdown not source of truth
     "Do not treat markdown as the source of truth for the plan. The plan's primary source is structured data in .planner/; markdown is a generated, human/agent-readable view.",
+    // §4 — project guidelines
+    "When a project defines the canonical Project Guidelines section, read it on planner load and before starting or switching task work whenever the current-session attestation is missing or stale. Keep coding standards, formatting, styling, and other project-specific rules from that section in working memory while executing the task.",
     // §5 — plan location
     "The plan lives in .planner/ within the target project. Whether .planner/ is git-tracked is at the project's discretion.",
     // §6 — discuss per phase

package/dist/planner-skill.d.ts

@@ -0,0 +1,24 @@
+export type PlannerSkillSyncStatus = "created" | "current" | "updated" | "customized";
+export interface PlannerSkillSyncResult {
+    path: string;
+    status: PlannerSkillSyncStatus;
+    content: string;
+    canonicalHash: string;
+    customized: boolean;
+    message: string;
+}
+export declare function plannerSkillHash(content: string): string;
+export declare function renderManagedPlannerSkill(content: string): string;
+export declare function managedPlannerSkillBody(content: string): string;
+export declare function loadCanonicalPlannerSkill(): Promise<string>;
+export declare function loadCanonicalGrillMeSkill(): Promise<string>;
+/** Create or safely refresh `.planner/SKILL.md`. */
+export declare function syncProjectPlannerSkill(plannerRoot: string): Promise<PlannerSkillSyncResult>;
+/** Create or safely refresh `.planner/skills/grill-me/SKILL.md`. */
+export declare function syncProjectGrillMeSkill(plannerRoot: string): Promise<PlannerSkillSyncResult>;
+/**
+ * Load the project-local Ideas discussion skill, safely creating/upgrading the
+ * managed copy first. Customized project copies are returned unchanged.
+ */
+export declare function loadProjectGrillMeSkill(plannerRoot: string): Promise<string>;
+//# sourceMappingURL=planner-skill.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner-skill.d.ts","sourceRoot":"","sources":["../src/planner-skill.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,YAAY,CAAC;AAEtF,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,sBAAsB,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGjE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,MAAM,CAAC,CAEjE;AAED,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,MAAM,CAAC,CAEjE;AAyED,oDAAoD;AACpD,wBAAsB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAYlG;AAED,oEAAoE;AACpE,wBAAsB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAYlG;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAElF"}

package/dist/planner-skill.js

@@ -0,0 +1,113 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const MANAGED_SKILL_HEADER = /^<!-- agent-plan-managed-skill sha256:([a-f0-9]{64}) -->\n/;
+const CANONICAL_SKILL_URL = new URL("../planner-skill.md", import.meta.url);
+const CANONICAL_GRILL_ME_SKILL_URL = new URL("../skills/grill-me/SKILL.md", import.meta.url);
+function normalizeSkillContent(content) {
+    return `${content.replace(/\r\n/g, "\n").trimEnd()}\n`;
+}
+export function plannerSkillHash(content) {
+    return createHash("sha256").update(normalizeSkillContent(content), "utf8").digest("hex");
+}
+export function renderManagedPlannerSkill(content) {
+    const normalized = normalizeSkillContent(content);
+    return `<!-- agent-plan-managed-skill sha256:${plannerSkillHash(normalized)} -->\n${normalized}`;
+}
+export function managedPlannerSkillBody(content) {
+    return normalizeSkillContent(content.replace(MANAGED_SKILL_HEADER, ""));
+}
+export async function loadCanonicalPlannerSkill() {
+    return normalizeSkillContent(await readFile(CANONICAL_SKILL_URL, "utf8"));
+}
+export async function loadCanonicalGrillMeSkill() {
+    return normalizeSkillContent(await readFile(CANONICAL_GRILL_ME_SKILL_URL, "utf8"));
+}
+async function syncManagedProjectSkill(path, canonical, messages) {
+    const canonicalHash = plannerSkillHash(canonical);
+    const managedCanonical = renderManagedPlannerSkill(canonical);
+    const existing = await readFile(path, "utf8").catch(() => null);
+    if (existing == null) {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, managedCanonical, "utf8");
+        return {
+            path,
+            status: "created",
+            content: canonical,
+            canonicalHash,
+            customized: false,
+            message: messages.created,
+        };
+    }
+    if (normalizeSkillContent(existing) === normalizeSkillContent(managedCanonical)) {
+        return {
+            path,
+            status: "current",
+            content: canonical,
+            canonicalHash,
+            customized: false,
+            message: messages.current,
+        };
+    }
+    // Adopt an exact unmarked canonical copy. This supports projects that copied
+    // a canonical skill before managed headers were introduced.
+    if (!MANAGED_SKILL_HEADER.test(existing) && normalizeSkillContent(existing) === canonical) {
+        await writeFile(path, managedCanonical, "utf8");
+        return {
+            path,
+            status: "updated",
+            content: canonical,
+            canonicalHash,
+            customized: false,
+            message: messages.adopted,
+        };
+    }
+    const marker = existing.match(MANAGED_SKILL_HEADER);
+    const existingBody = managedPlannerSkillBody(existing);
+    if (marker && plannerSkillHash(existingBody) === marker[1]) {
+        await writeFile(path, managedCanonical, "utf8");
+        return {
+            path,
+            status: "updated",
+            content: canonical,
+            canonicalHash,
+            customized: false,
+            message: messages.updated,
+        };
+    }
+    return {
+        path,
+        status: "customized",
+        content: existingBody,
+        canonicalHash,
+        customized: true,
+        message: messages.customized,
+    };
+}
+/** Create or safely refresh `.planner/SKILL.md`. */
+export async function syncProjectPlannerSkill(plannerRoot) {
+    return syncManagedProjectSkill(join(plannerRoot, "SKILL.md"), await loadCanonicalPlannerSkill(), {
+        created: "Created the canonical project-local planner skill.",
+        current: "The project-local planner skill matches the canonical version.",
+        adopted: "Adopted and marked the unmodified canonical planner skill.",
+        updated: "Updated the unmodified project-local planner skill to the current canonical version.",
+        customized: "Preserved the customized .planner/SKILL.md. Reconcile it manually with the current canonical Agent Plan guide; Agent Plan did not overwrite project instructions.",
+    });
+}
+/** Create or safely refresh `.planner/skills/grill-me/SKILL.md`. */
+export async function syncProjectGrillMeSkill(plannerRoot) {
+    return syncManagedProjectSkill(join(plannerRoot, "skills", "grill-me", "SKILL.md"), await loadCanonicalGrillMeSkill(), {
+        created: "Created the canonical project-local grill-me skill for Ideas discussions.",
+        current: "The project-local grill-me skill matches the canonical version.",
+        adopted: "Adopted and marked the unmodified canonical grill-me skill.",
+        updated: "Updated the unmodified project-local grill-me skill to the current canonical version.",
+        customized: "Preserved the customized .planner/skills/grill-me/SKILL.md. Reconcile it manually with the current canonical Agent Plan skill; Agent Plan did not overwrite project instructions.",
+    });
+}
+/**
+ * Load the project-local Ideas discussion skill, safely creating/upgrading the
+ * managed copy first. Customized project copies are returned unchanged.
+ */
+export async function loadProjectGrillMeSkill(plannerRoot) {
+    return (await syncProjectGrillMeSkill(plannerRoot)).content;
+}

package/dist/project-context-migration.d.ts

@@ -0,0 +1,47 @@
+import type { AcceptedDecision, Project } from "./schema.js";
+export declare const LEGACY_PROJECT_CONTEXT_MIGRATION_VERSION = 1;
+export type LegacyGuidelineSource = "global-rules" | "before-phase-start" | "before-task-start" | "after-phase-complete";
+export interface LegacyGuidelineAddition {
+    source: LegacyGuidelineSource;
+    text: string;
+}
+export type LegacyDecisionAddition = Omit<AcceptedDecision, "acceptedAt">;
+export interface LegacyProjectContextMigrationPreview {
+    version: number;
+    hasLegacyContext: boolean;
+    guidelinesChanged: boolean;
+    acceptedDecisionsChanged: boolean;
+    guidelineAdditions: LegacyGuidelineAddition[];
+    acceptedDecisionAdditions: LegacyDecisionAddition[];
+    skippedGuidelineDuplicates: number;
+    skippedDecisionDuplicates: number;
+    resultingGuidelinesContent: string;
+    legacyCounts: {
+        globalRules: number;
+        workflowRules: number;
+        decisions: number;
+    };
+    fieldsClearedOnApply: Array<"globalRules" | "workflowRules" | "decisions">;
+}
+export interface LegacyProjectContextMigrationResult {
+    applied: boolean;
+    preview: LegacyProjectContextMigrationPreview;
+    project: Project;
+}
+export interface PlannerSessionPreparationResult {
+    changed: boolean;
+    project: Project;
+    legacyProjectContext: {
+        migrated: boolean;
+        version: number;
+        guidelinesAdded: number;
+        acceptedDecisionsAdded: number;
+        duplicatesSkipped: number;
+        clearedFields: Array<"globalRules" | "workflowRules" | "decisions">;
+        summary: string;
+    };
+}
+export declare function plannerSessionPreparationResult(result: LegacyProjectContextMigrationResult): PlannerSessionPreparationResult;
+export declare function previewLegacyProjectContextMigration(project: Project): LegacyProjectContextMigrationPreview;
+export declare function applyLegacyProjectContextMigration(project: Project, acceptedAt: string): LegacyProjectContextMigrationResult;
+//# sourceMappingURL=project-context-migration.d.ts.map

package/dist/project-context-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-context-migration.d.ts","sourceRoot":"","sources":["../src/project-context-migration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAiB,MAAM,aAAa,CAAC;AAE5E,eAAO,MAAM,wCAAwC,IAAI,CAAC;AAE1D,MAAM,MAAM,qBAAqB,GAC7B,cAAc,GACd,oBAAoB,GACpB,mBAAmB,GACnB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;AAE1E,MAAM,WAAW,oCAAoC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,wBAAwB,EAAE,OAAO,CAAC;IAClC,kBAAkB,EAAE,uBAAuB,EAAE,CAAC;IAC9C,yBAAyB,EAAE,sBAAsB,EAAE,CAAC;IACpD,0BAA0B,EAAE,MAAM,CAAC;IACnC,yBAAyB,EAAE,MAAM,CAAC;IAClC,0BAA0B,EAAE,MAAM,CAAC;IACnC,YAAY,EAAE;QACZ,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,oBAAoB,EAAE,KAAK,CAAC,aAAa,GAAG,eAAe,GAAG,WAAW,CAAC,CAAC;CAC5E;AAED,MAAM,WAAW,mCAAmC;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,oCAAoC,CAAC;IAC9C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB,EAAE;QACpB,QAAQ,EAAE,OAAO,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,eAAe,EAAE,MAAM,CAAC;QACxB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,KAAK,CAAC,aAAa,GAAG,eAAe,GAAG,WAAW,CAAC,CAAC;QACpE,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,mCAAmC,GAC1C,+BAA+B,CAoBjC;AA0DD,wBAAgB,oCAAoC,CAAC,OAAO,EAAE,OAAO,GAAG,oCAAoC,CAiE3G;AAED,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,MAAM,GACjB,mCAAmC,CA0BrC"}

package/dist/project-context-migration.js

@@ -0,0 +1,168 @@
+import { createHash } from "node:crypto";
+export const LEGACY_PROJECT_CONTEXT_MIGRATION_VERSION = 1;
+export function plannerSessionPreparationResult(result) {
+    const guidelinesAdded = result.preview.guidelineAdditions.length;
+    const acceptedDecisionsAdded = result.preview.acceptedDecisionAdditions.length;
+    const duplicatesSkipped = result.preview.skippedGuidelineDuplicates + result.preview.skippedDecisionDuplicates;
+    const summary = result.applied
+        ? `Migrated legacy project context: ${guidelinesAdded} guideline${guidelinesAdded === 1 ? "" : "s"}, ${acceptedDecisionsAdded} accepted decision${acceptedDecisionsAdded === 1 ? "" : "s"}, ${duplicatesSkipped} duplicate${duplicatesSkipped === 1 ? "" : "s"} skipped.`
+        : "Legacy project context is already canonical; no migration was needed.";
+    return {
+        changed: result.applied,
+        project: result.project,
+        legacyProjectContext: {
+            migrated: result.applied,
+            version: result.preview.version,
+            guidelinesAdded,
+            acceptedDecisionsAdded,
+            duplicatesSkipped,
+            clearedFields: result.preview.fieldsClearedOnApply,
+            summary,
+        },
+    };
+}
+const SOURCE_LABELS = {
+    "global-rules": "Global rules",
+    "before-phase-start": "Before phase start",
+    "before-task-start": "Before task start",
+    "after-phase-complete": "After phase complete",
+};
+function normalizeComparable(value) {
+    return value
+        .trim()
+        .replace(/^[\s#>*+-]+/, "")
+        .replace(/\s+/g, " ")
+        .toLocaleLowerCase("en-US");
+}
+function guidelineKeys(content) {
+    return new Set(content
+        .split(/\r?\n/)
+        .map(normalizeComparable)
+        .filter(Boolean));
+}
+function workflowEntries(workflowRules) {
+    return [
+        ...workflowRules.beforePhaseStart.map((text) => ({ source: "before-phase-start", text })),
+        ...workflowRules.beforeTaskStart.map((text) => ({ source: "before-task-start", text })),
+        ...workflowRules.afterPhaseComplete.map((text) => ({ source: "after-phase-complete", text })),
+    ];
+}
+function renderGuidelineAdditions(existing, additions) {
+    if (additions.length === 0)
+        return existing.trim();
+    const lines = ["## Migrated legacy project rules", ""];
+    for (const source of Object.keys(SOURCE_LABELS)) {
+        const entries = additions.filter((entry) => entry.source === source);
+        if (entries.length === 0)
+            continue;
+        lines.push(`### ${SOURCE_LABELS[source]}`, ...entries.map((entry) => `- ${entry.text}`), "");
+    }
+    const rendered = lines.join("\n").trim();
+    return existing.trim() ? `${existing.trim()}\n\n${rendered}` : rendered;
+}
+function decisionKey(value) {
+    if (typeof value === "string")
+        return normalizeComparable(value);
+    return normalizeComparable(value.decision || value.title);
+}
+function legacyDecisionId(decision) {
+    return `legacy-project-decision-${createHash("sha256").update(decisionKey(decision), "utf8").digest("hex").slice(0, 16)}`;
+}
+function legacyDecisionTitle(decision) {
+    const firstLine = decision.trim().split(/\r?\n/, 1)[0] ?? decision.trim();
+    return firstLine.length <= 100 ? firstLine : `${firstLine.slice(0, 97).trimEnd()}...`;
+}
+export function previewLegacyProjectContextMigration(project) {
+    const legacyGuidelines = [
+        ...project.globalRules.map((text) => ({ source: "global-rules", text })),
+        ...workflowEntries(project.workflowRules),
+    ];
+    const existingGuidelines = guidelineKeys(project.projectGuidelines.content);
+    const seenGuidelines = new Set(existingGuidelines);
+    const guidelineAdditions = [];
+    let skippedGuidelineDuplicates = 0;
+    for (const entry of legacyGuidelines) {
+        const text = entry.text.trim();
+        const key = normalizeComparable(text);
+        if (!key || seenGuidelines.has(key)) {
+            skippedGuidelineDuplicates += 1;
+            continue;
+        }
+        seenGuidelines.add(key);
+        guidelineAdditions.push({ ...entry, text });
+    }
+    const seenDecisions = new Set(project.acceptedDecisions.map(decisionKey));
+    const acceptedDecisionAdditions = [];
+    let skippedDecisionDuplicates = 0;
+    for (const legacyDecision of project.decisions) {
+        const decision = legacyDecision.trim();
+        const key = decisionKey(decision);
+        if (!key || seenDecisions.has(key)) {
+            skippedDecisionDuplicates += 1;
+            continue;
+        }
+        seenDecisions.add(key);
+        acceptedDecisionAdditions.push({
+            id: legacyDecisionId(decision),
+            title: legacyDecisionTitle(decision),
+            decision,
+            rationale: "Migrated from the legacy project decisions collection.",
+            implementationNotes: "Review and enrich this structured decision when additional rationale or implementation detail is available.",
+        });
+    }
+    const workflowRuleCount = project.workflowRules.beforePhaseStart.length
+        + project.workflowRules.beforeTaskStart.length
+        + project.workflowRules.afterPhaseComplete.length;
+    const fieldsClearedOnApply = [];
+    if (project.globalRules.length > 0)
+        fieldsClearedOnApply.push("globalRules");
+    if (workflowRuleCount > 0)
+        fieldsClearedOnApply.push("workflowRules");
+    if (project.decisions.length > 0)
+        fieldsClearedOnApply.push("decisions");
+    return {
+        version: LEGACY_PROJECT_CONTEXT_MIGRATION_VERSION,
+        hasLegacyContext: fieldsClearedOnApply.length > 0,
+        guidelinesChanged: guidelineAdditions.length > 0,
+        acceptedDecisionsChanged: acceptedDecisionAdditions.length > 0,
+        guidelineAdditions,
+        acceptedDecisionAdditions,
+        skippedGuidelineDuplicates,
+        skippedDecisionDuplicates,
+        resultingGuidelinesContent: renderGuidelineAdditions(project.projectGuidelines.content, guidelineAdditions),
+        legacyCounts: {
+            globalRules: project.globalRules.length,
+            workflowRules: workflowRuleCount,
+            decisions: project.decisions.length,
+        },
+        fieldsClearedOnApply,
+    };
+}
+export function applyLegacyProjectContextMigration(project, acceptedAt) {
+    const preview = previewLegacyProjectContextMigration(project);
+    if (!preview.hasLegacyContext)
+        return { applied: false, preview, project };
+    const acceptedDecisions = [
+        ...project.acceptedDecisions,
+        ...preview.acceptedDecisionAdditions.map((decision) => ({ ...decision, acceptedAt })),
+    ];
+    return {
+        applied: true,
+        preview,
+        project: {
+            ...project,
+            projectGuidelines: {
+                ...project.projectGuidelines,
+                content: preview.resultingGuidelinesContent,
+            },
+            globalRules: [],
+            workflowRules: {
+                beforePhaseStart: [],
+                beforeTaskStart: [],
+                afterPhaseComplete: [],
+            },
+            decisions: [],
+            acceptedDecisions,
+        },
+    };
+}

package/dist/read-tracking.d.ts

@@ -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.
  */
 type SessionInfoEntry = {
     sessionId: string;
@@ -15,11 +15,18 @@ type ReadTrackedEntity = {
     descriptionUpdatedAt?: string;
     sessionInfo?: SessionInfoEntry[];
 };
+type ProjectGuidelinesTrackedProject = {
+    projectGuidelines?: {
+        content?: string;
+        updatedAt?: string;
+        sessionInfo?: SessionInfoEntry[];
+    };
+};
 export type ContextReadEntityKind = "task" | "phase" | "feature";
 export type RequiredContextRead = {
     kind: ContextReadEntityKind;
     id: string;
-    state: "missing" | "stale" | "out-of-order";
+    state: "missing" | "stale";
 };
 export type ContextReadEligibility = {
     eligible: boolean;
@@ -56,12 +63,15 @@ export declare function markRequirementRead(requirementId: string): void;
 /** Record that a requirement was explicitly read for an explicit session. */
 export declare function markRequirementReadForSessionId(sessionId: string, requirementId: string): void;
 /**
- * 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 declare function contextReadEligibilityForSession(input: SessionContextReadInput): ContextReadEligibility;
+export type ProjectGuidelinesReadState = "not-required" | "missing" | "stale" | "valid";
+export declare function projectGuidelinesReadStateForSession(project: ProjectGuidelinesTrackedProject, sessionId: string): ProjectGuidelinesReadState;
 /** Return true only when the persisted attestation covers the current revisions. */
 export declare function hasValidSessionAttestation(input: SessionContextReadInput): boolean;
 /** Compatibility check for the default session and in-memory reads only. */

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

@@ -1 +1 @@
-{"version":3,"file":"read-tracking.d.ts","sourceRoot":"","sources":["../src/read-tracking.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"read-tracking.d.ts","sourceRoot":"","sources":["../src/read-tracking.ts"],"names":[],"mappings":"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"}

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 = () => ({
@@ -77,19 +77,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 +113,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 +133,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 +157,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);
@@ -208,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,CAuOhH"}
+{"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

@@ -67,6 +67,7 @@ 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)`);

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"}