Context assembly

Use this page to inspect what a specialist saw before it worked, what Guild Stack intentionally left out, and what the specialist handed back when the lane finished.

Every dispatched lane receives a focused context bundle. The bundle is a file, not a vague memory state:

.guild/context/<run-id>/<specialist>-<task-id>.md

Dispatch passes that path by pointer. When a result looks wrong, compare the bundle with the handoff receipt instead of guessing what the agent remembered.

What goes into a bundle

A bundle has three layers:

Layer	Content	Size
Universal	Project identity, run rules, and conventions every lane needs.	Small fixed layer.
Role	The specialist’s standards, required playbooks, and role-specific knowledge.	Protected; not dropped for task material.
Task	Lane objective, source refs, upstream depends_on contracts, matched wiki pages, decisions, and graph-derived hints.	First to shrink under pressure.

• Target total: ~3k tokens.
• Hard cap: 6k tokens.
• Graph sub-cap: 1200 tokens for graph-derived material.
• Proof cue: the deterministic linter checks the finished bundle budget before dispatch.

Included and omitted facts

For a backend lane that implements an approved auth endpoint, the bundle might include:

Included	Why
The lane objective from .guild/plan/<slug>.md.	Keeps the specialist tied to approved scope.
depends_on from the architecture lane.	Carries upstream contract decisions forward.
Relevant .guild/wiki/** decisions about auth and security.	Uses canonical project memory before broad reads.
The specialist playbook and role boundary.	Prevents a backend lane from turning into release or copy work.
Named source refs from the plan.	Gives enough files to start without a project dump.

It might omit:

Omitted	Why
Unmatched wiki pages.	They are not relevant enough for this lane.
Extra graph nodes beyond the sub-cap.	Graph material is useful but droppable.
Raw project-wide transcripts.	The bundle is a focused task brief, not a context dump.
Conflicting low-trust recalled chunks.	Protection quarantines or wraps untrusted content before prompt use.

Budget pressure is deterministic: protect role content, keep matched decisions and open questions, drop graph material first, and record omissions under dropped_for_budget:. Nothing disappears silently.

Recall before read

Context assembly starts from recall. A lane queries project knowledge before opening broad source files. The current implementation combines several channels into one protected result:

Channel	What it reads	Why it matters
Structural	knowledge-graph.json for callers, callees, impact, and dead-code style questions.	Gives code-structure answers without spending model context first.
Wiki waterfall	SQLite FTS, then file BM25, then filesystem scan over .guild/wiki/**.	Keeps .guild/wiki/** canonical while allowing rebuildable indexes.
Knowledge recall	knowledge-recall.json through the KnowledgeGraph ranking path.	Adds ranked graph context after the wiki branch.
Memory transport	MCP, HTTP-MCP, bridge, or filesystem BM25 depending on host capability.	Records degraded retrieval when a stronger transport is unavailable.

Every recalled chunk passes through protectChunks before it reaches the prompt. The protection step probes for injection, classifies trust tier, quarantines flagged content, and wraps non-operator content. That is why the bundle can include project memory without treating every file as equally trusted.

The paired handoff receipt

The bundle is only half of the story. A finished lane writes a receipt under the run directory:

.guild/runs/<run-id>/handoffs/<specialist>-<task-id>.md

The useful debug pair is:

Before work	After work
.guild/context/<run-id>/<specialist>-<task-id>.md	.guild/runs/<run-id>/handoffs/<specialist>-<task-id>.md
What the specialist was allowed to see.	What the specialist claims it did, learned, assumed, or could not complete.
Includes source refs and omissions.	Includes output, assumptions, learnings, escalation notes, and receipt metadata.

Power Users can diff these files between runs to explain changed behavior. Beginner Users can open the handoff to see the work trail without reading every source file. Harness Developers can treat the bundle path plus handoff receipt as the stable cross-host communication boundary.

What the specialist sees

The bundle is the authoritative task brief. Ambient host context can still exist, such as a repo’s AGENTS.md, host memory, plugin skills, and configured MCP servers, but Guild Stack tells the specialist to privilege the bundle when there is a conflict and surface contradictions in its handoff receipt.

On team backends, the launcher restates the bundle path and required playbooks in the pane prompt. The file path is the shared contract across host shapes.

What this is not

• It is not a guarantee that a host has no ambient context.
• It is not an authoritative database; .guild/wiki/** is canonical, while indexes and recall projections are derived and rebuildable.
• It is not auto-promotion. Learning can propose candidates, but promotion into durable wiki or policy remains human-gated.
• It is not a claim that every host has the same memory transport. Capability gaps degrade with an observable signal.

Why this design

Benefit	How context assembly delivers it
Specialists stay on task	The lane receives a short bundle with its objective, role material, and named refs.
Runs are reproducible	The prompt points at a concrete .guild/context/<run-id>/... file.
Failures are debuggable	You can diff bundles, receipts, and source refs between runs.
Costs stay bounded	Recall and graph material are capped before dispatch.
Memory stays honest	Canonical wiki files remain the source of truth; derived indexes only speed lookup.

Source truth

• docs/v2/architecture/modules/context.md - module contract, protected recall, budget linter, and bundle path.
• docs/v2/dispatch-execution.md - task-agent lifecycle, dispatch-by-pointer, recall-before-read, and receipt handoff.
• docs/v2/architecture/modules/communication.md - file-first handoff envelopes, receipts, and artifact bus boundaries.

See also

• Architecture & Lifecycle, where context assembly sits in the lifecycle.
• Project Memory & Wiki Pattern, the wiki categories the assembler reads from.
• Cost-Aware Model Tiering, recall-score threshold and tier auto-score config.
• Configuration reference, defaults.index.* and models.recallScoreThreshold keys.