opencode-swarm 7.51.6 → 7.52.1

package/dist/cli/index.js

@@ -52,7 +52,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.51.6",
+    version: "7.52.1",
     description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
     main: "dist/index.js",
     types: "dist/index.d.ts",
@@ -17275,7 +17275,7 @@ function getCanonicalAgentRole(agentName, generatedAgentNames) {
 function stripKnownSwarmPrefix(agentName) {
   return getCanonicalAgentRole(agentName);
 }
-var SEPARATORS, CANONICAL_ROLES_LONGEST_FIRST, CANONICAL_ROLES_SET, AgentOverrideConfigSchema, SwarmConfigSchema, HooksConfigSchema, ScoringWeightsSchema, DecisionDecaySchema, TokenRatiosSchema, ScoringConfigSchema, ContextBudgetConfigSchema, EvidenceConfigSchema, GateFeatureSchema, PlaceholderScanConfigSchema, QualityBudgetConfigSchema, GateConfigSchema, PipelineConfigSchema, PhaseCompleteConfigSchema, SummaryConfigSchema, ReviewPassesConfigSchema, AdversarialDetectionConfigSchema, AdversarialTestingConfigSchemaBase, AdversarialTestingConfigSchema, IntegrationAnalysisConfigSchema, DocsConfigSchema, DesignDocsConfigSchema, UIReviewConfigSchema, CompactionAdvisoryConfigSchema, LintConfigSchema, SecretscanConfigSchema, GuardrailsProfileSchema, DEFAULT_AGENT_PROFILES, DEFAULT_ARCHITECT_PROFILE, GuardrailsConfigSchema, WatchdogConfigSchema, SelfReviewConfigSchema, ToolFilterConfigSchema, PlanCursorConfigSchema, CheckpointConfigSchema, AutomationModeSchema, AutomationCapabilitiesSchema, AutomationConfigSchemaBase, AutomationConfigSchema, KnowledgeConfigSchema, MemoryConfigSchema, CuratorConfigSchema, ArchitecturalSupervisionConfigSchema, KnowledgeApplicationConfigSchema, SkillImproverConfigSchema, SpecWriterConfigSchema, SlopDetectorConfigSchema, IncrementalVerifyConfigSchema, CompactionConfigSchema, PrmConfigSchema, AgentAuthorityRuleSchema, AuthorityConfigSchema, GeneralCouncilMemberConfigSchema, GeneralCouncilConfigSchema, CouncilConfigSchema, ParallelizationConfigSchema, LeanTurboConfigSchema, StandardTurboConfigSchema, LeanTurboStrategyConfigSchema, TurboConfigSchema, PluginConfigSchema;
+var SEPARATORS, CANONICAL_ROLES_LONGEST_FIRST, CANONICAL_ROLES_SET, AgentOverrideConfigSchema, SwarmConfigSchema, HooksConfigSchema, ScoringWeightsSchema, DecisionDecaySchema, TokenRatiosSchema, ScoringConfigSchema, ContextBudgetConfigSchema, EvidenceConfigSchema, GateFeatureSchema, PlaceholderScanConfigSchema, QualityBudgetConfigSchema, GateConfigSchema, PipelineConfigSchema, PhaseCompleteConfigSchema, SummaryConfigSchema, ReviewPassesConfigSchema, AdversarialDetectionConfigSchema, AdversarialTestingConfigSchemaBase, AdversarialTestingConfigSchema, IntegrationAnalysisConfigSchema, DocsConfigSchema, DesignDocsConfigSchema, UIReviewConfigSchema, CompactionAdvisoryConfigSchema, LintConfigSchema, SecretscanConfigSchema, GuardrailsProfileSchema, DEFAULT_AGENT_PROFILES, DEFAULT_ARCHITECT_PROFILE, GuardrailsConfigSchema, WatchdogConfigSchema, SelfReviewConfigSchema, ToolFilterConfigSchema, PlanCursorConfigSchema, ContextMapConfigSchema, CheckpointConfigSchema, AutomationModeSchema, AutomationCapabilitiesSchema, AutomationConfigSchemaBase, AutomationConfigSchema, KnowledgeConfigSchema, MemoryConfigSchema, CuratorConfigSchema, ArchitecturalSupervisionConfigSchema, KnowledgeApplicationConfigSchema, SkillImproverConfigSchema, SpecWriterConfigSchema, SlopDetectorConfigSchema, IncrementalVerifyConfigSchema, CompactionConfigSchema, PrmConfigSchema, AgentAuthorityRuleSchema, AuthorityConfigSchema, GeneralCouncilMemberConfigSchema, GeneralCouncilConfigSchema, CouncilConfigSchema, ParallelizationConfigSchema, LeanTurboConfigSchema, StandardTurboConfigSchema, LeanTurboStrategyConfigSchema, TurboConfigSchema, PluginConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   init_constants();
@@ -17678,6 +17678,13 @@ var init_schema = __esm(() => {
     max_tokens: exports_external.number().min(500).max(4000).default(1500),
     lookahead_tasks: exports_external.number().min(0).max(5).default(2)
   });
+  ContextMapConfigSchema = exports_external.object({
+    enabled: exports_external.boolean().default(false),
+    mode: exports_external.enum(["conservative", "balanced", "aggressive"]).default("balanced"),
+    max_capsule_tokens: exports_external.number().int().positive().default(2000),
+    invalidate_on_hash_change: exports_external.boolean().default(true),
+    agent_profiles: exports_external.record(exports_external.string(), exports_external.string()).default({})
+  });
   CheckpointConfigSchema = exports_external.object({
     enabled: exports_external.boolean().default(true),
     auto_checkpoint_threshold: exports_external.number().int().min(1).max(20).default(3),
@@ -17996,6 +18003,7 @@ var init_schema = __esm(() => {
     tool_filter: ToolFilterConfigSchema.optional(),
     authority: AuthorityConfigSchema.optional(),
     plan_cursor: PlanCursorConfigSchema.optional(),
+    context_map: ContextMapConfigSchema.optional(),
     evidence: EvidenceConfigSchema.optional(),
     summaries: SummaryConfigSchema.optional(),
     review_passes: ReviewPassesConfigSchema.optional(),

package/dist/config/schema.d.ts

@@ -439,6 +439,18 @@ export declare const PlanCursorConfigSchema: z.ZodObject<{
     lookahead_tasks: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type PlanCursorConfig = z.infer<typeof PlanCursorConfigSchema>;
+export declare const ContextMapConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        conservative: "conservative";
+        balanced: "balanced";
+        aggressive: "aggressive";
+    }>>;
+    max_capsule_tokens: z.ZodDefault<z.ZodNumber>;
+    invalidate_on_hash_change: z.ZodDefault<z.ZodBoolean>;
+    agent_profiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type ContextMapConfig = z.infer<typeof ContextMapConfigSchema>;
 export declare const CheckpointConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     auto_checkpoint_threshold: z.ZodDefault<z.ZodNumber>;
@@ -928,8 +940,8 @@ export declare const PluginConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     qa_retry_limit: z.ZodDefault<z.ZodNumber>;
     execution_mode: z.ZodDefault<z.ZodEnum<{
-        strict: "strict";
         balanced: "balanced";
+        strict: "strict";
         fast: "fast";
     }>>;
     inject_phase_reminders: z.ZodDefault<z.ZodBoolean>;
@@ -1081,6 +1093,17 @@ export declare const PluginConfigSchema: z.ZodObject<{
         max_tokens: z.ZodDefault<z.ZodNumber>;
         lookahead_tasks: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    context_map: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        mode: z.ZodDefault<z.ZodEnum<{
+            conservative: "conservative";
+            balanced: "balanced";
+            aggressive: "aggressive";
+        }>>;
+        max_capsule_tokens: z.ZodDefault<z.ZodNumber>;
+        invalidate_on_hash_change: z.ZodDefault<z.ZodBoolean>;
+        agent_profiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
     evidence: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         max_age_days: z.ZodDefault<z.ZodNumber>;

package/dist/context-map/capsule-builder.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Context Capsule Builder
+ *
+ * Constructs role-specific Context Capsules that are injected into delegated
+ * agent system messages. Uses the Context Map to populate file summaries,
+ * builds a per-file read policy based on staleness, and formats the capsule
+ * as a structured markdown document.
+ *
+ * Each agent role (coder, reviewer, critic, test_engineer, sme) has a
+ * dedicated profile that controls which sections are included and how many
+ * files appear in the capsule.
+ *
+ * Uses the `_internals` DI seam pattern so tests can override filesystem
+ * and analysis dependencies without `mock.module` (which leaks across
+ * files in Bun's shared test-runner process).
+ *
+ * All functions accept an explicit `directory` parameter (Invariant 4).
+ * No `process.cwd()` usage. Never throws — returns best-effort capsules.
+ * No `bun:` imports — Node-ESM-loadable (Invariant 2).
+ */
+import * as fs from 'node:fs';
+import type { AgentRole, CapsuleDelegationReason, CapsuleMetadata, ContextCapsule, ReadPolicyEntry, RoleProfile } from '../types/context-capsule';
+import type { ContextMap } from '../types/context-map';
+import { extractFileSummary, isFileStale } from './file-summary';
+import { computeContentHash, createEmptyContextMap, loadContextMap } from './persistence';
+/**
+ * Reuse shared token estimator with capsule-specific floor of 1.
+ * The base estimator returns 0 for empty strings; capsules need at least 1
+ * token to avoid degenerate budget calculations.
+ */
+export declare function estimateTokens(content: string): number;
+/**
+ * Test-only dependency-injection seam. Production code calls through this
+ * object so tests can replace the underlying implementations without
+ * `mock.module` (which leaks across files in Bun's shared test-runner process).
+ * Mutating this local object is file-scoped and trivially restorable
+ * via `afterEach`.
+ */
+export declare const _internals: {
+    readonly loadContextMap: typeof loadContextMap;
+    readonly createEmptyContextMap: typeof createEmptyContextMap;
+    readonly computeContentHash: typeof computeContentHash;
+    readonly isFileStale: typeof isFileStale;
+    readonly extractFileSummary: typeof extractFileSummary;
+    readonly estimateTokens: typeof estimateTokens;
+    readonly readFileSync: typeof fs.readFileSync;
+    readonly existsSync: typeof fs.existsSync;
+};
+/**
+ * Parameters for building a context capsule.
+ * Defined inline — not part of the public API surface.
+ */
+interface BuildCapsuleParams {
+    /** Task ID this capsule is for (e.g. "1.1", "2.3") */
+    task_id: string;
+    /** Which agent role receives this capsule */
+    agent_role: AgentRole;
+    /** Why this capsule was generated */
+    delegation_reason: CapsuleDelegationReason;
+    /** Files relevant to this task */
+    files_in_scope: string[];
+    /** What the task aims to accomplish */
+    task_goal: string;
+    /** Prior rejection reason, if this capsule is for a fix iteration */
+    prior_rejection?: string;
+    /** What needs to be fixed, if applicable */
+    required_fix?: string;
+    /** Repository facts relevant to this task */
+    relevant_facts?: string[];
+    /** Review checklist items, included for reviewer capsules */
+    review_checklist?: string[];
+    /** Coverage targets, included for test_engineer capsules */
+    coverage_targets?: string[];
+    /** Project root directory */
+    directory: string;
+    /** Maximum token budget for the capsule content (default 2000) */
+    max_capsule_tokens?: number;
+    /** Capsule mode: conservative (more files, less pruning), balanced (default), aggressive (fewer files, more pruning) */
+    mode?: 'conservative' | 'balanced' | 'aggressive';
+    /** Whether content hash changes invalidate cached file summaries. Default: true. */
+    invalidate_on_hash_change?: boolean;
+    /** Custom agent profile overrides — maps role names to strategy names */
+    agent_profiles?: Record<string, string>;
+}
+/**
+ * Default capsule construction profiles for each agent role.
+ * Controls strategy, max file count, and which optional sections are included.
+ */
+export declare const DEFAULT_ROLE_PROFILES: Record<AgentRole, RoleProfile>;
+/**
+ * Build a per-file read policy that tells the consuming agent whether to
+ * trust cached summaries or read the original source.
+ *
+ * For each file:
+ * - Not in map → read original (no cached data exists)
+ * - In map but stale (content hash changed) → read original
+ * - In map and fresh → trust summary
+ *
+ * When `contentCache` is provided, the file contents read during staleness
+ * checking are stored in the map so callers can reuse them without re-reading
+ * the filesystem (avoids the redundant double-read in buildCapsule).
+ *
+ * @param files - Relative file paths to build policy for
+ * @param map - The loaded Context Map
+ * @param directory - Project root directory for file resolution
+ * @param invalidateOnHashChange - Whether content hash changes invalidate entries
+ * @param contentCache - Optional output map populated with `filePath → content`
+ * @returns Array of read policy entries, one per file
+ */
+export declare function buildReadPolicy(files: string[], map: ContextMap, directory: string, invalidateOnHashChange?: boolean, contentCache?: Map<string, string | undefined>): ReadPolicyEntry[];
+/**
+ * Build a role-specific Context Capsule for a delegated agent.
+ *
+ * Loads the context map, applies the role profile to determine which
+ * sections to include, builds a per-file read policy, and formats
+ * everything as a structured markdown document.
+ *
+ * Never throws — returns a best-effort capsule even if the context map
+ * is missing or corrupt.
+ *
+ * @param params - Build parameters including task ID, role, files, and directory
+ * @returns The constructed capsule and diagnostic metadata
+ */
+export declare function buildCapsule(params: BuildCapsuleParams): {
+    capsule: ContextCapsule;
+    metadata: CapsuleMetadata;
+};
+export {};

package/dist/context-map/capsule-persistence.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Capsule persistence module — handles saving, loading, deleting, and
+ * listing Context Capsules stored at `.swarm/capsules/{task_id}.json`.
+ *
+ * All functions are synchronous for simplicity and reliability. The module
+ * uses the `_internals` DI seam pattern so tests can override filesystem
+ * operations without `mock.module` (which leaks across files in Bun's
+ * shared test-runner process).
+ *
+ * State lives exclusively under `.swarm/` (Invariant 4). No `process.cwd()`
+ * usage — every function accepts an explicit `directory` parameter.
+ *
+ * No `bun:` imports — this module is Node-ESM-loadable (Invariant 2).
+ *
+ * No imports from capsule-builder to avoid circular dependencies.
+ */
+import * as fs from 'node:fs';
+import type { CapsuleMetadata, ContextCapsule } from '../types/context-capsule';
+/**
+ * Test-only dependency-injection seam. Production code calls through this
+ * object so tests can replace the underlying implementations without
+ * `mock.module` (which leaks across files in Bun's shared test-runner process).
+ * Mutating this local object is file-scoped and trivially restorable
+ * via `afterEach`.
+ */
+export declare const _internals: {
+    readonly writeFileSync: typeof fs.writeFileSync;
+    readonly readFileSync: typeof fs.readFileSync;
+    readonly existsSync: typeof fs.existsSync;
+    readonly mkdirSync: typeof fs.mkdirSync;
+    readonly readdirSync: typeof fs.readdirSync;
+    readonly unlinkSync: typeof fs.unlinkSync;
+    readonly renameSync: typeof fs.renameSync;
+};
+/**
+ * Save a capsule to `.swarm/capsules/{task_id}.json` using an atomic
+ * temp-then-rename write pattern to avoid partial-write corruption.
+ *
+ * Creates the `.swarm/capsules/` directory if it does not exist.
+ *
+ * Returns {@link CapsuleMetadata} with diagnostics. On error, returns
+ * metadata with `success: false` — never throws.
+ */
+export declare function saveCapsule(capsule: ContextCapsule, directory: string): CapsuleMetadata;
+/**
+ * Load a capsule from `.swarm/capsules/{task_id}.json`.
+ *
+ * Returns the parsed {@link ContextCapsule}, or `null` if the file
+ * doesn't exist or the JSON is invalid. Never throws.
+ */
+export declare function loadCapsule(taskId: string, directory: string): ContextCapsule | null;
+/**
+ * Delete a capsule from `.swarm/capsules/{task_id}.json`.
+ *
+ * Returns `true` if the file was deleted, `false` if it didn't exist.
+ * Never throws.
+ */
+export declare function deleteCapsule(taskId: string, directory: string): boolean;
+/**
+ * List all saved capsule task IDs in `.swarm/capsules/`.
+ *
+ * Returns an array of task IDs derived from filenames (stripping the
+ * `.json` extension). Returns an empty array if the directory doesn't
+ * exist. Never throws.
+ */
+export declare function listCapsules(directory: string): string[];

package/dist/context-map/file-summary.d.ts

@@ -0,0 +1,100 @@
+/**
+ * File Summary Population Module
+ *
+ * Incrementally builds FileContextEntry records as agents interact with files.
+ * Uses lightweight regex-based analysis (no external tool calls) to extract
+ * exports, imports, language, and purpose summaries from source content.
+ *
+ * All functions are synchronous and bounded — no filesystem scans,
+ * no subprocess calls, no network requests. This module is designed
+ * to be fast enough to call on every file an agent touches.
+ */
+import type { FileContextEntry } from '../types/context-map';
+/**
+ * Detect the programming language of a file from its extension.
+ *
+ * @param filePath - Relative or absolute file path
+ * @returns Language identifier string, or undefined if the extension is unrecognized
+ */
+export declare function detectLanguage(filePath: string): string | undefined;
+/**
+ * Matches named ESM exports: "export function foo", "export class Bar", etc.
+ * Capture group 1: the exported symbol name.
+ */
+export declare const RE_EXPORT_NAMED: RegExp;
+/**
+ * Matches brace-delimited ESM re-exports: "export { foo, bar }".
+ * Capture group 1: the comma-separated symbol list inside braces.
+ */
+export declare const RE_EXPORT_BRACE: RegExp;
+/**
+ * Matches ESM import statements: "import ... from '...'".
+ * Capture group 1: the module specifier (source path).
+ */
+export declare const RE_IMPORT_FROM: RegExp;
+/**
+ * Matches CommonJS require calls: "require('...')".
+ * Capture group 1: the module specifier.
+ */
+export declare const RE_IMPORT_REQUIRE: RegExp;
+/**
+ * Matches the first JSDoc or block comment in a file.
+ * Capture group 1: the comment body (between slash-star and star-slash).
+ */
+export declare const RE_FIRST_COMMENT: RegExp;
+/**
+ * Maximum number of key symbols to retain per file entry.
+ */
+export declare const MAX_KEY_SYMBOLS = 10;
+/**
+ * Maximum character length for purpose summaries.
+ */
+export declare const MAX_PURPOSE_LENGTH = 200;
+/**
+ * Build a complete FileContextEntry from file content.
+ *
+ * Computes content hash, detects language, extracts exports/imports,
+ * generates a purpose summary from the first JSDoc comment, and
+ * identifies key symbols from export names.
+ *
+ * When an existing entry is provided, mutable fields (hash, language,
+ * purpose, exports, imports, summary, mtime) are refreshed while
+ * accumulated fields (invariants, risks, tests, last_seen_task_ids)
+ * are preserved.
+ *
+ * @param filePath - Relative file path within the project
+ * @param content - Full file content as a string
+ * @param absolutePath - Optional absolute path for filesystem stat (avoids process.cwd() resolution)
+ * @param existingEntry - Optional previous entry to merge with
+ * @returns A complete FileContextEntry
+ */
+export declare function extractFileSummary(filePath: string, content: string, absolutePath?: string, existingEntry?: FileContextEntry): FileContextEntry;
+/**
+ * Populate FileContextEntry records for multiple files at once.
+ *
+ * For each file path, reads content from directory + path, calls
+ * extractFileSummary, and collects the result. Skips files that
+ * don't exist or can't be read.
+ *
+ * When an existing map is provided, entries are merged: new extractions
+ * take precedence for mutable fields while accumulated fields from
+ * existing entries are preserved.
+ *
+ * @param filePaths - Array of relative file paths to populate
+ * @param directory - Project root directory to resolve file paths against
+ * @param existingMap - Optional map of previously populated entries to merge with
+ * @returns Record mapping file paths to their FileContextEntry instances
+ */
+export declare function batchPopulateSummaries(filePaths: string[], directory: string, existingMap?: Record<string, FileContextEntry>): Record<string, FileContextEntry>;
+/**
+ * Check whether a stored context map entry is stale relative to current content.
+ *
+ * Compares the stored content_hash against a fresh SHA-256 hash of the
+ * provided current content. Returns true if the hashes differ, indicating
+ * the file has been modified since the entry was last populated.
+ *
+ * @param entry - The stored FileContextEntry to check
+ * @param currentContent - The current file content to compare against
+ * @returns true if the entry is stale (hashes differ), false if still current
+ */
+export declare function isFileStale(entry: FileContextEntry, currentContent: string): boolean;

package/dist/context-map/persistence.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Context Map persistence module — handles reading, writing, and invalidating
+ * the durable Context Map stored at `.swarm/context-map.json`.
+ *
+ * All functions are synchronous for simplicity and reliability. The module
+ * uses the `_internals` DI seam pattern so tests can override filesystem
+ * and crypto operations without `mock.module` (which leaks across files in
+ * Bun's shared test-runner process).
+ *
+ * State lives exclusively under `.swarm/` (Invariant 4). No `process.cwd()`
+ * usage — every function accepts an explicit `directory` parameter.
+ *
+ * No `bun:` imports — this module is Node-ESM-loadable (Invariant 2).
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import type { ContentHash, ContextMap, ContextMapStaleEntry, DecisionEntry, TaskContextSummary } from '../types/context-map';
+/**
+ * Test-only dependency-injection seam. Production code calls through this
+ * object so tests can replace the underlying implementations without
+ * `mock.module` (which leaks across files in Bun's shared test-runner process).
+ * Mutating this local object is file-scoped and trivially restorable
+ * via `afterEach`.
+ */
+export declare const _internals: {
+    readonly readFileSync: typeof fs.readFileSync;
+    readonly writeFileSync: typeof fs.writeFileSync;
+    readonly mkdirSync: typeof fs.mkdirSync;
+    readonly renameSync: typeof fs.renameSync;
+    readonly existsSync: typeof fs.existsSync;
+    readonly statSync: fs.StatSyncFn;
+    readonly createHash: typeof crypto.createHash;
+};
+/**
+ * Compute a SHA-256 content hash for the given string content.
+ * Returns the hash as a 64-character lowercase hex string.
+ */
+export declare function computeContentHash(content: string): ContentHash;
+/**
+ * Create a new empty ContextMap with sensible defaults.
+ * The `repo_fingerprint` is left empty and populated by the caller later.
+ */
+export declare function createEmptyContextMap(): ContextMap;
+/**
+ * Load the Context Map from `.swarm/context-map.json` in the given directory.
+ * Returns `null` if the file doesn't exist or cannot be parsed (corrupt file).
+ * Never throws.
+ */
+export declare function loadContextMap(directory: string): ContextMap | null;
+/**
+ * Save the Context Map to `.swarm/context-map.json` using an atomic
+ * temp-then-rename write pattern to avoid partial-write corruption.
+ *
+ * Updates `generated_at` to the current timestamp before writing.
+ * Creates the `.swarm/` directory if it does not exist.
+ */
+export declare function saveContextMap(map: ContextMap, directory: string): void;
+/**
+ * Scan all file entries in the context map and detect which ones have
+ * changed or been deleted since the map was last generated.
+ *
+ * Uses an mtime pre-check before computing the expensive SHA-256 hash —
+ * only files with a modified timestamp undergo hashing.
+ *
+ * Returns the list of stale entries. Files that don't exist on disk or
+ * whose content hash differs from the stored hash are included.
+ * This function is read-only and does NOT modify the input map.
+ */
+export declare function markStaleEntries(map: ContextMap, directory: string): ContextMapStaleEntry[];
+/**
+ * Add or update a task history entry in the context map.
+ * Returns a new ContextMap with the entry added/updated (input is not mutated).
+ */
+export declare function appendTaskHistory(map: ContextMap, summary: TaskContextSummary): ContextMap;
+/**
+ * Append an architectural decision to the context map's decisions array.
+ * Returns a new ContextMap with the decision appended (input is not mutated).
+ */
+export declare function appendDecision(map: ContextMap, decision: DecisionEntry): ContextMap;

package/dist/context-map/post-agent-update.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Post-Agent Context Map Update Module
+ *
+ * After an agent completes a task, this module updates the Context Map with
+ * the task's results — files touched, implementation summary,
+ * rejection/review findings, and decisions made. This is the "write-back"
+ * half of the context map lifecycle.
+ *
+ * All functions use the `_internals` DI seam pattern so tests can override
+ * dependencies without `mock.module` (which leaks across files in Bun's
+ * shared test-runner process).
+ *
+ * State lives exclusively under `.swarm/` (Invariant 4). No `process.cwd()`
+ * usage — every function accepts an explicit `directory` parameter.
+ *
+ * No `bun:` imports — this module is Node-ESM-loadable (Invariant 2).
+ */
+import * as fs from 'node:fs';
+import type { ContextMap } from '../types/context-map';
+import { extractFileSummary } from './file-summary';
+import { appendDecision, appendTaskHistory, createEmptyContextMap, loadContextMap, saveContextMap } from './persistence';
+/**
+ * Parameters for updating the Context Map after an agent completes a task.
+ * Captures all relevant context from the agent's work session so that
+ * future agents can understand what happened without re-reading evidence files.
+ */
+export interface PostAgentUpdateParams {
+    /** Task ID (e.g. "1.1", "2.3") */
+    task_id: string;
+    /** Agent role that completed (coder, reviewer, etc.) */
+    agent_role: string;
+    /** Files the agent touched/modified */
+    files_touched: string[];
+    /** Brief summary of what the agent did */
+    implementation_summary: string;
+    /** Task goal description */
+    task_goal: string;
+    /** Final status of the task */
+    final_status: 'completed' | 'failed' | 'blocked' | 'cancelled';
+    /** Reviewer rejection reasons (if any) */
+    rejection_reasons?: string[];
+    /** Review findings (if any) */
+    review_findings?: string[];
+    /** Decisions made during this task */
+    decisions?: Array<{
+        decision: string;
+        rationale: string;
+    }>;
+    /** Project root directory */
+    directory: string;
+}
+/**
+ * Test-only dependency-injection seam. Production code calls through this
+ * object so tests can replace the underlying implementations without
+ * `mock.module` (which leaks across files in Bun's shared test-runner process).
+ * Mutating this local object is file-scoped and trivially restorable
+ * via `afterEach`.
+ */
+export declare const _internals: {
+    loadContextMap: typeof loadContextMap;
+    saveContextMap: typeof saveContextMap;
+    createEmptyContextMap: typeof createEmptyContextMap;
+    extractFileSummary: typeof extractFileSummary;
+    existsSync: typeof fs.existsSync;
+    readFileSync: typeof fs.readFileSync;
+    readdirSync: typeof fs.readdirSync;
+    realpathSync: typeof fs.realpathSync;
+    appendTaskHistory: typeof appendTaskHistory;
+    appendDecision: typeof appendDecision;
+};
+/**
+ * Extract reviewer/critic findings from .swarm/evidence/ files for a task.
+ *
+ * Looks for reviewer and test-engineer evidence files under
+ * `.swarm/evidence/{taskId}/`, parses them, and returns consolidated
+ * rejection reasons and findings.
+ *
+ * Tries both `test-engineer.json` and `test_engineer.json` filenames to
+ * handle naming inconsistencies across the repo.
+ *
+ * Evidence files may contain:
+ * - `verdict`: string (e.g. "APPROVED", "approved", "pass", "REJECTED") —
+ *   non-approval verdicts are collected as rejection reasons. Case-insensitive.
+ * - `issues`: array of objects with a `message`, `detail`, or `description`
+ *   string field — each is collected as a finding.
+ * - `findings`: array of objects with a `message`, `detail`, or `description`
+ *   string field — also collected as findings.
+ *
+ * Never throws — returns empty arrays on any error (missing directory,
+ * unreadable files, malformed JSON, etc.).
+ *
+ * @param taskId - Task ID (e.g. "1.1", "2.3")
+ * @param directory - Project root directory
+ * @returns Consolidated rejection reasons and review findings from evidence
+ */
+export declare function extractEvidenceFindings(taskId: string, directory: string): {
+    rejection_reasons: string[];
+    review_findings: string[];
+};
+/**
+ * Update the Context Map after an agent completes a task.
+ *
+ * This is the "write-back" half of the context map lifecycle. It:
+ * 1. Loads the existing context map (or creates an empty one)
+ * 2. Refreshes file summaries for all touched files, preserving accumulated data
+ * 3. Appends a TaskContextSummary entry for the completed task
+ * 4. Appends any architectural decisions made during the task
+ * 5. Saves the updated map and returns it
+ *
+ * Never throws — on any error, returns the best-effort context map
+ * (either the existing one or a fresh empty one).
+ *
+ * @param params - Parameters describing the completed task and its results
+ * @returns The updated ContextMap
+ */
+export declare function updateContextMapAfterAgent(params: PostAgentUpdateParams): ContextMap;