@felixdotgo/aidlc-kit 0.0.1

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

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+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";
+
+try {
+const raw = process.argv.slice(2);
+const valueOptions = ["--root", "--status", "--limit", "--cursor", "--query", "--title", "--type", "--language", "--risk", "--area", "--mode", "--reason", "--source", "--to", "--kind", "--successor", "--label", "--resolution", "--result", "--gate", "--detail", "--summary", "--prevention", "--example", "--promotion", "--guidance", "--phase", "--priority", "--source-task", "--source-lesson", "--approved-by", "--switch-from"];
+const parsed = parseArguments(raw, { valueOptions, booleanOptions: ["--include-archive"] });
+const args = parsed.positionals;
+const [group, action, rawId] = args;
+const id = rawId;
+const schemas = {
+  "state migrate": { minPositionals: 2 },
+  "task show": { minPositionals: 2, maxPositionals: 3, valueOptions: ["--status", "--limit", "--cursor"], booleanOptions: ["--include-archive"] },
+  "task list": { minPositionals: 2, valueOptions: ["--status", "--limit", "--cursor"], booleanOptions: ["--include-archive"] },
+  "task find": { minPositionals: 2, valueOptions: ["--query", "--status", "--limit", "--cursor"], booleanOptions: ["--include-archive"], requiredOptions: ["--query"] },
+  "task next": { minPositionals: 3 },
+  "task create": { minPositionals: 3, valueOptions: ["--title", "--type", "--language", "--risk", "--area", "--switch-from"], requiredOptions: ["--title"] },
+  "task transition": { minPositionals: 3, valueOptions: ["--mode", "--reason", "--source", "--to"], requiredOptions: ["--mode", "--reason", "--source", "--to"], usage: "task transition requires --mode audited, --reason, --source, and --to" },
+  "task archive": { minPositionals: 3, valueOptions: ["--reason", "--source"], requiredOptions: ["--reason", "--source"] },
+  "task handoff": { minPositionals: 3, valueOptions: ["--kind", "--reason", "--source"], requiredOptions: ["--kind", "--reason", "--source"] },
+  "task close": { minPositionals: 3, valueOptions: ["--reason", "--source"], requiredOptions: ["--reason", "--source"] },
+  "task supersede": { minPositionals: 3, valueOptions: ["--successor", "--reason", "--source"], requiredOptions: ["--successor", "--reason", "--source"] },
+  "task reopen": { minPositionals: 3, valueOptions: ["--to", "--reason", "--source"], requiredOptions: ["--to", "--reason", "--source"] },
+  "task status": { minPositionals: 3, valueOptions: ["--status", "--mode", "--reason", "--source"], requiredOptions: ["--status"] },
+  "task item": { minPositionals: 4, valueOptions: ["--status", "--label"], requiredOptions: ["--status"] },
+  "decision set": { minPositionals: 4, valueOptions: ["--status", "--label", "--resolution"], requiredOptions: ["--status"] },
+  "evidence add": { minPositionals: 3, valueOptions: ["--kind", "--result", "--gate", "--area", "--source", "--detail"], requiredOptions: ["--kind", "--result"] },
+  "lesson record": { minPositionals: 4, valueOptions: ["--area", "--summary", "--prevention", "--example", "--promotion", "--source"] },
+  "lesson none": { minPositionals: 3, valueOptions: ["--reason", "--source"], requiredOptions: ["--reason", "--source"] },
+  "lesson rebuild": { minPositionals: 2 },
+  "lesson search": { minPositionals: 2, valueOptions: ["--query", "--area", "--limit"] },
+  "memory list": { minPositionals: 2 },
+  "memory promote": { minPositionals: 3, valueOptions: ["--summary", "--guidance", "--area", "--phase", "--priority", "--source-task", "--source-lesson", "--approved-by"], requiredOptions: ["--summary", "--guidance", "--source-task", "--source-lesson", "--approved-by"] },
+  "memory retire": { minPositionals: 3, valueOptions: ["--reason", "--approved-by"], requiredOptions: ["--reason", "--approved-by"] },
+  "gate approve": { minPositionals: 3, valueOptions: ["--gate", "--source"], requiredOptions: ["--gate", "--source"] }
+};
+const usage = "Usage: state.mjs state migrate | task create|show|list|find|next|status|item|transition|archive|handoff|close|supersede|reopen | decision set | evidence add | lesson record|none|search|rebuild | memory list|promote|retire | gate approve";
+const schema = schemas[`${group ?? ""} ${action ?? ""}`];
+if (!schema) throw new Error(usage);
+validateArguments(parsed, { ...schema, maxPositionals: schema.maxPositionals ?? schema.minPositionals, usage: schema.usage ?? usage });
+const root = rootOption(parsed);
+const releaseStateLock = acquireStateLock(root);
+let released = false;
+const releaseOnce = () => { if (!released) { releaseStateLock(); released = true; } };
+process.once("exit", releaseOnce);
+try {
+const state = loadState(root);
+const now = () => new Date().toISOString();
+const numberOption = (name, fallback) => {
+  const rawValue = option(parsed, name);
+  if (rawValue === undefined) return fallback;
+  const value = Number(rawValue);
+  if (!Number.isInteger(value) || value < 0) throw new Error(`${name} must be a non-negative integer`);
+  return value;
+};
+const summaryOptions = (query) => ({
+  includeArchive: parsed.flags.has("--include-archive"),
+  statuses: option(parsed, "--status")?.split(",").map((item) => item.trim()).filter(Boolean),
+  query,
+  limit: numberOption("--limit", 20),
+  cursor: numberOption("--cursor", 0)
+});
+const warnings = [];
+const derivedStep = (code, hint, step) => { try { step(); } catch (error) { warnings.push({ code, message: error instanceof Error ? error.message : String(error), hint }); } };
+const persist = (tasks, rebuildLessons = false) => {
+  const archived = saveState(root, state);
+  if (rebuildLessons || archived.length) derivedStep("LESSON_INDEX_STALE", "restore the damaged archive record from git history, then run state.mjs lesson rebuild", () => rebuildLessonIndex(root, state));
+  derivedStep("RENDER_FAILED", "fix the reported path, then run render.mjs <task-id>", () => renderViews(root, state, tasks.filter(Boolean)));
+};
+const emit = (result, task) => console.log(JSON.stringify({ ok: true, ...(result === undefined ? {} : { result }), ...(warnings.length ? { warnings } : {}), ...(task ? { nextAction: nextAction(task, root) } : {}) }, null, 2));
+const respond = (task, result = {}) => emit({ task, ...result }, task);
+
+if (group === "state" && action === "migrate") {
+  emit(migrateState(root, state));
+} else if (group === "task" && action === "show") {
+  if (id) { const shown = loadTask(root, id, state) ?? null; emit(shown, shown ?? undefined); }
+  else emit(listTaskSummaries(state, summaryOptions()));
+} else if (group === "task" && action === "list") {
+  emit(listTaskSummaries(state, summaryOptions()));
+} else if (group === "task" && action === "find") {
+  const query = option(parsed, "--query");
+  if (!query) throw new Error("task find requires --query");
+  emit(listTaskSummaries(state, summaryOptions(query)));
+} else if (group === "task" && action === "next") {
+  const task = loadTask(root, id, state);
+  if (!task) throw new Error(`Unknown task: ${id}`);
+  emit({ id: task.id, phase: task.phase, gate: task.gate, status: task.status }, task);
+} else if (group === "task" && action === "create") {
+  const title = option(parsed, "--title");
+  if (!id || !title) throw new Error("task create requires <task-id> and --title");
+  if (loadTask(root, id, state)) throw new Error(`Task already exists: ${id}; use task next ${id} to resume it`);
+  const collision = [...Object.keys(state.tasks), ...Object.keys(state.archive ?? {})].find((existing) => existing.toLowerCase() === id.toLowerCase());
+  if (collision) throw new Error(`Task id collides case-insensitively with existing task: ${collision}`);
+  const actionable = Object.values(state.tasks).filter((existing) => nextAction(existing, root).classification === "run_phase").map((existing) => existing.id).sort();
+  const actionableByLowercase = new Map(actionable.map((existing) => [existing.toLowerCase(), existing]));
+  const acknowledgedTokens = [...new Set((option(parsed, "--switch-from") ?? "").split(",").map((item) => item.trim()).filter(Boolean))];
+  const unknownAcknowledgement = acknowledgedTokens.filter((ack) => !actionableByLowercase.has(ack.toLowerCase()));
+  if (unknownAcknowledgement.length) throw new Error(`--switch-from must name only actionable task(s); not actionable: ${unknownAcknowledgement.join(", ")}`);
+  const acknowledged = [...new Set(acknowledgedTokens.map((ack) => actionableByLowercase.get(ack.toLowerCase())))];
+  const stranded = actionable.filter((existing) => !acknowledged.includes(existing));
+  if (stranded.length) throw new Error(`Task create is blocked while other work is actionable: ${stranded.join(", ")}. With explicit user direction to switch, rerun with --switch-from ${actionable.join(",")}; acknowledged tasks keep their state and remain the resume target`);
+  const recordedAt = now();
+  const task = state.tasks[id] = {
+    id, title, type: option(parsed, "--type") ?? "infra", phase: "clarify", gate: "G0_confirm", status: "active",
+    language: option(parsed, "--language") === "en" ? "en" : "vi", risk: option(parsed, "--risk") ?? "normal",
+    areas: (option(parsed, "--area") ?? "root").split(",").map((area) => area.trim()).filter(Boolean), branch: "—",
+    artifacts: { intent: `.agents/data/tasks/${id}/intent.md`, design: `.agents/data/tasks/${id}/design.md`, workplan: `.agents/data/tasks/${id}/workplan.md` },
+    decisions: [], tasks: [], evidence: [], createdAt: recordedAt, updatedAt: recordedAt
+  };
+  const acknowledgedTasks = acknowledged.map((ack) => state.tasks[ack]);
+  for (const prior of acknowledgedTasks) {
+    prior.evidence.push({ kind: "diagnostic", result: "pass", source: `task create ${id}`, detail: `Switch acknowledged: created ${id} while ${prior.id} was actionable; ${prior.id} keeps its state — resume with task next ${prior.id}`, recordedAt });
+    prior.updatedAt = recordedAt;
+  }
+  persist([task, ...acknowledgedTasks]); respond(task);
+} else if (group === "task" && action === "transition") {
+  const mode = option(parsed, "--mode"); const reason = option(parsed, "--reason"); const source = option(parsed, "--source");
+  if (mode !== "audited" || !reason?.trim() || !source?.trim()) throw new Error("task transition requires --mode audited, --reason, and --source");
+  const from = state.tasks[id]?.phase; const target = option(parsed, "--to"); const task = transitionTask(state, id, target);
+  task.evidence.push({ kind: "diagnostic", result: "pass", source, detail: `Audited transition ${from} → ${target}: ${reason}`, recordedAt: now() });
+  persist([task]); respond(task);
+} else if (group === "task" && action === "archive") {
+  const reason = option(parsed, "--reason"); const source = option(parsed, "--source");
+  if (!reason?.trim() || !source?.trim()) throw new Error("task archive requires --reason and --source");
+  const task = transitionTask(state, id, "done");
+  task.evidence.push({ kind: "diagnostic", result: "pass", source, detail: `Archive to done: ${reason}`, recordedAt: now() });
+  persist([task], true); respond(task);
+} else if (group === "task" && action === "handoff") {
+  const task = handoffTask(state, id, option(parsed, "--kind"), option(parsed, "--reason"), option(parsed, "--source"));
+  persist([task]); respond(task);
+} else if (group === "task" && action === "close") {
+  const task = closeTask(state, id, option(parsed, "--reason"), option(parsed, "--source"));
+  persist([task]); respond(task);
+} else if (group === "task" && action === "supersede") {
+  const task = supersedeTask(state, id, option(parsed, "--successor"), option(parsed, "--reason"), option(parsed, "--source")); const successor = state.tasks[task.successorTaskId];
+  persist([task, successor]); respond(task, { successor });
+} else if (group === "task" && action === "reopen") {
+  const task = reopenTask(state, id, option(parsed, "--to"), option(parsed, "--reason"), option(parsed, "--source"));
+  persist([task]); respond(task);
+} else if (group === "task" && action === "status") {
+  const task = state.tasks[id]; const status = option(parsed, "--status");
+  if (!task || !["active", "blocked_on_user", "paused"].includes(status)) throw new Error("task status requires an active task id and --status active|blocked_on_user|paused; finishing a task uses task transition --to done or task archive");
+  const leavingGateWait = task.status === "blocked_on_user" && status !== "blocked_on_user";
+  const recoveringGatelessWrap = leavingGateWait && task.phase === "wrap" && task.gate === "none" && status === "active";
+  if (leavingGateWait && !recoveringGatelessWrap) {
+    const mode = option(parsed, "--mode"); const reason = option(parsed, "--reason"); const cancelSource = option(parsed, "--source");
+    if (mode !== "audited" || !reason?.trim() || !cancelSource?.trim()) throw new Error("Cancelling a human-gate wait requires --mode audited, --reason, and --source (e.g. the user's rejection message)");
+    task.evidence.push({ kind: "diagnostic", result: "pass", source: cancelSource, detail: `Cancelled gate wait at ${task.gate}: ${reason}`, recordedAt: now() });
+  }
+  const enteringPause = status === "paused" && task.status === "active";
+  if (enteringPause) {
+    const mode = option(parsed, "--mode"); const reason = option(parsed, "--reason"); const pauseSource = option(parsed, "--source");
+    if (mode !== "audited" || !reason?.trim() || !pauseSource?.trim()) throw new Error("Pausing an active task requires --mode audited, --reason, and --source");
+    task.evidence.push({ kind: "diagnostic", result: "pass", source: pauseSource, detail: `Paused while active: ${reason}`, recordedAt: now() });
+  }
+  if (status === "blocked_on_user") {
+    if (task.gate === "none") throw new Error("Phase wrap has no human gate; continue wrap and finish with task transition --to done or task archive");
+    const errors = checkGate(root, state, id, task.gate).filter((item) => item.level === "ERROR");
+    if (errors.length) throw new Error(`Gate is not ready: ${errors.map((item) => `${item.code}: ${item.message}`).join("; ")}`);
+  }
+  if (leavingGateWait) delete task.legacyG2Wait;
+  task.status = status; task.updatedAt = now(); persist([task]); respond(task);
+} else if (group === "task" && action === "item") {
+  const itemId = args[3]; const task = state.tasks[id]; const status = option(parsed, "--status");
+  if (!task || !itemId || !["todo", "in_progress", "done", "deferred"].includes(status)) throw new Error("task item requires active task id, item id, and valid --status");
+  const item = task.tasks.find((entry) => entry.id === itemId);
+  if (item) { item.status = status; if (parsed.present.has("--label")) item.label = option(parsed, "--label"); }
+  else task.tasks.push({ id: itemId, label: option(parsed, "--label") ?? itemId, status });
+  task.updatedAt = now(); persist([task]); respond(task);
+} else if (group === "decision" && action === "set") {
+  const decisionId = args[3]; const task = state.tasks[id]; const status = option(parsed, "--status");
+  if (!task || !decisionId || !["unresolved", "approved", "changed", "dropped"].includes(status)) throw new Error("decision set requires active task id, decision id, and valid --status");
+  const current = task.decisions.find((entry) => entry.id === decisionId);
+  if (current) { current.status = status; if (parsed.present.has("--label")) current.label = option(parsed, "--label"); if (parsed.present.has("--resolution")) current.resolution = option(parsed, "--resolution"); }
+  else task.decisions.push({ id: decisionId, label: option(parsed, "--label") ?? decisionId, status, resolution: option(parsed, "--resolution") });
+  task.updatedAt = now(); persist([task]); respond(task);
+} else if (group === "evidence" && action === "add") {
+  const task = state.tasks[id]; const kind = option(parsed, "--kind"); const result = option(parsed, "--result");
+  if (!task || !["spec", "test", "lint", "review", "diagnostic"].includes(kind) || !["pass", "fail", "skip"].includes(result)) throw new Error("evidence add requires active task id, non-approval --kind, and valid --result; approvals use gate approve");
+  const area = option(parsed, "--area");
+  if (area && !task.areas.includes(area)) throw new Error(`Evidence area must belong to task.areas: ${area}`);
+  if (["test", "lint"].includes(kind) && task.areas.length > 1 && !area) throw new Error("Test and lint evidence for multi-area tasks requires --area");
+  task.evidence.push({ kind, gate: option(parsed, "--gate"), area, result, source: option(parsed, "--source") ?? "local Node.js script", detail: option(parsed, "--detail"), recordedAt: now() });
+  task.updatedAt = now(); persist([task]); respond(task);
+} else if (group === "lesson" && action === "record") {
+  const lessonId = args[3]; const task = state.tasks[id];
+  if (!task || !lessonId) throw new Error("lesson record requires active task id and lesson id");
+  const source = option(parsed, "--source");
+  const lesson = recordLesson(task, { id: lessonId, areas: (option(parsed, "--area") ?? task.areas.join(",")).split(",").map((item) => item.trim()).filter(Boolean), summary: option(parsed, "--summary"), prevention: option(parsed, "--prevention"), example: option(parsed, "--example"), promotion: option(parsed, "--promotion") ?? "not promoted", source });
+  persist([task], true); respond(task, { lesson });
+} else if (group === "lesson" && action === "none") {
+  const task = state.tasks[id]; if (!task) throw new Error("lesson none requires active task id");
+  recordNoLessons(task, option(parsed, "--reason"), option(parsed, "--source")); persist([task], true); respond(task, { lessonDisposition: task.lessonDisposition });
+} else if (group === "lesson" && action === "rebuild") {
+  emit(rebuildLessonIndex(root, state));
+} else if (group === "lesson" && action === "search") {
+  emit(searchLessons(root, state, option(parsed, "--query") ?? "", (option(parsed, "--area") ?? "").split(",").map((item) => item.trim()).filter(Boolean), numberOption("--limit", 5)));
+} else if (group === "memory" && action === "list") {
+  emit(loadMemoryRegistry(root));
+} else if (group === "memory" && action === "promote") {
+  const entry = promoteAgenticMemory(root, {
+    id: args[2], summary: option(parsed, "--summary"), guidance: option(parsed, "--guidance"),
+    areas: (option(parsed, "--area") ?? "*").split(",").map((item) => item.trim()).filter(Boolean),
+    phases: (option(parsed, "--phase") ?? "*").split(",").map((item) => item.trim()).filter(Boolean),
+    priority: numberOption("--priority", 50), sourceTaskId: option(parsed, "--source-task"), sourceLessonId: option(parsed, "--source-lesson"), approvedBy: option(parsed, "--approved-by"), approvedAt: now()
+  });
+  emit(entry);
+} else if (group === "memory" && action === "retire") {
+  const entry = retireAgenticMemory(root, args[2], option(parsed, "--reason"), option(parsed, "--approved-by"));
+  emit(entry);
+} else if (group === "gate" && action === "approve") {
+  const gate = option(parsed, "--gate"); const source = option(parsed, "--source");
+  if (!id || !gate || !source) throw new Error("gate approve requires active task id, --gate, and explicit --source");
+  const outcome = approveAndAdvance(root, state, id, gate, source); persist([outcome.task]); emit({ task: outcome.task, idempotent: outcome.idempotent }, outcome.task);
+} else {
+  throw new Error("Usage: state.mjs state migrate | task create|show|list|find|next|status|item|transition|archive|handoff|close|supersede|reopen | decision set | evidence add | lesson record|none|search|rebuild | memory list|promote|retire | gate approve");
+}
+} finally {
+  process.off("exit", releaseOnce);
+  releaseOnce();
+}
+} catch (error) { failEntry(error); }

