~bigbes/sr-ht-spec · parade

main · last commit 18 hours ago · 8tmadfpi

← Back to the parade

spec-by6.3 Phase 5b: inline comments on proposals Past Stand

status: closed P2 feature
bd reopen spec-by6.3
Created byEugene Blikh
Ownerbigbes@gmail.com
Created2026-07-24T18:56:37Z
Updated2026-07-24T19:59:29Z
Closed2026-07-24T19:59:29Z
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.

Depends on

  • spec-by6 — Phase 5: comments, webhooks, mutations, vector search parent-child open

Depended on by

  • spec-by6.3.2 — service: comment API + policy auto-merge gate parent-child
  • spec-by6.3.4 — mcpsrv: spec_comment tool (read + reply, no resolve) parent-child
  • spec-by6.3.3 — web: commentable diff — context blocks, anchor ids, comment UI parent-child
  • spec-by6.3.1 — Comment anchors: core type + db schema parent-child
  • spec-by6.3.5 — Port review UI to a line-numbered unified prose diff parent-child

Prerequisite chain — everything this waits on, transitively

  • spec-by6 — Phase 5: comments, webhooks, mutations, vector search parent-child open
  • spec-3vz — Phase 4: review plane — approve/reject in a browser blocks closed
  • spec-ejq — spec.sr.ht — reviewable document storage for humans and agents parent-child open
  • spec-zqb — Phase 3: write plane — agents propose blocks closed

Unblocks — everything waiting on this, transitively

  • spec-by6.3.2 — service: comment API + policy auto-merge gate parent-child closed
  • spec-by6.3.4 — mcpsrv: spec_comment tool (read + reply, no resolve) blocks closed
  • spec-by6.3.3 — web: commentable diff — context blocks, anchor ids, comment UI blocks closed
  • spec-by6.3.1 — Comment anchors: core type + db schema parent-child closed
  • spec-by6.3.5 — Port review UI to a line-numbered unified prose diff parent-child closed

No comments.

Close reason

All four children done: core+db anchors (1a25367), service API + auto-merge gate (c6e5d66), mcpsrv spec_comment (f82d90a), web commentable diff (472bcb1).
  • Eugene Blikh added under epic spec-by6 · 2026-07-24T21:56:36Z
  • Eugene Blikh created the issue · 2026-07-24T21:56:36Z
  • Eugene Blikh added subtask spec-by6.3.1 · 2026-07-24T21:57:01Z
  • Eugene Blikh added subtask spec-by6.3.2 · 2026-07-24T21:57:05Z
  • Eugene Blikh added subtask spec-by6.3.3 · 2026-07-24T21:57:14Z
  • Eugene Blikh added subtask spec-by6.3.4 · 2026-07-24T21:57:17Z
  • Eugene Blikh closed the issue · 2026-07-24T22:59:29Z
    All four children done: core+db anchors (1a25367), service API + auto-merge gate (c6e5d66), mcpsrv spec_comment (f82d90a), web commentable diff (472bcb1).
  • Eugene Blikh added subtask spec-by6.3.5 · 2026-07-25T14:40:01Z
Stored rows — what this pane was built from, as read
issues 1 row
id spec-by6.3
content_hash 930b48e40e540558361755cb2ef2835d8eaaed9478dd461ca9e239ede1b8639d
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.
notes
status closed
priority 2
issue_type feature
assignee NULL
estimated_minutes NULL
created_at 2026-07-24T18:56:37Z
created_by Eugene Blikh
owner bigbes@gmail.com
updated_at 2026-07-24T19:59:29Z
closed_at 2026-07-24T19:59:29Z
closed_by_session
external_ref NULL
spec_id
compaction_level 0
compacted_at NULL
compacted_at_commit NULL
original_size NULL
sender
ephemeral 0
wisp_type
pinned 0
is_template 0
mol_type
work_type
source_system
metadata �{}
source_repo
close_reason All four children done: core+db anchors (1a25367), service API + auto-merge gate (c6e5d66), mcpsrv spec_comment (f82d90a), web commentable diff (472bcb1).
event_kind
actor
target
payload
await_type
await_id
timeout_ns 0
waiters
hook_bead
role_bead
agent_state
last_activity NULL
role_type
rig
due_at NULL
defer_until NULL
no_history 0
started_at NULL
is_blocked 0
dependencies 6 rows
id 1abd28f3-dc9a-5482-bbed-35750bdf8816
issue_id spec-by6.3
type parent-child
created_at 2026-07-24T21:56:36Z
created_by Eugene Blikh
metadata �{}
thread_id
depends_on_issue_id spec-by6
depends_on_wisp_id NULL
depends_on_external NULL
id 5207f602-ab28-5e4c-82ba-c85ccb3b64c6
issue_id spec-by6.3.2
type parent-child
created_at 2026-07-24T21:57:05Z
created_by Eugene Blikh
metadata �{}
thread_id
depends_on_issue_id spec-by6.3
depends_on_wisp_id NULL
depends_on_external NULL
id 7e0d0f19-7eb9-5aae-ad63-b01c54c304ca
issue_id spec-by6.3.4
type parent-child
created_at 2026-07-24T21:57:17Z
created_by Eugene Blikh
metadata �{}
thread_id
depends_on_issue_id spec-by6.3
depends_on_wisp_id NULL
depends_on_external NULL
id b075b1a9-51df-59f2-aea1-14415b52401d
issue_id spec-by6.3.3
type parent-child
created_at 2026-07-24T21:57:14Z
created_by Eugene Blikh
metadata �{}
thread_id
depends_on_issue_id spec-by6.3
depends_on_wisp_id NULL
depends_on_external NULL
id c760df6c-6c39-5284-b58a-ef91dbe63f01
issue_id spec-by6.3.1
type parent-child
created_at 2026-07-24T21:57:01Z
created_by Eugene Blikh
metadata �{}
thread_id
depends_on_issue_id spec-by6.3
depends_on_wisp_id NULL
depends_on_external NULL
id ce808c5f-ccd6-50c3-ba24-422984df8fa6
issue_id spec-by6.3.5
type parent-child
created_at 2026-07-25T14:40:01Z
created_by Eugene Blikh
metadata �{}
thread_id
depends_on_issue_id spec-by6.3
depends_on_wisp_id NULL
depends_on_external NULL
events 2 rows
id 019f957c-90e6-7655-b056-68c310182019
issue_id spec-by6.3
event_type created
actor Eugene Blikh
old_value
new_value
comment NULL
created_at 2026-07-24T21:56:36Z
id 019f95b6-2115-7259-b377-e6371d2941f0
issue_id spec-by6.3
event_type closed
actor Eugene Blikh
old_value
new_value All four children done: core+db anchors (1a25367), service API + auto-merge gate (c6e5d66), mcpsrv spec_comment (f82d90a), web commentable diff (472bcb1).
comment NULL
created_at 2026-07-24T22:59:29Z