main · last commit
18 hours ago ·
8tmadfpi
spec-by6.3 Phase 5b: inline comments on proposals
Past Stand
bd reopen spec-by6.3
| Created by | Eugene Blikh |
| Owner | bigbes@gmail.com |
| Created | 2026-07-24T18:56:37Z |
| Updated | 2026-07-24T19:59:29Z |
| Closed | 2026-07-24T19:59:29Z |
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.
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.
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.
spec-by6
— Phase 5: comments, webhooks, mutations, vector search
parent-child
open
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
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
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
| 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 |
| 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 |
| 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 |
No comments.
Close reason