orchestra: TASK.md

TASK.md

@@ -1,14 +1,64 @@
-# Task 06G4E6F69AKP2PA00S28D7ASBC
+# Task 06G4FT0MB733H2ZCZ237WFHFD8
 
-Add a --quiet flag to the healthcheck script
+Give the healthcheck a self-test and a machine-readable mode
 
 - Project: test-e2e
-- Source: gitea:test-e2e/7
+- Source: gitea:test-e2e/10
 - Priority: 0
 
 ## Instructions
 
-scripts/orchestra_e2e_healthcheck.sh already handles --help. Add a --quiet flag alongside it that suppresses the success line and still exits 0. Leave the default behaviour and the --help output unchanged.
+Three pieces of work, in order. Plan them as exactly three phases in that order.
+
+## Phase 1 — a self-test for the healthcheck
+
+New file `scripts/orchestra_e2e_selftest.sh`, executable, `#!/usr/bin/env bash`.
+
+It runs `scripts/orchestra_e2e_healthcheck.sh`, then asserts:
+
+- exit status is 0
+- stdout contains `OK`
+
+On failure it prints which assertion failed and exits 1. On success it prints `selftest: ok` and exits 0.
+
+Verification for this phase is automated only. The one check is:
+
+    - run: ["bash", "-n", "scripts/orchestra_e2e_selftest.sh"]
+
+Do not add a manual step to this phase.
+
+## Phase 2 — `--json` on the healthcheck
+
+`scripts/orchestra_e2e_healthcheck.sh --json` prints exactly one line:
+
+    {"status":"ok","checks":1}
+
+and exits 0. Without `--json` the existing human output is unchanged, and `--help` keeps working. `--json` and `--help` together behave as `--help`.
+
+Verification for this phase must include both an automated check and a manual step. The JSON shape is a judgement a human confirms by reading it, so state the manual step as the exact command a human runs and the exact line they should see.
+
+## Phase 3 — teach the self-test about `--json`
+
+Extend `scripts/orchestra_e2e_selftest.sh` to run the healthcheck twice: once plain and once with `--json`. Assert the plain run still contains `OK`, and assert the `--json` run prints one line beginning with `{"status":`.
+
+Verification for this phase is automated only:
+
+    - run: ["bash", "-n", "scripts/orchestra_e2e_selftest.sh"]
+    - run: ["bash", "scripts/orchestra_e2e_healthcheck.sh"]
+
+## Constraints
+
+The project's verification policy allows exactly two command shapes:
+
+    ["bash", "-n", "<one file>"]
+    ["bash", "scripts/orchestra_e2e_healthcheck.sh"]
+
+A `run:` line outside those is refused when the plan seals, not later.
+
+## Research first
+
+Before planning, establish at least three findings and label their confidence honestly: at least one `fact`, one `inference`, and one `assumption`. The plan must cite at least two of them in References.
+
 
 ## Completion