_type: issue

title: Phase 3: write plane — agents propose

description: The agent half of the loop, and the service's whole premise: an agent proposes a document change, gets back a link, a human approves in a browser. Until this ships, agents can only read.

design: Scope: proposals (branch proposals/<id> + Postgres row, state open->merged|rejected); the If-Match tree-splice merge with the four staleness cases and the ancestry check gitx flagged; the single agent token + mandatory provenance trailers; spec_propose / spec_comment over REST + MCP; every write response returns {proposal, url} so the agent can hand over a link. Prereqs found during Phases 1-2: (1) service.ListProposals(space, state) — graph proposal listing is stubbed and db only has ListProposalsByState; (2) IsAncestor(proposalHead, H) check before Merge so an already-merged proposal reports 'already merged' not a confusing 409; (3) auto-merge policy evaluation (.spec.yml AutoMerges) which the reconciler's 'approval=policy' inference also wants. Dispatch like Phases 1-2: proposal orchestration in service/ first and committed, then surface tools fan out. This is where the merge model and reconciler first run under real proposals rather than on paper.

status: open

issue_type: feature

created_by: Eugene Blikh

issue_id: spec-zqb

depends_on_id: spec-ejq

type: parent-child


title: spec.sr.ht — reviewable document storage for humans and agents

description: A third custom Go service on the self-hosted SourceHut instance: agents propose documents, a human reviews and curates, agents read the approved text. One loop — bot produces, human curates, bots consume. Runs at https://spec.srht.bigb.es, deployed on phoebe as srht-spec-1. Code: git.sourcecraft.dev/bigbes/sr-ht-spec. Design: docs/DESIGN.md.

design: DONE and deployed (Phases 0-2): core domain, gitx (bare repos + id-keyed tree-splice merge), db (Postgres schema + global ID registry), authn (unified-login cookie + agent tokens + provenance), the three receive hooks + hook RPC + daemon, service layer + reconciler, doc (warren vault/render on git objects), search (one global bleve index, per-line ru/en routing), projects (saved filter, not container), web read UI, mcpsrv read tools, graph read schema, prosediff (Phase 0 gate PASSED), specsrht space create/list, push->reindex. Live corpus: ~bigbes/rfcs holds SPEC-0001 and NOTE-0001. Verified end-to-end: validating push path, fail-closed reads, id-addressing, bilingual search, GraphQL. NOT DONE: the agent half of the loop (write plane), review UI, comments.

issue_type: epic


title: Stale apk pins: paste.sr.ht 0.19.3-r0 and hub.sr.ht 0.29.4-r0 aged off the mirror

description: Pre-existing, not caused by spec.sr.ht — but a FULL stack rebuild (post_push) would fail on these two apk layers and leave the stack un-deployable (the 2026-07-11 incident pattern). The self-hosted append-only repo.bigb.es mirror only preserves what it has seen, and it started after these aged off; old versions are unrecoverable.

design: spec.sr.ht was deployed AROUND this with labng push --no-restart + a single-service 'docker compose build spec', so nothing else rebuilt. To fix properly: bump the two pins in versions.env to what the mirror currently ships (paste 0.19.4-r0, hub 0.31.1-r0 as of 2026-07-22). hub 0.29.4->0.31.1 crosses two minors with forward-only migrations — pg_dumpall first per the stack CLAUDE.md. Kept separate from the spec deploy deliberately.

issue_type: bug


title: Restart other SourceHut services so spec.sr.ht appears in their nav

description: The switcher entry is config-driven: each service builds its own nav from config sections ending in .sr.ht. spec.sr.ht is in the shared config.ini now, but the OTHER services (git, meta, todo, ...) only pick up the new entry on restart. Not done unprompted because it briefly bounces every service. On phoebe: docker compose restart <the sourcehut services>.

issue_type: task


title: Phase 4: review plane — approve/reject in a browser

description: Proposal pages at stable URLs (returned by every write), the inbox, prose diff, approve (merges immediately) / reject, status lifecycle, and the digest of policy-merged firehose content.

design: Productionise prosediff (the Phase 0 spike) into the review UI. CRITICAL requirement from the Phase 0 verdict: 13% of real prose modifications shred into interleaved fragments (similarity <= 0.73), so the UI MUST switch to a two-column old/new view below ~0.75 and inline word diffs above it — building only the inline renderer makes one review in eight unreadable. The prosediff package already emits the (Hash, HeadingPath, Ordinal) comment-anchor tuple. Reads a proposal branch via service.ReadDocumentAtRef (the deliberately-awkward bypass), never the normal read path.

depends_on_id: spec-zqb

type: blocks


title: Loose ends from Phases 1-2 (latent bugs, no user impact yet)

description: Real issues agents flagged and deliberately left alone during the parallel build. None blocks anything today; each is a trap for a later phase.

design: 1. ProposalBranch derived THREE ways: core.ProposalBranch (canonical), and a third copy in SQL — db.OpenProposal concatenates prefix||serial in its INSERT to allocate id+branch atomically. Shares the prefix constant but not the function; reconcile if they can ever diverge. 2. doc.linkHierarchy passes path.Dir(p.Path) i.e. '.' as fromDir where every other call site uses DirOf ('') — section-proximity lookup misses for root-level parent: targets. Latent; fixing changes resolution behaviour. 3. doc.SplitLog collides entry IDs within a space (two type:log docs -> identical IDs -> second silently overwrites first in one index). Defended in search/ but should be fixed at source in doc/. 4. doc.Scan/DocumentSource are production-dead after service.Archive landed — they're the documented seam but also the API that made web's layering violation writable; delete is a judgement call. 5. mcpsrv ships a beforeCAS test hook in production code (gitx too). 6. No GraphQL complexity limit — service authenticates on its own router, not core-go's WithSchema, so nothing bounds query cost; low risk on a single-user authed surface. 7. Attachments: gitx walks .md only, so image embeds render as visibly-missing; needs WalkBlobs + asset index, or prefer Mermaid by convention.

issue_type: chore

issue_id: spec-wcr


title: Phase 5: comments, webhooks, mutations, vector search

description: The deferred pile, each unblocked once its prerequisite lands.

design: Inline comments (anchor tuple already emitted by prosediff; settle resolution against the built review UI before committing a schema). Webhooks + notifications (core-go/webhooks is GraphQL-native; the Phase 2 read schema is the foundation). GraphQL mutations once the proposal state machine stops moving. Vector search over the project index (warren's embed/ was deliberately not ported). Per-space token scoping (currently one token; scoping is a column + filter clause). Read-only mounts of external corpora (second-brain, Confluence RFCs) if the boundary ever moves — global IDs keep the door open.