@kaddo/cli 3.4.0 → 3.5.1

package/README.md

@@ -436,6 +436,8 @@ create --from roadmap → owners → guard → explain`.
 | 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) |
+| v3.5 | Knowledge discovery by front-matter type with per-layer maturity (explain/understand/context); context pack carries Operating Rules so agents never commit without confirmation |
+| v3.5.1 | Author attribution & knowledge identity: Kaddo as a practical implementation of KDD for AI-assisted development (docs/README) |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -2592,6 +2592,14 @@ var agentReadme = {
     "",
     "**Kaddo does not execute these agents.** The CLI prepares context; the LLM interprets.",
     "",
+    "## Operating rules (apply to every agent)",
+    "",
+    "- **Never run `git commit`, `git push` or `git merge` without explicit human confirmation.**",
+    "- Never push or merge automatically. Suggest a Conventional Commit message and wait.",
+    "- When implementing a Work Item, create a branch first (per the Git strategy in",
+    "  `.kaddo/git.yml`); never work directly on `main`.",
+    "- The Kaddo CLI never calls an LLM and never runs git \u2014 every git action is the human\u2019s.",
+    "",
     "## How to use",
     "",
     "1. Run `kaddo scan` then `kaddo context` to generate `.kaddo/context-pack.md`.",
@@ -4263,59 +4271,158 @@ function runIgnoreRemove(artifactId) {
 import matter2 from "gray-matter";
 import { parse as parseYaml8 } from "yaml";
 
-// src/core/layers.ts
+// src/core/knowledge-discovery.ts
 var KNOWLEDGE = "knowledge";
-var LAYER_SPEC = [
-  {
-    layer: "Business",
-    items: [
-      { name: "problem", path: `${KNOWLEDGE}/business/problem.md` },
-      { name: "users", path: `${KNOWLEDGE}/business/users.md` },
-      { name: "value-proposition", path: `${KNOWLEDGE}/business/value-proposition.md` },
-      { name: "constraints", path: `${KNOWLEDGE}/business/constraints.md` },
-      { name: "business-rules", path: `${KNOWLEDGE}/business/business-rules.md` }
-    ]
-  },
-  {
-    layer: "Product",
-    items: [
-      { name: "product brief", path: `${KNOWLEDGE}/product/product-brief.md` },
-      { name: "capabilities", path: `${KNOWLEDGE}/product/capabilities.md` }
-    ]
-  },
-  {
-    layer: "Tech",
-    items: [
-      { name: "codebase", path: `${KNOWLEDGE}/tech/codebase.md` },
-      { name: "current-state", path: `${KNOWLEDGE}/tech/current-state.md` },
-      { name: "decisions", path: `${KNOWLEDGE}/tech/decisions` }
-    ]
-  },
-  {
-    layer: "Delivery",
-    items: [
-      { name: "roadmap", path: `${KNOWLEDGE}/delivery/roadmap.md` },
-      { name: "work items", path: `${KNOWLEDGE}/delivery/work-items` }
-    ]
+var CONSOLIDATED_TYPE = {
+  Business: "business",
+  Product: "product",
+  Tech: "codebase"
+};
+var STRUCTURED_TYPES = {
+  Business: /* @__PURE__ */ new Set(["problem", "users", "value-proposition", "business-rules", "constraints", "glossary"]),
+  Product: /* @__PURE__ */ new Set(["product-brief", "capabilities"]),
+  Tech: /* @__PURE__ */ new Set([
+    "current-state",
+    "architecture-notes",
+    "decision-candidates",
+    "quality-attributes",
+    "stack",
+    "standards",
+    "security",
+    "git-strategy",
+    "module-design",
+    "adr",
+    "decision"
+  ]),
+  Delivery: /* @__PURE__ */ new Set([])
+};
+var WORK_ITEM_TYPES = /* @__PURE__ */ new Set([
+  "work-item",
+  "feature",
+  "bugfix",
+  "hotfix",
+  "spike"
+]);
+function layerForType(type) {
+  if (!type) return null;
+  if (type === CONSOLIDATED_TYPE.Business || STRUCTURED_TYPES.Business.has(type)) return "Business";
+  if (type === CONSOLIDATED_TYPE.Product || STRUCTURED_TYPES.Product.has(type)) return "Product";
+  if (type === CONSOLIDATED_TYPE.Tech || STRUCTURED_TYPES.Tech.has(type) || type === "knowledge")
+    return "Tech";
+  if (type === "roadmap" || WORK_ITEM_TYPES.has(type)) return "Delivery";
+  return null;
+}
+function layerFromPath(filePath) {
+  const p2 = filePath.replace(/\\/g, "/");
+  if (p2.includes(`/${KNOWLEDGE}/business/`)) return "Business";
+  if (p2.includes(`/${KNOWLEDGE}/product/`)) return "Product";
+  if (p2.includes(`/${KNOWLEDGE}/tech/`)) return "Tech";
+  if (p2.includes(`/${KNOWLEDGE}/delivery/`)) return "Delivery";
+  return null;
+}
+function basename(p2) {
+  return p2.replace(/\\/g, "/").split("/").pop() ?? p2;
+}
+function discoverLayers(dir) {
+  const acc = {
+    Business: blank(),
+    Product: blank(),
+    Tech: blank(),
+    Delivery: blank()
+  };
+  const archDir = join(dir, KNOWLEDGE);
+  const artifacts = exists(archDir) ? readArtifacts(archDir) : [];
+  for (const a of artifacts) {
+    const type = a.type;
+    const layer = layerForType(type) ?? layerFromPath(a.filePath);
+    if (!layer) continue;
+    const slot = acc[layer];
+    slot.detected.add(basename(a.filePath));
+    if (layer === "Delivery") {
+      if (type === "roadmap" || basename(a.filePath) === "roadmap.md") slot.hasRoadmap = true;
+      if (WORK_ITEM_TYPES.has(type) || a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/")) {
+        if (a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/")) slot.hasWorkItem = true;
+      }
+      continue;
+    }
+    if (type === CONSOLIDATED_TYPE[layer]) slot.consolidated = true;
+    else if (STRUCTURED_TYPES[layer].has(type)) slot.structured = true;
+    else if (!type) {
+      slot.consolidated = true;
+    }
+    if (type === "adr" || type === "decision") slot.hasDecision = true;
   }
-];
-function knowledgeLayers(dir) {
-  return LAYER_SPEC.map(({ layer, items }) => ({
+  if (existsDirWithMd(join(dir, KNOWLEDGE, "tech", "decisions"))) acc.Tech.structured = true;
+  return ["Business", "Product", "Tech", "Delivery"].map((layer) => ({
     layer,
-    items: items.map((it) => ({ name: it.name, present: exists(join(dir, it.path)) }))
+    status: statusFor(layer, acc[layer]),
+    detected: [...acc[layer].detected].sort()
   }));
 }
+function blank() {
+  return {
+    consolidated: false,
+    structured: false,
+    hasRoadmap: false,
+    hasWorkItem: false,
+    hasDecision: false,
+    detected: /* @__PURE__ */ new Set()
+  };
+}
+function existsDirWithMd(d) {
+  if (!exists(d)) return false;
+  try {
+    return readDir(d).some((e) => e.endsWith(".md") && isFile(join(d, e)));
+  } catch {
+    return false;
+  }
+}
+function statusFor(layer, a) {
+  if (layer === "Delivery") {
+    if (a.hasWorkItem) return "Traceable";
+    if (a.hasRoadmap) return "Partial";
+    return "Missing";
+  }
+  if (a.structured) return "Structured";
+  if (a.consolidated) return "Consolidated";
+  return "Missing";
+}
+function roadmapHasUnmaterializedCandidates(dir) {
+  const roadmap = join(dir, KNOWLEDGE, "delivery", "roadmap.md");
+  if (!exists(roadmap)) return false;
+  let hasCandidates = false;
+  try {
+    hasCandidates = /WI-[A-Z0-9-]*\d/i.test(readFile(roadmap));
+  } catch {
+    return false;
+  }
+  if (!hasCandidates) return false;
+  const wiDir = join(dir, KNOWLEDGE, "delivery", "work-items");
+  return !existsDirWithMd(wiDir);
+}
+
+// src/core/layers.ts
+function knowledgeLayers(dir) {
+  return discoverLayers(dir);
+}
+var COMPLETE = {
+  Business: (s) => s !== "Missing",
+  Product: (s) => s !== "Missing",
+  Tech: (s) => s !== "Missing",
+  Delivery: (s) => s === "Traceable"
+};
 function currentPhase(layers) {
-  for (const { layer, items } of layers) {
-    if (items.some((i) => !i.present)) return layer;
+  for (const l of layers) {
+    if (!COMPLETE[l.layer](l.status)) return l.layer;
   }
   return "Delivery";
 }
 function renderLayersMarkdown(layers) {
   const lines = [];
-  for (const { layer, items } of layers) {
-    lines.push(`### ${layer}`);
-    for (const it of items) lines.push(`- ${it.present ? "\u2713" : "\u2717"} ${it.name}`);
+  for (const { layer, status, detected } of layers) {
+    lines.push(`### ${layer} \u2014 ${status}`);
+    if (detected.length > 0) for (const d of detected) lines.push(`- \u2713 ${d}`);
+    else lines.push("- \u2717 none");
     lines.push("");
   }
   return lines.join("\n").trimEnd();
