@jenga-ai/agent 3.0.0 → 3.1.1

package/scripts/verify-postinstall-reconcile.sh

@@ -0,0 +1,392 @@
+#!/usr/bin/env bash
+#
+# verify-postinstall-reconcile.sh — fixture rehearsal for E26_S08_T01
+#
+# Rehearses the manifest-based delete reconciliation in scripts/postinstall.js
+# against a THROWAWAY fixture consumer project, as required by E26_S08's
+# `crucial_level: gated` note ("must be rehearsed against a throwaway fixture
+# consumer directory before being considered done, not just unit-reasoned about").
+#
+# SAFETY: this script creates its own fixture root via `mktemp -d` and writes and
+# deletes ONLY inside it. It takes no path argument and will never operate on an
+# existing directory, so it cannot touch this repo or a real consumer project.
+# Set KEEP_FIXTURE=1 to leave the fixture on disk for inspection.
+#
+# Scenarios covered
+#   A. First install with no prior manifest  -> additive only, pre-existing consumer
+#      files survive, NO delete pass runs.
+#   B. Upgrade across a release that renames / removes / excludes skills -> stale
+#      package files removed from both mirror roots, consumer-authored files survive
+#      (including one planted INSIDE a package directory that is otherwise emptied),
+#      and files common to both versions are left byte- and mtime-identical.
+#
+# Usage:  bash scripts/verify-postinstall-reconcile.sh
+# Exit:   0 = all assertions passed, 1 = at least one failed.
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+FIXTURE="$(mktemp -d "${TMPDIR:-/tmp}/jenga-postinstall-fixture.XXXXXX")"
+
+PASS=0
+FAIL=0
+
+# When RESULTS_FILE is set, every verdict is also appended in a machine-readable
+# `PASS<TAB><name>` / `FAIL<TAB><name>` form, so tests/postinstall-delete-reconciliation.bats
+# can assert on individual named checks instead of on one opaque exit status.
+record() { if [ -n "${RESULTS_FILE:-}" ]; then printf '%s\t%s\n' "$1" "$2" >> "$RESULTS_FILE"; fi; }
+
+pass() { PASS=$((PASS + 1)); record PASS "$1"; printf '  \033[32mPASS\033[0m  %s\n' "$1"; }
+fail() { FAIL=$((FAIL + 1)); record FAIL "$1"; printf '  \033[31mFAIL\033[0m  %s\n' "$1"; }
+
+exists()     { [ -e "$1" ]; }
+assert_file()    { if [ -f "$1" ]; then pass "$2"; else fail "$2 (missing: $1)"; fi; }
+assert_absent()  { if [ ! -e "$1" ]; then pass "$2"; else fail "$2 (still present: $1)"; fi; }
+assert_grep()    { if grep -q "$1" "$2" 2>/dev/null; then pass "$3"; else fail "$3"; fi; }
+assert_nogrep()  { if grep -q "$1" "$2" 2>/dev/null; then fail "$3"; else pass "$3"; fi; }
+# ERE variant — needed where the pattern is a real regex rather than a literal.
+assert_nogrep_re() { if grep -qE "$1" "$2" 2>/dev/null; then fail "$3"; else pass "$3"; fi; }
+
+cleanup() {
+  if [ "${KEEP_FIXTURE:-0}" = "1" ]; then
+    printf '\n  Fixture retained at: %s\n' "$FIXTURE"
+  else
+    # Confined to the mktemp -d created by this script itself.
+    rm -rf "$FIXTURE"
+  fi
+}
+trap cleanup EXIT
+
+# ── build a fake package version ─────────────────────────────────────────────
+# Copies the real lib/, scripts/ and templates/ from this repo (so the code under
+# test is the real code), then lays down a small synthetic skills/ + agents/ tree.
+make_pkg() {
+  local dir="$1" version="$2"
+  mkdir -p "$dir"
+  cp -R "$REPO_ROOT/lib"       "$dir/lib"
+  cp -R "$REPO_ROOT/scripts"   "$dir/scripts"
+  cp -R "$REPO_ROOT/templates" "$dir/templates" 2>/dev/null || true
+  cat > "$dir/package.json" <<JSON
+{ "name": "@jenga-ai/agent", "version": "$version", "type": "module" }
+JSON
+  mkdir -p "$dir/skills" "$dir/agents"
+}
+
+add_skill() {
+  local dir="$1" name="$2" body="$3"
+  mkdir -p "$dir/skills/$name"
+  printf '%s\n' "$body" > "$dir/skills/$name/SKILL.md"
+}
+
+run_install() {
+  local pkg="$1" consumer="$2" log="$3"
+  ( cd "$pkg" && INIT_CWD="$consumer" node scripts/postinstall.js ) > "$log" 2>&1
+}
+
+echo
+echo "══ Jenga postinstall delete-reconciliation rehearsal ══"
+echo "  fixture: $FIXTURE"
+
+# ── package v1.0.0 ───────────────────────────────────────────────────────────
+PKG1="$FIXTURE/pkg-v1"
+make_pkg "$PKG1" "1.0.0"
+add_skill "$PKG1" "do"           "# do — stable across both versions"
+add_skill "$PKG1" "renamed-old"  "# renamed-old — becomes renamed-new in v2"
+add_skill "$PKG1" "j-legacy-twin" "# j-legacy-twin — excluded in v2 (E50_S06 style)"
+printf '# developer agent v1\n' > "$PKG1/agents/developer.md"
+
+# ── package v2.0.0 ───────────────────────────────────────────────────────────
+PKG2="$FIXTURE/pkg-v2"
+make_pkg "$PKG2" "2.0.0"
+add_skill "$PKG2" "do"           "# do — stable across both versions"   # byte-identical
+add_skill "$PKG2" "renamed-new"  "# renamed-new — replaces renamed-old"
+# j-legacy-twin intentionally absent (excluded), renamed-old intentionally absent
+printf '# developer agent v2 (changed)\n' > "$PKG2/agents/developer.md"
+
+CONSUMER="$FIXTURE/consumer"
+mkdir -p "$CONSUMER"
+
+# ═══ Scenario A — first install, no prior manifest ═══════════════════════════
+echo
+echo "── Scenario A: first install (no prior manifest) ──"
+
+# Plant a consumer file BEFORE the very first install. A first install must never
+# delete it, because there is no manifest telling us what we wrote before.
+mkdir -p "$CONSUMER/.agents/skills/preexisting" "$CONSUMER/.claude/skills/preexisting"
+printf '# consumer file that predates any jenga install\n' > "$CONSUMER/.agents/skills/preexisting/JUNK.md"
+printf '# consumer file that predates any jenga install\n' > "$CONSUMER/.claude/skills/preexisting/JUNK.md"
+
+run_install "$PKG1" "$CONSUMER" "$FIXTURE/install-v1.log"
+
+assert_grep "no previous install manifest" "$FIXTURE/install-v1.log" \
+  "first install reports no delete pass"
+assert_nogrep_re "[1-9][0-9]* stale file" "$FIXTURE/install-v1.log" \
+  "first install deletes nothing (zero stale files reported)"
+assert_file "$CONSUMER/.agents/skills/preexisting/JUNK.md" \
+  "pre-existing consumer file survives first install (.agents)"
+assert_file "$CONSUMER/.claude/skills/preexisting/JUNK.md" \
+  "pre-existing consumer file survives first install (.claude)"
+assert_file "$CONSUMER/.agents/skills/renamed-old/SKILL.md" \
+  "v1 skill mirrored to .agents"
+assert_file "$CONSUMER/.claude/skills/renamed-old/SKILL.md" \
+  "v1 skill mirrored to .claude"
+assert_file "$CONSUMER/.agents/.jenga-postinstall-manifest.json" \
+  "manifest written to .agents on first install"
+assert_file "$CONSUMER/.claude/.jenga-postinstall-manifest.json" \
+  "manifest written to .claude on first install"
+assert_nogrep "preexisting/JUNK.md" "$CONSUMER/.agents/.jenga-postinstall-manifest.json" \
+  "consumer file is NOT recorded in the manifest"
+assert_grep "skills/do/SKILL.md" "$CONSUMER/.agents/.jenga-postinstall-manifest.json" \
+  "manifest records mirrored package paths"
+
+# ═══ Scenario B — upgrade with renames / removals / exclusions ════════════════
+echo
+echo "── Scenario B: upgrade 1.0.0 -> 2.0.0 ──"
+
+# Consumer authors their own custom skill alongside package-owned ones.
+for root in .agents .claude; do
+  mkdir -p "$CONSUMER/$root/skills/my-custom-skill"
+  printf '# my hand-authored skill\n' > "$CONSUMER/$root/skills/my-custom-skill/SKILL.md"
+  # ...and drops a note INSIDE a package directory that v2 removes entirely.
+  printf '# my notes inside a package-owned dir\n' > "$CONSUMER/$root/skills/j-legacy-twin/MY-NOTES.md"
+done
+
+# Record identity of a file common to both versions, to prove it is not needlessly
+# deleted and recopied (mirror() should classify it as `skipped`).
+DO_BEFORE="$(ls -li "$CONSUMER/.agents/skills/do/SKILL.md" | awk '{print $1, $6, $7, $8}')"
+
+run_install "$PKG2" "$CONSUMER" "$FIXTURE/install-v2.log"
+
+echo
+echo "  [upgrade cleanup lines]"
+grep -E "stale file|left in place|no previous" "$FIXTURE/install-v2.log" | sed 's/^/    /'
+echo
+
+# 1. Stale, fully-removed package skill is gone from BOTH roots, dir pruned.
+assert_absent "$CONSUMER/.agents/skills/renamed-old" \
+  "renamed-away skill dir removed from .agents"
+assert_absent "$CONSUMER/.claude/skills/renamed-old" \
+  "renamed-away skill dir removed from .claude"
+
+# 2. Excluded twin's package file is gone, but the consumer's note in the same dir
+#    survives — so the directory itself must NOT be pruned.
+assert_absent "$CONSUMER/.agents/skills/j-legacy-twin/SKILL.md" \
+  "excluded twin's package file removed (.agents)"
+assert_absent "$CONSUMER/.claude/skills/j-legacy-twin/SKILL.md" \
+  "excluded twin's package file removed (.claude)"
+assert_file "$CONSUMER/.agents/skills/j-legacy-twin/MY-NOTES.md" \
+  "consumer note INSIDE the emptied package dir survives (.agents)"
+assert_file "$CONSUMER/.claude/skills/j-legacy-twin/MY-NOTES.md" \
+  "consumer note INSIDE the emptied package dir survives (.claude)"
+
+# 3. Consumer's own custom skill is untouched.
+assert_file "$CONSUMER/.agents/skills/my-custom-skill/SKILL.md" \
+  "consumer custom skill survives upgrade (.agents)"
+assert_file "$CONSUMER/.claude/skills/my-custom-skill/SKILL.md" \
+  "consumer custom skill survives upgrade (.claude)"
+assert_file "$CONSUMER/.agents/skills/preexisting/JUNK.md" \
+  "pre-manifest consumer file still survives upgrade (.agents)"
+assert_file "$CONSUMER/.claude/skills/preexisting/JUNK.md" \
+  "pre-manifest consumer file still survives upgrade (.claude)"
+
+# 4. New skill arrived.
+assert_file "$CONSUMER/.agents/skills/renamed-new/SKILL.md" \
+  "renamed-to skill installed (.agents)"
+assert_file "$CONSUMER/.claude/skills/renamed-new/SKILL.md" \
+  "renamed-to skill installed (.claude)"
+
+# 5. Unchanged common file was neither deleted nor recopied.
+DO_AFTER="$(ls -li "$CONSUMER/.agents/skills/do/SKILL.md" | awk '{print $1, $6, $7, $8}')"
+if [ "$DO_BEFORE" = "$DO_AFTER" ]; then
+  pass "file common to both versions untouched (same inode+mtime)"
+else
+  fail "file common to both versions was rewritten ($DO_BEFORE -> $DO_AFTER)"
+fi
+
+# 6. Changed common file was overwritten.
+assert_grep "v2 (changed)" "$CONSUMER/.agents/agents/developer.md" \
+  "changed package file overwritten with v2 content"
+
+# 7. Manifest refreshed.
+assert_nogrep "renamed-old" "$CONSUMER/.agents/.jenga-postinstall-manifest.json" \
+  "refreshed manifest no longer lists the removed skill"
+assert_grep "renamed-new" "$CONSUMER/.agents/.jenga-postinstall-manifest.json" \
+  "refreshed manifest lists the new skill"
+assert_nogrep "my-custom-skill" "$CONSUMER/.agents/.jenga-postinstall-manifest.json" \
+  "refreshed manifest never records consumer-authored files"
+
+# ═══ Scenario C — idempotent re-run of the same version ══════════════════════
+echo
+echo "── Scenario C: re-run same version (version gate) ──"
+run_install "$PKG2" "$CONSUMER" "$FIXTURE/install-v2-again.log"
+assert_grep "Nothing to do" "$FIXTURE/install-v2-again.log" \
+  "same-version re-run short-circuits before any delete pass"
+assert_file "$CONSUMER/.agents/skills/my-custom-skill/SKILL.md" \
+  "consumer custom skill still present after re-run"
+assert_file "$CONSUMER/.agents/skills/renamed-new/SKILL.md" \
+  "package skill still present after re-run"
+
+# ═══ Scenario D — adversarial / corrupt manifests ════════════════════════════
+# Exercises the guards directly: a manifest is data on the consumer's disk, so a
+# tampered or corrupted one must never turn into an out-of-bounds or wrong-type
+# delete. Uses a fresh consumer so it cannot disturb the scenarios above.
+echo
+echo "── Scenario D: adversarial + corrupt manifests ──"
+
+CONSUMER_D="$FIXTURE/consumer-d"
+mkdir -p "$CONSUMER_D"
+run_install "$PKG1" "$CONSUMER_D" "$FIXTURE/d-install-v1.log"
+
+# A file OUTSIDE the mirror roots that a traversal entry would try to reach.
+printf 'precious\n' > "$CONSUMER_D/OUTSIDE-THE-MIRROR.txt"
+# A symlink planted at a path the manifest will claim as ours.
+mkdir -p "$CONSUMER_D/.agents/skills/trap"
+ln -sf "$CONSUMER_D/OUTSIDE-THE-MIRROR.txt" "$CONSUMER_D/.agents/skills/trap/LINK.md"
+# A directory planted where the manifest claims a file.
+mkdir -p "$CONSUMER_D/.agents/skills/trap/DIR.md"
+
+# Hand-craft a hostile manifest: traversal escape, symlink, directory, plus a real
+# stale file that SHOULD still be cleaned up (proves the guards are selective, not
+# a blanket bail-out).
+python3 - "$CONSUMER_D" <<'PYEOF'
+import json, sys, os
+root = sys.argv[1]
+m = os.path.join(root, ".agents", ".jenga-postinstall-manifest.json")
+d = json.load(open(m))
+d["paths"] = [
+    "../OUTSIDE-THE-MIRROR.txt",   # traversal escape  -> must be refused
+    "skills/trap/LINK.md",          # symlink           -> must be refused
+    "skills/trap/DIR.md",           # directory         -> must be refused
+    "skills/renamed-old/SKILL.md",  # genuinely stale   -> must be deleted
+]
+json.dump(d, open(m, "w"), indent=2)
+PYEOF
+
+run_install "$PKG2" "$CONSUMER_D" "$FIXTURE/d-install-v2.log"
+
+echo
+echo "  [guard lines]"
+grep -E "left in place|stale file" "$FIXTURE/d-install-v2.log" | sed 's/^/    /'
+echo
+
+assert_file "$CONSUMER_D/OUTSIDE-THE-MIRROR.txt" \
+  "traversal entry cannot delete a file outside the mirror root"
+assert_grep "outside-dest-root" "$FIXTURE/d-install-v2.log" \
+  "traversal entry explicitly refused"
+if [ -L "$CONSUMER_D/.agents/skills/trap/LINK.md" ]; then
+  pass "symlink entry refused, not followed or unlinked"
+else
+  fail "symlink entry was removed"
+fi
+assert_grep "not-a-regular-file" "$FIXTURE/d-install-v2.log" \
+  "non-regular-file entries explicitly refused"
+if [ -d "$CONSUMER_D/.agents/skills/trap/DIR.md" ]; then
+  pass "directory entry refused (manifests record files only)"
+else
+  fail "directory entry was removed"
+fi
+assert_absent "$CONSUMER_D/.agents/skills/renamed-old/SKILL.md" \
+  "genuinely stale entry still cleaned up alongside refusals"
+
+# Corrupt manifest must disable the delete pass entirely, not guess.
+CONSUMER_E="$FIXTURE/consumer-e"
+mkdir -p "$CONSUMER_E"
+run_install "$PKG1" "$CONSUMER_E" "$FIXTURE/e-install-v1.log"
+printf '{ this is not valid json' > "$CONSUMER_E/.agents/.jenga-postinstall-manifest.json"
+printf '{"manifest_version": 99, "paths": ["skills/renamed-old/SKILL.md"]}' \
+  > "$CONSUMER_E/.claude/.jenga-postinstall-manifest.json"
+run_install "$PKG2" "$CONSUMER_E" "$FIXTURE/e-install-v2.log"
+
+assert_file "$CONSUMER_E/.agents/skills/renamed-old/SKILL.md" \
+  "corrupt manifest disables the delete pass (.agents)"
+assert_file "$CONSUMER_E/.claude/skills/renamed-old/SKILL.md" \
+  "unknown manifest_version disables the delete pass (.claude)"
+assert_grep "no previous install manifest" "$FIXTURE/e-install-v2.log" \
+  "unreadable manifest degrades to additive-only"
+assert_grep "manifest_version" "$CONSUMER_E/.agents/.jenga-postinstall-manifest.json" \
+  "a fresh valid manifest is rewritten over the corrupt one"
+
+# ═══ Scenario E — case-only rename on a case-insensitive filesystem ══════════
+# Regression cover for tester finding 1 (E26_S08_T01 rapport). Staleness is decided
+# by a case-SENSITIVE string set, but unlinks happen on a filesystem that may be
+# case-INSENSITIVE (macOS APFS, Windows NTFS). After skill.md -> SKILL.md the old
+# manifest string looks stale, yet it resolves to the file this run just wrote --
+# so a string-only diff deletes the new file and the skill vanishes entirely.
+echo
+echo "── Scenario E: case-only rename (finding 1) ──"
+
+PKG1C="$FIXTURE/pkg-v1-case"
+PKG2C="$FIXTURE/pkg-v2-case"
+make_pkg "$PKG1C" "1.0.0"
+make_pkg "$PKG2C" "2.0.0"
+mkdir -p "$PKG1C/skills/alpha" "$PKG2C/skills/alpha"
+printf '# alpha\n' > "$PKG1C/skills/alpha/skill.md"   # lowercase in v1
+printf '# alpha\n' > "$PKG2C/skills/alpha/SKILL.md"   # UPPERCASE in v2
+
+CONSUMER_C="$FIXTURE/consumer-case"
+mkdir -p "$CONSUMER_C"
+run_install "$PKG1C" "$CONSUMER_C" "$FIXTURE/case-v1.log"
+run_install "$PKG2C" "$CONSUMER_C" "$FIXTURE/case-v2.log"
+
+# Detect whether this filesystem is even case-insensitive; on a case-SENSITIVE fs
+# both names legitimately coexist and the old one is genuinely stale.
+if [ -f "$CONSUMER_C/.agents/skills/alpha/skill.md" ] && \
+   [ -f "$CONSUMER_C/.agents/skills/alpha/SKILL.md" ] && \
+   [ "$(cat "$CONSUMER_C/.agents/skills/alpha/skill.md" 2>/dev/null)" != "$(cat "$CONSUMER_C/.agents/skills/alpha/SKILL.md" 2>/dev/null)" ]; then
+  CASE_INSENSITIVE=0
+else
+  CASE_INSENSITIVE=1
+fi
+
+if [ "$CASE_INSENSITIVE" -eq 1 ]; then
+  # The whole point: the skill must still exist under SOME name after the upgrade.
+  if [ -f "$CONSUMER_C/.agents/skills/alpha/SKILL.md" ] || [ -f "$CONSUMER_C/.agents/skills/alpha/skill.md" ]; then
+    pass "case-only rename does not delete the just-written file (.agents)"
+  else
+    fail "case-only rename deleted the skill entirely (.agents)"
+  fi
+  if [ -f "$CONSUMER_C/.claude/skills/alpha/SKILL.md" ] || [ -f "$CONSUMER_C/.claude/skills/alpha/skill.md" ]; then
+    pass "case-only rename does not delete the just-written file (.claude)"
+  else
+    fail "case-only rename deleted the skill entirely (.claude)"
+  fi
+  assert_grep "written-this-run" "$FIXTURE/case-v2.log" \
+    "identity guard reports the spared entry as written-this-run"
+else
+  pass "case-only rename (skipped: filesystem is case-sensitive)"
+  pass "case-only rename (skipped: filesystem is case-sensitive) (.claude)"
+  pass "identity guard reports the spared entry as written-this-run (n/a on case-sensitive fs)"
+fi
+
+# ═══ Scenario F — copySet entry missing from the package ═════════════════════
+# Regression cover for tester finding 2. mirror() silently skips a missing source,
+# so currentPaths under-reports and the delete pass would read the whole mirrored
+# subtree as stale -- converting a bad publish into mass deletion on every consumer.
+echo
+echo "── Scenario F: packaging regression (finding 2) ──"
+
+PKG2M="$FIXTURE/pkg-v2-missing"
+make_pkg "$PKG2M" "2.0.0"
+printf '# developer agent v2\n' > "$PKG2M/agents/developer.md"
+rm -rf "$PKG2M/skills"          # simulate skills/ omitted from the published package
+
+CONSUMER_M="$FIXTURE/consumer-missing"
+mkdir -p "$CONSUMER_M"
+run_install "$PKG1" "$CONSUMER_M" "$FIXTURE/missing-v1.log"
+run_install "$PKG2M" "$CONSUMER_M" "$FIXTURE/missing-v2.log"
+
+assert_file "$CONSUMER_M/.agents/skills/do/SKILL.md" \
+  "missing copySet entry does not wipe the mirrored subtree (.agents)"
+assert_file "$CONSUMER_M/.claude/skills/do/SKILL.md" \
+  "missing copySet entry does not wipe the mirrored subtree (.claude)"
+assert_grep "Upgrade cleanup skipped" "$FIXTURE/missing-v2.log" \
+  "packaging regression reported, cleanup skipped"
+assert_grep "skills/renamed-old/SKILL.md" "$CONSUMER_M/.agents/.jenga-postinstall-manifest.json" \
+  "previous manifest left intact (still describes what is on disk)"
+
+echo
+echo "══════════════════════════════════════════════════════"
+printf '  Result: %d passed, %d failed\n' "$PASS" "$FAIL"
+echo "══════════════════════════════════════════════════════"
+echo
+[ "$FAIL" -eq 0 ]

package/skills/j-uncharted/scripts/elicitation-state.sh

@@ -151,7 +151,21 @@ if [ -z "$REPO_ROOT" ]; then
   exit 2
 fi
 
-WITH_LOCK="$REPO_ROOT/scripts/with-lock.sh"
+# ─── Resolve with-lock.sh's package root ──────────────────────────────────
+# postinstall.js mirrors only skills/ and agents/ into a consumer's .claude/
+# and .agents/ — scripts/ (which owns with-lock.sh) is never copied there, so
+# this script — itself shipped under skills/j-uncharted/scripts/ and mirrored
+# alongside it — cannot assume "$REPO_ROOT/scripts/with-lock.sh" exists.
+# Mirrors skills/init/scripts/init.sh's PKG_ROOT fallback: prefer a monorepo
+# checkout's sibling scripts/ dir, else fall back to the installed npm
+# package under node_modules/@jenga-ai/agent.
+if [ -f "$SCRIPT_DIR/../../../scripts/with-lock.sh" ]; then
+  WITH_LOCK="$SCRIPT_DIR/../../../scripts/with-lock.sh"
+elif [ -f "$REPO_ROOT/node_modules/@jenga-ai/agent/scripts/with-lock.sh" ]; then
+  WITH_LOCK="$REPO_ROOT/node_modules/@jenga-ai/agent/scripts/with-lock.sh"
+else
+  WITH_LOCK="$REPO_ROOT/scripts/with-lock.sh"
+fi
 STATE_DIR="$REPO_ROOT/project/queue/elicitation-state"
 DEFAULT_CAP=5
 

