[schlessera]

Closes #2418
Refs #2390

What changed

Records the complete selected shared reference-source and managed-worktree policy in a new decision record, with adjacent amendments in governed workers, writable areas, native storage and hygiene review, plus the decisions index. The contribution remains exactly six documentation files and 248 added lines. It preserves authorization and independent source-freshness clocks, live shared readers, governed fixed-starting-commit worktrees, explicit renewal, preservation-aware cleanup and hygiene, and the separate actual-allocation Btrfs budget. Selected policy is explicitly distinguished from implementation and qualification.

Why this shape

#2390's consolidated specification and maintainer rulings settle the policy; #2418 is its independent durable-documentation deliverable. #2390 is now the open umbrella epic, with implementation children #2428–#2432. This PR closes only #2418 after required verification; it does not deliver the umbrella's runtime acceptance.

The delivered Storage work in #2172 is preserved. Its StorageInventory reports allocated-byte observations with an explicit warning that shared extents may be charged more than once; the decision explains why those observations are not the reference pool's selected unique aggregate allocation metric. Existing brain-content logical retained-history accounting, concrete owners, governance and append-only provider history continue to bind. No product implementation, machine-surface change, extension seam or package changeset is introduced by this contribution.

Proof

Fresh local candidate:

• Head: 518dfa3419009c19f151967da5460288180c0fcf
• Base and merge base: 6a73a598dd9dcbe8715126eeadf0cb47e3211a64
• Candidate tree: d2cfb0158f0df2d2c3e57f8f5f27f07add94f8d5
• History-preserving merge parents: 4df4177092100b4d9dd6955c4541e862f00d228d and 6a73a598dd9dcbe8715126eeadf0cb47e3211a64.
• Stable contribution patch ID: c516d76522b6786e4717a9d11218bd5c649748be, identical before and after refresh. All 248 contributed lines are preserved; incoming Storage citation corrections remain intact.

Fresh execution:

bun run check:pr --base origin/main --plan
bun run check:pr --base origin/main

Exactly one plan and one default preflight ran on this candidate. The actual plan selected the six docs and 21 fast invariant files, with affected packages empty and global, types, packaging, full-suite, browser, layout, capture, endurance and runtime categories false. Default preflight passed all lint, environment-documentation and changeset gates and 446 tests across 21 files, with 2,133 assertions and zero failures. The selected decision-citation invariants passed within that run; no duplicate standalone citation test was executed. Oxlint reported eight warnings and zero errors. Import-graph feedback separately selected zero tests for six changed Markdown files; that empty feedback is not the nonempty invariant proof.

Bun 1.4.3, Node 26.7.0, Git 2.56.0, TypeScript 6.0.3 and oxlint 1.86.0. The existing owned frozen copyfile installation was used; the lock SHA-256 remained 5bbd5f6651f111db3fcfabeda512d44a21163cba54c58993f8878012d548cc14. No install, build or typecheck was needed or run in this window. No mutable dependencies or build output were shared between checkouts.

A bounded harmless prerequisite passed before project commands. Both commands ran as UID/GID 1000 with normal HOME, private temporary/cache directories and a private maintenance ledger. The adapted existing launcher configured its private user/mount/network namespace, then used the repository entry to drop every capability set before executing project commands. Receipts verify a different network namespace, actual unfiltered empty IPv4/IPv6 main routes, the original /tmp identity, memory/disk/temp floors and an owned bounded write/fsync/unlink probe for unknown zero/zero Btrfs inode counters. Repository offline and ordinary workspace-lease guards remained enabled; no outer Python flock was used. Complete command logs, launcher source/adaptation hashes, capability/network/resource receipts and input identities are retained.

Historical evidence remains separate:

• Earlier head 6fc6183fe36125db1f465c9abb72eed0838d32ef, base 90a95123cfceb169bd2ecf7c213544db742eaed7, tree 212a1ec86ce0cb92bfbe254b4697c303de4ff3b1: 446 tests / 2,126 assertions, plus standalone 44 decision tests / 113 assertions and 1,155 citation observations. These are historical receipts, not proof of the refreshed candidate.
• The intermediate local 4df4177 refresh was source/plan-only and supplied no fresh test proof.
• An initial offline-launch attempt on the current source failed enabling loopback because its launcher lacked keep-caps; neither plan nor preflight started. That failed bootstrap is preserved separately. The subsequent proven-template adaptation first passed the harmless prerequisite and dropped all capabilities before the sole fresh plan/default execution. No failed product test was rerun for green.

No behavioral guard changed, so no behavioral mutation receipt is required. No reference acquisition, native allocation, browser, provider or managed-worktree runtime qualification is claimed. Complete selected hosted proof remains pending; neither historical candidate proof nor automatic main proof is substituted for it.

Checklist

• Focused local preflight/behavioral receipts and complete selected hosted proof passed; actual head/base/job checkout evidence is in Proof.
• Acceptance criteria from the issue are all met, or the gap is named below.
• The PR and completed/advanced issues have verified release milestones under docs/process/github.md.
• A changeset is included, or this changes nothing a consumer can see.
• No personal data anywhere in the diff — the leakage gate covers the whole tree.
• The integration contract index or relevant component is updated in this same commit, or nothing in the machine surface moved.
• Docs under docs/ reflect the change, or nothing documented moved.
• Provider history stays append-only (docs/decisions/provider-history.md): the provider-history guard passes, or nothing on a turn's path changed.

Anything left open

Complete selected hosted proof under the current exact-candidate integration reservation procedure before merge. Release context remains 0.44.0 for this PR, #2418 and the advanced #2390 work. #2390 and implementation children #2428–#2432 remain open for the managed reference/worktree implementation, additive contracts and integrated native/backend qualification. Documentation adds no shipped behavior or machine surface, so it needs no changeset. No confirmation or merge qualification is claimed by this draft.