@jenga-ai/agent 3.1.0 → 3.2.0

package/skills/jenga/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: j.jenga
 description: Interactive-by-default board orchestrator with a fully automated escape hatch. Bare `/jenga` renders a picker and confirmation tree before scoping the run; `/jenga <ids>` resolves an explicit fuzzy-ID scope and confirms it; `/jenga *` reproduces the original zero-prompt behavior — decomposing any unbroken Epics into Stories, any unbroken Stories into Tasks, queuing all unqueued Tasks into todo.md, then executing every eligible item with no user prompts — until the board is fully started.
+output_types:
+  - when: detect-nl-intent
+    type: id_list
 keywords:
   - jenga
   - orchestrate
@@ -96,7 +99,7 @@ Do not proceed with this task.
 
 #### Rule 4 — crucial_level: locked forces execution_scope: inline
 
-If the task frontmatter contains `crucial_level: locked` (per `templates/SCRUM_BOARD_SCHEMA.md`'s Crucial Flag Fields), `execution_scope` for that task MUST be `inline` — only the current foreground/inline session can pause mid-run for a live confirmation; a backgrounded subagent has no live channel back to the user.
+If the task frontmatter contains `crucial_level: locked` (per `$([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)`'s Crucial Flag Fields), `execution_scope` for that task MUST be `inline` — only the current foreground/inline session can pause mid-run for a live confirmation; a backgrounded subagent has no live channel back to the user.
 
 This rule **auto-corrects and continues**; unlike Rules 1-3, it never halts.
 
@@ -132,13 +135,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 +159,61 @@ 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. **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
+      flattened string list) for any StepObject carrying a `conditional: {"depends_on": "<name>",
+      "predicate": "..."}` field. Build a JSON object mapping each such step's name to its
+      `depends_on` step's name only (e.g. `{"stepC": "stepA"}` — the confirmation display needs no
+      predicate detail, only which step to point at). If no step carries a `conditional`, this
+      object is empty/omitted.
+      **Also resolve composition origin metadata** (`E53_S05_T01`/`T03`) — inspect the SAME
+      `steps` array (`match-playbook.sh`'s `steps` field is already load-playbooks.sh's fully
+      FLATTENED, composition-resolved catalog output — composition is invisible to
+      `match-playbook.sh` itself; there is nothing further to "flatten" at this point, only to
+      read) for any StepObject carrying `_origin_playbook`/`_origin_depth` (present only on steps
+      whose `_origin_depth` is greater than 1 — see `load-playbooks.sh`'s header "COMPOSITION
+      RESOLUTION"). Build a JSON object mapping each such step's name to `{"playbook_id":
+      "<_origin_playbook>", "depth": <_origin_depth>}`. If no step in this playbook came from a
+      composed/nested playbook, this object is empty/omitted.
+   b. **Render and confirm the chain** — invoke `skills/jenga/scripts/render-playbook-confirmation.sh "<playbook_id>" "<name>" "<comma-separated steps>" ["<json-conditionals from 5a>" ["<json-origins from 5a>"]]` (start mode, using `match-playbook.sh`'s `playbook_id`/`name`/`steps` fields verbatim; the 4th argument is omitted entirely when 5a produced no conditionals, and the 5th argument is omitted entirely when 5a produced no composition-origin metadata — omitting both reproduces the exact pre-`E53_S04` 3-arg call, and omitting only the 5th reproduces the exact pre-`E53_S05` 4-arg call). Relay STDOUT (the numbered chain + instructions, now marking any conditional step with "(may be skipped depending on step N's result)" and any composed/nested step with indentation plus "(from playbook: <id>, depth N)") to the user verbatim. Capture the `STATE_FILE:` path from STDERR.
+   c. 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 5c 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 5d.
+   d. **Initialize the sequential runner** — re-derive the `<json-conditionals>` object for `run-playbook-step.sh init` from the same StepObject data as 5a, but in `init`'s own richer shape (`{"<step>": {"depends_on": "...", "predicate": "..."}}`, `E53_S04_T02`), and apply one filtering rule first: **drop any conditional whose `depends_on` step is not present in the CONFIRMED step list from 5c.** The user may have unchecked the depended-on step at confirmation; `init` would otherwise reject such a conditional outright (its existence check requires `depends_on` to be an earlier step in the run), and the more sensible fallback than a hard failure over the user's own edit is to treat that now-conditionless step as always-running for this particular execution. **Also re-derive the composition origin metadata** (`E53_S05_T04`) for `init`'s optional 5th argument, from the same `_origin_playbook`/`_origin_depth` data as 5a, filtered the same way (drop any entry for a step the user unchecked at confirmation — `init` requires every key to be present in the confirmed step list). Invoke `skills/jenga/scripts/run-playbook-step.sh init "<playbook_id>" "<name>" "<comma-separated confirmed steps>" ["<json-conditionals, filtered>" ["<json-origins, filtered>"]]` (the 4th argument is omitted when empty, and the 5th is omitted when empty — omitting both reproduces the exact pre-`E53_S04` 3-arg call, and omitting only the 5th reproduces the exact pre-`E53_S05` 4-arg call). Its `step_ready` result names the first step to invoke.
+   e. **Execute steps in a loop** — for the step named by the runner's most recent `step_ready` result:
+      i. **Evaluate whether this step should run** (`E53_S04_T02`) — invoke `skills/jenga/scripts/run-playbook-step.sh should-skip <state_file>`.
+         - `{"skip": true, ...}` — do **not** invoke the step. Call `skills/jenga/scripts/run-playbook-step.sh advance <state_file> skipped` directly (never `passed`/`failed` for a step that never ran), then handle its result exactly as iv-vi below (`step_ready`/`complete`/`halted`) — skip step 5e-ii and 5e-iii entirely for this step, since it never runs. This is non-blocking and non-failing — it never halts the chain, and is not narrated to the user turn-by-turn (it is folded into the final `completed`/`skipped` summary reported at `complete`/`halted`, the same posture already given to individual `passed` steps, which also aren't separately narrated mid-chain).
+         - `{"skip": false, ...}` — proceed to step 5e-ii and invoke the step normally.
+      ii. **Resolve `forward_from` and `resolve`, if the step declares either** (`E53_S03`, runtime-wired by `E53_S04_T02`; `resolve` runtime behavior added by `E53_S06_T01`) — invoke `skills/jenga/scripts/run-playbook-step.sh get-output <state_file> <named source step>` before invoking this step. On `{"status": "found", "value": "..."}`, use that value as this step's actual invocation input (per the design's forwarding semantics). On `{"status": "unavailable", "reason": "step_skipped"}` or `"reason": "not_captured"` — the named source produced no usable value (it was itself skipped, or never captured one) — do not guess a fallback value; treat this exactly like a step failure: call `advance <state_file> failed "forward_from source '<name>' unavailable (<reason>)"` and follow the `halted` handling in 5e-vi below, without ever invoking this step. This is the documented, non-silent failure mode for a `forward_from` naming a skipped step (`E53_S04_T06`'s fixture coverage).
+
+         **Then, if the step also declares a non-empty `resolve` field** (`E53_S06_T01`) — this is a documented, named, scoped exception to `CLAUDE.md`'s "Skill Implementation Principle — Scripts Over Inline Logic": open-ended reshaping/filtering/type-bridging genuinely needs the agent's own LLM judgment, which a deterministic script cannot provide, and `resolve` is never used for anything else in this codebase's playbook mechanism — in particular, never to pre-authorize a downstream confirmation, a combination `load-playbooks.sh` already rejects outright at load time (see `docs/skill-authoring.md`'s "The `resolve` / confirmation-gate rule"):
+         - **No-op without `forward_from`** — a step carrying `resolve` but no `forward_from` (or one that resolved to no forwardable value) has nothing to reshape. This is a defined, non-crashing runtime behavior, not an error: the `resolve` field is simply ignored for that step, and invocation proceeds exactly as it would with no `resolve` field at all.
+         - **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.
+      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.
 
 #### Shared confirmation step (bare and scoped branches only)
 
@@ -208,7 +264,7 @@ For each in-scope story that has one or more tasks listed in `todo.md`:
 2. **Guard: empty task list** — if the `tasks:` list is empty (zero entries), this story is **not** eligible for the bundle path. Skip to per-task dispatch in Phase 4.
 3. **Read each task file** — for every task ID in the `tasks:` list, read the corresponding task file from `project/board/tasks/`.
 4. **Collect `execution_scope`** — extract the `execution_scope` field from each task's YAML frontmatter. If the field is absent or has any value other than `story`, treat that task as **not** story-scoped.
-5. **Guard: locked-task disqualifier (defense-in-depth)** — for each task file already read in step 3, also read `crucial_level` (per `templates/SCRUM_BOARD_SCHEMA.md`'s Crucial Flag Fields). If **any** task in the story's `tasks:` list has `crucial_level: locked`, this story is **not** eligible for the bundle path — skip to per-task dispatch in Phase 4 for this story, **regardless of that task's `execution_scope` value**, even if it already reads `inline`. This check is defense-in-depth alongside Phase 0.5's Rule 4 (which forces a locked task's own `execution_scope` to `inline` when Rule 4 processes it): it exists for the race window where Rule 4 hasn't (yet) corrected the task — e.g. the task was added to the story's `tasks:` list after Rule 4 last ran, or the file was edited by hand after validation. It is not a replacement for Rule 4.
+5. **Guard: locked-task disqualifier (defense-in-depth)** — for each task file already read in step 3, also read `crucial_level` (per `$([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)`'s Crucial Flag Fields). If **any** task in the story's `tasks:` list has `crucial_level: locked`, this story is **not** eligible for the bundle path — skip to per-task dispatch in Phase 4 for this story, **regardless of that task's `execution_scope` value**, even if it already reads `inline`. This check is defense-in-depth alongside Phase 0.5's Rule 4 (which forces a locked task's own `execution_scope` to `inline` when Rule 4 processes it): it exists for the race window where Rule 4 hasn't (yet) corrected the task — e.g. the task was added to the story's `tasks:` list after Rule 4 last ran, or the file was edited by hand after validation. It is not a replacement for Rule 4.
 6. **Apply the all-or-nothing rule** — a story qualifies for the bundle path **only if every task** in its `tasks:` list has `execution_scope: story`. A single task with a different scope (or a missing field) disqualifies the entire story.
 7. **Route bundle candidates** — if all tasks in the story are `execution_scope: story` and the list is non-empty:
    a. Emit:
@@ -255,6 +311,21 @@ 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 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.
+- **A step's conditional predicate evaluates false (`E53_S04_T02`)** — the Natural-language branch's step 5e(i) never invokes that step at all; it calls `advance <state_file> skipped` directly, the step is recorded under the run's `skipped` list (never `completed`, never `failed`), and the chain continues to the next step exactly as it would after a `passed` step — a skipped step never halts the chain and is not narrated to the user as a separate turn, only reflected in the final `completed`/`skipped` summary (or the `halted` report's `skipped` field, if a later step fails).
+- **A `skipped` step is later named by a `forward_from`** — the Natural-language branch's step 5e(ii) calls `get-output` for the named source before invoking the dependent step; a skipped source returns `{"status": "unavailable", "reason": "step_skipped"}`. This is the documented, non-silent failure mode (`E53_S04_T06`'s fixture coverage): the calling agent does NOT guess a fallback value or silently forward an empty string — it calls `advance <state_file> failed "forward_from source '<name>' unavailable (<reason>)"` and the chain halts with a `halted` report naming the dependent step as `failed_step`, exactly as any other step failure would.
+- **A `resolve` step carries no `forward_from` (`E53_S06_T01`)** — the Natural-language branch's step 5e(ii) treats this as a defined no-op: there is no forwarded value to reshape, so the `resolve` field is simply ignored and the step is invoked normally with whatever input it would otherwise have received. This is never surfaced to the user as an error or a warning.
+- **A `resolve` step's transform cannot cleanly produce a usable result (`E53_S06_T01`)** — the Natural-language branch's step 5e(ii) never invokes the target step and never guesses or passes through a differently-shaped value; it calls `advance <state_file> failed "<note>"` with a note that includes the raw pre-transform value, and the chain halts exactly as any other step failure would (5e-vi) — no silent skip-ahead, no fallback value.
+- **A playbook step carries a `conditional`, shown at confirmation (`E53_S04_T04`)** — the Natural-language branch's step 5b relays `render-playbook-confirmation.sh`'s rendered chain, which visibly marks that step's line with "(may be skipped depending on step N's result)" — confirming a chain with a conditional step never hides its real conditional structure from the user, even though checking/unchecking that step still works exactly like any other step (the marker is display-only; the actual runtime skip decision belongs entirely to `should-skip`, independent of what the user checks or unchecks here).
+- **The user unchecks, at confirmation, the specific step a later step's conditional depends on** — the Natural-language branch's step 5d drops that conditional before calling `init` (its `depends_on` step is no longer in the confirmed list, and `init` would otherwise reject the conditional outright as naming a nonexistent earlier step). The dependent step becomes unconditional for this run and always executes — a deliberate, documented fallback rather than a hard failure over the user's own edit.
+- **A playbook contains a cyclic `{"playbook": "<id>"}` reference (`E53_S05_T01`)** — rejected entirely at `load-playbooks.sh` load time, before `/jenga` ever runs: the whole cyclic playbook is dropped from the catalog with a stderr warning naming the cycle. It is never surfaced as a `match-playbook.sh` candidate at all (a dropped playbook simply doesn't exist in the catalog `match-playbook.sh` matches against) — there is no runtime-visible error for this case, only a load-time one a human reviewing stderr output would see.
+- **A playbook's composition nests deeper than the configured `max_composition_depth` (`E53_S05_T01`, default 3)** — same posture as the cyclic-reference case above: dropped at `load-playbooks.sh` load time with a stderr warning, never surfaced as a `match-playbook.sh` candidate, no runtime-visible error.
+- **A `forward_from` crosses a composition boundary (`E53_S05_T02`)** — transparent in both directions with no special handling required anywhere in this SKILL.md: `load-playbooks.sh`'s composition resolution runs before its `forward_from`/`conditional` validation, so by the time a playbook reaches `match-playbook.sh`'s catalog, its `steps` array is already fully flattened — a step from a composed/nested playbook forwarding from (or being forwarded into by) a step outside it behaves exactly like any other `forward_from` relationship in step 5e(ii); the Natural-language branch never needs to know or care which originating playbook a step came from.
+- **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.

package/skills/jenga/playbooks/idea-to-committed.json

@@ -0,0 +1,20 @@
+{
+  "id": "idea-to-committed",
+  "name": "Idea to Committed",
+  "description": "Takes a rough idea through planning, board capture, implementation, and a commit -- the end-to-end Jenga workflow chain, stopping at the commit rather than at a release.",
+  "keywords": [
+    "idea to commit",
+    "plan build commit",
+    "brainstorm to commit",
+    "capture and implement",
+    "start to commit"
+  ],
+  "examples": [
+    "I have an idea, help me plan it, build it, and commit it",
+    "take this feature from a rough idea through to a commit",
+    "plan this out, put it on the board, implement it, and commit the work",
+    "walk this through planning, implementation, and committing",
+    "help me think this through, break it down, build it, and commit"
+  ],
+  "steps": ["j-brainstorm", "j-todo", "j-do", "j-commit"]
+}

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 canonical skill DIRECTORY names (the directory under skills/<dir>/SKILL.md, e.g. \"j-brainstorm\", not the \"j.brainstorm\" frontmatter/invocation form and not the retired bare \"brainstorm\") that make up this playbook's chain, in the exact execution order. Per E50_S10's canonical naming contract the canonical directory is skills/j-<name>/, so a step value carries the j- prefix; the three permanent exceptions (jenga, jenga-permission-level, index) keep their bare directory names and are written bare. Each entry MUST resolve to an existing skills/<dir>/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
+    }
+  }
+}

package/skills/jenga/scripts/detect-nl-intent.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/jenga/scripts/detect-nl-intent.sh
+#
+# Deterministic classification wrapper around `resolve-id.sh` for `/jenga`'s
+# Phase 0.75 entry-mode resolution (E53_S01). Phase 0.75's scoped branch used
+# to call `resolve-id.sh` directly and halt the whole invocation the moment
+# ANY comma-delimited segment was rejected by the ID grammar. E53_S01 adds a
+# new outcome: when EVERY segment is rejected, the raw argument is not a
+# malformed ID list at all — it's natural-language intent, which should be
+# routed to /jenga's new NL branch (wired up in E53_S01_T03) instead of
+# halting.
+#
+# This script performs exactly that classification and nothing else. Per
+# CLAUDE.md's "Skill Implementation Principle — Scripts Over Inline Logic",
+# `skills/jenga/SKILL.md` never parses `resolve-id.sh`'s raw JSON array
+# itself for this decision — it only ever reads this script's three output
+# shapes below.
+#
+# ---------------------------------------------------------------------------
+# USAGE
+# ---------------------------------------------------------------------------
+#   skills/jenga/scripts/detect-nl-intent.sh "<raw Phase 0.75 argument>"
+#
+# The argument is passed through verbatim to `resolve-id.sh` — this script
+# does not itself split, clean, or reinterpret it. See `resolve-id.sh`'s own
+# header for the exact ID grammar and its per-segment output schema.
+#
+# ---------------------------------------------------------------------------
+# CLASSIFICATION CONTRACT (stable — E53_S01_T03 wires against this exactly)
+# ---------------------------------------------------------------------------
+# `resolve-id.sh`'s JSON array (one object per comma-delimited segment) is
+# reduced to exactly ONE of three classifications, based on the distinct set
+# of `status` values across all segments:
+#
+#   1. every segment "resolved"  -> "all_resolved"
+#   2. every segment "rejected"  -> "nl_intent"
+#   3. a mix of both             -> "mixed"
+#
+# stdout is always a single JSON object. Nothing else is ever written to
+# stdout — errors and warnings go to stderr only.
+#
+#   "all_resolved":
+#     {
+#       "classification":   "all_resolved",
+#       "resolved_ids":     ["E01_S02", ...],
+#       "resolved_ids_csv": "E01_S02,..."
+#     }
+#     exit 0 — the existing scoped-branch confirmation flow in
+#     `skills/jenga/SKILL.md` is unaffected by this script's introduction.
+#
+#   "nl_intent":
+#     {
+#       "classification": "nl_intent",
+#       "raw_argument":   "<the original $1, verbatim>"
+#     }
+#     exit 0 — this is the signal E53_S01_T03's new branch uses to enter
+#     natural-language matching instead of halting.
+#
+#   "mixed":
+#     {
+#       "classification": "mixed",
+#       "rejected": [
+#         {"input": "<raw segment>", "reason": "<human-readable reason>"},
+#         ...
+#       ]
+#     }
+#     exit 1 — preserves the exact current halt-and-report behavior already
+#     documented in `skills/jenga/SKILL.md`'s "`resolve-id.sh` rejects one or
+#     more segments" edge case. No partial scope is ever assembled from the
+#     segments that did resolve.
+#
+# ---------------------------------------------------------------------------
+# EXIT CODES
+# ---------------------------------------------------------------------------
+#   0   "all_resolved" or "nl_intent" classification (see above)
+#   1   "mixed" classification (see above)
+#   2   usage error (no argument given) or a `resolve-id.sh` / `board-scan.sh`
+#       setup failure — a real setup problem, not a classification outcome.
+#       `resolve-id.sh`'s own stderr message (already emitted by it) is what
+#       explains the failure; this script does not re-emit a second message
+#       on top of it.
+#
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+RESOLVE_ID="$SCRIPT_DIR/resolve-id.sh"
+
+if [ $# -lt 1 ] || [ -z "${1:-}" ]; then
+  echo 'Usage: detect-nl-intent.sh "<raw Phase 0.75 argument>"' >&2
+  exit 2
+fi
+
+RAW_INPUT="$1"
+
+if [ ! -x "$RESOLVE_ID" ]; then
+  echo "Error: resolve-id.sh not found or not executable at $RESOLVE_ID" >&2
+  exit 2
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "Error: python3 is required by detect-nl-intent.sh" >&2
+  exit 2
+fi
+
+# resolve-id.sh exits 0 (all resolved) or 1 (at least one rejected) as
+# legitimate per-segment outcomes — only exit 2 (usage/setup failure) is a
+# real problem here. Guard the capture explicitly so `set -e` doesn't abort
+# this script on resolve-id.sh's own exit 1.
+set +e
+RESOLVE_JSON="$("$RESOLVE_ID" "$RAW_INPUT")"
+RESOLVE_EXIT=$?
+set -e
+
+if [ "$RESOLVE_EXIT" -eq 2 ]; then
+  # resolve-id.sh already wrote a plain-text error to stderr — just
+  # propagate its exit code rather than re-deriving a second message.
+  exit 2
+fi
+
+PY_SCRIPT="$(mktemp -t detect-nl-intent-XXXXXX.py)"
+trap 'rm -f "$PY_SCRIPT"' EXIT
+
+cat > "$PY_SCRIPT" <<'PY'
+import json
+import sys
+
+raw_argument = sys.argv[1]
+resolve_json = sys.stdin.read()
+
+try:
+    segments = json.loads(resolve_json)
+except Exception as e:
+    print(f"Error: could not parse resolve-id.sh output as JSON: {e}", file=sys.stderr)
+    sys.exit(2)
+
+if not isinstance(segments, list) or len(segments) == 0:
+    # resolve-id.sh only emits [] for an empty/whitespace-only argument,
+    # which should never reach this script — Phase 0.75 routes an empty
+    # argument to the bare branch before detect-nl-intent.sh is ever
+    # invoked. Treat this as a setup problem rather than silently guessing
+    # a classification for input this script was never meant to see.
+    print("Error: resolve-id.sh produced an empty or non-array result", file=sys.stderr)
+    sys.exit(2)
+
+statuses = {seg.get("status") for seg in segments}
+
+if statuses == {"resolved"}:
+    resolved_ids = [seg["resolved_id"] for seg in segments]
+    print(json.dumps({
+        "classification": "all_resolved",
+        "resolved_ids": resolved_ids,
+        "resolved_ids_csv": ",".join(resolved_ids),
+    }))
+    sys.exit(0)
+
+if statuses == {"rejected"}:
+    print(json.dumps({
+        "classification": "nl_intent",
+        "raw_argument": raw_argument,
+    }))
+    sys.exit(0)
+
+rejected = [
+    {"input": seg.get("input"), "reason": seg.get("reason")}
+    for seg in segments
+    if seg.get("status") == "rejected"
+]
+print(json.dumps({
+    "classification": "mixed",
+    "rejected": rejected,
+}))
+sys.exit(1)
+PY
+
+python3 "$PY_SCRIPT" "$RAW_INPUT" <<< "$RESOLVE_JSON"
+exit $?

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

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * skills/jenga/scripts/load-nl-catalog.js
+ *
+ * Node (ESM) helper behind `load-nl-catalog.sh` — the SINGLE REQUIRED SOURCE of skill-catalog
+ * data for `/jenga`'s natural-language branch (E53_S01_T03). `skills/jenga/SKILL.md` must never
+ * re-implement its own skill directory scan or hand-maintain a skill list; it only ever reads
+ * this script's stdout.
+ *
+ * The catalog's NAME LIST comes exclusively from `lib/generate-skill-allow-list.js`'s generated
+ * inventory (`readSkillAllowList()`, which reads the committed `lib/skill-allow-list.json`
+ * artifact) — this script does not independently re-scan `skills/` for a name list of its own,
+ * per E53_S01_T02's acceptance criteria and the drift lesson E41_S04 already documented for that
+ * generator. For each name in that inventory, this script reads exactly one file —
+ * `skills/<name>/SKILL.md` — to populate the remaining catalog fields: `description`, `keywords`,
+ * `examples`, and `metadata.prefered_agent`. These are the same fields `/route`'s Step 1
+ * ("Discover Available Skills") collects.
+ *
+ * ---------------------------------------------------------------------------
+ * USAGE
+ * ---------------------------------------------------------------------------
+ *   node load-nl-catalog.js <projectRoot> <pkgRoot>
+ *
+ *   <projectRoot>  the consuming project's root (passed through to
+ *                  readSkillAllowList's projectRoot fallback candidate)
+ *   <pkgRoot>      the jenga-agent PACKAGE root — where lib/generate-skill-allow-list.js and the
+ *                  canonical skills/ tree actually live (monorepo checkout root, or
+ *                  node_modules/@jenga-ai/agent for an installed consumer)
+ *
+ * ---------------------------------------------------------------------------
+ * OUTPUT SCHEMA
+ * ---------------------------------------------------------------------------
+ * stdout is a single JSON array, one object per catalog entry, e.g.:
+ *
+ *   [
+ *     {
+ *       "name":           "btw",
+ *       "description":    "...",
+ *       "keywords":       ["..."],
+ *       "examples":       ["..."],
+ *       "prefered_agent": "scrum-master"   // or null when absent
+ *     },
+ *     ...
+ *   ]
+ *
+ * Nothing but this JSON array is ever written to stdout. Warnings (a skill skipped because its
+ * SKILL.md is missing/unreadable, or its frontmatter lacks `description`) go to stderr only, and
+ * are non-fatal.
+ *
+ * ---------------------------------------------------------------------------
+ * EXIT CODES
+ * ---------------------------------------------------------------------------
+ *   0   catalog written to stdout (possibly with skip warnings already emitted to stderr)
+ *   2   usage error, or a real setup failure (allow-list inventory unreadable/empty, or
+ *       lib/generate-skill-allow-list.js failed to load)
+ *
+ * ---------------------------------------------------------------------------
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { pathToFileURL } from "url";
+
+/**
+ * Parses YAML frontmatter from a SKILL.md's content into a plain object. This is a hand-rolled,
+ * intentionally minimal parser scoped to the small set of shapes SKILL.md frontmatter actually
+ * uses — it follows the same overall approach as mcp/router/skill-index.js's `parseFrontmatter`
+ * (scalar keys, and array keys introduced by an empty `key:` line followed by `  - item` lines),
+ * extended here to also recognize ONE level of nested mapping (the `metadata:` block, e.g.
+ * `metadata:\n  prefered_agent: developer`) — a shape skill-index.js's parser doesn't need to
+ * handle, since it never reads `metadata`.
+ *
+ * Returns {} if no frontmatter block is found.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+
+  const lines = match[1].split("\n");
+  const obj = {};
+  let i = 0;
+
+  const stripQuotes = (s) => s.trim().replace(/^["']|["']$/g, "");
+
+  while (i < lines.length) {
+    const topMatch = lines[i].match(/^(\w+):\s*(.*)$/);
+    if (!topMatch) {
+      i++;
+      continue;
+    }
+    const [, key, valRaw] = topMatch;
+    const val = valRaw.trim();
+
+    if (val === "[]") {
+      obj[key] = [];
+      i++;
+      continue;
+    }
+
+    if (val !== "") {
+      obj[key] = stripQuotes(val);
+      i++;
+      continue;
+    }
+
+    // Empty value — look ahead at indented child lines to decide whether this key is an array
+    // (child lines shaped `  - item`) or a nested map (child lines shaped `  childKey: value`).
+    // A block is only ever consistently one or the other in this repo's frontmatter, so the
+    // first child line's shape decides it.
+    let j = i + 1;
+    const arrayItems = [];
+    const mapObj = {};
+    let sawArray = false;
+    let sawMap = false;
+
+    while (j < lines.length && /^\s+\S/.test(lines[j])) {
+      const arrItem = lines[j].match(/^\s+-\s+(.*)$/);
+      const mapItem = lines[j].match(/^\s+(\w+):\s*(.*)$/);
+      if (arrItem && !sawMap) {
+        sawArray = true;
+        arrayItems.push(stripQuotes(arrItem[1]));
+      } else if (mapItem && !sawArray) {
+        sawMap = true;
+        mapObj[mapItem[1]] = stripQuotes(mapItem[2]);
+      }
+      j++;
+    }
+
+    obj[key] = sawArray ? arrayItems : sawMap ? mapObj : [];
+    i = j;
+  }
+
+  return obj;
+}
+
+async function main() {
+  const [projectRoot, pkgRoot] = process.argv.slice(2);
+  if (!projectRoot || !pkgRoot) {
+    process.stderr.write("Usage: load-nl-catalog.js <projectRoot> <pkgRoot>\n");
+    process.exit(2);
+  }
+
+  const generatorPath = join(pkgRoot, "lib", "generate-skill-allow-list.js");
+  let readSkillAllowList;
+  try {
+    ({ readSkillAllowList } = await import(pathToFileURL(generatorPath).href));
+  } catch (e) {
+    process.stderr.write(`Error: failed to load ${generatorPath}: ${e.message}\n`);
+    process.exit(2);
+    return;
+  }
+
+  const names = readSkillAllowList(projectRoot, pkgRoot);
+  if (!Array.isArray(names) || names.length === 0) {
+    process.stderr.write(
+      "Error: skill allow-list inventory is empty or unreadable (lib/skill-allow-list.json) — cannot build NL catalog\n"
+    );
+    process.exit(2);
+    return;
+  }
+
+  const catalog = [];
+  for (const name of names) {
+    const skillMdPath = join(pkgRoot, "skills", name, "SKILL.md");
+    if (!existsSync(skillMdPath)) {
+      process.stderr.write(
+        `Warning: ${skillMdPath} not found for allow-listed skill '${name}' — skipped\n`
+      );
+      continue;
+    }
+
+    let content;
+    try {
+      content = readFileSync(skillMdPath, "utf8");
+    } catch (e) {
+      process.stderr.write(`Warning: failed to read ${skillMdPath}: ${e.message} — skipped\n`);
+      continue;
+    }
+
+    const fm = parseFrontmatter(content);
+    if (!fm.description) {
+      process.stderr.write(
+        `Warning: ${skillMdPath} missing 'description' in frontmatter — skipped\n`
+      );
+      continue;
+    }
+
+    catalog.push({
+      name,
+      description: fm.description,
+      keywords: Array.isArray(fm.keywords) ? fm.keywords : [],
+      examples: Array.isArray(fm.examples) ? fm.examples : [],
+      prefered_agent:
+        fm.metadata && typeof fm.metadata === "object" && fm.metadata.prefered_agent
+          ? fm.metadata.prefered_agent
+          : null,
+    });
+  }
+
+  process.stdout.write(JSON.stringify(catalog, null, 2) + "\n");
+}
+
+main().catch((e) => {
+  process.stderr.write(`Error: ${e.message}\n`);
+  process.exit(2);
+});