autonomous-sdlc-harness 0.1.0 → 0.2.0

package/templates/scripts/cleanup-merged-worktrees.sh

@@ -37,10 +37,10 @@
 #     checkout's own directory;
 #   * a branch with an ACTIVE RUN — one whose record in the run registry
 #     (`<state_dir>/autonomous_logs/registry.json`, shaped
-#     `{"runs": {"<branch>": {"status": …}}}`) says `running`, `parked` or
-#     `paused`. All three own a working copy the watcher will come back to: a
-#     parked run is waiting for a clarification answer and a paused one for a
-#     RESUME sentinel, and `worktree remove --force` would discard the pause
+#     `{"runs": {"<branch>": {"status": …}}}`) says `running`, `parked`,
+#     `park_loop` or `paused`. All four own a working copy the watcher will come
+#     back to: a parked run is waiting for a clarification answer, a `park_loop`
+#     one for an operator to clear it, and a paused one for a RESUME sentinel, and `worktree remove --force` would discard the pause
 #     note the resumed engine is pointed at.
 #
 # CAVEAT: `: gone` + force-delete also catches an ABANDONED branch whose remote
@@ -89,6 +89,13 @@
 # Usage: cleanup-merged-worktrees.sh [--dry-run]
 #   --dry-run   report what would be removed; remove nothing
 #
+# Environment:
+#   HARNESS_FETCH_TIMEOUT   seconds to allow the `fetch --prune` before it is
+#                           killed and the round skipped (default 60, clamped to
+#                           1..3600; anything else falls back to the default).
+#                           The bound exists because this sweep runs inside the
+#                           watcher's loop — see the paragraph on it below.
+#
 # Exit map a caller can switch on:
 #
 #   0  the sweep ran, or refused and deleted nothing (the message says which)
@@ -120,7 +127,7 @@
 #                 printf '%s' '{"runs":{"feat_gone":{"status":"running"}}}' \
 #                   > "$d/sdlc-harness/autonomous_logs/registry.json"
 #                 -> the skip line for feat_gone; nothing deleted (same with
-#                    "parked" and "paused")
+#                    "parked", "park_loop" and "paused")
 #   unresolvable  printf 'x' > "$d/harness.config.json"
 #                 -> one line, exit 0, nothing deleted
 #   offline       git -C "$d" remote set-url origin /nonexistent.git
@@ -206,17 +213,128 @@ if [ -e "$registry" ]; then
   # document without it is a registry this cannot enumerate, so `jq` fails and
   # the refusal below fires — which is the point: reading such a file as "no
   # active runs" would delete a branch a run is still working on.
-  if ! active="$(jq -r '.runs | to_entries[] | select(.value.status == "running" or .value.status == "parked" or .value.status == "paused") | .key' "$registry" 2>/dev/null)"; then
+  if ! active="$(jq -r '.runs | to_entries[] | select(.value.status == "running" or .value.status == "parked" or .value.status == "park_loop" or .value.status == "paused") | .key' "$registry" 2>/dev/null)"; then
     echo "cleanup-merged-worktrees.sh: '$registry' could not be read as a run registry — refusing to delete anything"
     exit 0
   fi
 fi
 
