OpenClerk synthesis

Type: agentic-system-analyses/types/agentic-system-synthesis.md

Bounded synthesis

A knowledge layer operated by an external agent

OpenClerk implements a local knowledge interface for coding agents, not their enclosing model/tool scheduler. It combines canonical Markdown, derived SQLite views, citation-bearing retrieval, explicit session-artifact planning and document maintenance. This account concerns the shipped whole-system boundary at commit 092fb98d243c2d9d95867ad04618ebce88983552, with cutoff 2026-10-16. SRC-1 supplies implementation and doctrine/design evidence, not an observed run or causal experiment. The boundary includes shipped instructions, modules, examples and evaluation callers; external hosts, provider internals and private vault contents are excluded. Whole-system scope does not mean exhaustive implementation inspection (boundary and source register).

The intended progression is to inspect readiness, request task context, read cited evidence, perform application work outside OpenClerk, submit explicit after-work evidence, then apply separately approved knowledge changes. An external agent chooses requests and interprets results under shipped natural-language instructions. Deterministic Go code owns selection, planning and individual command effects. Returning an instruction-bearing JSON handoff does not give OpenClerk control over the host or prove compliance (RT-OBJ-agent-contract, RT-BAP-skill-routing).

Select context before work

A requested context pack prefers an explicit query over task text, searches retained material and looks up decisions. It returns selected snippets, citations, decision summaries and warnings, with path-prefix and count limits. Full documents require another request. Selection therefore controls incoming external material, not the host's accumulated context window; count limits are not a demonstrated token budget, and citations are reload handles rather than automatically dereferenced pointers (RT-RTE-context-pack).

Markdown is authoritative by product contract, but ordinary ID lookup and lexical search actually consume the synchronized SQLite mirror and chunks. A raw file edit need not be visible to an initialized read-only request until synchronization. Full vault synchronization selects nonsymlink Markdown under configured ignores, imports content, prunes missing document rows and rebuilds derived access state. It is not a whole-vault transaction or a universal withdrawal guarantee (MEM-OBJ-documents, MEM-OBJ-chunks, MEM-RTE-vault-sync).

Primitive graph, record, service and decision reads offer other views. Their parser-relative structures do not independently validate their source assertions. Fixed-path policy recall is another distinct selector: much of its returned policy description is code-authored from file-presence and token tests, not general interpretation of policy prose (MEM-RTE-projection-read, MEM-RTE-policy-recall).

Semantic retrieval is explicit, not the default context-pack search. Its configured route requires an installed, enabled, verified module binding, invokes a local subprocess and ranks chunks using provider embeddings. Retained vectors and symbolic identity fields form a reusable file cache; they are not newly trained model weights. Cache identity checks gate reuse, but provider/model names do not pin immutable weights. Cache writes can fail without failing the search. Direct adapter requests can also select a fallback provider that the runner does not forward. Local executable hashes neither sandbox the subprocess nor establish provider reliability or retrieval benefit (RT-RTE-semantic-search, RT-RTE-module-install, MEM-OBJ-semantic-cache, RT-CMP-embedding-provider).

Turn an explicit session artifact into a proposal, then a document

The representative workflow uses the shipped auth-callback session-to-docs example. Its handoff asserts completed work and suggests source-note or decision updates; those are fixture claims, not verified application changes. Chronicler receives an explicit local artifact and delegates deterministic artifact planning, not model authorship. The planner derives candidate fields, searches for duplicates and may return a serialized create request. Its first-hit duplicate heuristic and confidence gate can withhold that convenient request, but do not universally prevent a caller from constructing another write (workflow account, WF-RTE-artifact-plan).

Chronicler delivers selected fields and a compact body summary; fuller proposed text may occur inside the serialized request. Per-file rejection becomes a blocker while processing can continue; a returned Go error aborts. Within RunOnce, inbox planning precedes the accompanying context construction. The separate pre-work context step belongs to the agent contract, not that internal order. Planning delivery ends at a zero-document-write envelope. Durable delivery needs another admitted lifecycle request; the example supplies no receipt or later-use trace (RT-RTE-session-plan, WF-RTE-artifact-plan).

