fix(prompt): clarify execute-phase active flags

commands/gsd/execute-phase.md

@@ -22,6 +22,11 @@ Optional wave filter:
 - `--wave N` executes only Wave `N` for pacing, quota management, or staged rollout
 - phase verification/completion still only happens when no incomplete plans remain after the selected wave finishes
 
+Flag handling rule:
+- The optional flags documented below are available behaviors, not implied active behaviors
+- A flag is active only when its literal token appears in `$ARGUMENTS`
+- If a documented flag is absent from `$ARGUMENTS`, treat it as inactive
+
 Context budget: ~15% orchestrator, 100% fresh per subagent.
 </objective>
 
@@ -33,10 +38,16 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
 <context>
 Phase: $ARGUMENTS
 
-**Flags:**
+**Available optional flags (documentation only — not automatically active):**
 - `--wave N` — Execute only Wave `N` in the phase. Use when you want to pace execution or stay inside usage limits.
 - `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
 
+**Active flags must be derived from `$ARGUMENTS`:**
+- `--wave N` is active only if the literal `--wave` token is present in `$ARGUMENTS`
+- `--gaps-only` is active only if the literal `--gaps-only` token is present in `$ARGUMENTS`
+- If neither token appears, run the standard full-phase execution flow with no flag-specific filtering
+- Do not infer that a flag is active just because it is documented in this prompt
+
 Context files are resolved inside the workflow via `gsd-tools init execute-phase` and per-subagent `<files_to_read>` blocks.
 </context>
 

tests/execute-phase-active-flags.test.cjs

@@ -0,0 +1,58 @@
+/**
+ * Execute-phase active flag prompt tests
+ *
+ * Guards against prompt wording that makes optional flags look active by default.
+ * This is especially important for weaker runtimes that may infer `--gaps-only`
+ * from the command docs instead of the literal user arguments.
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+const COMMAND_PATH = path.join(__dirname, '..', 'commands', 'gsd', 'execute-phase.md');
+
+describe('execute-phase command: active flags are explicit', () => {
+  test('command file exists', () => {
+    assert.ok(fs.existsSync(COMMAND_PATH), 'commands/gsd/execute-phase.md should exist');
+  });
+
+  test('objective says documented flags are not implied active', () => {
+    const content = fs.readFileSync(COMMAND_PATH, 'utf-8');
+    const objectiveMatch = content.match(/<objective>([\s\S]*?)<\/objective>/);
+    assert.ok(objectiveMatch, 'should have <objective> section');
+    assert.ok(
+      objectiveMatch[1].includes('available behaviors, not implied active behaviors'),
+      'objective should state that documented flags are not automatically active'
+    );
+    assert.ok(
+      objectiveMatch[1].includes('appears in `$ARGUMENTS`'),
+      'objective should tie flag activation to literal $ARGUMENTS presence'
+    );
+  });
+
+  test('context separates available flags from active flags', () => {
+    const content = fs.readFileSync(COMMAND_PATH, 'utf-8');
+    assert.ok(
+      content.includes('Available optional flags (documentation only'),
+      'context should clearly label flags as documentation only'
+    );
+    assert.ok(
+      content.includes('Active flags must be derived from `$ARGUMENTS`'),
+      'context should have a separate active-flags section'
+    );
+  });
+
+  test('context explicitly warns against inferring inactive flags', () => {
+    const content = fs.readFileSync(COMMAND_PATH, 'utf-8');
+    assert.ok(
+      content.includes('Do not infer that a flag is active just because it is documented in this prompt'),
+      'context should forbid inferring flags from documentation alone'
+    );
+    assert.ok(
+      content.includes('If neither token appears, run the standard full-phase execution flow'),
+      'context should define the no-flags fallback behavior'
+    );
+  });
+});