[itercharles]

Summary

Charter iteration 3, approval and accountability. The branch went through three designs; its history keeps them, and the ADR records why the first two were dropped. What it delivers is the last one.

ADR-004: Signed Approval of Released Documents (Proposed)

• What the inventory found: approval lives only in GitHub; 95 of ContourLab's last 100 merged PRs had no standing approval; approvals carry no meaning; their identity is within an agent's reach.
• During development: pull-request review only, under the team's rules. That includes the CCB accepting and closing CRs. Nothing waits on a signature, and today's gates are unchanged.
• At release: a pipeline started on purpose (in ContourLab, release-baseline.yml, not a merge) writes a manifest and a change report. Each specification is signed by the role that owns its type, and the quality lead signs the release.
• What is signed: the manifest's entry for each document, which lists the items and their content hashes. The rendered file is not signed, because rendering is not byte-stable; its hash is recorded alongside.
• Evidence is kept for the life of the device. The ContourLab artifact kept for 90 days is not enough.
• Dropped: per-item signatures checked at merge, and a CCB signature on each CR.

Implementation

• Approvers list DHF/config/approvers.yaml (people, roles, public keys).

  • A change to it must be signed by someone already on the list.
  • The first list is a stated root of trust.

• Roles: approval_roles (item type → role that signs its specification) and release_role in global.yaml.

• build release --write also writes:

  • DHF/releases/<version>/manifest.yaml: per document, its items and hashes, plus the rendered file's hash, the DHF hash and the approvers-list hash;
  • changes.md: per document, items added, modified and removed since the previous release, with their CRs.

  REL items are left out of both, so a REL moving through its states after signing is not drift.

• item approve --release V --key <private key>:

  • shows the signer the changes;
  • writes one record covering every document the signer's roles own, plus the release for release_role;
  • signs it with ssh-keygen -Y sign, never through ssh-agent.

• Approval log: DHF/approvals/<scope>/<ULID>.yaml with .sig. Records are append-only, never loaded by the item store, and collision-free across branches.

• verify approval checks that the log is sound on any PR: signatures, append-only, the approvers guard. It never asks for a signature.

• verify approval --release V additionally requires a signature from each document's role over the document's current hash, and the quality lead's signature over the manifest. It also fails if the manifest no longer matches the DHF.

• Off until configured: without an approvers list, existing projects see no change.

Not in this PR

• Updating the docs that say "approval is not a command" (CLAUDE.md prose, interface.md, ai-security.md).
• Durable storage of rendered documents in ContourLab's release pipeline.
• ContourLab adoption.

Known limits (ADR open questions)

• Presence is declared, not proven. OpenSSH's allowed_signers cannot require the user-presence flag. No test uses a real hardware key.
• Removing an approver's key would invalidate the signatures it made in past releases. The list needs revoked keys.
• Release order for changes.md compares the numbers in the version: 1.10.0 sorts after 1.9.0, and a pre-release suffix sorts above its release.

Validation

• Full suite: 2082 passed, 9 skipped, 3 xfailed.
• scripts/generate_interface.py run; CHANGELOG under Unreleased; no version bump.

Manual review

• Implemented by Sonnet subagents, then reviewed. I fixed one issue myself: the REL was in dhf_hash, so approving the REL after signing read as drift. A test now covers it.

🤖 Generated with Claude Code