package/dist/assets/.agents/aidlc/scripts/task-next.mjs

@@ -0,0 +1,27 @@
+import { failEntry, loadState, loadTask, nextAction, parseArguments, rootOption, validateArguments } from "./lib/runtime.mjs";
+
+try {
+  const raw = process.argv.slice(2);
+  const parsed = parseArguments(raw, { valueOptions: ["--root"], booleanOptions: ["--require-stop"] });
+  validateArguments(parsed, { minPositionals: 1, booleanOptions: ["--require-stop"], usage: "Usage: task-next.mjs <task-id> [--root <path>] [--require-stop]" });
+  const root = rootOption(parsed);
+  const [id] = parsed.positionals;
+  const task = loadTask(root, id, loadState(root));
+  if (!task) throw new Error(`Unknown task: ${id}`);
+  const action = nextAction(task, root);
+  const requireStop = parsed.flags.has("--require-stop");
+  const required = action.classification === "run_phase";
+  const continuation = requireStop ? {
+    required,
+    code: required ? "CONTINUATION_REQUIRED" : "STOP_ALLOWED",
+    taskId: task.id,
+    classification: action.classification,
+    ...(required ? { command: action.command, reason: action.reason, ...(action.itemId !== undefined ? { itemId: action.itemId } : {}), ...(action.remainingItems !== undefined ? { remainingItems: action.remainingItems } : {}) } : {})
+  } : undefined;
+  console.log(JSON.stringify({ ok: true, result: { id: task.id, phase: task.phase, gate: task.gate, status: task.status }, nextAction: action, ...(continuation ? { continuation } : {}) }, null, 2));
+  if (requireStop && required) {
+    console.error(`CONTINUATION_REQUIRED: ${JSON.stringify({ taskId: task.id, command: action.command, reason: action.reason })}`);
+    console.error("note: exit code 2 is the continuation guard working as intended (an expected pause, not a failure); execute the command above instead of replying.");
+    process.exitCode = 2;
+  }
+} catch (error) { failEntry(error); }

