@jenga-ai/agent 3.5.0 → 4.0.0

package/skills/j-uncharted/scripts/write-scan-record.sh

@@ -0,0 +1,361 @@
+#!/usr/bin/env bash
+# write-scan-record.sh — write a COMMITTED baseline scan-record after a successful onboard/refresh run
+#
+# Usage: write-scan-record.sh [options] [<report.json>]
+#        discover-subsystems.sh <root> | write-scan-record.sh [options]
+#        write-scan-record.sh --help
+#
+# `onboard` mode (and, once E40_S07_T02/T03 land, `refresh` mode) needs a durable, DISKED record
+# of what a scan actually found, so a later run can tell what changed since the last one. This
+# script is that record's writer, and only that — baseline DISCOVERY (which scan-record is the
+# authoritative one to diff against) and DIFF CLASSIFICATION (unchanged/changed/new/removed) are
+# separate, not-yet-implemented scripts (E40_S07_T02, E40_S07_T03). This script only writes.
+#
+# This is deliberately NOT elicitation-state.sh's persistence mechanism. elicitation-state.sh's
+# state file is explicit, transient SESSION SCRATCH — git-ignored, meant to survive a pause within
+# one elicitation, not to persist meaning between separate onboard/refresh runs weeks or months
+# apart. This record is the opposite: COMMITTED to the repository (never git-ignored), and is the
+# only thing that gives a future `refresh` run something durable to compare against.
+#
+# This script performs NO discovery of its own. It consumes discover-subsystems.sh's ranked
+# output (the same report apply-subsystem-cap.sh consumes) and contributes only the record write.
+# It is read-only against the analysed codebase — its only write is the scan-record file itself.
+#
+# ---------------------------------------------------------------------------
+# INPUT
+# ---------------------------------------------------------------------------
+# discover-subsystems.sh's JSON report, from a file argument or from stdin (`-`, or no argument) —
+# the same input contract apply-subsystem-cap.sh uses, so both scripts can consume the identical
+# discover-subsystems.sh invocation in one onboard run. The fields read are the report's `root`
+# (repo-relative analysed root) plus each `candidates[]` entry's `path`, `files`, and `lines` —
+# real fields discover-subsystems.sh actually emits (see that script's own OUTPUT CONTRACT
+# comment), nothing invented. Everything else in the input report is ignored.
+#
+# ---------------------------------------------------------------------------
+# OPTIONS
+# ---------------------------------------------------------------------------
+#   --out-dir DIR    Where the scan-record is written. Default <repo-root>/project/rapports/analysis
+#                    — the same directory the Understanding Document convention uses, kept
+#                    distinguishable from it by filename suffix (see OUTPUT below), never by a
+#                    separate location.
+#   --json-out FILE  Also write the same JSON to this exact path (in addition to the timestamped
+#                    file under --out-dir). Not written unless requested.
+#   --label TEXT     Human label for the analysed codebase, used only in the output filename's
+#                    slug. Default: the report's own `root` (or its basename when `root` is "."
+#                    or empty, the same fallback apply-subsystem-cap.sh uses).
+#   -h, --help       Show this help and exit 0.
+#
+# ---------------------------------------------------------------------------
+# OUTPUT
+# ---------------------------------------------------------------------------
+# stdout : the absolute path of the written scan-record file. One line, nothing else — so
+#          `PATH=$(write-scan-record.sh ...)` is safe, matching run-engine.sh's own contract.
+# stderr : notices and diagnostics only, never document content.
+#
+# Filename: uncharted-scan-record-<slug>-<YYYYMMDDTHHMMSSZ>.scan-record.json, under
+# project/rapports/analysis/ — the SAME directory the Understanding Document uses, but never the
+# same file: the `.scan-record.json` suffix (as opposed to a document's `.md`) is what keeps a run
+# that produces both from overloading one artifact with two purposes. A name collision gets a
+# -2, -3... suffix, the same convention run-engine.sh uses, so repeated runs leave a diffable
+# history rather than clobbering each other. This script always writes a FRESH, timestamped file
+# per run rather than mutating a prior one in place — baseline DISCOVERY (deciding which prior
+# scan-record is the one to diff against) is a separate, later concern (E40_S07_T02); this script's
+# only job is to make sure a new one always exists to be found.
+#
+# ---------------------------------------------------------------------------
+# RECORD SHAPE (the written JSON, and what --json-out duplicates)
+# ---------------------------------------------------------------------------
+# {
+#   "script":          "write-scan-record.sh",
+#   "version": 1,
+#   "baseline_commit":  "<short HEAD SHA>" | null,   // null only when the repo has no commits yet
+#   "scanned_at":       "<ISO 8601 UTC timestamp>",
+#   "root":             "<repo-relative analysed root, from the input report>",
+#   "candidates": [
+#     { "path": "<path relative to root>", "files": <int>, "lines": <int> }, ...
+#   ],
+#   "candidate_count":  <int>,
+#   "notices":          [ "<non-fatal diagnostic>", ... ]
+# }
+#
+# `baseline_commit` is `git -C <repo-root> rev-parse --short HEAD` at scan time — the repo that
+# OWNS the engine (this repo), matching every sibling script's REPO_ROOT anchor, not the analysed
+# root (which `import`-staged or out-of-repo targets may not even share a git history with).
+#
+# ---------------------------------------------------------------------------
+# EXIT CODES
+# ---------------------------------------------------------------------------
+#   0 — success; scan-record written, its path printed on stdout
+#   1 — usage error: unknown flag, missing value, more than one positional input
+#   2 — input error: report missing/unreadable/unparseable JSON, or not a discover-subsystems.sh
+#       report (no "candidates" array)
+#   4 — write failure: --out-dir (or --json-out's directory) could not be created or is not
+#       writable. Deliberately fatal: a "successful" run that silently failed to leave a durable
+#       record would defeat the entire point of this script, the same reasoning
+#       apply-subsystem-cap.sh applies to its own rapport write.
+#
+# Examples:
+#   discover-subsystems.sh . | write-scan-record.sh
+#   discover-subsystems.sh . > s.json && write-scan-record.sh --label "my-app" s.json
+#   write-scan-record.sh --json-out /tmp/latest-scan-record.json s.json
+#
+# Requires: bash, git, python3. jq is NOT required — JSON is parsed and emitted by python3.
+
+set -euo pipefail
+
+OUT_DIR=""
+JSON_OUT=""
+LABEL=""
+INPUT=""
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [options] [<report.json>]
+
+Write a COMMITTED baseline scan-record from discover-subsystems.sh output: baseline_commit
+(repo HEAD short SHA), scanned_at (ISO 8601 UTC), root, and one candidates[] entry per subsystem
+(path, files, lines). Unlike elicitation-state.sh's transient session scratch, this record is
+never git-ignored and is meant to survive indefinitely between onboard/refresh runs.
+
+Arguments:
+  <report.json>    discover-subsystems.sh output. Omit, or pass "-", to read stdin.
+
+Options:
+  --out-dir DIR    Directory for the scan-record (default: <repo-root>/project/rapports/analysis)
+  --json-out FILE  Also write the same JSON to this exact path
+  --label TEXT     Human label used only in the output filename's slug (default: the report's root)
+  -h, --help       Show this help and exit
+
+Exit codes: 0 success, 1 usage error, 2 input error, 4 write failure.
+EOF
+}
+
+die_usage() {
+  echo "Error: $1" >&2
+  echo >&2
+  usage >&2
+  exit 1
+}
+
+require_value() {
+  # require_value <flag> <remaining-arg-count>
+  [ "$2" -ge 2 ] || die_usage "$1 requires a value"
+}
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --out-dir)     require_value "--out-dir" "$#";    OUT_DIR="$2"; shift 2 ;;
+    --out-dir=*)   OUT_DIR="${1#*=}"; shift ;;
+    --json-out)    require_value "--json-out" "$#";   JSON_OUT="$2"; shift 2 ;;
+    --json-out=*)  JSON_OUT="${1#*=}"; shift ;;
+    --label)       require_value "--label" "$#";      LABEL="$2"; shift 2 ;;
+    --label=*)     LABEL="${1#*=}"; shift ;;
+    -h|--help)     usage; exit 0 ;;
+    --)
+      shift
+      [ "$#" -le 1 ] || die_usage "at most one input report is accepted"
+      [ "$#" -eq 0 ] || INPUT="$1"
+      break ;;
+    -)
+      INPUT="-"; shift ;;
+    -*)
+      die_usage "unknown option \"$1\"" ;;
+    *)
+      [ -z "$INPUT" ] || die_usage "at most one input report is accepted (got \"$INPUT\" and \"$1\")"
+      INPUT="$1"; shift ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Input resolution
+# ---------------------------------------------------------------------------
+
+if [ -z "$INPUT" ] || [ "$INPUT" = "-" ]; then
+  INPUT="-"
+else
+  if [ ! -e "$INPUT" ]; then
+    echo "Error: input report does not exist: $INPUT" >&2
+    echo "       Expected discover-subsystems.sh JSON output." >&2
+    exit 2
+  fi
+  if [ ! -f "$INPUT" ] || [ ! -r "$INPUT" ]; then
+    echo "Error: input report is not a readable file: $INPUT" >&2
+    exit 2
+  fi
+  INPUT=$(cd -- "$(dirname -- "$INPUT")" && pwd -P)/$(basename -- "$INPUT")
+fi
+
+# ---------------------------------------------------------------------------
+# Output destinations — pre-flighted BEFORE any work, same fail-fast contract as
+# run-engine.sh / apply-subsystem-cap.sh: an unwritable destination must surface with nothing
+# done, rather than after the record has already been computed.
+#
+# Anchored on THIS SCRIPT, not on the analysed root: the record belongs to the project that owns
+# the engine, even when the analysed root lives elsewhere (import staging areas, out-of-repo
+# targets).
+# ---------------------------------------------------------------------------
+
+REPO_ROOT=$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || true)
+[ -n "$REPO_ROOT" ] || REPO_ROOT="$(pwd -P)"
+
+[ -n "$OUT_DIR" ] || OUT_DIR="$REPO_ROOT/project/rapports/analysis"
+mkdir -p "$OUT_DIR" 2>/dev/null || {
+  echo "Error: could not create output directory: $OUT_DIR" >&2
+  exit 4
+}
+[ -w "$OUT_DIR" ] || { echo "Error: output directory is not writable: $OUT_DIR" >&2; exit 4; }
+OUT_DIR=$(cd -- "$OUT_DIR" && pwd -P)
+
+if [ -n "$JSON_OUT" ]; then
+  JSON_OUT_DIR=$(dirname -- "$JSON_OUT")
+  [ -d "$JSON_OUT_DIR" ] || { echo "Error: --json-out directory does not exist: $JSON_OUT_DIR" >&2; exit 4; }
+  [ -w "$JSON_OUT_DIR" ] || { echo "Error: --json-out directory is not writable: $JSON_OUT_DIR" >&2; exit 4; }
+  JSON_OUT=$(cd -- "$JSON_OUT_DIR" && pwd -P)/$(basename -- "$JSON_OUT")
+fi
+
+# baseline_commit is the ENGINE REPO's HEAD, not the analysed root's — see header. null (not a
+# usage error) when this repo has no commits yet; a notice records why.
+BASELINE_COMMIT=$(git -C "$REPO_ROOT" rev-parse --short HEAD 2>/dev/null || true)
+SCANNED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+STAMP=$(date -u +%Y%m%dT%H%M%SZ)
+
+# ---------------------------------------------------------------------------
+# Read the discoverer's report, build the record, write it
+# ---------------------------------------------------------------------------
+# Captured into a variable and run with `python3 -c`, exactly as run-engine.sh and
+# apply-subsystem-cap.sh do: a `python3 - <<PY` heredoc would occupy python's stdin, and this
+# script must itself be able to read stdin (discover-subsystems.sh . | write-scan-record.sh).
+
+PY_SRC=$(cat <<'PY'
+import json
+import os
+import re
+import sys
+
+(INPUT, OUT_DIR, JSON_OUT, LABEL, BASELINE_COMMIT, SCANNED_AT, STAMP) = sys.argv[1:8]
+
+notices = []
+
+# --- read the discoverer's report ---------------------------------------------------------------
+
+try:
+    if INPUT == "-":
+        raw = sys.stdin.read()
+        origin = "stdin"
+    else:
+        with open(INPUT, "r", encoding="utf-8") as fh:
+            raw = fh.read()
+        origin = INPUT
+except OSError as exc:
+    sys.stderr.write("Error: could not read input report: %s\n" % exc)
+    sys.exit(2)
+
+if not raw.strip():
+    sys.stderr.write("Error: input report is empty (%s).\n" % origin)
+    sys.stderr.write("       Expected discover-subsystems.sh JSON output.\n")
+    sys.exit(2)
+
+try:
+    report = json.loads(raw)
+except ValueError as exc:
+    sys.stderr.write("Error: input report is not valid JSON (%s): %s\n" % (origin, exc))
+    sys.stderr.write("       Expected discover-subsystems.sh JSON output.\n")
+    sys.exit(2)
+
+if not isinstance(report, dict) or not isinstance(report.get("candidates"), list):
+    sys.stderr.write("Error: input report has no \"candidates\" array (%s).\n" % origin)
+    sys.stderr.write("       This does not look like discover-subsystems.sh output.\n")
+    sys.exit(2)
+
+produced_by = report.get("script")
+if produced_by and produced_by != "discover-subsystems.sh":
+    notices.append(
+        "Input reports itself as \"%s\" rather than discover-subsystems.sh; proceeding on the "
+        "strength of its candidates array." % produced_by)
+
+root = report.get("root") or report.get("root_absolute") or "(unknown root)"
+root_absolute = report.get("root_absolute") or ""
+# "." is what the discoverer reports when the analysed root IS the repo root -- a useless label
+# for a filename slug. Fall back to the directory's real name, same convention
+# apply-subsystem-cap.sh uses for its rapport label.
+if LABEL:
+    label = LABEL
+elif root not in (".", "", "./"):
+    label = root
+else:
+    label = os.path.basename(root_absolute.rstrip("/")) or root
+
+if not BASELINE_COMMIT:
+    notices.append(
+        "Could not resolve a HEAD commit for this repository (no commits yet, or not a git work "
+        "tree); \"baseline_commit\" was recorded as null."
+    )
+
+# --- candidates[] — only real fields discover-subsystems.sh actually emits ----------------------
+
+candidates = []
+for c in report.get("candidates", []):
+    if not isinstance(c, dict):
+        continue
+    candidates.append({
+        "path": c.get("path"),
+        "files": c.get("files", 0),
+        "lines": c.get("lines", 0),
+    })
+
+record = {
+    "script": "write-scan-record.sh",
+    "version": 1,
+    "baseline_commit": BASELINE_COMMIT or None,
+    "scanned_at": SCANNED_AT,
+    "root": root,
+    "candidates": candidates,
+    "candidate_count": len(candidates),
+    "notices": notices,
+}
+
+# --- filename: slugged label + timestamp, collision-safe --------------------------------------
+
+slug = re.sub(r"[^a-z0-9]+", "-", label.lower()).strip("-")[:40]
+if not slug:
+    slug = "target"
+
+out_file = os.path.join(OUT_DIR, "uncharted-scan-record-%s-%s.scan-record.json" % (slug, STAMP))
+n = 2
+while os.path.exists(out_file):
+    out_file = os.path.join(
+        OUT_DIR, "uncharted-scan-record-%s-%s-%d.scan-record.json" % (slug, STAMP, n))
+    n += 1
+
+body = json.dumps(record, indent=2, ensure_ascii=False) + "\n"
+
+try:
+    with open(out_file, "w", encoding="utf-8") as fh:
+        fh.write(body)
+except OSError as exc:
+    sys.stderr.write("Error: could not write scan-record: %s\n" % exc)
+    sys.exit(4)
+
+if JSON_OUT:
+    try:
+        with open(JSON_OUT, "w", encoding="utf-8") as fh:
+            fh.write(body)
+    except OSError as exc:
+        sys.stderr.write("Error: could not write --json-out file: %s\n" % exc)
+        sys.exit(4)
+
+for n_ in notices:
+    sys.stderr.write("Notice: %s\n" % n_)
+
+print(out_file)
+PY
+)
+
+python3 -c "$PY_SRC" \
+  "$INPUT" "$OUT_DIR" "$JSON_OUT" "$LABEL" "$BASELINE_COMMIT" "$SCANNED_AT" "$STAMP"

package/skills/j-wtf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: j.wtf
-description: Polyfill alias of the wtf skill under a collision-safe directory name. Identical behavior to /wtf — Alias of /clearify — clarifies ambiguous, dense, or under-specified prompts and conversation on request. This folder exists only so the `/wtf` slash command resolves to a skill; behaviour is identical to `/clearify`. Use when the bare /wtf form is shadowed by another tool's own built-in command of the same name.
+description: Alias of /clearify — clarifies ambiguous, dense, or under-specified prompts and conversation on request. This folder exists only so the `/wtf` slash command resolves to a skill; behaviour is identical to `/clearify`.
 keywords:
   - wtf
   - confused
@@ -8,7 +8,6 @@ keywords:
   - what does this mean
   - I'm lost
   - j-wtf
-  - polyfill
 examples:
   - "wtf"
   - "wtf does this mean"
@@ -18,10 +17,10 @@ examples:
 
 # WTF — Alias of /clearify
 
-This skill is a literal-directory-name duplicate of `skills/wtf/`. It exists so that `/j-wtf` (and `j.j-wtf`) give a guaranteed-unshadowed way to reach the same flow as `/wtf`, even if a host tool's own built-in command of the same name would otherwise shadow or override the bare `/wtf` alias (Claude Code's native skill resolution is a literal-string, directory-name-based match — see `docs/skill-authoring.md`'s "Invocation Convention").
+`skills/j-wtf/` is the **canonical, hand-edited** directory for this skill, per CLAUDE.md's "The Canonical Naming Contract" (the `E50` reopening of 2026-09-09, which promoted `skills/j-wtf/` from generated twin to sole canonical form). The `j-` prefix is there for collision safety — a real directory under a distinct name, so a host tool shipping its own same-named built-in command cannot shadow it (Claude Code's native skill resolution is a literal-string, directory-name-based match; see `docs/skill-authoring.md`'s "Invocation Convention").
 