package/skills/jenga/SKILL.md

@@ -132,13 +132,15 @@ If all applicable rules pass (or the task is a legacy task), proceed to the next
 
 ### Phase 0.75 — Entry Mode Resolution
 
-This phase determines **how `/jenga` was invoked** and, for two of the three entry modes, produces a **scoped set** — a confirmed list of board IDs (epics/stories/tasks) that Phases 1-4 must restrict themselves to. All board scanning, ID parsing, cascade expansion, and rendering used by this phase already live in `skills/jenga/scripts/` per this repo's "Scripts Over Inline Logic" principle — this phase never re-implements any of that logic inline. The executing agent's job here is limited to: invoking the right script with the right arguments, relaying its STDOUT verbatim to the user when the contract calls for that, capturing the `STATE_FILE:` line from STDERR for the next turn, and forwarding the user's raw reply back into the next invocation unmodified.
+This phase determines **how `/jenga` was invoked** and, for two of the four entry modes, produces a **scoped set** — a confirmed list of board IDs (epics/stories/tasks) that Phases 1-4 must restrict themselves to. All board scanning, ID parsing, cascade expansion, and rendering used by this phase already live in `skills/jenga/scripts/` per this repo's "Scripts Over Inline Logic" principle — this phase never re-implements any of that logic inline. The executing agent's job here is limited to: invoking the right script with the right arguments, relaying its STDOUT verbatim to the user when the contract calls for that, capturing the `STATE_FILE:` line from STDERR for the next turn, and forwarding the user's raw reply back into the next invocation unmodified.
 
 **Determine the invocation form** from the raw argument (if any) passed to `/jenga`:
 
 - No argument at all → **bare branch**.
 - The argument is the literal string `*` → **wildcard branch**.
