@jenga-ai/agent 1.2.4 → 2.0.0

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

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/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.
+# That is wrong whenever a directory already carries a Jenga scaffold, or
+# already carries substantial application code that predates Jenga entirely
+# -- in the second case, scaffolding fresh produces an empty board and a stub
+# PROJECT_SUMMARY.md that actively misrepresent the project.
+#
+# 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.
+#
+# ---------------------------------------------------------------------------
+# VERDICTS -- exactly one is printed on stdout, nothing else
+# ---------------------------------------------------------------------------
+#   empty               The target is empty, or contains only boilerplate
+#                       that does not count as "there is a project here":
+#                       .git (the directory itself, pruned entirely -- not
+#                       merely excluded by name), .gitignore, and top-level
+#                       README*/LICENSE*/LICENCE* files (case-insensitive),
+#                       plus anything git itself reports as ignored. A repo
+#                       containing only a README is empty for this purpose.
+#   already-scaffolded  The target already carries a Jenga scaffold: any one
+#                       of project/board/, project/PROJECT_SUMMARY.md, or
+#                       project/configs/workflow.json is present. Checked
+#                       BEFORE the emptiness scan, so a scaffolded project
+#                       that also happens to look sparse is never misreported
+#                       as "empty".
+#   existing-codebase   The target has real content (source files, configs,
+#                       docs beyond the boilerplate list above, etc.) and is
+#                       not already Jenga-scaffolded. This is the case /init
+#                       currently mishandles: scaffolding fresh here silently
+#                       discards the fact that pre-existing code exists.
+#
+# ---------------------------------------------------------------------------
+# NOTES ON GITIGNORE HANDLING
+# ---------------------------------------------------------------------------
+# /init runs this check BEFORE `git init` in the fresh-scaffold path, so the
+# target directory is very often not a git work tree yet. Gitignore-based
+# filtering is therefore best-effort: it only runs when the target already
+# has a `.git` directory AND `git` is on PATH. A standalone `.gitignore` file
+# with no repository behind it still counts as boilerplate via the name-based
+# exclusion below -- it just cannot hide any OTHER file, because there is no
+# git to ask "is this ignored".
+#
+# README/LICENSE exclusion applies to TOP-LEVEL entries only. A directory
+# whose only content is a buried `docs/README.md` two levels down is real
+# structure, not boilerplate, and must not be reported as empty.
+#
+# ---------------------------------------------------------------------------
+# Usage
+# ---------------------------------------------------------------------------
+#   detect-existing-codebase.sh [target-dir]
+#
+#   target-dir   Directory to classify. Default: current directory.
+#
+# Options:
+#   -h, --help   Show this help and exit 0.
+#
+# Exit codes:
+#   0   A verdict was printed on stdout.
+#   1   Usage error (unknown option, more than one positional argument).
+#   2   target-dir does not exist or is not a directory.
+#
+# Requires: bash, find. git is used opportunistically for gitignore
+# filtering when the target is already a git work tree; its absence never
+# causes a failure.
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SELF="$(basename "$0")"
+
+usage() {
+  sed -n '/^# Usage$/,/^# Requires:/p' "$0" | sed -e 's/^# \{0,1\}//' -e '/^-\{10,\}$/d'
+}
+
+die_usage() {
+  printf '%s: error: %s\n' "$SELF" "$*" >&2
+  echo >&2
+  usage >&2
+  exit 1
+}
+
+TARGET_DIR="."
+HAVE_TARGET=0
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    --)
+      shift
+      [ "$#" -le 1 ] || die_usage "at most one target directory is allowed"
+      if [ "$#" -eq 1 ]; then TARGET_DIR="$1"; HAVE_TARGET=1; fi
+      shift $#
+      ;;
+    -*)
+      die_usage "unknown option \"$1\"" ;;
+    *)
+      [ "$HAVE_TARGET" -eq 0 ] || die_usage "at most one target directory is allowed (got \"$TARGET_DIR\" and \"$1\")"
+      TARGET_DIR="$1"; HAVE_TARGET=1; shift ;;
+  esac
+done
+
+[ -d "$TARGET_DIR" ] || { printf '%s: error: not a directory: %s\n' "$SELF" "$TARGET_DIR" >&2; exit 2; }
+
+TARGET_DIR="$(cd -- "$TARGET_DIR" && pwd -P)"
+
+# --- already-scaffolded: checked first, independent of emptiness -----------
+if [ -d "$TARGET_DIR/project/board" ] \
+   || [ -f "$TARGET_DIR/project/PROJECT_SUMMARY.md" ] \
+   || [ -f "$TARGET_DIR/project/configs/workflow.json" ]; then
+  echo "already-scaffolded"
+  exit 0
+fi
+
+# --- enumerate candidate files, pruning .git entirely -----------------------
+ALL_FILES=$(mktemp "${TMPDIR:-/tmp}/detect-existing-codebase.XXXXXX")
+IGNORED_FILES=$(mktemp "${TMPDIR:-/tmp}/detect-existing-codebase-ignored.XXXXXX")
+cleanup() { rm -f "$ALL_FILES" "$IGNORED_FILES"; }
+trap cleanup EXIT
+
+find "$TARGET_DIR" -path "$TARGET_DIR/.git" -prune -o -type f -print > "$ALL_FILES"
+
+# --- best-effort gitignore filtering ----------------------------------------
+: > "$IGNORED_FILES"
+if [ -d "$TARGET_DIR/.git" ] && command -v git >/dev/null 2>&1; then
+  git -C "$TARGET_DIR" check-ignore --stdin < "$ALL_FILES" > "$IGNORED_FILES" 2>/dev/null || true
+fi
+
+# --- classify each candidate -------------------------------------------------
+SOURCE_FOUND=0
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+
+  if [ -s "$IGNORED_FILES" ] && grep -Fxq -- "$f" "$IGNORED_FILES"; then
+    continue
+  fi
+
+  rel="${f#"$TARGET_DIR"/}"
+  base="$(basename -- "$f")"
+  dir_rel="$(dirname -- "$rel")"
+
+  if [ "$dir_rel" = "." ]; then
+    if [ "$base" = ".gitignore" ]; then
+      continue
+    fi
+    base_upper="$(printf '%s' "$base" | tr '[:lower:]' '[:upper:]')"
+    case "$base_upper" in
+      README*|LICENSE*|LICENCE*) continue ;;
+    esac
+  fi
+
+  SOURCE_FOUND=1
+  break
+done < "$ALL_FILES"
+
+if [ "$SOURCE_FOUND" -eq 1 ]; then
+  echo "existing-codebase"
+else
+  echo "empty"
+fi

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

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ASSETS_DIR="$SCRIPT_DIR/../assets"
+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/)
+# 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
+# templates/ and lib/ three levels up. Consumers instead have them inside the
+# installed npm package.
+if [[ -d "$SCRIPT_DIR/../../../templates" ]]; then
+  PKG_ROOT="$SCRIPT_DIR/../../.."
+elif [[ -d "$PWD/node_modules/@jenga-ai/agent/templates" ]]; then
+  PKG_ROOT="$PWD/node_modules/@jenga-ai/agent"
+else
+  echo "Error: could not locate the jenga-agent package root (templates/ not found via monorepo checkout or node_modules/@jenga-ai/agent)." >&2
+  exit 1
+fi
+
+# ─── 0. Resolve project_files_visibility ─────────────────────────────────────
+# Defaults to `visible` — the only value that touches nothing on disk — so an
+# unattended run can never silently relocate directories or edit .gitignore.
+VISIBILITY="${JENGA_PROJECT_FILES_VISIBILITY:-visible}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --visibility)   VISIBILITY="${2:-}"; shift 2 ;;
+    --visibility=*) VISIBILITY="${1#*=}"; shift ;;
+    *) echo "Unknown argument: $1" >&2
+       echo "Usage: $(basename "$0") [--visibility <visible|ignored>]" >&2
+       exit 1 ;;
+  esac
+done
+
+# Validate before scaffolding so a typo cannot leave a half-initialised project.
+bash "$VISIBILITY_SCRIPT" --check-only "$VISIBILITY"
+
+# ─── 1. Initialize git repository ────────────────────────────────────────────
+echo "→ Initializing git repository..."
+git init
+
+# ─── 2. Create .gitignore ─────────────────────────────────────────────────────
+echo "→ Copying .gitignore from template..."
+cp "$ASSETS_DIR/.gitignore_template" .gitignore
+
+# ─── 3. Scaffold directory structure ──────────────────────────────────────────
+echo "→ Scaffolding directory structure..."
+while IFS= read -r dir || [[ -n "$dir" ]]; do
+  [[ -z "$dir" || "$dir" == \#* ]] && continue
+  mkdir -p "$dir"
+done < "$ASSETS_DIR/directory_structure.txt"
+
+# ─── 4. Create project/PROJECT_SUMMARY.md ────────────────────────────────────
+echo "→ Copying PROJECT_SUMMARY.md from template..."
+cp "$ASSETS_DIR/PROJECT_SUMMARY_template.md" project/PROJECT_SUMMARY.md
+
+# ─── 5. Create project/configs/workflow.json ─────────────────────────────────
+echo "→ Copying workflow.json from template..."
+cp "$ASSETS_DIR/workflow_template.json" project/configs/workflow.json
+
+# ─── 6. Create project/configs/test-config.json stub ─────────────────────────
+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
+# 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
+
+# ─── 7. Create project/data/baselines.json ───────────────────────────────────
+echo "→ Creating baselines.json..."
+echo '{}' > project/data/baselines.json
+
+# ─── 8. Create project/logs/events.json ──────────────────────────────────────
+echo "→ Creating events.json..."
+echo '[]' > project/logs/events.json
+
+# ─── 9. Create docs/STRATEGY.md ──────────────────────────────────────────────
+echo "→ Creating docs/STRATEGY.md (strategic brief for investors, partners, and the product team)..."
+mkdir -p docs
+cp "$ASSETS_DIR/strategy_stub_template.md" docs/STRATEGY.md
+
+# ─── 10. Create CHANGELOG.md ──────────────────────────────────────────────────
+echo "→ Creating CHANGELOG.md from template..."
+cp "$PKG_ROOT/templates/CHANGELOG_TEMPLATE.md" CHANGELOG.md
+
+# ─── 11. Apply project_files_visibility ──────────────────────────────────────
+# Runs before the commit so the .gitignore entry (ignored) is captured in the
+# initial commit.
+echo "→ Applying project files visibility ($VISIBILITY)..."
+bash "$VISIBILITY_SCRIPT" "$VISIBILITY" "$PWD"
+
+# ─── 12. Generate CLAUDE.md / AGENTS.md ──────────────────────────────────────
+# Unconditional — never gated on agentTarget (E41_S04). Applies the J-
+# collision rule and idempotent managed-block updates; see
+# lib/generate-agent-context.js (shared with the published `jenga init` CLI).
+echo "→ Generating CLAUDE.md / AGENTS.md..."
+if command -v node >/dev/null 2>&1; then
+  node "$PKG_ROOT/lib/generate-agent-context.js" "$PWD"
+else
+  echo "  Warning: node not found — skipped CLAUDE.md/AGENTS.md generation." >&2
+fi
+
+# ─── 13. Initial commit ──────────────────────────────────────────────────────
+echo "→ Staging and committing scaffolded files..."
+git add -A
+git commit -m "init: scaffold project structure and workflow config"
+
+echo ""
+echo "✓ Project scaffold complete."

package/skills/jbp/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: jbp
+name: j:jbp
 description: Scaffold the project using the JengaBasePlate boilerplate repo template from https://github.com/samwelmunga/JengaBasePlate.git
 keywords:
   - jbp

package/skills/jenga/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: jenga
+name: j:jenga
 description: Interactive-by-default board orchestrator with a fully automated escape hatch. Bare `/jenga` renders a picker and confirmation tree before scoping the run; `/jenga <ids>` resolves an explicit fuzzy-ID scope and confirms it; `/jenga *` reproduces the original zero-prompt behavior — decomposing any unbroken Epics into Stories, any unbroken Stories into Tasks, queuing all unqueued Tasks into todo.md, then executing every eligible item with no user prompts — until the board is fully started.
 keywords:
   - jenga

package/skills/jenga/scripts/render-confirmation.sh

@@ -97,12 +97,18 @@
 # ENTIRE turn is rejected as an error turn (state left untouched) — there
 # is no partial application of the valid numbers in a mixed-validity reply.
 #
-# Toggling is NOT cascading: unchecking a parent epic/story does not
-# automatically uncheck its children, and vice versa. Each displayed
-# number is an independent checkbox. This is a deliberate simplicity
-# choice — the task only requires "uncheck or re-check individual
-# presented items", not cascading selection logic (that expansion/cascade
-# concern already belongs to cascade-resolve.sh, per its own header).
+# Toggling CASCADES downward (E45_S02_T03): checking or unchecking a
+# story applies the same resulting state to all of its tasks; checking or
+# unchecking an epic applies the same resulting state to all of its
+# stories and their tasks. This is a deliberate, explicit reversal of the
+# original non-cascading design (see this story's 2026-08-27 close-out) —
+# the user hit a real case where unchecking a parent epic left its child
+# story/tasks checked, requiring a manual follow-up uncheck command.
+# Cascade is STRICTLY DOWNWARD (parent -> descendants) only: checking a
+# leaf task does NOT imply its ancestors should also be checked, so a
+# checked child under an unchecked parent is a valid (if visually
+# inconsistent) state. Toggling a leaf task (no children) behaves exactly
+# as it always has — no descendants to cascade into.
 #
 # ---------------------------------------------------------------------------
 # OUTPUT CONTRACT (deliberately NOT uniform JSON — see rationale below)
@@ -165,8 +171,15 @@
 # STATE FILE
 # ---------------------------------------------------------------------------
 # Created under `mktemp -t jenga-confirm-XXXXXX.json`. Stores:
-#   - `numbering`: displayed number -> {item, level, checked} — the ONLY
-#     field that mutates across turns is `checked`.
+#   - `numbering`: displayed number -> {item, level, checked, children} —
+#     `children` is a fixed list of the item's direct descendant numbers
+#     (a story's task numbers; an epic's story numbers), computed once at
+#     build time so continue-mode can cascade a toggle without
+#     re-deriving parent/child relationships from `item_id`/`epic_id`/
+#     `story_id` at toggle time. `children` is always `[]` for a leaf
+#     task. The only fields that mutate across turns are `checked` values
+#     (potentially many at once, via cascade — see TOGGLE COMMAND GRAMMAR
+#     above).
 #   - `layout`: the fixed print order (item lines + header markers),
 #     computed once at start. Continue mode never recomputes tree shape —
 #     it only re-renders from `layout` + the live `checked` flags in
@@ -305,15 +318,17 @@ def pluralize_task(n):
     return f"{n} task{'' if n == 1 else 's'}"
 
 
-def add_item(item, level, indent):
+def add_item(item, level, indent, parent_number=None):
     global counter
     n = str(counter)
     counter += 1
     suffix = ""
     if item.get("id") in undecomposed_ids:
         suffix = "  [needs decomposition -- no children on the board yet]"
-    numbering[n] = {"item": item, "level": level, "checked": True}
+    numbering[n] = {"item": item, "level": level, "checked": True, "children": []}
     layout.append({"kind": "item", "number": n, "level": level, "indent": indent, "suffix": suffix})
+    if parent_number is not None:
+        numbering[parent_number]["children"].append(n)
     return n
 
 
@@ -328,7 +343,7 @@ def append_suffix(extra):
 
 
 for e in epics:
-    add_item(e, "epic", INDENT["epic"])
+    e_num = add_item(e, "epic", INDENT["epic"])
     child_stories = stories_by_epic.get(e["id"], [])
     story_count = len(child_stories)
     task_count = sum(len(tasks_by_story.get(s["id"], [])) for s in child_stories)
@@ -340,23 +355,23 @@ for e in epics:
     append_suffix(", ".join(parts))
 
     for s in child_stories:
-        add_item(s, "story", INDENT["story"])
+        s_num = add_item(s, "story", INDENT["story"], parent_number=e_num)
         child_tasks = tasks_by_story.get(s["id"], [])
         if child_tasks:
             append_suffix(pluralize_task(len(child_tasks)))
         for t in child_tasks:
-            add_item(t, "task", INDENT["task"])
+            add_item(t, "task", INDENT["task"], parent_number=s_num)
 
 if orphan_stories:
     layout.append({"kind": "header", "text": ""})
     layout.append({"kind": "header", "text": "-- Directly Selected Stories (no epic in this selection) --"})
     for s in orphan_stories:
-        add_item(s, "story", INDENT["story"])
+        s_num = add_item(s, "story", INDENT["story"])
         child_tasks = tasks_by_story.get(s["id"], [])
         if child_tasks:
             append_suffix(pluralize_task(len(child_tasks)))
         for t in child_tasks:
-            add_item(t, "task", INDENT["task"])
+            add_item(t, "task", INDENT["task"], parent_number=s_num)
 
 if orphan_tasks:
     layout.append({"kind": "header", "text": ""})
@@ -644,18 +659,40 @@ if invalid:
     print(f"STATE_FILE: {state_file_path}", file=sys.stderr)
     sys.exit(1)
 
+def apply_cascade(num, value):
+    """Set `num`'s checked state to `value`, then recurse into every
+    number in its `children` list (a story's tasks; an epic's stories,
+    which recurse further into their own tasks). Strictly downward —
+    never touches a parent. A leaf task has an empty `children` list, so
+    this degenerates to exactly the old single-flag assignment for the
+    non-cascading base case."""
+    numbering[num]["checked"] = value
+    for child in numbering[num].get("children", []):
+        apply_cascade(child, value)
+
+
 # All-or-nothing application, de-duplicated (first-seen wins on dupes).
+# Resulting values are computed from PRE-mutation state in a first pass,
+# then applied (with cascade) in a second pass -- this avoids a
+# parent-then-child (or child-then-parent) double-toggle artifact when a
+# single reply lists both a parent and one of its own descendants, e.g.
+# bare-number toggle "5,6" where 6 is a child of 5.
 seen = set()
+pending = []
 for tok in valid_tokens:
     if tok in seen:
         continue
     seen.add(tok)
     if action == "check":
-        numbering[tok]["checked"] = True
+        value = True
     elif action == "uncheck":
-        numbering[tok]["checked"] = False
+        value = False
     else:
-        numbering[tok]["checked"] = not numbering[tok]["checked"]
+        value = not numbering[tok]["checked"]
+    pending.append((tok, value))
+
+for tok, value in pending:
+    apply_cascade(tok, value)
 
 state["numbering"] = numbering
 with open(state_file_path, "w", encoding="utf-8") as f:

package/skills/jenga-permission-level/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: jenga-permission-level
+name: j:jenga-permission-level
 description: Report or switch the current session's 5-tier permission level (Locked/Guarded/Standard/Elevated/Unrestricted) without hand-editing settings.json.
 keywords:
   - "permission level"

package/skills/lgtm/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: lgtm
+name: j:lgtm
 description: Approve and commit the current work, then continue to the next task. Shortcut that chains /commit followed by /continue.
 keywords:
   - lgtm

package/skills/pi-plan/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pi-plan
+name: j:pi-plan
 description: Define or expand project Epics in PROJECT_SUMMARY.md. Use this at the start of a project to establish its foundation, AND whenever the user wants to add major new features, plan a significant new area of work, or make epic-level changes to an existing project. Trigger whenever you hear things like "new feature area", "big change", "new epic", "expand the project", "add a major capability", or "plan a new phase" — even mid-project.
 keywords:
   - epic

package/skills/proceed/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: proceed
+name: j:proceed
 description: Review project progress by checking epics and stories, optionally consulting PROJECT_SUMMARY.md and WARP.md, then continue executing the project plan.
 keywords:
   - proceed

package/skills/publish/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: publish
+name: j:publish
 description: Configure, validate, and orchestrate scaffolded release workflows through a single `/publish` entry point with bounded sub-commands.
 keywords:
   - publish
@@ -9,6 +9,8 @@ keywords:
   - npm
   - registry
   - release notes
+  - staged publishing
+  - stage
 examples:
   - "publish setup --target staging-appstore"
   - "publish setup --type mobile-ios"
@@ -21,6 +23,9 @@ examples:
   - "publish deploy --target my-droplet --dry-run"
   - "publish history --limit 5"
   - "publish release-notes --target staging-appstore"
+  - "test a release before publishing"
+  - "publish stage --target npm-registry --dry-run"
+  - "approve a staged npm release"
 metadata:
   scope: multi-target-v2
   primary_target: multi
@@ -76,6 +81,7 @@ If config or env validation fails, the skill exits with code `4` and does not co
 |---|---|---|---|
 | `/publish setup` | Prepare or refresh target configuration | `skills/publish/scripts/setup_wizard.sh` | Supported types: `mobile-ios`, `npm`, `npm-ci`, `droplet` |
 | `/publish deploy` | Run the full 11-step deploy orchestration | `skills/publish/scripts/publish_deploy.sh` | Dispatches to the adapter for the target's `type` (`mobile-ios`, `npm`, `npm-ci`, or `droplet`); `--dry-run` is honoured end-to-end |
+| `/publish stage` | Stage an npm release into npm's staged-publishing area, smoke-test it in isolation, then approve or reject it | `skills/publish/scripts/npm_stage_pipeline.sh` (the `publish` sub-command) and `skills/publish/scripts/npm_stage_inspect.sh` (`list`, `view`, `download`, `test`, `approve`, `reject`) | Supported for `npm` and `npm-ci` target types only |
 | `/publish history` | Read the canonical publish ledger | `skills/publish/scripts/show_history.sh` | Target-agnostic; filter by `--target <name>` |
 | `/publish release-notes` | Merge new release notes into the standing `CHANGELOG.md` (or a standalone draft via `--output`) without publishing | `skills/publish/scripts/generate_release_notes.sh` | Target-agnostic |
 
@@ -170,6 +176,66 @@ Example invocations:
 
 Use `--dry-run` to rehearse a release, validate that gates pass, and confirm the generated release notes without publishing.
 
+### `/publish stage`
+
+Staged publishing for `npm`/`npm-ci` targets only. Not available for
+`mobile-ios` or `droplet` — those adapters have no staging area to dispatch
+to. The lifecycle is **stage → test → approve**, with `reject` as the
+discard path at any point after staging:
+
+```text
+staged ──▶ stage_tested ──▶ approved   (approve requires 2FA; refuses without
+   │             │                      a passing test unless --force <reason>)
+   │             │
+   └─────────────┴──▶ rejected   (discard path — available from any staged state)
+```
+
+Two registry constraints trip people up and are worth stating plainly:
+
+- **The package must already exist on the registry.** npm's staged-publishing
+  workflow only applies to a package that has had at least one normal,
+  non-staged publish already — `validate_npm_stage_env.sh` checks this
+  up front and exits `4` if it doesn't hold.
+- **Approval requires 2FA; staging does not.** `npm stage publish` (the
+  `stage` sub-command below) can run non-interactively in CI. `npm stage
+  approve` cannot — npmjs.com requires an interactive one-time-password
+  step for approval, so it is always a human action even when staging was
+  automated (see the npm-ci adapter's OIDC staging section for the CI-stage,
+  human-approve split).
+
+All seven sub-commands:
+
+```text
+/publish stage publish <target> <path-to-publish.json> [--dry-run] [--non-interactive] [--otp <otp>]
+/publish stage test <stage-id> [--keep] [--config <path>] [--dry-run] [--json]
+/publish stage list [<package-spec>] [--config <path>] [--dry-run] [--json]
+/publish stage view <stage-id> [--config <path>] [--dry-run] [--json]
+/publish stage download <stage-id> [--out <dir>] [--config <path>] [--dry-run] [--json]
+/publish stage approve <stage-id> [--otp <otp>] [--force <reason>] [--config <path>] [--dry-run] [--json]
+/publish stage reject <stage-id> [--config <path>] [--dry-run] [--json]
+```
+
+Implementation:
+
+- `publish` → `bash skills/publish/scripts/npm_stage_pipeline.sh <target> <path-to-publish.json> [--dry-run] [--non-interactive] [--otp <otp>]` — six ordered phases (validate, gates, pack, stage, capture, ledger); writes a `staged` ledger entry on success.
+- `test`, `list`, `view`, `download`, `approve`, `reject` → `bash skills/publish/scripts/npm_stage_inspect.sh <sub> [args] [--config <path>] [--dry-run] [--json]`
+  - `test` downloads the exact staged tarball into an isolated scratch directory outside the repo, installs it, runs the target's `npm.stage.smoke_cmd` (or the documented default check), and writes a `stage_tested` ledger entry (`pass`/`fail`).
+  - `approve` refuses to run unless a passing `test` is on record for that exact stage id, unless `--force <reason>` is given; writes an `approved` ledger entry.
+  - `reject` is the discard path omitted from npm's own staged-publishing docs page — documented here so it stays discoverable; writes a `rejected` ledger entry.
+
+Example invocations:
+
+```bash
+/publish stage publish npm-registry ./publish.json --dry-run
+/publish stage test <stage-id>
+/publish stage approve <stage-id>
+/publish stage reject <stage-id>
+```
+
+Use `/publish stage` to rehearse and smoke-test a release before it goes
+live — the point of staging is that a bad tarball is caught in isolation
+instead of being caught by users after `npm publish`.
+
 ### `/publish history`
 
 ```text

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

@@ -99,11 +99,33 @@ Run the adapter phases in this exact order:
    ```yaml
    permissions:
      id-token: write
-     contents: read
+     contents: write
    ```
-   and runs `npm publish --provenance` to attach a build provenance attestation
-   to the published package. In `--dry-run` mode, print the rendered YAML to
-   stdout and exit 0 without writing any file.
+   (`contents: write` — bumped from `read` — is required so the `publish` and
+   `stage` jobs can push the tags described below; this is the CI's own token
+   gaining write access to tag *its own* repository, nothing else, and no new
+   secret or credential is introduced) and runs `npm publish --provenance` to
+   attach a build provenance attestation to the published package. In
+   `--dry-run` mode, print the rendered YAML to stdout and exit 0 without
+   writing any file.
+
+   Each job also gains a final step, gated on `if: success()` so a failed
+   publish/stage never creates or moves a tag:
+   - **`publish` job — "Tag prod release and remove stage tag":** reads the
+     version from `package.json`, tags the checked-out commit `v<version>`
+     (no force — this tag is immutable; a genuine collision fails loudly
+     rather than silently moving a prod tag), pushes it, then best-effort
+     deletes the corresponding `v<version>-stage` tag both locally and on the
+     remote (tolerating its absence, e.g. a prod publish that skipped
+     staging).
+   - **`stage` job — "Tag stage release":** reads the version the same way
+     and tags the checked-out commit `v<version>-stage` — a **mutable**
+     pointer, force-created (`git tag -f`) and force-pushed, so re-staging the
+     same version moves the tag rather than failing.
+
+   Both new steps configure a `github-actions[bot]` git identity
+   (`user.name`/`user.email`) before tagging, since no prior step in the
+   workflow sets one.
 
 3. **`commit-workflow`** — write the generated YAML to `<workflow_path>`
    (creating the `.github/workflows/` directory if needed) and commit it with:
@@ -190,6 +212,40 @@ A successful non-dry-run produces:
 - A history entry in `project/logs/publish-history.json` written by
   `publish_deploy.sh` with `platform_state: "triggered"`
 
+## Staged Publishing
+
+This target type also supports **staged publishing** via `/publish stage` —
+npm's pre-publish staging area — with an OIDC-specific split between the
+automated and human halves of the flow:
+
+- **The actual `npm stage publish --provenance` call always runs inside
+  GitHub Actions, never on a local machine.** For `npm-ci` targets, phase 4
+  of `npm_stage_pipeline.sh` (run locally via `/publish stage publish`)
+  dispatches the `stage` job of the target's generated workflow (the same
+  `<workflow_path>` / OIDC Trusted Publisher link `npm_ci_pipeline.sh` uses
+  for `/publish deploy`, generated with a `mode: publish | stage`
+  `workflow_dispatch` input) via
+  `gh workflow run <workflow_filename> --repo <github_repo> -f mode=stage`,
+  then blocks on `gh run watch` until that run finishes. The `stage` job
+  itself runs a plain `npm stage publish --provenance --access <access>
+  --tag <dist_tag>` step, authorised through the same Trusted Publisher OIDC
+  link described above — no `NPM_TOKEN` is needed to stage, exactly as none
+  is needed to publish. Local `--dry-run` only prints the `gh workflow run`
+  command that would be dispatched; it never triggers a workflow run.
+- **Approval is always a human, out-of-CI step.** `npm stage approve`
+  requires an interactive npm 2FA one-time password — there is no OIDC
+  equivalent for approval. A human runs
+  `bash skills/publish/scripts/npm_stage_inspect.sh test <stage-id>` (or
+  relies on the automated CI-staged test result) and then
+  `bash skills/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.
+
+Same registry-existence precondition as a normal `npm-ci` deploy: staged
+publishing only applies to a package that has already had at least one
+non-staged publish (`validate_npm_stage_env.sh` checks this up front, exit
+`4` if not).
+
 ## Post-deploy manual steps
 
 After a successful deploy trigger, the adapter prints the workflow run URL.