Adopt the config-driven extractor; project overview README

Replaces the copy taken earlier with the newer version from
scene-actor-extraction's traceability-tooling branch, which had moved on: it
takes per-repo settings from a traceability.toml rather than the CLI flags
added here, validates them, and names languages ("rust") rather than making
each repo spell out extensions. That is the better design, so the flags go and
this becomes the single source.

Two fixes on top:

- Config discovery searched from the working directory only, so --root pointed
  at another tree found no traceability.toml and failed with
  "requirement_types is empty" while a perfectly good config sat in the
  directory named. That breaks both intended callers: CI passing --root, and a
  wrapper running the vendored copy. Discovery now starts from --root.
- The test suite had not been migrated with the Config refactor and failed on
  the branch as well as here. All 53 now pass: entry points take a Config,
  ci_executable moved to the Register which owns tier policy, fixtures write a
  real traceability.toml so config discovery is exercised rather than bypassed,
  and the live-register tests take LIVE_REGISTER from the environment since the
  project home holds no component register of its own.

The README becomes a project overview rather than a table of contents: what the
problem is, why a paused-frame answer is the wrong question, why gallery data
never leaves the instance, and why the manifest server can hold no binary.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

scripts/traceability/traceability-gate.sh

@@ -1,89 +1,62 @@
 #!/bin/sh
 #
-# Requirement traceability gate. Run locally exactly as CI runs it:
+# Requirement traceability gate. Run locally exactly as CI runs it, from the
+# component repo root:
 #
 #     scripts/traceability/traceability-gate.sh
 #
-# Writes traces-report.json and docs/traceability.md, prints the coverage
-# report, and exits non-zero when the gate fails.
+# Writes the JSON report and the markdown matrix, prints the coverage report,
+# and exits non-zero when the gate fails.
 #
-# Environment:
-#   MIN_COVERAGE    minimum overall coverage percent (default 0 - see below)
-#   ALLOW_ORPHANS   set to 1 to report orphan tags without failing
-#   TRACES_JSON     JSON report path (default traces-report.json)
-#   TRACES_MD       markdown matrix path (default docs/traceability.md)
-#   REPO_ROOT       repository to scan. Defaults to two levels above this
-#                   script, which is correct when the tooling lives in the repo
-#                   it checks. **When vendored as a submodule that default is
-#                   the submodule itself**, so a consuming repo must set this —
-#                   its wrapper does.
-#   TYPES           comma-separated requirement prefixes (e.g. UR,DR). Defaults
-#                   to the extraction set; a repo whose prefixes differ parses
-#                   to zero requirements without this.
-#   SUFFIXES        comma-separated file extensions (e.g. .rs). Defaults to the
-#                   C++/Python set; a repo whose language differs scans zero
-#                   files without this.
-#   SCAN_ROOTS      comma-separated directories to walk, relative to REPO_ROOT.
-#   SYSTEM_SPEC     optional path to the system SPEC.md, which defines the PR/SR
-#                   IDs; when given, PR/SR orphans are reported too. It lives in
-#                   the project home (jray-project) — when this tooling is
-#                   vendored from there, it is a sibling of this script.
+# This script is shared by every JRay component, so it knows nothing about any
+# one repo. All repo-specific settings - requirement ID prefixes, source
+# suffixes, scan roots, register path, thresholds - live in `traceability.toml`
+# at the component repo root. Run
 #
-# Threshold policy lives here and nowhere else. It is deliberately NOT
-# duplicated into the workflow YAML: a threshold written in two places is a
-# threshold that will disagree with itself.
+#     scripts/traceability/extract_traces.py --print-example-config
 #
-# MIN_COVERAGE defaults to 0 because almost nothing is tagged yet - tags are
-# added as the pipeline is built, so a low number today is accurate rather than
-# alarming. A zero threshold does NOT mean the gate cannot fail: orphan tags,
-# a >100% ratio, a register that parses to nothing, and an empty source scan
-# are all hard failures from day one. Raise MIN_COVERAGE as tags land; treat
-# every raise as a ratchet, never a reset.
+# for the annotated schema. A repo whose config is wrong parses zero
+# requirements or scans zero files, and the gate refuses to report rather than
+# printing a misleading 0%.
+#
+# Environment (all optional; each overrides the config file):
+#   TRACES_CONFIG   path to traceability.toml
+#   TRACES_ROOT     repo root (default: nearest dir containing traceability.toml)
+#   MIN_COVERAGE    minimum overall coverage percent
+#   ALLOW_ORPHANS   1 to report orphan tags without failing
+#   TRACES_JSON     JSON report path
+#   TRACES_MD       markdown matrix path
+#   SYSTEM_SPEC     SPEC.md defining PR/SR; enables PR/SR orphan checking
+#   PYTHON          interpreter (default: python3)
+#
+# Threshold policy belongs in traceability.toml, not here and not in the
+# workflow YAML: a threshold written in two places is a threshold that will
+# disagree with itself.
 #
 # POSIX sh, no bashisms, no jq - the extractor does its own arithmetic and
-# printing so CI needs nothing beyond python3.
+# printing, so CI needs nothing beyond python3.
 
 set -eu
 
 SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-REPO_ROOT="${REPO_ROOT:-$(CDPATH= cd -- "$SCRIPT_DIR/../.." && pwd)}"
-
-MIN_COVERAGE="${MIN_COVERAGE:-0}"
-TRACES_JSON="${TRACES_JSON:-$REPO_ROOT/traces-report.json}"
-TRACES_MD="${TRACES_MD:-$REPO_ROOT/docs/traceability.md}"
 
 PYTHON="${PYTHON:-python3}"
 command -v "$PYTHON" >/dev/null 2>&1 || {
-    echo "FAILED: $PYTHON not found. The traceability gate needs Python 3.9+" >&2
+    echo "FAILED: $PYTHON not found. The traceability gate needs Python 3.9+," >&2
+    echo "        or 3.11+ to read traceability.toml." >&2
     exit 2
 }
 
-set -- \
-    --root "$REPO_ROOT" \
-    --requirements "${REQUIREMENTS:-$REPO_ROOT/docs/requirements.md}" \
-    --format coverage \
-    --json-out "$TRACES_JSON" \
-    --markdown-out "$TRACES_MD" \
-    --min-coverage "$MIN_COVERAGE"
+set -- --format coverage
 
-if [ "${ALLOW_ORPHANS:-0}" = "1" ]; then
-    set -- "$@" --allow-orphans
-fi
-
-if [ -n "${SYSTEM_SPEC:-}" ]; then
-    set -- "$@" --system-spec "$SYSTEM_SPEC"
-fi
-
-if [ -n "${TYPES:-}" ]; then
-    set -- "$@" --types "$TYPES"
-fi
-
-if [ -n "${SUFFIXES:-}" ]; then
-    set -- "$@" --suffixes "$SUFFIXES"
-fi
-
-if [ -n "${SCAN_ROOTS:-}" ]; then
-    set -- "$@" --scan-roots "$SCAN_ROOTS"
-fi
+# Explicit `if` rather than `[ ... ] && ...`, because a trailing false test in
+# an && list exits under `set -e` in some POSIX shells.
+if [ -n "${TRACES_CONFIG:-}" ]; then set -- "$@" --config "$TRACES_CONFIG"; fi
+if [ -n "${TRACES_ROOT:-}" ];   then set -- "$@" --root "$TRACES_ROOT"; fi
+if [ -n "${MIN_COVERAGE:-}" ];  then set -- "$@" --min-coverage "$MIN_COVERAGE"; fi
+if [ -n "${TRACES_JSON:-}" ];   then set -- "$@" --json-out "$TRACES_JSON"; fi
+if [ -n "${TRACES_MD:-}" ];     then set -- "$@" --markdown-out "$TRACES_MD"; fi
+if [ -n "${SYSTEM_SPEC:-}" ];   then set -- "$@" --system-spec "$SYSTEM_SPEC"; fi
+if [ "${ALLOW_ORPHANS:-0}" = "1" ]; then set -- "$@" --allow-orphans; fi
 
 exec "$PYTHON" "$SCRIPT_DIR/extract_traces.py" "$@"