@jenga-ai/agent 1.3.0 → 2.0.0

package/skills/j-init/scripts/init.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ASSETS_DIR="$SCRIPT_DIR/../assets"
+VISIBILITY_SCRIPT="$SCRIPT_DIR/apply-project-visibility.sh"
+
+# ─── Resolve the package root that owns templates/ and lib/ ──────────────────
+# postinstall.js mirrors only skills/ and agents/ into .claude/ and .agents/ —
+# templates/ and lib/ are never copied there, so a script running from a
+# mirrored copy (.claude/skills/init/scripts/ or .agents/skills/init/scripts/)
+# cannot reach its siblings via a fixed ../../../ climb the way it can in this
+# monorepo checkout, where init.sh actually lives at skills/init/scripts/ with
+# templates/ and lib/ three levels up. Consumers instead have them inside the
+# installed npm package.
+if [[ -d "$SCRIPT_DIR/../../../templates" ]]; then
+  PKG_ROOT="$SCRIPT_DIR/../../.."
+elif [[ -d "$PWD/node_modules/@jenga-ai/agent/templates" ]]; then
+  PKG_ROOT="$PWD/node_modules/@jenga-ai/agent"
+else
+  echo "Error: could not locate the jenga-agent package root (templates/ not found via monorepo checkout or node_modules/@jenga-ai/agent)." >&2
+  exit 1
+fi
+
+# ─── 0. Resolve project_files_visibility ─────────────────────────────────────
+# Defaults to `visible` — the only value that touches nothing on disk — so an
+# unattended run can never silently relocate directories or edit .gitignore.
+VISIBILITY="${JENGA_PROJECT_FILES_VISIBILITY:-visible}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --visibility)   VISIBILITY="${2:-}"; shift 2 ;;
+    --visibility=*) VISIBILITY="${1#*=}"; shift ;;
+    *) echo "Unknown argument: $1" >&2
+       echo "Usage: $(basename "$0") [--visibility <visible|ignored>]" >&2
+       exit 1 ;;
+  esac
+done
+
+# Validate before scaffolding so a typo cannot leave a half-initialised project.
+bash "$VISIBILITY_SCRIPT" --check-only "$VISIBILITY"
+
+# ─── 1. Initialize git repository ────────────────────────────────────────────
+echo "→ Initializing git repository..."
+git init
+
+# ─── 2. Create .gitignore ─────────────────────────────────────────────────────
+echo "→ Copying .gitignore from template..."
+cp "$ASSETS_DIR/.gitignore_template" .gitignore
+
+# ─── 3. Scaffold directory structure ──────────────────────────────────────────
+echo "→ Scaffolding directory structure..."
+while IFS= read -r dir || [[ -n "$dir" ]]; do
+  [[ -z "$dir" || "$dir" == \#* ]] && continue
+  mkdir -p "$dir"
+done < "$ASSETS_DIR/directory_structure.txt"
+
+# ─── 4. Create project/PROJECT_SUMMARY.md ────────────────────────────────────
+echo "→ Copying PROJECT_SUMMARY.md from template..."
+cp "$ASSETS_DIR/PROJECT_SUMMARY_template.md" project/PROJECT_SUMMARY.md
+
+# ─── 5. Create project/configs/workflow.json ─────────────────────────────────
+echo "→ Copying workflow.json from template..."
+cp "$ASSETS_DIR/workflow_template.json" project/configs/workflow.json
+
+# ─── 6. Create project/configs/test-config.json stub ─────────────────────────
+echo "→ Copying test-config.json from template..."
+cp "$ASSETS_DIR/test-config_template.json" project/configs/test-config.json
+
+# ─── 6.5. Create project/configs/scope-thresholds.json ───────────────────────
+# Consumed by skills/jenga (Phase 0) and skills/do (Step 0); both halt if it's
+# missing, so it must exist immediately after scaffold.
+echo "→ Copying scope-thresholds.json from template..."
+cp "$ASSETS_DIR/scope-thresholds_template.json" project/configs/scope-thresholds.json
+
+# ─── 7. Create project/data/baselines.json ───────────────────────────────────
+echo "→ Creating baselines.json..."
+echo '{}' > project/data/baselines.json
+
+# ─── 8. Create project/logs/events.json ──────────────────────────────────────
+echo "→ Creating events.json..."
+echo '[]' > project/logs/events.json
+
+# ─── 9. Create docs/STRATEGY.md ──────────────────────────────────────────────
+echo "→ Creating docs/STRATEGY.md (strategic brief for investors, partners, and the product team)..."
+mkdir -p docs
+cp "$ASSETS_DIR/strategy_stub_template.md" docs/STRATEGY.md
+
+# ─── 10. Create CHANGELOG.md ──────────────────────────────────────────────────
+echo "→ Creating CHANGELOG.md from template..."
+cp "$PKG_ROOT/templates/CHANGELOG_TEMPLATE.md" CHANGELOG.md
+
+# ─── 11. Apply project_files_visibility ──────────────────────────────────────
+# Runs before the commit so the .gitignore entry (ignored) is captured in the
+# initial commit.
+echo "→ Applying project files visibility ($VISIBILITY)..."
+bash "$VISIBILITY_SCRIPT" "$VISIBILITY" "$PWD"
+
+# ─── 12. Generate CLAUDE.md / AGENTS.md ──────────────────────────────────────
+# Unconditional — never gated on agentTarget (E41_S04). Applies the J-
+# collision rule and idempotent managed-block updates; see
+# lib/generate-agent-context.js (shared with the published `jenga init` CLI).
+echo "→ Generating CLAUDE.md / AGENTS.md..."
+if command -v node >/dev/null 2>&1; then
+  node "$PKG_ROOT/lib/generate-agent-context.js" "$PWD"
+else
+  echo "  Warning: node not found — skipped CLAUDE.md/AGENTS.md generation." >&2
+fi
+
+# ─── 13. Initial commit ──────────────────────────────────────────────────────
+echo "→ Staging and committing scaffolded files..."
+git add -A
+git commit -m "init: scaffold project structure and workflow config"
+
+echo ""
+echo "✓ Project scaffold complete."

package/skills/jbp/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: jbp
+name: j:jbp
 description: Scaffold the project using the JengaBasePlate boilerplate repo template from https://github.com/samwelmunga/JengaBasePlate.git
 keywords:
   - jbp

package/skills/jenga/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: jenga
+name: j:jenga
 description: Interactive-by-default board orchestrator with a fully automated escape hatch. Bare `/jenga` renders a picker and confirmation tree before scoping the run; `/jenga <ids>` resolves an explicit fuzzy-ID scope and confirms it; `/jenga *` reproduces the original zero-prompt behavior — decomposing any unbroken Epics into Stories, any unbroken Stories into Tasks, queuing all unqueued Tasks into todo.md, then executing every eligible item with no user prompts — until the board is fully started.
 keywords:
   - jenga

package/skills/jenga/scripts/render-confirmation.sh

@@ -97,12 +97,18 @@
 # ENTIRE turn is rejected as an error turn (state left untouched) — there
 # is no partial application of the valid numbers in a mixed-validity reply.
 #
-# Toggling is NOT cascading: unchecking a parent epic/story does not
-# automatically uncheck its children, and vice versa. Each displayed
-# number is an independent checkbox. This is a deliberate simplicity
-# choice — the task only requires "uncheck or re-check individual
-# presented items", not cascading selection logic (that expansion/cascade
-# concern already belongs to cascade-resolve.sh, per its own header).
+# Toggling CASCADES downward (E45_S02_T03): checking or unchecking a
+# story applies the same resulting state to all of its tasks; checking or
+# unchecking an epic applies the same resulting state to all of its
+# stories and their tasks. This is a deliberate, explicit reversal of the
+# original non-cascading design (see this story's 2026-08-27 close-out) —
+# the user hit a real case where unchecking a parent epic left its child
+# story/tasks checked, requiring a manual follow-up uncheck command.
+# Cascade is STRICTLY DOWNWARD (parent -> descendants) only: checking a
+# leaf task does NOT imply its ancestors should also be checked, so a
+# checked child under an unchecked parent is a valid (if visually
+# inconsistent) state. Toggling a leaf task (no children) behaves exactly
+# as it always has — no descendants to cascade into.
 #
 # ---------------------------------------------------------------------------
 # OUTPUT CONTRACT (deliberately NOT uniform JSON — see rationale below)
@@ -165,8 +171,15 @@
 # STATE FILE
 # ---------------------------------------------------------------------------
 # Created under `mktemp -t jenga-confirm-XXXXXX.json`. Stores:
-#   - `numbering`: displayed number -> {item, level, checked} — the ONLY
-#     field that mutates across turns is `checked`.
+#   - `numbering`: displayed number -> {item, level, checked, children} —
+#     `children` is a fixed list of the item's direct descendant numbers
+#     (a story's task numbers; an epic's story numbers), computed once at
+#     build time so continue-mode can cascade a toggle without
+#     re-deriving parent/child relationships from `item_id`/`epic_id`/
+#     `story_id` at toggle time. `children` is always `[]` for a leaf
+#     task. The only fields that mutate across turns are `checked` values
+#     (potentially many at once, via cascade — see TOGGLE COMMAND GRAMMAR
+#     above).
 #   - `layout`: the fixed print order (item lines + header markers),
 #     computed once at start. Continue mode never recomputes tree shape —
 #     it only re-renders from `layout` + the live `checked` flags in
@@ -305,15 +318,17 @@ def pluralize_task(n):
     return f"{n} task{'' if n == 1 else 's'}"
 
 
-def add_item(item, level, indent):
+def add_item(item, level, indent, parent_number=None):
     global counter
     n = str(counter)
     counter += 1
     suffix = ""
     if item.get("id") in undecomposed_ids:
         suffix = "  [needs decomposition -- no children on the board yet]"
-    numbering[n] = {"item": item, "level": level, "checked": True}
+    numbering[n] = {"item": item, "level": level, "checked": True, "children": []}
     layout.append({"kind": "item", "number": n, "level": level, "indent": indent, "suffix": suffix})
+    if parent_number is not None:
+        numbering[parent_number]["children"].append(n)
     return n
 
 
@@ -328,7 +343,7 @@ def append_suffix(extra):
 
 
 for e in epics:
-    add_item(e, "epic", INDENT["epic"])
+    e_num = add_item(e, "epic", INDENT["epic"])
     child_stories = stories_by_epic.get(e["id"], [])
     story_count = len(child_stories)
     task_count = sum(len(tasks_by_story.get(s["id"], [])) for s in child_stories)
@@ -340,23 +355,23 @@ for e in epics:
     append_suffix(", ".join(parts))
 
     for s in child_stories:
-        add_item(s, "story", INDENT["story"])
+        s_num = add_item(s, "story", INDENT["story"], parent_number=e_num)
         child_tasks = tasks_by_story.get(s["id"], [])
         if child_tasks:
             append_suffix(pluralize_task(len(child_tasks)))
         for t in child_tasks:
-            add_item(t, "task", INDENT["task"])
+            add_item(t, "task", INDENT["task"], parent_number=s_num)
 
 if orphan_stories:
     layout.append({"kind": "header", "text": ""})
     layout.append({"kind": "header", "text": "-- Directly Selected Stories (no epic in this selection) --"})
     for s in orphan_stories:
-        add_item(s, "story", INDENT["story"])
+        s_num = add_item(s, "story", INDENT["story"])
         child_tasks = tasks_by_story.get(s["id"], [])
         if child_tasks:
             append_suffix(pluralize_task(len(child_tasks)))
         for t in child_tasks:
-            add_item(t, "task", INDENT["task"])
+            add_item(t, "task", INDENT["task"], parent_number=s_num)
 
 if orphan_tasks:
     layout.append({"kind": "header", "text": ""})
@@ -644,18 +659,40 @@ if invalid:
     print(f"STATE_FILE: {state_file_path}", file=sys.stderr)
     sys.exit(1)
 
+def apply_cascade(num, value):
+    """Set `num`'s checked state to `value`, then recurse into every
+    number in its `children` list (a story's tasks; an epic's stories,
+    which recurse further into their own tasks). Strictly downward —
+    never touches a parent. A leaf task has an empty `children` list, so
+    this degenerates to exactly the old single-flag assignment for the
+    non-cascading base case."""
+    numbering[num]["checked"] = value
+    for child in numbering[num].get("children", []):
+        apply_cascade(child, value)
+
+
 # All-or-nothing application, de-duplicated (first-seen wins on dupes).
+# Resulting values are computed from PRE-mutation state in a first pass,
+# then applied (with cascade) in a second pass -- this avoids a
+# parent-then-child (or child-then-parent) double-toggle artifact when a
+# single reply lists both a parent and one of its own descendants, e.g.
+# bare-number toggle "5,6" where 6 is a child of 5.
 seen = set()
+pending = []
 for tok in valid_tokens:
     if tok in seen:
         continue
     seen.add(tok)
     if action == "check":
-        numbering[tok]["checked"] = True
+        value = True
     elif action == "uncheck":
-        numbering[tok]["checked"] = False
+        value = False
     else:
-        numbering[tok]["checked"] = not numbering[tok]["checked"]
+        value = not numbering[tok]["checked"]
+    pending.append((tok, value))
+
+for tok, value in pending:
+    apply_cascade(tok, value)
 
 state["numbering"] = numbering
 with open(state_file_path, "w", encoding="utf-8") as f:

package/skills/jenga-permission-level/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: jenga-permission-level
+name: j:jenga-permission-level
 description: Report or switch the current session's 5-tier permission level (Locked/Guarded/Standard/Elevated/Unrestricted) without hand-editing settings.json.
 keywords:
   - "permission level"

package/skills/lgtm/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: lgtm
+name: j:lgtm
 description: Approve and commit the current work, then continue to the next task. Shortcut that chains /commit followed by /continue.
 keywords:
   - lgtm

package/skills/pi-plan/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pi-plan
+name: j:pi-plan
 description: Define or expand project Epics in PROJECT_SUMMARY.md. Use this at the start of a project to establish its foundation, AND whenever the user wants to add major new features, plan a significant new area of work, or make epic-level changes to an existing project. Trigger whenever you hear things like "new feature area", "big change", "new epic", "expand the project", "add a major capability", or "plan a new phase" — even mid-project.
 keywords:
   - epic

package/skills/proceed/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: proceed
+name: j:proceed
 description: Review project progress by checking epics and stories, optionally consulting PROJECT_SUMMARY.md and WARP.md, then continue executing the project plan.
 keywords:
   - proceed

package/skills/publish/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: publish
+name: j:publish
 description: Configure, validate, and orchestrate scaffolded release workflows through a single `/publish` entry point with bounded sub-commands.
 keywords:
   - publish

package/skills/publish/adapters/npm-ci.md

@@ -99,11 +99,33 @@ Run the adapter phases in this exact order:
    ```yaml
    permissions:
      id-token: write
-     contents: read
+     contents: write
    ```
-   and runs `npm publish --provenance` to attach a build provenance attestation
-   to the published package. In `--dry-run` mode, print the rendered YAML to
-   stdout and exit 0 without writing any file.
+   (`contents: write` — bumped from `read` — is required so the `publish` and
+   `stage` jobs can push the tags described below; this is the CI's own token
+   gaining write access to tag *its own* repository, nothing else, and no new
+   secret or credential is introduced) and runs `npm publish --provenance` to
+   attach a build provenance attestation to the published package. In
+   `--dry-run` mode, print the rendered YAML to stdout and exit 0 without
+   writing any file.
+
+   Each job also gains a final step, gated on `if: success()` so a failed
+   publish/stage never creates or moves a tag:
+   - **`publish` job — "Tag prod release and remove stage tag":** reads the
+     version from `package.json`, tags the checked-out commit `v<version>`
+     (no force — this tag is immutable; a genuine collision fails loudly
+     rather than silently moving a prod tag), pushes it, then best-effort
+     deletes the corresponding `v<version>-stage` tag both locally and on the
+     remote (tolerating its absence, e.g. a prod publish that skipped
+     staging).
+   - **`stage` job — "Tag stage release":** reads the version the same way
+     and tags the checked-out commit `v<version>-stage` — a **mutable**
+     pointer, force-created (`git tag -f`) and force-pushed, so re-staging the
+     same version moves the tag rather than failing.
+
+   Both new steps configure a `github-actions[bot]` git identity
+   (`user.name`/`user.email`) before tagging, since no prior step in the
+   workflow sets one.
 
 3. **`commit-workflow`** — write the generated YAML to `<workflow_path>`
    (creating the `.github/workflows/` directory if needed) and commit it with:

package/skills/publish/scripts/npm_ci_pipeline.sh

@@ -172,7 +172,7 @@ on:
 
 permissions:
   id-token: write
-  contents: read
+  contents: write
 
 jobs:
   publish:
@@ -194,6 +194,17 @@ jobs:
       - name: Publish to npm
         run: npm publish --provenance --access ${NPM_ACCESS} --tag ${DIST_TAG}
 
+      - name: Tag prod release and remove stage tag
+        if: success()
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          VERSION="\$(node -p "require('./package.json').version")"
+          git tag "v\${VERSION}"
+          git push origin "v\${VERSION}"
+          git tag -d "v\${VERSION}-stage" 2>/dev/null || true
+          git push origin ":refs/tags/v\${VERSION}-stage" 2>/dev/null || true
+
   stage:
     if: \${{ github.event.inputs.mode == 'stage' }}
     runs-on: ubuntu-latest
@@ -212,6 +223,15 @@ jobs:
 
       - name: Stage to npm
         run: npm stage publish --provenance --access ${NPM_ACCESS} --tag ${DIST_TAG}
+
+      - name: Tag stage release
+        if: success()
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          VERSION="\$(node -p "require('./package.json').version")"
+          git tag -f "v\${VERSION}-stage"
+          git push origin "v\${VERSION}-stage" --force
 EOF
 )"
 

package/skills/reconcile/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: reconcile
+name: j:reconcile
 description: Reconcile the scrum board with actual implementation state. Cross-checks every task's board status against git history and worktrees, merges orphaned worktree branches, demotes unimplemented "Done" items, promotes secretly-implemented items, flags code with no board provenance and offers /uncharted segment for it, and cleans stale entries from todo.md. Use when the board feels out of sync, after a big merge session, when tasks were completed outside the normal workflow, or when todo.md has grown stale. Trigger on phrases like "sync the board", "clean up the board", "reconcile", "board is out of date", "todo is stale", or "check what's really done".
 metadata:
   prefered_agent: scrum-master

package/skills/reconcile-origin/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: reconcile-origin
+name: j:reconcile-origin
 description: Sync the current (or specified) branch with origin by rebasing local commits on top of the latest upstream state.
 keywords:
   - "sync branch"

package/skills/redo/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: redo
+name: j:redo
 description: Redo parts or entire previous implementations identified by a commit SHA or an Epic/Story number (e.g. E01, E02_S03). Expects an identifier and a description of what to redo and why. Use when the user wants to revisit, rework, or rewrite previously completed work, including updating all affected documentation.
 keywords:
   - redo

package/skills/skillify/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: skillify
+name: j:skillify
 description: Refactor one or more existing skills into a cleaner, more maintainable structure — extracting hardcoded content into asset files, offloading deterministic steps into scripts, and reorganizing the skill body to reflect the leaner result. Use this whenever the user wants to clean up, improve, or restructure an existing skill, mentions that a skill has hardcoded content that could be templated, or asks to "skillify", "refactor", or "tidy up" a skill. Trigger even if the user just pastes a skill and says something like "can we make this better?".
 ---
 

package/skills/spinoff/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: spinoff
+name: j:spinoff
 description: Capture a diverging topic mid-conversation. Collects context and a mandatory origin, optionally runs /brainstorm for prerequisites, saves an /idea entry, and returns focus to the primary thread.
 keywords:
   - spinoff

package/skills/status/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: status
+name: j:status
 description: Print a human-readable summary of the entire scrum board — all epics, stories, and tasks with their statuses — plus any open rapports and unprocessed queue triggers. Use when you want a quick overview of project state without reading raw files.
 keywords:
   - status

package/skills/todo/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: todo
+name: j:todo
 description: Add missions to the project todo list (project/todo.md), optionally linking them to epics and stories. Loops until the user is done, then optionally executes the list.
 keywords:
   - todo
@@ -16,6 +16,16 @@ metadata:
 
 # Todo — Add Missions to the Todo List
 
+## `--trivial` Flag
+
+**Syntax:** `/todo --trivial <description>` — optionally combined with the same `: <Epic no.>_<Story no.>` linkage syntax normal `/todo` entries use, e.g. `/todo --trivial Fix typo in error message: E12_S03`.
+
+When `--trivial` is present, the mission is written as a **fully-formed task board file immediately** (not just a raw `todo.md` line deferred to `/do`'s own breakdown pass) with `execution_scope: inline` forced unconditionally — no threshold computation is consulted for the scope value itself. See step 4.5 below for the mechanics.
+
+**Human-only override.** `--trivial` is invoked by a human typing `/todo --trivial ...` — it is never applied by the scrum-master to itself during autonomous story/epic breakdown elsewhere (e.g. `/jenga`'s Phase 0.5, or `/do`'s own scrum-master decomposition step in `skills/do/SKILL.md` step 3). Those paths keep using the normal heuristic-only `execution_scope` assignment documented in `agents/scrum-master.md`'s Execution Scope Assignment section, unmodified by this flag.
+
+**Fallback on failure is out of scope here.** If a `--trivial`-forced inline run fails the smoke-harness or shows scope creep at dispatch time, `/do`'s own `--trivial` handling (a separate task, E32_S14_T02) is responsible for falling back to the full `task` pipeline — this skill only ever writes the initial forced-inline task.
+
 ## Instructions
 
 1. **Ensure `project/todo.md` exists** — If it doesn't exist, it will be auto-created by `todo_manager.sh` — no manual action needed.
@@ -24,6 +34,7 @@ metadata:
    - Where do you want to do this?
    - What would you like to do?
    - What is the goal?
+   - (If `--trivial` was passed, these answers still apply — `--trivial` changes how the mission is written to the board in step 4.5, not what's asked here.)
 
 3. **Classify the mission** — Check if it fits into:
    - An existing story
@@ -31,18 +42,44 @@ metadata:
    - A new story inside a new Epic
    - None of the above
 
+   **`--trivial` requires an existing (or, in this same step, newly-created) story to attach to.** It forces the scope of a single task, not a container — if the mission has no story yet, create it now via step 4 below exactly as normal, then continue to step 4.5. `--trivial` cannot be used for "None of the above."
+
 4. **Update project documentation** — Add the mission to the appropriate files under `project/board/epics/` and `project/board/stories/` if applicable.
    - If the mission involves implementing or modifying a skill, apply the **Skill Implementation Principle — Scripts Over Inline Logic** (see `CLAUDE.md` / `AGENTS.md`): note in the story/task's acceptance criteria that deterministic, repeatable steps must be offloaded to scripts under `skills/<name>/scripts/` (or `scripts/`) rather than encoded as inline agent instructions in `SKILL.md`.
    - If the user indicates the mission is high-risk, or explicitly asks to flag it, set an elevated caution tier directly on the story or task frontmatter: `crucial_level` (one of `advisory`, `gated`, `locked` — see `templates/SCRUM_BOARD_SCHEMA.md` for valid values and their meaning), `crucial_set_by: user`, and `crucial_note` capturing the user's stated reason. This user-initiated flag is written immediately — it does not require the confirm-before-write gate, which applies only to scrum-master-*proposed* caution tiers (a separate, heuristic-driven path).
 
-5. **Add to `project/todo.md`** by running:
+4.5. **If `--trivial` was passed, create the task now** (skip step 5 — this step writes the todo.md entry itself):
+
+   a. **Estimate the change**, using the same judgment `agents/scrum-master.md`'s Execution Scope Assignment heuristic applies: how many files will this mission likely touch, and roughly how many lines. This is a reasoning step, not a script step — do not guess wildly, but a rough, honest estimate is sufficient.
+
+   b. **Determine `computed_tier`** — what `execution_scope` the normal heuristic would have assigned to this estimate, purely for the audit trail (it is never written as the actual `execution_scope`, which is always forced to `inline`):
+      - Read `inline_max_files`, `inline_max_lines`, and `story_max_files` from `project/configs/scope-thresholds.json` at run time — never hardcode these numbers here.
+      - Apply `agents/scrum-master.md`'s `inline` / `story` / `task` heuristics (file count vs. `inline_max_files`, line estimate vs. `inline_max_lines`, contention and cross-cutting checks for `story`) to the estimate from (a). The result is `computed_tier` — one of `inline`, `task`, or `story` (never `epic` — the heuristic never autonomously computes `epic`).
+
+   c. **Run the helper script**, which handles everything mechanical — next task-ID assignment, writing the task board file with `execution_scope: inline` forced, registering the new task ID into the parent story's `tasks:` frontmatter list, and adding the `project/todo.md` entry using the full task ID (so `/do` routes straight into its Inline Execution Path with no redundant breakdown pass):
+      ```
+      bash skills/todo/scripts/add_trivial_task.sh \
+        --story <E##_S##> \
+        --title "<mission title>" \
+        --description "<mission description>" \
+        --criteria "<criterion 1>|<criterion 2>|..." \
+        --computed-tier <inline|task|story> \
+        --est-files <N> \
+        --est-lines <M> \
+        [--prerequisites "<text>"]
+      ```
+      The script writes `scope_rationale` in the form `"forced inline via --trivial; computed scope would have been '<computed_tier>' — estimated <N> files, ~<M> lines"` and sets `jenga_assigned: false` with a matching `override_justification`, so `/do` step 4.1's existing override-validation logs the override on dispatch — no separate acknowledgement step needed here.
+      On success the script prints the new task ID to stdout; on failure (e.g. the story doesn't exist yet, or `--computed-tier` is invalid) it exits non-zero with an explanatory message on stderr — surface that to the user rather than retrying blindly.
+   d. Continue to step 6 (skip step 5 — the script already added the `todo.md` entry).
+
+5. **Add to `project/todo.md`** by running (skip this step if step 4.5 already ran):
    ```
    bash scripts/todo_manager.sh add '<mission title>: <Epic no.>_<Story no.>'
    ```
    The epic and story reference is only required if the mission is assigned to one.
 
 6. **Ask the user**: "Add another todo" or "Done"?
-   - If **add another** — go back to step 2.
+   - If **add another** — go back to step 2. (`--trivial` applies only to the mission it was passed with — it does not carry over to the next mission unless the user says `--trivial` again.)
    - If **done** — ask if they want to execute the todo list.
      - If **yes** — invoke the `/do` skill.
      - If **no** — exit.