@lazyingart/agintiflow 0.12.11 → 0.13.0

package/README.md

@@ -75,7 +75,7 @@ For code edits, AgInTiFlow routes patch/refactor/database-style tasks to DeepSee
 
 For larger repositories, use `--profile large-codebase` or choose **Large codebase engineering** in the web UI. The web default stays **Auto**, and Auto now escalates codebase/system/debugging prompts to the same engineering loop when needed. Complex work routes to DeepSeek v4 pro, starts with `inspect_project`, then uses search/read/patch/check loops inspired by Codex, Copilot SDK, Claude Code, Gemini CLI, Qwen, and Claw Code. See [docs/large-codebase-engineering.md](docs/large-codebase-engineering.md).
 
-AgInTiFlow can also spend cheap DeepSeek calls on parallel scout notes before the main executor starts a complicated task. It first builds a bounded `inspect_project` context pack, then runs scouts for architecture, implementation, review, research, context mapping, tests, git workflow, integration, symbol tracing, and dependency risks. A coordinator Swarm Board is injected for the main agent. The executor still does the real file/shell/browser work itself. Disable with `--no-parallel-scouts` or set `--scout-count 1..10`.
+AgInTiFlow can also spend cheap DeepSeek calls on parallel scout notes before the main executor starts a complicated task. It first writes a bounded project map to `.aginti/codebase-map.json`, then runs scouts for architecture, implementation, review, research, context mapping, tests, git workflow, integration, symbol tracing, and dependency risks. A coordinator Swarm Board is injected for the main agent and saved as `artifacts/scout-blackboard.json` in the session. The executor still does the real file/shell/browser work itself. Disable with `--no-parallel-scouts` or set `--scout-count 1..10`.
 
 The next productive-agent roadmap is tracked in [docs/productive-agent-roadmap.md](docs/productive-agent-roadmap.md): durable codebase maps, stronger scout blackboards, long-run checkpoints, LSP/symbol tools, test triage, and release automation.
 

package/docs/large-codebase-engineering.md

@@ -99,9 +99,9 @@ DeepSeek calls are cheap enough that complex tasks can use several short advisor
 - Symbol tracer: predicts names, APIs, routes, schemas, and searches that connect the change.
 - Dependency doctor: checks package managers, Docker/toolchain setup, generated artifacts, and install risks.
 
-Before scouts run, AgInTiFlow builds a bounded shared context pack with `inspect_project`: manifests, top-level files, source/test directories, package scripts, language counts, git status hints, and recommended reads. This avoids the weak pattern of each scout rediscovering the repo differently or flooding the main context with an infinite tree.
+Before scouts run, AgInTiFlow builds a bounded shared context pack from a durable project map at `.aginti/codebase-map.json`: manifests, top-level files, source/test directories, package scripts, language counts, git status hints, and recommended reads. This avoids the weak pattern of each scout rediscovering the repo differently or flooding the main context with an infinite tree.
 
