@chrysb/alphaclaw 0.4.6-beta.1 → 0.4.6-beta.3

package/lib/server/doctor/normalize.js

@@ -89,42 +89,76 @@ const normalizeCardStatus = (value) => {
   return kDoctorCardStatus.open;
 };
 
-const normalizeEvidence = (value) => {
-  if (Array.isArray(value)) {
-    return value
-      .map((item) => {
-        if (item == null) return null;
-        if (typeof item === "string") {
-          const text = toTrimmedString(item);
-          return text ? { type: "text", text } : null;
-        }
-        if (typeof item === "object") return item;
-        return { type: "text", text: String(item) };
-      })
-      .filter(Boolean);
+const normalizeEvidenceItem = (item) => {
+  if (item == null) return null;
+  if (typeof item === "string") {
+    const text = toTrimmedString(item);
+    return text ? { type: "text", text } : null;
+  }
+  if (typeof item === "object") {
+    const entry = { ...item };
+    if (entry.type === "path" && entry.path) {
+      entry.path = toTrimmedString(entry.path);
+      if (Number.isFinite(entry.startLine) && entry.startLine > 0) {
+        entry.startLine = entry.startLine;
+      } else {
+        delete entry.startLine;
+      }
+      if (Number.isFinite(entry.endLine) && entry.endLine > 0) {
+        entry.endLine = entry.endLine;
+      } else {
+        delete entry.endLine;
+      }
+    }
+    return entry;
   }
+  return { type: "text", text: String(item) };
+};
+
+const normalizeEvidence = (value) => {
+  if (Array.isArray(value)) return value.map(normalizeEvidenceItem).filter(Boolean);
   if (typeof value === "string") {
     const text = toTrimmedString(value);
     return text ? [{ type: "text", text }] : [];
   }
-  if (value && typeof value === "object") return [value];
+  if (value && typeof value === "object") return [normalizeEvidenceItem(value)].filter(Boolean);
   return [];
 };
 
+const normalizeTargetPathItem = (item) => {
+  if (item == null) return null;
+  if (typeof item === "string") {
+    const path = toTrimmedString(item);
+    return path ? { path } : null;
+  }
+  if (typeof item === "object" && item.path) {
+    const path = toTrimmedString(item.path);
+    if (!path) return null;
+    const entry = { path };
+    if (Number.isFinite(item.startLine) && item.startLine > 0) entry.startLine = item.startLine;
+    if (Number.isFinite(item.endLine) && item.endLine > 0) entry.endLine = item.endLine;
+    return entry;
+  }
+  return null;
+};
+
 const normalizeTargetPaths = (value) => {
   const values = Array.isArray(value) ? value : value == null ? [] : [value];
-  return Array.from(
-    new Set(
-      values
-        .map((item) => toTrimmedString(item))
-        .filter(Boolean),
-    ),
-  );
+  const seen = new Set();
+  return values
+    .map(normalizeTargetPathItem)
+    .filter((item) => {
+      if (!item) return false;
+      if (seen.has(item.path)) return false;
+      seen.add(item.path);
+      return true;
+    });
 };
 
 const buildFallbackFixPrompt = ({ title, recommendation, targetPaths }) => {
-  const targetLine = targetPaths.length
-    ? `Focus on these paths if relevant: ${targetPaths.join(", ")}.`
+  const pathStrings = targetPaths.map((item) => item?.path || String(item)).filter(Boolean);
+  const targetLine = pathStrings.length
+    ? `Focus on these paths if relevant: ${pathStrings.join(", ")}.`
     : "Inspect the relevant workspace files before making changes.";
   return (
     `Please address this Doctor finding safely.\n\n` +

package/lib/server/doctor/prompt.js

@@ -1,13 +1,29 @@
 const renderList = (items = []) =>
   items.length ? items.map((item) => `- ${item}`).join("\n") : "- (none)";
 
+const renderResolvedCards = (cards = []) => {
+  if (!cards.length) return "";
+  const lines = cards.map(
+    (card) =>
+      `- [${card.status}] ${card.title}` +
+      (card.category ? ` (${card.category})` : ""),
+  );
+  return `
+
+Previously resolved findings (do not re-suggest these):
+${lines.join("\n")}
+`;
+};
+
 const buildDoctorPrompt = ({
   workspaceRoot = "",
   managedRoot = "",
   protectedPaths = [],
   lockedPaths = [],
+  resolvedCards = [],
   promptVersion = "doctor-v1",
-}) => `
+}) =>
+  `
 You are AlphaClaw Doctor. Analyze this OpenClaw workspace for guidance drift, redundancy, misplacement, and cleanup opportunities.
 
 Important:
@@ -20,6 +36,10 @@ Important:
 - A fresh install can be healthy even if it includes broad default guidance.
 - Return ONLY valid JSON. No markdown fences. No extra prose.
 
+OpenClaw context injection:
+- OpenClaw automatically injects ALL root-level \`.md\` files (e.g. AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md) into the agent's context window as "project context" on every turn.
+- Additionally, AlphaClaw injects bootstrap files from \`hooks/bootstrap/\` (e.g. AGENTS.md, TOOLS.md) as extra context on every turn.
+
 OpenClaw default context:
 - \`AGENTS.md\` is the workspace home file in the default OpenClaw template. It may intentionally include first-run instructions, session-startup guidance, memory conventions, safety rules, tool pointers, and optional behavioral guidance.
 - Do not treat default-template content as drift just because it is broad or multi-purpose.
@@ -64,20 +84,26 @@ Return exactly this JSON shape:
       "summary": "what is wrong and why it matters",
       "recommendation": "clear recommended action",
       "evidence": [
-        { "type": "path", "path": "relative/path" },
+        { "type": "path", "path": "relative/path", "startLine": 10, "endLine": 25 },
         { "type": "note", "text": "short supporting note" }
       ],
-      "targetPaths": ["relative/path/one", "relative/path/two"],
+      "targetPaths": [
+        { "path": "relative/path/one", "startLine": 10 },
+        { "path": "relative/path/two" }
+      ],
       "fixPrompt": "a concise message another agent can use to fix just this finding safely",
       "status": "open"
     }
   ]
 }
 
-Constraints:
+${renderResolvedCards(resolvedCards)}Constraints:
 - Maximum 12 cards
 - Use relative paths in evidence and targetPaths
+- Include startLine (and optionally endLine) in evidence and targetPaths when the finding relates to a specific section of a file
+- targetPaths items can be strings or objects with { path, startLine? }
 - Do not include duplicate cards
+- Do not re-suggest findings that appear in the "Previously resolved" list above
 - Do not create cards for healthy default-template behavior
 - Do not create cards whose primary recommendation is to refactor AlphaClaw-managed file structure
 - If there are no meaningful findings, return an empty cards array

package/lib/server/doctor/service.js

@@ -1,3 +1,5 @@
+const fs = require("fs");
+const path = require("path");
 const { buildDoctorPrompt } = require("./prompt");
 const { normalizeDoctorResult } = require("./normalize");
 const { calculateWorkspaceDelta, computeWorkspaceSnapshot } = require("./workspace-fingerprint");
@@ -10,6 +12,8 @@ const {
   kDoctorStaleThresholdMs,
 } = require("./constants");
 
+const kMaxSnippetLines = 20;
+
 const shellEscapeArg = (value) => {
   const safeValue = String(value || "");
   return `'${safeValue.replace(/'/g, `'\\''`)}'`;
@@ -35,6 +39,37 @@ const formatElapsedSince = (isoTime) => {
   return `${elapsedDays} day${elapsedDays === 1 ? "" : "s"} ago`;
 };
 
+const readFileSnippet = (rootDir, relativePath, startLine, endLine) => {
+  try {
+    const fullPath = path.join(rootDir, String(relativePath || ""));
+    const content = fs.readFileSync(fullPath, "utf-8");
+    const lines = content.split("\n");
+    const start = Math.max(0, (startLine || 1) - 1);
+    const end = endLine && endLine >= startLine ? Math.min(lines.length, endLine) : start + 1;
+    const cappedEnd = Math.min(end, start + kMaxSnippetLines);
+    return {
+      text: lines.slice(start, cappedEnd).join("\n"),
+      startLine: start + 1,
+      endLine: start + (cappedEnd - start),
+      truncated: cappedEnd < end,
+      totalFileLines: lines.length,
+    };
+  } catch {
+    return null;
+  }
+};
+
+const captureEvidenceSnippets = (cards, rootDir) => {
+  for (const card of cards) {
+    if (!Array.isArray(card.evidence)) continue;
+    for (const item of card.evidence) {
+      if (!item || item.type !== "path" || !item.path || !item.startLine) continue;
+      const snippet = readFileSnippet(rootDir, item.path, item.startLine, item.endLine);
+      if (snippet) item.snippet = snippet;
+    }
+  }
+};
+
 const buildDoctorSessionKey = (runId) => `agent:main:doctor:${Number(runId || 0)}`;
 const buildDoctorSessionId = (runId) => buildDoctorSessionKey(runId);
 const buildDoctorIdempotencyKey = (runId) => `doctor-run-${Number(runId || 0)}`;
@@ -156,11 +191,20 @@ const createDoctorService = ({
 
   const executeDoctorRun = async (runId) => {
     try {
+      const allCards = listDoctorCards();
+      const resolvedCards = allCards
+        .filter((card) => card.status === "dismissed" || card.status === "fixed")
+        .map((card) => ({
+          status: card.status,
+          title: card.title || "",
+          category: card.category || "",
+        }));
       const prompt = buildDoctorPrompt({
         workspaceRoot,
         managedRoot,
         protectedPaths,
         lockedPaths,
+        resolvedCards,
         promptVersion: kDoctorPromptVersion,
       });
       const gatewayTimeoutMs = kDoctorRunTimeoutMs + 30000;
@@ -204,6 +248,7 @@ const createDoctorService = ({
         console.error(`[doctor] run ${runId} stderr end`);
         throw error;
       }
+      captureEvidenceSnippets(normalizedResult.cards, workspaceRoot);
       insertDoctorCards({
         runId,
         cards: normalizedResult.cards,
@@ -300,6 +345,7 @@ const createDoctorService = ({
       throw new Error("Doctor import requires raw output");
     }
     const normalizedResult = normalizeDoctorResult(normalizedRawOutput);
+    captureEvidenceSnippets(normalizedResult.cards, workspaceRoot);
     const workspaceSnapshot = getCurrentWorkspaceSnapshot();
     const runId = createDoctorRun({
       status: kDoctorRunStatus.completed,

package/lib/server/doctor/workspace-fingerprint.js

@@ -4,6 +4,17 @@ const crypto = require("crypto");
 
 const kIgnoredDirectoryNames = new Set([".git", "node_modules"]);
 
+const kContentFileExtensions = new Set([
+  ".md", ".json", ".js", ".ts", ".jsx", ".tsx", ".yaml", ".yml",
+  ".txt", ".sh", ".css", ".html", ".xml", ".toml", ".ini", ".cfg",
+  ".py", ".rb", ".go", ".rs", ".java", ".c", ".cpp", ".h",
+]);
+
+const isContentFile = (relativePath = "") => {
+  const ext = path.extname(String(relativePath || "")).toLowerCase();
+  return kContentFileExtensions.has(ext);
+};
+
 const hashFile = (filePath) => {
   const buffer = fs.readFileSync(filePath);
   return crypto.createHash("sha256").update(buffer).digest("hex");
@@ -34,11 +45,21 @@ const buildWorkspaceManifest = (rootDir) => {
   const normalizedRootDir = path.resolve(String(rootDir || ""));
   const files = walkFiles(normalizedRootDir);
   return files.reduce((manifest, filePath) => {
-    manifest[normalizeRelativePath(normalizedRootDir, filePath)] = hashFile(filePath);
+    const stat = fs.statSync(filePath);
+    manifest[normalizeRelativePath(normalizedRootDir, filePath)] = {
+      hash: hashFile(filePath),
+      size: stat.size,
+    };
     return manifest;
   }, {});
 };
 
+const getManifestEntryHash = (entry) =>
+  typeof entry === "object" && entry !== null ? String(entry.hash || "") : String(entry || "");
+
+const getManifestEntrySize = (entry) =>
+  typeof entry === "object" && entry !== null ? Number(entry.size || 0) : 0;
+
 const computeWorkspaceFingerprintFromManifest = (manifest = {}) => {
   const hash = crypto.createHash("sha256");
   const entries = Object.entries(manifest).sort(([leftPath], [rightPath]) =>
@@ -46,10 +67,10 @@ const computeWorkspaceFingerprintFromManifest = (manifest = {}) => {
   );
 
   hash.update("workspace-fingerprint-v1");
-  for (const [relativePath, fileHash] of entries) {
+  for (const [relativePath, entry] of entries) {
     hash.update(relativePath);
     hash.update("\0");
-    hash.update(fileHash);
+    hash.update(getManifestEntryHash(entry));
     hash.update("\0");
   }
 
@@ -84,6 +105,20 @@ const getPathChangeWeight = (relativePath = "") => {
   return 1;
 };
 
+const kByteDeltaSmallThreshold = 100;
+const kByteDeltaSignificantThreshold = 500;
+
+const getModifiedFileScore = (relativePath, previousEntry, currentEntry) => {
+  if (!isContentFile(relativePath)) return 1;
+  const previousSize = getManifestEntrySize(previousEntry);
+  const currentSize = getManifestEntrySize(currentEntry);
+  if (!previousSize && !currentSize) return getPathChangeWeight(relativePath);
+  const byteDelta = Math.abs(currentSize - previousSize);
+  if (byteDelta < kByteDeltaSmallThreshold) return 1;
+  if (byteDelta < kByteDeltaSignificantThreshold) return 2;
+  return getPathChangeWeight(relativePath);
+};
+
 const calculateWorkspaceDelta = ({ previousManifest = {}, currentManifest = {} } = {}) => {
   const previousPaths = Object.keys(previousManifest);
   const currentPaths = Object.keys(currentManifest);
@@ -100,19 +135,23 @@ const calculateWorkspaceDelta = ({ previousManifest = {}, currentManifest = {} }
   };
 
   for (const relativePath of allPaths) {
-    const previousHash = previousManifest[relativePath] || "";
-    const currentHash = currentManifest[relativePath] || "";
+    const previousEntry = previousManifest[relativePath];
+    const currentEntry = currentManifest[relativePath];
+    const previousHash = getManifestEntryHash(previousEntry);
+    const currentHash = getManifestEntryHash(currentEntry);
     if (!previousHash && currentHash) {
       changeSummary.addedFilesCount += 1;
+      changeSummary.deltaScore += getPathChangeWeight(relativePath);
     } else if (previousHash && !currentHash) {
       changeSummary.removedFilesCount += 1;
+      changeSummary.deltaScore += getPathChangeWeight(relativePath);
     } else if (previousHash !== currentHash) {
       changeSummary.modifiedFilesCount += 1;
+      changeSummary.deltaScore += getModifiedFileScore(relativePath, previousEntry, currentEntry);
     } else {
       continue;
     }
     changeSummary.changedFilesCount += 1;
-    changeSummary.deltaScore += getPathChangeWeight(relativePath);
     changeSummary.changedPaths.push(relativePath);
   }
 
@@ -123,4 +162,5 @@ module.exports = {
   calculateWorkspaceDelta,
   computeWorkspaceFingerprintFromManifest,
   computeWorkspaceSnapshot,
+  isContentFile,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrysb/alphaclaw",
-  "version": "0.4.6-beta.1",
+  "version": "0.4.6-beta.3",
   "publishConfig": {
     "access": "public"
   },