@jenga-ai/agent 1.0.1 → 1.1.1

package/skills/do/SKILL.md

@@ -18,9 +18,256 @@ metadata:
 
 ## Instructions
 
+### 0. Load threshold config
+
+Read `project/configs/scope-thresholds.json`.
+
+If the file does not exist, emit:
+```
+ERROR: project/configs/scope-thresholds.json not found. Cannot proceed.
+```
+and halt. Do not fall back to any default values.
+
+If the file is not valid JSON, emit:
+```
+ERROR: project/configs/scope-thresholds.json is malformed (invalid JSON). Cannot proceed.
+```
+and halt.
+
+Extract the following named values for use throughout this skill:
+- `inline_max_files` — maximum files a task may touch to qualify for inline execution scope
+- `inline_max_lines` — maximum total lines changed for inline scope
+- `story_max_files` — maximum files a task may touch to qualify for story-scope bundling
+- `bundle_lock_ttl_minutes` — time-to-live in minutes for a story-scope bundle lock
+
+These values must be read fresh on each invocation. Never use hardcoded fallbacks.
+
 ### 1. Check for `project/todo.md`
 Run `bash scripts/todo_manager.sh exists`. If it exits non-zero, inform the user there are no queued tasks and exit.
 
+### 1.5. Story-Bundle Execution Mode
+
+When `/do` is invoked with a story ID (e.g., `/do E##_S##`), skip steps 2–4 and enter story-bundle execution mode:
+
+1. **Read the story file** from `project/board/stories/<E##_S##>_*.md`. Extract the `tasks:` list. If the story file does not exist, emit:
+   ```
+   ERROR: Story file for <story_id> not found. Cannot execute bundle.
+   ```
+   and halt.
+
+#### Epic-Level Bundle Lock
+
+Before proceeding, acquire the epic-level sequential lock for this bundle:
+
+a. **Derive the lock file path**: `project/queue/epic-lock-<E##>.json` where `<E##>` is the epic ID extracted from the story ID.
+
+b. **Check for an existing lock**:
+   - If `project/queue/epic-lock-<E##>.json` exists:
+     1. Parse the JSON and read the `started_at` field (ISO 8601 UTC timestamp).
+     2. Compute the lock age: `age_minutes = (now_utc - started_at) / 60`.
+     3. Read `bundle_lock_ttl_minutes` from `project/configs/scope-thresholds.json` (already loaded in step 0).
+     4. If `age_minutes < bundle_lock_ttl_minutes` (lock is **non-stale**), emit:
+        ```
+        BLOCKED: Epic <E##> already has a running bundle (<bundle_story_id>, started <started_at>). Wait for it to complete or for the TTL to expire.
+        ```
+        and **halt** — do not proceed with this bundle.
+     5. If `age_minutes >= bundle_lock_ttl_minutes` (lock is **stale**), delete it with `rm -f project/queue/epic-lock-<E##>.json` and continue to the write step below.
+   - If `project/queue/epic-lock-<E##>.json` does not exist, continue to the write step below.
+
+c. **Write the lock atomically**:
+   1. Compose the lock JSON:
+      ```json
+      {
+        "epic_id": "<E##>",
+        "bundle_story_id": "<E##_S##>",
+        "started_at": "<current ISO 8601 UTC timestamp>"
+      }
+      ```
+   2. Write this JSON to `project/queue/epic-lock-<E##>.json.tmp` (temporary file in the same directory).
+   3. Rename (move) `project/queue/epic-lock-<E##>.json.tmp` to `project/queue/epic-lock-<E##>.json`. This rename is atomic on POSIX filesystems and prevents any observer from reading a partially-written lock file.
+
+> **Note:** Each epic has its own lock file keyed by `<E##>`. Bundles belonging to different epics have separate lock files and do not block each other.
+
+> **Cleanup contract:** The epic lock file **must** be deleted on every exit path — success, failure, and interruption. Register a cleanup/trap handler immediately after writing the lock so that the lock is released even if the skill is interrupted mid-execution (e.g., `trap 'rm -f project/queue/epic-lock-<E##>.json' EXIT` in a shell implementation, or equivalent in other runtimes). Deleting a non-existent lock file must be idempotent — always use `rm -f` (never `rm` alone).
+
+#### Pre-execution cross-bundle conflict check
+
+After acquiring the epic lock and before writing the bundle manifest, scan all other active bundle manifests to detect file-level overlap with the current bundle:
+
+1. **Glob other bundle manifests**: list all files matching `project/queue/bundle-*.json`. Exclude the current bundle's own file (`project/queue/bundle-<E##_S##>.json` — it does not exist yet at this point, so no special filter is needed; simply exclude any path whose basename equals `bundle-<E##_S##>.json`).
+
+2. **If no other manifests exist**: skip steps 3–6 entirely — this step completes silently.
+
+3. **For each other manifest file found**:
+   a. Parse the JSON and read its `task_changed_files` map.
+   b. Collect the union of all file-path arrays across every key in `task_changed_files` into a flat, deduplicated set called `other_touched_files`.
+   c. Record the other bundle's `story_id` (or derive it from the filename: `bundle-<story_id>.json`).
+
+4. **Build the expected file set for the current bundle** (`current_expected_files`):
+   For each task in the current bundle's `tasks:` list:
+   a. Read the task file at `project/board/tasks/<task_id>_*.md`.
+   b. Extract file paths from the task's `scope_rationale` frontmatter field and from the full text of the task's `## Description` section. A string is treated as a file path if it contains a forward-slash (`/`) or a dot-separated extension (e.g. `.md`, `.json`, `.sh`, `.ts`, `.js`, `.py`). Extract all such tokens.
+   c. Add all extracted paths to `current_expected_files` (deduplicated set).
+
+5. **Compute overlap**: for each other bundle scanned in step 3, compute the intersection of `other_touched_files` and `current_expected_files`.
+
+6. **If any overlap is found**:
+   a. Emit the following log line to the console (one line per conflicting bundle):
+      ```
+      [CROSS-BUNDLE CONFLICT] Bundle <current_story_id> and bundle <other_story_id> share expected files: <file1>, <file2>
+      ```
+   b. Store the conflict data in memory as `pending_conflicts`:
+      ```json
+      {
+        "<other_story_id>": ["<file1>", "<file2>"]
+      }
+      ```
+      If multiple other bundles each have overlap, accumulate all of them under their respective story IDs in `pending_conflicts`.
+
+7. **Pass `pending_conflicts` forward**: when writing the bundle manifest in the next step (step 2 below), initialise the `cross_bundle_conflicts` key in the manifest with the contents of `pending_conflicts` (or `{}` if no conflicts were found). See "### Bundle Manifest and Rollback Anchor" for the updated manifest structure.
+
+> **This check is non-blocking.** Regardless of whether conflicts are found, execution always continues to step 2. The conflict data is recorded for later review only.
+
+2. **Invoke rollback anchor**: write a bundle manifest at `project/queue/bundle-<E##_S##>.json` before the first task executes. See "### Bundle Manifest and Rollback Anchor" below for the full procedure.
+
+3. **Spawn one developer subagent** in one shared worktree named `bundle-<E##_S##>`. This is the only developer subagent for the entire story bundle — do not spawn additional subagents per task.
+
+4. **Execute tasks sequentially** in `tasks:` list order, within the same shared developer subagent context:
+
+   For each task in the `tasks:` list:
+
+   a. **Before the task begins** — write `status: In Progress` and `date_started: <today>` to the task's frontmatter using the file-locking protocol:
+      1. Locate the task file: `project/board/tasks/<task_id>_*.md`.
+      2. Check for an existing lock file at `project/board/tasks/<task_id>_*.md.lock`. If it exists and is less than 60 seconds old, wait 10 seconds and retry once. If still locked after the retry, log a warning and skip this status write (do not block task execution).
+      3. Create the lock file: write the current ISO 8601 timestamp into `project/board/tasks/<task_id>_*.md.lock`.
+      4. Update the task frontmatter fields `status: In Progress` and `date_started: <YYYY-MM-DD>` (today's date).
+      5. Delete the lock file immediately after the write completes (before step b).
+
+   b. **Pass task context** to the shared developer subagent: task file content (title, description, acceptance criteria), parent story file, and parent epic file.
+
+   c. **After successful task**: first run the **Intent-vs-Diff Check** (see `### 5.1. Intent-vs-Diff Check` below) for this task. Then write `status: Passed` and `date_completed: <today>` to the task's frontmatter using the file-locking protocol:
+      1. Check for an existing lock file at `project/board/tasks/<task_id>_*.md.lock`. If it exists and is less than 60 seconds old, wait 10 seconds and retry once. If still locked, log a warning and skip this status write.
+      2. Create the lock file: write the current ISO 8601 timestamp into `project/board/tasks/<task_id>_*.md.lock`.
+      3. Update the task frontmatter fields `status: Passed` and `date_completed: <YYYY-MM-DD>` (today's date).
+      4. Delete the lock file immediately after the write completes.
+      > The lock must be released before proceeding to task N+1. Never hold a lock across task execution.
+
+   c.1. **Post-task file extraction** — immediately after the status write in step c and before proceeding to the next task, record the files changed by this task into the bundle manifest:
+      1. Run `git diff --name-only HEAD~1` to obtain the list of files changed by the just-completed task. Capture each line as a relative file path. If the command returns empty output (the task made no commits), treat the result as an empty array `[]` — this is not an error.
+      2. Read the bundle manifest at `project/queue/bundle-<E##_S##>.json`.
+      3. Add or update the key `task_changed_files` in the manifest object. Set `task_changed_files[<task_id>]` to the captured file list (an array of strings, or `[]` if no files changed). If `task_changed_files` does not yet exist in the manifest, create it as an empty object first.
+      4. Write the updated manifest atomically:
+         a. Serialise the updated manifest to JSON.
+         b. Write the JSON to `project/queue/bundle-<E##_S##>.json.tmp`.
+         c. Rename (move) `project/queue/bundle-<E##_S##>.json.tmp` to `project/queue/bundle-<E##_S##>.json`. The rename is atomic on POSIX filesystems and prevents any consumer from reading a partially-written file.
+      > This step is mandatory before proceeding to task N+1. The extraction must complete (even if the file list is empty) before the next task begins.
+
+   c.2. **Conflict report** — immediately after step c.1, compare the extracted file list against the files the task was expected to touch, and write a conflict report if unexpected files are found:
+
+      1. **Extract expected files** from the task's frontmatter field `scope_rationale` and from the task's `## Description` section. Use a best-effort prose heuristic: split the text on whitespace and punctuation, then retain any token that either (a) contains a `/` character or (b) matches the pattern `*.*` (a dot surrounded by non-dot characters on both sides, e.g. `SKILL.md`, `foo.json`). Collect all retained tokens into a set called `expected_files`. This is intentionally permissive — false positives (expected files that were never actually changed) are acceptable and produce no report.
+
+      2. **Compute unexpected files**: let `actual_files` = the array stored at `task_changed_files[<task_id>]` in the bundle manifest (from step c.1). Compute `unexpected = actual_files − expected_files` (set difference: files in `actual_files` that have no match in `expected_files`). Matching is case-sensitive and exact against the relative path or the basename of the path — a token like `SKILL.md` matches any actual file whose basename is `SKILL.md` (e.g. `skills/do/SKILL.md`).
+
+      3. **If `unexpected` is non-empty**:
+         a. Write a Markdown conflict report to `project/queue/conflict-<task_id>.md` with the following structure:
+            ```markdown
+            # Conflict Report: <task_id>
+
+            **Generated:** <ISO 8601 UTC timestamp>
+            **Bundle:** <E##_S##>
+
+            ## Task ID
+            <task_id>
+
+            ## Expected Files
+            Files inferred from scope_rationale and description:
+            - <file1>
+            - ...
+
+            ## Actual Files Changed
+            Files changed by this task (from git diff):
+            - <file1>
+            - ...
+
+            ## Unexpected Files
+            Files changed that were not anticipated by the task definition:
+            - <file1>
+            - ...
+            ```
+         b. Read the bundle manifest at `project/queue/bundle-<E##_S##>.json`.
+         c. Append `<task_id>` to the `conflict_reports` array in the manifest. If the key `conflict_reports` does not yet exist, create it as an empty array first.
+         d. Write the updated manifest atomically (tmp-file rename pattern — same as step c.1.4).
+
+      4. **If `unexpected` is empty**: skip this step entirely. Do not write a conflict report. Do not modify the bundle manifest.
+
+      > **This step is non-blocking.** A conflict report does NOT affect the task's `Passed` status or halt bundle execution. It is informational only — a human can review `project/queue/conflict-<task_id>.md` after the bundle completes.
+
+   d. **After task failure** — write `status: Failed` to the task's frontmatter using the file-locking protocol:
+      1. Check for an existing lock file at `project/board/tasks/<task_id>_*.md.lock`. If it exists and is less than 60 seconds old, wait 10 seconds and retry once. If still locked, log a warning and skip this status write.
+      2. Create the lock file: write the current ISO 8601 timestamp into `project/board/tasks/<task_id>_*.md.lock`.
+      3. Update the task frontmatter field `status: Failed`.
+      4. Delete the lock file immediately after the write completes.
+      Then invoke the rollback anchor cleanup procedure (see "### Bundle Manifest and Rollback Anchor" — failure path). After the rollback anchor completes, **release the epic lock**: run `rm -f project/queue/epic-lock-<E##>.json`. Mark the bundle as failed and **halt** — do not execute any remaining tasks in the sequence.
+
+5. **Post-bundle verification** (runs only if all tasks completed without failure):
+   - Inspect each task in the bundle for `needs_docs: true` in its frontmatter.
+   - **If any task has `needs_docs: true`**: invoke the tester agent once for the full story. Pass the story ID, the list of all task IDs in the bundle, and the shared worktree path. The tester is responsible for updating individual task statuses.
+   - **If all tasks have `needs_docs: false`**: the developer agent self-verifies — reviews each task's implementation against its acceptance criteria without invoking the tester. After self-verification passes, write `status: Passed` and `date_completed: <YYYY-MM-DD>` (today's date) to each task file using the file-locking protocol (steps c.1–c.4 above). No tester invocation occurs.
+
+6. **Cleanup**: on successful bundle completion, invoke the rollback anchor success path (see "### Bundle Manifest and Rollback Anchor" — success path) to delete the bundle manifest. Then **release the epic lock**: run `rm -f project/queue/epic-lock-<E##>.json`.
+
+### Bundle Manifest and Rollback Anchor
+
+The bundle manifest records the repository state before any task in the bundle executes. It serves as the anchor for rollback on failure and as a reference for conflict reports (E32_S07) and concurrency locks (E32_S08).
+
+#### Before the first task executes
+
+1. Run `git rev-parse HEAD` to capture the current HEAD SHA as `anchor_sha`.
+2. Write `project/queue/bundle-<E##_S##>.json` with the following structure:
+   ```json
+   {
+     "story_id": "<E##_S##>",
+     "anchor_sha": "<SHA from git rev-parse HEAD>",
+     "started_at": "<ISO 8601 UTC timestamp>",
+     "tasks": ["<E##_S##_T##>", "..."],
+     "task_changed_files": {},
+     "conflict_reports": [],
+     "cross_bundle_conflicts": {}
+   }
+   ```
+   - `story_id`: the story ID for this bundle (e.g. `E32_S05`)
+   - `anchor_sha`: the full 40-character SHA returned by `git rev-parse HEAD`
+   - `started_at`: current UTC timestamp in ISO 8601 format (e.g. `2026-08-16T12:00:00Z`)
+   - `tasks`: ordered array of task IDs drawn from the story's `tasks:` frontmatter list
+   - `task_changed_files`: starts as an empty object `{}`; populated after each task completes (see step 4c.1). Each key is a task ID and each value is an array of relative file paths changed by that task.
+   - `conflict_reports`: starts as an empty array `[]`; populated after each task's step 4c.2 conflict check. Each entry is a task ID string for which a conflict report was written to `project/queue/conflict-<task_id>.md`.
+   - `cross_bundle_conflicts`: populated from the pre-execution conflict check (see "Pre-execution cross-bundle conflict check" above). Each key is the `story_id` of a conflicting bundle and each value is an array of overlapping file paths. Initialised with the `pending_conflicts` data collected during the conflict check; if no conflicts were found, initialised as `{}`.
+
+   Do not proceed to the first task until this file is written successfully.
+
+#### On any task failure (failure path)
+
+Execute the following steps in order. Do not skip any step.
+
+1. **Save partial diff**: run `git diff <anchor_sha> HEAD` and write the output to `project/queue/bundle-<E##_S##>-partial.patch`. This captures all commits made since the anchor, providing a record of partial work for diagnosis.
+2. **Verify clean worktree**: run `git status --porcelain`. If the output is non-empty, there are uncommitted changes that would cause `git reset --hard` to error or lose work. In this case, emit:
+   ```
+   ROLLBACK WARNING: worktree has uncommitted changes. Stashing before reset.
+   ```
+   Then run `git stash` before proceeding. This ensures the reset completes without git complaints.
+3. **Reset to anchor**: run `git reset --hard <anchor_sha>`. The repository returns to the exact state it was in before the bundle started.
+4. **Delete bundle manifest**: remove `project/queue/bundle-<E##_S##>.json`.
+
+After completing the failure path, halt bundle execution. Do not execute any remaining tasks in the sequence.
+
+#### On successful bundle completion (success path)
+
+1. **Delete bundle manifest**: remove `project/queue/bundle-<E##_S##>.json`.
+
+No patch file is written on success.
+
+If `/do` is invoked with a task ID (`E##_S##_T##`) or a plain-text title, skip this section and use the normal task execution path (steps 2–8 below).
+
 ### 2. List tasks and let the user choose
 Run `bash scripts/todo_manager.sh list` to display the queued tasks. Ask the user:
 - Execute a specific task (by number or title)
@@ -52,6 +299,76 @@ Before starting:
 2. If the file does not exist, warn the user and skip — do not proceed with a task that has no scrum board definition
 3. Present a brief summary of the task: title, acceptance criteria, parent story, parent epic
 
+### 4.1. Override validation
+
+Before invoking the developer, check whether this task was manually scoped by a human operator.
+
+1. Read `jenga_assigned` from the resolved task's frontmatter.
+2. If `jenga_assigned` is `true` or the field is absent — proceed to step 4.2 without any further check.
+3. If `jenga_assigned` is `false`:
+   a. Read `override_justification` from the task's frontmatter.
+   b. If `override_justification` is absent or its value is an empty string, **halt execution** and emit:
+      ```
+      OVERRIDE VALIDATION ERROR [<task_id>]: jenga_assigned is false but override_justification is missing or empty. Add a justification before proceeding.
+      ```
+      Do not invoke the developer. Do not remove the task from `project/todo.md`. Return control to the user.
+   c. If `override_justification` is present and non-empty, log:
+      ```
+      Override acknowledged for <task_id>: <override_justification>
+      ```
+      Then proceed to step 4.2.
+
+### 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.
+
+**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`:
+
+- This task MUST be routed through the inline execution path below — no worktree, no developer subagent — regardless of what `execution_scope` currently reads. This guards against a locked task reaching dispatch with a non-`inline` `execution_scope` (a race, a manually edited file, or a task added to a story's `tasks:` list after `skills/jenga/SKILL.md` Phase 0.5's Rule 4 last ran).
+- If `execution_scope` is already `inline`, proceed directly to the inline steps below — no correction needed.
+- If `execution_scope` is anything other than `inline` (absent, `task`, `story`, or `epic`), auto-correct it to `inline` in the task frontmatter now, and record the correction using the **same logged-note convention** as `skills/jenga/SKILL.md` Phase 0.5 Rule 4 (do not invent a second, inconsistent logging mechanism):
+  - Append to the task's `override_justification` frontmatter field:
+    ```
+    override_justification: "/do dispatch guard auto-correction <date>: execution_scope forced from '<previous_value>' to 'inline' because crucial_level: locked."
+    ```
+  - Then emit (non-fatally — do not halt):
+    ```
+    AUTO-CORRECTION [<task_id>]: crucial_level=locked requires execution_scope=inline; corrected from "<previous_value>" to "inline".
+    ```
+  - Then proceed to the inline steps below with the now-corrected `execution_scope: inline`.
+- **Under no circumstance does a `crucial_level: locked` task fall through to step 5** (developer agent invocation / worktree creation) — this applies whether the task was resolved individually or would otherwise have entered the normal per-task worktree-creation flow.
+
+**If `execution_scope: inline`** (including tasks corrected above), execute the task directly in the current session without spawning a developer subagent:
+
+1. Read the task file and load its full content (description, acceptance criteria). Do NOT create a worktree. Do NOT spawn a developer subagent.
+2. Implement the task inline — make the required changes to files directly in the current session.
+3. Run the smoke test harness before committing anything:
+   - Run `bash scripts/smoke-harness.sh <changed_file>...`, passing the paths changed in step 2. 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).
+     ```
+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.
+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.
+   - Self-verify the implementation against the acceptance criteria.
+   - Write `status: Passed` and `date_completed: <today>` to the task's frontmatter if verification passes.
+   - Remove the task from `project/todo.md`.
+6. `inline` tasks do not invoke the tester agent — the smoke test and self-verification are the only gates.
+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 `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.
+
 ### 5. Invoke the developer agent
 Pass the following to the developer agent:
 
@@ -68,6 +385,40 @@ The developer agent will:
 - Implement, commit at milestones, and invoke the tester agent
 - Return when the tester has verified the work
 
+### 5.1. Intent-vs-Diff Check (needs_docs: false only)
+
+After the developer agent returns (or after inline execution completes), run the following check if the task has `needs_docs: false` in its frontmatter. If `needs_docs: true`, skip this check entirely — the full documentation lifecycle handles divergence detection for those tasks.
+
+**Steps:**
+
+1. Read `needs_docs` from the task's frontmatter. If `needs_docs: true` (or absent and defaulting to `true`), skip to step 6.
+
+2. Run `git diff --name-only HEAD~1` to retrieve the list of changed file names (relative paths, one per line).
+
+3. Read the prompt template from `skills/do/assets/intent-vs-diff-prompt.md`. Extract the prompt block (the content between the triple backticks under `## Prompt`).
+
+4. Substitute the placeholders:
+   - `{description}` — full text of the task's `## Description` section
+   - `{acceptance_criteria}` — full text of the task's `## Acceptance Criteria` section
+   - `{changed_files}` — newline-separated output from step 2
+
+5. Invoke the LLM with the constructed prompt (using the orchestrating agent's LLM access). Ask for a JSON array response only.
+
+6. Parse the LLM response as a JSON array:
+   - If parsing fails (malformed JSON): treat as `[]`, emit: `[intent-vs-diff] LLM response was not valid JSON; treating as no divergence.`, and continue.
+   - If the array is empty (`[]`): no action — do not modify the task frontmatter.
+   - If the array is non-empty: write `divergence_flag: true` to the task's frontmatter, then emit:
+     ```
+     [DIVERGENCE WARNING] Task <task_id>: the following files were changed but are not mentioned or inferable from the task description:
+       - <file1>
+       - <file2>
+     This is a non-blocking warning. Task outcome is not affected.
+     ```
+
+**This check is non-blocking.** It does not change the task's Passed/Failed outcome. It only writes `divergence_flag: true` and emits a warning for human review. Execution continues regardless of the check result.
+
+**Prompt calibration:** The prompt in `skills/do/assets/intent-vs-diff-prompt.md` is tuned to flag only files with zero plausible connection to the stated task. Test files, documentation files, lock files, and clearly implied files are excluded from flagging. See the `## False-Positive Tuning Rationale` section in the prompt template for full details.
+
 ### 6. Verify documentation
 After the developer completes the task, confirm the following documentation was written:
 - **Execution plan** — `project/documentation/plans/<E##_S##_T##>-plan.md` must exist (written by the developer before starting work)
@@ -78,7 +429,7 @@ If either file is missing, ask the developer to produce it before continuing.
 Additionally, if the completed work introduces user-facing changes, update `README.md` and `WARP.md` accordingly.
 
 ### 7. After successful completion
-- Check for any `_INSTRUCTIONS.md` files in `$(bash scripts/board_resolver.sh)tasks/` whose ID matches the completed task. If found, present them to the user and explain that these actions must be completed before the feature will work correctly.
+- Check for any `_INSTRUCTIONS.md` files in `project/instructions/` whose ID matches the completed task. If found, present them to the user and explain that these actions must be completed before the feature will work correctly.
 - Invoke the `/commit` skill to commit the work (if not already committed by the developer)
 - Run `bash scripts/todo_manager.sh remove '<task title>'` to remove the completed task from `project/todo.md`
 - Run `bash scripts/todo_manager.sh teardown` to delete `project/todo.md` if it is now effectively empty

package/skills/do/assets/intent-vs-diff-prompt.md

@@ -0,0 +1,69 @@
+# Intent-vs-Diff LLM Prompt Template
+
+This file contains the structured prompt used by `/do` to compare a completed task's stated intent against its actual diff. It is invoked **only** for tasks where `needs_docs: false`.
+
+## Purpose
+
+After a `needs_docs: false` task completes, `/do` runs `git diff --name-only HEAD~1` to get the list of changed file names and passes them — along with the task description and acceptance criteria — to the LLM using the prompt below. The LLM identifies any files that fall outside the expected scope of the task, enabling early detection of unregistered scope expansion.
+
+## False-Positive Tuning Rationale
+
+The prompt is calibrated to minimize false positives:
+
+1. **Test file exemption**: Test files that correspond to source files explicitly mentioned in the task description are NOT flagged. Adding tests is universally expected and implied by any implementation task.
+2. **Documentation file exemption**: Files like `README.md`, `WARP.md`, `CHANGELOG.md`, and any `*.md` in a `docs/` directory are NOT flagged. Documentation updates are standard outputs of any change.
+3. **Inferability threshold — both conditions required**: A file is only flagged when it is BOTH (a) not mentioned by name in the description, AND (b) not clearly inferable from what the description says. A task that says "update the login handler" implicitly covers the login handler's test file, its dependency injector, and related middleware — even if those are not named. Only files with zero connection to the stated task are flagged.
+4. **JSON-only output**: The LLM is asked to return only a JSON array to eliminate ambiguity in parsing the response.
+5. **Config/lock file exemption**: `package-lock.json`, `yarn.lock`, `*.lock`, and other machine-managed files are NOT flagged — they change as a side-effect of dependency changes and are never the primary intent of a task.
+
+## Prompt
+
+```
+You are reviewing a completed task to check if the implementation stayed within scope.
+
+Task description: {description}
+
+Acceptance criteria:
+{acceptance_criteria}
+
+Changed files:
+{changed_files}
+
+Your job: identify any changed files that are NOT mentioned and NOT clearly inferable from the task description or acceptance criteria above.
+
+Rules for what NOT to flag:
+- Do not flag test files (*.test.*, *.spec.*, files in __tests__/ or test/ directories) for source files that are explicitly mentioned or clearly implied in the task.
+- Do not flag documentation files (*.md, files in docs/ directories, README, WARP.md, CHANGELOG).
+- Do not flag lock files (package-lock.json, yarn.lock, *.lock, *.sum) or generated files (*.generated.*, dist/, build/).
+- Do not flag configuration files (*.config.*, .env.example, tsconfig.json) unless the task has zero connection to configuration.
+- Only flag a file when it has zero plausible connection to the stated task description. If you can construct a reasonable sentence explaining why the file might be touched given the task description, do not flag it.
+
+Return ONLY a JSON array of file paths that are unexpected scope expansions. If all files are expected or fall under the exemptions above, return an empty array.
+
+Examples of correct output:
+- All files expected: []
+- Two unexpected files: ["src/billing/invoice.ts", "scripts/deploy.sh"]
+
+Do not include any explanation, commentary, or text outside the JSON array.
+```
+
+## Usage in `/do`
+
+When the check runs, replace the template placeholders as follows:
+
+- `{description}` — the full text of the task's `## Description` section from the task board file
+- `{acceptance_criteria}` — the full text of the task's `## Acceptance Criteria` section (each criterion on its own line, including the `- [ ]` or `- [x]` prefix)
+- `{changed_files}` — the newline-separated output of `git diff --name-only HEAD~1`, one file path per line
+
+After receiving the LLM response:
+
+1. Attempt to parse the response as a JSON array.
+2. If parsing fails (malformed JSON), treat it as `[]` — do not flag divergence. Emit a debug note: `[intent-vs-diff] LLM response was not valid JSON; treating as no divergence.`
+3. If the array is empty (`[]`), proceed without modifying the task frontmatter.
+4. If the array is non-empty, write `divergence_flag: true` to the task's frontmatter and emit the warning:
+   ```
+   [DIVERGENCE WARNING] Task <task_id>: the following files were changed but are not mentioned or inferable from the task description:
+     - <file1>
+     - <file2>
+   This is a non-blocking warning. Task outcome is not affected.
+   ```

package/skills/doc/assets/path-objectives.yaml

@@ -36,3 +36,16 @@ rules:
     required_sections:
       - Release Entries
       - Notable Changes
+  - path: docs/STRATEGY.md
+    objective: strategy brief
+    summary: Produce a high-level strategy brief suitable for investors and strategic partners. Covers vision, value proposition, scope, and target audience. Does not include revenue model, pricing, or competitive analysis.
+    required_sections:
+      - Vision
+      - Value Proposition
+      - Scope
+      - Target Audience
+    generation_rules:
+      tone: Write for an investor or strategic partner audience. Use clear, confident language. Avoid jargon and internal shorthand. Do not use first-person plural ("we") excessively — prefer direct statements about the project.
+      sourcing: Draw content exclusively from PROJECT_SUMMARY.md and existing docs/. Do not invent facts, figures, or claims not present in the source material.
+      missing_fields: If the project has insufficient context to fill a section, produce a stub with the section header and a clearly marked note — e.g. "<!-- TODO: fill in once product direction is confirmed -->" — rather than erroring or hallucinating content.
+      exclusions: Do not include revenue model, pricing strategy, monetisation plans, competitive analysis, or financial projections. If any of these are present in source files, omit them silently.

package/skills/doc-sync/SKILL.md

@@ -87,6 +87,21 @@ For each update target and its resolved sources:
    - Outdated examples, wrong flag names, stale code snippets.
    - Incorrect or missing configuration keys/values.
 
+#### 4a. Cross-reference `.publicignore` for "missing documentation" candidates
+
+Every candidate identified above as "missing documentation for new things added in source" ships publicly by default unless this project has adopted `/mirror-public`. Before flagging any such candidate, check whether it's actually private-only:
+
+1. **Check for `.publicignore` at the repo root.** Most projects using this framework will not have one (they haven't adopted `/mirror-public`) — if it's absent, **skip this entire sub-step**. Fall through to flagging every "missing documentation" candidate exactly as `3.` above already would, with no further filtering.
+2. **If `.publicignore` exists**, for each "missing documentation" candidate, determine its source path (relative to the repo root) and classify it by running:
+   ```
+   scripts/check-publicignore-match.sh <path> [<path> ...]
+   ```
+   This reuses `/mirror-public`'s own `mirror.sh` matching logic (`rsync --exclude-from=.publicignore`) — a file this script reports `BLOCKED` is guaranteed to be a file `/mirror-public --dry-run` would also report as "would be blocked", and vice versa for `PUBLIC`. It needs no network access and does not require `/mirror-public` to be configured.
+3. **`BLOCKED`** → do not flag this candidate as missing documentation. It's private-only and will never ship to the public mirror, so public docs coverage is not applicable.
+4. **`PUBLIC`** → flag it as usual in step 5's report, and name `README.md` and `project/.wiki/documentation.md` (the confirmed canonical full-reference doc — see `assets/doc_targets.md`) as the target docs to check for coverage of this item.
+
+This sub-step only changes what gets flagged as "missing documentation" in step 3's third bullet — it does not affect the other three drift categories (renamed/removed references, outdated examples, incorrect config keys), which are flagged regardless of `.publicignore` since they concern existing documentation content, not public-shipping coverage of new source additions.
+
 ### 5. Report findings before updating
 
 Before making any writes, present a concise drift summary per file:
@@ -165,3 +180,4 @@ If minification could not reach the target, note: `⚠️ docs/API.md reduced to
 
 - `assets/doc_targets.md` — Editable list of documentation files this skill checks by default.
 - `assets/default_excludes.txt` — Paths always excluded from source analysis unless overridden.
+- `scripts/check-publicignore-match.sh` (repo root) — Used in step 4a to classify "missing documentation" candidates as `PUBLIC`/`BLOCKED` per `.publicignore`, reusing `/mirror-public`'s exact matching semantics.

package/skills/doc-sync/assets/doc_targets.md

@@ -8,7 +8,18 @@ Add one path per line inside the list below. Blank lines and lines starting with
 
 <!-- Add your project's documentation files here, one per line -->
 README.md
+project/.wiki/documentation.md
 <!-- docs/API.md -->
 <!-- docs/config.md -->
 <!-- CHANGELOG.md -->
 <!-- CONTRIBUTING.md -->
+
+<!--
+Note: project/.wiki/documentation.md is the confirmed-canonical full
+skill-reference doc (README.md links to it directly as "Full reference").
+A near-duplicate, project/documentation/documentation.md, has independently
+diverged from this canonical copy — see E28_S03_T01's execution summary for
+the investigation, and story E38_S01 for the planned consolidation. Do not
+add project/documentation/documentation.md here until that consolidation
+lands.
+-->

package/skills/idea/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: idea
+description: Capture a loosely-defined idea to project/ideas.md — a lightweight, "maybe someday" log with no board or promotion overhead.
+keywords:
+  - idea
+  - capture idea
+  - log idea
+  - brain dump
+  - maybe someday
+examples:
+  - "capture this as an idea"
+  - "log this idea for later"
+  - "I have a rough idea I want to jot down"
+metadata:
+  prefered_agent: scrum-master
+---
+
+# Idea — Lightweight Idea Capture
+
+## Instructions
+
+1. **Ensure `project/ideas.md` exists** — If it doesn't exist, it will be auto-created by `idea_manager.sh` from `skills/idea/assets/idea_template.md` — no manual action needed.
+
+2. **Ask the user about the idea:**
+   - What's the idea?
+   - Any known context worth noting (why it came up, what it might relate to)?
+
+   Keep this light — `/idea` is a low-overhead capture, not a structured mission intake like `/todo`.
+
+3. **Add to `project/ideas.md`** by running:
+   ```
+   bash scripts/idea_manager.sh add '<idea>'
+   ```
+
+4. **Ask the user**: "Capture another idea, or done?"
+   - If **another** — go back to step 2.
+   - If **done** — exit.
+
+   Unlike `/todo`, `/idea` never offers to execute, refine, or promote the captured idea(s) at the end. There is no `/do`-style follow-up here — `/idea` has no refine or promotion logic of its own.
+
+## For Reference Only — Promotion Convention (not implemented here)
+
+`/idea` does not implement any refine or promotion mechanism. This section documents, for reference, how promotion is expected to work elsewhere so future flows stay consistent:
+
+- **Promoting an idea** means re-running `/brainstorm` on it, which routes onward to `/btw` or `/todo` as normal. That routing behavior already exists and is out of scope for `/idea`.
+- **Terminal idea states** are marked directly in `project/ideas.md` using the same HTML-comment tag convention `project/todo.md` uses for `RECONCILED`:
+  - `PROMOTED` — the idea was picked up via `/brainstorm` and turned into board work.
+  - `DISCARDED` — the idea was reviewed and dropped.
+
+  Example (mirroring `project/todo.md`'s tagging style):
+  ```
+  Add dark mode toggle to settings page <!-- PROMOTED -->
+  Rewrite onboarding copy in a more casual tone <!-- DISCARDED -->
+  ```
+
+No agent invoked by `/idea` applies these tags or acts on them — that is reserved for a future promotion step (e.g. within `/brainstorm`).

package/skills/idea/assets/idea_handoff_template.md

@@ -0,0 +1,26 @@
+# Idea Handoff
+
+<!-- PREAMBLE (for /idea): This template was pre-filled by a caller (e.g. /spinoff).
+     Skip any questions whose answers are already provided below. Only prompt the user
+     for fields that remain empty or marked as a placeholder. -->
+
+<!-- Format: <mission title>: <E##_S##> (epic/story ref optional) -->
+
+## Mission Title
+<!-- PLACEHOLDER: short name for this idea, e.g. "Refactor auth middleware" -->
+
+## Goal / Objective
+<!-- PLACEHOLDER: what this idea is trying to achieve -->
+
+## Affected Files or Scope
+<!-- PLACEHOLDER: which files, modules, or areas are involved, e.g. src/auth/, skills/idea/ -->
+
+## Intended Approach
+<!-- PLACEHOLDER: step-by-step or high-level approach to the work -->
+
+## Epic / Story Linkage
+<!-- PLACEHOLDER: known Epic or Story ID this links to, e.g. E02_S03 — or "None" if not linked -->
+
+## Origin
+<!-- PLACEHOLDER: EST id (task/story/epic) in progress when the divergence happened, or "None" -->
+<!-- PLACEHOLDER: one-line summary of what the user was doing at the time -->

package/skills/idea/assets/idea_template.md

@@ -0,0 +1,3 @@
+# Ideas
+
+<!-- Format: <idea text> (one line per idea; terminal tags PROMOTED / DISCARDED appended by /brainstorm, not by /idea) -->