ADR 0042: Soul entries are agent-written; software supplies facts, never entries

Status: accepted (2026-10-14). Plan: deterministic session capture. Applies the responsibility boundary (agents decide meaning, software executes mechanics) to what lands in the soul. Part of the decisions hub.

Context

• Capture depends on the agent choosing to write. The session-end nudge fires when a session changed files and wrote nothing, but carries no facts, so entries come out vague or not at all.
• The first draft of the capture plan had the plugin binary write a journal stub on SessionEnd from the transcript and git state, with no agent involved, first as the default and then as an opt-in.
• Automatic capture is a different product concept: record everything, then rank, decay and deduplicate the noise. demarkus is built the other way round. The agent is the librarian, writes are deliberate, the soul rules forbid trivia and anything derivable from the repo, and lookup quality rests on every document having been chosen.
• An entry nobody chose to write is not curated. Even a factual stub competes with curated entries in lookup and dilutes the journal the session primer reads.

Decision

• Nothing writes to the soul except an agent acting on its own judgment or a user's instruction. No hook, binary, server job or background pass creates or edits soul documents on its own, by default or as an option.
• Software may compute facts deterministically and hand them to the agent: in a nudge, through a subcommand, in a tool result. The agent decides whether any of it is worth recording and words the entry.
• Mechanics that act on a write the agent already chose stay allowed: the journal route, hub links, tag widening, the write gate, curate proposals applied after a human gate.
• Reports stay reports. Doctor, staleness, conflict and near-duplicate checks surface findings; the agent or the user resolves them.

Consequences

• A killed or abandoned session can leave no entry. Accepted: the floor is the agent's habit plus better facts, not an uncurated record.
• The capture plan narrows to facts in the session-end nudge and a session-facts subcommand for /soul-journal.
• Future proposals for auto-capture, decay, automatic consolidation or model rewrites of soul content are out of scope under this decision; reopening one needs a superseding ADR.
• The knowledge system already holds the stricter form of this rule through promote and its human gate; the soul now states it explicitly too.

Alternatives considered

• Automatic stub on session end, default on. Rejected: uncurated content in every soul, against the restraint rule and the librarian principle.
• Automatic stub, opt-in. Rejected: an option that lowers lookup quality for those who enable it is still a second product concept to maintain, and it invites the next automatic writer.
• Stubs in a separate unindexed area. Rejected: hidden content still costs storage and review, and a stub nobody reads has no value; facts handed to the agent at the right moment do the same job.