@kaddo/cli 3.13.2 → 3.15.0

package/dist/index.js

@@ -101,6 +101,7 @@ project:
   name: "${meta.name}"
   state: ${meta.state}
   structure: ${meta.structure}
+  language: ${meta.language}
   domains: []
 team:
   size: ${meta.teamSize}
@@ -210,11 +211,20 @@ async function runInit() {
     ],
     initialValue: "monorepo"
   });
+  const language = await select2({
+    message: "Project knowledge language (the CLI stays in English)",
+    options: [
+      { value: "en", label: "English" },
+      { value: "es", label: "Spanish" }
+    ],
+    initialValue: "en"
+  });
   const meta = {
     name: projectName.trim(),
     state,
     teamSize,
-    structure
+    structure,
+    language
   };
   const kaddoConfigPath = join(dir, KADDO_DIR, "config.yml");
   writeFile(kaddoConfigPath, buildConfig(meta));
@@ -510,11 +520,20 @@ import { parse as parseYaml2 } from "yaml";
 var PROJECT_STATES = ["new", "pre-ai", "legacy"];
 var TEAM_SIZES = ["indie", "small", "medium", "enterprise"];
 var REPOSITORY_STRUCTURES = ["monorepo", "multirepo"];
+var PROJECT_LANGUAGES = ["en", "es"];
 var DEFAULTS = {
   state: "pre-ai",
   structure: "monorepo",
-  teamSize: "indie"
+  teamSize: "indie",
+  language: "en"
 };
+function languageLabel(lang) {
+  return lang === "es" ? "Spanish" : "English";
+}
+function projectLanguage(config) {
+  const lang = config.project.language;
+  return lang === "es" ? "es" : "en";
+}
 var ConfigError = class extends Error {
   constructor(message) {
     super(message);
@@ -536,12 +555,18 @@ var structureSchema = z.enum(["monorepo", "multirepo"], {
     message: `project.structure must be one of: ${REPOSITORY_STRUCTURES.join(", ")}`
   })
 });
+var languageSchema = z.enum(["en", "es"], {
+  errorMap: () => ({
+    message: `project.language must be one of: ${PROJECT_LANGUAGES.join(", ")}`
+  })
+});
 var configSchema = z.object({
   version: z.union([z.string(), z.number()]).optional(),
   project: z.object({
     name: z.string().default("project"),
     state: projectStateSchema.default(DEFAULTS.state),
     structure: structureSchema.default(DEFAULTS.structure),
+    language: languageSchema.default(DEFAULTS.language),
     domains: z.array(z.string()).optional()
   }).passthrough().default({}),
   team: z.object({
@@ -599,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
@@ -1586,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"],
@@ -1654,11 +1692,24 @@ function renderAgentTrace(agent) {
     ""
   ].join("\n");
 }
+function renderLanguageRule() {
+  return [
+    "## Project Language",
+    "",
+    "The project knowledge language is defined in `.kaddo/config.yml` (`project.language`) and shown",
+    "in the context pack's Project Metadata (`Language:`). Write **all** generated knowledge",
+    "artifacts in that language (default: English).",
+    "",
+    "Do not translate: code, file names, CLI commands or configuration keys.",
+    ""
+  ].join("\n");
+}
 function withResponsibilityTrace(fileName, content) {
   const agent = fileName.replace(/\.md$/, "");
   if (!RESPONSIBILITY_MATRIX[agent]) return content;
   return `${content.trimEnd()}
 
+${renderLanguageRule()}
 ${renderAgentBoundaries(agent)}
 ${renderAgentTrace(agent)}`;
 }
@@ -1846,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
@@ -2171,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.
 `;
@@ -2875,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
@@ -2986,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) }));
 
@@ -3008,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"]
@@ -3041,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",
@@ -3050,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) {
@@ -4196,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";
@@ -4216,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;
@@ -4854,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);
@@ -4863,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);
@@ -4902,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);
   }
@@ -5031,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": {
@@ -5054,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;
     }
@@ -5076,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
@@ -5220,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);
@@ -5271,7 +5471,8 @@ function buildProjectExplanation(dir) {
     name: config?.project.name ?? "unknown",
     state: config?.project.state ?? "unknown",
     teamSize: config?.team.size ?? "unknown",
-    structure: config?.project.structure ?? "unknown"
+    structure: config?.project.structure ?? "unknown",
+    language: config ? languageLabel(projectLanguage(config)) : "English"
   };
   const scan2 = loadScan(dir);
   const stack = scan2 ? {
@@ -5337,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);
@@ -5386,6 +5590,7 @@ function buildProjectExplanation(dir) {
     workItems,
     ownership,
     domains,
+    duplicateWorkItems,
     layers,
     roadmap,
     mappedModules,
@@ -5417,6 +5622,7 @@ function renderExplanationHuman(exp) {
   lines.push(`- State: ${stateLabel(exp.project.state)}`);
   lines.push(`- Team: ${exp.project.teamSize}`);
   lines.push(`- Structure: ${exp.project.structure}`);
+  lines.push(`- Project language: ${exp.project.language}`);
   lines.push("");
   lines.push("## Knowledge Layers");
   lines.push(renderLayersMarkdown(exp.layers));
@@ -5518,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}`);
@@ -5886,7 +6101,8 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
       name: config.project.name,
       state,
       teamSize: config.team.size,
-      structure: config.project.structure
+      structure: config.project.structure,
+      language: languageLabel(projectLanguage(config))
     },
     scan: {
       available: scanJson !== null,
@@ -5911,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
     }
   };
