@kaddo/cli 3.3.0 → 3.4.0

package/README.md

@@ -435,6 +435,7 @@ create --from roadmap → owners → guard → explain`.
 | 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
 
@@ -5186,19 +5205,21 @@ function renderUnderstandTerminal(plan) {
 }
 
 // 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((a) => {
-    const id = a.id || a.title || "WI";
-    return { id, title: a.title || id, type: a.type, slug: slugify2(a.title || id) };
-  });
+  return readArtifacts(archDir).filter((a) => isWorkItem(a) && a.status === "in-progress").map(toActive);
 }
 function branchPrefix(type) {
   switch (type) {
@@ -5233,15 +5254,15 @@ function renderDeliveryLifecycle(wi) {
   return [
     `Active work item: ${wi.id} \u2014 ${wi.title}`,
     "",
-    "Delivery lifecycle (Kaddo never runs git for you):",
-    `  1. Create a branch          e.g. ${suggestedBranch(wi)}`,
+    "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                   e.g. ${suggestedCommit(wi)}`
+    `  8. Commit only with human confirmation   e.g. ${suggestedCommit(wi)}`
   ];
 }
 
@@ -5539,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 {};
   }
@@ -5748,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;
@@ -5772,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);
@@ -5785,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 {
@@ -6109,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;
   }
@@ -6216,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";
@@ -7714,7 +7735,7 @@ 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: [] };
@@ -7994,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.3.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.3.0",
+  "version": "3.4.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {