Keep Guardex prompts from encouraging fragmented probe loops (#346)

Guardex already preferred phase-based execution, but the copied task-loop prompt was still too sparse. This change makes the repo contract and gx prompt say low output is fine when bounded, and that long runs should collapse back to inspect once, patch once, verify once, then finish.

Constraint: Prompt copy must stay short enough for gx prompt output
Rejected: Only patch AGENTS.md | gx prompt would keep emitting weaker task-loop wording
Confidence: high
Scope-risk: narrow
Directive: Keep task-loop copy phase-shaped; do not reintroduce vague micro-step prompt text
Tested: node --test test/prompt.test.js; openspec validate --specs; git diff --check
Not-tested: Full gx prompt output in a live protected-repo bootstrap

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

AGENTS.md

@@ -21,6 +21,7 @@ When writing complex features or significant refactors, use an ExecPlan (as desc
   2. grouped edits or grouped repo actions
   3. focused verification
   4. compact summary
+- Low output alone is not a defect. A bounded run that finishes in roughly <=10 steps is usually fine; low output stretched across 20+ steps with rising input is fragmentation.
 - Treat obvious follow-on actions as part of the active phase; do not stop for tiny internal checkpoints.
 - If context grows or the session becomes fragmented, write a short working summary and continue from it.
 
@@ -30,12 +31,14 @@ When writing complex features or significant refactors, use an ExecPlan (as desc
 - Prefer targeted reads: `rg`, `head`, `tail`, `git diff`, and exact line ranges.
 - Keep command output compact and relevant.
 - Avoid repeated status checks unless something changed.
+- Treat repeated `sed` / `cat` peeks, tiny diagnostic retries, and repeated `write_stdin` as red flags. When they appear, stop the probe loop and reset to one bounded phase.
 
 ### Command Discipline
 
 - Batch related shell commands whenever safe.
 - Prefer one-shot non-interactive commands, scripts, or exact invocations over interactive loops or repeated stdin driving.
 - For diagnosis, gather the relevant evidence in one pass, then summarize once.
+- If the session turns fragmented, collapse back to inspect once, patch once, verify once, and summarize once.
 
 ### Git And PR Workflow
 

openspec/changes/tighten-token-fragmentation-prompts/proposal.md

@@ -0,0 +1,7 @@
+# Proposal: tighten Guardex token-fragmentation prompts
+
+Guardex already prefers phase-based execution, but the copied `gx prompt` task loop still underspecifies the anti-fragmentation pattern. This change makes the repo contract and prompt output teach the stronger classifier: low output alone is fine when the run is bounded, while long low-output sessions with repeated peeks or `write_stdin` loops are fragmentation.
+
+- add the bounded-vs-fragmented classifier to `AGENTS.md`
+- teach `gx prompt` to say inspect once, patch once, verify once, then finish
+- lock the prompt wording with focused tests

openspec/changes/tighten-token-fragmentation-prompts/tasks.md

@@ -0,0 +1,22 @@
+## 1. Spec
+
+- [x] 1.1 Capture why Guardex prompt surfaces should blame long fragmented runs, not low output alone.
+
+## 2. Implementation
+
+- [x] 2.1 Update `AGENTS.md` with the bounded-vs-fragmented classifier and stop-loop guidance.
+- [x] 2.2 Update `src/context.js` task-loop prompt text to push inspect-once / patch-once / verify-once execution.
+- [x] 2.3 Update `test/prompt.test.js` to lock the new prompt wording.
+
+## 3. Verification
+
+- [x] 3.1 Run `node --test test/prompt.test.js`.
+- [x] 3.2 Run `openspec validate --specs`.
+
+Verification evidence:
+- `node --test test/prompt.test.js` (pass)
+- `openspec validate --specs` (no items found to validate)
+
+## 4. Cleanup
+
+- [ ] 4.1 Commit, push, open/update PR, merge, and clean up the worktree.

src/context.js

@@ -425,7 +425,8 @@ const AI_SETUP_PARTS = [
     label: 'Task loop',
     promptLines: [
       'gx branch start "<task>" "<agent>"',
-      'then gx locks claim --branch "<agent-branch>" <file...> -> gx branch finish',
+      'then gx locks claim --branch "<agent-branch>" <file...> -> inspect once -> patch once -> verify once -> gx branch finish',
+      'batch discovery, git/PR, and CI by phase; avoid repeated peeks or stdin loops',
     ],
     execLines: [
       'gx branch start "<task>" "<agent>"',

test/prompt.test.js

@@ -73,6 +73,8 @@ test('prompt outputs AI setup instructions', () => {
   assert.match(result.stdout, /gx doctor/);
   assert.match(result.stdout, /gx branch start/);
   assert.match(result.stdout, /gx locks claim/);
+  assert.match(result.stdout, /inspect once -> patch once -> verify once -> gx branch finish/);
+  assert.match(result.stdout, /avoid repeated peeks or stdin loops/);
   assert.match(result.stdout, /gx finish --all/);
   assert.match(result.stdout, /\/opsx:propose/);
   assert.match(result.stdout, /https:\/\/github\.com\/apps\/pull/);
@@ -101,6 +103,7 @@ test('prompt --part outputs only the selected checklist slices', () => {
   assert.equal(result.status, 0, result.stderr || result.stdout);
   assert.match(result.stdout, /^Task loop:/m);
   assert.match(result.stdout, /gx branch start "<task>" "<agent>"/);
+  assert.match(result.stdout, /inspect once -> patch once -> verify once -> gx branch finish/);
   assert.match(result.stdout, /^Finish:/m);
   assert.match(result.stdout, /gx finish --all/);
   assert.doesNotMatch(result.stdout, /GitGuardex \(gx\) setup checklist/);