beads_rust synthesis
Type: agentic-system-analyses/types/agentic-system-synthesis.md
Bounded synthesis
Retain work, then let the caller choose
beads_rust (br) is a local-first issue tracker used as project memory by agents and humans. It retains issues, dependencies, comments and work status, then supplies selected state for later decisions. It is not the executor of the implementation work described in its issues. This account covers the shipped CLI, optional MCP server, library, state admission and maintenance, and agent-facing instructions at commit 53f7a3d30aca8cab3c3e4abdefeade459e8a3089, with an analysis cutoff of 2026-10-16. SRC-1 is the frozen repository; its evidence is inspected implementation and doctrine/design. No target execution, host trace or causal experiment supports this account. External model hosts, dependency internals and Git remotes are outside the implementation boundary (boundary and evidence, Source register).
The runtime is symbolic Rust code. Ordinary CLI creation accepts caller content and configuration, applies storage validation and workflow admission, commits issue state, returns the stored issue and attempts export. The caller retains responsibility for the next action. The optional feature-gated stdio MCP driver separately opens request storage and coordinates mutation, policy refresh and export; its seven registered tools include mutations, alongside twelve resources and four prompts. Neither driver invokes a model or launches an implementation worker in the inspected routes (RT-CMP-beads-rust, RT-RTE-create-issue, RT-RTE-mcp-request).
The memory has two consequential kinds of content. Descriptions, design, criteria, notes and comments supply prose and potentially reasons to later readers. Status, priority, assignment and dependencies supply fixed-rule selection inputs. Both persist in SQLite and eligible issue JSONL, but accepting prose establishes neither its truth nor its adequacy. Initial human/model authorship remains unresolved. Import acquires upstream state through dedicated writers rather than replaying interactive admission checks (MEM-OBJ-issue, MEM-OBJ-dependency, RT-RTE-jsonl-import).
A later br ready filters represented workflow state, dependencies, deferrals and caller criteria, checks external blockers and delivers a sorted, limited projection. A detail read supplies omitted prose and relations. Readiness is conditional on the represented inputs; it is not proof of task value, a reservation or a promise that eligibility will survive until claim. The stronger --claim update rechecks eligibility and assignment transactionally. A plain in-progress status update, although called a claim in the installed blurb, does not inherit that assignment precondition. Same-actor reclaim can be idempotent unless exclusive claiming is configured; actor strings do not authenticate principals (RT-RTE-ready-query, MEM-RTE-state-read, RT-RTE-claim-issue, RT-CLM-work-cycle).
Deliver bounded context, not an autonomous continuation
Context control happens mainly before delivery. MCP prompts project selected fields and cap rows, then return data and guidance as user-role messages. They ask the external host to triage, plan or revise; they neither execute those judgments nor automatically retain resulting recommendations. Description length, default priority and graph connectivity are limited quality proxies. Row caps are not host token budgets, and a status-report period does not itself establish historical activity retrieval (RT-RTE-triage-prompt, MEM-RTE-guided-context).
An additional opt-in path selects mutable ancestor agent_context when a child is shown or enters eligible text-mode start-work output. It delivers at most the root and immediate-parent governing blocks, with source identities; intermediate ancestors can be omitted. This is automatic identifier-based enrichment within a caller-triggered request, not an independently scheduled injection. Structured show attaches blocks, but structured update and MCP detail do not inherit the text-update delivery guarantee. The budget bounds block count, not bytes or tokens. Syntax normalization does not establish semantic safety of the open-shaped context document (MEM-OBJ-agent-context, MEM-RTE-inherited-context).
These instructions can direct an external reader, but delivery does not establish compliance or repair of behavior after host compaction. Omitted content remains reloadable from the store; emitted text is a copy in the host, not a live reference. The inspected mechanisms do not establish host conversation eviction, a per-worker isolated context or a trace summarizer (MEM-BAP-inherited-guidance, MEM-CLM-compaction-scope).
Admit reported completion under a conditional policy
The representative shipped workflow connects ready discovery, detail inspection, stronger claim, external implementation, reasoned closure, queue re-query, export and Git publication. It is a documented caller-led protocol, not a reconstructed successful run. A rejected claim returns the decision to the caller; a rejected closure requires addressing the condition or an allowed explicit bypass. There is no automatic worker recovery established by that sequence (workflow account, WF-CLM-session-delivery).
Gate reporting gives retained evidence a stronger force than advisory prose. A caller supplies a provider, verdict and optional note for an issue's source-status revision and target transition. Code retains scoped history, derives whether required reports suffice and rejects covered non-bypass transitions when they do not. This is implemented acceptance of report sufficiency for workflow admission, not independently verified acceptance of task correctness. Provider strings do not authenticate independent reviewers; the evaluator does not assess the truth of notes (EPI-OBJ-gate-result, EPI-RTE-gate-report, EPI-RTE-gate-check, EPI-RTE-gate-admission).
The qualification is operationally important. Later same-provider reports replace earlier effective verdicts within scope; old status revisions are excluded. Another provider's pass can nevertheless satisfy a named gate despite a fail. Closure checks can inspect recorded criteria and evidence fields, but checked markup and a commit reference do not prove fulfillment. Explicit CLI policy bypass and import-specific admission prevent a universal gate guarantee. Lint likewise checks template presence, not semantic adequacy (EPI-RTE-gate-check, RT-RTE-close-issue, RT-RTE-jsonl-import, EPI-RTE-lint-check).
Separate closure, export and publication
A mutation commit, JSONL export and external Git publication are three different effects. CLI export can fail after a write; MCP can return a committed-but-export-pending error with mutation retry disabled. Close metadata can also fail after closure commits. Recovery therefore requires understanding the reported outcome rather than blindly repeating a mutation. Transactions and locks depend on the database engine, filesystem and cooperating writers; they do not contain arbitrary same-privilege external edits (RT-RTE-create-issue, RT-RTE-mcp-request, RT-RTE-close-issue).
The shipped skill's claim that sync is never automatic conflicts with implemented automatic export attempts. Explicit session-end export remains a conservative instruction, not evidence that automatic paths are absent. Git commit, push and the final up-to-date check remain caller responsibilities, and no supplied trace establishes delivery (RT-CLM-explicit-sync, WF-CLM-session-delivery).
JSONL is not a complete copy of all memory. Mutation events and gate evidence are local; exports omit ephemeral/wisp records and expired tombstones. Tombstoning, purging and restoring a saved JSONL generation have different effects. Ordinary backup deduplication, throttling and rotation preclude a per-edit history guarantee; protected pre-salvage backups have different retention. Restore supplies bytes for later import, not universal database or conversation rollback (MEM-OBJ-event, MEM-RTE-gate-report, MEM-OBJ-history-backup, MEM-RTE-state-withdrawal).
What can change, and what improvement remains unestablished
The strongest supported contribution is durable, revisable work coordination: retained state changes later selection, gate reports change permitted transitions, and ancestor instructions can reach later readers. Backlog-polish prompts afford externally performed revision. These are concrete mechanisms, not demonstrated gains in future capacity. Explicit interaction records and review labels retain evidence, but their inspected consumers do not complete an automatic trace-to-durable-method-to-later-reasoner chain (MEM-RTE-guided-context, MEM-RTE-audit-record, EPI-RTE-gate-admission).
Instruction-file replacement and checksum-gated executable replacement can change future guidance and machinery. Neither route establishes that operational criticism determined the successor or that it improved future action. At the inspected boundary, learning through criticism of a consumed theory is unestablished; exercised reflection and autonomy of project work are separately unestablished. The accepted runtime supplies no condition-by-condition theory-builder assessment to promote into a four-condition verdict. The epistemic account establishes conditional derivation and operational admission, not iterative content-directed theory criticism. These are independent limits, not a single negative grade (RT-RTE-agents-update, RT-RTE-upgrade-binary, bounded epistemic conclusion).
Self-improvement is also unestablished over later invocations and sessions: installation can alter future organization, but evidence-responsive update determination and subsequent behavior causally depending on that update are not demonstrated. The scenario supported here is caller-led issue continuity and conditional workflow control. Actual host compliance, task correctness and productivity require different evidence. Source-linked host traces showing received context, decisions, admitted edits and later reuse would change the operational assessment. Objective-bearing criticism tied to a retained method revision and subsequent use would change the learning/self-improvement assessment; a controlled comparison would be needed for causal benefit. Complete recovery and cross-endpoint comparisons additionally require the omitted branches named below. No new source reads were made for this synthesis.
Limitations
| limitation | affected SRC IDs and record citations | inspected boundary | conclusion prevented | evidence that would resolve it |
|---|---|---|---|---|
| Static evidence, external host and dependency boundary | SRC-1; RT-CMP-beads-rust, RT-RTE-mcp-request, WF-CLM-session-delivery | Inspected implementation and shipped protocol; no execution or host trace; external engines, hosts and remotes excluded | Successful operation, compliance, task correctness, publication, engine correctness and causal productivity benefit | Source-linked execution and host records, dependency-specific evidence and appropriately controlled outcome comparisons |
| Incomplete auxiliary, evaluator and endpoint coverage | SRC-1; MEM-RTE-state-read, MEM-RTE-guided-context, EPI-RTE-gate-admission | Selected queries, prompts and gates; full acceptance/capacity provenance, search/list filters, graph projections and remaining evaluators not audited | Complete policy/evidence inventory, ranking equivalence and system-complete epistemic negatives | Records tracing those retained parts, admission paths, transformations and actual consumers |
| Recovery and portability are bounded | SRC-1; RT-RTE-jsonl-import, MEM-OBJ-event, MEM-RTE-gate-report, MEM-RTE-state-withdrawal | Import/export, deletion and history selections; full merge/reconcile/doctor/WAL paths not audited | Universal losslessness, complete local-evidence roundtrip, every-edit recovery or erasure of external copies | Branch-specific preservation/recovery records and source-linked roundtrip evidence; a broader recovery claim must account for DB-only state |
| Consumer and trace-fed update gaps | SRC-1; MEM-RTE-audit-record, MEM-CLM-compaction-scope, RT-BAP-agent-instructions | Explicit audit/label path, conditional compaction doctrine and installed-file affordance; later semantic consumers and other maintenance/distribution paths unresolved | Complete trace-learning classification, host load policy, semantic compaction activation or evidence-responsive self-improvement | Recorded automatic update inputs, durable outputs and later consumers; activation evidence and linked later operation |
| Source-native sync mismatch and path-specific guarantees | SRC-1; RT-CLM-explicit-sync, RT-RTE-close-issue, MEM-RTE-inherited-context | Never-automatic skill wording versus auto-flush; bypass/import and output-mode distinctions | A uniform sync contract, universal gated closure or universal claim-time instruction delivery | Aligned shipped instructions and implementation; path-specific records supporting any broadened guarantee |
| Profile omits automatic force-branch instruction admission | SRC-1; RT-RTE-agents-update, profile verification limits | The partial write-agency inventory combines generic callers with replacement; the force branch permits machine-driven software-constructed replacement without confirmation | Complete mechanism-level comparison of instruction-replacement agency; not the existing positive automatic-write finding | A profile unit separating the evidenced automatic force branch from unresolved caller admissions |
| Profile omits instruction-replacement curation | SRC-1; RT-RTE-agents-update, profile verification limits | Installed mutable guidance is included, but its recognized-old-guidance replacement is not separately classified in the partial curation inventory | Complete instruction-maintenance transformation inventory; existing positive revision findings remain valid | A separately supported classification of replacement as revision of the retained instruction artifact, without inferring trace learning |