@felixdotgo/aidlc-kit 0.1.0 → 0.2.0

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;
 };

package/dist/src/model/config-contracts.d.ts

@@ -0,0 +1,65 @@
+import type { AgentId, RiskLevel, StateMutationMode } from "./lifecycle-enums.js";
+import type { LoopConfig } from "./loop.js";
+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 {
+    $schema?: string;
+    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;
+    loop?: LoopConfig;
+}
+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;
+    };
+}

package/dist/src/model/config-contracts.js

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

package/dist/src/model/install-contracts.d.ts

@@ -0,0 +1,29 @@
+import type { AgentId } from "./lifecycle-enums.js";
+import type { LoopConfig } from "./loop.js";
+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;
+    loop?: LoopConfig;
+}

package/dist/src/model/install-contracts.js

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

package/dist/src/model/lifecycle-enums.d.ts

@@ -0,0 +1,13 @@
+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 Diagnostic {
+    level: "ERROR" | "WARN" | "INFO";
+    code: string;
+    message: string;
+}

package/dist/src/model/lifecycle-enums.js

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

package/dist/src/model/loop.d.ts

@@ -0,0 +1,20 @@
+export type LoopMode = "off" | "local" | "fleet";
+export declare const LOOP_PROVIDERS: readonly ["codex", "claude", "opencode"];
+export type LoopAgent = (typeof LOOP_PROVIDERS)[number];
+export interface LoopConfig {
+    mode: LoopMode;
+    agents?: {
+        lead: LoopAgent;
+        workers: Record<string, LoopAgent>;
+    };
+    workerImage?: Partial<Record<LoopAgent, string>>;
+    /** Local daemon canonical-state poll interval (1000–300000 ms). */
+    pollMs?: number;
+    /** Per-run lead loop limits; bounds mirror `validateLimits` in loop-runtime.mjs. */
+    limits?: LoopLimits;
+}
+export interface LoopLimits {
+    maxTurns?: number;
+    turnTimeoutMs?: number;
+    maxStallTurns?: number;
+}

package/dist/src/model/loop.js

@@ -0,0 +1 @@
+export const LOOP_PROVIDERS = Object.freeze(["codex", "claude", "opencode"]);

package/dist/src/model/manifest.d.ts

@@ -0,0 +1,16 @@
+import type { AgentId } from "./lifecycle-enums.js";
+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-kit" | "aidlc-workflow";
+    adapters: AgentId[];
+    files: Record<string, ManifestInventoryItem>;
+}

package/dist/src/model/manifest.js

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

package/dist/src/model/records.d.ts

@@ -0,0 +1,138 @@
+import type { DecisionStatus, Gate, HandoffKind, Phase, RiskLevel, TaskStatus } from "./lifecycle-enums.js";
+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;
+    featureId?: 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";
+        dependsOn?: string[];
+        ownedPaths?: string[];
+    }>;
+    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;
+    }>;
+}

package/dist/src/model/records.js

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