dreampiler/kandev
1
0
Fork 0
Code Issues 43 Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
eeeb6f5586b4bd89b6c00a647b3b4a0975fc0d3a
kandev/docs/specs/tasks/requirements/plan-comments.md
T

13 KiB
Raw Blame History

status, system, created, updated, owners
status system created updated owners
active tasks 2026-09-02 2026-09-13
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

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.

Reference in New Issue View Git Blame Copy Permalink