@jenga-ai/agent 3.1.0 → 3.2.0

package/skills/j-playbook/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: j.playbook
+description: Invoke a specific /jenga playbook directly by ID, skipping natural-language matching entirely and going straight to chain confirmation and execution.
+keywords:
+  - run playbook
+  - invoke playbook by id
+  - playbook direct
+  - execute playbook
+examples:
+  - "j.playbook brainstorm-to-mirror"
+  - "run the understand-then-ship playbook"
+  - "invoke playbook by id"
+---
+
+# Playbook — Direct Playbook Invocation by ID
+
+## Purpose
+
+`/jenga`'s natural-language branch (`skills/jenga/SKILL.md`) proposes a playbook only when
+free-text intent doesn't cleanly resolve to a single skill and `skills/jenga/scripts/match-playbook.sh`
+finds a confident match. That's the right default when the user doesn't know a playbook exists or
+doesn't know its exact id. `j.playbook <id>` is the other case: the user already knows exactly
+which playbook they want and names it directly — this skill skips `detect-nl-intent.sh` and
+`match-playbook.sh` entirely and goes straight to the same confirmation-and-execution machinery
+`/jenga`'s natural-language branch already uses (`E53_S06_T03`, per story `E53_S06`'s fourth and
+fifth Acceptance Criteria).
+
+This skill never re-implements chain confirmation, sequential execution, `forward_from`/`resolve`
+resolution, or composition/conditional handling — all of that is `skills/jenga/SKILL.md`'s
+Natural-language branch steps 5a-5e, reused here by reference. The only genuinely new logic in
+this skill is id resolution (step 1 below).
+
+## Instructions
+
+1. **Resolve the id** — invoke `skills/jenga/scripts/load-playbooks.sh lookup "<id>"`
+   (`E53_S06_T02`), where `<id>` is this skill's argument. Branch on the returned `status` field:
+
+   - **`"not_found"`** — no playbook with that id exists. Tell the user plainly that no such
+     playbook was found. As a "did you mean" nudge, you may additionally invoke
+     `skills/jenga/scripts/load-playbooks.sh` (no arguments, full-catalog mode) and list the
+     available `id`s from its output — use your judgment on whether this is helpful given the
+     specific id the user typed. Halt this invocation; do not proceed to step 2.
+   - **`"invalid"`** — a file for that id exists but failed load-time validation. Report the
+     `reason` field to the user **verbatim** — never a generic "not found" message, since this is
+     a materially different situation from `not_found` (the story's explicit distinguishing
+     requirement, `E53_S06_T02`). Halt this invocation; do not proceed to step 2.
+   - **`"valid"`** — continue to step 2, using the returned `playbook` object's `id`, `name`, and
+     `steps` fields. This object has the exact same field shape as one entry from
+     `load-playbooks.sh`'s full-catalog output — the same shape `match-playbook.sh`'s
+     `playbook_match` result carries `id`/`name`/`steps` in, for `/jenga`'s Natural-language
+     branch step 5.
+
+2. **Confirm and execute the chain** — follow `skills/jenga/SKILL.md`'s Natural-language branch
+   **step 5, sub-steps a through e, verbatim** (conditional/origin metadata resolution; render and
+   confirm the chain via `render-playbook-confirmation.sh`; the reply loop; sequential-runner
+   `init`; the execute-in-a-loop procedure covering skip evaluation, `forward_from`/`resolve`
+   resolution (`E53_S06_T01`), invocation, `advance`, and halt handling) exactly as written there
+   — do not duplicate that prose here. Use the `id`/`name`/`steps` resolved in step 1 above
+   wherever that section refers to `match-playbook.sh`'s `playbook_id`/`name`/`steps` output; every
+   other detail (including how `forward_from`, `resolve`, conditionals, and composed/nested steps
+   are handled) is identical, with no special-casing for this direct-invocation entry point.
+
+   The one framing difference: step 5b's confirmation prompt need not (and should not) present
+   this as a *proposal* the user might not have expected — they named this playbook explicitly by
+   id. Otherwise render, confirm, and execute exactly as that section already does.
+
+3. **On a `complete` or `halted` result** (per step 5e-v/5e-vi), report exactly as that section
+   already specifies. This skill does not continue into any further phase — there is no `/jenga`
+   Phase 1-4 to fall into here, since this is a direct entry point, not `/jenga` itself.
+
+## Edge Cases
+
+- **The looked-up playbook contains a `resolve` step or composed/nested steps** — handled
+  identically to the natural-language path; no special-casing exists or is ever needed here (per
+  story `E53_S06`'s fifth Acceptance Criterion).
+- **The user cancels at the chain confirmation step (step 5c)** — identical posture to
+  `/jenga`'s own playbook-confirmation cancellation: halt immediately after relaying the
+  cancellation acknowledgement, with no step of the chain executed.
+- **`load-playbooks.sh lookup` itself fails unexpectedly (exit code 2, usage/setup error)** — this
+  is an environment/setup problem, not a normal `not_found`/`invalid` result; surface the script's
+  stderr output to the user rather than treating it as either playbook-lookup outcome.

package/skills/j-proceed/SKILL.md

@@ -30,7 +30,7 @@ This file is generated/synced by `scripts/generate-j-alias.sh proceed` from `ski
 
 3. **Determine the next action**:
    - If there are tasks in `Pending` or `In Progress` status that have not yet been assigned to the developer, identify them.
-   - If outstanding tasks are ready for implementation, write a session handoff to `project/queue/handoffs/scrum-master-<session_id>-<task_id>.json` (per-session path — see `templates/SCRUM_BOARD_SCHEMA.md`'s `handoffs/` section; use the first task ID, or `batch` if several) with `"status": "planning_complete"` so that `on_session_end.sh` routes them to the developer queue.
+   - If outstanding tasks are ready for implementation, write a session handoff to `project/queue/handoffs/scrum-master-<session_id>-<task_id>.json` (per-session path — see `$([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)`'s `handoffs/` section; use the first task ID, or `batch` if several) with `"status": "planning_complete"` so that `on_session_end.sh` routes them to the developer queue.
    - If all tasks are complete, check for epic/story rollup and update board statuses accordingly.
 
 4. **Report** a clear summary to the user: what is done, what is in progress, what is next — and which agent will handle it.

package/skills/j-publish/SKILL.md

@@ -261,7 +261,7 @@ Implementation: `bash skills/j-publish/scripts/generate_release_notes.sh [--targ
 
 Release-note rules:
 - The last publish tag is the highest semver tag on the current branch that also has a matching ledger entry in `project/logs/publish-history.json`.
-- **Default target (no `--output`):** the repo-root `CHANGELOG.md` — created from `templates/CHANGELOG_TEMPLATE.md` first if it doesn't exist yet (backward-compat for projects scaffolded before this convention). New Features/Bug Fixes/Other/Completed-task entries since the last publish tag are appended under the existing `## [Unreleased]` heading's subsections; everything else in the file (prior versioned entries, manual edits) is preserved. Entries already present are deduped (matched by commit short-sha or task id), so re-running with no new commits produces zero diff.
+- **Default target (no `--output`):** the repo-root `CHANGELOG.md` — created from `$([ -f templates/CHANGELOG_TEMPLATE.md ] && echo templates/CHANGELOG_TEMPLATE.md || echo node_modules/@jenga-ai/agent/templates/CHANGELOG_TEMPLATE.md)` first if it doesn't exist yet (backward-compat for projects scaffolded before this convention). New Features/Bug Fixes/Other/Completed-task entries since the last publish tag are appended under the existing `## [Unreleased]` heading's subsections; everything else in the file (prior versioned entries, manual edits) is preserved. Entries already present are deduped (matched by commit short-sha or task id), so re-running with no new commits produces zero diff.
 - **`--output <path>`:** writes a standalone, disposable draft to that path instead (the pre-E36 behavior) — `CHANGELOG.md` is not touched in this mode.
 - If no prior ledger-backed tag exists, a `--output` draft includes `> First release — full history included`; the standing `CHANGELOG.md` merge mode has no equivalent banner (it just merges full history into `[Unreleased]` like any other run).
 - Scrum-board enrichment is best-effort only; missing or unreadable board data never fails the command.

package/skills/j-publish/adapters/npm-ci.md

@@ -240,6 +240,35 @@ automated and human halves of the flow:
   `bash skills/j-publish/scripts/npm_stage_inspect.sh approve <stage-id> --otp <otp>`
   from their own machine. `reject` (same script) is available to either
   side to discard a staged candidate.
+- **Stage-id capture reads the CI run's own log, not a local `npm stage
+  list` call.** Because the actual `npm stage publish --provenance` call
+  runs inside the dispatched Actions run, the local `npm_stage_pipeline.sh`
+  process never sees npm's real stage-publish output — `STAGE_OUTPUT` for
+  an `npm-ci` target is only ever the fixed dispatch-summary string ("staged
+  via GitHub Actions workflow run: `<url>`"). Once `gh run watch` reports
+  the run finished successfully, phase 5 instead fetches the full run log
+  via `gh run view <run-id> --repo <github_repo> --log` and parses that
+  text for a `stage id: ...` line (or a JSON payload), using the same
+  parsing logic the `npm` target applies to its local output. **`npm stage
+  list ... --json` (the `npm` target's third fallback attempt) is never
+  invoked for `npm-ci`** — there is no local npm credential for this target
+  type, so a local `npm stage list` call would only ever fail with an
+  unrelated auth error.
+- **Manual recovery when the log can't be parsed.** If no stage id can be
+  parsed from the run log, `npm_stage_pipeline.sh` exits `3`
+  (`EXIT_STAGE_FAILURE`) with a message stating that staging on the
+  registry likely **succeeded** — the workflow run itself exited 0, so the
+  `npm stage publish --provenance` step almost certainly ran — pointing at
+  `gh run view <run-id> --repo <github_repo> --log` (or the printed run
+  URL) to find the id by hand in the `npm stage publish` step output, and
+  printing an already-filled-in recovery command:
+  ```
+  bash skills/j-publish/scripts/write_ledger_entry.sh <target> npm-ci staged "" \
+    --version <version> --config <config> --stage-id <recovered-id> --dist-tag <tag>
+  ```
+  `<target>`, `<version>`, `<config>`, and `<tag>` are the real, already-known
+  values for the run that just happened — only `--stage-id` is left for the
+  operator to fill in by hand after reading it out of the run log.
 
 Same registry-existence precondition as a normal `npm-ci` deploy: staged
 publishing only applies to a package that has already had at least one

package/skills/j-publish/scripts/npm_ci_pipeline.sh

@@ -191,6 +191,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Regenerate lib/legacy-shipped-paths.json (E26_S08_T03)
+        run: node scripts/generate-legacy-shipped-paths.js || echo "::warning::legacy-shipped-paths generation failed; publishing without an updated list"
+
       - name: Publish to npm
         run: npm publish --provenance --access ${NPM_ACCESS} --tag ${DIST_TAG}
 

package/skills/j-publish/scripts/npm_pipeline.sh

@@ -207,6 +207,24 @@ if (( DRY_RUN )); then
   MODE_LABEL="dry-run"
 fi
 
+# Regenerate lib/legacy-shipped-paths.json (E26_S08_T03) — incremental, no-network mode:
+# folds this release's own skills/+agents/ tree into the running cumulative record so the
+# artifact this version SHIPS already reflects what it is about to publish, ready to seed
+# a pre-manifest consumer's first manifest on their NEXT upgrade. Runs on both dry-run and
+# live publish (it only writes a local file, never touches the registry) so a dry-run
+# rehearsal surfaces a generation failure too. Best-effort: a failure here must not block
+# a publish, matching this repo's existing fail-toward-doing-nothing posture for generated
+# artifacts (see lib/generate-skill-allow-list.js's equivalent best-effort call sites).
+GENERATE_LEGACY_PATHS_SCRIPT="$REPO_ROOT/scripts/generate-legacy-shipped-paths.js"
+if [[ -f "$GENERATE_LEGACY_PATHS_SCRIPT" ]]; then
+  log_info "Regenerating lib/legacy-shipped-paths.json (incremental, no network)…"
+  if ! node "$GENERATE_LEGACY_PATHS_SCRIPT"; then
+    log_warn "legacy-shipped-paths generation failed; publishing without an updated list"
+  fi
+else
+  log_warn "scripts/generate-legacy-shipped-paths.js not found; skipping legacy-paths regeneration"
+fi
+
 echo "========== NPM PUBLISH PIPELINE =========="
 printf 'Package:  %s\n' "$PACKAGE_NAME"
 printf 'Version:  %s\n' "$PACKAGE_VERSION"

package/skills/j-publish/scripts/npm_stage_pipeline.sh

@@ -359,6 +359,32 @@ if (( DRY_RUN )); then
   exit 0
 fi
 
+# ---------------------------------------------------------------------------
+# Stage-id parsing helper — shared between the `npm` target's locally
+# captured STAGE_OUTPUT and the `npm-ci` target's fetched CI run log. Tries
+# direct-output regex parsing first, then treats the text as JSON. Echoes
+# the recovered id, or nothing if neither matches.
+# ---------------------------------------------------------------------------
+parse_stage_id_from_text() {
+  local text="$1"
+  local id=""
+
+  # Direct-output parsing. Tolerant of label variants npm may use
+  # ("stage id:", "stageId:", "stage_id="), case-insensitive.
+  id="$(printf '%s\n' "${text}" \
+    | grep -Eio '\bstage[ _-]?id["'"'"']?[[:space:]]*[:=][[:space:]]*["'"'"']?[A-Za-z0-9._-]+' \
+    | head -n 1 \
+    | grep -Eo '[A-Za-z0-9._-]+$' || true)"
+
+  # The text is itself JSON (e.g. if npm's stage publish supports --json the
+  # way `npm publish --json` does, or a fenced JSON blob in a CI log).
+  if [[ -z "${id}" ]] && printf '%s' "${text}" | jq -e . >/dev/null 2>&1; then
+    id="$(printf '%s' "${text}" | jq -r '.id // .stageId // .stage_id // empty' 2>/dev/null || true)"
+  fi
+
+  printf '%s' "${id}"
+}
+
 # ---------------------------------------------------------------------------
 # Phase 5: capture — parse the stage id
 # ---------------------------------------------------------------------------
@@ -366,52 +392,66 @@ log_info "[capture] parsing stage id from stage output..."
 
 STAGE_ID=""
 
-# Attempt 1: direct-output parsing. Tolerant of label variants npm may use
-# ("stage id:", "stageId:", "stage_id="), case-insensitive.
-STAGE_ID="$(printf '%s\n' "${STAGE_OUTPUT}" \
-  | grep -Eio '\bstage[ _-]?id["'"'"']?[[:space:]]*[:=][[:space:]]*["'"'"']?[A-Za-z0-9._-]+' \
-  | head -n 1 \
-  | grep -Eo '[A-Za-z0-9._-]+$' || true)"
-
-# Attempt 2: the captured output is itself JSON (e.g. if npm's stage publish
-# supports --json the way `npm publish --json` does).
-if [[ -z "${STAGE_ID}" ]] && printf '%s' "${STAGE_OUTPUT}" | jq -e . >/dev/null 2>&1; then
-  STAGE_ID="$(printf '%s' "${STAGE_OUTPUT}" | jq -r '.id // .stageId // .stage_id // empty' 2>/dev/null || true)"
-fi
-
-# Attempt 3: fall back to `npm stage list <package> --json` and extract the
-# most recent matching entry's id. `npm stage list` rejects a version-
-# qualified spec ("Version specifiers are not supported for listing staged
-# packages") — it only accepts a bare package name — so this must pass
-# PACKAGE_NAME, never PACKAGE_SPEC; the version match happens client-side via
-# jq below instead (confirmed live on jenga-npm during v1.3.0 staging on
-# 2026-09-01, project/todo.md).
-if [[ -z "${STAGE_ID}" ]]; then
-  log_warn "could not parse a stage id directly from stage output; falling back to 'npm stage list --json'..."
-
-  LIST_STATUS=0
-  LIST_OUTPUT="$(npm stage list "${PACKAGE_NAME}" --json 2>&1)" || LIST_STATUS=$?
-
-  if [[ ${LIST_STATUS} -ne 0 ]]; then
-    printf '%s\n' "${LIST_OUTPUT}" >&2
-    printf 'npm stage pipeline: staged successfully but stage id capture failed (npm stage list also exited %s).\n' "${LIST_STATUS}" >&2
+if [[ "${TARGET_TYPE}" == "npm-ci" ]]; then
+  # STAGE_OUTPUT for npm-ci is the fixed one-line dispatch-summary string set
+  # in Phase 4 above ("staged via GitHub Actions workflow run: <url>") —
+  # never npm's real output — so Attempt 1/2 can never match against it. The
+  # actual `npm stage publish --provenance` output (including whatever
+  # "stage id: ..." line npm prints) lands in the workflow run's own log
+  # instead. Fetch it and apply the same parsing logic used for the `npm`
+  # target's local STAGE_OUTPUT. `npm stage list --json` (Attempt 3) is
+  # never invoked for npm-ci — there is no local npm auth for this target
+  # type, so it would only ever produce a misleading secondary failure.
+  log_info "[capture] fetching CI run log for run ${RUN_ID}..."
+  CI_LOG_OUTPUT="$(gh run view "${RUN_ID}" --repo "${GITHUB_REPO}" --log 2>&1)" || true
+  STAGE_ID="$(parse_stage_id_from_text "${CI_LOG_OUTPUT}")"
+
+  if [[ -z "${STAGE_ID}" ]]; then
+    {
+      printf 'npm stage pipeline: the GitHub Actions workflow run completed successfully, so staging on the registry likely SUCCEEDED — but the stage id could not be parsed from the run log.\n'
+      printf 'Run "gh run view %s --repo %s --log" (or open %s) to find the "stage id: ..." line by hand in the "npm stage publish" step output, then record it manually:\n' "${RUN_ID}" "${GITHUB_REPO}" "${RUN_URL}"
+      printf '  bash skills/j-publish/scripts/write_ledger_entry.sh %s %s staged "" --version %s --config %s --stage-id <recovered-id> --dist-tag %s\n' "${TARGET_NAME}" "${TARGET_TYPE}" "${PACKAGE_VERSION}" "${CONFIG_PATH}" "${DIST_TAG}"
+    } >&2
     exit "${EXIT_STAGE_FAILURE}"
   fi
+else
+  STAGE_ID="$(parse_stage_id_from_text "${STAGE_OUTPUT}")"
+
+  # Attempt 3: fall back to `npm stage list <package> --json` and extract the
+  # most recent matching entry's id. `npm stage list` rejects a version-
+  # qualified spec ("Version specifiers are not supported for listing staged
+  # packages") — it only accepts a bare package name — so this must pass
+  # PACKAGE_NAME, never PACKAGE_SPEC; the version match happens client-side
+  # via jq below instead (confirmed live on jenga-npm during v1.3.0 staging
+  # on 2026-09-01, project/todo.md). `npm` target only — npm-ci never
+  # reaches here (see the branch above).
+  if [[ -z "${STAGE_ID}" ]]; then
+    log_warn "could not parse a stage id directly from stage output; falling back to 'npm stage list --json'..."
+
+    LIST_STATUS=0
+    LIST_OUTPUT="$(npm stage list "${PACKAGE_NAME}" --json 2>&1)" || LIST_STATUS=$?
+
+    if [[ ${LIST_STATUS} -ne 0 ]]; then
+      printf '%s\n' "${LIST_OUTPUT}" >&2
+      printf 'npm stage pipeline: staged successfully but stage id capture failed (npm stage list also exited %s).\n' "${LIST_STATUS}" >&2
+      exit "${EXIT_STAGE_FAILURE}"
+    fi
 
-  if printf '%s' "${LIST_OUTPUT}" | jq -e . >/dev/null 2>&1; then
-    STAGE_ID="$(printf '%s' "${LIST_OUTPUT}" | jq -r --arg pkg "${PACKAGE_NAME}" --arg ver "${PACKAGE_VERSION}" '
-      ( if (type == "array") then . else (.stages? // .items? // []) end ) as $entries
-      | [ $entries[]? | select(((.name // .package // "") == $pkg) and ((.version // "") == $ver)) ]
-      | sort_by(.stagedAt // .staged_at // .created // .createdAt // "")
-      | last
-      | (.id // .stageId // .stage_id // empty)
-    ' 2>/dev/null || true)"
+    if printf '%s' "${LIST_OUTPUT}" | jq -e . >/dev/null 2>&1; then
+      STAGE_ID="$(printf '%s' "${LIST_OUTPUT}" | jq -r --arg pkg "${PACKAGE_NAME}" --arg ver "${PACKAGE_VERSION}" '
+        ( if (type == "array") then . else (.stages? // .items? // []) end ) as $entries
+        | [ $entries[]? | select(((.name // .package // "") == $pkg) and ((.version // "") == $ver)) ]
+        | sort_by(.stagedAt // .staged_at // .created // .createdAt // "")
+        | last
+        | (.id // .stageId // .stage_id // empty)
+      ' 2>/dev/null || true)"
+    fi
   fi
-fi
 
-if [[ -z "${STAGE_ID}" ]]; then
-  printf 'npm stage pipeline: staged successfully but the stage id could not be captured from either the direct output or "npm stage list --json". Run "npm stage list %s --json" manually to recover it (bare package name — a version-qualified spec is rejected by npm).\n' "${PACKAGE_NAME}" >&2
-  exit "${EXIT_STAGE_FAILURE}"
+  if [[ -z "${STAGE_ID}" ]]; then
+    printf 'npm stage pipeline: staged successfully but the stage id could not be captured from either the direct output or "npm stage list --json". Run "npm stage list %s --json" manually to recover it (bare package name — a version-qualified spec is rejected by npm).\n' "${PACKAGE_NAME}" >&2
+    exit "${EXIT_STAGE_FAILURE}"
+  fi
 fi
 
 echo ""

package/skills/j-reconcile/SKILL.md

@@ -3,6 +3,7 @@ name: j.reconcile
 description: Polyfill alias of the reconcile skill under a collision-safe directory name. Identical behavior to /reconcile — Reconcile the scrum board with actual implementation state. Cross-checks every task's board status against git history and worktrees, merges orphaned worktree branches, demotes unimplemented "Done" items, promotes secretly-implemented items, flags code with no board provenance and offers /uncharted segment for it, and cleans stale entries from todo.md. Use when the board feels out of sync, after a big merge session, when tasks were completed outside the normal workflow, or when todo.md has grown stale. Trigger on phrases like "sync the board", "clean up the board", "reconcile", "board is out of date", "todo is stale", or "check what's really done". Use when the bare /reconcile form is shadowed by another tool's own built-in command of the same name.
 metadata:
   prefered_agent: scrum-master
+output_types: text
 keywords:
   - j-reconcile
   - polyfill

package/skills/j-redo/SKILL.md

@@ -45,7 +45,7 @@ If either part is missing, ask the user to provide it before proceeding.
 - Run `git --no-pager show <SHA>` to inspect the full diff.
 
 **Epic / Story number:**
-- Read the matching file under `$(bash scripts/board_resolver.sh)epics/` or `$(bash scripts/board_resolver.sh)stories/` to understand the scope.
+- Read the matching file under `$(bash "$([ -f scripts/board_resolver.sh ] && echo scripts/board_resolver.sh || echo node_modules/@jenga-ai/agent/scripts/board_resolver.sh)")epics/` or `$(bash "$([ -f scripts/board_resolver.sh ] && echo scripts/board_resolver.sh || echo node_modules/@jenga-ai/agent/scripts/board_resolver.sh)")stories/` to understand the scope.
 - Use `git --no-pager log --all --oneline --grep="<epic or story title>"` to locate related commits and their diffs.
 
 Collect the list of **files originally changed** and the **original intent** of the implementation.

package/skills/j-status/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: j.status
 description: Polyfill alias of the status skill under a collision-safe directory name. Identical behavior to /status — Print a human-readable summary of the entire scrum board — all epics, stories, and tasks with their statuses — plus any open rapports and unprocessed queue triggers. Use when you want a quick overview of project state without reading raw files. Use when the bare /status form is shadowed by another tool's own built-in command of the same name.
+output_types: text
 keywords:
   - status
   - board summary
@@ -38,3 +39,14 @@ This file is generated/synced by `scripts/generate-j-alias.sh status` from `skil
 7. **Print the summary** following the layout and icon conventions in `assets/output_format.md`.
 
 8. If no epics exist, print: `No board items found. Run /pi-plan to define epics or /todo to add items.`
+
+## Scope note: playbook step status (E53_S04_T03 audit)
+
+This skill reports board-level status only (steps 2-4 above: epic/story/task `status` from
+`project/board/`). It never reads or reports `/jenga` playbook run state
+(`skills/jenga/scripts/run-playbook-step.sh`'s temp state file, its `step_ready`/`complete`/
+`halted` reports, or per-step `passed`/`failed`/`skipped` outcomes) — a playbook run is ephemeral,
+session-local execution state, not a board item, and has no representation in
+`project/board/`. This is confirmed as intentional, not a gap: `skipped` is scoped strictly to
+playbook-step context and is never written to a task/story's board-level `status` field (see
+`templates/SCRUM_BOARD_SCHEMA.md`'s Status Values table, unmodified by `E53_S04`).

package/skills/j-todo/SKILL.md

@@ -53,7 +53,7 @@ When `--trivial` is present, the mission is written as a **fully-formed task boa
 
 4. **Update project documentation** — Add the mission to the appropriate files under `project/board/epics/` and `project/board/stories/` if applicable.
    - If the mission involves implementing or modifying a skill, apply the **Skill Implementation Principle — Scripts Over Inline Logic** (see `CLAUDE.md` / `AGENTS.md`): note in the story/task's acceptance criteria that deterministic, repeatable steps must be offloaded to scripts under `skills/<name>/scripts/` (or `scripts/`) rather than encoded as inline agent instructions in `SKILL.md`.
-   - If the user indicates the mission is high-risk, or explicitly asks to flag it, set an elevated caution tier directly on the story or task frontmatter: `crucial_level` (one of `advisory`, `gated`, `locked` — see `templates/SCRUM_BOARD_SCHEMA.md` for valid values and their meaning), `crucial_set_by: user`, and `crucial_note` capturing the user's stated reason. This user-initiated flag is written immediately — it does not require the confirm-before-write gate, which applies only to scrum-master-*proposed* caution tiers (a separate, heuristic-driven path).
+   - If the user indicates the mission is high-risk, or explicitly asks to flag it, set an elevated caution tier directly on the story or task frontmatter: `crucial_level` (one of `advisory`, `gated`, `locked` — see `$([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)` for valid values and their meaning), `crucial_set_by: user`, and `crucial_note` capturing the user's stated reason. This user-initiated flag is written immediately — it does not require the confirm-before-write gate, which applies only to scrum-master-*proposed* caution tiers (a separate, heuristic-driven path).
 
 4.5. **If `--trivial` was passed, create the task now** (skip step 5 — this step writes the todo.md entry itself):
 
@@ -81,7 +81,7 @@ When `--trivial` is present, the mission is written as a **fully-formed task boa
 
 5. **Add to `project/todo.md`** by running (skip this step if step 4.5 already ran):
    ```
-   bash scripts/todo_manager.sh add '<mission title>: <Epic no.>_<Story no.>'
+   bash "$([ -f scripts/todo_manager.sh ] && echo scripts/todo_manager.sh || echo node_modules/@jenga-ai/agent/scripts/todo_manager.sh)" add '<mission title>: <Epic no.>_<Story no.>'
    ```
    The epic and story reference is only required if the mission is assigned to one.
 

package/skills/j-uncharted/SKILL.md

@@ -3,6 +3,7 @@ name: j.uncharted
 description: Polyfill alias of the uncharted skill under a collision-safe directory name. Identical behavior to /uncharted — Investigate code that has no Jenga board provenance — a foreign file, an external source being pulled in, or an entire pre-existing codebase — and give it a consistent understanding document plus proper board representation. Use when the bare /uncharted form is shadowed by another tool's own built-in command of the same name.
 metadata:
   prefered_agent: scrum-master
+output_types: text
 keywords:
   - "uncharted"
   - "foreign code"
@@ -117,7 +118,7 @@ Every mode produces exactly one document per target, rendered from `skills/j-unc
 
 **Where it goes:** `project/rapports/analysis/`, named `uncharted-<mode>-<slug>-<YYYYMMDDTHHMMSSZ>.md`. Nothing is ever overwritten — a name collision gets a `-2`, `-3`… suffix, so repeated runs against one target leave a diffable history.
 
-This reuses the **existing `analysis` rapport type** already defined in `templates/SCRUM_BOARD_SCHEMA.md`. `/uncharted` introduces **no new rapport type** — if a change to the rapport taxonomy ever seems necessary, that is a schema change to be raised with the scrum-master, not something this skill invents.
+This reuses the **existing `analysis` rapport type** already defined in `$([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)`. `/uncharted` introduces **no new rapport type** — if a change to the rapport taxonomy ever seems necessary, that is a schema change to be raised with the scrum-master, not something this skill invents.
 
 **Fixed structure** — seven headings, never added to, removed, reordered, or renamed, because downstream steps read the document by heading:
 
@@ -157,7 +158,7 @@ A document whose judgement sections are generic enough to apply to any codebase
 
 Since **E20_S08_T03**, `onboard`'s default behavior and `segment --mode investigate` both run a human-in-the-loop **conversational elicitation** instead of (or, for `onboard`, in addition to keeping available) a one-shot deterministic pass. This section defines the mechanics shared by both; each mode's own subsection below only describes what is specific to it.
 
-**What conversational elicitation produces, and how that differs from the Understanding Document above:** the **primary** output is coarse-tier graph nodes/edges — written directly to `project/knowledge-graph/graph.json`, conforming to the stub schema at `project/knowledge-graph/STUB_SCHEMA.md` (E20_S08_T01; this is a throwaway pilot schema, swapped wholesale once E20_S01's real schema lands — do not extend it expecting stability). Every node this flow writes carries `source: "human"`, since it comes from a person confirming or correcting a proposed understanding, not from mechanical extraction. Board representation is a `[ARCH]`-tagged epic, story, or task at whichever level fits the investigated scope (see `templates/SCRUM_BOARD_SCHEMA.md`'s `[ARCH]` — Durable Architectural Inventory convention) — **not** the delivery-shaped epic/story/task proposal `segment --mode delivery` and legacy `onboard` produce, and not the fixed 7-heading Understanding Document either. A written summary is produced only when warranted, filed as the resulting board item's ordinary `-summary.md` — there is no new artifact type or separate "Understanding Document" for conversational output.
+**What conversational elicitation produces, and how that differs from the Understanding Document above:** the **primary** output is coarse-tier graph nodes/edges — written directly to `project/knowledge-graph/graph.json`, conforming to the stub schema at `project/knowledge-graph/STUB_SCHEMA.md` (E20_S08_T01; this is a throwaway pilot schema, swapped wholesale once E20_S01's real schema lands — do not extend it expecting stability). Every node this flow writes carries `source: "human"`, since it comes from a person confirming or correcting a proposed understanding, not from mechanical extraction. Board representation is a `[ARCH]`-tagged epic, story, or task at whichever level fits the investigated scope (see `$([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)`'s `[ARCH]` — Durable Architectural Inventory convention) — **not** the delivery-shaped epic/story/task proposal `segment --mode delivery` and legacy `onboard` produce, and not the fixed 7-heading Understanding Document either. A written summary is produced only when warranted, filed as the resulting board item's ordinary `-summary.md` — there is no new artifact type or separate "Understanding Document" for conversational output.
 
 ### Human-Oracle-Availability Limitation
 
@@ -252,7 +253,7 @@ A whole-codebase `onboard` conversation, or an investigation of a large director
 
   Idempotent — safe to call again on a resumed `<elicitation-id>` without resetting progress. Choose `<elicitation-id>` so it is stable and re-derivable across sessions (e.g. `onboard-<root-slug>-<date>`, or `segment-investigate-<target-slug>`), since a resuming session must be able to reconstruct it to call `init` again.
 - **`checkpoint` after every converged node and after the Directory Triage confirmation gate** — never only at the end. This is what makes a mid-run pause lossless: `checkpoint --id <id> --json <file>` merges arbitrary progress data (triage results, draft nodes not yet converged, anything else worth surviving a pause) into the state file.
-- **`pause` when a session must end before the elicitation has converged.** Immediately after calling `elicitation-state.sh pause --id <elicitation-id>`, write the scrum-master's own `SessionEnd` handoff (per `templates/SCRUM_BOARD_SCHEMA.md`'s `handoffs/` convention) with `status: "elicitation_paused"` and both `elicitation_id` and `state_file` set — `hooks/on_session_end.sh` routes that into an `elicitation_resume` trigger on `scrum_triggers.jsonl`, which the next scrum-master session's Drain Scrum Triggers Queue procedure picks up (`agents/scrum-master.md`).
+- **`pause` when a session must end before the elicitation has converged.** Immediately after calling `elicitation-state.sh pause --id <elicitation-id>`, write the scrum-master's own `SessionEnd` handoff (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 `handoffs/` convention) with `status: "elicitation_paused"` and both `elicitation_id` and `state_file` set — `hooks/on_session_end.sh` routes that into an `elicitation_resume` trigger on `scrum_triggers.jsonl`, which the next scrum-master session's Drain Scrum Triggers Queue procedure picks up (`agents/scrum-master.md`).
 - **On resume**, read `state_file` directly — every converged node, every flagged node, and the checkpoint data (including the confirmed directory-triage lists) are already there. Do not re-run Directory Triage or re-ask about an already-converged node; resume the Convergence Loop only for nodes still `pending` or explicitly deferred.
 - **`complete` when every candidate has converged, been deferred, or been explicitly accepted past the cap.** The state file is left on disk afterward as an audit trail — nothing currently prunes a completed elicitation's state file.
 
@@ -341,7 +342,7 @@ A new epic is the last option, not the default, and needs a stated reason. Recor
 
 **Step 5 — Draft the proposal** using `skills/j-uncharted/assets/SEGMENT_PROPOSAL_TEMPLATE.md`. Its six headings are fixed; fill every one of them. Two things it will not let you skip:
 
-- **Every proposed task carries `execution_scope` and a non-empty `scope_rationale`** containing a file-count or line-count claim, assigned against `project/configs/scope-thresholds.json` rather than by feel — `inline` at or under 1 file / 20 lines, `story` when tasks share files across the story (up to 5 files), `task` otherwise. Never self-assign `execution_scope: epic`: it requires `epic_scope_approval: true`, which only a human sets. Propose `story` and say the task looks bigger instead. Field semantics live in `templates/SCRUM_BOARD_SCHEMA.md` — read them there, do not paraphrase them here.
+- **Every proposed task carries `execution_scope` and a non-empty `scope_rationale`** containing a file-count or line-count claim, assigned against `project/configs/scope-thresholds.json` rather than by feel — `inline` at or under 1 file / 20 lines, `story` when tasks share files across the story (up to 5 files), `task` otherwise. Never self-assign `execution_scope: epic`: it requires `epic_scope_approval: true`, which only a human sets. Propose `story` and say the task looks bigger instead. Field semantics live in `$([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)` — read them there, do not paraphrase them here.
 - **The document's `Open Questions` carry over verbatim**, not re-derived, each with who can answer it and whether it blocks confirmation. A blocking question is resolved *before* the proposal is accepted, because the breakdown depends on its answer.
 - **Propose everything the board file will contain**, not just titles. Each story's Acceptance Criteria and Definition of Done are proposed at the gate, and a new epic's Purpose and Definition of Done with it — `scripts/validate-story-format.sh` requires those sections, so anything missing here is text `E40_S02_T03` would have to invent after the user has already said yes.
 
@@ -367,7 +368,7 @@ Options 2 and 3 loop back to Step 5 (or to Step 4 for a re-parent) and re-presen
 
 The proposal is the input and the **only** source of content. Everything the board files contain — the epic's Purpose and Definition of Done, each story's `As a …, I want …, so that …` line, Acceptance Criteria, and Definition of Done, each task's `execution_scope` and `scope_rationale` — was proposed at the gate and is transcribed **verbatim**. Nothing is composed, expanded, or improved at write time. If a field looks wrong now, that is a revision (option 2), not an edit in passing: text the user did not read has no business on the board, which is the whole point of the gate.
 
-Shape, field names, and file naming come from `templates/SCRUM_BOARD_SCHEMA.md`. Read them there — do not paraphrase them here. Five things it will not let you skip:
+Shape, field names, and file naming come from `$([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)`. Read them there — do not paraphrase them here. Five things it will not let you skip:
 
 - **Parent before child.** Epic (if new), then stories, then tasks. The schema's Linking Convention makes the epic's `stories[]` and each story's `tasks[]` the authoritative index, so a child written before its parent leaves an index nobody has updated.
 - **IDs continue the sequence they belong to.** `E##` is the next free epic number board-wide, but `S##` is the next free story number **within its parent epic** and `T##` the next free task number **within its parent story** — that is what the `E##_S##_T##` shape means. Story numbers restarting per epic is normal and expected, not a collision. Nothing catches an error here: `validate-board.sh` checks an ID's *shape*, never its uniqueness or its sequence, so a well-formed wrong number passes every gate in Step 7 and quietly reuses an ID that already meant something else.
@@ -387,7 +388,7 @@ It runs `scripts/validate-board.sh` over every file and `scripts/validate-story-
 
 On success, tell the user exactly which files were created, with their IDs.
 
-**Step 8 — Hand off to the standard path.** Queue each new task with the canonical todo owner — `scripts/todo_manager.sh add "<entry>"`, one call per task, referencing the task ID — and the work then proceeds through the ordinary `/todo` → `/do` → developer → tester path, with no special casing anywhere along it. Point the tasks' Description at the understanding document from Step 2; it is the context the developer picking one up would otherwise lack.
+**Step 8 — Hand off to the standard path.** Queue each new task with the canonical todo owner — `` bash "$([ -f scripts/todo_manager.sh ] && echo scripts/todo_manager.sh || echo node_modules/@jenga-ai/agent/scripts/todo_manager.sh)" add "<entry>" ``, one call per task, referencing the task ID — and the work then proceeds through the ordinary `/todo` → `/do` → developer → tester path, with no special casing anywhere along it. Point the tasks' Description at the understanding document from Step 2; it is the context the developer picking one up would otherwise lack.
 
 **`/uncharted` writes board files and stops there.** It does not adapt the segment to project conventions, edit or move the code it just analysed, open a worktree, or write an execution plan. That is ordinary developer work, driven by ordinary task files, and it is the developer agent's job — the same as for a task that came from `/brainstorm` or `/pi-plan`. A segment that has reached the board is no longer a special case, and this skill growing its own integration path would be a second, divergent execution route for work the existing one already handles.
 
@@ -712,7 +713,7 @@ re-running `onboard` with a higher `--cap`.
 Live as of `E40_S04_T04`. `skills/j-uncharted/scripts/write-backfilled-epics.sh` is the only thing
 that actually writes backfilled epics to the board — it consumes `apply-subsystem-cap.sh`'s
 `kept` array and renders one epic file per entry, following the Epic format in
-`templates/SCRUM_BOARD_SCHEMA.md` exactly (`provenance: backfilled`, `status: Pending`, an empty
+`$([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)` exactly (`provenance: backfilled`, `status: Pending`, an empty
 `stories` array, a Purpose section built from the discovery evidence, and a Definition of Done
 framed around understanding and integration, never original construction):
 

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/j-uncharted/scripts/validate-proposed-items.sh

@@ -48,8 +48,24 @@ SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)
 REPO_ROOT=$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || true)
 [ -n "$REPO_ROOT" ] || REPO_ROOT=$(cd -- "$SCRIPT_DIR/../../.." && pwd -P)
 
-BOARD_VALIDATOR="$REPO_ROOT/scripts/validate-board.sh"
-STORY_VALIDATOR="$REPO_ROOT/scripts/validate-story-format.sh"
+# ─── Resolve the validators' package root ─────────────────────────────────
+# postinstall.js mirrors only skills/ and agents/ into a consumer's .claude/
+# and .agents/ — scripts/ (which owns both validators) is never copied there,
+# so this script — itself shipped under skills/j-uncharted/scripts/ and mirrored
+# alongside it — cannot assume "$REPO_ROOT/scripts/..." exists. Mirrors
+# skills/init/scripts/init.sh's PKG_ROOT fallback (same pattern already
+# applied to this skill's elicitation-state.sh WITH_LOCK resolution): 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/validate-board.sh" ]; then
+  VALIDATOR_ROOT="$SCRIPT_DIR/../../../scripts"
+elif [ -f "$REPO_ROOT/node_modules/@jenga-ai/agent/scripts/validate-board.sh" ]; then
+  VALIDATOR_ROOT="$REPO_ROOT/node_modules/@jenga-ai/agent/scripts"
+else
+  VALIDATOR_ROOT="$REPO_ROOT/scripts"
+fi
+BOARD_VALIDATOR="$VALIDATOR_ROOT/validate-board.sh"
+STORY_VALIDATOR="$VALIDATOR_ROOT/validate-story-format.sh"
 
 usage() {
   echo "Usage: $(basename "$0") <board-file> [more-files...]" >&2