@jenga-ai/agent 1.0.1 → 1.1.0

package/skills/close-story/scripts/extract-task-diff-stats.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# extract-task-diff-stats.sh — Extract actual git diff stats for a single task
+#
+# Usage: extract-task-diff-stats.sh <task-id>
+#
+# Finds all commits whose message contains <task-id> (EST naming convention,
+# e.g. E32_S06_T01), aggregates the file count and net line delta across all
+# matched commits, and prints:
+#
+#   actual_files_changed: <N>
+#   actual_lines_delta: <N>
+#
+# For bundle tasks (a single commit covers multiple task IDs), each task that
+# matches the commit receives the full bundle stats — this is the "full credit"
+# attribution model. See skills/close-story/SKILL.md for the rationale.
+#
+# Exit codes:
+#   0 — success (even when no commits are found; outputs 0 values)
+#   1 — missing or invalid argument
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Argument validation
+# ---------------------------------------------------------------------------
+
+TASK_ID="${1:-}"
+
+if [[ -z "$TASK_ID" ]]; then
+  echo "Usage: $(basename "$0") <task-id>" >&2
+  echo "  Example: $(basename "$0") E32_S06_T01" >&2
+  exit 1
+fi
+
+# Validate EST format: E##_S##_T##
+if [[ ! "$TASK_ID" =~ ^E[0-9]{2}_S[0-9]{2}_T[0-9]{2}$ ]]; then
+  echo "ERROR: Invalid task ID format '$TASK_ID'. Expected E##_S##_T## (e.g. E32_S06_T01)" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Find commits matching this task ID in the message
+# ---------------------------------------------------------------------------
+
+MATCHED_SHAS=$(git log --all --no-merges --grep="$TASK_ID" --pretty=format:"%H" 2>/dev/null || true)
+
+if [[ -z "$MATCHED_SHAS" ]]; then
+  # No commits found — task may predate EST tagging or use a non-standard message
+  echo "actual_files_changed: 0"
+  echo "actual_lines_delta: 0"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Aggregate diff stats across all matched commits
+# ---------------------------------------------------------------------------
+
+TOTAL_FILES=0
+TOTAL_INSERTIONS=0
+TOTAL_DELETIONS=0
+
+while IFS= read -r sha; do
+  [[ -z "$sha" ]] && continue
+
+  # Get the diff stat summary line for this commit
+  # git diff --stat <sha>~1..<sha> outputs individual file lines plus a summary:
+  #   N files changed, M insertions(+), K deletions(-)
+  # We only need the last (summary) line.
+  STAT_OUTPUT=$(git diff --stat "${sha}~1..${sha}" 2>/dev/null || true)
+
+  if [[ -z "$STAT_OUTPUT" ]]; then
+    # Commit with no parent (initial commit) or empty diff — skip
+    continue
+  fi
+
+  # Parse files changed from the summary line
+  # The summary line contains "N file(s) changed"
+  FILES_THIS=$(echo "$STAT_OUTPUT" | (grep -o '[0-9][0-9]* file' || true) | awk '{sum+=$1} END {print sum+0}')
+  # Parse insertions
+  INS_THIS=$(echo "$STAT_OUTPUT" | (grep -o '[0-9][0-9]* insertion' || true) | awk '{sum+=$1} END {print sum+0}')
+  # Parse deletions
+  DEL_THIS=$(echo "$STAT_OUTPUT" | (grep -o '[0-9][0-9]* deletion' || true) | awk '{sum+=$1} END {print sum+0}')
+
+  TOTAL_FILES=$((TOTAL_FILES + FILES_THIS))
+  TOTAL_INSERTIONS=$((TOTAL_INSERTIONS + INS_THIS))
+  TOTAL_DELETIONS=$((TOTAL_DELETIONS + DEL_THIS))
+
+done <<< "$MATCHED_SHAS"
+
+TOTAL_DELTA=$((TOTAL_INSERTIONS + TOTAL_DELETIONS))
+
+# ---------------------------------------------------------------------------
+# Output structured results
+# ---------------------------------------------------------------------------
+
+echo "actual_files_changed: $TOTAL_FILES"
+echo "actual_lines_delta: $TOTAL_DELTA"

package/skills/close-story/scripts/update-task-frontmatter.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# update-task-frontmatter.sh — Write or update a YAML key in task/story frontmatter
+#
+# Usage: update-task-frontmatter.sh <file-path> <key> <value>
+#
+# If the key already exists in the frontmatter block (between the first pair
+# of --- delimiters), its value is replaced in-place.
+# If the key does not exist, it is appended just before the closing ---.
+#
+# Works with both GNU and BSD sed (macOS-compatible — uses a temp file instead
+# of sed -i '').
+#
+# Exit codes:
+#   0 — success
+#   1 — argument error or file not found
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Argument validation
+# ---------------------------------------------------------------------------
+
+FILE_PATH="${1:-}"
+KEY="${2:-}"
+VALUE="${3:-}"
+
+if [[ -z "$FILE_PATH" || -z "$KEY" || -z "$VALUE" ]]; then
+  echo "Usage: $(basename "$0") <file-path> <key> <value>" >&2
+  echo "  Example: $(basename "$0") project/board/tasks/E32_S06_T01_my-task.md actual_files_changed 5" >&2
+  exit 1
+fi
+
+if [[ ! -f "$FILE_PATH" ]]; then
+  echo "ERROR: File not found: '$FILE_PATH'" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Process frontmatter
+# ---------------------------------------------------------------------------
+
+# Strategy:
+#   1. Read the file line by line.
+#   2. Track whether we are inside the frontmatter block (between --- delimiters).
+#   3. If the key exists in frontmatter, replace the line.
+#   4. If we reach the closing --- without having replaced the key, insert the
+#      key:value line immediately before the closing ---.
+#   5. Write the result to a temp file and move it back.
+
+TMPFILE=$(mktemp)
+trap 'rm -f "$TMPFILE"' EXIT
+
+in_frontmatter=0
+frontmatter_open=0   # set to 1 after the opening ---
+key_replaced=0
+closing_found=0
+
+while IFS= read -r line; do
+  # Detect frontmatter boundaries
+  if [[ "$line" == "---" ]]; then
+    if [[ $frontmatter_open -eq 0 ]]; then
+      # Opening ---
+      frontmatter_open=1
+      in_frontmatter=1
+      echo "$line" >> "$TMPFILE"
+      continue
+    elif [[ $in_frontmatter -eq 1 ]]; then
+      # Closing --- — if key was not found yet, insert it now
+      if [[ $key_replaced -eq 0 ]]; then
+        echo "${KEY}: ${VALUE}" >> "$TMPFILE"
+        key_replaced=1
+      fi
+      in_frontmatter=0
+      closing_found=1
+      echo "$line" >> "$TMPFILE"
+      continue
+    fi
+  fi
+
+  # Replace existing key in frontmatter
+  if [[ $in_frontmatter -eq 1 && $key_replaced -eq 0 ]]; then
+    # Match lines starting with exactly this key (not a key that begins with the same prefix)
+    if [[ "$line" =~ ^${KEY}:[[:space:]]* ]]; then
+      echo "${KEY}: ${VALUE}" >> "$TMPFILE"
+      key_replaced=1
+      continue
+    fi
+  fi
+
+  echo "$line" >> "$TMPFILE"
+done < "$FILE_PATH"
+
+# Edge case: file had no frontmatter closing --- (malformed file)
+if [[ $key_replaced -eq 0 && $closing_found -eq 0 ]]; then
+  echo "WARNING: No frontmatter closing --- found in '$FILE_PATH'. Key not written." >&2
+  exit 1
+fi
+
+# Move the temp file into place
+mv "$TMPFILE" "$FILE_PATH"
+trap - EXIT
+
+exit 0

package/skills/commit/SKILL.md

@@ -14,6 +14,24 @@ examples:
 
 # Commit — Commit Completed Work
 
+## Inline Mode (called by /do for inline-scoped tasks)
+
+When invoked with the `--inline` flag OR when the environment variable `JENGA_COMMIT_INLINE=1` is set, execute inline mode:
+
+1. **Skip** the user-action prerequisites check (step 1 in normal mode). No `_INSTRUCTIONS.md` lookup is performed.
+2. **Skip** any worktree merge logic — inline tasks execute in the main session with no dedicated worktree to merge.
+3. Stage all changed files relevant to the task (use `git add -A` or specific files if a list was provided by the caller).
+4. Commit using the EST naming convention:
+   ```
+   task(<E##_S##_T##>): <short description of what was done>
+   ```
+   The task ID (`E##_S##_T##`) must be taken from the context provided by `/do` — do not inspect task frontmatter independently.
+5. **Exit** — do not check for the next epic and do not emit "All Done!" in inline mode. `/do` manages the loop and next-epic detection.
+
+If `--inline` is absent **and** `JENGA_COMMIT_INLINE` is not set (or is not `1`), ignore this section entirely and proceed with normal mode below.
+
+---
+
 ## Instructions
 
 If no epic, task, or story has been implemented, exit with the message: "No implementation to commit."

package/skills/distribute/CONFIG_SCHEMA.md

@@ -0,0 +1,90 @@
+# jenga.config.json — Schema Reference
+
+This document is the canonical reference for the `jenga.config.json` file written into **consuming projects** during framework distribution. The file is created and maintained by `distribute-changes.sh`; it should not be edited by hand.
+
+---
+
+## Purpose
+
+`jenga.config.json` lives at the root of a consuming project and tracks which version of the JengaAgent framework is currently installed there, where the framework files were placed, and when the last distribution occurred. It is read by the distribution script on subsequent runs to determine the target directory and detect whether an upgrade is needed.
+
+---
+
+## File location
+
+```
+<project-root>/jenga.config.json
+```
+
+---
+
+## Example
+
+```json
+{
+  "project_name": "my-project",
+  "target_dir": ".agents",
+  "version": "2.3.1",
+  "updated_at": "2026-08-11",
+  "last_distributed": "2026-08-11T10:00:00Z",
+  "source": "private"
+}
+```
+
+---
+
+## Field reference
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `project_name` | string | yes | — | Human-readable identifier for the consuming project. Must match the `name` field of the corresponding entry in the monorepo's `distribute.config.json`. |
+| `target_dir` | string | yes | `.agents` | The directory under the project root where framework files are copied. `distribute-changes.sh` reads this field to resolve the destination path on every run. Change this only if the consuming project uses a non-standard layout. |
+| `version` | string | yes | — | The JengaAgent semantic version currently installed in this project (e.g. `"2.3.1"`). Compared against the `version` field in the monorepo's `package.json` to determine whether an upgrade is required. |
+| `updated_at` | string (ISO 8601 date) | yes | — | Date of the last successful distribution, in `YYYY-MM-DD` format. Does **not** include a time component. |
+| `last_distributed` | string (ISO 8601 datetime) | yes | — | Full UTC timestamp of the last successful distribution, in `YYYY-MM-DDTHH:MM:SSZ` format. Provides more precision than `updated_at` and is useful for audit and ordering purposes. |
+| `source` | string | yes | `"private"` | Distribution channel. Always `"private"` for projects that receive updates via the filesystem distribution mechanism. Distinguishes these projects from any future npm-installed consumers. Do not change this value manually. |
+
+---
+
+## First distribution
+
+When `distribute-changes.sh` runs against a project for the first time and no `jenga.config.json` exists in the project root, the script creates the file from scratch. All six fields are populated using:
+
+- `project_name` — taken from the matching entry in `distribute.config.json`
+- `target_dir` — taken from the matching entry in `distribute.config.json` (falls back to `.agents` if absent)
+- `version` — read from `package.json` in the monorepo at the time of distribution
+- `updated_at` — today's date (`YYYY-MM-DD`)
+- `last_distributed` — current UTC datetime (`YYYY-MM-DDTHH:MM:SSZ`)
+- `source` — hardcoded to `"private"`
+
+The directory referenced by `target_dir` is created if it does not already exist.
+
+---
+
+## Atomic write mechanism
+
+To prevent a consuming project from reading a partially-written `jenga.config.json` if distribution is interrupted (e.g. by a signal or disk error), the script uses an atomic write pattern:
+
+1. The updated JSON is written to a temporary file in the same directory as the target (e.g. `jenga.config.json.tmp`).
+2. The temporary file is renamed over the target with a single `mv` call.
+
+Because rename is atomic on POSIX filesystems, a reader will always see either the previous complete file or the new complete file — never a half-written intermediate state.
+
+---
+
+## The `active` flag in `distribute.config.json`
+
+`distribute.config.json` (in the monorepo, not in consuming projects) may include an `active` field on each target entry:
+
+```json
+{
+  "targets": [
+    { "name": "my-project", "path": "../my-project", "active": false }
+  ]
+}
+```
+
+- When `active` is `true` (or absent, which defaults to active), the target is distributed normally.
+- When `active` is `false`, distribution is **skipped** for that target and a warning is printed to stdout. The distribution run continues to process remaining targets — an inactive entry is not treated as an error.
+
+Use `active: false` to temporarily pause distribution to a project without removing its entry from the config.

