Files
kandev/docs/specs/tasks/requirements/plan-comments.md
T

246 lines
13 KiB
Markdown

---
status: active
system: tasks
created: 2026-09-02
updated: 2026-09-13
owners:
- kandev
---
# Task Plan Comments Requirements
## Overview
Pending comments on a task plan are feedback the user has prepared but has not
yet delivered to an agent. They belong to the task's current plan, not to the
Agent session that happened to be selected when they were written. Kandev
shows one shared pending set on the plan and at every session composer, then
chooses a destination only when the user sends a message or selects **Run**.
## Terminology
- **Open comment draft:** Text being entered before Add or Update succeeds;
it is not yet part of the persisted pending set.
- **Pending plan comment:** An unsent comment anchored to selected text in the
task's current plan.
- **Selected session:** The Agent session whose composer the user is currently
using.
- **Primary session:** The task session currently designated as primary.
- **Accepted delivery:** A direct user message durably persisted for dispatch,
or a queued prompt durably admitted for a session.
- **Run:** The action beside one plan comment that delivers that comment
without requiring composer text.
## Requirements
### REQ-TASKS-PLAN-COMMENTS-001: Task-owned pending feedback
**Intent:** A pending plan comment remains attached to the plan while the user
navigates between sessions, devices, and browser lifecycles.
**User story:** As a user reviewing a task plan, I want one durable comment set
for the task, so that choosing another Agent session cannot hide or destroy my
unsent feedback.
#### Acceptance criteria
- **AC-TASKS-PLAN-COMMENTS-001.1:** When an authorized user adds a plan
comment, Kandev shall persist it against the task's current plan and show the
same highlight, badge, and comment text in every view of that plan.
- **AC-TASKS-PLAN-COMMENTS-001.2:** Selecting another session, changing the
primary session, creating a session, or deleting a session shall not hide,
move, duplicate, or delete a pending plan comment.
- **AC-TASKS-PLAN-COMMENTS-001.3:** After reload, reconnect, backend restart, or
opening the task from another authorized browser, Kandev shall restore the
current pending comment set from backend state.
- **AC-TASKS-PLAN-COMMENTS-001.4:** A user shall be able to add, edit, and
delete pending comments whenever the task has a current plan, even when the
task has no session that can accept input.
- **AC-TASKS-PLAN-COMMENTS-001.5:** Updating or reverting the current plan shall
retain comments whose selected text can still be anchored. An explicit
comment delete or a destructive plan edit that removes the marked range
shall delete that pending comment for the task.
- **AC-TASKS-PLAN-COMMENTS-001.6:** Deleting the current plan or deleting the
task shall delete its pending plan comments. Deleting and later recreating a
plan shall not attach comments from the deleted plan to the new plan.
- **AC-TASKS-PLAN-COMMENTS-001.7:** Desktop and mobile task surfaces shall
expose the same pending comment set and lifecycle.
- **AC-TASKS-PLAN-COMMENTS-001.8:** Kandev shall limit each comment body to
64 KiB and its selected text to 256 KiB, measured as UTF-8 bytes. A task plan
shall hold at most 100 pending comments and 1 MiB of combined bodies and
selected text. An over-limit mutation shall leave the previous snapshot intact.
- **AC-TASKS-PLAN-COMMENTS-001.9:** While adding or editing a comment on the
same current plan, switching away from the browser and returning shall
preserve the open editor, entered text, and selected plan text. Background
refresh and reconnect shall preserve that draft during pending, successful,
and failed reads on desktop and phone. Plan content editing shall pause during
the read and resume on settlement; the open comment remains editable.
- **AC-TASKS-PLAN-COMMENTS-001.10:** Preserving an open comment draft shall
not automatically persist or deliver it. Add, Update, and Run remain explicit
actions; failed mutations shall preserve the entered text for retry.
- **AC-TASKS-PLAN-COMMENTS-001.11:** Initial plan loading shall not display
another task's plan or draft. A task change, confirmed plan deletion, or
replacement of the current plan shall clear the outgoing transient editor
so its draft cannot be applied to the new context.
### REQ-TASKS-PLAN-COMMENTS-002: Selected-session composer delivery
**Intent:** Pending plan feedback can accompany a message to whichever session
the user deliberately addresses.
**User story:** As a user working with several Agent sessions, I want the plan
comments available at each composer, so that I can send my message and its plan
context to a non-primary session when I choose.
#### Acceptance criteria
- **AC-TASKS-PLAN-COMMENTS-002.1:** Every rendered composer for a task session
shall show a plan-comment context item above its text area when the task has
pending plan comments. The item shall represent the same shared set shown on
the plan.
- **AC-TASKS-PLAN-COMMENTS-002.2:** When the user selects ordinary **Send** from
a session composer, Kandev shall include the visible pending plan-comment
snapshot with the message and address the delivery to that selected session,
even when another session is primary.
- **AC-TASKS-PLAN-COMMENTS-002.3:** A pending plan comment shall not be injected
into an agent's context merely because a session or plan is opened. It shall
become agent context only through an explicit **Send** or **Run** action.
- **AC-TASKS-PLAN-COMMENTS-002.4:** A composer shall allow submission with no
typed text when at least one pending plan comment is included.
- **AC-TASKS-PLAN-COMMENTS-002.5:** After an accepted direct or queued delivery,
Kandev shall consume exactly the included comments and remove them from the
plan and every session composer. Comments created after the submitted
snapshot shall remain pending.
- **AC-TASKS-PLAN-COMMENTS-002.6:** If delivery is rejected, the included
comments and typed composer text shall remain available for retry. If Kandev
cannot establish whether delivery was accepted, it shall reconcile the
attempt by the caller-generated message or queue identifier. An accepted
replay returns the durable delivery without re-sending or re-consuming the
comments; an absent delivery leaves the comments pending.
- **AC-TASKS-PLAN-COMMENTS-002.7:** If two delivery attempts include the same
pending comment, no more than one attempt shall be accepted with that
comment. A competing attempt shall fail without silently sending its typed
text without the requested plan context.
- **AC-TASKS-PLAN-COMMENTS-002.8:** Direct and queued admission shall reject
a final server-rendered prompt larger than 1 MiB before inserting the delivery
or consuming its comments. The comments and composer draft shall remain
available for the user to shorten and retry.
### REQ-TASKS-PLAN-COMMENTS-003: Primary-session Run routing
**Intent:** **Run** is a task-level shortcut with one predictable destination,
independent of the currently selected Agent tab.
#### Acceptance criteria
- **AC-TASKS-PLAN-COMMENTS-003.1:** Selecting **Run** for a plan comment shall
submit that comment, and no other pending plan comment, to the task's current
primary session.
- **AC-TASKS-PLAN-COMMENTS-003.2:** When a non-primary session is selected,
**Run** shall still target the primary session and shall not add the comment
to the selected session's transcript or queue.
- **AC-TASKS-PLAN-COMMENTS-003.3:** When the primary session can accept a
prompt, **Run** shall create a direct plan-mode user message. When the primary
session is busy but accepts queued prompts, **Run** shall create a distinct
queued plan-mode prompt.
- **AC-TASKS-PLAN-COMMENTS-003.4:** Kandev shall validate primary ownership at
delivery acceptance. If the primary changes during the action, Kandev shall
not deliver to the stale target and shall preserve the comment for retry.
Recovery shall not overwrite a newer live primary-session change with an
older session-list response.
- **AC-TASKS-PLAN-COMMENTS-003.5:** When there is no eligible primary session,
**Run** shall be unavailable with an actionable reason. Adding and editing
comments shall remain available.
- **AC-TASKS-PLAN-COMMENTS-003.6:** An accepted **Run** shall consume the run
comment task-wide. A rejected or failed **Run** shall preserve it.
### REQ-TASKS-PLAN-COMMENTS-004: Lossless legacy-draft migration
**Intent:** The session-scoped browser drafts shipped by the earlier repair
must move to task ownership without another comment-loss window.
#### Acceptance criteria
- **AC-TASKS-PLAN-COMMENTS-004.1:** When Kandev identifies session-scoped
pending plan comments belonging to the open task, it shall migrate those
comments to the task's current plan before accepting a composer Send that
would omit them. Discovering or recovering comments shall not itself deliver
a prompt or consume pending feedback.
- **AC-TASKS-PLAN-COMMENTS-004.2:** Migration shall retain each comment's
client-generated identifier. Retrying the same identifier and content shall
be idempotent; distinct identifiers shall remain distinct even when their
selected text and comment text match.
- **AC-TASKS-PLAN-COMMENTS-004.3:** Kandev shall remove a legacy plan-comment
record from browser storage only after backend persistence is acknowledged.
Failed plan comments and every non-plan comment in the same session record
shall remain unchanged.
- **AC-TASKS-PLAN-COMMENTS-004.4:** A recovery failure shall show comment-specific
feedback only when at least one identified legacy comment for the open task
still needs recovery and either automatic retries have been exhausted or
user action is required. The feedback shall offer retry where retry can help.
Background discovery and transient recovery attempts shall not display a
restoration warning. Failed recovery shall preserve both the saved comments
and any attempted composer message.
- **AC-TASKS-PLAN-COMMENTS-004.5:** When no unresolved legacy comments have been
identified for the open task and a composer represents no pending plan
comments, ordinary Send shall remain available despite pending or failed
comment discovery, plan lookup, or comment refresh. This applies to tasks
with a plan, without a plan, and before the presence of a plan is known.
Comments belonging to another task shall not block that Send or produce a
restoration warning on the open task. Ordinary connection and session-input
constraints still apply.
- **AC-TASKS-PLAN-COMMENTS-004.6:** Transient discovery and recovery failures
shall retry automatically with bounded request frequency while the task is
open and connectivity permits progress. Returning to the foreground or
reconnecting shall resume recovery without requiring a reload or Retry
action. Success shall clear obsolete recovery feedback and restrictions;
recovery shall never automatically submit a previously blocked message.
- **AC-TASKS-PLAN-COMMENTS-004.7:** Ordinary Send shall remain blocked while at
least one identified legacy comment for its task would be omitted, including
a mixed set of recovered and unrecovered comments. Run of an already
persisted comment shall depend only on that selected comment and its eligible
primary destination; unrelated unrecovered comments shall remain pending.
A background read failure shall not remove visible persisted comments from
a submitted snapshot or bypass their acceptance checks.
- **AC-TASKS-PLAN-COMMENTS-004.8:** Desktop, phone, structured chat, and
passthrough composers shall apply the same recovery and delivery rules.
Recovery feedback requiring action shall remain inline with the affected
comment context, preserve the composer draft and focus, and expose a
touch-accessible action on phones. Task or plan changes shall not apply a
previous context's failure, cleanup, or retry to the new context.
## Recovery compatibility
Discovery is background work, not an implicit comment selection. Before any
legacy feedback is identified for the task, Send uses the visible persisted
snapshot under `REQ-TASKS-PLAN-COMMENTS-002`. Discovery that finishes later
preserves and exposes the recovered feedback for a subsequent explicit action;
it does not amend or resend an earlier prompt. This narrows the former blanket
migration gate without changing task ownership or backend acceptance semantics.
## Implementation plans
- [Plan comment foreground preservation](../../../plans/plan-comment-foreground-preservation/plan.md)
- [Task-owned plan comments](../../../plans/task-owned-plan-comments/plan.md)
records the original delivery.
- [Plan comment recovery](../../../plans/plan-comment-recovery/plan.md)
implements the recovery and delivery refinements in requirement 004.
## Out of scope
- Restoring an open, unsubmitted comment editor after page reload, task
navigation, or explicit dismissal; synchronizing that transient draft to
another browser or device.
- Changing the task-session ownership of diff, file, pull-request,
walkthrough, or agent-message comments.
- Keeping a separate sent-comment history. Accepted message and queue content
remain the durable delivery record.
- Adding comments to historical plan revisions.
- Broadcasting one comment prompt to every session.
- Automatically exposing pending comments to an agent before the user sends
them.