orchestra: pre-release WIP snapshot (orchestra-06g4ft0mb733h2zcz237wfhfd8-b318f8b5)

orchestra burn-in: PR tail

TASK.md

@@ -1,49 +1,64 @@
-# Task 06G4E83E4KRXM8DS90M2648MGM
+# 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/8
+- Source: gitea:test-e2e/10
 - Priority: 0
 
 ## Instructions
 
-## Goal
+Three pieces of work, in order. Plan them as exactly three phases in that order.
 
-Add a --quiet flag to the healthcheck script
+## Phase 1 — a self-test for the healthcheck
 
-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.
+New file `scripts/orchestra_e2e_selftest.sh`, executable, `#!/usr/bin/env bash`.
 
-## Verification
+It runs `scripts/orchestra_e2e_healthcheck.sh`, then asserts:
 
-- `bash -n scripts/*.sh && bash scripts/orchestra_e2e_healthcheck.sh` exited 0
-- commit: 41dee802416aaa9020a2e31ae5b79fa084a4f150
-- independent review of 41dee802416aaa9020a2e31ae5b79fa084a4f150: pass
-- accepted plan: 6c62e3cde23ed9aca296ed5b60295384b35cdad9fe0e1e45fa381d5801fb9af3
+- exit status is 0
+- stdout contains `OK`
 
-## Behavioural changes
+On failure it prints which assertion failed and exits 1. On success it prints `selftest: ok` and exits 0.
 
-- none reported
+Verification for this phase is automated only. The one check is:
 
-## Deviations from plan
+    - run: ["bash", "-n", "scripts/orchestra_e2e_selftest.sh"]
 
-- none reported
+Do not add a manual step to this phase.
 
-## Remaining risks
+## Phase 2 — `--json` on the healthcheck
 
-- none reported
+`scripts/orchestra_e2e_healthcheck.sh --json` prints exactly one line:
 
-## Review hotspots
+    {"status":"ok","checks":1}
 
-- none reported
+and exits 0. Without `--json` the existing human output is unchanged, and `--help` keeps working. `--json` and `--help` together behave as `--help`.
 
-The sections above are derived from Orchestra state. The reported
-changes, deviations, risks, and hotspots are the implementing agent's
-own account and are not verified.
+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.
 
-## Acceptance criteria
+## 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.
 
-- not stated in the task contract
 
 ## Completion
 

scripts/orchestra_e2e_healthcheck.sh

@@ -1,16 +1,28 @@
 #!/usr/bin/env bash
 
 main() {
+  local quiet=
+  local json=
   for arg in "$@"; do
     if [ "$arg" = --help ]; then
-      printf 'Usage: %s\n\n' "${0##*/}"
+      printf 'Usage: %s [--quiet]\n\n' "${0##*/}"
       printf 'Healthcheck script for Orchestra E2E tests.\n'
       printf 'Exits 0 with a success message if all checks pass.\n'
+      printf '  --quiet  Suppress the success message; still exits 0.\n'
       exit 0
+    elif [ "$arg" = --quiet ]; then
+      quiet=1
+    elif [ "$arg" = --json ]; then
+      json=1
     fi
   done
 
-  printf 'OK - all healthchecks passed\n'
+  if [ -n "$json" ]; then
+    printf '{"status":"ok","checks":1}\n'
+    exit 0
+  fi
+
+  [ -n "$quiet" ] || printf 'OK - all healthchecks passed\n'
   exit 0
 }
 

scripts/orchestra_e2e_selftest.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Self-test for the Orchestra E2E healthcheck.
+
+here=$(cd "$(dirname "$0")" && pwd)
+healthcheck="$here/orchestra_e2e_healthcheck.sh"
+
+# fail <assertion> <captured stdout>: always echo what the healthcheck printed,
+# so a red run is diagnosable without rerunning it by hand.
+fail() {
+  printf 'selftest: FAILED %s\n' "$1" >&2
+  printf 'selftest: healthcheck stdout was:\n%s\n' "$2" >&2
+  exit 1
+}
+
+# plain run
+out=$(bash "$healthcheck")
+status=$?
+
+[ "$status" -eq 0 ] || fail "plain run exit status: want 0, got $status" "$out"
+case "$out" in
+  *OK*) ;;
+  *) fail "plain run stdout contains OK" "$out" ;;
+esac
+
+# --json run
+jout=$(bash "$healthcheck" --json)
+jstatus=$?
+
+[ "$jstatus" -eq 0 ] || fail "--json run exit status: want 0, got $jstatus" "$jout"
+jlines=$(printf '%s\n' "$jout" | wc -l)
+[ "$jlines" -eq 1 ] || fail "--json run line count: want 1, got $jlines" "$jout"
+case "$jout" in
+  '{"status":'*) ;;
+  *) fail '--json run stdout prefix: want {"status":' "$jout" ;;
+esac
+
+printf 'selftest: ok\n'

scripts/test_healthcheck.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Self-check for orchestra_e2e_healthcheck.sh.
+
+HC="$(dirname "$0")/orchestra_e2e_healthcheck.sh"
+OK='OK - all healthchecks passed'
+USAGE="$(printf 'Usage: orchestra_e2e_healthcheck.sh [--quiet]\n\nHealthcheck script for Orchestra E2E tests.\nExits 0 with a success message if all checks pass.\n  --quiet  Suppress the success message; still exits 0.')"
+fails=0
+
+check() { # check <expected-stdout> <label> [args...]
+  local want=$1 label=$2 got status
+  shift 2
+  got=$(bash "$HC" "$@" 2>/dev/null)
+  status=$?
+  if [ "$got" != "$want" ] || [ "$status" -ne 0 ]; then
+    printf 'FAIL: %s (exit=%s)\n---got---\n%s\n---want---\n%s\n' "$label" "$status" "$got" "$want"
+    fails=$((fails + 1))
+  fi
+}
+
+check "$OK" 'no args'
+check '' '--quiet' --quiet
+check "$USAGE" '--help' --help
+check "$USAGE" '--help --quiet' --help --quiet
+check "$USAGE" '--quiet --help' --quiet --help
+check "$OK" 'unknown flag ignored' --bogus
+
+[ "$fails" -eq 0 ] || exit 1
+printf 'all checks passed\n'