@@ -5924,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 = [];
@@ -5942,7 +6157,8 @@ function renderContextPack(pack) {
       `- Name: ${project.name}`,
       `- State: ${project.state}`,
       `- Team size: ${project.teamSize}`,
-      `- Structure: ${project.structure}`
+      `- Structure: ${project.structure}`,
+      `- Language: ${project.language}`
     ].join("\n") + "\n"
   );
   parts.push("## Current Phase\n");
@@ -6066,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");
@@ -6169,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) {
@@ -6192,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) => {
@@ -6365,6 +6581,7 @@ function runUnderstand() {
     );
   }
   console.log(renderUnderstandTerminal(plan));
+  console.log(`Project language: ${pack.project.language} (knowledge artifacts are written in this language)`);
   const exp = buildProjectExplanation(dir);
   const assessment = assessPhase(exp);
   console.log("");
@@ -6943,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) : [];
 }
@@ -7088,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)];
@@ -9003,6 +9290,12 @@ var BOOTSTRAP_LAYERS = ["Business", "Product", "Tech"];
 function bootstrap(dir) {
   const written = [];
   const skipped = [];
+  let language = "en";
+  try {
+    const config = loadConfig(dir);
+    if (config) language = projectLanguage(config);
+  } catch {
+  }
   for (const target of TARGETS) {
     const full = join(dir, target.path);
     if (exists(full)) {
@@ -9010,13 +9303,22 @@ function bootstrap(dir) {
       continue;
     }
     const tpl = getTemplate(target.templateId);
-    const content = tpl ? tpl.content : "";
+    const base = tpl ? tpl.content : "";
+    const content = withLanguageDirective(base, language);
     writeFile(full, content.endsWith("\n") ? content : `${content}
 `);
     written.push(target.path);
   }
   return { written, skipped, layers: BOOTSTRAP_LAYERS };
 }
+function withLanguageDirective(content, language) {
+  if (language !== "es") return content;
+  const note = "> Idioma del proyecto: **espa\xF1ol**. Escribe este conocimiento en espa\xF1ol. Mant\xE9n en ingl\xE9s el c\xF3digo, los nombres de archivo, los comandos y las claves de configuraci\xF3n.\n";
+  const fm = content.match(/^---\n[\s\S]*?\n---\n/);
+  if (fm) return content.slice(0, fm[0].length) + "\n" + note + content.slice(fm[0].length);
+  return `${note}
+${content}`;
+}
 async function runBootstrap(dir = cwd()) {
   intro2("kaddo bootstrap");
   if (!exists(join(dir, CONFIG_PATH8))) {

package/package.json

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