-This file is generated/synced by `scripts/generate-j-alias.sh wtf` from `skills/wtf/SKILL.md` — do not hand-edit it; re-run the generator instead to pick up source changes.
+> ⚠️ **`scripts/generate-j-alias.sh` was retired by `E50_S14` and no longer exists — there is nothing to run.** This file was previously generated from a bare `skills/wtf/SKILL.md` source; `E50_S15` deleted that directory. This file is now the sole canonical, hand-edited source for this skill — edit it directly.
 
 ## Instructions
 
-`/wtf` is an alias of `/clearify`. Follow `skills/clearify/SKILL.md` in full — do not duplicate or reimplement its ambiguity-detection logic here. Read that file's `## Instructions` section and execute it exactly as written, using whatever prompt or conversation context is attached to this `/wtf` invocation.
+`/wtf` is an alias of `/clearify`. Follow `skills/j-clearify/SKILL.md` in full — do not duplicate or reimplement its ambiguity-detection logic here. Read that file's `## Instructions` section and execute it exactly as written, using whatever prompt or conversation context is attached to this `/wtf` invocation.

package/skills/jenga/SKILL.md

@@ -169,11 +169,11 @@ This branch is entered when `detect-nl-intent.sh` (invoked above) classifies the
 This branch is entered when `detect-nl-intent.sh` classifies the argument as `nl_intent` — every comma-delimited segment failed the ID grammar, so the raw argument is treated as natural-language intent rather than a malformed ID list. This is purely a new *outcome* of the same argument-shape detection above — no new sigil, trigger prefix, or separate entry point is introduced.
 
 1. **Load the catalog** — invoke `skills/jenga/scripts/load-nl-catalog.sh` with no arguments (E53_S01_T02). Its stdout is the full skill catalog (`name`/`description`/`keywords`/`examples`/`prefered_agent` per skill), sourced exclusively from `lib/generate-skill-allow-list.js`'s generated inventory — see the script's own header for the full contract. Never re-derive this catalog by re-scanning `skills/` inline.
-2. **Match** — run `skills/route/SKILL.md`'s **Step 2 — Match the Prompt to a Skill** (the three-pass keyword → example-similarity → description match, including its tie-break and no-match handling) against this catalog, treating `detect-nl-intent.sh`'s `raw_argument` field as the prompt. Reuse that section's matching logic by reference — do not re-author its prose here.
-3. **Confident single match** — report the routing decision using `skills/route/SKILL.md`'s **Step 7 — Report Routing Decision** format (substitute `/jenga` for `/route` as the invoking command named in the report), then invoke the matched skill exactly as `skills/route/SKILL.md`'s **Step 6 — Invoke the Matched Skill** already does: load `agents/<prefered_agent>.md` when the matched skill specifies `metadata.prefered_agent`, otherwise execute the skill instructions directly. The matched skill's own execution takes over from here — do not continue into this `/jenga` invocation's Phase 1.
-4. **No match, or an ambiguous multi-way tie (single-skill match)** — before surfacing `/route`'s generic disambiguation options, attempt a **playbook fallback** (E53_S02): invoke `skills/jenga/scripts/match-playbook.sh "<raw_argument>"`. This step only ever runs when step 3 above did NOT already commit to a confident single-skill match — a confident single-skill match always wins outright and this playbook fallback is never even invoked in that case. Branch on `match-playbook.sh`'s `classification` field:
+2. **Match** — run this section's own **Skill Matching & Invocation Contract** (below) — the three-pass keyword → example-similarity → description match, including its tie-break and no-match handling — against this catalog, treating `detect-nl-intent.sh`'s `raw_argument` field as the prompt.
+3. **Confident single match** — report the routing decision using the **Skill Matching & Invocation Contract**'s **Report** format, then invoke the matched skill exactly as its **Invoke** rule already does: load `agents/<prefered_agent>.md` when the matched skill specifies `metadata.prefered_agent`, otherwise execute the skill instructions directly. The matched skill's own execution takes over from here — do not continue into this `/jenga` invocation's Phase 1.
+4. **No match, or an ambiguous multi-way tie (single-skill match)** — before surfacing the **Skill Matching & Invocation Contract**'s generic disambiguation options, attempt a **playbook fallback** (E53_S02): invoke `skills/jenga/scripts/match-playbook.sh "<raw_argument>"`. This step only ever runs when step 3 above did NOT already commit to a confident single-skill match — a confident single-skill match always wins outright and this playbook fallback is never even invoked in that case. Branch on `match-playbook.sh`'s `classification` field:
    - `playbook_match` → continue to **step 5 (Playbook proposal and execution)** below.
-   - `ambiguous` or `no_match` → continue to **step 6 (Fall through to `/route`'s disambiguation)** below — the exact behavior this branch already had before E53_S02, unchanged.
+   - `ambiguous` or `no_match` → continue to **step 6 (Fall through to the Skill Matching & Invocation Contract's disambiguation)** below — the exact behavior this branch already had before E53_S02, unchanged.
 5. **Playbook proposal and execution** — entered only on a `playbook_match` result from step 4. A proposed playbook is an ordered chain of skills (e.g. the canonical `brainstorm -> j.todo -> j.do -> j.dev-done -> j.mirror-public` chain defined in `skills/jenga/playbooks/brainstorm-to-mirror.json`) that must be confirmed, editable, and confirmable per `CLAUDE.md`'s Interaction Pattern before any step executes — the same confirm-before-execute posture `/jenga` already applies to the bare/scoped branches via `render-confirmation.sh`.
    a. **Resolve conditional metadata** (`E53_S04_T02`/`T04`) — before rendering, inspect the
       matched playbook's own `steps` array (as returned by `load-playbooks.sh`'s catalog, not the
@@ -208,12 +208,73 @@ This branch is entered when `detect-nl-intent.sh` classifies the argument as `nl
          - **Apply the transform** — when both `forward_from` (successfully resolved immediately above) and `resolve` are present, use your own LLM judgment to reshape/filter/type-bridge the forwarded value per `resolve`'s natural-language instructions (e.g. "pick the first three items", "convert this file_list to a text summary"). The transformed value — never the raw forwarded value — becomes this step's actual invocation input.
          - **Hard-fail, never silent pass-through** — if the transform cannot cleanly produce a usable, type-compatible result (the instructions don't plausibly apply to the actual value, the value is empty/malformed for what's being asked, or the result would not plausibly satisfy the target step's expected input shape), do **not** invoke this step and do **not** guess or pass through a differently-shaped value. Instead call `skills/jenga/scripts/run-playbook-step.sh advance <state_file> failed "<note>"`, where `<note>` follows the format `resolve failed on step '<step name>': could not apply "<resolve text>" to raw value <raw pre-transform value> — <short reason>` (the raw pre-transform value is always included, for debugging). Then follow the `halted` handling in 5e-vi below exactly as any other step failure — immediately stop executing further steps, report `failed_step`/`failed_note`/`completed`/`skipped`/`never_run` verbatim.
 
-         Then invoke the step exactly as `skills/route/SKILL.md`'s **Step 6 — Invoke the Matched Skill** already does for a single matched skill: load `agents/<prefered_agent>.md` when that step's own `SKILL.md` specifies `metadata.prefered_agent`, otherwise execute its instructions directly.
+         Then invoke the step exactly as this section's **Skill Matching & Invocation Contract**'s **Invoke** rule already does for a single matched skill: load `agents/<prefered_agent>.md` when that step's own `SKILL.md` specifies `metadata.prefered_agent`, otherwise execute its instructions directly.
       iii. After a normally-invoked step's execution concludes, call `skills/jenga/scripts/run-playbook-step.sh advance <state_file> passed ["<typed-output-value>"]` (the step completed successfully — supply the step's declared typed output, per its `output_types`, if it produced one) or `... advance <state_file> failed "<short failure note>"` (the step failed).
       iv. On a `step_ready` result, repeat step 5e for the newly-named step.
       v. On a `complete` result, report the full lists of `completed` AND `skipped` steps to the user and stop — the playbook run is finished; do not continue into this `/jenga` invocation's Phase 1.
       vi. On a `halted` result, **immediately stop executing any further steps** — no silent skip-ahead. Report `failed_step`, `failed_note`, `completed`, `skipped` (steps that already finished or were skipped), and `never_run` (steps that never got a chance to run) to the user verbatim from the halt report. Do not continue into this `/jenga` invocation's Phase 1.
-6. **Fall through to `/route`'s disambiguation** — entered when step 4 found no playbook match (`ambiguous` or `no_match`). Surface the same disambiguation options `skills/route/SKILL.md`'s **Step 2** already defines for these cases (browse `/help`, create a new skill via `/btw`, or proceed with the raw prompt) by reference to that section — do not re-copy its prose. Halt this `/jenga` invocation once the user picks an option; none of Phase 0.75's remaining steps or Phases 1-4 run for this branch.
+6. **Fall through to the Skill Matching & Invocation Contract's disambiguation** — entered when step 4 found no playbook match (`ambiguous` or `no_match`). Surface the same disambiguation options this section's **Skill Matching & Invocation Contract** already defines for these cases (browse `/help`, create a new skill via `/btw`, or proceed with the raw prompt). Halt this `/jenga` invocation once the user picks an option; none of Phase 0.75's remaining steps or Phases 1-4 run for this branch.
+
+##### Skill Matching & Invocation Contract
+
+This contract is inlined here — rather than referenced by path to `skills/j-route/SKILL.md` — because
+`j.route` is one of six skills that never ship publicly in either naming form (see
+`docs/public-mirror-content-parity.md`'s "Which skills are never public"), while `/jenga` itself ships
+publicly. A path reference from a shipped file to an unshipped one is a dead reference in the public
+package even though it resolves fine in this private repo (filed via `j.error` 2026-09-26).
+`skills/j-route/SKILL.md`'s own Step 2/6/7 carry the authoritative copy of this same contract for
+`/route`'s own use — the two are intentionally duplicated for public-mirror reasons; keep them in sync
+by hand if either changes.
+
+**Matching** (three passes, stop at first confident match):
+
+- *Pass 1 — Keyword Match* — check whether any phrase from a skill's `keywords` list appears verbatim
+  (case-insensitive) in the prompt.
+- *Pass 2 — Example Similarity* — compare the prompt against each skill's `examples` list as a
+  semantic similarity check; pick the skill whose examples most closely reflect the intent of the
+  prompt.
+- *Pass 3 — Description Match* — if no clear winner has emerged, compare the prompt against each
+  skill's `description` field; pick the skill whose description best captures what the user is trying
+  to do.
+
+**Tie-break** (two or more skills score equally) — present the top candidates and ask the user to
+choose:
+
+```
+More than one skill matches your prompt. Which should I apply?
+1. /<skill-a> — <one-line description>
+2. /<skill-b> — <one-line description>
+3. Neither — describe what you need
+```
+
+**No match** — inform the user and offer:
+
+```
+No matching skill found for: "<prompt>"
+Would you like to:
+1. Browse all available skills (/help)
+2. Create a new skill for this use case (/btw)
+3. Proceed without a skill (raw prompt)
+```
+
+**Invoke** — deliver to the appropriate agent: if the matched skill specifies
+`metadata.prefered_agent`, load that agent's definition from `agents/<prefered_agent>.md` and pass it
+the full context; otherwise execute the skill's instructions directly. Do not summarise or restate the
+matched skill's instructions — deliver them as-is.
+
+**Report** — before invoking, briefly inform the user:
+
+```
+Routing to: /<matched-skill-name>
+Reason: <one sentence explaining why this skill was chosen>
+```
+
+(`skills/j-route/SKILL.md`'s own Step 7 additionally reports `Board items found`/`Docs found` counts
+from its Steps 3-5 board/doc enrichment — this `/jenga` natural-language branch never performs that
+enrichment, so those two fields do not apply here and are intentionally omitted.)
+
+Then proceed immediately — do not wait for user confirmation unless the match was ambiguous (the
+tie-break above already handled that).
 
 #### Shared confirmation step (bare and scoped branches only)
 
@@ -228,6 +289,39 @@ After this phase completes (bare and scoped branches via confirmation, wildcard
 
 ---
 
+### Phase 0.9 — Generate the Run's Shared `orchestrator_session_id`
+
+This phase runs for every entry mode that reaches Phase 1 at all — bare, scoped, and wildcard (`*`) —
+immediately after Phase 0.75 completes and before Phase 1 begins. It does not run for the
+natural-language branch's playbook/single-skill-match outcomes (E53_S01/E53_S02), since those hand off
+entirely to another skill or playbook and never reach Phase 1-4 of this document.
+
+Generate exactly **one** `orchestrator_session_id` for this entire `/jenga` run, here and only here.
+Both Phase 3.5's bundle dispatch and Phase 4's first (and every later) wave dispatch need this same
+value, which is why it is generated once, early, before either call site runs.
+
+**Format.** Generate it as `jenga-<UTC ISO 8601 basic-format timestamp>` (e.g.
+`jenga-20260917T162349Z`) — a short prefix naming the orchestrating skill, plus a UTC timestamp, with no
+`/` or `..` characters. This follows the same session-id string convention this repo already uses for
+other orchestrator-minted session ids (e.g. `/do`'s own dispatch sessions), and stays compatible with
+`scripts/acquire-concurrency-slot.sh`'s own validation, which refuses a `<session_id>` argument
+containing a path separator or traversal sequence, because the value is used verbatim in filenames such
+as `project/queue/concurrency-slots-<session_id>.json`.
+
+**Generate once, reuse everywhere in this run — never regenerate.** This value MUST be reused,
+byte-for-byte unchanged, across:
+- Phase 3.5 step 7b's bundle `/do <E##_S##>` call.
+- Every wave dispatched by Phase 4 step 3, across every loop-back at Phase 4 step 5b. The loop-back
+  never mints a new value — it only ever references the one value generated here.
+
+This is what allows `E32_S15`'s per-session `max_concurrent_developers`/`max_concurrent_testers` cap
+(`skills/j-do/SKILL.md`'s `### 4.4`) to actually contend across an entire `/jenga` run's dispatches,
+instead of every spawned `/do` sub-agent minting its own private `orchestrator_session_id` and getting
+its own private, uncontended `project/queue/concurrency-slots-<id>.json` counter file — the root-cause
+defect this story (`E32_S16`) fixes.
+
+---
+
 ### Phase 1 — Decompose Epics into Stories
 
 If Phase 0.75 produced a scoped set, restrict this phase to epics that are members of that set (directly selected, or flagged in its `undecomposed` list). Under `/jenga *`, this phase is unrestricted, exactly as before.
@@ -272,7 +366,7 @@ For each in-scope story that has one or more tasks listed in `todo.md`:
       BUNDLE DETECTED: story <E##_S##> — <N> story-scoped tasks will execute as a bundle.
       ```
       where `<E##_S##>` is the story ID and `<N>` is the count of tasks in the list.
-   b. Call `/do <E##_S##>` once (with the story ID, not individual task IDs). This invokes the bundle execution path in `/do` (implemented in E32_S05_T02), which runs all tasks sequentially in one shared worktree.
+   b. Call `/do <E##_S##>` once (with the story ID, not individual task IDs), passing this run's shared `orchestrator_session_id` (generated once in Phase 0.9) into the bundle's sender object as its `session_id` field — a caller-supplied session id per `skills/j-do/SKILL.md`'s standalone-vs-caller-supplied contract (`### 4.4`/`### 5`, `E32_S16_T02`), so the bundle path's own `### 4.4` slot acquire shares this run's one counter file too, rather than minting a private one. This invokes the bundle execution path in `/do` (implemented in E32_S05_T02), which runs all tasks sequentially in one shared worktree.
    c. **Mark these tasks as bundled** — record their task IDs so Phase 4 skips individual dispatch for them.
 8. **Non-bundle stories** — stories with a mixed scope, a zero-length task list, any task missing `execution_scope: story`, or any task with `crucial_level: locked` (step 5) use the normal per-task dispatch in Phase 4 without any change.
 
@@ -282,11 +376,11 @@ Loop through `todo.md` and execute all eligible items, running independent ones
 
 1. **Collect eligible items** — from `todo.md`, find all items whose board file has `status: Pending` and no unresolved dependencies, **excluding tasks already dispatched as part of a story bundle in Phase 3.5**. If Phase 0.75 produced a scoped set, also exclude any item not a member of that set — execution never runs outside the confirmed/resolved scope. Under `/jenga *`, no such exclusion applies. A dependency is resolved if the blocking item's status is at least `In Progress` or `Passed`.
 2. **Group by parallelism** — items with no shared dependencies and no overlapping output files can run concurrently. Items that depend on each other must be sequenced.
-3. **Invoke `/do` in parallel** — launch each independent item as a **background sub-agent** simultaneously. Do not wait for one to finish before starting another if they are independent.
+3. **Invoke `/do` in parallel** — launch each independent item as a **background sub-agent** simultaneously. Do not wait for one to finish before starting another if they are independent. Pass this run's shared `orchestrator_session_id` (generated once in Phase 0.9, unchanged across every wave) into each sub-agent's sender object as its `session_id` field, per `assets/sender_template.json`'s existing shape and `skills/j-do/SKILL.md`'s caller-supplied-session-id case (`### 4.4`/`### 5`, `E32_S16_T02`) — this is what lets `E32_S15`'s per-session developer/tester concurrency cap actually contend across every sub-agent dispatched within (and across) this run's waves, instead of each one minting its own private session id and its own private, uncontended counter file.
 4. **Mark In Progress** — update `status: In Progress` in each launched item's board file (YAML front-matter) immediately after launch.
 5. **Wait, drain, and loop** — once all active background agents in the wave have completed:
    a. **Drain the scrum triggers queue** — invoke the `## Drain Scrum Triggers Queue` procedure from `agents/scrum-master.md` against `project/queue/scrum_triggers.jsonl`. `/jenga`'s orchestrating agent is the scrum-master, and this is the same session-start procedure applied mid-run: process any `rapport_review`, `status_review`, and `story_rollup` triggers written by the tester sub-sessions that just completed, then clear the file. This ensures rollups become visible on the board (story/epic status updates) before the next wave is collected, instead of sitting unprocessed until some future scrum-master session start.
-   b. **Return to step 1** of this phase to pick up any newly unblocked items — including items unblocked by the rollups just processed in (a).
+   b. **Return to step 1** of this phase to pick up any newly unblocked items — including items unblocked by the rollups just processed in (a). This loop-back reuses the SAME `orchestrator_session_id` generated once in Phase 0.9 for every subsequent wave's `/do` dispatches — it is never regenerated here or anywhere else in this phase.
 
 ### Exit condition
 
@@ -312,8 +406,8 @@ When no eligible candidates remain in Phase 4, exit and output:
 - **Picker cancelled (bare branch)** — the entire `/jenga` run halts immediately after relaying the cancellation acknowledgement; no phase past 0.75 runs, and nothing on the board is modified.
 - **Confirmation cancelled (bare or scoped branch)** — same as picker cancellation: the entire `/jenga` run halts immediately; no scoped set is produced and no later phase runs.
 - **`detect-nl-intent.sh` classifies the argument as `mixed` (scoped branch)** — the whole invocation halts at Phase 0.75 with each rejected segment's `input`/`reason` reported verbatim, per `detect-nl-intent.sh`'s own classification contract (E53_S01_T01); no partial scope is assembled from the segments that did resolve, and no fallback guess is made for the rejected ones. The user must re-invoke `/jenga <ids>` with corrected input.
-- **`detect-nl-intent.sh` classifies the argument as `nl_intent`, no confident single-skill match, and `match-playbook.sh` (E53_S02) also finds no playbook match** — the natural-language branch's step 4 attempts the playbook fallback first (see the Natural-language branch's step 4/6), and only THEN surfaces `skills/route/SKILL.md`'s Step 2 no-match disambiguation options (browse `/help`, create a new skill via `/btw`, proceed with the raw prompt) instead of guessing; no phase past 0.75 runs until the user picks one.
-- **`detect-nl-intent.sh` classifies the argument as `nl_intent`, no confident single-skill match, and `match-playbook.sh` returns an ambiguous multi-way tie between playbooks** — treated the same as the no-playbook-match case above: falls through to `skills/route/SKILL.md`'s Step 2 tie-break prompt (top candidates + a "neither, describe what you need" option) instead of guessing; no phase past 0.75 runs until the user picks one. (`match-playbook.sh`'s own `ambiguous` result — a tie between playbooks — is intentionally not given its own separate disambiguation UI; it is treated identically to `no_match` and routed to the same `/route` Step 2 fallback prose, which already has its own tie-break handling.)
+- **`detect-nl-intent.sh` classifies the argument as `nl_intent`, no confident single-skill match, and `match-playbook.sh` (E53_S02) also finds no playbook match** — the natural-language branch's step 4 attempts the playbook fallback first (see the Natural-language branch's step 4/6), and only THEN surfaces the **Skill Matching & Invocation Contract**'s no-match disambiguation options (browse `/help`, create a new skill via `/btw`, proceed with the raw prompt) instead of guessing; no phase past 0.75 runs until the user picks one.
+- **`detect-nl-intent.sh` classifies the argument as `nl_intent`, no confident single-skill match, and `match-playbook.sh` returns an ambiguous multi-way tie between playbooks** — treated the same as the no-playbook-match case above: falls through to the **Skill Matching & Invocation Contract**'s tie-break prompt (top candidates + a "neither, describe what you need" option) instead of guessing; no phase past 0.75 runs until the user picks one. (`match-playbook.sh`'s own `ambiguous` result — a tie between playbooks — is intentionally not given its own separate disambiguation UI; it is treated identically to `no_match` and routed to the same fallback prose, which already has its own tie-break handling.)
 - **`match-playbook.sh` returns `playbook_match` and the user confirms the full chain, and every step succeeds** — the Natural-language branch's step 5e reports the full `completed` AND `skipped` steps lists to the user and stops; `/jenga`'s own Phase 1 never runs for this invocation (execution was already fully handled by the playbook's own steps, e.g. `j.do`/`j.dev-done`).
 - **`match-playbook.sh` returns `playbook_match` but the user cancels at the chain confirmation step (step 5c)** — identical posture to the existing picker/confirmation cancellation cases above: the entire `/jenga` run halts immediately after relaying the cancellation acknowledgement, with NO step of the chain executed; nothing on the board is modified by this invocation.
 - **`match-playbook.sh` returns `playbook_match`, the user confirms, and a step mid-chain fails** — the Natural-language branch's step 5e(vi) halts immediately on `run-playbook-step.sh`'s `halted` result: no step after the failed one runs (no silent skip-ahead), and the user is shown exactly which steps already completed or were skipped, which step failed (with its note), and which steps never ran.
@@ -329,3 +423,4 @@ When no eligible candidates remain in Phase 4, exit and output:
 - **A playbook step carries composition origin metadata (depth > 1), shown at confirmation (`E53_S05_T03`)** — the Natural-language branch's step 5b relays `render-playbook-confirmation.sh`'s rendered chain, which now visibly indents and labels that step's line with "(from playbook: <id>, depth N)" — composing another playbook's steps into a chain never hides where one playbook ends and another begins from the user, even though the whole chain is still ONE numbered, editable, confirmable list (never a separate confirmation per nested playbook) and checking/unchecking a composed step still works exactly like any other step.
 - **`/jenga *` (wildcard branch)** — never produces a scoped set; Phases 1-4 run fully unrestricted over the entire board, identical to `/jenga`'s behavior before Phase 0.75 existed.
 - **Stale out-of-scope story queued in `todo.md` from an earlier run (scoped run only)** — Phase 3.5's scoped-set guard skips it entirely (not considered for bundling), so it cannot be dispatched via a bundle `/do <E##_S##>` call that would otherwise bypass Phase 4's own scoped-set exclusion; it remains untouched in `todo.md` until a future run's scope includes it.
+- **`orchestrator_session_id` reuse across waves and phases (`E32_S16_T01`)** — the value generated once in Phase 0.9 is the exact same value threaded into Phase 3.5's bundle `/do` call and into every wave's `/do` sub-agent sender objects dispatched by Phase 4, for the entire duration of a single `/jenga` run; Phase 4 step 5b's loop-back never mints a new one. A run that halts before Phase 0.9 completes (e.g. cancelled at Phase 0.75's picker/confirmation) never reaches Phase 3.5 or Phase 4, so the value it would have generated is simply never used.

