fix(tasks): require executable commands for governed operations in task bodies#2264
Conversation
|
How does this solve the issue if the tasks.md itself gets truncated out of context? |
|
Good question — this is the key distinction: The fix targets the generated output, not the template. Here's the flow:
The template being truncated is irrelevant to execution: its job is done the moment the tasks are generated. The task body is what persists across sessions and late-context compression — and that's exactly where the command now lives. |
|
You misunderstood me. When you execute the implement command it will read the tasks.md file at the beginning and during the execution it can also lose the context of that. It is the nature of how the original SDD process as defined by Spec Kit operates. All implementation is done by the implement command and so if the tasks.md has a large number of tasks whatever was in context at the beginning can disappear just the same |
|
You're right that tasks.md can be compacted out during a long implement session. The distinction is: when the implement command re-reads a task from disk to execute it, the exact command is already in that task body — no cross-reference to the constitution is needed. Each task is now self-contained, so context compression of tasks.md doesn't cascade into a command-guessing failure at execution time. |
| - **Mandatory hook** (`optional: false`): | ||
| ``` | ||
|
|
||
| ```text |
There was a problem hiding this comment.
Why are you adding this in multiple places?
There was a problem hiding this comment.
Good catch — removed the duplicate from tasks-template.md Format Legend (commit 498251f). The generation rule in tasks.md is the single authoritative source; the legend entry was redundant.
…nd fix context-loss gap Remove governed-operation hint from tasks-template.md Format Legend; the generation rule in tasks.md is the single authoritative source, so the legend entry was redundant duplication. Add Task-level re-read instruction to implement.md step 6: before executing each task the agent re-reads that task's entry from tasks.md on disk. This closes the gap the reviewer identified — the initial tasks.md load can be compacted out of context during a long session, but a per-task re-read ensures embedded governed commands are always in active context at execution time.
|
Two changes in commit 498251f:
|
There was a problem hiding this comment.
Pull request overview
This PR updates the /speckit.tasks (and related) documentation/templates to require that tasks for constitution-governed operations include the exact executable command (with env var placeholders), reducing agent “guessing” when constitution context is no longer present.
Changes:
- Add a new Governed Operations (REQUIRED) rule to the tasks command template, including examples.
- Update the implement command template to encourage re-reading each task entry before execution (to keep embedded commands in context).
- Apply markdownlint-driven formatting fixes across several markdown docs (e.g., fenced code block info strings and spacing).
Show a summary per file
| File | Description |
|---|---|
| workflows/README.md | Adds fenced code language (text) for markdownlint compliance. |
| workflows/ARCHITECTURE.md | Adds fenced code language (text) for markdownlint compliance. |
| tests/hooks/TESTING.md | Removes trailing whitespace in expected behavior header. |
| templates/commands/taskstoissues.md | Adds blank lines + text info strings to fenced blocks; normalizes list formatting. |
| templates/commands/tasks.md | Introduces governed-operations requirement; normalizes fenced block formatting. |
| templates/commands/implement.md | Adds task-level re-read instruction; minor whitespace normalization. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 5/6 changed files
- Comments generated: 3
|
Please address Copilot feedback |
- Fix escaped-backtick rendering bug in governed example (tasks.md:175): use double-backtick outer span so inner backtick displays correctly - Add missing info strings (text) to four bare fenced code blocks in implement.md (MD040 compliance) - pre-hook and post-hook sections
There was a problem hiding this comment.
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 5/6 changed files
- Comments generated: 2
| When a task covers a governed operation, its description MUST include the exact executable command from the constitution, parameterized with environment variable names rather than literal credential values. Do not paraphrase the command. | ||
|
|
||
| ```text | ||
| - [ ] [TaskID] [P?] [Story?] Description: `<exact-command --flag $ENV_VAR>` |
There was a problem hiding this comment.
This new governed-operations guidance conflicts with the earlier "Description with file path" requirement: both the governed example and the governed format snippet omit a file path entirely. Either update the governed examples/snippet to include a file path (while still embedding the exact executable command), or explicitly document that certain governed-operation tasks are exempt from the file-path requirement so agents don’t get contradictory instructions.
| When a task covers a governed operation, its description MUST include the exact executable command from the constitution, parameterized with environment variable names rather than literal credential values. Do not paraphrase the command. | |
| ```text | |
| - [ ] [TaskID] [P?] [Story?] Description: `<exact-command --flag $ENV_VAR>` | |
| When a task covers a governed operation, it MUST still include the required file path from the standard task format, and its description MUST include the exact executable command from the constitution, parameterized with environment variable names rather than literal credential values. Do not paraphrase the command. | |
| ```text | |
| - [ ] [TaskID] [P?] [Story?] path/to/file.ext Description: `<exact-command --flag $ENV_VAR>` |
| ```text | ||
| ## Extension Hooks | ||
|
|
||
| **Automatic Pre-Hook**: {extension} |
There was a problem hiding this comment.
In this fenced text example, there is a whitespace-only line after EXECUTE_COMMAND: {command} (within the same block) that contains trailing spaces. With markdownlint default rules (MD009) enabled, that can cause a lint failure; make the line truly empty (no spaces) or remove it.
See below for a potential fix:
|
Please address Copilot feedback. If not applicable, please explain why |
- Remove trailing whitespace in implement.md line 45 (MD009 lint fix) - Clarify file path requirement for governed operations in tasks.md - Update governed example to include file path (dist/*.nupkg) - Update format template to show: path/to/file.ext Description: `command` Resolves all outstanding Copilot review comments.
|
All Copilot feedback has been addressed in commit 6a4294f:
The governed operations section now explicitly states: "it MUST still include the required file path from the standard task format" and the format shows: Ready for re-review. |
There was a problem hiding this comment.
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (3)
templates/commands/implement.md:41
- Markdownlint MD031 (enabled by default) requires fenced code blocks to be surrounded by blank lines. This mandatory-hook fenced block starts immediately after the list item line; insert a blank line before the fence (maintaining list indentation) to avoid lint failures.
- **Mandatory hook** (`optional: false`):
```text
## Extension Hooks
templates/commands/implement.md:186
- Markdownlint MD031 requires fenced code blocks to be surrounded by blank lines. In this post-execution optional-hook example, the fence starts immediately after the list item line; add a blank line before the fence (with proper indentation) to comply.
- **Optional hook** (`optional: true`):
```text
## Extension Hooks
templates/commands/implement.md:198
- Markdownlint MD031 requires fenced code blocks to be surrounded by blank lines. In this post-execution mandatory-hook example, the fence starts immediately after the list item line; add a blank line before the fence (with proper indentation) to comply.
- **Mandatory hook** (`optional: false`):
```text
## Extension Hooks
**Automatic Hook**: {extension}
- Files reviewed: 5/6 changed files
- Comments generated: 1
| - **Optional hook** (`optional: true`): | ||
| ``` | ||
| ```text | ||
| ## Extension Hooks |
There was a problem hiding this comment.
Markdownlint MD031 is enabled (default rules) and requires fenced code blocks to be surrounded by blank lines. This optional-hook fence is immediately after the list item line; add a blank line before the fence (and keep indentation) to satisfy MD031 consistently with the other command templates.
This issue also appears in the following locations of the same file:
- line 38
- line 183
- line 194
|
Please address Copilot feedback |
…ompliance Addresses Copilot feedback: MD031 requires fenced code blocks to be surrounded by blank lines. Added blank lines before all four hook example code blocks (lines 27, 38, 183, 194) to satisfy markdownlint default rules.
ayeshakhalid192007-dev
left a comment
There was a problem hiding this comment.
Fixed in b0db74f — added blank lines before all four fenced code blocks (lines 27, 38, 183, 194) to satisfy MD031.
|
All Copilot feedback addressed:
The governed example now includes the file path (dist/*.nupkg) and the format template explicitly documents that governed operations MUST include the file path. |
There was a problem hiding this comment.
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 5/6 changed files
- Comments generated: 0 new
Fixes #2219
Description
Tasks generated by
/speckit.tasksdescribe governed operations in prose.When the constitution is compacted out of context, the agent guesses the
command, gets flags wrong, and the operation fails (e.g. 403 on NuGet push).
Root Cause
Task Generation Rules had no requirement to embed the exact command for
operations the constitution defines with specific syntax, flags, or env vars.
Tasks are always in agent context — prose descriptions throw that away.
Solution
Require that any task covering a governed operation includes the exact
executable command, parameterized with env var names, directly in the task body.
Changes
templates/commands/tasks.md— new### Governed Operations (REQUIRED)rule + examples; fix inline-code nesting in governed example (double-backtick outer span)templates/commands/implement.md— adds task-level re-read instruction; fixes four bare fenced code blocks (MD040 info strings)templates/commands/taskstoissues.md,tests/hooks/TESTING.md,workflows/ARCHITECTURE.md,workflows/README.md— pre-existing MD031/MD032/MD040 lint fixesWhy This Is Safe
Pure documentation change — no Python code, no CLI arguments, no new files.
Adds an instruction to an existing rule section; all existing task formats remain valid.
Testing
/speckit.taskson a project with a governed push/deploy in the constitution — verify generated task body contains the exact commandruff check src/passesmarkdownlinton changed files: 0 errors