Journal 2026-08-17

Corpus-wide catalog sweep of the soul, a hub restore, an ADR mirror, and two graph bugs found by doing it.

Hub restored after a section-fetch truncation

/soul-doctor found /index.md serving only Active Plans and RFC Review with no H1. It had been truncated at v69 (2026-08-12) when a #active-plans section fetch was republished as the whole body; eight later versions edited the fragment. Every root section, plugin entry, sub-project hub, and plan archive was unreachable from the hub for five days. Restored at v78 from the v68 body with the current sections spliced in. Lesson and proposed gate check in /debugging.md.

Core ADRs now live in the soul

The core project had no ADR series here: protocol decisions lived only in git docs/adr/, so mark_lookup for a decision found library ADRs and stray journals. Adopted the mirror convention, git canonical, soul copy for recall and backlinks, and published ADR 0001, ADR 0002, ADR 0003, ADR 0004 verbatim with source and rel-* metadata. Rule recorded in /conventions.md.

The sweep

Every catalogued document was force-fetched, given an OKF type, extended tags, and where the body warranted it a rel-* relation or an appended ## Related documents block. 187 of 192 documents carry a type; the five that do not are the four index.md hubs and the agent manifest, which OKF leaves untyped. One document remains untagged, the agent manifest. Run as eleven parallel subagents, interrupted once by a rate limit and resumed from a catalog diff rather than from agent memory, which is why the resume was cheap.

Method note that mattered: publishing a body that has been retyped through a model is unsafe. Four documents came back with a changed content-hash because the terminal newline was added or dropped. Every write was hash-verified against the pre-write value and repaired from the pinned prior version. The reliable path is fetching the body to a file and publishing byte-exact from that file.

Two graph bugs

Rebuilding /graph.md produced 388 nodes for 192 documents, split between soul.demarkus.io and soul.demarkus.io:6309. demarkus graph keys nodes by the raw start URL; the MCP crawler canonicalizes to host:port first and comments that it must, so the two clients disagree on node identity and a shared store answers backlinks from half its data. A canonical re-crawl gave 220 nodes with zero duplicates, which also proved no document body links to an absolute bare-host URL. Both this and the byte-identical /plans/obsidian-plugin.md and /plugins/obsidian/plan.md pair are in /debt.md.

/graph.md was two months stale (133 nodes, 190 edges, exported 2026-06-26). Republished at 220 nodes and 866 edges, 100 of them typed relations. Published with tags and deliberately without retention, since that key is destructive and the document had never carried one.

Next session

ADR 0005 (node identity omits the default port) is written and deliberately left at status: proposed. Implementation is deferred to 2026-08-18, after the demo.

Resume state:

Branch docs/adr-0005-node-identity-default-port holds docs/adr/0005-node-identity-default-port.md, uncommitted. The soul mirror is published and the hub Decisions row is in place, so the catalog is already consistent with a decision that has not been accepted yet. Flip the status in both copies together when it is.
PR #318 is merged, so the crawl entry is canonical. The remaining doors are SeedFromExport, the three read paths, and absolute body links. /debt.md carries the open list.
Order of work when it starts: accept or amend the ADR, then the injected canonicalizer, then schemaVersion 1 to 2 with migration on load, then the producer side (demarkus-agent and mark_graph_publish), then re-publish the hub aggregates.
Watch the library floor. It broke once on an export format change, so accept-both on ingest is the load-bearing part, not a nicety.

Demo-facing state is current: the hub is restored, /graph.md is fresh at 220 nodes and 866 edges, and /rfc-review-faq.md is the RFC review source.

Graph: conventions