@agent-plan/core 0.2.24 → 0.2.26

package/dist/planner-rules.d.ts

@@ -1,13 +1,3 @@
-/**
- * Canonical planner extension rules — the agent-behavior contract that applies
- * to EVERY project using the Agent Plan extension (Pi, MCP / Claude Code / Codex,
- * future harnesses). These are STATIC: no timestamps, no dynamic content, so the
- * same text seeds every .planner/ and never diverges across worktrees or
- * branches (no conflict from date/timestamp changes).
- *
- * AGENTS.md governs ONLY the development of the agent-plan extension and must
- * not duplicate these rules.
- */
 export declare const PLANNER_EXTENSION_RULES: string[];
 export interface ExtensionRulesFile {
     extensionRules: string[];
@@ -15,7 +5,9 @@ export interface ExtensionRulesFile {
 /**
  * Load the effective extension rules for a planner root. Returns the project's
  * own .planner/rules.json (static, user-overridable) when present and non-empty,
- * otherwise the canonical code set. Never returns timestamps or dynamic data.
+ * otherwise the canonical code set. Exact legacy canonical read-protocol rules
+ * are upgraded in memory without rewriting the project file; unrelated project
+ * overrides remain untouched. Never returns timestamps or dynamic data.
  */
 export declare function loadExtensionRules(plannerRoot: string): Promise<string[]>;
 //# sourceMappingURL=planner-rules.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"planner-rules.d.ts","sourceRoot":"","sources":["../src/planner-rules.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,EA2B3C,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAW/E"}
+{"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,6 +10,10 @@ 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 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 = [
     // §1 — source of truth
     "Keep the planner as the single operational source of truth while working: read the relevant planner state before starting; update it when an activity starts, changes state, blocks, or concludes; and record next steps, blockers, and decisions in the relevant planner entities. Never leave work only in the conversation.",
@@ -17,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
@@ -31,24 +37,35 @@ export const PLANNER_EXTENSION_RULES = [
     "Handoff is per-phase (phase.handoff), not a file. Write it only on explicit user request and only after the exact feature+phase target is confirmed. Run handoff_prepare for that phase, reconcile all still-relevant existing content into one active handoff, and synchronize durable task/phase/feature context in the same handoff_write operation. A pending handoff never blocks task_start and is archived only when the phase completes or the user explicitly clears it; refreshing it must not create superseded copies.",
     // §12 — operational hygiene
     "Operational hygiene: start the task (task_start) before thinking about implementation; complete it (task_complete) as part of delivering the deliverable, not after; motivate every block so a third party can understand the impediment.",
-    // Avvio del planner
+    // Planner startup
     "The planner and Web UI never start automatically. Do not start the Web UI or show its URL unless the user runs load/recap/web-status. The Web UI URL appears only in the recap after load, or on explicit web status.",
-    // Regola dettagli
-    "Write relevant points (decisions, constraints, current state, file:line refs, edge cases) into the task/phase/feature description or notes as soon as they emerge. 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.",
+    // Detail-writing rule
+    DETAIL_WRITING_RULE,
     // Expected operational behavior
-    "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.",
+    EXPECTED_OPERATIONAL_RULE,
 ];
+function normalizeLegacyRules(rules) {
+    return rules.map((rule) => {
+        if (rule === LEGACY_DETAIL_WRITING_RULE)
+            return DETAIL_WRITING_RULE;
+        if (rule === LEGACY_EXPECTED_OPERATIONAL_RULE)
+            return EXPECTED_OPERATIONAL_RULE;
+        return rule;
+    });
+}
 /**
  * Load the effective extension rules for a planner root. Returns the project's
  * own .planner/rules.json (static, user-overridable) when present and non-empty,
- * otherwise the canonical code set. Never returns timestamps or dynamic data.
+ * otherwise the canonical code set. Exact legacy canonical read-protocol rules
+ * are upgraded in memory without rewriting the project file; unrelated project
+ * overrides remain untouched. Never returns timestamps or dynamic data.
  */
 export async function loadExtensionRules(plannerRoot) {
     try {
         const raw = await readFile(join(plannerRoot, "rules.json"), "utf8");
         const parsed = JSON.parse(raw);
         if (Array.isArray(parsed.extensionRules) && parsed.extensionRules.length > 0) {
-            return parsed.extensionRules.filter((r) => typeof r === "string" && r.length > 0);
+            return normalizeLegacyRules(parsed.extensionRules.filter((r) => typeof r === "string" && r.length > 0));
         }
     }
     catch {

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
- * 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.
  */
 type SessionInfoEntry = {
     sessionId: string;
@@ -12,11 +12,26 @@ type SessionInfoEntry = {
 };
 type ReadTrackedEntity = {
     updatedAt: string;
+    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";
+};
 export type ContextReadEligibility = {
     eligible: boolean;
     reason: string;
+    requiredReads?: RequiredContextRead[];
 };
 export interface SessionContextReadInput {
     sessionId: string;
@@ -48,11 +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;
 /**
- * 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 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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"}