+# Run one command with a WALL-CLOCK CEILING, and report a timeout as 124 the way
+# GNU `timeout` does. Written out here rather than taken from `timeout`, which is
+# not on a stock macOS, nor from lib/harness-run-lib.sh, which an adopter's
+# `scriptsDir` may be carrying at an older revision than this file — a sweep that
+# dies on an unbound function is a worse failure than the hang it closes.
+#
+# The command runs in the BACKGROUND and is polled, because `wait` alone cannot be
+# bounded in POSIX shell. On expiry the child gets a TERM, then a KILL two seconds
+# later if it is still there, so it is asked before it is forced.
+#
+# THE SIGNAL GOES TO THE PROCESS GROUP, NOT THE CHILD — `kill -TERM -$pid`, with
+# the negative pid — and `set -m` is what makes that possible, by giving the
+# background job a process group of its own whose id is that pid. Signalling the
+# child alone is not enough and was measured not to be: `git fetch` spawns the
+# transport (`ssh`, `git-remote-https`) as its own child, and that grandchild
+# INHERITS THIS SCRIPT'S STDOUT. Kill only git and the transport survives, holding
+# the write end of the pipe the watcher is reading, so the watcher blocks on a
+# sweep that already printed its verdict — the original hang, moved rather than
+# closed. Against a fetch stalled for 3 seconds under a 3-second ceiling, the
+# child-only version returned its message on time and did not let the script exit
+# for 144 seconds; the group kill ends it in the 2 the escalation costs.
+#
+# Job control is restored to whatever it was, since a script that leaves `-m` on
+# behind it changes how every later background command here reports.
+#
+# run_bounded <seconds> <command> [args…]
+# NOT GROUPED WHEN A PERSON IS WATCHING. `set -m` puts the child in a process
+# group that is not the terminal's foreground one, so a child that reads the
+# CONTROLLING TERMINAL is stopped with SIGTTIN instead of being answered — and
+# `ssh` reads a key passphrase from `/dev/tty` directly, which `GIT_TERMINAL_PROMPT=0`
+# does not cover because it is not git asking. `kill -0` keeps succeeding on a
+# stopped process, so a by-hand sweep on a passphrase-protected key would burn the
+# whole ceiling and report a network failure that never happened. The header's
+# "WHO RUNS IT" names a person by hand as a supported caller, so that path keeps
+# the child in this script's own group and signals the child alone: the pipe a
+# surviving transport could hold is a terminal the person is looking at, and they
+# can end it themselves. The watcher is daemonised with no controlling terminal,
+# so it takes the grouped path, which is the one the orphaned-transport hang
+# needed.
+run_bounded() {
+  local limit="$1" pid waited=0 job_control=0 grouped=1
+  shift
+  if { : > /dev/tty; } 2>/dev/null; then grouped=0; fi
+  case "$-" in *m*) job_control=1 ;; esac
+  [ "$grouped" -eq 1 ] && set -m
+  "$@" &
+  pid=$!
+  [ "$job_control" -eq 1 ] || set +m
+  while kill -0 "$pid" 2>/dev/null; do
+    if [ "$waited" -ge "$limit" ]; then
+      if [ "$grouped" -eq 1 ]; then
+        kill -TERM "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || :
+        sleep 2
+        # Only while the group is still there. Once it is gone the negative form
+        # fails, and retrying the bare pid would aim an unconditional SIGKILL at a
+        # number the kernel may already have handed to somebody else.
+        kill -0 "-$pid" 2>/dev/null && { kill -KILL "-$pid" 2>/dev/null || :; }
+      else
+        kill -TERM "$pid" 2>/dev/null || :
+        sleep 2
+        kill -0 "$pid" 2>/dev/null && { kill -KILL "$pid" 2>/dev/null || :; }
+      fi
+      wait "$pid" 2>/dev/null || :
+      return 124
+    fi
+    sleep 1
+    waited=$((waited + 1))
+  done
+  wait "$pid"
+}
+
 # Refresh remote-tracking refs so a deleted upstream becomes `[gone]`. A failed
 # fetch (offline, or an unreachable remote) skips this round rather than sweeping
 # on stale tracking information, which would report every branch as gone.
