@kaddo/cli 3.5.0 → 3.6.0

package/README.md

@@ -437,6 +437,7 @@ create --from roadmap → owners → guard → explain`.
 | 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

@@ -3093,8 +3093,91 @@ function parseBlock(block) {
     openQuestions: meta.openQuestions.length ? [...meta.openQuestions] : void 0
   }));
 }
+var WI_ID_RE = /\bWI-[A-Za-z0-9-]*\d/;
+var HEADING_RE = /^#{2,4}\s+(.*)$/;
+var FLEX_BULLET_RE = /^\s*[-*]\s+(?:\[[ xX]?\]\s+)?(WI-[A-Za-z0-9-]*\d)\b[\s:.\-–)]*\s*(.*)$/;
+var SEPARATOR_CELL_RE = /^:?-{2,}:?$/;
+function splitRow(line) {
+  return line.replace(/^\s*\|/, "").replace(/\|\s*$/, "").split("|").map((c) => c.trim());
+}
+function isSeparatorRow(cells) {
+  return cells.length > 0 && cells.every((c) => SEPARATOR_CELL_RE.test(c) || c === "");
+}
+function initiativeFromHeading(text3) {
+  const rm = text3.match(/^(RM-[\w.-]+)\s*[:\-–]?\s*(.*)$/);
+  if (rm) return { id: rm[1], title: rm[2].trim() || void 0 };
+  return { title: text3.trim() || void 0 };
+}
+function extractDeps(cell) {
+  if (!cell) return void 0;
+  const ids = cell.match(/WI-[A-Za-z0-9-]*\d/g);
+  return ids && ids.length ? [...new Set(ids)] : void 0;
+}
+function parseFlexible(markdown) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  let initiative;
+  let cols = null;
+  const push = (id, title, deps, raw) => {
+    if (seen.has(id)) return;
+    seen.add(id);
+    out.push({
+      id,
+      title: title.trim() || id,
+      dependencies: deps,
+      initiative: initiative?.id || initiative?.title ? { ...initiative } : void 0,
+      rawMarkdown: raw.trim()
+    });
+  };
+  for (const line of markdown.split(/\r?\n/)) {
+    const h = line.match(HEADING_RE);
+    if (h) {
+      initiative = initiativeFromHeading(h[1]);
+      cols = null;
+      continue;
+    }
+    if (line.includes("|")) {
+      const cells = splitRow(line);
+      if (isSeparatorRow(cells)) continue;
+      const lower = cells.map((c) => c.toLowerCase());
+      const idIdx = lower.findIndex((c) => c === "id" || c === "wi" || c === "work item id");
+      if (idIdx >= 0 && !WI_ID_RE.test(line)) {
+        cols = {
+          id: idIdx,
+          title: lower.findIndex((c) => /work item|title|item|name|description/.test(c)),
+          deps: lower.findIndex((c) => /depend/.test(c))
+        };
+        continue;
+      }
+      if (WI_ID_RE.test(line)) {
+        let idCell = cols && cols.id >= 0 ? cells[cols.id] : cells.find((c) => /^WI-/.test(c));
+        const idMatch = (idCell ?? line).match(/WI-[A-Za-z0-9-]*\d/);
+        if (!idMatch) continue;
+        const id = idMatch[0];
+        const title = cols && cols.title >= 0 ? cells[cols.title] ?? "" : cells.find((c) => !/^WI-/.test(c) && c) ?? "";
+        const deps = cols && cols.deps >= 0 ? extractDeps(cells[cols.deps]) : void 0;
+        push(id, title, deps, line);
+        continue;
+      }
+      continue;
+    }
+    const b = line.match(FLEX_BULLET_RE);
+    if (b) {
+      push(b[1], b[2] ?? "", void 0, line);
+      continue;
+    }
+  }
+  return out;
+}
 function parseRoadmapCandidates(markdown) {
-  return splitInitiatives(markdown).flatMap(parseBlock);
+  const strict = splitInitiatives(markdown).flatMap(parseBlock);
+  if (strict.length > 0) return strict;
+  return parseFlexible(markdown);
+}
+function roadmapStats(markdown, materialized) {
+  if (markdown == null) return { present: false, candidates: 0, materialized, remaining: 0 };
+  const candidates = parseRoadmapCandidates(markdown).length;
+  return { present: true, candidates, materialized, remaining: Math.max(0, candidates - materialized) };
 }
 
 // src/commands/create.ts
@@ -4533,6 +4616,9 @@ function buildProjectExplanation(dir) {
     workItemsMissingOwnership: items.length - withOwnership
   };
   const domains = [...new Set(workItemArtifacts.flatMap((a) => a.domains))].filter(Boolean);
+  const roadmapPath = join(dir, ARCH_DIR3, "delivery", "roadmap.md");
+  const roadmapMd = exists(roadmapPath) ? readFile(roadmapPath) : null;
+  const roadmap = roadmapStats(roadmapMd, items.length);
   const mappedModules = loadMappedModules(dir);
   const missingKnowledge = [];
   if (!knowledge.hasScan) missingKnowledge.push("Scan baseline (.kaddo/scan.json)");
@@ -4560,8 +4646,12 @@ function buildProjectExplanation(dir) {
   }
   if (!knowledge.hasRoadmap) {
     suggestedNextSteps.push("Use roadmap-agent to generate knowledge/delivery/roadmap.md.");
+  } else if (roadmap.remaining > 0) {
+    suggestedNextSteps.push(
+      `Materialize ${roadmap.remaining} roadmap candidate(s) with \`kaddo create --from roadmap\`.`
+    );
   }