package/dist/assets/.agents/aidlc/templates/design.md

@@ -0,0 +1,15 @@
+# Design — <Title>
+
+## 🧩 Solution per affected area
+- `<area>` — <approach, target, and reuse candidate>
+
+## 📌 Spec traceability
+| design element | source | exact quote / approved decision |
+|----------------|--------|---------------------------------|
+| <quantified rule or contract> | <path:line, rule ID, or user decision> | <exact source> |
+
+## 🔗 Cross-service contracts
+- <contract or `none`>
+
+## ⚠️ Risks / edge cases
+- <risk and mitigation>

package/dist/assets/.agents/aidlc/templates/intent.md

@@ -0,0 +1,17 @@
+# <Title>
+
+## 📋 Problem
+<Restate the goal and why it matters.>
+
+## 🗺️ Affected areas
+- `<area>` — <why> — spec: <indexed source or `none indexed`>
+
+## 💭 Assumptions
+- <assumption>
+
+## ❓ Open questions
+1. <question> — *default:* <safe default>
+
+## 🎯 Scope
+**In:** <decidable scope>
+**🚫 Out:** <explicit exclusions>

package/dist/assets/.agents/aidlc/templates/lesson.md

@@ -0,0 +1,28 @@
+# Structured lesson contract
+
+Lessons are canonical task data with task provenance. Project-wide advisory memory is a separate, explicitly approved registry; it never rewrites lifecycle state or project rules.
+
+Required fields: `id`, `taskId`, `areas`, `summary`, `prevention`, `example`, `promotion`, `source`, `recordedAt`.
+
+```sh
+node .agents/aidlc/scripts/state.mjs lesson record <task-id> <lesson-id> \
+  --area <areas> --summary <summary> --prevention <rule> \
+  --example <example> --promotion <status-or-target> --source <artifact-or-evidence>
+```
+
+If honest review finds no durable lesson:
+
+```sh
+node .agents/aidlc/scripts/state.mjs lesson none <task-id> --reason <reason> --source <source>
+```
+
+`lesson search` reads the digest-checked derived index; `lesson rebuild` recreates it from canonical task records. Promote only an existing source lesson with explicit human approval:
+
+```sh
+node .agents/aidlc/scripts/state.mjs memory promote <memory-id> \
+  --summary <summary> --guidance <actionable-guidance> --area <areas> \
+  --phase <phases-or-*> --priority <0-100> --source-task <task-id> \
+  --source-lesson <lesson-id> --approved-by <explicit-human-approval>
+```
+
+Retirement is also audited: `state.mjs memory retire <memory-id> --reason <reason> --approved-by <explicit-human-approval>`. Context packets load only matching registry entries after project rules and only when budget remains.

