@jenga-ai/agent 1.2.4 → 1.3.0

package/README.md

@@ -228,6 +228,7 @@ Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `/<name>` in your A
 | `/do` | Execute tasks from the scrum board, drives the Developer agent through the full loop |
 | `/dooo` | Parallel execution orchestrator — runs multiple tasks simultaneously via sub-agents |
 | `/redo` | Rework a previous implementation by commit SHA or Epic/Story number |
+| `/publish` | Configure, validate, and orchestrate scaffolded release workflows — `setup`, `deploy`, `stage` (npm/npm-ci pre-approval staged publishing), `history`, `release-notes` |
 | `/error` | Guided troubleshooting — gathers context, investigates, and drives a fix |
 | `/train` | Scaffold and run ML training jobs (new job from template or run existing) |
 

package/agents/developer.md

@@ -287,6 +287,24 @@ See `templates/PROBLEM_RAPPORT_TEMPLATE.md` for the required format. Commit the
 
 ---
 
+## Investigative Mode
+
+**Trigger.** You are sometimes dispatched not to implement a task, but purely to build understanding of existing code — e.g. by the scrum-master during `/uncharted`'s conversational architecture elicitation, when it needs to know what a named flow or target actually does before proposing graph nodes or asking the user to confirm/correct an understanding. This is a distinct dispatch mode from the standard Task Intake flow above, and it is recognized by the request itself (you are asked to *trace* or *investigate*, not to *implement*), not by any board field.
+
+**Hard constraints.** Investigative Mode is strictly read-only:
+- No worktree is created for write purposes, no application code is written or modified, no dependency installs or generated artifacts.
+- No commits of any kind.
+- No board status writes — task/story/epic status is the tester's exclusive responsibility, and Investigative Mode doesn't touch the board at all, not even a status you'd normally be permitted to leave alone.
+- No edits to `PROJECT_SUMMARY.md`, board files, or any other project artifact. The only output is the trace itself, returned to whoever dispatched you.
+
+**Sandbox — reuse the existing worktree hooks, read-only.** Per the story decision behind this mode (see `project/documentation/plans/uncharted-interactive-elicitation.md` and its solution assessment, Problem 7 / Solution A), do not invent a new isolation mechanism. Mount a throwaway worktree via the same `WorktreeCreate` hook used for normal tasks (see Worktree Management above) purely to get a disposable, isolated checkout to read from, and tear it down via `WorktreeRemove` once the investigation ends. This is convention-enforced, not filesystem-enforced: the hook mounts an ordinary writable worktree, and it is Investigative Mode's contract — not a permission bit — that keeps it read-only. Treat any temptation to write into that worktree (a scratch file, a quick local test run) as a violation of the mode, not a harmless side effect.
+
+**What you trace.** For the named flow or target, follow what the code actually does: call paths, data flow, key decision points, error handling, and any conditions or configuration that change the behavior. Report this in plain language back to the dispatcher — this is not a new artifact type and is not written to disk as part of Investigative Mode itself; if the dispatching flow later decides the finding is worth persisting, that happens through its own normal mechanism (e.g. a graph write or a summary doc), not through you.
+
+**Human-oracle-availability limitation.** For genuinely undocumented code, there is often no reliable code-level way to confirm what was *intended* — only what currently happens. Naming conventions can mislead, a branch that looks dead may be load-bearing for a caller you haven't found, and "this must be for X" is a guess dressed as a finding. When you hit this wall, say so explicitly — report the uncertainty, name what you did and didn't check, and stop short of presenting a guess as a settled fact. This is an accepted, standing limitation of the mode, not something to engineer around by fabricating confidence.
+
+---
+
 ## Hooks
 
 Defined in agent frontmatter:

package/agents/scrum-master.md

