@jenga-ai/agent 1.3.0 → 3.0.0

package/skills/{publish → j-publish}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: publish
-description: Configure, validate, and orchestrate scaffolded release workflows through a single `/publish` entry point with bounded sub-commands.
+name: j.publish
+description: Polyfill alias of the publish skill under a collision-safe directory name. Identical behavior to /publish — Configure, validate, and orchestrate scaffolded release workflows through a single `/publish` entry point with bounded sub-commands. Use when the bare /publish form is shadowed by another tool's own built-in command of the same name.
 keywords:
   - publish
   - deploy
@@ -11,6 +11,8 @@ keywords:
   - release notes
   - staged publishing
   - stage
+  - j-publish
+  - polyfill
 examples:
   - "publish setup --target staging-appstore"
   - "publish setup --type mobile-ios"
@@ -26,6 +28,7 @@ examples:
   - "test a release before publishing"
   - "publish stage --target npm-registry --dry-run"
   - "approve a staged npm release"
+  - "j-publish"
 metadata:
   scope: multi-target-v2
   primary_target: multi
@@ -39,13 +42,17 @@ metadata:
 
 # Publish — Deployment Pipeline Orchestrator
 
+This skill is a literal-directory-name duplicate of `skills/publish/`. It exists so that `/j-publish` (and `j.j-publish`) give a guaranteed-unshadowed way to reach the same flow as `/publish`, even if a host tool's own built-in command of the same name would otherwise shadow or override the bare `/publish` alias (Claude Code's native skill resolution is a literal-string, directory-name-based match — see `docs/skill-authoring.md`'s "Invocation Convention").
+
+This file is generated/synced by `scripts/generate-j-alias.sh publish` from `skills/publish/SKILL.md` — do not hand-edit it; re-run the generator instead to pick up source changes.
+
 `/publish` is the single entry point for release workflows in this repository. It wires configuration validation, setup, gated deployment, release-note drafting, and ledger history into one end-to-end flow, and dispatches the final publish step to a per-type adapter.
 
 Four target types are currently supported:
 
 - **`mobile-ios`** — publishes an iOS build to App Store Connect via the iOS adapter. See the [iOS App Store](#ios-app-store) section for iOS-specific configuration.
-- **`npm`** — publishes a package to an npm registry via the npm adapter. See the npm adapter (`skills/publish/adapters/npm.md`) and the npm wizard (`skills/publish/wizards/npm.md`) for npm-specific configuration.
-- **`npm-ci`** — publishes a package to npmjs.com via GitHub Actions OIDC (Trusted Publishers), with no `NPM_TOKEN` stored. The adapter generates a GitHub Actions workflow, commits it to the repository, and triggers it via `gh workflow run`. See the npm-ci adapter (`skills/publish/adapters/npm-ci.md`) and the npm-ci wizard (`skills/publish/wizards/npm-ci.md`) for configuration details.
+- **`npm`** — publishes a package to an npm registry via the npm adapter. See the npm adapter (`skills/j-publish/adapters/npm.md`) and the npm wizard (`skills/j-publish/wizards/npm.md`) for npm-specific configuration.
+- **`npm-ci`** — publishes a package to npmjs.com via GitHub Actions OIDC (Trusted Publishers), with no `NPM_TOKEN` stored. The adapter generates a GitHub Actions workflow, commits it to the repository, and triggers it via `gh workflow run`. See the npm-ci adapter (`skills/j-publish/adapters/npm-ci.md`) and the npm-ci wizard (`skills/j-publish/wizards/npm-ci.md`) for configuration details.
 - **`droplet`** — deploys a website or app to any SSH-reachable Linux host (including DigitalOcean Droplets) using a generated GitHub Actions workflow. The workflow SSHes into the host, pulls the deploy branch, runs an optional build command, and restarts the service. See [Droplet (GitHub Actions → SSH)](#droplet-github-actions--ssh) for configuration details.
 
 Every sub-command validates the config before doing anything else, so behaviour is identical regardless of which target type a project uses.
@@ -55,23 +62,23 @@ Every sub-command validates the config before doing anything else, so behaviour
 Before any sub-command executes, validate the config with:
 
 ```bash
-bash skills/publish/scripts/validate_config.sh <path-to-publish.json>
+bash skills/j-publish/scripts/validate_config.sh <path-to-publish.json>
 ```
 
 For deploy-oriented flows, validate the selected target with:
 
 ```bash
-bash skills/publish/scripts/check_target_config.sh <target-name> <path-to-publish.json>
+bash skills/j-publish/scripts/check_target_config.sh <target-name> <path-to-publish.json>
 ```
 
 - Default config resolution: prefer repo-root `publish.json`, fall back to `project/configs/publish.json`
-- Schema: `skills/publish/schemas/publish.schema.json`
-- Example config: `skills/publish/assets/publish.example.json`
-- Secrets guide: `skills/publish/assets/secrets-guide.md`
-- Deploy contract and exit codes: `skills/publish/assets/ci-contract.md`
-- iOS adapter template: `skills/publish/adapters/mobile-ios.md`
-- npm adapter template: `skills/publish/adapters/npm.md`
-- Ownership matrix: `skills/publish/assets/ownership-matrix.md`
+- Schema: `skills/j-publish/schemas/publish.schema.json`
+- Example config: `skills/j-publish/assets/publish.example.json`
+- Secrets guide: `skills/j-publish/assets/secrets-guide.md`
+- Deploy contract and exit codes: `skills/j-publish/assets/ci-contract.md`
+- iOS adapter template: `skills/j-publish/adapters/mobile-ios.md`
+- npm adapter template: `skills/j-publish/adapters/npm.md`
+- Ownership matrix: `skills/j-publish/assets/ownership-matrix.md`
 
 If config or env validation fails, the skill exits with code `4` and does not continue.
 
@@ -79,15 +86,15 @@ If config or env validation fails, the skill exits with code `4` and does not co
 
 | Command | Purpose | Implementation script | Notes |
 |---|---|---|---|
-| `/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 |
+| `/publish setup` | Prepare or refresh target configuration | `skills/j-publish/scripts/setup_wizard.sh` | Supported types: `mobile-ios`, `npm`, `npm-ci`, `droplet` |
+| `/publish deploy` | Run the full 11-step deploy orchestration | `skills/j-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/j-publish/scripts/npm_stage_pipeline.sh` (the `publish` sub-command) and `skills/j-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/j-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/j-publish/scripts/generate_release_notes.sh` | Target-agnostic |
 
 ## Quality Gate Policy
 
-The deploy flow invokes `skills/publish/scripts/run_gates.sh` at two fixed points:
+The deploy flow invokes `skills/j-publish/scripts/run_gates.sh` at two fixed points:
 
 1. **Pre-deploy:** `run_gates.sh pre <target> <publish.json> [--non-interactive]`
 2. **Post-deploy:** `run_gates.sh post <target> <publish.json> [--non-interactive]`
@@ -98,7 +105,7 @@ The deploy flow invokes `skills/publish/scripts/run_gates.sh` at two fixed point
 - Post-deploy gate failure records a `partial` publish result instead of rolling back the adapter upload
 - `--non-interactive` suppresses retry prompts and aborts immediately on failure
 
-See `skills/publish/assets/ci-contract.md` for the full quality-gate policy.
+See `skills/j-publish/assets/ci-contract.md` for the full quality-gate policy.
 
 ## Usage Signatures
 
@@ -108,13 +115,13 @@ See `skills/publish/assets/ci-contract.md` for the full quality-gate policy.
 /publish setup [<target>] [--type mobile-ios|npm|droplet] [--config <path>]
 ```
 
-Implementation: `bash skills/publish/scripts/setup_wizard.sh [<target>] [--type <deployment_type>] [--config <path>]`
+Implementation: `bash skills/j-publish/scripts/setup_wizard.sh [<target>] [--type <deployment_type>] [--config <path>]`
 
 Wizard flow:
 1. Resolve or prompt for the target name.
 2. Resolve or prompt for the deployment type. Supported values: `mobile-ios`, `npm`, `droplet`.
-3. Print the secrets guide path and the opening warning from `skills/publish/assets/secrets-guide.md`.
-4. Load `skills/publish/wizards/<type>.md` and render each `## Question:` section as a prompt.
+3. Print the secrets guide path and the opening warning from `skills/j-publish/assets/secrets-guide.md`.
+4. Load `skills/j-publish/wizards/<type>.md` and render each `## Question:` section as a prompt.
 5. Preview the generated target config as JSON.
 6. Save on confirmation by merging or creating `publish.json`.
 7. Validate the saved file with `validate_config.sh`; if validation fails, roll back the write.
@@ -140,7 +147,7 @@ Example invocations:
 /publish deploy [--target <name>] [--config <path>] [--yes] [--dry-run] [--minor | --major] [--notes-file <path>]
 ```
 
-Implementation: `bash skills/publish/scripts/publish_deploy.sh [flags...]`
+Implementation: `bash skills/j-publish/scripts/publish_deploy.sh [flags...]`
 
 Deploy flow:
 1. Select the target from config or `--target`
@@ -217,8 +224,8 @@ All seven sub-commands:
 
 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]`
+- `publish` → `bash skills/j-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/j-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.
@@ -242,7 +249,7 @@ instead of being caught by users after `npm publish`.
 /publish history [--config <path>] [--limit <count>] [--target <name>] [--json]
 ```
 
-Implementation: `bash skills/publish/scripts/show_history.sh [--limit <count>] [--target <name>] [--json] [--config <path>]`
+Implementation: `bash skills/j-publish/scripts/show_history.sh [--limit <count>] [--target <name>] [--json] [--config <path>]`
 
 ### `/publish release-notes`
 
@@ -250,7 +257,7 @@ Implementation: `bash skills/publish/scripts/show_history.sh [--limit <count>] [
 /publish release-notes --target <name> [--config <path>] [--from-tag <tag>] [--to-ref <git-ref>] [--output <path>]
 ```
 
-Implementation: `bash skills/publish/scripts/generate_release_notes.sh [--target <name>] [--from-tag <tag>] [--to-ref <git-ref>] [--output <path>] [<publish_json_path>]`
+Implementation: `bash skills/j-publish/scripts/generate_release_notes.sh [--target <name>] [--from-tag <tag>] [--to-ref <git-ref>] [--output <path>] [<publish_json_path>]`
 
 Release-note rules:
 - The last publish tag is the highest semver tag on the current branch that also has a matching ledger entry in `project/logs/publish-history.json`.
@@ -263,15 +270,15 @@ Release-note rules:
 ## Ledger & Tagging
 
 - `project/logs/publish-history.json` is append-only. New publishes add new rows; existing rows are never edited in-place.
-- `bash skills/publish/scripts/suggest_semver_bump.sh` suggests `major`, `minor`, or `patch` based on git history since the last ledger-backed publish tag.
-- `bash skills/publish/scripts/write_ledger_entry.sh <target> <adapter> <platform_state> <notes_path> [--yes] [--dry-run] [--version <vX.Y.Z>] [--config <path>]` appends the canonical publish entry and creates the matching annotated git tag.
-- `bash skills/publish/scripts/reconcile_tags.sh [--dry-run] [--config <path>]` repairs drift:
+- `bash skills/j-publish/scripts/suggest_semver_bump.sh` suggests `major`, `minor`, or `patch` based on git history since the last ledger-backed publish tag.
+- `bash skills/j-publish/scripts/write_ledger_entry.sh <target> <adapter> <platform_state> <notes_path> [--yes] [--dry-run] [--version <vX.Y.Z>] [--config <path>]` appends the canonical publish entry and creates the matching annotated git tag.
+- `bash skills/j-publish/scripts/reconcile_tags.sh [--dry-run] [--config <path>]` repairs drift:
   - git tag without ledger entry → append `partial` ledger row with note `Manually tagged without /publish`
   - ledger entry without git tag → create the missing tag retroactively
 
 ## Agent Roles
 
-See `skills/publish/assets/ownership-matrix.md` for the action-by-action ownership matrix.
+See `skills/j-publish/assets/ownership-matrix.md` for the action-by-action ownership matrix.
 
 Summary:
 - **Developer** initiates `/publish setup`, `/publish deploy`, and release-note review
@@ -280,7 +287,7 @@ Summary:
 
 ## Configuration Model
 
-The canonical config must validate against `skills/publish/schemas/publish.schema.json`.
+The canonical config must validate against `skills/j-publish/schemas/publish.schema.json`.
 
 ### Required top-level structure
 
@@ -327,10 +334,10 @@ The iOS adapter trust boundary is explicit: publish-side external commands are l
 
 The `npm` adapter publishes a Node package to an npm-compatible registry.
 
-- Adapter template: `skills/publish/adapters/npm.md`
-- Wizard template: `skills/publish/wizards/npm.md`
+- Adapter template: `skills/j-publish/adapters/npm.md`
+- Wizard template: `skills/j-publish/wizards/npm.md`
 
-See those files for the required target fields (registry URL, access, tag, `--dry-run` behaviour) and env references. Additional npm-specific schema details are owned by the npm settings block in `skills/publish/schemas/publish.schema.json`.
+See those files for the required target fields (registry URL, access, tag, `--dry-run` behaviour) and env references. Additional npm-specific schema details are owned by the npm settings block in `skills/j-publish/schemas/publish.schema.json`.
 
 ## npm CI (OIDC Trusted Publisher)
 
@@ -338,9 +345,9 @@ The `npm-ci` adapter publishes a Node package to npmjs.com via **GitHub Actions
 
 > Use `npm` for local publishes with a token; use `npm-ci` for CI-only publishing with OIDC (no token required).
 
-- Adapter template: `skills/publish/adapters/npm-ci.md`
-- Wizard template: `skills/publish/wizards/npm-ci.md`
-- Example config: `skills/publish/assets/publish.example.npm-ci.json`
+- Adapter template: `skills/j-publish/adapters/npm-ci.md`
+- Wizard template: `skills/j-publish/wizards/npm-ci.md`
+- Example config: `skills/j-publish/assets/publish.example.npm-ci.json`
 
 ### Required target fields for `npm-ci`
 
@@ -400,7 +407,7 @@ The generated workflow reads these from GitHub Actions secrets:
 - `DROPLET_SSH_KEY` (or value of `ssh_key_secret`) — private key contents
 - `DROPLET_KNOWN_HOSTS` (or value of `known_hosts_secret`) — `ssh-keyscan` output
 
-See `skills/publish/assets/secrets-guide.md` for setup instructions.
+See `skills/j-publish/assets/secrets-guide.md` for setup instructions.
 
 ### First-run prerequisites (manual)
 

package/skills/{publish → j-publish}/adapters/droplet.md

@@ -76,7 +76,7 @@ The `gh` CLI must be authenticated (`gh auth login`) before running
 ### Pipeline entrypoint
 
 ```bash
-bash skills/publish/scripts/droplet_pipeline.sh \
+bash skills/j-publish/scripts/droplet_pipeline.sh \
   --target <name> \
   --config <path-to-publish.json> \
   [--dry-run]

package/skills/{publish → j-publish}/adapters/mobile-ios.md

@@ -2,7 +2,7 @@
 
 The `mobile-ios` adapter drives the `/publish deploy` flow for iOS App Store targets.
 It is a prompt/template contract for the agent layer and delegates concrete execution to
-`skills/publish/scripts/ios_pipeline.sh`.
+`skills/j-publish/scripts/ios_pipeline.sh`.
 
 ## Invocation Contract
 
@@ -43,13 +43,13 @@ The required env vars are:
 Validate them before execution with:
 
 ```bash
-bash skills/publish/scripts/validate_ios_env.sh <path-to-publish.json>
+bash skills/j-publish/scripts/validate_ios_env.sh <path-to-publish.json>
 ```
 
 ### Pipeline entrypoint
 
 ```bash
-bash skills/publish/scripts/ios_pipeline.sh <target> <path-to-publish.json> [--dry-run] [--non-interactive]
+bash skills/j-publish/scripts/ios_pipeline.sh <target> <path-to-publish.json> [--dry-run] [--non-interactive]
 ```
 
 ## Execution Phases

package/skills/{publish → j-publish}/adapters/npm-ci.md

@@ -79,7 +79,7 @@ The `gh` CLI must be authenticated before running `/publish deploy` against an
 ### Pipeline entrypoint
 
 ```bash
-bash skills/publish/scripts/npm_ci_pipeline.sh \
+bash skills/j-publish/scripts/npm_ci_pipeline.sh \
   --target <name> \
   --config <path-to-publish.json> \
   [--dry-run]
@@ -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:
@@ -213,9 +235,9 @@ automated and human halves of the flow:
 - **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
+  `bash skills/j-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>`
+  `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.
 

package/skills/{publish → j-publish}/adapters/npm.md

@@ -2,7 +2,7 @@
 
 The `npm` adapter drives the `/publish deploy` flow for npm registry targets.
 It is a prompt/template contract for the agent layer and delegates concrete execution to
-`skills/publish/scripts/npm_pipeline.sh`.
+`skills/j-publish/scripts/npm_pipeline.sh`.
 
 ## Invocation Contract
 
@@ -30,13 +30,13 @@ The required env vars are:
 Validate them before execution with:
 
 ```bash
-bash skills/publish/scripts/validate_npm_env.sh <path-to-publish.json>
+bash skills/j-publish/scripts/validate_npm_env.sh <path-to-publish.json>
 ```
 
 ### Pipeline entrypoint
 
 ```bash
-bash skills/publish/scripts/npm_pipeline.sh <target> <path-to-publish.json> [--dry-run] [--non-interactive]
+bash skills/j-publish/scripts/npm_pipeline.sh <target> <path-to-publish.json> [--dry-run] [--non-interactive]
 ```
 
 ## Execution Phases
@@ -114,13 +114,13 @@ A successful run produces:
 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
+becomes visible on the registry. See `skills/j-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.
+- `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 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

package/skills/{publish → j-publish}/assets/ci-contract.md

@@ -7,9 +7,9 @@ This document defines the CI-safe execution contract for the scaffolded `/publis
 Every `/publish` invocation must perform these steps before command-specific work:
 
 1. Resolve config path (`--config <path>` or default `project/configs/publish.json`)
-2. Run `bash skills/publish/scripts/validate_config.sh <resolved-path>`
+2. Run `bash skills/j-publish/scripts/validate_config.sh <resolved-path>`
 3. Abort immediately with exit code `4` if the file is missing, invalid JSON, or fails validation
-4. For the iOS adapter, run `bash skills/publish/scripts/validate_ios_env.sh <resolved-path>` before build/upload work begins
+4. For the iOS adapter, run `bash skills/j-publish/scripts/validate_ios_env.sh <resolved-path>` before build/upload work begins
 
 ## Inputs
 

package/skills/{publish → j-publish}/schemas/publish.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://jenga.local/skills/publish/schemas/publish.schema.json",
+  "$id": "https://jenga.local/skills/j-publish/schemas/publish.schema.json",
   "title": "Publish Skill Configuration",
   "description": "Schema for project/configs/publish.json used by the /publish skill.",
   "type": "object",

package/skills/{publish → j-publish}/scripts/npm_ci_pipeline.sh

@@ -172,7 +172,7 @@ on:
 
 permissions:
   id-token: write
-  contents: read
+  contents: write
 
 jobs:
   publish:
@@ -194,6 +194,17 @@ jobs:
       - name: Publish to npm
         run: npm publish --provenance --access ${NPM_ACCESS} --tag ${DIST_TAG}
 
+      - name: Tag prod release and remove stage tag
+        if: success()
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          VERSION="\$(node -p "require('./package.json').version")"
+          git tag "v\${VERSION}"
+          git push origin "v\${VERSION}"
+          git tag -d "v\${VERSION}-stage" 2>/dev/null || true
+          git push origin ":refs/tags/v\${VERSION}-stage" 2>/dev/null || true
+
   stage:
     if: \${{ github.event.inputs.mode == 'stage' }}
     runs-on: ubuntu-latest
@@ -212,6 +223,15 @@ jobs:
 
       - name: Stage to npm
         run: npm stage publish --provenance --access ${NPM_ACCESS} --tag ${DIST_TAG}
+
+      - name: Tag stage release
+        if: success()
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          VERSION="\$(node -p "require('./package.json').version")"
+          git tag -f "v\${VERSION}-stage"
+          git push origin "v\${VERSION}-stage" --force
 EOF
 )"
 

package/skills/{publish → j-publish}/scripts/npm_stage_inspect.sh

@@ -419,8 +419,31 @@ cmd_list() {
   # `list` itself needs no config (npm stage list takes no target/config).
   : "${config_arg}"
 
+  # `npm stage list` rejects a version-qualified spec ("Version specifiers
+  # are not supported for listing staged packages") — it only accepts a bare
+  # package name. If the caller passed one anyway (e.g. "@jenga-ai/agent@1.3.0"
+  # or "some-pkg@1.3.0"), split it into name + version here, pass only the
+  # bare name to npm, and filter the result to that version client-side
+  # below (same fallback the fix in npm_stage_pipeline.sh uses). A leading
+  # '@' belongs to a scoped package's own name, not a version marker, so the
+  # version split point is the second '@' for scoped specs, the first for
+  # unscoped ones.
+  local package_name="${package_spec}" package_version=""
+  if [[ -n "${package_spec}" ]]; then
+    if [[ "${package_spec}" == @* ]]; then
+      local rest="${package_spec#@}"
+      if [[ "${rest}" == *"@"* ]]; then
+        package_name="@${rest%%@*}"
+        package_version="${rest#*@}"
+      fi
+    elif [[ "${package_spec}" == *"@"* ]]; then
+      package_name="${package_spec%%@*}"
+      package_version="${package_spec#*@}"
+    fi
+  fi
+
   local -a cmd=(npm stage list)
-  [[ -n "${package_spec}" ]] && cmd+=("${package_spec}")
+  [[ -n "${package_name}" ]] && cmd+=("${package_name}")
   cmd+=(--json)
 
   if (( dry_run )); then
@@ -436,6 +459,16 @@ cmd_list() {
     exit "${EXIT_OP_FAILED}"
   fi
 
+  if [[ -n "${package_version}" ]]; then
+    local filtered
+    if filtered="$(printf '%s' "${output}" | jq -c --arg ver "${package_version}" '
+      ( if (type == "array") then . else (.stages? // .items? // []) end )
+      | [ .[] | select((.version // "") == $ver) ]
+    ' 2>/dev/null)"; then
+      output="${filtered}"
+    fi
+  fi
+
   if (( json_out )); then
     printf '%s\n' "${output}"
     exit "${EXIT_OK}"

package/skills/{publish → j-publish}/scripts/npm_stage_pipeline.sh

@@ -379,13 +379,18 @@ if [[ -z "${STAGE_ID}" ]] && printf '%s' "${STAGE_OUTPUT}" | jq -e . >/dev/null
   STAGE_ID="$(printf '%s' "${STAGE_OUTPUT}" | jq -r '.id // .stageId // .stage_id // empty' 2>/dev/null || true)"
 fi
 
-# Attempt 3: fall back to `npm stage list <package>@<version> --json` and
-# extract the most recent matching entry's id.
+# Attempt 3: fall back to `npm stage list <package> --json` and extract the
+# most recent matching entry's id. `npm stage list` rejects a version-
+# qualified spec ("Version specifiers are not supported for listing staged
+# packages") — it only accepts a bare package name — so this must pass
+# PACKAGE_NAME, never PACKAGE_SPEC; the version match happens client-side via
+# jq below instead (confirmed live on jenga-npm during v1.3.0 staging on
+# 2026-09-01, project/todo.md).
 if [[ -z "${STAGE_ID}" ]]; then
   log_warn "could not parse a stage id directly from stage output; falling back to 'npm stage list --json'..."
 
   LIST_STATUS=0
-  LIST_OUTPUT="$(npm stage list "${PACKAGE_SPEC}" --json 2>&1)" || LIST_STATUS=$?
+  LIST_OUTPUT="$(npm stage list "${PACKAGE_NAME}" --json 2>&1)" || LIST_STATUS=$?
 
   if [[ ${LIST_STATUS} -ne 0 ]]; then
     printf '%s\n' "${LIST_OUTPUT}" >&2
@@ -405,7 +410,7 @@ if [[ -z "${STAGE_ID}" ]]; then
 fi
 
 if [[ -z "${STAGE_ID}" ]]; then
-  printf 'npm stage pipeline: staged successfully but the stage id could not be captured from either the direct output or "npm stage list --json". Run "npm stage list %s --json" manually to recover it.\n' "${PACKAGE_SPEC}" >&2
+  printf 'npm stage pipeline: staged successfully but the stage id could not be captured from either the direct output or "npm stage list --json". Run "npm stage list %s --json" manually to recover it (bare package name — a version-qualified spec is rejected by npm).\n' "${PACKAGE_NAME}" >&2
   exit "${EXIT_STAGE_FAILURE}"
 fi
 

package/skills/{publish → j-publish}/scripts/publish_deploy.sh

@@ -463,16 +463,16 @@ print_manual_steps() {
   local adapter_doc
   case "$TARGET_TYPE" in
     droplet)
-      adapter_doc="$PUBLISH_REPO_ROOT/skills/publish/adapters/droplet.md"
+      adapter_doc="$PUBLISH_REPO_ROOT/skills/j-publish/adapters/droplet.md"
       ;;
     npm)
-      adapter_doc="$PUBLISH_REPO_ROOT/skills/publish/adapters/npm.md"
+      adapter_doc="$PUBLISH_REPO_ROOT/skills/j-publish/adapters/npm.md"
       ;;
     npm-ci)
-      adapter_doc="$PUBLISH_REPO_ROOT/skills/publish/adapters/npm-ci.md"
+      adapter_doc="$PUBLISH_REPO_ROOT/skills/j-publish/adapters/npm-ci.md"
       ;;
     mobile-ios)
-      adapter_doc="$PUBLISH_REPO_ROOT/skills/publish/adapters/mobile-ios.md"
+      adapter_doc="$PUBLISH_REPO_ROOT/skills/j-publish/adapters/mobile-ios.md"
       ;;
     *)
       return 0

package/skills/{publish → j-publish}/scripts/validate_npm_stage_env.sh

@@ -13,7 +13,7 @@
 # Exit codes:
 #   0  all four preflight checks passed
 #   4  one of the checks failed (config/environment invalid), matching
-#      skills/publish/assets/ci-contract.md
+#      skills/j-publish/assets/ci-contract.md
 #
 # Security note: the registry probe (check 4) never prints npm's raw stdout/stderr. Only
 # messages composed by this script are emitted, so nothing npm writes — which could in

package/skills/{publish → j-publish}/wizards/droplet.md

@@ -261,7 +261,7 @@ Once all answers have been collected, perform the following steps in order:
    ```
 
 4. **Validate against the schema.** Run
-   `bash skills/publish/scripts/validate_config.sh <path-to-publish.json>`
+   `bash skills/j-publish/scripts/validate_config.sh <path-to-publish.json>`
    before saving. If validation fails, report the error and abort — do not
    write a broken `publish.json`.
 

package/skills/{publish → j-publish}/wizards/mobile-ios.md

@@ -110,7 +110,7 @@ Optional short string such as `exampleco`.
 Maps to: `targets[].secrets.app_store_connect_api_key_id`
 
 Enter the environment-variable name that will supply the App Store Connect API key identifier.
-See `skills/publish/assets/secrets-guide.md` before answering.
+See `skills/j-publish/assets/secrets-guide.md` before answering.
 
 ## Expected format:
 

package/skills/{publish → j-publish}/wizards/npm-ci.md

@@ -213,7 +213,7 @@ Once all six answers have been collected, perform the following steps in order:
    - Do not include a `secrets` block — this adapter uses OIDC and no token
      is required.
 4. **Validate against the schema.** Run
-   `skills/publish/scripts/validate_config.sh` before saving. If validation
+   `skills/j-publish/scripts/validate_config.sh` before saving. If validation
    fails, report the error and abort — do not write a broken `publish.json`.
 5. **Report to the user.** Print a short summary confirming (a) the target
    block written, (b) the `github_repo` value, and (c) the `workflow_path`

package/skills/{publish → j-publish}/wizards/npm.md

@@ -97,7 +97,7 @@ deploy).
 ## Prerequisite: NPM_TOKEN
 
 The npm pipeline reads the auth token from the `NPM_TOKEN` environment
-variable at publish time (`skills/publish/adapters/npm.md` defines this
+variable at publish time (`skills/j-publish/adapters/npm.md` defines this
 contract). The wizard does not collect the token value — that would be
 unsafe. Instead, at the end of the wizard, write the following instructions
 file so the user knows exactly what to configure: