Archive the-agent-asks-the-operator

openspec/specs/acp-agent-adapters/spec.md

@@ -216,3 +216,18 @@ run it names, and never to the default runner in its place.
   agent
 - **THEN** that agent's runner receives the answer and the run goes on,
   and the default runner receives nothing
+
+### Requirement: The product's own agent asks in its turn
+
+`local-llm-acp` SHALL offer a tool `ask_operator` taking one argument,
+`question`. Calling it SHALL emit a `question` event and write the question
+to `decisions.md` as any question is, and SHALL block the agent's loop
+until the question is answered; the answer SHALL be the tool's result, and
+the turn SHALL go on. `local-llm` SHALL NOT offer it.
+
+#### Scenario: Asking mid-turn
+
+- **WHEN** `local-llm-acp` calls `ask_operator` with "Keep the target
+  filter?" and the operator answers "Yes"
+- **THEN** the loop waits until the answer, the tool's result is "Yes", and
+  the agent continues its turn

openspec/specs/agentic-harness/spec.md

@@ -3754,3 +3754,16 @@ failed update SHALL end the chain before `apply`.
   fails
 - **THEN** the chain ends with the update's failure and `apply` does not
   start
+
+### Requirement: A chain waits on its stage's question
+
+A chain SHALL NOT start its next stage while a stage's question is open,
+under every autonomy level, and SHALL go on once the stage has run again
+with the answers. Under `act`, the supervisor SHALL NOT repeat or move a
+stage that waits on a question.
+
+#### Scenario: Autonomous, with a question
+
+- **WHEN** an autonomous chain's propose stage asks a question
+- **THEN** the chain does not start review until the question is answered
+  and propose has run again as an update with the answer

openspec/specs/ci-cli/spec.md

@@ -1082,3 +1082,18 @@ not a terminal, it SHALL be denied, and the denial printed.
   terminal to answer
 - **THEN** the request is denied, the denial is printed, and the run goes on
   instead of waiting for an answer
+
+### Requirement: The CLI answers a question
+
+`openspec-ui-cli answer <change> <question-id> <text> [--cwd <path>]` SHALL
+answer the question, writing `decisions.md` and the audit log and reaching
+a run that waits on it. `openspec-ui-cli answer <change>` SHALL list the
+change's open questions with their ids. `openspec-ui-cli status` SHALL list
+each waiting run's open questions with their ids and the command that
+answers each.
+
+#### Scenario: From a terminal
+
+- **WHEN** `openspec-ui-cli answer demo Q-r1-1 "Active contacts only"` runs
+- **THEN** `decisions.md` of `demo` holds that answer, and a run waiting on
+  `Q-r1-1` goes on

openspec/specs/execution-core/spec.md

@@ -3381,3 +3381,48 @@ that nothing was archived, and why.
   `! [rejected] ... (fetch first)`
 - **THEN** the sweep says the `! [rejected]` line, and sweeps again within
   minutes; the same failure again is left to the usual interval
+
+### Requirement: An agent's question stops its run until answered
+
+Every agent stage's instruction SHALL ask the agent to print, for each
+decision it needs from the operator that the change's files do not make, a
+line of its own `Question for the operator: <question>`, and not to make
+that decision itself. The product SHALL read such lines as markers, and
+SHALL NOT read prose for questions. Each question SHALL be emitted as a
+`question` event and written to the change's `decisions.md` with its stage,
+run and time and an open answer, and recorded in the audit log.
+
+A run whose turn ended with an open question SHALL NOT complete: it SHALL
+wait, saying so and writing `waiting` with kind `question` to its status
+record, under every autonomy level and whether or not it is a chain's
+stage. An `answerQuestion` command SHALL answer one question, writing the
+answer, who gave it and when to `decisions.md` and the audit log. When every
+question of the run is answered, the stage SHALL run again within the same
+run, with the questions and answers in its prompt - as `update` for a `plan`
+or `review` stage, as the same command otherwise - and the run SHALL end as
+that does.
+
+#### Scenario: A review with two questions
+
+- **WHEN** a review run prints two `Question for the operator:` lines and
+  ends its turn
+- **THEN** two `question` events are emitted, `decisions.md` holds both as
+  open, and the run waits instead of completing
+
+#### Scenario: Answered
+
+- **WHEN** both questions are answered
+- **THEN** `decisions.md` and the audit log hold the answers, and the run
+  goes on as an `update` whose prompt holds both questions and answers
+
+### Requirement: Nothing runs past an open question
+
+An agent command on a change whose `decisions.md` holds an open question
+that is not the run's own SHALL be refused, naming the question and how to
+answer it. A read-only command SHALL NOT be refused.
+
+#### Scenario: Apply with a question open
+
+- **WHEN** `implement` is started on a change with an open question in its
+  `decisions.md`
+- **THEN** it is refused, naming the question

openspec/specs/shared-ui/spec.md

@@ -2388,3 +2388,19 @@ as a `cwd`, and nothing else outside the workspace.
   an `origin`
 - **THEN** the page's workspace root becomes the change's directory and the
   change is open in the editor
+
+### Requirement: Open questions are answered where they are shown
+
+A change's card SHALL offer to answer each open question from its
+`decisions.md`, with a field for each answer and **Answer**, whether or not
+the run that asked is alive. The AI panel SHALL do the same for the run it
+shows. The Human-Only Inbox SHALL list open questions, from the checkout's
+changes and from each change's own worktree, beside Human-only items and
+answer them. An answer given in a host where the waiting run is not SHALL
+reach that run.
+
+#### Scenario: Answering from the card
+
+- **WHEN** a change's review waits on a question and the operator types an
+  answer on its card and presses **Answer**
+- **THEN** the answer is in `decisions.md`, and the waiting run goes on