Amanuensis synthesis
Type: agentic-system-analyses/types/agentic-system-synthesis.md
Bounded synthesis
From a survey request to durable codebase memory
Amanuensis combines an agent-operated survey method, a deterministic MCP state service and a documentation renderer. The host model owns source interpretation and continuation; the service admits, retains and selects records; Python projects them into HTML and Markdown. Its intended product is a reusable account of a codebase, rather than a saved conversation. This analysis covers the shipped system at Git commit a98093dc7aad3c0e64d42132ece305fc5ea7f3f9, with an applicability cutoff of 2026-11-08. SRC-1 is the repository https://github.com/nfeldman/amanuensis. The whole-system functional boundary includes prompts, maintenance, callers, state service, publication and evaluation surfaces, but does not imply every included handler was fully traced. The evidence is inspected implementation and shipped doctrine/design. No target execution, inspected trial or causal experiment establishes actual survey quality, host compliance or longitudinal benefit. External host/provider internals and private populated stores are outside the supplied evidence (boundary, Source register).
The representative workflow is a requested subsystem survey, selected because one shipped procedure joins scoping, structural reading, concern assessment, adversarial review and delivery. The coordinator verifies the workspace, distinguishes cold from warm state, starts a session and fixes a survey revision. The MCP server binds a workspace, validates requests and lazily opens SQLite. A conflicting explicit handshake is refused, but an omitted handshake cannot disclose the caller's unstated intended workspace. Service binding is not host filesystem isolation (RT-RTE-tool-dispatch).
Phases 1–4 may be delegated to host Task agents or run inline. Each handoff supplies the relevant phase reference, subsystem/session IDs and survey SHA, with a short summary prescribed to return while substantive work is persisted. Selective reference loading and separate phase contexts are requested controls over working context, not server-implemented isolation or chat compaction. Inline fallback provides no such separation. Phase 5 is explicitly coordinator-only: it integrates criticism, settles explanations and publishes. The workflow is afforded by instructions and supported by concrete state handlers; successful end-to-end execution is unobserved (RT-RTE-survey-cycle, RT-CMP-host-model, workflow account).
What admission and criticism establish
The conspectus retains natural-language claims, findings, explanations and prose alongside symbolic evidence links, revisions, validity intervals and workflow standing. SQLite stores typed state; registered prose lives in files; storage Git checkpoints support recovery. The ordinary survey assigns authorship to models without per-content human approval. A session or actor label is not authenticated human identity. Registration is also distinct from writing or approving prose: an artifact can be registered before its file exists (MEM-OBJ-claims, MEM-OBJ-findings, MEM-OBJ-explanations, MEM-OBJ-prose-artifacts).
The discriminating control is record authority, not an automatic truth oracle. Evidence admission retains caller-supplied excerpts without fetching and comparing their source lines. Claim admission checks revision ancestry, evidence eligibility and current-key constraints, then grants current recorded authority before later challenge. Disposition quality is bounded by supplied evidence-kind labels, whose semantic accuracy is still the caller's responsibility. These are real enforcing gates, but a valid record can contain a mistaken interpretation (EPI-RTE-evidence-record, EPI-RTE-claim-admission, EPI-RTE-concern-disposition).
Phase 4 asks the reviewer to find actual overturning mechanisms, not to manufacture balance. It can change findings, restrict scope and retain criticisms of particular explanation sentences for packaging. Code checks current-session evidence custody for an overturn, not semantic disproof. Structured claim-challenge outcomes separately govern ordinary completion progression; a field note alone is not that outcome row. Both ordinary forward status writers check prerequisites, but a transition from deferred bypasses the ordered prerequisite walk. Explanation discharge into mapped remains separately enforced. Thus mapped standing does not universally certify that challenge occurred (WF-RTE-adversarial-review, EPI-RTE-claim-challenge, RT-RTE-survey-cycle).
Corrections have consequential consumers. Claim invalidation closes an exclusive validity interval; supersession atomically introduces a newly supported successor. Default current readers omit the predecessor while history preserves it. Explanations instead use append-only whole-body replacement: the newest eligible resolvable row can record an account, decline the slot or withdraw it. Decline/withdrawal does not silently revive an older positive account, and Git resolvability is not freshness. Repair handling separately keeps coarse fixed status pending until an explicit verification call supplies qualifying attachment, session and revision custody. That verifies the recorded verification assertion, not test success (EPI-RTE-claim-withdrawal, MEM-RTE-explanation-cycle, EPI-RTE-explanation-selection, EPI-RTE-finding-resolution).
Later consumption, recovery and delivery
A later agent normally requests retained content through describe_locus or dedicated readers. Locus delivery preserves standing, census and omission accounting while reducing selected items under byte budgets. An untruncatable floor can exceed the intended budget; a separate hard ceiling refuses oversized responses. This is deterministic selection, not a model-generated summary or removal of old host turns. Returned standing guides the answering model, but delivery does not establish compliance. Examined-stale standing can still authorize content rather than withdrawing everything on drift (RT-RTE-locus-read, MEM-BAP-recorded-standing, epistemic conclusion).
Task-context preparation is a distinct route. Persisted CodebaseBriefs force requested registry matches and required content, then rank optional candidates by lexical matching under an item budget. Design planning automatically narrows the stored brief into lens-specific packets for dispatch. Requested lookup is pull; automatic supply of selected retained parts to a design lens is push within that larger requested workflow. Forced selections precede optional mode filtering, so mode labels do not guarantee exclusion of all off-mode content. Packet separation is not proof of fresh, blind host contexts, and an item limit is not a token budget (MEM-OBJ-codebase-brief, MEM-RTE-brief-delivery).
Refresh and rebuild preserve different obligations. Clearing staleness asserts re-examination and changes backlog membership; it does not prove the file was read. Carrying an archived finding imports an obligation to decide, not fresh confirmation. Archived-terminal handling remains historical closure, while new-store discharge requires its own evidence relationships. A mistaken terminal carry outcome has no established straightforward same-pair recarry recovery (EPI-RTE-staleness-clear, MEM-RTE-carry-recheck).
The coordinator recovers from a refused phase advance by diagnosing the missing deliverable, retrying once and then deferring independent work if necessary. Durable status, dispatch history and checkpoints support resumption, not restoration of private reasoning. The packaging reference closes the session before its final checkpoint, although that checkpoint requires an active session; literal completion therefore needs reordered operations or a reopened session. Delivery is prescribed as the returned HTML entrypoint plus counts, unresolved questions and explanation decisions. Open explanation slots can be published as visible incompleteness (RT-RTE-survey-cycle, workflow account).
Generated views remain derived from SQLite and registered prose. MCP publication preflights HEAD reconciliation, but standalone Python does not inherit that preflight or MCP output containment. Normal non-clean rendering writes before verification. Preservation of the previous view belongs to failed verified clean rendering, subject to filesystem recovery behavior; clean mode with verification disabled can still promote on ok. Readback checks correspondence with retained state, not the truth of the codebase account (RT-RTE-docs-publication).
Evaluation and future change
Amanuensis has more than one evaluation domain. Sealed review aggregation derives survived, defeated or contested keys from role judgments and evidence fan-in. Reference scoring checks agreement and stability against caller-supplied sealed keys; it neither authenticates their correctness nor demonstrates a component's causal benefit. Imported research retains access/confidence restrictions and excerpts, but its consumption receipt records claimed use rather than mutating the destination. Decision acceptance separately changes recorded authority, not application code (EPI-RTE-review-aggregation, EPI-RTE-review-scoring, EPI-RTE-research-landing, EPI-RTE-research-consumption, RT-RTE-decision-admission).
The strongest supported improvement-related contribution is a wired outcome-to-policy admission service: terminal artifact extraction, separately authored lessons/configurations, qualification from supplied measurements, staged activation and transactional reader comparison. Reasons persist in a lesson ledger but are omitted from the active-policy response. This is more than inert logging, but the records do not establish a future host consumer whose behavior depends on that configuration. Neither improved capacity for future action nor exercised self-improvement follows from its active label (MEM-OBJ-learning-lessons, MEM-OBJ-learning-policy, RT-RTE-policy-admission).
The properties remain separate. For the inspected explanation route, localized whole-body content/replacement affords theory-builder condition 1. Consumption of that content, sentence-directed criticism and revision, and carrying the result into packaging address conditions 2–4 in the prescribed method; exercised satisfaction of each is unestablished. No evidence shows that criticism of a consumed theory improved future capacity. Autonomous survey continuation is requested without per-phase human gates, not demonstrated autonomous theory building. Reflection's two causal directions are not established by storing self-related outcomes, and policy activation does not close the later behavioral-dependence link required for exercised self-improvement. Other included review/design/evaluation paths prevent turning these bounded findings into system-wide negatives (EPI-RTE-explanation-record, WF-RTE-adversarial-review, RT-CLM-autonomous-survey, epistemic conclusion).
For a later codebase-orientation question, the supported capacity is therefore revision-aware retrieval with explicit standing, correction history and bounded context delivery. It is not established accurate architectural knowledge or saved verification effort over changing projects. Linked source/evidence comparisons and execution traces would strengthen that assessment; longitudinal comparisons would address utility. A concrete future-policy consumer and evidence of subsequent dependence would change the improvement assessment. Fixing checkpoint order, carry correction and the conditional completion/publication paths would change their respective guarantees, not by itself establish semantic correctness or benefit (EPI-CLM-earned-reliance, report verification).
Limitations
| Limitation | Affected SRC IDs and record citations | Inspected boundary | Conclusion prevented | Evidence that would resolve it |
|---|---|---|---|---|
| No inspected execution or longitudinal comparison | SRC-1; RT-RTE-survey-cycle, EPI-CLM-earned-reliance | Frozen implementation and doctrine; repository receipts not used as operation evidence | Successful survey execution, actual content accuracy, saved work or causal benefit | Provenance-linked runs and code comparisons; longitudinal outcome comparisons with stated controls |
| External host execution remains opaque | SRC-1; RT-CMP-host-model, RT-RTE-tool-dispatch | Shipped handoffs and service, not provider/host internals | Guaranteed isolation, model compliance, exact model fixity or parameter-update conclusions; universal MCP control over shell/direct writers | Host grants, context assembly and provider/version evidence tied to an execution |
| Gates check bounded custody and eligibility | SRC-1; EPI-RTE-evidence-record, EPI-RTE-claim-admission, EPI-RTE-finding-resolution | Inspected evidence, claim and repair handlers | Semantic proof of admitted claims or verified repairs; authenticated human approval | Checked source-to-claim support and repair outcomes, plus authenticated approval where claimed |
| Deferred status bypasses the forward prerequisite walk | SRC-1; RT-RTE-survey-cycle, EPI-RTE-claim-challenge | Public status writers and separate mapped explanation discharge | Universal completed-challenge inference from mapped status; no exercised bypass is established either | Revised transition enforcement or explicit completion provenance for a particular store |
| Publication guarantees depend on route/options | SRC-1; RT-RTE-docs-publication | MCP wrapper, standalone entry, clean/default/no-verification paths | Unconditional readback, rollback or MCP preflight/containment across publication routes | Enforced verified-clean policy and equivalent alternate-path controls; execution evidence for recovery |
| Final checkpoint ordering defect; carried from report verification | SRC-1; RT-RTE-survey-cycle, workflow delivery, verification limit | Packaging closes active session before a gate requiring one | Literal prescribed sequence completes its final checkpoint without adjustment | Corrected order or explicit reopen protocol, with a linked completion trace; narrower durable state and close-time commit attempt remain supported |
| Terminal carry correction unresolved; carried from report verification | SRC-1; MEM-RTE-carry-recheck, verification limit | Carry handler and included rebuild caller | Working same-pair rollback/retry after a mistaken terminal outcome | A concrete correction/recovery mechanism consistent with uniqueness constraints |
| Included alternative chains incompletely traced; carried from report verification | SRC-1; memory inventory, epistemic inventory, RT-RTE-policy-admission, verification limit | Selected maintenance, composition, program-evaluation, adapter-recovery and broader driver-consumer surfaces | Complete admission/invalidation/update/consumer comparisons; system-wide absence of acceptance, integration, theory building or adaptation | Records tracing material alternative payloads, admission, withdrawal, evaluators and later consumers |
| Selection is not full-object delivery or host blindness | SRC-1; RT-RTE-locus-read, MEM-RTE-brief-delivery | Locus reduction and brief-to-lens packet chain | Universal target-budget adherence, complete field delivery, off-mode exclusion or independent model contexts | Consumer-visible payload audits and host isolation evidence; revised forced-selection policy where exclusion is intended |
| Policy activation has no established future behavioral dependency | SRC-1; RT-RTE-policy-admission, MEM-OBJ-learning-policy, MEM-OBJ-learning-lessons | Extraction, authored proposals, qualification, active representation and internal readback | Qualifying trace-learning/source classification, improved future capacity, reflection or exercised self-improvement from this route | Original trace provenance, configuration semantics, concrete later consumer and evidence-responsive subsequent behavioral dependence; outcome comparisons for success |
| Initial control and trace origin remain unresolved | SRC-1; MEM-OBJ-file-ledger, MEM-OBJ-query-log | Known subsequent ledger maintenance and caller-reported usage | Complete provenance/admission inventory or authenticated human-query origin | Initial writer/admission trace and original usage-source evidence |
| Body-level form inventory omission; carried from profile verification | SRC-1; MEM-OBJ-codebase-brief, MEM-OBJ-learning-lessons, verification limit | Profile's partial form inventory omits separate natural-language treatment of brief objective/constraints/inherited statements and lesson proposition/provenance | Complete object-by-object form inventory or form-prevalence comparison; supported natural-language and symbolic findings remain valid | Explicit enumeration of those body parts in the form inventory |