-  if (items.length === 0) {
+  if (items.length === 0 && !roadmap.present) {
     suggestedNextSteps.push("Create your first Work Item with `kaddo create`.");
   } else if (ownership.workItemsMissingOwnership > 0) {
     suggestedNextSteps.push(
@@ -4576,6 +4666,7 @@ function buildProjectExplanation(dir) {
     ownership,
     domains,
     layers,
+    roadmap,
     mappedModules,
     missingKnowledge,
     suggestedNextSteps
@@ -4619,7 +4710,14 @@ function renderExplanationHuman(exp) {
   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}`);
+  if (exp.roadmap.present) {
+    lines.push(`- Roadmap candidates: ${exp.roadmap.candidates}`);
+    lines.push(`- Materialized work items: ${exp.roadmap.materialized}`);
+    if (exp.roadmap.remaining > 0)
+      lines.push(`- Remaining candidates: ${exp.roadmap.remaining}`);
+  } else {
+    lines.push(`- Work items: ${exp.workItems.total}`);
+  }
   lines.push(
     `- Ownership coverage: ${exp.ownership.workItemsWithOwnership}/${exp.ownership.workItemsTotal} work items`
   );
@@ -4973,6 +5071,11 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     missing.push("No work items found.");
   }
   const state = config.project.state;
+  const roadmapPath = join(dir, ARCH_DIR5, "delivery", "roadmap.md");
+  const materialized = allArtifacts.filter(
+    (a) => a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type)
+  ).length;
+  const roadmap = roadmapStats(exists(roadmapPath) ? readFile(roadmapPath) : null, materialized);
   const mappedModules = loadMappedModules(dir);
   const layers = knowledgeLayers(dir);
   return {
@@ -5002,6 +5105,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
       artifacts: workItems.filter((a) => a.codeGlobs.length > 0).map(toContextArtifact)
     },
     layers,
+    roadmap,
     mappedModules,
     missing,
     handoff: {
@@ -5076,6 +5180,20 @@ function renderContextPack(pack) {
   parts.push("## Current Knowledge\n");
   parts.push((knowledge.summary || "No project knowledge summary found yet.") + "\n");
   parts.push("## Roadmap\n");
+  if (pack.roadmap.present) {
+    parts.push(
+      [
+        `- Roadmap candidates: ${pack.roadmap.candidates}`,
+        `- Materialized work items: ${pack.roadmap.materialized}`,
+        `- Remaining candidates: ${pack.roadmap.remaining}`
+      ].join("\n") + "\n"
+    );
+    if (pack.roadmap.remaining > 0) {
+      parts.push(
+        "Candidates are not yet Work Items. Materialize them with `kaddo create --from roadmap`.\n"
+      );
+    }
+  }
   parts.push((knowledge.roadmapSummary || "No roadmap baseline found.") + "\n");
   parts.push("## Existing Work Items\n");
   if (knowledge.workItems.length > 0) {
@@ -5439,8 +5557,11 @@ function runUnderstand() {
     utilities: ["Use legacy-agent to surface risks and unknowns"]
   };
   if (roadmapHasUnmaterializedCandidates(dir)) {
+    const { candidates, materialized, remaining } = pack.roadmap;
     console.log("");
-    console.log("The roadmap has Work Item candidates that are not materialized yet.");
+    console.log(
+      `The roadmap has ${remaining} unmaterialized Work Item candidate(s) (${candidates} candidate(s), ${materialized} materialized).`
+    );
     console.log("  \u2192 Run `kaddo create --from roadmap`, or use the work-item-agent to");
     console.log("    materialize them into knowledge/delivery/work-items/.");
   }
@@ -8145,7 +8266,7 @@ async function runBootstrap(dir = cwd()) {
 
 // src/index.ts
 var program = new Command();
-program.name("kaddo").description("Knowledge Driven Development toolkit").version("3.5.0");
+program.name("kaddo").description("Knowledge Driven Development toolkit").version("3.6.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.5.0",
+  "version": "3.6.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {