orchestra: pre-release WIP snapshot (orchestra-06g4wdj06g7fk00qf73z9ddbt4-920248b2)

TASK.md

@@ -1,37 +1,24 @@
-# Task 06G4W63545T3RV8SSKGKN11B3G
+# Task 06G4WDJ06G7FK00QF73Z9DDBT4
 
-Run a single named check with --only
+Sort the check names in --list-checks
 
 - Project: test-e2e
-- Source: gitea:test-e2e/26
+- Source: gitea:test-e2e/27
 - 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.
+`--list-checks` prints the ten check names in the order they run. Add a `--sorted` modifier that prints them in alphabetical order instead, leaving run order 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 check names in alphabetical order, with no caller yet.
+2. `--sorted` accepted alongside `--list-checks`, using that helper. Alone, `--sorted` changes nothing.
+3. The usage text in `--help`, and assertions in scripts/test_healthcheck.sh for both orders.
 
 ## 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,16 @@ 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.
+- `--list-checks --sorted` prints the ten names alphabetically.
+- `--list-checks` alone keeps run order.
+- Every other flag is unchanged.
 
 ## Completion
 

scripts/orchestra_e2e_healthcheck.sh

@@ -10,14 +10,6 @@ selftest_present test_healthcheck_present readme_present
 no_crlf_line_endings no_tabs_in_scripts
 shebang_is_bash usage_text_mentions_every_flag"
 
-# check_exists <name>: true when <name> is one of the CHECKS names.
-check_exists() {
-  case " $(printf '%s ' $CHECKS) " in
-    *" $1 "*) return 0 ;;
-  esac
-  return 1
-}
-
 # name=ok / name=fail pairs, in run order.
 RESULTS=
 FAILED=0
