@kaddo/cli 3.67.0 → 3.69.0

package/dist/index.js

@@ -1361,8 +1361,8 @@ function loadConfig(dir) {
   const parsed = configSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path8 = i.path.join(".");
-      return path8 ? `  - ${path8}: ${i.message}` : `  - ${i.message}`;
+      const path9 = i.path.join(".");
+      return path9 ? `  - ${path9}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -2455,8 +2455,23 @@ The context pack and the Work Item (draft or candidate).
 
 ## Output
 
-An improved Work Item with: problem, expected result, scope, out of scope, acceptance criteria,
-validation (how to test it), definition of done, open questions and dependencies.
+An improved Work Item with: actor and outcome, current behavior, target behavior, entry points,
+end-to-end flow, impact analysis, module coverage, scope unknowns, scope confidence, problem,
+expected result, scope, out of scope, acceptance criteria (including end-to-end criteria for
+user-facing changes), validation (how to test it), definition of done, open questions and
+dependencies.
+
+## Steps
+
+1. **Outcome framing** \u2014 identify actor, current behavior, target behavior, observable completion.
+2. **Journey reconstruction** \u2014 map entry point, interaction, service/API, state change, response,
+   final outcome.
+3. **Surface review** \u2014 evaluate: product/UI, frontend, backend, database, configuration, feature
+   flags, content/copy, authentication/authorization, notifications, analytics, documentation,
+   operations/release \u2014 as affected, reviewed-not-affected, unknown, or not-applicable.
+4. **Module review** \u2014 for multirepo, evaluate each mapped module with the same statuses.
+5. **Completeness review** \u2014 confirm: outcome covered, journey covered, modules assessed, unknowns
+   visible, acceptance criteria end-to-end, scope and out-of-scope coherent.
 
 ## Rules
 
@@ -2464,14 +2479,23 @@ validation (how to test it), definition of done, open questions and dependencies
 - Do not expand scope without explicit confirmation.
 - Do not create mega Work Items \u2014 split when it covers multiple outcomes.
 - Keep acceptance criteria testable.
+- Include at least one end-to-end acceptance criterion for user-facing changes.
+- Do not reduce a product intent to the first technical implementation found.
+- Evaluate surfaces and modules before proposing files.
 - This skill refines scope and acceptance criteria but does not approve implementation readiness.
   Readiness requires human confirmation through \`kaddo ready\` or the MCP \`mark_work_item_ready\` action.
 
 ## Quality checklist
 
+- Actor and outcome are identified.
+- Current and target behavior are documented.
+- Journey is reconstructed for user-facing changes.
+- Surfaces and modules are evaluated with explicit statuses.
 - Problem and expected result are unambiguous.
 - Scope and out-of-scope are explicit.
-- Acceptance criteria and validation are present and testable.
+- Acceptance criteria include end-to-end validation when applicable.
+- Scope unknowns are visible, not hidden.
+- Scope confidence is declared with reasons.
 - Open questions and dependencies are surfaced, not hidden.
 
 ## Example output
@@ -2692,14 +2716,19 @@ steps, and stop criteria (when to pause and ask).
 ## Rules
 
 - Do not start coding without confirmation.
-- Do not expand scope.
+- Do not expand scope without updating the Work Item.
 - Never make commits or push \u2014 suggest only.
+- Review scope coverage before planning: check that expected result, current/target behavior,
+  module coverage, and acceptance criteria are consistent. Flag contradictions (e.g., user-facing
+  change with unassessed frontend module).
 
 ## Quality checklist
 
+- Pre-implementation scope review is documented.
 - Scope and expected files are explicit.
 - Risks and validations are listed.
 - Stop criteria are defined.
+- Module coverage aligns with planned changes.
 
 ## Example output
 
@@ -3863,18 +3892,31 @@ A refined Work Item intended to be saved under the lifecycle workspace:
 
 ## Instructions
 
-1. Restate the problem in one clear sentence.
-2. Split the candidate if it is too large for a single Work Item.
-3. Preserve the candidate's type (\`feature\`, \`bugfix\`, \`hotfix\`, \`spike\`, \`chore\`).
-   Keep \`chore\` for maintenance/tooling/config/infra work \u2014 never upgrade a chore to a feature.
-4. Validate the Knowledge Level (K0\u2013K4) and propose a different one if needed.
-5. Propose acceptance criteria.
-6. Propose an Out of scope section.
-7. Propose **how to test it** \u2014 concrete validation steps (commands to run, manual steps, or
-   test cases) that prove the change works once implemented. This is mandatory.
-8. Propose a Definition of Done.
-9. Identify open questions and assumptions.
-10. Suggest ownership candidates (code globs) if evident.
+1. **Interpret the outcome** \u2014 what must change for the actor or consumer of this change.
+2. **Identify the actor** \u2014 who experiences or triggers the change.
+3. **Describe current behavior** \u2014 what happens today.
+4. **Describe target behavior** \u2014 what should happen after the change.
+5. **Reconstruct the journey** \u2014 for user-facing changes, map the end-to-end flow from entry
+   point to final observable result before proposing files.
+6. **Evaluate surfaces** \u2014 assess each potentially affected surface (frontend, backend, database,
+   configuration, content, feature flags, authentication, notifications, analytics, documentation,
+   operations) as \`affected\`, \`reviewed-not-affected\`, \`unknown\`, or \`not-applicable\`.
+7. **Evaluate modules** \u2014 for multirepo projects, assess each plausibly related mapped module with
+   the same statuses. A module must be \`affected\`, \`reviewed-not-affected\`, \`unknown\`, or
+   \`not-applicable\`. Do not leave related modules unmentioned.
+8. Restate the problem in one clear sentence.
+9. Split the candidate if it is too large for a single Work Item.
+10. Preserve the candidate's type (\`feature\`, \`bugfix\`, \`hotfix\`, \`spike\`, \`chore\`).
+    Keep \`chore\` for maintenance/tooling/config/infra work \u2014 never upgrade a chore to a feature.
+11. Validate the Knowledge Level (K0\u2013K4) and propose a different one if needed.
+12. Propose acceptance criteria \u2014 include at least one end-to-end criterion for user-facing changes.
+13. Propose an Out of scope section.
+14. Propose **how to test it** \u2014 concrete validation steps (commands to run, manual steps, or
+    test cases) that prove the change works once implemented. This is mandatory.
+15. Propose a Definition of Done.
+16. Identify open questions, assumptions, and scope unknowns.
+17. Determine scope confidence (high, medium, low) with reasons.
+18. Suggest ownership candidates (code globs) if evident.
 
 ## Constraints
 
@@ -3882,19 +3924,49 @@ A refined Work Item intended to be saved under the lifecycle workspace:
 - Do not invent business facts.
 - Do not assign a Knowledge Level higher than the change requires.
 - Mark assumptions explicitly.
+- Do not reduce a product intent to the first technical implementation found.
+- Inspect the observable outcome before proposing files.
+- For user-facing changes, assess the entry point, interaction surface, backend behavior, and
+  final user-visible result.
+- For multirepo projects, assess each plausibly related mapped module.
+- Do not mark the Work Item ready while material scope remains unknown.
+- Ask focused questions instead of silently narrowing the request.
+- Preserve unsupported assumptions as assumptions.
 
 ## Output Format
 
 \`\`\`markdown
 # <Work Item title>
 
+**Actor and outcome:**
+
+**Current behavior:**
+
+**Target behavior:**
+
+**Entry points:**
+
+**End-to-end flow:**
+
 **Problem:**
 
 **Expected result:**
 
 **Suggested Knowledge Level:** K1 / K2 / K3 / K4
 
+**Impact analysis:**
+<!-- surfaces: affected / reviewed-not-affected / unknown / not-applicable -->
+
+**Module coverage:**
+<!-- for multirepo: each module as affected / reviewed-not-affected / unknown / not-applicable -->
+
+**Scope unknowns:**
+
+**Scope confidence:** high / medium / low
+<!-- reasons: -->
+
 **Acceptance criteria:**
+<!-- include at least one end-to-end criterion for user-facing changes -->
 
 **Out of scope:**
 
@@ -4631,6 +4703,20 @@ Working code, tests and migrations, plus updated knowledge (ADR / capabilities /
 when the change affects them. You also produce a suggested branch name and a suggested
 Conventional Commit message \u2014 as suggestions, never executed.
 
+## Pre-implementation Scope Review (VS-095)
+
+Before implementing, review the Work Item's scope coverage:
+- Check that expected result, current behavior, and target behavior are documented.
+- Verify the journey covers the full user-facing flow when applicable.
+- Confirm affected surfaces and modules are declared.
+- Check module_coverage: if a mapped module is plausibly related but not assessed, flag it.
+- Verify acceptance criteria include end-to-end validation for user-facing changes.
+- Check for unresolved scope unknowns that could change the implementation.
+
+If you find a contradiction (e.g., target behavior describes a user-facing registration flow but
+the mapped frontend module was not assessed), explain the finding, propose updating the Work Item,
+and wait for confirmation before proceeding. Do not silently expand scope.
+
 ## Instructions
 
 1. **Suggest a branch first** (do not run it). Follow the Git strategy
@@ -6380,6 +6466,53 @@ async function getUntrackedFiles() {
 
 // src/services/artifact-reader.ts
 import matter from "gray-matter";
+var VALID_SCOPE_CONFIDENCE_LEVELS = /* @__PURE__ */ new Set(["high", "medium", "low"]);
+var VALID_COVERAGE_STATUSES = /* @__PURE__ */ new Set(["affected", "reviewed-not-affected", "unknown", "not-applicable"]);
+function parseScopeConfidence(data) {
+  const sc = data.scope_confidence;
+  if (!sc || typeof sc !== "object" || Array.isArray(sc)) return null;
+  const obj = sc;
+  const level = String(obj.level ?? "");
+  if (!VALID_SCOPE_CONFIDENCE_LEVELS.has(level)) return null;
+  const reasons = Array.isArray(obj.reasons) ? obj.reasons.map(String).filter(Boolean) : [];
+  return { level, reasons };
+}
+function parseModuleCoverage(data) {
+  const mc = data.module_coverage;
+  if (!mc || typeof mc !== "object" || Array.isArray(mc)) return null;
+  const result = {};
+  for (const [id, val] of Object.entries(mc)) {
+    if (!val || typeof val !== "object" || Array.isArray(val)) continue;
+    const v = val;
+    const status = String(v.status ?? "");
+    if (!VALID_COVERAGE_STATUSES.has(status)) continue;
+    result[id] = {
+      status,
+      ...v.reason ? { reason: String(v.reason) } : {},
+      ...Array.isArray(v.evidence) ? { evidence: v.evidence.map(String).filter(Boolean) } : {}
+    };
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
+function parseImpactAnalysis(data) {
+  const ia = data.impact_analysis;
+  if (!ia || typeof ia !== "object" || Array.isArray(ia)) return null;
+  const surfaces = ia.surfaces;
+  if (!surfaces || typeof surfaces !== "object" || Array.isArray(surfaces)) return null;
+  const result = {};
+  for (const [id, val] of Object.entries(surfaces)) {
+    if (!val || typeof val !== "object" || Array.isArray(val)) continue;
+    const v = val;
+    const status = String(v.status ?? "");
+    if (!VALID_COVERAGE_STATUSES.has(status)) continue;
+    result[id] = {
+      status,
+      ...v.reason ? { reason: String(v.reason) } : {},
+      ...v.question ? { question: String(v.question) } : {}
+    };
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
 function parseArtifact(filePath, raw) {
   try {
     const { data } = matter(raw);
@@ -6408,7 +6541,10 @@ function parseArtifact(filePath, raw) {
       affectedModules: Array.isArray(data.affected_modules) ? data.affected_modules.map(String).filter(Boolean) : [],
       refinedBy: String(data.refined_by ?? ""),
       implementedBy: String(data.implemented_by ?? ""),
-      closedBy: String(data.closed_by ?? "")
+      closedBy: String(data.closed_by ?? ""),
+      scopeConfidence: parseScopeConfidence(data),
+      moduleCoverage: parseModuleCoverage(data),
+      impactAnalysis: parseImpactAnalysis(data)
     };
   } catch {
     return null;
@@ -6596,10 +6732,10 @@ function analyzeGuard(touchedFiles, artifacts, silentWithoutOwnership) {
 import { parse as parseYaml4, stringify as stringifyYaml2 } from "yaml";
 var IGNORE_FILE = ".kaddo/ignores.yml";
 function loadIgnores(dir) {
-  const path8 = join(dir, IGNORE_FILE);
-  if (!exists(path8)) return [];
+  const path9 = join(dir, IGNORE_FILE);
+  if (!exists(path9)) return [];
   try {
-    const raw = readFile(path8);
+    const raw = readFile(path9);
     const parsed = parseYaml4(raw);
     return Array.isArray(parsed) ? parsed : [];
   } catch {
@@ -6607,7 +6743,7 @@ function loadIgnores(dir) {
   }
 }
 function saveIgnore(dir, entry) {
-  const path8 = join(dir, IGNORE_FILE);
+  const path9 = join(dir, IGNORE_FILE);
   const existing = loadIgnores(dir);
   const idx = existing.findIndex((e) => e.artifact_id === entry.artifact_id);
   if (idx >= 0) {
@@ -6615,17 +6751,17 @@ function saveIgnore(dir, entry) {
   } else {
     existing.push(entry);
   }
-  writeFile(path8, stringifyYaml2(existing));
+  writeFile(path9, stringifyYaml2(existing));
 }
 function isIgnored(ignores, artifactId) {
   return ignores.find((e) => e.artifact_id === artifactId);
 }
 function removeIgnore(dir, artifactId) {
-  const path8 = join(dir, IGNORE_FILE);
+  const path9 = join(dir, IGNORE_FILE);
   const existing = loadIgnores(dir);
   const filtered = existing.filter((e) => e.artifact_id !== artifactId);
   if (filtered.length === existing.length) return false;
-  writeFile(path8, stringifyYaml2(filtered));
+  writeFile(path9, stringifyYaml2(filtered));
   return true;
 }
 
@@ -6647,11 +6783,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path8 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path8)) return [];
+  const path9 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path9)) return [];
   let parsed;
   try {
-    parsed = parseYaml5(readFile(path8));
+    parsed = parseYaml5(readFile(path9));
   } catch {
     return [];
   }
@@ -6969,6 +7105,142 @@ function analyzeCrossRepoEvidence(input) {
   };
 }
 
+// src/core/scope-coverage.ts
+var VALID_CONFIDENCE_LEVELS = /* @__PURE__ */ new Set(["high", "medium", "low"]);
+var VALID_COVERAGE_STATUSES2 = /* @__PURE__ */ new Set(["affected", "reviewed-not-affected", "unknown", "not-applicable"]);
+var USER_FACING_KEYWORDS_EN = [
+  "user",
+  "visitor",
+  "page",
+  "registration",
+  "login",
+  "form",
+  "show",
+  "display",
+  "cta",
+  "flow",
+  "screen",
+  "dashboard",
+  "ui",
+  "frontend",
+  "interface",
+  "button",
+  "menu",
+  "navigation",
+  "modal",
+  "dialog",
+  "notification",
+  "toast",
+  "message"
+];
+var USER_FACING_KEYWORDS_ES = [
+  "usuario",
+  "visitante",
+  "p\xE1gina",
+  "registro",
+  "login",
+  "formulario",
+  "mostrar",
+  "cta",
+  "flujo",
+  "pantalla",
+  "interfaz",
+  "bot\xF3n",
+  "men\xFA",
+  "navegaci\xF3n",
+  "modal",
+  "di\xE1logo",
+  "notificaci\xF3n",
+  "mensaje"
+];
+var USER_FACING_KEYWORDS = /* @__PURE__ */ new Set([...USER_FACING_KEYWORDS_EN, ...USER_FACING_KEYWORDS_ES]);
+function analyzeScopeCoverage(artifact, registeredModuleIds, frontendModuleIds) {
+  const findings = [];
+  const id = artifact.id || artifact.title;
+  const mc = artifact.moduleCoverage;
+  const ia = artifact.impactAnalysis;
+  const sc = artifact.scopeConfidence;
+  const affectedModules = artifact.affectedModules;
+  const lifecycle = artifact.status;
+  const isCompleted = lifecycle === "completed" || lifecycle === "archived";
+  const isReady = lifecycle === "ready";
+  const hasScopeCoverage = mc !== null || ia !== null || sc !== null;
+  const unknownModules = [];
+  if (sc) {
+    if (!VALID_CONFIDENCE_LEVELS.has(sc.level)) {
+      findings.push({ id, severity: "blocking", message: `Invalid scope_confidence level "${sc.level}". Must be high, medium, or low.` });
+    }
+    if (isReady && sc.level === "low") {
+      findings.push({ id, severity: "warning", message: "Work Item is ready but scope confidence is low." });
+    }
+  }
+  if (mc) {
+    for (const modId of Object.keys(mc)) {
+      if (modId === "core") continue;
+      if (!registeredModuleIds.includes(modId)) {
+        findings.push({ id, severity: "blocking", message: `Module "${modId}" in module_coverage is not registered in .kaddo/modules.yml.` });
+      }
+    }
+    for (const [modId, entry] of Object.entries(mc)) {
+      if (!VALID_COVERAGE_STATUSES2.has(entry.status)) {
+        findings.push({ id, severity: "blocking", message: `Invalid module_coverage status "${entry.status}" for module "${modId}".` });
+      }
+      if (entry.status === "affected" && !entry.reason) {
+        findings.push({ id, severity: "warning", message: `Module "${modId}" is affected but has no reason.` });
+      }
+      if (entry.status === "unknown") {
+        unknownModules.push(modId);
+      }
+    }
+    for (const [modId, entry] of Object.entries(mc)) {
+      if (entry.status === "affected" && !affectedModules.includes(modId)) {
+        findings.push({ id, severity: "blocking", message: `Module "${modId}" is marked affected in module_coverage but missing from affected_modules.` });
+      }
+    }
+    for (const modId of affectedModules) {
+      const entry = mc[modId];
+      if (entry && entry.status !== "affected") {
+        findings.push({ id, severity: "blocking", message: `Module "${modId}" is in affected_modules but module_coverage status is "${entry.status}", not "affected".` });
+      }
+    }
+    if (isReady && unknownModules.length > 0) {
+      for (const modId of unknownModules) {
+        findings.push({ id, severity: "warning", message: `Work Item is ready but module "${modId}" scope remains unknown.` });
+      }
+    }
+  }
+  if (ia) {
+    for (const [surface, entry] of Object.entries(ia)) {
+      if (!VALID_COVERAGE_STATUSES2.has(entry.status)) {
+        findings.push({ id, severity: "blocking", message: `Invalid impact_analysis status "${entry.status}" for surface "${surface}".` });
+      }
+      if (entry.status === "unknown" && !entry.question && !entry.reason) {
+        findings.push({ id, severity: "warning", message: `Surface "${surface}" is unknown but has no question or explanation.` });
+      }
+    }
+  }
+  if (!isCompleted && frontendModuleIds.length > 0) {
+    const wiText = `${artifact.title} ${artifact.rawFrontmatter?.target_behavior ?? ""} ${artifact.rawFrontmatter?.current_behavior ?? ""}`.toLowerCase();
+    const isUserFacing = [...USER_FACING_KEYWORDS].some((kw) => wiText.includes(kw));
+    if (isUserFacing && mc) {
+      for (const fid of frontendModuleIds) {
+        if (!mc[fid]) {
+          findings.push({ id, severity: "warning", message: `A mapped user-facing module "${fid}" was not assessed in module_coverage.` });
+        }
+      }
+    }
+  }
+  return {
+    id,
+    scopeConfidence: sc,
+    moduleCoverage: mc,
+    impactAnalysis: ia,
+    findings,
+    unknownModules,
+    hasScopeCoverage
+  };
+}
+
 // src/commands/guard.ts
 import path4 from "path";
 import { parse as parseYaml7 } from "yaml";
@@ -7259,7 +7531,7 @@ function buildGuardHistory(dir) {
     const d = hotspotDir(t.code_path);
     hotspotMap.set(d, (hotspotMap.get(d) ?? 0) + 1);
   }
-  const hotspots = [...hotspotMap.entries()].map(([path8, warnings]) => ({ path: path8, warnings })).sort((a, b) => b.warnings - a.warnings);
+  const hotspots = [...hotspotMap.entries()].map(([path9, warnings]) => ({ path: path9, warnings })).sort((a, b) => b.warnings - a.warnings);
   return {
     available: true,
     total_runs: sorted.length,
@@ -7630,6 +7902,27 @@ async function runGuard(opts = {}) {
       console.log("");
     }
   }
+  const mappedModules = loadMappedModules(dir);
+  const registeredModuleIdsForScope = mappedModules.map((m) => m.id);
+  const frontendModuleIds = mappedModules.filter((m) => m.type === "frontend" || m.type === "web" || m.type === "mobile" || m.type === "ui").map((m) => m.id);
+  const wiArtifactsForScope = artifacts.filter((a) => a.isWorkItem);
+  const scopeSummaries = [];
+  for (const wi of wiArtifactsForScope) {
+    if (!wi.scopeConfidence && !wi.moduleCoverage && !wi.impactAnalysis) continue;
+    const summary = analyzeScopeCoverage(wi, registeredModuleIdsForScope, frontendModuleIds);
+    if (summary.findings.length > 0) scopeSummaries.push(summary);
+  }
+  if (scopeSummaries.length > 0) {
+    console.log("Scope coverage:");
+    for (const s of scopeSummaries) {
+      console.log(`  ${s.id}:`);
+      for (const f of s.findings) {
+        const icon = f.severity === "blocking" ? "\u2717" : f.severity === "warning" ? "!" : "\xB7";
+        console.log(`    ${icon} ${f.message}`);
+      }
+    }
+    console.log("");
+  }
   const ownerMap = loadOwners(dir);
   const matchedDomains = collectMatchedDomains(activeMatches.map((m) => m.artifact.domains));
   const affectedOwners = resolveAffectedOwners(matchedDomains, ownerMap);
@@ -7907,12 +8200,44 @@ domains: []
 capabilities: []
 code: []
 created_at: YYYY-MM-DD
+# scope_confidence:
+#   level: medium
+#   reasons: []
+# module_coverage:
+#   core:
+#     status: affected
+#     reason: ""
+# impact_analysis:
+#   surfaces:
+#     frontend:
+#       status: affected
+#       reason: ""
 ---
 
 # <Title>
 
 > Type: feature \xB7 Level: K2
 
+## Actor and outcome
+
+_Who experiences the change and what is the observable result?_
+
+## Current behavior
+
+_What happens today?_
+
+## Target behavior
+
+_What should happen after this change?_
+
+## Entry points
+
+_Where does the flow start for the actor?_
+
+## End-to-end flow
+
+_Describe the complete flow from entry point to final result._
+
 ## Problem
 
 _What problem or opportunity does this address?_
@@ -7921,9 +8246,26 @@ _What problem or opportunity does this address?_
 
 _What should be true once this is done?_
 
+## Impact analysis
+
+_Which surfaces are affected, reviewed-not-affected, unknown, or not-applicable?_
+
+## Module coverage
+
+_For multirepo: which modules were evaluated and their status._
+
+## Scope unknowns
+
+_What remains unknown? Include focused questions._
+
+## Scope confidence
+
+_high / medium / low \u2014 with reasons._
+
 ## Acceptance criteria
 
 - [ ] ...
+- [ ] _Include at least one end-to-end criterion for user-facing changes._
 
 ## Design
 
@@ -7955,6 +8297,9 @@ ${QUALITY}
 - [ ] Title is specific and action-oriented.
 - [ ] \`code:\` globs declared so Guard can relate changes.
 - [ ] Knowledge level matches the real uncertainty.
+- [ ] Actor and outcome are identified.
+- [ ] Current and target behavior are documented.
+- [ ] Scope confidence is declared.
 `;
 var ROADMAP = `---
 type: roadmap
@@ -9757,10 +10102,10 @@ function slugify2(name) {
   return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function readModulesDescriptor(dir) {
-  const path8 = join(dir, DESCRIPTOR_PATH2);
-  if (!exists(path8)) return { version: 1, modules: [] };
+  const path9 = join(dir, DESCRIPTOR_PATH2);
+  if (!exists(path9)) return { version: 1, modules: [] };
   try {
-    const parsed = parseYaml9(readFile(path8));
+    const parsed = parseYaml9(readFile(path9));
     return { version: parsed.version ?? 1, modules: parsed.modules ?? [] };
   } catch {
     return { version: 1, modules: [] };
@@ -10140,7 +10485,7 @@ function sectionParagraph(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path8, md) {
+function parseCapsule(id, path9, md) {
   const { data } = matter3(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -10150,7 +10495,7 @@ function parseCapsule(id, path8, md) {
   }
   return {
     id,
-    path: path8,
+    path: path9,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -10236,9 +10581,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer2 of layerDocs) {
-    const path8 = layer2.files.map((f) => `${KNOWLEDGE3}/${f}`).find((rel) => exists(join(dir, rel)));
-    if (path8) {
-      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path8 });
+    const path9 = layer2.files.map((f) => `${KNOWLEDGE3}/${f}`).find((rel) => exists(join(dir, rel)));
+    if (path9) {
+      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path9 });
       presentLayers.push(layer2.id);
     }
   }
@@ -11774,10 +12119,10 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   const q = (rel) => analyzeKnowledgeArtifact(dir, rel);
   const resolveAgent = (agent) => {
     const file = agent.endsWith(".md") ? agent : `${agent}.md`;
-    const path8 = agentInstallPath(file);
-    const installed = isFile(join(dir, path8));
+    const path9 = agentInstallPath(file);
+    const installed = isFile(join(dir, path9));
     const group = agentGroupOf(file);
-    return { agentPath: path8, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+    return { agentPath: path9, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
   };
   const moduleRepo = isModule(config);
   const coreRepo = isCore(config);
@@ -13250,6 +13595,16 @@ function buildProjectExplanation(dir) {
         releaseReady: completed.filter((a) => a.releaseStatus === "ready" || a.releaseStatus === "released").length
       };
     })(),
+    scopeCoverage: workItemArtifacts.filter((a) => a.scopeConfidence || a.moduleCoverage || a.impactAnalysis).map((a) => {
+      const unknownModules = a.moduleCoverage ? Object.entries(a.moduleCoverage).filter(([, v]) => v.status === "unknown").map(([k]) => k) : [];
+      return {
+        id: a.id || a.title,
+        scopeConfidence: a.scopeConfidence,
+        moduleCoverage: a.moduleCoverage,
+        unknownModules,
+        hasScopeCoverage: true
+      };
+    }),
     implementationEvidence: workItemArtifacts.filter((a) => a.affectedModules.length > 0).map((a) => {
       const fm2 = a.rawFrontmatter;
       const evidence = fm2.implementation_evidence;
@@ -13430,6 +13785,23 @@ function renderExplanationHuman(exp) {
     }
     lines.push("");
   }
+  if (exp.scopeCoverage.length > 0) {
+    lines.push("## Work Item Scope Coverage");
+    for (const sc of exp.scopeCoverage) {
+      lines.push("");
+      lines.push(`### ${sc.id}`);
+      if (sc.scopeConfidence) lines.push(`- Scope confidence: ${sc.scopeConfidence.level}`);
+      if (sc.moduleCoverage) {
+        const affected = Object.entries(sc.moduleCoverage).filter(([, v]) => v.status === "affected").map(([k]) => k);
+        const reviewed = Object.entries(sc.moduleCoverage).filter(([, v]) => v.status === "reviewed-not-affected").map(([k]) => k);
+        const unknown = Object.entries(sc.moduleCoverage).filter(([, v]) => v.status === "unknown").map(([k]) => k);
+        if (affected.length > 0) lines.push(`Affected: ${affected.join(", ")}`);
+        if (reviewed.length > 0) lines.push(`Reviewed, not affected: ${reviewed.join(", ")}`);
+        if (unknown.length > 0) lines.push(`Unknown: ${unknown.join(", ")}`);
+      }
+    }
+    lines.push("");
+  }
   if (exp.domains.length > 0) {
     lines.push("## Domains");
     lines.push(`- ${exp.domains.join(", ")}`);
@@ -13918,6 +14290,13 @@ function toContextWorkItem(a) {
   wi.validationStatus = a.validationStatus || (isHistorical ? "not-assessed" : void 0);
   wi.releaseStatus = a.releaseStatus || (isHistorical ? "not-assessed" : void 0);
   if (a.affectedModules.length > 0) wi.affectedModules = a.affectedModules;
+  if (a.scopeConfidence) wi.scopeConfidence = a.scopeConfidence;
+  if (a.moduleCoverage) wi.moduleCoverage = a.moduleCoverage;
+  if (a.impactAnalysis) wi.impactAnalysis = a.impactAnalysis;
+  if (a.moduleCoverage) {
+    const unknowns = Object.entries(a.moduleCoverage).filter(([, v]) => v.status === "unknown").map(([k]) => k);
+    if (unknowns.length > 0) wi.scopeUnknowns = unknowns;
+  }
   return wi;
 }
 function toContextArtifact(a) {
@@ -15054,6 +15433,24 @@ function runUnderstand() {
       if (ds2.releaseReady > 0) console.log(`  - Release ready: ${ds2.releaseReady}`);
       console.log(`  - Current active work: ${ds2.activeWorkItems > 0 ? ds2.activeWorkItems : "none"}`);
     }
+    if (exp.scopeCoverage.length > 0) {
+      const withUnknowns = exp.scopeCoverage.filter((sc) => sc.unknownModules.length > 0);
+      if (withUnknowns.length > 0) {
+        console.log("");
+        console.log("Scope unknowns:");
+        for (const sc of withUnknowns) {
+          console.log(`  ${sc.id}: ${sc.unknownModules.join(", ")}`);
+        }
+      }
+      const lowConfidence = exp.scopeCoverage.filter((sc) => sc.scopeConfidence?.level === "low");
+      if (lowConfidence.length > 0) {
+        console.log("");
+        console.log("Low scope confidence:");
+        for (const sc of lowConfidence) {
+          console.log(`  ${sc.id}`);
+        }
+      }
+    }
     if (rec.skill) console.log(`Recommended skill: ${rec.skill}`);
     console.log(`Next step: ${rec.label}`);
     if (rec.reason) console.log(`Why: ${rec.reason}`);
@@ -18095,6 +18492,110 @@ async function runReady(id, opts = {}) {
   outro2(`Work Item ${wi.id} is ready.`);
 }
 
+// src/commands/admin.ts
+import path8 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import net from "net";
+function isPortAvailable(port, host) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.once("listening", () => {
+      server.close();
+      resolve(true);
+    });
+    server.listen(port, host);
+  });
+}
+function resolveStaticDir() {
+  const __dirname = path8.dirname(fileURLToPath2(import.meta.url));
+  const candidates = [
+    path8.resolve(__dirname, "..", "..", "admin", "dist"),
+    path8.resolve(__dirname, "..", "node_modules", "@kaddo", "admin", "dist")
+  ];
+  for (const c of candidates) {
+    if (exists(join(c, "index.html"))) return c;
+  }
+  return null;
+}
+async function runAdmin(opts = {}) {
+  const dir = cwd();
+  const port = opts.port ?? 4173;
+  const host = opts.host ?? "127.0.0.1";
+  const config = loadConfig(dir);
+  if (!config) {
+    console.log("");
+    console.log("Kaddo Admin could not start.");
+    console.log("");
+    console.log("No Kaddo project was detected in the current directory.");
+    console.log("");
+    console.log("Run:");
+    console.log("  kaddo init");
+    console.log("");
+    console.log("or execute this command from a Kaddo project.");
+    console.log("");
+    process.exit(1);
+  }
+  const available = await isPortAvailable(port, host);
+  if (!available) {
+    console.log("");
+    console.log(`Port ${port} is already in use.`);
+    console.log("");
+    console.log("Use:");
+    console.log(`  kaddo admin --port <port>`);
+    console.log("");
+    process.exit(1);
+  }
+  const staticDir = resolveStaticDir();
+  if (!staticDir) {
+    console.error("Admin frontend not built. Run `pnpm -r build` first.");
+    process.exit(1);
+  }
+  const { createAdminServer, SQLiteAdminStorage } = await import("@kaddo/admin-server");
+  const dbDir = join(dir, ".kaddo", "admin");
+  ensureDir(dbDir);
+  const dbPath = join(dbDir, "admin.db");
+  const storage = new SQLiteAdminStorage(dbPath);
+  await storage.initialize();
+  const server = await createAdminServer({
+    projectDir: dir,
+    storage,
+    staticDir,
+    host,
+    port
+  });
+  const address = await server.start();
+  console.log("");
+  console.log("Kaddo Admin");
+  console.log("");
+  console.log(`Project: ${config.project.name}`);
+  console.log(`Mode: local`);
+  console.log(`Address: ${address}`);
+  console.log("");
+  console.log(`Session: active`);
+  console.log(`Storage: SQLite`);
+  console.log(`Project source: Kaddo Core`);
+  console.log("");
+  console.log("Press Ctrl+C to stop.");
+  console.log("");
+  if (!opts.noOpen) {
+    try {
+      const { default: open } = await import("open");
+      await open(address);
+    } catch {
+    }
+  }
+  const shutdown = async () => {
+    console.log("");
+    console.log("Shutting down...");
+    await server.stop();
+    console.log("Kaddo Admin stopped.");
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -18119,8 +18620,8 @@ var capsuleCmd = program.command("capsule").description("Export this project as
 capsuleCmd.command("export").description("Write a Knowledge Capsule about this project to .kaddo/exports/").option("--scope <scope>", 'Export scope: "system" includes all mapped modules').option("--module <id>", "Export a capsule for a specific mapped module").action((opts) => {
   runCapsuleExport(opts);
 });
-capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path8) => {
-  runCapsuleAdd(path8);
+capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path9) => {
+  runCapsuleAdd(path9);
 });
 var graphCmd = program.command("graph").description("Export the lightweight, file-based knowledge graph of the project");
 graphCmd.command("export").description("Write the knowledge graph to .kaddo/graph.json and .kaddo/graph.mmd").option("--scope <scope>", "Graph scope: active (default) or all").option("--format <format>", "Output format: json, mermaid (default: both)").action((opts) => {
@@ -18238,6 +18739,9 @@ modulesCmd.command("validate").description("Validate registered modules against
 program.command("add [module]").description("Install an optional Kaddo module (adr, incident, rfc, migration, legacy, agents, skills, standards, security, stack, git-strategy)").option("--all", "For `add agents` / `add skills`: install every item (not just the recommended set)").option("--group <name>", "For `add agents`: business|product|tech|delivery|utilities. For `add skills`: delivery|tech|integration").action((moduleName, opts) => {
   runAdd(moduleName ?? "", { all: opts.all, group: opts.group });
 });
+program.command("admin").description("Start Kaddo Admin \u2014 a local web interface for the project knowledge").option("--port <port>", "Server port (default: 4173)", parseInt).option("--host <host>", "Server host (default: 127.0.0.1)").option("--no-open", "Do not open the browser automatically").action(async (opts) => {
+  await runAdmin({ port: opts.port, host: opts.host, noOpen: opts.open === false });
+});
 program.parseAsync(process.argv).catch((err) => {
   console.error(err);
   process.exit(1);