@kaddo/cli 3.2.0 → 3.4.0

package/README.md

@@ -434,6 +434,8 @@ create --from roadmap → owners → guard → explain`.
 | v3.0 | Knowledge-centric realignment: `architecture/` → `knowledge/` with layers Business → Product → Tech → Delivery; context/explain by layer (breaking) |
 | v3.1 | Minimum Sufficient Knowledge: bootstrap one consolidated file per layer; progressive `add agents` by group (state default, `--all`, `--group`) |
 | v3.2 | New-project flow hardening: agents in per-layer folders; `new` recommends capability+architecture agents; explain Work Item parser fix; intent vs reality (codebase vs current-state) |
+| v3.3 | Work Item delivery lifecycle: `understand` shows branch → scan → ownership → guard → knowledge → commit for active Work Items (suggestions only; Kaddo never runs git) |
+| v3.4 | Delivery protocol in the `work-item-agent`: branch first per the Git strategy, commit only with human confirmation (CLI never touches git) |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -1950,6 +1950,24 @@ A refined Work Item intended to be saved as \`knowledge/delivery/work-items/*.md
 
 Save the output as a file under \`knowledge/delivery/work-items/\`.
 
+## Delivery workflow
+
+When this Work Item is **implemented** (by you or the coding agent), follow the project's
+delivery protocol. **Never run git mutating commands without the human's confirmation.**
+
+1. **Branch first.** Before changing any code, create a branch following the project's Git
+   strategy (\`.kaddo/git.yml\` \u2192 \`branchNaming.pattern\`, default
+   \`feature/<work-item-id>-<slug>\`; also \`bugfix/\`, \`hotfix/\`, \`spike/\`). This keeps work
+   off the default branch so nothing lands on \`main\` by accident.
+2. Implement the change.
+3. Run \`kaddo scan\` after adding modules, migrations, contracts or significant structure.
+4. Run \`kaddo owners suggest\` and confirm the \`code:\` globs.
+5. Run \`kaddo guard\` before committing to detect possible knowledge drift.
+6. Update the affected knowledge (ADR / capabilities.md / current-state.md).
+7. **Commit only with explicit human confirmation.** Never commit, push or merge on your
+   own \u2014 suggest a Conventional Commit message and wait for the human. The Kaddo CLI itself
+   never touches git.
+
 ## Quality Checklist
 
 - The problem is one clear sentence.
@@ -1957,6 +1975,7 @@ Save the output as a file under \`knowledge/delivery/work-items/\`.
 - Knowledge Level is justified.
 - Acceptance criteria are testable.
 - Open questions are explicit.
+- Delivery: branch first, commit only with human confirmation.
 `;
 var GIT_STRATEGY_AGENT = `# Git Strategy Agent
 
@@ -5185,6 +5204,68 @@ function renderUnderstandTerminal(plan) {
   return lines.join("\n");
 }
 
+// src/core/delivery.ts
+import { parse as parseYaml9 } from "yaml";
+function slugify2(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function isWorkItem(a) {
+  return a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type);
+}
+function toActive(a) {
+  const id = a.id || a.title || "WI";
+  return { id, title: a.title || id, type: a.type, slug: slugify2(a.title || id) };
+}
+function activeWorkItems(dir) {
+  const archDir = join(dir, "knowledge");
+  if (!exists(archDir)) return [];
+  return readArtifacts(archDir).filter((a) => isWorkItem(a) && a.status === "in-progress").map(toActive);
+}
+function branchPrefix(type) {
+  switch (type) {
+    case "bugfix":
+      return "bugfix";
+    case "hotfix":
+      return "hotfix";
+    case "spike":
+      return "spike";
+    default:
+      return "feature";
+  }
+}
+function commitPrefix(type) {
+  switch (type) {
+    case "bugfix":
+    case "hotfix":
+      return "fix";
+    case "spike":
+      return "chore";
+    default:
+      return "feat";
+  }
+}
+function suggestedBranch(wi) {
+  return `${branchPrefix(wi.type)}/${wi.id}-${wi.slug}`;
+}
+function suggestedCommit(wi) {
+  return `${commitPrefix(wi.type)}: ${wi.title.toLowerCase()}`;
+}
+function renderDeliveryLifecycle(wi) {
+  return [
+    `Active work item: ${wi.id} \u2014 ${wi.title}`,
+    "",
+    "Delivery lifecycle (the building agent follows this; Kaddo CLI never touches git):",
+    `  1. Create a branch          ${suggestedBranch(wi)} (per your Git strategy)`,
+    "  2. Implement the work item",
+    "  3. Run `kaddo scan`         (after new modules/migrations/contracts)",
+    "  4. Run `kaddo owners suggest`  \u2192 confirm code: globs",
+    "  5. Run `kaddo guard`        before committing (detect knowledge drift)",
+    "  6. Update knowledge         ADR / capabilities.md / current-state.md as needed",
+    "  7. Review (human)",
+    `  8. Commit only with human confirmation   e.g. ${suggestedCommit(wi)}`
+  ];
+}
+
 // src/commands/understand.ts
 function runUnderstand() {
   const dir = cwd();
@@ -5247,6 +5328,15 @@ function runUnderstand() {
   if (groupAgents.length > 0) {
     console.log(`Agents for this phase: ${groupAgents.join(", ")}`);
   }
+  const active = activeWorkItems(dir);
+  if (active.length > 0) {
+    console.log("");
+    for (const line of renderDeliveryLifecycle(active[0])) console.log(line);
+    if (active.length > 1) {
+      console.log("");
+      console.log(`Other active work items: ${active.slice(1).map((w) => w.id).join(", ")}`);
+    }
+  }
   writeFile(join(dir, ".kaddo", "understand.md"), renderUnderstand(plan));
   log2.success("Wrote .kaddo/understand.md");
   outro2("Handoff ready. CLI prepares context \u2014 your LLM creates the understanding.");
@@ -5470,14 +5560,14 @@ async function runClassify(opts = {}) {
 }
 
 // src/commands/status.ts
-import { parse as parseYaml9 } from "yaml";
+import { parse as parseYaml10 } from "yaml";
 var ARCH_DIR7 = "knowledge";
 var CONFIG_PATH4 = ".kaddo/config.yml";
 function loadConfig3(dir) {
   const p2 = join(dir, CONFIG_PATH4);
   if (!exists(p2)) return {};
   try {
-    return parseYaml9(readFile(p2));
+    return parseYaml10(readFile(p2));
   } catch {
     return {};
   }
@@ -5679,13 +5769,13 @@ function runHistory(opts = {}) {
 }
 
 // src/commands/add.ts
-import { parse as parseYaml10, stringify as stringifyYaml3 } from "yaml";
+import { parse as parseYaml11, stringify as stringifyYaml3 } from "yaml";
 var CONFIG_PATH5 = ".kaddo/config.yml";
 function readProjectState(dir) {
   const configPath = join(dir, CONFIG_PATH5);
   if (!exists(configPath)) return void 0;
   try {
-    const config = parseYaml10(readFile(configPath));
+    const config = parseYaml11(readFile(configPath));
     return config.project?.state;
   } catch {
     return void 0;
@@ -5703,7 +5793,7 @@ function markModuleInstalled(dir, configKey, moduleName) {
   const configPath = join(dir, CONFIG_PATH5);
   if (!exists(configPath)) return;
   try {
-    const config = parseYaml10(readFile(configPath));
+    const config = parseYaml11(readFile(configPath));
     config[configKey] = { installed: true, installed_at: (/* @__PURE__ */ new Date()).toISOString().split("T")[0] };
     const modules = config.modules ?? [];
     if (!modules.includes(moduleName)) modules.push(moduleName);
@@ -5716,7 +5806,7 @@ function isModuleInstalled(dir, configKey) {
   const configPath = join(dir, CONFIG_PATH5);
   if (!exists(configPath)) return false;
   try {
-    const config = parseYaml10(readFile(configPath));
+    const config = parseYaml11(readFile(configPath));
     const moduleConfig = config[configKey];
     return moduleConfig?.installed === true;
   } catch {
@@ -6040,13 +6130,13 @@ ${globs.map((g) => `  - ${g}`).join("\n")}`);
 }
 
 // src/commands/module-descriptor.ts