package/skills/jenga/playbooks/board-hygiene.json

@@ -0,0 +1,32 @@
+{
+  "id": "board-hygiene",
+  "name": "Board Hygiene",
+  "description": "Reconciles the scrum board against what is actually implemented, captures whatever drift that turns up as follow-up todos, and reports the resulting board state -- a read-only triage chain that writes no code and produces no commit of its own.",
+  "keywords": [
+    "board hygiene",
+    "board triage",
+    "board health",
+    "tidy the board",
+    "board audit"
+  ],
+  "examples": [
+    "reconcile the board, capture whatever drift you find as todos, then show me the status",
+    "do a full board hygiene pass -- sync it with what's really implemented, queue follow-ups for anything off, and report where we stand",
+    "check the board against reality, turn any discrepancies into todo items, and give me an overview at the end",
+    "the board feels out of sync -- triage it, capture the fixes, and summarise the state afterwards",
+    "audit the board end to end and only queue follow-up work if something is actually wrong"
+  ],
+  "steps": [
+    "j-reconcile",
+    {
+      "skill": "j-todo",
+      "forward_from": "j-reconcile",
+      "conditional": {
+        "depends_on": "j-reconcile",
+        "predicate": "non_empty"
+      },
+      "instruction": "capture each reconciliation finding as a follow-up todo"
+    },
+    "j-status"
+  ]
+}