311 — tp overview: answer a called story from its card (#311)
Why
A story whose agent has called shows on tp overview as a card flagged
"blocked", and that is all the page does for it. To answer, the human
finds the reason in the issue's comments on the forge, reads the story
in another tab, goes to the story's worktree in a terminal for
tp story answer, and then starts an agent there to carry on. The
board is where the human learns they are needed; it should also be
where they answer, and the answer should set the work going again.
What changes
tp overview, a blocked card: a link, "answer", to a page of that story.tp overview, the answer page: the story, why it was called, a comment box, a button "answer" and a link "back" to the board. It also says that "answer" starts an agent in the story's worktree, and that a session left open there should be closed first.- "answer": does what
tp story answer TEXTdoes, against the forge (the commentAnswered: TEXT, thencalledtaken off), then starts an agent on this machine in the story's worktree, as "interview" starts one in the checkout, and sends the browser to its session. docs/overview.md: "Blocked" describes the page, the press and the note on open sessions;diris needed to resume as well as to interview; "answer" joins "accept" and "to idea" as what writes to a forge.docs/story.md: "Calling for a human" names the page as the other way to answer.
Acceptance
R is the repository, N the issue, story/<N>-<slug> the story's branch
on the forge, and the worktree <dir>/R-<N>-<slug>, where
tp idea story makes it.
The card
| Card | Has |
|---|---|
| flagged "blocked", in any column | a link, "answer", to the answer page of that story; pressing it writes nothing |
| not blocked | no such link |
The page
| Part | The forge has | Shown |
|---|---|---|
| the story | the branch, and the story file on it | the file rendered in full, and a link to it on the forge |
| the story | no branch, or no story file on it | that the story was not found, and a link to the issue; the call can still be answered |
| why it was called | Called: comments, none Answered: |
every Called: comment, oldest first, each with its date |
| why it was called | Called: comments after the last Answered: one |
those only; the issue is linked for the earlier ones |
| why it was called | no Called: comment after the last Answered: |
that no reason was found, and a link to the issue |
| the comment box | — | empty |
| the note | — | "answer" starts an agent in the worktree; close a session left open there first |
| "back" | — | the board; nothing written |
| Issue N when the page is asked for | The page |
|---|---|
open, story, called |
as above |
| anything else, or not an issue of a level 3 repository of a forge of the user config | says why there is nothing to answer, with a link back |
The press
The issue is read again at the press. The forge is written in the
order tp story answer writes: the comment, then the label. The agent
is claude --remote-control in the worktree, its session named
R #N, its first message: #N was called and is answered; read the
answer on the issue, run tp story query, do what it says. The message
is the same whether or not the story is defined.
| The box | Issue, read again | The forge | The agent | The browser |
|---|---|---|---|---|
| text | open, story, called |
Answered: TEXT commented; called off |
started; prints its session's address within a minute | sent to the session |
| text | open, story, called, not defined (a call -undefined) |
the same | the same, the same first message | the same |
| text | open, story, called |
the same | one started by an "answer" for this story from this tp overview is still running: no second |
a page saying the answer is recorded and that the running agent has not been told, with a link to its session |
| text | open, story, called |
the same | not started: the forge's dir not set |
a page: the answer is recorded; names the user config and the forge; a link back |
| text | open, story, called |
the same | not started: no branch on the forge, so no worktree known | a page: the answer is recorded; says why; a link back |
| text | open, story, called |
the same | not started: the worktree absent, or not a directory | a page: the answer is recorded; names the path; a link back |
| text | open, story, called |
the same | not started: claude not on the PATH |
a page: the answer is recorded; says so; a link back |
| text | open, story, called |
the same | ends, or prints no address within a minute and is stopped | a page: the answer is recorded; the last line it printed; the worktree's path; a link back |
| empty, or blanks only | any | nothing written | none | the answer page again, saying an answer is needed |
| text | open, story, not called |
nothing written | none | a page: it is answered already; a link back |
| text | closed, or not story |
nothing written | none | a page saying why; a link back |
| text | open, story, called, the forge refusing the comment |
nothing written | none | the answer page again, the forge's words above the box, the text still in it |
| text | open, story, called, the comment written, the forge refusing the label |
the comment only | none | a page: the comment is on the issue and called still on, in the forge's words; names tp story answer with no text, in the worktree; a link back |
After a press that takes called off, the card on the board is no
longer blocked.
The guard
| Request | Outcome |
|---|---|
the press without the secret tp overview made when it started |
refused; nothing written, no agent |
| the page or the press under a name other than this machine's own | refused |
| the press for a repository below level 3, or of a forge not in the user config | refused; nothing written, no agent |
An agent started by "answer" lasts while tp overview runs and ends
with it, as an interview does. Linux and macOS.
Out of scope
- Detecting an agent in the worktree that this
tp overviewdid not start: one left open in a terminal, or started by anothertp overview. The agent that called has stopped by the flow's contract; the page's note asks the human to close a session left open. A second agent is started beside it. - Telling a running agent of the answer.
tp overviewcannot send a message into a session; the human tells it. - Answering with no text.
tp story answerwith no text, in the worktree, still takescalledoff without a comment. - Finishing a press the forge stopped between the comment and the
label.
tp story answerdoes it. - Accepting a story from the answer page. One called
-undefinedis rewritten by the agent, offered, and accepted from its card as any other. - Earlier calls and answers, review verdicts and the rest of the issue's thread on the page: the issue is linked.
- Any change to
tp story callortp story answer, and the renaming ofcalledto "blocked" (#281).
Decisions
None. The interview's choices are in the tables: the answer is recorded
before the agent is started and stays recorded when the start fails;
one first message serves a defined story and one not defined, because
tp story query already gives the next step.
Done when
- tests express the acceptance table and pass
- spec updated
- changelog entry
- issue closed with a link to the release