diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 4796062a7ee2ff19a2c3fd181f6635f2843efcf0..1d653a1ff2312495f33761f061679e8e4c825f62 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -47,6 +47,7 @@ | Relationship to existing doc homes | **New home for agent-authored specs only.** `second-brain`, the Confluence-synced RFCs, yonote and ultrapack task files stay independent and untouched. Read-only mounts stay in the model as an escape hatch but drop out of v1. | | Audience | **Single-user: bigbes plus his agents.** No other human reads or reviews. Approval collapses to triage; visibility levels, approver lists and approval counts drop from v1. | | Cadence | **Bimodal.** Specs/RFCs get careful review; research notes and reports flow through with light or automatic approval. `.spec.yml` policy carries the split. | | Human edit path | **`git clone`, edit locally, push.** The web editor is not v1 and may never be. This makes a real git remote a v1 requirement — see "Two write paths" below. | +| Review surface | **Browser, reached by a link the agent hands you.** Confirms the prose differ as a v1 build and keeps it as the Phase 0 gate. The inbox is the backstop for work no link reached, not the primary entry point. | ## Architecture summary @@ -356,11 +357,31 @@ The write always lands on `proposals/`, never on the approved branch. ### 3. Review plane (humans) -**The inbox is the product.** The landing page is "N proposals waiting on you", -not a file browser. A proposal page shows the prose diff, per-document, with -approve (which merges immediately) or reject, and (post-v1) inline comments. -There is no request-changes cycle and no web editor: with one reviewer, changes -are made by rejecting and re-proposing, or by editing locally and pushing. +**Review happens in a browser** (user-confirmed), which keeps the prose differ on +the critical path and keeps the Phase 0 gate as written. + +**The link is the entry point; the inbox is the backstop.** The normal flow is +that an agent finishes, hands you a URL, and you open it — you are usually +already talking to the agent when it proposes, so a link beats going to look for +one. Two things follow, and the first is an API requirement rather than a UI +nicety: + +- **Every write response carries the proposal URL.** `spec_propose` over MCP and + the REST `PUT` both return `{proposal, url}`, so the agent can say + *"proposed: https://spec.srht.bigb.es/~bigbes/rfcs/p/42"* in the transcript. + An agent that proposes without surfacing a link makes the work invisible. +- **Proposal URLs are stable and shareable** — they outlive the branch, so a link + still resolves after merge or rejection, showing the outcome. + +The inbox ("N proposals waiting on you") then catches what no link reached: work +from unattended agents, cron-driven runs, and anything proposed while you were +away. It shares the page with the digest of policy-merged firehose content, which +has the same problem — nobody handed you a link for it either. + +A proposal page shows the prose diff, per-document, with approve (which merges +immediately) or reject, and (post-v1) inline comments. There is no +request-changes cycle and no web editor: with one reviewer, changes are made by +rejecting and re-proposing, or by editing locally and pushing. ## Merge model: no text merge, ever @@ -715,7 +736,8 @@ **Phase 3 — write plane.** Proposals, `If-Match` concurrency, the merge model, agent tokens + scoping + provenance trailers, REST + MCP write tools. MCP tools and GraphQL resolvers share one service layer — no parallel implementations. -**Phase 4 — review plane.** Inbox, prose diff, approve / reject, status +**Phase 4 — review plane.** Proposal pages at stable URLs (returned by every +write, so agents can hand you a link), inbox, prose diff, approve / reject, status lifecycle, and the **digest of policy-merged content** (the firehose half is unreviewed by design, so it must at least be *visible* or it rots silently). @@ -765,33 +787,27 @@ ### Raised by review, awaiting a decision Ordered by how much the answer would change the build: -1. **Would review happen in a browser, or at a terminal?** `git fetch origin - proposals/42 && git diff` with a local word-diff is a workflow that exists - today. If terminal review is acceptable even initially, the prose-diff - renderer and most of the review plane — the largest net-new component and the - Phase 0 gate — leave v1, shrinking it to storage + hooks + read plane + - proposal API. -2. **Do agents genuinely need `?rev=` pinning and the approved/draft split?** It +1. **Do agents genuinely need `?rev=` pinning and the approved/draft split?** It is a founding premise of this document, but if every real consumer just wants "current approved text", the pinning machinery, the dual read path, and part of the token-scope model all simplify. -3. **Is the materialized checkout a requirement or an implementation detail?** +2. **Is the materialized checkout a requirement or an implementation detail?** Dropping it for blob reads at the approved ref plus a render cache removes the atomic-swap problem, the staleness coupling, and a whole cache tier — at the cost of a deeper rework of warren's file-oriented scan. -4. **What is the real firehose volume?** Decides whether full-index-rebuild-on- +3. **What is the real firehose volume?** Decides whether full-index-rebuild-on- merge is fine (deleting the incremental-indexing work), whether retention matters, and whether merge contention is real or theoretical. -5. **Scoped per-agent tokens in v1, or one token plus mandatory provenance?** If +4. **Scoped per-agent tokens in v1, or one token plus mandatory provenance?** If every agent is a Claude Code session you launched, one token and trailers give full provenance for a fraction of the machinery; scoping can arrive when a genuinely autonomous agent does. -6. **Should your own pushes be validated at all, or are you trusted absolutely?** +5. **Should your own pushes be validated at all, or are you trusted absolutely?** If you can push whatever you like, the `update` hook shrinks to "no force-push on approved" and the entire validation stack lives only in the API path, where it is in-process and easy. -7. **Will existing corpora ever be imported or mounted?** If the honest answer is +6. **Will existing corpora ever be imported or mounted?** If the honest answer is never, delete mounts from this document entirely. -8. **Is `spec` the final name?** Low architectural leverage, but it locks the +7. **Is `spec` the final name?** Low architectural leverage, but it locks the config section, DNS, module path and nav entry on day one, and every example here already hardcodes it.