Development record
The lifeboat is a coverage experiment — read-only, out-of-tree, and proven before it is packed (supersedes adr-4)
Context
The lifeboat is what abcd's press release says abcd is: the artefact that makes a project survivable. It is also the only major surface with zero code — no internal/core/lifeboat/, no verbs, no agent prompts. The roadmap parks it at Phase 6, last, on the stated grounds that it "depends on every prior substrate being native."
Checked against the binary rather than the record — per CONTEXT.md's rule that where the record and the binary disagree, verify against the binary — that rationale is mostly false, and the error is load-bearing:
| The roadmap says it blocks | What the binary shows |
|---|---|
| Phase 4 native spec engine | spec.Load / Create / Close / Validate all ship. Not a blocker. |
| Phase 5 run seam | Backgrounding is a host affordance; the design's own checkpoint is "forensic only — abcd ships no resume verb". Not a blocker. |
| Phase 3 reviews (itd-28) | Reviews are already committed markdown under .abcd/work/reviews/. Not a blocker. |
| itd-2 in-session subagent dispatch | The host-delegation seam already ships twice: memory.Distiller fed by --pages-json, and intent review ingest --verdict-json with a dead-letter path. Not a blocker. |
| Phase 2 history + memory | The packages are built. The data is empty. Real — and not a code problem. |
So the sequencing argument does not hold. Three further facts forced this decision:
- The premise is untested. The brief's structure is an assumption: that these are the sections a project's theory decomposes into. Building a packer first assumes the answer. Nobody has ever run the extraction against a repository that has no record to see which sections come back empty.
- adr-4 put the operations namespace inside the source repo (
.abcd/development/voyage/). Voyage records absolute source paths; theprivacy-hygieneaudit rule (itd-85) flags/Users/<name>/in committed files. abcd would have failed its own audit. ~/.abcd/does not exist. There are zero transcripts.history.Captureis built, redacts on write, and is called by nothing — noStophook is wired. Pass B (mining chat for the rationale nobody wrote down) has no corpus and cannot get one retroactively. This is the only cost on the board that is permanent and compounding.
Decision
The lifeboat is built as an experiment whose first output is a verdict on the brief's own structure, not a lifeboat.
- Probe before pack.
abcd disembark probe <repo>produces a coverage report — which brief sections a real repository can ground, which are blank, and what was searched — across a corpus of repos of mixed record quality, before a packer exists at all. Running the same probe over a rich-record repo and a git-only repo yields a delta in section coverage, and that delta is what the record is worth. If half the brief is permanently blank on every repository, the structure is wrong and we have learned it for the cost of one milestone.
- Disembark is read-only and out-of-tree.
abcd disembark <source-repo> to <dest>— point it at any repository, touch nothing, write elsewhere. A test hashes the source tree before and after. This replaces adr-4's model of a lifeboat written back into the source at.abcd/lifeboat/: mining a dead or archived project must not requireahoy installinto a repo we only want to read.
- Voyage moves to the operator level —
~/.abcd/voyage/<source-root-sha>/, keyed on the root-commit SHA, matching the existing history-store convention. This is the clause that supersedes adr-4, which defined voyage as the operations namespace inside the source repo. It is therefore never committed, which dissolves theprivacy-hygienecollision above.
- The lifeboat remains regenerable output (adr-4's surviving core, restated here because supersession prunes the original): it is the latest snapshot, not an accumulating archive; there is never a
lifeboat-v1//lifeboat-v2/; history lives in the append-only voyage log, not in stale snapshots. The naming distinction stays load-bearing —lifeboat/is the artefact (noun; what gets carried),voyage/is operations (verb; what we did to produce it). What changes is where each lands: the lifeboat at an operator-chosen destination, voyage at the operator level. adr-4's overwrite-in-place-with-.bakmodel is replaced by a destination safety gate — refuse unless the destination is absent, an empty directory, or one carrying a parseable_provenance.json. Never overwrite a directory abcd did not produce.
- The hash chain is pinned. adr-4 asserted a chain but never defined it.
manifest_sha256is SHA-256 over the concatenation of"<sha256> <path>\n"for every manifest entry, sorted lexicographically by path, POSIX separators, LF only, with_provenance.jsonexcluded (it cannot hash itself). adr-4'sshared_withfield is dropped: nothing produces it, and an empty field is a lie in a schema.
- Coverage is a first-class output, not an exemption footnote. The brief carries only what abcd could ground, each claim citing its source; a separate
coverage.{json,md}carries what is missing, what was searched, and the question a human must answer. Its schema aggregates across repositories, because that aggregate is the experiment's readout.statusis one ofgrounded/partial/blank, and a blank is a first-class result, not a failure.
- The graveyard is a new first-class section — "extract what failed, so it isn't tried again" — in three layers, and the order is the anti-fiction discipline: archaeology (Tier 0, any repo: reverted commits, branches abandoned unmerged, files deleted after substantial history, dependencies added then removed), then recorded abandonment (superseded ADRs and intents,
wontfixissues, alternatives-considered sections), then interpretation (host-delegated LLM). Interpretation sits at the bottom and cannot float free: every interpreted entry must carry anevidence[]array citing layer-1 or layer-2 ids, and an entry with no evidence is dropped by the Go validator — not by the model's good intentions. This is the mechanism itd-11 was reaching for, made structural.
- The spine is re-sourced. The design sources it from the native spec store, which holds exactly one spec — a fiction. The spine is the intent corpus where one exists, and git where it does not.
- The lifeboat-oracle reuses the registered review-verdict enum
{SHIP, NEEDS_WORK, MAJOR_RETHINK}. The brief's "sufficient" verdict was a member of no registered enum; no third verdict family is minted.
- itd-2 is not a prerequisite, per the table above.
- Phase 6's fidelity claim is re-authored. "A reader with no prior context can reconstruct not just what the project is but why it was built the way it was" cannot be met by a transcript-less lifeboat as literally written. It becomes "the recorded why, with every claim citing its source", and Pass B ships as a declared exemption in
_provenance.json, never a silent gap.
Alternatives Considered
- Build the packer first, as the design is written (Phase 6, adapters → Pass A → Pass B → Pass C → embark). Rejected: it assumes the brief's structure is right, which is the very thing in question, and it spends the most expensive milestone on that assumption. The probe answers it for a fraction of the cost, and the packer is strictly better for having the answer.
- Amend adr-4 in place (append an
## Amendmentsection, as adr-9 does). Rejected: adr-9's amendment refined how one section was expressed. Here, two of adr-4's three operative claims change — where the lifeboat lands, and where voyage lives — and its overwrite model is replaced by a safety gate. That is a replacement, not a clarification, and the record's convention is that a replacement gets a new id and prunes the original.
- Keep voyage in the source repo and gitignore it. Rejected: a gitignored in-tree operations log still lives in a tree we have promised not to touch (decision 2), and it duplicates a convention abcd already has — the history store keyed on root-commit SHA under
~/.abcd/. One operator-level home, one keying rule.
- Keep disembark cwd-based (
disembarkpacks this repo). Rejected: it forcesahoy installinto a repository we only want to read, and it is backwards for the primary use case — mining a project that is already dead.
- Mint a new verdict enum for the lifeboat oracle (e.g.
{sufficient, insufficient}). Rejected:{SHIP, NEEDS_WORK, MAJOR_RETHINK}is registered and means exactly this. A third family is vocabulary drift.
Consequences
Gains:
- The premise gets tested before it gets built. The cross-repo coverage aggregate is a number a human can read and act on, and it can only say "the brief structure is wrong" before a packer has been written to that structure.
- Disembark can be pointed at any repository — including dead ones, archived ones, and ones abcd has never touched — without modifying them.
- The
privacy-hygienecollision is dissolved rather than exempted; abcd stops being at risk of failing its own audit rule. - A blank section becomes a question a human must answer, carried in the artefact, instead of a silent omission.
Costs / obligations:
- The transcript clock must start now. Pass B's corpus is unrecoverable for every session that runs before a
Stophook is wired. This ADR does not fix that; it names it as the reason the hook ships first, ahead of any lifeboat code. - Vocabulary must be registered in
02-constraints/04-naming.md:voyage/,manifest_sha256,_provenance.json,history.jsonl,coverage.json,graveyard/, plus the two new enums (status ∈ {grounded, partial, blank}andtier ∈ {git, conventions, abcd-native}). adr-4 claimed this registration and never made it — the terms were absent from the registry. This ADR fulfils the claim. - The mapping table is a hypothesis and is expected to lose. It is generated from
internal/core/lifeboat/mapping.goand rendered into the brief's00-meta.md, which has called it "the contract" while no such table existed anywhere. The probe is what will revise it. surface_coverageis a tripwire. Rows 2 and 3 of the surface registry arestaged, and that rule asserts astagedrow has no backing surface. Addingcommands/abcd/disembark.mdwithout flipping the row toshippedin the same commit turnsmake preflightred.fsutil.WriteFileAtomicis unusable for embark's target writes — it callsos.MkdirAllon the path's directory, so a manifest entry of../../.ssh/authorized_keyswould create the directory and write the file. Embark needsos.Rootcontainment, the pattern theprivacy-hygienerule already adopted after a proof-of-concept showed a leaf-onlyO_NOFOLLOWis insufficient (a symlinked intermediate directory still escapes).launch.ResolveBundlemust not be reused for disembark — itsDenyNamespacesstructurally denies.abcd, which is exactly what disembark must read. Mirror its safety disciplines (symlink-escape, control-character, hardlink, duplicate rejection); do not reuse the function.
Downstream decisions enabled:
- The section list that survives the coverage aggregate is what the packer is built to — so M3 onward has an evidence-backed target schema instead of an assumed one.
- The graveyard's cite-or-be-dropped validator generalises: it is the shape any host-delegated synthesis over an untrusted corpus should take.
Frontmatter
| id | adr-35 |
|---|---|
| type | adr |
| status | accepted |
| date | 2026-07-14 |
.abcd/development/decisions/adrs/0035-lifeboat-as-coverage-experiment.md
open on GitHub ↗ · commit history ↗
References9
- adr-25The LLM is host-delegated by default; oracles are opt-in adaptersrelated
- adr-28One repository, a curated release artifact — no dev→public mirrorrelated
- adr-29A native local redacted transcript corpusrelated
- adr-33Launch phase ownership is tiered; the phase index is the sole ownership sourcerelated
- itd-2In-Session Subagent Dispatch — the Default Host-Delegated Oraclerelated
- itd-11Disembark Survives Noisy Transcriptsrelated
- itd-21Start a New Project With abcd Conventionsrelated
- itd-88Know What a Repo Can and Cannot Tell You — Before You Trust the Lifeboatrelated
- adr-4not in the treesupersedes
Referenced by6
- adr-1Three-layer mental model (brief / intent / spec)related
- adr-5Brief is the current state; no version label, no archive directoryrelated
- adr-36Coverage blanks are a fillable lifecycle — authored is not extracted, and the interview is its own steprelated
- adr-2609091014087993A tool never creates directories in user-owned project space; agent and session scratch is machine-scopedrelated
- adr-2609091248200336A tool never creates directories in user-owned project space; the store's location binds now and its verbs bind when the store shipsrelated
- itd-90The Product Thinker Is Handed Exactly The Questions Only They Can Answer — And Nothing Elserelated
mentions34
- adr-9Phase as a product-reflection layer between brief and intent
- dcn-26071400000000012026-07-14 — The lifeboat is built as a COVERAGE EXPERIMENT, not a feature
- dcn-26071400000000022026-07-14 — adr-4 SUPERSEDED by adr-35 and pruned per the ADR convention
- dcn-26071400000000052026-07-14 — adr-35's blast radius across the record was FAR wider than the plan
- dcn-26071400000000062026-07-14 — iss-93: adr-35 promises disembark is READ-ONLY over the source (a test
- dcn-26090900000000062026-09-09 — The headline product is settled (maintainer, closing the press release's "Product framing after adr-35" open question, both halves). abcd helps a product thinker realise an intent as a high-fidelity prototype or demonstrator, carrying the why from idea to shipped reality: the identity block's story, the one the README strapline and the roles page already tell and the one the roles and product-thinker-surface decisions on the design branch (numbered 0055 and 0056 there, re-minted at merge) are built on. The lifeboat is a key capability of that product rather than its headline, and its widening from whole repositories to a single feature, a lab session or an abandoned worktree enters the press release under the not-yet-real marker, as intention rather than commitment. `disembark probe` is a user-facing command and keeps its place in the press release's scope list. Rejected: the rescue story as headline (it would re-pin the identity block and every surface held to it); adr-35's "read any repository for its theory" as headline (it is the probe's own promise, now one capability among the surfaces); deferring (the audit of the press release against delivered reality had been blocked on this question since adr-35).
- iss-93adr-35 leaves two paths by which disembark still writes into the source repo: the Pass-0 dev-sync stage (writes .abcd/work/reviews, .abcd/memory, .abcd/work/issues into the repo) and the backgrounded-execution checkpoint (.abcd/logbook/disembark/<ts>/_state.json). adr-35 promises disembark is read-only over the source and that a test hashes the tree before and after, so both must move out-of-tree (under <dest>, or under ~/.abcd/voyage/<source-root-sha>/) or be excluded from the disembark path entirely. adr-35 does not settle where they go — a design decision owed before the packer ships.
- iss-94The intent corpus still specifies the pre-adr-35 lifeboat model: itd-2, itd-8, itd-9, itd-10, itd-13, itd-15, itd-19, itd-22 and itd-24 variously use the retired 'disembark to home' signature, the in-tree .abcd/lifeboat/ home, or the in-tree .abcd/development/voyage/ path (itd-9's acceptance writes voyage provenance in-tree — the exact path that would fail abcd's own privacy-hygiene audit rule). The brief, glossary and roadmap were reconciled to adr-35; the intents were deliberately NOT rewritten, because an intent is a proposal with its own lifecycle and silently rewriting nine of them inside an unrelated change is worse than tracking the drift. Each reconciles when it is next planned.
- iss-2608220150157498Eight typed cross-references point at targets absent from the tree — adr-22 supersedes adr-14, adr-15 and adr-17; adr-25 supersedes adr-8; adr-27 supersedes adr-16; adr-28 supersedes adr-18; adr-35 supersedes adr-4 (all retired under retire-the-name); itd-3 names spec_id spc-1 which has no file — and nothing checks supersedes targets today. The 2026-08-21 site investigation counted six; the in-session grep found eight. The planned site build arms the detector via the .abcd/site-baseline.json ratchet, seeded with what the build finds, and the tombstones-or-stubs question (itd-136/itd-137) decides how they render
- iss-2610262030391056Meta's truth rule bans aspirational maybes from the brief; the press release's open questions carry one outside the registered question homes
- iss-2610262030587661The meta page says unsettled questions are recorded only as registered open questions or as explicit `Open question` notes; the reading chapter carries an owed product-thinker ruling inline, in neither form.
- iss-2610262032046139The register reserves `voyage` for the operator-level operations namespace; itd-36 uses `voyage` to mean a project abcd manages.
- iss-261026203249169007-memory names the lifeboat the surface that publishes curated project memory; disembark's pack inventory walks record families and brief sections and writes no memory
- iss-2610262032516143embark's lessons speak of 'the previous voyage' and 'the new voyage's brief'; the voyage glossary restricts the word to the operations namespace and forbids it for a project
- iss-2610262033042911itd-35 writes its lifeboat report in the repository under .abcd/logbook/audit/; the embark page says lifeboat operations record at the operator level under ~/.abcd.noindex/voyage/, never committed.
- iss-2610262033521157The reflect chapter uses 'voyage' for a project's lifetime ('every retrospective the voyage produced', 'the new voyage's store'); the glossary fixes voyage as the operator-level log of disembark and embark runs.
- iss-2610262041318943itd-24 uses "voyage" for a project's lifetime of work; the glossary defines voyage as the operations namespace of disembark and embark runs and forbids it for a project
- iss-2610262041325659itd-50 says a NOT_MET verdict is logged and "the voyage moves on", using voyage for project progress; the glossary reserves voyage for the operations namespace
- iss-2610262041481549The voyage glossary entry forbids using voyage for a project; itd-36 uses voyage to mean the project a researcher runs under abcd.
- iss-2610262041499021In the glossary a voyage is the operations namespace of lifeboat runs; itd-34 calls an application project a voyage.
- itd-9Old Lifeboats Still Unpack
- itd-10Full Removal When You Mean It
- itd-28Spec-Tied Reviews Live Next To The Spec They Reviewed
- itd-85A Read-Only Repo-Conformance Audit
- itd-89Capture the Session You Just Had, Because You Cannot Capture It Later
- itd-95Disembark Grounds A Lifeboat's Open Questions On A Repo's TODO And FIXME Markers
- itd-96Disembark Reads A Repo's Naming And Internals Conventions Into Its Lifeboat
- itd-160Eight typed cross-references point at targets absent from the tree — adr-22 supersedes adr-14, adr-15 and adr-17; adr-25 supersedes adr-8; adr-27 supersedes adr-16; adr-28 supersedes adr-18; adr-35 supersedes adr-4 (all retired under retire-the-name); itd-3 names spec_id spc-1 which has no file — and nothing checks supersedes targets today. The 2026-08-21 site investigation counted six; the in-session grep found eight. The planned site build arms the detector via the .abcd/site-baseline.json ratchet, seeded with what the build finds, and the tombstones-or-stubs question (itd-136/itd-137) decides how they render
- itd-2609091014076309Session and agent worktrees live in a machine-scoped store that abcd lists and reclaims, never beside the user's own projects
- spc-3lifeboat-coverage-experiment
- spc-12disembark-grounds-a-lifeboat-s-open-questions-on-a-repo-s-to
- spc-38alice-opens-the-record-explorer-and-reads-the-whole-developm
- spc-52dangling-supersedes-and-spec-targets-nothing-checks-them
- the-users-directory-is-theirsThe user's directory is theirs