orchestra: pre-release WIP snapshot (orchestra-06g4w2tmz9mw9sebm5mgtm5288-89c1c97d)

TASK.md

@@ -1,24 +1,43 @@
-# Task 06G54DZYGP30QXM4SXDB1NF1E0
+# Task 06G4W2TMZ9MW9SEBM5MGTM5288
 
-Report the slowest check in the summary footer
+Describe each healthcheck check in one line
 
 - Project: test-e2e
-- Source: gitea:test-e2e/36
+- Source: gitea:test-e2e/24
 - Priority: 0
 
 ## Instructions
 
-`--summary` prints one line per check. After those lines, print a footer naming the slowest check and its elapsed milliseconds, in the form `slowest: <name> (<n>ms)`.
+scripts/orchestra_e2e_healthcheck.sh now runs ten named checks. Give each one a one-line description, and print those descriptions where the names are already printed.
 
-Plan this as THREE phases:
+The descriptions, one per check:
 
-1. Record each check's elapsed milliseconds beside its existing result, with no output change.
-2. The footer printed by --summary from those recorded values.
-3. The usage text in `--help`, and assertions in scripts/test_healthcheck.sh.
+- repo_root_readable: the repository root exists and is readable
+- scripts_dir_present: the scripts directory exists
+- healthcheck_executable_bit: this script is executable
+- selftest_present: the selftest script is present
+- test_healthcheck_present: the healthcheck test is present
+- readme_present: README.md is present
+- no_crlf_line_endings: no tracked text file uses CRLF endings
+- no_tabs_in_scripts: no script indents with tabs
+- shebang_is_bash: every script declares the bash shebang
+- usage_text_mentions_every_flag: the usage text lists every flag
+
+Where they appear:
+
+- `--list-checks` prints `<name>: <description>`, one per line.
+- `--help` prints the same description beside each name in its Checks section.
+- `--summary` is unchanged and keeps printing `<name>: ok`.
+
+Plan this as FIVE phases, two checks per phase, in the order listed above.
 
 ## Work one phase at a time
 
-Implement phase N, request its verification, and only then begin phase N+1.
+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.
 
 ## Verification policy for this project
 
@@ -27,15 +46,25 @@ 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. Give every phase at least one automated check from that list and at least one manual check.
+Anything else is refused when you seal the plan.
+
+## Behaviour that must not change
+
+Every existing flag keeps its current behaviour and exit status: --quiet, --json, --summary, --timing, --strict, --help. The success line is unchanged.
 
 ## 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:
-- --summary ends with the slowest line.
-- --quiet suppresses it, and every other flag is unchanged.
+- Each of the ten checks has a one-line description in exactly one place in the script.
+- --list-checks prints name and description for all ten.
+- --help lists all ten names with their descriptions.
+- --summary, --timing, --strict, --json and --quiet behave exactly as before.
 
 ## Completion
 

scripts/orchestra_e2e_healthcheck.sh

@@ -12,8 +12,6 @@ shebang_is_bash usage_text_mentions_every_flag"
 
 # name=ok / name=fail pairs, in run order.
 RESULTS=
-# name=ms pairs, in run order.
-TIMES=
 FAILED=0
 TOTAL=0
 
@@ -75,6 +73,35 @@ emit() {
   [ "$format" = none ] || printf "$@"
 }
 