-if ! git -C "$main_repo" fetch --prune --quiet 2>/dev/null; then
-  echo "cleanup-merged-worktrees.sh: fetch --prune failed (offline?); skipping this round"
+#
+# BOUNDED, BECAUSE THIS SWEEP RUNS INSIDE THE WATCHER'S LOOP.
+# `autonomous-watcher.sh` calls this script synchronously, so a fetch that HANGS
+# rather than fails stalls the whole loop — no inbox pass, no drop picked up,
+# nothing written to `watcher.log`, and the watcher still alive and healthy-looking
+# in `ps`. The paragraph above anticipated a fetch that FAILS and skips the round;
+# a stale TCP connection left behind by a network change or a laptop sleep never
+# fails, and an unbounded `git fetch` sits in it indefinitely. The ceiling turns
+# that second mode into the first, which this script already handles.
+#
+# `GIT_TERMINAL_PROMPT=0` closes the other hang of the same shape: a credential
+# prompt, on a remote whose authentication has lapsed, blocks on a terminal that
+# no unattended run is watching.
+#
+# SIXTY SECONDS, AND OVERRIDABLE. The default is generous next to a healthy fetch
+# of a repository this size and short next to `CLEANUP_INTERVAL_SECS` (300), the
+# interval the watcher runs this sweep on, so a hung remote costs a fraction of
+# that round rather than the loop. It is NOT short next to `POLL_INTERVAL_SECS`
+# (15): a sweep that spends the whole ceiling does hold the loop for it, which is
+# the price of bounding the fetch at all and the reason the ceiling is not larger.
+# `HARNESS_FETCH_TIMEOUT` raises it for an adopter on a link where 60 s is not
+# generous, and lowers it for the test that drives this ceiling.
+#
+# VALIDATED BY VALUE, NOT BY SHAPE. An earlier form of this clause tested the
+# string for non-digits, which let through two values the sentence below calls
+# impossible. A 19-digit number is all digits, and `[ "$waited" -ge <huge> ]` does
+# not compare false — it ERRORS, and a non-zero status reads as false, so the
+# timeout branch never fires and the poll loop runs forever: unbounded, which is
+# the one thing this knob must not express. `00` is all digits and is not the
+# string `0`, and `[ 0 -ge 00 ]` is true on the first iteration, so every sweep
+# kills its own fetch before it starts, blames the network, and never cleans up
+# another branch. Comparing the VALUE closes both: `[ ]` returns non-zero for an
+# unparseable or out-of-range string as readily as for a number that fails the
+# test, and the default is what survives either way. The upper clamp is what keeps
+# a fat-fingered value from expressing "wait forever" in seconds.
+fetch_timeout="${HARNESS_FETCH_TIMEOUT:-60}"
+if ! { [ "$fetch_timeout" -ge 1 ] && [ "$fetch_timeout" -le 3600 ]; } 2>/dev/null; then
+  fetch_timeout=60
+fi
+
+if ! GIT_TERMINAL_PROMPT=0 run_bounded "$fetch_timeout" git -C "$main_repo" fetch --prune --quiet 2>/dev/null; then
+  echo "cleanup-merged-worktrees.sh: fetch --prune failed (offline, unreachable or timed out); skipping this round"
   exit 0
 fi
 

package/templates/scripts/docs-search-server.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# docs-search-server.sh — start the docs-retrieval MCP server for the checkout
+# this script sits in, by `exec`ing the machine-shared retrieval runtime's
+# `docs serve`.
+#
+# WHO RUNS IT. The agent runner, from the `harness-docs` entry `init` writes into
+# `.mcp.json` when `docs.retrieval` is on — never a dispatched agent's Bash call,
+# so its row in `cli/src/generators/outerLoopScripts.ts` is
+# `agentInvocable: false` and the generated permission profile carries no entry
+# for it.
+#
+# STDOUT BELONGS TO THE MCP TRANSPORT. Nothing here may print to stdout before
+# the `exec`: a stray byte there is a malformed frame for the client. Every
+# diagnostic goes to stderr.
+#
+# THE RUNTIME IS THE ONLY THING THIS RUNS, with no fallback to any other
+# installation: a committed `.mcp.json` cannot know where an adopter's own CLI
+# lives. `doctor`'s `retrieval-dependencies` check and `init`'s install both key
+# on the same entry file this script tests. `PATH` is settled through the
+# library's fallback list before the `exec`, because the starter is the agent
+# runner rather than a login shell.
+#
+# MIRRORS — a change to any owner below is an edit here too:
+#   `retrieval/runtime` and `node_modules/autonomous-sdlc-harness/dist/cli.js`
+#     mirror `RETRIEVAL_CACHE_DIRNAME`, `RETRIEVAL_RUNTIME_DIRNAME` and
+#     `RUNTIME_CLI_RELATIVE` in `cli/src/retrieval/runtime.ts`;
+#   `hr_cache_dir` mirrors `machineCacheDir()` in `cli/src/machine/paths.ts`.
+#
+# Exit contract:
+#   1    no runtime entry at the resolved path, no cache directory to resolve
+#        it under, or no repository at this script's location; stderr names
+#        which
+#   N    otherwise `docs serve`'s own status, through `exec`; a failure to
+#        source the library exits non-zero before that, on stderr only
+
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/harness-run-lib.sh
+. "$script_dir/lib/harness-run-lib.sh"
+
+# The agent runner starts this script, and a runner launched from a desktop session carries a
+# minimal PATH. The library appends the usual locations without promoting any of them, which is the
+# same bootstrap autonomous-watcher.sh runs for the same reason.
+PATH="$(hr_path_with_fallbacks)"
+export PATH
+
+if ! root="$(hr_repo_root "$script_dir")"; then
+  echo "docs-search-server: $script_dir is not inside a git repository, so there is no checkout to serve" >&2
+  exit 1
+fi
+
+if ! cache_dir="$(hr_cache_dir)"; then
+  echo "docs-search-server: neither XDG_CACHE_HOME nor HOME is set, so the retrieval runtime cannot be located" >&2
+  exit 1
+fi
+entry="$cache_dir/retrieval/runtime/node_modules/autonomous-sdlc-harness/dist/cli.js"
+
+if [ ! -f "$entry" ]; then
+  echo "docs-search-server: no retrieval runtime at $entry; run \`npx autonomous-sdlc-harness init\` in a repository with docs.retrieval on" >&2
+  exit 1
+fi
+
+exec node "$entry" docs serve --cwd "$root"

package/templates/scripts/lib/harness-run-lib.sh

@@ -52,8 +52,8 @@
 # an `hr_lane_*` function still gets a library that only reads. The lane's
 # ceilings are the only environment values here that carry policy, because the
 # lane is machine-scoped and has no configuration key to carry them; each is
-# named where it is used. `XDG_STATE_HOME`, `XDG_CONFIG_HOME`, `HOME` and `PWD`
-# are also read, as location anchors only, and `PATH` is read by
+# named where it is used. `XDG_STATE_HOME`, `XDG_CONFIG_HOME`, `XDG_CACHE_HOME`,
+# `HOME` and `PWD` are also read, as location anchors only, and `PATH` is read by
 # `hr_path_with_fallbacks` alone — as that function's input, which it prints back
 # transformed and never assigns.
 #
@@ -196,6 +196,8 @@
 #   anchors           hr_main_repo "$root"; hr_work_root "$root"
 #                     hr_worktree_dir "$root" feat/x; hr_repo_slug "$root"
 #                     hr_state_path "$root" autonomous_logs/registry.json
+#   machine dirs      ( XDG_CACHE_HOME= hr_cache_dir )     -> $HOME/.cache/autonomous-sdlc-harness
+#                     ( XDG_CACHE_HOME=/x/ hr_cache_dir )  -> /x/autonomous-sdlc-harness
 #   the PATH policy   run each in a SUBSHELL, so your own PATH is untouched:
 #                     ( PATH="$HOME/.rbenv/shims:/usr/bin:/bin"
 #                       hr_path_with_fallbacks )
@@ -966,6 +968,20 @@ hr_machine_config_dir() {
   printf '%s/autonomous-sdlc-harness\n' "${base%/}"
 }
 
+# The machine-local cache directory, holding the shared docs-retrieval runtime.
+# Mirrors `machineCacheDir()` in `cli/src/machine/paths.ts`: the variable when
+# set and non-empty, else `$HOME/.cache`, one trailing slash stripped. Return 1
+# when there is no home to anchor it to.
+hr_cache_dir() {
+  local base="${XDG_CACHE_HOME-}"
+  [ -n "$base" ] || base="${HOME-}/.cache"
+  case "$base" in
+    /.cache) return 1 ;;
+  esac
+  [ -n "$base" ] || return 1
+  printf '%s/autonomous-sdlc-harness\n' "${base%/}"
+}
+
 # The push-notification credential files, in RESOLUTION ORDER, one per line and
 # whether or not each exists — the caller sources the first that does:
 #
