@felixdotgo/aidlc-kit 0.1.0 → 0.2.0

package/dist/src/installer.js

@@ -1,93 +1,24 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { adapters, findAdapter, installableAdapters, resolvedAdapters } from "./adapters.js";
-import { loadProjectConfig, validateLoopConfig } from "./profiles.js";
+import { adapters, findAdapter, resolvedAdapters } from "./adapters.js";
+import { loadProjectConfig } from "./profiles.js";
 import { loadState } from "./state.js";
 import { planProjectLayoutMigration } from "./project-migration.js";
-import { managedBlock, mergeManagedBlock } from "./managed-content.js";
+import { legacyManagedMarker, managedBlock, removeManagedBlock } from "./managed-content.js";
+import { hasOwnedManifest, managedContentHash, planLoopSelection, planManagedWrites, readManifest, readManifestFile, splitInventoryKey } from "./managed-planning.js";
 import { resolveProjectPathWithoutSymlinks } from "./project-path.js";
 import { contentHash, coreWorkflowFiles, initialProjectFiles, manifestSpec, packageVersion } from "./workflow.js";
+/** Manifest reading lives in the managed-planning core; this export path stays stable for existing importers. */
+export { readManifest } from "./managed-planning.js";
 const shortHash = (content) => contentHash(content).slice(0, 12);
 const safeTarget = (root, path) => resolveProjectPathWithoutSymlinks(root, path, "Managed path escapes the project", "Managed path crosses a symlink");
-/** Managed prompt blocks share a path across owners, so inventory keys carry the owner. */
-export const installedHashFor = (files, spec) => {
-    if (!files)
-        return undefined;
-    const keyed = files[`${spec.path}#${spec.owner}`];
-    if (keyed)
-        return keyed.hash;
-    const legacy = files[spec.path];
-    return legacy && (spec.strategy !== "managed-block" || legacy.owner === spec.owner) ? legacy.hash : undefined;
-};
-export const managedContentHash = (spec, content) => {
-    const managed = managedBlock(spec, content);
-    return managed === undefined ? undefined : contentHash(managed);
-};
-export const readManifest = (root) => {
-    const path = join(resolve(root), ".agents/aidlc/manifest.json");
-    if (!existsSync(path))
-        return undefined;
-    try {
-        const value = JSON.parse(readFileSync(path, "utf8"));
-        const validFiles = value.files && typeof value.files === "object" && !Array.isArray(value.files) && Object.values(value.files).every((item) => item && typeof item.hash === "string" && typeof item.owner === "string" && ["replace", "managed-block"].includes(item.strategy));
-        return value.schemaVersion === 2 && typeof value.packageVersion === "string" && value.workflow === "AI-DLC" && value.source === "local-package-assets" && value.remoteUpdates === false && value.managedBy === "aidlc-workflow" && Array.isArray(value.adapters) && validFiles ? value : undefined;
-    }
-    catch {
-        return undefined;
-    }
-};
-export const detectedAgents = (root) => installableAdapters().filter((adapter) => adapter.detect(root)).map((adapter) => adapter.id);
+export const detectedAgents = (root) => resolvedAdapters().filter((adapter) => adapter.detect(root)).map((adapter) => adapter.id);
 export const selectAgents = (options) => {
     if (options.all)
         return adapters.map((adapter) => adapter.id);
     return [...new Set(options.agents)];
 };
-const planFile = (root, spec, force, installed) => {
-    const target = safeTarget(root, spec.path);
-    if (spec.ownershipClass === "project" || spec.ownershipClass === "state") {
-        return existsSync(target)
-            ? { ...spec, content: readFileSync(target, "utf8"), action: "preserve", reason: `${spec.ownershipClass}-owned file` }
-            : { ...spec, action: "create", reason: `new ${spec.ownershipClass}-owned file` };
-    }
-    if (spec.strategy === "managed-block") {
-        const current = existsSync(target) ? readFileSync(target, "utf8") : "";
-        const next = mergeManagedBlock(spec, current);
-        return { ...spec, content: next, action: existsSync(target) ? (next === current ? "skip" : "update") : "create", reason: existsSync(target) ? "managed prompt block" : "new managed prompt" };
-    }
-    if (!existsSync(target))
-        return { ...spec, action: "create", reason: "new managed file" };
-    const current = readFileSync(target, "utf8");
-    if (current === spec.content)
-        return { ...spec, action: "skip", reason: "already current" };
-    if (spec.path === ".agents/aidlc/manifest.json" && installed)
-        return { ...spec, action: "update", reason: "refresh manifest inventory" };
-    const installedHash = installedHashFor(installed?.files, spec);
-    if (installedHash && contentHash(current) === installedHash)
-        return { ...spec, action: "update", reason: "unchanged managed file" };
-    if (force)
-        return { ...spec, action: "update", reason: "--force permits replacement of an unmanaged file" };
-    return { ...spec, action: "conflict", reason: "managed ownership cannot be proven; use upgrade or review --force" };
-};
-/** Include an explicitly selected loop config in the same preview/transaction as setup. */
-export const planLoopSelection = (plan, selection) => {
-    if (selection === undefined)
-        return;
-    const loop = validateLoopConfig(selection);
-    const config = plan.find((item) => item.path === ".agents/config.json");
-    if (!config || !["create", "preserve", "skip", "migrate"].includes(config.action))
-        throw new Error("Cannot change loop configuration while the project config has another planned change");
-    const parsed = JSON.parse(config.content);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-        throw new Error("Invalid project config");
-    const current = parsed;
-    if (JSON.stringify(current.loop) === JSON.stringify(loop))
-        return;
-    const previousAction = config.action;
-    current.loop = loop;
-    config.content = `${JSON.stringify(current, null, 2)}\n`;
-    config.action = previousAction === "create" || previousAction === "migrate" ? previousAction : "update";
-    config.reason = "explicit loop mode selection";
-};
+/** Plans an init transaction: managed workflow files, manifest, and project-owned files. */
 export const planInit = (options) => {
     const root = resolve(options.root);
     const installed = readManifest(root);
@@ -100,23 +31,12 @@ export const planInit = (options) => {
     const agentFiles = selected.flatMap((id) => findAdapter(id)?.files() ?? []).map((file) => ({ ...file, ownershipClass: "managed" }));
     const managedFiles = [...coreWorkflowFiles(), ...agentFiles];
     const files = [...managedFiles, manifestSpec(managedFiles, selected), ...initialProjectFiles()];
-    const plan = [];
-    for (const spec of files) {
-        const previous = spec.strategy === "managed-block" ? plan.find((item) => item.path === spec.path && ["create", "update", "skip"].includes(item.action)) : undefined;
-        if (!previous) {
-            plan.push(planFile(root, spec, options.force, installed));
-            continue;
-        }
-        const target = safeTarget(root, spec.path);
-        const current = existsSync(target) ? readFileSync(target, "utf8") : "";
-        previous.content = mergeManagedBlock(spec, previous.content);
-        previous.action = existsSync(target) ? (previous.content === current ? "skip" : "update") : "create";
-        previous.reason = existsSync(target) ? "managed prompt block" : "new managed prompt";
-    }
+    const plan = planManagedWrites(root, files, { flow: "init", force: options.force, installed, resolvePath: safeTarget });
     planProjectLayoutMigration(root, plan);
     planLoopSelection(plan, options.loop);
     return plan;
 };
+/** Applies a planned init/uninstall transaction to disk. */
 export const applyPlan = (root, plan) => {
     for (const write of plan.filter((item) => item.action === "delete"))
         rmSync(safeTarget(root, write.path), { force: true });
@@ -127,109 +47,124 @@ export const applyPlan = (root, plan) => {
     }
 };
 export const formatPlan = (plan) => plan.map((item) => `${item.action.padEnd(8)} ${item.path} (${item.reason}; sha=${shortHash(item.contentEncoding === "base64" ? Buffer.from(item.content, "base64") : item.content)})`).join("\n");
-const hasOwnedManifest = (root) => {
-    const path = join(resolve(root), ".agents/aidlc/manifest.json");
-    if (!existsSync(path))
-        return false;
-    try {
-        return JSON.parse(readFileSync(path, "utf8")).managedBy === "aidlc-workflow";
+/** Maps one manifest inventory record onto its current spec and installed hash. */
+const uninstallEntry = (key, item, currentSpecs) => {
+    const { path, owner: keyedOwner } = splitInventoryKey(key);
+    const owner = keyedOwner ?? item.owner;
+    const spec = currentSpecs.find((candidate) => candidate.path === path && (candidate.strategy !== "managed-block" || candidate.owner === owner)) ?? { path, owner, strategy: item.strategy, content: "", ownershipClass: "managed" };
+    return { spec, hash: item.hash };
+};
+/** Groups installed specs (or all current specs without a manifest) by path; shared blocks carry multiple owners. */
+const uninstallGroups = (installed, currentSpecs) => {
+    const entries = installed ? Object.entries(installed.files).map(([key, item]) => uninstallEntry(key, item, currentSpecs)) : currentSpecs.map((spec) => ({ spec }));
+    const groups = new Map();
+    for (const entry of entries)
+        groups.set(entry.spec.path, [...(groups.get(entry.spec.path) ?? []), entry]);
+    return groups;
+};
+/** Removes each verified owner block from a shared file; stops at the first user-modified block. */
+const stripManagedBlocks = (group, current) => {
+    let next = current;
+    let modified;
+    for (const { spec, hash } of group) {
+        const block = managedBlock(spec, next);
+        // A v0.2.1 single-marker block cannot be removed safely; retain ownership instead of orphaning it.
+        if (!block) {
+            if (next.includes(legacyManagedMarker(spec.owner)))
+                modified = spec;
+            continue;
+        }
+        if (contentHash(block) !== (hash ?? contentHash(spec.content.trimEnd()))) {
+            modified = spec;
+            break;
+        }
+        next = removeManagedBlock(next, spec.owner);
     }
-    catch {
-        return false;
+    return { next, modified };
+};
+/** Decides the plan entry for a whole-file (non shared-block) path. */
+const uninstallWholeFile = (group, exists, current) => {
+    if (!exists)
+        return { ...group[0].spec, action: "skip", reason: "not installed" };
+    if (!group.some((entry) => entry.spec.strategy === "managed-block")) {
+        const { spec, hash } = group[0];
+        const installedHash = hash ?? contentHash(spec.content);
+        return contentHash(current) === installedHash ? { ...spec, action: "delete", reason: "remove unchanged managed file" } : { ...spec, action: "preserve", reason: "managed file was modified" };
     }
+    const { next, modified } = stripManagedBlocks(group, current);
+    const legacyResidue = group.find(({ spec }) => next.includes(legacyManagedMarker(spec.owner)));
+    const ownerSpec = group[0].spec;
+    if (modified)
+        return { ...modified, action: "preserve", reason: "managed block was modified" };
+    if (legacyResidue)
+        return { ...legacyResidue.spec, action: "preserve", reason: "legacy prompt marker requires manual removal" };
+    if (next === current)
+        return { ...ownerSpec, action: "skip", reason: "owned block not found" };
+    if (next)
+        return { ...ownerSpec, content: `${next}\n`, action: "update", reason: "remove owned prompt block" };
+    return { ...ownerSpec, content: "", action: "delete", reason: "remove owned prompt file" };
 };
-const removeManagedBlock = (current, owner) => {
-    const start = `<!-- aidlc-installer:${owner}:start -->`;
-    const end = `<!-- aidlc-installer:${owner}:end -->`;
-    return current.replace(new RegExp(`${start}[\\s\\S]*?${end}\\n?`, "g"), "").replace(/\n{3,}/g, "\n\n").trimEnd();
+/** Keeps the ownership manifest only while modified managed files remain on disk. */
+const manifestDisposition = (plan) => {
+    const preserved = plan.some((item) => item.action === "preserve");
+    return { path: ".agents/aidlc/manifest.json", owner: "aidlc-core", content: "", ownershipClass: "managed", action: preserved ? "preserve" : "delete", reason: preserved ? "retained while modified managed files remain" : "remove ownership manifest" };
 };
+/** Plans an uninstall transaction that removes only unchanged managed assets. */
 export const planUninstall = (root) => {
     const project = resolve(root);
     if (!hasOwnedManifest(project))
-        throw new Error("No aidlc-workflow ownership manifest found; refusing to remove files.");
+        throw new Error("No managed ownership manifest (.agents/aidlc/manifest.json) found; refusing to remove files.");
     const installed = readManifest(project);
     const currentSpecs = [...coreWorkflowFiles(), ...resolvedAdapters().flatMap((adapter) => adapter.files()).map((file) => ({ ...file, ownershipClass: "managed" }))];
-    const entries = installed
-        ? Object.entries(installed.files).map(([key, item]) => {
-            const separator = key.lastIndexOf("#");
-            const path = separator > 0 ? key.slice(0, separator) : key;
-            const owner = separator > 0 ? key.slice(separator + 1) : item.owner;
-            const spec = currentSpecs.find((candidate) => candidate.path === path && (candidate.strategy !== "managed-block" || candidate.owner === owner)) ?? { path, owner, strategy: item.strategy, content: "", ownershipClass: "managed" };
-            return { spec, hash: item.hash };
-        })
-        : currentSpecs.map((spec) => ({ spec }));
-    const grouped = new Map();
-    for (const entry of entries)
-        grouped.set(entry.spec.path, [...(grouped.get(entry.spec.path) ?? []), entry]);
     const plan = [];
-    for (const [path, group] of grouped) {
+    for (const [path, group] of uninstallGroups(installed, currentSpecs)) {
         const target = safeTarget(project, path);
         const exists = existsSync(target);
-        const current = exists ? readFileSync(target, "utf8") : "";
-        if (!exists) {
-            plan.push({ ...group[0].spec, action: "skip", reason: "not installed" });
-            continue;
-        }
-        if (!group.some((entry) => entry.spec.strategy === "managed-block")) {
-            const { spec, hash } = group[0];
-            const installedHash = hash ?? contentHash(spec.content);
-            plan.push(contentHash(current) === installedHash ? { ...spec, action: "delete", reason: "remove unchanged managed file" } : { ...spec, action: "preserve", reason: "managed file was modified" });
-            continue;
-        }
-        let next = current;
-        let modified;
-        for (const { spec, hash } of group) {
-            const block = managedBlock(spec, next);
-            // A v0.2.1 single-marker block cannot be removed safely; retain ownership instead of orphaning it.
-            if (!block) {
-                if (next.includes(`<!-- aidlc-installer:${spec.owner} -->`))
-                    modified = spec;
-                continue;
-            }
-            if (contentHash(block) !== (hash ?? contentHash(spec.content.trimEnd()))) {
-                modified = spec;
-                break;
-            }
-            next = removeManagedBlock(next, spec.owner);
-        }
-        const ownerSpec = group[0].spec;
-        const legacyResidue = group.find(({ spec }) => next.includes(`<!-- aidlc-installer:${spec.owner} -->`));
-        if (modified)
-            plan.push({ ...modified, action: "preserve", reason: "managed block was modified" });
-        else if (legacyResidue)
-            plan.push({ ...legacyResidue.spec, action: "preserve", reason: "legacy prompt marker requires manual removal" });
-        else if (next === current)
-            plan.push({ ...ownerSpec, action: "skip", reason: "owned block not found" });
-        else if (next)
-            plan.push({ ...ownerSpec, content: `${next}\n`, action: "update", reason: "remove owned prompt block" });
-        else
-            plan.push({ ...ownerSpec, content: "", action: "delete", reason: "remove owned prompt file" });
+        plan.push(uninstallWholeFile(group, exists, exists ? readFileSync(target, "utf8") : ""));
     }
-    plan.push({ path: ".agents/aidlc/manifest.json", owner: "aidlc-core", content: "", ownershipClass: "managed", action: plan.some((item) => item.action === "preserve") ? "preserve" : "delete", reason: plan.some((item) => item.action === "preserve") ? "retained while modified managed files remain" : "remove ownership manifest" });
+    plan.push(manifestDisposition(plan));
     return plan;
 };
-export const status = (root) => {
+export const statusData = (root) => {
     const manifest = readManifest(root);
     const legacyPath = join(resolve(root), ".agents/aidlc/manifest.json");
+    return {
+        workflow: manifest || existsSync(legacyPath) ? "installed" : "not installed",
+        installedVersion: manifest?.packageVersion ?? (existsSync(legacyPath) ? "legacy/unknown" : "none"),
+        schema: `${manifest?.schemaVersion ?? (existsSync(legacyPath) ? "legacy" : "none")}`,
+        detectedAgents: detectedAgents(root)
+    };
+};
+/** Reports installed workflow version, schema, and detected agents. */
+export const status = (root) => {
+    const data = statusData(root);
     return [
-        `workflow: ${manifest || existsSync(legacyPath) ? "installed" : "not installed"}`,
-        `installed version: ${manifest?.packageVersion ?? (existsSync(legacyPath) ? "legacy/unknown" : "none")}`,
-        `schema: ${manifest?.schemaVersion ?? (existsSync(legacyPath) ? "legacy" : "none")}`,
-        `detected agents: ${detectedAgents(root).join(", ") || "none"}`
+        `workflow: ${data.workflow}`,
+        `installed version: ${data.installedVersion}`,
+        `schema: ${data.schema}`,
+        `detected agents: ${data.detectedAgents.join(", ") || "none"}`
     ].join("\n");
 };
+/** Manifest inventory paths whose on-disk content no longer matches the recorded owner hash. */
+const modifiedManagedPaths = (root, manifest) => {
+    const modified = Object.entries(manifest.files).filter(([key, item]) => {
+        const target = safeTarget(root, splitInventoryKey(key).path);
+        if (!existsSync(target))
+            return true;
+        const spec = { owner: item.owner, strategy: item.strategy };
+        return managedContentHash(spec, readFileSync(target, "utf8")) !== item.hash;
+    });
+    return [...new Set(modified.map(([key]) => splitInventoryKey(key).path))];
+};
+/** Validates the installed workflow manifest and local config/state. */
 export const doctor = (root, strict = false) => {
-    const manifestPath = join(resolve(root), ".agents/aidlc/manifest.json");
-    if (!existsSync(manifestPath))
+    const read = readManifestFile(root);
+    if (read.status === "missing")
         return "ERROR: .agents/aidlc/manifest.json is missing. Run npx @felixdotgo/aidlc-kit init --yes.";
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
-    }
-    catch {
+    if (read.status === "invalid")
         return "ERROR: workflow manifest is invalid JSON.";
-    }
-    if (parsed.remoteUpdates || parsed.source !== "local-package-assets" || parsed.managedBy !== "aidlc-workflow")
+    const parsed = read.value;
+    if (parsed.remoteUpdates || parsed.source !== "local-package-assets" || (parsed.managedBy !== "aidlc-kit" && parsed.managedBy !== "aidlc-workflow"))
         return "ERROR: workflow manifest violates local-only asset policy.";
     if (typeof parsed.schemaVersion === "number" && parsed.schemaVersion > 2)
         return `ERROR: installed manifest schema ${parsed.schemaVersion} is newer than this CLI supports.`;
@@ -243,15 +178,13 @@ export const doctor = (root, strict = false) => {
     catch (error) {
         return `ERROR: local config/state is invalid: ${error instanceof Error ? error.message : String(error)}`;
     }
-    const modified = [...new Set(Object.entries(manifest.files).filter(([key, item]) => {
-            const separator = key.lastIndexOf("#");
-            const target = safeTarget(root, separator > 0 ? key.slice(0, separator) : key);
-            if (!existsSync(target))
-                return true;
-            const spec = { owner: item.owner, strategy: item.strategy };
-            return managedContentHash(spec, readFileSync(target, "utf8")) !== item.hash;
-        }).map(([key]) => key.includes("#") ? key.slice(0, key.lastIndexOf("#")) : key))];
+    const modified = modifiedManagedPaths(root, manifest);
     if (modified.length)
         return `${strict ? "ERROR" : "WARN"}: managed integrity differs: ${modified.join(", ")}`;
     return `OK: local workflow ${manifest.packageVersion} is valid; remote updates are disabled.`;
 };
+export const doctorData = (root, strict = false) => {
+    const message = doctor(root, strict);
+    const level = message.startsWith("ERROR:") ? "error" : message.startsWith("WARN:") ? "warn" : "ok";
+    return { level, message, strict };
+};

package/dist/src/legacy.js

@@ -25,6 +25,7 @@ const instruction = (agent) => [
     "Read `.agents/aidlc/orchestrator.md` and `.agents/data/state/BOARD.md` before starting non-trivial work. Use phase skills under `.agents/skills/`; do not fetch remote workflow content. Respect more-specific instructions already present in this repository.",
     ""
 ].join("\n");
+/** Frozen v0.2.1 baseline payload — intentionally does NOT reuse managed-content markers: this string is a historical fact that must not track future marker-format changes. */
 const block = (owner, body) => `<!-- aidlc-installer:${owner} -->\n${body}`;
 export const legacyV021AdapterContents = Object.freeze({
     "CLAUDE.md": block("claude", instruction("Claude Code")),

package/dist/src/managed-content.d.ts

@@ -1,3 +1,10 @@
 import type { FileSpec } from "./model.js";
+/** Canonical managed-block markers; every emitter and detector must build them through these helpers. */
+export declare const managedStartMarker: (owner: string) => string;
+export declare const managedEndMarker: (owner: string) => string;
+/** Single-marker block emitted by the frozen v0.2.1 baseline; upgrade and uninstall still detect it. */
+export declare const legacyManagedMarker: (owner: string) => string;
 export declare const managedBlock: (spec: Pick<FileSpec, "owner" | "strategy">, content: string) => string | undefined;
 export declare const mergeManagedBlock: (spec: FileSpec, current: string) => string;
+/** Removes every block owned by `owner` from `current` and normalizes the leftover blank-line runs. */
+export declare const removeManagedBlock: (current: string, owner: string) => string;

package/dist/src/managed-content.js

@@ -1,16 +1,27 @@
+/** Canonical managed-block markers; every emitter and detector must build them through these helpers. */
+export const managedStartMarker = (owner) => `<!-- aidlc-installer:${owner}:start -->`;
+export const managedEndMarker = (owner) => `<!-- aidlc-installer:${owner}:end -->`;
+/** Single-marker block emitted by the frozen v0.2.1 baseline; upgrade and uninstall still detect it. */
+export const legacyManagedMarker = (owner) => `<!-- aidlc-installer:${owner} -->`;
 export const managedBlock = (spec, content) => {
     if (spec.strategy !== "managed-block")
         return content;
-    const start = `<!-- aidlc-installer:${spec.owner}:start -->`;
-    const end = `<!-- aidlc-installer:${spec.owner}:end -->`;
+    const start = managedStartMarker(spec.owner);
+    const end = managedEndMarker(spec.owner);
     return content.match(new RegExp(`${start}[\\s\\S]*?${end}`))?.[0];
 };
 export const mergeManagedBlock = (spec, current) => {
-    const start = `<!-- aidlc-installer:${spec.owner}:start -->`;
-    const end = `<!-- aidlc-installer:${spec.owner}:end -->`;
+    const start = managedStartMarker(spec.owner);
+    const end = managedEndMarker(spec.owner);
     const block = spec.content.trimEnd();
     const matches = new RegExp(`${start}[\\s\\S]*?${end}\\n?`, "g");
     const withoutOwnedBlocks = current.replace(matches, "").replace(/\n{3,}/g, "\n\n").trim();
     const next = `${withoutOwnedBlocks}${withoutOwnedBlocks ? "\n\n" : ""}${block}`;
     return `${next.trimEnd()}\n`;
 };
+/** Removes every block owned by `owner` from `current` and normalizes the leftover blank-line runs. */
+export const removeManagedBlock = (current, owner) => {
+    const start = managedStartMarker(owner);
+    const end = managedEndMarker(owner);
+    return current.replace(new RegExp(`${start}[\\s\\S]*?${end}\\n?`, "g"), "").replace(/\n{3,}/g, "\n\n").trimEnd();
+};

package/dist/src/managed-planning.d.ts

@@ -0,0 +1,65 @@
+import type { FileSpec, LoopConfig, ManifestInventoryItem, PlannedWrite, WorkflowManifest } from "./model.js";
+/** Constructs manifest inventory keys (`path#owner` for shared managed blocks). The definition should live here; it stays in workflow.ts pending a cross-owner move. */
+export { manifestKey } from "./workflow.js";
+/** Raw outcome of reading the ownership manifest: missing on disk, unparseable, or parsed but unvalidated. */
+export type ManifestFileRead = {
+    status: "missing";
+} | {
+    status: "invalid";
+} | {
+    status: "parsed";
+    value: Record<string, unknown>;
+};
+/** The single read+parse of .agents/aidlc/manifest.json that every manifest question goes through. */
+export declare const readManifestFile: (root: string) => ManifestFileRead;
+/** Strict schema-v2 ownership manifest; malformed or non-conforming content reads as "not installed". */
+export declare const readManifest: (root: string) => WorkflowManifest | undefined;
+/** Whether the on-disk manifest is owned by this package (any schema version). */
+export declare const hasOwnedManifest: (root: string) => boolean;
+/** Whether the on-disk manifest is a legacy aidlc-workflow v0.x install (schema 0 or 1). */
+export declare const legacyManifest: (root: string) => boolean;
+/** Splits a manifest inventory key into its path and, when present, its `#owner` suffix. */
+export declare const splitInventoryKey: (key: string) => {
+    path: string;
+    owner?: string;
+};
+/** Managed prompt blocks share a path across owners, so inventory keys carry the owner. */
+export declare const installedHashFor: (files: Record<string, ManifestInventoryItem> | undefined, spec: Pick<FileSpec, "path" | "owner" | "strategy">) => string | undefined;
+/** Hash of the managed slice of a file: the owned block for managed-block strategies, the whole file otherwise. */
+export declare const managedContentHash: (spec: Pick<FileSpec, "owner" | "strategy">, content: string) => string | undefined;
+/** Plans one project/state-owned file: preserved verbatim when present, seeded from the package when absent. */
+export declare const preserveOwnedFile: (target: string, spec: FileSpec) => PlannedWrite;
+/** Caller-supplied project-path resolver so each flow keeps its own error persona (init refuses escapes and symlinks; upgrade refuses only escapes). */
+export type ProjectPathResolver = (root: string, relative: string) => string;
+/** Policy fields shared by both flows. */
+export interface PlanPolicyBase {
+    /** Installed manifest to prove ownership against, when one exists. */
+    installed?: WorkflowManifest;
+    /** Project-path resolver carrying the caller's error persona. */
+    resolvePath: ProjectPathResolver;
+}
+/** Init: managed blocks merge unconditionally and --force may replace unmanaged files. */
+export interface InitPlanPolicy extends PlanPolicyBase {
+    flow: "init";
+    force: boolean;
+}
+/** Upgrade: ownership is proven against installed hashes and the frozen v0.2.1 baselines. */
+export interface UpgradePlanPolicy extends PlanPolicyBase {
+    flow: "upgrade";
+    /** True when no schema-2 manifest exists and a legacy v0.x install is being migrated. */
+    legacy: boolean;
+    /** Recognizes a v0.2.1 baseline for a spec's current managed-content hash; consulted only while `legacy` is set. */
+    legacyBaseline?: (spec: FileSpec, currentHash: string | undefined) => boolean;
+}
+/** Per-flow policy for the shared managed-file ladder; the union makes each flow's knobs explicit. */
+export type PlanPolicy = InitPlanPolicy | UpgradePlanPolicy;
+/**
+ * Plans managed files (and, for init, the manifest and project/state files) in
+ * order; later owners of a shared managed-block path merge into the earlier
+ * entry. Init finds the earlier entry by scanning the plan; upgrade tracks the
+ * first block entry per path so a conflicted first owner stays the single
+ * reportable entry for that path.
+ */
+export declare const planManagedWrites: (root: string, files: FileSpec[], policy: PlanPolicy) => PlannedWrite[];
+/** Include an explicitly selected loop config in the same preview/transaction as setup. */
+export declare const planLoopSelection: (plan: PlannedWrite[], selection?: LoopConfig) => void;