-- Any other non-empty argument → **scoped branch** (treat the whole argument as the comma-separated raw ID list).
+- Any other non-empty argument → invoke `skills/jenga/scripts/detect-nl-intent.sh "<raw argument>"` (E53_S01_T01) and branch on its `classification` field:
+  - `all_resolved` or `mixed` → **scoped branch** (below) — this is the same branch as before; only its internal mechanics changed (see below).
+  - `nl_intent` → **natural-language branch** (below) — new for E53_S01, no new sigil or entry point, purely a new outcome of this same argument-shape detection.
 
 #### Wildcard branch (`/jenga *`)
 
@@ -154,10 +156,35 @@ Skip both the picker and the confirmation step entirely. There is no scoped set
 
 #### Scoped branch (`/jenga <ids>`)
 
-1. Invoke `skills/jenga/scripts/resolve-id.sh "<raw argument>"` directly — the picker is skipped entirely in this branch.
-2. Parse the JSON array response, one object per comma-delimited input segment.
-   - If **every** segment has `status: "resolved"`, collect their `resolved_id` values into a comma-separated list and continue to the shared confirmation step below.
-   - If **any** segment has `status: "rejected"`, halt this phase (do not proceed to confirmation or Phase 1) and report each rejected segment's `input` and `reason` to the user verbatim, per `resolve-id.sh`'s own contract — a partial or ambiguous ID is never guessed. The user must re-invoke `/jenga <ids>` with corrected input.
+This branch is entered when `detect-nl-intent.sh` (invoked above) classifies the argument as `all_resolved` or `mixed` — the picker is skipped entirely in this branch. `detect-nl-intent.sh` has already invoked `resolve-id.sh` internally and reduced its per-segment output to one of these two shapes; `skills/jenga/SKILL.md` never parses `resolve-id.sh`'s raw array itself (see `detect-nl-intent.sh`'s own header comment for the full classification contract, E53_S01_T01).
+
+1. On `all_resolved`, take the `resolved_ids` (or `resolved_ids_csv`) field directly from `detect-nl-intent.sh`'s output and continue to the shared confirmation step below.
+2. On `mixed`, halt this phase (do not proceed to confirmation or Phase 1) and report each entry in `detect-nl-intent.sh`'s `rejected` array — its `input` and `reason` — to the user verbatim; a partial or ambiguous ID is never guessed. The user must re-invoke `/jenga <ids>` with corrected input.
+
+#### Natural-language branch (`/jenga <free-form text>`)
+
+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:
+   - `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.
+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. **Render and confirm the chain** — invoke `skills/jenga/scripts/render-playbook-confirmation.sh "<playbook_id>" "<name>" "<comma-separated steps>"` (start mode, using `match-playbook.sh`'s `playbook_id`/`name`/`steps` fields verbatim). Relay STDOUT (the numbered chain + instructions) to the user verbatim. Capture the `STATE_FILE:` path from STDERR.
+   b. Wait for the user's chat reply, then invoke `skills/jenga/scripts/render-playbook-confirmation.sh <state_file> "<raw_reply>"` (continue mode).
+      - **Toggle or error turn** (plain text on STDOUT, state file retained) — relay verbatim and return to step 5b for another reply. This loops exactly as the existing bare/scoped confirmation flow's own toggle/error turns already do.
+      - **Cancellation** — relay the cancellation acknowledgement and halt the entire `/jenga` invocation immediately, with no step executed — identical posture to the existing picker/confirmation cancellation edge cases already documented for the bare/scoped branches (see "## Edge Cases" below).
+      - **Confirmed** (JSON object on STDOUT, state file removed) — take the confirmed `steps` array (checked-only, in original playbook order) and continue to step 5c.
+   c. **Initialize the sequential runner** — invoke `skills/jenga/scripts/run-playbook-step.sh init "<playbook_id>" "<name>" "<comma-separated confirmed steps>"`. Its `step_ready` result names the first step to invoke.
+   d. **Execute steps in a loop** — for the step named by the runner's most recent `step_ready` result:
+      i. Invoke that 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.
+      ii. After that step's execution concludes, call `skills/jenga/scripts/run-playbook-step.sh advance <state_file> passed` (the step completed successfully) or `... advance <state_file> failed "<short failure note>"` (the step failed).
+      iii. On a `step_ready` result, repeat step 5d for the newly-named step.
+      iv. On a `complete` result, report the full list of completed steps to the user and stop — the playbook run is finished; do not continue into this `/jenga` invocation's Phase 1.
+      v. On a `halted` result, **immediately stop executing any further steps** — no silent skip-ahead. Report `failed_step`, `failed_note`, `completed` (steps that already finished), 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.
 
 #### Shared confirmation step (bare and scoped branches only)
 
@@ -255,6 +282,11 @@ When no eligible candidates remain in Phase 4, exit and output:
 - **Bundle `/do` call failure** — treated as a skip for the entire bundle; mark all bundled tasks' status back to `Pending` and continue Phase 4 with remaining non-bundled candidates.
 - **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.
-- **`resolve-id.sh` rejects one or more segments (scoped branch)** — the whole invocation halts at Phase 0.75 with the rejected segments' reasons reported verbatim; 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 `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.)
+- **`match-playbook.sh` returns `playbook_match` and the user confirms the full chain, and every step succeeds** — the Natural-language branch's step 5d reports the full `completed` steps list 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 5b)** — 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 5d(v) 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, which step failed (with its note), and which steps never ran.
 - **`/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.

package/skills/jenga/playbooks/brainstorm-to-mirror.json

@@ -0,0 +1,22 @@
+{
+  "id": "brainstorm-to-mirror",
+  "name": "Idea to Public Release",
+  "description": "Takes a rough idea all the way from planning through implementation, committing, and a public mirror release -- the canonical end-to-end Jenga workflow chain.",
+  "keywords": [
+    "idea to release",
+    "plan and ship",
+    "idea to done",
+    "full workflow",
+    "end to end",
+    "plan build ship",
+    "idea to production"
+  ],
+  "examples": [
+    "I have an idea, help me plan it, build it, and ship it",
+    "take this feature from idea to committed and published",
+    "let's go from a rough idea all the way to a public release",
+    "plan this out, implement it, commit it, and push it to the public mirror",
+    "walk this through the whole pipeline from brainstorm to release"
+  ],
+  "steps": ["brainstorm", "todo", "do", "dev-done", "mirror-public"]
+}

package/skills/jenga/playbooks/schema.json

@@ -0,0 +1,42 @@
+{
+  "$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/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.",
+  "type": "object",
+  "required": ["id", "name", "description", "keywords", "examples", "steps"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Stable, unique, kebab-case identifier for this playbook (e.g. \"brainstorm-to-mirror\"). Must equal the filename's basename without the .json extension -- load-playbooks.sh validates this so a playbook's id can never silently drift from its file location.",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "name": {
+      "type": "string",
+      "description": "Short human-readable display name shown to the user in the confirmation prompt and in routing/report output, e.g. \"Idea to Public Release\"."
+    },
+    "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/route/SKILL.md's Step 2 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/route/SKILL.md's Step 2 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/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.",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "steps": {
+      "type": "array",
+      "description": "Ordered list of bare skill names (the directory name under skills/<name>/SKILL.md, e.g. \"brainstorm\", not \"j.brainstorm\" or \"/brainstorm\") that make up this playbook's chain, in the exact execution order. Each entry MUST resolve to an existing skills/<name>/SKILL.md at load time -- load-playbooks.sh skips (with a stderr warning) any playbook referencing a nonexistent skill rather than silently including a broken chain in the catalog.",
+      "items": { "type": "string" },
+      "minItems": 2
+    }
+  }
+}