docs: bring all documentation current with shipped work

A multi-agent audit of every doc against the code surfaced ~50 stale/missing
items (the roadmap/status docs and the backlog had fallen behind the code).
This catches them up:

- CLAUDE.md: phase status was ~3 phases stale ("Phase 1 is next" while Phase 1 +
  chunks of 2 & 4 shipped). Rewrote the status list; added a model-provider
  tech-stack entry; updated repo-layout (integrations objectstore/models,
  deploy backup.sh/dev compose).
- ARCHITECTURE.md: §6 privacy engine described 3 visibility levels — corrected to
  the shipped 4 (adds site_members); documented per-tree AI policy on Tree,
  LLMProvider/EmbeddingProvider split + registry, ChangeProposal origin/status/
  operations, verified-email session gate, instance-owner role, schema-drift
  guard, and the env_file config model.
- PRD.md: 4-level visibility in US-040/§5.5, instance-owner role (§5.1/§5.11),
  per-tree AI policy (§5.8), §8 sequencing annotated with shipped status, header
  date/status bumped.
- README.md: 4-level privacy; softened "Full GEDCOM 7" to the 5.5.1/7 common
  subset; noted backups + instance-owner admin; moved property/land to an
  explicit "where it's headed" (no property models exist yet).
- BACKLOG.md: flipped ~15 shipped-but-open rows to Have (ChangeProposal, provider
  abstraction, GEDCOM citation export, membership management, operator backup,
  email-verification gate, per-tree AI policy, instance owner, the whole
  visibility/public-viewing/child-resource-redaction cluster #41-#51/#46), and
  reconciled the executive summary, "current defects" list, quick wins, and
  differentiators. Left genuinely-open items (citation/source redaction, sitemap,
  per-tree noindex, scoped-token API) accurately open.
- .env.example: dropped "SMTP wired in a later phase"; documented the worker
  purge knobs, S3_PRESIGN_TTL, COOKIE_NAME; removed a stray duplicate line.
- design/: tree-visibility.md and change-proposal.md marked Shipped; corrected
  the redaction approach (reuses member schemas, not a separate PublicPersonRead)
  and the apply() rollback claim (v1 is not cross-op transactional), and marked
  rate-limiting/sitemap/noindex as deferred.

No code changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>
This commit is contained in:
2026-06-10 21:05:29 -04:00
parent 0388b9b99f
commit 447daf7fa8
8 changed files with 135 additions and 96 deletions
+6 -2
View File
@@ -1,6 +1,8 @@
# Design note: ChangeProposal (propose-then-confirm)
Status: **in progress**. Implements non-negotiable #1 (CLAUDE.md): *the AI
Status: **Shipped (#214/#236)** — model, service, API, and review UI landed; the
assistant producer and cross-op transactional apply remain as follow-ups (see
Out of scope). Implements non-negotiable #1 (CLAUDE.md): *the AI
assistant never writes autonomously.* Every assistant "write" emits a
**ChangeProposal** — a structured diff a human approves, edits, or rejects.
@@ -63,7 +65,9 @@ is a follow-up (it needs the services to accept a no-commit mode).
- `apply(session, *, actor, tree, proposal_id, edited_operations=None) -> ChangeProposal`
— editor-only. Optional `edited_operations` lets the reviewer tweak the diff
before applying ("edit" in approve/edit/reject). Dispatches each op through the
editing services; on any failure, rolls back and records `apply_error`.
editing services; on failure it records `apply_error` and leaves the proposal
pending — it does **not** roll back ops already committed by earlier dispatches
(v1 is not cross-op transactional; see Data model).
- `reject(session, *, actor, tree, proposal_id, note=None)` — editor-only.
## API