Human approval is an external policy, not a universally authenticated gate. Omitted approval mode defaults to approve_write; checked runner branches reject explicit propose_only. Runner locks coordinate cooperating writers using the same database path, not raw editors or every lower-level caller. Creation writes Markdown before synchronizing derived state, so an error can leave a file written. Replacement compensation is another explicit request, not automatic rollback. Moves likewise have sequential partial-failure exposure (RT-CLM-approval-boundary, RT-RTE-document-write, MEM-RTE-document-move).

Acquisition has separate limits. Web extraction imports assertions rather than endorsing them; HTML transformation can lose relationships. OCR module/file/process checks and nonempty text establish extraction availability, not transcription accuracy. Its review-required candidate still needs separate adoption. Original PDF bytes and optional video metadata assets are distinct from extracted notes; their retention does not establish ordinary-agent consumption (EPI-RTE-web-import, EPI-RTE-artifact-ocr, MEM-OBJ-source-assets).

Maintain source currency without equating it with truth

The strongest supported adaptive contribution is implemented source-sensitive maintenance: OpenClerk can derive currency metadata and durably replace an existing synthesis Summary using a classified current source. This is more than passive storage. The unresolved question is whether a particular correction is substantively warranted and improves later action; no supplied run or comparison establishes that benefit (EPI-RTE-synthesis-freshness, EPI-RTE-audit-repair).

Compilation preserves caller body/facts, adds narrow source-role material and chooses create versus update. Missing source lookup can continue with a path-only citation. Duplicate-target and mode checks govern storage admission, not evidence-consuming acceptance of the body's claims. Generated freshness: fresh text is separate from computed projection currency. The latter depends on stored paths, timestamps and supersession declarations; it supports metadata-relative derivations, not source truth or general factual acceptance (EPI-RTE-synthesis-build, EPI-RTE-synthesis-write, EPI-RTE-synthesis-freshness).

Repair requires exactly one existing target, current and superseded source classes, and a nonempty Summary from the first sorted current source. It copies that summary with role references and a scope disclaimer. The separate conflict recognizer tests a finite set of number/day patterns in search snippets. Compatible subjects can be flagged; unsupported quantities can be missed. Conflict reporting follows possible replacement, not a pre-write semantic veto. Repair is also a retrieval-family mutation, so the ordinary document-family approval account is not the whole admission inventory (EPI-RTE-audit-repair, EPI-RTE-audit-conflicts).

Evaluate bounded outcomes, not an undifferentiated intelligence property

Retrieval capture retains reduced selectors and result identities; replay compares overlap, top-result agreement and latency. Even two empty result sets can agree perfectly. These are regression criteria, not relevance or truth labels, and replay does not itself adopt a new ranker. The separate shipped Codex driver orchestrates bounded scenarios and session-ID continuation; its cited document oracle checks required and forbidden strings. Neither source inspection nor these predicates establishes successful task execution, a component's causal benefit or automatic product-successor admission (EPI-RTE-eval-capture, EPI-RTE-eval-replay, RT-RTE-eval-turn).

For a later task needing cited local evidence, implemented request-driven retrieval and durable source-sensitive maintenance are the supported capacities. For independently warranted knowledge production, authenticated human consent or demonstrated learning benefit, the account remains insufficient. Retained evidence can reach future agents, but delivery is not proof of content-dependent reliance (MEM-BAP-retained-evidence).

The runtime does not establish a formulated-theory route supporting a condition-by-condition theory-builder verdict. Conditions 1–4 therefore remain unestablished rather than inferred from storage, retrieval, repair or evaluation scores. Improved future capacity caused by criticism of a consumed theory is separately unestablished: summary replacement records source classification, not that criticism-and-benefit chain. Reflection is also not established merely by stored provenance, and deterministic request orchestration does not establish an autonomous theory builder. These are independent limits, not a single negative grade (EPI-RTE-audit-repair, epistemic bounded conclusion).

At this boundary, exercised self-improvement is unestablished. A changed knowledge document can enter later behavior through retrieval, so its output label does not exclude it from behavior-shaping organization. But the inspected maintenance/evaluation routes do not close an objective-bearing evidence-to-update chain followed by subsequent operation causally dependent on the change. Retention and potential delivery establish neither exercised self-change nor successful improvement. Trace-learning classification likewise remains unresolved rather than globally absent: session adoption and external checkpoint production are not fully known (EPI-RTE-audit-repair, EPI-RTE-eval-replay, RT-RTE-eval-turn, profile verification).

An inspectable artifact-to-write-to-later-answer trace would change the assessment of exercised reliance. A content-directed criticism naming its target, result and resulting revision, with retained next-round use, would change the theory-building assessment. An independently specified objective and controlled comparison linking an update to subsequent operation would support a finer improvement attribution. Technical approval authentication across alternate writers would change the permission conclusion; broader semantic checks before repair would change what its admission guarantees. None of these is presumed from current labels or wiring.

Limitations

Limitation	Affected SRC IDs and record citations	Inspected boundary	Conclusion prevented	Evidence that would resolve it
Relationship-maintenance proposals and Git history have only partial route characterization; this carries the report verifier's declared limit.	SRC-1; report-verification limit, MEM-RTE-projection-read, MEM-RTE-document-move, RT-RTE-document-write, epistemic bounded conclusion	Verifier inspected relationship-section proposals with serialized write requests and explicitly enabled, caller-path-scoped Git checkpoints; analyst records lack their full selection, persistence and later-consumer chains.	Exhaustive route comparisons, complete version recovery and system-wide negatives about maintenance or adaptation. Recorded retrieval, planning, compilation and repair remain supported.	Accepted records tracing those paths, checkpoint contents, admission and actual later recovery/consumption.
No exercised route or causal benefit is established by this analysis.	SRC-1; boundary, RT-RTE-eval-turn, EPI-RTE-eval-replay	Frozen implementation/design only; examples and bundled evaluator code are not adopted run results.	Successful host compliance, later-answer dependence, deployment quality and causal retrieval/task improvement.	Inspectable linked runs and outcomes; independently varied interventions for component attribution.
Approval and recovery guarantees are narrower than ordinary-language readings.	SRC-1; RT-CLM-approval-boundary, RT-RTE-document-write, MEM-RTE-document-move, EPI-RTE-audit-repair	Checked mode gates, cooperating locks, sequential file/sync effects and separate compensating actions; raw/direct writers remain alternatives.	Universal authenticated human approval, universal isolation or all-or-nothing rollback.	Authentication/enforcement across admitted paths, explicit external writer contracts and failure/recovery evidence.
Currency and discrepancy checks do not certify substantive truth.	SRC-1; EPI-RTE-synthesis-build, EPI-RTE-synthesis-freshness, EPI-RTE-audit-conflicts, EPI-RTE-audit-repair	Caller assertions, metadata-relative currency, first-current-summary copying and finite snippet/day heuristic.	General contradiction resolution, independently warranted synthesis, accepted ampliative production or content-directed theory criticism.	Evidence-consuming semantic acceptance criteria, provenance and criticism/revision records at the claimed scope.
Host payloads, provider state and original-asset consumers remain unresolved.	SRC-1; RT-RTE-eval-turn, RT-CMP-embedding-provider, RT-CMP-codex-model, MEM-OBJ-source-assets, profile verification	Session-ID continuation and external model labels are visible; checkpoint/compaction payloads, exact weights and original-asset later delivery are not.	Complete memory/form/selector inventories, immutable provider semantics, host-context recovery claims or a global trace-learning negative.	Host retention/write/delivery contracts and traces, immutable model identities, and recorded original-payload consumers within an authorized boundary.
Other included maintenance, acquisition and projection internals are partly uninspected.	SRC-1; MEM-RTE-vault-sync, MEM-RTE-projection-read, MEM-OBJ-source-assets, EPI-RTE-artifact-ocr, epistemic bounded conclusion	Selected parsing/rebuild, source creation, OCR planning and report witnesses; not all merge/conflict, cleanup, refresh/restore, report-conversion or development/release paths.	Lossless projections, comprehensive acquisition fidelity/withdrawal and system-complete negatives about acceptance, reflection, adaptation or self-improvement.	Accepted records for material alternate transformations and their consequential consumers; outcome evidence where benefit is claimed.