agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/cli/planArtifacts.js

@@ -0,0 +1,350 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML, { isMap, isScalar, isSeq } from "yaml";
+import { loadYamlMapping } from "../core/yaml.js";
+import { resolvePlanIdentity } from "../state/planIdentity.js";
+import { asList, firstPresent } from "./stateQuery.js";
+/** The immutable filenames produced by the typed plan archive writer. */
+const PLAN_ARCHIVE_FILE = /^PLAN-.+\.ya?ml$/i;
+const COMPLETE_TASK_STATUSES = new Set(["complete", "completed", "closed", "done", "resolved", "retired"]);
+function isMapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeLegacyStatus(status) {
+    if (status === "active")
+        return "open";
+    if (status === "completed")
+        return "complete";
+    return status;
+}
+function planStatus(data) {
+    const header = isMapping(data.header) ? data.header : {};
+    return String(firstPresent(header, ["status"], "") || "");
+}
+function hasYamlMetadata(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const node = value;
+    return node.anchor !== undefined || node.tag !== undefined;
+}
+function hasSafeRange(value, textLength) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const range = value.range;
+    if (!Array.isArray(range) || range.length < 2 || range.some((offset) => !Number.isInteger(offset)))
+        return false;
+    return range[0] >= 0 && range[0] <= range[1] && range[1] <= textLength &&
+        (range[2] === undefined || (range[1] <= range[2] && range[2] <= textLength));
+}
+function hasPlainSequenceItemPrefix(text, itemStart) {
+    const lineStart = text.lastIndexOf("\n", itemStart - 1) + 1;
+    return /^[ \t]*-[ \t]+$/.test(text.slice(lineStart, itemStart));
+}
+function blockScopeItemSources(text) {
+    const sources = new Map();
+    const document = YAML.parseDocument(text);
+    if (!isMap(document.contents))
+        return sources;
+    const scope = document.contents.get("scope", true);
+    if (!isMap(scope))
+        return sources;
+    for (const field of ["included", "excluded", "deferred"]) {
+        const sequence = scope.get(field, true);
+        if (!isSeq(sequence))
+            continue;
+        sequence.items.forEach((item, index) => {
+            if (!isMap(item) || item.flow === true || item.items.length !== 1)
+                return;
+            const [pair] = item.items;
+            const { key, value } = pair;
+            if (!isScalar(key) || !isScalar(value) || typeof key.value !== "string" || typeof value.value !== "string")
+                return;
+            if ([item, pair, key, value].some(hasYamlMetadata))
+                return;
+            if (!hasSafeRange(item, text.length) || !hasSafeRange(key, text.length) || !hasSafeRange(value, text.length))
+                return;
+            if (key.range[0] < item.range[0] || key.range[1] > item.range[1] || value.range[0] < item.range[0] || value.range[1] > item.range[1])
+                return;
+            if (!hasPlainSequenceItemPrefix(text, item.range[0]))
+                return;
+            const sourceText = text.slice(item.range[0], item.range[1]).trimEnd();
+            if (sourceText.includes("\n") || sourceText.includes("\r"))
+                return;
+            sources.set(`${field}:${index}`, {
+                source_form: "block_single_pair_mapping",
+                source_context: `scope.${field}_sequence_item`,
+                source_text: sourceText,
+                normalized: `${key.value}: ${value.value}`,
+            });
+        });
+    }
+    return sources;
+}
+function normalizePlanDocument(data, archived, blockScopeItems) {
+    const header = isMapping(data.header) ? data.header : {};
+    const status = planStatus(data);
+    const sourceTasks = (Array.isArray(data.entries) ? data.entries : data.tasks);
+    const incomplete = sourceTasks.some((task) => !taskIsComplete(task));
+    const normalizedStatus = normalizeLegacyStatus(status) === "complete" && incomplete ? "open" : normalizeLegacyStatus(status);
+    const taskNormalizations = [];
+    const tasks = sourceTasks.map((source, index) => {
+        const task = structuredClone(source);
+        const legacy = typeof task.id === "string" ? /^T([1-9][0-9]*)$/.exec(task.id) : null;
+        const taskNormalization = { index };
+        if (legacy && task.number === undefined) {
+            task.number = Number(legacy[1]);
+            delete task.id;
+            if (task.name === undefined && typeof task.title === "string") {
+                task.name = task.title;
+                delete task.title;
+            }
+            Object.assign(taskNormalization, { source_id: source.id, source_title: source.title, normalized_number: task.number, normalized_name: task.name });
+        }
+        const normalizedLists = ["depends_on", "acceptance"].filter((field) => source[field] === undefined || source[field] === null || typeof source[field] === "string");
+        if (normalizedLists.length) {
+            for (const field of normalizedLists)
+                task[field] = typeof source[field] === "string" && source[field] !== "" ? [source[field]] : [];
+            taskNormalization.normalized_list_fields = normalizedLists;
+            taskNormalization.source_list_forms = Object.fromEntries(normalizedLists.map((field) => [field, source[field] === undefined ? "absent" : source[field] === null ? "null" : source[field] === "" ? "empty_scalar" : "scalar"]));
+        }
+        if (Array.isArray(task.acceptance)) {
+            const acceptanceItems = [];
+            task.acceptance = task.acceptance.map((item, acceptanceIndex) => {
+                if (!isMapping(item))
+                    return item;
+                const pairs = Object.entries(item);
+                if (pairs.length !== 1 || typeof pairs[0][1] !== "string")
+                    return item;
+                const normalized = `${pairs[0][0]}: ${pairs[0][1]}`;
+                acceptanceItems.push({ index: acceptanceIndex, source_mapping: item, normalized });
+                return normalized;
+            });
+            if (acceptanceItems.length)
+                taskNormalization.acceptance_mapping_items = acceptanceItems;
+        }
+        if (task.status === "completed") {
+            task.status = "complete";
+            taskNormalization.status = { original: "completed", normalized: "complete" };
+        }
+        if (Object.keys(taskNormalization).length > 1)
+            taskNormalizations.push(taskNormalization);
+        if (Array.isArray(task.depends_on))
+            task.depends_on = task.depends_on.map((dependency) => { const match = /^Task ([1-9][0-9]*)$/.exec(String(dependency)); return match ? match[1] : dependency; });
+        return task;
+    });
+    const normalizedData = { ...data, header: { ...header, status: normalizedStatus }, ...(Array.isArray(data.entries) ? { entries: tasks } : { tasks }) };
+    const changes = {};
+    if (status !== normalizedStatus)
+        changes.lifecycle = { original_status: status, normalized_status: normalizedStatus, rule: incomplete ? "completed_with_incomplete_tasks_to_open" : "legacy_status" };
+    if (data.scope === undefined || data.scope === null || data.scope === "") {
+        normalizedData.scope = { included: [], excluded: [] };
+        changes.scope = { source_form: data.scope === undefined ? "absent" : data.scope === null ? "null" : "empty_scalar", normalized: "explicit_empty_lists" };
+    }
+    else if (isMapping(data.scope)) {
+        const scope = structuredClone(data.scope);
+        const itemNormalizations = [];
+        for (const field of ["included", "excluded", "deferred"]) {
+            if (!Array.isArray(scope[field]))
+                continue;
+            scope[field] = scope[field].map((item, index) => {
+                if (Array.isArray(item) && item.length === 1 && typeof item[0] === "string") {
+                    itemNormalizations.push({ field, index, source_form: "singleton_sequence", source: item, normalized: item[0] });
+                    return item[0];
+                }
+                if (isMapping(item)) {
+                    const pairs = Object.entries(item);
+                    const source = blockScopeItems.get(`${field}:${index}`);
+                    if (pairs.length === 1 && typeof pairs[0][1] === "string" && source?.normalized === `${pairs[0][0]}: ${pairs[0][1]}`) {
+                        const normalized = source.normalized;
+                        itemNormalizations.push({ field, index, ...source, source: item });
+                        return normalized;
+                    }
+                }
+                return item;
+            });
+        }
+        normalizedData.scope = scope;
+        if (itemNormalizations.length)
+            changes.scope_list_items = itemNormalizations;
+    }
+    if (taskNormalizations.length)
+        changes.tasks = taskNormalizations;
+    return { data: normalizedData, ...(Object.keys(changes).length ? { provenance: { kind: "legacy_plan_normalization", archived, ...changes } } : {}) };
+}
+/**
+ * A plan archive is valid only when it retains the task list (including an
+ * intentionally empty list). This keeps unrelated YAML and malformed plan
+ * names from replacing a valid archive during discovery.
+ */
+function isPlanDocument(value) {
+    if (!isMapping(value) || !isMapping(value.header))
+        return false;
+    const entries = Array.isArray(value.entries) ? value.entries : value.tasks;
+    return Array.isArray(entries) && entries.every(isMapping);
+}
+function taskIsComplete(task) {
+    return COMPLETE_TASK_STATUSES.has(String(task.status ?? "").toLowerCase());
+}
+function inspectionDiagnostic(path, category, message) {
+    return { path, category, message };
+}
+function inspectPlanArtifact(artifactPath, archived, bytes) {
+    let data;
+    let sourceText;
+    try {
+        sourceText = bytes !== undefined ? bytes.toString("utf8") : fs.readFileSync(artifactPath, "utf8");
+        data = loadYamlMapping(sourceText);
+    }
+    catch (error) {
+        const message = error.message;
+        const category = message === "YAML root must be a mapping" ? "schema" : "parse";
+        return { artifact: null, diagnostics: [inspectionDiagnostic(artifactPath, category, message)] };
+    }
+    if (!isPlanDocument(data)) {
+        return {
+            artifact: null,
+            diagnostics: [
+                inspectionDiagnostic(artifactPath, "schema", "plan requires a header mapping and a tasks or entries array of task mappings"),
+            ],
+        };
+    }
+    const status = planStatus(data);
+    if (!["open", "complete", "active", "completed"].includes(status)) {
+        return {
+            artifact: null,
+            diagnostics: [
+                inspectionDiagnostic(artifactPath, "lifecycle", `plan header.status must be open or complete; received ${status || "missing"}`),
+            ],
+        };
+    }
+    const diagnostics = [];
+    if (status === "active" || status === "completed") {
+        diagnostics.push(inspectionDiagnostic(artifactPath, "legacy", `legacy plan status ${status} normalized to ${normalizeLegacyStatus(status)}`));
+    }
+    const sourceTasks = (Array.isArray(data.entries) ? data.entries : data.tasks);
+    if (normalizeLegacyStatus(status) === "complete" && sourceTasks.some((task) => !taskIsComplete(task))) {
+        diagnostics.push(inspectionDiagnostic(artifactPath, "legacy", "completed plan with incomplete tasks normalized to open"));
+    }
+    if (Array.isArray(data.entries)) {
+        diagnostics.push(inspectionDiagnostic(artifactPath, "legacy", "legacy entries task shape is read compatibly"));
+    }
+    const normalized = normalizePlanDocument(data, archived, blockScopeItemSources(sourceText));
+    return { artifact: { path: artifactPath, data: normalized.data, archived, ...(normalized.provenance ? { migrationProvenance: normalized.provenance } : {}) }, diagnostics };
+}
+export function planDocumentParts(data) {
+    const legacyEntries = Array.isArray(data.entries);
+    const header = isMapping(data.header) ? data.header : {};
+    const rawTasks = legacyEntries ? asList(data.entries) : asList(data.tasks);
+    const tasks = rawTasks.filter((task) => isMapping(task));
+    return {
+        header,
+        tasks,
+        status: normalizeLegacyStatus(String(firstPresent(header, ["status"], "") || "")),
+        title: String(firstPresent(header, ["title"], data.title ?? "") || ""),
+        created: String(firstPresent(header, ["created"], data.created ?? "") || ""),
+        legacyEntries,
+    };
+}
+/**
+ * Discover the active plan and typed-writer archives. The active path is
+ * schema-resolved; its sibling `archive/` directory is the writer-owned
+ * history location. Callers with inspected sources can pin active and archive
+ * bytes, or pass null to exclude an unsafe active path without following it.
+ */
+export function discoverPlanArtifacts(activePath, options) {
+    const archiveDirectory = path.join(path.dirname(activePath), "archive");
+    const activeInspection = options
+        ? options.activeBytes === null
+            ? { artifact: null, diagnostics: [] }
+            : inspectPlanArtifact(activePath, false, options.activeBytes)
+        : fs.existsSync(activePath)
+            ? inspectPlanArtifact(activePath, false)
+            : { artifact: null, diagnostics: [] };
+    const active = activeInspection.artifact;
+    const archived = [];
+    const invalidArchivePaths = [];
+    const diagnostics = [...activeInspection.diagnostics];
+    let archiveSources = [];
+    if (options?.archiveBytes) {
+        archiveSources = [...options.archiveBytes.entries()]
+            .filter(([archivePath]) => path.dirname(archivePath) === archiveDirectory && PLAN_ARCHIVE_FILE.test(path.basename(archivePath)))
+            .sort(([left], [right]) => left.localeCompare(right));
+    }
+    else {
+        let names = [];
+        try {
+            names = fs.readdirSync(archiveDirectory);
+        }
+        catch {
+            // A missing archive directory is the normal state before the first archive.
+        }
+        archiveSources = names
+            .filter((candidate) => PLAN_ARCHIVE_FILE.test(candidate))
+            .sort()
+            .flatMap((name) => {
+            const archivePath = path.join(archiveDirectory, name);
+            try {
+                return fs.statSync(archivePath).isFile() ? [[archivePath, undefined]] : [];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    for (const [archivePath, bytes] of archiveSources) {
+        const inspection = inspectPlanArtifact(archivePath, true, bytes);
+        diagnostics.push(...inspection.diagnostics);
+        if (inspection.artifact)
+            archived.push(inspection.artifact);
+        else
+            invalidArchivePaths.push(archivePath);
+    }
+    // Lifecycle migration updates bytes and therefore mtimes. Persisted creation
+    // dates, followed by the immutable path, keep historical order stable.
+    archived.sort((a, b) => {
+        const createdDelta = planDocumentParts(b.data).created.localeCompare(planDocumentParts(a.data).created);
+        return createdDelta === 0 ? b.path.localeCompare(a.path) : createdDelta;
+    });
+    const artifacts = [...(active ? [active] : []), ...archived];
+    const resolved = artifacts.flatMap((artifact) => {
+        try {
+            return [{ artifact, ...resolvePlanIdentity(artifact.data) }];
+        }
+        catch (error) {
+            diagnostics.push(inspectionDiagnostic(artifact.path, "identity", error.message));
+            return [];
+        }
+    });
+    const identities = resolved.map((identity) => {
+        const matching = resolved.filter((candidate) => candidate.stableId === identity.stableId);
+        const provenancePaths = matching.map((candidate) => candidate.artifact.path).sort();
+        const ambiguous = new Set(matching.map((candidate) => candidate.canonicalJson)).size > 1;
+        if (ambiguous) {
+            diagnostics.push(inspectionDiagnostic(identity.artifact.path, "identity", `plan identity ${identity.stableId} is ambiguous across ${provenancePaths.join(", ")}`));
+        }
+        return { ...identity, ambiguous, provenancePaths };
+    });
+    return { activePath, archiveDirectory, active, archived, invalidArchivePaths, diagnostics, identities };
+}
+export function planCatalogEntry(artifact, activePath, identity) {
+    const parts = planDocumentParts(artifact.data);
+    const active = artifact.path === activePath;
+    return {
+        path: artifact.path,
+        ...(identity ? { stable_id: identity.stableId } : {}),
+        addressable: identity ? !identity.ambiguous : false,
+        active,
+        archived: !active,
+        title: parts.title,
+        status: parts.status,
+        created: parts.created,
+        task_count: parts.tasks.length,
+        compatibility: identity?.ambiguous ? "degraded" : identity?.persisted ? "complete" : "degraded",
+        provenance: {
+            storage: active ? "active_plan_file" : "immutable_plan_archive",
+            path: artifact.path,
+            lifecycle_position: active ? "active" : "archived",
+            ...(identity && identity.provenancePaths.length > 1 ? { mirrored_paths: identity.provenancePaths } : {}),
+        },
+    };
+}

package/dist/cli/planEvidence.js

@@ -0,0 +1,157 @@
+import { artifactPath } from "./appContext.js";
+import { asList, loadArtifact } from "./stateQuery.js";
+/**
+ * These phrases are the stable progress-to-task joins for the completed
+ * lifecycle plan. They intentionally match task-specific progress language,
+ * rather than every cycle that happens to mention a shared runtime concept.
+ */
+const LIFECYCLE_PROGRESS_MATCHES = {
+    "1": "canonical runtime lifecycle projection for task 1",
+    "2": "defined default preview and explicit apply semantics",
+    "3": "task 3 ownership-safe repair",
+    "4": "drove project integration from the canonical runtime lifecycle projection",
+    "5": "surface bounded lifecycle attention rows",
+    "6": "verified runtime lifecycle selectors, ownership safety, preview purity",
+    "7": "verified task 7 consumer and distribution parity",
+    "8": "synchronized packages/cli/package.json dev.17",
+};
+function isMapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasRecordedEvidence(value) {
+    if (Array.isArray(value))
+        return value.some((item) => hasRecordedEvidence(item));
+    if (value !== null && typeof value === "object")
+        return Object.keys(value).length > 0;
+    return value !== null && value !== undefined && String(value).trim().length > 0;
+}
+function cycleNumber(value) {
+    if (typeof value === "number" && Number.isInteger(value))
+        return value;
+    if (typeof value === "string" && value.trim())
+        return /^\d+$/.test(value.trim()) ? Number(value) : value.trim();
+    return null;
+}
+function progressEvidenceRecords(schemas) {
+    const info = schemas.progress;
+    if (!info)
+        return [];
+    const progressPath = artifactPath(info, "progress");
+    const data = loadArtifact(progressPath);
+    if (!isMapping(data))
+        return [];
+    const records = [];
+    for (const raw of asList(data.cycles)) {
+        if (!isMapping(raw))
+            continue;
+        const number = cycleNumber(raw.number);
+        const what = String(raw.what ?? "").trim();
+        if (number === null || !what)
+            continue;
+        const verified = String(raw.verified ?? "").trim();
+        records.push({
+            cycleNumber: number,
+            artifactPath: progressPath,
+            field: verified ? "verified" : "what",
+            detail: verified || what,
+            matchText: what.toLowerCase(),
+        });
+    }
+    for (const raw of asList(data.archive)) {
+        if (!isMapping(raw))
+            continue;
+        const summary = String(raw.summary ?? "").trim();
+        const match = /^Cycle\s+(\d+)\b/i.exec(summary);
+        if (!match || !summary)
+            continue;
+        records.push({
+            cycleNumber: Number(match[1]),
+            artifactPath: progressPath,
+            field: "summary",
+            detail: summary,
+            matchText: summary.toLowerCase(),
+        });
+    }
+    return records;
+}
+function progressMatch(task, records) {
+    const number = String(task.number ?? "");
+    const phrase = LIFECYCLE_PROGRESS_MATCHES[number];
+    if (!phrase)
+        return null;
+    const matches = records
+        .filter((record) => record.matchText.includes(phrase))
+        .sort((a, b) => {
+        const aNumber = typeof a.cycleNumber === "number" ? a.cycleNumber : Number.MAX_SAFE_INTEGER;
+        const bNumber = typeof b.cycleNumber === "number" ? b.cycleNumber : Number.MAX_SAFE_INTEGER;
+        return aNumber - bNumber || a.detail.localeCompare(b.detail);
+    });
+    return matches.length > 0 ? { record: matches[0], phrase } : null;
+}
+function supportsLifecycleProgressJoin(artifact) {
+    const header = isMapping(artifact.data.header) ? artifact.data.header : {};
+    const title = String(header.title ?? artifact.data.title ?? "").toLowerCase();
+    return title.includes("runtime lifecycle");
+}
+function progressProvenance(match, task) {
+    return {
+        source_family: "progress",
+        source_kind: match.record.field === "summary" ? "typed_writer_archive" : "typed_writer_cycle",
+        artifact_path: match.record.artifactPath,
+        cycle_number: match.record.cycleNumber,
+        field: match.record.field,
+        task_number: task.number ?? null,
+        deterministic_match: match.phrase,
+        detail: match.record.detail,
+    };
+}
+function planProvenance(planPath, task) {
+    return {
+        source_family: "plan",
+        source_kind: "immutable_archive",
+        artifact_path: planPath,
+        field: `tasks[${String(task.number ?? "?")}].evidence`,
+        task_number: task.number ?? null,
+    };
+}
+/**
+ * Project evidence into the read-only state response. Existing plan evidence
+ * remains intact; missing evidence is resolved only through a deterministic
+ * join to typed progress cycles or compacted writer summaries.
+ */
+export function resolvePlanTaskEvidence(artifact, tasks, schemas) {
+    const records = supportsLifecycleProgressJoin(artifact) ? progressEvidenceRecords(schemas) : [];
+    const sources = new Set();
+    let complete = true;
+    const resolved = tasks.map((task) => {
+        const stored = hasRecordedEvidence(task.evidence);
+        const match = stored ? null : progressMatch(task, records);
+        const provenance = [];
+        let evidence = task.evidence;
+        if (stored) {
+            provenance.push(planProvenance(artifact.path, task));
+            sources.add("plan");
+        }
+        else if (match) {
+            evidence = [{
+                    source: "progress",
+                    cycle_number: match.record.cycleNumber,
+                    field: match.record.field,
+                    detail: match.record.detail,
+                }];
+            provenance.push(progressProvenance(match, task));
+            sources.add("progress");
+        }
+        else {
+            evidence = [];
+            complete = false;
+        }
+        return {
+            ...task,
+            evidence,
+            evidence_status: hasRecordedEvidence(evidence) ? "present" : "missing",
+            evidence_provenance: provenance,
+        };
+    });
+    return { tasks: resolved, complete, sources: [...sources].sort() };
+}

package/dist/cli/planLifecycleState.js

@@ -0,0 +1,36 @@
+import { entityListFamily } from "../state/entityRetrievalHelp.js";
+import { sourceProvenance } from "./capabilityContext/shared.js";
+import { asList } from "./stateQuery.js";
+import { preCutoverCommand } from "./preCutoverCommand.js";
+const PLAN_LIST_COMMAND = preCutoverCommand(`state ${entityListFamily("plans").commandTokens.join(" ")} list --format json`);
+function diagnosticEntries(value) {
+    return asList(value).filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)));
+}
+/** Shared lifecycle health projection for status and plan-consuming capabilities. */
+export function planLifecycleState(plan) {
+    const diagnostics = diagnosticEntries(plan.diagnostics);
+    const degradedDiagnostics = diagnostics.filter((diagnostic) => diagnostic.category !== "legacy");
+    const exists = Boolean(plan.exists);
+    const active = plan.active === true;
+    const activePath = typeof plan.active_path === "string" ? plan.active_path : null;
+    const currentDiagnostics = activePath
+        ? degradedDiagnostics.filter((diagnostic) => diagnostic.path === activePath)
+        : degradedDiagnostics;
+    const currentPlanDegraded = currentDiagnostics.length > 0;
+    const status = degradedDiagnostics.length > 0 ? "degraded" : !exists ? "unavailable" : active ? "available" : "history_only";
+    return {
+        status,
+        diagnostic_count: degradedDiagnostics.length,
+        diagnostics: degradedDiagnostics,
+        current_plan_degraded: currentPlanDegraded,
+        execution_eligible: active && !currentPlanDegraded,
+        source_provenance: sourceProvenance("plan", PLAN_LIST_COMMAND, "source.diagnostics"),
+        caveats: status === "degraded"
+            ? [
+                currentPlanDegraded
+                    ? "Current plan lifecycle data is degraded; executable plan work is withheld until it is repaired."
+                    : "Historical plan lifecycle data is degraded; archived plans remain non-executable.",
+            ]
+            : [],
+    };
+}

package/dist/cli/planTaskIndex.js

@@ -0,0 +1,11 @@
+const indexes = new WeakMap();
+/** Retain the complete canonical task graph for in-process capability projections. */
+export function rememberPlanTaskIndex(plan, tasks) {
+    indexes.set(plan, tasks);
+}
+/** Public plan projections remain bounded; orchestration reads this exact internal graph. */
+export function planTaskIndex(plan) {
+    return indexes.get(plan) ?? (Array.isArray(plan.tasks)
+        ? plan.tasks.filter((task) => Boolean(task) && typeof task === "object" && !Array.isArray(task))
+        : []);
+}

package/dist/cli/preCutoverCommand.js

@@ -0,0 +1,32 @@
+import { CANONICAL_DEVELOPMENT_CLI } from "../core/developmentChannel.js";
+export const PRE_CUTOVER_CLI = CANONICAL_DEVELOPMENT_CLI;
+export function assertPreCutoverCommand(command) {
+    if (!command.startsWith(`${PRE_CUTOVER_CLI} `) || command.includes("agentera@latest")) {
+        throw new Error(`pre-cutover v3 command must use ${PRE_CUTOVER_CLI}: ${command}`);
+    }
+    return command;
+}
+export function preCutoverCommand(argumentsText) {
+    if (!argumentsText.trim() || /(?:^|\s)(?:npx|agentera(?:@\S+)?)(?:\s|$)/.test(argumentsText)) {
+        throw new Error(`pre-cutover command arguments must not select an executable or channel: ${argumentsText}`);
+    }
+    return assertPreCutoverCommand(`${PRE_CUTOVER_CLI} ${argumentsText}`);
+}
+export function preCutoverCommandFromBare(command) {
+    if (!command.startsWith("agentera ")) {
+        throw new Error(`expected a bare Agentera command before pre-cutover channel binding: ${command}`);
+    }
+    return preCutoverCommand(command.slice("agentera ".length));
+}
+const BARE_V3_COMMAND = /(?<![\w@-])agentera (?=(?:prime|doctor|upgrade|route|state|schema|check|report)\b)/g;
+/** Bind every executable Agentera command in a pre-cutover instruction body. */
+export function preCutoverInstructionBody(body) {
+    if (/\bagentera@latest\b/.test(body) || /\bnpx\s+(?:-y\s+)?agentera\s/.test(body)) {
+        throw new Error(`pre-cutover instruction body selects a bare or stable Agentera executable`);
+    }
+    const bound = body.replace(BARE_V3_COMMAND, `${PRE_CUTOVER_CLI} `);
+    if (BARE_V3_COMMAND.test(bound)) {
+        throw new Error(`pre-cutover instruction body retains a bare Agentera command`);
+    }
+    return bound;
+}

package/dist/cli/prime-blob.js

@@ -1,3 +1,71 @@
-// AUTO-PORTED from scripts/agentera PRIME_BLOB. Byte-exact.
-export const PRIME_BLOB = "# agentera priming guide\n\n## Routing: agentera vs native tools\n\nUse top-level `agentera <state>` commands for routine questions about project state.\nUse native tools (read, grep, glob, edit, bash) for source code operations.\n\nagentera queries return compact answers from structured state. Do NOT read\nraw YAML artifacts directly. The CLI is the seam between agent and state.\n\nSupported state commands:\n  agentera prime                                # Composite orientation briefing\n  agentera prime --guidance                     # Print this guide\n  agentera state decisions [--topic TOPIC]      # Decision log\n  agentera state health [--dimension DIM]       # Latest health audit\n  agentera state todo [--severity LEVEL]        # TODO summary\n  agentera state plan                           # Active plan + task status\n  agentera state progress [--limit N]           # Recent cycle summary\n  agentera state docs                           # Docs mappings + stale docs\n  agentera state objective                      # Active optimera objective\n  agentera state experiments                    # Active optimera experiments\n  agentera check lint --artifact PROGRESS.md --file .agentera/progress.yaml  # Pre-write artifact prose self-audit\n  agentera state query --list-artifacts         # Discover advanced schema names\n  agentera state query <artifact-name>          # Advanced custom artifact query\n\nWhen to use agentera:\n  - \"What did we decide about X?\"       \u2192 agentera state decisions --topic X\n  - \"How's the codebase health?\"        \u2192 agentera state health\n  - \"What's the coupling grade?\"        \u2192 agentera state health --dimension coupling_health\n  - \"Any critical open issues?\"         \u2192 agentera state todo --severity critical\n\nWhen to use native tools:\n  - Reading or editing source code      \u2192 native read/edit/grep\n  - Searching files                     \u2192 native glob/grep\n  - Running commands                    \u2192 native bash\n  - Browsing the web                    \u2192 native fetch\n\n## Recovery: stale or missing artifacts\n\nIf `agentera <state>` returns empty:\n  1. The artifact may not exist yet (no data has been written to it).\n  2. Run without filters to see all available data.\n  3. If data is stale, the producing capability needs to run again.\n\nIf artifacts are corrupted:\n  1. Check the YAML file in .agentera/ directly.\n  2. Run `agentera schema --format json` and use `source.schemas_dir`.\n  3. Re-run the producing capability to regenerate the artifact.\n\nIf schemas are missing:\n  1. Run `agentera schema --format json`.\n  2. Make sure Agentera's app files exist at the reported `managedAppRoot` path.\n  3. Run `agentera doctor` for a plain-language repair preview.\n";
-//# sourceMappingURL=prime-blob.js.map
+import { preCutoverInstructionBody } from "./preCutoverCommand.js";
+export const PRIME_BLOB = preCutoverInstructionBody([
+    "# agentera priming guide",
+    "",
+    "## Routing: agentera vs native tools",
+    "",
+    "Use the top-level state-command namespace for routine questions about project state.",
+    "Use native tools (read, grep, glob, edit, bash) for source code operations.",
+    "",
+    "Agentera queries return compact answers from structured state. Do NOT read",
+    "raw YAML artifacts directly. The CLI is the seam between agent and state.",
+    "",
+    "For supported artifact mutations, use the typed state writer instead of native",
+    "file edits. Discover the live fields and examples before constructing a write:",
+    "  agentera state <artifact> explain --format json",
+    "  agentera state <artifact> explain --verb <verb> --format json",
+    "",
+    "Supported state commands:",
+    "  agentera prime                                # Composite orientation briefing",
+    "  agentera prime --guidance                     # Print this guide",
+    "  agentera state decisions [--topic TOPIC]      # Decision log",
+    "  agentera state health [--dimension DIM]       # Latest health audit",
+    "  agentera state todo [--severity LEVEL]        # TODO summary",
+    "  agentera state plan                           # Plans, task evidence + provenance",
+    "  agentera state progress [--limit N]           # Recent cycle summary",
+    "  agentera state docs                           # Docs mappings + stale docs",
+    "  agentera state objective                      # Active optimize objective",
+    "  agentera state experiments                    # Active optimize experiments",
+    "  agentera check lint --artifact PLAN.md --file plan.yaml  # Optional draft prose preview; the writer validates published bytes",
+    "  agentera state query --list-artifacts         # Discover advanced schema names",
+    "  agentera state query <artifact-name>          # Advanced custom artifact query",
+    "",
+    "Supported typed writes:",
+    "  agentera state progress append ...            # Record verified cycle evidence",
+    "  agentera state decisions explain --format json # Discover decision record operations",
+    "  agentera state plan explain --format json      # Discover plan record operations",
+    "  plan create ordinals are atomic-input symbols only; published plan/task identities are bare ten-letter IDs",
+    "  agentera state health append --input PATH     # Record one complete audit",
+    "  agentera state experiments publish --objective ID --input PATH  # Publish one validated experiment",
+    "  Add --dry-run to preview any mutation without publishing it.",
+    "",
+    "When to use agentera:",
+    '  - "What did we decide about X?"       → agentera state decisions --topic X',
+    '  - "How\'s the codebase health?"        → agentera state health',
+    '  - "What\'s the coupling grade?"        → agentera state health --dimension coupling_health',
+    '  - "Any critical open issues?"         → agentera state todo --severity critical',
+    "  - Recording supported artifact state   → agentera state <artifact> explain",
+    "",
+    "When to use native tools:",
+    "  - Reading or editing source code      → native read/edit/grep",
+    "  - Searching files                     → native glob/grep",
+    "  - Running commands                    → native bash",
+    "  - Browsing the web                    → native fetch",
+    "",
+    "## Recovery: stale or missing artifacts",
+    "",
+    "If `agentera <state>` returns empty:",
+    "  1. The artifact may not exist yet (no data has been written to it).",
+    "  2. Run without filters to see all available data.",
+    "  3. If data is stale, the producing capability needs to run again.",
+    "",
+    "If entity state is corrupted:",
+    "  1. Run `agentera check validate state --format json` for exact diagnostics.",
+    "  2. Use the reported bare ID with `agentera state <artifact> get --id ID --format json`.",
+    "  3. Follow the validator recovery; do not edit writer-owned entity files directly.",
+    "",
+    "If schemas are missing:",
+    "  1. Run `agentera schema --format json`.",
+    "  2. Make sure Agentera's app files exist at the reported `managedAppRoot` path.",
+    "  3. Run `agentera doctor` for a plain-language repair preview.",
+].join("\n") + "\n");