-Scout output is synthesized by a coordinator Swarm Board and injected as advisory context only. The board records shared context, execution order, conflicts/unknowns, must-read files/checks, and stop conditions. The main agent still owns execution and must use real tools to inspect, edit, run commands, and finish. CLI flags:
+Scout output is synthesized by a coordinator Swarm Board, persisted as `artifacts/scout-blackboard.json`, and injected as advisory context only. The board records shared context, execution order, conflicts/unknowns, must-read files/checks, and stop conditions. The main agent still owns execution and must use real tools to inspect, edit, run commands, and finish. CLI flags:
 
 ```bash
 aginti --parallel-scouts --scout-count 10 "fix this complicated repo bug"

package/docs/productive-agent-roadmap.md

@@ -19,8 +19,8 @@ AgInTiFlow should become a practical coding agent, not only a chat UI around a m
 
 ## Missing Productive-Agent Pieces
 
-1. Durable codebase map: cache `inspect_project`, symbol locations, test commands, package scripts, and recently changed files per project.
-2. Scout blackboard: let scouts write short structured findings to a shared board, then run a coordinator pass that resolves conflicts before execution.
+1. Durable codebase map: cache `inspect_project`, symbol locations, test commands, package scripts, and recently changed files per project. Initial slice implemented as `.aginti/codebase-map.json` with manifests, source/test dirs, package scripts, languages, git hints, and recommended reads.
+2. Scout blackboard: let scouts write short structured findings to a shared board, then run a coordinator pass that resolves conflicts before execution. Initial slice implemented as per-session `artifacts/scout-blackboard.json` with role lanes, findings, coordinator handoff, and codebase-map metadata.
 3. Long-run checkpoints: save phase state after inspect, patch, test, repair, and commit so a long task can recover after interruption.
 4. Symbol/LSP tools: add find-definition, references, diagnostics, and document-symbols for JS/TS, Python, Rust, Go, and C/C++ where available.
 5. Test triage: parse common test failures into file, symbol, command, and likely cause so repair loops stay narrow.
@@ -30,6 +30,6 @@ AgInTiFlow should become a practical coding agent, not only a chat UI around a m
 
 ## Swarm Design
 
-Scouts must not become noisy subagents. Each scout gets the same bounded context pack and one role. The coordinator produces a Swarm Board with shared context, execution order, disagreements, must-read files, checks, and stop conditions. The main agent still owns tool use and must re-read exact files before editing.
+Scouts must not become noisy subagents. Each scout gets the same bounded context pack generated from the durable codebase map and one role. The coordinator produces a Swarm Board with shared context, execution order, disagreements, must-read files, checks, and stop conditions. The main agent still owns tool use and must re-read exact files before editing.
 
 Use 3 scouts for medium tasks, 5 for large tasks, and up to 10 for complex multi-language or system tasks. More scouts are only useful when their roles cover different failure modes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.12.11",
+  "version": "0.13.0",
   "type": "module",
   "description": "AgInTiFlow is a resumable Playwright website-control agent with OpenAI-compatible tool calling.",
   "license": "Apache-2.0",

package/scripts/smoke-coding-tools.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { repairModelMessageHistory, runAgent } from "../src/agent-runner.js";
 import { resolveRuntimeConfig } from "../src/config.js";
+import { readCodebaseMap } from "../src/codebase-map.js";
 import { engineeringGuidanceForTask, recommendedMaxStepsForTask } from "../src/engineering-guidance.js";
 import { selectModelRoute } from "../src/model-routing.js";
 import { listParallelScouts, runParallelScouts, shouldRunParallelScouts } from "../src/parallel-scouts.js";
@@ -219,10 +220,19 @@ try {
   assert(scoutRun.contextPack.includes("package.json"), "parallel scout context pack did not include manifest evidence");
   assert(scoutRun.summary.includes("## shared context pack"), "parallel scout summary omitted shared context pack");
   assert(scoutRun.summary.includes("## coordinator"), "parallel scout summary omitted coordinator synthesis");
+  assert(scoutRun.codebaseMap?.fingerprint, "parallel scout run did not return durable codebase map metadata");
+  assert(scoutRun.blackboard?.lanes?.length === 10, "parallel scout blackboard did not include all scout lanes");
+  assert(scoutRun.blackboard?.coordinator.includes("Swarm Board"), "parallel scout blackboard did not retain coordinator synthesis");
   assert(
     fakeScoutPrompts.filter((prompt) => /Shared context pack:[\s\S]*package\.json/.test(prompt)).length >= 10,
     "parallel scouts did not receive the shared context pack"
   );
+  const codebaseMap = await readCodebaseMap(workspace);
+  assert(codebaseMap.ok && codebaseMap.map.fingerprint === scoutRun.codebaseMap.fingerprint, "durable codebase map was not persisted");
+  const blackboardStore = new SessionStore(runtimeDir, "blackboard-smoke");
+  const blackboardPath = await blackboardStore.saveJsonArtifact("scout-blackboard.json", scoutRun.blackboard);
+  const blackboardJson = JSON.parse(await fs.readFile(blackboardPath, "utf8"));
+  assert(blackboardJson.lanes.length === 10, "scout blackboard artifact did not persist lanes");
 
   const inspectRun = await runMock("Inspect this large codebase and recommend next reads.", "coding-inspect");
   assert(
@@ -368,6 +378,8 @@ try {
           "web_search_dry_run",
           "inspect_project",
           "parallel_scout_context_pack",
+          "durable_codebase_map",
+          "scout_blackboard",
           "mock_inspect_project",
           "write_file",
           "duplicate_write_failed",

package/src/agent-runner.js

@@ -1170,11 +1170,16 @@ export async function runAgent(config) {
 
     if (shouldRunParallelScouts(config, state)) {
       const scouts = await runParallelScouts(client, config, state);
+      const blackboardPath = scouts.blackboard
+        ? await store.saveJsonArtifact("scout-blackboard.json", scouts.blackboard).catch(() => "")
+        : "";
       state.meta.parallelScoutsCompleted = true;
       state.meta.parallelScouts = {
         model: scouts.model,
         requested: scouts.requested,
         completed: scouts.completed,
+        codebaseMap: scouts.codebaseMap || null,
+        blackboardPath,
         contextPack: scouts.contextPack ? scouts.contextPack.slice(0, 1200) : "",
         synthesis: scouts.synthesis || "",
       };
@@ -1186,8 +1191,11 @@ export async function runAgent(config) {
         model: scouts.model,
         requested: scouts.requested,
         completed: scouts.completed,
+        codebaseMap: scouts.codebaseMap || null,
+        blackboardPath,
         contextPack: scouts.contextPack || "",
         synthesis: scouts.synthesis || "",
+        blackboard: scouts.blackboard || null,
         scouts: scouts.scouts.map((scout) => ({
           name: scout.name,
           model: scout.model,
@@ -1200,6 +1208,7 @@ export async function runAgent(config) {
         model: scouts.model,
         requested: scouts.requested,
         completed: scouts.completed,
+        blackboardPath,
       });
       emitConsole(config, `Parallel scouts: ${scouts.completed}/${scouts.requested} completed using ${scouts.model}`, {
         kind: "meta",

package/src/capabilities.js

@@ -8,6 +8,7 @@ import { listProjectSessions, projectPaths, providerKeyStatus, readProjectInstru
 import { listTaskProfiles } from "./task-profiles.js";
 import { listAgentWrappers } from "./tool-wrappers.js";
 import { listAuxiliarySkills } from "./auxiliary-tools.js";
+import { readCodebaseMap } from "./codebase-map.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -110,7 +111,7 @@ function trustedDockerPolicyChecks(config) {
 export async function buildCapabilityReport(projectRoot, packageVersion, config) {
   const paths = projectPaths(projectRoot);
   const keyStatus = providerKeyStatus(projectRoot);
-  const [node, npm, python, conda, r, pdflatex, latexmk, dockerStatus, sessions, instructions] = await Promise.all([
+  const [node, npm, python, conda, r, pdflatex, latexmk, dockerStatus, sessions, instructions, codebaseMap] = await Promise.all([
     commandAvailable("node", ["--version"]),
     commandAvailable("npm", ["--version"]),
     commandAvailable("python3", ["--version"]),
@@ -121,6 +122,7 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
     getDockerSandboxStatus(config).catch((error) => ({ ok: false, error: error.message })),
     listProjectSessions(projectRoot, 12),
     readProjectInstructions(projectRoot, { maxBytes: 1 }),
+    readCodebaseMap(projectRoot),
   ]);
 
   const npmPrefixPolicy = evaluateCommandPolicy("npm --prefix round9-node-app test", config);
@@ -179,6 +181,13 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
       sessionsDir: paths.sessionsDir,
       sessionDbPath: paths.sessionDbPath,
       sharedSessionFolder: path.resolve(config.sessionsDir) === path.resolve(paths.sessionsDir),
+      codebaseMap: {
+        present: Boolean(codebaseMap.ok),
+        path: paths.codebaseMapPath,
+        generatedAt: codebaseMap.ok ? codebaseMap.map.generatedAt || "" : "",
+        fingerprint: codebaseMap.ok ? codebaseMap.map.fingerprint || "" : "",
+        summary: codebaseMap.ok ? codebaseMap.map.inspection?.summary || "" : "",
+      },
     },
     routing: {
       active: {

package/src/codebase-map.js

@@ -0,0 +1,151 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { projectPaths } from "./project.js";
+import { redactSensitiveText } from "./redaction.js";
+import { executeWorkspaceTool } from "./workspace-tools.js";
+
+const MAP_VERSION = 1;
+const DEFAULT_CONTEXT_PACK_CHARS = 3800;
+
+function stableHash(value) {
+  return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 16);
+}
+
+function truncateText(text, limit = DEFAULT_CONTEXT_PACK_CHARS) {
+  const value = String(text || "");
+  if (value.length <= limit) return value;
+  return `${value.slice(0, Math.max(limit - 80, 1))}\n... [truncated ${value.length - limit + 80} chars]`;
+}
+
+function listValues(items, limit, mapper) {
+  const values = Array.isArray(items) ? items.slice(0, limit).map(mapper).filter(Boolean) : [];
+  if (!values.length) return "";
+  const suffix = Array.isArray(items) && items.length > limit ? `, ... +${items.length - limit}` : "";
+  return `${values.join(", ")}${suffix}`;
+}
+
+function packageScriptValues(scripts) {
+  if (!Array.isArray(scripts) || !scripts.length) return "";
+  return listValues(scripts, 14, (item) => `${item.name}: ${item.command}`);
+}
+
+function compactInspection(inspected) {
+  return {
+    summary: inspected.summary || "",
+    counts: inspected.counts || {},
+    truncated: Boolean(inspected.truncated),
+    topLevel: Array.isArray(inspected.topLevel) ? inspected.topLevel.slice(0, 80) : [],
+    manifestFiles: Array.isArray(inspected.manifestFiles) ? inspected.manifestFiles.slice(0, 80) : [],
+    sourceDirs: Array.isArray(inspected.sourceDirs) ? inspected.sourceDirs.slice(0, 60) : [],
+    testFiles: Array.isArray(inspected.testFiles) ? inspected.testFiles.slice(0, 80) : [],
+    packageManagers: Array.isArray(inspected.packageManagers) ? inspected.packageManagers.slice(0, 20) : [],
+    packageScripts: Array.isArray(inspected.packageScripts) ? inspected.packageScripts.slice(0, 30) : [],
+    languageCounts: Array.isArray(inspected.languageCounts) ? inspected.languageCounts.slice(0, 30) : [],
+    git: inspected.git || {},
+    recommendedReads: Array.isArray(inspected.recommendedReads) ? inspected.recommendedReads.slice(0, 40) : [],
+    engineeringHints: Array.isArray(inspected.engineeringHints) ? inspected.engineeringHints.slice(0, 20) : [],
+  };
+}
+
+export function codebaseMapToContextPack(map, { maxChars = DEFAULT_CONTEXT_PACK_CHARS } = {}) {
+  if (!map?.inspection) return "Context pack: no durable codebase map available.";
+  const inspected = map.inspection;
+  const sections = [
+    `Context pack for ${map.commandCwd || map.projectRoot}`,
+    `Map: version=${map.version} generatedAt=${map.generatedAt} fingerprint=${map.fingerprint}`,
+    `Summary: ${inspected.summary || "no summary"}`,
+    inspected.counts
+      ? `Counts: files=${inspected.counts.files} dirs=${inspected.counts.directories} bytes=${inspected.counts.totalBytes}`
+      : "",
+    `Top level: ${listValues(inspected.topLevel, 20, (item) => `${item.type}:${item.path}`)}`,
+    `Manifests: ${listValues(inspected.manifestFiles, 18, (item) => item.path)}`,
+    `Source dirs: ${listValues(inspected.sourceDirs, 14, (item) => item.path)}`,
+    `Tests: ${listValues(inspected.testFiles, 18, (item) => item.path)}`,
+    `Package managers: ${listValues(inspected.packageManagers, 8, (item) => item.name || item.path || item)}`,
+    packageScriptValues(inspected.packageScripts) ? `Package scripts: ${packageScriptValues(inspected.packageScripts)}` : "",
+    `Languages: ${listValues(inspected.languageCounts, 10, (item) => `${item.name}:${item.count}`)}`,
+    inspected.git?.present
+      ? `Git: present; start with ${inspected.git.recommendedCommands?.join(" && ") || "git status --short"}; ${inspected.git.workflow}`
+      : "Git: not detected at workspace root.",
+    `Recommended reads: ${listValues(inspected.recommendedReads, 16, (item) => item)}`,
+    `Engineering hints: ${listValues(inspected.engineeringHints, 8, (item) => item)}`,
+  ].filter(Boolean);
+  return truncateText(redactSensitiveText(sections.join("\n")), maxChars);
+}
+
+export async function readCodebaseMap(projectRoot = process.cwd()) {
+  const paths = projectPaths(projectRoot);
+  try {
+    const raw = await fs.readFile(paths.codebaseMapPath, "utf8");
+    return {
+      ok: true,
+      path: paths.codebaseMapPath,
+      map: JSON.parse(raw),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      path: paths.codebaseMapPath,
+      reason: error?.code === "ENOENT" ? "missing" : error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function refreshCodebaseMap(config, options = {}) {
+  if (!config.allowFileTools) {
+    return { ok: false, reason: "workspace file tools disabled" };
+  }
+  const projectRoot = path.resolve(options.projectRoot || config.commandCwd || config.baseDir || process.cwd());
+  const paths = projectPaths(projectRoot);
+  const inspected = await executeWorkspaceTool(
+    "inspect_project",
+    {
+      path: options.path || ".",
+      maxDepth: options.maxDepth || 4,
+      limit: options.limit || 1000,
+      includeFiles: Boolean(options.includeFiles),
+    },
+    {
+      ...config,
+      commandCwd: projectRoot,
+      allowFileTools: true,
+    }
+  );
+
+  if (!inspected?.ok) {
+    return {
+      ok: false,
+      path: paths.codebaseMapPath,
+      reason: inspected?.reason || inspected?.error || "inspect_project failed",
+    };
+  }
+
+  const inspection = compactInspection(inspected);
+  const fingerprint = stableHash({
+    summary: inspection.summary,
+    counts: inspection.counts,
+    manifests: inspection.manifestFiles.map((item) => item.path),
+    sourceDirs: inspection.sourceDirs.map((item) => item.path),
+    tests: inspection.testFiles.map((item) => item.path),
+    packageScripts: inspection.packageScripts,
+    languages: inspection.languageCounts,
+  });
+  const map = {
+    version: MAP_VERSION,
+    generatedAt: new Date().toISOString(),
+    projectRoot: paths.root,
+    commandCwd: projectRoot,
+    fingerprint,
+    inspection,
+  };
+
+  await fs.mkdir(paths.controlDir, { recursive: true });
+  await fs.writeFile(paths.codebaseMapPath, `${JSON.stringify(map, null, 2)}\n`, "utf8");
+  return {
+    ok: true,
+    path: paths.codebaseMapPath,
+    map,
+    contextPack: codebaseMapToContextPack(map),
+  };
+}

package/src/parallel-scouts.js

@@ -2,7 +2,7 @@ import { engineeringGuidanceForTask } from "./engineering-guidance.js";
 import { getModelPresets } from "./model-routing.js";
 import { getTaskProfile, normalizeTaskProfile } from "./task-profiles.js";
 import { redactSensitiveText } from "./redaction.js";
-import { executeWorkspaceTool } from "./workspace-tools.js";
+import { refreshCodebaseMap } from "./codebase-map.js";
 
 const MAX_CONTEXT_PACK_CHARS = 3800;
 const MAX_SCOUT_CONTENT_CHARS = 1200;
@@ -94,60 +94,36 @@ function truncateText(text, limit = MAX_CONTEXT_PACK_CHARS) {
   return `${value.slice(0, limit - 80)}\n... [truncated ${value.length - limit + 80} chars]`;
 }
 
-function listValues(items, limit, mapper) {
-  const values = Array.isArray(items) ? items.slice(0, limit).map(mapper).filter(Boolean) : [];
-  if (!values.length) return "";
-  const suffix = Array.isArray(items) && items.length > limit ? `, ... +${items.length - limit}` : "";
-  return `${values.join(", ")}${suffix}`;
-}
-
-function packageScriptValues(scripts) {
-  if (!Array.isArray(scripts) || !scripts.length) return "";
-  return listValues(scripts, 14, (item) => `${item.name}: ${item.command}`);
-}
-
 async function buildScoutContextPack(config) {
   if (!config.allowFileTools) {
-    return "Context pack: workspace file tools are disabled. Scouts should recommend the minimal inspection commands/files instead of assuming repository structure.";
+    return {
+      text: "Context pack: workspace file tools are disabled. Scouts should recommend the minimal inspection commands/files instead of assuming repository structure.",
+      codebaseMap: null,
+    };
   }
 
   try {
-    const inspected = await executeWorkspaceTool(
-      "inspect_project",
-      { path: ".", maxDepth: 4, limit: 1000, includeFiles: false },
-      {
-        ...config,
-        allowFileTools: true,
-      }
-    );
-    if (!inspected?.ok) {
-      return `Context pack: inspect_project unavailable (${inspected?.reason || inspected?.error || "unknown error"}).`;
+    const refreshed = await refreshCodebaseMap(config, { maxDepth: 4, limit: 1000, includeFiles: false });
+    if (!refreshed?.ok) {
+      return {
+        text: `Context pack: inspect_project unavailable (${refreshed?.reason || refreshed?.error || "unknown error"}).`,
+        codebaseMap: null,
+      };
     }
-
-    const packageScripts = packageScriptValues(inspected.packageScripts);
-    const sections = [
-      `Context pack for ${config.commandCwd}`,
-      `Summary: ${inspected.summary || "no summary"}`,
-      inspected.counts
-        ? `Counts: files=${inspected.counts.files} dirs=${inspected.counts.directories} bytes=${inspected.counts.totalBytes}`
-        : "",
-      `Top level: ${listValues(inspected.topLevel, 20, (item) => `${item.type}:${item.path}`)}`,
-      `Manifests: ${listValues(inspected.manifestFiles, 18, (item) => item.path)}`,
-      `Source dirs: ${listValues(inspected.sourceDirs, 14, (item) => item.path)}`,
-      `Tests: ${listValues(inspected.testFiles, 18, (item) => item.path)}`,
-      `Package managers: ${listValues(inspected.packageManagers, 8, (item) => item.name || item.path || item)}`,
-      packageScripts ? `Package scripts: ${packageScripts}` : "",
-      `Languages: ${listValues(inspected.languageCounts, 10, (item) => `${item.name}:${item.count}`)}`,
-      inspected.git?.present
-        ? `Git: present; start with ${inspected.git.recommendedCommands?.join(" && ") || "git status --short"}; ${inspected.git.workflow}`
-        : "Git: not detected at workspace root.",
-      `Recommended reads: ${listValues(inspected.recommendedReads, 16, (item) => item)}`,
-      `Engineering hints: ${listValues(inspected.engineeringHints, 8, (item) => item)}`,
-    ].filter(Boolean);
-
-    return truncateText(redactSensitiveText(sections.join("\n")));
+    return {
+      text: truncateText(redactSensitiveText(refreshed.contextPack || "")),
+      codebaseMap: {
+        path: refreshed.path,
+        generatedAt: refreshed.map.generatedAt,
+        fingerprint: refreshed.map.fingerprint,
+        summary: refreshed.map.inspection?.summary || "",
+      },
+    };
   } catch (error) {
-    return `Context pack: inspect_project failed (${redactSensitiveText(error instanceof Error ? error.message : String(error))}).`;
+    return {
+      text: `Context pack: inspect_project failed (${redactSensitiveText(error instanceof Error ? error.message : String(error))}).`,
+      codebaseMap: null,
+    };
   }
 }
 
@@ -212,11 +188,44 @@ async function synthesizeScouts(client, config, model, scouts, contextPack) {
   return redactSensitiveText(response.choices[0]?.message?.content || "").trim();
 }
 
+function extractFindings(content) {
+  return String(content || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim().replace(/^[-*]\s+/, "").replace(/^\d+\.\s+/, ""))
+    .filter((line) => line && line.length > 8)
+    .slice(0, 6);
+}
+
+function buildScoutBlackboard({ config, state, model, requested, completed, scouts, contextPack, codebaseMap, synthesis }) {
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    goal: config.goal || state.goal || "",
+    model,
+    requested,
+    completed,
+    codebaseMap,
+    contextPack,
+    coordinator: synthesis || "",
+    lanes: scouts.map((scout) => ({
+      role: scout.name,
+      model: scout.model || model,
+      status: scout.content ? "completed" : "failed",
+      findings: scout.content ? extractFindings(scout.content) : [],
+      content: scout.content || "",
+      error: scout.error || "",
+    })),
+    handoff:
+      "Use this blackboard as advisory shared context. The executor must still inspect exact files, patch deterministically, run focused checks, and stop on conflicts or unrelated dirty work.",
+  };
+}
+
 export async function runParallelScouts(client, config, state) {
   const count = Math.min(Math.max(Number(config.parallelScoutCount) || 3, 1), SCOUTS.length);
   const selected = SCOUTS.slice(0, count);
   const model = scoutModel(config);
-  const contextPack = await buildScoutContextPack(config);
+  const context = await buildScoutContextPack(config);
+  const contextPack = context.text;
   const settled = await Promise.allSettled(
     selected.map(async (scout) => {
       const response = await client.chat.completions.create(
@@ -260,6 +269,17 @@ export async function runParallelScouts(client, config, state) {
   ]
     .filter(Boolean)
     .join("\n");
+  const blackboard = buildScoutBlackboard({
+    config,
+    state,
+    model,
+    requested: selected.length,
+    completed,
+    scouts,
+    contextPack,
+    codebaseMap: context.codebaseMap,
+    synthesis,
+  });
 
   return {
     ok: completed > 0,
@@ -268,6 +288,8 @@ export async function runParallelScouts(client, config, state) {
     completed,
     scouts,
     contextPack,
+    codebaseMap: context.codebaseMap,
+    blackboard,
     synthesis,
     summary,
   };

package/src/project.js

@@ -33,6 +33,7 @@ export function projectPaths(projectRoot = process.cwd()) {
     rootEnvPath: path.join(root, ".env"),
     envExamplePath: path.join(root, ".aginti", ".env.example"),
     controlReadmePath: path.join(root, ".aginti", "README.md"),
+    codebaseMapPath: path.join(root, ".aginti", "codebase-map.json"),
     notesDir: path.join(root, "notes"),
     notesReadmePath: path.join(root, "notes", "README.md"),
     sessionsDir: path.join(root, ".sessions"),
@@ -195,6 +196,7 @@ export async function initProject(projectRoot = process.cwd()) {
       "- `../AGINTI.md` stores editable project instructions for CLI and web agents.",
       "- `.env` is ignored and can hold local provider keys.",
       "- `.env.example` documents accepted variable names.",
+      "- `codebase-map.json` is a generated, ignored project-intelligence cache.",
       "- `.sessions/` at the project root stores CLI and web run history.",
       "",
     ].join("\n")
@@ -227,6 +229,7 @@ export async function initProject(projectRoot = process.cwd()) {
     ".aginti/.env",
     ".aginti/.env.*",
     "!.aginti/.env.example",
+    ".aginti/codebase-map.json",
     ".sessions/",
   ]);
   if (gitignore.changed) updated.push(paths.gitignorePath);

package/src/session-store.js

@@ -38,6 +38,15 @@ export class SessionStore {
     await fs.writeFile(this.planPath, `${planText.trim()}\n`, "utf8");
   }
 
+  async saveJsonArtifact(filename, data) {
+    await this.ensure();
+    const safeName = path.basename(String(filename || "artifact.json"));
+    const outputName = safeName.endsWith(".json") ? safeName : `${safeName}.json`;
+    const filePath = path.join(this.artifactsDir, outputName);
+    await fs.writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    return filePath;
+  }
+
   async appendEvent(type, data = {}) {
     await this.ensure();
     const line = JSON.stringify({