package/skills/distribute/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: distribute
+description: Distribute JengaAgent framework files from this private monorepo to one or more consuming projects via the local filesystem. Manages release type selection, version bumping, dry-run preview, per-target file copy, and a post-distribution git commit.
+keywords:
+  - distribute
+  - private distribution
+  - filesystem distribute
+  - framework update
+  - version bump
+  - distribute to projects
+examples:
+  - "/distribute"
+  - "/distribute /path/to/consuming-project"
+  - "/distribute --dry-run"
+---
+
+# Distribute
+
+Copies JengaAgent framework files from this monorepo to all active consuming projects registered in `distribute.config.json`. Manages the full version lifecycle: release type selection, `package.json` version bump, dry-run preview, per-target file copy, and a final git commit of the version bump.
+
+Distinct from `/self-sync` (which mirrors root → in-repo `.claude/.agents/`) and `/mirror-public` (which syncs to the public GitHub repo). Do not call either of those skills from within this flow.
+
+## Instructions
+
+Follow these steps in order. Do not skip any step.
+
+### Step 1 — Path argument check
+
+If the user passed a path argument (e.g. `/distribute /path/to/project`):
+
+1. Verify the path exists on disk. If it does not, print an error and halt.
+2. Read `distribute.config.json` at the repo root.
+3. Derive `name` from the directory name of the path (e.g. `my-project` from `/home/user/my-project`).
+4. Add a new entry to the `targets` array:
+   ```json
+   { "name": "<derived-name>", "path": "<absolute-or-relative-path>", "active": true }
+   ```
+5. Write the updated `distribute.config.json`.
+6. Confirm the addition to the user: `Added <name> (<path>) to distribute.config.json.`
+
+If no path argument was passed, skip this step.
+
+### Step 2 — Release type prompt
+
+Ask the user to choose a release type. Present all four options:
+
+| Type | Effect |
+|------|--------|
+| `major` | Breaking change. Bumps major version in `package.json`. Distributes to ALL active targets. |
+| `minor` | New feature. Bumps minor version in `package.json`. Distributes to ALL active targets. |
+| `patch` | Bug fix. Bumps patch version in `package.json`. Distributes to ALL active targets. |
+| `amend` | No version bump. Distributes only to targets whose `jenga.config.json` version is behind the current `package.json` version, or targets that have no `jenga.config.json`. |
+
+Wait for the user's answer before continuing.
+
+### Step 3 — Config validation
+
+Read `distribute.config.json`.
+
+For each entry in `targets`:
+- If `active` is `false`: print `Skipping <name> — inactive.` Do not include it in the distribution run.
+- If the `path` does not exist on disk: print `Skipping <name> — path not found: <path>.` Do not include it in the distribution run.
+- If release type is `amend`: run `bash skills/distribute/scripts/check-version.sh <path>`.
+  - Exit 0 → include the target.
+  - Exit 1 → print `Skipping <name> — already up to date.` Do not include it in the distribution run (record it in the final report as "already up to date").
+  - Exit 2 → print `Skipping <name> — invalid path or config.` Do not include it.
+- Otherwise (major / minor / patch): include all active, path-valid targets.
+
+Print the final list of targets that will receive distribution. If the list is empty, print `No targets eligible for distribution.` and halt.
+
+### Step 4 — Version bump (non-amend only)
+
+Skip this step entirely for `amend`.
+
+For `major`, `minor`, or `patch`:
+
+```bash
+npm version <type> --no-git-tag-version
+```
+
+Run this at the monorepo root. If the command fails (non-zero exit), print the error, and halt — do not proceed to distribution with an unbumped or failed version.
+
+On success, read the new version from `package.json` and print: `Version bumped to <new-version>.`
+
+### Step 5 — Dry-run preview
+
+For each eligible target (from Step 3), run:
+
+```bash
+bash skills/distribute/scripts/distribute-changes.sh <project_path> --dry-run
+```
+
+Display the full output for each target. Then ask the user:
+
+`Proceed with distribution to the above targets? [y/N]`
+
+Wait for confirmation. If the user does not confirm, halt without making any changes. If a version bump was already applied in Step 4 and the user aborts here, inform them that `package.json` has been bumped but not committed, and they must either re-run `/distribute` or revert manually.
+
+### Step 6 — Execute distribution
+
+For each eligible target in sequence:
+
+```bash
+bash skills/distribute/scripts/distribute-changes.sh <project_path>
+```
+
+Record the exit code and any output. If a target fails (non-zero exit), record the failure and continue to the next target. Do not abort the run on partial failure.
+
+### Step 7 — Report results
+
+Print a per-target summary:
+
+**Succeeded:**
+- List each target name and the version distributed (read from `package.json`)
+
+**Failed:**
+- List each target name and the error output; note that manual retry is required
+
+**Already up to date (amend mode only):**
+- List each target skipped due to version match
+
+**Skipped:**
+- List inactive or missing-path targets from Step 3
+
+### Step 8 — Commit version bump (non-amend only, only if at least one target succeeded)
+
+Skip this step for `amend`. Skip this step if no targets succeeded in Step 6.
+
+Call:
+
+```bash
+bash skills/distribute/scripts/commit-version-bump.sh
+```
+
+Report the resulting commit SHA to the user.
+
+If at least one target failed and at least one succeeded, note that the version bump commit reflects the distributed version; failed targets need manual retry and will receive the same version on retry.
+
+### Step 9 — Do not call downstream skills
+
+Do not invoke `/self-sync` or `/mirror-public` at any point in this flow. They are separate skills with separate responsibilities and separate triggers.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `skills/distribute/scripts/distribute-changes.sh <path> [--dry-run]` | Copy framework files to a single consuming project |
+| `skills/distribute/scripts/commit-version-bump.sh` | Commit the `package.json` version bump |
+| `skills/distribute/scripts/check-version.sh <path>` | Amend mode: exits 0 if target needs update, 1 if up to date, 2 if invalid |
+
+## Config
+
+`distribute.config.json` at the repo root is the registry of consuming projects.
+
+Schema reference: `skills/distribute/CONFIG_SCHEMA.md`
+
+Each target entry:
+
+```json
+{
+  "name": "my-project",
+  "path": "/absolute/or/relative/path/to/project",
+  "active": true
+}
+```
+
+## Guard Rails
+
+- Never call `/self-sync` or `/mirror-public` from this skill.
+- Never inline file copy logic — all filesystem work goes through `distribute-changes.sh`.
+- Never commit anything other than `package.json` via `commit-version-bump.sh`.
+- Never skip the dry-run confirmation gate — even in non-interactive contexts, print the dry-run output and require explicit `y` from the user.
+- Never proceed past Step 4 if `npm version` fails.

package/skills/distribute/scripts/check-version.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# check-version.sh <project_path>
+#
+# Compares the monorepo version (package.json) against the target project's
+# jenga.config.json version field.
+#
+# Exit codes:
+#   0 — target needs an update: jenga.config.json absent OR versions differ
+#   1 — already up to date: versions match exactly
+#   2 — invalid input: <project_path> missing or monorepo package.json missing
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Resolve monorepo root from this script's own location (two levels up)
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MONOREPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+# ---------------------------------------------------------------------------
+# Validate arguments
+# ---------------------------------------------------------------------------
+if [[ $# -ne 1 ]]; then
+  echo "Usage: check-version.sh <project_path>" >&2
+  exit 2
+fi
+
+PROJECT_PATH="$1"
+
+# ---------------------------------------------------------------------------
+# Validate paths
+# ---------------------------------------------------------------------------
+PACKAGE_JSON="${MONOREPO_ROOT}/package.json"
+
+if [[ ! -d "$PROJECT_PATH" ]]; then
+  echo "check-version: project path does not exist: ${PROJECT_PATH}" >&2
+  exit 2
+fi
+
+if [[ ! -f "$PACKAGE_JSON" ]]; then
+  echo "check-version: monorepo package.json not found at ${PACKAGE_JSON}" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Read monorepo version
+# ---------------------------------------------------------------------------
+MONOREPO_VERSION="$(node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('${PACKAGE_JSON}','utf8')).version || '')")"
+
+if [[ -z "$MONOREPO_VERSION" ]]; then
+  echo "check-version: could not read version from ${PACKAGE_JSON}" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Read target version (absent jenga.config.json => needs update)
+# ---------------------------------------------------------------------------
+JENGA_CONFIG="${PROJECT_PATH}/jenga.config.json"
+
+if [[ ! -f "$JENGA_CONFIG" ]]; then
+  # No config file — target needs to be initialised
+  exit 0
+fi
+
+TARGET_VERSION="$(node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('${JENGA_CONFIG}','utf8')).version || '')")"
+
+# ---------------------------------------------------------------------------
+# Compare using exact string equality
+# ---------------------------------------------------------------------------
+if [[ "$MONOREPO_VERSION" == "$TARGET_VERSION" ]]; then
+  exit 1  # Already up to date
+else
+  exit 0  # Needs update
+fi

package/skills/distribute/scripts/commit-version-bump.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# commit-version-bump.sh — Commit the package.json version bump as a standalone git commit.
+#
+# Called by the /distribute skill after a successful non-amend distribution run.
+# No arguments. Reads the new version from package.json at the monorepo root.
+#
+# Behaviour:
+#   1. Resolve monorepo root from this script's own location (two levels up from scripts/).
+#   2. Read the version field from <monorepo_root>/package.json.
+#   3. Stage only package.json: git add package.json.
+#   4. If nothing changed, exit 0 with an informational message.
+#   5. Create commit: "chore: bump version to <version>".
+#   6. Exit 0 on success, non-zero with a descriptive message on failure.
+#
+# Exit codes:
+#   0  success (commit created, or nothing to commit)
+#   1  fatal error (package.json missing, version unreadable, git commit failed)
+
+set -uo pipefail
+
+# ---------------------------------------------------------------------------
+# Path resolution
+# ---------------------------------------------------------------------------
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# scripts/ -> distribute/ -> skills/ -> <monorepo_root>
+MONOREPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+PACKAGE_JSON="$MONOREPO_ROOT/package.json"
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+log_info() {
+  printf '→ %s\n' "$1"
+}
+
+fail() {
+  printf 'commit-version-bump: error: %s\n' "$1" >&2
+  exit 1
+}
+
+# ---------------------------------------------------------------------------
+# Validate prerequisites
+# ---------------------------------------------------------------------------
+
+if [[ ! -f "$PACKAGE_JSON" ]]; then
+  fail "package.json not found at $PACKAGE_JSON"
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  fail "node is required to read package.json but was not found in PATH"
+fi
+
+# ---------------------------------------------------------------------------
+# Read version from package.json
+# ---------------------------------------------------------------------------
+
+VERSION="$(node -p "require('$PACKAGE_JSON').version" 2>/dev/null)" || \
+  fail "Failed to read version from $PACKAGE_JSON"
+
+if [[ -z "$VERSION" ]]; then
+  fail "version field is empty or missing in $PACKAGE_JSON"
+fi
+
+log_info "Version read from package.json: $VERSION"
+
+# ---------------------------------------------------------------------------
+# Stage package.json
+# ---------------------------------------------------------------------------
+
+git -C "$MONOREPO_ROOT" add "$PACKAGE_JSON" || fail "git add failed for $PACKAGE_JSON"
+
+# ---------------------------------------------------------------------------
+# Check whether there is anything to commit
+# ---------------------------------------------------------------------------
+
+if git -C "$MONOREPO_ROOT" diff --cached --quiet; then
+  log_info "Nothing to commit — package.json is already clean"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Verify only package.json is staged (safety check)
+# ---------------------------------------------------------------------------
+
+STAGED_FILES="$(git -C "$MONOREPO_ROOT" diff --cached --name-only)"
+STAGED_COUNT="$(printf '%s\n' "$STAGED_FILES" | grep -c .)"
+
+if [[ "$STAGED_COUNT" -gt 1 ]]; then
+  fail "Unexpected staged files detected. Only package.json should be staged. Found:
+$STAGED_FILES"
+fi
+
+# ---------------------------------------------------------------------------
+# Commit
+# ---------------------------------------------------------------------------
+
+COMMIT_MSG="chore: bump version to $VERSION"
+
+log_info "Creating commit: $COMMIT_MSG"
+
+if ! git -C "$MONOREPO_ROOT" commit -m "$COMMIT_MSG"; then
+  fail "git commit failed for version bump to $VERSION"
+fi
+
+log_info "Committed successfully: $COMMIT_MSG"
+exit 0