strikethroo 3.21.2 → 3.22.0

package/templates/harness/skills/st-execute-blueprint/SKILL.md

@@ -5,15 +5,6 @@ description: Use when the user asks to run, execute, implement, or carry out a S
 
 # st-execute-blueprint
 
-Drive the end-to-end execution of an existing Strikethroo plan blueprint.
-
-## Critical Rules
-
-1. **Never skip validation gates** — a phase is not complete until `POST_PHASE.md` succeeds.
-2. **Preserve dependency order** — never execute a task before all of its dependencies are completed.
-3. **Maximize parallelism within each phase** — run all tasks whose dependencies are satisfied simultaneously.
-4. **Fail safely and document everything** — halt on unrecoverable errors, and record all decisions, issues, and outcomes under "Noteworthy Events" in the execution summary.
-
 ## Inputs
 
 The user supplies the numeric plan ID conversationally.
@@ -22,20 +13,22 @@ The user supplies the numeric plan ID conversationally.
 
 ### 1. Locate the strikethroo root
 
-Run `scripts/find-strikethroo-root.cjs` from the user's working directory.
+Run `scripts/find-strikethroo-root.cjs` from the user's working directory. If
+it exits non-zero, stop and ask the user to run `npx strikethroo init`.
 
-If the script exits non-zero, the working directory is not inside an
-initialized strikethroo workspace. Stop and ask the user to run the project
-initializer (e.g. `npx strikethroo init`) before continuing. Do
-not attempt to execute a plan outside of a valid root.
+Treat the path it prints as `<root>` for every subsequent step.
 
-For every subsequent step, treat the path printed by this script as `<root>`.
+Delegated execution workers skip this step and do not emit update notices.
+
+Run `scripts/check-for-updates.cjs "<root>"` as a separate command using this
+skill's script path. Keep the user's working directory. Read the one JSON line
+on stdout. When `notice` is present, retain its exact text for the final
+user-facing response. Never pause for permission and never run an update.
 
 ### 2. Resolve the plan
 
-Run `scripts/validate-plan-blueprint.cjs <plan-id> planFile` to obtain the
-absolute path of the plan file. Passing a different field name prints that
-field alone.
+Run `scripts/validate-plan-blueprint.cjs <plan-id> planFile` for the plan
+file's absolute path. Another field name prints that field instead.
 
 If the script exits non-zero, stop and ask the user to confirm the plan ID.
 Do not guess a different ID.
@@ -52,26 +45,26 @@ Run `scripts/validate-plan-blueprint.cjs <plan-id> taskCount` and
 
 If `taskCount` is 0 or `blueprintExists` is `no`:
 
-- Notify the user: "Tasks or execution blueprint not found. Generating tasks automatically..."
+Notify the user: "Tasks or execution blueprint not found. Generating tasks automatically..."
+
 - Follow the `st-generate-tasks` skill for this plan ID. Execute its operating procedure in full, including running `POST_TASK_GENERATION_ALL.md` to write the Execution Blueprint.
-- After generation completes, re-run the `planFile`, `planDir`, `taskCount`, and `blueprintExists` queries to refresh the resolved paths and counts.
+- Re-run the `planFile`, `planDir`, `taskCount`, and `blueprintExists` queries to refresh the resolved paths and counts.
 
-If generation still leaves the plan without tasks or a blueprint, stop and report failure. Do not attempt execution without a valid blueprint.
+If the plan still has no tasks or no blueprint, stop and report failure.
 
 ### 5. Optionally create a feature branch
 
-Run `scripts/create-feature-branch.cjs <plan-id>` once before phase execution. Branch creation is best-effort: when the script reports that it skipped creation (for example, not on `main`/`master`), continue on the current branch and do not retry or create a branch manually. Uncommitted or untracked changes are permitted only when every change is inside the repository-root `.ai/strikethroo` subtree. When the script exits with an error—including changes anywhere outside that subtree or an inability to inspect Git status on `main`/`master`—halt and report the error. Do not treat a skipped branch as a failure or spend effort working around a skip.
+Run `scripts/create-feature-branch.cjs <plan-id>` once before phase execution. A skip is not a failure. Continue on the current branch, and never create the branch by hand. Uncommitted or untracked changes are permitted only inside the repository-root `.ai/strikethroo` subtree. An error result halts execution; report it.
 
