@jenga-ai/agent 1.1.0 → 1.2.0

package/skills/jenga/scripts/board-scan.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/jenga/scripts/board-scan.sh
+#
+# Deterministic board inventory for `/jenga`'s interactive scope-selection
+# flow (E45). Walks project/board/epics/, project/board/stories/, and
+# project/board/tasks/ and emits a structured JSON array describing every
+# item on the board.
+#
+# This is the SINGLE SOURCE OF TRUTH for board contents in E45. Per this
+# repo's "Scripts Over Inline Logic" principle, no other script or agent
+# instruction may re-scan the board independently — every consumer below
+# reads this script's stdout instead:
+#
+#   - E45_S01_T02 (fuzzy-ID grammar parser)      resolves user-typed IDs
+#     against the `id`/`type` fields this script emits.
+#   - E45_S01_T03 (cascade resolver)             expands an epic/story
+#     selection to eligible descendants using `epic_id`/`story_id`/`status`.
+#   - E45_S02_T01 (interactive picker)           renders the numbered
+#     hierarchical checklist from this inventory.
+#   - E45_S02_T02 (confirmation-tree renderer)   renders the nested
+#     Epic > Story > Task confirmation tree from this inventory.
+#
+# ---------------------------------------------------------------------------
+# USAGE
+# ---------------------------------------------------------------------------
+#   skills/jenga/scripts/board-scan.sh
+#
+# No arguments. Reads project/board/ under the resolved project root (see
+# lib/resolve-project-dir.sh — honours CLAUDE_PROJECT_DIR / the git repo
+# root / cwd, in that priority order).
+#
+# ---------------------------------------------------------------------------
+# OUTPUT SCHEMA (stable — downstream scripts depend on these exact names)
+# ---------------------------------------------------------------------------
+# stdout is a single JSON array. Nothing else is ever written to stdout.
+# Each element is an object:
+#
+#   {
+#     "id":       "E45_S01_T01",          // the item's own board ID
+#     "type":     "epic" | "story" | "task",
+#     "epic_id":  "E45",                   // this item's epic: itself (epic),
+#                                           // its parent (story/task), or
+#                                           // null if the frontmatter omits it
+#     "story_id": "E45_S01",               // this item's story: itself
+#                                           // (story), its parent (task),
+#                                           // or null for epics / if absent
+#     "title":    "Board scanner script — structured inventory ...",
+#     "status":   "Pending",               // verbatim value of the
+#                                           // frontmatter `status:` field
+#     "summary":  "Everything else in E45 reads this script's output ...",
+#     "file":     "project/board/tasks/E45_S01_T01_board-scanner-script.md"
+#   }
+#
+# Field notes:
+#   - `epic_id` / `story_id` are ALWAYS PRESENT KEYS, whose value is `null`
+#     when not applicable/absent — never an omitted key. Consumers should
+#     use a null-safe read (e.g. `.epic_id // empty` in jq), not assume the
+#     key exists with a non-null value.
+#   - `summary` is a single-line, best-effort excerpt:
+#       * epic  -> first non-empty, non-heading line after "## Purpose"
+#       * story -> first non-empty line after the "# Story: <Title>"
+#                  heading and before the next "##" heading (the
+#                  "As a ... I want ... so that ..." statement)
+#       * task  -> first non-empty, non-heading line after "## Description"
+#     `summary` is "" (empty string, never absent) when no matching section
+#     is found.
+#   - `file` is repo-relative (relative to the resolved project root), using
+#     forward slashes, suitable for display or re-opening the source file.
+#   - Array order: epics first, then stories, then tasks; within each type,
+#     files are sorted lexically by filename (stable across runs).
+#
+# ---------------------------------------------------------------------------
+# ERROR HANDLING
+# ---------------------------------------------------------------------------
+# A single board file that fails to parse (unreadable, or missing the `id`
+# frontmatter key) is SKIPPED and reported as a warning on stderr — it does
+# NOT abort the scan or corrupt stdout. This is a deliberate design choice:
+# the picker and confirmation renderer need a scan that degrades gracefully
+# on one malformed file rather than producing no output for the whole board.
+#
+# Exit codes:
+#   0   scan completed (stdout is always valid JSON on this path, even if
+#       some files were skipped with stderr warnings, and even if the
+#       result is an empty array because no board files exist yet)
+#   1   the board root (project/board/) does not exist at all, or python3
+#       is not available — both are real setup problems, not per-file noise
+#
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Resolve JENGA_PROJECT_DIR the same way every other script in this repo
+# does (CLAUDE_PROJECT_DIR -> git toplevel -> cwd). Falls back to locating
+# the repo root relative to this script if the shared helper is missing.
+if [ -f "$SCRIPT_DIR/../../../lib/resolve-project-dir.sh" ]; then
+  # shellcheck source=lib/resolve-project-dir.sh
+  source "$SCRIPT_DIR/../../../lib/resolve-project-dir.sh"
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+  JENGA_PROJECT_DIR="$CLAUDE_PROJECT_DIR"
+else
+  JENGA_PROJECT_DIR="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)"
+fi
+
+BOARD_DIR="$JENGA_PROJECT_DIR/project/board"
+
+if [ ! -d "$BOARD_DIR" ]; then
+  echo "Error: board directory not found at $BOARD_DIR" >&2
+  exit 1
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "Error: python3 is required by board-scan.sh" >&2
+  exit 1
+fi
+
+python3 - "$JENGA_PROJECT_DIR" "$BOARD_DIR" <<'PY'
+import json
+import re
+import sys
+from pathlib import Path
+
+project_root = Path(sys.argv[1])
+board_dir = Path(sys.argv[2])
+
+FRONTMATTER_RE = re.compile(r'^---\n(.*?)\n---\n?(.*)$', re.DOTALL)
+TOP_LEVEL_KV_RE = re.compile(r'^([A-Za-z_][A-Za-z0-9_]*):[ \t]*(.*)$')
+
+
+def parse_frontmatter(text):
+    """Return (fields_dict, body_text). Only top-level `key: value` lines
+    are captured (indented list items such as `  - E01_S02` are skipped
+    intentionally — this scanner reads each board file directly and does
+    not need to follow parent->children ID lists)."""
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return {}, text
+    fm_text, body = m.group(1), m.group(2)
+    fields = {}
+    for line in fm_text.splitlines():
+        if not line or line[0] in (' ', '\t', '#'):
+            continue
+        km = TOP_LEVEL_KV_RE.match(line)
+        if not km:
+            continue
+        key, val = km.group(1), km.group(2).strip()
+        val = val.strip('"').strip("'")
+        fields[key] = val
+    return fields, body
+
+
+def first_line_after_heading(body, heading_re):
+    """First non-empty line strictly after a line matching heading_re, up
+    to (not including) the next '#'-prefixed heading line."""
+    lines = body.splitlines()
+    for i, line in enumerate(lines):
+        if heading_re.match(line.strip()):
+            for candidate in lines[i + 1:]:
+                stripped = candidate.strip()
+                if not stripped:
+                    continue
+                if stripped.startswith('#'):
+                    return ""
+                return stripped
+            return ""
+    return ""
+
+
+PURPOSE_HEADING_RE = re.compile(r'^##\s+Purpose\s*$', re.IGNORECASE)
+DESCRIPTION_HEADING_RE = re.compile(r'^##\s+Description\s*$', re.IGNORECASE)
+TITLE_HEADING_RE = re.compile(r'^#\s+Story:.*$', re.IGNORECASE)
+
+
+def summarize(item_type, body):
+    if item_type == "epic":
+        return first_line_after_heading(body, PURPOSE_HEADING_RE)
+    if item_type == "task":
+        return first_line_after_heading(body, DESCRIPTION_HEADING_RE)
+    # story: first non-empty line after the "# Story: <Title>" heading and
+    # before the next "##" heading.
+    return first_line_after_heading(body, TITLE_HEADING_RE)
+
+
+TYPE_DIRS = [
+    ("epic", board_dir / "epics"),
+    ("story", board_dir / "stories"),
+    ("task", board_dir / "tasks"),
+]
+
+items = []
+
+for item_type, dir_path in TYPE_DIRS:
+    if not dir_path.is_dir():
+        continue
+    for f in sorted(dir_path.glob("*.md")):
+        try:
+            text = f.read_text(encoding="utf-8")
+        except Exception as e:
+            print(f"Warning: skipping {f}: read error: {e}", file=sys.stderr)
+            continue
+
+        fields, body = parse_frontmatter(text)
+        item_id = fields.get("id", "")
+        if not item_id:
+            print(f"Warning: skipping {f}: missing 'id' in frontmatter", file=sys.stderr)
+            continue
+
+        if item_type == "epic":
+            epic_id = item_id
+            story_id = None
+        elif item_type == "story":
+            epic_id = fields.get("epic_id") or None
+            story_id = item_id
+        else:
+            epic_id = fields.get("epic_id") or None
+            story_id = fields.get("story_id") or None
+
+        try:
+            rel_file = f.relative_to(project_root).as_posix()
+        except ValueError:
+            rel_file = f.as_posix()
+
+        items.append({
+            "id": item_id,
+            "type": item_type,
+            "epic_id": epic_id,
+            "story_id": story_id,
+            "title": fields.get("title", ""),
+            "status": fields.get("status", ""),
+            "summary": summarize(item_type, body),
+            "file": rel_file,
+        })
+
+json.dump(items, sys.stdout, indent=2)
+sys.stdout.write("\n")
+PY

package/skills/jenga/scripts/cascade-resolve.sh

@@ -0,0 +1,297 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/jenga/scripts/cascade-resolve.sh
+#
+# Cascade resolver for `/jenga`'s interactive scope-selection flow (E45).
+# Given a resolved board-ID set (exact `E##` / `E##_S##` / `E##_S##_T##`
+# IDs — already resolved by the picker in E45_S02_T01 or by
+# `resolve-id.sh` in E45_S01_T02; this script does NOT do fuzzy-ID
+# parsing), expands any epic or story selection into its full set of
+# eligible descendants:
+#
+#   - An epic selection expands to all of its stories and their tasks.
+#   - A story selection expands to all of its tasks.
+#   - Expansion only includes descendants in a Pending/eligible state —
+#     terminal-status descendants (Passed, Passed with remarks, Failed,
+#     Rejected, Blocked, Done) are excluded.
+#   - A descendant epic/story that has not yet been broken down on the
+#     board (zero stories under an epic, zero tasks under a story) is
+#     flagged under `undecomposed` so jenga's existing Phase 1/2
+#     decomposition logic can pick it up. This script never decomposes
+#     anything itself — it only flags the need.
+#
+# Per this repo's "Scripts Over Inline Logic" principle and the sibling
+# board-scan.sh's own header contract, this script consumes
+# board-scan.sh's JSON output as the SINGLE SOURCE OF TRUTH for board
+# contents — it does not re-scan project/board/ independently.
+#
+# Downstream consumer: E45_S02_T02 (confirmation-tree renderer) reads
+# this script's output to render the nested Epic > Story > Task
+# confirmation tree with per-level counts.
+#
+# ---------------------------------------------------------------------------
+# USAGE
+# ---------------------------------------------------------------------------
+#   skills/jenga/scripts/cascade-resolve.sh "<comma-separated-ids>"
+#
+# One argument: a comma-separated list of exact, already-resolved board
+# IDs (e.g. "E01,E02_S03,E04_S05_T06"). Whitespace around commas/ids is
+# trimmed. IDs are matched case-sensitively against the board (board IDs
+# are always uppercase per templates/SCRUM_BOARD_SCHEMA.md).
+#
+# ---------------------------------------------------------------------------
+# OUTPUT SCHEMA (stable — downstream scripts depend on these exact names)
+# ---------------------------------------------------------------------------
+# stdout is a single JSON object. Nothing else is ever written to stdout.
+#
+#   {
+#     "items": [ <board-scan.sh item objects — see that script's header
+#                 for the per-item schema — for every epic/story/task
+#                 node in the resolved tree, deduplicated> ],
+#     "resolved_ids": ["E01", "E01_S02", "E01_S02_T01"],
+#     "counts": {"epics": 1, "stories": 1, "tasks": 1},
+#     "undecomposed": [
+#       {"id": "E02", "type": "epic", "missing": "stories"},
+#       {"id": "E02_S01", "type": "story", "missing": "tasks"}
+#     ],
+#     "warnings": [
+#       {"input": "E99", "reason": "not found on board"},
+#       {"input": "E01_S02_T09", "reason": "excluded: terminal status (Passed)"},
+#       {"input": "foo", "reason": "malformed ID (does not match E##, E##_S##, or E##_S##_T## shape)"}
+#     ]
+#   }
+#
+# Field notes:
+#   - `items` includes every node actually present in the resolved tree —
+#     epics/stories that were directly selected or expanded into, plus
+#     eligible (non-terminal) descendant stories/tasks. It is NOT limited
+#     to leaf tasks, because the confirmation-tree renderer needs the
+#     full Epic > Story > Task shape, not just an execution list.
+#   - `resolved_ids` is the same set as `items`, as a flat list of IDs
+#     (convenience for callers that only need IDs).
+#   - `counts` reflects unique nodes of each type present in `items` —
+#     i.e. what the confirmation tree will actually render — not a count
+#     of input arguments.
+#   - `undecomposed` entries mean "this epic/story has zero children on
+#     the board at all", distinct from "this epic/story has children but
+#     none are eligible" (which is not flagged — there is nothing to
+#     decompose, the work is simply already done or blocked).
+#   - `warnings` covers three non-fatal per-input problems: an ID not
+#     found on the board, a directly-selected task/story/epic excluded
+#     for being in a terminal status, and a malformed ID shape. None of
+#     these abort the run — valid inputs are still resolved and stdout is
+#     still a complete, valid JSON object.
+#
+# ---------------------------------------------------------------------------
+# ERROR HANDLING
+# ---------------------------------------------------------------------------
+# Exit codes:
+#   0   resolution completed (stdout is always valid JSON on this path,
+#       even if some inputs produced warnings, and even if the result is
+#       an empty items/resolved_ids set because every input was invalid)
+#   1   a structural failure: no argument given, board-scan.sh itself
+#       failed or produced unparseable output, or python3 is unavailable
+#       — these are real setup problems, not per-input noise
+#
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [ $# -lt 1 ] || [ -z "${1// /}" ]; then
+  echo "Usage: cascade-resolve.sh \"<comma-separated-ids>\"" >&2
+  echo "Example: cascade-resolve.sh \"E01,E02_S03,E04_S05_T06\"" >&2
+  exit 1
+fi
+
+RAW_IDS="$1"
+
+# No project-dir resolution needed here: board-scan.sh (invoked below)
+# already resolves JENGA_PROJECT_DIR itself (CLAUDE_PROJECT_DIR -> git
+# toplevel -> cwd) and is the sole source of board contents for this
+# script, per the "Scripts Over Inline Logic" / single-source-of-truth
+# contract documented in its own header.
+BOARD_SCAN="$SCRIPT_DIR/board-scan.sh"
+
+if [ ! -x "$BOARD_SCAN" ]; then
+  echo "Error: board-scan.sh not found or not executable at $BOARD_SCAN" >&2
+  exit 1
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "Error: python3 is required by cascade-resolve.sh" >&2
+  exit 1
+fi
+
+BOARD_JSON_FILE="$(mktemp)"
+trap 'rm -f "$BOARD_JSON_FILE"' EXIT
+
+if ! "$BOARD_SCAN" > "$BOARD_JSON_FILE"; then
+  echo "Error: board-scan.sh failed" >&2
+  exit 1
+fi
+
+python3 - "$RAW_IDS" "$BOARD_JSON_FILE" <<'PY'
+import json
+import re
+import sys
+
+raw_ids_arg = sys.argv[1]
+board_json_file = sys.argv[2]
+
+try:
+    with open(board_json_file, encoding="utf-8") as f:
+        board_items = json.load(f)
+except Exception as e:
+    print(f"Error: could not parse board-scan.sh output as JSON: {e}", file=sys.stderr)
+    sys.exit(1)
+
+# Terminal statuses, verbatim from templates/SCRUM_BOARD_SCHEMA.md's
+# Status Values table. An item in one of these statuses is never
+# included as an expanded/eligible descendant.
+TERMINAL_STATUSES = {
+    "Passed",
+    "Passed with remarks",
+    "Failed",
+    "Rejected",
+    "Blocked",
+    "Done",
+}
+
+EPIC_RE = re.compile(r'^E\d{2}$')
+STORY_RE = re.compile(r'^E\d{2}_S\d{2}$')
+TASK_RE = re.compile(r'^E\d{2}_S\d{2}_T\d{2}$')
+
+by_id = {}
+stories_by_epic = {}
+tasks_by_story = {}
+
+for item in board_items:
+    item_id = item.get("id", "")
+    if not item_id:
+        continue
+    by_id[item_id] = item
+    if item.get("type") == "story":
+        epic_id = item.get("epic_id")
+        if epic_id:
+            stories_by_epic.setdefault(epic_id, []).append(item)
+    elif item.get("type") == "task":
+        story_id = item.get("story_id")
+        if story_id:
+            tasks_by_story.setdefault(story_id, []).append(item)
+
+
+def classify(item_id):
+    if TASK_RE.match(item_id):
+        return "task"
+    if STORY_RE.match(item_id):
+        return "story"
+    if EPIC_RE.match(item_id):
+        return "epic"
+    return None
+
+
+resolved = {}       # id -> item, dedup-preserving insertion order
+resolved_order = []
+undecomposed = []
+undecomposed_seen = set()
+warnings = []
+
+
+def add_item(item):
+    item_id = item["id"]
+    if item_id not in resolved:
+        resolved[item_id] = item
+        resolved_order.append(item_id)
+
+
+def flag_undecomposed(entry_id, entry_type, missing):
+    key = (entry_id, missing)
+    if key in undecomposed_seen:
+        return
+    undecomposed_seen.add(key)
+    undecomposed.append({"id": entry_id, "type": entry_type, "missing": missing})
+
+
+def expand_story(story_item, include_story_node=True):
+    """Add an eligible story node and its eligible (non-terminal) tasks.
+    Flags the story as undecomposed if it has zero tasks at all."""
+    if include_story_node:
+        add_item(story_item)
+    story_id = story_item["id"]
+    tasks = tasks_by_story.get(story_id, [])
+    if not tasks:
+        flag_undecomposed(story_id, "story", "tasks")
+        return
+    for task_item in tasks:
+        if task_item.get("status") in TERMINAL_STATUSES:
+            continue
+        add_item(task_item)
+
+
+raw_inputs = [tok.strip() for tok in raw_ids_arg.split(",")]
+raw_inputs = [tok for tok in raw_inputs if tok]
+
+for input_id in raw_inputs:
+    item_type = classify(input_id)
+    if item_type is None:
+        warnings.append({
+            "input": input_id,
+            "reason": "malformed ID (does not match E##, E##_S##, or E##_S##_T## shape)",
+        })
+        continue
+
+    item = by_id.get(input_id)
+    if item is None:
+        warnings.append({"input": input_id, "reason": "not found on board"})
+        continue
+
+    if item_type == "epic":
+        # Always include the epic node itself for tree display, regardless
+        # of the epic's own status — cascading is about its descendants.
+        add_item(item)
+        stories = stories_by_epic.get(input_id, [])
+        if not stories:
+            flag_undecomposed(input_id, "epic", "stories")
+            continue
+        for story_item in stories:
+            if story_item.get("status") in TERMINAL_STATUSES:
+                continue
+            expand_story(story_item, include_story_node=True)
+
+    elif item_type == "story":
+        add_item(item)
+        expand_story(item, include_story_node=False)
+
+    else:  # task
+        if item.get("status") in TERMINAL_STATUSES:
+            warnings.append({
+                "input": input_id,
+                "reason": f"excluded: terminal status ({item.get('status')})",
+            })
+            continue
+        add_item(item)
+
+items_out = [resolved[i] for i in resolved_order]
+counts = {"epics": 0, "stories": 0, "tasks": 0}
+for it in items_out:
+    t = it.get("type")
+    if t == "epic":
+        counts["epics"] += 1
+    elif t == "story":
+        counts["stories"] += 1
+    elif t == "task":
+        counts["tasks"] += 1
+
+output = {
+    "items": items_out,
+    "resolved_ids": resolved_order,
+    "counts": counts,
+    "undecomposed": undecomposed,
+    "warnings": warnings,
+}
+
+json.dump(output, sys.stdout, indent=2)
+sys.stdout.write("\n")
+PY