@@ -4386,14 +4493,16 @@ function buildProjectExplanation(dir) {
     contractFiles: scan2.contractFiles,
     infrastructureFiles: scan2.infrastructureFiles
   } : null;
+  const layers = knowledgeLayers(dir);
+  const layerStatus = (name) => layers.find((l) => l.layer === name)?.status ?? "Missing";
   const knowledge = {
     hasScan: scan2 !== null,
     hasInventory: exists(join(dir, ARCH_DIR3, "inventory.md")),
     hasContextPack: exists(join(dir, ".kaddo", "context-pack.md")),
     hasUnderstand: exists(join(dir, ".kaddo", "understand.md")),
-    hasCapabilities: exists(join(dir, ARCH_DIR3, "product", "capabilities.md")),
-    hasArchitecture: exists(join(dir, ARCH_DIR3, "tech", "current-state.md")),
-    hasRoadmap: exists(join(dir, ARCH_DIR3, "delivery", "roadmap.md")),
+    hasCapabilities: layerStatus("Product") !== "Missing",
+    hasArchitecture: layerStatus("Tech") !== "Missing",
+    hasRoadmap: layerStatus("Delivery") !== "Missing",
     hasAgents: hasAgents(dir)
   };
   const archDir = join(dir, ARCH_DIR3);
