@felixdotgo/aidlc-kit 0.0.1

package/dist/src/tracker.d.ts

@@ -0,0 +1,29 @@
+import type { TrackerConfig } from "./model.js";
+export interface TrackerDiagnostic {
+    code: "TRACKER_DISABLED" | "TRACKER_AUTH" | "TRACKER_RATE_LIMIT" | "TRACKER_REQUEST";
+    message: string;
+    retryable: boolean;
+}
+export interface BacklogRequest {
+    method: "GET" | "PATCH";
+    path: string;
+    form?: Record<string, string | number>;
+}
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export type TrackerResolution = {
+    enabled: false;
+    diagnostic: TrackerDiagnostic;
+} | {
+    enabled: true;
+    config: TrackerConfig;
+    token: string;
+};
+export declare const resolveTracker: (config: TrackerConfig | undefined, environment?: NodeJS.ProcessEnv) => TrackerResolution;
+export declare const executeBacklog: (resolution: TrackerResolution, request: BacklogRequest, fetcher?: FetchLike) => Promise<{
+    ok: true;
+    body: unknown;
+} | {
+    ok: false;
+    diagnostic: TrackerDiagnostic;
+}>;
+export declare const gateUpdate: (config: TrackerConfig, issue: string, phase: "clarify" | "plan" | "build" | "wrap" | "done", idempotencyKey: string) => BacklogRequest;

package/dist/src/tracker.js

@@ -0,0 +1,41 @@
+export const resolveTracker = (config, environment = process.env) => {
+    if (!config)
+        return { enabled: false, diagnostic: { code: "TRACKER_DISABLED", message: "Tracker is not configured; Git-only mode is active.", retryable: false } };
+    const token = environment[config.tokenEnv];
+    if (!token)
+        return { enabled: false, diagnostic: { code: "TRACKER_DISABLED", message: `Backlog tracker is disabled because ${config.tokenEnv} is unavailable.`, retryable: false } };
+    return { enabled: true, config, token };
+};
+const form = (values) => {
+    const body = new URLSearchParams();
+    for (const [key, value] of Object.entries(values))
+        body.set(key, String(value));
+    return body;
+};
+export const executeBacklog = async (resolution, request, fetcher = fetch) => {
+    if (!resolution.enabled)
+        return { ok: false, diagnostic: resolution.diagnostic };
+    const response = await fetcher(`${resolution.config.spaceUrl}/api/v2/${request.path.replace(/^\//, "")}`, {
+        method: request.method,
+        headers: { Authorization: `Bearer ${resolution.token}`, ...(request.form ? { "Content-Type": "application/x-www-form-urlencoded" } : {}) },
+        body: request.form ? form(request.form) : undefined
+    });
+    if (response.status === 401)
+        return { ok: false, diagnostic: { code: "TRACKER_AUTH", message: "Backlog authentication failed; Git state was not changed.", retryable: false } };
+    if (response.status === 429)
+        return { ok: false, diagnostic: { code: "TRACKER_RATE_LIMIT", message: "Backlog rate limit reached; retry after the provider reset window.", retryable: true } };
+    if (!response.ok)
+        return { ok: false, diagnostic: { code: "TRACKER_REQUEST", message: `Backlog request failed with HTTP ${response.status}.`, retryable: response.status >= 500 } };
+    return { ok: true, body: await response.json() };
+};
+export const gateUpdate = (config, issue, phase, idempotencyKey) => {
+    const comment = `[aidlc:${idempotencyKey}] ${phase}`;
+    if (config.workflow === "waterfall") {
+        const statusId = config.mapping.statuses?.[phase];
+        if (!statusId)
+            throw new Error(`Backlog status mapping is required for Waterfall phase: ${phase}`);
+        return { method: "PATCH", path: `issues/${issue}`, form: { statusId, comment } };
+    }
+    const field = config.mapping.gateFieldId;
+    return { method: "PATCH", path: `issues/${issue}`, form: { ...(field ? { [`customField_${field}`]: phase } : {}), comment } };
+};

package/dist/src/upgrade.d.ts

@@ -0,0 +1,11 @@
+import type { FileSpec, PlannedWrite, WorkflowState } from "./model.js";
+export declare const migrateLegacyBoard: (root: string) => {
+    state: WorkflowState;
+    files: FileSpec[];
+};
+export declare const planUpgrade: (root: string) => PlannedWrite[];
+export interface UpgradeResult {
+    backup: string;
+    changed: number;
+}
+export declare const applyUpgrade: (root: string, plan: PlannedWrite[]) => UpgradeResult;

package/dist/src/upgrade.js

