@jenga-ai/agent 1.0.1 → 1.1.1

package/scripts/worktree-remove-guard.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# scripts/worktree-remove-guard.sh — hard-block-by-default liveness
+# precondition for `git worktree remove`, wired into the `WorktreeRemove`
+# hook in (root, canonical) settings.json.
+#
+# Why this exists: see project/board/epics/E37_inter-agent-completion-signaling.md
+# and project/board/stories/E37_S03_worktree-remove-liveness-precondition.md.
+# `git worktree remove --force` previously ran unconditionally as soon as
+# the WorktreeRemove hook fired, with no precondition of any kind — this is
+# how a 2026-08-25 incident's orphaned shell polling loops got their cwd
+# deleted out from under them. This script now runs
+# scripts/check-worktree-liveness.sh (E37_S03_T01) first, and only proceeds
+# to `git worktree remove --force` if that check reports the path clear (or
+# an explicit override is set).
+#
+# Invocation modes:
+#
+#   1. Hook mode (no positional worktree-path argument): reads a JSON
+#      payload from stdin and extracts `.worktree_path` (required) and an
+#      optional `.force_ignore_liveness` boolean field. This is how the
+#      WorktreeRemove hook actually invokes this script — matching the
+#      pre-existing `jq -r '.worktree_path'` convention this script
+#      replaces. Note: the native harness's WorktreeRemove hook JSON
+#      schema is outside this repo's control (its `ExitWorktree` tool
+#      exposes only `action`/`discard_changes`, no pass-through custom
+#      field), so `.force_ignore_liveness` on the payload is supported for
+#      any caller that *does* control the JSON directly (e.g. a script
+#      invoking this guard outside the native tool), but is not the primary
+#      override mechanism for the native hook path — see the environment
+#      variable below for that.
+#
+#   2. CLI mode (direct/manual invocation — used for this script's own
+#      testing and any other scripted use outside the hook):
+#        scripts/worktree-remove-guard.sh [--force-ignore-liveness] <worktree-path>
+#
+# Override (works in both modes): set the environment variable
+#   WORKTREE_REMOVE_FORCE_IGNORE_LIVENESS=1
+# immediately before invoking this script (directly, or before whatever
+# triggers the WorktreeRemove hook). Accepted truthy values: 1, true, TRUE,
+# True, yes, YES. This is the one lever guaranteed to work regardless of
+# invocation mode or what JSON the calling harness does or doesn't pass
+# through. It must be set explicitly on each invocation — it is never read
+# from a file, never cached, and never a default; every invocation re-reads
+# the environment fresh.
+#
+# Decision logic:
+#   - If an override is set (CLI flag, JSON field, or env var): skip the
+#     liveness check, print a visible bypass notice to stderr, and run
+#     `git worktree remove --force <path>`.
+#   - Otherwise, run scripts/check-worktree-liveness.sh <path>. ANY non-zero
+#     exit blocks removal by default — not just exit 1 ("live process
+#     found"), but also exit 2/3/4 (usage error / invalid path / liveness
+#     indeterminate), since none of those represent "the path is
+#     affirmatively clear," consistent with that script's own fail-closed
+#     design. `git worktree remove` is never invoked in this branch. The
+#     liveness check's own PID/command output (or error message) is
+#     surfaced to the caller, plus a note on how to override.
+#   - On a clear (exit 0) result: proceed to `git worktree remove --force
+#     <path>` exactly as the old unconditional one-liner did, with no extra
+#     output — the "clear worktree" case must behave exactly as before,
+#     with no added friction.
+#
+# Exit codes:
+#   *   whatever `git worktree remove --force <path>` itself exits with, if
+#       removal proceeded (clear path, or override set)
+#   1   blocked — liveness check reported non-zero and no override was set;
+#       git worktree remove was NOT run
+#   2   usage error — no worktree path resolvable from CLI args or stdin
+#       JSON, or an unrecognized flag
+
+set -u
+
+SCRIPT_NAME="worktree-remove-guard.sh"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd -P)"
+LIVENESS_SCRIPT="$SCRIPT_DIR/check-worktree-liveness.sh"
+
+# Resolve a safe anchor directory to relocate this process's own cwd into
+# further below (see the "Caller-cwd self-detection hardening" block after
+# argument parsing) — the main repository's working-tree root, derived from
+# the shared git common dir so it resolves correctly regardless of which
+# worktree this script's own cwd currently happens to be in. Must be
+# computed now, from the ORIGINAL cwd, since `git rev-parse` depends on
+# being inside a git working tree.
+GIT_COMMON_DIR_RAW="$(git rev-parse --git-common-dir 2>/dev/null)"
+SAFE_ANCHOR=""
+if [ -n "$GIT_COMMON_DIR_RAW" ]; then
+  SAFE_ANCHOR="$(cd "$(dirname "$GIT_COMMON_DIR_RAW")" >/dev/null 2>&1 && pwd -P)"
+fi
+
+FORCE_OVERRIDE=0
+WORKTREE_PATH=""
+
+# --- Parse CLI-style args, if any. ---
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --force-ignore-liveness)
+      FORCE_OVERRIDE=1
+      shift
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -*)
+      echo "$SCRIPT_NAME: unknown flag '$1'" >&2
+      exit 2
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+if [ "$#" -ge 1 ]; then
+  WORKTREE_PATH="$1"
+fi
+
+# --- Hook mode: no positional worktree path given, so read the JSON
+#     payload the WorktreeRemove hook receives on stdin. ---
+if [ -z "$WORKTREE_PATH" ]; then
+  if [ -t 0 ]; then
+    echo "$SCRIPT_NAME: no worktree path given (expected a positional argument, or JSON on stdin with a 'worktree_path' field)" >&2
+    exit 2
+  fi
+  PAYLOAD="$(cat)"
+  WORKTREE_PATH="$(printf '%s' "$PAYLOAD" | jq -r '.worktree_path // empty' 2>/dev/null)"
+  if [ "$FORCE_OVERRIDE" -eq 0 ]; then
+    PAYLOAD_OVERRIDE="$(printf '%s' "$PAYLOAD" | jq -r 'if .force_ignore_liveness == true then "true" else "false" end' 2>/dev/null)"
+    [ "$PAYLOAD_OVERRIDE" = "true" ] && FORCE_OVERRIDE=1
+  fi
+fi
+
+if [ -z "$WORKTREE_PATH" ]; then
+  echo "$SCRIPT_NAME: no worktree path provided (expected a positional argument, or a 'worktree_path' field on stdin JSON)" >&2
+  exit 2
+fi
+
+# Resolve WORKTREE_PATH to an absolute, symlink-resolved path NOW, while
+# still in the original cwd — we're about to relocate this process's own
+# cwd away (hardening below), and a relative path would no longer resolve
+# correctly against the caller's original cwd afterward. (In practice the
+# hook always supplies an absolute path — see WorktreeCreate's own
+# `DIR="$JENGA_PROJECT_DIR/.claude/worktrees/$NAME"` construction — this
+# also makes relative paths work correctly for CLI-mode/manual use.) If
+# resolution fails (path does not exist), fall through with the original,
+# unresolved string; check-worktree-liveness.sh and/or `git worktree
+# remove` will report the appropriate error themselves.
+WORKTREE_PATH_RESOLVED="$(cd "$WORKTREE_PATH" 2>/dev/null && pwd -P)"
+[ -n "$WORKTREE_PATH_RESOLVED" ] && WORKTREE_PATH="$WORKTREE_PATH_RESOLVED"
+
+# --- Environment override — checked last so it can force the bypass
+#     regardless of how the path was supplied. ---
+case "${WORKTREE_REMOVE_FORCE_IGNORE_LIVENESS:-}" in
+  1|true|TRUE|True|yes|YES)
+    FORCE_OVERRIDE=1
+    ;;
+esac
+
+# Caller-cwd self-detection hardening (this script's own layer of it — see
+# the matching comment block in check-worktree-liveness.sh for the
+# underlying check script's own layer, which protects only its own spawned
+# subprocesses). THIS script is what actually invokes that check below —
+# if this script's own process was itself launched with a cwd already
+# inside the worktree being removed (a real, expected scenario: the
+# WorktreeRemove hook may fire from a session whose cwd is inside the
+# worktree about to be removed, right before cleanup), this script's own
+# PID would itself be "a live process rooted in" that path at the moment
+# the check runs — check-worktree-liveness.sh's $$-exclusion only ever
+# covers its own PID, not its caller's. Relocating to the main repo root
+# (resolved above, before WORKTREE_PATH is used any further) — rather than
+# to `/` — means both the liveness check AND the eventual `git worktree
+# remove` below keep working normally (git needs to run from inside some
+# working tree), while still guaranteeing neither this script's own process
+# nor the check script it spawns as a child can be cwd'd inside the target,
+# regardless of what cwd the original caller had. Falls back to `/` only if
+# the repo-root anchor could not be resolved (a degenerate case; `git
+# worktree remove` itself will then fail with its own clear error).
+# (Residual, out-of-our-control limitation: if some ancestor further up the
+# process chain — e.g. the harness's own hook-runner shell, if it stays
+# resident rather than exec'ing straight into this script — independently
+# keeps its own cwd inside the target and stays alive while waiting on this
+# script, that ancestor is a separate process this script cannot
+# retroactively relocate; the courtesy $$-style exclusion pattern used
+# throughout these two scripts only ever covers processes each script
+# itself controls.)
+cd "${SAFE_ANCHOR:-/}" 2>/dev/null || true
+
+if [ "$FORCE_OVERRIDE" -eq 1 ]; then
+  echo "$SCRIPT_NAME: liveness check explicitly bypassed (--force-ignore-liveness / WORKTREE_REMOVE_FORCE_IGNORE_LIVENESS) for '$WORKTREE_PATH' — proceeding to remove without checking for live processes." >&2
+  git worktree remove --force "$WORKTREE_PATH"
+  exit $?
+fi
+
+LIVENESS_OUTPUT="$("$LIVENESS_SCRIPT" "$WORKTREE_PATH" 2>&1)"
+LIVENESS_EXIT=$?
+
+if [ "$LIVENESS_EXIT" -eq 0 ]; then
+  git worktree remove --force "$WORKTREE_PATH"
+  exit $?
+fi
+
+echo "$SCRIPT_NAME: BLOCKED — not removing '$WORKTREE_PATH' (liveness check exited $LIVENESS_EXIT):" >&2
+[ -n "$LIVENESS_OUTPUT" ] && echo "$LIVENESS_OUTPUT" >&2
+echo "$SCRIPT_NAME: git worktree remove was NOT run. If this is expected (e.g. a known, accepted background process), re-run with an explicit override: pass --force-ignore-liveness (CLI mode), a true 'force_ignore_liveness' field on the input JSON (hook mode), or set WORKTREE_REMOVE_FORCE_IGNORE_LIVENESS=1 in the environment (either mode)." >&2
+exit 1

package/skills/clearify/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: clearify
+description: Clarifies ambiguous, dense, or under-specified prompts and conversation on request — inspects an attached prompt or falls back to the current conversation and surfaces plain-language clarifications with examples.
+keywords:
+  - clarify this
+  - clarify
+  - what do you mean
+  - I don't understand
+  - wtf
+  - explain that again
+  - can you simplify
+examples:
+  - "clarify this"
+  - "clearify the last message"
+  - "wtf does this mean"
+  - "I don't understand what you're asking me to do here"
+alias: wtf
+---
+
+# Clearify — Ambiguity Clarification
+
+> **Note on the `alias: wtf` frontmatter field:** this repo has no runtime mechanism that reads an `alias` key to route slash commands — no existing `SKILL.md` implements one, and `project/configs/workflow.json` has no alias registry. The field here documents the intended relationship only. `/wtf` is made invocable as a working alias by the companion skill folder at `skills/wtf/SKILL.md`, which delegates to these same instructions.
+
+## Instructions
+
+1. **Determine the target content.**
+   - If the user attached a prompt, file, or pasted block of text with this invocation, treat that as the target content.
+   - Otherwise, fall back to the most recent user message, plus any surrounding conversation context needed to make sense of it (e.g. the message it's replying to, an earlier instruction it references).
+   - Note: this is the only fallback distinction that matters — do not ask the user which content to clarify; infer it from what's available.
+
+2. **Identify ambiguous or dense formulations** in the target content. Look for:
+   - Jargon or domain-specific terms used without definition
+   - Unclear pronouns or references ("it", "that", "this one" — where the referent isn't obvious)
+   - Compound asks (multiple distinct requests bundled into one sentence)
+   - Unstated assumptions (the request depends on context the reader doesn't have)
+   - Vague quantifiers or qualifiers ("soon", "a bit", "some of them") where precision matters
+   - Overloaded or dense sentences that pack too much meaning into too little structure
+
+3. **For each ambiguous item found, output a structured block** with:
+   - **Plain-language clarification** — what it most likely means, stated simply and directly
+   - **Simplified restatement** — the original phrasing rewritten in plain terms
+   - **Additional context** — relevant background the user may be missing (why this term/reference matters, what it typically implies)
+   - **Example(s)** — a concrete worked example, included only where it would actually help clarify the specific ambiguity — skip this sub-section for an item if an example wouldn't add value, rather than manufacturing a weak one
+
+4. **Format the output so it's scannable.** Use a header or bold label per ambiguous item (e.g. `### 1. "the usual setup"` or `**1. "the usual setup"**`) — never collapse multiple ambiguous items into a single unstructured paragraph. If there are multiple items, number them in the order they appear in the source content.
+
+5. **Handle the zero-ambiguity case explicitly.** If nothing in the target content is actually ambiguous, dense, or under-specified, say so plainly — e.g. "Nothing here looks ambiguous — the request is clear as written." Do not manufacture findings just to have something to report.
+
+## Examples
+- `/clearify` — Clarify the most recent user message / relevant conversation context
+- `/clearify <pasted text>` — Clarify the attached text directly
+- `/wtf` — Alias for `/clearify`, invoked via the companion skill in `skills/wtf/`

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