feat(gastown): Convoy context sharing — inject prior bead summaries into agent prompts

[jrf0110]

Summary

Agents working on convoy beads have no awareness of what previous agents in the convoy did, decided, or discovered. Each polecat starts fresh. This leads to duplicated exploration, contradictory decisions, and missed context from earlier beads.

Solution

Two complementary mechanisms — one automatic, one organic. Neither requires new tools or external storage.

1. Automatic: Inject prior bead summaries into the agent prompt

When a polecat calls gt_done, the agent_done event already carries a summary field describing what was accomplished. This summary is already stored as part of the bead/event data in TownDO SQLite.

When dispatching an agent for bead N in a convoy, the system prompt includes the titles and summaries from all previously-closed beads in the same convoy:

## Prior work in this convoy

Bead 1 — "Explore codebase and plan architecture" (completed by Toast):
> Analyzed the repo structure. Auth uses JWT with RSA256 in src/auth/.
> Tests use vitest. Chose Hono for the new API routes. Wrote schema
> definitions in src/schemas/. Discovery doc at .gt/discovery/bead-1.md.

Bead 2 — "Implement user registration endpoint" (completed by Maple):
> Added POST /api/users/register with Zod validation. Password hashing
> via bcrypt. Tests added in test/routes/register.test.ts. All tests pass.

This is assembled at dispatch time with a single SQL query:

SELECT b.title, b.summary, b.status, am.role,
       (SELECT name FROM beads WHERE bead_id = b.assignee_agent_bead_id) as agent_name
FROM beads b
JOIN bead_dependencies bd ON bd.bead_id = b.bead_id
WHERE bd.depends_on_bead_id = :convoy_id
  AND bd.dependency_type = 'tracks'
  AND b.type = 'issue'
  AND b.status IN ('closed', 'failed')
ORDER BY b.closed_at ASC

The summaries are included in the bead body or system prompt context that the container plugin injects (similar to how the GASTOWN CONTEXT block is injected today).

Context window management

If the convoy has many completed beads, the accumulated summaries could get large. Mitigation:

• Cap at the last 10 bead summaries (most recent context is most relevant)
• Truncate each summary to 500 characters
• For convoys with >10 completed beads, summarize the first N into a one-paragraph overview and include the last 5 verbatim

2. Organic: Discovery document convention via prompt guidance

For detailed architectural context that does not fit in a summary, encourage agents to write discovery documents to the repo. This is not a tool — it is prompt guidance in the polecat system prompt:

When working on exploration or planning beads, write your findings and
decisions to .gt/discovery/<bead-title-slug>.md in the repo. Subsequent
agents in the convoy will read these documents for detailed context.

The .gt/discovery/ directory:

• Lives on the convoy feature branch (not main)
• Is committed and pushed like any other file
• Is visible to subsequent polecats who check out the same branch
• Is cleaned up in the landing MR (the refinery or landing polecat deletes .gt/ before the final merge)

Add .gt/ to the landing MR prompt instructions: "Remove any .gt/discovery/ files before merging to the target branch."

Why NOT a new tool or KV storage

• No gt_share_context tool: Agents already have a crowded tool list. An optional context-sharing tool would rarely be used in practice — LLMs are bad at the meta-cognitive task of deciding what is worth sharing. The summary from gt_done captures this automatically.
• No KV storage: The summaries already exist in TownDO SQLite (bead records). No need to duplicate to another storage layer. The SQL query at dispatch time is negligible cost.

Implementation

Dispatch path changes

In container-dispatch.ts or the reconciler's applyAction('dispatch_agent'), when the bead being dispatched is part of a convoy:

1. Query closed beads in the convoy (SQL above)
2. Format as the "Prior work in this convoy" block
3. Include in the beadBody or systemPromptSuffix passed to startAgentInContainer

Prompt template changes

In the polecat system prompt (src/prompts/ or the container plugin's gastown context injection):

• Add the discovery doc convention guidance
• Add the .gt/ cleanup instruction for landing MR beads

Acceptance Criteria

• Convoy bead dispatch includes summaries from previously-closed beads in the prompt
• Summaries are ordered chronologically (oldest first)
• Context is capped/truncated for large convoys
• Polecat system prompt encourages .gt/discovery/ docs for detailed context
• Landing MR instructions include .gt/ cleanup
• No new tools added to the agent tool list
• No external storage dependencies (uses existing TownDO SQLite data)

References

• Reconciler spec — dispatch_agent action
• PR feat(gastown): implement town reconciler with event-driven state management #1336 — Reconciler implementation (dispatch path)
• container/src/agent-runner.ts — buildKiloConfigContent, agent prompt assembly