@jenga-ai/agent 3.1.1 → 3.2.0

package/scripts/check-public-playbook-steps.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+#
+# scripts/check-public-playbook-steps.sh — every public playbook's steps must ship publicly
+#
+# E50_S20_T01. Guards the invariant that a playbook shipped to the public mirror can actually
+# run there: for each playbook JSON that `.publicignore` does NOT block, every step must resolve
+# to a skill directory that `.publicignore` also does not block.
+#
+# Why this exists: `skills/jenga/scripts/load-playbooks.sh` requires every step's
+# `skills/<dir>/SKILL.md` to exist, and silently SKIPS the whole playbook (stderr warning only)
+# when one is missing. In the private repo every skill is present, so a playbook referencing a
+# private-only skill looks perfectly healthy — the breakage appears only in the public mirror,
+# where it surfaced as a stage-deploy gate failure rather than as a test failure (E50_S13).
+# This check reproduces that condition statically, on the private side, before anything ships.
+#
+# Blocklist semantics are NOT re-derived here. Classification is delegated to
+# scripts/check-publicignore-match.sh, which itself reuses /mirror-public's own
+# `rsync --exclude-from=.publicignore` matching — a second, hand-rolled answer to "is this path
+# blocked" is exactly the drift this repo has been bitten by before.
+#
+# Composed steps: a StepObject of the form {"playbook": "<id>"} composes another playbook. Its
+# own steps are checked when that playbook is itself public; a public playbook composing a
+# BLOCKED playbook is a violation in its own right, since the composed id will not resolve in
+# the mirror (see tests/load-playbooks-composition.bats's nonexistent-playbook-id behaviour).
+#
+# Usage:
+#   scripts/check-public-playbook-steps.sh [<repo-root>]
+#
+# Exit codes:
+#   0  every public playbook's every step (and composed playbook) is public
+#   1  at least one violation — each is named on stdout
+#   2  usage / environment error (bad root, missing helper, unparseable playbook)
+
+set -euo pipefail
+
+REPO_ROOT="${1:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+
+if [ ! -d "$REPO_ROOT" ]; then
+  echo "check-public-playbook-steps.sh: error: not a directory: $REPO_ROOT" >&2
+  exit 2
+fi
+
+PLAYBOOKS_DIR="$REPO_ROOT/skills/jenga/playbooks"
+MATCHER="$REPO_ROOT/scripts/check-publicignore-match.sh"
+
+if [ ! -f "$REPO_ROOT/.publicignore" ]; then
+  echo "check-public-playbook-steps.sh: no .publicignore at $REPO_ROOT — nothing to enforce, skipping"
+  exit 0
+fi
+
+if [ ! -f "$MATCHER" ]; then
+  echo "check-public-playbook-steps.sh: error: missing $MATCHER (the single source of blocklist semantics)" >&2
+  exit 2
+fi
+
+if [ ! -d "$PLAYBOOKS_DIR" ]; then
+  echo "check-public-playbook-steps.sh: no playbooks directory at $PLAYBOOKS_DIR — nothing to check"
+  exit 0
+fi
+
+# classify <path-relative-to-repo-root> -> echoes PUBLIC or BLOCKED
+classify() {
+  bash "$MATCHER" "$1" 2>/dev/null | head -1 | cut -f1
+}
+
+violations=0
+checked=0
+skipped_private=0
+
+for pb in "$PLAYBOOKS_DIR"/*.json; do
+  [ -f "$pb" ] || continue
+  base="$(basename "$pb")"
+  # schema.json describes playbooks, it is not one.
+  [ "$base" = "schema.json" ] && continue
+
+  rel="skills/jenga/playbooks/$base"
+  if [ "$(classify "$rel")" = "BLOCKED" ]; then
+    skipped_private=$((skipped_private + 1))
+    continue
+  fi
+
+  checked=$((checked + 1))
+
+  # Emit one "<kind>\t<value>" line per step. A bare string and {"skill": ...} are both skills;
+  # {"playbook": ...} is a composition.
+  steps="$(python3 -c '
+import json, sys
+with open(sys.argv[1]) as fh:
+    pb = json.load(fh)
+for s in pb.get("steps", []):
+    if isinstance(s, str):
+        print("skill\t" + s)
+    elif isinstance(s, dict):
+        if "skill" in s:
+            print("skill\t" + str(s["skill"]))
+        elif "playbook" in s:
+            print("playbook\t" + str(s["playbook"]))
+' "$pb")" || {
+    echo "check-public-playbook-steps.sh: error: could not parse $rel" >&2
+    exit 2
+  }
+
+  while IFS=$'\t' read -r kind value; do
+    [ -n "${kind:-}" ] || continue
+    case "$kind" in
+      skill)
+        target="skills/$value/SKILL.md"
+        if [ ! -f "$REPO_ROOT/$target" ]; then
+          echo "VIOLATION  $rel -> step '$value': no $target on disk"
+          violations=$((violations + 1))
+        elif [ "$(classify "$target")" = "BLOCKED" ]; then
+          echo "VIOLATION  $rel -> step '$value': $target is blocklisted, so this public playbook cannot load in the mirror"
+          violations=$((violations + 1))
+        fi
+        ;;
+      playbook)
+        target="skills/jenga/playbooks/$value.json"
+        if [ ! -f "$REPO_ROOT/$target" ]; then
+          echo "VIOLATION  $rel -> composes '$value': no $target on disk"
+          violations=$((violations + 1))
+        elif [ "$(classify "$target")" = "BLOCKED" ]; then
+          echo "VIOLATION  $rel -> composes '$value': $target is blocklisted, so the composed id will not resolve in the mirror"
+          violations=$((violations + 1))
+        fi
+        ;;
+    esac
+  done <<< "$steps"
+done
+
+if [ "$violations" -gt 0 ]; then
+  echo "check-public-playbook-steps.sh: $violations violation(s) across $checked public playbook(s) ($skipped_private private playbook(s) not checked)"
+  exit 1
+fi
+
+echo "check-public-playbook-steps.sh: OK — $checked public playbook(s) checked, every step ships publicly ($skipped_private private playbook(s) skipped)"
+exit 0

package/skills/j-close-story/SKILL.md

@@ -129,7 +129,7 @@ For **each task ID** listed in the story's `tasks:` frontmatter array:
    ```bash
    bash skills/j-close-story/scripts/check-privatized.sh <task-id> "project/board/tasks/<task-id>_*.md"
    ```
-   This is a **static** check (per `templates/SCRUM_BOARD_SCHEMA.md`'s "Static
+   This is a **static** check (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 "Static
    vs. Reactive Status Setting" section) — it derives the task's touched-file
    list from its own EST-tagged commit history (same technique as Step 2) and
    tests every file against `.publicignore`, with **no dependency on any

package/skills/j-do/SKILL.md

@@ -58,7 +58,7 @@ Extract the following named values for use throughout this skill:
 These values must be read fresh on each invocation. Never use hardcoded fallbacks.
 
 ### 1. Check for `project/todo.md`
-Run `bash scripts/todo_manager.sh exists`. If it exits non-zero, inform the user there are no queued tasks and exit.
+Run `bash "$([ -f scripts/todo_manager.sh ] && echo scripts/todo_manager.sh || echo node_modules/@jenga-ai/agent/scripts/todo_manager.sh)" exists`. If it exits non-zero, inform the user there are no queued tasks and exit.
 
 ### 1.5. Story-Bundle Execution Mode
 
@@ -284,7 +284,7 @@ No patch file is written on success.
 If `/do` is invoked with a task ID (`E##_S##_T##`) or a plain-text title, skip this section and use the normal task execution path (steps 2–8 below).
 
 ### 2. List tasks and let the user choose
-Run `bash scripts/todo_manager.sh list` to display the queued tasks. Ask the user:
+Run `bash "$([ -f scripts/todo_manager.sh ] && echo scripts/todo_manager.sh || echo node_modules/@jenga-ai/agent/scripts/todo_manager.sh)" list` to display the queued tasks. Ask the user:
 - Execute a specific task (by number or title)
 - Execute the next task from the top of the list
 - Exit
@@ -294,14 +294,14 @@ Run `bash scripts/todo_manager.sh list` to display the queued tasks. Ask the use
 Before resolving a task for execution, inspect the selected entry's ID:
 
 - **Epic (`E##`)** — the entry refers to a whole epic that has not yet been broken into stories.
-  Use the scrum-master agent to read the epic's board file (`$(bash scripts/board_resolver.sh)epics/`) and decompose it into stories. For each story produced:
-  1. Write a story file to `$(bash scripts/board_resolver.sh)stories/`.
-  2. Run `bash scripts/todo_manager.sh add '<story title>: <E##_S##>'`
-  After breakdown, Run `bash scripts/todo_manager.sh remove '<epic entry title>'` and go back to step 2 so the new stories are visible.
+  Use the scrum-master agent to read the epic's board file (`$(bash "$([ -f scripts/board_resolver.sh ] && echo scripts/board_resolver.sh || echo node_modules/@jenga-ai/agent/scripts/board_resolver.sh)")epics/`) and decompose it into stories. For each story produced:
+  1. Write a story file to `$(bash "$([ -f scripts/board_resolver.sh ] && echo scripts/board_resolver.sh || echo node_modules/@jenga-ai/agent/scripts/board_resolver.sh)")stories/`.
+  2. Run `bash "$([ -f scripts/todo_manager.sh ] && echo scripts/todo_manager.sh || echo node_modules/@jenga-ai/agent/scripts/todo_manager.sh)" add '<story title>: <E##_S##>'`
+  After breakdown, Run `bash "$([ -f scripts/todo_manager.sh ] && echo scripts/todo_manager.sh || echo node_modules/@jenga-ai/agent/scripts/todo_manager.sh)" remove '<epic entry title>'` and go back to step 2 so the new stories are visible.
 
 - **Story (`E##_S##`) with no tasks** — the entry refers to a story that has not yet been broken into tasks.
-  Check `$(bash scripts/board_resolver.sh)tasks/` for any task files whose front-matter `story_id` matches this story. If none exist, use the scrum-master agent to read the story's board file and decompose it into tasks. For each task produced:
-  1. Write a task file to `$(bash scripts/board_resolver.sh)tasks/`.
+  Check `$(bash "$([ -f scripts/board_resolver.sh ] && echo scripts/board_resolver.sh || echo node_modules/@jenga-ai/agent/scripts/board_resolver.sh)")tasks/` for any task files whose front-matter `story_id` matches this story. If none exist, use the scrum-master agent to read the story's board file and decompose it into tasks. For each task produced:
+  1. Write a task file to `$(bash "$([ -f scripts/board_resolver.sh ] && echo scripts/board_resolver.sh || echo node_modules/@jenga-ai/agent/scripts/board_resolver.sh)")tasks/`.
   After breakdown, keep the story entry in `project/todo.md` (tasks are discovered from it automatically). Go back to step 2.
 
 - **Story (`E##_S##`) with existing tasks**, or **Task (`E##_S##_T##`)** — no breakdown needed; proceed to step 4.
@@ -310,7 +310,7 @@ Before resolving a task for execution, inspect the selected entry's ID:
 Each todo entry uses the format: `<mission title>: <E##_S##_T##>` (or `E##_S##` if no task ID).
 
 Before starting:
-1. Locate and read the matching file from `$(bash scripts/board_resolver.sh)tasks/` (or `$(bash scripts/board_resolver.sh)stories/` if story-level)
+1. Locate and read the matching file from `$(bash "$([ -f scripts/board_resolver.sh ] && echo scripts/board_resolver.sh || echo node_modules/@jenga-ai/agent/scripts/board_resolver.sh)")tasks/` (or `$(bash "$([ -f scripts/board_resolver.sh ] && echo scripts/board_resolver.sh || echo node_modules/@jenga-ai/agent/scripts/board_resolver.sh)")stories/` if story-level)
 2. If the file does not exist, warn the user and skip — do not proceed with a task that has no scrum board definition
 3. Present a brief summary of the task: title, acceptance criteria, parent story, parent epic
 
@@ -343,7 +343,7 @@ After override validation (step 4.1) and before branching on `execution_scope` i
 
 3. **Overwrite `execution_scope` to `inline`** in the task's frontmatter, unconditionally — `--trivial` always forces `inline`, never a softer "lightest safe tier."
 
-4. **Record the override for audit**, reusing the existing `jenga_assigned` / `override_justification` pairing already defined in `templates/SCRUM_BOARD_SCHEMA.md` for exactly this situation ("scope overridden by a human"), rather than inventing a new field:
+4. **Record the override for audit**, reusing the existing `jenga_assigned` / `override_justification` pairing 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)` for exactly this situation ("scope overridden by a human"), rather than inventing a new field:
    - Set `jenga_assigned: false` (if not already `false`).
    - Set (or append to, if already present) `override_justification`:
      ```
@@ -368,7 +368,7 @@ After override validation (step 4.1) and before branching on `execution_scope` i
 
 After resolving the task context (step 4), passing override validation (step 4.1), and applying the `--trivial` dispatch-time override if present (step 4.1.5), read `execution_scope` from the task frontmatter.
 
-**Locked-task dispatch guard (defense-in-depth).** Before branching on `execution_scope` below, read `crucial_level` from the task frontmatter (per `templates/SCRUM_BOARD_SCHEMA.md`'s Crucial Flag Fields). If `crucial_level: locked`:
+**Locked-task dispatch guard (defense-in-depth).** Before branching on `execution_scope` below, read `crucial_level` from the task frontmatter (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 `crucial_level: locked`:
 
 - This task MUST be routed through the inline execution path below — no worktree, no developer subagent — regardless of what `execution_scope` currently reads. This guards against a locked task reaching dispatch with a non-`inline` `execution_scope` (a race, a manually edited file, or a task added to a story's `tasks:` list after `skills/jenga/SKILL.md` Phase 0.5's Rule 4 last ran).
 - If `execution_scope` is already `inline`, proceed directly to the inline steps below — no correction needed.
@@ -389,10 +389,10 @@ After resolving the task context (step 4), passing override validation (step 4.1
 1. Read the task file and load its full content (description, acceptance criteria). Do NOT create a worktree. Do NOT spawn a developer subagent.
 2. Implement the task inline — make the required changes to files directly in the current session.
 3. Run the smoke test harness before committing anything:
-   - Run `bash scripts/smoke-harness.sh <changed_file>...`, passing the paths changed in step 2. With no arguments the harness infers them from `git diff --name-only HEAD`. It exits `0` on pass and `1` on failure.
-   - If `scripts/smoke-harness.sh` does not exist, log a warning and treat the result as a pass:
+   - Run `bash "$([ -f scripts/smoke-harness.sh ] && echo scripts/smoke-harness.sh || echo node_modules/@jenga-ai/agent/scripts/smoke-harness.sh)" <changed_file>...`, passing the paths changed in step 2. With no arguments the harness infers them from `git diff --name-only HEAD`. It exits `0` on pass and `1` on failure.
+   - If neither `scripts/smoke-harness.sh` nor `node_modules/@jenga-ai/agent/scripts/smoke-harness.sh` exists, log a warning and treat the result as a pass:
      ```
-     WARNING [<task_id>]: scripts/smoke-harness.sh not found. Smoke test skipped (stub pass).
+     WARNING [<task_id>]: smoke-harness.sh not found. Smoke test skipped (stub pass).
      ```
 4. **If the smoke test exits non-zero**:
    - **If this is a `--trivial`-forced run** (marker set in step 4.1.5 — and `crucial_level` is not `locked`, which never falls back, per 4.1.5's precedence note): do NOT write `status: Failed`. `--trivial` always forces `inline` with no softer "lightest safe tier" to fall back to first, so a smoke-harness failure here goes straight to the shared `#### Fallback to Full Task-Scope Pipeline` procedure below (origin: `trivial`). Do not proceed with the remaining inline steps below — the Fallback procedure takes over from here.
@@ -431,10 +431,10 @@ After resolving the task context (step 4), passing override validation (step 4.1
 1. **Spawn a developer subagent** (Agent tool, `subagent_type: "developer"`) with the same sender object and context payload as step 5 would use, but with an explicit instruction added to the dispatch prompt: **do not create a worktree** — implement directly against the current checkout (the session's existing working tree), not an isolated `.claude/worktrees/<slug>` copy. This is the one concrete difference from the step-5 `task` path: everything else about how the subagent implements the task (reading the task file, following acceptance criteria, following repo conventions) is unchanged.
 
 2. **After the developer subagent reports implementation complete**, run the smoke test harness using the same invocation convention as `### 4.2. Inline Execution Path`:
-   - Run `bash scripts/smoke-harness.sh <changed_file>...`, passing the paths the subagent changed. With no arguments the harness infers them from `git diff --name-only HEAD`. It exits `0` on pass and `1` on failure.
-   - If `scripts/smoke-harness.sh` does not exist, log a warning and treat the result as a pass:
+   - Run `bash "$([ -f scripts/smoke-harness.sh ] && echo scripts/smoke-harness.sh || echo node_modules/@jenga-ai/agent/scripts/smoke-harness.sh)" <changed_file>...`, passing the paths the subagent changed. With no arguments the harness infers them from `git diff --name-only HEAD`. It exits `0` on pass and `1` on failure.
+   - If neither `scripts/smoke-harness.sh` nor `node_modules/@jenga-ai/agent/scripts/smoke-harness.sh` exists, log a warning and treat the result as a pass:
      ```
-     WARNING [<task_id>]: scripts/smoke-harness.sh not found. Smoke test skipped (stub pass).
+     WARNING [<task_id>]: smoke-harness.sh not found. Smoke test skipped (stub pass).
      ```
 
 3. **If the smoke test passes**:
@@ -528,8 +528,8 @@ Additionally, if the completed work introduces user-facing changes, update `READ
 ### 7. After successful completion
 - Check for any `_INSTRUCTIONS.md` files in `project/instructions/` whose ID matches the completed task. If found, present them to the user and explain that these actions must be completed before the feature will work correctly.
 - Invoke the `/commit` skill to commit the work (if not already committed by the developer)
-- Run `bash scripts/todo_manager.sh remove '<task title>'` to remove the completed task from `project/todo.md`
-- Run `bash scripts/todo_manager.sh teardown` to delete `project/todo.md` if it is now effectively empty
+- Run `bash "$([ -f scripts/todo_manager.sh ] && echo scripts/todo_manager.sh || echo node_modules/@jenga-ai/agent/scripts/todo_manager.sh)" remove '<task title>'` to remove the completed task from `project/todo.md`
+- Run `bash "$([ -f scripts/todo_manager.sh ] && echo scripts/todo_manager.sh || echo node_modules/@jenga-ai/agent/scripts/todo_manager.sh)" teardown` to delete `project/todo.md` if it is now effectively empty
 
 ### 8. Loop
 Go back to step 1.

package/skills/j-doc-sync/SKILL.md

@@ -101,7 +101,7 @@ Every candidate identified above as "missing documentation for new things added
 1. **Check for `.publicignore` at the repo root.** Most projects using this framework will not have one (they haven't adopted `/mirror-public`) — if it's absent, **skip this entire sub-step**. Fall through to flagging every "missing documentation" candidate exactly as `3.` above already would, with no further filtering.
 2. **If `.publicignore` exists**, for each "missing documentation" candidate, determine its source path (relative to the repo root) and classify it by running:
    ```
-   scripts/check-publicignore-match.sh <path> [<path> ...]
+   bash "$([ -f scripts/check-publicignore-match.sh ] && echo scripts/check-publicignore-match.sh || echo node_modules/@jenga-ai/agent/scripts/check-publicignore-match.sh)" <path> [<path> ...]
    ```
    This reuses `/mirror-public`'s own `mirror.sh` matching logic (`rsync --exclude-from=.publicignore`) — a file this script reports `BLOCKED` is guaranteed to be a file `/mirror-public --dry-run` would also report as "would be blocked", and vice versa for `PUBLIC`. It needs no network access and does not require `/mirror-public` to be configured.
 3. **`BLOCKED`** → do not flag this candidate as missing documentation. It's private-only and will never ship to the public mirror, so public docs coverage is not applicable.
@@ -181,6 +181,17 @@ After all writes are done, print a summary:
 If nothing needed updating, print: `✅ Documentation is already in sync with the source.`
 If minification could not reach the target, note: `⚠️ docs/API.md reduced to X% (target was Y% — essential content limit reached).`
 
+### 8. GitHub Pages site follow-up (E41_S13)
+
+If this run updated `project/.wiki/documentation.md`, `project/.wiki/intro-guide.md`, or any
+`project/.wiki/concepts/*.md` file, also re-run `bash "$([ -f scripts/build-pages-site.sh ] && echo scripts/build-pages-site.sh || echo node_modules/@jenga-ai/agent/scripts/build-pages-site.sh)"` afterward. That
+script deterministically regenerates the GitHub Pages documentation site's wiki-derived pages
+(`docs/getting-started.md`, `docs/concepts.md`, `docs/skills.md`, `docs/agents.md`,
+`docs/hooks.md`, `docs/mcp-tools.md`, `docs/reference.md`) from the wiki content this step just
+updated — without re-running it, the Pages site silently drifts from the wiki the same way
+`README.md` and the wiki itself have drifted from each other before. Mention this in the
+summary output (e.g. `🔄 Re-ran build-pages-site.sh to refresh the Pages site`).
+
 ---
 
 ## Reference files

package/skills/j-idea/SKILL.md

@@ -36,7 +36,7 @@ This file is generated/synced by `scripts/generate-j-alias.sh idea` from `skills
 
 3. **Add to `project/ideas.md`** by running:
    ```
-   bash scripts/idea_manager.sh add '<idea>'
+   bash "$([ -f scripts/idea_manager.sh ] && echo scripts/idea_manager.sh || echo node_modules/@jenga-ai/agent/scripts/idea_manager.sh)" add '<idea>'
    ```
 
 4. **Ask the user**: "Capture another idea, or done?"

package/skills/j-init/SKILL.md

@@ -144,10 +144,11 @@ This script handles all scaffolding in one step:
 7. Creates `project/configs/scope-thresholds.json` with default execution-scope thresholds (consumed by `/jenga` and `/do`, which halt if it's missing)
 8. Creates `project/data/baselines.json`
 9. Creates `project/logs/events.json`
-10. Creates `docs/STRATEGY.md` — a strategic brief stub intended for investors, partners, and the product team
-11. Creates `CHANGELOG.md` from the shared template — a running log of notable changes, seeded with an `[Unreleased]` section
-12. Applies the chosen visibility mode via `scripts/apply-project-visibility.sh`, which records it as `project_files_visibility` in `jenga.config.json` and performs any `.gitignore` change
-13. Stages and commits all files with the message `init: scaffold project structure and workflow config`
+10. Creates `project/knowledge-graph/STUB_SCHEMA.md` from the shared template and `project/knowledge-graph/graph.json` seeded with empty `nodes`/`edges` arrays — consumed by `/uncharted`'s conversational elicitation flow
+11. Creates `docs/STRATEGY.md` — a strategic brief stub intended for investors, partners, and the product team
+12. Creates `CHANGELOG.md` from the shared template — a running log of notable changes, seeded with an `[Unreleased]` section
+13. Applies the chosen visibility mode via `scripts/apply-project-visibility.sh`, which records it as `project_files_visibility` in `jenga.config.json` and performs any `.gitignore` change
+14. Stages and commits all files with the message `init: scaffold project structure and workflow config`
 
 The visibility mode is validated before any scaffolding happens, so an invalid
 value fails fast and leaves nothing behind. It is applied before the commit, so

package/skills/j-init/assets/directory_structure.txt

@@ -3,6 +3,7 @@ project/board/stories
 project/board/tasks
 project/instructions
 project/configs
+project/knowledge-graph
 project/data
 project/queue
 project/rapports/problems

package/skills/j-init/scripts/detect-existing-codebase.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # ---------------------------------------------------------------------------
-# skills/init/scripts/detect-existing-codebase.sh
+# skills/j-init/scripts/detect-existing-codebase.sh
 #
 # Deterministic front half of the /init "detect existing project state" step.
 # /init currently always scaffolds as though the target directory were empty.
@@ -12,7 +12,7 @@
 # This script answers exactly one question -- "what kind of directory is
 # this?" -- and nothing else. It never scaffolds, never prompts, never runs
 # /uncharted, and never modifies anything on disk. Deciding what to DO with
-# the verdict is agent judgement and lives in skills/init/SKILL.md.
+# the verdict is agent judgement and lives in skills/j-init/SKILL.md.
 #
 # ---------------------------------------------------------------------------
 # VERDICTS -- exactly one is printed on stdout, nothing else

package/skills/j-init/scripts/init.sh

@@ -8,9 +8,9 @@ VISIBILITY_SCRIPT="$SCRIPT_DIR/apply-project-visibility.sh"
 # ─── Resolve the package root that owns templates/ and lib/ ──────────────────
 # postinstall.js mirrors only skills/ and agents/ into .claude/ and .agents/ —
 # templates/ and lib/ are never copied there, so a script running from a
-# mirrored copy (.claude/skills/init/scripts/ or .agents/skills/init/scripts/)
+# mirrored copy (.claude/skills/j-init/scripts/ or .agents/skills/j-init/scripts/)
 # cannot reach its siblings via a fixed ../../../ climb the way it can in this
-# monorepo checkout, where init.sh actually lives at skills/init/scripts/ with
+# monorepo checkout, where init.sh actually lives at skills/j-init/scripts/ with
 # templates/ and lib/ three levels up. Consumers instead have them inside the
 # installed npm package.
 if [[ -d "$SCRIPT_DIR/../../../templates" ]]; then
@@ -81,6 +81,17 @@ echo '{}' > project/data/baselines.json
 echo "→ Creating events.json..."
 echo '[]' > project/logs/events.json
 
+# ─── 8.5. Create project/knowledge-graph/{STUB_SCHEMA.md,graph.json} ─────────
+# Consumed by skills/uncharted's conversational elicitation flow (`onboard`,
+# `segment --mode investigate`), which writes coarse graph nodes/edges to
+# graph.json per the stub schema — both must exist before that flow's first
+# write, per templates/KNOWLEDGE_GRAPH_STUB_SCHEMA_TEMPLATE.md's own header
+# comment (E20_S08_T01; replaced wholesale once E20_S01's real schema lands).
+echo "→ Copying knowledge-graph STUB_SCHEMA.md from template..."
+cp "$PKG_ROOT/templates/KNOWLEDGE_GRAPH_STUB_SCHEMA_TEMPLATE.md" project/knowledge-graph/STUB_SCHEMA.md
+echo "→ Creating project/knowledge-graph/graph.json..."
+echo '{"nodes": [], "edges": []}' > project/knowledge-graph/graph.json
+
 # ─── 9. Create docs/STRATEGY.md ──────────────────────────────────────────────
 echo "→ Creating docs/STRATEGY.md (strategic brief for investors, partners, and the product team)..."
 mkdir -p docs

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"