@@ -4429,10 +4538,8 @@ function buildProjectExplanation(dir) {
   if (!knowledge.hasScan) missingKnowledge.push("Scan baseline (.kaddo/scan.json)");
   if (!knowledge.hasContextPack) missingKnowledge.push("Context pack (.kaddo/context-pack.md)");
   if (!knowledge.hasInventory) missingKnowledge.push("Inventory (knowledge/inventory.md)");
-  if (!knowledge.hasCapabilities)
-    missingKnowledge.push("Capabilities (knowledge/product/capabilities.md)");
-  if (!knowledge.hasArchitecture)
-    missingKnowledge.push("Architecture baseline (knowledge/tech/current-state.md)");
+  if (!knowledge.hasCapabilities) missingKnowledge.push("Product knowledge (knowledge/product/)");
+  if (!knowledge.hasArchitecture) missingKnowledge.push("Tech knowledge (knowledge/tech/)");
   if (!knowledge.hasRoadmap) missingKnowledge.push("Roadmap (knowledge/delivery/roadmap.md)");
   if (!knowledge.hasAgents) missingKnowledge.push("Agents (knowledge/agents/)");
   if (items.length === 0) missingKnowledge.push("Work items (knowledge/delivery/work-items/)");
@@ -4468,7 +4575,7 @@ function buildProjectExplanation(dir) {
     workItems,
     ownership,
     domains,
-    layers: knowledgeLayers(dir),
+    layers,
     mappedModules,
     missingKnowledge,
     suggestedNextSteps
@@ -4503,14 +4610,14 @@ function renderExplanationHuman(exp) {
       lines.push(`- Infrastructure: ${exp.stack.infrastructureFiles.join(", ")}`);
     lines.push("");
   }
+  const ls = (name) => exp.layers.find((l) => l.layer === name)?.status ?? "Missing";
   lines.push("## Knowledge Status");
   lines.push(`- Inventory: ${exp.knowledge.hasInventory ? "available" : "missing"}`);
   lines.push(`- Context pack: ${exp.knowledge.hasContextPack ? "available" : "missing"}`);
-  lines.push(`- Capabilities: ${exp.knowledge.hasCapabilities ? "available" : "missing"}`);
-  lines.push(
-    `- Architecture baseline: ${exp.knowledge.hasArchitecture ? "available" : "missing"}`
-  );
-  lines.push(`- Roadmap: ${exp.knowledge.hasRoadmap ? "available" : "missing"}`);
+  lines.push(`- Business: ${ls("Business")}`);
+  lines.push(`- Product: ${ls("Product")}`);
+  lines.push(`- Tech: ${ls("Tech")}`);
+  lines.push(`- Delivery: ${ls("Delivery")}`);
   lines.push(`- Agents: ${exp.knowledge.hasAgents ? "available" : "missing"}`);
   lines.push(`- Work items: ${exp.workItems.total}`);
   lines.push(
@@ -4818,6 +4925,13 @@ var LLM_INSTRUCTIONS = [
   "First extract: system capabilities, architecture notes, risks, open questions and roadmap candidates.",
   "This pack is deterministic CLI output \u2014 it does not interpret the system. That is your job."
 ];
+var OPERATING_RULES = [
+  "**Never run `git commit`, `git push` or `git merge` without explicit human confirmation.**",
+  "Never push or merge automatically \u2014 ever. Suggest a Conventional Commit message and wait.",
+  "When implementing a Work Item, create a branch FIRST (per the project Git strategy, `.kaddo/git.yml`, default `feature/<id>-<slug>`). Never work directly on `main`.",
+  "After significant changes run `kaddo scan`, `kaddo owners suggest` and `kaddo guard`, and update the affected knowledge (ADR / capabilities / current-state).",
+  "Kaddo itself never calls an LLM and never runs git \u2014 every git action is the human\u2019s."
+];
 function toContextWorkItem(a) {
   return {
     id: a.id,
@@ -4893,7 +5007,8 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     handoff: {
       recommendedAgents: recommendedAgentsForState(state),
       nextSteps: nextStepsForState2(state),
-      instructions: LLM_INSTRUCTIONS
+      instructions: LLM_INSTRUCTIONS,
+      operatingRules: OPERATING_RULES
     }
   };
 }
@@ -4912,6 +5027,8 @@ function renderContextPack(pack) {
   parts.push(
     "> Generated by `kaddo context`. Deterministic CLI output \u2014 not an interpretation of the system.\n"
   );
+  parts.push("## Operating Rules (read first)\n");
+  parts.push(handoff.operatingRules.map((r) => `- ${r}`).join("\n") + "\n");
   parts.push("## Project Metadata\n");
   parts.push(
     [
@@ -4925,6 +5042,9 @@ function renderContextPack(pack) {
   parts.push(
     "Project knowledge is organized in four layers: **Business \u2192 Product \u2192 Tech \u2192 Delivery**.\n"
   );
+  const maturity = pack.layers.map((l) => `${l.layer}: ${l.status}`).join(" \xB7 ");
+  parts.push(`Knowledge maturity \u2014 ${maturity}
+`);
   parts.push(renderLayersMarkdown(pack.layers) + "\n");
   parts.push("## Technical Inventory\n");
   if (scan2.available) {
@@ -5318,6 +5438,12 @@ function runUnderstand() {
     ],
     utilities: ["Use legacy-agent to surface risks and unknowns"]
   };
+  if (roadmapHasUnmaterializedCandidates(dir)) {
+    console.log("");
+    console.log("The roadmap has Work Item candidates that are not materialized yet.");
+    console.log("  \u2192 Run `kaddo create --from roadmap`, or use the work-item-agent to");
+    console.log("    materialize them into knowledge/delivery/work-items/.");
+  }
   console.log("");
   console.log(`Current phase: ${phase}`);
   console.log("Recommended next steps:");
@@ -8008,6 +8134,10 @@ async function runBootstrap(dir = cwd()) {
     for (const p2 of result.skipped) console.log(`  - ${p2}`);
   }
   console.log("");
+  console.log("");
+  log2.info(
+    "When you pass the context pack to your LLM/coding agent, it must never commit, push or merge without your confirmation \u2014 and create a branch before implementing."
+  );
   outro2(
     "Minimal knowledge base ready (Business \u2192 Product \u2192 Tech). Run `kaddo context` and `kaddo add agents`, then refine with the business-agent, bootstrap-agent and codebase-agent. Roadmap and work items come next under knowledge/delivery/."
   );
@@ -8015,7 +8145,7 @@ async function runBootstrap(dir = cwd()) {
 
 // src/index.ts
 var program = new Command();
-program.name("kaddo").description("Knowledge Driven Development toolkit").version("3.4.0");
+program.name("kaddo").description("Knowledge Driven Development toolkit").version("3.5.1");
 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.4.0",
+  "version": "3.5.1",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {