Merge branch 'main' into verify-gaps

This commit is contained in:
2026-10-18 02:46:48 +01:00
24 changed files with 1202 additions and 409 deletions
+56
View File
@@ -0,0 +1,56 @@
# Work documentation now describes the agent-driven model
## What this item changed
The workflow documentation was rewritten to describe how the system actually works:
the agent (the session) is the brain and advances the queue by hand through the
`pipelines` CLI. There is **no orchestration script, no driver, no polling loop and no
lane machinery, and none may be written.**
- `internal/author/skill/references/work.md` — rewritten end to end. The queue-driver
script (`drivers/workd.sh`), the claim-file ledger with atomic renames, the `PAUSED`
marker and the poll loop are gone. The ledger is now the per-project markdown
`queue.md` (authoritative for intent) plus `notes.md`; run state is read from the
server (`pipelines inspect <run-id> --json`); the agent launches each run itself with
`pipelines run <pipeline> <brief> --json --yes` from the item's worktree and is woken
by a background `pipelines wait`.
- `internal/author/skill/references/queue.md` — the landing gate now runs the command
directly (`git merge-base --is-ancestor <branch> main`, exit 0 = landed) instead of a
`land-check.sh` helper; the waiting section states the agent advances the queue by
hand and there is no driver.
- `internal/author/skill/references/orchestration.md` — the intro and "Running and
watching" state the agent-driven, event-driven model; "Pipeline choice" now names the
current set (`Android`, `TUI`, `Server`, `Generic`, `Plan and land`, `UI sweep`,
`Probe`), chosen by area, and records the retired names.
- `internal/author/skill/references/debugging.md` — "Duplicated work after a driver
restart" became "…after a session restart", resuming from the queue file rather than a
cursor file.
- `internal/author/skill/SKILL.md` — the routing table row no longer says "queue driver".
- `AGENTS.md` — the maintenance workflow section names the current pipeline set instead
of the retired `Pipelines maintenance - plan implement review`.
- `internal/tui/AGENTS.md` — the "do not restart … the lanes …" line no longer names
lanes.
`delivery.md`, `operations.md` and `verification.md` were swept and needed no change:
they contain no driver, poll loop, cursor file or lane guidance. Genuine device tooling
(`android/scripts/capture_png.sh`) is left alone.
## Shared documents this change makes stale
No README or topic doc still teaches the scripted driver model. One topic doc needs a
wording alignment for the event-driven model; the `docs-fold` writer should apply it
when it next folds notes:
- `docs/cli.md` — its "Scripted runs" section frames runs as scripted automation, and
its `--wait` paragraph is the only follow-a-run guidance. It should state that the
agent (not a script) advances work, and that `pipelines wait <run-id> [run-id ...]`
run as a **background task** is the event-driven wait. The `wait` command's own flag
text is already recorded separately in `docs/notes/wait-command.md`.
## Do not change
- The dated evidence documents (`docs/pipeline-performance-review.md`,
`docs/chat-verification.md`, `docs/app-integration-verification.md`) describe the
scripted era as it was and stay as they are.
- `internal/author/install.go`'s managed file inventory needs no change: no packaged
reference file was added or removed.
+79
View File
@@ -0,0 +1,79 @@
# Chat transcript: one agent reply is one bubble
## What this item changed
`internal/` and `android/`, the brokered chat transcript. Three defects measured
against the operator's own OpenCode (127.0.0.1:49374):
- **Server, delta part ids.** `internal/protocol/chat.go` adds
`ChatDeltaPartID(messageID, kind, ordinal)` (mirrored as
`ChatProtocol.deltaPartId` in `android/.../data/protocol/Chat.kt`), and
`internal/opencode/chat.go`'s `NormalizeChatEvent` keys a text or reasoning
delta on it. OpenCode numbers one message's text and reasoning parts
independently from 0, so the old `"%s#%d"` gave a message's first text delta and
its first reasoning part the same id — the client appended the answer into the
thinking block and the server's retained state re-collided on resume.
- **Server, tool fields.** `NormalizeChatEvent` now takes a tool call's arguments
from `session.tool.input.ended`'s `text` as well as `session.tool.called`'s
`input` object (`toolInput`), and `internal/server/chat_hub.go`'s new
`mergeChatToolPart` folds each tool frame onto the retained part so a later
`progress`/`success` frame that omits the name or the input never blanks it.
- **Android, transcript.** `ui/chat/ChatFormat.kt` adds the pure `ChatTurn` /
`TranscriptRow` / `transcriptRows` fold (each run of assistant messages between
two of the operator's messages is one agent turn), the kind-aware
`deltaPartId` net and `mergeToolPart`; `ChatStore` folds deltas and tool frames
through them; `ChatTranscript` renders one bubble per turn — one thinking block
over all the turn's reasoning, then its tool chips, then one answer block of
its text parts — replacing `AssistantParts`/`MessagePart` with
`AgentTurnItem`/`UserMessageItem`.
Tests: `internal/opencode/chat_v2_test.go` and `internal/server/chat_test.go` add
the id-collision and tool name+input retention cases; `ChatReasoningTurnTest`,
`ChatTranscriptTest` and `ChatRunningWorkTest` cover the turn fold, the
text/reasoning collision and the tool lifecycle on the client.
## Shared documents this change makes stale
`android/README.md` describes the surfaces this item changed. The note is written
here rather than edited in place; the `docs-fold` writer should update it.
- `android/README.md:6021` — the **Reasoning collapsed by default** bullet reads
"`ReasoningBlock` is now one compact, muted line per part". It should say one
block per *agent turn*: the transcript folds every consecutive assistant message
between two of the operator's messages into one `ChatTurn`, so all the turn's
reasoning is one collapsible block (labelled with its step count when it
reasoned more than once) and the reply is one bubble, not one per model step.
- `android/README.md:4669` — "`ChatScreen.MessagePart` now calls
`MarkdownText(part.text)` for `PART_TEXT`; the assistant message stays one
`SelectionContainer`". `MessagePart` no longer exists; the answer is
`MarkdownText(turn.answer)` inside `AgentTurnItem`, where `turn.answer` is the
turn's text parts joined in order. The one-`SelectionContainer`-per-bubble fact
is still true.
- `android/README.md:6040` — the test paragraph's "`ChatTranscriptTest`, 7 cases"
is now 9 (the fold tests); `ChatReasoningTurnTest` and `ChatRunningWorkTest`
gained the collision and tool-lifecycle cases.
- `android/README.md:4786` — the **Grouped chips** bullet says "a run of
consecutive `tool` parts in one assistant turn is now one `FlowRow`". The chips
still group in one `FlowRow`, but the calls shown are now the whole folded
turn's (`ChatTurn.tools`), across every step of the reply, not one assistant
message's parts.
Dates, counts and capture names in those dated records are past evidence and stay
as they are; only the behaviour statements above are now stale.
## Not stale
- `docs/cli.md`'s and `internal/author/skill/references/operations.md`'s brokered
chat sections describe the `chat_*` surface and its retained
per-session/per-message state and resync; that remains true. Neither documents
the delta part-id derivation or the tool-field retention, so neither gains a
wrong statement — the derivation now lives in the `internal/protocol/chat.go`
comment. The docs-fold writer may add one sentence to the reference's
retained-state paragraph if it documents part ids there, but nothing there is
now false.
- No packaged OpenCode skill reference documents the app's chat transcript, and no
packaged template or `internal/author/` managed file names it.
- `android/AGENTS.md` and `internal/server/AGENTS.md` list the files this item
touched (`ui/chat/`, `internal/server/chat_*.go`, `internal/protocol/`,
`internal/opencode/chat.go`); no file moved and no build/test step changed, so
both maps stay correct.