mrvn-cli 0.3.3 → 0.3.6

package/dist/marvin.js

@@ -920,10 +920,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path18) {
-  if (!path18)
+function getElementAtPath(obj, path20) {
+  if (!path20)
     return obj;
-  return path18.reduce((acc, key) => acc?.[key], obj);
+  return path20.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -1306,11 +1306,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path18, issues) {
+function prefixIssues(path20, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path18);
+    iss.path.unshift(path20);
     return iss;
   });
 }
@@ -1493,7 +1493,7 @@ function formatError(error48, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error48, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error49, path18 = []) => {
+  const processError = (error49, path20 = []) => {
     var _a2, _b;
     for (const issue2 of error49.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
@@ -1503,7 +1503,7 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
       } else if (issue2.code === "invalid_element") {
         processError({ issues: issue2.issues }, issue2.path);
       } else {
-        const fullpath = [...path18, ...issue2.path];
+        const fullpath = [...path20, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -1535,8 +1535,8 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path18 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path18) {
+  const path20 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path20) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -13513,13 +13513,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path18 = ref.slice(1).split("/").filter(Boolean);
-  if (path18.length === 0) {
+  const path20 = ref.slice(1).split("/").filter(Boolean);
+  if (path20.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path18[0] === defsKey) {
-    const key = path18[1];
+  if (path20[0] === defsKey) {
+    const key = path20[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -13942,7 +13942,7 @@ function createMeetingTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool(
       "get_meeting",
@@ -13969,7 +13969,7 @@ function createMeetingTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool(
       "create_meeting",
@@ -14094,7 +14094,7 @@ function createMeetingTools(store) {
           content: [{ type: "text", text: sections.join("\n") }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     )
   ];
 }
@@ -14111,12 +14111,20 @@ function collectGarMetrics(store) {
   const blockedItems = allDocs.filter(
     (d) => d.frontmatter.tags?.includes("blocked")
   );
-  const overdueItems = allDocs.filter(
+  const tagOverdueItems = allDocs.filter(
     (d) => d.frontmatter.tags?.includes("overdue")
   );
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const dateOverdueActions = openActions.filter((d) => {
+    const dueDate = d.frontmatter.dueDate;
+    return typeof dueDate === "string" && dueDate < today;
+  });
+  const overdueItems = [...tagOverdueItems, ...dateOverdueActions].filter(
+    (d, i, arr) => arr.findIndex((x) => x.frontmatter.id === d.frontmatter.id) === i
+  );
   const openQuestions = store.list({ type: "question", status: "open" });
   const riskItems = allDocs.filter(
-    (d) => d.frontmatter.tags?.includes("risk")
+    (d) => d.frontmatter.tags?.includes("risk") && d.frontmatter.status !== "done" && d.frontmatter.status !== "closed"
   );
   const unownedActions = openActions.filter((d) => !d.frontmatter.owner);
   const total = allActions.length;
@@ -14222,6 +14230,253 @@ function evaluateGar(projectName, metrics) {
   };
 }
 
+// src/reports/health/collector.ts
+var FIELD_CHECKS = [
+  {
+    type: "action",
+    openStatuses: ["open", "in-progress"],
+    requiredFields: ["owner", "priority", "dueDate", "content"]
+  },
+  {
+    type: "decision",
+    openStatuses: ["open", "proposed"],
+    requiredFields: ["owner", "content"]
+  },
+  {
+    type: "question",
+    openStatuses: ["open"],
+    requiredFields: ["owner", "content"]
+  },
+  {
+    type: "feature",
+    openStatuses: ["draft", "approved"],
+    requiredFields: ["owner", "priority", "content"]
+  },
+  {
+    type: "epic",
+    openStatuses: ["planned", "in-progress"],
+    requiredFields: ["owner", "targetDate", "estimatedEffort", "content"]
+  },
+  {
+    type: "sprint",
+    openStatuses: ["planned", "active"],
+    requiredFields: ["goal", "startDate", "endDate", "linkedEpics"]
+  }
+];
+var STALE_THRESHOLD_DAYS = 14;
+var AGING_THRESHOLD_DAYS = 30;
+function daysBetween(a, b) {
+  const msPerDay = 864e5;
+  const dateA = new Date(a);
+  const dateB = new Date(b);
+  return Math.floor(Math.abs(dateB.getTime() - dateA.getTime()) / msPerDay);
+}
+function checkMissingFields(doc, requiredFields) {
+  const missing = [];
+  for (const field of requiredFields) {
+    if (field === "content") {
+      if (!doc.content || doc.content.trim().length === 0) {
+        missing.push("content");
+      }
+    } else if (field === "linkedEpics") {
+      const val = doc.frontmatter[field];
+      if (!Array.isArray(val) || val.length === 0) {
+        missing.push(field);
+      }
+    } else {
+      const val = doc.frontmatter[field];
+      if (val === void 0 || val === null || val === "") {
+        missing.push(field);
+      }
+    }
+  }
+  return missing;
+}
+function collectCompleteness(store) {
+  const result = {};
+  for (const check2 of FIELD_CHECKS) {
+    const allOfType = store.list({ type: check2.type });
+    const openDocs = allOfType.filter(
+      (d) => check2.openStatuses.includes(d.frontmatter.status)
+    );
+    const gaps = [];
+    let complete = 0;
+    for (const doc of openDocs) {
+      const missingFields = checkMissingFields(doc, check2.requiredFields);
+      if (missingFields.length === 0) {
+        complete++;
+      } else {
+        gaps.push({
+          id: doc.frontmatter.id,
+          title: doc.frontmatter.title,
+          missingFields
+        });
+      }
+    }
+    result[check2.type] = {
+      total: openDocs.length,
+      complete,
+      gaps
+    };
+  }
+  return result;
+}
+function collectProcess(store) {
+  const today = (/* @__PURE__ */ new Date()).toISOString();
+  const allDocs = store.list();
+  const openStatuses = new Set(FIELD_CHECKS.flatMap((c) => c.openStatuses));
+  const openDocs = allDocs.filter((d) => openStatuses.has(d.frontmatter.status));
+  const stale = [];
+  for (const doc of openDocs) {
+    const updated = doc.frontmatter.updated ?? doc.frontmatter.created;
+    const days = daysBetween(updated, today);
+    if (days >= STALE_THRESHOLD_DAYS) {
+      stale.push({ id: doc.frontmatter.id, title: doc.frontmatter.title, days });
+    }
+  }
+  const openActions = store.list({ type: "action" }).filter((d) => d.frontmatter.status === "open" || d.frontmatter.status === "in-progress");
+  const agingActions = [];
+  for (const doc of openActions) {
+    const days = daysBetween(doc.frontmatter.created, today);
+    if (days >= AGING_THRESHOLD_DAYS) {
+      agingActions.push({ id: doc.frontmatter.id, title: doc.frontmatter.title, days });
+    }
+  }
+  const resolvedDecisions = store.list({ type: "decision" }).filter((d) => !["open", "proposed"].includes(d.frontmatter.status));
+  let decisionTotal = 0;
+  for (const doc of resolvedDecisions) {
+    decisionTotal += daysBetween(doc.frontmatter.created, doc.frontmatter.updated);
+  }
+  const decisionVelocity = {
+    avgDays: resolvedDecisions.length > 0 ? Math.round(decisionTotal / resolvedDecisions.length) : 0,
+    count: resolvedDecisions.length
+  };
+  const answeredQuestions = store.list({ type: "question" }).filter((d) => d.frontmatter.status !== "open");
+  let questionTotal = 0;
+  for (const doc of answeredQuestions) {
+    questionTotal += daysBetween(doc.frontmatter.created, doc.frontmatter.updated);
+  }
+  const questionResolution = {
+    avgDays: answeredQuestions.length > 0 ? Math.round(questionTotal / answeredQuestions.length) : 0,
+    count: answeredQuestions.length
+  };
+  return { stale, agingActions, decisionVelocity, questionResolution };
+}
+function collectHealthMetrics(store) {
+  return {
+    completeness: collectCompleteness(store),
+    process: collectProcess(store)
+  };
+}
+
+// src/reports/health/evaluator.ts
+function worstStatus2(statuses) {
+  if (statuses.includes("red")) return "red";
+  if (statuses.includes("amber")) return "amber";
+  return "green";
+}
+function completenessStatus(total, complete) {
+  if (total === 0) return "green";
+  const pct = Math.round(complete / total * 100);
+  if (pct >= 100) return "green";
+  if (pct >= 75) return "amber";
+  return "red";
+}
+var TYPE_LABELS = {
+  action: "Actions",
+  decision: "Decisions",
+  question: "Questions",
+  feature: "Features",
+  epic: "Epics",
+  sprint: "Sprints"
+};
+function evaluateHealth(projectName, metrics) {
+  const completeness = [];
+  for (const [type, catMetrics] of Object.entries(metrics.completeness)) {
+    const { total, complete, gaps } = catMetrics;
+    const status = completenessStatus(total, complete);
+    const pct = total > 0 ? Math.round(complete / total * 100) : 100;
+    completeness.push({
+      name: TYPE_LABELS[type] ?? type,
+      status,
+      summary: `${pct}% complete (${complete}/${total})`,
+      items: gaps.map((g) => ({
+        id: g.id,
+        detail: `missing: ${g.missingFields.join(", ")}`
+      }))
+    });
+  }
+  const process3 = [];
+  const staleCount = metrics.process.stale.length;
+  const staleStatus = staleCount === 0 ? "green" : staleCount <= 3 ? "amber" : "red";
+  process3.push({
+    name: "Stale Items",
+    status: staleStatus,
+    summary: staleCount === 0 ? "no stale items" : `${staleCount} item(s) not updated in 14+ days`,
+    items: metrics.process.stale.map((s) => ({
+      id: s.id,
+      detail: `${s.days} days since last update`
+    }))
+  });
+  const agingCount = metrics.process.agingActions.length;
+  const agingStatus = agingCount === 0 ? "green" : agingCount <= 3 ? "amber" : "red";
+  process3.push({
+    name: "Aging Actions",
+    status: agingStatus,
+    summary: agingCount === 0 ? "no aging actions" : `${agingCount} action(s) open for 30+ days`,
+    items: metrics.process.agingActions.map((a) => ({
+      id: a.id,
+      detail: `open for ${a.days} days`
+    }))
+  });
+  const dv = metrics.process.decisionVelocity;
+  let dvStatus;
+  if (dv.count === 0) {
+    dvStatus = "green";
+  } else if (dv.avgDays <= 7) {
+    dvStatus = "green";
+  } else if (dv.avgDays <= 21) {
+    dvStatus = "amber";
+  } else {
+    dvStatus = "red";
+  }
+  process3.push({
+    name: "Decision Velocity",
+    status: dvStatus,
+    summary: dv.count === 0 ? "no resolved decisions" : `avg ${dv.avgDays} days to resolve (${dv.count} decision(s))`,
+    items: []
+  });
+  const qr = metrics.process.questionResolution;
+  let qrStatus;
+  if (qr.count === 0) {
+    qrStatus = "green";
+  } else if (qr.avgDays <= 7) {
+    qrStatus = "green";
+  } else if (qr.avgDays <= 14) {
+    qrStatus = "amber";
+  } else {
+    qrStatus = "red";
+  }
+  process3.push({
+    name: "Question Resolution",
+    status: qrStatus,
+    summary: qr.count === 0 ? "no answered questions" : `avg ${qr.avgDays} days to answer (${qr.count} question(s))`,
+    items: []
+  });
+  const allStatuses = [
+    ...completeness.map((c) => c.status),
+    ...process3.map((p) => p.status)
+  ];
+  const overall = worstStatus2(allStatuses);
+  return {
+    projectName,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+    overall,
+    completeness,
+    process: process3
+  };
+}
+
 // src/plugins/builtin/tools/reports.ts
 function createReportTools(store) {
   return [
@@ -14241,7 +14496,8 @@ function createReportTools(store) {
             id: d.frontmatter.id,
             title: d.frontmatter.title,
             owner: d.frontmatter.owner,
-            priority: d.frontmatter.priority
+            priority: d.frontmatter.priority,
+            dueDate: d.frontmatter.dueDate
           })),
           completedActions: completedActions.map((d) => ({
             id: d.frontmatter.id,
@@ -14260,7 +14516,7 @@ function createReportTools(store) {
           content: [{ type: "text", text: JSON.stringify(report, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool2(
       "generate_risk_register",
@@ -14269,7 +14525,7 @@ function createReportTools(store) {
       async () => {
         const allDocs = store.list();
         const taggedRisks = allDocs.filter(
-          (d) => d.frontmatter.tags?.includes("risk")
+          (d) => d.frontmatter.tags?.includes("risk") && d.frontmatter.status !== "done" && d.frontmatter.status !== "closed"
         );
         const highPriorityActions = store.list({ type: "action", status: "open" }).filter((d) => d.frontmatter.priority === "high");
         const unresolvedQuestions = store.list({ type: "question", status: "open" });
@@ -14304,7 +14560,7 @@ function createReportTools(store) {
           content: [{ type: "text", text: JSON.stringify(register, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool2(
       "generate_gar_report",
@@ -14317,7 +14573,7 @@ function createReportTools(store) {
           content: [{ type: "text", text: JSON.stringify(report, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool2(
       "generate_epic_progress",
@@ -14402,7 +14658,7 @@ function createReportTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool2(
       "generate_sprint_progress",
@@ -14447,7 +14703,8 @@ function createReportTools(store) {
                 id: d.frontmatter.id,
                 title: d.frontmatter.title,
                 type: d.frontmatter.type,
-                status: d.frontmatter.status
+                status: d.frontmatter.status,
+                dueDate: d.frontmatter.dueDate
               }))
             }
           };
@@ -14456,7 +14713,7 @@ function createReportTools(store) {
           content: [{ type: "text", text: JSON.stringify({ sprints }, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool2(
       "generate_feature_progress",
@@ -14496,7 +14753,20 @@ function createReportTools(store) {
           content: [{ type: "text", text: JSON.stringify({ features }, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
+    ),
+    tool2(
+      "generate_health_report",
+      "Generate a governance health check report covering artifact completeness and process health metrics",
+      {},
+      async () => {
+        const metrics = collectHealthMetrics(store);
+        const report = evaluateHealth("project", metrics);
+        return {
+          content: [{ type: "text", text: JSON.stringify(report, null, 2) }]
+        };
+      },
+      { annotations: { readOnlyHint: true } }
     ),
     tool2(
       "save_report",
@@ -14558,7 +14828,7 @@ function createFeatureTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool3(
       "get_feature",
@@ -14585,7 +14855,7 @@ function createFeatureTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool3(
       "create_feature",
@@ -14626,7 +14896,8 @@ function createFeatureTools(store) {
         status: external_exports.enum(["draft", "approved", "deferred", "done"]).optional().describe("New status"),
         content: external_exports.string().optional().describe("New content"),
         owner: external_exports.string().optional().describe("New owner"),
-        priority: external_exports.enum(["critical", "high", "medium", "low"]).optional().describe("New priority")
+        priority: external_exports.enum(["critical", "high", "medium", "low"]).optional().describe("New priority"),
+        tags: external_exports.array(external_exports.string()).optional().describe("Replace tags (e.g. remove 'risk', add 'risk-mitigated')")
       },
       async (args) => {
         const { id, content, ...updates } = args;
@@ -14676,7 +14947,7 @@ function createEpicTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool4(
       "get_epic",
@@ -14703,7 +14974,7 @@ function createEpicTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool4(
       "create_epic",
@@ -14783,7 +15054,8 @@ function createEpicTools(store) {
         content: external_exports.string().optional().describe("New content"),
         owner: external_exports.string().optional().describe("New owner"),
         targetDate: external_exports.string().optional().describe("New target date"),
-        estimatedEffort: external_exports.string().optional().describe("New estimated effort")
+        estimatedEffort: external_exports.string().optional().describe("New estimated effort"),
+        tags: external_exports.array(external_exports.string()).optional().describe("Replace tags (e.g. remove 'risk', add 'risk-mitigated')")
       },
       async (args) => {
         const { id, content, ...updates } = args;
@@ -14835,7 +15107,7 @@ function createContributionTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool5(
       "get_contribution",
@@ -14862,7 +15134,7 @@ function createContributionTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool5(
       "create_contribution",
@@ -14947,7 +15219,7 @@ function createSprintTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool6(
       "get_sprint",
@@ -14974,7 +15246,7 @@ function createSprintTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool6(
       "create_sprint",
@@ -15271,7 +15543,7 @@ function createSprintPlanningTools(store) {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     )
   ];
 }
@@ -15325,6 +15597,7 @@ var genericAgilePlugin = {
 - Do NOT create epics \u2014 that is the Tech Lead's responsibility. You can view epics to track progress.
 - Use priority levels (critical, high, medium, low) to communicate business value.
 - Tag features for categorization and cross-referencing.
+- Include a \`dueDate\` on actions when target dates are known, to enable schedule tracking and overdue detection.
 
 **Contribution Tools:**
 - **list_contributions** / **get_contribution**: Browse and read contribution records.
@@ -15355,6 +15628,7 @@ var genericAgilePlugin = {
 - Tag work items (actions, decisions, questions) with \`epic:E-xxx\` to group them under an epic.
 - Collaborate with the Delivery Manager on target dates and effort estimates.
 - Each epic should have a clear scope and definition of done.
+- Set \`dueDate\` on technical actions based on sprint timelines or epic target dates. Use the \`sprints\` parameter to assign actions to relevant sprints.
 
 **Contribution Tools:**
 - **list_contributions** / **get_contribution**: Browse and read contribution records.
@@ -15414,6 +15688,11 @@ var genericAgilePlugin = {
 - **generate_sprint_progress**: Progress report for a specific sprint or all sprints \u2014 shows linked epics with statuses, work items tagged \`sprint:SP-xxx\` grouped by status, and done/total completion %.
 - Use \`save_report\` with reportType "sprint-progress" to persist sprint reports.
 
+**Date Enforcement:**
+- Always set \`dueDate\` when creating or updating actions. Use the \`sprints\` parameter to assign actions to sprints \u2014 the tool translates this into \`sprint:SP-xxx\` tags automatically.
+- When create_action suggests matching sprints in its response, review and assign accordingly using update_action.
+- Use \`suggest_sprints_for_action\` to find the right sprint for existing actions that lack sprint assignment.
+
 **Sprint Workflow:**
 - Create sprints with clear goals and date boundaries.
 - Assign epics to sprints via linkedEpics.
@@ -15433,7 +15712,7 @@ var genericAgilePlugin = {
 **Sprints** (SP-xxx): Time-boxed iterations that group epics and work items with delivery dates. Sprints progress through planned \u2192 active \u2192 completed (or cancelled).
 **Meetings**: Meeting records with attendees, agendas, and notes.
 
-**Key workflow rule:** Epics must link to approved features \u2014 the system enforces this. The Product Owner defines and approves features, the Tech Lead breaks them into epics, the Delivery Manager plans sprints and tracks dates and progress. Work items are associated with sprints via \`sprint:SP-xxx\` tags.
+**Key workflow rule:** Epics must link to approved features \u2014 the system enforces this. The Product Owner defines and approves features, the Tech Lead breaks them into epics, the Delivery Manager plans sprints and tracks dates and progress. Work items are associated with sprints via \`sprint:SP-xxx\` tags. Actions support a \`dueDate\` field for schedule tracking \u2014 actions with a past due date are automatically flagged as overdue in GAR reports. Use the \`sprints\` parameter on create_action/update_action to assign actions to sprints.
 
 - **list_meetings** / **get_meeting**: Browse and read meeting records.
 - **create_meeting**: Record meetings with attendees, date, and agenda. The meeting date is required \u2014 extract it from the meeting content or ask the user if not found.
@@ -15479,7 +15758,7 @@ function createUseCaseTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool8(
       "get_use_case",
@@ -15506,7 +15785,7 @@ function createUseCaseTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool8(
       "create_use_case",
@@ -15604,7 +15883,7 @@ function createTechAssessmentTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool9(
       "get_tech_assessment",
@@ -15631,7 +15910,7 @@ function createTechAssessmentTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool9(
       "create_tech_assessment",
@@ -15765,7 +16044,7 @@ function createExtensionDesignTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool10(
       "get_extension_design",
@@ -15792,7 +16071,7 @@ function createExtensionDesignTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool10(
       "create_extension_design",
@@ -15944,7 +16223,7 @@ function createAemReportTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool11(
       "generate_tech_readiness",
@@ -15996,7 +16275,7 @@ function createAemReportTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool11(
       "generate_phase_status",
@@ -16051,7 +16330,7 @@ function createAemReportTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     )
   ];
 }
@@ -16083,7 +16362,7 @@ function createAemPhaseTools(store, marvinDir) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool12(
       "advance_phase",
@@ -16348,6 +16627,56 @@ function getPluginPromptFragment(plugin, personaId) {
   return plugin.promptFragments[personaId] ?? plugin.promptFragments["*"];
 }
 
+// src/templates/claude-md.ts
+function getDefaultClaudeMdContent(projectName) {
+  return `# Marvin \u2014 Project Instructions for "${projectName}"
+
+You are **Marvin**, an AI-powered product development assistant.
+You operate as one of three personas \u2014 stay in role and suggest switching when a question falls outside your scope.
+
+## Personas
+
+| Persona | Short | Focus |
+|---------|-------|-------|
+| Product Owner | po | Vision, backlog, requirements, features, acceptance criteria |
+| Delivery Manager | dm | Planning, risks, actions, timelines, sprints, status |
+| Tech Lead | tl | Architecture, trade-offs, technical decisions, code quality |
+
+## Proactive Governance
+
+When conversation implies a commitment, risk, or open question, **suggest creating the matching artifact**:
+- A decision was made \u2192 offer to create a **Decision (D-xxx)**
+- Someone committed to a task \u2192 offer an **Action (A-xxx)** with owner and due date
+- An unanswered question surfaced \u2192 offer a **Question (Q-xxx)**
+- A new capability is discussed \u2192 offer a **Feature (F-xxx)**
+- Implementation scope is agreed \u2192 offer an **Epic (E-xxx)** linked to a feature
+- Work is being time-boxed \u2192 offer a **Sprint (SP-xxx)**
+
+## Insights
+
+Proactively flag:
+- Overdue actions or unresolved questions
+- Decisions without rationale or linked features
+- Features without linked epics
+- Risks mentioned but not tracked
+- When a risk is resolved \u2192 remove the "risk" tag and add "risk-mitigated"
+
+## Tool Usage
+
+- **Search before creating** \u2014 avoid duplicate artifacts
+- **Reference IDs** (e.g. D-001, A-003) when discussing existing items
+- **Link artifacts** \u2014 epics to features, actions to decisions, etc.
+- Use \`search_documents\` to find related context before answering
+
+## Communication Style
+
+- Be concise and structured
+- State assumptions explicitly
+- Use bullet points and tables where they aid clarity
+- When uncertain, ask a clarifying question rather than guessing
+`;
+}
+
 // src/cli/commands/init.ts
 async function initCommand() {
   const cwd = process.cwd();
@@ -16404,11 +16733,17 @@ async function initCommand() {
     YAML3.stringify(config2),
     "utf-8"
   );
+  fs4.writeFileSync(
+    path4.join(marvinDir, "CLAUDE.md"),
+    getDefaultClaudeMdContent(projectName),
+    "utf-8"
+  );
   console.log(chalk.green(`
 Initialized Marvin project "${projectName}" in ${cwd}`));
   console.log(chalk.dim(`Methodology: ${plugin?.name ?? methodology}`));
   console.log(chalk.dim("\nCreated:"));
   console.log(chalk.dim("  .marvin/config.yaml"));
+  console.log(chalk.dim("  .marvin/CLAUDE.md"));
   console.log(chalk.dim("  .marvin/docs/decisions/"));
   console.log(chalk.dim("  .marvin/docs/actions/"));
   console.log(chalk.dim("  .marvin/docs/questions/"));
@@ -16517,6 +16852,8 @@ var deliveryManager = {
 
 ## How You Work
 - Review open actions (A-xxx) and follow up on overdue items
+- Ensure every action has a dueDate \u2014 use update_action to backfill existing ones
+- Assign actions to sprints when sprint planning is active, using the sprints parameter
 - Ensure decisions (D-xxx) are properly documented with rationale
 - Track questions (Q-xxx) and ensure they get answered
 - Monitor project health and flag risks early
@@ -16609,8 +16946,8 @@ function resolvePersonaId(input4) {
 }
 
 // src/agent/session.ts
-import * as fs9 from "fs";
-import * as path9 from "path";
+import * as fs10 from "fs";
+import * as path10 from "path";
 import * as readline from "readline";
 import chalk2 from "chalk";
 import ora from "ora";
@@ -16619,9 +16956,24 @@ import {
 } from "@anthropic-ai/claude-agent-sdk";
 
 // src/personas/prompt-builder.ts
-function buildSystemPrompt(persona, projectConfig, pluginPromptFragment, skillPromptFragment) {
+import * as fs5 from "fs";
+import * as path5 from "path";
+function buildSystemPrompt(persona, projectConfig, pluginPromptFragment, skillPromptFragment, marvinDir) {
   const parts = [];
   parts.push(persona.systemPrompt);
+  if (marvinDir) {
+    const claudeMdPath = path5.join(marvinDir, "CLAUDE.md");
+    try {
+      const content = fs5.readFileSync(claudeMdPath, "utf-8").trim();
+      if (content) {
+        parts.push(`
+## Project Instructions
+${content}
+`);
+      }
+    } catch {
+    }
+  }
   parts.push(`
 ## Project Context
 - **Project Name:** ${projectConfig.name}
@@ -16631,7 +16983,7 @@ function buildSystemPrompt(persona, projectConfig, pluginPromptFragment, skillPr
 ## Available Tools
 You have access to governance tools for managing project artifacts:
 - **Decisions** (D-xxx): List, get, create, and update decisions
-- **Actions** (A-xxx): List, get, create, and update action items
+- **Actions** (A-xxx): List, get, create, and update action items. Actions support \`dueDate\` for schedule tracking and \`sprints\` for sprint assignment.
 - **Questions** (Q-xxx): List, get, create, and update questions
 - **Features** (F-xxx): List, get, create, and update feature definitions
 - **Epics** (E-xxx): List, get, create, and update implementation epics (must link to approved features)
@@ -16668,8 +17020,8 @@ ${projectConfig.personas[persona.id].extraInstructions}
 }
 
 // src/storage/store.ts
-import * as fs5 from "fs";
-import * as path5 from "path";
+import * as fs6 from "fs";
+import * as path6 from "path";
 
 // src/storage/document.ts
 import matter from "gray-matter";
@@ -16707,7 +17059,7 @@ var DocumentStore = class {
   typeDirs;
   idPrefixes;
   constructor(marvinDir, registrations) {
-    this.docsDir = path5.join(marvinDir, "docs");
+    this.docsDir = path6.join(marvinDir, "docs");
     this.typeDirs = { ...CORE_TYPE_DIRS };
     this.idPrefixes = { ...CORE_ID_PREFIXES };
     for (const reg of registrations ?? []) {
@@ -16722,12 +17074,12 @@ var DocumentStore = class {
   buildIndex() {
     this.index.clear();
     for (const type of Object.keys(this.typeDirs)) {
-      const dir = path5.join(this.docsDir, this.typeDirs[type]);
-      if (!fs5.existsSync(dir)) continue;
-      const files = fs5.readdirSync(dir).filter((f) => f.endsWith(".md"));
+      const dir = path6.join(this.docsDir, this.typeDirs[type]);
+      if (!fs6.existsSync(dir)) continue;
+      const files = fs6.readdirSync(dir).filter((f) => f.endsWith(".md"));
       for (const file2 of files) {
-        const filePath = path5.join(dir, file2);
-        const raw = fs5.readFileSync(filePath, "utf-8");
+        const filePath = path6.join(dir, file2);
+        const raw = fs6.readFileSync(filePath, "utf-8");
         const doc = parseDocument(raw, filePath);
         if (doc.frontmatter.id) {
           if (this.index.has(doc.frontmatter.id)) {
@@ -16746,12 +17098,12 @@ var DocumentStore = class {
     for (const type of types) {
       const dirName = this.typeDirs[type];
       if (!dirName) continue;
-      const dir = path5.join(this.docsDir, dirName);
-      if (!fs5.existsSync(dir)) continue;
-      const files = fs5.readdirSync(dir).filter((f) => f.endsWith(".md"));
+      const dir = path6.join(this.docsDir, dirName);
+      if (!fs6.existsSync(dir)) continue;
+      const files = fs6.readdirSync(dir).filter((f) => f.endsWith(".md"));
       for (const file2 of files) {
-        const filePath = path5.join(dir, file2);
-        const raw = fs5.readFileSync(filePath, "utf-8");
+        const filePath = path6.join(dir, file2);
+        const raw = fs6.readFileSync(filePath, "utf-8");
         const doc = parseDocument(raw, filePath);
         if (query7?.status && doc.frontmatter.status !== query7.status) continue;
         if (query7?.owner && doc.frontmatter.owner !== query7.owner) continue;
@@ -16764,12 +17116,12 @@ var DocumentStore = class {
   }
   get(id) {
     for (const type of Object.keys(this.typeDirs)) {
-      const dir = path5.join(this.docsDir, this.typeDirs[type]);
-      if (!fs5.existsSync(dir)) continue;
-      const files = fs5.readdirSync(dir).filter((f) => f.endsWith(".md"));
+      const dir = path6.join(this.docsDir, this.typeDirs[type]);
+      if (!fs6.existsSync(dir)) continue;
+      const files = fs6.readdirSync(dir).filter((f) => f.endsWith(".md"));
       for (const file2 of files) {
-        const filePath = path5.join(dir, file2);
-        const raw = fs5.readFileSync(filePath, "utf-8");
+        const filePath = path6.join(dir, file2);
+        const raw = fs6.readFileSync(filePath, "utf-8");
         const doc = parseDocument(raw, filePath);
         if (doc.frontmatter.id === id) return doc;
       }
@@ -16783,8 +17135,8 @@ var DocumentStore = class {
     if (!dirName) {
       throw new Error(`Unknown document type: ${type}`);
     }
-    const dir = path5.join(this.docsDir, dirName);
-    fs5.mkdirSync(dir, { recursive: true });
+    const dir = path6.join(this.docsDir, dirName);
+    fs6.mkdirSync(dir, { recursive: true });
     const cleaned = Object.fromEntries(
       Object.entries(frontmatter).filter(([, v]) => v !== void 0)
     );
@@ -16798,13 +17150,13 @@ var DocumentStore = class {
       ...cleaned
     };
     const fileName = type === "meeting" ? `${cleaned.date?.slice(0, 10) ?? now.slice(0, 10)}-${slugify2(fullFrontmatter.title)}.md` : `${id}.md`;
-    const filePath = path5.join(dir, fileName);
+    const filePath = path6.join(dir, fileName);
     const doc = {
       frontmatter: fullFrontmatter,
       content,
       filePath
     };
-    fs5.writeFileSync(filePath, serializeDocument(doc), "utf-8");
+    fs6.writeFileSync(filePath, serializeDocument(doc), "utf-8");
     this.index.set(id, fullFrontmatter);
     return doc;
   }
@@ -16819,12 +17171,12 @@ var DocumentStore = class {
         `Document ${frontmatter.id} already exists. Resolve conflicts before importing.`
       );
     }
-    const dir = path5.join(this.docsDir, dirName);
-    fs5.mkdirSync(dir, { recursive: true });
+    const dir = path6.join(this.docsDir, dirName);
+    fs6.mkdirSync(dir, { recursive: true });
     const fileName = type === "meeting" ? `${frontmatter.date?.slice(0, 10) ?? frontmatter.created.slice(0, 10)}-${slugify2(frontmatter.title)}.md` : `${frontmatter.id}.md`;
-    const filePath = path5.join(dir, fileName);
+    const filePath = path6.join(dir, fileName);
     const doc = { frontmatter, content, filePath };
-    fs5.writeFileSync(filePath, serializeDocument(doc), "utf-8");
+    fs6.writeFileSync(filePath, serializeDocument(doc), "utf-8");
     this.index.set(frontmatter.id, frontmatter);
     return doc;
   }
@@ -16846,7 +17198,7 @@ var DocumentStore = class {
       content: content ?? existing.content,
       filePath: existing.filePath
     };
-    fs5.writeFileSync(existing.filePath, serializeDocument(doc), "utf-8");
+    fs6.writeFileSync(existing.filePath, serializeDocument(doc), "utf-8");
     this.index.set(id, updatedFrontmatter);
     return doc;
   }
@@ -16856,14 +17208,14 @@ var DocumentStore = class {
       throw new Error(`Unknown document type: ${type}`);
     }
     const dirName = this.typeDirs[type];
-    const dir = path5.join(this.docsDir, dirName);
-    if (!fs5.existsSync(dir)) return `${prefix}-001`;
+    const dir = path6.join(this.docsDir, dirName);
+    if (!fs6.existsSync(dir)) return `${prefix}-001`;
     const idPattern = new RegExp(`^${prefix}-(\\d+)$`);
-    const files = fs5.readdirSync(dir).filter((f) => f.endsWith(".md"));
+    const files = fs6.readdirSync(dir).filter((f) => f.endsWith(".md"));
     let maxNum = 0;
     for (const file2 of files) {
-      const filePath = path5.join(dir, file2);
-      const raw = fs5.readFileSync(filePath, "utf-8");
+      const filePath = path6.join(dir, file2);
+      const raw = fs6.readFileSync(filePath, "utf-8");
       const doc = parseDocument(raw, filePath);
       const match = doc.frontmatter.id?.match(idPattern);
       if (match) {
@@ -16876,12 +17228,12 @@ var DocumentStore = class {
   counts() {
     const result = {};
     for (const type of Object.keys(this.typeDirs)) {
-      const dir = path5.join(this.docsDir, this.typeDirs[type]);
-      if (!fs5.existsSync(dir)) {
+      const dir = path6.join(this.docsDir, this.typeDirs[type]);
+      if (!fs6.existsSync(dir)) {
         result[type] = 0;
         continue;
       }
-      result[type] = fs5.readdirSync(dir).filter((f) => f.endsWith(".md")).length;
+      result[type] = fs6.readdirSync(dir).filter((f) => f.endsWith(".md")).length;
     }
     return result;
   }
@@ -16891,13 +17243,13 @@ function slugify2(text) {
 }
 
 // src/storage/session-store.ts
-import * as fs6 from "fs";
-import * as path6 from "path";
+import * as fs7 from "fs";
+import * as path7 from "path";
 import * as YAML4 from "yaml";
 var SessionStore = class {
   filePath;
   constructor(marvinDir) {
-    this.filePath = path6.join(marvinDir, "sessions.yaml");
+    this.filePath = path7.join(marvinDir, "sessions.yaml");
   }
   list() {
     const entries = this.load();
@@ -16938,9 +17290,9 @@ var SessionStore = class {
     this.write(entries);
   }
   load() {
-    if (!fs6.existsSync(this.filePath)) return [];
+    if (!fs7.existsSync(this.filePath)) return [];
     try {
-      const raw = fs6.readFileSync(this.filePath, "utf-8");
+      const raw = fs7.readFileSync(this.filePath, "utf-8");
       const parsed = YAML4.parse(raw);
       if (!Array.isArray(parsed)) return [];
       return parsed;
@@ -16949,11 +17301,11 @@ var SessionStore = class {
     }
   }
   write(entries) {
-    const dir = path6.dirname(this.filePath);
-    if (!fs6.existsSync(dir)) {
-      fs6.mkdirSync(dir, { recursive: true });
+    const dir = path7.dirname(this.filePath);
+    if (!fs7.existsSync(dir)) {
+      fs7.mkdirSync(dir, { recursive: true });
     }
-    fs6.writeFileSync(this.filePath, YAML4.stringify(entries), "utf-8");
+    fs7.writeFileSync(this.filePath, YAML4.stringify(entries), "utf-8");
   }
 };
 
@@ -16982,7 +17334,7 @@ function createDecisionTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool13(
       "get_decision",
@@ -17009,7 +17361,7 @@ function createDecisionTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool13(
       "create_decision",
@@ -17050,7 +17402,8 @@ function createDecisionTools(store) {
         title: external_exports.string().optional().describe("New title"),
         status: external_exports.string().optional().describe("New status"),
         content: external_exports.string().optional().describe("New content"),
-        owner: external_exports.string().optional().describe("New owner")
+        owner: external_exports.string().optional().describe("New owner"),
+        tags: external_exports.array(external_exports.string()).optional().describe("Replace tags (e.g. remove 'risk', add 'risk-mitigated')")
       },
       async (args) => {
         const { id, content, ...updates } = args;
@@ -17070,6 +17423,19 @@ function createDecisionTools(store) {
 
 // src/agent/tools/actions.ts
 import { tool as tool14 } from "@anthropic-ai/claude-agent-sdk";
+function findMatchingSprints(store, dueDate) {
+  const sprints = store.list({ type: "sprint" });
+  return sprints.filter((s) => {
+    const start = s.frontmatter.startDate;
+    const end = s.frontmatter.endDate;
+    return start && end && dueDate >= start && dueDate <= end;
+  }).map((s) => ({
+    id: s.frontmatter.id,
+    title: s.frontmatter.title,
+    startDate: s.frontmatter.startDate,
+    endDate: s.frontmatter.endDate
+  }));
+}
 function createActionTools(store) {
   return [
     tool14(
@@ -17085,19 +17451,24 @@ function createActionTools(store) {
           status: args.status,
           owner: args.owner
         });
-        const summary = docs.map((d) => ({
-          id: d.frontmatter.id,
-          title: d.frontmatter.title,
-          status: d.frontmatter.status,
-          owner: d.frontmatter.owner,
-          priority: d.frontmatter.priority,
-          created: d.frontmatter.created
-        }));
+        const summary = docs.map((d) => {
+          const sprintIds = (d.frontmatter.tags ?? []).filter((t) => t.startsWith("sprint:")).map((t) => t.slice(7));
+          return {
+            id: d.frontmatter.id,
+            title: d.frontmatter.title,
+            status: d.frontmatter.status,
+            owner: d.frontmatter.owner,
+            priority: d.frontmatter.priority,
+            dueDate: d.frontmatter.dueDate,
+            sprints: sprintIds.length > 0 ? sprintIds : void 0,
+            created: d.frontmatter.created
+          };
+        });
         return {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool14(
       "get_action",
@@ -17124,7 +17495,7 @@ function createActionTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool14(
       "create_action",
@@ -17135,9 +17506,18 @@ function createActionTools(store) {
         status: external_exports.string().optional().describe("Status (default: 'open')"),
         owner: external_exports.string().optional().describe("Person responsible"),
         priority: external_exports.string().optional().describe("Priority (high, medium, low)"),
-        tags: external_exports.array(external_exports.string()).optional().describe("Tags for categorization")
+        tags: external_exports.array(external_exports.string()).optional().describe("Tags for categorization"),
+        dueDate: external_exports.string().optional().describe("Due date in ISO format (e.g. '2026-03-15')"),
+        sprints: external_exports.array(external_exports.string()).optional().describe("Sprint IDs to assign (e.g. ['SP-001']). Adds sprint:SP-xxx tags.")
       },
       async (args) => {
+        const tags = [...args.tags ?? []];
+        if (args.sprints) {
+          for (const sprintId of args.sprints) {
+            const tag = `sprint:${sprintId}`;
+            if (!tags.includes(tag)) tags.push(tag);
+          }
+        }
         const doc = store.create(
           "action",
           {
@@ -17145,17 +17525,21 @@ function createActionTools(store) {
             status: args.status,
             owner: args.owner,
             priority: args.priority,
-            tags: args.tags
+            tags: tags.length > 0 ? tags : void 0,
+            dueDate: args.dueDate
           },
           args.content
         );
+        const parts = [`Created action ${doc.frontmatter.id}: ${doc.frontmatter.title}`];
+        if (args.dueDate && (!args.sprints || args.sprints.length === 0)) {
+          const matching = findMatchingSprints(store, args.dueDate);
+          if (matching.length > 0) {
+            const suggestions = matching.map((s) => `${s.id} "${s.title}" (${s.startDate} \u2013 ${s.endDate})`).join(", ");
+            parts.push(`Suggested sprints for dueDate ${args.dueDate}: ${suggestions}. Use the sprints parameter or update_action to assign.`);
+          }
+        }
         return {
-          content: [
-            {
-              type: "text",
-              text: `Created action ${doc.frontmatter.id}: ${doc.frontmatter.title}`
-            }
-          ]
+          content: [{ type: "text", text: parts.join("\n") }]
         };
       }
     ),
@@ -17168,10 +17552,35 @@ function createActionTools(store) {
         status: external_exports.string().optional().describe("New status"),
         content: external_exports.string().optional().describe("New content"),
         owner: external_exports.string().optional().describe("New owner"),
-        priority: external_exports.string().optional().describe("New priority")
+        priority: external_exports.string().optional().describe("New priority"),
+        dueDate: external_exports.string().optional().describe("Due date in ISO format (e.g. '2026-03-15')"),
+        tags: external_exports.array(external_exports.string()).optional().describe("Replace all tags. When provided with sprints, sprint tags are merged into this array."),
+        sprints: external_exports.array(external_exports.string()).optional().describe("Sprint IDs to assign (replaces existing sprint tags). E.g. ['SP-001'].")
       },
       async (args) => {
-        const { id, content, ...updates } = args;
+        const { id, content, sprints, tags, ...updates } = args;
+        if (tags !== void 0) {
+          const merged = [...tags];
+          if (sprints) {
+            for (const s of sprints) {
+              const tag = `sprint:${s}`;
+              if (!merged.includes(tag)) merged.push(tag);
+            }
+          }
+          updates.tags = merged;
+        } else if (sprints !== void 0) {
+          const existing = store.get(id);
+          if (!existing) {
+            return {
+              content: [{ type: "text", text: `Action ${id} not found` }],
+              isError: true
+            };
+          }
+          const existingTags = existing.frontmatter.tags ?? [];
+          const nonSprintTags = existingTags.filter((t) => !t.startsWith("sprint:"));
+          const newSprintTags = sprints.map((s) => `sprint:${s}`);
+          updates.tags = [...nonSprintTags, ...newSprintTags];
+        }
         const doc = store.update(id, updates, content);
         return {
           content: [
@@ -17182,6 +17591,35 @@ function createActionTools(store) {
           ]
         };
       }
+    ),
+    tool14(
+      "suggest_sprints_for_action",
+      "Suggest sprints whose date range contains the given due date. Helps assign actions to the right sprint.",
+      {
+        dueDate: external_exports.string().describe("Due date in ISO format (e.g. '2026-03-15')")
+      },
+      async (args) => {
+        const matching = findMatchingSprints(store, args.dueDate);
+        if (matching.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No sprints found containing dueDate ${args.dueDate}.`
+              }
+            ]
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(matching, null, 2)
+            }
+          ]
+        };
+      },
+      { annotations: { readOnlyHint: true } }
     )
   ];
 }
@@ -17209,7 +17647,7 @@ function createQuestionTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool15(
       "get_question",
@@ -17236,7 +17674,7 @@ function createQuestionTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool15(
       "create_question",
@@ -17277,7 +17715,8 @@ function createQuestionTools(store) {
         title: external_exports.string().optional().describe("New title"),
         status: external_exports.string().optional().describe("New status (e.g. 'answered')"),
         content: external_exports.string().optional().describe("Updated content / answer"),
-        owner: external_exports.string().optional().describe("New owner")
+        owner: external_exports.string().optional().describe("New owner"),
+        tags: external_exports.array(external_exports.string()).optional().describe("Replace tags (e.g. remove 'risk', add 'risk-mitigated')")
       },
       async (args) => {
         const { id, content, ...updates } = args;
@@ -17329,7 +17768,7 @@ function createDocumentTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool16(
       "read_document",
@@ -17356,7 +17795,7 @@ function createDocumentTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool16(
       "project_summary",
@@ -17384,7 +17823,7 @@ function createDocumentTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     )
   ];
 }
@@ -17421,7 +17860,7 @@ function createSourceTools(manifest) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool17(
       "get_source_info",
@@ -17455,7 +17894,7 @@ function createSourceTools(manifest) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     )
   ];
 }
@@ -17486,7 +17925,7 @@ function createSessionTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool18(
       "get_session",
@@ -17504,7 +17943,7 @@ function createSessionTools(store) {
           content: [{ type: "text", text: JSON.stringify(session, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     )
   ];
 }
@@ -17584,6 +18023,46 @@ function getBoardData(store, type) {
   }));
   return { columns, type, types };
 }
+function getDiagramData(store) {
+  const allDocs = store.list();
+  const sprints = [];
+  const epics = [];
+  const features = [];
+  const statusCounts = {};
+  for (const doc of allDocs) {
+    const fm = doc.frontmatter;
+    const status = fm.status.toLowerCase();
+    statusCounts[status] = (statusCounts[status] ?? 0) + 1;
+    switch (fm.type) {
+      case "sprint":
+        sprints.push({
+          id: fm.id,
+          title: fm.title,
+          status: fm.status,
+          startDate: fm.startDate,
+          endDate: fm.endDate,
+          linkedEpics: fm.linkedEpics ?? []
+        });
+        break;
+      case "epic":
+        epics.push({
+          id: fm.id,
+          title: fm.title,
+          status: fm.status,
+          linkedFeature: fm.linkedFeature
+        });
+        break;
+      case "feature":
+        features.push({
+          id: fm.id,
+          title: fm.title,
+          status: fm.status
+        });
+        break;
+    }
+  }
+  return { sprints, epics, features, statusCounts };
+}
 
 // src/web/templates/layout.ts
 function escapeHtml(str) {
@@ -17614,16 +18093,43 @@ function renderMarkdown(md) {
   const out = [];
   let inList = false;
   let listTag = "ul";
-  for (const raw of lines) {
-    const line = raw;
+  let inTable = false;
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
     if (inList && !/^\s*[-*]\s/.test(line) && !/^\s*\d+\.\s/.test(line) && line.trim() !== "") {
       out.push(`</${listTag}>`);
       inList = false;
     }
+    if (inTable && !/^\s*\|/.test(line)) {
+      out.push("</tbody></table></div>");
+      inTable = false;
+    }
+    if (/^(-{3,}|\*{3,}|_{3,})\s*$/.test(line.trim())) {
+      i++;
+      out.push("<hr>");
+      continue;
+    }
+    if (!inTable && /^\s*\|/.test(line) && i + 1 < lines.length && /^\s*\|[\s:|-]+\|\s*$/.test(lines[i + 1])) {
+      const headers = parseTableRow(line);
+      out.push('<div class="table-wrap"><table><thead><tr>');
+      out.push(headers.map((h) => `<th>${inline(h)}</th>`).join(""));
+      out.push("</tr></thead><tbody>");
+      inTable = true;
+      i += 2;
+      continue;
+    }
+    if (inTable && /^\s*\|/.test(line)) {
+      const cells = parseTableRow(line);
+      out.push("<tr>" + cells.map((c) => `<td>${inline(c)}</td>`).join("") + "</tr>");
+      i++;
+      continue;
+    }
     const headingMatch = line.match(/^(#{1,3})\s+(.+)$/);
     if (headingMatch) {
       const level = headingMatch[1].length;
       out.push(`<h${level}>${inline(headingMatch[2])}</h${level}>`);
+      i++;
       continue;
     }
     const ulMatch = line.match(/^\s*[-*]\s+(.+)$/);
@@ -17635,6 +18141,7 @@ function renderMarkdown(md) {
         listTag = "ul";
       }
       out.push(`<li>${inline(ulMatch[1])}</li>`);
+      i++;
       continue;
     }
     const olMatch = line.match(/^\s*\d+\.\s+(.+)$/);
@@ -17646,6 +18153,7 @@ function renderMarkdown(md) {
         listTag = "ol";
       }
       out.push(`<li>${inline(olMatch[1])}</li>`);
+      i++;
       continue;
     }
     if (line.trim() === "") {
@@ -17653,13 +18161,19 @@ function renderMarkdown(md) {
         out.push(`</${listTag}>`);
         inList = false;
       }
+      i++;
       continue;
     }
     out.push(`<p>${inline(line)}</p>`);
+    i++;
   }
   if (inList) out.push(`</${listTag}>`);
+  if (inTable) out.push("</tbody></table></div>");
   return out.join("\n");
 }
+function parseTableRow(line) {
+  return line.replace(/^\s*\|/, "").replace(/\|\s*$/, "").split("|").map((cell) => cell.trim());
+}
 function inline(text) {
   let s = escapeHtml(text);
   s = s.replace(/`([^`]+)`/g, "<code>$1</code>");
@@ -17673,7 +18187,8 @@ function layout(opts, body) {
   const topItems = [
     { href: "/", label: "Overview" },
     { href: "/board", label: "Board" },
-    { href: "/gar", label: "GAR Report" }
+    { href: "/gar", label: "GAR Report" },
+    { href: "/health", label: "Health" }
   ];
   const isActive = (href) => opts.activePath === href || href !== "/" && opts.activePath.startsWith(href) ? " active" : "";
   const groupsHtml = opts.navGroups.map((group) => {
@@ -17708,9 +18223,15 @@ function layout(opts, body) {
       </nav>
     </aside>
     <main class="main">
+      <button class="expand-toggle" onclick="document.querySelector('.main').classList.toggle('expanded')" title="Toggle wide view">
+        <svg class="icon-expand" viewBox="0 0 16 16" width="16" height="16" fill="currentColor"><path d="M1 1h5v1.5H3.56l3.72 3.72-1.06 1.06L2.5 3.56V6H1V1zm14 14h-5v-1.5h2.44l-3.72-3.72 1.06-1.06 3.72 3.72V10H15v5z"/></svg>
+        <svg class="icon-collapse" viewBox="0 0 16 16" width="16" height="16" fill="currentColor"><path d="M6 7H1V5.5h2.44L0.22 2.28l1.06-1.06L4.5 4.44V2H6v5zm4-1h5v1.5h-2.44l3.22 3.22-1.06 1.06L11.5 8.56V11H10V6z"/></svg>
+      </button>
       ${body}
     </main>
   </div>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+  <script>mermaid.initialize({ startOnLoad: true, theme: 'dark' });</script>
 </body>
 </html>`;
 }
@@ -17825,7 +18346,33 @@ a:hover { text-decoration: underline; }
   flex: 1;
   padding: 2rem 2.5rem;
   max-width: 1200px;
+  position: relative;
+  transition: max-width 0.2s ease;
+}
+.main.expanded {
+  max-width: none;
+}
+.expand-toggle {
+  position: absolute;
+  top: 1rem;
+  right: 1rem;
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  color: var(--text-dim);
+  cursor: pointer;
+  padding: 0.4rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: color 0.15s, border-color 0.15s;
 }
+.expand-toggle:hover {
+  color: var(--text);
+  border-color: var(--text-dim);
+}
+.main.expanded .icon-expand { display: none; }
+.main:not(.expanded) .icon-collapse { display: none; }
 
 /* Page header */
 .page-header {
@@ -17854,12 +18401,26 @@ a:hover { text-decoration: underline; }
 .breadcrumb a:hover { color: var(--accent); }
 .breadcrumb .sep { margin: 0 0.4rem; }
 
+/* Card groups */
+.card-group {
+  margin-bottom: 1.5rem;
+}
+
+.card-group-label {
+  font-size: 0.7rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-dim);
+  font-weight: 600;
+  margin-bottom: 0.5rem;
+}
+
 /* Cards grid */
 .cards {
   display: grid;
   grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
   gap: 1rem;
-  margin-bottom: 2rem;
+  margin-bottom: 0.5rem;
 }
 
 .card {
@@ -18140,6 +18701,14 @@ tr:hover td {
   font-family: var(--mono);
   font-size: 0.85em;
 }
+.detail-content hr {
+  border: none;
+  border-top: 1px solid var(--border);
+  margin: 1.25rem 0;
+}
+.detail-content .table-wrap {
+  margin: 0.75rem 0;
+}
 
 /* Filters */
 .filters {
@@ -18184,21 +18753,206 @@ tr:hover td {
 .priority-high { color: var(--red); }
 .priority-medium { color: var(--amber); }
 .priority-low { color: var(--green); }
+
+/* Health */
+.health-section-title {
+  font-size: 1.1rem;
+  font-weight: 600;
+  margin: 2rem 0 1rem;
+  color: var(--text);
+}
+
+/* Mermaid diagrams */
+.mermaid-container {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 1.5rem;
+  margin: 1rem 0;
+  overflow-x: auto;
+}
+
+.mermaid-container .mermaid {
+  display: flex;
+  justify-content: center;
+}
+
+.mermaid-empty {
+  text-align: center;
+  color: var(--text-dim);
+  font-size: 0.875rem;
+}
+
+.mermaid-row {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
+  gap: 1rem;
+}
+
+.mermaid-row .mermaid-container {
+  margin: 0;
+}
 `;
 }
 
+// src/web/templates/mermaid.ts
+function sanitize(text, maxLen = 40) {
+  const cleaned = text.replace(/["'`]/g, "").replace(/[\r\n]+/g, " ");
+  return cleaned.length > maxLen ? cleaned.slice(0, maxLen - 1) + "\u2026" : cleaned;
+}
+function mermaidBlock(definition) {
+  return `<div class="mermaid-container"><pre class="mermaid">
+${definition}
+</pre></div>`;
+}
+function placeholder(message) {
+  return `<div class="mermaid-container mermaid-empty"><p>${message}</p></div>`;
+}
+function buildTimelineGantt(data) {
+  const sprintsWithDates = data.sprints.filter((s) => s.startDate && s.endDate);
+  if (sprintsWithDates.length === 0) {
+    return placeholder("No timeline data available \u2014 sprints need start and end dates.");
+  }
+  const epicMap = new Map(data.epics.map((e) => [e.id, e]));
+  const lines = ["gantt", "  title Project Timeline", "  dateFormat YYYY-MM-DD"];
+  for (const sprint of sprintsWithDates) {
+    lines.push(`  section ${sanitize(sprint.id + " " + sprint.title, 50)}`);
+    const linked = sprint.linkedEpics.map((eid) => epicMap.get(eid)).filter(Boolean);
+    if (linked.length === 0) {
+      lines.push(`    ${sanitize(sprint.title)} :${sprint.startDate}, ${sprint.endDate}`);
+    } else {
+      for (const epic of linked) {
+        const tag = epic.status === "in-progress" ? "active, " : epic.status === "done" ? "done, " : "";
+        lines.push(`    ${sanitize(epic.id + " " + epic.title)} :${tag}${sprint.startDate}, ${sprint.endDate}`);
+      }
+    }
+  }
+  return mermaidBlock(lines.join("\n"));
+}
+function buildArtifactFlowchart(data) {
+  if (data.features.length === 0 && data.epics.length === 0) {
+    return placeholder("No artifact relationships found \u2014 create features and epics to see the hierarchy.");
+  }
+  const lines = ["graph TD"];
+  lines.push("  classDef done fill:#065f46,stroke:#34d399,color:#d1fae5");
+  lines.push("  classDef inprogress fill:#78350f,stroke:#fbbf24,color:#fef3c7");
+  lines.push("  classDef blocked fill:#7f1d1d,stroke:#f87171,color:#fee2e2");
+  lines.push("  classDef default fill:#1e293b,stroke:#475569,color:#e2e8f0");
+  const nodeIds = /* @__PURE__ */ new Set();
+  for (const epic of data.epics) {
+    if (epic.linkedFeature) {
+      const feature = data.features.find((f) => f.id === epic.linkedFeature);
+      if (feature) {
+        const fNode = feature.id.replace(/-/g, "_");
+        const eNode = epic.id.replace(/-/g, "_");
+        if (!nodeIds.has(fNode)) {
+          lines.push(`  ${fNode}["${sanitize(feature.id + " " + feature.title)}"]`);
+          nodeIds.add(fNode);
+        }
+        if (!nodeIds.has(eNode)) {
+          lines.push(`  ${eNode}["${sanitize(epic.id + " " + epic.title)}"]`);
+          nodeIds.add(eNode);
+        }
+        lines.push(`  ${fNode} --> ${eNode}`);
+      }
+    }
+  }
+  for (const sprint of data.sprints) {
+    const sNode = sprint.id.replace(/-/g, "_");
+    for (const epicId of sprint.linkedEpics) {
+      const epic = data.epics.find((e) => e.id === epicId);
+      if (epic) {
+        const eNode = epic.id.replace(/-/g, "_");
+        if (!nodeIds.has(eNode)) {
+          lines.push(`  ${eNode}["${sanitize(epic.id + " " + epic.title)}"]`);
+          nodeIds.add(eNode);
+        }
+        if (!nodeIds.has(sNode)) {
+          lines.push(`  ${sNode}["${sanitize(sprint.id + " " + sprint.title)}"]`);
+          nodeIds.add(sNode);
+        }
+        lines.push(`  ${eNode} --> ${sNode}`);
+      }
+    }
+  }
+  if (nodeIds.size === 0) {
+    return placeholder("No artifact relationships found \u2014 link epics to features and sprints.");
+  }
+  const allItems = [
+    ...data.features.map((f) => ({ id: f.id, status: f.status })),
+    ...data.epics.map((e) => ({ id: e.id, status: e.status })),
+    ...data.sprints.map((s) => ({ id: s.id, status: s.status }))
+  ];
+  for (const item of allItems) {
+    const node = item.id.replace(/-/g, "_");
+    if (!nodeIds.has(node)) continue;
+    const cls = item.status === "done" || item.status === "completed" ? "done" : item.status === "in-progress" || item.status === "active" ? "inprogress" : item.status === "blocked" ? "blocked" : null;
+    if (cls) {
+      lines.push(`  class ${node} ${cls}`);
+    }
+  }
+  return mermaidBlock(lines.join("\n"));
+}
+function buildStatusPie(title, counts) {
+  const entries = Object.entries(counts).filter(([, v]) => v > 0);
+  if (entries.length === 0) {
+    return placeholder(`No data for ${title}.`);
+  }
+  const lines = [`pie title ${sanitize(title, 60)}`];
+  for (const [label, count] of entries) {
+    lines.push(`  "${sanitize(label, 30)}" : ${count}`);
+  }
+  return mermaidBlock(lines.join("\n"));
+}
+function buildHealthGauge(categories) {
+  const valid = categories.filter((c) => c.total > 0);
+  if (valid.length === 0) {
+    return placeholder("No completeness data available.");
+  }
+  const pies = valid.map((cat) => {
+    const incomplete = cat.total - cat.complete;
+    const lines = [
+      `pie title ${sanitize(cat.name, 30)}`,
+      `  "Complete" : ${cat.complete}`,
+      `  "Incomplete" : ${incomplete}`
+    ];
+    return mermaidBlock(lines.join("\n"));
+  });
+  return `<div class="mermaid-row">${pies.join("\n")}</div>`;
+}
+
 // src/web/templates/pages/overview.ts
-function overviewPage(data) {
-  const cards = data.types.map(
-    (t) => `
+function renderCard(t) {
+  return `
       <div class="card">
         <a href="/docs/${t.type}">
           <div class="card-label">${escapeHtml(typeLabel(t.type))}s</div>
           <div class="card-value">${t.total}</div>
           ${t.open > 0 ? `<div class="card-sub">${t.open} open</div>` : `<div class="card-sub">none open</div>`}
         </a>
-      </div>`
-  ).join("\n");
+      </div>`;
+}
+function overviewPage(data, diagrams, navGroups) {
+  const typeMap = new Map(data.types.map((t) => [t.type, t]));
+  const placed = /* @__PURE__ */ new Set();
+  const groupSections = navGroups.map((group) => {
+    const groupCards = group.types.filter((type) => typeMap.has(type)).map((type) => {
+      placed.add(type);
+      return renderCard(typeMap.get(type));
+    });
+    if (groupCards.length === 0) return "";
+    return `
+      <div class="card-group">
+        <div class="card-group-label">${escapeHtml(group.label)}</div>
+        <div class="cards">${groupCards.join("\n")}</div>
+      </div>`;
+  }).filter(Boolean).join("\n");
+  const ungrouped = data.types.filter((t) => !placed.has(t.type));
+  const ungroupedSection = ungrouped.length > 0 ? `
+      <div class="card-group">
+        <div class="card-group-label">Other</div>
+        <div class="cards">${ungrouped.map(renderCard).join("\n")}</div>
+      </div>` : "";
   const rows = data.recent.map(
     (doc) => `
         <tr>
@@ -18214,9 +18968,14 @@ function overviewPage(data) {
       <h2>Project Overview</h2>
     </div>
 
-    <div class="cards">
-      ${cards}
-    </div>
+    ${groupSections}
+    ${ungroupedSection}
+
+    <div class="section-title">Project Timeline</div>
+    ${buildTimelineGantt(diagrams)}
+
+    <div class="section-title">Artifact Relationships</div>
+    ${buildArtifactFlowchart(diagrams)}
 
     <div class="section-title">Recent Activity</div>
     ${data.recent.length > 0 ? `
@@ -18383,6 +19142,76 @@ function garPage(report) {
     <div class="gar-areas">
       ${areaCards}
     </div>
+
+    <div class="section-title">Status Distribution</div>
+    ${buildStatusPie("Action Status", {
+    Open: report.metrics.scope.open,
+    Done: report.metrics.scope.done,
+    "In Progress": Math.max(0, report.metrics.scope.total - report.metrics.scope.open - report.metrics.scope.done)
+  })}
+  `;
+}
+
+// src/web/templates/pages/health.ts
+function healthPage(report, metrics) {
+  const dotClass = `dot-${report.overall}`;
+  function renderSection(title, categories) {
+    const cards = categories.map(
+      (cat) => `
+        <div class="gar-area">
+          <div class="area-header">
+            <div class="area-dot dot-${cat.status}"></div>
+            <div class="area-name">${escapeHtml(cat.name)}</div>
+          </div>
+          <div class="area-summary">${escapeHtml(cat.summary)}</div>
+          ${cat.items.length > 0 ? `<ul>${cat.items.map((item) => `<li><span class="ref-id">${escapeHtml(item.id)}</span>${escapeHtml(item.detail)}</li>`).join("")}</ul>` : ""}
+        </div>`
+    ).join("\n");
+    return `
+      <div class="health-section-title">${escapeHtml(title)}</div>
+      <div class="gar-areas">${cards}</div>
+    `;
+  }
+  return `
+    <div class="page-header">
+      <h2>Governance Health Check</h2>
+      <div class="subtitle">Generated ${escapeHtml(report.generatedAt)}</div>
+    </div>
+
+    <div class="gar-overall">
+      <div class="dot ${dotClass}"></div>
+      <div class="label">Overall: ${escapeHtml(report.overall)}</div>
+    </div>
+
+    ${renderSection("Completeness", report.completeness)}
+
+    <div class="health-section-title">Completeness Overview</div>
+    ${buildHealthGauge(
+    metrics ? Object.entries(metrics.completeness).map(([name, cat]) => ({
+      name: name.replace(/\b\w/g, (c) => c.toUpperCase()),
+      complete: cat.complete,
+      total: cat.total
+    })) : report.completeness.map((c) => {
+      const match = c.summary.match(/(\d+)\s*\/\s*(\d+)/);
+      return {
+        name: c.name,
+        complete: match ? parseInt(match[1], 10) : 0,
+        total: match ? parseInt(match[2], 10) : 0
+      };
+    })
+  )}
+
+    ${renderSection("Process", report.process)}
+
+    <div class="health-section-title">Process Summary</div>
+    ${metrics ? buildStatusPie("Process Health", {
+    Stale: metrics.process.stale.length,
+    "Aging Actions": metrics.process.agingActions.length,
+    Healthy: Math.max(
+      0,
+      (metrics.completeness ? Object.values(metrics.completeness).reduce((sum, c) => sum + c.total, 0) : 0) - metrics.process.stale.length - metrics.process.agingActions.length
+    )
+  }) : ""}
   `;
 }
 
@@ -18449,7 +19278,8 @@ function handleRequest(req, res, store, projectName, navGroups) {
     }
     if (pathname === "/") {
       const data = getOverviewData(store);
-      const body = overviewPage(data);
+      const diagrams = getDiagramData(store);
+      const body = overviewPage(data, diagrams, navGroups);
       respond(res, layout({ title: "Overview", activePath: "/", projectName, navGroups }, body));
       return;
     }
@@ -18459,6 +19289,13 @@ function handleRequest(req, res, store, projectName, navGroups) {
       respond(res, layout({ title: "GAR Report", activePath: "/gar", projectName, navGroups }, body));
       return;
     }
+    if (pathname === "/health") {
+      const healthMetrics = collectHealthMetrics(store);
+      const report = evaluateHealth(projectName, healthMetrics);
+      const body = healthPage(report, healthMetrics);
+      respond(res, layout({ title: "Health Check", activePath: "/health", projectName, navGroups }, body));
+      return;
+    }
     const boardMatch = pathname.match(/^\/board(?:\/([^/]+))?$/);
     if (boardMatch) {
       const type = boardMatch[1];
@@ -18519,8 +19356,8 @@ import * as http from "http";
 import { exec } from "child_process";
 
 // src/skills/registry.ts
-import * as fs7 from "fs";
-import * as path7 from "path";
+import * as fs8 from "fs";
+import * as path8 from "path";
 import { fileURLToPath } from "url";
 import * as YAML5 from "yaml";
 import matter2 from "gray-matter";
@@ -18573,8 +19410,8 @@ var JiraClient = class {
     this.baseUrl = `https://${config2.host}/rest/api/2`;
     this.authHeader = "Basic " + Buffer.from(`${config2.email}:${config2.apiToken}`).toString("base64");
   }
-  async request(path18, method = "GET", body) {
-    const url2 = `${this.baseUrl}${path18}`;
+  async request(path20, method = "GET", body) {
+    const url2 = `${this.baseUrl}${path20}`;
     const headers = {
       Authorization: this.authHeader,
       "Content-Type": "application/json",
@@ -18588,7 +19425,7 @@ var JiraClient = class {
     if (!response.ok) {
       const text = await response.text().catch(() => "");
       throw new Error(
-        `Jira API error ${response.status} ${method} ${path18}: ${text}`
+        `Jira API error ${response.status} ${method} ${path20}: ${text}`
       );
     }
     if (response.status === 204) return void 0;
@@ -18698,7 +19535,7 @@ function createJiraTools(store) {
           content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool19(
       "get_jira_issue",
@@ -18730,7 +19567,7 @@ function createJiraTools(store) {
           ]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     // --- Jira → Local tools ---
     tool19(
@@ -19068,13 +19905,13 @@ var GOVERNANCE_TOOL_NAMES = [
 ];
 function getBuiltinSkillsDir() {
   const thisFile = fileURLToPath(import.meta.url);
-  return path7.join(path7.dirname(thisFile), "builtin");
+  return path8.join(path8.dirname(thisFile), "builtin");
 }
 function loadSkillFromDirectory(dirPath) {
-  const skillMdPath = path7.join(dirPath, "SKILL.md");
-  if (!fs7.existsSync(skillMdPath)) return void 0;
+  const skillMdPath = path8.join(dirPath, "SKILL.md");
+  if (!fs8.existsSync(skillMdPath)) return void 0;
   try {
-    const raw = fs7.readFileSync(skillMdPath, "utf-8");
+    const raw = fs8.readFileSync(skillMdPath, "utf-8");
     const { data, content } = matter2(raw);
     if (!data.name || !data.description) return void 0;
     const metadata = data.metadata ?? {};
@@ -19085,13 +19922,13 @@ function loadSkillFromDirectory(dirPath) {
     if (wildcardPrompt) {
       promptFragments["*"] = wildcardPrompt;
     }
-    const personasDir = path7.join(dirPath, "personas");
-    if (fs7.existsSync(personasDir)) {
+    const personasDir = path8.join(dirPath, "personas");
+    if (fs8.existsSync(personasDir)) {
       try {
-        for (const file2 of fs7.readdirSync(personasDir)) {
+        for (const file2 of fs8.readdirSync(personasDir)) {
           if (!file2.endsWith(".md")) continue;
           const personaId = file2.replace(/\.md$/, "");
-          const personaPrompt = fs7.readFileSync(path7.join(personasDir, file2), "utf-8").trim();
+          const personaPrompt = fs8.readFileSync(path8.join(personasDir, file2), "utf-8").trim();
           if (personaPrompt) {
             promptFragments[personaId] = personaPrompt;
           }
@@ -19100,10 +19937,10 @@ function loadSkillFromDirectory(dirPath) {
       }
     }
     let actions;
-    const actionsPath = path7.join(dirPath, "actions.yaml");
-    if (fs7.existsSync(actionsPath)) {
+    const actionsPath = path8.join(dirPath, "actions.yaml");
+    if (fs8.existsSync(actionsPath)) {
       try {
-        const actionsRaw = fs7.readFileSync(actionsPath, "utf-8");
+        const actionsRaw = fs8.readFileSync(actionsPath, "utf-8");
         actions = YAML5.parse(actionsRaw);
       } catch {
       }
@@ -19130,10 +19967,10 @@ function loadAllSkills(marvinDir) {
   }
   try {
     const builtinDir = getBuiltinSkillsDir();
-    if (fs7.existsSync(builtinDir)) {
-      for (const entry of fs7.readdirSync(builtinDir)) {
-        const entryPath = path7.join(builtinDir, entry);
-        if (!fs7.statSync(entryPath).isDirectory()) continue;
+    if (fs8.existsSync(builtinDir)) {
+      for (const entry of fs8.readdirSync(builtinDir)) {
+        const entryPath = path8.join(builtinDir, entry);
+        if (!fs8.statSync(entryPath).isDirectory()) continue;
         if (skills.has(entry)) continue;
         const skill = loadSkillFromDirectory(entryPath);
         if (skill) skills.set(skill.id, skill);
@@ -19142,18 +19979,18 @@ function loadAllSkills(marvinDir) {
   } catch {
   }
   if (marvinDir) {
-    const skillsDir = path7.join(marvinDir, "skills");
-    if (fs7.existsSync(skillsDir)) {
+    const skillsDir = path8.join(marvinDir, "skills");
+    if (fs8.existsSync(skillsDir)) {
       let entries;
       try {
-        entries = fs7.readdirSync(skillsDir);
+        entries = fs8.readdirSync(skillsDir);
       } catch {
         entries = [];
       }
       for (const entry of entries) {
-        const entryPath = path7.join(skillsDir, entry);
+        const entryPath = path8.join(skillsDir, entry);
         try {
-          if (fs7.statSync(entryPath).isDirectory()) {
+          if (fs8.statSync(entryPath).isDirectory()) {
             const skill = loadSkillFromDirectory(entryPath);
             if (skill) skills.set(skill.id, skill);
             continue;
@@ -19163,7 +20000,7 @@ function loadAllSkills(marvinDir) {
         }
         if (!entry.endsWith(".yaml") && !entry.endsWith(".yml")) continue;
         try {
-          const raw = fs7.readFileSync(entryPath, "utf-8");
+          const raw = fs8.readFileSync(entryPath, "utf-8");
           const parsed = YAML5.parse(raw);
           if (!parsed?.id || !parsed?.name || !parsed?.version) continue;
           const skill = {
@@ -19268,12 +20105,12 @@ function getSkillAgentDefinitions(skillIds, allSkills) {
   return agents;
 }
 function migrateYamlToSkillMd(yamlPath, outputDir) {
-  const raw = fs7.readFileSync(yamlPath, "utf-8");
+  const raw = fs8.readFileSync(yamlPath, "utf-8");
   const parsed = YAML5.parse(raw);
   if (!parsed?.id || !parsed?.name) {
     throw new Error(`Invalid skill YAML: missing required fields (id, name)`);
   }
-  fs7.mkdirSync(outputDir, { recursive: true });
+  fs8.mkdirSync(outputDir, { recursive: true });
   const frontmatter = {
     name: parsed.id,
     description: parsed.description ?? ""
@@ -19287,15 +20124,15 @@ function migrateYamlToSkillMd(yamlPath, outputDir) {
   const skillMd = matter2.stringify(wildcardPrompt ? `
 ${wildcardPrompt}
 ` : "\n", frontmatter);
-  fs7.writeFileSync(path7.join(outputDir, "SKILL.md"), skillMd, "utf-8");
+  fs8.writeFileSync(path8.join(outputDir, "SKILL.md"), skillMd, "utf-8");
   if (promptFragments) {
     const personaKeys = Object.keys(promptFragments).filter((k) => k !== "*");
     if (personaKeys.length > 0) {
-      const personasDir = path7.join(outputDir, "personas");
-      fs7.mkdirSync(personasDir, { recursive: true });
+      const personasDir = path8.join(outputDir, "personas");
+      fs8.mkdirSync(personasDir, { recursive: true });
       for (const personaId of personaKeys) {
-        fs7.writeFileSync(
-          path7.join(personasDir, `${personaId}.md`),
+        fs8.writeFileSync(
+          path8.join(personasDir, `${personaId}.md`),
           `${promptFragments[personaId]}
 `,
           "utf-8"
@@ -19305,8 +20142,8 @@ ${wildcardPrompt}
   }
   const actions = parsed.actions;
   if (actions && actions.length > 0) {
-    fs7.writeFileSync(
-      path7.join(outputDir, "actions.yaml"),
+    fs8.writeFileSync(
+      path8.join(outputDir, "actions.yaml"),
       YAML5.stringify(actions),
       "utf-8"
     );
@@ -19461,7 +20298,7 @@ function createWebTools(store, projectName, navGroups) {
           content: [{ type: "text", text: JSON.stringify(urls, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool20(
       "get_dashboard_overview",
@@ -19483,7 +20320,7 @@ function createWebTools(store, projectName, navGroups) {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool20(
       "get_dashboard_gar",
@@ -19495,7 +20332,7 @@ function createWebTools(store, projectName, navGroups) {
           content: [{ type: "text", text: JSON.stringify(report, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     ),
     tool20(
       "get_dashboard_board",
@@ -19523,7 +20360,7 @@ function createWebTools(store, projectName, navGroups) {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     )
   ];
 }
@@ -19580,8 +20417,8 @@ function slugify3(text) {
 }
 
 // src/sources/manifest.ts
-import * as fs8 from "fs";
-import * as path8 from "path";
+import * as fs9 from "fs";
+import * as path9 from "path";
 import * as crypto from "crypto";
 import * as YAML6 from "yaml";
 var MANIFEST_FILE = ".manifest.yaml";
@@ -19594,37 +20431,37 @@ var SourceManifestManager = class {
   manifestPath;
   sourcesDir;
   constructor(marvinDir) {
-    this.sourcesDir = path8.join(marvinDir, "sources");
-    this.manifestPath = path8.join(this.sourcesDir, MANIFEST_FILE);
+    this.sourcesDir = path9.join(marvinDir, "sources");
+    this.manifestPath = path9.join(this.sourcesDir, MANIFEST_FILE);
     this.manifest = this.load();
   }
   load() {
-    if (!fs8.existsSync(this.manifestPath)) {
+    if (!fs9.existsSync(this.manifestPath)) {
       return emptyManifest();
     }
-    const raw = fs8.readFileSync(this.manifestPath, "utf-8");
+    const raw = fs9.readFileSync(this.manifestPath, "utf-8");
     const parsed = YAML6.parse(raw);
     return parsed ?? emptyManifest();
   }
   save() {
-    fs8.mkdirSync(this.sourcesDir, { recursive: true });
-    fs8.writeFileSync(this.manifestPath, YAML6.stringify(this.manifest), "utf-8");
+    fs9.mkdirSync(this.sourcesDir, { recursive: true });
+    fs9.writeFileSync(this.manifestPath, YAML6.stringify(this.manifest), "utf-8");
   }
   scan() {
     const added = [];
     const changed = [];
     const removed = [];
-    if (!fs8.existsSync(this.sourcesDir)) {
+    if (!fs9.existsSync(this.sourcesDir)) {
       return { added, changed, removed };
     }
     const onDisk = new Set(
-      fs8.readdirSync(this.sourcesDir).filter((f) => {
-        const ext = path8.extname(f).toLowerCase();
+      fs9.readdirSync(this.sourcesDir).filter((f) => {
+        const ext = path9.extname(f).toLowerCase();
         return SOURCE_EXTENSIONS.includes(ext);
       })
     );
     for (const fileName of onDisk) {
-      const filePath = path8.join(this.sourcesDir, fileName);
+      const filePath = path9.join(this.sourcesDir, fileName);
       const hash2 = this.hashFile(filePath);
       const existing = this.manifest.files[fileName];
       if (!existing) {
@@ -19687,7 +20524,7 @@ var SourceManifestManager = class {
     this.save();
   }
   hashFile(filePath) {
-    const content = fs8.readFileSync(filePath);
+    const content = fs9.readFileSync(filePath);
     return crypto.createHash("sha256").update(content).digest("hex");
   }
 };
@@ -19702,8 +20539,8 @@ async function startSession(options) {
   const skillRegistrations = collectSkillRegistrations(skillIds, allSkills);
   const store = new DocumentStore(marvinDir, [...pluginRegistrations, ...skillRegistrations]);
   const sessionStore = new SessionStore(marvinDir);
-  const sourcesDir = path9.join(marvinDir, "sources");
-  const hasSourcesDir = fs9.existsSync(sourcesDir);
+  const sourcesDir = path10.join(marvinDir, "sources");
+  const hasSourcesDir = fs10.existsSync(sourcesDir);
   const manifest = hasSourcesDir ? new SourceManifestManager(marvinDir) : void 0;
   const pluginTools = plugin ? getPluginTools(plugin, store, marvinDir) : [];
   const pluginPromptFragment = plugin ? getPluginPromptFragment(plugin, persona.id) : void 0;
@@ -19726,7 +20563,7 @@ async function startSession(options) {
     projectName: config2.project.name,
     navGroups
   });
-  const systemPrompt = buildSystemPrompt(persona, config2.project, pluginPromptFragment, skillPromptFragment);
+  const systemPrompt = buildSystemPrompt(persona, config2.project, pluginPromptFragment, skillPromptFragment, marvinDir);
   let existingSession;
   if (options.sessionName) {
     existingSession = sessionStore.get(options.sessionName);
@@ -20179,13 +21016,13 @@ async function setApiKey() {
 }
 
 // src/cli/commands/ingest.ts
-import * as fs11 from "fs";
-import * as path11 from "path";
+import * as fs12 from "fs";
+import * as path12 from "path";
 import chalk8 from "chalk";
 
 // src/sources/ingest.ts
-import * as fs10 from "fs";
-import * as path10 from "path";
+import * as fs11 from "fs";
+import * as path11 from "path";
 import chalk7 from "chalk";
 import ora2 from "ora";
 import { query as query3 } from "@anthropic-ai/claude-agent-sdk";
@@ -20288,15 +21125,15 @@ async function ingestFile(options) {
   const persona = getPersona(personaId);
   const manifest = new SourceManifestManager(marvinDir);
   const sourcesDir = manifest.sourcesDir;
-  const filePath = path10.join(sourcesDir, fileName);
-  if (!fs10.existsSync(filePath)) {
+  const filePath = path11.join(sourcesDir, fileName);
+  if (!fs11.existsSync(filePath)) {
     throw new Error(`Source file not found: ${filePath}`);
   }
-  const ext = path10.extname(fileName).toLowerCase();
+  const ext = path11.extname(fileName).toLowerCase();
   const isPdf = ext === ".pdf";
   let fileContent = null;
   if (!isPdf) {
-    fileContent = fs10.readFileSync(filePath, "utf-8");
+    fileContent = fs11.readFileSync(filePath, "utf-8");
   }
   const store = new DocumentStore(marvinDir);
   const createdArtifacts = [];
@@ -20399,9 +21236,9 @@ Ingest ended with error: ${message.subtype}`)
 async function ingestCommand(file2, options) {
   const project = loadProject();
   const marvinDir = project.marvinDir;
-  const sourcesDir = path11.join(marvinDir, "sources");
-  if (!fs11.existsSync(sourcesDir)) {
-    fs11.mkdirSync(sourcesDir, { recursive: true });
+  const sourcesDir = path12.join(marvinDir, "sources");
+  if (!fs12.existsSync(sourcesDir)) {
+    fs12.mkdirSync(sourcesDir, { recursive: true });
   }
   const manifest = new SourceManifestManager(marvinDir);
   manifest.scan();
@@ -20412,8 +21249,8 @@ async function ingestCommand(file2, options) {
     return;
   }
   if (file2) {
-    const filePath = path11.join(sourcesDir, file2);
-    if (!fs11.existsSync(filePath)) {
+    const filePath = path12.join(sourcesDir, file2);
+    if (!fs12.existsSync(filePath)) {
       console.log(chalk8.red(`Source file not found: ${file2}`));
       console.log(chalk8.dim(`Expected at: ${filePath}`));
       console.log(chalk8.dim(`Drop files into .marvin/sources/ and try again.`));
@@ -20480,7 +21317,7 @@ import ora3 from "ora";
 import { input as input3 } from "@inquirer/prompts";
 
 // src/git/repository.ts
-import * as path12 from "path";
+import * as path13 from "path";
 import simpleGit from "simple-git";
 var MARVIN_GITIGNORE = `node_modules/
 .DS_Store
@@ -20500,7 +21337,7 @@ var DIR_TYPE_LABELS = {
 function buildCommitMessage(files) {
   const counts = /* @__PURE__ */ new Map();
   for (const f of files) {
-    const parts2 = f.split(path12.sep).join("/").split("/");
+    const parts2 = f.split(path13.sep).join("/").split("/");
     const docsIdx = parts2.indexOf("docs");
     if (docsIdx !== -1 && docsIdx + 1 < parts2.length) {
       const dirName = parts2[docsIdx + 1];
@@ -20540,9 +21377,9 @@ var MarvinGit = class {
       );
     }
     await this.git.init();
-    const { writeFileSync: writeFileSync9 } = await import("fs");
-    writeFileSync9(
-      path12.join(this.marvinDir, ".gitignore"),
+    const { writeFileSync: writeFileSync10 } = await import("fs");
+    writeFileSync10(
+      path13.join(this.marvinDir, ".gitignore"),
       MARVIN_GITIGNORE,
       "utf-8"
     );
@@ -20662,9 +21499,9 @@ var MarvinGit = class {
     }
   }
   static async clone(url2, targetDir) {
-    const marvinDir = path12.join(targetDir, ".marvin");
-    const { existsSync: existsSync16 } = await import("fs");
-    if (existsSync16(marvinDir)) {
+    const marvinDir = path13.join(targetDir, ".marvin");
+    const { existsSync: existsSync17 } = await import("fs");
+    if (existsSync17(marvinDir)) {
       throw new GitSyncError(
         `.marvin/ already exists at ${targetDir}. Remove it first or choose a different directory.`
       );
@@ -20842,8 +21679,8 @@ async function cloneCommand(url2, directory) {
 }
 
 // src/mcp/stdio-server.ts
-import * as fs12 from "fs";
-import * as path13 from "path";
+import * as fs13 from "fs";
+import * as path14 from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -21074,7 +21911,7 @@ ${summaries}`
           content: [{ type: "text", text: guidance }]
         };
       },
-      { annotations: { readOnly: true } }
+      { annotations: { readOnlyHint: true } }
     )
   ];
 }
@@ -21141,8 +21978,8 @@ function collectTools(marvinDir) {
   const plugin = resolvePlugin(config2.methodology);
   const registrations = plugin?.documentTypeRegistrations ?? [];
   const store = new DocumentStore(marvinDir, registrations);
-  const sourcesDir = path13.join(marvinDir, "sources");
-  const hasSourcesDir = fs12.existsSync(sourcesDir);
+  const sourcesDir = path14.join(marvinDir, "sources");
+  const hasSourcesDir = fs13.existsSync(sourcesDir);
   const manifest = hasSourcesDir ? new SourceManifestManager(marvinDir) : void 0;
   const pluginTools = plugin ? getPluginTools(plugin, store, marvinDir) : [];
   const sessionStore = new SessionStore(marvinDir);
@@ -21150,7 +21987,7 @@ function collectTools(marvinDir) {
   const allSkillIds = [...allSkills.keys()];
   const codeSkillTools = getSkillTools(allSkillIds, allSkills, store);
   const skillsWithActions = allSkillIds.map((id) => allSkills.get(id)).filter((s) => s.actions && s.actions.length > 0);
-  const projectRoot = path13.dirname(marvinDir);
+  const projectRoot = path14.dirname(marvinDir);
   const actionTools = createSkillActionTools(skillsWithActions, { store, marvinDir, projectRoot });
   return [
     ...createDecisionTools(store),
@@ -21213,8 +22050,8 @@ async function serveCommand() {
 }
 
 // src/cli/commands/skills.ts
-import * as fs13 from "fs";
-import * as path14 from "path";
+import * as fs14 from "fs";
+import * as path15 from "path";
 import * as YAML7 from "yaml";
 import matter3 from "gray-matter";
 import chalk10 from "chalk";
@@ -21320,14 +22157,14 @@ async function skillsRemoveCommand(skillId, options) {
 }
 async function skillsCreateCommand(name) {
   const project = loadProject();
-  const skillsDir = path14.join(project.marvinDir, "skills");
-  fs13.mkdirSync(skillsDir, { recursive: true });
-  const skillDir = path14.join(skillsDir, name);
-  if (fs13.existsSync(skillDir)) {
+  const skillsDir = path15.join(project.marvinDir, "skills");
+  fs14.mkdirSync(skillsDir, { recursive: true });
+  const skillDir = path15.join(skillsDir, name);
+  if (fs14.existsSync(skillDir)) {
     console.log(chalk10.yellow(`Skill directory already exists: ${skillDir}`));
     return;
   }
-  fs13.mkdirSync(skillDir, { recursive: true });
+  fs14.mkdirSync(skillDir, { recursive: true });
   const displayName = name.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
   const frontmatter = {
     name,
@@ -21341,7 +22178,7 @@ async function skillsCreateCommand(name) {
 You have the **${displayName}** skill.
 `;
   const skillMd = matter3.stringify(body, frontmatter);
-  fs13.writeFileSync(path14.join(skillDir, "SKILL.md"), skillMd, "utf-8");
+  fs14.writeFileSync(path15.join(skillDir, "SKILL.md"), skillMd, "utf-8");
   const actions = [
     {
       id: "run",
@@ -21351,7 +22188,7 @@ You have the **${displayName}** skill.
       maxTurns: 5
     }
   ];
-  fs13.writeFileSync(path14.join(skillDir, "actions.yaml"), YAML7.stringify(actions), "utf-8");
+  fs14.writeFileSync(path15.join(skillDir, "actions.yaml"), YAML7.stringify(actions), "utf-8");
   console.log(chalk10.green(`Created skill: ${skillDir}/`));
   console.log(chalk10.dim("  SKILL.md      \u2014 skill definition and prompt"));
   console.log(chalk10.dim("  actions.yaml  \u2014 action definitions"));
@@ -21359,14 +22196,14 @@ You have the **${displayName}** skill.
 }
 async function skillsMigrateCommand() {
   const project = loadProject();
-  const skillsDir = path14.join(project.marvinDir, "skills");
-  if (!fs13.existsSync(skillsDir)) {
+  const skillsDir = path15.join(project.marvinDir, "skills");
+  if (!fs14.existsSync(skillsDir)) {
     console.log(chalk10.dim("No skills directory found."));
     return;
   }
   let entries;
   try {
-    entries = fs13.readdirSync(skillsDir);
+    entries = fs14.readdirSync(skillsDir);
   } catch {
     console.log(chalk10.red("Could not read skills directory."));
     return;
@@ -21378,16 +22215,16 @@ async function skillsMigrateCommand() {
   }
   let migrated = 0;
   for (const file2 of yamlFiles) {
-    const yamlPath = path14.join(skillsDir, file2);
+    const yamlPath = path15.join(skillsDir, file2);
     const baseName = file2.replace(/\.(yaml|yml)$/, "");
-    const outputDir = path14.join(skillsDir, baseName);
-    if (fs13.existsSync(outputDir)) {
+    const outputDir = path15.join(skillsDir, baseName);
+    if (fs14.existsSync(outputDir)) {
       console.log(chalk10.yellow(`Skipping "${file2}" \u2014 directory "${baseName}/" already exists.`));
       continue;
     }
     try {
       migrateYamlToSkillMd(yamlPath, outputDir);
-      fs13.renameSync(yamlPath, `${yamlPath}.bak`);
+      fs14.renameSync(yamlPath, `${yamlPath}.bak`);
       console.log(chalk10.green(`Migrated "${file2}" \u2192 "${baseName}/"`));
       migrated++;
     } catch (err) {
@@ -21401,35 +22238,35 @@ ${migrated} skill(s) migrated. Original files renamed to *.bak`));
 }
 
 // src/cli/commands/import.ts
-import * as fs16 from "fs";
-import * as path17 from "path";
+import * as fs17 from "fs";
+import * as path18 from "path";
 import chalk11 from "chalk";
 
 // src/import/engine.ts
-import * as fs15 from "fs";
-import * as path16 from "path";
+import * as fs16 from "fs";
+import * as path17 from "path";
 import matter5 from "gray-matter";
 
 // src/import/classifier.ts
-import * as fs14 from "fs";
-import * as path15 from "path";
+import * as fs15 from "fs";
+import * as path16 from "path";
 import matter4 from "gray-matter";
 var RAW_SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".pdf", ".txt"]);
 var CORE_DIR_NAMES = /* @__PURE__ */ new Set(["decisions", "actions", "questions"]);
 var ID_PATTERN = /^[A-Z]+-\d{3,}$/;
 function classifyPath(inputPath, knownTypes, knownDirNames) {
-  const resolved = path15.resolve(inputPath);
-  const stat = fs14.statSync(resolved);
+  const resolved = path16.resolve(inputPath);
+  const stat = fs15.statSync(resolved);
   if (!stat.isDirectory()) {
     return classifyFile(resolved, knownTypes);
   }
-  if (path15.basename(resolved) === ".marvin" || fs14.existsSync(path15.join(resolved, "config.yaml"))) {
+  if (path16.basename(resolved) === ".marvin" || fs15.existsSync(path16.join(resolved, "config.yaml"))) {
     return { type: "marvin-project", inputPath: resolved };
   }
   const allDirNames = /* @__PURE__ */ new Set([...CORE_DIR_NAMES, ...knownDirNames]);
-  const entries = fs14.readdirSync(resolved);
+  const entries = fs15.readdirSync(resolved);
   const hasDocSubdirs = entries.some(
-    (e) => allDirNames.has(e) && fs14.statSync(path15.join(resolved, e)).isDirectory()
+    (e) => allDirNames.has(e) && fs15.statSync(path16.join(resolved, e)).isDirectory()
   );
   if (hasDocSubdirs) {
     return { type: "docs-directory", inputPath: resolved };
@@ -21438,7 +22275,7 @@ function classifyPath(inputPath, knownTypes, knownDirNames) {
   if (mdFiles.length > 0) {
     const hasMarvinDocs = mdFiles.some((f) => {
       try {
-        const raw = fs14.readFileSync(path15.join(resolved, f), "utf-8");
+        const raw = fs15.readFileSync(path16.join(resolved, f), "utf-8");
         const { data } = matter4(raw);
         return isValidMarvinDocument(data, knownTypes);
       } catch {
@@ -21452,14 +22289,14 @@ function classifyPath(inputPath, knownTypes, knownDirNames) {
   return { type: "raw-source-dir", inputPath: resolved };
 }
 function classifyFile(filePath, knownTypes) {
-  const resolved = path15.resolve(filePath);
-  const ext = path15.extname(resolved).toLowerCase();
+  const resolved = path16.resolve(filePath);
+  const ext = path16.extname(resolved).toLowerCase();
   if (RAW_SOURCE_EXTENSIONS.has(ext)) {
     return { type: "raw-source-file", inputPath: resolved };
   }
   if (ext === ".md") {
     try {
-      const raw = fs14.readFileSync(resolved, "utf-8");
+      const raw = fs15.readFileSync(resolved, "utf-8");
       const { data } = matter4(raw);
       if (isValidMarvinDocument(data, knownTypes)) {
         return { type: "marvin-document", inputPath: resolved };
@@ -21584,9 +22421,9 @@ function executeImportPlan(plan, store, marvinDir, options) {
       continue;
     }
     if (item.action === "copy") {
-      const targetDir = path16.dirname(item.targetPath);
-      fs15.mkdirSync(targetDir, { recursive: true });
-      fs15.copyFileSync(item.sourcePath, item.targetPath);
+      const targetDir = path17.dirname(item.targetPath);
+      fs16.mkdirSync(targetDir, { recursive: true });
+      fs16.copyFileSync(item.sourcePath, item.targetPath);
       copied++;
       continue;
     }
@@ -21622,19 +22459,19 @@ function formatPlanSummary(plan) {
     lines.push(`Documents to import: ${imports.length}`);
     for (const item of imports) {
       const idInfo = item.originalId !== item.newId ? `${item.originalId} \u2192 ${item.newId}` : item.newId ?? item.originalId ?? "";
-      lines.push(`  ${idInfo}  ${path16.basename(item.sourcePath)}`);
+      lines.push(`  ${idInfo}  ${path17.basename(item.sourcePath)}`);
     }
   }
   if (copies.length > 0) {
     lines.push(`Files to copy to sources/: ${copies.length}`);
     for (const item of copies) {
-      lines.push(`  ${path16.basename(item.sourcePath)} \u2192 ${path16.basename(item.targetPath)}`);
+      lines.push(`  ${path17.basename(item.sourcePath)} \u2192 ${path17.basename(item.targetPath)}`);
     }
   }
   if (skips.length > 0) {
     lines.push(`Skipped (conflict): ${skips.length}`);
     for (const item of skips) {
-      lines.push(`  ${item.originalId ?? path16.basename(item.sourcePath)}  ${item.reason ?? ""}`);
+      lines.push(`  ${item.originalId ?? path17.basename(item.sourcePath)}  ${item.reason ?? ""}`);
     }
   }
   if (plan.items.length === 0) {
@@ -21667,11 +22504,11 @@ function getDirNameForType(store, type) {
 }
 function collectMarvinDocs(dir, knownTypes) {
   const docs = [];
-  const files = fs15.readdirSync(dir).filter((f) => f.endsWith(".md"));
+  const files = fs16.readdirSync(dir).filter((f) => f.endsWith(".md"));
   for (const file2 of files) {
-    const filePath = path16.join(dir, file2);
+    const filePath = path17.join(dir, file2);
     try {
-      const raw = fs15.readFileSync(filePath, "utf-8");
+      const raw = fs16.readFileSync(filePath, "utf-8");
       const { data, content } = matter5(raw);
       if (isValidMarvinDocument(data, knownTypes)) {
         docs.push({
@@ -21727,23 +22564,23 @@ function planDocImports(docs, store, options) {
 }
 function planFromMarvinProject(classification, store, _marvinDir, options) {
   let projectDir = classification.inputPath;
-  if (path16.basename(projectDir) !== ".marvin") {
-    const inner = path16.join(projectDir, ".marvin");
-    if (fs15.existsSync(inner)) {
+  if (path17.basename(projectDir) !== ".marvin") {
+    const inner = path17.join(projectDir, ".marvin");
+    if (fs16.existsSync(inner)) {
       projectDir = inner;
     }
   }
-  const docsDir = path16.join(projectDir, "docs");
-  if (!fs15.existsSync(docsDir)) {
+  const docsDir = path17.join(projectDir, "docs");
+  if (!fs16.existsSync(docsDir)) {
     return [];
   }
   const knownTypes = store.registeredTypes;
   const allDocs = [];
-  const subdirs = fs15.readdirSync(docsDir).filter(
-    (d) => fs15.statSync(path16.join(docsDir, d)).isDirectory()
+  const subdirs = fs16.readdirSync(docsDir).filter(
+    (d) => fs16.statSync(path17.join(docsDir, d)).isDirectory()
   );
   for (const subdir of subdirs) {
-    const docs = collectMarvinDocs(path16.join(docsDir, subdir), knownTypes);
+    const docs = collectMarvinDocs(path17.join(docsDir, subdir), knownTypes);
     allDocs.push(...docs);
   }
   return planDocImports(allDocs, store, options);
@@ -21753,10 +22590,10 @@ function planFromDocsDirectory(classification, store, _marvinDir, options) {
   const knownTypes = store.registeredTypes;
   const allDocs = [];
   allDocs.push(...collectMarvinDocs(dir, knownTypes));
-  const entries = fs15.readdirSync(dir);
+  const entries = fs16.readdirSync(dir);
   for (const entry of entries) {
-    const entryPath = path16.join(dir, entry);
-    if (fs15.statSync(entryPath).isDirectory()) {
+    const entryPath = path17.join(dir, entry);
+    if (fs16.statSync(entryPath).isDirectory()) {
       allDocs.push(...collectMarvinDocs(entryPath, knownTypes));
     }
   }
@@ -21765,7 +22602,7 @@ function planFromDocsDirectory(classification, store, _marvinDir, options) {
 function planFromSingleDocument(classification, store, _marvinDir, options) {
   const filePath = classification.inputPath;
   const knownTypes = store.registeredTypes;
-  const raw = fs15.readFileSync(filePath, "utf-8");
+  const raw = fs16.readFileSync(filePath, "utf-8");
   const { data, content } = matter5(raw);
   if (!isValidMarvinDocument(data, knownTypes)) {
     return [];
@@ -21781,14 +22618,14 @@ function planFromSingleDocument(classification, store, _marvinDir, options) {
 }
 function planFromRawSourceDir(classification, marvinDir) {
   const dir = classification.inputPath;
-  const sourcesDir = path16.join(marvinDir, "sources");
+  const sourcesDir = path17.join(marvinDir, "sources");
   const items = [];
-  const files = fs15.readdirSync(dir).filter((f) => {
-    const stat = fs15.statSync(path16.join(dir, f));
+  const files = fs16.readdirSync(dir).filter((f) => {
+    const stat = fs16.statSync(path17.join(dir, f));
     return stat.isFile();
   });
   for (const file2 of files) {
-    const sourcePath = path16.join(dir, file2);
+    const sourcePath = path17.join(dir, file2);
     const targetPath = resolveSourceFileName(sourcesDir, file2);
     items.push({
       action: "copy",
@@ -21799,8 +22636,8 @@ function planFromRawSourceDir(classification, marvinDir) {
   return items;
 }
 function planFromRawSourceFile(classification, marvinDir) {
-  const sourcesDir = path16.join(marvinDir, "sources");
-  const fileName = path16.basename(classification.inputPath);
+  const sourcesDir = path17.join(marvinDir, "sources");
+  const fileName = path17.basename(classification.inputPath);
   const targetPath = resolveSourceFileName(sourcesDir, fileName);
   return [
     {
@@ -21811,25 +22648,25 @@ function planFromRawSourceFile(classification, marvinDir) {
   ];
 }
 function resolveSourceFileName(sourcesDir, fileName) {
-  const targetPath = path16.join(sourcesDir, fileName);
-  if (!fs15.existsSync(targetPath)) {
+  const targetPath = path17.join(sourcesDir, fileName);
+  if (!fs16.existsSync(targetPath)) {
     return targetPath;
   }
-  const ext = path16.extname(fileName);
-  const base = path16.basename(fileName, ext);
+  const ext = path17.extname(fileName);
+  const base = path17.basename(fileName, ext);
   let counter = 1;
   let candidate;
   do {
-    candidate = path16.join(sourcesDir, `${base}-${counter}${ext}`);
+    candidate = path17.join(sourcesDir, `${base}-${counter}${ext}`);
     counter++;
-  } while (fs15.existsSync(candidate));
+  } while (fs16.existsSync(candidate));
   return candidate;
 }
 
 // src/cli/commands/import.ts
 async function importCommand(inputPath, options) {
-  const resolved = path17.resolve(inputPath);
-  if (!fs16.existsSync(resolved)) {
+  const resolved = path18.resolve(inputPath);
+  if (!fs17.existsSync(resolved)) {
     throw new ImportError(`Path not found: ${resolved}`);
   }
   const project = loadProject();
@@ -21881,7 +22718,7 @@ async function importCommand(inputPath, options) {
     console.log(chalk11.bold("\nStarting ingest of copied sources...\n"));
     const manifest = new SourceManifestManager(marvinDir);
     manifest.scan();
-    const copiedFileNames = result.items.filter((i) => i.action === "copy").map((i) => path17.basename(i.targetPath));
+    const copiedFileNames = result.items.filter((i) => i.action === "copy").map((i) => path18.basename(i.targetPath));
     for (const fileName of copiedFileNames) {
       try {
         await ingestFile({
@@ -22284,7 +23121,8 @@ The contributor is identifying a project risk.
 - Create actions for risk mitigation tasks
 - Create decisions for risk response strategies
 - Create questions for risks needing further assessment
-- Tag all related artifacts with "risk" for tracking`,
+- Tag all related artifacts with "risk" for tracking
+- When a risk is resolved, use the update tool to remove the "risk" tag and add "risk-mitigated" so it no longer inflates the GAR quality metric`,
     "blocker-report": `
 ### Type-Specific Guidance: Blocker Report
 The contributor is reporting a blocker.
@@ -22629,6 +23467,105 @@ function renderConfluence(report) {
   return lines.join("\n");
 }
 
+// src/reports/health/render-ascii.ts
+import chalk17 from "chalk";
+var STATUS_DOT2 = {
+  green: chalk17.green("\u25CF"),
+  amber: chalk17.yellow("\u25CF"),
+  red: chalk17.red("\u25CF")
+};
+var STATUS_LABEL2 = {
+  green: chalk17.green.bold("GREEN"),
+  amber: chalk17.yellow.bold("AMBER"),
+  red: chalk17.red.bold("RED")
+};
+var SEPARATOR2 = chalk17.dim("\u2500".repeat(60));
+function renderAscii2(report) {
+  const lines = [];
+  lines.push("");
+  lines.push(chalk17.bold(`  Health Check \xB7 ${report.projectName}`));
+  lines.push(chalk17.dim(`  ${report.generatedAt}`));
+  lines.push("");
+  lines.push(`  Overall:  ${STATUS_LABEL2[report.overall]}`);
+  lines.push("");
+  lines.push(`  ${SEPARATOR2}`);
+  lines.push(chalk17.bold("  Completeness"));
+  lines.push(`  ${SEPARATOR2}`);
+  for (const cat of report.completeness) {
+    lines.push(`  ${STATUS_DOT2[cat.status]} ${chalk17.bold(cat.name.padEnd(16))} ${cat.summary}`);
+    for (const item of cat.items) {
+      lines.push(`    ${chalk17.dim("\u2514")} ${item.id} ${chalk17.dim(item.detail)}`);
+    }
+  }
+  lines.push("");
+  lines.push(`  ${SEPARATOR2}`);
+  lines.push(chalk17.bold("  Process"));
+  lines.push(`  ${SEPARATOR2}`);
+  for (const cat of report.process) {
+    lines.push(`  ${STATUS_DOT2[cat.status]} ${chalk17.bold(cat.name.padEnd(22))} ${cat.summary}`);
+    for (const item of cat.items) {
+      lines.push(`    ${chalk17.dim("\u2514")} ${item.id} ${chalk17.dim(item.detail)}`);
+    }
+  }
+  lines.push(`  ${SEPARATOR2}`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/reports/health/render-confluence.ts
+var EMOJI2 = {
+  green: ":green_circle:",
+  amber: ":yellow_circle:",
+  red: ":red_circle:"
+};
+function renderConfluence2(report) {
+  const lines = [];
+  lines.push(`# Health Check \u2014 ${report.projectName}`);
+  lines.push("");
+  lines.push(`**Date:** ${report.generatedAt}`);
+  lines.push(`**Overall:** ${EMOJI2[report.overall]} ${report.overall.toUpperCase()}`);
+  lines.push("");
+  lines.push("## Completeness");
+  lines.push("");
+  lines.push("| Category | Status | Summary |");
+  lines.push("|----------|--------|---------|");
+  for (const cat of report.completeness) {
+    lines.push(
+      `| ${cat.name} | ${EMOJI2[cat.status]} ${cat.status.toUpperCase()} | ${cat.summary} |`
+    );
+  }
+  lines.push("");
+  for (const cat of report.completeness) {
+    if (cat.items.length === 0) continue;
+    lines.push(`### ${cat.name}`);
+    lines.push("");
+    for (const item of cat.items) {
+      lines.push(`- **${item.id}** ${item.detail}`);
+    }
+    lines.push("");
+  }
+  lines.push("## Process");
+  lines.push("");
+  lines.push("| Metric | Status | Summary |");
+  lines.push("|--------|--------|---------|");
+  for (const cat of report.process) {
+    lines.push(
+      `| ${cat.name} | ${EMOJI2[cat.status]} ${cat.status.toUpperCase()} | ${cat.summary} |`
+    );
+  }
+  lines.push("");
+  for (const cat of report.process) {
+    if (cat.items.length === 0) continue;
+    lines.push(`### ${cat.name}`);
+    lines.push("");
+    for (const item of cat.items) {
+      lines.push(`- **${item.id}** ${item.detail}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
 // src/cli/commands/report.ts
 async function garReportCommand(options) {
   const project = loadProject();
@@ -22644,6 +23581,20 @@ async function garReportCommand(options) {
     console.log(renderAscii(report));
   }
 }
+async function healthReportCommand(options) {
+  const project = loadProject();
+  const plugin = resolvePlugin(project.config.methodology);
+  const registrations = plugin?.documentTypeRegistrations ?? [];
+  const store = new DocumentStore(project.marvinDir, registrations);
+  const metrics = collectHealthMetrics(store);
+  const report = evaluateHealth(project.config.name, metrics);
+  const format = options.format ?? "ascii";
+  if (format === "confluence") {
+    console.log(renderConfluence2(report));
+  } else {
+    console.log(renderAscii2(report));
+  }
+}
 
 // src/cli/commands/web.ts
 async function webCommand(options) {
@@ -22655,12 +23606,38 @@ async function webCommand(options) {
   await startWebServer({ port, open: options.open });
 }
 
+// src/cli/commands/generate.ts
+import * as fs18 from "fs";
+import * as path19 from "path";
+import chalk18 from "chalk";
+import { confirm as confirm2 } from "@inquirer/prompts";
+async function generateClaudeMdCommand(options) {
+  const project = loadProject();
+  const filePath = path19.join(project.marvinDir, "CLAUDE.md");
+  if (fs18.existsSync(filePath) && !options.force) {
+    const overwrite = await confirm2({
+      message: ".marvin/CLAUDE.md already exists. Overwrite?",
+      default: false
+    });
+    if (!overwrite) {
+      console.log(chalk18.dim("Aborted."));
+      return;
+    }
+  }
+  fs18.writeFileSync(
+    filePath,
+    getDefaultClaudeMdContent(project.config.name),
+    "utf-8"
+  );
+  console.log(chalk18.green("Created .marvin/CLAUDE.md"));
+}
+
 // src/cli/program.ts
 function createProgram() {
   const program2 = new Command();
   program2.name("marvin").description(
     "AI-powered product development assistant with Product Owner, Delivery Manager, and Technical Lead personas"
-  ).version("0.3.3");
+  ).version("0.3.6");
   program2.command("init").description("Initialize a new Marvin project in the current directory").action(async () => {
     await initCommand();
   });
@@ -22737,9 +23714,19 @@ function createProgram() {
   ).action(async (options) => {
     await garReportCommand(options);
   });
+  reportCmd.command("health").description("Generate a governance health check report").option(
+    "--format <format>",
+    "Output format: ascii or confluence (default: ascii)"
+  ).action(async (options) => {
+    await healthReportCommand(options);
+  });
   program2.command("web").description("Launch a local web dashboard for project data").option("-p, --port <port>", "Port to listen on (default: 3000)").option("--no-open", "Don't auto-open the browser").action(async (options) => {
     await webCommand(options);
   });
+  const generateCmd = program2.command("generate").description("Generate project files");
+  generateCmd.command("claude-md").description("Generate .marvin/CLAUDE.md project instruction file").option("--force", "Overwrite existing file without prompting").action(async (options) => {
+    await generateClaudeMdCommand(options);
+  });
   return program2;
 }