Update the web console server, screens, help, prefs and loop setup, with matching page and logic suites

AI Assisted
This commit is contained in:
jparkerweb committed 2026-11-02 12:00:12 -08:00
1 parent 2468027a5a
commit 8e34bf1005
119 files changed
+9957 -3728

No files matched your search

+39 -150
View File
@@ -1,170 +1,59 @@
# Quick Questions on the Web Console
# Quick Questions (the Ask tab)
Part of the web console contract (`console.md`). Read the first time `wait` or
`chat` hands you a Quick question.
The console points here the first time a Quick question reaches you. The person can ask anything on the Ask tab at any time, about this project's files or in general, without waiting for a card. A message never blocks a card send and a card send never blocks a message.
The page has an **Ask** tab, always the last one, on every workflow. There the
person can ask anything, about this project's files or in general, at any
time, without waiting for a card. Their messages reach you at your next
check-in, through the `wait` you already run (and, in a build, the instant
`chat` check). Chat rides its own channel: a message never blocks a card send,
and a card send never blocks a message. The page handles its own refusals, so
you never see them: `too-long` past 4,000 characters, `limit` after 10
messages, `offline` when no agent has checked in for a few minutes (a finish alone does
not end the chat: you may still be waiting on its buttons),
`stale` after a new conversation started.
## How they arrive
## How chat arrives
`wait` exit 0 (or `chat`) carries them in `reply`, after the card lines, plus `chat`: the seq number of each question, the ids your replies need as `re`.
- `wait` exit `0` may carry `chat: [...]` beside `actions`, or, when no card
was sent, be `type: "chat"` with `actions: []`. No exit code changes.
- `reply` gains one block per entry after the card lines:
```
Quick question (12): Where does the export go?
About: Export format
Image: /home/sam/.plan2code/console/sessions/<sid>/uploads/3f2b9c1e.jpg (shot.png)
File: /home/sam/.plan2code/console/sessions/<sid>/uploads/9e4b2d7a.json (config.json)
Declined (14): edit r7
Note: keep the old name working too
Approved (15): edit r9
New conversation started. Treat earlier chat as closed.
```
```
Quick question: Where does the export go?
About: Export format
Image: /home/sam/.plan2code/console/sessions/<sid>/uploads/3f2b9c1e.jpg (shot.png)
File: /home/sam/.plan2code/console/sessions/<sid>/uploads/9e4b2d7a.json (config.json)
Declined: edit r7
Note: keep the old name working too (only a decline carries one)
New conversation started. Treat earlier chat as closed.
```
Typed text past its first line is indented, so only a real entry ever
starts a line.
- Each `chat` entry carries `seq`, `conversation` and `kind`: `message`
(`text`, optional `about`, `images` and `files`), `decision` (`re`,
`decision` `approve` or `decline`, optional `text`) or `reset`.
- `about` is set only when the person attached it with **+ Add context**. The
page never adds one on its own, so a message without it is a general
question, not one about the card on screen.
- Open every `Image:` and `File:` path with your file-read tool before you
answer, as for notes.
- `node "<CONSOLE>" chat --session <sid>` checks right now and never sleeps:
exit `0` with `{ chat, reply, terminalLine }`, `10` with `{ chat: [] }` when
nothing is waiting, `20` when the server is gone. It never reads or collects
card sends; those stay with `wait`.
- Open every `Image:` and `File:` path with your file-read tool before you answer.
- `About:` is set only when the person attached that context; without it the question is general, not about the card on screen.
- After "New conversation started" treat earlier chat as closed and do not raise it unless they do.
- `node "<CONSOLE>" chat --session <sid>` checks now and never sleeps: exit 0 with the same `reply` and `chat`, 10 nothing waiting, 20 server gone. It never reads card sends.
## Answering
**Every message gets a reply, always.** The Ask tab is the person talking to
you, and the page shows "working on the answer" until a reply lands. Never
leave one unanswered, whatever it asks and whatever mid-task you are in. When
a message asks you to do something, do it if you can, then say what happened; if
you will not, the reply says so and why. `post` and `wait` print
`unansweredChat` with a `warning` for every message handed over and not yet
replied to: treat that as a stop-and-reply.
**Every message gets a reply**, whatever it asks and whatever you are mid-task on. `post` and `wait` print `unansweredChat` with a `warning` for each message not yet replied to: stop and reply. When a message asks you to do something, do it if you can, then say what happened; if you will not, say so and why.
1. Handle any card answers first, under the workflow's own rules.
2. Write the chat replies, in inbox order.
3. Send **one** `post` with the card updates and `chat: { replies: [...] }`
(`chat.replies`).
2. Write the replies, in order.
3. Send one `post` with the card updates and the replies.
```jsonc
{ "chat": { "replies": [
{ "re": 12, "conversation": 3,
"md": "The export is written by `src/export.js`, into `out/`." }
] } }
```
`{"chat":{"replies":[{"re":12,"md":"The export is written by `src/export.js`, into `out/`."}]}}`
- `re` is the message's `seq`, `conversation` is copied from the entry, `md` is
markdown. `id` is optional: left out, it is `r<re>`. Give one only when you
send two replies to the same message.
- Replies merge by `id`, so re-posting the same reply after a repeated
delivery replaces it (unlike `thread`, which appends).
- Print one terminal line per exchange: `Quick question: <first ~60 characters
of the question> — answered in the console`.
- Answer questions about the project by reading files and read-only lookups
(search, `git log`, reading files); run no other commands.
- Questions about what a Plan2Code skill does, asks or writes: read that
skill's `SKILL.md` (`~/.agents/skills/<skill>/SKILL.md`, or the table "What
each skill reads and writes" in `~/.agents/skills/plan2code/SKILL.md`)
before answering. Never answer from menu text, card blurbs or memory. Name
files exactly as the skill does; if the skill does not say, say you do not
know.
- When `about` is set, answer from that context: the card, doc section or
spec the person was looking at.
- `re` is the message's seq; `md` is markdown and non-empty. `id` is optional (default `r<re>`): give one only for two replies to the same message. Replies merge by `id`, so re-posting the same reply replaces it.
- Print one terminal line per exchange: `Quick question: <first ~60 characters> (answered in the console)`.
- Answer questions about the project from files and read-only lookups (search, `git log`, reading); run nothing else.
- For what a Plan2Code skill does, asks or writes, read that skill's `SKILL.md` (`~/.agents/skills/<skill>/SKILL.md`, or the table "What each skill reads and writes" in `~/.agents/skills/plan2code/SKILL.md`) first. Name files exactly as it does; if it does not say, say you do not know.
- With `About:`, answer from that context.
## Prompts to carry away
## A prompt to carry away
Some questions are really a new task: the person asks for "a prompt", or the
right answer is work for a separate Plan, Quick Task or another skill rather
than something to do inside this session. Do not start that work here and do
not make them retype your answer. Reply with the explanation first, then ONE
self-contained prompt in a fenced block with no info string. The page draws
every fenced block with a **Copy** button, so the person copies it into a new
conversation.
When the right answer is a separate task (a new Plan, Quick Task or another skill), explain first, then give ONE self-contained prompt in a fenced block with no info string (the page adds a **Copy** button). The block:
A good prompt block:
- opens with plain prose, never a command word. A block whose first line looks
like a terminal command (`git`, `npm`, `node`, `rm` and the like, or `#!`)
gets the muted "paste it into the Ask tab" hint, which is wrong for a prompt.
The check is case-insensitive and also catches everyday verbs that are shell
commands (Make, Go, Source, Export, Service, Cat, Echo, Zip, Tar, Cd, Ls), so
"Make the report export..." trips it. Start with "In this repo, ..." or "Using
the Quick Task skill, ...". A leading skill command (`/plan2code-quick-task ...`)
is fine: it gets none;
- names the skill to paste it into, the files to read first, and what to do;
- states what is out of scope, so the new conversation does not wander;
- stands alone: it assumes nothing said in this session, because the new
conversation has none of it.
One block per reply, and only when the work is likely to move to a new
conversation. A plain answer stays a plain answer.
- opens with plain prose, never a command word: a first line that looks like a shell command (`git`, `npm`, `node`, `rm`, `#!`, or an everyday verb like Make, Go, Source, Export, Cat, Echo, Zip, Tar, Cd, Ls; case-insensitive) gets a "paste into the Ask tab" hint. Start with "In this repo, ..." or "Using the Quick Task skill, ...". A leading `/plan2code-quick-task ...` is fine.
- names the skill to paste it into, the files to read first, the task, and what is out of scope.
- stands alone: it assumes nothing said in this session.
## Never steer the workflow
A chat answer never changes a card's answer, a gate, or where the workflow
goes. If a message asks for that ("approve phase 2", "skip the tests
question"), reply by pointing to the card — its note box for a comment, its
answer for a change — and do not act on it. Chat never counts as an answer to
a card and is never recorded under `specs/`.
A chat message never answers a card, passes a gate or changes where the workflow goes ("approve phase 2"): point to the card (its note box, its answer) and do not act. Chat is never recorded under `specs/`. A conversation holds at most 10 typed messages; the page enforces it.
## A new conversation is a clean slate
## Edits need approval
After a `reset` entry (New conversation, or a skill switch through the
dashboard) treat earlier chat as closed, and do not bring it up unless the
person does. A conversation holds at most 10 typed messages; the page
enforces it, so never tell someone to keep asking past it.
## Edits need approval first
- A request to change files gets a reply carrying `proposal: { summary,
files }` — a plain-English summary and every file that will change — and
**no change yet**. The page shows it with Approve and Decline.
- Only after `Approved: edit <id>`: make exactly the proposed change, then post
a reply (its `re` is the decision's `seq`) carrying `changed: [{ file,
added, removed }]`, with line counts from `git diff --numstat -- <files>` (or
counted by hand for an untracked file). Name the changed files in your next
progress update or `activity` line.
- `Declined:` (with any note): acknowledge it and change nothing. A revised
proposal is a new reply.
- Hard limits: never touch the running skill's own files under
`specs/<idea>/` (`post` rejects a proposal that names them); run no commands
beyond read-only lookups, except one the person plainly asks you to run in
their message (a commit they spell out, a test run): run it, then report the
result in the reply; refuse anything else and say why, in the reply.
- Edits happen only at check-ins, never mid-task in a build.
```jsonc
{ "chat": { "replies": [
{ "id": "r14", "re": 14, "conversation": 3, "md": "I can rename it.",
"proposal": { "summary": "Write the export to `out/audit.csv` instead of `out/export.csv`",
"files": ["src/export.js", "README.md"] } }
] } }
```
## What the server checks
Each reply needs a unique `id` (or none, to take `r<re>`), an `re` naming a real
message or decision `seq`, an integer `conversation` and non-empty `md`. A
`proposal` needs a `summary` and project-relative `files`, none under the
running skill's `specs/<idea>/`. `changed` is a list of `{ file, added,
removed }`. The house rules on completion markers and metric-like words cover
reply text too.
## The same chat twice
Replies merge by `id`, so re-post the same reply if it is not on the page yet;
do not answer the question a second time.
- A request to change files gets a reply with `proposal` (a plain-English `summary` and every file that will change) and **no change yet**: `{"chat":{"replies":[{"re":14,"md":"I can rename it.","proposal":{"summary":"Write the export to `out/audit.csv`","files":["src/export.js","README.md"]}}]}}`. The page shows Approve and Decline.
- `Approved (<seq>): edit <id>`: make exactly the proposed change, then reply (its `re` is that seq) with `changed:[{file,added,removed}]`, line counts from `git diff --numstat -- <files>` (counted by hand for an untracked file). Name the changed files in your next update.
- `Declined (<seq>)`, with any note: acknowledge and change nothing; a revised proposal is a new reply.
- Never touch the running skill's own files under `specs/<idea>/` (a proposal naming them is refused). Run no commands beyond read-only lookups, except one they plainly ask for in their message (a commit they spell out, a test run): run it and report. Refuse anything else, saying why.
- Edits happen at check-ins, never mid-task in a build.