@jenga-ai/agent 1.3.0 → 2.0.0

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

@@ -0,0 +1,345 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/close-story/scripts/check-privatized.sh
+#
+# Static (run-independent) `.publicignore` membership check for a single
+# board ticket, invoked by /close-story at both task granularity (Step 2's
+# per-task loop) and story granularity (Step 4's finalization), per
+# E51_S03_T03. Unlike `Merged` (skills/self-sync/scripts/mark-merged.sh) and
+# `Publicized` (skills/mirror-public/scripts/mark-publicized.sh, E51_S03_T02),
+# which both react to a specific run's file diff, `Privatized` has NO
+# dependency on any run ever having occurred -- it is a pure blocklist
+# membership test against the ticket's own derived touched-file list, per
+# templates/SCRUM_BOARD_SCHEMA.md's "Static vs. Reactive Status Setting"
+# section.
+#
+# Usage: check-privatized.sh <id> <board-file-path>
+#
+#   <id>               EST ticket id -- a task id (E##_S##_T##) or a story id
+#                       (E##_S##). The anchored-grep commit matching (below)
+#                       is what keeps a story id from over-matching its own
+#                       children's commits, so the same script handles both
+#                       granularities with no separate code path.
+#   <board-file-path>   Path to the ticket's own board markdown file (task or
+#                       story), used to read its current `status:` and as the
+#                       write target.
+#
+# Touched-file derivation -- IDENTICAL technique to
+# skills/self-sync/scripts/mark-merged.sh (reused, not reinvented, per this
+# task's own description):
+#   1. git log --all --no-merges --extended-regexp \
+#        --grep="<id>([^0-9_]|$)" --pretty=format:'%H'
+#      The anchored pattern (not a plain substring grep) is required so a
+#      story id like "E51_S03" does not over-match every one of its own
+#      child tasks' commits -- the character immediately following a story
+#      id in a child task's commit message is "_", which the anchor
+#      excludes.
+#   2. Per matched commit: `git diff --name-only <sha>~1..<sha>`, falling
+#      back to `git diff-tree --no-commit-id --name-only -r <sha>` for a
+#      root commit with no parent.
+#   3. Union (dedup) the file paths across all matched commits.
+#   4. Zero matched commits -> nothing to check -> UNCHANGED (not an error).
+#
+# .publicignore matching -- ported (not sourced) from
+# skills/mirror-public/scripts/mirror.sh's `_publicignore_rule_for` helper:
+# directory-prefix match for trailing-"/" lines, glob match against the full
+# relative path and the basename for everything else, skipping comments,
+# blank lines, and "+"-prefixed include lines (which never block anything).
+# This is a deliberate, flagged duplication of matching logic -- not a
+# `source` of mirror.sh, which unconditionally loads config.json and
+# requires rsync near the top of its execution, neither of which this
+# lighter, dependency-free check needs. Same tradeoff mark-merged.sh's own
+# header comment already documents and accepts for its COPY_SET extraction.
+#
+# A ticket is "fully blocklisted" iff EVERY file in its derived touched-file
+# list matches SOME .publicignore pattern. Partial coverage leaves the
+# ticket unchanged, no error (mirrors AC5's "no files fully covered"
+# language, applied to the blocklist side).
+#
+# Precedence / mismatch logging (AC4, this script's half of it): a ticket
+# already at `status: Publicized` that is found fully blocklisted still gets
+# overwritten to `Privatized` (Privatized wins -- the static, always-knowable
+# check takes precedence per the story's AC4 and
+# templates/SCRUM_BOARD_SCHEMA.md's "Publicized / Privatized / Deployed
+# Lifecycle Relationship" section), but the contradiction is logged to
+# project/logs/events.json as `event: publicized_privatized_mismatch` (same
+# array-of-objects convention already used by session_start/etc., and the
+# same event name E51_S03_T02's own task description documents for the
+# reverse-direction mismatch) so it's flagged for investigation rather than
+# silently resolved. The read-modify-write against events.json is wrapped in
+# scripts/with-lock.sh since multiple sessions may be writing to it
+# concurrently.
+#
+# A ticket already at `status: Privatized` is skipped without error
+# (idempotency) -- same defensive-skip convention mark-merged.sh uses for
+# its own terminal status.
+#
+# Output contract (stdout, single line) -- consumed by /close-story's prose
+# steps to decide whether to report a Privatized ticket:
+#   PRIVATIZED   status was written (or already Privatized -- treated the
+#                same by the caller: either way the ticket ends this call at
+#                status Privatized)
+#   UNCHANGED    ticket left as-is (zero matched commits, partial coverage,
+#                or already Privatized with nothing further to do)
+#
+# Exit codes:
+#   0   success (covers both PRIVATIZED and UNCHANGED outcomes)
+#   1   error (bad usage, missing file, or a status-write failure)
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+IFS=$'\n\t'
+
+die() {
+  printf 'check-privatized.sh: error: %s\n' "$*" >&2
+  exit 1
+}
+
+log() {
+  printf 'check-privatized.sh: %s\n' "$*" >&2
+}
+
+usage() {
+  cat <<'EOF'
+Usage: check-privatized.sh <id> <board-file-path>
+
+Static .publicignore membership check for a single ticket (task or story).
+Prints PRIVATIZED or UNCHANGED to stdout. See script header for full
+semantics.
+EOF
+}
+
+if [ $# -ne 2 ]; then
+  usage >&2
+  die "expected exactly 2 arguments, got $#"
+fi
+
+ID="$1"
+BOARD_FILE="$2"
+
+[ -f "$BOARD_FILE" ] || die "board file not found: $BOARD_FILE"
+
+# -----------------------------------------------------------------------------
+# Locate script + repo root (same symlink-resolution + repo-root derivation
+# pattern as mark-merged.sh, so this script behaves identically whether
+# invoked directly or via a symlink).
+# -----------------------------------------------------------------------------
+
+SCRIPT_PATH="${BASH_SOURCE[0]}"
+while [ -h "$SCRIPT_PATH" ]; do
+  LINK_TARGET="$(readlink "$SCRIPT_PATH")"
+  case "$LINK_TARGET" in
+    /*) SCRIPT_PATH="$LINK_TARGET" ;;
+    *)  SCRIPT_PATH="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)/$LINK_TARGET" ;;
+  esac
+done
+SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)"
+
+REPO_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || true)"
+[ -n "$REPO_ROOT" ] || die "could not locate repo root (git rev-parse failed from $SCRIPT_DIR)"
+
+PUBLICIGNORE="$REPO_ROOT/.publicignore"
+[ -f "$PUBLICIGNORE" ] || die ".publicignore not found at $PUBLICIGNORE"
+
+WITH_LOCK_SCRIPT="$REPO_ROOT/scripts/with-lock.sh"
+UPDATE_FRONTMATTER_SCRIPT="$REPO_ROOT/skills/close-story/scripts/update-task-frontmatter.sh"
+EVENTS_FILE="$REPO_ROOT/project/logs/events.json"
+
+[ -f "$WITH_LOCK_SCRIPT" ] || die "expected script not found: $WITH_LOCK_SCRIPT"
+[ -f "$UPDATE_FRONTMATTER_SCRIPT" ] || die "expected script not found: $UPDATE_FRONTMATTER_SCRIPT"
+
+# -----------------------------------------------------------------------------
+# Frontmatter field reader -- same "line == ---" boundary-detection style
+# already used by update-task-frontmatter.sh / mark-merged.sh.
+# -----------------------------------------------------------------------------
+
+read_frontmatter_field() {
+  local file="$1" key="$2"
+  awk -v key="$key" '
+    NR==1 && $0=="---" { infm=1; next }
+    infm && $0=="---" { exit }
+    infm && $0 ~ ("^" key ":") {
+      sub("^" key ":[ \t]*", "", $0)
+      print $0
+      exit
+    }
+  ' "$file"
+}
+
+trim() {
+  local s="$1"
+  s="${s#"${s%%[![:space:]]*}"}"
+  s="${s%"${s##*[![:space:]]}"}"
+  s="${s%\"}"; s="${s#\"}"
+  s="${s%\'}"; s="${s#\'}"
+  printf '%s' "$s"
+}
+
+CURRENT_STATUS="$(trim "$(read_frontmatter_field "$BOARD_FILE" "status")")"
+
+if [ "$CURRENT_STATUS" = "Privatized" ]; then
+  log "$ID: already Privatized -- skip (idempotent no-op)"
+  echo "UNCHANGED"
+  exit 0
+fi
+
+# -----------------------------------------------------------------------------
+# Touched-file derivation -- identical technique to mark-merged.sh.
+# -----------------------------------------------------------------------------
+
+commits_for_ticket() {
+  local id="$1"
+  git -C "$REPO_ROOT" log --all --no-merges --extended-regexp \
+    --grep="${id}([^0-9_]|\$)" --pretty=format:'%H' 2>/dev/null || true
+}
+
+commit_files() {
+  local sha="$1"
+  if git -C "$REPO_ROOT" rev-parse --verify -q "${sha}~1" >/dev/null 2>&1; then
+    git -C "$REPO_ROOT" diff --name-only "${sha}~1..${sha}" 2>/dev/null || true
+  else
+    git -C "$REPO_ROOT" diff-tree --no-commit-id --name-only -r "$sha" 2>/dev/null || true
+  fi
+}
+
+collect_touched_files() {
+  local id="$1"
+  local shas sha
+  shas="$(commits_for_ticket "$id")"
+  [ -n "$shas" ] || return 0
+  while IFS= read -r sha; do
+    [ -n "$sha" ] || continue
+    commit_files "$sha"
+  done <<< "$shas" | sort -u
+}
+
+TOUCHED="$(collect_touched_files "$ID")"
+
+if [ -z "$TOUCHED" ]; then
+  log "$ID: zero matched EST-tagged commits -- left unchanged"
+  echo "UNCHANGED"
+  exit 0
+fi
+
+# -----------------------------------------------------------------------------
+# .publicignore matching -- ported from mirror.sh's _publicignore_rule_for.
+#
+# Prints the matching .publicignore line and returns 0 on a match; returns 1
+# with no output if nothing matched. Directory-prefix match for trailing-"/"
+# lines, glob match against the full relative path and the basename for
+# everything else, skipping comments/blank lines/"+"-prefixed include lines.
+# -----------------------------------------------------------------------------
+
+_publicignore_rule_for() {
+  local rel_path="$1" line pattern base dirpat
+  base="$(basename "$rel_path")"
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      ''|'#'*|'+'*) continue ;;
+    esac
+    pattern="$line"
+    case "$pattern" in
+      '- '*) pattern="${pattern#- }" ;;
+    esac
+    [ -n "$pattern" ] || continue
+    case "$pattern" in
+      */)
+        dirpat="${pattern%/}"
+        case "$rel_path" in
+          "$dirpat"/*)
+            printf '%s\n' "$line"
+            return 0
+            ;;
+        esac
+        ;;
+      *)
+        case "$rel_path" in
+          $pattern)
+            printf '%s\n' "$line"
+            return 0
+            ;;
+        esac
+        case "$base" in
+          $pattern)
+            printf '%s\n' "$line"
+            return 0
+            ;;
+        esac
+        ;;
+    esac
+  done < "$PUBLICIGNORE"
+  return 1
+}
+
+# True (0) iff every line of $1 (touched files, newline-separated) matches
+# some .publicignore pattern.
+is_fully_blocklisted() {
+  local touched="$1"
+  local line
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    _publicignore_rule_for "$line" >/dev/null || return 1
+  done <<< "$touched"
+  return 0
+}
+
+if ! is_fully_blocklisted "$TOUCHED"; then
+  log "$ID: not fully covered by .publicignore -- left unchanged"
+  echo "UNCHANGED"
+  exit 0
+fi
+
+# -----------------------------------------------------------------------------
+# Fully blocklisted. Precedence check against a contradictory Publicized
+# status (AC4) before writing.
+# -----------------------------------------------------------------------------
+
+if [ "$CURRENT_STATUS" = "Publicized" ]; then
+  log "$ID: WARNING -- ticket is status: Publicized but every touched file matches .publicignore; Privatized takes precedence (overwriting), logging mismatch"
+
+  TOUCHED_JSON_LIST="$(printf '%s\n' "$TOUCHED" | awk '
+    BEGIN { printf "[" ; first=1 }
+    { if (!first) printf ","; printf "\"%s\"", $0; first=0 }
+    END { printf "]" }
+  ')"
+  [ -n "$TOUCHED_JSON_LIST" ] || TOUCHED_JSON_LIST="[]"
+
+  MISMATCH_EVENT=$(printf '{"event": "publicized_privatized_mismatch", "agent": "developer", "id": "%s", "file": "%s", "touched_files": %s, "date": "%s"}' \
+    "$ID" "$BOARD_FILE" "$TOUCHED_JSON_LIST" "$(date -u +%Y-%m-%dT%H:%M:%SZ)")
+
+  if [ -f "$EVENTS_FILE" ]; then
+    "$WITH_LOCK_SCRIPT" "$EVENTS_FILE" -- bash -c '
+      set -euo pipefail
+      events_file="$1"
+      new_event="$2"
+      tmp="$(mktemp)"
+      if command -v python3 >/dev/null 2>&1; then
+        python3 -c "
+import json, sys
+path = sys.argv[1]
+new_event = json.loads(sys.argv[2])
+with open(path) as f:
+    data = json.load(f)
+data.append(new_event)
+with open(path, \"w\") as f:
+    json.dump(data, f, indent=2)
+    f.write(\"\n\")
+" "$events_file" "$new_event"
+      else
+        echo "check-privatized.sh: python3 not available -- could not append mismatch event" >&2
+        rm -f "$tmp"
+        exit 1
+      fi
+    ' _ "$EVENTS_FILE" "$MISMATCH_EVENT" || log "WARNING: failed to log publicized_privatized_mismatch event for $ID (continuing with status overwrite)"
+  else
+    log "WARNING: $EVENTS_FILE not found -- could not log publicized_privatized_mismatch event"
+  fi
+fi
+
+log "$ID: fully covered by .publicignore -- writing status: Privatized ($BOARD_FILE)"
+if ! "$WITH_LOCK_SCRIPT" "$BOARD_FILE" -- bash "$UPDATE_FRONTMATTER_SCRIPT" "$BOARD_FILE" status Privatized; then
+  die "failed to write status: Privatized for $ID ($BOARD_FILE)"
+fi
+
+echo "PRIVATIZED"
+exit 0

package/skills/commit/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: commit
+name: j:commit
 description: Commit implemented epic, story, or task work using the EST naming convention. Also handles user-action prerequisites and new-epic boundaries. Use after completing any EST work item.
 keywords:
   - commit

package/skills/continue/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: continue
+name: j:continue
 description: Check project status across PROJECT_SUMMARY.md, epics, and stories to determine what should be done next. Reports "All done!" if everything is complete.
 keywords:
   - continue

package/skills/deep-dive/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: deep-dive
+name: j:deep-dive
 description: >
   Multi-phase investigation workflow. The scrum-master orchestrates information
   gathering, interactive brainstorming, critical scrutiny, and solution assessment

package/skills/dev-done/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: dev-done
+name: j:dev-done
 description: Commit the current work and immediately sync it into the .claude/ and .agents/ mirrors. Shortcut that chains /commit followed by /self-sync.
 keywords:
   - dev done

package/skills/distribute/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: distribute
+name: j:distribute
 description: Distribute Jenga AI framework files from this private monorepo to one or more consuming projects via the local filesystem. Manages release type selection, version bumping, dry-run preview, per-target file copy, and a post-distribution git commit.
 keywords:
   - distribute

package/skills/do/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: do
+name: j:do
 description: Execute tasks from the scrum board. Reads from project/todo.md, resolves each entry to its full scrum board context, and drives the developer agent through implementation with the correct sender object and communication contract. Loops until all selected tasks are done or the user exits.
 keywords:
   - do
@@ -16,6 +16,14 @@ metadata:
 
 # Do — Execute Scrum Board Tasks
 
+## `--trivial` Flag
+
+**Syntax:** `/do <id> --trivial` — a dispatch-time override, distinct from `/todo --trivial` (a creation-time flag documented in `skills/todo/SKILL.md`). Where `/todo --trivial` writes a brand-new task straight to `execution_scope: inline`, `/do <id> --trivial` overrides an **already-existing** task's `execution_scope` — whatever it currently is, including absent (legacy tasks with no execution-scope fields at all) — to `inline` at the moment it's dispatched. See `### 4.1.5. \`--trivial\` Dispatch-Time Override` below for the full mechanics.
+
+**No softer fallback tier — hard fallback to the full pipeline instead.** Unlike `light` scope (which sits between `inline` and `task`), `--trivial` always forces `inline` directly, with no intermediate tier to fall back to first. To compensate, a `--trivial`-forced run that fails `scripts/smoke-harness.sh` or shows detected scope creep mid-run automatically re-routes to the full `task` pipeline (worktree + developer + tester) via the same `#### Fallback to Full Task-Scope Pipeline` procedure the `light`-tier fallback uses — see `### 4.2`'s failure-handling branches and the shared Fallback subsection under `### 4.3`.
+
+**Human-only, same as `/todo --trivial`.** `--trivial` is invoked by a human typing `/do <id> --trivial` — it is never applied autonomously by `/jenga` or the scrum-master's own breakdown/dispatch passes.
+
 ## Instructions
 
 ### 0. Load threshold config
@@ -318,9 +326,40 @@ Before invoking the developer, check whether this task was manually scoped by a
       ```
       Then proceed to step 4.2.
 
+### 4.1.5. `--trivial` Dispatch-Time Override
+
+After override validation (step 4.1) and before branching on `execution_scope` in step 4.2, check whether this invocation was `/do <id> --trivial`.
+
+1. **Detect the flag.** If the task was invoked as `/do <id>` with no `--trivial` flag, skip this entire section and proceed directly to `### 4.2`.
+
+2. **If `--trivial` is present**, read the task's current `execution_scope` from frontmatter. Treat an absent value as `task`, per the epic's backward-compatibility rule (a task that omits `execution_scope` is treated as `execution_scope: task`). Call this the **prior tier** — this covers both tasks nobody flagged as trivial at creation (an already-assigned `story`/`task`/`light` tier) and legacy tasks with no `execution_scope` set at all.
+
+3. **Overwrite `execution_scope` to `inline`** in the task's frontmatter, unconditionally — `--trivial` always forces `inline`, never a softer "lightest safe tier."
+
+4. **Record the override for audit**, reusing the existing `jenga_assigned` / `override_justification` pairing already defined in `templates/SCRUM_BOARD_SCHEMA.md` for exactly this situation ("scope overridden by a human"), rather than inventing a new field:
+   - Set `jenga_assigned: false` (if not already `false`).
+   - Set (or append to, if already present) `override_justification`:
+     ```
+     override_justification: "/do --trivial dispatch-time override on <date>: execution_scope forced from '<prior_tier>' to 'inline' by human operator."
+     ```
+   - Also set (or append to) `scope_rationale`, mirroring the phrasing convention `skills/todo/scripts/add_trivial_task.sh` already uses for the creation-time flag, so both audit fields agree on the prior tier:
+     ```
+     scope_rationale: "forced inline via /do --trivial (dispatch-time override); prior execution_scope was '<prior_tier>'"
+     ```
+   - Emit a non-fatal log line (styled like 4.2's `AUTO-CORRECTION` message):
+     ```
+     TRIVIAL OVERRIDE [<task_id>]: execution_scope forced from "<prior_tier>" to "inline" via --trivial dispatch-time override.
+     ```
+
+5. **Set an in-session marker** (this dispatch is a `--trivial`-forced run) — this does not need to be persisted to frontmatter; it only needs to survive for the remainder of this `/do` invocation. This marker is distinct from an organically-assigned `execution_scope: inline` task (one the scrum-master or `/jenga` assigned `inline` to directly, with no `--trivial` involved) because its failure handling differs — see `### 4.2`'s failure-handling steps below. Do not confuse a `--trivial`-forced run with an organic `inline` task when applying those steps.
+
+6. **Proceed to `### 4.2. Inline Execution Path`** with `execution_scope` now `inline`. Everything else about inline execution (implementation, smoke test invocation, commit convention) is identical between an organic `inline` task and a `--trivial`-forced one — only the two failure-handling branches in `### 4.2` differ, per the marker set in step 5 above.
+
+**Precedence with the locked-task dispatch guard.** If `crucial_level: locked` (checked by `### 4.2`'s locked-task dispatch guard, which always runs and always wins), `--trivial` is redundant but harmless — the task was already going to be forced `inline`. The locked-task guard's own audit fields take precedence for that correction; do not double-write conflicting `override_justification` text. A `locked` task's fallback behavior remains "halt and report," never the `--trivial` fallback below, regardless of whether `--trivial` was also passed.
+
 ### 4.2. Inline Execution Path (execution_scope: inline)
 
-After resolving the task context (step 4) and passing override validation (step 4.1), read `execution_scope` from the task frontmatter.
+After resolving the task context (step 4), passing override validation (step 4.1), and applying the `--trivial` dispatch-time override if present (step 4.1.5), read `execution_scope` from the task frontmatter.
 
 **Locked-task dispatch guard (defense-in-depth).** Before branching on `execution_scope` below, read `crucial_level` from the task frontmatter (per `templates/SCRUM_BOARD_SCHEMA.md`'s Crucial Flag Fields). If `crucial_level: locked`:
 
@@ -349,12 +388,14 @@ After resolving the task context (step 4) and passing override validation (step
      WARNING [<task_id>]: scripts/smoke-harness.sh not found. Smoke test skipped (stub pass).
      ```
 4. **If the smoke test exits non-zero**:
-   - Write `status: Failed` to the task's frontmatter.
-   - Emit:
-     ```
-     INLINE TASK FAILED [<task_id>]: smoke test returned non-zero exit code. Task marked Failed. Halting.
-     ```
-   - Do not commit. Do not proceed to the next task.
+   - **If this is a `--trivial`-forced run** (marker set in step 4.1.5 — and `crucial_level` is not `locked`, which never falls back, per 4.1.5's precedence note): do NOT write `status: Failed`. `--trivial` always forces `inline` with no softer "lightest safe tier" to fall back to first, so a smoke-harness failure here goes straight to the shared `#### Fallback to Full Task-Scope Pipeline` procedure below (origin: `trivial`). Do not proceed with the remaining inline steps below — the Fallback procedure takes over from here.
+   - **Otherwise** (an organically-assigned `inline` task, `--trivial` not involved): behavior is unchanged from before —
+     - Write `status: Failed` to the task's frontmatter.
+     - Emit:
+       ```
+       INLINE TASK FAILED [<task_id>]: smoke test returned non-zero exit code. Task marked Failed. Halting.
+       ```
+     - Do not commit. Do not proceed to the next task.
 5. **If the smoke test passes**:
    - Commit the changes using the standard commit convention (`task(<task_id>): <short description>`) via `/commit` in inline mode (E32_S04_T03).
    - Run the **Intent-vs-Diff Check** (see `### 5.1. Intent-vs-Diff Check` below) for this task.
@@ -365,9 +406,58 @@ After resolving the task context (step 4) and passing override validation (step
 7. `inline` tasks always have `needs_docs: false` — skip plan and summary documentation for the implemented task.
 8. Continue to `### 6. Verify documentation`, then `### 7. After successful completion`.
 
-If the implementation cannot be completed inline (scope is larger than anticipated), abort and re-route to the normal developer path (step 5) — unless `crucial_level: locked`, in which case do not re-route; re-attempt inline or halt and report, per the locked-task dispatch guard above.
+If the implementation cannot be completed inline (scope is larger than anticipated — detected scope creep mid-run):
+- **If this is a `--trivial`-forced run** (and `crucial_level` is not `locked`): invoke the shared `#### Fallback to Full Task-Scope Pipeline` procedure below (origin: `trivial`) — the same procedure the smoke-harness-failure branch above uses, not a second bespoke re-route.
+- **Otherwise** (an organically-assigned `inline` task): abort and re-route to the normal developer path (step 5), unchanged from before.
+- **Regardless of `--trivial`**, if `crucial_level: locked`, do not re-route via either path above; re-attempt inline or halt and report, per the locked-task dispatch guard above.
 
-**If `execution_scope` is not `inline`** (or is absent / `task` / `story` / `epic`) **and `crucial_level` is not `locked`**, proceed to step 5 (invoke the developer agent) as normal.
+**If `execution_scope` is `light`** (and `crucial_level` is not `locked` — the locked-task dispatch guard above already ran and takes precedence over any scope check), proceed to `### 4.3. Light Execution Path` below instead of step 5.
+
+**If `execution_scope` is not `inline` and not `light`** (or is absent / `task` / `story` / `epic`) **and `crucial_level` is not `locked`**, proceed to step 5 (invoke the developer agent) as normal.
+
+### 4.3. Light Execution Path (execution_scope: light)
+
+After resolving the task context (step 4), passing override validation (step 4.1), and applying the `--trivial` dispatch-time override if present (step 4.1.5 — note `--trivial` always forces `inline`, so a `light`-scoped task only reaches this section if `--trivial` was *not* passed), if `execution_scope: light` and `crucial_level` is not `locked` (per the locked-task dispatch guard in 4.2, which runs first and always wins), route the task through this path instead of the full `task`-scope pipeline in step 5.
+
+`light` sits between `inline` and `task`: unlike `inline`, it spawns a real developer subagent (so it can handle small branching logic that inline's main-session execution isn't suited for); unlike `task`, it does not create a dedicated worktree and does not invoke the tester as a separate step.
+
+1. **Spawn a developer subagent** (Agent tool, `subagent_type: "developer"`) with the same sender object and context payload as step 5 would use, but with an explicit instruction added to the dispatch prompt: **do not create a worktree** — implement directly against the current checkout (the session's existing working tree), not an isolated `.claude/worktrees/<slug>` copy. This is the one concrete difference from the step-5 `task` path: everything else about how the subagent implements the task (reading the task file, following acceptance criteria, following repo conventions) is unchanged.
+
+2. **After the developer subagent reports implementation complete**, run the smoke test harness using the same invocation convention as `### 4.2. Inline Execution Path`:
+   - Run `bash scripts/smoke-harness.sh <changed_file>...`, passing the paths the subagent changed. With no arguments the harness infers them from `git diff --name-only HEAD`. It exits `0` on pass and `1` on failure.
+   - If `scripts/smoke-harness.sh` does not exist, log a warning and treat the result as a pass:
+     ```
+     WARNING [<task_id>]: scripts/smoke-harness.sh not found. Smoke test skipped (stub pass).
+     ```
+
+3. **If the smoke test passes**:
+   - The developer subagent self-verifies the implementation against the task's acceptance criteria. No tester subagent is invoked for a `light`-scoped task — this is a deliberate, documented exception to "the tester is the sole status-writer" (`agents/tester.md`), mirroring the same exception already established for `inline` scope in step 5 of `### 4.2`. Since no tester runs, the developer/orchestrator is the one who writes the terminal status for a `light`-scoped task.
+   - Commit the changes using the standard commit convention (`task(<task_id>): <short description>`) via `/commit`.
+   - Run the **Intent-vs-Diff Check** (see `### 5.1. Intent-vs-Diff Check` below) for this task.
+   - Write `status: Passed` and `date_completed: <today>` to the task's frontmatter if self-verification passes.
+   - Remove the task from `project/todo.md`.
+   - Continue to `### 6. Verify documentation`, then `### 7. After successful completion`.
+
+4. **If the smoke test fails (non-zero exit)**: do NOT write `status: Failed` and do NOT halt. Instead, invoke `#### Fallback to Full Task-Scope Pipeline` below (origin: `light`).
+
+#### Fallback to Full Task-Scope Pipeline
+
+This is a self-contained, reusable procedure with two current callers — `### 4.2`'s `--trivial`-forced inline failure branches (origin: `trivial`) and `### 4.3`'s `light`-scope smoke-harness failure (origin: `light`) — given a task that was attempted under a reduced-overhead execution scope and failed its smoke-harness check (or, for `trivial`, showed detected scope creep mid-run), do the following. The only thing that varies by caller is the notice text in step 5; steps 1–4 and 6 are identical regardless of origin.
+
+1. **Do not mark the task `Failed`.** A smoke-harness failure (or detected scope creep) under a reduced-overhead scope means the scope was too small for the task, not that the task itself is unworkable — the correct response is to retry under full isolation, not to reject the work.
+2. **Create a worktree** for the task, named `<E##_S##_T##-short-slug>` per standard Worktree Management conventions, if one does not already exist for this task. (A task dispatched under `light` scope, or forced `inline` via `--trivial`, never had one — both premises skip worktree creation — so this step always creates a fresh worktree in that case.)
+3. **Spawn a developer subagent** in that worktree and have it pick up from the current state of the code (the changes already made by the reduced-overhead attempt are still present in the working tree / already committed, if any commit occurred — the subagent continues from there rather than starting over).
+4. **Invoke the tester agent** per the normal `### 5. Invoke the developer agent` flow's contract — full sender object, commit SHAs, worktree path. The tester is responsible for the terminal status write, exactly as in the standard `task`-scope pipeline.
+5. **Emit a clear, non-fatal fallback notice** to the user/orchestrator, using the message matching the caller's origin:
+   - origin `light`:
+     ```
+     LIGHT SCOPE FALLBACK [<task_id>]: smoke test failed; re-routing to full task-scope pipeline (worktree + developer + tester).
+     ```
+   - origin `trivial`:
+     ```
+     TRIVIAL OVERRIDE FALLBACK [<task_id>]: smoke test failed (or scope creep detected); re-routing to full task-scope pipeline (worktree + developer + tester).
+     ```
+6. Resume normal `task`-scope processing (steps 6–8 below) once the tester returns a verdict.
 
 ### 5. Invoke the developer agent
 Pass the following to the developer agent: