Skip to content

Add trust, defaults, reversibility and formats to the existing design rules #421

Open

Description

@cuibonobo

Problem

The spec already practices several principles without stating them, so a reviewer can't cite them and a new section can drift from them:

  • wire-format.md § Identity is trusted on transport notes the spec is "otherwise scrupulous about naming exactly this kind of asymmetry", but no rule asks for it.
  • Defaults like create: 'never' and the refusal of undeclared fields come with their reasons, but nothing says a default must.
  • Soft delete before purge, restore as a new version, and deleting a Group withdrawing it are all chosen for recoverability, without a stated rule.
  • Nothing says that a format a person might need to recover their data (an export, a recovery share, a sealed Record) must be specified, not left to the tool that writes it.

Decision

Add each principle to the rule set that already governs its kind of change, rather than a new section:

  • CONTRIBUTING.md § The spec is the source of truth (and its short form in AGENTS.md):
    • Name every trust asymmetry. Where one party must trust another without proof, the spec says so.
    • A default is a decision. Where the spec is silent, a default still governs, so state it and why.
  • CONTRIBUTING.md § Architecture conventions (and AGENTS.md § Architecture rules):
    • Formats live in the spec, not in tooling. Anything a person needs to recover their data is decodable from the spec without the tool that wrote it.
  • docs/spec/data-model.md, beside the existing inline design principle on native fields versus content:
    • Prefer what can be undone. Recoverable operations come first; irreversible ones are carved out and named.

"Leaving never needs permission" waits for the export work to land, since today it would describe a promise the system doesn't keep yet.

Actions

  • The four additions above, each one or two sentences, linking an existing section as its example.
  • No changeset: docs and repo guidance only.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions