@jenga-ai/agent 1.1.0 → 1.1.1

package/scripts/check-worktree-liveness.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# scripts/check-worktree-liveness.sh — detect OS processes still rooted
+# inside a given worktree path.
+#
+# Usage:
+#   scripts/check-worktree-liveness.sh <worktree-path>
+#
+# Why this exists: `ListAgents` reports agent lifecycle, not detached OS
+# processes. A live incident (2026-08-25, see E37's Purpose) showed a
+# completed agent leaving shell polling loops running with their cwd inside
+# a worktree; `ListAgents` showed the agent itself as "completed" and gave
+# no signal that those loops were still alive, so the worktree was removed
+# out from under them. This script answers a narrower, deterministic
+# question instead: "does any OS process currently have its *current
+# working directory* rooted inside this path (the path itself, or any
+# subdirectory of it)?" It is intended to be run as a precondition before
+# `git worktree remove` (wired in the sibling task E37_S03_T02, not here —
+# this task only produces the standalone check).
+#
+# Detection mechanism (primary): `lsof +D <path> -F pcfn`
+#   `+D <path>` recursively restricts lsof's report to files open within
+#   that directory subtree (this alone gives us "inside the given path,
+#   including subdirectories" — verified locally against a nested-subdir
+#   case). `-F pcfn` is lsof's machine-parsable output mode, emitting one
+#   attribute per line: `p<pid>`, `c<command>`, `f<fd-or-descriptor-type>`,
+#   `n<file name>`, grouped per matching open-file record. Records are then
+#   filtered down to those whose `f` field is literally `cwd` — this is what
+#   distinguishes "this process's current working directory is here" from
+#   "this process merely has some unrelated file open under here" (e.g. a
+#   log file), which `+D` alone does not distinguish.
+#
+#   `-F pcfn` (not lsof's default human-readable columnar output) is used
+#   deliberately: column widths/ordering in the default output are not
+#   guaranteed stable across lsof versions/platforms, whereas the `-F` field
+#   protocol is. Verified directly against this repo's own Darwin runtime
+#   (lsof 4.91) — both an exact-path cwd match and a subdirectory cwd match
+#   are correctly reported, and process cwd is resolved through symlinks
+#   (macOS reports `/tmp/x` as `/private/tmp/x`), which is why the input
+#   path is canonicalized below before comparison.
+#
+# Detection mechanism (fallback, when `lsof` is not on PATH): enumerate
+# `/proc/[0-9]*` (Linux only — macOS has no `/proc`) and `readlink` each
+# `/proc/<pid>/cwd`, comparing against the canonicalized target path. macOS
+# ships `lsof` by default, so this branch is not expected to run on this
+# repo's actual runtime, but keeps the script functional on minimal Linux
+# containers that may lack `lsof`. If neither mechanism is available, the
+# script cannot determine liveness at all and fails closed (non-zero exit,
+# clear stderr message) rather than silently reporting "clear" when it does
+# not actually know.
+#
+# Command-line resolution for reported matches uses `ps -o command= -p
+# <pid>` — confirmed to behave identically on macOS's BSD `ps` and Linux's
+# GNU `ps`, unlike some other `ps` flags/keywords (e.g. `-e` listing
+# semantics differ between BSD and GNU `ps`, which is why the fallback path
+# above enumerates PIDs via `/proc` rather than `ps -e`).
+#
+# Caller-cwd self-detection hardening: if the *caller* invokes this script
+# from a shell whose own cwd is already inside the target path (e.g. `cd
+# <worktree> && check-worktree-liveness.sh <worktree>` — a very plausible
+# state right before a worktree is removed), every subprocess the script
+# forks (the `lsof` child, and the process-substitution subshell wrapping
+# it below, or the `readlink` calls in the /proc fallback) would otherwise
+# *inherit* that cwd, since bash processes inherit cwd from their parent by
+# default. That produced a real, reproduced false positive: the script's
+# own subprocess chain got reported as a "live process rooted in" the very
+# path being checked, even with zero genuinely orphaned processes running.
+# See project/rapports/problems/E37_S03_T01-self-detection-false-positive-remarks.md
+# for the original reproduction and the two fix options it proposed.
+#
+# Fix: immediately after resolving $ABS_PATH (and before spawning anything),
+# the script `cd`s itself to `/` — a path guaranteed to be outside every
+# possible target. This moves the *script's own process* outside the target,
+# so every descendant it forks from this point on inherits a cwd of `/`
+# instead of the caller's original cwd, regardless of where the caller
+# happened to be standing when it invoked this script. This is preferred
+# over tracking and excluding individual subprocess PIDs (the script's own
+# PID `$$` was already excluded as a courtesy, see below) because `cd /`
+# removes the precondition for the whole bug class structurally, rather
+# than requiring every current and future subprocess this script might ever
+# spawn to be enumerated and excluded by PID after the fact.
+#
+# The script also excludes its own PID ($$) from reported matches as a
+# second, defense-in-depth courtesy (now largely redundant given the `cd /`
+# fix above, but harmless to keep).
+#
+# Exit codes:
+#   0   clear — no live process found, no output
+#   1   one or more live processes found — PID(s) and command(s) printed
+#   2   invalid usage (wrong argument count / empty argument)
+#   3   <worktree-path> does not resolve to an existing directory
+#   4   unable to determine liveness on this platform (neither `lsof` nor
+#       /proc available) — fail closed, this is NOT the same as "clear"
+
+set -u
+
+SCRIPT_NAME="check-worktree-liveness.sh"
+
+usage() {
+  echo "Usage: $SCRIPT_NAME <worktree-path>" >&2
+  exit 2
+}
+
+[ "$#" -eq 1 ] || usage
+RAW_PATH="$1"
+[ -n "$RAW_PATH" ] || usage
+
+if [ ! -d "$RAW_PATH" ]; then
+  echo "$SCRIPT_NAME: '$RAW_PATH' is not a directory" >&2
+  exit 3
+fi
+
+# Canonicalize to an absolute, symlink-resolved path so comparisons against
+# process cwd values (which the OS reports fully resolved — e.g. macOS
+# reports /tmp as /private/tmp) match correctly regardless of how the
+# caller spelled the input path.
+ABS_PATH="$(cd "$RAW_PATH" 2>/dev/null && pwd -P)"
+if [ -z "$ABS_PATH" ]; then
+  echo "$SCRIPT_NAME: unable to resolve '$RAW_PATH' to an absolute path" >&2
+  exit 3
+fi
+
+# Move this process (and therefore every subprocess it forks from here on)
+# outside of every possible target path, so the scan below can never
+# self-detect regardless of the caller's cwd at invocation time. See the
+# "Caller-cwd self-detection hardening" comment in the header above. `/` is
+# always present and readable on every platform this script targets; if for
+# some reason it could not be `cd`'d into, fall through rather than abort —
+# worst case the pre-existing $$ exclusion below is the only mitigation,
+# same as before this fix.
+cd / 2>/dev/null || true
+
+SELF_PID="$$"
+FOUND_ANY=0
+REPORTED_PIDS=""
+
+already_reported() {
+  case " $REPORTED_PIDS " in
+    *" $1 "*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+report_match() {
+  pid="$1"
+  already_reported "$pid" && return 0
+  REPORTED_PIDS="$REPORTED_PIDS $pid"
+  cmd="$(ps -o command= -p "$pid" 2>/dev/null)"
+  [ -n "$cmd" ] || cmd="(command unavailable — process may have exited)"
+  echo "$SCRIPT_NAME: live process rooted in '$ABS_PATH' — PID $pid: $cmd"
+  FOUND_ANY=1
+}
+
+if command -v lsof >/dev/null 2>&1; then
+  current_pid=""
+  current_fd=""
+  while IFS= read -r line; do
+    case "$line" in
+      p*)
+        current_pid="${line#p}"
+        current_fd=""
+        ;;
+      f*)
+        current_fd="${line#f}"
+        ;;
+      n*)
+        if [ "$current_fd" = "cwd" ] && [ -n "$current_pid" ] && [ "$current_pid" != "$SELF_PID" ]; then
+          report_match "$current_pid"
+        fi
+        ;;
+    esac
+  done < <(lsof +D "$ABS_PATH" -F pcfn 2>/dev/null)
+else
+  if [ -d /proc ]; then
+    for pid_dir in /proc/[0-9]*; do
+      [ -e "$pid_dir" ] || continue
+      pid="${pid_dir#/proc/}"
+      [ "$pid" != "$SELF_PID" ] || continue
+      cwd_link="$(readlink "$pid_dir/cwd" 2>/dev/null)" || continue
+      [ -n "$cwd_link" ] || continue
+      case "$cwd_link" in
+        "$ABS_PATH"|"$ABS_PATH"/*)
+          report_match "$pid"
+          ;;
+      esac
+    done
+  else
+    echo "$SCRIPT_NAME: neither 'lsof' nor /proc is available on this system — cannot determine worktree liveness for '$ABS_PATH'" >&2
+    exit 4
+  fi
+fi
+
+[ "$FOUND_ANY" -eq 1 ] && exit 1
+exit 0

package/scripts/generate-rapport-manifest.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# scripts/generate-rapport-manifest.sh
+#
+# Regenerates the rapport manifest used by hooks/on_session_end.sh to detect
+# *new* problem rapports (project/rapports/problems/*.md, excluding resolved
+# *.IGNORE.md files). This script is the single source of truth for "what
+# does the manifest look like right now" — it is used both to produce the
+# committed seed manifest and, at runtime, by the hook itself whenever it
+# rewrites the manifest after finding new rapports.
+#
+# Entries are stored as paths relative to the repo root (e.g.
+# "project/rapports/problems/foo.md"), NOT absolute paths. The manifest is
+# a committed artifact shared across every clone/worktree, each of which
+# has a different absolute checkout location — absolute paths would make
+# the seed match nobody's filesystem but the one it was generated on.
+#
+# Safe to re-run at any time: it is a pure snapshot of the current directory
+# contents, never a diff, so running it twice in a row produces identical
+# output.
+#
+# Usage: scripts/generate-rapport-manifest.sh [output_file]
+#   output_file defaults to project/data/rapport_manifest.json
+
+set -euo pipefail
+
+# shellcheck source=lib/resolve-project-dir.sh
+source "$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh"
+
+PROJECT_DIR="$JENGA_PROJECT_DIR"
+RAPPORT_DIR="$PROJECT_DIR/project/rapports/problems"
+OUTPUT="${1:-$PROJECT_DIR/project/data/rapport_manifest.json}"
+
+mkdir -p "$(dirname "$OUTPUT")"
+
+if [ -d "$RAPPORT_DIR" ]; then
+  find "$RAPPORT_DIR" -name "*.md" ! -name "*.IGNORE.md" 2>/dev/null \
+    | sed "s|^$PROJECT_DIR/||" \
+    | sort | jq -R . | jq -s . > "$OUTPUT"
+else
+  echo "[]" > "$OUTPUT"
+fi
+
+echo "Wrote $(jq 'length' "$OUTPUT") rapport filename(s) to $OUTPUT"

package/scripts/idea_manager.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# scripts/idea_manager.sh — canonical owner of all project/ideas.md operations.
+# Run from the repository root.
+
+IDEA_FILE="project/ideas.md"
+TEMPLATE="skills/idea/assets/idea_template.md"
+
+usage() {
+  cat >&2 <<EOF
+Usage: $0 <subcommand> [args]
+
+Subcommands:
+  add "<entry>"    Append entry to project/ideas.md (auto-creates from template if missing)
+  list             Print all non-comment, non-blank entries (silent if file missing/empty)
+EOF
+  exit 1
+}
+
+# Filters out blank lines, lines starting with #, and HTML comments
+real_entries() {
+  grep -v '^\s*$' "$1" 2>/dev/null \
+    | grep -v '^\s*#' \
+    | grep -v '^\s*<!--'
+}
+
+case "${1:-}" in
+  add)
+    [ -z "${2:-}" ] && { echo "Error: add requires an entry argument" >&2; exit 1; }
+    if [ ! -f "$IDEA_FILE" ]; then
+      if [ ! -f "$TEMPLATE" ]; then
+        echo "Error: template not found at $TEMPLATE" >&2; exit 1
+      fi
+      cp "$TEMPLATE" "$IDEA_FILE"
+    fi
+    printf '%s\n' "$2" >> "$IDEA_FILE"
+    ;;
+
+  list)
+    [ ! -f "$IDEA_FILE" ] && exit 0
+    real_entries "$IDEA_FILE"
+    exit 0
+    ;;
+
+  *)
+    usage
+    ;;
+esac

package/scripts/install-worktree-commit-guard.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# scripts/install-worktree-commit-guard.sh — install a branch-guard pre-commit
+# hook into a given git worktree.
+#
+# Usage:
+#   scripts/install-worktree-commit-guard.sh <worktree-path> <branch-name>
+#
+# Writes a `pre-commit` hook that rejects any commit attempted while HEAD is
+# on a branch other than <branch-name>. This exists because a tester once
+# committed its verification of a task to `main` instead of the branch it was
+# actually verifying, from inside the worktree created for that task —
+# nothing mechanically prevented it (see E37's Purpose / E37_S02). Written
+# rules alone have a documented track record of drifting in this project
+# (E17 rollup note: two of its own stories were marked complete without the
+# underlying change landing), so this is a real guard, not just a documented
+# rule.
+#
+# IMPORTANT — why this does NOT just write to `git rev-parse --git-path
+# hooks`: that path resolves to the *shared* `hooks` directory common to the
+# main repository and every one of its linked worktrees (verified against
+# git 2.39: `git -C <any-worktree> rev-parse --git-path hooks` returns the
+# same common path for every worktree of the same repo, including the main
+# one). A naive install there would mean each new worktree's guard silently
+# clobbers every other worktree's guard (only the most-recently-created
+# worktree's branch would ever be accepted), and every *other* worktree would
+# then have its commits blocked outright, since the current branch would
+# never match the last-installed expected branch. That is worse than doing
+# nothing: it defeats the isolation this task exists to provide.
+#
+# The actual fix is git's per-worktree config file
+# (`$GIT_DIR/worktrees/<name>/config.worktree`, gated behind the
+# `extensions.worktreeConfig` repo extension) combined with the `core.hooksPath`
+# setting, which git DOES resolve per-worktree when scoped that way. This
+# script:
+#   1. enables `extensions.worktreeConfig` on the repo if not already set
+#      (idempotent, additive, does not disturb any existing config value —
+#      it only enables the *possibility* of per-worktree config overrides)
+#   2. resolves this worktree's own private git-dir via
+#      `git -C <worktree-path> rev-parse --absolute-git-dir` (this IS
+#      genuinely private per worktree — `.git/worktrees/<name>` for a linked
+#      worktree, verified distinct per worktree in the same test)
+#   3. points `core.hooksPath`, set with `git config --worktree` (so it lands
+#      in that worktree's own config.worktree file, not the shared config),
+#      at a private `hooks-guard` directory under that private git-dir
+#   4. writes the branch-guard `pre-commit` hook there
+#
+# This was manually verified end-to-end against a scratch repo with two
+# worktrees: installing the guard for worktree A blocked wrong-branch commits
+# in A and had zero effect on worktree B or the main repo, both of which kept
+# using the shared default hooks directory untouched.
+#
+# This script is intended to be called automatically at the end of the
+# `WorktreeCreate` hook in the canonical root `settings.json`, immediately
+# after `git worktree add "$DIR" -b "$NAME"` — see that file for the wiring.
+# It can also be run manually against any existing worktree, and is safe to
+# re-run against the same worktree (idempotent — simply overwrites the hook).
+#
+# Exit codes:
+#   0   hook installed successfully
+#   1   invalid usage (wrong argument count)
+#   2   <worktree-path> is not a valid git working tree
+
+set -u
+
+usage() {
+  echo "Usage: $0 <worktree-path> <branch-name>" >&2
+  exit 1
+}
+
+[ "$#" -eq 2 ] || usage
+WORKTREE_PATH="$1"
+BRANCH_NAME="$2"
+
+[ -n "$WORKTREE_PATH" ] || usage
+[ -n "$BRANCH_NAME" ] || usage
+
+if ! git -C "$WORKTREE_PATH" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "install-worktree-commit-guard: '$WORKTREE_PATH' is not a valid git working tree" >&2
+  exit 2
+fi
+
+# Enable per-worktree config overrides on the repo, if not already enabled.
+# This is a one-time, repo-wide, additive flag — it does not move or change
+# any existing config value, it only makes `git config --worktree` (used
+# below) actually take effect instead of silently writing to a file git
+# never reads.
+if [ "$(git -C "$WORKTREE_PATH" config --get extensions.worktreeConfig 2>/dev/null)" != "true" ]; then
+  git -C "$WORKTREE_PATH" config extensions.worktreeConfig true
+fi
+
+# This worktree's own private git-dir. For a linked worktree this resolves to
+# `.git/worktrees/<name>` (private to this worktree); for the main working
+# tree it resolves to the common `.git` dir itself. Either way it is safe to
+# scope a private hooks directory under it.
+PRIVATE_GIT_DIR="$(git -C "$WORKTREE_PATH" rev-parse --absolute-git-dir)"
+
+# A distinctly-named directory (not the default `hooks`) so this never
+# collides with, or gets confused for, whatever the shared default hooks
+# directory may already contain.
+HOOKS_DIR="$PRIVATE_GIT_DIR/hooks-guard"
+mkdir -p "$HOOKS_DIR"
+
+# Scope the override to THIS worktree only, via its private config.worktree
+# file — not the shared/common config, which would affect every worktree.
+git -C "$WORKTREE_PATH" config --worktree core.hooksPath "$HOOKS_DIR"
+
+HOOK_FILE="$HOOKS_DIR/pre-commit"
+
+# The expected branch name is baked into the generated hook as a literal
+# comparison value (it is fixed at install time — the branch this worktree
+# was created for). The *actual* branch is always re-checked live, at commit
+# time, via `git rev-parse --abbrev-ref HEAD`.
+cat > "$HOOK_FILE" <<EOF
+#!/usr/bin/env bash
+# Installed by scripts/install-worktree-commit-guard.sh — do not edit by hand.
+# Rejects any commit made while this worktree is not checked out on its
+# assigned branch: '$BRANCH_NAME'.
+set -u
+
+expected_branch="$BRANCH_NAME"
+current_branch="\$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
+
+if [ "\$current_branch" != "\$expected_branch" ]; then
+  echo "pre-commit: commit blocked — this worktree is assigned to branch '\$expected_branch' but HEAD is currently on '\$current_branch'." >&2
+  echo "pre-commit: verification/implementation commits for this worktree must land on '\$expected_branch', never on any other branch (including main)." >&2
+  exit 1
+fi
+
+exit 0
+EOF
+
+chmod +x "$HOOK_FILE"
+
+echo "install-worktree-commit-guard: installed branch guard for '$BRANCH_NAME' at $HOOK_FILE (core.hooksPath scoped to this worktree only)"

package/scripts/jenga-permission-level-switch.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# scripts/jenga-permission-level-switch.sh — switch the current session's
+# 5-tier permission level by copying the matching template into
+# .claude/settings.json and .agents/settings.json, and recording the level
+# in .jenga-permission-level.json at the repo root.
+#
+# Usage: bash scripts/jenga-permission-level-switch.sh <n>
+#   <n> must be an integer 1-5.
+#
+# Behavior:
+#   - Templates live at templates/permission-levels/level-<n>-<name>.json
+#     and are COMPLETE settings.json documents (defaultMode, env,
+#     permissions, hooks). The copy is a whole-file overwrite of the
+#     destination, not a merge — this intentionally drops any extra
+#     top-level blocks (e.g. autoMode) present in the destination but
+#     absent from the template. autoMode is never used at any permission
+#     level (see PROJECT_SUMMARY.md, epic E33).
+#   - Both destination writes use a temp-file-then-atomic-rename pattern.
+#   - .jenga-permission-level.json is only written after BOTH settings.json
+#     copies succeed. If the .claude/ copy succeeds but the .agents/ copy
+#     fails, the script fails loud (no rollback of the .claude/ copy, no
+#     write to .jenga-permission-level.json) and instructs the user to
+#     re-run — re-running with the same <n> is idempotent and self-heals
+#     the inconsistency, since every copy is an unconditional overwrite.
+#   - Invalid input (missing/extra args, non-integer, out of range 1-5)
+#     exits non-zero and makes zero file changes.
+#
+# Exit codes:
+#   0  Success — all three files updated consistently.
+#   1  Invalid usage/argument — no files changed.
+#   2  Mapped template file missing — no files changed.
+#   3  Failed to copy template to .claude/settings.json — no files changed.
+#   4  Failed to copy template to .agents/settings.json — .claude/settings.json
+#      WAS updated (inconsistent state); re-run the script to repair.
+#   5  Failed to write .jenga-permission-level.json — both settings.json
+#      files WERE updated (inconsistent state); re-run the script to repair.
+
+set -euo pipefail
+
+usage() {
+  echo "Usage: $(basename "$0") <n>   (n must be an integer 1-5)" >&2
+}
+
+if [[ $# -ne 1 ]]; then
+  echo "Error: expected exactly one argument, got $#." >&2
+  usage
+  exit 1
+fi
+
+LEVEL="$1"
+
+if ! [[ "$LEVEL" =~ ^[1-5]$ ]]; then
+  echo "Error: permission level must be an integer between 1 and 5, got '$LEVEL'." >&2
+  usage
+  exit 1
+fi
+
+case "$LEVEL" in
+  1) NAME="locked" ;;
+  2) NAME="guarded" ;;
+  3) NAME="standard" ;;
+  4) NAME="elevated" ;;
+  5) NAME="unrestricted" ;;
+esac
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+TEMPLATE="$REPO_ROOT/templates/permission-levels/level-${LEVEL}-${NAME}.json"
+CLAUDE_SETTINGS="$REPO_ROOT/.claude/settings.json"
+AGENTS_SETTINGS="$REPO_ROOT/.agents/settings.json"
+LEVEL_FILE="$REPO_ROOT/.jenga-permission-level.json"
+
+if [[ ! -f "$TEMPLATE" ]]; then
+  echo "Error: template file not found for level $LEVEL: $TEMPLATE" >&2
+  exit 2
+fi
+
+# Whole-file overwrite of destination via temp-file + atomic rename.
+copy_template() {
+  local dest="$1"
+  local tmp="${dest}.tmp"
+  mkdir -p "$(dirname "$dest")"
+  cp "$TEMPLATE" "$tmp" && mv "$tmp" "$dest"
+}
+
+if ! copy_template "$CLAUDE_SETTINGS"; then
+  echo "Error: failed to copy template to $CLAUDE_SETTINGS. No files changed." >&2
+  rm -f "${CLAUDE_SETTINGS}.tmp"
+  exit 3
+fi
+
+if ! copy_template "$AGENTS_SETTINGS"; then
+  echo "Error: failed to copy template to $AGENTS_SETTINGS." >&2
+  echo "State is now INCONSISTENT: $CLAUDE_SETTINGS was updated to level $LEVEL but $AGENTS_SETTINGS was not." >&2
+  echo ".jenga-permission-level.json was NOT updated. Re-run this script to repair (it is idempotent)." >&2
+  rm -f "${AGENTS_SETTINGS}.tmp"
+  exit 4
+fi
+
+# Only write the metadata file after both settings.json copies succeeded.
+LEVEL_TMP="${LEVEL_FILE}.tmp"
+if ! jq -n --argjson n "$LEVEL" '{"session_level": $n}' > "$LEVEL_TMP" || ! mv "$LEVEL_TMP" "$LEVEL_FILE"; then
+  echo "Error: failed to write $LEVEL_FILE." >&2
+  echo "State is now INCONSISTENT: both settings.json files were updated to level $LEVEL but .jenga-permission-level.json was not. Re-run this script to repair (it is idempotent)." >&2
+  rm -f "$LEVEL_TMP"
+  exit 5
+fi
+
+echo "Switched to level $LEVEL ($NAME)."
+exit 0

package/scripts/smoke-harness.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# smoke-harness.sh — Per-repository smoke test harness for inline-scoped task execution
+#
+# Usage:
+#   bash scripts/smoke-harness.sh [changed_file ...]
+#
+# If changed files are supplied as positional arguments, those are used directly.
+# If no arguments are given, the harness infers changed files from:
+#   git diff --name-only HEAD
+#
+# Discovery algorithm (in priority order):
+#   1. scripts/smoke.sh   — if present, delegate and return its exit code
+#   2. npm test           — if package.json has a .scripts.test entry and jq is available
+#   3. pytest             — if pytest is in PATH and setup.py/pyproject.toml exists
+#   4. go test ./...      — if go.mod exists
+#   5. No runner found    — pass if all changed files are config/docs; fail otherwise
+#
+# Exit codes:
+#   0 — smoke test passed (or structural-only change with no runner available)
+#   1 — smoke test failed (or logic files changed with no runner available)
+
+set -uo pipefail
+
+# ---------------------------------------------------------------------------
+# Resolve repo root
+# ---------------------------------------------------------------------------
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+# ---------------------------------------------------------------------------
+# Collect changed files
+# ---------------------------------------------------------------------------
+# Accept changed files as positional arguments; if none given, infer from git.
+# Uses a portable loop rather than mapfile/readarray (bash 3.x safe for macOS).
+if [[ $# -gt 0 ]]; then
+  CHANGED_FILES=("$@")
+else
+  CHANGED_FILES=()
+  while IFS= read -r line; do
+    [[ -n "$line" ]] && CHANGED_FILES+=("$line")
+  done < <(git diff --name-only HEAD 2>/dev/null || true)
+fi
+
+# ---------------------------------------------------------------------------
+# Step 1: Delegate to scripts/smoke.sh if it exists
+# ---------------------------------------------------------------------------
+if [[ -f "$REPO_ROOT/scripts/smoke.sh" ]]; then
+  echo "INFO: Found scripts/smoke.sh — delegating to project smoke test."
+  bash "$REPO_ROOT/scripts/smoke.sh"
+  exit $?
+fi
+
+# ---------------------------------------------------------------------------
+# Step 2: Infer npm test
+# Requires: package.json with a non-null .scripts.test field, and jq in PATH.
+# ---------------------------------------------------------------------------
+if [[ -f "$REPO_ROOT/package.json" ]]; then
+  if command -v jq > /dev/null 2>&1; then
+    if jq -e '.scripts.test // empty' "$REPO_ROOT/package.json" > /dev/null 2>&1; then
+      echo "INFO: Detected npm project with test script — running npm test."
+      cd "$REPO_ROOT" && npm test
+      exit $?
+    else
+      echo "INFO: package.json found but no .scripts.test entry — skipping npm test inference."
+    fi
+  else
+    echo "INFO: package.json found but jq is not available — skipping npm test inference."
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Step 3: Infer pytest
+# Requires: pytest in PATH, and setup.py or pyproject.toml at repo root.
+# ---------------------------------------------------------------------------
+if command -v pytest > /dev/null 2>&1; then
+  if [[ -f "$REPO_ROOT/setup.py" || -f "$REPO_ROOT/pyproject.toml" ]]; then
+    echo "INFO: Detected Python project — running pytest."
+    cd "$REPO_ROOT" && pytest
+    exit $?
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Step 4: Infer go test
+# Requires: go.mod at repo root.
+# ---------------------------------------------------------------------------
+if [[ -f "$REPO_ROOT/go.mod" ]]; then
+  echo "INFO: Detected Go project — running go test ./..."
+  cd "$REPO_ROOT" && go test ./...
+  exit $?
+fi
+
+# ---------------------------------------------------------------------------
+# Step 5: No test runner found — classify changed files
+#
+# Files are considered config/documentation if they match one of:
+#   - Extension: .json .yaml .yml .md .txt .toml .ini .cfg
+#   - Path prefix: docs/ project/ templates/
+#   - Shell scripts in scripts/: scripts/*.sh (structural scaffolding, not logic)
+# All other files are treated as logic/source files requiring a real test.
+# ---------------------------------------------------------------------------
+CONFIG_DOC_PATTERN='\.(json|yaml|yml|md|txt|toml|ini|cfg)$'
+STRUCTURAL_SCRIPT_PATTERN='^scripts/[^/]+\.sh$'
+STRUCTURAL_PATH_PATTERN='^(docs|project|templates)/'
+
+NON_CONFIG_FILES=()
+for f in "${CHANGED_FILES[@]}"; do
+  is_config=false
+
+  # Check extension pattern
+  if echo "$f" | grep -qE "$CONFIG_DOC_PATTERN"; then
+    is_config=true
+  fi
+
+  # Check structural script pattern (scripts/*.sh)
+  if echo "$f" | grep -qE "$STRUCTURAL_SCRIPT_PATTERN"; then
+    is_config=true
+  fi
+
+  # Check structural path prefix
+  if echo "$f" | grep -qE "$STRUCTURAL_PATH_PATTERN"; then
+    is_config=true
+  fi
+
+  if [[ "$is_config" == "false" ]]; then
+    NON_CONFIG_FILES+=("$f")
+  fi
+done
+
+if [[ ${#NON_CONFIG_FILES[@]} -gt 0 ]]; then
+  echo "ERROR: No smoke test runner found and the task touches logic/source files:" >&2
+  for f in "${NON_CONFIG_FILES[@]}"; do
+    echo "  - $f" >&2
+  done
+  echo "Add a test runner (scripts/smoke.sh, npm test, pytest, or go test) before marking this task complete." >&2
+  exit 1
+fi
+
+echo "INFO: No test runner discoverable; all changed files are config/docs/structural. Smoke test passes."
+exit 0