From b85a1a76ca55098a9fd5ef74cbc92815e41ce647 Mon Sep 17 00:00:00 2001 From: Alexander Ivanov Date: Mon, 5 Oct 2026 08:55:56 +0300 Subject: [PATCH] Archive the-supervisor-advises - the-supervisor-advises Opened by the workspace sweep: each landed with nothing open (ADR 0035). --- .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/agentic-harness/spec.md | 0 .../specs/ci-cli/spec.md | 0 .../specs/execution-core/spec.md | 0 .../specs/shared-ui/spec.md | 0 .../tasks.md | 0 openspec/specs/agentic-harness/spec.md | 88 +++++++++++++++++++ openspec/specs/ci-cli/spec.md | 20 +++++ openspec/specs/execution-core/spec.md | 49 +++++++++++ openspec/specs/shared-ui/spec.md | 35 ++++++++ 12 files changed, 192 insertions(+) rename openspec/changes/{the-supervisor-advises => archive/2026-10-05-the-supervisor-advises}/.openspec.yaml (100%) rename openspec/changes/{the-supervisor-advises => archive/2026-10-05-the-supervisor-advises}/design.md (100%) rename openspec/changes/{the-supervisor-advises => archive/2026-10-05-the-supervisor-advises}/proposal.md (100%) rename openspec/changes/{the-supervisor-advises => archive/2026-10-05-the-supervisor-advises}/specs/agentic-harness/spec.md (100%) rename openspec/changes/{the-supervisor-advises => archive/2026-10-05-the-supervisor-advises}/specs/ci-cli/spec.md (100%) rename openspec/changes/{the-supervisor-advises => archive/2026-10-05-the-supervisor-advises}/specs/execution-core/spec.md (100%) rename openspec/changes/{the-supervisor-advises => archive/2026-10-05-the-supervisor-advises}/specs/shared-ui/spec.md (100%) rename openspec/changes/{the-supervisor-advises => archive/2026-10-05-the-supervisor-advises}/tasks.md (100%) diff --git a/openspec/changes/the-supervisor-advises/.openspec.yaml b/openspec/changes/archive/2026-10-05-the-supervisor-advises/.openspec.yaml similarity index 100% rename from openspec/changes/the-supervisor-advises/.openspec.yaml rename to openspec/changes/archive/2026-10-05-the-supervisor-advises/.openspec.yaml diff --git a/openspec/changes/the-supervisor-advises/design.md b/openspec/changes/archive/2026-10-05-the-supervisor-advises/design.md similarity index 100% rename from openspec/changes/the-supervisor-advises/design.md rename to openspec/changes/archive/2026-10-05-the-supervisor-advises/design.md diff --git a/openspec/changes/the-supervisor-advises/proposal.md b/openspec/changes/archive/2026-10-05-the-supervisor-advises/proposal.md similarity index 100% rename from openspec/changes/the-supervisor-advises/proposal.md rename to openspec/changes/archive/2026-10-05-the-supervisor-advises/proposal.md diff --git a/openspec/changes/the-supervisor-advises/specs/agentic-harness/spec.md b/openspec/changes/archive/2026-10-05-the-supervisor-advises/specs/agentic-harness/spec.md similarity index 100% rename from openspec/changes/the-supervisor-advises/specs/agentic-harness/spec.md rename to openspec/changes/archive/2026-10-05-the-supervisor-advises/specs/agentic-harness/spec.md diff --git a/openspec/changes/the-supervisor-advises/specs/ci-cli/spec.md b/openspec/changes/archive/2026-10-05-the-supervisor-advises/specs/ci-cli/spec.md similarity index 100% rename from openspec/changes/the-supervisor-advises/specs/ci-cli/spec.md rename to openspec/changes/archive/2026-10-05-the-supervisor-advises/specs/ci-cli/spec.md diff --git a/openspec/changes/the-supervisor-advises/specs/execution-core/spec.md b/openspec/changes/archive/2026-10-05-the-supervisor-advises/specs/execution-core/spec.md similarity index 100% rename from openspec/changes/the-supervisor-advises/specs/execution-core/spec.md rename to openspec/changes/archive/2026-10-05-the-supervisor-advises/specs/execution-core/spec.md diff --git a/openspec/changes/the-supervisor-advises/specs/shared-ui/spec.md b/openspec/changes/archive/2026-10-05-the-supervisor-advises/specs/shared-ui/spec.md similarity index 100% rename from openspec/changes/the-supervisor-advises/specs/shared-ui/spec.md rename to openspec/changes/archive/2026-10-05-the-supervisor-advises/specs/shared-ui/spec.md diff --git a/openspec/changes/the-supervisor-advises/tasks.md b/openspec/changes/archive/2026-10-05-the-supervisor-advises/tasks.md similarity index 100% rename from openspec/changes/the-supervisor-advises/tasks.md rename to openspec/changes/archive/2026-10-05-the-supervisor-advises/tasks.md diff --git a/openspec/specs/agentic-harness/spec.md b/openspec/specs/agentic-harness/spec.md index ddb60c90..89d3c092 100644 --- a/openspec/specs/agentic-harness/spec.md +++ b/openspec/specs/agentic-harness/spec.md @@ -3516,3 +3516,91 @@ checked against the same permitted character set as any other. - **WHEN** a stage's entry is `"local-llm-acp"` alone - **THEN** the configuration is read without error, and the model is found from the settings or the server + +### Requirement: The supervisor advises by default and can be turned off + +The harness configuration SHALL accept `supervisor.mode` with the values +`advise` and `off`, in the global file and in a change's own file. Absent +SHALL mean `advise`. A change's own `supervisor` object SHALL be merged +key by key over the global one. + +Under `off`, none of the supervisor's suggestions SHALL be computed. +Under `advise`, the supervisor SHALL suggest and SHALL NOT stop, start, +restart or change any run, file or setting. + +Any other value of `supervisor.mode` SHALL be refused where the +configuration resolves. + +`supervisor.silentAfterSeconds` and `supervisor.waitingAfterSeconds` SHALL +be positive integers, 600 and 60 where absent. + +#### Scenario: A configuration that says nothing about it + +- **WHEN** neither harness file sets `supervisor` +- **THEN** the supervisor advises, with thresholds of 600 and 60 seconds + +#### Scenario: Turned off + +- **WHEN** the resolved `supervisor.mode` is `off` +- **THEN** no suggestion of the supervisor's is computed, and every other + suggestion still is + +#### Scenario: A mode that does not exist + +- **WHEN** a harness file sets `supervisor.mode` to a value other than + `advise` or `off` +- **THEN** resolving the configuration fails and names the field + +### Requirement: A run that says nothing new is pointed out + +The supervisor SHALL suggest looking at a run whose status record is not +gone, which is not waiting on anyone, and whose activity has not changed +for longer than `supervisor.silentAfterSeconds`. + +The suggestion SHALL quote what the run last said and for how long, and +SHALL give the command that shows the run's status and the command that +asks it to stop. It SHALL NOT call the run hung or stuck: a long turn and +a hang look the same from outside (ADR 0028). + +#### Scenario: Silent past the threshold + +- **WHEN** a run's heartbeat is fresh and its activity is twelve minutes + old, with the threshold at ten +- **THEN** a suggestion names the run, quotes its last activity, says + twelve minutes, and gives `status` and `stop` commands for it + +#### Scenario: A run whose writer is gone + +- **WHEN** a run's heartbeat is older than the staleness window +- **THEN** this suggestion is not made for it + +### Requirement: A run waiting on a person is pointed out + +The supervisor SHALL suggest attending to a run that has waited on a +checkpoint or a permission for longer than +`supervisor.waitingAfterSeconds`, naming what it waits for. + +A waiting run SHALL NOT also be pointed out as saying nothing new. + +#### Scenario: A permission nobody answered + +- **WHEN** a run has waited for a permission for three minutes, with the + threshold at one +- **THEN** a suggestion says the run waits on a person, names the + permission, and the run is not pointed out as silent + +### Requirement: A change whose last run cannot be repeated is pointed out + +The supervisor SHALL suggest the remedy for a change whose last run +failed with a diagnosis saying repeating will not help, while no run is +working on that change. + +#### Scenario: The agent was not signed in + +- **WHEN** a change's last run failed diagnosed as "not signed in" +- **THEN** a suggestion says so, quotes the line, and gives the remedy + +#### Scenario: A later run succeeded + +- **WHEN** a later run of the same change completed +- **THEN** the suggestion is no longer made diff --git a/openspec/specs/ci-cli/spec.md b/openspec/specs/ci-cli/spec.md index 699693b4..a4a1957c 100644 --- a/openspec/specs/ci-cli/spec.md +++ b/openspec/specs/ci-cli/spec.md @@ -2,7 +2,9 @@ ## Purpose TBD - created by archiving change ci-cli. Update Purpose after archive. + ## Requirements + ### Requirement: `validate` command checks every active change and aggregates the result The CLI SHALL list every active OpenSpec change in the given workspace, @@ -1011,3 +1013,21 @@ It SHALL exit `2` only where the changes themselves cannot be read. - **THEN** it prints both stays In review, and the time In review over two visits +### Requirement: The terminal shows what the supervisor finds + +`openspec-ui-cli advise` SHALL print the supervisor's suggestions with the +others, in text and in JSON. `openspec-ui-cli run` SHALL print a failed +run's diagnosis beneath its failure. + +#### Scenario: A silent run seen from a terminal + +- **WHEN** a run has said nothing new past the threshold and `advise` is + run +- **THEN** the suggestion is printed with its reason and its commands + +#### Scenario: A run that fails in the terminal + +- **WHEN** `openspec-ui-cli run` ends with a failed stage that carries a + diagnosis +- **THEN** the cause, whether repeating can help, the quoted line and the + remedy are printed after the failure diff --git a/openspec/specs/execution-core/spec.md b/openspec/specs/execution-core/spec.md index 0f52a3c3..217f4dfc 100644 --- a/openspec/specs/execution-core/spec.md +++ b/openspec/specs/execution-core/spec.md @@ -3175,3 +3175,52 @@ SHALL say whether it honours the switch: `ignored`, `environment` or - **WHEN** the switch is off - **THEN** every agent's environment and connections are what they were before this requirement + +### Requirement: A failed run says what is known about why + +When a run of any agent fails, the runner SHALL diagnose the failure from +the run's reason and the last of its output, and SHALL attach the +diagnosis to the `failed` event and to the run's terminal audit entry. + +A diagnosis SHALL name one cause from a closed set: the agent is not +installed, it is not signed in, the machine blocked it, the network could +not be reached, the service rate-limited it, the service failed, or +unknown. It SHALL say whether repeating the run can help (`no`, `likely` +or `unknown`), SHALL quote the line the cause was found in, and SHALL say +what to do instead where repeating cannot help. + +A failure matching no known cause SHALL be diagnosed as `unknown`, never +as a guessed cause. + +The diagnosis SHALL be an optional field. A reader written before it +SHALL read the event and the entry as before. + +#### Scenario: An agent that is not signed in + +- **WHEN** a run fails and its output says "Authentication required" +- **THEN** its `failed` event and its audit entry carry the cause + "not signed in", repeating `no`, the quoted line, and a remedy naming + the agent's executable + +#### Scenario: An agent that is not installed + +- **WHEN** a run fails because its executable could not be found +- **THEN** the diagnosis says the agent is not installed and that + repeating will not help + +#### Scenario: A service under load + +- **WHEN** a run fails and its output names HTTP 503 +- **THEN** the diagnosis says the service failed and that repeating is + likely to help + +#### Scenario: A failure nobody has seen + +- **WHEN** a run fails with output matching no known cause +- **THEN** the diagnosis says the cause is unknown and whether repeating + helps is unknown + +#### Scenario: A chain fails at a stage + +- **WHEN** a chain ends because one of its stages failed +- **THEN** the chain's ending entry carries that stage's diagnosis diff --git a/openspec/specs/shared-ui/spec.md b/openspec/specs/shared-ui/spec.md index 3e2f5652..c3e5956f 100644 --- a/openspec/specs/shared-ui/spec.md +++ b/openspec/specs/shared-ui/spec.md @@ -2153,3 +2153,38 @@ which command is sent: `propose` is sent as `plan`, and `apply` as - **THEN** each option reads as its name and what it does, and the `propose` option says it writes the change's missing planning artifacts and is sent as `plan` + +### Requirement: A failure is shown with its diagnosis + +Where a host shows that a run failed, on a change's card, in a run's +panel or in its log, it SHALL show the failure's diagnosis with it: the +cause, whether repeating can help, the quoted line and the remedy. Both +hosts SHALL render it with one shared component, from the field the +event and the last run already carry, and SHALL NOT diagnose anything +themselves. + +A failure without a diagnosis SHALL be shown as before. + +#### Scenario: A card whose last run failed + +- **WHEN** a change's last run failed diagnosed as "not signed in" +- **THEN** its card says the last run failed, and that the agent is not + signed in and repeating will not help + +#### Scenario: A chain that fails while watched + +- **WHEN** a chain's stage fails with a diagnosis while its panel is open +- **THEN** the panel shows the failure reason, the diagnosis beneath it, + and the remedy as text a person can copy + +### Requirement: The Harness Settings views set the supervisor's mode + +Both Harness Settings views, the global one and a change's own, SHALL +offer the supervisor's mode, Advise or Off, and SHALL save it with the +rest of the configuration. + +#### Scenario: Turning it off for one change + +- **WHEN** a person sets the supervisor to Off in a change's Harness tab + and saves +- **THEN** that change's `harness.json` carries `supervisor.mode: "off"`