Adopt artifact-first context for judgment-independent agents

README.md

@@ -305,7 +305,7 @@ The [fuseraft VS Code extension](https://github.com/fuseraft/fuseraft-vscode) br
 
 **Activity bar panel** — four persistent views:
 - **Run Task** — compose a task, pick a config, set flags (`--hitl`, `--tools`, `--verbose`, `--devui`), and launch. Each task opens in its own named terminal; multiple tasks can run simultaneously.
-- **Sessions** — lists sessions scoped to your workspace with status, age, and task preview. Click to resume; preview icon opens a formatted transcript with per-turn token usage and cost.
+- **Sessions** — lists sessions scoped to your workspace with status, age, and task preview. Click to resume; preview icon opens a formatted transcript with per-turn token usage.
 - **Configs** — auto-discovers every fuseraft config in your workspace. Click to open, or hit **+** to run the Initialize Config wizard.
 - **Context** — manages reference material agents can access during sessions. Import files or folders; they're stored in `.fuseraft/context/` and available to any session in the workspace.
 

config/examples/fuseraft-designer.yaml

@@ -43,12 +43,10 @@ Orchestration:
         ContextWindow.TextOnly (strip tool frames from history — useful for review agents),
         MaxToolCallsPerTurn, MaxInTurnContextTokens, MaxInTurnToolPairs (sliding-window cap — deterministic
         alternative to MaxInTurnContextTokens; recommended 8–16 for Developer/Tester/Operator),
-        EnableMemory, SubAgentModel, SubAgentPlugins,
-        RemoteAgent.Url (delegate to remote A2A endpoint — ignores Model/Plugins/FunctionChoice/Capabilities).
+        SubAgentModel, SubAgentPlugins, RemoteAgent.Url (delegate to remote A2A endpoint — ignores Model/Plugins/FunctionChoice/Capabilities).
 
         ROUTING:
-        - statemachine: States with Agent, Transitions (Signal, To, optional Contract for evidence gates).
-          Agents signal transitions with handoff(route_keyword: "SIGNAL") or plain keyword on its own line.
+        - statemachine: States with Agent, Transitions (Signal, To, optional Contract for evidence gates). Agents signal transitions with handoff(route_keyword: "SIGNAL") or plain keyword on its own line.
         - magentic: manager LLM selects participants dynamically each round. No routing keywords needed.
         - roundrobin / sequential: agents take turns in order.
         - keyword: routes on text patterns in responses.

docs/configuration.md

@@ -141,7 +141,6 @@ Each entry in `Agents` configures one participant in the group chat.
 | `MaxInTurnToolPairs` | int | `0` | no | Hard sliding-window cap (deterministic) on the number of tool call/result pairs kept in full within a turn. Before every inner LLM call, all but the most-recent N pairs are replaced with placeholders unconditionally — regardless of total token count. `0` means no limit. Recommended: 8–16 for high-volume action agents. |
 | `TrustScore` | number | `0.7` | no | Governance trust score (0.0–1.0) used to assign an execution ring. See [Governance](governance.md#execution-rings). |
 | `ContextWindow` | object | — | no | Filters the conversation history before it reaches this agent. See [ContextWindow](#contextwindow). |
-| `EnableMemory` | bool | `false` | no | When `true`, persistent memories from `~/.fuseraft/memory/agents/{Name}/` are prepended to the agent's instructions at session start. See [Memory](#memory). |
 | `SubAgentModel` | string | — | no | Model ID override for the sub-agent spawned by the `SubAgent` plugin. Defaults to the parent agent's model when unset. Useful for running a cheaper model (e.g. Haiku) for `sub_agent_explore` / `sub_agent_locate` calls. |
 | `SubAgentPlugins` | array | — | no | Explicit list of plugin names to load into the sub-agent. When unset the sub-agent receives the default read-only set: FileSystem read, Search, Shell read, Git read. Unknown names raise an error at session startup. |
 | `SubAgentMaxToolCalls` | int | `0` | no | Maximum tool-call iterations for `sub_agent_explore`. `0` uses the built-in default of 20. `sub_agent_locate` always uses a hard cap of 5 regardless of this setting. |
@@ -229,7 +228,6 @@ Agents:
 | int | inline is non-zero |
 | `TrustScore` | inline differs from `0.7` |
 | `FunctionChoice` | inline differs from `"auto"` |
-| `EnableMemory` | either inline or file is `true` |
 
 This means: to inherit a field from the file, simply omit it in the inline config. To override, set it explicitly.
 
@@ -278,7 +276,7 @@ Delegates an agent slot to a remote process that implements the [A2A protocol](h
 | `Url` | string | — | yes | Base URL of the remote A2A agent. Card is resolved from `{Url}/.well-known/agent.json`. |
 | `TimeoutSeconds` | int | `120` | no | HTTP timeout for card resolution and per-turn calls. |
 
-**Fields that apply when `RemoteAgent` is set:** `Name`, `Instructions`, `TrustScore`, `ContextWindow`, `MaxToolCallsPerTurn`, `EnableMemory`.
+**Fields that apply when `RemoteAgent` is set:** `Name`, `Instructions`, `TrustScore`, `ContextWindow`, `MaxToolCallsPerTurn`.
 
 **Fields that are ignored when `RemoteAgent` is set:** `Model`, `Plugins`, `FunctionChoice`, `Capabilities`, `SubAgentModel`, `SubAgentPlugins` — those are properties of the remote agent.
 
@@ -325,28 +323,15 @@ Filters are applied in order: `TextOnly` / `ExcludeAgents` first, then `MaxTurnA
 
 ## Memory
 
-When `EnableMemory: true` is set on an agent, fuseraft loads that agent's persistent memory store at session start and prepends a structured block to its instructions:
-
-```yaml
-- Name: Developer
-  EnableMemory: true
-  Instructions: You are a software engineer...
-```
+Every agent's persistent memory store is loaded and ranked by relevance before each turn, then
+injected into its system prompt automatically by the context assembly pipeline — no per-agent
+config is required. See [Context Management — Layer 2](context-management.md#layer-2-persistent-memory-pipeline-injected)
+for ranking and injection format details.
 
 **How it works**
 
 Memories are stored as Markdown files with YAML frontmatter in `~/.fuseraft/memory/agents/{Name}/`. An index file (`MEMORY.md`) maintains a one-line-per-entry listing in injection order.
 
-At session start, each memory entry is rendered into the agent's instructions as:
-
-```
-## Persistent Memory
-
-- [memory-name] (type): One-line description of the memory
-```
-
-When `EnableMemory: false` (the default), no memory is loaded and the directory is not read.
-
 **Memory storage location**
 
 | Context | Path |
@@ -371,7 +356,7 @@ When the session ends, the model is asked to extract new memories from the conve
 
 ## Pluggable memory provider
 
-The `Memory` top-level key activates a live memory provider that runs pre- and post-turn hooks around every agent turn. Unlike the static `EnableMemory` flag (which loads once at session start), the pluggable provider fetches fresh context before each turn and can persist the full accumulated history after each turn.
+The `Memory` top-level key activates a live memory provider that runs pre- and post-turn hooks around every agent turn. The provider fetches fresh context before each turn and can persist the full accumulated history after each turn.
 
 ### Providers
 
@@ -416,15 +401,6 @@ Memory:
 | `TimeoutSeconds` | int | `10` | Per-request HTTP timeout. |
 | `SaveEveryNTurns` | int | `10` | Save only every Nth turn; 1 = every turn. |
 
-### Relationship to `EnableMemory`
-
-`EnableMemory: true` on an agent and a top-level `Memory:` provider are independent:
-
-- `EnableMemory` loads memories once at agent creation time (synchronous, from disk).
-- `Memory:` loads fresh context before each turn via the provider (async, per-turn).
-
-Both can be active simultaneously. The injected blocks are additive — the `EnableMemory` block is baked into the agent's static instructions; the `Memory:` block is prepended at turn time.
-
 ---
 
 ## Selection strategy
@@ -708,6 +684,8 @@ Each line is a JSON object:
 
 **`hitl_escalation` payload:** `{ message }` — the error message surfaced to the user when a validator fires 3 consecutive times and the session stalls.
 
+**`context_assembly` payload:** `{ knowledge_retrieved, knowledge_included, memory_loaded, memory_included, artifacts, context_chars, system_prompt_chars, assembly_ms, context_strategy, declared_sources, empty_sources }` (sequential-agent turns add `context_chars_breakdown`, `tool_count`, `tool_schema_est_tokens`). `context_strategy` is `"artifact_spec"` when the agent's `Context:` block drove assembly or `"shared_history_fallback"` when it fell back to `ContextWindow`-filtered shared history — the field to alert on if you expect every Reviewer/Tester/Critic-style agent to be running isolated and want to catch one that silently isn't. `declared_sources` lists the `Context:` sources requested (empty under the fallback strategy); `empty_sources` is the subset that resolved to no content at assembly time — e.g. a `brief_field:` naming a field the Planner never wrote — distinguishing "the spec omitted a needed source" (visible by reading the config) from "the spec named a source that was never produced" (only visible at runtime, via this field).
+
 **Omit** `Events` if you don't need the event stream.
 
 ---

docs/context-management.md

@@ -34,10 +34,6 @@ types — `AgentOrchestrator` (sequential, parallel, verifier), `MagenticOrchest
 agents) all call `AssembleAsync` identically. Most layers are always-on; use `KnowledgeWeight`
 on an agent's config to tune retrieval depth.
 
-> **Upgrading from `EnableMemory`:** `EnableMemory: true` is deprecated. Memory is now
-> runtime-injected by the pipeline every turn and ranked by relevance to the current task.
-> Remove `EnableMemory` from your agent configs — it will be ignored in a future release.
-
 ---
 
 ## Automatic runtime injection
@@ -121,9 +117,6 @@ directory are loaded. Directories without `.fuseraft/` fall back to all global m
 automatically at the end of each session and scoped to the working directory via
 `.fuseraft/memory/sessions/{session_id}/memory_refs.json`. Use `/memory` commands to inspect or delete them.
 
-> **Deprecated:** `EnableMemory: true` on an agent config is no longer needed. Memory is now
-> injected at runtime by the pipeline regardless of this flag.
-
 See [Configuration — Memory](configuration.md#memory) for the full field reference.
 
 ---
@@ -306,6 +299,30 @@ Transitions:
 
 When `Context:` is declared on an agent, the orchestrator assembles that agent's context from disk artifacts instead of filtering or replaying the shared transcript. The agent receives only the declared sources plus its own prior turns — no Planner analysis, no Developer tool traces, nothing from other agents.
 
+> **Recommended for judgment-independent roles.** When every agent shares the same growing
+> transcript (Layer 3), a downstream agent can't distinguish a verified fact from an earlier
+> agent's unverified claim — the conversation itself becomes evidence, and claims compound
+> into hallucinations several turns later. `Context:` spec is the fix: it drives assembly from
+> durable artifacts (`brief.json`, `changes.json`, the evidence graph) instead of replayed
+> chat, so an agent's information diet is exactly what someone deliberately packaged for it.
+> Treat it as the default for roles that render an independent verdict — Reviewer, Tester,
+> Critic, Auditor — and reserve full shared-history replay (`ContextWindow`, below) for
+> collaborative/continuity roles (Planner, Developer mid-phase) and for rapid prototyping,
+> where you don't yet know which artifacts a new agent needs. The `swe`, `greenfield`,
+> `audit`, `research`, `brownfield`, and `devops` templates generated by `fuseraft init`
+> apply `Context:` to their Reviewer/Tester/Critic/Auditor/Verifier-equivalent agents by
+> default — use those as a starting point rather than designing a source list from scratch.
+>
+> **Exception:** an agent whose job is specifically to catch a mismatch between what other
+> agents *claimed* and what the change log / execution state actually shows (e.g. an
+> evidence-auditor `Verifier` that cross-checks "claimed success without evidence" patterns)
+> needs to see the claims to audit them — isolating it via `Context:` would remove the very
+> signal it exists to check. The `swe` template's `Verifier` is intentionally left on shared
+> history for this reason.
+>
+> A declared source resolving to no content is itself a signal worth watching, not just a
+> silent gap — see `empty_sources` in the [`context_assembly` event payload](configuration.md#events) below.
+
 ```yaml
 Agents:
   - Name: Tester
@@ -830,7 +847,15 @@ Compaction:
   TokenBudget: 60000
 ```
 
-**For a downstream agent (Reviewer, Tester) that needs less history:** use `ContextWindow`.
+**For a judgment-independent agent (Reviewer, Tester, Critic, Auditor) in production:** use
+`Context:` spec (Layer 3a) — see below. It's the recommended default for these roles because
+it assembles from durable artifacts rather than replayed chat, so the agent can't mistake an
+earlier agent's unverified claim for a fact. The remaining examples below (`ContextWindow`
+filtering of shared history) are the lighter/compatibility path — reach for them when you're
+prototyping a new pipeline and haven't yet worked out which artifacts a role needs, or for
+roles that are meant to see prior claims (see the exception noted in Layer 3a above).
+
+**For a downstream agent still on shared history that just needs less of it:** use `ContextWindow`.
 
 ```yaml
 Agents:
@@ -840,8 +865,8 @@ Agents:
       MaxTurnAge: 3
 ```
 
-**For an agent that should know nothing about earlier phases:** combine `ExcludeAgents` with
-`MaxTailMessages` so it only sees the final handoff.
+**For an agent that should know nothing about earlier phases but is still on shared history:**
+combine `ExcludeAgents` with `MaxTailMessages` so it only sees the final handoff.
 
 ```yaml
 Agents:

src/Cli/Commands/InitTemplates.Audit.cs

@@ -90,6 +90,11 @@ You are read-only with respect to this project's own files — you have no
             Capabilities:
               FileSystem: [read]
             FunctionChoice: required
+            Context:
+              - Source: session_context
+              - Source: file:.fuseraft/artifacts/audit-findings.json
+                MaxChars: 6000
+              - Source: own_history:2
             {AgentFileOptions}
             """;
 
@@ -158,6 +163,12 @@ so the Prioritizer can update the plan and the Developer can retry.
             Capabilities:
               FileSystem: [read]
             FunctionChoice: required
+            Context:
+              - Source: session_context
+              - Source: file:.fuseraft/artifacts/remediation-plan.json
+                MaxChars: 6000
+              - Source: changes_recent:5
+              - Source: own_history:2
             {AgentFileOptions}
             """;
 

src/Cli/Commands/InitTemplates.Brownfield.cs

@@ -205,8 +205,10 @@ and evidence before your routing keyword.
             Capabilities:
               FileSystem: [read]
             FunctionChoice: auto
-            ContextWindow:
-              TextOnly: true
+            Context:
+              - Source: session_context
+              - Source: changes_recent:3
+              - Source: own_history:2
             {AgentFileOptions}
             """;
 

src/Cli/Commands/InitTemplates.DevOps.cs

@@ -116,6 +116,12 @@ can run the rollback steps.
             Capabilities:
               FileSystem: [read]
             FunctionChoice: required
+            Context:
+              - Source: session_context
+              - Source: file:.fuseraft/artifacts/ops-plan.yaml
+                MaxChars: 4000
+              - Source: changes_recent:3
+              - Source: own_history:2
             {AgentFileOptions}
             """;
 

src/Cli/Commands/InitTemplates.DevTeam.cs

@@ -275,6 +275,9 @@ You are read-only with respect to this project's own files — you have no
             Capabilities:
               FileSystem: [read]
             FunctionChoice: required
+            Context:
+              - Source: session_context
+              - Source: own_history:2
             {AgentFileOptions}
             """;
 

src/Cli/Commands/InitTemplates.Research.cs

@@ -93,6 +93,11 @@ You are read-only with respect to this project's own files — you have no
             Capabilities:
               FileSystem: [read]
             FunctionChoice: required
+            Context:
+              - Source: session_context
+              - Source: file:.fuseraft/docs/research-findings.md
+                MaxChars: 8000
+              - Source: own_history:2
             {AgentFileOptions}
             """;