@@ -0,0 +1,270 @@
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { findAdapterForUpgrade, resolvedAdaptersForUpgrade } from "./adapters.js";
+import { managedContentHash, readManifest } from "./installer.js";
+import { legacyV021AdapterContents, legacyV021Hashes } from "./legacy.js";
+import { planProjectLayoutMigration } from "./project-migration.js";
+import { mergeManagedBlock } from "./managed-content.js";
+import { resolveProjectPath, resolveProjectPathWithoutSymlinks } from "./project-path.js";
+import { emptyState, prepareV4Migration, renderWorkplan, validateState } from "./state.js";
+import { contentHash, coreWorkflowFiles, initialProjectFiles, manifestSpec } from "./workflow.js";
+const safePath = (root, relative) => resolveProjectPath(root, relative, "Unsafe upgrade path");
+const assertNoSymlinkPath = (root, relative) => { resolveProjectPathWithoutSymlinks(root, relative, "Unsafe upgrade path", "Refusing to upgrade symlink path"); };
+const legacyManifest = (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-workflow" && (parsed.schemaVersion === 0 || parsed.schemaVersion === 1);
+    }
+    catch {
+        return false;
+    }
+};
+const parseFrontmatter = (content) => {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return {};
+    return Object.fromEntries(match[1].split("\n").flatMap((line) => {
+        const separator = line.indexOf(":");
+        return separator < 0 ? [] : [[line.slice(0, separator).trim(), line.slice(separator + 1).trim().replace(/^['"]|['"]$/g, "")]];
+    }));
+};
+const cells = (line) => line.split("|").slice(1, -1).map((cell) => cell.trim().replace(/^`|`$/g, ""));
+export const migrateLegacyBoard = (root) => {
+    const boardPath = join(resolve(root), ".agents/data/state/BOARD.md");
+    if (!existsSync(boardPath))
+        return { state: emptyState(), files: [] };
+    const state = emptyState();
+    const files = [];
+    const boardContent = readFileSync(boardPath, "utf8");
+    let migratedRows = 0;
+    for (const line of boardContent.split("\n")) {
+        if (!line.startsWith("|") || /^\|[- ]+\|/.test(line) || line.includes("| id |"))
+            continue;
+        const row = cells(line);
+        if (row.length < 8)
+            throw new Error("Legacy BOARD contains a malformed task row; refusing lossy migration");
+        const [id, title, phaseRaw, gateRaw, statusRaw, branch, areasRaw, doc] = row;
+        migratedRows += 1;
+        const oldDoc = safePath(root, doc);
+        const source = existsSync(oldDoc) ? readFileSync(oldDoc, "utf8") : "";
+        const frontmatter = parseFrontmatter(source);
+        const stableDir = `.agents/data/tasks/${id}`;
+        const prosePath = `${stableDir}/intent-design.md`;
+        const workplanPath = `${stableDir}/workplan.md`;
+        if (source)
+            files.push({ path: prosePath, owner: "aidlc-state", ownershipClass: "state", content: source });
+        const oldWorkplan = doc.replace(/\.md$/, ".workplan.md");
+        if (existsSync(safePath(root, oldWorkplan)))
+            files.push({ path: `${stableDir}/legacy-workplan.md`, owner: "aidlc-state", ownershipClass: "state", content: readFileSync(safePath(root, oldWorkplan), "utf8") });
+        const phase = ["clarify", "plan", "build", "wrap", "done"].includes(phaseRaw) ? phaseRaw : "clarify";
+        const gate = ["none", "G0_confirm", "G1_review", "G2_codereview"].includes(gateRaw) ? gateRaw : "G0_confirm";
+        const evidence = [];
+        const now = new Date().toISOString();
+        if (["plan", "build", "wrap", "done"].includes(phase))
+            evidence.push({ kind: "approval", gate: "G0_confirm", source: "legacy state migration", result: "pass", recordedAt: now });
+        if (["build", "wrap", "done"].includes(phase))
+            evidence.push({ kind: "approval", gate: "G1_review", source: "legacy state migration", result: "pass", recordedAt: now });
+        state.tasks[id] = {
+            id,
+            title,
+            type: (["feature", "bug", "refactor", "infra"].includes(frontmatter.type) ? frontmatter.type : "infra"),
+            phase,
+            gate,
+            status: (["active", "blocked_on_user", "paused", "done"].includes(statusRaw) ? statusRaw : "paused"),
+            language: frontmatter.language === "en" ? "en" : "vi",
+            risk: "normal",
+            areas: areasRaw.split(",").map((area) => area.trim()).filter(Boolean),
+            branch: branch || "—",
+            artifacts: { intent: source ? prosePath : undefined, design: source ? prosePath : undefined, workplan: workplanPath },
+            decisions: [],
+            tasks: [],
+            evidence: [...evidence, { kind: "diagnostic", source: "legacy state migration", result: "pass", detail: `Original artifacts preserved at ${doc}`, recordedAt: now }],
+            createdAt: now,
+            updatedAt: now
+        };
+    }
+    if (!migratedRows && !boardContent.includes("_No tasks in flight._"))
+        throw new Error("Legacy BOARD contains no recognizable task rows; refusing lossy migration");
+    for (const task of Object.values(state.tasks))
+        files.push({ path: task.artifacts.workplan, owner: "aidlc-state", ownershipClass: "state", content: renderWorkplan(task) });
+    validateState(state);
+    return { state, files };
+};
+const planManaged = (root, spec, installedHash, legacy) => {
+    const target = safePath(root, spec.path);
+    if (!existsSync(target))
+        return { ...spec, action: "create", reason: "new managed file" };
+    const current = readFileSync(target, "utf8");
+    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" };
+    if (installedHash && currentHash === installedHash)
+        return { ...spec, content: next, action: "update", reason: "unchanged managed file" };
+    const legacyAdapter = legacyV021AdapterContents[spec.path];
+    const legacyAdapterHash = legacyAdapter ? contentHash(spec.strategy === "managed-block" ? legacyAdapter.trimEnd() : legacyAdapter) : undefined;
+    if (legacy && (legacyV021Hashes[spec.path] === currentHash || legacyAdapterHash === currentHash))
+        return { ...spec, content: next, action: "update", reason: "recognized v0.2.1 baseline" };
+    if (spec.strategy === "managed-block" && current.includes(`<!-- aidlc-installer:${spec.owner} -->`))
+        return { ...spec, content: next, action: "conflict", reason: "managed prompt block was modified" };
+    return { ...spec, content: next, action: "conflict", reason: legacy ? "legacy core differs from known baseline" : "managed file differs from installed hash" };
+};
+export const planUpgrade = (root) => {
+    const project = resolve(root);
+    const installed = readManifest(project);
+    const legacy = !installed && legacyManifest(project);
+    if (!installed && !legacy)
+        throw new Error("No owned AI-DLC installation found. Use init instead of upgrade.");
+    const upgradeAdapters = resolvedAdaptersForUpgrade();
+    const requested = installed?.adapters?.length ? installed.adapters : upgradeAdapters.filter((adapter) => adapter.detect(project)).map((adapter) => adapter.id);
+    const selected = requested.filter((id) => findAdapterForUpgrade(id));
+    const agentFiles = selected.flatMap((id) => findAdapterForUpgrade(id)?.files() ?? []).map((file) => ({ ...file, ownershipClass: "managed" }));
+    const managed = [...coreWorkflowFiles(), ...agentFiles];
+    const plan = managed.map((spec) => planManaged(project, spec, installed?.files[spec.path]?.hash, legacy));
+    if (installed) {
+        for (const [path, item] of Object.entries(installed.files)) {
+            if (managed.some((spec) => spec.path === path))
+                continue;
+            const target = safePath(project, path);
+            if (!existsSync(target))
+                continue;
+            const current = readFileSync(target, "utf8");
+            const hash = managedContentHash({ owner: item.owner, strategy: item.strategy }, current);
+            plan.push({ path, owner: item.owner, strategy: item.strategy, ownershipClass: "managed", content: "", action: hash === item.hash ? "delete" : "conflict", reason: hash === item.hash ? "obsolete unchanged managed file" : "obsolete managed file was modified" });
+        }
+    }
+    for (const spec of initialProjectFiles()) {
+        if (legacy && spec.path === ".agents/data/state/aidlc-state.json" && !existsSync(safePath(project, spec.path)))
+            continue;
+        const target = safePath(project, spec.path);
+        plan.push(existsSync(target) ? { ...spec, content: readFileSync(target, "utf8"), action: "preserve", reason: `${spec.ownershipClass}-owned file` } : { ...spec, action: "create", reason: `new ${spec.ownershipClass}-owned file` });
+    }
+    const canonicalState = plan.find((item) => item.path === ".agents/data/state/aidlc-state.json");
+    if (canonicalState && canonicalState.action === "preserve") {
+        const parsed = JSON.parse(canonicalState.content);
+        const normalized = validateState(parsed);
+        if (parsed.schemaVersion === 1 || parsed.schemaVersion === 2 || parsed.schemaVersion === 3) {
+            const migration = prepareV4Migration(normalized);
+            canonicalState.content = `${JSON.stringify(migration.state, null, 2)}\n`;
+            canonicalState.action = "migrate";
+            canonicalState.reason = `migrate canonical state schema v${parsed.schemaVersion} to v4 compact catalog${migration.stamped.length ? ` and stamp pre-existing ready G2 waits: ${migration.stamped.join(", ")}` : " without changing task content"}`;
+            for (const record of migration.records) {
+                assertNoSymlinkPath(project, record.path);
+                const target = safePath(project, record.path);
+                if (!existsSync(target))
+                    plan.push({ path: record.path, owner: "aidlc-state", ownershipClass: "state", content: record.content, action: "migrate", reason: "write immutable terminal task record" });
+                else if (readFileSync(target, "utf8") !== record.content)
+                    plan.push({ path: record.path, owner: "aidlc-state", ownershipClass: "state", content: record.content, action: "conflict", reason: "terminal task record conflicts with prior canonical content" });
+            }
+            const lessonIndex = plan.find((item) => item.path === ".agents/data/lessons/index.json");
+            if (!lessonIndex)
+                throw new Error("Lesson index plan is missing");
+            lessonIndex.content = `${JSON.stringify(migration.lessonIndex, null, 2)}\n`;
+            lessonIndex.action = "migrate";
+            lessonIndex.reason = "build derived lesson index from canonical task records";
+        }
+    }
+    planProjectLayoutMigration(project, plan);
+    if (legacy && !existsSync(safePath(project, ".agents/data/state/aidlc-state.json"))) {
+        const migration = migrateLegacyBoard(project);
+        const compact = prepareV4Migration(migration.state);
+        plan.push({ path: ".agents/data/state/aidlc-state.json", owner: "aidlc-state", ownershipClass: "state", content: `${JSON.stringify(compact.state, null, 2)}\n`, action: "migrate", reason: "migrate legacy BOARD to canonical v4 state" });
+        for (const record of compact.records)
+            plan.push({ path: record.path, owner: "aidlc-state", ownershipClass: "state", content: record.content, action: "migrate", reason: "preserve legacy terminal task as immutable record" });
+        const lessonIndex = plan.find((item) => item.path === ".agents/data/lessons/index.json");
+        if (lessonIndex) {
+            lessonIndex.content = `${JSON.stringify(compact.lessonIndex, null, 2)}\n`;
+            lessonIndex.action = "migrate";
+            lessonIndex.reason = "build derived lesson index during legacy migration";
+        }
+        for (const file of migration.files)
+            plan.push({ ...file, action: "migrate", reason: "preserve legacy task prose in stable task directory" });
+    }
+    const boardPath = safePath(project, ".agents/data/state/BOARD.md");
+    if (existsSync(boardPath)) {
+        const stateItem = plan.find((item) => item.path === ".agents/data/state/aidlc-state.json");
+        if (!stateItem)
+            throw new Error("Canonical state must be present before removing legacy BOARD");
+        validateState(JSON.parse(stateItem.content));
+        plan.push({ path: ".agents/data/state/BOARD.md", owner: "aidlc-state", ownershipClass: "state", content: "", action: "delete", reason: "remove duplicate lifecycle-state projection after canonical JSON validation" });
+    }
+    const manifest = manifestSpec(managed, selected);
+    plan.push({ ...manifest, action: "update", reason: legacy ? "migrate manifest to schema v2" : "update manifest inventory" });
+    return plan;
+};
+export const applyUpgrade = (root, plan) => {
+    const conflicts = plan.filter((item) => item.action === "conflict");
+    if (conflicts.length)
+        throw new Error(`Upgrade has ${conflicts.length} conflict(s); no files were written`);
+    const project = resolve(root);
+    const id = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupRelative = `.agents/data/state/backups/upgrade-${id}`;
+    const backup = safePath(project, backupRelative);
+    const stage = safePath(project, `.agents/data/state/.upgrade-stage-${id}`);
+    const writes = plan.filter((item) => ["create", "update", "delete", "migrate"].includes(item.action));
+    mkdirSync(stage, { recursive: true });
+    const journal = [];
+    try {
+        for (const item of writes) {
+            const target = safePath(project, item.path);
+            assertNoSymlinkPath(project, item.path);
+            const existed = existsSync(target);
+            journal.push({ path: item.path, existed, action: item.action });
+            if (existed) {
+                const destination = join(backup, item.path);
+                mkdirSync(dirname(destination), { recursive: true });
+                copyFileSync(target, destination);
+            }
+            if (item.action !== "delete") {
+                const staged = join(stage, item.path);
+                mkdirSync(dirname(staged), { recursive: true });
+                writeFileSync(staged, item.contentEncoding === "base64" ? Buffer.from(item.content, "base64") : item.content);
+                if (item.path.endsWith(".json") && item.contentEncoding !== "base64")
+                    JSON.parse(item.content);
+            }
+        }
+        mkdirSync(backup, { recursive: true });
+        writeFileSync(join(backup, "journal.json"), `${JSON.stringify(journal, null, 2)}\n`, "utf8");
+        for (const item of writes) {
+            const target = safePath(project, item.path);
+            if (item.action === "delete")
+                rmSync(target, { force: true });
+            else {
+                mkdirSync(dirname(target), { recursive: true });
+                if (existsSync(target))
+                    rmSync(target, { force: true });
+                renameSync(join(stage, item.path), target);
+            }
+        }
+        const pruneEmpty = (directory) => {
+            if (!existsSync(directory) || !lstatSync(directory).isDirectory())
+                return;
+            for (const entry of readdirSync(directory, { withFileTypes: true }))
+                if (entry.isDirectory())
+                    pruneEmpty(join(directory, entry.name));
+            if (readdirSync(directory).length === 0)
+                rmdirSync(directory);
+        };
+        pruneEmpty(safePath(project, ".aidlc"));
+        rmSync(stage, { recursive: true, force: true });
+        return { backup: backupRelative, changed: writes.length };
+    }
+    catch (error) {
+        for (const entry of journal.reverse()) {
+            const target = safePath(project, entry.path);
+            const source = join(backup, entry.path);
+            if (entry.existed && existsSync(source)) {
+                mkdirSync(dirname(target), { recursive: true });
+                copyFileSync(source, target);
+            }
+            else if (!entry.existed)
+                rmSync(target, { force: true });
+        }
+        rmSync(stage, { recursive: true, force: true });
+        throw error;
+    }
+};

package/dist/src/workflow.d.ts

@@ -0,0 +1,7 @@
+import type { AgentId, FileSpec, WorkflowManifest } from "./model.js";
+export declare const contentHash: (content: string | Uint8Array) => string;
+export declare const coreWorkflowFiles: () => FileSpec[];
+export declare const initialProjectFiles: () => FileSpec[];
+export declare const manifestFor: (files: FileSpec[], adapters: AgentId[]) => WorkflowManifest;
+export declare const manifestSpec: (files: FileSpec[], adapters: AgentId[]) => FileSpec;
+export declare const packageVersion: () => string;

package/dist/src/workflow.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defaultConfig } from "./profiles.js";
+import { createLessonIndex, emptyMemoryRegistry, emptyState, lessonStateDigest } from "./state.js";
+const owner = "aidlc-core";
+const assetRoot = fileURLToPath(new URL("../assets/.agents", import.meta.url));
+const packageJson = JSON.parse(readFileSync(fileURLToPath(new URL("../../package.json", import.meta.url)), "utf8"));
+export const contentHash = (content) => createHash("sha256").update(content).digest("hex");
+const collect = (directory, target) => readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const source = join(directory, entry.name);
+    const destination = `${target}/${entry.name}`;
+    return entry.isDirectory() ? collect(source, destination) : [{ path: destination, content: readFileSync(source, "utf8"), owner, ownershipClass: "managed" }];
+});
+export const coreWorkflowFiles = () => [
+    ...collect(join(assetRoot, "aidlc"), ".agents/aidlc"),
+    ...collect(join(assetRoot, "skills"), ".agents/skills")
+];
+export const initialProjectFiles = () => [
+    { path: ".agents/config.json", owner: "aidlc-project", ownershipClass: "project", content: `${JSON.stringify(defaultConfig(), null, 2)}\n` },
+    { path: ".agents/data/state/aidlc-state.json", owner: "aidlc-state", ownershipClass: "state", content: `${JSON.stringify(emptyState(), null, 2)}\n` },
+    { path: ".agents/data/lessons/index.json", owner: "aidlc-state", ownershipClass: "state", content: `${JSON.stringify(createLessonIndex([], lessonStateDigest(emptyState())), null, 2)}\n` },
+    { path: ".agents/data/memory/agentic-memory.json", owner: "aidlc-memory", ownershipClass: "project", content: `${JSON.stringify(emptyMemoryRegistry(), null, 2)}\n` }
+];
+export const manifestFor = (files, adapters) => ({
+    schemaVersion: 2,
+    packageVersion: packageJson.version,
+    workflow: "AI-DLC",
+    source: "local-package-assets",
+    remoteUpdates: false,
+    managedBy: "aidlc-workflow",
+    adapters,
+    files: Object.fromEntries(files.filter((file) => file.ownershipClass === "managed" || !file.ownershipClass).map((file) => [file.path, {
+            hash: contentHash(file.strategy === "managed-block" ? file.content.trimEnd() : file.content),
+            owner: file.owner,
+            strategy: file.strategy ?? "replace"
+        }]))
+});
+export const manifestSpec = (files, adapters) => ({
+    path: ".agents/aidlc/manifest.json",
+    owner,
+    ownershipClass: "managed",
+    content: `${JSON.stringify(manifestFor(files, adapters), null, 2)}\n`
+});
+export const packageVersion = () => packageJson.version;

package/docs/README.md

@@ -0,0 +1,31 @@
+# Documentation
+
+Use this page to choose the guide that matches your role and next task.
+
+## For package users and operators
+
+1. Start with the repository [README](../README.md) to install the workflow.
+2. Read [Operating the workflow](./operating-workflow.md) before asking an agent to change a project.
+3. Use [Configuration](./configuration.md) to configure project rules, profiles, and Codex/Claude permissions.
+4. Keep [Command reference](./command-reference.md) nearby for safe CLI usage.
+5. Read [AI-DLC Coordination service](./coordination-service.md) before enabling remote canonical state.
+
+## For contributors and maintainers
+
+1. Begin with [Development](./development.md) for local setup and implementation boundaries.
+2. Use [Testing and release](./testing-and-release.md) for the verification and package-smoke workflow.
+3. Read [Architecture](./architecture.md) before changing package, installed-runtime, migration, or asset behaviour.
+
+## Documentation map
+
+| Page | Audience | Purpose |
+| --- | --- | --- |
+| [Operating the workflow](./operating-workflow.md) | Operators | Lifecycle, task state, human gates, and blocked work. |
+| [Configuration](./configuration.md) | Operators and maintainers | Project configuration, profile precedence, rules, and Codex/Claude permissions. |
+| [Command reference](./command-reference.md) | Operators | Package CLI commands, flags, previews, and safety limits. |
+| [Development](./development.md) | Contributors | Dependencies, source layout, local commands, and implementation rules. |
+| [Testing and release](./testing-and-release.md) | Maintainers | Test strategy, evaluator, package smoke test, and release checks. |
+| [Architecture](./architecture.md) | Contributors | Boundaries, dependency direction, and source-to-consumer flow. |
+| [AI-DLC Coordination service](./coordination-service.md) | Operators | Opt-in service deployment, state authority, and credential safety. |
+
+When a public command, configuration field, or installed layout changes, update the relevant guide and its validation in the same change.

package/docs/architecture.md

@@ -0,0 +1,72 @@
+# Architecture
+
+`aidlc-kit` is a single Node.js/TypeScript package that installs static AI-DLC workflow assets into another project. The package CLI is used for installation and human-authorised maintenance; an installed project runs the dependency-free workflow scripts locally.
+
+## Source-to-consumer flow
+
+```text
+assets/aidlc/ + skills/
+        │ build-assets.mjs
+        ▼
+dist/assets/.agents/ + dist/src/
+        │ package CLI: init / upgrade
+        ▼
+consumer project: .agents/aidlc/ + .agents/skills/ + project-owned .agents/data/
+```
+
+The distinction matters:
+
+- **Source layout** is this repository's editable `assets/aidlc/` and `skills/` tree.
+- **Bundle layout** is generated under `dist/assets/.agents/` for package publication.
+- **Installed layout** is written under a consumer project's `.agents/` directory.
+
+`dist/` is generated. Source assets and installed assets must remain behaviourally aligned through the bundle and package-smoke tests.
+
+## Module boundaries
+
+| Boundary | Modules | Responsibility |
+| --- | --- | --- |
+| CLI and installation | `src/cli.ts`, `src/installer.ts`, `src/workflow.ts`, `src/adapters.ts` | Parse commands, select adapters, plan deterministic writes, install managed assets, and expose local status/doctor checks. |
+| Lifecycle domain | `src/model.ts`, `src/state.ts`, `src/gate.ts`, `src/context.ts` | Validate canonical state, calculate transitions and gate readiness, and build bounded phase packets. |
+| Profiles and project integration | `src/profiles.ts`, `src/tracker.ts` | Resolve project configuration/profiles and optional tracker integration. |
+| Migration | `src/upgrade.ts`, `src/project-migration.ts`, `src/legacy.ts` | Plan and apply safe legacy-data and version-layout migration with audit backups. |
+| Shared file semantics | `src/project-path.ts`, `src/managed-content.ts` | Keep all paths inside the project, reject unsafe symlinks, and preserve managed-content ownership. |
+| Development evaluator | `dev/evaluator/` | Run repository-only evaluation; never expose evaluator assets through the published package CLI. |
+
+Dependencies flow inward: CLI, installation, and migration depend on lifecycle and shared helpers; lifecycle does not depend on installation; evaluator may provision an installation but is not part of published runtime behaviour.
+
+## Installed workflow runtime
+
+The installed kernel consists of contracts, templates, schemas, profiles, and dependency-free scripts under `.agents/aidlc/`. Thin adapter instructions connect a selected coding tool to that kernel. Project customisation belongs outside the kernel:
+
+| Location | Ownership | Purpose |
+| --- | --- | --- |
+| `.agents/aidlc/` | Package managed | Lifecycle contracts, schemas, and scripts. |
+| `.agents/data/` | Project owned | Canonical state, task artifacts, derived indexes, memory, and evidence. |
+| `.agents/project/` | Project owned | Local profiles, rules, and evaluation material. |
+
+The state machine enforces the lifecycle; gates require explicit human approval; evidence is append-only. Installed scripts remain usable without an `aidlc-workflow` executable or a duplicate board file.
+
+Installed entry points share a strict dependency-free argv parser. Parsing and command-shape validation precede root discovery, lock acquisition, and state reads. Explicit roots are validated project directories; implicit roots use nearest-ancestor `.agents/aidlc/` discovery and never fall back to writing beneath an arbitrary working directory.
+
+## Trust and safety boundaries
+
+- Workflow assets are local package assets. The manifest records `remoteUpdates: false`; status and doctor do not consult a registry.
+- Install/upgrade plans are conflict-first, path-contained, and reject unsafe symlink traversal.
+- Human-only upgrade is an intentional boundary: interactive confirmation is required and agents must not run or discover upgrades.
+- Only Codex and Claude Code adapters are installed. Codex uses trusted project-scoped `.codex/config.toml` and `.codex/rules/aidlc.rules`; Claude Code scopes lifecycle-script permission through its local settings and phase skills.
+- Project commands are configured as executable-and-argument arrays rather than opaque shell strings.
+- Canonical state, terminal records, and rendered workplans reject symlink traversal and use same-directory atomic replacement. Lock acquisition is guard-serialized, while release verifies the owner token directly so a contended guard cannot strand the owner's main lock.
+- The compact master catalog remains archive authority. Recovery can replace only a valid, unreferenced terminal orphan tied by `id` and `createdAt` to the still-active catalog task; referenced, malformed, and identity-conflicting records fail closed.
+
+## Change impact guide
+
+| If you change… | Also inspect… |
+| --- | --- |
+| A lifecycle/state rule | Installed scripts, schemas, gate/context rendering, runtime parity tests. |
+| An asset or adapter | Asset builder, package inventory, installer, adapter tests, tarball smoke test. |
+| A configuration/profile field | Validator, schema, effective-profile behaviour, documentation, and tests. |
+| Migration semantics | Upgrade plan/apply logic, path safety, transaction rollback, and migration tests. |
+| A public command | CLI parsing, README/setup guidance, command reference, and package tests. |
+
+Use this guide with [Development](./development.md) and [Testing and release](./testing-and-release.md) before changing a cross-cutting boundary.

package/docs/command-reference.md

@@ -0,0 +1,110 @@
+# Command reference
+
+All package commands operate on local files. The examples run version `0.0.1` through npm; `npx` may ask permission to fetch that package on first use. Replace `.` with the target project path when needed. For a source checkout, see the [development guide](./development.md).
+
+## `init`
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow init [path] [--agent <name[,name]> | --all] [--yes] [--dry-run] [--force]
+```
+
+Plans the installation, prints a preview, and then writes the workflow only after confirmation (or `--yes`). `--dry-run` prints the same plan without writing. If exactly one installed agent is detected, it can be selected automatically. In an interactive terminal, choose multiple agents with the checkbox prompt: use arrow keys to move, Space to toggle, A to toggle all, and Enter to confirm. For scripts and non-interactive terminals, use `--agent <name[,name]>` or `--all`.
+
+`--force` is for an intentional initial replacement of an unmanaged conflicting file. It is not an upgrade mechanism. If the project already has another workflow package version, use the human-run upgrade flow instead.
+
+## `status`
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow status [path]
+```
+
+Reports the installed version and local installation status. It does not query a registry.
+
+## `doctor`
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow doctor [path] [--strict]
+```
+
+Checks the local manifest, configuration, and canonical state. `--strict` turns compatibility warnings such as a legacy manifest into errors. It does not query a registry.
+
+## `profile validate`
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow profile validate [path]
+```
+
+Loads `.agents/config.json`, resolves its profile chain, and prints the effective profile order. Use it after changing `extends` or local profiles.
+
+## `uninstall`
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow uninstall [path] [--yes] [--dry-run]
+```
+
+Prints the removal plan before applying it. It removes eligible unchanged managed assets but preserves project configuration and state. Prefer `--dry-run` first when working in an existing project.
+
+## `mcp setup`
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow mcp setup [path] [--dry-run] [--yes] [--storage sqlite|postgres] [--deployment docker|remote] [--bind localhost|network] [--workspace <id>] [--poll-ms <n>] [--enable]
+```
+
+Previews the optional AI-DLC Coordination service configuration, then writes only after confirmation. Non-interactive use requires `--deployment`, `--storage`, `--bind`, and `--workspace`. It never starts Docker; `--enable` is explicit and remote mode has no local fallback. See [AI-DLC Coordination service](./coordination-service.md) for deployment and credential requirements.
+
+## `upgrade`
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow upgrade [path] [--dry-run]
+```
+
+Upgrade is deliberately human-only. The command rejects `--yes` and `--force`; applying it requires an interactive terminal and an exact typed confirmation of the package version. Interactive confirmations use the same styled terminal prompt as `init`. Agents must not run, preview, detect, or suggest package upgrades on their own.
+
+The upgrade plan handles supported legacy `.aidlc/` project data transactionally: identical paths are deduplicated, differing content or unsafe entries stop the plan, and an audit backup supports rollback. Review the preview before an authorised human applies it.
+
+## Installed lifecycle scripts
+
+After `init`, task lifecycle commands live in the target project, not in the package CLI:
+
+```sh
+node .agents/aidlc/scripts/state.mjs task list --limit 20
+node .agents/aidlc/scripts/state.mjs task find --query "<words>" --include-archive
+node .agents/aidlc/scripts/state.mjs task show <task-id>
+node .agents/aidlc/scripts/state.mjs task next <task-id>
+node .agents/aidlc/scripts/task-next.mjs <task-id> --require-stop
+node .agents/aidlc/scripts/gate-view.mjs <task-id>
+```
+
+Installed lifecycle options may appear before or after positionals and accept both `--name value` and `--name=value`. Unknown, duplicate, command-irrelevant, missing-value, and surplus positional arguments are rejected before state I/O. Boolean options such as `--all`, `--include-archive`, and `--require-stop` do not accept values. When a literal value begins with `--`, use the equals form so it is not confused with a missing value.
+
+An explicit `--root <path>` wins and must identify a directory containing `.agents/`. Without `--root`, the runtime walks upward from the current working directory and selects the nearest ancestor containing `.agents/aidlc/`. If no installed-workflow marker exists, the command fails without creating local state. Manual calls from a nested directory need an absolute or upward-relative script path so Node can locate the entry point. Runtime-generated actions always include both an absolute script path and an absolute `--root`, so they remain executable from any working directory.
+
+Every `state.mjs` and `task-next.mjs` command prints one JSON envelope: `{ok: true, result, nextAction?}`. `result` carries the command payload (a mutated command nests it as `{task, ...extra}`; a read returns the read object), and `nextAction` is present whenever the command is task-scoped. Task-less commands (`memory list|promote|retire`, `lesson rebuild|search`, `state migrate`, `task list|find`) return no `nextAction`. A success envelope may additionally carry `warnings: [{code, message, hint?}]` when the mutation persisted but a derived step failed afterwards — `LESSON_INDEX_STALE` (lesson-index rebuild) or `RENDER_FAILED` (workplan render); the mutation is committed and the exit code stays `0`, so callers follow the warning hint instead of retrying the mutation, while the explicit repair commands (`lesson rebuild`, `render.mjs`) and `state migrate` still fail loudly. Failures print a one-line `{ok: false, error: {message, hint?}}` on stderr — never a stack trace. Exit codes are typed: `0` success, `1` expected validation or gate error, `2` the continuation guard, `3` an unexpected crash. Callers must execute `run_phase` actions immediately; a successful mutation is not permission to stop. In build, the action includes `itemId`, `remainingItems`, and an item-focused context command while work remains, and every embedded command carries an explicit `--root` so it runs from any working directory.
+
+`task-next.mjs --require-stop` prints the current action plus a machine-readable `continuation` object in the stdout envelope — `{required, code, taskId, classification}` and, when work remains, `command`, `reason`, `itemId`, and `remainingItems` — and exits `2` when the classification is `run_phase`. The first stderr line is `CONTINUATION_REQUIRED: {json}` carrying the same task id, command, and reason (followed by an explicit "expected pause, not a failure" note); it is a local guard against a premature final response, and the caller must execute `continuation.command` instead of replying. It exits normally (`continuation.code = STOP_ALLOWED`) for a valid human gate, durable blocker, terminal outcome, or completion. The guard is detection at the package boundary: it cannot technically intercept a message a model host has already emitted, so hosts recover by running `task next <task-id>` in the next turn and executing its command. `task status ... --status blocked_on_user` fails instead of persisting when the current gate is not ready, and `gate-view.mjs` only renders tasks already in that validated status.
+
+Human approval is a dedicated atomic operation:
+
+```sh
+node .agents/aidlc/scripts/state.mjs gate approve <task-id> --gate <gate> --source "<explicit approval>"
+```
+
+`--source` is audit provenance, not authentication or proof of consent. The host agent must invoke this command only in a later user turn that explicitly approves the gate currently presented.
+
+`evidence add` accepts `spec`, `test`, `lint`, `review`, and `diagnostic`; it rejects `approval`. An evidence `--area` must belong to the task's affected areas, and multi-area test or lint evidence must name its area. `task status` accepts `active`, `blocked_on_user`, and `paused` (`done` is not a status command; finish with `task transition --to done` or `task archive`), and rejects `blocked_on_user` at wrap, which has no human gate. Every route out of a validated `blocked_on_user` wait, including `paused`, requires audited `--reason` and `--source` metadata and appends diagnostic evidence; entering `paused` from `active` requires the same audited `--mode audited --reason --source` triple and appends a `Paused while active` diagnostic, while resuming `paused → active` needs no audit metadata. Repair bounds are machine-enforced: the third failed verify record per area, or the second failed review record, in the current build flips `nextAction` to `blocked` and adds a `REPAIR_BOUND` error to the G2 gate check. Normal phase advancement uses `gate approve`, and wrap completion uses `task transition --to done` or `task archive <task-id> --reason "<reason>" --source "<source>"`, which applies the same transition checks and appends an `Archive to done` diagnostic. The low-level transition escape hatch is intentionally noisy, records diagnostic evidence, still applies all transition checks, and requires audit metadata:
+
+```sh
+node .agents/aidlc/scripts/state.mjs task transition <task-id> --to <phase> --mode audited --reason "<reason>" --source "<source>"
+```
+
+Self-transitions are rejected, and `task create` rejects an id that collides case-insensitively with an existing task or archive record. `task create` also fails while any other task is actionable (`nextAction` classification `run_phase`); the error lists the actionable task ids and the exact `--switch-from <ids>` acknowledgement. Passing that flag — only with explicit user direction to switch — records a resume-marker diagnostic on each acknowledged task and never pauses, closes, or otherwise mutates its lifecycle; the acknowledged task remains the authoritative resume target. After a G1 reopen, all non-deferred execution items return to `todo`; prior G2, verification, and review evidence cannot satisfy the new build boundary, and repair-bound counters reset with it.
+
+State writes and generated workplans use symlink-checked atomic replacement. State-lock release is owner-token checked and never removes a replacement owner's lock. If a process stops after writing a terminal archive record but before committing the catalog, a retry replaces that orphan only when the persisted catalog still contains the same active task identity and does not reference an archive record; malformed, referenced, or identity-conflicting records fail closed.
+
+Promoting an agent-memory candidate requires traceable source records and an explicit approver:
+
+```sh
+node .agents/aidlc/scripts/state.mjs memory promote <memory-id> --summary "<summary>" --guidance "<guidance>" --source-task <task-id> --source-lesson <lesson-id> --approved-by "<human>"
+```
+
+Use [Operating the workflow](./operating-workflow.md) for gates, approvals, handoffs, and task ownership.