@jenga-ai/agent 1.0.0 → 1.1.0

package/mcp/training_runner/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "training-runner-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server that validates and runs ML training jobs via bash start.sh",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.1",
+    "js-yaml": "^4.1.0",
+    "zod": "^3.23.8"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "JengaAgent — agentic project management CLI",
   "type": "module",
   "publishConfig": {
@@ -26,22 +26,24 @@
     "templates/",
     "bin/",
     "lib/",
-    "mcp/execute-ticket/",
-    "mcp/help/",
-    "mcp/router/index.js",
-    "mcp/router/matcher.js",
-    "mcp/router/embedder.js",
-    "mcp/router/skill-index.js",
-    "mcp/router/package.json",
-    "mcp/router/package-lock.json",
-    "mcp/router/README.md",
+    "mcp/",
     "README.md",
     "LICENSE"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/samwelmunga/jenga-npm"
+  },
   "keywords": [],
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xenova/transformers": "^2.17.2"
+    "@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."
   }
 }

package/skills/close-story/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: close-story
+description: Close a story by verifying all tasks are in terminal state, extracting actual diff stats per task, computing scope divergence flags, and writing closure metadata to task frontmatter.
+keywords:
+  - close story
+  - close
+  - finish story
+  - complete story
+  - story done
+examples:
+  - "close story E17_S06"
+  - "/close-story E32_S06"
+  - "mark story E12_S03 as done"
+---
+
+# close-story — Close a Story
+
+## Purpose
+
+`/close-story <story-id>` performs the final closure steps for a story:
+
+1. Verifies all tasks in the story are in a terminal state (Passed or Done).
+2. Extracts actual `git diff --stat` metrics for each task from the commit history.
+3. Writes `actual_files_changed`, `actual_lines_delta`, and `scope_divergence_flag` to each task's frontmatter.
+4. Updates the story's frontmatter `status` to `Done` and records `date_completed`.
+
+---
+
+## Instructions
+
+### Step 1 — Verify story is closeable
+
+Run the guard script:
+
+```bash
+bash skills/close-story/scripts/check-story-closeable.sh <story-id>
+```
+
+- If it exits with code 0 and prints `CLOSEABLE`, continue.
+- If it exits with code 1, halt and report the blocking tasks to the user. Do not proceed.
+
+---
+
+### Step 2 — Extract per-task diff stats and compute scope divergence
+
+**At the start of this step**, read `project/configs/scope-thresholds.json` to check that it
+exists and is parseable. If it is missing or malformed, log a warning and continue — divergence
+flags will be skipped (non-blocking). The `compute-scope-divergence.sh` script handles this
+gracefully by always printing `false` on error.
+
+For **each task ID** listed in the story's `tasks:` frontmatter array:
+
+1. **Find the task file** at `project/board/tasks/<task-id>_*.md`.
+
+2. **Extract commit SHA(s)** for this task:
+   ```bash
+   git log --all --no-merges --grep="<task-id>" --pretty=format:"%H" 2>/dev/null
+   ```
+   This matches commits whose message contains the EST task identifier (e.g. `E32_S06_T01`).
+
+3. **Run per-task diff stat extraction:**
+   ```bash
+   bash skills/close-story/scripts/extract-task-diff-stats.sh <task-id>
+   ```
+   The script outputs:
+   ```
+   actual_files_changed: <N>
+   actual_lines_delta: <N>
+   ```
+   Parse these values from stdout.
+
+4. **Write stats to task frontmatter:**
+   ```bash
+   bash skills/close-story/scripts/update-task-frontmatter.sh \
+     "project/board/tasks/<task-id>_*.md" \
+     actual_files_changed <N>
+
+   bash skills/close-story/scripts/update-task-frontmatter.sh \
+     "project/board/tasks/<task-id>_*.md" \
+     actual_lines_delta <N>
+   ```
+
+5. **Compute and write scope divergence flag:**
+
+   Read the task's `execution_scope` from its frontmatter:
+   ```bash
+   EXECUTION_SCOPE=$(grep '^execution_scope:' "project/board/tasks/<task-id>_*.md" \
+     | head -1 | awk '{print $2}')
+   ```
+
+   If `execution_scope` is empty or absent, treat it as `task` (no divergence).
+
+   Run the divergence computation:
+   ```bash
+   DIVERGENCE_FLAG=$(bash skills/close-story/scripts/compute-scope-divergence.sh \
+     "<execution_scope>" <actual_files_changed> <actual_lines_delta>)
+   ```
+
+   Write the result to task frontmatter:
+   ```bash
+   bash skills/close-story/scripts/update-task-frontmatter.sh \
+     "project/board/tasks/<task-id>_*.md" \
+     scope_divergence_flag "$DIVERGENCE_FLAG"
+   ```
+
+   Track diverging tasks in a running list for the final report (Step 5).
+
+6. **Skip tasks with no matched commits** — If `actual_files_changed` is `0`
+   and `actual_lines_delta` is `0`, it likely means the task predates this
+   feature or uses an untracked commit. Write the `0` values anyway so the
+   field is present but do not treat this as an error. Run divergence
+   computation with `0 0` — this will return `false` for all scopes.
+
+---
+
+### Step 3 — Bundle task attribution
+
+A **bundle task** is one where a single commit message contains multiple task
+IDs (e.g. `task(E32_S06_T01, E32_S06_T02): ...`). In this case:
+
+- Each task matched by `git log --grep` will independently resolve to the same
+  commit SHA, and each will receive the **full bundle stats** as its
+  `actual_files_changed` and `actual_lines_delta` values.
+- This is the **"full credit"** attribution model: each task is credited with
+  the total work of the bundle commit since the individual contribution cannot
+  be mechanically separated.
+- An alternative **proportional split** (divide total stats by number of tasks
+  in the bundle) is mathematically cleaner but requires detecting the bundle
+  size at query time, which is not supported by the current scripts.
+- The full-credit model is the default. Future work may introduce proportional
+  splitting if telemetry shows significant over-counting in bundle scenarios.
+
+> Note for tester: bundle attribution means the sum of `actual_lines_delta`
+> across tasks may exceed the true total for stories where bundle commits were
+> used.
+
+---
+
+### Step 4 — Update story frontmatter
+
+After all tasks have been updated, set the following fields in the story's
+frontmatter:
+
+- `status: Done`
+- `date_completed: <YYYY-MM-DD>` (today's date in UTC)
+
+Use `update-task-frontmatter.sh` targeting the story file, or edit directly.
+
+---
+
+### Step 5 — Report
+
+Print a summary to the user:
+
+```
+Story <story-id> closed.
+Tasks updated with actual diff stats:
+  <task-id>: files_changed=<N>, lines_delta=<N>, scope_divergence_flag=<true|false>
+  ...
+```
+
+If any task had `0` for both fields, note it as potentially untracked:
+```
+  <task-id>: files_changed=0, lines_delta=0 (no EST-tagged commit found)
+```
+
+#### Scope Divergence
+
+Include a "Scope Divergence" section listing every task whose `scope_divergence_flag` was set
+to `true`. If no tasks diverged, note that explicitly.
+
+```
+Scope Divergence:
+  <task-id> [scope=<execution_scope>]: files_changed=<N>, lines_delta=<N> — exceeded threshold
+  ...
+```
+
+Or, if none diverged:
+```
+Scope Divergence: none
+```
+
+The divergence thresholds applied are those from `project/configs/scope-thresholds.json`:
+- `inline` scope: max_files=<inline_max_files>, max_lines=<inline_max_lines>
+- `story` scope: max_files=<story_max_files>
+- `task` / `epic` scope: no threshold (always false)
+
+If the config was missing or malformed, note that divergence flags were skipped:
+```
+Scope Divergence: skipped (scope-thresholds.json missing or malformed)
+```
+
+---
+
+## Scripts Reference
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/check-story-closeable.sh <story-id>` | Guard: verify all tasks in terminal state |
+| `scripts/extract-diff-stats.sh <story-id>` | Story-level aggregate diff stats (for story frontmatter) |
+| `scripts/extract-task-diff-stats.sh <task-id>` | Per-task diff stats from EST-tagged commits |
+| `scripts/update-task-frontmatter.sh <file> <key> <value>` | Write/update a YAML field in task or story frontmatter |
+| `scripts/compute-scope-divergence.sh <execution_scope> <actual_files_changed> <actual_lines_delta>` | Compute scope divergence flag: prints `true` or `false` |

package/skills/close-story/scripts/check-story-closeable.sh

@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+# check-story-closeable.sh — Last-task detection guard for /close-story
+#
+# Usage: bash check-story-closeable.sh <story-id>
+#
+# Exits 0 and prints "CLOSEABLE" to stdout when all tasks in the story's
+# `tasks:` frontmatter list have status Passed or Done.
+# Exits 1 and prints a descriptive message to stderr for any other outcome.
+#
+# This script always re-reads task files from disk — never uses cached state.
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+usage() {
+  echo "Usage: $(basename "$0") <story-id>" >&2
+  echo "  Example: $(basename "$0") E17_S06" >&2
+  exit 1
+}
+
+# Locate the project root relative to this script's location.
+# Script lives at: skills/close-story/scripts/check-story-closeable.sh
+# Project root is three levels up (skills/ → repo root).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+STORIES_DIR="$PROJECT_ROOT/project/board/stories"
+TASKS_DIR="$PROJECT_ROOT/project/board/tasks"
+
+# ---------------------------------------------------------------------------
+# Argument validation
+# ---------------------------------------------------------------------------
+
+if [[ $# -ne 1 ]]; then
+  usage
+fi
+
+STORY_ID="$1"
+
+# Basic sanity check on the story ID format (E##_S##)
+if [[ ! "$STORY_ID" =~ ^E[0-9]{2}_S[0-9]{2}$ ]]; then
+  echo "ERROR: Invalid story ID format '$STORY_ID'. Expected format: E##_S## (e.g. E17_S06)" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Step 1: Locate story file
+# ---------------------------------------------------------------------------
+
+# Use a glob — story slug may vary, so match on ID prefix only.
+story_file=""
+while IFS= read -r -d '' candidate; do
+  story_file="$candidate"
+  break
+done < <(find "$STORIES_DIR" -maxdepth 1 -name "${STORY_ID}_*.md" -print0 2>/dev/null)
+
+if [[ -z "$story_file" ]]; then
+  echo "ERROR: Story file not found for '$STORY_ID' in $STORIES_DIR" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Step 2: Extract tasks: list from story frontmatter
+# ---------------------------------------------------------------------------
+# Frontmatter is the YAML block between the first pair of --- delimiters.
+# The tasks: field is a YAML list of task IDs, e.g.:
+#   tasks:
+#     - E17_S06_T01
+#     - E17_S06_T02
+
+extract_tasks() {
+  local file="$1"
+  local in_frontmatter=0
+  local in_tasks=0
+  local found_any=0
+
+  while IFS= read -r line; do
+    # Detect frontmatter boundaries
+    if [[ "$line" == "---" ]]; then
+      if [[ $in_frontmatter -eq 0 ]]; then
+        in_frontmatter=1
+        continue
+      else
+        # Closing --- ends the frontmatter block
+        break
+      fi
+    fi
+
+    # Only process lines inside frontmatter
+    if [[ $in_frontmatter -eq 0 ]]; then
+      continue
+    fi
+
+    # Detect the start of the tasks: key
+    if [[ "$line" =~ ^tasks:[[:space:]]*$ ]]; then
+      in_tasks=1
+      continue
+    fi
+
+    # If we are collecting tasks, look for list items
+    if [[ $in_tasks -eq 1 ]]; then
+      # A list item starts with optional whitespace then "- "
+      if [[ "$line" =~ ^[[:space:]]*-[[:space:]]+([A-Za-z0-9_]+) ]]; then
+        echo "${BASH_REMATCH[1]}"
+        found_any=1
+      elif [[ "$line" =~ ^[^[:space:]] ]]; then
+        # A non-indented, non-list line means we've left the tasks block
+        break
+      fi
+    fi
+  done < "$file"
+}
+
+mapfile -t TASK_IDS < <(extract_tasks "$story_file")
+
+# ---------------------------------------------------------------------------
+# Step 3: Validate tasks: list is present and non-empty
+# ---------------------------------------------------------------------------
+
+if [[ ${#TASK_IDS[@]} -eq 0 ]]; then
+  echo "ERROR: No tasks found in story frontmatter for '$STORY_ID' — cannot determine close state" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Step 4: Check each task's status
+# ---------------------------------------------------------------------------
+
+all_closeable=1
+
+for task_id in "${TASK_IDS[@]}"; do
+  # 4a. Locate the task file (always re-read from disk)
+  task_file=""
+  while IFS= read -r -d '' candidate; do
+    task_file="$candidate"
+    break
+  done < <(find "$TASKS_DIR" -maxdepth 1 -name "${task_id}_*.md" -print0 2>/dev/null)
+
+  if [[ -z "$task_file" ]]; then
+    echo "ERROR: Task file not found for '$task_id' — treating as open" >&2
+    all_closeable=0
+    continue
+  fi
+
+  # 4b/4c. Extract status: field from the task's frontmatter
+  task_status=""
+  in_fm=0
+  while IFS= read -r line; do
+    if [[ "$line" == "---" ]]; then
+      if [[ $in_fm -eq 0 ]]; then
+        in_fm=1
+        continue
+      else
+        break
+      fi
+    fi
+    if [[ $in_fm -eq 1 && "$line" =~ ^status:[[:space:]]*(.+)$ ]]; then
+      task_status="${BASH_REMATCH[1]}"
+      # Trim surrounding quotes if present
+      task_status="${task_status%\"}"
+      task_status="${task_status#\"}"
+      task_status="${task_status%\'}"
+      task_status="${task_status#\'}"
+      break
+    fi
+  done < "$task_file"
+
+  # 4d. Evaluate status
+  case "$task_status" in
+    Passed|Done)
+      # Task is in a terminal state — OK
+      ;;
+    "")
+      echo "OPEN: '$task_id' has no status field — treating as open" >&2
+      all_closeable=0
+      ;;
+    *)
+      echo "OPEN: '$task_id' has status '$task_status'" >&2
+      all_closeable=0
+      ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Step 5: Report result
+# ---------------------------------------------------------------------------
+
+if [[ $all_closeable -eq 1 ]]; then
+  echo "CLOSEABLE"
+  exit 0
+else
+  exit 1
+fi

package/skills/close-story/scripts/compute-scope-divergence.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# compute-scope-divergence.sh — Compute scope_divergence_flag for a task
+#
+# Usage: compute-scope-divergence.sh <execution_scope> <actual_files_changed> <actual_lines_delta>
+#
+# Reads project/configs/scope-thresholds.json (resolved from git root) and compares
+# the supplied diff stats against the thresholds that apply to <execution_scope>.
+#
+# Scope logic:
+#   inline  — divergence if actual_files_changed > inline_max_files
+#                       OR actual_lines_delta    > inline_max_lines
+#   story   — divergence if actual_files_changed > story_max_files
+#   task    — no automatic threshold: always false
+#   epic    — no automatic threshold: always false
+#   (any other value) — treated as task; always false
+#
+# Prints "true" or "false" on stdout and exits 0.
+# If the config file is missing or cannot be parsed, prints "false" (non-blocking),
+# emits a warning to stderr, and exits 0.
+#
+# Exit codes:
+#   0 — success (including graceful degradation when config is absent/malformed)
+#   1 — invalid argument count
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Argument validation
+# ---------------------------------------------------------------------------
+
+if [[ $# -ne 3 ]]; then
+  echo "Usage: $(basename "$0") <execution_scope> <actual_files_changed> <actual_lines_delta>" >&2
+  echo "  Example: $(basename "$0") inline 2 35" >&2
+  exit 1
+fi
+
+EXECUTION_SCOPE="${1}"
+ACTUAL_FILES="${2}"
+ACTUAL_LINES="${3}"
+
+# ---------------------------------------------------------------------------
+# Short-circuit: task and epic scopes never flag divergence
+# ---------------------------------------------------------------------------
+
+if [[ "$EXECUTION_SCOPE" == "task" || "$EXECUTION_SCOPE" == "epic" ]]; then
+  echo "false"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Locate the config file (relative to git root)
+# ---------------------------------------------------------------------------
+
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+
+if [[ -z "$GIT_ROOT" ]]; then
+  echo "WARNING: Not inside a git repository; cannot locate scope-thresholds.json. Skipping divergence flag." >&2
+  echo "false"
+  exit 0
+fi
+
+CONFIG_FILE="${GIT_ROOT}/project/configs/scope-thresholds.json"
+
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo "WARNING: scope-thresholds.json not found at '${CONFIG_FILE}'. Skipping divergence flag." >&2
+  echo "false"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Parse thresholds (jq preferred, plain shell fallback)
+# ---------------------------------------------------------------------------
+
+INLINE_MAX_FILES=""
+INLINE_MAX_LINES=""
+STORY_MAX_FILES=""
+
+if command -v jq >/dev/null 2>&1; then
+  INLINE_MAX_FILES=$(jq -r '.inline_max_files // empty' "$CONFIG_FILE" 2>/dev/null || true)
+  INLINE_MAX_LINES=$(jq -r '.inline_max_lines // empty' "$CONFIG_FILE" 2>/dev/null || true)
+  STORY_MAX_FILES=$(jq -r  '.story_max_files  // empty' "$CONFIG_FILE" 2>/dev/null || true)
+else
+  # Plain shell fallback: grep for the numeric value on the matching key line
+  INLINE_MAX_FILES=$(grep '"inline_max_files"' "$CONFIG_FILE" | grep -o '[0-9][0-9]*' | head -1 || true)
+  INLINE_MAX_LINES=$(grep '"inline_max_lines"' "$CONFIG_FILE" | grep -o '[0-9][0-9]*' | head -1 || true)
+  STORY_MAX_FILES=$(grep  '"story_max_files"'  "$CONFIG_FILE" | grep -o '[0-9][0-9]*' | head -1 || true)
+fi
+
+# Validate that all required thresholds were parsed
+if [[ -z "$INLINE_MAX_FILES" || -z "$INLINE_MAX_LINES" || -z "$STORY_MAX_FILES" ]]; then
+  echo "WARNING: scope-thresholds.json is malformed or missing required keys (inline_max_files, inline_max_lines, story_max_files). Skipping divergence flag." >&2
+  echo "false"
+  exit 0
+fi
+
+# Ensure values are integers
+if ! [[ "$INLINE_MAX_FILES" =~ ^[0-9]+$ && "$INLINE_MAX_LINES" =~ ^[0-9]+$ && "$STORY_MAX_FILES" =~ ^[0-9]+$ ]]; then
+  echo "WARNING: Non-integer threshold value found in scope-thresholds.json. Skipping divergence flag." >&2
+  echo "false"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Apply per-scope divergence logic
+# ---------------------------------------------------------------------------
+
+case "$EXECUTION_SCOPE" in
+  inline)
+    if [[ "$ACTUAL_FILES" -gt "$INLINE_MAX_FILES" ]] || [[ "$ACTUAL_LINES" -gt "$INLINE_MAX_LINES" ]]; then
+      echo "true"
+    else
+      echo "false"
+    fi
+    ;;
+  story)
+    if [[ "$ACTUAL_FILES" -gt "$STORY_MAX_FILES" ]]; then
+      echo "true"
+    else
+      echo "false"
+    fi
+    ;;
+  *)
+    # Unknown scope — treat conservatively as no divergence
+    echo "false"
+    ;;
+esac
+
+exit 0

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

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+STORY_ID="${1:-}"
+DATE_STARTED="${2:-}"
+DATE_COMPLETED="${3:-}"
+
+if [[ -z "$STORY_ID" ]]; then
+  echo "Usage: extract-diff-stats.sh <story-id> [<date_started> <date_completed>]" >&2
+  exit 1
+fi
+
+# Primary query — EST pattern match
+# Collect all --stat output for commits matching the story ID pattern
+STAT_OUTPUT=$(git log --all --stat --no-merges --grep="$STORY_ID" --pretty=format:"COMMIT:%H %s" 2>/dev/null || true)
+
+# Parse insertions and deletions from --stat lines
+# --stat lines look like: " 3 files changed, 45 insertions(+), 12 deletions(-)"
+# Using portable grep (BSD and GNU compatible) instead of grep -oP
+DIFF_ADDED=$(echo "$STAT_OUTPUT" | (grep -o '[0-9]* insertion' || true) | awk '{sum+=$1} END {print sum+0}')
+DIFF_REMOVED=$(echo "$STAT_OUTPUT" | (grep -o '[0-9]* deletion' || true) | awk '{sum+=$1} END {print sum+0}')
+COMMITS_MATCHED=$(git log --all --no-merges --grep="$STORY_ID" --pretty=format:"%H" 2>/dev/null | wc -l | tr -d ' ')
+
+# Secondary query — date-window unmatched count
+if [[ -n "$DATE_STARTED" && -n "$DATE_COMPLETED" ]]; then
+  ALL_IN_WINDOW=$(git log --all --no-merges \
+    --since="$DATE_STARTED" \
+    --until="${DATE_COMPLETED}T23:59:59" \
+    --pretty=format:"%H" 2>/dev/null || true)
+
+  MATCHED_HASHES=$(git log --all --no-merges --grep="$STORY_ID" --pretty=format:"%H" 2>/dev/null || true)
+
+  COMMITS_UNMATCHED=0
+  while IFS= read -r hash; do
+    [[ -z "$hash" ]] && continue
+    if ! echo "$MATCHED_HASHES" | grep -q "^$hash$"; then
+      COMMITS_UNMATCHED=$((COMMITS_UNMATCHED + 1))
+    fi
+  done <<< "$ALL_IN_WINDOW"
+else
+  COMMITS_UNMATCHED="unknown"
+fi
+
+# Output structured results
+echo "diff_added: $DIFF_ADDED"
+echo "diff_removed: $DIFF_REMOVED"
+echo "commits_matched: $COMMITS_MATCHED"
+echo "commits_unmatched_in_window: $COMMITS_UNMATCHED"