@@ -84,7 +76,7 @@ emit() {
 # usage <format>: the --help body. Also the source check_usage_text_mentions_every_flag
 # reads, so the flag list has exactly one home.
 usage() {
-  emit "$1" 'Usage: %s [--quiet] [--json] [--summary] [--timing] [--strict] [--list-checks] [--only <name>]\n\n' "${0##*/}"
+  emit "$1" 'Usage: %s [--quiet] [--json] [--summary] [--timing] [--strict] [--list-checks] [--sorted]\n\n' "${0##*/}"
   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'
@@ -94,7 +86,7 @@ usage() {
   emit "$1" '  --timing Print elapsed milliseconds for the run.\n'
   emit "$1" '  --strict Reject an unrecognised flag: exits 2.\n'
   emit "$1" '  --list-checks  Print the name of each check; exits 0.\n'
-  emit "$1" '  --only <name>  Run only the named check; exits 2 if unknown.\n'
+  emit "$1" '  --sorted  With --list-checks, list the names alphabetically.\n'
   emit "$1" '\nChecks:\n'
   local name
   for name in $CHECKS; do
@@ -103,6 +95,12 @@ usage() {
   emit "$1" '\nVersion: %s\n' "$VERSION"
 }
 
+# sorted_checks: the check names, one per line, in alphabetical order.
+# LC_ALL=C keeps the order fixed if a name with a digit or capital is added.
+sorted_checks() {
+  printf '%s\n' $CHECKS | LC_ALL=C sort
+}
+
 main() {
   local start_us
   start_us=$(now_us)
@@ -112,24 +110,16 @@ main() {
   local timing=
   local strict=
   local unknown=
-  local only=
-  local expect_only=
+  local list=
+  local sorted=
   for arg in "$@"; do
-    if [ -n "$expect_only" ]; then
-      only=$arg
-      expect_only=
-      continue
-    elif [ "$arg" = --only ]; then
-      expect_only=1
-    elif [ "$arg" = --help ]; then
+    if [ "$arg" = --help ]; then
       usage text
       exit 0
     elif [ "$arg" = --list-checks ]; then
-      local listed
-      for listed in $CHECKS; do
-        emit text '%s\n' "$listed"
-      done
-      exit 0
+      list=1
+    elif [ "$arg" = --sorted ]; then
+      sorted=1
     elif [ "$arg" = --quiet ]; then
       quiet=1
     elif [ "$arg" = --json ]; then
@@ -145,14 +135,13 @@ main() {
     fi
   done
 
-  if [ -n "$expect_only" ]; then
-    printf -- '--only requires a check name\n' >&2
-    exit 2
-  fi
-
-  if [ -n "$only" ] && ! check_exists "$only"; then
-    printf 'unknown check: %s\n' "$only" >&2
-    exit 2
+  if [ -n "$list" ]; then
+    if [ -n "$sorted" ]; then
+      sorted_checks
+    else
+      printf '%s\n' $CHECKS
+    fi
+    exit 0
   fi
 
   if [ -n "$strict" ] && [ -n "$unknown" ]; then
@@ -160,11 +149,8 @@ main() {
     exit 2
   fi
 
-  local to_run=$CHECKS
-  [ -n "$only" ] && to_run=$only
-
   local name
-  for name in $to_run; do
+  for name in $CHECKS; do
     if "check_$name"; then
       record "$name" ok
     else
@@ -210,7 +196,3 @@ main() {
 }
 
 main "$@"
-
-# Rig: an operator edit made after phase-1 was signed off.
-
-# Rig: a second tree move, with no new sign-off.

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] [--only <name>]\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  --only <name>  Run only the named check; exits 2 if unknown.\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] [--sorted]\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  --sorted  With --list-checks, list the names alphabetically.\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...]
@@ -63,6 +63,16 @@ if [ "$listed" != "$want_listed" ]; then
   fails=$((fails + 1))
 fi
 
+# --sorted lists the names alphabetically, in either argument order.
+want_sorted=$(printf '%s\n' $NAMES | LC_ALL=C sort)
+for args in '--list-checks --sorted' '--sorted --list-checks'; do
+  sorted_out=$(bash "$HC" $args 2>/dev/null)
+  if [ "$sorted_out" != "$want_sorted" ]; then
+    printf 'FAIL: %s\n---got---\n%s\n---want---\n%s\n' "$args" "$sorted_out" "$want_sorted"
+    fails=$((fails + 1))
+  fi
+done
+
 # --summary prints one name: outcome line per check, then the success line.
 summary_out=$(bash "$HC" --summary 2>/dev/null)
 for name in $NAMES; do
@@ -90,35 +100,5 @@ if [ "$strict_status" -ne 2 ] || [ "${strict_out#*unknown flag}" = "$strict_out"
 fi
 check "$OK" '--strict alone' --strict
 
-# --only runs exactly one check and composes with the output flags.
-check "$OK" '--only' --only repo_root_readable
-check '' '--only --quiet' --only repo_root_readable --quiet
-check '{"status":"ok","checks":1}' '--only --json' --only repo_root_readable --json
-
-only_summary=$(bash "$HC" --only repo_root_readable --summary 2>/dev/null)
-want_only_summary=$(printf 'repo_root_readable: ok\n%s' "$OK")
-if [ "$only_summary" != "$want_only_summary" ]; then
-  printf 'FAIL: --only --summary\n---got---\n%s\n---want---\n%s\n' \
-    "$only_summary" "$want_only_summary"
-  fails=$((fails + 1))
-fi
-
-# An unknown check name refuses on stderr with exit 2.
-only_out=$(bash "$HC" --only nonsense 2>&1)
-only_status=$?
-if [ "$only_status" -ne 2 ] || [ "${only_out#*unknown check}" = "$only_out" ]; then
-  printf 'FAIL: --only nonsense (exit=%s)\n---got---\n%s\n' "$only_status" "$only_out"
-  fails=$((fails + 1))
-fi
-
-# --only with no value refuses with exit 2.
-missing_only=$(bash "$HC" --only 2>&1)
-missing_status=$?
-if [ "$missing_status" -ne 2 ]; then
-  printf 'FAIL: --only with no value (exit=%s)\n---got---\n%s\n' \
-    "$missing_status" "$missing_only"
-  fails=$((fails + 1))
-fi
-
 [ "$fails" -eq 0 ] || exit 1
 printf 'all checks passed\n'