-After the branch step, run `scripts/capture-base-commit.cjs <plan-id>` once. It records the commit the review gate diffs against. A `skipped` result is not a failure — continue execution and note that the review gate will skip. Only an `error` result halts.
+Then run `scripts/capture-base-commit.cjs <plan-id>` once to record the commit the review gate diffs against. A `skipped` result continues execution and means the review gate will skip. Only an `error` result halts.
 
 ### 6. Load project context and execution blueprint
 
 Read these files, in order:
 
-- `<root>/config/STRIKETHROO.md` — directory conventions and project context.
-- The plan document at the path returned by step 2.
-- The plan's Execution Blueprint section — this defines the phase groupings and task dispatch order.
-- `<root>/config/shared/verification-gate.md` and `<root>/config/shared/anti-rationalization.md` — apply in the phase loop below.
+- `<root>/config/STRIKETHROO.md`
+- The plan document at the path from step 2, including its Execution Blueprint section, which defines the phase groupings and task dispatch order.
+- `<root>/config/shared/verification-gate.md` and `<root>/config/shared/anti-rationalization.md`, both applied in the phase loop below.
 
 ### 7. Execute phases in order
 
@@ -93,17 +86,13 @@ scripts/dispatch-task-execution.cjs resolve <task-file> <current-harness> <works
 ```
 
 Resolvers never launch external processes. After interpreting all route results, issue
-every external execution and every native Task-tool agent **together in one parallel
+every external execution and every sub-agent **together in one parallel
 tool operation**. External execution uses:
 
 ```text
 scripts/dispatch-task-execution.cjs execute <handoff> <task-file> <current-harness> <workspace> <plan-id> <task-id>
 ```
 
-This two-step protocol is mandatory: do not execute external tasks during route
-resolution, do not serialize external commands, and do not wait for external completion
-before launching ready native agents.
-
 `<current-harness>` is the exact supported harness identifier running this
 skill; `<workspace>` is the project working directory.
 
@@ -114,29 +103,20 @@ Interpret the one-line JSON result and act on its `kind` exactly once:
 | `native-default` | Dispatch natively with no execution-setting prose. |
 | `native-override` | Dispatch natively, explicitly requiring the exact returned `model`. Require the returned `reasoningEffort` only when that property is present. |
 | `external-override` | Run the `execute` command with the returned `handoff`, then read its result against this same table. |
-| `fallback` | Nothing launched. Record the returned `reason` and `detail` visibly, then dispatch natively with no execution-setting prose. Either command can return it. |
+| `fallback` | Nothing launched. Record the returned `reason` and `detail` visibly, then dispatch natively with no execution-setting prose. |
 | `launched-success` | The external process exited zero. Do not dispatch natively; review status and evidence as you would for a native agent. |
 | `launched-failure` | A failed task. Set its status to `failed` and run `<root>/config/hooks/POST_ERROR_DETECTION.md`. Never retry it natively. |
-| `infrastructure-failure` | A failed task. Set its status to `failed` and run `<root>/config/hooks/POST_ERROR_DETECTION.md`. Never retry it natively. |
+| `infrastructure-failure` | Handle exactly as the preceding row. |
 
-Handoff and exit rules:
+Handoff rules:
 
 - Pass the exact opaque `handoff` string the resolver returned for that task. Never reconstruct one.
 - Never reuse a handoff for another task, and never rerun resolution after launches begin.
-- `execute` validates the handoff and does not reread routing configuration.
-- The command emits exactly one JSON line. Exit code `2` is an infrastructure failure; exit code `1` is a launched task failure.
 
-Deploy all remaining native agents simultaneously using your internal Task tool. Each agent MUST:
-
-1. Read and execute `<root>/config/hooks/PRE_TASK_EXECUTION.md` before starting any implementation work.
-2. Execute the task according to its requirements.
-3. Monitor execution progress and capture outputs and artifacts.
-4. Update task status in real-time.
+Deploy all remaining native sub-agents simultaneously. Each sub-agent must read and execute `<root>/config/hooks/PRE_TASK_EXECUTION.md` before any implementation work, then execute the task and update its status. Do not run `scripts/check-for-updates.cjs`; delegated workers do not consume update notices.
 
 #### 7c. Phase completion verification
-Ensure every task in the phase has status `completed`. Collect and review all task outputs. Document any issues or exceptions encountered.
-
-Do not accept a subagent's report of success as proof. Apply the evidence gate in `<root>/config/shared/verification-gate.md` before marking the phase complete. Do not mark a phase complete on an unverified claim.
+Ensure every task in the phase has status `completed` and collect its outputs. Do not accept a subagent's report of success as proof. Apply the evidence gate in `<root>/config/shared/verification-gate.md` before marking the phase complete.
 
 #### 7d. Phase post-execution
 Read `<root>/config/hooks/POST_PHASE.md` and execute its instructions. Do not proceed to the next phase until this hook succeeds.
@@ -167,17 +147,15 @@ After `POST_EXECUTION.md` reports green, follow the `st-code-review` skill and r
 code-review.cjs <plan-id> <current-harness>
 ```
 
-Resolve `code-review.cjs` from the `st-code-review` skill's sibling `scripts` directory. Pass the exact supported harness identifier running this skill. The command emits exactly one JSON line on stdout; reviewer output goes to stderr.
-
-If the `st-code-review` skill is not installed, record that outcome in the execution summary and continue to summary and archival.
+Resolve `code-review.cjs` from the `st-code-review` skill's sibling `scripts` directory and pass the exact supported harness identifier running this skill. If the `st-code-review` skill is not installed, record that outcome in the execution summary and continue to summary and archival.
 
-Handle the JSON line in this order:
+Handle the one JSON line it prints on stdout, in this order:
 
 1. Copy it verbatim into the execution summary's review outcome. Do not reformat it or omit fields.
-2. Follow its top-level `action`. If it is `halt`, stop and report the top-level `detail`; execution is incomplete. If it is `continue`, proceed to the execution summary and archival.
+2. Follow its top-level `action`. If it is `halt`, stop and report the top-level `detail`. If it is `continue`, proceed to the execution summary and archival.
 3. Only when `verdict.kind` is `review-recorded`, read `<plan-dir>/review/review.xml` and `<plan-dir>/review/findings.json`, then decide which findings to act on. `severity` and `confidence` are advisory labels, not instructions.
 
-The compiled top-level `action` and exit status control the decision. Do not re-derive `action` from another field. Never report an uncertified review as clean.
+Never report an uncertified review as clean.
 
 Hard rules:
 
@@ -187,19 +165,11 @@ Hard rules:
 
 ### 9. Append execution summary
 
-Append an execution summary section to the plan document using the format described in `<root>/config/templates/EXECUTION_SUMMARY_TEMPLATE.md`. Populate:
-
-- **Status**: Completed Successfully
-- **Completed Date**: current date
-- **Results**: brief summary of deliverables
-- **Noteworthy Events**: all decisions, issues, and outcomes encountered during execution. Always record the review gate's outcome here: the gate's JSON line verbatim, then which findings you acted on versus ignored and why. If nothing else occurred, state "No significant issues encountered." after the review outcome.
-- **Necessary follow-ups**: any follow-up actions or optimizations
+Append an execution summary section to the plan document, filling every field of `<root>/config/templates/EXECUTION_SUMMARY_TEMPLATE.md`. Under Noteworthy Events, always record the review gate's JSON line verbatim, then which findings you acted on versus ignored and why.
 
 ### 10. Archive the plan
 
-Move the completed plan directory from `<root>/plans/<plan-folder>` to `<root>/archive/<plan-folder>`.
-
-Preserve the entire folder structure, including all tasks and subdirectories. If the move fails, log the error but do not fail the overall execution.
+Move the completed plan directory from `<root>/plans/<plan-folder>` to `<root>/archive/<plan-folder>`, preserving the entire folder structure. If the move fails, log the error but do not fail the overall execution.
 
 ## Failure Modes
 
@@ -207,7 +177,7 @@ Preserve the entire folder structure, including all tasks and subdirectories. If
 
 ## Execution Summary
 
-Conclude with exactly this block as the final output:
+Conclude with exactly this block (a retained update notice, when present, follows separately):
 
 ```
 ---
@@ -219,3 +189,7 @@ Execution Summary:
 ```
 
 The summary is consumed by downstream automation; keep the format exact.
+
+When the retained update `notice` is present, append that exact sentence after
+the structured summary block, or after your final response when this skill emits
+no summary block. Nothing may follow the notice.