-import { parse as parseYaml11, stringify as stringifyYaml4 } from "yaml";
+import { parse as parseYaml12, stringify as stringifyYaml4 } from "yaml";
 var DESCRIPTOR_PATH2 = "knowledge/module.yml";
 function readDescriptor(dir) {
   const path5 = join(dir, DESCRIPTOR_PATH2);
   if (!exists(path5)) return null;
   try {
-    return parseYaml11(readFile(path5));
+    return parseYaml12(readFile(path5));
   } catch {
     return null;
   }
@@ -6147,7 +6237,7 @@ function printDescriptor(d) {
 }
 
 // src/commands/modules-map.ts
-import { parse as parseYaml12, stringify as stringifyYaml5 } from "yaml";
+import { parse as parseYaml13, stringify as stringifyYaml5 } from "yaml";
 
 // src/templates/registry.ts
 var QUALITY = "## Quality checklist";
@@ -7638,14 +7728,14 @@ var MODULE_TYPES = [
   "data",
   "unknown"
 ];
-function slugify2(name) {
+function slugify3(name) {
   return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function readModulesDescriptor(dir) {
   const path5 = join(dir, DESCRIPTOR_PATH3);
   if (!exists(path5)) return { version: 1, modules: [] };
   try {
-    const parsed = parseYaml12(readFile(path5));
+    const parsed = parseYaml13(readFile(path5));
     return { version: parsed.version ?? 1, modules: parsed.modules ?? [] };
   } catch {
     return { version: 1, modules: [] };
@@ -7658,7 +7748,7 @@ function moduleDir(id) {
   return `knowledge/tech/modules/${id}`;
 }
 function buildModule(input) {
-  const id = slugify2(input.name);
+  const id = slugify3(input.name);
   const base = moduleDir(id);
   return {
     id,
@@ -7925,7 +8015,7 @@ async function runBootstrap(dir = cwd()) {
 
 // src/index.ts
 var program = new Command();
-program.name("kaddo").description("Knowledge Driven Development toolkit").version("3.2.0");
+program.name("kaddo").description("Knowledge Driven Development toolkit").version("3.4.0");
 program.command("init").description("Initialize Kaddo in the current project").action(async () => {
   await runInit();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/cli",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {