@felixdotgo/aidlc-kit 0.0.1

package/dist/src/model.d.ts

@@ -0,0 +1,249 @@
+export type AgentId = string;
+export type StateMutationMode = "native" | "scripted";
+export type Phase = "clarify" | "plan" | "build" | "wrap" | "done";
+export type Gate = "none" | "G0_confirm" | "G1_review" | "G2_codereview";
+export type TaskStatus = "active" | "blocked_on_user" | "paused" | "done" | "closed" | "superseded";
+export type RiskLevel = "low" | "normal" | "high" | "regulated";
+export type DecisionStatus = "unresolved" | "approved" | "changed" | "dropped";
+export type HandoffKind = "repair_exhausted" | "review_exhausted" | "g2_failed" | "release_failed" | "structural_change" | "other";
+export interface FileSpec {
+    path: string;
+    content: string;
+    owner: string;
+    strategy?: "replace" | "managed-block";
+    ownershipClass?: "managed" | "project" | "state";
+}
+export interface Adapter {
+    id: AgentId;
+    displayName: string;
+    detect(root: string): boolean;
+    files(): FileSpec[];
+}
+export interface PlannedWrite extends FileSpec {
+    action: "create" | "update" | "delete" | "skip" | "conflict" | "migrate" | "preserve";
+    reason: string;
+    contentEncoding?: "base64";
+}
+export interface InitOptions {
+    root: string;
+    agents: AgentId[];
+    all: boolean;
+    dryRun: boolean;
+    yes: boolean;
+    force: boolean;
+}
+export interface CommandSpec {
+    command: string;
+    args: string[];
+}
+export interface Profile {
+    schemaVersion: 1;
+    id: string;
+    extends?: string[];
+    topology: string;
+    discovery?: {
+        roots?: string[];
+        workspaceMarkers?: string[];
+    };
+    specs?: {
+        roots?: string[];
+    };
+    commands?: Record<string, CommandSpec>;
+    rules?: {
+        include?: string[];
+    };
+}
+export interface ProjectConfig {
+    schemaVersion: 1 | 2 | 3;
+    extends: string[];
+    specs: {
+        roots: string[];
+    };
+    commands: Record<string, CommandSpec>;
+    rules: {
+        include: string[];
+    };
+    risk: {
+        default: RiskLevel;
+    };
+    context: {
+        maxChars: number;
+    };
+    agentState: Partial<Record<AgentId, StateMutationMode>>;
+    tracker?: TrackerConfig;
+    mcp: McpConfig;
+}
+export interface McpConfig {
+    enabled: boolean;
+    endpoint?: string;
+    workspace?: string;
+    tokenEnv?: string;
+    pollMs?: number;
+    providers?: Array<"jira" | "trello" | "github-issues">;
+}
+export interface TrackerConfig {
+    enabled: boolean;
+    provider: "backlog";
+    spaceUrl: string;
+    project: string;
+    tokenEnv: string;
+    workflow: "waterfall" | "scrum";
+    mapping: {
+        statuses?: Partial<Record<"clarify" | "plan" | "build" | "wrap" | "done", number>>;
+        gateFieldId?: number;
+    };
+}
+export interface TaskDecision {
+    id: string;
+    label: string;
+    status: DecisionStatus;
+    resolution?: string;
+}
+export interface Evidence {
+    kind: "approval" | "spec" | "test" | "lint" | "review" | "diagnostic";
+    gate?: Gate;
+    area?: string;
+    source: string;
+    result: "pass" | "fail" | "skip";
+    detail?: string;
+    recordedAt: string;
+}
+export interface LessonRecord {
+    id: string;
+    taskId: string;
+    areas: string[];
+    summary: string;
+    prevention: string;
+    example: string;
+    promotion: string;
+    source: string;
+    recordedAt: string;
+}
+export interface LessonDisposition {
+    status: "captured" | "none";
+    reason?: string;
+    source: string;
+    recordedAt: string;
+}
+export interface TaskState {
+    id: string;
+    title: string;
+    type: "feature" | "bug" | "refactor" | "infra";
+    phase: Phase;
+    gate: Gate;
+    status: TaskStatus;
+    language: "vi" | "en";
+    risk: RiskLevel;
+    areas: string[];
+    branch: string;
+    artifacts: {
+        intent?: string;
+        design?: string;
+        workplan?: string;
+    };
+    decisions: TaskDecision[];
+    tasks: Array<{
+        id: string;
+        label: string;
+        status: "todo" | "in_progress" | "done" | "deferred";
+    }>;
+    evidence: Evidence[];
+    lessons?: LessonRecord[];
+    lessonDisposition?: LessonDisposition;
+    handoff?: {
+        kind: HandoffKind;
+        reason: string;
+        source: string;
+        recordedAt: string;
+    };
+    closure?: {
+        reason: string;
+        source: string;
+        recordedAt: string;
+    };
+    legacyG2Wait?: {
+        migratedAt: string;
+        source: string;
+    };
+    predecessorTaskId?: string;
+    successorTaskId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface WorkflowState {
+    schemaVersion: 1 | 2 | 3 | 4;
+    tasks: Record<string, TaskState>;
+    archive?: Record<string, ArchivedTaskSummary>;
+}
+export interface ArchivedTaskSummary {
+    id: string;
+    title: string;
+    type: TaskState["type"];
+    phase: Phase;
+    gate: Gate;
+    status: "done" | "closed" | "superseded";
+    risk: RiskLevel;
+    areas: string[];
+    record: string;
+    digest: string;
+    lessonCount: number;
+    predecessorTaskId?: string;
+    successorTaskId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LessonIndexEntry {
+    id: string;
+    taskId: string;
+    areas: string[];
+    summary: string;
+    prevention: string;
+    source: string;
+    recordedAt: string;
+}
+export interface LessonIndex {
+    schemaVersion: 1;
+    sourceDigest: string;
+    lessons: LessonIndexEntry[];
+}
+export interface AgenticMemoryEntry {
+    id: string;
+    summary: string;
+    guidance: string;
+    areas: string[];
+    phases: Array<Exclude<Phase, "done"> | "*">;
+    priority: number;
+    sourceTaskId: string;
+    sourceLessonId: string;
+    approvedBy: string;
+    approvedAt: string;
+}
+export interface AgenticMemoryRegistry {
+    schemaVersion: 1;
+    entries: AgenticMemoryEntry[];
+    retired: Array<AgenticMemoryEntry & {
+        retiredBy: string;
+        retiredAt: string;
+        reason: string;
+    }>;
+}
+export interface ManifestInventoryItem {
+    hash: string;
+    owner: string;
+    strategy: "replace" | "managed-block";
+}
+export interface WorkflowManifest {
+    schemaVersion: 2;
+    packageVersion: string;
+    workflow: "AI-DLC";
+    source: "local-package-assets";
+    remoteUpdates: false;
+    managedBy: "aidlc-workflow";
+    adapters: AgentId[];
+    files: Record<string, ManifestInventoryItem>;
+}
+export interface Diagnostic {
+    level: "ERROR" | "WARN" | "INFO";
+    code: string;
+    message: string;
+}

package/dist/src/model.js

@@ -0,0 +1 @@
+export {};

package/dist/src/profiles.d.ts

@@ -0,0 +1,28 @@
+import type { McpConfig, Profile, ProjectConfig, RiskLevel } from "./model.js";
+export declare const builtInProfiles: Readonly<Record<string, Profile>>;
+export declare const validateProfile: (value: unknown, label?: string) => Profile;
+export declare const defaultConfig: () => ProjectConfig;
+export declare const loadProjectConfig: (root: string) => ProjectConfig;
+export declare const resolveProfiles: (root: string, ids: string[]) => Profile[];
+export declare const resolveEffectiveConfig: (root: string, config: ProjectConfig) => {
+    profiles: Profile[];
+    discovery: {
+        roots: string[];
+        workspaceMarkers: string[];
+    };
+    specs: {
+        roots: string[];
+    };
+    commands: any;
+    rules: {
+        include: string[];
+    };
+    risk: {
+        default: RiskLevel;
+    };
+    context: {
+        maxChars: number;
+    };
+    mcp: McpConfig;
+};
+export declare const includedRuleFiles: (root: string, patterns: string[]) => string[];

package/dist/src/profiles.js

@@ -0,0 +1,216 @@
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+const profile = (id, markers = []) => ({
+    schemaVersion: 1,
+    id: `topology/${id}`,
+    topology: id,
+    discovery: { roots: ["."], workspaceMarkers: markers },
+    specs: { roots: [] },
+    commands: {},
+    rules: { include: [] }
+});
+export const builtInProfiles = Object.freeze({
+    "topology/generic": profile("generic"),
+    "topology/single": profile("single"),
+    "topology/workspace": profile("workspace", ["package.json", "pnpm-workspace.yaml", "lerna.json"]),
+    "topology/git-submodules": profile("git-submodules", [".gitmodules"])
+});
+const object = (value, label) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+};
+const strings = (value, label) => {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
+        throw new Error(`${label} must be a string array`);
+    return value;
+};
+const command = (value, label) => {
+    const item = object(value, label);
+    if (typeof item.command !== "string" || !item.command || isAbsolute(item.command))
+        throw new Error(`${label}.command must be a non-absolute executable name`);
+    return { command: item.command, args: strings(item.args ?? [], `${label}.args`) };
+};
+const commands = (value, label) => {
+    if (value === undefined)
+        return {};
+    return Object.fromEntries(Object.entries(object(value, label)).map(([key, item]) => [key, command(item, `${label}.${key}`)]));
+};
+const safeRelative = (path, label) => {
+    const cleaned = normalize(path);
+    if (isAbsolute(cleaned) || cleaned === ".." || cleaned.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`))
+        throw new Error(`${label} must stay inside the project`);
+    return cleaned;
+};
+const tracker = (value) => {
+    if (value === undefined)
+        return undefined;
+    const item = object(value, "config.tracker");
+    if (item.enabled === false)
+        return undefined;
+    if (item.enabled !== true || item.provider !== "backlog" || typeof item.spaceUrl !== "string" || !/^https:\/\/[^/]+\/?$/.test(item.spaceUrl) || typeof item.project !== "string" || !item.project.trim() || typeof item.tokenEnv !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(item.tokenEnv) || !["waterfall", "scrum"].includes(String(item.workflow)))
+        throw new Error("config.tracker must be a complete enabled Backlog configuration");
+    const mapping = object(item.mapping ?? {}, "config.tracker.mapping");
+    const statuses = mapping.statuses === undefined ? undefined : object(mapping.statuses, "config.tracker.mapping.statuses");
+    const statusValues = statuses ? Object.fromEntries(Object.entries(statuses).map(([phase, id]) => {
+        if (!["clarify", "plan", "build", "wrap", "done"].includes(phase) || !Number.isInteger(id) || Number(id) < 1)
+            throw new Error("config.tracker.mapping.statuses is invalid");
+        return [phase, Number(id)];
+    })) : undefined;
+    if (mapping.gateFieldId !== undefined && (!Number.isInteger(mapping.gateFieldId) || Number(mapping.gateFieldId) < 1))
+        throw new Error("config.tracker.mapping.gateFieldId is invalid");
+    return { enabled: true, provider: "backlog", spaceUrl: item.spaceUrl.replace(/\/$/, ""), project: item.project, tokenEnv: item.tokenEnv, workflow: item.workflow, mapping: { ...(statusValues ? { statuses: statusValues } : {}), ...(mapping.gateFieldId === undefined ? {} : { gateFieldId: mapping.gateFieldId }) } };
+};
+const mcp = (value) => {
+    if (value === undefined)
+        return { enabled: false };
+    const item = object(value, "config.mcp");
+    if (item.enabled === false)
+        return { enabled: false };
+    if (item.enabled !== true || typeof item.endpoint !== "string" || !/^https?:\/\//.test(item.endpoint) || typeof item.workspace !== "string" || !item.workspace.trim())
+        throw new Error("config.mcp.enabled requires endpoint and workspace");
+    if (item.tokenEnv !== undefined && (typeof item.tokenEnv !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(item.tokenEnv)))
+        throw new Error("config.mcp.tokenEnv is invalid");
+    if (item.pollMs !== undefined && (!Number.isInteger(item.pollMs) || Number(item.pollMs) < 1_000 || Number(item.pollMs) > 3_600_000))
+        throw new Error("config.mcp.pollMs must be an integer from 1000 to 3600000");
+    const providers = item.providers === undefined ? undefined : strings(item.providers, "config.mcp.providers");
+    if (providers?.some((provider) => !["jira", "trello", "github-issues"].includes(provider)))
+        throw new Error("config.mcp.providers is invalid");
+    return { enabled: true, endpoint: item.endpoint, workspace: item.workspace, ...(item.tokenEnv === undefined ? {} : { tokenEnv: item.tokenEnv }), ...(item.pollMs === undefined ? {} : { pollMs: Number(item.pollMs) }), ...(providers === undefined ? {} : { providers: providers }) };
+};
+export const validateProfile = (value, label = "profile") => {
+    const item = object(value, label);
+    if (item.schemaVersion !== 1 || typeof item.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/.test(item.id) || typeof item.topology !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/.test(item.topology))
+        throw new Error(`${label} has an unsupported schema, id, or topology`);
+    const discovery = item.discovery === undefined ? undefined : object(item.discovery, `${label}.discovery`);
+    const specs = item.specs === undefined ? undefined : object(item.specs, `${label}.specs`);
+    const rules = item.rules === undefined ? undefined : object(item.rules, `${label}.rules`);
+    return {
+        schemaVersion: 1,
+        id: item.id,
+        extends: item.extends === undefined ? [] : strings(item.extends, `${label}.extends`),
+        topology: item.topology,
+        discovery: discovery ? {
+            roots: strings(discovery.roots ?? [], `${label}.discovery.roots`).map((path) => safeRelative(path, `${label}.discovery.roots`)),
+            workspaceMarkers: strings(discovery.workspaceMarkers ?? [], `${label}.discovery.workspaceMarkers`).map((path) => safeRelative(path, `${label}.discovery.workspaceMarkers`))
+        } : undefined,
+        specs: specs ? { roots: strings(specs.roots ?? [], `${label}.specs.roots`).map((path) => safeRelative(path, `${label}.specs.roots`)) } : undefined,
+        commands: commands(item.commands, `${label}.commands`),
+        rules: rules ? { include: strings(rules.include ?? [], `${label}.rules.include`).map((path) => safeRelative(path, `${label}.rules.include`)) } : undefined
+    };
+};
+export const defaultConfig = () => ({
+    schemaVersion: 2,
+    extends: ["topology/single"],
+    specs: { roots: [] },
+    commands: {},
+    rules: { include: [] },
+    risk: { default: "normal" },
+    context: { maxChars: 16_000 },
+    agentState: {},
+    mcp: { enabled: false }
+});
+export const loadProjectConfig = (root) => {
+    const path = join(resolve(root), ".agents/config.json");
+    if (!existsSync(path))
+        return defaultConfig();
+    const item = object(JSON.parse(readFileSync(path, "utf8")), ".agents/config.json");
+    const risk = object(item.risk ?? {}, "config.risk");
+    const context = object(item.context ?? {}, "config.context");
+    const levels = ["low", "normal", "high", "regulated"];
+    const riskDefault = String(risk.default ?? "normal");
+    if (![1, 2, 3].includes(Number(item.schemaVersion)) || !levels.includes(riskDefault))
+        throw new Error("Unsupported project config schema or risk level");
+    const agentStateRaw = object(item.agentState ?? {}, "config.agentState");
+    const agentState = Object.fromEntries(Object.entries(agentStateRaw).map(([id, mode]) => {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id) || (mode !== "native" && mode !== "scripted"))
+            throw new Error("config.agentState must map adapter ids to native or scripted");
+        return [id, mode];
+    }));
+    const maxChars = Number(context.maxChars ?? 16_000);
+    if (!Number.isInteger(maxChars) || maxChars < 4_000 || maxChars > 128_000)
+        throw new Error("context.maxChars must be an integer from 4000 to 128000");
+    return {
+        schemaVersion: Number(item.schemaVersion),
+        extends: strings(item.extends ?? ["topology/single"], "config.extends"),
+        specs: { roots: strings(object(item.specs ?? {}, "config.specs").roots ?? [], "config.specs.roots").map((entry) => safeRelative(entry, "config.specs.roots")) },
+        commands: commands(item.commands, "config.commands"),
+        rules: { include: strings(object(item.rules ?? {}, "config.rules").include ?? [], "config.rules.include").map((entry) => safeRelative(entry, "config.rules.include")) },
+        risk: { default: riskDefault },
+        context: { maxChars },
+        agentState,
+        tracker: tracker(item.tracker),
+        mcp: mcp(item.mcp)
+    };
+};
+const readLocalProfile = (root, id) => {
+    const path = join(resolve(root), ".agents/project/profiles", safeRelative(id, "profile id"), "profile.json");
+    if (!existsSync(path))
+        return undefined;
+    if (lstatSync(path).isSymbolicLink() || !realpathSync(path).startsWith(`${realpathSync(resolve(root))}${process.platform === "win32" ? "\\" : "/"}`))
+        throw new Error(`Profile escapes the project: ${id}`);
+    return validateProfile(JSON.parse(readFileSync(path, "utf8")), id);
+};
+export const resolveProfiles = (root, ids) => {
+    const resolved = [];
+    const visiting = new Set();
+    const visit = (id) => {
+        const resolvedId = builtInProfiles[id] ? id : builtInProfiles[`topology/${id}`] ? `topology/${id}` : id;
+        if (resolved.some((entry) => entry.id === resolvedId))
+            return;
+        if (visiting.has(resolvedId))
+            throw new Error(`Profile cycle detected at ${resolvedId}`);
+        visiting.add(resolvedId);
+        const current = builtInProfiles[resolvedId] ?? readLocalProfile(root, resolvedId);
+        if (!current)
+            throw new Error(`Unknown profile: ${id}`);
+        for (const parent of current.extends ?? [])
+            visit(parent);
+        visiting.delete(resolvedId);
+        resolved.push(current);
+    };
+    ids.forEach(visit);
+    return resolved;
+};
+const stable = (values) => [...new Set(values)];
+export const resolveEffectiveConfig = (root, config) => {
+    const profiles = resolveProfiles(root, config.extends);
+    return {
+        profiles,
+        discovery: { roots: stable(profiles.flatMap((item) => item.discovery?.roots ?? ["."])), workspaceMarkers: stable(profiles.flatMap((item) => item.discovery?.workspaceMarkers ?? [])) },
+        specs: { roots: stable([...profiles.flatMap((item) => item.specs?.roots ?? []), ...config.specs.roots]) },
+        commands: Object.assign({}, ...profiles.map((item) => item.commands ?? {}), config.commands),
+        rules: { include: stable([...profiles.flatMap((item) => item.rules?.include ?? []), ...config.rules.include]) },
+        risk: config.risk,
+        context: config.context,
+        mcp: config.mcp
+    };
+};
+export const includedRuleFiles = (root, patterns) => {
+    const project = resolve(root);
+    const realProject = realpathSync(project);
+    const inside = (path) => {
+        if (lstatSync(path).isSymbolicLink())
+            return false;
+        return realpathSync(path).startsWith(`${realProject}${process.platform === "win32" ? "\\" : "/"}`);
+    };
+    const files = new Set();
+    for (const pattern of patterns) {
+        const safe = safeRelative(pattern, "rule include");
+        if (safe.endsWith("/*.md")) {
+            const directory = join(project, safe.slice(0, -5));
+            if (existsSync(directory) && inside(directory))
+                for (const entry of readdirSync(directory)) {
+                    const path = join(directory, entry);
+                    if (entry.endsWith(".md") && existsSync(path) && inside(path))
+                        files.add(path);
+                }
+        }
+        else {
+            const target = join(project, safe);
+            if (existsSync(target) && inside(target))
+                files.add(target);
+        }
+    }
+    return [...files].filter((path) => dirname(path).startsWith(project) || path.startsWith(project)).sort();
+};

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

@@ -0,0 +1,2 @@
+import type { PlannedWrite } from "./model.js";
+export declare const planProjectLayoutMigration: (project: string, plan: PlannedWrite[]) => void;

package/dist/src/project-migration.js

@@ -0,0 +1,144 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { resolveProjectPath } from "./project-path.js";
+const safePath = (root, relative) => resolveProjectPath(root, relative, "Unsafe migration path");
+const legacyReference = (value) => {
+    if (value === ".aidlc/config.json")
+        return ".agents/config.json";
+    if (value === ".aidlc/index")
+        return ".agents/index";
+    if (value.startsWith(".aidlc/index/"))
+        return `.agents/data/index/${value.slice(".aidlc/index/".length)}`;
+    if (value === ".aidlc")
+        return ".agents/project";
+    if (value.startsWith(".aidlc/"))
+        return `.agents/project/${value.slice(".aidlc/".length)}`;
+    return value;
+};
+const rewriteStrings = (value) => Array.isArray(value) ? value.map((entry) => typeof entry === "string" ? legacyReference(entry) : entry) : value;
+const rewriteKnownJson = (relative, content) => {
+    const isConfig = relative === "config.json";
+    const isProfile = /^profiles\/.+\/profile\.json$/.test(relative);
+    const isAdapter = /^adapters\/.+\/adapter\.json$/.test(relative);
+    if (!isConfig && !isProfile && !isAdapter)
+        return undefined;
+    const source = content.toString("utf8");
+    const value = JSON.parse(source);
+    const before = JSON.stringify(value);
+    if (isConfig || isProfile) {
+        const discovery = value.discovery;
+        const specs = value.specs;
+        const rules = value.rules;
+        if (discovery) {
+            discovery.roots = rewriteStrings(discovery.roots);
+            discovery.workspaceMarkers = rewriteStrings(discovery.workspaceMarkers);
+        }
+        if (specs)
+            specs.roots = rewriteStrings(specs.roots);
+        if (rules)
+            rules.include = rewriteStrings(rules.include);
+    }
+    if (isAdapter) {
+        value.detect = rewriteStrings(value.detect);
+        if (Array.isArray(value.files))
+            for (const file of value.files) {
+                if (file && typeof file === "object" && typeof file.path === "string") {
+                    file.path = legacyReference(file.path);
+                }
+            }
+    }
+    const changed = before !== JSON.stringify(value);
+    return { content: changed ? `${JSON.stringify(value, null, 2)}\n` : source, changed };
+};
+const migrationPayload = (relative, source) => {
+    const rewritten = rewriteKnownJson(relative, source);
+    return rewritten ? { content: rewritten.content } : { content: source.toString("base64"), contentEncoding: "base64" };
+};
+const payloadBuffer = (item) => item.contentEncoding === "base64" ? Buffer.from(item.content, "base64") : Buffer.from(item.content, "utf8");
+const legacyDestination = (relative) => {
+    if (relative === "config.json")
+        return ".agents/config.json";
+    if (relative === "index")
+        return ".agents/index";
+    if (relative.startsWith("index/"))
+        return `.agents/data/index/${relative.slice("index/".length)}`;
+    return `.agents/project/${relative}`;
+};
+const planMigrationFile = (project, plan, sourcePath, destinationPath, legacyRelative) => {
+    const source = safePath(project, sourcePath);
+    const payload = migrationPayload(legacyRelative, readFileSync(source));
+    const destination = safePath(project, destinationPath);
+    const existingPlan = plan.find((item) => item.path === destinationPath);
+    const destinationContent = existingPlan && ["update", "migrate"].includes(existingPlan.action)
+        ? payloadBuffer(existingPlan)
+        : existsSync(destination) && lstatSync(destination).isFile() ? readFileSync(destination) : undefined;
+    if (existsSync(destination) && !lstatSync(destination).isFile()) {
+        plan.push({ path: destinationPath, owner: "aidlc-project", ownershipClass: "project", content: "", action: "conflict", reason: `legacy migration destination is not a regular file: ${sourcePath}` });
+        return;
+    }
+    if (destinationContent) {
+        if (!destinationContent.equals(payloadBuffer(payload))) {
+            plan.push({ path: destinationPath, owner: "aidlc-project", ownershipClass: "project", ...payload, action: "conflict", reason: `legacy source differs from existing destination: ${sourcePath}` });
+            return;
+        }
+    }
+    else if (existingPlan?.action === "create") {
+        if (existingPlan.ownershipClass === "managed" && !payloadBuffer(existingPlan).equals(payloadBuffer(payload))) {
+            Object.assign(existingPlan, { action: "conflict", reason: `legacy managed file differs from the new managed content: ${sourcePath}` });
+            return;
+        }
+        Object.assign(existingPlan, payload, { action: "migrate", reason: `migrate legacy project file from ${sourcePath}` });
+    }
+    else {
+        plan.push({ path: destinationPath, owner: "aidlc-project", ownershipClass: "project", ...payload, action: "migrate", reason: `migrate legacy project file from ${sourcePath}` });
+    }
+    if (!plan.some((item) => item.path === sourcePath && item.action === "delete")) {
+        plan.push({ path: sourcePath, owner: "aidlc-project", ownershipClass: "project", content: "", action: "delete", reason: `remove migrated legacy project file after creating ${destinationPath}` });
+    }
+};
+const planLegacyTreeMigration = (project, plan) => {
+    const legacyRoot = safePath(project, ".aidlc");
+    if (!existsSync(legacyRoot))
+        return;
+    if (lstatSync(legacyRoot).isSymbolicLink() || !lstatSync(legacyRoot).isDirectory()) {
+        plan.push({ path: ".aidlc", owner: "aidlc-project", ownershipClass: "project", content: "", action: "conflict", reason: "legacy migration root must be a real directory" });
+        return;
+    }
+    const visit = (directory, prefix = "") => {
+        for (const entry of readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+            const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const sourcePath = `.aidlc/${relative}`;
+            if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) {
+                plan.push({ path: sourcePath, owner: "aidlc-project", ownershipClass: "project", content: "", action: "conflict", reason: "legacy migration refuses symlink or special filesystem entry" });
+            }
+            else if (entry.isDirectory())
+                visit(safePath(project, sourcePath), relative);
+            else
+                planMigrationFile(project, plan, sourcePath, legacyDestination(relative), relative);
+        }
+    };
+    visit(legacyRoot);
+};
+const planExistingConfigRewrite = (project, plan) => {
+    const path = ".agents/config.json";
+    const target = safePath(project, path);
+    if (!existsSync(target))
+        return;
+    const rewritten = rewriteKnownJson("config.json", readFileSync(target));
+    if (!rewritten?.changed)
+        return;
+    const item = plan.find((candidate) => candidate.path === path);
+    if (item)
+        Object.assign(item, { content: rewritten.content, action: "migrate", reason: "rewrite legacy .aidlc references in canonical project config" });
+};
+const planLegacyIndexMigration = (project, plan) => {
+    for (const name of ["repo-map.md", "specs-index.md"]) {
+        const source = `.agents/data/state/${name}`;
+        if (existsSync(safePath(project, source)))
+            planMigrationFile(project, plan, source, `.agents/data/index/${name}`, `index/${name}`);
+    }
+};
+export const planProjectLayoutMigration = (project, plan) => {
+    planExistingConfigRewrite(project, plan);
+    planLegacyTreeMigration(project, plan);
+    planLegacyIndexMigration(project, plan);
+};

package/dist/src/project-path.d.ts

@@ -0,0 +1,2 @@
+export declare const resolveProjectPath: (root: string, path: string, escapeMessage: string) => string;
+export declare const resolveProjectPathWithoutSymlinks: (root: string, path: string, escapeMessage: string, symlinkMessage: string) => string;

package/dist/src/project-path.js

@@ -0,0 +1,20 @@
+import { existsSync, lstatSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+export const resolveProjectPath = (root, path, escapeMessage) => {
+    const project = resolve(root);
+    const target = resolve(project, path);
+    const fromRoot = relative(project, target);
+    if (!path || isAbsolute(path) || fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot))
+        throw new Error(`${escapeMessage}: ${path}`);
+    return target;
+};
+export const resolveProjectPathWithoutSymlinks = (root, path, escapeMessage, symlinkMessage) => {
+    const target = resolveProjectPath(root, path, escapeMessage);
+    let cursor = resolve(root);
+    for (const part of relative(cursor, target).split(sep).filter(Boolean)) {
+        cursor = join(cursor, part);
+        if (existsSync(cursor) && lstatSync(cursor).isSymbolicLink())
+            throw new Error(`${symlinkMessage}: ${path}`);
+    }
+    return target;
+};