@felixdotgo/aidlc-kit 0.1.0 → 0.1.1

package/README.md

@@ -2,7 +2,10 @@
 
 `@felixdotgo/aidlc-kit` installs an AI-DLC workflow into an existing project. The workflow gives coding agents a shared task lifecycle, dependency-aware work, explicit human review gates, and project-owned state and rules. The normal lead runs in your Codex, Claude Code, or OpenCode conversation; an optional coordination service supports workers on multiple machines.
 
-Workflow assets are bundled with the package, `remoteUpdates` is `false`, and normal status checks never contact a registry. Fleet execution is opt-in and uses a separately deployed service. The optional end-to-end loop is also opt-in: select a mode during `init` or a human-run `upgrade`, then start it explicitly with `aidlc-workflow loop start` — selecting a mode never starts or approves anything by itself.
+Workflow assets are bundled with the package, `remoteUpdates` is `false`, and normal status checks never contact a registry. Fleet execution is opt-in and uses a separately deployed service. The optional end-to-end loop is also opt-in: select a mode during `init` or a human-run `upgrade`, then start it explicitly with `aidlc-kit loop start` — selecting a mode never starts or approves anything by itself.
+
+> [!WARNING]
+> The optional end-to-end loop and the AI-DLC Coordination service are **experimental and unfinished**: they contain known bugs and rough edges. The package is pre-1.0 (`0.x`), so their CLI flags, `loop.*`/`mcp.*` configuration fields, environment variables, and installed layouts can change incompatibly in any release before `1.0.0`.
 
 ## Requirements
 
@@ -15,11 +18,11 @@ Workflow assets are bundled with the package, `remoteUpdates` is `false`, and no
 Run these commands from your existing project's directory to preview the installation, then apply it:
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow init . --agent codex --dry-run
-npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow init . --agent codex --yes
+npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit init . --agent codex --dry-run
+npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit init . --agent codex --yes
 ```
 
-`npx` may ask permission to download the package on first use. These examples pin version `0.0.1`. After installation, the project's lifecycle scripts run locally without `npx` or a registry connection.
+`npx` may ask permission to download the package on first use. These examples pin version `0.1.1`. After installation, the project's lifecycle scripts run locally without `npx` or a registry connection.
 
 Use the adapter that matches the coding tool:
 
@@ -34,8 +37,8 @@ Use `--all` to install every supported adapter. Codex installs workspace-write s
 Confirm the installed project locally:
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow status .
-npx --package @felixdotgo/aidlc-kit@0.0.1 aidlc-workflow doctor . --strict
+npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit status .
+npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit doctor . --strict
 ```
 
 ## Documentation
@@ -55,6 +58,13 @@ The detailed documentation is organised by task and audience:
 
 Only a human may initiate or apply a workflow upgrade. `upgrade` rejects `--yes` and `--force`, requires an interactive terminal, and asks the human to type the target package version. See the [command reference](./docs/command-reference.md#upgrade) before changing an existing installation.
 
+## Recent changes
+
+- Synced the two committed ESM lifecycle cores so `lifecycle-core-conformance` passes.
+- Normalized Git path scopes (trailing slashes stripped) consistently across fleet, local-worker, and snapshot flows; directory scopes now work in all three.
+- Hardened the state lock to reclaim partially written (corrupt) lock files instead of wedging mutations.
+- Made the fleet end-to-end test skip cleanly when its Docker worker image is unavailable.
+
 ## License
 
 MIT

package/dist/assets/.agents/aidlc/schemas/manifest.schema.json

@@ -5,7 +5,7 @@
   "required": ["schemaVersion", "packageVersion", "workflow", "source", "remoteUpdates", "managedBy", "adapters", "files"],
   "properties": {
     "schemaVersion": { "const": 2 }, "packageVersion": { "type": "string" }, "workflow": { "const": "AI-DLC" },
-    "source": { "const": "local-package-assets" }, "remoteUpdates": { "const": false }, "managedBy": { "const": "aidlc-workflow" },
+    "source": { "const": "local-package-assets" }, "remoteUpdates": { "const": false }, "managedBy": { "const": "aidlc-kit" },
     "adapters": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } },
     "files": { "type": "object", "additionalProperties": { "type": "object", "required": ["hash", "owner", "strategy"], "properties": { "hash": { "type": "string" }, "owner": { "type": "string" }, "strategy": { "enum": ["replace", "managed-block"] } } } }
   }

package/dist/assets/.agents/aidlc/scripts/lib/context-runtime.mjs

@@ -1,3 +1,7 @@
+/**
+ * Context packet compiler: assembles the phase packet (task state, rules,
+ * agentic memory, spec traceability) consumed by the lead and workers.
+ */
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
 import { loadMemoryRegistry, nextAction, selectAgenticMemory } from "./store.mjs";
@@ -209,6 +213,7 @@ const requiredEvidence = (task) => task.evidence.filter((item, index, entries) =
   return !entries.slice(index + 1).some((candidate) => `${candidate.kind}:${candidate.area ?? ""}:${candidate.gate ?? ""}` === key);
 }).map(({ detail, ...item }) => item);
 