package/dist/assets/.agents/aidlc/templates/model-contract.md

@@ -0,0 +1,41 @@
+# Model collaboration contract
+
+Use this managed baseline with any AI model. It standardizes communication; it does not replace canonical state, executable verification, human gates, or approved task decisions. Project-specific additions belong in `.agents/project/rules/`.
+
+## COSTARS — task context
+
+Express the applicable parts of a task in this order:
+
+1. **Context** — current phase, task state, relevant files/spec anchors, constraints, and known risks.
+2. **Objective** — the concrete result to produce and the boundary of responsibility.
+3. **Style** — required reasoning/implementation style, such as evidence-first or minimal diff.
+4. **Tone** — concise, direct, and calibrated to the intended reader.
+5. **Audience** — human reviewer, implementer, or another model; state their assumed context.
+6. **Response format** — exact headings, structured data, file paths, or commands expected.
+7. **Success criteria** — observable acceptance conditions, required evidence, and when to stop/escalate.
+
+Omit fields that the active phase packet already makes explicit; never invent a spec, approval, or passing result to complete the format.
+
+## Phase mapping
+
+| phase | required COSTARS emphasis | output |
+|-------|---------------------------|--------|
+| clarify | Context, Objective, Audience, Success criteria | intent, assumptions, open questions, scope |
+| plan | Context, Objective, Response format, Success criteria | design, explicit decisions, workplan, verification plan |
+| build | Context, Objective, Style, Success criteria | smallest approved diff and executable verification evidence |
+
+Use CRITICS during clarify or plan only when risk is elevated, requirements are ambiguous, or models disagree.
+
+## CRITICS — adversarial review
+
+Before recording passing review evidence for G2, report these sections against the approved decisions, cited anchors, and task diff:
+
+1. **Criteria** — acceptance criteria, invariants, and exact spec anchors checked.
+2. **Risks** — regression, safety, compatibility, and unverified assumptions.
+3. **Issues** — each finding with severity (`critical`, `high`, `medium`, `low`) and evidence; state `none found` when applicable.
+4. **Tests / evidence** — commands or inspections run, results, and residual gaps.
+5. **Improvements** — required fixes or explicitly deferred follow-ups, each tied to an issue.
+6. **Conclusion** — `pass`, `needs changes`, or `escalate`; a pass requires no unresolved critical/high issue.
+7. **Stop / escalate** — reopen G1 for a structural/spec conflict; otherwise defer to the human gate when authority is needed.
+
+CRITICS is a review record, not approval. Only the state machine, recorded evidence, and human G2 approval advance the task.

package/dist/assets/.agents/aidlc/templates/workplan.md

@@ -0,0 +1,9 @@
+# Workplan — <Title> (`<task-id>`)
+
+> Review artifact derived from `.agents/data/state/aidlc-state.json`. Resolve decisions and update progress with `node .agents/aidlc/scripts/state.mjs`, then run `node .agents/aidlc/scripts/render.mjs`.
+
+## 🧩 Decisions (Gate G1 — approve before build)
+- <generated decision state>
+
+## 🧩 Tasks (Gate G2 — build execution)
+- <generated task state>

package/dist/assets/.agents/skills/aidlc-build/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: aidlc-build
+description: "AI-DLC phase 3 (Gate G2): after explicit G1 plan approval, implement the canonical work items, run the narrowest tests/lint, then run code-review. Triggers when the AI-DLC Orchestrator routes an approved post-G1 task to build. Ends at G2 for explicit user code review."
+---
+
+# AI-DLC · Build (Gate G2) — adapter
+
+This skill is a thin Claude Code adapter. The canonical playbook is tool-agnostic and lives in the repo:
+
+**Read `.agents/aidlc/phase-build.md` and execute it exactly.**
+
+Completing a canonical item is progress, not a stopping point. Execute the mutation's returned `nextAction` immediately, loop across remaining items, and run `task-next.mjs <task-id> --require-stop` before any final response.
+
+- Shared conventions (canonical state, gates, continuation, evidence): `.agents/aidlc/conventions.md`
+- Common rules & orchestrator: `.agents/aidlc/orchestrator.md`
+- Templates: `.agents/aidlc/templates/` · Stack rules: `.agents/aidlc/rules/`
+- Lifecycle state: `.agents/data/state/aidlc-state.json` · discovery indexes: `.agents/data/index/repo-map.md`, `.agents/data/index/specs-index.md`
+
+Do not re-author content from memory — the canonical files are the source of truth.

package/dist/assets/.agents/skills/aidlc-clarify/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: aidlc-clarify
+description: "AI-DLC phase 1 (Gate G0): turn a raw request into a confirmed intent brief — restate the problem, map affected submodules + specs, list assumptions and open questions, fix scope. Cheap: reads only the AI-DLC index, no deep code dive. Triggers: a NEW feature/bug/change request when the AI-DLC Orchestrator routes to clarify. Ends by STOPPING for user confirmation (G0)."
+---
+
+# AI-DLC · Clarify (Gate G0) — adapter
+
+This skill is a thin Claude Code adapter. The canonical playbook is tool-agnostic and lives in the repo:
+
+**Read `.agents/aidlc/phase-clarify.md` and execute it exactly.**
+
+- Shared conventions (canonical state, gates, continuation, evidence): `.agents/aidlc/conventions.md`
+- Common rules & orchestrator: `.agents/aidlc/orchestrator.md`
+- Templates: `.agents/aidlc/templates/` · Stack rules: `.agents/aidlc/rules/`
+- Lifecycle state: `.agents/data/state/aidlc-state.json` · discovery indexes: `.agents/data/index/repo-map.md`, `.agents/data/index/specs-index.md`
+
+Do not re-author content from memory — the canonical files are the source of truth.

package/dist/assets/.agents/skills/aidlc-index/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: aidlc-index
+description: "Build or refresh the AI-DLC index — a compact repo-map and spec-index used by every other AI-DLC phase to locate relevant code and docs cheaply. Run when .agents/data/index/repo-map.md is missing, or whenever submodules, stacks, or spec files change. Triggers: 'aidlc index', 'refresh repo map', 'rebuild spec index', 'index the specs'. Normally invoked automatically by the AI-DLC Orchestrator, not by the user."
+---
+
+# AI-DLC · Index — adapter
+
+This skill is a thin Claude Code adapter. The canonical playbook is tool-agnostic and lives in the repo:
+
+**Read `.agents/aidlc/phase-index.md` and execute it exactly.**
+
+- Shared conventions (canonical state, gates, continuation, evidence): `.agents/aidlc/conventions.md`
+- Common rules & orchestrator: `.agents/aidlc/orchestrator.md`
+- Templates: `.agents/aidlc/templates/` · Stack rules: `.agents/aidlc/rules/`
+- Lifecycle state: `.agents/data/state/aidlc-state.json` · discovery indexes: `.agents/data/index/repo-map.md`, `.agents/data/index/specs-index.md`
+
+Do not re-author content from memory — the canonical files are the source of truth.

