Skip to content

fix(tasks): require executable commands for governed operations in task bodies#2264

Open
ayeshakhalid192007-dev wants to merge 4 commits intogithub:mainfrom
ayeshakhalid192007-dev:fix/tasks-embed-governed-commands
Open

fix(tasks): require executable commands for governed operations in task bodies#2264
ayeshakhalid192007-dev wants to merge 4 commits intogithub:mainfrom
ayeshakhalid192007-dev:fix/tasks-embed-governed-commands

Conversation

@ayeshakhalid192007-dev
Copy link
Copy Markdown
Contributor

Fixes #2219

Description

Tasks generated by /speckit.tasks describe 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
  • templates/tasks-template.md — governed-command bullet added to Format legend
  • templates/commands/taskstoissues.md, tests/hooks/TESTING.md,
    workflows/ARCHITECTURE.md, workflows/README.md — pre-existing MD031/MD032/MD040 lint fixes

Why 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

  • Run /speckit.tasks on a project with a governed push/deploy in the constitution — verify generated task body contains the exact command
  • ruff check src/ passes
  • markdownlint on changed files: 0 errors

@mnriem
Copy link
Copy Markdown
Collaborator

mnriem commented Apr 20, 2026

How does this solve the issue if the tasks.md itself gets truncated out of context?

@ayeshakhalid192007-dev
Copy link
Copy Markdown
Contributor Author

Good question — this is the key distinction: templates/commands/tasks.md is only read during /speckit.tasks generation, not during task execution.

The fix targets the generated output, not the template.

Here's the flow:

  1. Agent runs /speckit.tasks → constitution is in active context → template instructs the agent to read the constitution and embed exact governed commands into each task body.
  2. Later, when the agent executes a task, it reads the task body — which now contains the exact command (e.g., dotnet nuget push "*.nupkg" --api-key $NUGET_API_KEY --source $NUGET_FEED_URL).
  3. At execution time, the constitution and the template may both be gone — but the command is already embedded in the task itself, so the agent runs it correctly.

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.

@mnriem
Copy link
Copy Markdown
Collaborator

mnriem commented Apr 20, 2026

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

@ayeshakhalid192007-dev
Copy link
Copy Markdown
Contributor Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: Agent loses constitution context mid-execution and falls back to guessing

2 participants