From f0dcfb4dbb69cec756220dd8102c9a27f53eb7a8 Mon Sep 17 00:00:00 2001 From: bigbes Date: Wed, 22 Jul 2026 10:08:40 +0300 Subject: [PATCH] docs: confirm browser review, and make the link the entry point Review happens in a browser, so the prose differ stays in v1 and remains the Phase 0 gate. The link, not the inbox, is the normal way in: you are usually already talking to an agent when it proposes, so every write response must carry the proposal URL for the agent to surface. Proposal URLs are stable past merge or rejection. The inbox demotes to a backstop for unattended work, sharing a page with the policy-merged digest, which is invisible for the same reason. --- docs/DESIGN.md | 54 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 19 deletions(-) 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 @@ modification**. Runs at `https://spec.srht.bigb.es`. | 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 @@ machinery exists. 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 @@ the concurrent-web-edit-vs-push conflict problem it would have created. 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.