+# describe <name>: the one-line description of a check. One case branch per
+# name; this is the only place a description is written.
+describe() {
+  case "$1" in
+    repo_root_readable) printf 'the repository root exists and is readable' ;;
+    scripts_dir_present) printf 'the scripts directory exists' ;;
+    healthcheck_executable_bit) printf 'this script is executable' ;;
+    selftest_present) printf 'the selftest script is present' ;;
+    test_healthcheck_present) printf 'the healthcheck test is present' ;;
+    readme_present) printf 'README.md is present' ;;
+    no_crlf_line_endings) printf 'no tracked text file uses CRLF endings' ;;
+    no_tabs_in_scripts) printf 'no script indents with tabs' ;;
+    shebang_is_bash) printf 'every script declares the bash shebang' ;;
+    usage_text_mentions_every_flag) printf 'the usage text lists every flag' ;;
+  esac
+}
+
+# label <name>: '<name>: <description>', or bare '<name>' while a name has no
+# description yet.
+label() {
+  local text
+  text=$(describe "$1")
+  if [ -n "$text" ]; then
+    printf '%s: %s' "$1" "$text"
+  else
+    printf '%s' "$1"
+  fi
+}
+
 # usage <format>: the --help body. Also the source check_usage_text_mentions_every_flag
 # reads, so the flag list has exactly one home.
 usage() {
@@ -84,14 +111,14 @@ usage() {
   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" '  --help   Print this usage text and exit 0.\n'
-  emit "$1" '  --summary  Print one line per check before the success message, then the slowest check after it.\n'
+  emit "$1" '  --summary  Print one line per check before the success message.\n'
   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" '\nChecks:\n'
   local name
   for name in $CHECKS; do
-    emit "$1" '  %s\n' "$name"
+    emit "$1" '  %s\n' "$(label "$name")"
   done
   emit "$1" '\nVersion: %s\n' "$VERSION"
 }
@@ -112,7 +139,7 @@ main() {
     elif [ "$arg" = --list-checks ]; then
       local listed
       for listed in $CHECKS; do
-        emit text '%s\n' "$listed"
+        emit text '%s\n' "$(label "$listed")"
       done
       exit 0
     elif [ "$arg" = --quiet ]; then
@@ -135,15 +162,13 @@ main() {
     exit 2
   fi
 
-  local name check_start
+  local name
   for name in $CHECKS; do
-    check_start=$(now_us)
     if "check_$name"; then
       record "$name" ok
     else
       record "$name" fail
     fi
-    TIMES="$TIMES $name=$(elapsed_ms "$check_start")"
   done
 
   local format=text
@@ -180,19 +205,6 @@ main() {
   fi
 
   emit "$format" '%s\n' "$SUCCESS_MESSAGE"
-
-  if [ -n "$summary" ]; then
-    local slow_name= slow_ms=-1 ms
-    for entry in $TIMES; do
-      ms=${entry#*=}
-      if [ "$ms" -gt "$slow_ms" ]; then
-        slow_ms=$ms
-        slow_name=${entry%=*}
-      fi
-    done
-    emit "$format" 'slowest: %s (%sms)\n' "$slow_name" "$slow_ms"
-  fi
-
   exit 0
 }
 

scripts/test_healthcheck.sh

@@ -7,7 +7,19 @@ 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, then the slowest check after it.\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')"
+LABELS='repo_root_readable: the repository root exists and is readable
+scripts_dir_present: the scripts directory exists
+healthcheck_executable_bit: this script is executable
+selftest_present: the selftest script is present
+test_healthcheck_present: the healthcheck test is present
+readme_present: README.md is present
+no_crlf_line_endings: no tracked text file uses CRLF endings
+no_tabs_in_scripts: no script indents with tabs
+shebang_is_bash: every script declares the bash shebang
+usage_text_mentions_every_flag: the usage text lists 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'
+  while IFS= read -r line; do printf '  %s\n' "$line"; done <<<"$LABELS"
+  printf '\nVersion: 1.0.0')"
 fails=0
 
 check() { # check <expected-stdout> <label> [args...]
@@ -57,7 +69,7 @@ fi
 
 # --list-checks prints one name per line and nothing else.
 listed=$(bash "$HC" --list-checks 2>/dev/null)
-want_listed=$(printf '%s\n' $NAMES)
+want_listed=$LABELS
 if [ "$listed" != "$want_listed" ]; then
   printf 'FAIL: --list-checks\n---got---\n%s\n---want---\n%s\n' "$listed" "$want_listed"
   fails=$((fails + 1))
@@ -71,18 +83,10 @@ for name in $NAMES; do
     *) printf 'FAIL: --summary omits %s\n' "$name"; fails=$((fails + 1)) ;;
   esac
 done
-# The success line, then the slowest footer as the final line.
-summary_tail=${summary_out##*$'\n'}
-summary_body=${summary_out%$'\n'*}
-case "$summary_body" in
+case "$summary_out" in
   *"$OK") ;;
   *) printf 'FAIL: --summary does not end with the success line\n'; fails=$((fails + 1)) ;;
 esac
-case "$summary_tail" in
-  'slowest: '*'ms)') ;;
-  *) printf 'FAIL: --summary does not end with the slowest line\n---got---\n%s\n' "$summary_tail"; fails=$((fails + 1)) ;;
-esac
-check '' '--quiet --summary' --quiet --summary
 
 # --timing prints an elapsed line, and composes with --json and --quiet.
 contains 'healthchecks:' '--timing' --timing