@jenga-ai/agent 3.1.1 → 3.4.0

package/skills/j-playbook-new/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: j.playbook-new
+description: Guided wizard that walks you through authoring a new project-local playbook — id, name, description, keywords, examples, and an ordered list of skills — validates every input against the real catalogs, and self-validates the written file before reporting success.
+keywords:
+  - new playbook
+  - create playbook
+  - author playbook
+  - project playbook
+  - custom playbook
+examples:
+  - "I want to create my own playbook"
+  - "help me author a new project-local playbook"
+  - "set up a custom workflow chain for my project"
+  - "j.playbook-new"
+---
+
+# Playbook New — Guided Playbook-Authoring Wizard
+
+## Purpose
+
+`skills/jenga/scripts/load-playbooks.sh` merges two playbook sources into one catalog: the
+framework-owned `skills/jenga/playbooks/` tree, and a project-owned `project/.playbooks/`
+directory (`E53_S09_T01`). This skill is the guided authoring path for the second source — it
+walks the user step by step through the required fields, validates each one against the real,
+live catalogs (never a hand-maintained list of skill names or existing playbook ids), writes
+`project/.playbooks/<id>.json`, and re-validates the just-written file via
+`skills/jenga/scripts/load-playbooks.sh lookup` before ever declaring success. Hand-editing the
+written JSON file remains the escape hatch for anything this wizard doesn't author (see the "v1
+scope cut" note below).
+
+**All deterministic work — slug/uniqueness validation, catalog lookups, and the JSON write
+itself — lives in `skills/j-playbook-new/scripts/playbook-new.sh`** (per `CLAUDE.md`'s "Scripts
+Over Inline Logic" principle). This skill's own job is only to run the conversational loop around
+that script and interpret its JSON results — it never re-implements any validation or catalog
+logic inline.
+
+**v1 scope cut (deliberate, matches `E53_S09`'s story-level scope cut):** this wizard authors
+plain, ordered, bare-string skill-name chains only — no `forward_from`, `resolve`, `conditional`,
+or `playbook`-type (composition) `StepObject` fields. Hand-edit the written file directly if you
+need any of those.
+
+**Scope note — keywords and examples.** The playbook schema
+(`skills/jenga/playbooks/schema.json`) requires every playbook to carry non-empty `keywords` and
+`examples` arrays, exactly like every existing built-in playbook file already does — these are
+what let `/jenga`'s own natural-language matching (`match-playbook.sh`) ever propose this playbook
+from a free-text request. This wizard therefore asks for both, in addition to id/name/description/
+skill-list, so the result is a genuinely useful, matchable playbook rather than one that merely
+parses.
+
+## Instructions
+
+1. **Ask for an id** — a short, stable, kebab-case identifier (e.g. `my-release-flow`). Validate
+   it by running:
+   ```
+   skills/j-playbook-new/scripts/playbook-new.sh validate-id "<id>"
+   ```
+   Parse the single JSON object printed to stdout:
+   - `{"valid": true}` — continue to step 2.
+   - `{"valid": false, "reason": "..."}` — show the `reason` to the user verbatim and re-prompt
+     for a different id. Do not proceed until a validation call returns `valid: true`.
+
+2. **Ask for a `name`** — a short, human-readable display name (e.g. "My Release Flow"), shown to
+   users in confirmation prompts and routing output, mirroring every existing playbook's `name`
+   field. No script validation needed beyond "non-empty" — re-prompt if the user gives an empty
+   answer.
+
+3. **Ask for a `description`** — one sentence explaining what this playbook accomplishes
+   end-to-end. Re-prompt if empty.
+
+4. **Ask for `keywords`** — one or more short phrases (1-3 words each) a user might type that
+   should match this playbook, mirroring every existing playbook's `keywords` field (see
+   `skills/jenga/playbooks/brainstorm-to-mirror.json` for a concrete example of the expected
+   shape and specificity). Accept them one at a time or as a single comma-separated batch —
+   your judgment, whichever the user's response shape suggests. Require at least one.
+
+5. **Ask for `examples`** — one or more natural-language example prompts a user might type that
+   should resolve to this playbook (again, mirror the existing built-in playbooks' style and
+   level of specificity). Require at least one; at least one example should plausibly span the
+   full breadth of the playbook's steps, not just its first one, so it's distinguishable from a
+   single-skill match — use your judgment coaching the user toward this if their first example is
+   too narrow.
+
+6. **Ask for an ordered list of skill names** — one at a time, or as a single ordered batch —
+   your judgment based on how the user responds. For **each** name entered, validate it by
+   running:
+   ```
+   skills/j-playbook-new/scripts/playbook-new.sh validate-skill "<name>"
+   ```
+   Parse the JSON result:
+   - `{"valid": true}` — accept it into the ordered list and continue.
+   - `{"valid": false, "reason": "..."}` — show the `reason` verbatim and re-prompt for that
+     position in the list (do not silently drop it or guess a correction).
+
+   Once the user signals they're done adding skills, require **at least 2** total (a playbook is a
+   chain — a single-skill "playbook" isn't a meaningful use of this mechanism). If fewer than 2
+   were entered, tell the user this and continue prompting for more.
+
+7. **Write the playbook.** Assemble the JSON payload from steps 1-6:
+   ```json
+   {
+     "id": "<id>",
+     "name": "<name>",
+     "description": "<description>",
+     "keywords": ["<keyword 1>", "..."],
+     "examples": ["<example 1>", "..."],
+     "steps": ["<skill 1>", "<skill 2>", "..."]
+   }
+   ```
+   Pipe it to stdin of:
+   ```
+   skills/j-playbook-new/scripts/playbook-new.sh write
+   ```
+   Parse the JSON result:
+   - `{"written": true, "path": "..."}` — continue to step 8.
+   - `{"written": false, "reason": "..."}` — show the `reason` to the user verbatim. This should
+     only happen if something changed between validation and write (e.g. a race, or a shape
+     issue this wizard's own prompts didn't already catch) — do not silently retry; tell the user
+     what failed and, if it's fixable (e.g. the id collided after all), loop back to the relevant
+     earlier step.
+
+8. **Self-validate before declaring success — never skip this step.** Run:
+   ```
+   skills/jenga/scripts/load-playbooks.sh lookup "<id>"
+   ```
+   Branch on the returned `status`:
+   - **`"valid"`** — report success to the user: the playbook was written to
+     `project/.playbooks/<id>.json` and is confirmed loadable. Mention it can now be invoked via
+     `j.playbook <id>` or matched naturally through `j.jenga`.
+   - **`"invalid"`** — report the `reason` field to the user **verbatim** — never a generic
+     failure message. This is a real defect (the write succeeded but load-time validation still
+     rejects it) — do not claim success.
+   - **`"not_found"`** — report to the user that the write appears to have silently failed (the
+     file the wizard just wrote could not be found by the loader) — this would indicate an
+     environment problem (e.g. a different project root being resolved by the two scripts), not a
+     normal outcome. Never claim success.
+
+   Under no circumstances report success to the user without having seen `"status": "valid"` from
+   this exact call.
+
+## Edge Cases
+
+- **The user wants to add `forward_from`/`resolve`/`conditional`/composition to a step.** Tell
+  them this wizard doesn't author those fields (v1 scope cut) and that they can hand-edit
+  `project/.playbooks/<id>.json` afterward — the schema supports these fields identically
+  regardless of which directory a playbook file lives in.
+- **The id collides with a project playbook that already exists on disk but is currently
+  invalid** (e.g. a hand-edited file with a JSON syntax error) — `validate-id` still rejects it (it
+  checks raw file existence, not just catalog membership) rather than silently overwriting a file
+  the user may not realize is broken.
+- **A skill name the user enters exists under multiple forms in the catalog** (e.g. both a bare
+  and a `j-`-prefixed directory, during this repo's ongoing `E50` naming-contract transition) —
+  accept whichever exact form the user typed if `validate-skill` reports it valid; this wizard
+  does not impose a preference between forms the catalog itself doesn't distinguish.
+- **The user cancels mid-wizard** — do not write anything; only step 7 ever touches disk, and only
+  once a complete, locally-validated payload exists.

package/skills/j-playbook-new/scripts/playbook-new.sh

@@ -0,0 +1,332 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/j-playbook-new/scripts/playbook-new.sh
+#
+# Deterministic helper behind the `j.playbook-new` guided wizard (E53_S09_T02). Per CLAUDE.md's
+# "Scripts Over Inline Logic" principle, every mechanical step of the wizard -- id slug/uniqueness
+# validation, skill-name validation against the real catalog, and the JSON write itself -- lives
+# here rather than as inline agent prose in skills/j-playbook-new/SKILL.md. The agent driving the
+# wizard calls this script once per step and interprets its JSON result; it never re-implements
+# any of this logic itself.
+#
+# Reuses, never re-implements, the two existing single-source-of-truth catalogs:
+#   - skills/jenga/scripts/load-playbooks.sh   (merged builtin+project playbook catalog, E53_S09_T01)
+#   - skills/jenga/scripts/load-nl-catalog.sh  (the real, generated skill catalog /jenga's own
+#                                                natural-language matching already uses)
+#
+# ---------------------------------------------------------------------------
+# USAGE
+# ---------------------------------------------------------------------------
+#   playbook-new.sh validate-id <id>
+#
+# Checks <id> is slug-safe (the same pattern skills/jenga/playbooks/schema.json requires:
+# ^[a-z0-9]+(-[a-z0-9]+)*$) and does not collide with any id already present in the merged catalog
+# (skills/jenga/scripts/load-playbooks.sh, no arguments -- built-in and project sources both) OR an
+# existing (possibly currently invalid, and therefore catalog-invisible) file at
+# project/.playbooks/<id>.json. Prints exactly one JSON object to stdout:
+#   {"valid": true}
+#   {"valid": false, "reason": "<human-readable reason>"}
+# Exit 0 for BOTH outcomes -- mirrors load-playbooks.sh's own `lookup` mode convention of
+# reserving a non-zero exit for usage/setup errors only, never for a normal negative validation
+# result the caller is expected to branch on.
+#
+#   playbook-new.sh validate-skill <name>
+#
+# Checks <name> is a real, currently-loadable skill per skills/jenga/scripts/load-nl-catalog.sh's
+# generated catalog -- the exact source /jenga's own natural-language matching already uses, never
+# a hand-maintained list. Prints:
+#   {"valid": true}
+#   {"valid": false, "reason": "..."}
+# Exit 0 for both outcomes, same convention as validate-id.
+#
+#   playbook-new.sh write
+#
+# Reads a single JSON object from stdin:
+#   {"id": "...", "name": "...", "description": "...", "keywords": ["..."],
+#    "examples": ["..."], "steps": ["...", "..."]}
+# Pre-validates it against the same required-field / non-empty-list / steps-shape rules
+# skills/jenga/playbooks/schema.json declares (id slug pattern, all six required fields present,
+# keywords/examples non-empty lists of non-empty strings, steps a list of >= 2 non-empty strings --
+# this wizard authors bare-string steps only, per this task's v1 scope cut) BEFORE writing anything
+# to disk. This is a defensive, redundant pre-check only -- the actual source of truth for validity
+# remains load-playbooks.sh's own load-time validation, which the wizard's own self-validation step
+# (SKILL.md step 8) always runs afterward regardless of this result. Creates project/.playbooks/ if
+# it does not yet exist, and refuses to overwrite an already-existing file for the same id. On
+# success, writes project/.playbooks/<id>.json (pretty-printed) and prints
+# {"written": true, "path": "<absolute path>"}. On any shape/overwrite failure, prints
+# {"written": false, "reason": "..."} and writes nothing. Exit 0 for both outcomes.
+#
+# ---------------------------------------------------------------------------
+# PROJECT ROOT RESOLUTION
+# ---------------------------------------------------------------------------
+# Honors JENGA_PLAYBOOKS_TEST_ROOT -- the SAME override variable load-playbooks.sh itself defines
+# (see that script's header "TESTING OVERRIDE"), not a second, script-specific one -- so a fixture
+# pointing this script at a throwaway project root also makes load-playbooks.sh (invoked internally
+# by validate-id, and by the wizard's own later self-validation step) resolve project/.playbooks/
+# under that same root. Never set this variable in a real invocation.
+#
+# ---------------------------------------------------------------------------
+# EXIT CODES
+# ---------------------------------------------------------------------------
+#   0   a result JSON object was printed to stdout (whether valid:true/false or written:true/false)
+#   2   usage error, or a real setup failure (missing python3, the sibling load-playbooks.sh /
+#       load-nl-catalog.sh scripts could not be located, one of them exited non-zero, or the
+#       project/.playbooks/ directory could not be created)
+#
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LOAD_PLAYBOOKS="$SCRIPT_DIR/../../jenga/scripts/load-playbooks.sh"
+LOAD_NL_CATALOG="$SCRIPT_DIR/../../jenga/scripts/load-nl-catalog.sh"
+
+if [ ! -f "$LOAD_PLAYBOOKS" ]; then
+  echo "Error: could not locate load-playbooks.sh at $LOAD_PLAYBOOKS" >&2
+  exit 2
+fi
+if [ ! -f "$LOAD_NL_CATALOG" ]; then
+  echo "Error: could not locate load-nl-catalog.sh at $LOAD_NL_CATALOG" >&2
+  exit 2
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "Error: python3 is required by playbook-new.sh" >&2
+  exit 2
+fi
+
+if [ -n "${JENGA_PLAYBOOKS_TEST_ROOT:-}" ]; then
+  # Test-only override -- see header "PROJECT ROOT RESOLUTION" above. Never set in a real
+  # invocation.
+  PROJECT_DIR="$JENGA_PLAYBOOKS_TEST_ROOT"
+else
+  PROJECT_DIR="${JENGA_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)}}"
+fi
+PLAYBOOKS_TARGET_DIR="$PROJECT_DIR/project/.playbooks"
+
+if [ $# -lt 1 ]; then
+  echo "Usage: $(basename "$0") <validate-id|validate-skill|write> [args...]" >&2
+  exit 2
+fi
+MODE="$1"
+shift
+
+PY_SCRIPT="$(mktemp -t playbook-new-XXXXXX.py)"
+trap 'rm -f "$PY_SCRIPT"' EXIT
+
+cat > "$PY_SCRIPT" <<'PY'
+import json
+import os
+import re
+import sys
+
+mode = sys.argv[1]
+SLUG_RE = re.compile(r'^[a-z0-9]+(-[a-z0-9]+)*$')
+
+
+def emit(obj):
+    print(json.dumps(obj))
+
+
+if mode == "validate-id":
+    target_id = sys.argv[2]
+    playbooks_target_dir = sys.argv[3]
+
+    if not SLUG_RE.match(target_id):
+        emit({
+            "valid": False,
+            "reason": (
+                f"'{target_id}' is not slug-safe -- must match ^[a-z0-9]+(-[a-z0-9]+)*$ "
+                f"(lowercase letters, digits, single hyphens between segments)"
+            ),
+        })
+        sys.exit(0)
+
+    existing_file = os.path.join(playbooks_target_dir, f"{target_id}.json")
+    if os.path.isfile(existing_file):
+        emit({
+            "valid": False,
+            "reason": (
+                f"a file already exists at {existing_file} -- choose a different id or edit "
+                f"that file directly"
+            ),
+        })
+        sys.exit(0)
+
+    try:
+        catalog = json.load(sys.stdin)
+    except Exception as e:
+        emit({
+            "valid": False,
+            "reason": f"could not read the playbook catalog to check for collisions ({e})",
+        })
+        sys.exit(0)
+
+    for entry in catalog:
+        if entry.get("id") == target_id:
+            src = entry.get("source", "unknown")
+            emit({
+                "valid": False,
+                "reason": (
+                    f"id '{target_id}' collides with an already-loaded {src} playbook (see "
+                    f"skills/jenga/scripts/load-playbooks.sh's merged catalog) -- choose a "
+                    f"different id"
+                ),
+            })
+            sys.exit(0)
+
+    emit({"valid": True})
+    sys.exit(0)
+
+elif mode == "validate-skill":
+    target_name = sys.argv[2]
+
+    try:
+        nl_catalog = json.load(sys.stdin)
+    except Exception as e:
+        emit({"valid": False, "reason": f"could not read the generated skill catalog ({e})"})
+        sys.exit(0)
+
+    for entry in nl_catalog:
+        if entry.get("name") == target_name:
+            emit({"valid": True})
+            sys.exit(0)
+
+    emit({
+        "valid": False,
+        "reason": (
+            f"'{target_name}' is not a recognized skill directory name in the generated skill "
+            f"catalog (skills/jenga/scripts/load-nl-catalog.sh) -- check spelling and the exact "
+            f"directory-name form the catalog currently lists"
+        ),
+    })
+    sys.exit(0)
+
+elif mode == "write":
+    playbooks_target_dir = sys.argv[2]
+
+    try:
+        payload = json.load(sys.stdin)
+    except Exception as e:
+        emit({"written": False, "reason": f"stdin was not valid JSON ({e})"})
+        sys.exit(0)
+
+    if not isinstance(payload, dict):
+        emit({"written": False, "reason": "stdin JSON must be an object"})
+        sys.exit(0)
+
+    required_fields = ["id", "name", "description", "keywords", "examples", "steps"]
+    missing = [f for f in required_fields if f not in payload]
+    if missing:
+        emit({"written": False, "reason": f"missing required field(s) {missing}"})
+        sys.exit(0)
+
+    target_id = payload["id"]
+    if not isinstance(target_id, str) or not SLUG_RE.match(target_id):
+        emit({
+            "written": False,
+            "reason": f"id '{target_id}' is not slug-safe -- must match ^[a-z0-9]+(-[a-z0-9]+)*$",
+        })
+        sys.exit(0)
+
+    for field in ("name", "description"):
+        if not isinstance(payload[field], str) or not payload[field]:
+            emit({"written": False, "reason": f"'{field}' must be a non-empty string"})
+            sys.exit(0)
+
+    for field in ("keywords", "examples"):
+        value = payload[field]
+        if (
+            not isinstance(value, list)
+            or len(value) == 0
+            or not all(isinstance(v, str) and v for v in value)
+        ):
+            emit({
+                "written": False,
+                "reason": f"'{field}' must be a non-empty list of non-empty strings",
+            })
+            sys.exit(0)
+
+    steps = payload["steps"]
+    if not isinstance(steps, list) or len(steps) < 2 or not all(isinstance(s, str) and s for s in steps):
+        emit({
+            "written": False,
+            "reason": (
+                "'steps' must be a list of at least 2 non-empty strings (bare skill-name steps "
+                "only -- this wizard authors no StepObject fields, per this task's v1 scope cut)"
+            ),
+        })
+        sys.exit(0)
+
+    target_file = os.path.join(playbooks_target_dir, f"{target_id}.json")
+    if os.path.isfile(target_file):
+        emit({
+            "written": False,
+            "reason": f"a file already exists at {target_file} -- refusing to overwrite",
+        })
+        sys.exit(0)
+
+    try:
+        os.makedirs(playbooks_target_dir, exist_ok=True)
+    except OSError as e:
+        print(f"Error: could not create {playbooks_target_dir}: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    ordered = {
+        "id": target_id,
+        "name": payload["name"],
+        "description": payload["description"],
+        "keywords": payload["keywords"],
+        "examples": payload["examples"],
+        "steps": steps,
+    }
+
+    try:
+        with open(target_file, "w", encoding="utf-8") as fh:
+            json.dump(ordered, fh, indent=2)
+            fh.write("\n")
+    except OSError as e:
+        print(f"Error: could not write {target_file}: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    emit({"written": True, "path": os.path.abspath(target_file)})
+    sys.exit(0)
+
+else:
+    print(f"Error: unrecognized mode '{mode}' (usage: validate-id|validate-skill|write)", file=sys.stderr)
+    sys.exit(2)
+PY
+
+case "$MODE" in
+  validate-id)
+    if [ $# -lt 1 ] || [ -z "${1:-}" ]; then
+      echo "Usage: $(basename "$0") validate-id <id>" >&2
+      exit 2
+    fi
+    TARGET_ID="$1"
+    if ! CATALOG_JSON="$("$LOAD_PLAYBOOKS")"; then
+      echo "Error: load-playbooks.sh failed while checking id '$TARGET_ID' for collisions" >&2
+      exit 2
+    fi
+    printf '%s' "$CATALOG_JSON" | python3 "$PY_SCRIPT" validate-id "$TARGET_ID" "$PLAYBOOKS_TARGET_DIR"
+    ;;
+  validate-skill)
+    if [ $# -lt 1 ] || [ -z "${1:-}" ]; then
+      echo "Usage: $(basename "$0") validate-skill <name>" >&2
+      exit 2
+    fi
+    TARGET_NAME="$1"
+    if ! NL_CATALOG_JSON="$("$LOAD_NL_CATALOG")"; then
+      echo "Error: load-nl-catalog.sh failed while validating skill name '$TARGET_NAME'" >&2
+      exit 2
+    fi
+    printf '%s' "$NL_CATALOG_JSON" | python3 "$PY_SCRIPT" validate-skill "$TARGET_NAME"
+    ;;
+  write)
+    python3 "$PY_SCRIPT" write "$PLAYBOOKS_TARGET_DIR"
+    ;;
+  *)
+    echo "Error: unrecognized mode '$MODE' (usage: $(basename "$0") <validate-id|validate-skill|write> [args...])" >&2
+    exit 2
+    ;;
+esac

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,12 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Install project/app workspace dependencies (E29_S05_T01)
+        run: npm ci --prefix project/app
+
+      - 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}
 
@@ -221,6 +227,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Install project/app workspace dependencies (E29_S05_T01)
+        run: npm ci --prefix project/app
+
       - name: Stage to npm
         run: npm stage 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"