+/** Compiles a phase context packet (task state, rules, memory, spec traceability). */
 export const compileContext = (root, task, phase = task.phase, options = {}) => {
   if (!["clarify", "plan", "build", "wrap", "done"].includes(phase)) throw new Error(`Unsupported phase: ${phase}`);
   const config = loadConfig(root);

package/dist/assets/.agents/aidlc/scripts/lib/loop-drivers.mjs

@@ -1,3 +1,7 @@
+/**
+ * Agent driver adapters: preflight, turn execution, and provider-specific
+ * command construction for codex/claude/opencode.
+ */
 import { spawn } from "node:child_process";
 import { accessSync, constants } from "node:fs";
 import { delimiter, join } from "node:path";
@@ -35,7 +39,7 @@ export async function preflightAgentAdapter(name, { env = process.env, root } =
   const adapter = adapters.get(name);
   if (!adapter) throw new Error(`Unknown agent adapter: ${name}`);
   const paths = (env.PATH ?? process.env.PATH ?? "").split(delimiter);
-  if (!paths.some((entry) => { try { accessSync(join(entry || ".", adapter.command), constants.X_OK); return true; } catch { return false; } })) throw new Error(`Worker provider CLI is unavailable: ${name}`);
+  if (!paths.some((entry) => { try { accessSync(join(entry || ".", adapter.command), constants.X_OK); return true; } catch { return false; } /* intentional: missing/unreadable executable is treated as unavailable */ })) throw new Error(`Worker provider CLI is unavailable: ${name}`);
   if (adapter.preflight) await adapter.preflight({ env, root });
 }
 registerAgentAdapter("codex", {
@@ -102,6 +106,7 @@ registerAgentAdapter("opencode", {
  * redacted error message.
  */
 export async function runAgentTurn({ agent, root, sessionId, prompt, timeoutMs, onSessionId, onEvent, signal, env, spawnProcess = spawn } = {}) {
+  // --- Validate inputs and resolve the adapter -------------------------------
   const adapter = adapters.get(agent);
   if (!adapter) throw new Error(`agent must be ${LOOP_PROVIDER_LIST} or a trusted registered adapter`);
   if (typeof root !== "string" || !root) throw new Error("root must be a nonempty path");

package/dist/assets/.agents/aidlc/scripts/lib/loop-fleet.mjs

@@ -1,3 +1,7 @@
+/**
+ * Fleet coordination: job reconciliation, coordinator loop, and worker loop
+ * for multi-host AI-DLC execution.
+ */
 import { createHash, randomUUID } from "node:crypto";
 import { readyTaskItems, formatGateView } from "./store.mjs";
 import { isLoopProvider, LOOP_PROVIDER_LIST } from "./loop-drivers.mjs";
@@ -116,6 +120,7 @@ export async function runFleetCoordinator({ repository, taskId, ownerId = random
   for (const workerId of workerIds) assertId(workerId, "worker ID");
   if (workerProviders !== undefined && (!workerProviders || typeof workerProviders !== "object" || Array.isArray(workerProviders) || Object.keys(workerProviders).length !== workerIds.length || workerIds.some((workerId) => !isLoopProvider(workerProviders[workerId])) || Object.keys(workerProviders).some((workerId) => !workerIds.includes(workerId)))) throw new Error(`workerProviders must map each configured worker ID to ${LOOP_PROVIDER_LIST}`);
   const limits = validateFleetLimits(inputLimits);
+  // --- Validate limits and normalize inputs ---------------------------------
   integer(pollMs, "pollMs", 300000);
   const pickupTimeoutMs = integer(inputPickupTimeout ?? limits.leaseMs, "pickupTimeoutMs", 3_600_000);
   const readTask = required(repository, "readTask");
@@ -234,6 +239,7 @@ export async function runFleetWorker({ repository, workerId = randomUUID(), work
   assertId(workerId, "worker ID");
   if (workerAgent !== undefined && !isLoopProvider(workerAgent)) throw new Error(`workerAgent must be ${LOOP_PROVIDER_LIST}`);
   const limits = validateFleetLimits(inputLimits);
+  // --- Validate limits and bind adapter methods ------------------------------
   const claimJob = required(repository, "claimJob");
   const renewJob = required(repository, "renewJob");
   const checkpointJob = required(repository, "checkpointJob");

package/dist/assets/.agents/aidlc/scripts/lib/loop-git.mjs

@@ -1,3 +1,7 @@
+/**
+ * Git handoff helpers: create lead/worker/isolated worktrees, sync the
+ * integration branch, and produce scoped change reports.
+ */
 import { createHash, randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync } from "node:fs";
@@ -30,9 +34,9 @@ function validPath(value, label = "path") {
 }
 function scopes(input) {
   if (!Array.isArray(input) || input.length === 0) throw new Error("Assignment requires nonempty ownedPaths");
-  return [...new Set(input.map((path) => validPath(path, "owned path")))].sort();
+  return [...new Set(input.map((path) => validPath(path, "owned path").replace(/\/+$/, "")))].filter(Boolean).sort();
 }
-function inScope(path, ownedPaths) { return ownedPaths.some((scope) => path === scope || (scope.endsWith("/") && path.startsWith(scope))); }
+function inScope(path, ownedPaths) { return ownedPaths.some((scope) => path === scope || path.startsWith(`${scope}/`)); }
 function changedPaths(root, base, head) {
   const raw = execFileSync("git", ["diff", "--no-renames", "--name-only", "-z", base, head], { cwd: root, encoding: "buffer", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
   return raw.toString("utf8").split("\0").filter(Boolean).map((path) => validPath(path, "changed path")).sort();
@@ -72,7 +76,7 @@ function fetchBranch(root, remote, branch) {
   return git(root, "rev-parse", remoteRef(remote, branch));
 }
 function ancestor(root, base, head) {
-  try { git(root, "merge-base", "--is-ancestor", base, head); return true; } catch { return false; }
+  try { git(root, "merge-base", "--is-ancestor", base, head); return true; } catch { return false; } /* intentional: non-git/non-worktree is treated as not clean */
 }
 function assertClean(root) {
   if (git(root, "status", "--porcelain=v1", "--untracked-files=all")) throw new Error("Git worktree must be clean before handoff or integration");
@@ -87,6 +91,7 @@ function normaliseReport(job) {
 
 /** The coordinator calls this from its protected integration checkout. */
 export function createLeadGitHandoff({ root: inputRoot, integrationBranch, remote = "origin", agent = "codex" }) {
+  // --- Validate inputs and resolve the integration checkout ------------------
   const root = resolve(inputRoot);
   validBranch(integrationBranch); validId(remote, "remote");
   if (!isLoopProvider(agent)) throw new Error("Invalid worker agent");

package/dist/assets/.agents/aidlc/scripts/lib/loop-local-workers.mjs

@@ -37,6 +37,7 @@ export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, workt
   if (!Number.isSafeInteger(maxTurns) || maxTurns < 1 || maxTurns > 1000 || !Number.isSafeInteger(maxStallTurns) || maxStallTurns < 1 || maxStallTurns > 20) throw new Error("Invalid worker turn or stall limit");
   const ids = new Set(), workers = new Set(), scopes = [];
   for (const job of jobs) {
+    if (Array.isArray(job.ownedPaths)) job.ownedPaths = [...new Set(job.ownedPaths.map((path) => (typeof path === "string" ? path.replace(/\/+$/, "") : path)).filter((path) => path))];
     if (!identifier(job.itemId) || !identifier(job.workerId) || !isLoopProvider(job.agent) || typeof job.prompt !== "string" || !job.prompt.trim() || !Array.isArray(job.ownedPaths) || !job.ownedPaths.length || job.ownedPaths.length > 64 || !job.ownedPaths.every(safePath)) throw new Error("Invalid local job");
     if (ids.has(job.itemId) || workers.has(job.workerId)) throw new Error("Items and workers must be distinct within a batch");
     ids.add(job.itemId); workers.add(job.workerId);

package/dist/assets/.agents/aidlc/scripts/lib/loop-runtime.mjs

@@ -1,3 +1,7 @@
+/**
+ * Local loop runtime: record management, checkpointing, turn orchestration,
+ * and pause/resume handling for a single lead.
+ */
 import { createHash, randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -152,6 +156,7 @@ function outputStop(record, action, gateView) { return { taskId: record.taskId,
 
 export async function runLoop({ root: rootInput, taskId, agent, mode = "run", limits: limitInput, driver, onEvent = () => {}, preflight = false, precondition }) {
   const root = validateRoot(rootInput);
+  // --- Validate mode and load/create the loop record -------------------------
   let record = readLoopRecord(root, taskId);
   if (mode === "run") {
     if (record) throw new Error(`Loop record already exists for ${taskId}; use resume`);
@@ -187,7 +192,8 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
     record.lastFingerprint = initial.digest;
     record.checkpoint = checkpoint(current.task, current.action, initial.tree, record.iteration);
     record.status = "running"; record.stopReason = null; record.updatedAt = iso(); writeLoopRecord(root, record);
-    for (;;) {
+    // --- Main turn loop --------------------------------------------------------
+  for (;;) {
       const kind = classifyAction(current.action);
       if (kind !== "run_phase") {
         record.status = kind === "await_user" ? "gate" : kind;

package/dist/assets/.agents/aidlc/scripts/lib/loop-worker-snapshot.mjs

@@ -51,13 +51,14 @@ export function createWorkerSnapshot(source, destination, trackedPaths) {
 
 /** Validate the complete stopped-worker snapshot before host integration. */
 export function inspectWorkerSnapshot(destination, baseline, scopes) {
-  if (!(baseline instanceof Map) || !Array.isArray(scopes) || !scopes.length || !scopes.every(scopePath)) throw new Error('Invalid snapshot baseline or scopes');
+  const normalizedScopes = (Array.isArray(scopes) ? scopes : []).map((scope) => (typeof scope === "string" ? scope.replace(/\/+$/, "") : scope)).filter((scope) => scope);
+  if (!(baseline instanceof Map) || !normalizedScopes.length || !normalizedScopes.every(scopePath)) throw new Error('Invalid snapshot baseline or scopes');
   const root = realpathSync(destination), current = inventory(root, false);
   const changed = [];
   for (const path of new Set([...baseline.keys(), ...current.keys()])) {
     const before = baseline.get(path), after = current.get(path);
     if (!before || !after || before.digest !== after.digest || before.executable !== after.executable) {
-      if (!scopePath(path) || !within(path, scopes)) throw new Error(`Worker changed a path outside its scope: ${path}`);
+      if (!scopePath(path) || !within(path, normalizedScopes)) throw new Error(`Worker changed a path outside its scope: ${path}`);
       changed.push(path);
     }
   }

package/dist/assets/.agents/aidlc/scripts/lib/store.mjs

@@ -29,7 +29,7 @@ const lockRecord = (path) => {
   try {
     const value = JSON.parse(readFileSync(path, "utf8"));
     return typeof value.token === "string" && Number.isInteger(value.pid) && value.pid > 0 && Number.isFinite(value.createdAt) ? value : undefined;
-  } catch { return undefined; }
+  } catch { return undefined; } /* intentional: unreadable record is treated as absent */
 };
 const processAlive = (pid) => {
   try { process.kill(pid, 0); return true; }
@@ -361,7 +361,7 @@ export const renderWorkplan = (task) => { const decisions = task.decisions.lengt
 export const renderViews = (root, state = loadState(root), selected = Object.values(state.tasks)) => { for (const task of selected) { if (!task.artifacts.workplan) continue; assertNoSymlinkPath(root, task.artifacts.workplan); writeAtomic(join(resolve(root), task.artifacts.workplan), renderWorkplan(task)); } };
 
 const safeArtifactTarget = (root, path) => { assertNoSymlinkPath(root, path); return join(resolve(root), path); };
-const artifactContent = (root, path) => { if (!path) return undefined; try { const target = safeArtifactTarget(root, path); return existsSync(target) ? readFileSync(target, "utf8") : undefined; } catch { return undefined; } };
+const artifactContent = (root, path) => { if (!path) return undefined; try { const target = safeArtifactTarget(root, path); return existsSync(target) ? readFileSync(target, "utf8") : undefined; } catch { return undefined; } /* intentional: unreadable/unsafe artifact is treated as absent */ };
 const artifactDiagnostics = (root, task, names) => names.flatMap((name) => { const path = task.artifacts[name]; if (!path) return [{ level: "ERROR", code: "ARTIFACT_REFERENCE", message: `${name} artifact is not referenced` }]; try { return existsSync(safeArtifactTarget(root, path)) ? [] : [{ level: "ERROR", code: "ARTIFACT_MISSING", message: `${path} does not exist` }]; } catch (error) { return [{ level: "ERROR", code: "ARTIFACT_UNSAFE", message: error instanceof Error ? error.message : String(error) }]; } });
 export const checkGate = (root, state, taskId, gate) => { const task = state.tasks[taskId]; if (!task) return [{ level: "ERROR", code: "TASK_UNKNOWN", message: `Unknown active task: ${taskId}` }]; const diagnostics = []; if (task.gate !== gate) diagnostics.push({ level: "ERROR", code: "GATE_STATE", message: `Task is at ${task.gate}, not ${gate}` }); if (["closed", "superseded"].includes(task.status)) diagnostics.push({ level: "ERROR", code: "TASK_TERMINAL", message: `Terminal task cannot approve ${gate}` }); if (task.handoff) diagnostics.push({ level: "ERROR", code: "TASK_HANDOFF", message: `Task has unresolved handoff: ${task.handoff.reason}` }); if (task.id !== taskId) diagnostics.push({ level: "ERROR", code: "TASK_ID", message: "Task key and id differ" }); if (!task.title.trim() || !task.areas.length) diagnostics.push({ level: "ERROR", code: "TASK_FIELDS", message: "Task title and affected areas are required" }); if (gate === "G0_confirm") { diagnostics.push(...artifactDiagnostics(root, task, ["intent"])); const content = artifactContent(root, task.artifacts.intent); if (content !== undefined) for (const heading of ["## 📋 Problem", "## 🗺️ Affected areas", "## 💭 Assumptions", "## ❓ Open questions", "## 🎯 Scope"]) if (!content.includes(heading)) diagnostics.push({ level: "ERROR", code: "INTENT_HEADING", message: `Intent is missing ${heading}` }); } if (gate === "G1_review") { diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"])); diagnostics.push(...transitionDiagnostics(task, "build").filter((item) => item.code === "UNRESOLVED_DECISION")); const content = artifactContent(root, task.artifacts.design); if (content !== undefined) for (const heading of ["## 🧩 Solution per affected area", "## 📌 Spec traceability", "## 🔗 Cross-service contracts", "## ⚠️ Risks / edge cases"]) if (!content.includes(heading)) diagnostics.push({ level: "ERROR", code: "DESIGN_HEADING", message: `Design is missing ${heading}` }); } if (gate === "G2_codereview") { diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"])); if (task.tasks.some((item) => !["done", "deferred"].includes(item.status))) diagnostics.push({ level: "ERROR", code: "TASKS_OPEN", message: "Build tasks remain open" }); for (const area of task.areas) if (!hasAreaVerification(task, area)) diagnostics.push({ level: "ERROR", code: "VERIFY_EVIDENCE", message: `Latest post-G1 verification evidence must pass for affected area: ${area}` }); if (!hasReview(task)) diagnostics.push({ level: "ERROR", code: "REVIEW_EVIDENCE", message: "Latest post-G1 code-review evidence must pass" }); const bounds = repairBounds(task); if (!isLegacyG2Wait(task) && (bounds.verifyExhausted || bounds.reviewExhausted)) diagnostics.push({ level: "ERROR", code: "REPAIR_BOUND", message: "Repair bound exhausted; record a durable handoff instead of presenting G2" }); } if (!diagnostics.length) diagnostics.push({ level: "INFO", code: "GATE_OK", message: `${gate} checks passed for ${taskId}` }); return diagnostics; };
 const gateTarget = { G0_confirm: "plan", G1_review: "build", G2_codereview: "wrap" };

package/dist/assets/.agents/aidlc/scripts/remote-state.mjs

@@ -69,6 +69,7 @@ export const runRemoteState = async (argv, client, root, git = {}) => {
   if (!extra && ["task item", "decision set", "lesson record"].includes(route)) throw new Error(`${route} requires an item/decision/lesson id`);
 
   const current = await client.get();
+  // --- Read-only routes ------------------------------------------------------
   if (!Number.isSafeInteger(current?.revision) || !current?.state?.tasks) throw new Error("Remote coordination returned invalid canonical state");
   const state = current.state;
   const previous = state.tasks[id];
@@ -100,6 +101,7 @@ export const runRemoteState = async (argv, client, root, git = {}) => {
     return { ok: true, result: await client.snapshot(current.revision, id, gate, reviewText, integrationCommit) };
   }
 
+  // --- Mutating routes -------------------------------------------------------
   let task;
   if (route === "task create") {
     if (previous || state.archive?.[id]) throw new Error(`Task already exists: ${id}`);

package/dist/assets/.agents/aidlc/scripts/state.mjs

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+/**
+ * AI-DLC lifecycle CLI. Parses argv, dispatches to the canonical state module,
+ * and emits the JSON result with the nextAction for the lead.
+ */
 import { acquireStateLock, approveAndAdvance, checkGate, closeTask, failEntry, handoffTask, listTaskSummaries, loadMemoryRegistry, loadState, loadTask, migrateState, nextAction, option, parseArguments, promoteAgenticMemory, rebuildLessonIndex, recordLesson, recordNoLessons, renderViews, reopenTask, retireAgenticMemory, rootOption, saveState, searchLessons, supersedeTask, transitionTask, validateArguments } from "./lib/runtime.mjs";
 import { readLiveLease } from "./lib/loop-lease.mjs";
 import { listFeatures, loadFeature, readyFeatureTasks, saveFeature } from "./lib/feature-store.mjs";

package/dist/services/aidlc-coordination/src/lifecycle-core.mjs

@@ -29,7 +29,7 @@ const lockRecord = (path) => {
   try {
     const value = JSON.parse(readFileSync(path, "utf8"));
     return typeof value.token === "string" && Number.isInteger(value.pid) && value.pid > 0 && Number.isFinite(value.createdAt) ? value : undefined;
-  } catch { return undefined; }
+  } catch { return undefined; } /* intentional: unreadable record is treated as absent */
 };
 const processAlive = (pid) => {
   try { process.kill(pid, 0); return true; }
@@ -361,7 +361,7 @@ export const renderWorkplan = (task) => { const decisions = task.decisions.lengt
 export const renderViews = (root, state = loadState(root), selected = Object.values(state.tasks)) => { for (const task of selected) { if (!task.artifacts.workplan) continue; assertNoSymlinkPath(root, task.artifacts.workplan); writeAtomic(join(resolve(root), task.artifacts.workplan), renderWorkplan(task)); } };
 
 const safeArtifactTarget = (root, path) => { assertNoSymlinkPath(root, path); return join(resolve(root), path); };
-const artifactContent = (root, path) => { if (!path) return undefined; try { const target = safeArtifactTarget(root, path); return existsSync(target) ? readFileSync(target, "utf8") : undefined; } catch { return undefined; } };
+const artifactContent = (root, path) => { if (!path) return undefined; try { const target = safeArtifactTarget(root, path); return existsSync(target) ? readFileSync(target, "utf8") : undefined; } catch { return undefined; } /* intentional: unreadable/unsafe artifact is treated as absent */ };
 const artifactDiagnostics = (root, task, names) => names.flatMap((name) => { const path = task.artifacts[name]; if (!path) return [{ level: "ERROR", code: "ARTIFACT_REFERENCE", message: `${name} artifact is not referenced` }]; try { return existsSync(safeArtifactTarget(root, path)) ? [] : [{ level: "ERROR", code: "ARTIFACT_MISSING", message: `${path} does not exist` }]; } catch (error) { return [{ level: "ERROR", code: "ARTIFACT_UNSAFE", message: error instanceof Error ? error.message : String(error) }]; } });
 export const checkGate = (root, state, taskId, gate) => { const task = state.tasks[taskId]; if (!task) return [{ level: "ERROR", code: "TASK_UNKNOWN", message: `Unknown active task: ${taskId}` }]; const diagnostics = []; if (task.gate !== gate) diagnostics.push({ level: "ERROR", code: "GATE_STATE", message: `Task is at ${task.gate}, not ${gate}` }); if (["closed", "superseded"].includes(task.status)) diagnostics.push({ level: "ERROR", code: "TASK_TERMINAL", message: `Terminal task cannot approve ${gate}` }); if (task.handoff) diagnostics.push({ level: "ERROR", code: "TASK_HANDOFF", message: `Task has unresolved handoff: ${task.handoff.reason}` }); if (task.id !== taskId) diagnostics.push({ level: "ERROR", code: "TASK_ID", message: "Task key and id differ" }); if (!task.title.trim() || !task.areas.length) diagnostics.push({ level: "ERROR", code: "TASK_FIELDS", message: "Task title and affected areas are required" }); if (gate === "G0_confirm") { diagnostics.push(...artifactDiagnostics(root, task, ["intent"])); const content = artifactContent(root, task.artifacts.intent); if (content !== undefined) for (const heading of ["## 📋 Problem", "## 🗺️ Affected areas", "## 💭 Assumptions", "## ❓ Open questions", "## 🎯 Scope"]) if (!content.includes(heading)) diagnostics.push({ level: "ERROR", code: "INTENT_HEADING", message: `Intent is missing ${heading}` }); } if (gate === "G1_review") { diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"])); diagnostics.push(...transitionDiagnostics(task, "build").filter((item) => item.code === "UNRESOLVED_DECISION")); const content = artifactContent(root, task.artifacts.design); if (content !== undefined) for (const heading of ["## 🧩 Solution per affected area", "## 📌 Spec traceability", "## 🔗 Cross-service contracts", "## ⚠️ Risks / edge cases"]) if (!content.includes(heading)) diagnostics.push({ level: "ERROR", code: "DESIGN_HEADING", message: `Design is missing ${heading}` }); } if (gate === "G2_codereview") { diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"])); if (task.tasks.some((item) => !["done", "deferred"].includes(item.status))) diagnostics.push({ level: "ERROR", code: "TASKS_OPEN", message: "Build tasks remain open" }); for (const area of task.areas) if (!hasAreaVerification(task, area)) diagnostics.push({ level: "ERROR", code: "VERIFY_EVIDENCE", message: `Latest post-G1 verification evidence must pass for affected area: ${area}` }); if (!hasReview(task)) diagnostics.push({ level: "ERROR", code: "REVIEW_EVIDENCE", message: "Latest post-G1 code-review evidence must pass" }); const bounds = repairBounds(task); if (!isLegacyG2Wait(task) && (bounds.verifyExhausted || bounds.reviewExhausted)) diagnostics.push({ level: "ERROR", code: "REPAIR_BOUND", message: "Repair bound exhausted; record a durable handoff instead of presenting G2" }); } if (!diagnostics.length) diagnostics.push({ level: "INFO", code: "GATE_OK", message: `${gate} checks passed for ${taskId}` }); return diagnostics; };
 const gateTarget = { G0_confirm: "plan", G1_review: "build", G2_codereview: "wrap" };

package/dist/src/adapters.js

@@ -1,3 +1,8 @@
+/**
+ * Coding-tool adapters. Each adapter describes the managed prompt blocks, config
+ * files, and skill files installed for one supported coding tool (Claude, Codex,
+ * OpenCode). The `instruction` text is shared verbatim across adapters.
+ */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 const hasManagedBlock = (root, path, owner) => {
@@ -10,13 +15,15 @@ const hasManagedBlock = (root, path, owner) => {
     }
     catch {
         return false;
-    }
+    } /* intentional: an unreadable prompt file is treated as not containing the block */
 };
+/** Builds a managed prompt block for one adapter-owned file. */
 const adapterFile = (owner, path, body) => ({
     path,
     owner,
     content: `<!-- aidlc-installer:${owner}:start -->\n${body}<!-- aidlc-installer:${owner}:end -->\n`
 });
+/** Shared AI-DLC instruction text installed into each tool's primary prompt file. */
 const instruction = (agent, adapter) => [
     `# AI-DLC for ${agent}`,
     "",

package/dist/src/cli.js

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
 import { stdin, stdout } from "node:process";
 import { spawnSync } from "node:child_process";
-import { resolve } from "node:path";
+import { resolve, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { join } from "node:path";
 import { installableAdapters } from "./adapters.js";
 import { applyPlan, detectedAgents, doctor, formatPlan, planInit, planUninstall, selectAgents, status } from "./installer.js";
 import { LOOP_PROVIDERS } from "./model.js";
@@ -22,12 +21,14 @@ const usage = `Usage:
   npx @felixdotgo/aidlc-kit mcp setup [path] [--dry-run] [--yes] [--storage sqlite|postgres] [--deployment docker|remote] [--bind localhost|network] [--workspace <id>] [--poll-ms <n>] [--enable]`;
 const interactive = () => Boolean(stdin.isTTY && stdout.isTTY);
 const prompts = async () => import("@inquirer/prompts");
+/* --- Argv helpers --------------------------------------------------------- */
 const value = (args, name) => {
     const index = args.indexOf(name);
     return index < 0 ? undefined : args[index + 1];
 };
 const flags = (args) => new Set(args.filter((item) => item.startsWith("--")));
 const valueFlags = new Set(["--agent", "--storage", "--deployment", "--bind", "--workspace", "--poll-ms", "--token-env", "--providers", "--loop-mode", "--loop-lead", "--loop-workers"]);
+const COMMAND_KEYWORDS = ["init", "upgrade", "uninstall", "status", "doctor", "validate", "run", "list"];
 const positional = (args) => {
     const result = [];
     for (let index = 0; index < args.length; index += 1) {
@@ -40,7 +41,18 @@ const positional = (args) => {
     }
     return result;
 };
-const rootArg = (args, fallback = ".") => positional(args).find((item) => !["init", "upgrade", "uninstall", "status", "doctor", "validate", "run", "list"].includes(item)) ?? fallback;
+const rootArg = (args, fallback = ".") => positional(args).find((item) => !COMMAND_KEYWORDS.includes(item)) ?? fallback;
+/* --- Loop configuration --------------------------------------------------- */
+const parseWorkerMapping = (rawWorkers) => {
+    const workers = Object.create(null);
+    for (const entry of rawWorkers.split(",")) {
+        const parts = entry.split("=");
+        if (parts.length !== 2 || !parts[0] || !parts[1] || Object.hasOwn(workers, parts[0]))
+            throw new Error("Invalid or duplicate loop worker mapping");
+        workers[parts[0]] = parts[1];
+    }
+    return workers;
+};
 const chooseLoop = async (args, upgrade) => {
     let mode = value(args, "--loop-mode");
     const leadArg = value(args, "--loop-lead"), workersArg = value(args, "--loop-workers");
@@ -68,15 +80,9 @@ const chooseLoop = async (args, upgrade) => {
     }
     if (!lead || !rawWorkers)
         throw new Error("An enabled loop requires --loop-lead and --loop-workers");
-    const workers = Object.create(null);
-    for (const entry of rawWorkers.split(",")) {
-        const parts = entry.split("=");
-        if (parts.length !== 2 || !parts[0] || !parts[1] || Object.hasOwn(workers, parts[0]))
-            throw new Error("Invalid or duplicate loop worker mapping");
-        workers[parts[0]] = parts[1];
-    }
-    return validateLoopConfig({ mode, agents: { lead, workers } });
+    return validateLoopConfig({ mode, agents: { lead, workers: parseWorkerMapping(rawWorkers) } });
 };
+/* --- Option builders and shared flows -------------------------------------- */
 const initOptions = (args) => ({
     root: rootArg(args),
     agents: (value(args, "--agent") ?? "").split(",").filter(Boolean),
@@ -120,7 +126,8 @@ const confirmGeneral = async (options, operation) => {
     const { confirm } = await prompts();
     return confirm({ message: `${operation} this plan?`, default: false });
 };
-const mcpSetupOptions = async (args) => {
+/* --- MCP setup options ----------------------------------------------------- */
+const mcpSetupSelections = async (args) => {
     const selected = {
         deployment: value(args, "--deployment"),
         storage: value(args, "--storage"),
@@ -143,32 +150,95 @@ const mcpSetupOptions = async (args) => {
     }
     if (!Number.isInteger(selected.pollMs) || selected.pollMs < 1_000 || selected.pollMs > 3_600_000)
         throw new Error("--poll-ms must be an integer from 1000 to 3600000");
+    return selected;
+};
+const mcpSetupOptions = async (args) => {
+    const selected = await mcpSetupSelections(args);
     return { root: rootArg(args), template: join(fileURLToPath(new URL("../services/aidlc-coordination", import.meta.url))), dryRun: flags(args).has("--dry-run"), deployment: selected.deployment, storage: selected.storage, bind: selected.bind, workspace: selected.workspace, pollMs: selected.pollMs, tokenEnv: selected.tokenEnv, providers: selected.providers, enable: flags(args).has("--enable") };
 };
+/* --- Command handlers ------------------------------------------------------ */
+const runLoopCommand = (args) => {
+    const action = args[0];
+    if (!["start", "status", "resume"].includes(action))
+        throw new Error("Expected loop start, status, or resume");
+    const parsed = new Map();
+    for (let index = 1; index < args.length; index += 2) {
+        const key = args[index], entry = args[index + 1];
+        if (!["--task-id", "--root", "--mode"].includes(key) || !entry || entry.startsWith("--") || parsed.has(key))
+            throw new Error("Invalid or duplicate loop option");
+        parsed.set(key, entry);
+    }
+    const root = resolve(parsed.get("--root") ?? ".");
+    const script = join(root, ".agents", "aidlc", "scripts", "loop-entry.mjs");
+    const child = spawnSync(process.execPath, [script, action, parsed.get("--task-id") ?? "", root, parsed.get("--mode") ?? ""], { stdio: "inherit" });
+    if (child.error)
+        throw child.error;
+    if (child.status !== 0)
+        process.exitCode = child.status ?? 1;
+};
+const runInit = async (args) => {
+    const options = { ...await chooseAgents(initOptions(args)), loop: await chooseLoop(args, false) };
+    const plan = planInit(options);
+    preview("INIT", plan);
+    if (plan.some((item) => item.action === "conflict"))
+        throw new Error("No files were written because the plan contains conflicts.");
+    if (!await confirmGeneral(options, "Apply"))
+        return;
+    if (plan.some((item) => item.action === "migrate" || item.action === "delete")) {
+        const result = applyUpgrade(options.root, plan);
+        console.log(`Installed local AI-DLC workflow assets and migrated legacy data. Backup: ${result.backup}; changed: ${result.changed}`);
+    }
+    else {
+        applyPlan(options.root, plan);
+        console.log("Installed local AI-DLC workflow assets.");
+    }
+};
+const runUninstall = async (args) => {
+    const options = initOptions(args);
+    const plan = planUninstall(options.root);
+    preview("UNINSTALL", plan);
+    if (!await confirmGeneral(options, "Remove"))
+        return;
+    applyPlan(options.root, plan);
+    console.log("Removed eligible managed assets; project config and state were preserved.");
+};
+const runUpgrade = async (args) => {
+    if (flags(args).has("--yes") || flags(args).has("--force"))
+        throw new Error("upgrade does not support --yes or --force; apply requires a human interactive TTY confirmation");
+    const root = rootArg(args);
+    const plan = planUpgrade(root, await chooseLoop(args, true));
+    preview("UPGRADE", plan);
+    if (plan.some((item) => item.action === "conflict"))
+        throw new Error("Upgrade contains conflicts; no files were written.");
+    if (flags(args).has("--dry-run"))
+        return;
+    if (!interactive())
+        throw new Error("Upgrade apply requires an interactive TTY. AI and non-interactive processes must not apply upgrades.");
+    const expected = packageVersion();
+    const { input } = await prompts();
+    if ((await input({ message: `Type ${expected} to apply this user-initiated upgrade` })).trim() !== expected)
+        throw new Error("Upgrade confirmation did not match the target version");
+    const result = applyUpgrade(root, plan);
+    console.log(`Upgrade complete. Backup: ${result.backup}; changed: ${result.changed}`);
+};
+const runMcpSetup = async (args) => {
+    const options = await mcpSetupOptions(args.slice(1));
+    const plan = planMcpSetup(options);
+    console.log(`◆ MCP SETUP preview — ${options.dryRun ? "no files will be written" : "review before applying"}`);
+    console.log(JSON.stringify(plan, null, 2));
+    if (options.dryRun)
+        return;
+    if (!await confirmGeneral({ ...initOptions(args), root: options.root }, "Apply MCP setup"))
+        return;
+    applyMcpSetup(options);
+    console.log(`MCP setup written to ${plan.target}. MCP remains ${options.enable ? "enabled" : "disabled"}; start Docker explicitly with docker compose --env-file .env -f ${join(plan.target, "compose.yaml")} up -d.`);
+};
 const main = async () => {
     const [command = "help", ...args] = process.argv.slice(2);
     if (command === "help" || command === "--help")
         return void console.log(usage);
-    if (command === "loop") {
-        const action = args[0];
-        if (!["start", "status", "resume"].includes(action))
-            throw new Error("Expected loop start, status, or resume");
-        const parsed = new Map();
-        for (let index = 1; index < args.length; index += 2) {
-            const key = args[index], entry = args[index + 1];
-            if (!["--task-id", "--root", "--mode"].includes(key) || !entry || entry.startsWith("--") || parsed.has(key))
-                throw new Error("Invalid or duplicate loop option");
-            parsed.set(key, entry);
-        }
-        const root = resolve(parsed.get("--root") ?? ".");
-        const script = join(root, ".agents", "aidlc", "scripts", "loop-entry.mjs");
-        const child = spawnSync(process.execPath, [script, action, parsed.get("--task-id") ?? "", root, parsed.get("--mode") ?? ""], { stdio: "inherit" });
-        if (child.error)
-            throw child.error;
-        if (child.status !== 0)
-            process.exitCode = child.status ?? 1;
-        return;
-    }
+    if (command === "loop")
+        return void runLoopCommand(args);
     if (command === "status")
         return void console.log(status(rootArg(args)));
     if (command === "doctor") {
@@ -178,68 +248,14 @@ const main = async () => {
             process.exitCode = 1;
         return;
     }
-    if (command === "init") {
-        const options = { ...await chooseAgents(initOptions(args)), loop: await chooseLoop(args, false) };
-        const plan = planInit(options);
-        preview("INIT", plan);
-        if (plan.some((item) => item.action === "conflict"))
-            throw new Error("No files were written because the plan contains conflicts.");
-        if (!await confirmGeneral(options, "Apply"))
-            return;
-        const migratesLegacyData = plan.some((item) => item.action === "migrate" || item.action === "delete");
-        if (migratesLegacyData) {
-            const result = applyUpgrade(options.root, plan);
-            console.log(`Installed local AI-DLC workflow assets and migrated legacy data. Backup: ${result.backup}; changed: ${result.changed}`);
-        }
-        else {
-            applyPlan(options.root, plan);
-            console.log("Installed local AI-DLC workflow assets.");
-        }
-        return;
-    }
-    if (command === "uninstall") {
-        const options = initOptions(args);
-        const plan = planUninstall(options.root);
-        preview("UNINSTALL", plan);
-        if (!await confirmGeneral(options, "Remove"))
-            return;
-        applyPlan(options.root, plan);
-        console.log("Removed eligible managed assets; project config and state were preserved.");
-        return;
-    }
-    if (command === "upgrade") {
-        if (flags(args).has("--yes") || flags(args).has("--force"))
-            throw new Error("upgrade does not support --yes or --force; apply requires a human interactive TTY confirmation");
-        const root = rootArg(args);
-        const plan = planUpgrade(root, await chooseLoop(args, true));
-        preview("UPGRADE", plan);
-        if (plan.some((item) => item.action === "conflict"))
-            throw new Error("Upgrade contains conflicts; no files were written.");
-        if (flags(args).has("--dry-run"))
-            return;
-        if (!interactive())
-            throw new Error("Upgrade apply requires an interactive TTY. AI and non-interactive processes must not apply upgrades.");
-        const expected = packageVersion();
-        const { input } = await prompts();
-        if ((await input({ message: `Type ${expected} to apply this user-initiated upgrade` })).trim() !== expected)
-            throw new Error("Upgrade confirmation did not match the target version");
-        const result = applyUpgrade(root, plan);
-        console.log(`Upgrade complete. Backup: ${result.backup}; changed: ${result.changed}`);
-        return;
-    }
-    if (command === "mcp" && args[0] === "setup") {
-        const options = await mcpSetupOptions(args.slice(1));
-        const plan = planMcpSetup(options);
-        console.log(`◆ MCP SETUP preview — ${options.dryRun ? "no files will be written" : "review before applying"}`);
-        console.log(JSON.stringify(plan, null, 2));
-        if (options.dryRun)
-            return;
-        if (!await confirmGeneral({ ...initOptions(args), root: options.root }, "Apply MCP setup"))
-            return;
-        applyMcpSetup(options);
-        console.log(`MCP setup written to ${plan.target}. MCP remains ${options.enable ? "enabled" : "disabled"}; start Docker explicitly with docker compose --env-file .env -f ${join(plan.target, "compose.yaml")} up -d.`);
-        return;
-    }
+    if (command === "init")
+        return void await runInit(args);
+    if (command === "uninstall")
+        return void await runUninstall(args);
+    if (command === "upgrade")
+        return void await runUpgrade(args);
+    if (command === "mcp" && args[0] === "setup")
+        return void await runMcpSetup(args);
     if (command === "profile" && args[0] === "validate") {
         const root = rootArg(args.slice(1));
         const config = loadProjectConfig(root);
@@ -249,4 +265,4 @@ const main = async () => {
     }
     throw new Error(`Unknown command: ${command}`);
 };
-main().catch((error) => { console.error(`aidlc-workflow: ${error instanceof Error ? error.message : String(error)}`); process.exitCode = 1; });
+main().catch((error) => { console.error(`aidlc-kit: ${error instanceof Error ? error.message : String(error)}`); process.exitCode = 1; });

package/dist/src/context.js

@@ -6,10 +6,12 @@ import { loadMemoryRegistry, nextAction, selectAgenticMemory } from "./state.js"
 const assetRoot = fileURLToPath(new URL("../assets/.agents/aidlc", import.meta.url));
 const phaseFile = (phase) => phase === "done" ? "phase-wrap.md" : `phase-${phase}.md`;
 const readAsset = (path) => readFileSync(join(assetRoot, path), "utf8");
+/** Keeps only the latest test/lint/review record per (kind, area, gate) and strips prose details. */
 const requiredEvidence = (task) => task.evidence.filter((item, index, entries) => {
     const key = `${item.kind}:${item.area ?? ""}:${item.gate ?? ""}`;
     return !entries.slice(index + 1).some((candidate) => `${candidate.kind}:${candidate.area ?? ""}:${candidate.gate ?? ""}` === key);
 }).map(({ detail: _detail, ...item }) => item);
+/** Compact canonical view of the task for a phase packet; `itemId` narrows execution items only. */
 const compactTask = (task, itemId) => JSON.stringify({
     id: task.id,
     title: task.title,

package/dist/src/gate.d.ts

@@ -1,4 +1,5 @@
 import type { Diagnostic, Gate, TaskState, WorkflowState } from "./model.js";
+/** Runs all diagnostics for a gate and returns them (empty-ish with GATE_OK when clean). */
 export declare const checkGate: (root: string, state: WorkflowState, taskId: string, gate: Gate) => Diagnostic[];
 export declare const approveAndAdvance: (root: string, state: WorkflowState, taskId: string, gate: Gate, source: string, recordedAt?: string) => {
     task: TaskState;