orchestra: pre-release WIP snapshot (orchestra-06g4ww6tnd26m16cza6we5t458-be13b045)

TASK.md

@@ -1,37 +1,24 @@
-# Task 06G4W63545T3RV8SSKGKN11B3G
+# Task 06G4WW6TND26M16CZA6WE5T458
 
-Run a single named check with --only
+Print the healthcheck version in --json output
 
 - Project: test-e2e
-- Source: gitea:test-e2e/26
+- Source: gitea:test-e2e/32
 - Priority: 0
 
 ## Instructions
 
-Give scripts/orchestra_e2e_healthcheck.sh a `--only <name>` flag that runs a single named check instead of all ten, then prints the usual success line.
+`--json` prints `{"status":"ok","checks":<n>}`. Add the script's VERSION to that object as a `version` field, leaving every other output untouched.
 
-Behaviour:
+Plan this as THREE phases:
 
-- `--only repo_root_readable` runs that check alone and exits 0 when it passes.
-- `--only nonsense` prints `unknown check: nonsense` on stderr and exits 2.
-- `--only` composes with `--summary`, `--json` and `--quiet`, each keeping its current shape over the single result.
-- Without `--only`, every existing flag behaves exactly as it does today.
-
-Plan this as FIVE phases:
-
-1. A helper that resolves a name to a check function and reports whether the name is known.
-2. Flag parsing for `--only <name>`, with the unknown-name refusal and exit 2.
-3. Running the single resolved check and recording its result through the existing results state.
-4. Composition with `--summary` and `--json`.
-5. The usage text in `--help`, and assertions in scripts/test_healthcheck.sh for each behaviour above.
+1. A helper that returns the JSON body as a string, with the current fields and no behaviour change.
+2. The `version` field added to that helper's output.
+3. The usage text in `--help`, and assertions in scripts/test_healthcheck.sh.
 
 ## Work one phase at a time
 
-Implement phase N, request its verification, and only then begin phase N+1. Do not write the whole change first and verify the phases afterwards.
-
-## Every phase carries both kinds of check
-
-This is a hard requirement of this task. Each phase must have at least one automated check from the policy below. Each phase must also have at least one manual check, confirmed by a human reading the printed output. Orchestra runs the automated ones. A human owns the manual ones, and the phase is not finished until that human signs it off.
+Implement phase N, request its verification, and only then begin phase N+1.
 
 ## Verification policy for this project
 
@@ -40,21 +27,15 @@ Only two commands may appear on a run: line, exactly:
 - ["bash", "-n", "<path>"]
 - ["bash", "scripts/orchestra_e2e_healthcheck.sh"]
 
-Anything else is refused when you seal the plan.
+Anything else is refused when you seal the plan. Give every phase at least one automated check from that list and at least one manual check.
 
 ## Research first
 
 Establish at least three findings with distinct confidence: at least one fact, one inference, one assumption.
 
-## Handoff behaviour
-
-Behave normally. If Orchestra asks you to write a handoff report, write it and stop.
-
 Acceptance:
-- `--only <name>` runs exactly one check.
-- An unknown name exits 2 with a message on stderr.
-- `--only` composes with `--summary`, `--json` and `--quiet`.
-- Every existing flag is unchanged when `--only` is absent.
+- `--json` carries a version field with the script's VERSION.
+- --quiet, --summary, --timing, --strict and --help are unchanged.
 
 ## Completion
 

scripts/orchestra_e2e_healthcheck.sh

@@ -73,6 +73,11 @@ emit() {
   [ "$format" = none ] || printf "$@"
 }
 
+# json_body <checks> <timings>: the --json object, no trailing newline.
+json_body() {
+  printf '{"status":"ok","checks":%d,"version":"%s"%s}' "$1" "$VERSION" "$2"
+}
+
 # usage <format>: the --help body. Also the source check_usage_text_mentions_every_flag
 # reads, so the flag list has exactly one home.
 usage() {
@@ -80,7 +85,7 @@ usage() {
   emit "$1" 'Healthcheck script for Orchestra E2E tests.\n'
   emit "$1" 'Exits 0 with a success message if all checks pass.\n'
   emit "$1" '  --quiet  Suppress the success message; still exits 0.\n'
-  emit "$1" '  --json   Print a single-line JSON result; still exits 0.\n'
+  emit "$1" '  --json   Print a single-line JSON result with the version; still exits 0.\n'
   emit "$1" '  --help   Print this usage text and exit 0.\n'
   emit "$1" '  --summary  Print one line per check before the success message.\n'
   emit "$1" '  --timing Print elapsed milliseconds for the run.\n'
@@ -160,7 +165,7 @@ main() {
   if [ "$format" = json ]; then
     local timings=
     [ -n "$timing" ] && timings=",\"timings\":{\"healthchecks\":$elapsed}"
-    emit "$format" '{"status":"ok","checks":%d%s}\n' "$TOTAL" "$timings"
+    emit "$format" '%s\n' "$(json_body "$TOTAL" "$timings")"
     exit 0
   fi
 

scripts/test_healthcheck.sh

@@ -7,7 +7,7 @@ NAMES='repo_root_readable scripts_dir_present healthcheck_executable_bit
 selftest_present test_healthcheck_present readme_present
 no_crlf_line_endings no_tabs_in_scripts
 shebang_is_bash usage_text_mentions_every_flag'
-USAGE="$(printf 'Usage: orchestra_e2e_healthcheck.sh [--quiet] [--json] [--summary] [--timing] [--strict] [--list-checks]\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.\n  --json   Print a single-line JSON result; still exits 0.\n  --help   Print this usage text and exit 0.\n  --summary  Print one line per check before the success message.\n  --timing Print elapsed milliseconds for the run.\n  --strict Reject an unrecognised flag: exits 2.\n  --list-checks  Print the name of each check; exits 0.\n\nChecks:\n  repo_root_readable\n  scripts_dir_present\n  healthcheck_executable_bit\n  selftest_present\n  test_healthcheck_present\n  readme_present\n  no_crlf_line_endings\n  no_tabs_in_scripts\n  shebang_is_bash\n  usage_text_mentions_every_flag\n\nVersion: 1.0.0')"
+USAGE="$(printf 'Usage: orchestra_e2e_healthcheck.sh [--quiet] [--json] [--summary] [--timing] [--strict] [--list-checks]\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.\n  --json   Print a single-line JSON result with the version; still exits 0.\n  --help   Print this usage text and exit 0.\n  --summary  Print one line per check before the success message.\n  --timing Print elapsed milliseconds for the run.\n  --strict Reject an unrecognised flag: exits 2.\n  --list-checks  Print the name of each check; exits 0.\n\nChecks:\n  repo_root_readable\n  scripts_dir_present\n  healthcheck_executable_bit\n  selftest_present\n  test_healthcheck_present\n  readme_present\n  no_crlf_line_endings\n  no_tabs_in_scripts\n  shebang_is_bash\n  usage_text_mentions_every_flag\n\nVersion: 1.0.0')"
 fails=0
 
 check() { # check <expected-stdout> <label> [args...]
@@ -79,6 +79,8 @@ esac
 # --timing prints an elapsed line, and composes with --json and --quiet.
 contains 'healthchecks:' '--timing' --timing
 contains '"timings":{"healthchecks":' '--timing --json' --timing --json
+contains '"version":"1.0.0"' '--json version' --json
+contains '"version":"1.0.0"' '--timing --json version' --timing --json
 check '' '--timing --quiet' --timing --quiet
 
 # --strict rejects an unrecognised flag; on its own it changes nothing.