@jenga-ai/agent 3.6.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,9 +17,9 @@ 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
 

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/j-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/j-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/j-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/j-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/j-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)
 
@@ -345,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/j-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/j-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.

package/skills/jenga/playbooks/schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://jenga.local/schemas/jenga-playbook.schema.json",
   "title": "Jenga Multi-Skill Playbook",
-  "description": "Schema for a single multi-skill playbook definition consumed by skills/jenga/scripts/load-playbooks.sh (E53_S02_T01). A playbook is a dedicated, versionable data file describing an ORDERED chain of skills that /jenga's natural-language branch may propose (as an editable, confirmable numbered list -- see skills/jenga/scripts/render-playbook-confirmation.sh, E53_S02_T03) when free-text intent spans more than one skill and does not cleanly resolve to a single one via skills/j-route/SKILL.md's Step 2 matching. This file itself (schema.json) is never treated as a playbook -- load-playbooks.sh explicitly excludes it by filename when scanning skills/jenga/playbooks/*.json.",
+  "description": "Schema for a single multi-skill playbook definition consumed by skills/jenga/scripts/load-playbooks.sh (E53_S02_T01). A playbook is a dedicated, versionable data file describing an ORDERED chain of skills that /jenga's natural-language branch may propose (as an editable, confirmable numbered list -- see skills/jenga/scripts/render-playbook-confirmation.sh, E53_S02_T03) when free-text intent spans more than one skill and does not cleanly resolve to a single one via skills/jenga/SKILL.md's inlined Skill Matching & Invocation Contract. This file itself (schema.json) is never treated as a playbook -- load-playbooks.sh explicitly excludes it by filename when scanning skills/jenga/playbooks/*.json.",
   "type": "object",
   "required": ["id", "name", "description", "keywords", "examples", "steps"],
   "additionalProperties": false,
@@ -18,17 +18,17 @@
     },
     "description": {
       "type": "string",
-      "description": "One-sentence explanation of what this playbook accomplishes end-to-end, used as the lowest-priority match signal (description match, same as skills/j-route/SKILL.md's Step 2 Pass 3) when keywords/examples don't produce a confident match."
+      "description": "One-sentence explanation of what this playbook accomplishes end-to-end, used as the lowest-priority match signal (description match, same as skills/jenga/SKILL.md's inlined Skill Matching & Invocation Contract Pass 3) when keywords/examples don't produce a confident match."
     },
     "keywords": {
       "type": "array",
-      "description": "Short phrases (1-3 words) for verbatim, case-insensitive keyword matching against the raw natural-language prompt -- the highest-priority match signal (Pass 1), mirroring skills/j-route/SKILL.md's Step 2 Pass 1 semantics exactly, but scoped to this playbook's catalog rather than the single-skill catalog.",
+      "description": "Short phrases (1-3 words) for verbatim, case-insensitive keyword matching against the raw natural-language prompt -- the highest-priority match signal (Pass 1), mirroring skills/jenga/SKILL.md's inlined Skill Matching & Invocation Contract Pass 1 semantics exactly, but scoped to this playbook's catalog rather than the single-skill catalog.",
       "items": { "type": "string" },
       "minItems": 1
     },
     "examples": {
       "type": "array",
-      "description": "Natural-language example prompts a user might type that should resolve to this playbook. Used for the semantic similarity match (Pass 2), mirroring skills/j-route/SKILL.md's Step 2 Pass 2 semantics. At least one example must plausibly span the full breadth of this playbook's steps (not just its first step) so it is distinguishable from a plain single-skill match.",
+      "description": "Natural-language example prompts a user might type that should resolve to this playbook. Used for the semantic similarity match (Pass 2), mirroring skills/jenga/SKILL.md's inlined Skill Matching & Invocation Contract Pass 2 semantics. At least one example must plausibly span the full breadth of this playbook's steps (not just its first step) so it is distinguishable from a plain single-skill match.",
       "items": { "type": "string" },
       "minItems": 1
     },

package/skills/jenga/scripts/load-nl-catalog.js

@@ -68,8 +68,11 @@ import { join } from "path";
 import { pathToFileURL } from "url";
 
 // The three permanent exceptions to the `j-<name>` canonical directory convention — see
-// docs/skill-authoring.md's Canonical Naming Contract and scripts/audit-twin-divergence.sh's
-// NEVER_TWINNED list, which this mirrors.
+// docs/skill-authoring.md's Canonical Naming Contract, and scripts/repoint-skill-refs.sh's
+// REPOINT_SKILL_REFS_EXCEPTIONS list, which this mirrors. (It previously mirrored the
+// twin-divergence audit script's NEVER_TWINNED tuple; that script was deleted when
+// E42_S07 retired the twin-parity gate, so both this comment and the cross-check in
+// tests/load-nl-catalog-twin-resolution.bats were repointed at the surviving list.)
 const NEVER_TWINNED = new Set(["jenga", "jenga-permission-level", "index"]);
 
 function canonicalSkillDir(name) {