@@ -1068,7 +1084,7 @@ hr_push_env_files() {
 # THE THREE CEILINGS ARE THE ONLY ENVIRONMENT VALUES THAT CARRY POLICY HERE. The
 # file's other environment reads are location anchors, not policy:
 # `XDG_STATE_HOME` and `HOME` in `hr_lane_dir`, `XDG_CONFIG_HOME` and `HOME` in
-# `hr_machine_config_dir`, `PWD` in `hr_repo_root` and `hr_main_repo`. The
+# `hr_machine_config_dir`, `XDG_CACHE_HOME` and `HOME` in `hr_cache_dir`, `PWD` in `hr_repo_root` and `hr_main_repo`. The
 # ceilings are machine-scoped policy with no configuration key:
 #
 #   HR_LANE_STATE_MAX_AGE_SECS   21600  when a PUBLISHED RECORD THAT NAMED NO

package/templates/scripts/restart-watcher.sh

@@ -52,7 +52,7 @@
 #
 #   * the run registry (`<state_dir>/autonomous_logs/registry.json`, shaped
 #     `{"runs": {"<branch>": {"status": …}}}`) is the SOURCE OF TRUTH: a record
-#     whose status is `running` or `parked` is a run in flight;
+#     whose status is `running`, `parked` or `park_loop` is a run in flight;
 #   * a process probe for the agent binary — `${HARNESS_AGENT_CLI:-claude}`, the
 #     same variable the watcher launches through — is a BACKSTOP, for a run OF
 #     THIS PROJECT whose record has not been written yet or was written by a
@@ -119,7 +119,8 @@
 #
 #   in flight     printf '%s' '{"runs":{"feat_x":{"status":"running"}}}' > "$reg"
 #                 run            -> the in-flight report, exit 2, and no
-#                                   "$w/calls" at all (same for "parked")
+#                                   "$w/calls" at all (same for "parked"
+#                                   and "park_loop")
 #   forced        run --force    -> the same report plus the restarting line,
 #                                   and "$w/calls" holds `daemon stop` then
 #                                   `daemon install`, in that order
@@ -257,7 +258,7 @@ else
   # document that has no such wrapper is a registry this cannot enumerate, so
   # `jq` fails and the refusal below fires. Reading such a file as "no active
   # runs" is the one misreading that costs a run.
-  elif ! active="$(jq -r '.runs | to_entries[] | select(.value.status == "running" or .value.status == "parked") | "\(.value.status) \(.key)"' "$registry" 2>/dev/null)"; then
+  elif ! active="$(jq -r '.runs | to_entries[] | select(.value.status == "running" or .value.status == "parked" or .value.status == "park_loop") | "\(.value.status) \(.key)"' "$registry" 2>/dev/null)"; then
     active=""
     unknown="'$registry' could not be read as a run registry (invalid JSON, or no .runs wrapper)"
   fi

package/templates/state-dir/business_parity_reviews/README.md

@@ -6,4 +6,4 @@ The reviewer reads the story index's `## Context` plus every per-task file and j
 
 The directory exists only while `phases.parity` is `true` in `harness.config.json`: a project with no reference implementation to compare against has no parity gate and will not have it, and turning the phase on and re-running `init` creates it — an absent directory here is a configuration answer, not a missing artifact. While the phase is on, files appear one per failed gate and stop at convergence or at the fifth iteration, where the gate escalates with the latest path. Nothing supersedes an earlier file, and the whole directory is committed with the branch, since no ignore rule reaches it.
 
-The mistake worth naming is expecting a plan to pass here on plausible prose. This gate is graded on **citations**: every constant, call name, wire field and boundary comparison the plan describes has to trace to a source line in the reference implementation, and a behaviour the reference has that no per-task file covers is a Must Fix of the same grade as a wrong field. A plan that describes the right behaviour without saying where it came from is the ordinary way a round is lost here.
+The mistake worth naming is expecting a plan to pass here on plausible prose. This gate is graded on **citations**: every constant, call name, wire field and boundary comparison the plan describes has to trace to an anchored source in the reference implementation (its path and symbol, never a line number in their place), and a behaviour the reference has that no per-task file covers is a Must Fix of the same grade as a wrong field. A plan that describes the right behaviour without saying where it came from is the ordinary way a round is lost here.

package/templates/state-dir/clarification_digests/README.md

@@ -1,6 +1,6 @@
 # clarification_digests/
 
-One `<state_dir>/clarification_digests/<branch>.md` per branch, holding one block per clarification the runs on that branch parked on and had answered: what was asked, the operator's ruling in the words it was given, and whatever that ruling settles beyond the question that prompted it. One file per **branch**, appended to and never rewritten — each block is headed by the `question_<n>` index it was derived from, and a later round or a resumed session adds only the blocks whose key is not in it already.
+One `<state_dir>/clarification_digests/<branch>.md` per branch, holding one block per park the runs on that branch stopped on and had answered — one per question file, however many questions it raised: what was asked, the operator's ruling in the words it was given, and whatever that ruling settles beyond the questions that prompted it. One file per **branch**, appended to and never rewritten — each block is headed by the `question_<n>` index of the question file it was derived from, and a later round or a resumed session adds only the blocks whose key is not in it already. Blocks written before a park held several questions — one per one-question file — are left exactly as written, and stay uniquely keyed because that index is never reused.
 
 Each block is written by the run's own orchestrator at the end of the run, from the question and answer files in `<state_dir>/clarifications/<branch>/` and its `answered/` archive. Those files are machine-local and go with the working copy — a working copy removed once its branch has merged takes every question and every answer with it, and **this file is the copy that survives**. Its readers are whoever comes to the branch afterwards: a reviewer asking why a decision was taken the way it was, and the human folding a ruling that outlives the branch into the rules the flow reads.
 

package/templates/state-dir/clarifications/README.md

@@ -1,9 +1,9 @@
 # clarifications/
 
-The park-and-ask channel: one question per file at `<state_dir>/clarifications/<branch>/question_<n>.md`, with the answer it waits for beside it as `answer_<n>.md`. Pairing is by the index `<n>`, which is 1-based and unique across the branch's directory **including its `answered/` archive** — a second question takes the next index above the highest `question_<n>.md` in either location, never merely the next free name at the top level and never overwriting the first, so an archived pair does not free its index for reuse and `answer_3.md` answers `question_3.md` and nothing else. One `<branch>` subdirectory holds one branch's exchange and is created with that branch's first question.
+The park-and-ask channel: one question file per park at `<state_dir>/clarifications/<branch>/question_<n>.md`, holding every question that park raises as its own `## Q<k> — <decision needed>` section with `k` counted from 1, and one answer file for the whole park beside it as `answer_<n>.md`. Pairing is by the index `<n>`, which is 1-based and unique across the branch's directory **including its `answered/` archive** — a second park takes the next index above the highest `question_<n>.md` in either location, never merely the next free name at the top level and never overwriting the first, so an archived pair does not free its index for reuse and `answer_3.md` answers `question_3.md` and nothing else. One `<branch>` subdirectory holds one branch's exchange and is created with that branch's first park.
 
-A question is written by the agent that reached a decision it must not take alone: writing the file and ending the session is what parks the run. The answer is written by the harness's answer command on the operator's behalf, verbatim and beside the question. The run daemon reads the pair and re-launches the same engine in the same working copy for the lowest answered index, and the re-entering run is what consumes the answer — the daemon never answers a question itself.
+A question file is written by the agent that reached decisions it must not take alone: writing the file and ending the session is what parks the run. The answer is written by the harness's answer command on the operator's behalf, verbatim and beside the question file; it addresses each question by its `Q<k>` label, and a question it leaves unaddressed is asked again by the resumed run, in a new park file. The run daemon resumes the same engine in the same working copy only once every question file at the top level of the branch's directory has its answer, and the re-entering run is what consumes the answers — the daemon never answers a question itself. A park written before this layout, as several one-question files, is resumed by the same rule.
 
-The pair stays at the top level of the branch's directory while that resumed session runs, and moves into `<branch>/answered/` only once it has exited, so the answer is still where the resumed run looks for it and an already-consumed one is never read a second time. Everything the runs write here is machine-local and gitignored; this README is the only committed file in **this** directory. What survives the working copy is the record: at the end of each run the branch's resolved questions are digested into `<state_dir>/clarification_digests/<branch>.md`, one committed block per question, keyed by that same index — what was asked and the operator's ruling in the words it was given. Reusing an index would make two parks indistinguishable there, which is the other reason it is never reused. That sibling directory's own README states the format. The harness's watcher documentation, which ships with it, states the same protocol from the daemon's side.
+The answered pairs stay at the top level of the branch's directory while that resumed session runs, and once it has exited exactly the pairs that resume consumed move into `<branch>/answered/`, so an answer is still where the resumed run looks for it and an already-consumed one is never read a second time. A pair written while the resumed run is going was not consumed by it and stays at the top level for the next resume. Everything the runs write here is machine-local and gitignored; this README is the only committed file in **this** directory. What survives the working copy is the record: at the end of each run the branch's resolved parks are digested into `<state_dir>/clarification_digests/<branch>.md`, one committed block per park, keyed by that same index — what was asked and the operator's ruling in the words it was given. Reusing an index would make two parks indistinguishable there, which is the other reason it is never reused. That sibling directory's own README states the format. The harness's watcher documentation, which ships with it, states the same protocol from the daemon's side.
 
-The mistake worth naming is tidying up by hand. Deleting a question, or archiving it into `answered/` before the run that parked on it has been resumed, does not unpark that run — an unanswered question is the sole signal that classifies a run as parked, so removing it strands the run instead, waiting on an answer nothing will now deliver.
+The mistake worth naming is tidying up by hand. Deleting a question file, or archiving it into `answered/` before the run that parked on it has been resumed, does not unpark that run — a question file left at the top level is the sole signal that classifies a run as parked, so removing it strands the run instead, waiting on an answer nothing will now deliver.