@kaddo/cli 3.14.0 → 3.15.0

package/dist/index.js

@@ -624,8 +624,8 @@ function createGuidanceForState(state) {
 }
 function describeProject(config) {
   const state = config.project.state;
-  const stateLabel4 = state === "pre-ai" ? "pre-AI" : state;
-  return `${stateLabel4} ${config.project.structure}`;
+  const stateLabel3 = state === "pre-ai" ? "pre-AI" : state;
+  return `${stateLabel3} ${config.project.structure}`;
 }
 
 // src/core/command-help.ts
@@ -1611,6 +1611,19 @@ var RESPONSIBILITY_MATRIX = {
     ],
     next: ["kaddo scan", "kaddo owners suggest", "kaddo guard", "kaddo explain"]
   },
+  "ownership-agent": {
+    agent: "ownership-agent",
+    responsibleFor: ["Precise code: ownership for Work Items and artifacts"],
+    produces: ["proposed code: globs"],
+    canSuggest: ["kaddo owners suggest", "kaddo guard"],
+    cannotSuggest: [
+      "code",
+      "branches",
+      "commits",
+      "modifying files without confirmation"
+    ],
+    next: ["kaddo owners suggest", "kaddo guard"]
+  },
   "guard-agent": {
     agent: "guard-agent",
     responsibleFor: ["Knowledge drift"],
@@ -1884,13 +1897,15 @@ Generated from Kaddo Context Pack.
 
 Save the architecture overview as \`knowledge/tech/current-state.md\`, supporting notes as
 \`knowledge/tech/architecture-notes.md\`, and decision candidates as
-\`knowledge/tech/decision-candidates.md\`.
+\`knowledge/tech/decision-candidates.md\`. Final ADRs always live under
+\`knowledge/tech/decisions/\` \u2014 never directly in \`knowledge/tech/\`.
 
 ## Quality Checklist
 
 - Every component is backed by evidence from the context pack.
 - Assumptions and confidence are explicit.
 - No final decisions are asserted \u2014 only candidates.
+- Final ADRs go to \`knowledge/tech/decisions/\`, not \`knowledge/tech/\`.
 - Open questions are listed.
 `;
 var ROADMAP_AGENT = `# Roadmap Agent
@@ -2209,12 +2224,16 @@ Generated from Kaddo Context Pack.
 
 ## Where to Save the Result
 
-Save the output as \`knowledge/tech/decision-candidates.md\`.
+Save decision **candidates** as \`knowledge/tech/decision-candidates.md\`. When a candidate becomes
+a **final ADR**, it must live under \`knowledge/tech/decisions/\` (one file per decision, e.g.
+\`knowledge/tech/decisions/ADR-0001-<slug>.md\`) \u2014 **never** directly in \`knowledge/tech/\`.
+(Decision = the concept \xB7 ADR = the format \xB7 Path = \`knowledge/tech/decisions/\`.)
 
 ## Quality Checklist
 
 - Each candidate has context and alternatives.
 - No decision is asserted as final.
+- Final ADRs go to \`knowledge/tech/decisions/\`, never to \`knowledge/tech/\` directly.
 - Assumptions are marked.
 - Validation needs are explicit.
 `;
@@ -2913,6 +2932,69 @@ Code, tests and migrations live in the repository. Knowledge updates go under \`
 - Affected knowledge is updated.
 - Commit is suggested and awaits human confirmation \u2014 never run automatically.
 `;
+var OWNERSHIP_AGENT = `# Ownership Agent
+
+## Role
+
+You are the Kaddo Ownership Agent. Your job is to propose **precise** \`code:\` ownership globs for
+Work Items and knowledge artifacts, so Guard can relate code changes to the right knowledge.
+
+You do not write code, you do not modify files, and you never run Git. You propose; the human
+confirms and applies (with \`kaddo owners suggest\`).
+
+## When to Use
+
+Use this agent after \`kaddo scan\` and \`kaddo context\`, when Work Items or artifacts are missing
+\`code:\` ownership, or when existing ownership is too broad or inaccurate.
+
+## Input Required
+
+Provide \`.kaddo/context-pack.md\` as the primary input, plus the Work Items under
+\`knowledge/delivery/work-items/\`, \`knowledge/tech/codebase.md\` and \`knowledge/inventory.md\` when
+they exist (for the real source structure).
+
+## Expected Output
+
+For each artifact, a precise set of \`code:\` globs.
+
+## Instructions
+
+1. Map each Work Item / artifact to the smallest set of paths that actually implement it.
+2. Prefer **narrow** globs (e.g. \`src/payments/**\`) over broad ones (e.g. \`src/**\`).
+3. Use real paths from the inventory/codebase \u2014 do not invent directories.
+4. Include relevant root files (e.g. \`package.json\`, \`tsconfig.json\`) when they belong.
+5. Flag artifacts where ownership is genuinely unclear instead of guessing broadly.
+
+## Constraints
+
+- Do not implement code.
+- Do not modify files without confirmation \u2014 propose globs for the human to apply.
+- Do not create branches or commits; never run Git.
+- Prefer precision: broad globs reduce Guard usefulness.
+
+## Output Format
+
+\`\`\`yaml
+# <Work Item id> \u2014 proposed ownership
+code:
+  - package.json
+  - tsconfig.json
+  - src/cli/**
+  - src/shared/**
+\`\`\`
+
+## Where to Save the Result
+
+The human applies the proposed globs to the artifact's front matter with \`kaddo owners suggest\`
+(or by editing the \`code:\` field). This agent does not write files.
+
+## Quality Checklist
+
+- Globs are narrow and based on real paths.
+- No \`src/**\`-style catch-alls unless truly justified.
+- Unclear ownership is flagged, not guessed.
+- Output is a proposal for human confirmation \u2014 nothing is applied automatically.
+`;
 var BACKLOG_AGENT = `# Backlog Agent
 
 ## Role
@@ -3024,7 +3106,9 @@ var AGENT_PROMPTS = [
   // Implementation (the only agent that may suggest a branch — VS-044)
   { fileName: "implementation-agent.md", content: IMPLEMENTATION_AGENT },
   // Backlog capture (idea → draft / roadmap candidate — VS-050)
-  { fileName: "backlog-agent.md", content: BACKLOG_AGENT }
+  { fileName: "backlog-agent.md", content: BACKLOG_AGENT },
+  // Ownership proposals (precise code: globs — VS-052)
+  { fileName: "ownership-agent.md", content: OWNERSHIP_AGENT }
   // Every official prompt ends with its responsibility boundaries + Agent Trace footer.
 ].map((p2) => ({ fileName: p2.fileName, content: withResponsibilityTrace(p2.fileName, p2.content) }));
 
@@ -3046,6 +3130,7 @@ var AGENT_GROUPS = {
     "roadmap-agent.md",
     "work-item-agent.md",
     "implementation-agent.md",
+    "ownership-agent.md",
     "git-strategy-agent.md"
   ],
   utilities: ["legacy-agent.md"]
@@ -3079,7 +3164,8 @@ var RECOMMENDED_BY_STATE = {
     "roadmap-agent.md",
     "backlog-agent.md",
     "work-item-agent.md",
-    "implementation-agent.md"
+    "implementation-agent.md",
+    "ownership-agent.md"
   ],
   legacy: [
     "legacy-agent.md",
@@ -3088,7 +3174,8 @@ var RECOMMENDED_BY_STATE = {
     "roadmap-agent.md",
     "backlog-agent.md",
     "work-item-agent.md",
-    "implementation-agent.md"
+    "implementation-agent.md",
+    "ownership-agent.md"
   ]
 };
 function recommendedAgents(state) {
@@ -4234,6 +4321,14 @@ async function isGitRepo(dir) {
     return false;
   }
 }
+async function getUntrackedFiles() {
+  try {
+    const result = await execa("git", ["ls-files", "--others", "--exclude-standard"]);
+    return result.stdout.split("\n").map((f) => f.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
 
 // src/services/artifact-reader.ts
 import matter from "gray-matter";
@@ -4254,7 +4349,8 @@ function parseArtifact(filePath, raw) {
       status: String(data.status ?? ""),
       phase: String(data.phase ?? ""),
       initiative: String(data.initiative ?? data.source_initiative ?? ""),
-      source: data.source ? String(data.source) : ""
+      source: data.source ? String(data.source) : "",
+      sourceId: String(data.source_id ?? "")
     };
   } catch {
     return null;
@@ -4892,6 +4988,15 @@ async function runGuard(opts = {}) {
   const plugins = resolvePlugins(config.plugins ?? []);
   const mode = opts.staged ? "staged" : "head";
   const currentFiles = await getModifiedFiles(mode);
+  const untrackedFiles = opts.staged ? [] : await getUntrackedFiles();
+  const printUntracked = () => {
+    if (untrackedFiles.length === 0 || jsonMode) return;
+    console.log("");
+    console.log(`Untracked files detected (${untrackedFiles.length}):`);
+    for (const f of untrackedFiles.slice(0, 10)) console.log(`  - ${f}`);
+    if (untrackedFiles.length > 10) console.log(`  \u2026and ${untrackedFiles.length - 10} more`);
+    console.log("Guard may not fully evaluate these files until they are tracked. (FYI \u2014 non-blocking)");
+  };
   let workspaceScan = null;
   if (opts.workspace) {
     workspaceScan = await collectWorkspaceChanges(dir, mode);
@@ -4901,6 +5006,7 @@ async function runGuard(opts = {}) {
   if (touchedFiles.length === 0) {
     if (workspaceScan) printWorkspaceHeader(workspaceScan);
     console.log("kaddo guard: no modified files detected.");
+    printUntracked();
     return;
   }
   const archDir = join(dir, ARCH_DIR3);
@@ -4940,10 +5046,12 @@ async function runGuard(opts = {}) {
     if (workspaceScan) printWorkspaceHeader(workspaceScan);
     printHeader(touchedFiles);
     console.log("  No artifact ownership matches found.");
+    printUntracked();
     return;
   }
   if (workspaceScan) printWorkspaceHeader(workspaceScan);
   printHeader(touchedFiles);
+  printUntracked();
   for (const match of activeMatches) {
     printFYI(match, dir);
   }
@@ -5069,22 +5177,30 @@ function assessPhase(input) {
   const firstOf = (s) => items.find((i) => i.lifecycle === s);
   let recommendedAgents2 = [];
   let nextStep = "";
+  let llmInstructions = [];
   switch (phase) {
     case "Discovery": {
       const m = firstMissingLayerAgent(input.layers);
       recommendedAgents2 = [m.agent];
       nextStep = m.step;
+      llmInstructions = [`Use the ${m.agent} to fill the missing base knowledge.`, "Do not write code."];
       break;
     }
     case "Planning": {
       recommendedAgents2 = ["roadmap-agent"];
       nextStep = "Use roadmap-agent to create knowledge/delivery/roadmap.md";
+      llmInstructions = ["Use the roadmap-agent.", "Do not write code.", "Generate roadmap candidates."];
       break;
     }
     case "Delivery Preparation": {
       recommendedAgents2 = ["kaddo create --from roadmap", "work-item-agent"];
       const n = input.roadmap.remaining || input.roadmap.candidates;
       nextStep = `Run \`kaddo create --from roadmap\`${n ? ` (${n} candidate(s))` : ""}, then refine with work-item-agent`;
+      llmInstructions = [
+        "Materialize roadmap candidates with `kaddo create --from roadmap`.",
+        "Use the work-item-agent to refine them.",
+        "Do not implement yet."
+      ];
       break;
     }
     case "Active Delivery": {
@@ -5092,21 +5208,41 @@ function assessPhase(input) {
         const wi = firstOf("ready");
         recommendedAgents2 = ["implementation-agent"];
         nextStep = wi ? `Start ${wi.id} \u2014 ${wi.title} (ready \u2192 in-progress)` : "Start a ready Work Item";
+        llmInstructions = [
+          "Use the implementation-agent.",
+          "Suggest a branch name only.",
+          "Do not run git commands."
+        ];
       } else if (bs["in-progress"] > 0) {
         const wi = firstOf("in-progress");
         recommendedAgents2 = ["implementation-agent", "kaddo scan", "kaddo owners suggest", "kaddo guard"];
         nextStep = wi ? `Continue ${wi.id} \u2014 ${wi.title}; then run kaddo scan, owners suggest, guard` : "Continue the in-progress Work Item; then scan, owners suggest, guard";
+        llmInstructions = [
+          "Continue the in-progress Work Item with the implementation-agent.",
+          "After changes, run `kaddo scan`, `kaddo owners suggest` and `kaddo guard`.",
+          "Do not commit, push or merge without explicit human confirmation."
+        ];
       } else if (bs.draft > 0) {
         const wi = firstOf("draft");
         recommendedAgents2 = ["work-item-agent"];
         nextStep = wi ? `Refine ${wi.id} from draft to ready` : "Refine a draft Work Item to ready";
+        llmInstructions = [
+          "Refine draft Work Items to ready.",
+          "Use the work-item-agent.",
+          "Do not implement unless the user explicitly asks."
+        ];
       } else if (bs.blocked > 0) {
         const wi = firstOf("blocked");
         recommendedAgents2 = ["work-item-agent"];
         nextStep = wi ? `Resolve the blocker on ${wi.id} \u2014 ${wi.title}` : "Resolve the blockers on active work";
+        llmInstructions = [
+          "Resolve the blockers with the work-item-agent.",
+          "Do not implement blocked work."
+        ];
       }
       if (input.ownership.workItemsMissingOwnership > 0) {
         recommendedAgents2.push("kaddo owners suggest");
+        llmInstructions.push("Ownership is incomplete \u2014 propose `code:` globs (run `kaddo owners suggest`).");
       }
       break;
     }
