1 files changed, 35 insertions(+), 19 deletions(-)

M 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/<id>`, 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.