package/dist/assets/.agents/skills/aidlc-plan/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: aidlc-plan
+description: "AI-DLC phase 2 (Gate G1): after intent is confirmed, run bounded discovery, then produce a detailed design, canonical decisions, and a per-submodule workplan. Triggers when the AI-DLC Orchestrator routes a confirmed post-G0 task to planning. Ends at the executable G1 plan review for explicit user approval."
+---
+
+# AI-DLC · Plan (Gate G1) — adapter
+
+This skill is a thin Claude Code adapter. The canonical playbook is tool-agnostic and lives in the repo:
+
+**Read `.agents/aidlc/phase-plan.md` and execute it exactly.**
+
+- Shared conventions (canonical state, gates, continuation, evidence): `.agents/aidlc/conventions.md`
+- Common rules & orchestrator: `.agents/aidlc/orchestrator.md`
+- Templates: `.agents/aidlc/templates/` · Stack rules: `.agents/aidlc/rules/`
+- Lifecycle state: `.agents/data/state/aidlc-state.json` · discovery indexes: `.agents/data/index/repo-map.md`, `.agents/data/index/specs-index.md`
+
+Do not re-author content from memory — the canonical files are the source of truth.

package/dist/assets/.agents/skills/aidlc-wrap/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: aidlc-wrap
+description: "AI-DLC phase 4 (post-G2): after the user approves the code, follow project delivery policy, capture lessons and residual risk, then close canonical task state."
+---
+
+# AI-DLC · Wrap — adapter
+
+This skill is a thin Claude Code adapter. The canonical playbook is tool-agnostic and lives in the repo:
+
+**Read `.agents/aidlc/phase-wrap.md` and execute it exactly.**
+
+- Shared conventions (canonical state, gates, continuation, evidence): `.agents/aidlc/conventions.md`
+- Common rules & orchestrator: `.agents/aidlc/orchestrator.md`
+- Templates: `.agents/aidlc/templates/` · Stack rules: `.agents/aidlc/rules/`
+- Lifecycle state: `.agents/data/state/aidlc-state.json` · discovery indexes: `.agents/data/index/repo-map.md`, `.agents/data/index/specs-index.md`
+
+Do not re-author content from memory — the canonical files are the source of truth.

