--- title: "What a 600-Line Architecture Document Missed About Adjacent Repos" canonical: https://dxdev.com/blog/manus-pushed-back-six-of-seven/ datePublished: 2026-05-08 --- Manus's critique came back disagreeing with six of our seven design decisions for the conversation archive. That was the first sign the architecture document was doing any work. The archive had taken a while to build. Four provider repos: Claude Code sessions, Codex runs, Manus jobs, and OpenRouter experiments. 1,585 sessions total, spread across the history of the AI ops setup we have been running. Getting them into a consistent structure with a shared manifest shape and a `Calendar_Index` for navigating by date had taken a few weekends of careful scripting and a lot of edge-case hunting. Finishing the build and having a working archive are different things. A working archive is one that survives a second opinion. ## What Manus read We sent a 600-line architecture document. It covered the manifest format, the indexing strategy, the folder naming conventions, and how continuity data should flow from session close into the archive. That is exactly the wrong state for an architecture document. Manus came back with seven points of contention. Six were legitimate. The seventh was a misread we cleared up with one sentence. The six real points: - The `Calendar_Index` folder structure, which we had named inconsistently in two places. - Session-close trigger versus a polling approach for ingestion. - The manifest field for sessions that span midnight. - The archive's behavior when a provider's API changes its session ID format. - The deduplication strategy for re-ingested sessions. - What "continuity" meant in terms of which fields downstream agents would read. We had answers for some of these and rationalizations for others. One we had not thought about at all: what happens to sessions re-ingested after a partial failure? Our spec said "upsert on session ID" and stopped there. Manus pointed out that if the manifest was partially written before a failure, an upsert would preserve the partial write. The session would look complete in the index and never get reprocessed. The gap looks obvious now, and it was invisible while nobody else had read the document. ## The remote routine that proved the point While we were still reviewing the critique, we had Manus run a small test. Pull one month of Claude Code sessions from the archive, summarize the recurring patterns, and write the output back to the established location in `Calendar_Index`. A standard retrieval and synthesis job. It cloned a different repo. Not the command station repo where the archive lives, but a sibling repo the spec had mentioned as context for the broader agent topology. Then it wrote its output into an `Archive_Sweeps` folder inside that sibling, a folder that did not exist until that moment. The job completed without errors. Manus reported success. We had two archives. One was the real one: 1,585 sessions, a consistent manifest format, a calendar index built over weeks. The other was a single month's summary in a new folder in the wrong repo, created because the spec carried enough ambient context about other repos that a capable model could mistake the territory. A multi-agent system with an underspecified architecture will generate parallel systems. Agents are good at building things that are locally consistent with what they were told. Here, locally consistent meant the wrong repo. ## Ratify what held, then pin the agent down Our first move was not to start revising the spec. We locked the decisions that were already right and ratified them explicitly, so future agents could not drift off them. We went through the six points. For four of them we had a defensible answer, and we wrote it into the spec as a decision record rather than a clarification. For the deduplication point, we rewrote the upsert logic to skip reingestion only when the manifest's completeness flag is set, so a partial write never passes for a finished session. For the `Calendar_Index` naming inconsistency, we fixed the name and noted which form is canonical. Then we wrote a Manus operating profile, a short document that says which repo is authoritative, how to verify it before any write, and what to do when a spec names adjacent repos. Here is the whole thing: ```yaml # manus-operating-profile.yaml # Loaded BEFORE any archive job. Overrides ambient context from the spec. authoritative_repo: command-station # the ONLY write destination write_root: command-station/Calendar_Index before_any_write: - confirm cwd repo == authoritative_repo - if a spec names another repo by path, treat it as READ-ONLY context - never create a new top-level folder; write only under write_root on_ambiguity: - stop and report which repo you believe is authoritative - do not infer the destination from adjacent-repo mentions upsert_rule: - skip reprocessing ONLY if manifest.complete == true - a partial/missing completeness flag means re-ingest, never skip ``` The profile loads as a separate artifact before any archive job, so the agent does not have to infer intent from the architecture document. The session manifests got a continuity block. The fields downstream agents are expected to read are now named explicitly instead of described in prose. Prose is ambiguous. Field names are not. Four follow-up tasks went into the project tracker for open questions without answers yet. The one about session-close trigger versus API polling is still open. We have a preference but not a justification rigorous enough to commit to the spec. ## What the stray folder left behind The `Archive_Sweeps` folder in the wrong repo is still there. We have not deleted it, because it shows what underspecification produces. The profile exists so that job does not repeat, and it only exists because the test run exposed the gap. If our own review had been the only one, the spec would have shipped with the upsert hole, the naming inconsistency, and no answer to what happens when a remote agent reads "adjacent repo" as "destination repo." The architecture would have felt finished because nobody had seriously read it. Before you let an agent run a job against any multi-repo spec, make it state which repo is authoritative and confirm its working directory matches that repo before the first write. If it cannot answer, or the spec does not say, stop and fix the spec first.