@jenga-ai/agent 3.5.0 → 3.6.0

package/skills/j-gitignore/scripts/untrack-jenga-files.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# skills/j-gitignore/scripts/untrack-jenga-files.sh
+#
+# Removes Jenga-owned paths from git WITHOUT removing them from disk —
+# `git rm -r --cached`, never a plain `git rm`. The files stay exactly where
+# they are; git simply stops tracking them, and the .gitignore entries written
+# by repair-gitignore.sh then keep them from coming back.
+#
+# Run repair-gitignore.sh FIRST. .gitignore has no effect on an already-tracked
+# file, so untracking without the entries in place just means the next
+# `git add -A` re-adds everything.
+#
+# ─── What "removed from origin" does and does not mean ──────────────────────
+# With --commit --push, these paths disappear from the branch TIP on the
+# remote: clone it fresh and they are gone. Earlier commits are UNTOUCHED —
+# the blobs remain reachable in history, so this is not a secret-scrubbing
+# tool. If something sensitive was committed, treat it as compromised, rotate
+# it, and use a history-rewriting tool (git-filter-repo) separately.
+#
+# Invoked via `bash`, not executed directly.
+#
+# Usage:
+#   untrack-jenga-files.sh [project_root]
+#                          [--tiers scaffold,hybrid,board,optional]
+#                          [--dry-run] [--commit] [--push]
+#                          [--allow-dirty-index]
+#
+# Options:
+#   --dry-run             List what would be untracked; touch nothing.
+#   --commit              Commit the removals. Without it, changes are left
+#                         staged for you to inspect and commit yourself.
+#   --push                Push to the branch's upstream. Requires --commit.
+#                         Never implied — this is the only outward-facing step.
+#   --allow-dirty-index   Proceed even if unrelated changes are already staged.
+#                         Off by default so this can never sweep your staged
+#                         work into its commit.
+#
+# Exit codes:
+#   0  Success (including "nothing tracked — nothing to do")
+#   1  Bad usage or missing prerequisite
+#   2  Invalid tier
+#   3  git operation failed
+#   4  Refused: index already dirty, or --push without --commit
+# -----------------------------------------------------------------------------
+
+set -uo pipefail
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/_catalog.sh"
+
+info() { echo "[untrack] $*"; }
+warn() { echo "[untrack] WARNING: $*"; }
+err()  { echo "[untrack] ERROR: $*" >&2; }
+
+PROJECT_ROOT=""
+TIERS="scaffold"
+DRY_RUN=0
+DO_COMMIT=0
+DO_PUSH=0
+ALLOW_DIRTY=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --tiers)   TIERS="${2:-}"; shift 2 ;;
+    --tiers=*) TIERS="${1#*=}"; shift ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    --commit)  DO_COMMIT=1; shift ;;
+    --push)    DO_PUSH=1; shift ;;
+    --allow-dirty-index) ALLOW_DIRTY=1; shift ;;
+    -h|--help)
+      echo "Usage: $(basename "$0") [project_root] [--tiers <csv>] [--dry-run] [--commit] [--push] [--allow-dirty-index]"
+      exit 0 ;;
+    -*) err "Unknown option: $1"; exit 1 ;;
+    *)
+      if [ -n "$PROJECT_ROOT" ]; then err "More than one project root given."; exit 1; fi
+      PROJECT_ROOT="$1"; shift ;;
+  esac
+done
+
+if [ "$DO_PUSH" -eq 1 ] && [ "$DO_COMMIT" -eq 0 ]; then
+  err "--push requires --commit. There would be nothing to push."
+  exit 4
+fi
+
+PROJECT_ROOT="${PROJECT_ROOT:-$PWD}"
+validate_tiers "$TIERS" || exit 2
+resolve_root "$PROJECT_ROOT" || exit 1
+load_catalog "$TIERS" || exit 1
+
+# ─── Refuse to run on a dirty index ─────────────────────────────────────────
+# .gitignore is the one staged path that is never "unrelated": it is the
+# companion change repair-gitignore.sh just made, and untracking without it is
+# pointless. Staged alone, it is allowed through and folded into this commit.
+# Anything else staged is refused.
+if [ "$ALLOW_DIRTY" -eq 0 ] && [ "$DRY_RUN" -eq 0 ]; then
+  if ! git diff --cached --quiet 2>/dev/null; then
+    staged="$(git diff --cached --name-only)"
+    if [ "$staged" = ".gitignore" ]; then
+      info "Staged .gitignore detected — folding the ignore-rule change into this commit."
+    else
+      err "The index already has staged changes:"
+      printf '%s\n' "$staged" | sed 's/^/        /' >&2
+      err "Refusing to run — a --commit here would sweep them into this commit."
+      err "Commit or unstage them first, or pass --allow-dirty-index if you"
+      err "genuinely want them included."
+      exit 4
+    fi
+  fi
+fi
+
+# ─── Find what is actually tracked ──────────────────────────────────────────
+TRACKED_PATHS=()
+TOTAL_FILES=0
+for i in "${!CATALOG_PATHS[@]}"; do
+  path="${CATALOG_PATHS[$i]}"
+  count="$(git ls-files -- "$path" 2>/dev/null | wc -l | tr -d ' ')"
+  if [ "${count:-0}" -gt 0 ]; then
+    TRACKED_PATHS+=("$path")
+    TOTAL_FILES=$((TOTAL_FILES + count))
+    printf '  %-36s %s tracked file(s)\n' "$path" "$count"
+  fi
+done
+
+if [ "${#TRACKED_PATHS[@]}" -eq 0 ]; then
+  info "No catalog path (tiers: ${TIERS}) is tracked — nothing to untrack."
+  exit 0
+fi
+
+echo
+info "${#TRACKED_PATHS[@]} path(s), ${TOTAL_FILES} file(s) would stop being tracked."
+info "All of them remain on disk — this uses 'git rm -r --cached'."
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  info "--dry-run — nothing changed."
+  exit 0
+fi
+
+# ─── Untrack ────────────────────────────────────────────────────────────────
+for path in "${TRACKED_PATHS[@]}"; do
+  if ! git rm -r --cached --quiet -- "$path"; then
+    err "git rm --cached failed for '${path}'. The index may be partially staged;"
+    err "inspect with 'git status' and 'git reset' to back out."
+    exit 3
+  fi
+  info "Untracked: ${path}"
+done
+
+# Verify nothing was deleted from disk before reporting success.
+MISSING=0
+for path in "${TRACKED_PATHS[@]}"; do
+  probe="${path%/}"
+  if [ ! -e "$probe" ]; then
+    warn "'${probe}' is not on disk. It was already absent before this ran"
+    warn "(git tracked it, the working tree did not), so nothing was lost here."
+    MISSING=$((MISSING + 1))
+  fi
+done
+[ "$MISSING" -eq 0 ] && info "Verified: every untracked path is still present on disk."
+
+if [ "$DO_COMMIT" -eq 0 ]; then
+  echo
+  info "Changes are STAGED but not committed. Review with:"
+  info "    git status"
+  info "    git diff --cached --stat"
+  info "Then commit yourself, or re-run with --commit."
+  exit 0
+fi
+
+# ─── Commit ─────────────────────────────────────────────────────────────────
+COMMIT_MSG="chore(jenga): untrack Jenga-owned files, keep them on disk
+
+Removes the Jenga scaffold from version control via 'git rm --cached' and
+relies on the j.gitignore managed block to keep it out. Files are untouched
+on disk. Tiers: ${TIERS}.
+
+Note: this changes the branch tip only — earlier commits still contain these
+paths."
+
+if ! git commit -q -m "$COMMIT_MSG"; then
+  err "git commit failed. Your removals are still staged."
+  exit 3
+fi
+info "Committed: $(git rev-parse --short HEAD)"
+
+if [ "$DO_PUSH" -eq 0 ]; then
+  echo
+  info "Not pushed. The remote still has these files until you push."
+  exit 0
+fi
+
+# ─── Push ───────────────────────────────────────────────────────────────────
+BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+UPSTREAM="$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null)"
+
+if [ -z "$UPSTREAM" ]; then
+  err "Branch '${BRANCH}' has no upstream — refusing to guess a remote."
+  err "Set one, then push yourself:  git push -u origin ${BRANCH}"
+  err "The commit itself succeeded and is safe on your local branch."
+  exit 3
+fi
+
+info "Pushing ${BRANCH} → ${UPSTREAM} ..."
+if ! git push; then
+  err "Push failed — most likely the branch is behind its upstream."
+  err "Reconcile (git pull --rebase) and push yourself. The commit is safe locally."
+  exit 3
+fi
+
+info "Pushed. These paths are gone from ${UPSTREAM}'s tip."
+info "They REMAIN in earlier commits — this did not rewrite history."
+exit 0

