@jenga-ai/agent 1.2.3 → 1.3.0

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."
     }
   ]
 }

package/skills/publish/schemas/publish.schema.json

@@ -237,6 +237,26 @@
           "minLength": 1,
           "pattern": "^[a-z0-9][a-z0-9._-]*$",
           "default": "latest"
+        },
+        "stage": {
+          "$ref": "#/definitions/npmStageSettings"
+        }
+      }
+    },
+    "npmStageSettings": {
+      "description": "Optional settings for `/publish stage` on an npm or npm-ci target. Absent entirely on targets that don't use staged publishing.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "smoke_cmd": {
+          "description": "Command that `stage test` runs against the installed staged tarball. When absent, `stage test` falls back to a documented default.",
+          "type": "string",
+          "minLength": 1
+        },
+        "require_test_before_approve": {
+          "description": "When true, `stage approve` refuses without a recorded successful test for that stage id. Defaults to true.",
+          "type": "boolean",
+          "default": true
         }
       }
     },

package/skills/publish/scripts/npm_ci_pipeline.sh

@@ -160,6 +160,15 @@ WORKFLOW_YAML="$(cat <<EOF
 name: "Publish — ${PACKAGE_NAME}"
 on:
   workflow_dispatch:
+    inputs:
+      mode:
+        description: "publish (default) or stage — dispatched by npm_stage_pipeline.sh with mode=stage for /publish stage"
+        required: false
+        default: publish
+        type: choice
+        options:
+          - publish
+          - stage
 
 permissions:
   id-token: write
@@ -167,6 +176,7 @@ permissions:
 
 jobs:
   publish:
+    if: \${{ github.event.inputs.mode == 'publish' || github.event.inputs.mode == '' }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -183,6 +193,25 @@ jobs:
 
       - name: Publish to npm
         run: npm publish --provenance --access ${NPM_ACCESS} --tag ${DIST_TAG}
+
+  stage:
+    if: \${{ github.event.inputs.mode == 'stage' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Stage to npm
+        run: npm stage publish --provenance --access ${NPM_ACCESS} --tag ${DIST_TAG}
 EOF
 )"