docs(adr): move the design record from issues into docs/adr/

[Soushi888]

SoushAI analysis. Drafted by Soushi's AI assistant, reviewed and posted by @Soushi888.

Closes #39.

Why

The design record lived in the descriptions of #1 and #15, although code comments across the repository cite ADR numbers. A reader of the code could not find the text those numbers point to without the issue tracker.

What

• docs/adr/0005-*.md to docs/adr/0017-*.md: one file per ADR, each with Status, Date, Source, Context, Decision and Consequences.
• ADR-005 to ADR-017 quote the decision text of Design: Workshop 2026 milestone (PM/Builder binôme record) #1 and Research record 2026-08-28: Holo ecosystem state and ADR amendments 007/008/009, 015/016/017 #15 as written, in quote blocks. Context is taken from the same issue (the "State of the repo at open" bullets of Design: Workshop 2026 milestone (PM/Builder binôme record) #1, the research sections of Research record 2026-08-28: Holo ecosystem state and ADR amendments 007/008/009, 015/016/017 #15). Where the issue gives no consequence, the file says so instead of supplying one.
• Amendments are recorded inside the ADR they amend, with their date: ADR-007 (dual-line), ADR-008 (the runner is compute donation), ADR-009 (gateway built from source per line), ADR-012 (SSH public keys committed). ADR-010 copies the slice order, the gate and the 01:58 gate amendment under "Related record in Design: Workshop 2026 milestone (PM/Builder binôme record) #1", because Design: Workshop 2026 milestone (PM/Builder binôme record) #1 keeps them in their own sections rather than in ADR-010.
• ADR-001 to ADR-004 are not published. They belong to the Phase 1 architecture design of 2026-05-13, the "May design doc" Design: Workshop 2026 milestone (PM/Builder binôme record) #1 continues the numbering of, which is not in the repository. They are cited only by number: in Design: Workshop 2026 milestone (PM/Builder binôme record) #1, and in the title of Hardware: one Holoport boots vanilla NixOS from the workshop ISO (ADR-003 gate) #8 (ADR-003). The index lists them as not published.
• A "Later record" section, where it applies, lists rulings from PR reviews and places where main no longer matches the recorded text and the record was not amended, each with its link: the 0.6 installer on hc sandbox call and the 0.6 network section carrying relay_url (feat(edgenode): conductor and hApp at boot on both Holochain lines, VM-tested (slice 2) #16), nixpkgs on 26.05 (chore(flake): move nixpkgs to nixos-26.05, fix its three breakages (slice 6) #20), the stack landing as seven merge-committed slices (ADR-010), the PNG ruling on ADR-012 (feat(observability): conductor metrics, provisioned dashboard, opt-in Wind Tunnel runner (slice 3) #17 review), and the boot loader moving out of the hardware stubs (fix: review hardening across the stack, installer, admin origin, templates, Grafana secrets (slice 7) #21, ADR-017). These are observations with evidence, not new decisions.
• docs/adr/README.md indexes all seventeen numbers with status and source, and explains the conventions. Every number from 005 to 017 referenced in the repository, Design: Workshop 2026 milestone (PM/Builder binôme record) #1 or Research record 2026-08-28: Holo ecosystem state and ADR amendments 007/008/009, 015/016/017 #15 has its text.
• docs/architecture.md gains a "Design record" section linking the index; the README layout tree lists docs/adr/.

How to test

Commands run on this branch:

nix flake check --no-build --all-systems

Exit 0.

grep -n $'—' docs/adr/*.md

Exit 1 (no match): no em-dash in the new files.

A throwaway script resolved every relative link and anchor in docs/adr/*.md, docs/architecture.md and README.md: 27 links, 0 broken, including the two anchors into docs/architecture.md. The issue, PR and review-comment links were checked with gh issue view, gh pr view and gh api repos/Sensorica/nixos-holochain/issues/comments/<id>.

Each "Later record" statement about main was checked against the tree: flake.nix pins nixos-26.05 and holonix/main-0.7; modules/holochain-edgenode.nix renders lair_server_in_proc, relay_url on both lines, and hc sandbox call --running below 0.7; git log --merges shows the seven slice merges; templates/minimal/configuration.nix enables systemd-boot.

Not covered

• The ADRs are not removed from Design: Workshop 2026 milestone (PM/Builder binôme record) #1 and Research record 2026-08-28: Holo ecosystem state and ADR amendments 007/008/009, 015/016/017 #15, and those issues are not edited. Whether to add a pointer to docs/adr/ there is a separate call.
• ADR-001 to ADR-004 stay out until Soushi decides to publish the May design. Restoring them is reverting the deletions of 99094da.
• ADRs numbered after 017 are not in Design: Workshop 2026 milestone (PM/Builder binôme record) #1 or Research record 2026-08-28: Holo ecosystem state and ADR amendments 007/008/009, 015/016/017 #15 and are not included.
• The divergences listed under "Later record" (ADR-007 nixpkgs, ADR-010 stack shape) are reported, not resolved: amending or superseding those ADRs is a decision for the maintainers.
• No convention for adding future ADRs is written, since that would be a new decision.

[Soushi888]

SoushAI analysis. Drafted by Soushi's AI assistant, reviewed and posted by @Soushi888.

Response to the adversarial review of 7c0a4a9. Fixes are in 99094da.

1. Major, ADR-001 to ADR-004 published from a private document: fixed by default-no. Verified: docs: move the ADRs from issues into docs/adr/ #39 scopes the move to ADR-005 to ADR-017, the source is a gitignored file, and no recorded decision covers publishing it. The four files are removed, the index lists 001 to 004 as "Not published: recorded in the May 2026 design, which is not in this repository", and the cross-references in ADR-006 and ADR-012 are gone. The text remains visible in 7c0a4a9 on this branch. If @Soushi888 wants them published, reverting the deletions of 99094da restores them.
2. Minor, references to documents the repository lacks: fixed. The PRD references went with ADR-001 and ADR-002. ADR-006 now says the May design and its §4.5 are not in the repository, and that §4.5 was the Node.js fallback of the May design's installer decision (ADR-004), confirmed against the design's heading "4.5 Fallback installer, Node.js via @holochain/client".
3. Minor, ADR-010 presents the slice order and the gate as its own text: fixed. Verified in Design: Workshop 2026 milestone (PM/Builder binôme record) #1: "Slice order", "Gate" and the 01:58 amendment are separate sections, and the 01:58 entry names the gate, not ADR-010. Consequences now says the record gives none; the three move under "Related record in Design: Workshop 2026 milestone (PM/Builder binôme record) #1", which states they are not part of ADR-010. Status stays Accepted, since Design: Workshop 2026 milestone (PM/Builder binôme record) #1 amends the gate, not ADR-010.
4. Minor, inferred "Superseded by" statuses: fixed. Both statuses belonged to ADR-002 and ADR-004, which are no longer published, and the "Superseded" convention is dropped from the index since no file uses it. ADR-012 no longer claims to supersede ADR-002.
5. Minor, hard-wrapped commit body of 7c0a4a9: rejected. Rewriting it needs an amend and a force-push, which this branch's workflow does not allow. The new commit's body is unwrapped. A squash merge would replace both messages if that matters.
6. Minor, PR body overstates how the code cites ADR-001 to ADR-004: fixed. Verified that no file on main cites them. The body now says they are cited only by number, in Design: Workshop 2026 milestone (PM/Builder binôme record) #1 and in Hardware: one Holoport boots vanilla NixOS from the workshop ISO (ADR-003 gate) #8's title (ADR-003), and describes the new state.
7. Minor, missing documentation label: fixed. Added.

Checks on 99094da: nix flake check --no-build --all-systems exits 0; grep -n $'—' docs/adr/*.md finds nothing; 27 relative links and 2 anchors in docs/adr/*.md, docs/architecture.md and README.md resolve.

[Soushi888]

SoushAI analysis. Drafted by Soushi's AI assistant, reviewed and posted by @Soushi888.

Merged origin/main into docs/adr (47d9097) to bring the branch up to date after #36, #48, #49, #25, #34 and #62 landed. No rebase, no force-push.

Conflict resolved

• README.md, the docs/ layout tree: feat(release): CHANGELOG and a tag-driven release workflow #49 added releasing.md at the line where this PR adds adr/. Both lines are kept, releasing.md first. That is the only conflict; docs/architecture.md merged on its own.

What did not change

• The review found no blocking items, so the ADR files, the index and the "Design record" section are untouched. The diff against main is still docs only: 16 files, +408/-0.
• The index claim still holds on the merged tree: every ADR number cited outside docs/adr/ falls in 005 to 017 (the 001 and 004 hits are the architecture sentence that says they are not published), and none of the newly merged files cites an ADR.
• No CHANGELOG line: nothing here is visible to someone running the modules, which is the bar CONTRIBUTING.md sets.

Local checks on 47d9097

• nix flake check --no-build: exit 0, every check derivation evaluates, including the new holochain-bootstrap VM test from feat: holochain-bootstrap module and relayAllowPlainText #62.
• Option reference: diff <(cat "$(nix build .#options-doc --print-out-paths)") docs/module-options.md prints options-doc in sync.
• Every relative link in docs/adr/*.md and docs/architecture.md resolves.

Left for later, as the review suggested

• ADR-017 still carries the open UEFI/Secure Boot question. Once the Holoport install work from the lab branch reaches main, a Later record entry citing scripts/holoport-install.sh, the SeaBIOS VM test and the 2026-09-27 install on sensorica-holoport-01 closes it.
• When the Moss node doc (feat(packages): Moss wdocker 0.15.8 with its pinned Holochain 0.6.1 #60) lands, its moss-node.md line goes into the same docs/ tree block; keep both.