@@ -76,6 +76,7 @@ This is a self-contained procedure, not a session-start-only step. It may be inv
        6. **This is the only path** by which a mid-task agent request results in a `crucial_level` board write. Developer and tester never write `crucial_level`, `crucial_set_by`, or `crucial_note` directly to a board file themselves under any circumstance — they may only *request* the change via a `crucial_escalation` rapport, and the actual frontmatter write happens here, exclusively by scrum-master, closing the loop described in E39's Purpose section ("the actual frontmatter write still goes through scrum-master, never the subagent itself").
    - `status_review`: Review the scrum board for any tasks or stories whose status should be updated based on recent activity.
    - `story_rollup`: Check all tasks under the referenced story; if all are `Passed` or `Passed with remarks`, update the story status to `Passed` (or `Passed with remarks` if any remark exists). Then check epic rollup (see Rollup Logic).
+   - `elicitation_resume`: A `/uncharted` conversational architecture elicitation session (`onboard`'s default flow, or `segment --mode investigate` — E20_S08_T03) ended mid-run without converging. Read `state_file` (`project/queue/elicitation-state/<elicitation_id>.json`, written by `skills/uncharted/scripts/elicitation-state.sh`) to see exactly where it left off — which nodes already converged, which are still pending or flagged, and any directory-triage/checkpoint data already confirmed — then resume the conversational flow documented in `skills/uncharted/SKILL.md`'s Multi-Session Persistence subsection from that point rather than restarting the elicitation from scratch. If the state file is missing or unreadable, report that to the user rather than silently starting a fresh elicitation under the same id.
    - After processing all triggers, **clear the file** by writing an empty file — do not leave processed triggers.
 
 2. **Check `project/queue/project_summary_updates.jsonl`** — If non-empty, review each proposed update and apply, revise, or reject it with a short note. Clear the file after processing.

package/agents/tester.md

@@ -407,6 +407,24 @@ There is no default analytics run. Analytics only happen when explicitly scoped
 
 ---
 
+## Investigative Mode
+
+**Trigger.** You are sometimes dispatched not to validate a task's implementation, but purely to build understanding of what the existing test suite actually covers for a named flow or target — e.g. by the scrum-master during `/uncharted`'s conversational architecture elicitation, alongside the developer's Investigative Mode pass over the same flow. This is a distinct dispatch mode from the standard Sender Object / Task Intake / Status Management flow above, recognized by the request itself (you are asked to *trace coverage*, not to *validate a task*), not by any board field.
+
+**Hard constraints.** Investigative Mode is strictly read-only:
+- No worktree is created for write purposes, no test files are written or modified, no test runs that mutate state, no dependency installs.
+- No commits of any kind.
+- No board status writes — this mode doesn't touch task/story/epic status at all, even though status writes are ordinarily your exclusive responsibility.
+- No edits to `PROJECT_SUMMARY.md`, board files, or any other project artifact. The only output is the trace itself, returned to whoever dispatched you.
+
+**Sandbox — reuse the existing worktree hooks, read-only.** Per the story decision behind this mode (see `project/documentation/plans/uncharted-interactive-elicitation.md` and its solution assessment, Problem 7 / Solution A), do not invent a new isolation mechanism. Mount a throwaway worktree via the same `WorktreeCreate` hook the developer agent uses for normal tasks, purely to get a disposable, isolated checkout to read from, and tear it down via `WorktreeRemove` once the investigation ends. This is convention-enforced, not filesystem-enforced: the hook mounts an ordinary writable worktree, and it is Investigative Mode's contract — not a permission bit — that keeps it read-only. Do not execute the test suite in a way that writes fixtures, snapshots, or coverage artifacts back into that worktree; reading existing test files and existing coverage output (if already present) is the mode's ceiling.
+
+**What you trace — the distinct vantage point.** Where the developer's Investigative Mode pass traces what the code *does*, yours traces what the test suite *actually exercises and verifies* for that same flow: which tests touch it, what they assert (and what they merely execute without asserting), and where the coverage gap is — untested branches, unasserted side effects, error paths with no test at all, or a flow that "passes" only because nothing checks the part that matters. These are two distinct vantage points on the same flow, not two names for the same read; do not simply restate the developer's trace with "and there's a test for it" appended.
+
+**Human-oracle-availability limitation.** The same limitation the developer faces applies to you, with an added facet: a passing test suite doesn't clarify intent either — a test can be green because it correctly verifies the right behavior, or green because it asserts nothing meaningful, and the test's own docstring or name can be as misleading as the code's. When you cannot determine from the tests (or their absence) what the intended behavior actually is, say so explicitly — report the uncertainty and the specific gap you couldn't close, rather than presenting a guess as a settled coverage verdict. This is an accepted, standing limitation of the mode, not something to engineer around by fabricating confidence.
+
+---
+
 ## Hooks
 
 Defined in agent frontmatter:

package/hooks/on_session_end.sh

@@ -308,6 +308,33 @@ for HANDOFF_FILE in "$HANDOFF_DIR"/*.json; do
         echo "$TRIGGER" >> "$DEV_QUEUE"
         echo "[on_session_end] scrum-master → developer queue: implementation_assignment"
       fi
+
+      # A conversational architecture elicitation session (/uncharted
+      # onboard's default flow, or segment --mode investigate — E20_S08_T03)
+      # ended mid-run without converging. The session driving it is
+      # responsible for calling skills/uncharted/scripts/elicitation-state.sh
+      # pause and then writing this handoff with status "elicitation_paused"
+      # as its last action (see skills/uncharted/SKILL.md's Multi-Session
+      # Persistence subsection). This routes that pause into a resume
+      # signal for the next scrum-master session, per the existing
+      # SessionEnd/queue pattern rather than a new persistence mechanism
+      # (solution-assessment-uncharted-interactive-elicitation.md, Problem 11).
+      if [ "$HANDOFF_STATUS" = "elicitation_paused" ]; then
+        TRIGGER=$(jq -n \
+          --slurpfile h "$HANDOFF_FILE" \
+          --arg type "elicitation_resume" \
+          --arg date "$TIMESTAMP" \
+          '{
+            type: $type,
+            date: $date,
+            sender: { agent: "scrum-master", session_id: $h[0].session_id, date: $date },
+            elicitation_id: ($h[0].elicitation_id // ""),
+            state_file:     ($h[0].state_file     // ""),
+            message: "A conversational architecture elicitation session paused mid-run. Resume it from the persisted state file."
+          }')
+        echo "$TRIGGER" >> "$QUEUE_FILE"
+        echo "[on_session_end] scrum-master (elicitation_paused) → scrum-master queue: elicitation_resume"
+      fi
       ;;
 
     developer)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "Structured multi-agent development workflow for AI coding agents — scrum board, role-bounded scrum master / developer / tester agents, and 30+ slash-command skills. Works with Claude Code, GitHub Copilot, and Codex.",
   "type": "module",
   "publishConfig": {
@@ -16,12 +16,12 @@
     "postinstall": "node scripts/postinstall.js",
     "test": "bats tests/*.bats",
     "validate:npm-metadata": "bash scripts/validate_npm_metadata.sh",
-    "ui:dev": "npm run ui:dev --prefix project/app",
-    "ui:build": "npm run ui:build --prefix project/app",
-    "api:start": "npm run api:start --prefix project/app",
-    "api:dev": "npm run api:dev --prefix project/app",
-    "dashboard:start": "npm run dashboard:start --prefix project/app",
-    "dashboard:open": "npm run dashboard:open --prefix project/app"
+    "ui:dev": "npm run ui:dev --prefix project/app --",
+    "ui:build": "npm run ui:build --prefix project/app --",
+    "api:start": "npm run api:start --prefix project/app --",
+    "api:dev": "npm run api:dev --prefix project/app --",
+    "dashboard:start": "npm run dashboard:start --prefix project/app --",
+    "dashboard:open": "npm run dashboard:open --prefix project/app --"
   },
   "files": [
     "skills/",
@@ -31,7 +31,17 @@
     "templates/",
     "bin/",
     "lib/",
-    "mcp/",
+    "mcp/execute-ticket/*.js",
+    "mcp/execute-ticket/package.json",
+    "mcp/help/*.js",
+    "mcp/help/package.json",
+    "mcp/router/*.js",
+    "mcp/router/package.json",
+    "mcp/router/package-lock.json",
+    "mcp/router/README.md",
+    "mcp/training_runner/*.js",
+    "mcp/training_runner/package.json",
+    "mcp/training_runner/package-lock.json",
     "README.md",
     "LICENSE"
   ],
@@ -67,15 +77,6 @@
     "url": "https://knappkod.se/jenga-ai"
   },
   "license": "MIT",
-  "dependencies": {
-    "@huggingface/transformers": "^4.2.0"
-  },
-  "overrides": {
-    "sharp": "^0.34.5"
-  },
-  "comments": {
-    "audit": "sharp <0.35.0 and adm-zip <0.6.0 are transitive deps of @huggingface/transformers with no upstream fix available. Not exploitable in this context: only text feature-extraction pipeline is used — no image processing or ZIP handling at application boundary. Review when @huggingface/transformers ships a patched release."
-  },
   "devDependencies": {
     "bats": "^1.13.0"
   }

package/skills/commit/SKILL.md

@@ -36,7 +36,17 @@ If `--inline` is absent **and** `JENGA_COMMIT_INLINE` is not set (or is not `1`)
 
 If no epic, task, or story has been implemented, exit with the message: "No implementation to commit."
 
-1. **Reconcile first** — Invoke the `/reconcile` skill before any other action, so the board is never committed in a drifted state.
+1. **Reconcile first, scoped to this commit** — Invoke the `/reconcile` skill before any other action, so the board is never committed in a drifted state.
+   - **Determine the scope to pass** (in order):
+     1. If `/commit` was invoked with an explicit epic/story/task id argument (e.g. `/commit E46`, `/commit E17_S04_T02`), use that id.
+     2. Otherwise, if the calling context already identifies a single task/story/epic just completed (e.g. a developer or tester agent's sender object naming `task_id`/`story_id`/`epic_id`, or a `/do` invocation for one task), use that id.
+     3. Otherwise, derive it from what's staged: run `git diff --cached --name-only` and filter to paths under `project/board/epics/`, `project/board/stories/`, and `project/board/tasks/`. Extract the id each matched filename encodes.
+        - If every extracted id shares a single common story-or-narrower ancestor (all belong to one story's own file plus any of its own tasks' files, or are all exactly one task's own file, or are all exactly one epic's own file with nothing narrower staged), use that single most-specific id (story/task id if present, else the epic id) as the scope.
+        - If matched ids span more than one distinct story, or more than one distinct epic, this case does not resolve — do not guess between them; fall through to case 4.
+        - **If no board files at all are staged, skip `/reconcile` entirely — do not fall through to case 4.** A commit that touches no board file cannot itself commit board drift, so there is nothing for a pre-commit reconcile to protect against; running a full unscoped scan here would be pure waste, not a safety net. This is distinct from the multi-item case immediately above, which still falls through to case 4 since board files genuinely are changing there.
+     4. Otherwise — no argument, no sender context, and staged board files span more than one distinct story or epic — fall back to unscoped `/reconcile` (full board), unchanged from prior behavior.
+   - **Invoke** `/reconcile <scope>` when a scope was determined in cases 1-3, unscoped `/reconcile` on the case-4 fallback, or skip the reconcile step entirely per case 3's no-board-files-staged outcome. Do not re-derive or duplicate `/reconcile`'s own default-scope-to-epic expansion here — passing a bare story or task id through is sufficient; `/reconcile` itself resolves that to the containing epic.
+   - **If `/reconcile` was skipped** (case 3's no-board-files-staged outcome) — continue silently to the next step, exactly as the no-drift outcome below.
    - **If reconcile detects and corrects drift** — inform the user what changed (e.g. demoted/promoted statuses, merged orphaned worktrees, cleaned `todo.md` entries) before proceeding.
    - **If reconcile finds no drift** — continue silently to the next step.
 

package/skills/dev-done/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: dev-done
+description: Commit the current work and immediately sync it into the .claude/ and .agents/ mirrors. Shortcut that chains /commit followed by /self-sync.
+keywords:
+  - dev done
+  - commit and sync
+  - commit and mirror
+  - done syncing
+examples:
+  - "dev-done E42_S04_T01"
+  - "commit this and sync the mirrors"
+---
+
+# Dev-Done — Commit, then Sync the Mirrors
+
+Chains `/commit <scope-id>` and `/self-sync`, the same "convenience shortcut" pattern `skills/lgtm/SKILL.md`
+uses for `/commit` + `/continue` — applied here to the commit -> mirror-sync sequence instead of the
+commit -> next-task sequence. Useful right after implementing a root-level framework change
+(`skills/`, `agents/`, `hooks/`, `scripts/`, `templates/`, `settings.json`), so the `.claude/` and
+`.agents/` mirrors never sit stale waiting on a manual `/self-sync` call.
+
+The deterministic decision of whether `/commit` halted early (nothing to commit) or completed
+normally lives in `skills/dev-done/scripts/classify-commit-outcome.sh`, not inline here — see that
+script's header for the exact contract.
+
+## Instructions
+
+1. Invoke the `/commit` skill with whatever scope-id argument `/dev-done` itself was given (e.g.
+   `/dev-done E42_S04_T01` invokes `/commit E42_S04_T01`) — the same EST scope-id argument contract
+   `/commit` already accepts (epic, story, or task id; see `skills/commit/SKILL.md`). Capture its full
+   output text.
+
+2. Pass the captured output to the classifier script:
+   ```
+   skills/dev-done/scripts/classify-commit-outcome.sh <<< "$COMMIT_OUTPUT"
+   ```
+
+3. If the script exits `1` (HALT): print its stdout — the exact message `No implementation to
+   commit.` — to the user, and stop. Do **not** invoke `/self-sync`.
+
+4. If the script exits `0` (PROCEED): invoke the `/self-sync` skill and wait for it to finish. This
+   happens regardless of whether `/commit` reported drift or doc-sync findings along the way — those
+   are informational, not blocking (see `skills/commit/SKILL.md`).
+
+5. Report both steps' output to the user in sequence — the commit result first, then the self-sync
+   summary.

package/skills/dev-done/scripts/classify-commit-outcome.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/dev-done/scripts/classify-commit-outcome.sh
+#
+# Deterministic classifier backing `/dev-done` (story E42_S04, task
+# E42_S04_T01). `/dev-done` chains `/commit <scope-id>` then `/self-sync`,
+# but must NOT proceed to `/self-sync` when `/commit` halted early because
+# there was nothing to commit. Per CLAUDE.md's "Skill Implementation
+# Principle — Scripts Over Inline Logic", that halt-vs-proceed check is a
+# deterministic, repeatable text match — it does not belong as inline
+# conditional logic in `skills/dev-done/SKILL.md`, so it lives here instead,
+# the same way `skills/self-sync/SKILL.md` delegates its own filesystem work
+# to `skills/self-sync/scripts/run.js` rather than inlining it.
+#
+# `/commit` and `/self-sync` are themselves agent-executed skills, not plain
+# executables — this script never shells out to invoke either one. It only
+# classifies text that the calling agent already captured from `/commit`'s
+# output. Invoking `/commit` and `/self-sync` remains `SKILL.md`'s job.
+#
+# ---------------------------------------------------------------------------
+# WHAT IT MATCHES
+# ---------------------------------------------------------------------------
+# `skills/commit/SKILL.md`'s Instructions section states, verbatim:
+#
+#   "If no epic, task, or story has been implemented, exit with the message:
+#   "No implementation to commit.""
+#
+# That exact sentence — "No implementation to commit." — is the ONLY halt
+# signal this script recognizes. If a future edit to `skills/commit/SKILL.md`
+# changes that wording, this script's match must be updated to match, or it
+# will silently stop recognizing the halt case (see Dependencies & Risks in
+# the task's execution plan).
+#
+# ---------------------------------------------------------------------------
+# INVOCATION
+# ---------------------------------------------------------------------------
+#   classify-commit-outcome.sh [<captured-commit-output>]
+#
+# The text `/commit` produced is passed either as the single argument, or
+# (when no argument is given) read from stdin in full, e.g.:
+#
+#   skills/dev-done/scripts/classify-commit-outcome.sh <<< "$COMMIT_OUTPUT"
+#   printf '%s' "$COMMIT_OUTPUT" | skills/dev-done/scripts/classify-commit-outcome.sh
+#
+# ---------------------------------------------------------------------------
+# OUTPUT CONTRACT (stdout, single line, nothing else)
+# ---------------------------------------------------------------------------
+#   HALT case      stdout is the exact literal message "No implementation to
+#                  commit." — the calling agent relays this stdout verbatim
+#                  to the user and does NOT invoke `/self-sync`.
+#   PROCEED case    stdout is the literal token "PROCEED" — the calling
+#                  agent invokes `/self-sync` next.
+#
+# ---------------------------------------------------------------------------
+# EXIT CODES
+# ---------------------------------------------------------------------------
+#   0   PROCEED — `/commit` completed normally (regardless of whether it
+#       reported drift or doc-sync findings along the way); stdout is
+#       "PROCEED".
+#   1   HALT — `/commit` halted early with the exact "No implementation to
+#       commit." message; stdout is that exact message.
+#   2   Usage/environment error (e.g. no input at all — neither an argument
+#       nor anything on stdin); nothing meaningful on stdout, an error on
+#       stderr.
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+HALT_MESSAGE="No implementation to commit."
+
+if [ "$#" -gt 1 ]; then
+  echo "Usage: $(basename "$0") [<captured-commit-output>]" >&2
+  echo "  (or pipe the captured output on stdin with no argument)" >&2
+  exit 2
+fi
+
+if [ "$#" -eq 1 ]; then
+  INPUT="$1"
+else
+  # No argument — read the full captured output from stdin.
+  if [ -t 0 ]; then
+    echo "ERROR: no argument given and stdin is a terminal — nothing to classify" >&2
+    exit 2
+  fi
+  INPUT="$(cat)"
+fi
+
+if [ -z "$INPUT" ]; then
+  echo "ERROR: no commit output provided to classify" >&2
+  exit 2
+fi
+
+# Trim leading/trailing whitespace from the whole input for the exact-match case.
+TRIMMED="$(printf '%s' "$INPUT" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
+
+if [ "$TRIMMED" = "$HALT_MESSAGE" ]; then
+  printf '%s\n' "$HALT_MESSAGE"
+  exit 1
+fi
+
+# Also match the halt message appearing as its own standalone line anywhere
+# in a longer captured response (e.g. wrapped in surrounding agent prose),
+# since the calling agent's captured "output text" is free-form, not a
+# guaranteed exact-equals string.
+while IFS= read -r line; do
+  LINE_TRIMMED="$(printf '%s' "$line" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
+  if [ "$LINE_TRIMMED" = "$HALT_MESSAGE" ]; then
+    printf '%s\n' "$HALT_MESSAGE"
+    exit 1
+  fi
+done <<< "$INPUT"
+
+printf 'PROCEED\n'
+exit 0

package/skills/init/SKILL.md

@@ -128,12 +128,13 @@ This script handles all scaffolding in one step:
 4. Creates `project/PROJECT_SUMMARY.md` with placeholder content
 5. Creates `project/configs/workflow.json` with shared constants
 6. Creates `project/configs/test-config.json` stub
-7. Creates `project/data/baselines.json`
-8. Creates `project/logs/events.json`
-9. Creates `docs/STRATEGY.md` — a strategic brief stub intended for investors, partners, and the product team
-10. Creates `CHANGELOG.md` from the shared template — a running log of notable changes, seeded with an `[Unreleased]` section
-11. 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
-12. Stages and commits all files with the message `init: scaffold project structure and workflow config`
+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`
 
 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/init/assets/scope-thresholds_template.json

@@ -0,0 +1,7 @@
+{
+  "threshold_version": 1,
+  "inline_max_files": 1,
+  "inline_max_lines": 20,
+  "story_max_files": 5,
+  "bundle_lock_ttl_minutes": 30
+}

package/skills/init/scripts/init.sh

@@ -67,6 +67,12 @@ cp "$ASSETS_DIR/workflow_template.json" project/configs/workflow.json
 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

package/skills/publish/SKILL.md

@@ -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

@@ -190,6 +190,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.

package/skills/publish/adapters/npm.md

@@ -109,6 +109,24 @@ A successful run produces:
 - A local (and optionally pushed) git tag `v<version>` matching the published `version`
 - A history row appended to `project/logs/publish-history.json`
 
+## Staged Publishing
+
+Before a live `deploy`, this target type also supports **staged publishing**
+via `/publish stage` — npm's own pre-publish staging area, which lets a
+release be smoke-tested from the exact tarball that would ship before it
+becomes visible on the registry. See `skills/publish/SKILL.md`'s
+`### /publish stage` section for the full command reference; summary here:
+
+- `bash skills/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/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/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/publish/scripts/npm_stage_inspect.sh reject <stage-id>` discards the staged version.
+
+Same registry-existence precondition as a normal `npm` publish: 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 publish, the deploy flow must print:

package/skills/publish/assets/ci-contract.md

@@ -71,6 +71,33 @@ These inputs remain optional in non-interactive mode:
 | `3` | Deploy failure | Used by the iOS adapter pipeline for build/export/upload failures |
 | `4` | Config or environment invalid | Implemented by validation scripts |
 
+## Staged publishing (`/publish stage`) — exit codes and ledger states
+
+`/publish stage` (npm/npm-ci only) has its own exit-code contract, separate
+from the deploy contract above:
+
+| Code | Meaning |
+|---|---|
+| `0` | Success (staged, or `--dry-run`/`--help` completed cleanly) |
+| `1` | User declined the pack confirmation prompt (or no tty was available) — `npm_stage_pipeline.sh` only |
+| `2` | A mandatory pre-deploy gate failed; nothing was staged — `npm_stage_pipeline.sh` only |
+| `3` | The underlying `npm stage <sub>` command failed, the tarball install failed, or the smoke test failed (`npm_stage_inspect.sh`); or `npm stage publish`/stage-id capture failed (`npm_stage_pipeline.sh`) |
+| `4` | Config/environment validation failure (`validate_npm_stage_env.sh`, or bad args), or (`npm_stage_inspect.sh` only) a usage error, an unknown sub-command, or the `approve` test interlock refusing without a passing test on record and no `--force <reason>` |
+
+`test` (via `npm_stage_inspect.sh`) surfaces a smoke-test failure as a
+non-zero exit — code `3` — distinct from a usage error (`4`).
+
+The publish ledger (`project/logs/publish-history.json`) gains four new
+`platform_state` values alongside the existing `uploaded`/`partial`/
+`dry-run`/`failed`:
+
+| `platform_state` | Written by | Meaning |
+|---|---|---|
+| `staged` | `npm_stage_pipeline.sh` | Version staged to npm's staged-publishing area; not yet visible on the registry |
+| `stage_tested` | `npm_stage_inspect.sh test` | The staged tarball was installed in isolation and smoke-tested; ledger row records `pass`/`fail` |
+| `approved` | `npm_stage_inspect.sh approve` | The staged version was approved (2FA-gated) and is now published |
+| `rejected` | `npm_stage_inspect.sh reject` | The staged version was discarded and will never be published |
+
 ## Precedence rules
 
 1. Command-line flags win over environment variables.

package/skills/publish/assets/publish.example.json

@@ -80,6 +80,33 @@
         "provider_short_name": "exampleco"
       },
       "notes": "Production upload example using App Store export mode."
+    },
+    {
+      "name": "npm-ci-example",
+      "type": "npm-ci",
+      "platform": "npm-ci-oidc",
+      "github_repo": "exampleco/example-package",
+      "workflow_path": ".github/workflows/npm-publish.yml",
+      "checks": {
+        "pre": [
+          "lint",
+          "type-check"
+        ],
+        "post": [
+          "smoke-test"
+        ]
+      },
+      "npm": {
+        "package_name": "@exampleco/example-package",
+        "access": "public",
+        "registry": "https://registry.npmjs.org",
+        "dist_tag": "latest",
+        "stage": {
+          "smoke_cmd": "npm run smoke-test",
+          "require_test_before_approve": true
+        }
+      },
+      "notes": "Scaffold example only. Demonstrates the optional npm.stage block used by '/publish stage'. Replace package_name and github_repo with your real values."
     }
   ]
 }