@@ -5114,14 +5250,16 @@ function assessPhase(input) {
       if (input.roadmap.remaining > 0) {
         recommendedAgents2 = ["kaddo create --from roadmap", "work-item-agent"];
         nextStep = `Materialize ${input.roadmap.remaining} remaining roadmap candidate(s)`;
+        llmInstructions = ["Materialize the remaining roadmap candidates.", "Do not implement yet."];
       } else {
         recommendedAgents2 = ["roadmap-agent"];
         nextStep = "No active work \u2014 use roadmap-agent to plan the next initiative";
+        llmInstructions = ["No active work.", "Use the roadmap-agent to plan the next initiative."];
       }
       break;
     }
   }
-  return { phase, reasons, recommendedAgents: recommendedAgents2, nextStep };
+  return { phase, reasons, recommendedAgents: recommendedAgents2, nextStep, llmInstructions };
 }
 
 // src/core/knowledge-discovery.ts
@@ -5258,6 +5396,30 @@ function renderLayersMarkdown(layers) {
 
 // src/core/project-explain.ts
 var ARCH_DIR4 = "knowledge";
+function normalizeTitle(t) {
+  return t.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, " ").trim();
+}
+function findDuplicateWorkItems(items) {
+  const groups = [];
+  const seen = /* @__PURE__ */ new Set();
+  const bucket = (key, reason, pred) => {
+    const matched = items.filter(pred);
+    if (matched.length > 1) {
+      const id = `${reason}:${key}:${matched.map((m) => m.id).sort().join(",")}`;
+      if (!seen.has(id)) {
+        seen.add(id);
+        groups.push({ reason, items: matched.map((m) => ({ id: m.id, title: m.title })) });
+      }
+    }
+  };
+  for (const sid of new Set(items.map((i) => i.sourceId).filter(Boolean))) {
+    bucket(sid, `same source candidate (${sid})`, (i) => i.sourceId === sid);
+  }
+  for (const nt of new Set(items.map((i) => normalizeTitle(i.title)).filter(Boolean))) {
+    bucket(nt, "same normalized title", (i) => normalizeTitle(i.title) === nt);
+  }
+  return groups;
+}
 function first(values) {
   if (Array.isArray(values)) {
     const v = values.find((x) => typeof x === "string" && x);
@@ -5376,6 +5538,9 @@ function buildProjectExplanation(dir) {
     workItemsMissingOwnership: items.length - withOwnership
   };
   const domains = [...new Set(workItemArtifacts.flatMap((a) => a.domains))].filter(Boolean);
+  const duplicateWorkItems = findDuplicateWorkItems(
+    workItemArtifacts.map((a) => ({ id: a.id || a.title, title: a.title, sourceId: a.sourceId }))
+  );
   const roadmapPath = join(dir, ARCH_DIR4, "delivery", "roadmap.md");
   const roadmapMd = exists(roadmapPath) ? readFile(roadmapPath) : null;
   const roadmap = roadmapStats(roadmapMd, items.length);
@@ -5425,6 +5590,7 @@ function buildProjectExplanation(dir) {
     workItems,
     ownership,
     domains,
+    duplicateWorkItems,
     layers,
     roadmap,
     mappedModules,
@@ -5558,6 +5724,15 @@ function renderExplanationHuman(exp) {
     for (const m of exp.missingKnowledge) lines.push(`- ${m}`);
     lines.push("");
   }
+  if (exp.duplicateWorkItems.length > 0) {
+    lines.push("## Possible Duplicate Work Items");
+    for (const g of exp.duplicateWorkItems) {
+      lines.push(`- ${g.reason}:`);
+      for (const i of g.items) lines.push(`  - ${i.id} \u2014 ${i.title}`);
+    }
+    lines.push("Review before continuing (non-blocking).");
+    lines.push("");
+  }
   const assessment = assessPhase(exp);
   lines.push("## Phase");
   lines.push(`- Phase: ${assessment.phase}`);
@@ -5952,10 +6127,12 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     deliveryMix,
     mappedModules,
     missing,
+    // VS-052: the handoff is driven by the REAL phase, not project.state, so the pack never
+    // contradicts the Current Phase block above it.
     handoff: {
-      recommendedAgents: recommendedAgentsForState(state),
-      nextSteps: nextStepsForState2(state),
-      instructions: LLM_INSTRUCTIONS,
+      recommendedAgents: phase.recommendedAgents.length > 0 ? phase.recommendedAgents : recommendedAgentsForState(state),
+      nextSteps: phase.nextStep ? [phase.nextStep] : nextStepsForState2(state),
+      instructions: phase.llmInstructions.length > 0 ? phase.llmInstructions : LLM_INSTRUCTIONS,
       operatingRules: OPERATING_RULES
     }
   };
@@ -5965,9 +6142,6 @@ function serializeContextPackJson(pack) {
 }
 
 // src/templates/context-pack-template.ts
-function stateLabel2(state) {
-  return state === "pre-ai" ? "pre-AI" : state;
-}
 function renderContextPack(pack) {
   const { project, scan: scan2, knowledge, missing, handoff } = pack;
   const parts = [];
@@ -6108,11 +6282,11 @@ function renderContextPack(pack) {
     parts.push("_None \u2014 all expected context is present._\n");
   }
   parts.push("## Recommended Agent Handoff\n");
-  parts.push(`Recommended agents for a ${stateLabel2(project.state)} project:
+  parts.push(`Recommended next for the **${pack.phase.phase}** phase:
 `);
   parts.push(handoff.recommendedAgents.map((a, i) => `${i + 1}. ${a}`).join("\n") + "\n");
   if (handoff.nextSteps.length > 0) {
-    parts.push("Next steps:\n");
+    parts.push("Next step:\n");
     parts.push(handoff.nextSteps.map((s) => `- ${s}`).join("\n") + "\n");
   }
   parts.push("## Instructions for the LLM\n");
@@ -6211,7 +6385,7 @@ function buildUnderstandPlan(dir, config) {
 }
 
 // src/templates/understand-template.ts
-function stateLabel3(state) {
+function stateLabel2(state) {
   return state === "pre-ai" ? "pre-AI" : state;
 }
 function agentName(file) {
@@ -6234,7 +6408,7 @@ function renderUnderstand(plan) {
     ].join("\n") + "\n"
   );
   parts.push("## Recommended Agent Flow\n");
-  parts.push(`Recommended order for a ${stateLabel3(project.state)} project:
+  parts.push(`Recommended order for a ${stateLabel2(project.state)} project:
 `);
   parts.push(
     steps.map((s, i) => {
@@ -6986,6 +7160,64 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
 // src/core/ownership-suggest.ts
 import matter5 from "gray-matter";
 var SCAN_PATH = ".kaddo/scan.json";
+function normalizeGlob(input) {
+  let g = input.trim().replace(/\\/g, "/");
+  if (!g) return g;
+  if (g.endsWith("/")) return `${g.slice(0, -1)}/**`;
+  if (!g.includes("*")) {
+    const base = g.split("/").pop() ?? "";
+    const looksLikeFile = /\.[A-Za-z0-9]+$/.test(base);
+    if (!looksLikeFile) return `${g}/**`;
+  }
+  return g;
+}
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const d = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
+  for (let j = 0; j <= n; j++) d[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+    }
+  }
+  return d[m][n];
+}
+function analyzeGlob(dir, input) {
+  const normalized = normalizeGlob(input);
+  const warnings = [];
+  let suggestion;
+  if (/^\*+$/.test(normalized) || /^[^/*]+\/\*\*$/.test(normalized)) {
+    warnings.push(
+      "This glob is broad and may reduce Guard usefulness. Prefer narrower ownership when possible."
+    );
+  }
+  const starIdx = normalized.indexOf("*");
+  const literal = (starIdx >= 0 ? normalized.slice(0, starIdx) : normalized).replace(/\/+$/, "");
+  if (literal && !exists(join(dir, literal))) {
+    const slash = literal.lastIndexOf("/");
+    const parent = slash >= 0 ? literal.slice(0, slash) : "";
+    const target = slash >= 0 ? literal.slice(slash + 1) : literal;
+    const parentFull = parent ? join(dir, parent) : dir;
+    let near;
+    try {
+      if (exists(parentFull)) {
+        near = readDir(parentFull).find(
+          (e) => e !== target && levenshtein(e.toLowerCase(), target.toLowerCase()) <= 2
+        );
+      }
+    } catch {
+    }
+    if (near) {
+      suggestion = `${parent ? parent + "/" : ""}${near}${normalized.slice(literal.length)}`;
+      warnings.push(`Path does not exist. Did you mean ${suggestion}?`);
+    } else {
+      warnings.push(`Path "${literal}" does not exist in the project.`);
+    }
+  }
+  return { normalized, warnings, suggestion };
+}
 function toStringArray3(value) {
   return Array.isArray(value) ? value.map((v) => String(v)).filter(Boolean) : [];
 }
@@ -7131,7 +7363,19 @@ async function chooseGlobs(suggested) {
       placeholder: "src/payments/**",
       validate: (v) => v.trim().length === 0 ? "A glob is required." : void 0
     });
-    chosen.push(glob.trim());
+    const analysis = analyzeGlob(cwd(), glob);
+    for (const w of analysis.warnings) log2.warn(w);
+    let value = analysis.normalized;
+    if (analysis.suggestion) {
+      const useSuggested = await confirm2({
+        message: `Use ${analysis.suggestion} instead?`,
+        initialValue: true
+      });
+      if (useSuggested) value = analysis.suggestion;
+    } else if (analysis.normalized !== glob.trim()) {
+      log2.info(`Normalized to ${analysis.normalized}`);
+    }
+    chosen.push(value);
     addMore = await confirm2({ message: "Add another glob?", initialValue: false });
   }
   return [...new Set(chosen)];

package/package.json

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