@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

package/dist/src/installer.js

@@ -1,113 +1,23 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, 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";
+import { contentHash, coreWorkflowFiles, initialProjectFiles, isExecutableAsset, 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-kit" || value.managedBy === "aidlc-workflow") && Array.isArray(value.adapters) && validFiles ? value : undefined;
-    }
-    catch {
-        return undefined;
-    } /* intentional: a malformed manifest is treated as "not installed" */
-};
-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";
-};
-/** Merges a later owner of an already-planned shared managed-block path into the emitted entry. */
-const mergeIntoPlannedBlock = (root, previous, spec) => {
-    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";
-};
-/** Plans managed workflow files, the manifest, and project-owned files; later block owners merge in line. */
-const planManagedWrites = (root, files, force, installed) => {
-    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, force, installed));
-        else
-            mergeIntoPlannedBlock(root, previous, spec);
-    }
-    return plan;
-};
 /** Plans an init transaction: managed workflow files, manifest, and project-owned files. */
 export const planInit = (options) => {
     const root = resolve(options.root);
@@ -121,7 +31,7 @@ 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 = planManagedWrites(root, files, options.force, installed);
+    const plan = planManagedWrites(root, files, { flow: "init", force: options.force, installed, resolvePath: safeTarget });
     planProjectLayoutMigration(root, plan);
     planLoopSelection(plan, options.loop);
     return plan;
@@ -134,31 +44,15 @@ export const applyPlan = (root, plan) => {
         const target = safeTarget(root, write.path);
         mkdirSync(dirname(target), { recursive: true });
         writeFileSync(target, write.content, "utf8");
+        if (isExecutableAsset(write.path) && process.platform !== "win32")
+            chmodSync(target, 0o755);
     }
 };
 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 {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        return parsed.managedBy === "aidlc-kit" || parsed.managedBy === "aidlc-workflow";
-    }
-    catch {
-        return false;
-    } /* intentional: a malformed/missing manifest is not owned */
-};
-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();
-};
 /** Maps one manifest inventory record onto its current spec and installed hash. */
 const uninstallEntry = (key, item, currentSpecs) => {
-    const separator = key.lastIndexOf("#");
-    const path = separator > 0 ? key.slice(0, separator) : key;
-    const owner = separator > 0 ? key.slice(separator + 1) : item.owner;
+    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 };
 };
@@ -178,7 +72,7 @@ const stripManagedBlocks = (group, current) => {
         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} -->`))
+            if (next.includes(legacyManagedMarker(spec.owner)))
                 modified = spec;
             continue;
         }
@@ -200,7 +94,7 @@ const uninstallWholeFile = (group, exists, current) => {
         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(`<!-- aidlc-installer:${spec.owner} -->`));
+    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" };
@@ -233,45 +127,45 @@ export const planUninstall = (root) => {
     plan.push(manifestDisposition(plan));
     return plan;
 };
-/** Reports installed workflow version, schema, and detected agents. */
-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");
 };
-/** Path portion of a manifest inventory key (`path#owner` for shared managed blocks). */
-const inventoryKeyPath = (key) => {
-    const separator = key.lastIndexOf("#");
-    return separator > 0 ? key.slice(0, separator) : key;
-};
 /** 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, inventoryKeyPath(key));
+        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]) => inventoryKeyPath(key)))];
+    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.";
-    }
+    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)
@@ -291,3 +185,8 @@ export const doctor = (root, strict = false) => {
         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;

package/dist/src/managed-planning.js

@@ -0,0 +1,219 @@
+/**
+ * Managed-planning core shared by init and upgrade: the manifest-reader family,
+ * inventory-key handling, managed-content hash proofs, and the single
+ * create/skip/update/conflict ladder for managed files, driven by explicit
+ * per-flow policies so installation and upgrade keep their exact semantics.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { legacyManagedMarker, managedBlock, mergeManagedBlock } from "./managed-content.js";
+import { validateLoopConfig } from "./profiles.js";
+import { contentHash } from "./workflow.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";
+/** The single read+parse of .agents/aidlc/manifest.json that every manifest question goes through. */
+export const readManifestFile = (root) => {
+    const path = join(resolve(root), ".agents/aidlc/manifest.json");
+    if (!existsSync(path))
+        return { status: "missing" };
+    try {
+        return { status: "parsed", value: JSON.parse(readFileSync(path, "utf8")) };
+    }
+    catch {
+        return { status: "invalid" };
+    } /* intentional: an unreadable manifest is missing/invalid, never a crash */
+};
+/** Strict schema-v2 ownership manifest; malformed or non-conforming content reads as "not installed". */
+export const readManifest = (root) => {
+    const read = readManifestFile(root);
+    if (read.status !== "parsed")
+        return undefined;
+    try {
+        const value = read.value;
+        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-kit" || value.managedBy === "aidlc-workflow") && Array.isArray(value.adapters) && validFiles ? value : undefined;
+    }
+    catch {
+        return undefined;
+    } /* intentional: a malformed manifest is treated as "not installed" */
+};
+/** Whether the on-disk manifest is owned by this package (any schema version). */
+export const hasOwnedManifest = (root) => {
+    const read = readManifestFile(root);
+    if (read.status !== "parsed")
+        return false;
+    try {
+        return read.value.managedBy === "aidlc-kit" || read.value.managedBy === "aidlc-workflow";
+    }
+    catch {
+        return false;
+    } /* intentional: a malformed/missing manifest is not owned */
+};
+/** Whether the on-disk manifest is a legacy aidlc-workflow v0.x install (schema 0 or 1). */
+export const legacyManifest = (root) => {
+    const read = readManifestFile(root);
+    if (read.status !== "parsed")
+        return false;
+    try {
+        return read.value.managedBy === "aidlc-workflow" && (read.value.schemaVersion === 0 || read.value.schemaVersion === 1);
+    }
+    catch {
+        return false;
+    } /* intentional: a malformed/missing manifest is not a legacy v0.x install */
+};
+/* --- Inventory keys and hash proofs --------------------------------------------- */
+/** Splits a manifest inventory key into its path and, when present, its `#owner` suffix. */
+export const splitInventoryKey = (key) => {
+    const separator = key.lastIndexOf("#");
+    return separator > 0 ? { path: key.slice(0, separator), owner: key.slice(separator + 1) } : { path: key };
+};
+/** 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;
+};
+/** Hash of the managed slice of a file: the owned block for managed-block strategies, the whole file otherwise. */
+export const managedContentHash = (spec, content) => {
+    const managed = managedBlock(spec, content);
+    return managed === undefined ? undefined : contentHash(managed);
+};
+/* --- Owned-file preservation ------------------------------------------------------ */
+/** Plans one project/state-owned file: preserved verbatim when present, seeded from the package when absent. */
+export const preserveOwnedFile = (target, spec) => existsSync(target)
+    ? { ...spec, content: readFileSync(target, "utf8"), action: "preserve", reason: `${spec.ownershipClass}-owned file` }
+    : { ...spec, action: "create", reason: `new ${spec.ownershipClass}-owned file` };
+/* --- The one managed-file planning ladder -------------------------------------------- */
+/**
+ * The single managed-file planning ladder shared by init and upgrade. The flows
+ * share the head rungs and then diverge; every difference is pinned below so
+ * each caller behaves exactly as it did before the extraction:
+ * - project/state specs: init plans preserve/create here; upgrade never passes
+ *   them (its project files go through its own preserveProjectFiles pass).
+ * - fresh managed-block file: init merges into the empty file and says "new
+ *   managed prompt"; upgrade copies spec.content verbatim and says "new managed
+ *   file".
+ * - current content: init skips on whole-file equality ("already current");
+ *   upgrade compares managed-content hashes ("managed content already current")
+ *   and can still plan an update when only the surrounding layout changed.
+ * - manifest refresh and --force: init-only rungs (upgrade rewrites the
+ *   manifest unconditionally through its own manifestSpec entry).
+ * - installed-hash proof: init compares the whole-file hash (only replace files
+ *   reach this rung); upgrade compares the managed-content hash (block-scoped
+ *   for shared blocks).
+ * - v0.2.1 baselines and the legacy single-marker conflict: upgrade-only rungs.
+ * - terminal conflict: init reports unprovable ownership; upgrade names the
+ *   legacy-baseline or installed-hash mismatch.
+ */
+const planManagedFile = (root, spec, policy) => {
+    const target = policy.resolvePath(root, spec.path);
+    if (policy.flow === "init" && (spec.ownershipClass === "project" || spec.ownershipClass === "state"))
+        return preserveOwnedFile(target, spec);
+    if (policy.flow === "init" && 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 (policy.flow === "init") {
+        if (current === spec.content)
+            return { ...spec, action: "skip", reason: "already current" };
+        if (spec.path === ".agents/aidlc/manifest.json" && policy.installed)
+            return { ...spec, action: "update", reason: "refresh manifest inventory" };
+        const installedHash = installedHashFor(policy.installed?.files, spec);
+        if (installedHash && contentHash(current) === installedHash)
+            return { ...spec, action: "update", reason: "unchanged managed file" };
+        if (policy.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" };
+    }
+    const next = spec.strategy === "managed-block" ? mergeManagedBlock(spec, current) : spec.content;
+    const currentHash = managedContentHash(spec, current);
+    const nextHash = contentHash(spec.strategy === "managed-block" ? spec.content.trimEnd() : spec.content);
+    if (currentHash === nextHash)
+        return { ...spec, content: next, action: next === current ? "skip" : "update", reason: "managed content already current" };
+    const installedHash = installedHashFor(policy.installed?.files, spec);
+    if (installedHash && currentHash === installedHash)
+        return { ...spec, content: next, action: "update", reason: "unchanged managed file" };
+    if (policy.legacy && policy.legacyBaseline?.(spec, currentHash))
+        return { ...spec, content: next, action: "update", reason: "recognized v0.2.1 baseline" };
+    if (spec.strategy === "managed-block" && current.includes(legacyManagedMarker(spec.owner)))
+        return { ...spec, content: next, action: "conflict", reason: "managed prompt block was modified" };
+    return { ...spec, content: next, action: "conflict", reason: policy.legacy ? "legacy core differs from known baseline" : "managed file differs from installed hash" };
+};
+/**
+ * Merges a later owner of a shared managed-block path into the already-planned
+ * entry. Upgrade proof-checks the later owner's installed block hash first so a
+ * user edit to a later adapter's block is reported instead of being silently
+ * overwritten; init has nothing to prove against and merges unconditionally,
+ * saying "new managed prompt" for a file that did not exist yet.
+ */
+const mergeSharedBlockOwner = (root, previous, spec, policy) => {
+    if (!["create", "update", "skip"].includes(previous.action))
+        return;
+    const target = policy.resolvePath(root, spec.path);
+    const current = existsSync(target) ? readFileSync(target, "utf8") : "";
+    if (policy.flow === "upgrade") {
+        const installedBlockHash = installedHashFor(policy.installed?.files, spec);
+        const currentBlockHash = managedContentHash(spec, current);
+        if (installedBlockHash !== undefined && currentBlockHash !== undefined && installedBlockHash !== currentBlockHash) {
+            previous.action = "conflict";
+            previous.reason = "managed prompt block was modified";
+            return;
+        }
+    }
+    previous.content = mergeManagedBlock(spec, previous.content);
+    previous.action = existsSync(target) ? (previous.content === current ? "skip" : "update") : "create";
+    previous.reason = policy.flow === "init" && !existsSync(target) ? "new managed prompt" : "managed prompt block";
+};
+/**
+ * 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 const planManagedWrites = (root, files, policy) => {
+    const plan = [];
+    const firstBlocks = new Map();
+    for (const spec of files) {
+        const previous = spec.strategy === "managed-block"
+            ? policy.flow === "init" ? plan.find((item) => item.path === spec.path && ["create", "update", "skip"].includes(item.action)) : firstBlocks.get(spec.path)
+            : undefined;
+        if (!previous) {
+            const write = planManagedFile(root, spec, policy);
+            plan.push(write);
+            if (policy.flow === "upgrade" && spec.strategy === "managed-block")
+                firstBlocks.set(spec.path, write);
+        }
+        else
+            mergeSharedBlockOwner(root, previous, spec, policy);
+    }
+    return plan;
+};
+/** 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";
+};

package/dist/src/mcp-setup.js

@@ -1,5 +1,6 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { defaultConfig, validateProjectConfig } from "./profiles.js";
 export const planMcpSetup = (options) => {
     const target = join(resolve(options.root), ".agents/aidlc-coordination");
     const endpoint = options.deployment === "docker" ? "http://127.0.0.1:8787/mcp" : "https://replace-with-service.example/mcp";
@@ -24,8 +25,9 @@ export const applyMcpSetup = (options) => {
     ].join("\n");
     writeFileSync(join(plan.target, ".env.example"), `${env}\n`, "utf8");
     const configPath = join(resolve(options.root), ".agents/config.json");
-    const current = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf8")) : { schemaVersion: 3, extends: ["topology/single"], specs: { roots: [] }, commands: {}, rules: { include: [] }, risk: { default: "normal" }, context: { maxChars: 16000 }, agentState: {} };
+    const current = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf8")) : { ...defaultConfig() };
     current.mcp = plan.config;
+    validateProjectConfig(current);
     writeFileSync(configPath, `${JSON.stringify(current, null, 2)}\n`, "utf8");
     return plan;
 };