package/dist/services/aidlc-coordination/Dockerfile

@@ -0,0 +1,10 @@
+FROM node:24-bookworm-slim
+WORKDIR /app
+RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ && rm -rf /var/lib/apt/lists/*
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+COPY src ./src
+RUN mkdir -p /data
+ENV MCP_STATE_HOST=0.0.0.0 MCP_STATE_PORT=8787 MCP_STATE_SQLITE_PATH=/data/mcp-state.db
+EXPOSE 8787
+CMD ["node", "src/server.mjs"]

package/dist/services/aidlc-coordination/compose.yaml

@@ -0,0 +1,25 @@
+services:
+  aidlc-coordination:
+    build: .
+    ports:
+      - "127.0.0.1:8787:8787"
+    volumes:
+      - aidlc-coordination-data:/data
+    environment:
+      MCP_STATE_DATABASE: sqlite
+      MCP_STATE_SQLITE_PATH: /data/mcp-state.db
+      MCP_STATE_AUTH_TOKEN: ${MCP_STATE_AUTH_TOKEN:?set MCP_STATE_AUTH_TOKEN in .env before starting the service}
+
+  postgres:
+    image: postgres:16-alpine
+    profiles: [postgres]
+    environment:
+      POSTGRES_DB: aidlc
+      POSTGRES_USER: aidlc
+      POSTGRES_PASSWORD: change-me
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+volumes:
+  aidlc-coordination-data:
+  postgres-data: