@kaddo/mcp 3.92.0 → 3.95.0

package/dist/index.js

@@ -4904,7 +4904,8 @@ var IMPLEMENTATION_PLANNING = skill(
 
 ## Purpose
 
-Standardize the plan produced before implementation starts.
+Standardize the plan produced before implementation starts and ensure design deliberation is
+explicit before coding begins.
 
 ## When to use
 
@@ -4912,33 +4913,96 @@ Before writing code for a ready Work Item.
 
 ## Inputs
 
-The context pack and the ready Work Item.
+Assemble context proportionally from the Build Contract's five sources:
+
+1. **Work Item:** outcome, acceptance criteria, constraints, out-of-scope, affected_modules, domains.
+2. **Knowledge:** business, product, tech and delivery knowledge relevant to the Work Item's domains.
+3. **System Context:** topology, module dependencies, system graph when available.
+4. **Repository Context:** existing patterns, file structure, test conventions in affected modules.
+5. **Related Work Items:** dependencies (depends_on), completed related Work Items for precedent.
+
+## Context assembly
+
+Assemble proportionally to scope. A single-module bugfix needs the affected module's codebase
+and tests. A cross-cutting feature needs topology, multiple modules, and business context.
+Do not load everything \u2014 load what the scope demands.
 
 ## Output
 
-A plan with: technical scope, expected files, risks, validations, out of scope, implementation
-steps, and stop criteria (when to pause and ask).
+A plan covering the template below, ending with a confirmation gate.
+
+### Output template
+
+\`\`\`markdown
+# Implementation Plan \u2014 <WI id>
+
+## Context Summary
+<!-- Relevant knowledge, system context, and repository observations assembled for this WI. -->
+
+## Design Deliberation
+
+### Technical Approach
+<!-- How this will be implemented. Be specific about patterns, modules, layers involved. -->
+
+### Rationale
+<!-- Why this approach. Reference existing patterns, constraints, or WI requirements. -->
+
+### Alternatives Considered
+<!-- When the change is non-trivial. May be omitted for trivial/obvious changes with a note. -->
+
+### Trade-offs
+<!-- When alternatives exist. Explicitly state what is gained and lost. -->
+
+### ADR Recommendation
+<!-- When the decision is architecturally significant: recommend materializing as ADR
+     via adr-writing skill. Remove this section if not applicable. -->
+
+## Affected Areas
+<!-- Modules, files, surfaces impacted by this change. -->
+
+## Implementation Steps
+<!-- Numbered steps with expected files per step. -->
+
+## Validation Plan
+<!-- How to verify: test commands, manual steps, AC verification. -->
+
+## Stop Criteria
+<!-- When to pause and ask: scope expansion, contradictions, missing knowledge,
+     architectural uncertainty. -->
+
+## Confirmation Gate
+Do not start coding without explicit human confirmation of this plan.
+\`\`\`
 
 ## Rules
 
+- Document Technical Approach and Rationale before listing implementation steps.
 - Do not start coding without confirmation.
 - 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).
+- When you discover an architecturally significant decision during planning, recommend the
+  adr-writing skill and pause.
+- When alternatives exist, document them. For trivial or obvious changes, Alternatives and
+  Trade-offs may be omitted with a note explaining why.
+- Context assembly is proportional: do not load all project knowledge for a small fix.
 
 ## Quality checklist
 
 - Pre-implementation scope review is documented.
+- Technical Approach is documented with specific patterns and modules.
+- Rationale references WI requirements or existing project patterns.
+- Alternatives documented when non-trivial, or explicitly noted as not applicable.
+- ADR recommendation present when the decision is architecturally significant.
+- Context sources consulted are listed in Context Summary.
 - Scope and expected files are explicit.
 - Risks and validations are listed.
+- Validation plan includes how to verify each AC.
 - Stop criteria are defined.
 - Module coverage aligns with planned changes.
-
-## Example output
-
-A numbered plan covering the sections above, ending with a request to confirm before coding.
+- Confirmation gate is present.
 `
 );
 var MODULE_CONTEXT_REFINEMENT = skill(
@@ -4993,6 +5057,56 @@ A refined \`module-context.md\` with real, project-specific content in all secti
 A \`module-context.md\` with all placeholder sections filled in.
 `
 );
+var EVIDENCE_VERIFICATION = skill(
+  "evidence-verification",
+  "Evidence Verification Skill",
+  "delivery",
+  ["implementation-agent", "guard-agent"],
+  `
+# Evidence Verification Skill
+
+## Purpose
+
+Estandarizar la recolecci\xF3n de evidencia de implementaci\xF3n y la verificaci\xF3n de Criterios de
+Aceptaci\xF3n antes de completar un Work Item.
+
+## When to use
+
+Despu\xE9s de que la implementaci\xF3n y las pruebas de un Work Item terminan, antes de llamar
+\`kaddo learn\`.
+
+## Inputs
+
+- El Work Item (id, ACs, affected_modules, release_gates, completion_exceptions).
+- El diff o lista de archivos modificados.
+- Resultados de pruebas y validaciones.
+- Excepciones propuestas con categor\xEDa e impacto.
+
+## Output
+
+Un reporte de verificaci\xF3n: estado por AC, release gates, excepciones, desviaciones planned vs
+actual, y decisi\xF3n de completitud (READY_TO_COMPLETE | NEEDS_WORK | BLOCKED | READY_WITH_EXCEPTIONS).
+
+## Rules
+
+- Nunca marcar un AC como passed sin evidencia concreta.
+- Nunca omitir un release gate fallido sin registrar una excepci\xF3n aceptada.
+- No incluir rutas de secretos en changed_paths.
+- Usar \`kaddo verify\` o MCP tools \`kaddo_collect_evidence\`/\`kaddo_verify_work_item\`.
+
+## Quality checklist
+
+- Cada AC tiene un status expl\xEDcito.
+- Los release gates fallidos tienen blocker documentado.
+- Las excepciones aceptadas tienen approved_by y raz\xF3n.
+- No hay rutas de secretos en la evidencia.
+- La decisi\xF3n de completitud es coherente con ACs y gates.
+
+## Example output
+
+Un reporte de verificaci\xF3n con ACs, gates, excepciones y decisi\xF3n de completitud.
+`
+);
 var SKILLS = [
   ADR_WRITING,
   WORK_ITEM_REFINEMENT,
@@ -5001,10 +5115,11 @@ var SKILLS = [
   CAPSULE_WRITING,
   LEARNING_CAPTURE,
   IMPLEMENTATION_PLANNING,
-  MODULE_CONTEXT_REFINEMENT
+  MODULE_CONTEXT_REFINEMENT,
+  EVIDENCE_VERIFICATION
 ];
 var SKILL_GROUPS = {
-  delivery: ["work-item-refinement", "implementation-planning", "learning-capture"],
+  delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification"],
   tech: ["adr-writing", "ownership-suggestion", "graph-metadata-review", "module-context-refinement"],
   integration: ["capsule-writing"]
 };
@@ -12686,7 +12801,8 @@ var IMPLEMENTATION_PLANNING2 = skill2(
 
 ## Purpose
 
-Standardize the plan produced before implementation starts.
+Standardize the plan produced before implementation starts and ensure design deliberation is
+explicit before coding begins.
 
 ## When to use
 
@@ -12694,33 +12810,96 @@ Before writing code for a ready Work Item.
 
 ## Inputs
 
-The context pack and the ready Work Item.
+Assemble context proportionally from the Build Contract's five sources:
+
+1. **Work Item:** outcome, acceptance criteria, constraints, out-of-scope, affected_modules, domains.
+2. **Knowledge:** business, product, tech and delivery knowledge relevant to the Work Item's domains.
+3. **System Context:** topology, module dependencies, system graph when available.
+4. **Repository Context:** existing patterns, file structure, test conventions in affected modules.
+5. **Related Work Items:** dependencies (depends_on), completed related Work Items for precedent.
+
+## Context assembly
+
+Assemble proportionally to scope. A single-module bugfix needs the affected module's codebase
+and tests. A cross-cutting feature needs topology, multiple modules, and business context.
+Do not load everything \u2014 load what the scope demands.
 
 ## Output
 
-A plan with: technical scope, expected files, risks, validations, out of scope, implementation
-steps, and stop criteria (when to pause and ask).
+A plan covering the template below, ending with a confirmation gate.
+
+### Output template
+
+\`\`\`markdown
+# Implementation Plan \u2014 <WI id>
+
+## Context Summary
+<!-- Relevant knowledge, system context, and repository observations assembled for this WI. -->
+
+## Design Deliberation
+
+### Technical Approach
+<!-- How this will be implemented. Be specific about patterns, modules, layers involved. -->
+
+### Rationale
+<!-- Why this approach. Reference existing patterns, constraints, or WI requirements. -->
+
+### Alternatives Considered
+<!-- When the change is non-trivial. May be omitted for trivial/obvious changes with a note. -->
+
+### Trade-offs
+<!-- When alternatives exist. Explicitly state what is gained and lost. -->
+
+### ADR Recommendation
+<!-- When the decision is architecturally significant: recommend materializing as ADR
+     via adr-writing skill. Remove this section if not applicable. -->
+
+## Affected Areas
+<!-- Modules, files, surfaces impacted by this change. -->
+
+## Implementation Steps
+<!-- Numbered steps with expected files per step. -->
+
+## Validation Plan
+<!-- How to verify: test commands, manual steps, AC verification. -->
+
+## Stop Criteria
+<!-- When to pause and ask: scope expansion, contradictions, missing knowledge,
+     architectural uncertainty. -->
+
+## Confirmation Gate
+Do not start coding without explicit human confirmation of this plan.
+\`\`\`
 
 ## Rules
 
+- Document Technical Approach and Rationale before listing implementation steps.
 - Do not start coding without confirmation.
 - 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).
+- When you discover an architecturally significant decision during planning, recommend the
+  adr-writing skill and pause.
+- When alternatives exist, document them. For trivial or obvious changes, Alternatives and
+  Trade-offs may be omitted with a note explaining why.
+- Context assembly is proportional: do not load all project knowledge for a small fix.
 
 ## Quality checklist
 
 - Pre-implementation scope review is documented.
+- Technical Approach is documented with specific patterns and modules.
+- Rationale references WI requirements or existing project patterns.
+- Alternatives documented when non-trivial, or explicitly noted as not applicable.
+- ADR recommendation present when the decision is architecturally significant.
+- Context sources consulted are listed in Context Summary.
 - Scope and expected files are explicit.
 - Risks and validations are listed.
+- Validation plan includes how to verify each AC.
 - Stop criteria are defined.
 - Module coverage aligns with planned changes.
-
-## Example output
-
-A numbered plan covering the sections above, ending with a request to confirm before coding.
+- Confirmation gate is present.
 `
 );
 var MODULE_CONTEXT_REFINEMENT2 = skill2(
@@ -12775,6 +12954,56 @@ A refined \`module-context.md\` with real, project-specific content in all secti
 A \`module-context.md\` with all placeholder sections filled in.
 `
 );
+var EVIDENCE_VERIFICATION2 = skill2(
+  "evidence-verification",
+  "Evidence Verification Skill",
+  "delivery",
+  ["implementation-agent", "guard-agent"],
+  `
+# Evidence Verification Skill
+
+## Purpose
+
+Estandarizar la recolecci\xF3n de evidencia de implementaci\xF3n y la verificaci\xF3n de Criterios de
+Aceptaci\xF3n antes de completar un Work Item.
+
+## When to use
+
+Despu\xE9s de que la implementaci\xF3n y las pruebas de un Work Item terminan, antes de llamar
+\`kaddo learn\`.
+
+## Inputs
+
+- El Work Item (id, ACs, affected_modules, release_gates, completion_exceptions).
+- El diff o lista de archivos modificados.
+- Resultados de pruebas y validaciones.
+- Excepciones propuestas con categor\xEDa e impacto.
+
+## Output
+
+Un reporte de verificaci\xF3n: estado por AC, release gates, excepciones, desviaciones planned vs
+actual, y decisi\xF3n de completitud (READY_TO_COMPLETE | NEEDS_WORK | BLOCKED | READY_WITH_EXCEPTIONS).
+
+## Rules
+
+- Nunca marcar un AC como passed sin evidencia concreta.
+- Nunca omitir un release gate fallido sin registrar una excepci\xF3n aceptada.
+- No incluir rutas de secretos en changed_paths.
+- Usar \`kaddo verify\` o MCP tools \`kaddo_collect_evidence\`/\`kaddo_verify_work_item\`.
+
+## Quality checklist
+
+- Cada AC tiene un status expl\xEDcito.
+- Los release gates fallidos tienen blocker documentado.
+- Las excepciones aceptadas tienen approved_by y raz\xF3n.
+- No hay rutas de secretos en la evidencia.
+- La decisi\xF3n de completitud es coherente con ACs y gates.
+
+## Example output
+
+Un reporte de verificaci\xF3n con ACs, gates, excepciones y decisi\xF3n de completitud.
+`
+);
 var SKILLS2 = [
   ADR_WRITING2,
   WORK_ITEM_REFINEMENT2,
@@ -12783,10 +13012,11 @@ var SKILLS2 = [
   CAPSULE_WRITING2,
   LEARNING_CAPTURE2,
   IMPLEMENTATION_PLANNING2,
-  MODULE_CONTEXT_REFINEMENT2
+  MODULE_CONTEXT_REFINEMENT2,
+  EVIDENCE_VERIFICATION2
 ];
 var SKILL_GROUPS2 = {
-  delivery: ["work-item-refinement", "implementation-planning", "learning-capture"],
+  delivery: ["work-item-refinement", "implementation-planning", "learning-capture", "evidence-verification"],
   tech: ["adr-writing", "ownership-suggestion", "graph-metadata-review", "module-context-refinement"],
   integration: ["capsule-writing"]
 };
@@ -15583,6 +15813,103 @@ var USER_FACING_KEYWORDS_ES = [
   "mensaje"
 ];
 var USER_FACING_KEYWORDS = /* @__PURE__ */ new Set([...USER_FACING_KEYWORDS_EN, ...USER_FACING_KEYWORDS_ES]);
+function analyzeCrossRepoEvidence(input) {
+  const findings = [];
+  const { id, lifecycle, implementationStatus, validationStatus, releaseStatus, affectedModules } = input;
+  const raw = input.rawFrontmatter;
+  const evidence = raw.implementation_evidence;
+  const repos = evidence?.repositories ?? {};
+  const releaseGates = Array.isArray(raw.release_gates) ? raw.release_gates : [];
+  const exceptions = Array.isArray(raw.completion_exceptions) ? raw.completion_exceptions : [];
+  const repoEvidence = {};
+  for (const [repoId, data] of Object.entries(repos)) {
+    const d3 = data;
+    repoEvidence[repoId] = {
+      role: String(d3.role ?? (repoId === "core" ? "core" : "module")),
+      status: String(d3.status ?? "unknown")
+    };
+  }
+  for (const mod of affectedModules) {
+    if (mod === "core") continue;
+    if (!input.registeredModuleIds.includes(mod)) {
+      findings.push({ id, severity: "blocking", message: `Affected module "${mod}" is not registered in .kaddo/modules.yml.` });
+    }
+  }
+  for (const repoId of input.modifiedRepoIds) {
+    if (!affectedModules.includes(repoId) && repoId !== "core") {
+      findings.push({ id, severity: "blocking", message: `Repository "${repoId}" was modified but not declared in affected_modules.` });
+    }
+  }
+  for (const mod of affectedModules) {
+    if (!repoEvidence[mod] && Object.keys(repos).length > 0) {
+      findings.push({ id, severity: "warning", message: `Declared affected module "${mod}" has no implementation evidence.` });
+    }
+  }
+  for (const [repoId, data] of Object.entries(repos)) {
+    const d3 = data;
+    const validations = Array.isArray(d3.validations) ? d3.validations : [];
+    for (const v of validations) {
+      if (v.status === "not-run") {
+        findings.push({ id, severity: "warning", message: `Validation "${v.command}" in ${repoId} was not executed.` });
+      }
+    }
+    const migrations = Array.isArray(d3.migrations) ? d3.migrations : [];
+    for (const m2 of migrations) {
+      if (m2.status === "blocked") {
+        findings.push({ id, severity: "warning", message: `Migration "${m2.id}" (${m2.environment}) in ${repoId} is blocked.` });
+      }
+    }
+  }
+  if (lifecycle === "completed") {
+    const proposedExceptions = exceptions.filter((e) => e.status === "proposed");
+    if (proposedExceptions.length > 0) {
+      findings.push({ id, severity: "blocking", message: "Work Item is completed but has proposed (not accepted) exceptions." });
+    }
+    if (releaseStatus === "ready") {
+      const blockedGates = releaseGates.filter((g) => g.status === "blocked" || g.status === "failed");
+      if (blockedGates.length > 0) {
+        findings.push({ id, severity: "blocking", message: `Release status is "ready" but ${blockedGates.length} gate(s) are blocked/failed.` });
+      }
+    }
+  }
+  for (const [repoId, data] of Object.entries(repos)) {
+    const d3 = data;
+    const validations = Array.isArray(d3.validations) ? d3.validations : [];
+    for (const v of validations) {
+      if (v.status === "passed" && (!v.command || !v.command.trim())) {
+        findings.push({ id, severity: "blocking", message: `Evidence in ${repoId} marked "passed" without a command record.` });
+      }
+    }
+  }
+  if (validationStatus === "accepted-with-exceptions") {
+    const hasExceptions = exceptions.length > 0;
+    const hasValidationGate = releaseGates.some(
+      (g) => (g.status === "pending" || g.status === "blocked") && (g.id.includes("validation") || g.id.includes("test"))
+    );
+    if (!hasExceptions && !hasValidationGate) {
+      findings.push({ id, severity: "warning", message: "Validation status is accepted-with-exceptions, but no exception evidence was found." });
+    }
+  }
+  if (raw.status === "done") {
+    findings.push({ id, severity: "warning", message: "Legacy status `done` detected. Canonical status is `completed`." });
+  }
+  if (raw.refined_by && raw.implemented_by && raw.refined_by === raw.implemented_by) {
+    findings.push({ id, severity: "fyi", message: "refined_by and implemented_by point to the same agent." });
+  }
+  const historicalDefault = lifecycle === "completed" || lifecycle === "archived" ? "not-assessed" : "not-started";
+  return {
+    id,
+    lifecycle,
+    implementationStatus: implementationStatus || historicalDefault,
+    validationStatus: validationStatus || historicalDefault,
+    releaseStatus: releaseStatus || "not-assessed",
+    affectedModules,
+    findings,
+    releaseGates,
+    completionExceptions: exceptions,
+    repoEvidence
+  };
+}
 var TOPOLOGY_FILE = "knowledge/tech/system-topology.yml";
 var SYSTEM_ENTITY_KINDS = /* @__PURE__ */ new Set([
   "system",
@@ -16435,6 +16762,228 @@ function buildRefinementHandoff(dir, workItemId) {
     text: lines.join("\n")
   };
 }
+var WorkItemNotInProgressError = class extends Error {
+  constructor(workItemId, actualState) {
+    super(`Work Item "${workItemId}" must be in "in-progress" state for verification, but is "${actualState}".`);
+    this.workItemId = workItemId;
+    this.actualState = actualState;
+    this.name = "WorkItemNotInProgressError";
+  }
+  workItemId;
+  actualState;
+};
+var SECRET_PATTERNS = [
+  /\.env($|\.)/i,
+  /credential/i,
+  /secret/i,
+  /token/i,
+  /\.key$/i,
+  /\.pem$/i,
+  /\.p12$/i,
+  /\.pfx$/i
+];
+function filterSecretPaths(paths) {
+  return paths.filter((p2) => !SECRET_PATTERNS.some((re) => re.test(p2)));
+}
+function collectImplementationEvidence(dir, workItemId, input) {
+  const artifacts = discoverWorkItems2(dir);
+  const match = artifacts.find((a2) => (a2.id || a2.title) === workItemId);
+  if (!match) throw new WorkItemNotFoundError(workItemId);
+  const lifecycle = lifecycleStateOf2({ status: match.status, filePath: match.filePath });
+  if (lifecycle !== "in-progress") throw new WorkItemNotInProgressError(workItemId, lifecycle);
+  const repositories = {};
+  for (const repo of input.repos) {
+    repositories[repo.repoId] = {
+      role: repo.role ?? (repo.repoId === "core" ? "core" : "module"),
+      status: deriveRepoStatus(repo),
+      changed_paths: filterSecretPaths(repo.changedPaths),
+      validations: repo.validations.map((v) => ({
+        command: v.command,
+        status: v.status,
+        ...v.reason ? { reason: v.reason } : {}
+      })),
+      ...repo.migrations?.length ? {
+        migrations: repo.migrations.map((m2) => ({
+          id: m2.id,
+          environment: m2.environment,
+          status: m2.status,
+          ...m2.reason ? { reason: m2.reason } : {}
+        }))
+      } : {}
+    };
+  }
+  return { repositories };
+}
+function verifyWorkItem(dir, workItemId, input) {
+  const evidence = collectImplementationEvidence(dir, workItemId, input);
+  const artifacts = discoverWorkItems2(dir);
+  const match = artifacts.find((a2) => (a2.id || a2.title) === workItemId);
+  const lifecycle = lifecycleStateOf2({ status: match.status, filePath: match.filePath });
+  const fm = match.rawFrontmatter;
+  const acVerifications = mapACVerifications(input.acVerifications);
+  const acSummary = computeACSummary(acVerifications);
+  const releaseGates = Array.isArray(fm.release_gates) ? fm.release_gates : [];
+  const completionExceptions = Array.isArray(fm.completion_exceptions) ? fm.completion_exceptions : [];
+  const plannedVsActual = computePlannedVsActual(match.affectedModules, input.repos);
+  const registeredModuleIds = loadMappedModules2(dir).map((m2) => m2.id);
+  const modifiedRepoIds = input.repos.map((r2) => r2.repoId);
+  const crossRepo = analyzeCrossRepoEvidence({
+    id: workItemId,
+    lifecycle,
+    implementationStatus: match.implementationStatus || "not-started",
+    validationStatus: match.validationStatus || "not-started",
+    releaseStatus: match.releaseStatus || "not-assessed",
+    affectedModules: match.affectedModules,
+    rawFrontmatter: fm,
+    registeredModuleIds,
+    modifiedRepoIds
+  });
+  const validationStatus = deriveValidationStatus(input.repos, acVerifications, completionExceptions);
+  const implementationStatus = deriveImplementationStatus(input.repos);
+  return {
+    workItemId,
+    lifecycle,
+    implementationEvidence: evidence,
+    acVerifications,
+    acSummary,
+    releaseGates,
+    completionExceptions,
+    findings: crossRepo.findings,
+    plannedVsActual,
+    validationStatus,
+    implementationStatus
+  };
+}
+function evaluateCompletion(verification) {
+  const blockers = [];
+  const warnings = [];
+  const reasons = [];
+  for (const gate of verification.releaseGates) {
+    if (gate.status === "failed" || gate.status === "blocked") {
+      blockers.push(`Release gate "${gate.id}" is ${gate.status}${gate.reason ? ": " + gate.reason : ""}.`);
+    } else if (gate.status === "pending") {
+      warnings.push(`Release gate "${gate.id}" is still pending.`);
+    }
+  }
+  for (const ex of verification.completionExceptions) {
+    if (ex.status === "rejected") {
+      blockers.push(`Completion exception "${ex.id}" was rejected${ex.reason ? ": " + ex.reason : ""}.`);
+    } else if (ex.status === "proposed") {
+      warnings.push(`Completion exception "${ex.id}" is still proposed (not yet accepted).`);
+    }
+  }
+  if (verification.acSummary.failed > 0) {
+    const failedACs = verification.acVerifications.filter((ac) => ac.status === "failed");
+    for (const ac of failedACs) {
+      blockers.push(`AC failed: "${ac.criterion}".`);
+    }
+  }
+  const blockingFindings = verification.findings.filter((f3) => f3.severity === "blocking");
+  for (const f3 of blockingFindings) {
+    blockers.push(f3.message);
+  }
+  if (verification.acSummary.manualReview > 0) {
+    warnings.push(`${verification.acSummary.manualReview} AC(s) require manual review.`);
+  }
+  if (verification.acSummary.notVerified > 0) {
+    warnings.push(`${verification.acSummary.notVerified} AC(s) not yet verified.`);
+  }
+  const warningFindings = verification.findings.filter((f3) => f3.severity === "warning");
+  for (const f3 of warningFindings) {
+    warnings.push(f3.message);
+  }
+  if (verification.plannedVsActual) {
+    const pva = verification.plannedVsActual;
+    if (pva.missingModules.length > 0) {
+      warnings.push(`Planned modules not touched: ${pva.missingModules.join(", ")}.`);
+    }
+    if (pva.addedModules.length > 0) {
+      warnings.push(`Unplanned modules modified: ${pva.addedModules.join(", ")}.`);
+    }
+  }
+  let readiness;
+  if (blockers.length > 0) {
+    const hasOnlyACFailures = blockers.every((b2) => b2.startsWith("AC failed:"));
+    if (hasOnlyACFailures) {
+      readiness = "NEEDS_WORK";
+      reasons.push("Acceptance criteria have failures that must be addressed.");
+    } else {
+      readiness = "BLOCKED";
+      reasons.push("Blocking conditions prevent completion.");
+    }
+  } else {
+    const hasAcceptedExceptions = verification.completionExceptions.some((e) => e.status === "accepted");
+    if (hasAcceptedExceptions) {
+      readiness = "READY_WITH_EXCEPTIONS";
+      reasons.push("All required criteria pass. Accepted exceptions are documented.");
+    } else {
+      readiness = "READY_TO_COMPLETE";
+      reasons.push("All acceptance criteria pass. No blocking conditions.");
+    }
+  }
+  return { readiness, reasons, blockers, warnings };
+}
+function deriveRepoStatus(repo) {
+  if (repo.validations.length === 0 && repo.changedPaths.length === 0) return "not-started";
+  const hasFailure = repo.validations.some((v) => v.status === "failed" || v.status === "error");
+  if (hasFailure) return "failed";
+  const allPassed = repo.validations.length > 0 && repo.validations.every((v) => v.status === "passed" || v.status === "skipped");
+  if (allPassed) return "completed";
+  return "in-progress";
+}
+function mapACVerifications(verifications) {
+  return verifications.map((v) => ({ ...v }));
+}
+function computeACSummary(verifications) {
+  return {
+    total: verifications.length,
+    passed: verifications.filter((v) => v.status === "passed").length,
+    failed: verifications.filter((v) => v.status === "failed").length,
+    notVerified: verifications.filter((v) => v.status === "not-verified").length,
+    manualReview: verifications.filter((v) => v.status === "manual-review-required").length
+  };
+}
+function computePlannedVsActual(affectedModules, repos) {
+  if (affectedModules.length === 0) return null;
+  const actualModules = [...new Set(repos.map((r2) => r2.repoId))];
+  const plannedSet = new Set(affectedModules);
+  const actualSet = new Set(actualModules);
+  return {
+    hasHandoff: true,
+    plannedModules: affectedModules,
+    actualModules,
+    addedModules: actualModules.filter((m2) => !plannedSet.has(m2)),
+    missingModules: affectedModules.filter((m2) => !actualSet.has(m2))
+  };
+}
+function deriveValidationStatus(repos, acVerifications, completionExceptions) {
+  const allValidations = repos.flatMap((r2) => r2.validations);
+  if (allValidations.length === 0 && acVerifications.length === 0) return "not-started";
+  const hasFailed = allValidations.some((v) => v.status === "failed" || v.status === "error") || acVerifications.some((v) => v.status === "failed");
+  if (hasFailed) {
+    const hasAccepted = completionExceptions.some((e) => e.status === "accepted");
+    if (hasAccepted) return "accepted-with-exceptions";
+    return "failed";
+  }
+  const hasBlocked = allValidations.some((v) => v.status === "error");
+  if (hasBlocked) return "blocked";
+  const allComplete = allValidations.every((v) => v.status === "passed" || v.status === "skipped") && acVerifications.every((v) => v.status === "passed" || v.status === "not-verified");
+  if (allComplete && allValidations.length > 0) return "passed";
+  return "in-progress";
+}
+function deriveImplementationStatus(repos) {
+  if (repos.length === 0) return "not-started";
+  const hasChanges = repos.some((r2) => r2.changedPaths.length > 0);
+  if (!hasChanges) return "not-started";
+  const allComplete = repos.every((r2) => {
+    const status = deriveRepoStatus(r2);
+    return status === "completed";
+  });
+  if (allComplete) return "completed";
+  const hasFailed = repos.some((r2) => deriveRepoStatus(r2) === "failed");
+  if (hasFailed) return "partial";
+  return "in-progress";
+}
 var MAX_INPUT_BYTES = 102400;
 var LIFECYCLE_FIELDS = /* @__PURE__ */ new Set([
   "id",
@@ -17465,6 +18014,27 @@ function importWorkItemTool(root, args) {
     return fail("Work Item import failed.");
   }
 }
+function collectEvidenceTool(root, args) {
+  try {
+    const result = collectImplementationEvidence(root, args.workItemId, args.evidence);
+    return ok({ workItemId: args.workItemId, evidence: result });
+  } catch (err) {
+    if (err instanceof WorkItemNotFoundError) return fail(err.message);
+    if (err instanceof WorkItemNotInProgressError) return fail(err.message);
+    return fail("Evidence collection failed.");
+  }
+}
+function verifyWorkItemTool(root, args) {
+  try {
+    const verification = verifyWorkItem(root, args.workItemId, args.evidence);
+    const evaluation = evaluateCompletion(verification);
+    return ok({ verification, evaluation });
+  } catch (err) {
+    if (err instanceof WorkItemNotFoundError) return fail(err.message);
+    if (err instanceof WorkItemNotInProgressError) return fail(err.message);
+    return fail("Work Item verification failed.");
+  }
+}
 
 // src/multirepo.ts
 import fs5 from "fs";
@@ -21026,6 +21596,59 @@ function createServer(root) {
     },
     async (args) => toolText(guarded(root, () => importWorkItemTool(root, args)))
   );
+  const evidenceRepoSchema = z4.object({
+    repoId: z4.string(),
+    role: z4.string().optional(),
+    changedPaths: z4.array(z4.string()),
+    validations: z4.array(z4.object({
+      command: z4.string(),
+      status: z4.enum(["passed", "failed", "skipped", "error"]),
+      reason: z4.string().optional()
+    })),
+    migrations: z4.array(z4.object({
+      id: z4.string(),
+      environment: z4.string(),
+      status: z4.string(),
+      reason: z4.string().optional()
+    })).optional()
+  });
+  const acVerificationSchema = z4.object({
+    criterion: z4.string(),
+    status: z4.enum(["passed", "failed", "not-verified", "manual-review-required"]),
+    evidence: z4.string().optional()
+  });
+  const evidenceInputSchema = z4.object({
+    repos: z4.array(evidenceRepoSchema),
+    summary: z4.string().optional(),
+    deviations: z4.array(z4.string()).optional(),
+    issues: z4.array(z4.string()).optional(),
+    knowledgeGaps: z4.array(z4.string()).optional(),
+    acVerifications: z4.array(acVerificationSchema)
+  });
+  server.registerTool(
+    "kaddo_collect_evidence",
+    {
+      title: "Collect Implementation Evidence",
+      description: "Collect structured evidence of what changed during implementation of an in-progress Work Item. Accepts repository changes, validations, and AC verifications. Returns structured evidence ready for frontmatter.",
+      inputSchema: {
+        workItemId: z4.string().describe("The Work Item ID (e.g. WI-005)"),
+        evidence: evidenceInputSchema
+      }
+    },
+    async (args) => toolText(guarded(root, () => collectEvidenceTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_verify_work_item",
+    {
+      title: "Verify Work Item",
+      description: "Verify implementation evidence, acceptance criteria, release gates, and completion exceptions for an in-progress Work Item. Returns a verification result with AC status, findings, and a completion decision (READY_TO_COMPLETE, NEEDS_WORK, BLOCKED, READY_WITH_EXCEPTIONS).",
+      inputSchema: {
+        workItemId: z4.string().describe("The Work Item ID (e.g. WI-005)"),
+        evidence: evidenceInputSchema
+      }
+    },
+    async (args) => toolText(guarded(root, () => verifyWorkItemTool(root, args)))
+  );
   let installedSkills = [];
   try {
     assertKaddoProject(root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/mcp",
-  "version": "3.92.0",
+  "version": "3.95.0",
   "description": "MCP server for Kaddo project knowledge: read-only resources/tools/prompts plus safe derived generation under .kaddo/.",
   "license": "MIT",
   "repository": {