package/skills/j-idea/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: j.idea
-description: Polyfill alias of the idea skill under a collision-safe directory name. Identical behavior to /idea — Capture a loosely-defined idea to project/ideas.md — a lightweight, "maybe someday" log with no board or promotion overhead. Use when the bare /idea form is shadowed by another tool's own built-in command of the same name.
+description: Polyfill alias of the idea skill under a collision-safe directory name. Identical behavior to /idea — DEPRECATED - use the prefixed 'j-idea' skill instead. Capture a loosely-defined idea to project/ideas.md — a lightweight, "maybe someday" log with no board or promotion overhead. Use when the bare /idea form is shadowed by another tool's own built-in command of the same name.
 keywords:
   - idea
   - capture idea
@@ -52,12 +52,84 @@ This file is generated/synced by `scripts/generate-j-alias.sh idea` from `skills
 - **Promoting an idea** means re-running `/brainstorm` on it, which routes onward to `/btw` or `/todo` as normal. That routing behavior already exists and is out of scope for `/idea`.
 - **Terminal idea states** are marked directly in `project/ideas.md` using the same HTML-comment tag convention `project/todo.md` uses for `RECONCILED`:
   - `PROMOTED` — the idea was picked up via `/brainstorm` and turned into board work.
-  - `DISCARDED` — the idea was reviewed and dropped.
+  - `REJECTED` — the idea was reviewed and dropped.
 
-  Example (mirroring `project/todo.md`'s tagging style):
+### Embedded Board ID
+
+`PROMOTED`/`REJECTED` tags support an embedded board ID, so the idea→board-item link is
+machine-readable directly from the tag itself, without needing a separate lookup:
+
+- `<!-- PROMOTED: E##_S##[_T##] -->` — the `_T##` task suffix is optional; use whichever level
+  the idea was actually promoted into (an epic, a story, or a specific task).
+- `<!-- REJECTED -->` — stays bare, with no embedded ID. A rejection has no resulting board
+  item to point at.
+
+Example (mirroring `project/todo.md`'s tagging style):
+```
+Add dark mode toggle to settings page <!-- PROMOTED: E12_S03 -->
+Add a settings-page keyboard shortcut cheat sheet <!-- PROMOTED: E12_S03_T02 -->
+Rewrite onboarding copy in a more casual tone <!-- REJECTED -->
+```
+
+### Source-Rapport Link Convention
+
+Some ideas originate from a rapport rather than being manually captured via `/idea` — e.g. when
+scrum-master's `rapport_review` step (E35_S03) detects a distinct idea surfaced inside a
+problem rapport and, on user confirmation, appends it to `project/ideas.md` the same way
+`/idea` does. When that happens, the entry's source rapport is recorded with a second inline
+HTML comment on the same line:
+
+```
+<!-- rapport: <path/to/rapport.md> -->
+```
+
+Rules:
+- Written at capture time, alongside the idea text, by whichever flow is adding the entry
+  (scrum-master's rapport-derived capture path; `/idea`'s own manual capture never has a source
+  rapport and omits this comment entirely).
+- Left in place through promotion/rejection — the `rapport:` comment and the terminal
+  `PROMOTED`/`REJECTED` comment coexist on the same line, e.g.:
   ```
-  Add dark mode toggle to settings page <!-- PROMOTED -->
-  Rewrite onboarding copy in a more casual tone <!-- DISCARDED -->
+  Extract shared retry logic into a utility <!-- rapport: project/rapports/problems/E40_S02_T01-segment-remarks.md --> <!-- PROMOTED: E61_S01 -->
   ```
+- Consumed by the outcome-record mechanism at promotion/rejection time: if a `rapport:` comment
+  is present on the line, that rapport is updated with the decision (and `[SPIKE]`-prefixed in
+  its title/header if not already, per `templates/SCRUM_BOARD_SCHEMA.md`'s `[SPIKE]` section);
+  if absent (a manually-captured `/idea` entry with no source rapport), a
+  `project/documentation/plans/<slug>_PROMOTED.md` or `_REJECTED.md` file is created instead.
+- Verified compatible with `scripts/idea_manager.sh`'s `real_entries()` filtering: that function
+  only strips lines whose first non-whitespace characters are `<!--`; a trailing inline comment
+  on an otherwise real entry line is untouched and the line still counts as a real entry.
+
+No agent invoked by `/idea` applies terminal (`PROMOTED`/`REJECTED`) tags or acts on them — that
+is reserved for the promotion step (e.g. within `/brainstorm`) and, for rapport-sourced ideas,
+scrum-master's rapport-review flow.
+
+### Outcome-Record Mechanism (`idea_manager.sh`) — E35_S03_T03
+
+`scripts/idea_manager.sh` implements the tagging and outcome-record behavior described above, via
+four additional subcommands beyond `add`/`list`:
+
+- `tag "<idea-text>" <PROMOTED:E##_S##[_T##]|REJECTED>` — writes the terminal tag onto the
+  `project/ideas.md` line matching `<idea-text>` (an exact/literal match; errors if zero or more
+  than one line matches, and errors if the line is already tagged).
+- `get-id "<idea-text>"` — prints the embedded board ID from that line's `PROMOTED` tag (errors
+  if the line has no `PROMOTED` tag).
+- `get-rapport "<idea-text>"` — prints the `rapport:` path recorded on that line, or nothing
+  (exit 0) if the line has no source-rapport comment.
+- `resolve "<idea-text>" <promoted|rejected> [board_id]` — the full outcome-record mechanism in
+  one call: tags the line (as `tag` does), then either updates the idea's source rapport or, if
+  none is recorded, creates the `project/documentation/plans/` fallback file:
+  - **Source rapport present:** the rapport's `# Rapport: ...` title line is prefixed
+    `[SPIKE] ` if not already, and an `## Idea Outcome Record` section (decision, date, resulting
+    board ID if promoted, and the idea text) is appended to the rapport file.
+  - **No source rapport:** `project/documentation/plans/<slug>_PROMOTED.md` or `_REJECTED.md` is
+    created (idea text slugified, lowercased, capped at 60 characters), containing the same
+    decision/date/board-ID/idea-text content.
+
+  `board_id` is required for `promoted` (validated to start with `E<digits>`) and must be omitted
+  for `rejected` (a rejection has no resulting board item).
 
-No agent invoked by `/idea` applies these tags or acts on them — that is reserved for a future promotion step (e.g. within `/brainstorm`).
+This is the mechanism itself, not the trigger — nothing currently calls `resolve` automatically.
+A future promotion step (e.g. within `/brainstorm`'s routing, or scrum-master acting on a
+rapport-sourced idea) is expected to invoke it once that trigger exists.

package/skills/j-idea/assets/idea_template.md

@@ -1,3 +1,3 @@
 # Ideas
 
-<!-- Format: <idea text> (one line per idea; terminal tags PROMOTED / DISCARDED appended by /brainstorm, not by /idea) -->
+<!-- Format: <idea text> (one line per idea; terminal tags PROMOTED / REJECTED appended by /brainstorm, not by /idea) -->

package/skills/j-improve/SKILL.md

@@ -50,7 +50,7 @@ Assess whether you have enough context to evaluate current behavior against the
 Invoke the `/examplify` skill. Specify clearly what you want it to find out — e.g. which code paths are exercised, what inputs/outputs look like, or what edge cases exist.
 
 ### 5. Run `/evaluate`
-Copy `.agents/skills/evaluate/assets/evaluation_invokation_template.yml` and fill in:
+Copy `.agents/skills/j-evaluate/assets/evaluation_invokation_template.yml` and fill in:
 - `paths`: path(s) to the relevant example files
 - `goal`: the confirmed target goal
 

package/skills/j-init/SKILL.md

@@ -101,7 +101,7 @@ run can never silently relocate directories or edit `.gitignore`.
 > `.agents/`/`.claude/` convention), was built and then withdrawn before release —
 > testing found it left board resolution and session-end hooks writing to two
 > different trees. It is not offered here. See
