Questions and decisions · Repository-aware brainstorm suggestions

Round 1

Q1. Which readiness policy should the second pass use: (A) non-blocking—publish the questions immediately and let each suggestion appear later or show an explicit unavailable state; (B) wait for suggestions up to a bounded timeout, then degrade; or (C) do not expose the round until every question has a suggestion? In all cases, may the operator answer and submit while suggestions are unavailable?

A1.

Choose A: publish questions immediately and generate suggestions asynchronously. Operators may answer and submit while suggestions are loading or unavailable.

Q2. When repository, wiki, task, and settled-answer context does not support one defensible answer—or the sources conflict—should Hive show a non-actionable “no safe suggestion” reason, or a clearly labelled low-confidence best effort? What minimum rationale or source labels should accompany a normal suggestion?

A2.

Show “no safe suggestion” when evidence is weak or conflicting. Normal suggestions need a short rationale and source-class labels, without hidden reasoning.

Q3. What exactly counts as an “already-settled brainstorm answer” for later suggestions: only answers from completed earlier rounds, every operator-written answer already persisted in `brainstorm.md`, or also unsent Web/TUI draft text? Should a suggestion or an agent-authored default ever qualify as settled context before final answer submission?

A3.

Only operator-written answers durably persisted in brainstorm.md are settled, including earlier answers in the current round. Drafts and suggestions are not.

Q4. What repository and wiki material is eligible for context and freshness binding? In particular, should repository context include tracked uncommitted changes or only committed `HEAD`; should ignored/untracked files always be excluded; and should wiki context include only the project’s managed `wiki/` or also a configured main wiki?

A4.

Bind to committed HEAD plus tracked working-tree changes; exclude ignored/untracked files. Include project wiki and configured main wiki with bounded provenance and secret controls.

Q5. When any binding input changes—task generation, question text/identity, relevant repository state, relevant wiki state, or settled answers—should Hive hide the old suggestion and regenerate automatically, show a disabled stale card with a manual Retry control, or follow another policy? If regeneration fails, what should remain visible and actionable?

A5.

Hide stale suggestion text from approval and regenerate automatically. Show stale/Retry state; if regeneration fails, keep manual answering fully usable.

Q6. For the TUI/editor contract, should each suggestion be one recognizable HTML-comment block immediately after its `### A<n>.` heading, accepted by removing only the comment delimiters and declined by deleting the block? Confirm whether untouched comments must remain invisible to answer parsing and completion, survive ordinary saves/reruns while still fresh, and never trigger auto-resume.

A6.

Yes. Use one recognizable HTML-comment envelope after the answer heading; untouched comments remain invisible to parsing/completion, survive while fresh, and never auto-resume.

Q7. For Web, how durable should Approve/Decline UI state be? For example: Approve copies text into the textarea and preserves that editable draft across Turbo refreshes without changing server state; Decline stays dismissed across refresh/reload for the exact suggestion binding but resets when a new suggestion is generated. Should either action be reversible before “Send answers”?

A7.

Approve creates a reversible editable client draft; Decline persists only for the exact binding and is reversible before Send. Neither changes server answer state until submission.

Q8. Are TUI and Web the only operator surfaces in scope, leaving Telegram and the existing `hive answer` Guided/YOLO flows unchanged? Should read-only CLI/status JSON nevertheless expose suggestion text/state/binding so Web and future clients share one contract, or should suggestions remain internal to these two presentations?

A8.

Keep writes scoped to TUI and Web; leave Telegram and Guided/YOLO unchanged. Expose bounded read-only suggestion state/text/provenance/binding through one machine contract.

Q9. What hard presentation bounds should apply per suggestion (for example, maximum characters/lines and whether code blocks are allowed), and what redaction behavior should operators see when candidate text contains secret-like material, prompt material, unsafe markup, or oversized content?

A9.

Limit to 1,000 UTF-8 characters and 12 lines, no fenced code blocks. Escape markup and suppress/redact secret-like, prompt-control, or unsafe content with a visible safe reason.

Requirements

Actor: A human Hive operator answers brainstorm questions in the TUI or Web. Suggestions are advisory context only; read-only clients may inspect them, but no suggestion or UI action has answer or workflow authority.
Flow: Publish the normal brainstorm questions immediately, then run a distinct asynchronous second pass that attempts one suggestion per question. The operator may edit and explicitly submit answers while suggestions are loading, unavailable, stale, declined, or failed.
Eligible context: Build each attempt from the exact task request, committed repository HEAD plus tracked working-tree changes, the managed project wiki plus configured main wiki, and operator-written answers already durably persisted in brainstorm.md, including earlier answers in the current round. Exclude ignored/untracked files, unsent drafts, prior suggestions, and agent-authored defaults from settled-answer context.
Suggestion contract: A defensible suggestion contains at most 1,000 UTF-8 characters and 12 lines, has no fenced code block, and includes a short rationale plus bounded source-class labels without hidden reasoning or prompt material. Escape markup and suppress or redact secret-like, prompt-control, unsafe, or oversized content with a visible safe reason. Weak or conflicting evidence produces a non-actionable no safe suggestion state rather than a low-confidence guess.
Freshness: Bind each suggestion to the exact task and task generation, brainstorm generation, question identity and text, relevant repository/wiki state, and settled-answer inputs. When any binding input changes, immediately hide the old text from approval, expose a stale/Retry state, and regenerate automatically. A failed regeneration must leave manual answering and submission fully usable.
TUI: Put a fresh suggestion in one recognizable HTML-comment envelope immediately after its ### A<n>. heading. Removing only the comment delimiters adopts it as editable answer text; deleting the block declines it. Untouched suggestion comments survive ordinary saves/reruns while fresh but are invisible to answer parsing, completion, and auto-resume.
Web: Show each suggestion beside its question with Approve and Decline. Approve copies the text into a reversible, editable client draft that survives Turbo refreshes; Decline dismisses only that exact binding and is reversible before Send answers. A newly bound suggestion resets the dismissed state. Neither action mutates server answer state.
Surface boundary: Suggestion writes are limited to TUI and Web; Telegram and existing Guided/YOLO hive answer behavior remain unchanged. Expose bounded suggestion state, text, provenance labels, and binding through one read-only machine contract for Web and future clients.
Acceptance example — advisory isolation: Given a generated suggestion, generation, display, Approve, Decline, refresh, retry, or comment persistence alone cannot create a parsed answer, write the final brainstorm artifact, mark the round complete, auto-resume, submit answers, or advance the workflow. Only the operator's explicit final answer submission may do so.
Acceptance example — stale/degraded behavior: Given a changed binding input or a failed/unavailable generator, stale text cannot be approved; the UI clearly reports loading, stale, Retry, unavailable, failed, or no safe suggestion as applicable, while the operator can still type and submit an answer.
Acceptance example — context safety: Given ignored/untracked content, secret-like text, unsafe markup, prompt-control material, conflicting sources, or output beyond the hard bounds, none is emitted as actionable suggestion text, and the operator sees a bounded safe explanation.
Acceptance example — presentation parity: Given the same fresh binding, TUI adoption and Web approval both yield editable draft answer text without server-side answer authority, and the shared read-only contract reports the same suggestion state and provenance.
Documentation: Update the managed wiki for the suggestion lifecycle, context/freshness rules, operator surfaces, degraded states, and authority boundary, and add the required wiki log fragment.