_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: closed

issue_type: feature

assignee: Eugene Blikh

created_by: Eugene Blikh

close_reason: Write plane shipped: service.Propose/Merge/Reject/ListProposals with provenance trailers, auto-merge policy, If-Match staleness + already-merged ancestry check; surfaces graph (Proposals port), mcpsrv spec_propose, and new api/ REST PUT — every write returns {proposal, url}. Validated end-to-end against Postgres. spec_comment deliberately deferred to Phase 5 (spec-by6), which gates the comment schema on the Phase 4 review UI; the approve/reject browser UI is Phase 4 (spec-3vz).

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.

status: open

issue_type: epic


title: web: commentable diff — context blocks, anchor ids, comment UI

description: renderDocDiff currently skips ChangeEqual ('the review shows only what changed', web/diff.go:61). It must now render unchanged blocks as commentable context — collapsed or dimmed so the diff still reads as a diff — because the settled scope is that any block of a proposed document can be commented on. Every rendered block gains a stable DOM id derived from the anchor tuple. Then the comment UI itself: existing comments rendered beside their block with their anchor state (moved / outdated shown honestly), a compose form, reply and resolve. Threading is flat per anchor.

issue_type: task

type: blocks


title: service: comment API + policy auto-merge gate

description: service.Comment type, Comment/ListComments/ReplyComment/ResolveComment, and the anchor resolution pass that takes a revision's prosediff blocks and reports each comment as anchored, moved or outdated. Wire the merge gate: an unresolved comment suppresses policy auto-merge (not manual approve) — the check belongs beside the existing auto-merge policy evaluation, and needs a test that a commented proposal stops auto-merging while Merge with human approval still succeeds.


title: Comment anchors: core type + db schema

description: Foundation wave. core.CommentAnchor (doc_id, heading_path, ordinal, hash) plus the anchor-state vocabulary (anchored | moved | outdated) and the resolution function, kept free of a prosediff import so core stays dependency-free — resolution takes the block fields it needs, not the Block type. migrations/0004_comment.sql + schema.sql: the comment table storing the tuple, threading via parent_id, author identity + agent provenance (mirroring proposal's ck_proposal_provenance rule), and resolved timestamp. Anchor state is NOT a column — it is derived per revision at read time. db/comment.go with the insert/list/resolve queries and a test that a reflow keeps the comment and a deletion outdates it.

close_reason: core.CommentAnchor + ResolveAnchor with 9 tests; migrations/0004_comment.sql + schema.sql; db/comment.go with 8 Postgres-backed tests, all green against real PG 16.


title: Phase 5b: inline comments on proposals

description:
Close the propose->critique->revise loop: the owner comments on blocks of a proposed document, the agent reads the comments, replies, and pushes a revision. Anchors re-resolve against the new revision rather than being lost.

Design gate cleared 2026-07-24: DESIGN.md deferred the comment schema until the Phase 4 review UI existed. It exists, and three facts from it shape the work: the review page renders only changed blocks (web/diff.go:61); the read view uses a different block model (doc.Renderer/goldmark, web/handlers.go:437) from the review view (prosediff.Segment); no rendered block carries a DOM id.

design:
ANCHOR MODEL (as DESIGN.md:793-808 specifies, implemented not revisited):
tuple = (doc_id, heading_path, block_ordinal, block_hash). Resolve against a
revision by block_hash first; fall back to heading_path + ordinal; when both
fail mark the comment OUTDATED rather than relocating it. heading_path is
deliberately NOT part of the hash, so renaming a section does not dirty every
block beneath it and orphan its comments at once. Anchor on doc_id, not path,
so comments survive renames.

ANCHOR STATE IS DERIVED, NOT STORED. A comment is not outdated in general, it
is outdated AT a revision, and a proposal branch moves under it. The DB stores
the tuple; resolution runs at read time against the revision being displayed.

SIDE: a comment anchors to the NEW side of a modified block (that is the text
under review) and to the OLD side of a pure deletion.

SCOPE DECISIONS (settled with owner 2026-07-24):
1. Surface: the review page, ALL blocks — not only changed ones. This changes
   the diff view rule: renderDocDiff currently skips ChangeEqual entirely, and
   must instead render unchanged blocks as commentable context. Comments on
   approved documents (the read view) stay out of scope: that needs prosediff
   segmentation of the read path plus a goldmark<->prosediff block mapping.
2. Merge gate: an unresolved comment suppresses POLICY AUTO-MERGE only. Manual
   approve still works — human judgement wins. Rationale: a comment means the
   owner engaged, so the proposal must not slip through unattended; but a stale
   comment must not be able to wedge a proposal.
3. Agents: read + reply + revise via spec_comment. Agents may NOT resolve —
   an agent marking its own critique resolved defeats the gate.

acceptance_criteria: A comment survives a revision that reflows its paragraph (hash miss, heading-path+ordinal hit) and is reported as moved, not lost. A comment whose block is deleted is reported outdated, never relocated. An unresolved comment prevents policy auto-merge and does not prevent manual approve. An agent can read and reply to comments on its own proposal but cannot resolve one.


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

close_reason: Stale apk pins already bumped in the stack versions.env (paste 0.19.4-r0, hub 0.31.1-r0); fixed out of band.


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>.


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.

close_reason: Review plane shipped: proposal page at /~owner/space/p/<id> with the prose diff (inline word-diff above 0.75 similarity, two-column old/new below — the Phase 0 verdict's hard requirement, in web/diff.go), approve(merge)/reject as owner-only CSRF-guarded POSTs, status badges, and the /inbox review queue + policy-merged digest. service.ProposalDiff/InboxProposals/DigestProposals/MergeHuman back it; web.Reader extended. Diff reads the proposal branch by resolving its tip to a sha (pinned read) rather than the ReadDocumentAtRef bypass — cleaner and immutable. Validated: diff renderer unit tests (inline/two-column/escaping), proposal-page + approve/reject handler tests (CSRF, owner-only, stale->409, wrong-space->404), inbox tests, and PG-backed service tests. Follow-up: digest_mark 'since last seen' tracking.

depends_on_id: spec-zqb


title: mcpsrv: spec_comment tool (read + reply, no resolve)

description: The agent half of the loop. spec_comment lets an agent list the comments on a proposal it authored and reply to them; it must NOT resolve one, since an agent marking its own critique resolved defeats the auto-merge gate. Reuses the Phase 3 provenance path (agent + agent_session) for reply authorship, and the existing owner+agents read gate from spec-jjo. mcpsrv/mcpsrv.go:39 still documents spec_comment as deliberately absent — update that comment when it lands.


title: Attachments: image embeds render as visibly missing

description: gitx walks .md only, so an archive built from a git tree has no attachment index and ![[diagram.png]] resolves to a visibly-missing link. doc.FromPages already accepts an assets map — the gap is producing one. Two options: (a) gitx.WalkBlobs + an asset index threaded through service.Archive, plus a read-plane route serving the blob; (b) adopt Mermaid-by-convention and document that binary attachments are out of scope. Carried over from spec-wcr item 7 (triaged 2026-07-24: a feature, not a latent bug).


title: Phase 5a-2: webhook tables, SDL, resolvers, delivery on proposal open/merge/reject

description: On top of 5a-1: gql_proposal_wh_sub/_delivery tables + migration, WebhookSubscription/Delivery/Payload SDL, create/delete mutations + webhooks queries, and fire via webhooks.Schedule on proposal lifecycle events (service event hook -> queue). Reference pages.sr.ht webhooks/webhooks.go + graph/model/webhooks.go.

close_reason: Webhook tables/SDL/resolvers/delivery all shipped and verified end-to-end.


title: Phase 5a-1: adopt core-go graph conventions (directives, database.Model, cursors, auth+user model)

description: Retrofit spec's minimal hand-written graph onto core-go's stack, the prerequisite for GraphQL-native webhooks. Per pages.sr.ht: @access/@private directives + impls, core-go database.Model for space/document/proposal/project/search types, cursor pagination, core-go auth.Middleware + a single-owner user table. Blueprint from ~/data/home/tmp/pages.sr.ht.

close_reason: Adopted core-go server stack for /query (faithful path); the convention pieces webhooks needed (auth/database/server context, database.Model for webhook models, gqlgen) are in.


title: Phase 5a: webhooks + notifications on proposal lifecycle

description: Phase 5a: webhooks via FULL core-go convention adoption (user chose to match pages.sr.ht/lists.sr.ht byte-for-byte). Prerequisite: retrofit graph/ onto core-go conventions (database.Model, @access/@private directives, cursor pagination, auth.Middleware + a user model with OAuth2 scopes). Then add gql_proposal_wh_sub/_delivery + webhook SDL/resolvers/delivery on top. Reference: ~/data/home/tmp/pages.sr.ht (same fork). Large graph rewrite, not additive.

close_reason: Phase 5a webhooks complete: DB + authn→AuthContext bridge + GraphQL surface + core-go server wiring + firing. Verified live: agent REST propose delivers an Ed25519-signed POST whose body is the subscription query executed against the ProposalEvent payload; delivery recorded.


title: Digest should track 'since you last looked' via digest_mark, not just show recent policy-merges

description: Phase 4 ships the policy-merged digest as 'recent policy-merged proposals' (service.DigestProposals). The design intends it as 'what auto-merged since you last saw the digest', backed by the digest_mark table (db.GetDigestMark/SetDigestMark, already present). Advancing the mark is a write, and the inbox GET is deliberately kept pure, so this needs either a POST 'mark as seen' action or an accepted side-effecting GET. Low priority: the digest already surfaces auto-merged content, which is its core purpose.

close_reason: Inbox GET reads digest_mark to flag/count new-since-last-looked auto-merges + divider (pure read); explicit POST /inbox/seen advances the mark behind owner-only + same-origin guard. service.DigestMark/MarkDigestSeen added. Commit 865a21f.

issue_id: spec-mfm


title: MCP read tools (/mcp) have no auth gate — reads are open behind the Host check

description: Phase 3 added the resolver middleware to /mcp so spec_propose can resolve the agent, but the read tools (spec_search/spec_read/spec_list) still have no ACL: anyone passing the Host allowlist can read approved content. graph's /query gates to owner+agents (graph.gate); /mcp does not. The design's read plane is fail-closed (owner+agents only). Add the same gate to the MCP surface. Pre-existing since Phase 2; not caused by Phase 3, but now that /mcp resolves a principal the gate is a one-liner. Deliberately left out of Phase 3 to avoid changing Phase 2 read behavior mid-feature.

close_reason: MCP surface gated to owner+agents (mcpsrv.Gate), mounted inside resolver middleware; tests cover anon 401 / owner+agent pass / fail-closed without middleware. Commit 7cc652d.

issue_id: spec-jjo


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.

notes:
RESOLVED 2026-07-24. All 7 items dispositioned.

#1 ProposalBranch 3rd copy in OpenProposal SQL — FIXED (e97532c), guard test.

#2 linkHierarchy path.Dir vs DirOf — FIXED. Prior triage called this a
judgement call that 'changes resolution behaviour'; that was wrong. Traced it:
path.Dir and DirOf differ only for root-level documents, and there the
section-proximity step (stemsIn[topSection(fromDir)+'/'+bare]) is subsumed by
the same-directory step above it — stemsIn['/x'] is populated only by a root
x.md, which byPath['x.md'] already returned. So '.' only ever skipped a lookup
that had already answered. VERIFIED by reverting to path.Dir and re-running:
identical results. Changed to DirOf as trap-removal, with
TestParentResolvesLikeAWikilinkFromTheSameDocument pinning the invariant
(parent: resolves to what the same wikilink in the body resolves to).

#3 SplitLog id collision — WONTFIX. Already correctly defended in
search/extract.go; 'fixing at source' would push index-keyspace uniqueness into
doc/, which shouldn't know it is indexed into a shared space index.

#4 delete doc.Scan/DocumentSource — DONE. Confirmed production-dead (only
consumer was doc's own test fixture). Deleted both; doc/ now owns no way to read
a revision, leaving service.Archive as the single route from rev to Archive —
closing the seam that made web's layering violation writable. doc test fixture
rewritten onto ListDocuments+FromDocuments; TestScanReportsGitErrors relocated
to gitx as TestWalkOfAnUnknownRevisionFails (gitx had no unknown-rev coverage).

#5 beforeCAS test hook — WONTFIX. Unexported, set only by same-package tests,
cannot be set externally. Standard test-seam pattern; mcpsrv has no such hook.

#6 GraphQL complexity limit — moved to spec-by6.1 (feature, Phase 5).
#7 attachments — moved to spec-by6.2 (feature, Phase 5).

issue_type: chore

close_reason: All 7 items dispositioned: 2 fixed (#1,#2), 1 deleted (#4), 2 wontfix (#3,#5), 2 moved to Phase 5 (spec-by6.1, spec-by6.2).

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.


title: GraphQL complexity limit on the /query surface

description: spec.sr.ht authenticates on its own router rather than core-go's WithSchema, so nothing bounds query cost — no depth or complexity limit on /query. Low risk today: the surface is single-user and authenticated. Wire a limit if /query is ever widened beyond owner+agents. Carried over from spec-wcr item 6 (triaged 2026-07-24: a feature, not a latent bug).


title: Consolidate owner+agents read predicate into one Principal.CanRead()

description: graph/server.go:161, web/handlers.go:61 and now mcpsrv.Gate each hand-spell 'IsOwner() || IsAgent()'. graph.gate's own comment warns two read surfaces with two policies is how a corpus leaks — there are now three copies. Add authn.Principal.CanRead() and route all three through it so the policy is defined once. Low-risk mechanical refactor; deferred out of spec-jjo to keep that bug fix surgical.

close_reason: authn.Principal.CanRead() defined once; graph.gate, web.mayRead, mcpsrv.Gate routed through it. coreauth left independent (different semantic). Unit test covers owner/agent true, anon/zero/unknown false. Commit pending push.