-> `skills/distribute/CONFIG_SCHEMA.md` for the root-cause note and the tracked
+> `skills/j-distribute/CONFIG_SCHEMA.md` for the root-cause note and the tracked
 > follow-up to reintroduce it once fixed.
 
 Carry the chosen value into step 4. Do not apply it yourself — the script owns all
@@ -116,7 +116,7 @@ framework scaffold (skill and agent definitions), which is a separate tree with
 separate lifecycle — it gets overwritten wholesale by every `/distribute` run or npm
 upgrade, unlike `project/`. Kept as its own flag (`scaffold_visibility`) rather than
 folded into `project_files_visibility`'s enum; see
-`skills/distribute/CONFIG_SCHEMA.md`'s "Scaffold visibility" section for the full
+`skills/j-distribute/CONFIG_SCHEMA.md`'s "Scaffold visibility" section for the full
 rationale.
 
 Ask the user this question, verbatim, before running any script:
@@ -195,7 +195,7 @@ run) by the time `/init` runs `git add -A`.
 If the script fails, check that you are in the project root and that git and `jq`
 are available.
 
-See `skills/distribute/CONFIG_SCHEMA.md` for the full `project_files_visibility` and
+See `skills/j-distribute/CONFIG_SCHEMA.md` for the full `project_files_visibility` and
 `scaffold_visibility` field reference.
 
 ### 5. Prompt next step

package/skills/j-init/assets/scope-thresholds_template.json

@@ -1,7 +1,10 @@
 {
-  "threshold_version": 2,
+  "threshold_version": 3,
   "inline_max_files": 3,
   "inline_max_lines": 75,
   "story_max_files": 5,
-  "bundle_lock_ttl_minutes": 30
+  "bundle_lock_ttl_minutes": 30,
+  "max_concurrent_developers": 3,
+  "max_concurrent_testers": 3,
+  "slot_ttl_minutes": 45
 }

package/skills/j-init/scripts/apply-scaffold-visibility.sh

@@ -11,7 +11,7 @@
 # overwritten wholesale by every `/distribute` run or npm upgrade; project/
 # is not). Filed as new, adjacent scope under E31_S07 rather than folded
 # silently into project_files_visibility's existing enum. See
-# skills/distribute/CONFIG_SCHEMA.md's "Scaffold visibility" section for the
+# skills/j-distribute/CONFIG_SCHEMA.md's "Scaffold visibility" section for the
 # full rationale.
 #
 # This is skills/j-init/'s own copy of skills/init/scripts/apply-scaffold-visibility.sh

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

@@ -30,7 +30,7 @@ fi
 # queue/, rapports/, logs/). scaffold_visibility is a distinct, independent
 # flag (E31_S07_T01, ported here in E31_S07_T03) covering the distributed
 # .claude/.agents framework scaffold — kept separate per
-# skills/distribute/CONFIG_SCHEMA.md's "Scaffold visibility" section, rather
+# skills/j-distribute/CONFIG_SCHEMA.md's "Scaffold visibility" section, rather
 # than folded into project_files_visibility's existing enum.
 VISIBILITY="${JENGA_PROJECT_FILES_VISIBILITY:-visible}"
 SCAFFOLD_VISIBILITY="${JENGA_SCAFFOLD_VISIBILITY:-visible}"
@@ -79,7 +79,7 @@ echo "→ Copying test-config.json from template..."
 cp "$ASSETS_DIR/test-config_template.json" project/configs/test-config.json
 
 # ─── 6.5. Create project/configs/scope-thresholds.json ───────────────────────
-# Consumed by skills/jenga (Phase 0) and skills/do (Step 0); both halt if it's
+# Consumed by skills/jenga (Phase 0) and skills/j-do (Step 0); both halt if it's
 # missing, so it must exist immediately after scaffold.
 echo "→ Copying scope-thresholds.json from template..."
 cp "$ASSETS_DIR/scope-thresholds_template.json" project/configs/scope-thresholds.json
@@ -93,7 +93,7 @@ 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`,
+# Consumed by skills/j-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
@@ -138,4 +138,4 @@ git add -A
 git commit -m "init: scaffold project structure and workflow config"
 
 echo ""
-echo "✓ Project scaffold complete."
+echo "✓ Project scaffold complete."

package/skills/j-playbook/SKILL.md

@@ -8,7 +8,7 @@ keywords:
   - execute playbook
 examples:
   - "j.playbook brainstorm-to-mirror"
-  - "run the understand-then-ship playbook"
+  - "run the understand-then-commit playbook"
   - "invoke playbook by id"
 ---
 

package/skills/j-publish/SKILL.md

@@ -265,7 +265,7 @@ Release-note rules:
 - **`--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.
-- **`.publicignore` filtering:** when a repo-root `.publicignore` exists (the blocklist `/mirror-public` also reads), a candidate commit — or a completed task's associated commit(s), matched via the `task(E##_S##_T##):` commit-message convention — is dropped entirely when every changed file it touches is covered by that blocklist. A commit touching a mix of blocked and unblocked files is still logged normally; only full coverage excludes an entry. This exists because `CHANGELOG.md` itself is not blocklisted and ships to the public mirror, so an unfiltered entry referencing a private-only path (e.g. `project/board/`) would leak. Absent `.publicignore`, this is a strict no-op — unchanged from pre-E36_S02_T02 behavior. Matching reuses `skills/mirror-public/scripts/mirror.sh`'s `rsync --exclude-from` evaluation rather than a separate glob implementation, so a path classified "blocked" by `/mirror-public --dry-run` is classified "blocked" here too.
+- **`.publicignore` filtering:** when a repo-root `.publicignore` exists (the blocklist `/mirror-public` also reads), a candidate commit — or a completed task's associated commit(s), matched via the `task(E##_S##_T##):` commit-message convention — is dropped entirely when every changed file it touches is covered by that blocklist. A commit touching a mix of blocked and unblocked files is still logged normally; only full coverage excludes an entry. This exists because `CHANGELOG.md` itself is not blocklisted and ships to the public mirror, so an unfiltered entry referencing a private-only path (e.g. `project/board/`) would leak. Absent `.publicignore`, this is a strict no-op — unchanged from pre-E36_S02_T02 behavior. Matching reuses `skills/j-mirror-public/scripts/mirror.sh`'s `rsync --exclude-from` evaluation rather than a separate glob implementation, so a path classified "blocked" by `/mirror-public --dry-run` is classified "blocked" here too.
 
 ## Ledger & Tagging
 

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

@@ -239,7 +239,12 @@ automated and human halves of the flow:
   relies on the automated CI-staged test result) and then
   `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.
+  side to discard a staged candidate. On success, `approve` also generates
+  release notes into `CHANGELOG.md`'s `[Unreleased]` section and finalizes
+  it with the approved version — the same behavior described in
+  `adapters/npm.md`'s Staged Publishing section, shared by both target
+  types since it lives in `npm_stage_inspect.sh` itself, not in either
+  target-type-specific pipeline (E22_S09_T08).
 - **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`

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

@@ -119,7 +119,7 @@ becomes visible on the registry. See `skills/j-publish/SKILL.md`'s
 
 - `bash skills/j-publish/scripts/npm_stage_pipeline.sh <target> <path-to-publish.json> [--dry-run] [--non-interactive] [--otp <otp>]` runs validate → gates → pack → stage → capture → ledger and writes a `staged` ledger entry.
 - `bash skills/j-publish/scripts/npm_stage_inspect.sh test <stage-id>` installs the staged tarball into an isolated scratch directory and smoke-tests it, writing a `stage_tested` ledger entry.
-- `bash skills/j-publish/scripts/npm_stage_inspect.sh approve <stage-id>` requires an npm 2FA one-time password and refuses without a passing `test` on record unless `--force <reason>` is given.
+- `bash skills/j-publish/scripts/npm_stage_inspect.sh approve <stage-id>` requires an npm 2FA one-time password and refuses without a passing `test` on record unless `--force <reason>` is given. On a successful `npm stage approve`, it also generates release notes into `CHANGELOG.md`'s `[Unreleased]` section and finalizes that section with the approved version — the same `generate_release_notes.sh` + `finalize_changelog.sh` pair `/publish deploy` runs, reused rather than duplicated (E22_S09_T08). `--dry-run` skips this (it exits before the real approve call runs at all); a failed `npm stage approve` skips it too (no changelog write on a failed approve); `--force` still runs it — `--force` only bypasses the passing-test requirement, not the changelog step.
 - `bash skills/j-publish/scripts/npm_stage_inspect.sh reject <stage-id>` discards the staged version.
 
 Same registry-existence precondition as a normal `npm` publish: staged

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

@@ -76,7 +76,7 @@ git rev-parse --verify "$TO_REF" >/dev/null 2>&1 || {
 # Absence of .publicignore is a strict no-op — PI_ACTIVE stays 0 and every
 # _pi_* helper below fails open immediately.
 #
-# Matching semantics are borrowed from skills/mirror-public/scripts/mirror.sh
+# Matching semantics are borrowed from skills/j-mirror-public/scripts/mirror.sh
 # rather than reimplemented: that script's compute_ship_list asks rsync
 # itself "what would transfer past --exclude-from=.publicignore?" and that
 # is the single source of truth /mirror-public --dry-run reports as

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

@@ -86,6 +86,8 @@ fi
 source "${SCRIPT_DIR}/publish_common.sh"
 
 WRITE_LEDGER_SCRIPT="${SCRIPT_DIR}/write_ledger_entry.sh"
+GENERATE_RELEASE_NOTES_SCRIPT="${SCRIPT_DIR}/generate_release_notes.sh"
+FINALIZE_CHANGELOG_SCRIPT="${SCRIPT_DIR}/finalize_changelog.sh"
 
 # ---------------------------------------------------------------------------
 # OTP tracing guard — MUST run at the top level, before `main "$@"` is ever
@@ -397,6 +399,53 @@ _write_stage_tested_ledger() {
   "${cmd[@]}" || log_warn "failed to write 'stage_tested' ledger entry for stage ${stage_id} (result: ${result})"
 }
 
+# _finalize_stage_changelog <target_name> <config_path> <package_version>
+#
+# `approve`'s equivalent of publish_deploy.sh's generate_release_notes() +
+# finalize_changelog() pair (E22_S09_T08) — reused verbatim, not
+# reimplemented. Only ever called AFTER a real `npm stage approve` call has
+# already succeeded, so a failure here never masks (nor is masked by) the
+# approve result itself; the caller decides how to report it.
+#
+# Mirrors publish_deploy.sh's resolve_last_tag(): resolves the last publish
+# tag from the ledger via publish_resolve_last_publish_tag, never a
+# hardcoded/guessed tag. Passes --from-tag only when a tag was actually
+# resolved, and passes the config path positional only when one is
+# resolved -- generate_release_notes.sh treats an omitted config the same
+# way it treats an unresolved one internally (falls back to its own
+# defaults via publish_resolve_history_file "").
+#
+# Uses the already-resolved package_version (from the stage's own `npm
+# stage view` output) for finalize_changelog.sh, per the task's acceptance
+# criteria -- never a re-derived version.
+_finalize_stage_changelog() {
+  local target_name="$1" config_path="$2" package_version="$3"
+  local history_file last_tag
+  local -a notes_cmd=(bash "${GENERATE_RELEASE_NOTES_SCRIPT}" --target "${target_name}")
+
+  history_file="$(publish_resolve_history_file "${config_path}")"
+  last_tag="$(publish_resolve_last_publish_tag "${history_file}" HEAD 2>/dev/null || true)"
+  [[ -n "${last_tag}" ]] && notes_cmd+=(--from-tag "${last_tag}")
+  [[ -n "${config_path}" ]] && notes_cmd+=("${config_path}")
+
+  if ! "${notes_cmd[@]}"; then
+    log_warn "failed to generate release notes for stage approve (target: ${target_name})"
+    return 1
+  fi
+
+  if [[ -z "${package_version}" ]]; then
+    log_warn "no package version resolved from stage view — skipping CHANGELOG.md finalization"
+    return 1
+  fi
+
+  if ! bash "${FINALIZE_CHANGELOG_SCRIPT}" "${package_version}" "${REPO_ROOT}/CHANGELOG.md"; then
+    log_warn "failed to finalize CHANGELOG.md for stage approve (version: ${package_version})"
+    return 1
+  fi
+
+  return 0
+}
+
 # ---------------------------------------------------------------------------
 # list [<package-spec>] [--config <path>] [--dry-run] [--json]
 # ---------------------------------------------------------------------------
@@ -772,6 +821,18 @@ cmd_approve() {
     exit "${EXIT_OP_FAILED}"
   fi
 
+  # Generate release notes into CHANGELOG.md's [Unreleased] section and
+  # stamp it with the approved version — mirroring publish_deploy.sh's own
+  # generate_release_notes() + finalize_changelog() pair (E22_S09_T08).
+  # Only reached after a confirmed successful `npm stage approve` above, so
+  # a failed approve never gets a changelog write, and --force only ever
+  # affects the test-interlock check earlier in this function — this step
+  # runs identically on both the normal and --force paths, no divergent
+  # logic. Never reached at all under --dry-run, which already exited
+  # earlier, before the real approve call.
+  _finalize_stage_changelog "${target_name}" "${config_path}" "${package_version}" \
+    || log_warn "stage ${stage_id} was approved, but CHANGELOG.md was not updated — see warnings above"
+
   local -a ledger_cmd=(bash "${WRITE_LEDGER_SCRIPT}" "${target_name}" "${target_type}" approved "" --stage-id "${stage_id}")
   [[ -n "${config_path}" ]] && ledger_cmd+=(--config "${config_path}")
   [[ -n "${package_version}" ]] && ledger_cmd+=(--version "${package_version}")

package/skills/j-reconcile/SKILL.md

@@ -3,7 +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
+output_types: id_list
 keywords:
   - j-reconcile
   - polyfill
@@ -200,7 +200,7 @@ older conventions still present in this repo's history (`E04_S01: ...` and
 `feat(train): implement E01_S05 - ...`).
 
 The script reuses the board-linkage check from
-`skills/uncharted/scripts/resolve-segment-target.sh` through its batch interface. Do not
+`skills/j-uncharted/scripts/resolve-segment-target.sh` through its batch interface. Do not
 re-derive linkage yourself, and do not substitute a `grep` over `project/board/` if the script
 fails — a second answer to "is this path on the board" is what that reuse exists to prevent.
 If the script exits non-zero, report the failure in the reconcile report and continue to phase 6.