Skip to content

Commit 3114401

Browse files
authored
Merge pull request #37 from nForma-AI/nf/quick-362-wire-debug-routing-into-execute-phase-md
feat: wire Loop 1 + Loop 2 into all phase execution paths
2 parents 61c7a63 + 8ea2085 commit 3114401

9 files changed

Lines changed: 333 additions & 2 deletions

File tree

.planning/STATE.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ See: .planning/PROJECT.md (updated 2026-03-25)
1212
Phase: 53 of 53 (Skill Deprecation) — COMPLETED
1313
Plan: 53-01 of 1 — COMPLETED
1414
Status: All phases complete — /nf:model-driven-fix deprecated, all consumers rewired to /nf:debug
15-
Last activity: 2026-03-26 - Completed quick task 361: Add automation-first bias to verify-work and execute-phase workflows
15+
Last activity: 2026-03-27 - Completed quick task 363: Push Loop 2 + debug_context into execute-plan.md Pattern A
1616

1717
Progress: [██████████] 100% (Phase 50 done; Phase 51 done; Phase 52 done; Phase 53 done)
1818

@@ -79,6 +79,8 @@ None yet.
7979
| 359 | Close gap: allow formal_artifacts create when scope-scan empty | 2026-03-26 | afdea71c | Verified | [359-close-the-gap-when-formal-scope-scan-fin](./quick/359-close-the-gap-when-formal-scope-scan-fin/) |
8080
| 360 | Add risk-based adaptive quorum fan-out: risk classifier, adaptive dispatch, audit logging | 2026-03-26 | 8e27fe35 | Verified | [360-add-risk-based-adaptive-quorum-fan-out-r](./quick/360-add-risk-based-adaptive-quorum-fan-out-r/) |
8181
| 361 | Add automation-first bias to verify-work and execute-phase workflows | 2026-03-26 | afbeac9e | Verified | [361-add-automation-first-bias-to-verify-work](./quick/361-add-automation-first-bias-to-verify-work/) |
82+
| 362 | Wire debug routing (Loop 1 + task classification + debug_context injection) into execute-phase.md | 2026-03-27 | 813c1d77 | Verified | [362-wire-debug-routing-into-execute-phase-md](./quick/362-wire-debug-routing-into-execute-phase-md/) |
83+
| 363 | Push Loop 2 + debug_context into execute-plan.md Pattern A spawn prompt | 2026-03-27 | 72bbe22d | Verified | [363-push-loop-2-and-debug-context-into-execu](./quick/363-push-loop-2-and-debug-context-into-execu/) |
8284

8385
### Blockers/Concerns
8486

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
task_id: 362
3+
description: "Wire debug routing (Loop 1 + task classification + autoresearch-refine + debug_context injection) into execute-phase.md"
4+
formal_artifacts: none
5+
---
6+
7+
# Plan: Wire Debug Routing into execute-phase.md
8+
9+
## Objective
10+
11+
Add per-plan task classification and debug routing to `execute-phase.md` so that bug-fix plans get routed through `/nf:debug` (Loop 1 autoresearch-refine) before execution, with constraints injected into executor prompts — matching the `quick.md` Step 5.8 pattern.
12+
13+
## Must-Haves
14+
15+
1. Per-plan Haiku task classification (bug_fix/feature/refactor) in the execute_waves step, before spawning each executor
16+
2. Debug routing: bug_fix plans (confidence >= 0.7) dispatched through `/nf:debug` before executor spawn
17+
3. Debug context injection: `<debug_context>` block conditionally injected into executor prompt with constraints, verdict, and reproducing model
18+
4. Fail-open: all new logic skips silently on Haiku unavailability, debug errors, or missing modules
19+
5. Sync repo source → installed copy after edit
20+
21+
## Tasks
22+
23+
### Task 1: Add per-plan task classification to execute_waves step
24+
25+
In `core/workflows/execute-phase.md`, inside `<step name="execute_waves">`, add a classification sub-step BEFORE spawning executor agents (before item 2 "Spawn executor agents"). For each plan in the wave:
26+
27+
1. Read the plan's `<objective>` text
28+
2. Spawn Haiku subagent to classify the plan objective as bug_fix/feature/refactor (same prompt as quick.md Step 2.7 sub-step 1.5)
29+
3. Store `$PLAN_CLASSIFICATION` per plan
30+
4. Fail-open: default to `{ type: "feature", confidence: 0.0 }` if Haiku unavailable
31+
32+
### Task 2: Add debug routing step between classification and executor spawn
33+
34+
Add a new sub-step after classification, before executor spawn:
35+
36+
1. **Skip if:** `$PLAN_CLASSIFICATION.type` is NOT `bug_fix`, OR confidence < 0.7
37+
2. **If routing:** Spawn `/nf:debug` as Task subagent with the plan objective as failure context (same pattern as quick.md Step 5.8 item 2)
38+
3. Parse debug output → extract `$DEBUG_CONSTRAINTS`, `$DEBUG_FORMAL_VERDICT`, `$DEBUG_REPRODUCING_MODEL`
39+
4. Fail-open: on error, set all debug vars to null and continue
40+
41+
### Task 3: Inject debug_context block into executor prompt
42+
43+
Modify the executor Task spawn (item 2 in execute_waves) to conditionally include a `<debug_context>` block after the `</formal_coverage_auto_detection>` section:
44+
45+
```
46+
${DEBUG_CONSTRAINTS || DEBUG_FORMAL_VERDICT || DEBUG_REPRODUCING_MODEL ?
47+
`<debug_context>
48+
This plan was routed through /nf:debug before execution...
49+
</debug_context>` : ''}
50+
```
51+
52+
Same template as quick.md lines 877-886.
53+
54+
### Task 4: Sync to installed copy
55+
56+
```bash
57+
cp core/workflows/execute-phase.md ~/.claude/nf/workflows/execute-phase.md
58+
```
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Verification: Quick Task 362
2+
3+
## Must-Haves
4+
5+
| # | Requirement | Status | Evidence |
6+
|---|---|---|---|
7+
| 1 | Per-plan Haiku task classification before executor spawn | PASS | Step 1.5a at line 108 — Haiku classifies plan objective as bug_fix/feature/refactor |
8+
| 2 | Debug routing for bug_fix plans (confidence >= 0.7) | PASS | Step 1.5b at line 145 — spawns /nf:debug before executor |
9+
| 3 | debug_context block injected into executor prompt | PASS | Lines 253-262 — conditional block with constraints, verdict, reproducing model |
10+
| 4 | Fail-open on all new logic | PASS | Line 139 (classification fallback), line 148 (debug vars null on skip), line 185 (debug error → null + continue) |
11+
| 5 | Sync repo source → installed copy | PASS | `cp core/workflows/execute-phase.md ~/.claude/nf/workflows/execute-phase.md` — verified via diff |
12+
13+
## Pattern Match with quick.md
14+
15+
| Element | quick.md | execute-phase.md | Match |
16+
|---|---|---|---|
17+
| Classification | Step 2.7 sub-step 1.5 | Step 1.5a | Yes — same Haiku prompt, same JSON schema |
18+
| Debug routing | Step 5.8 | Step 1.5b | Yes — same skip condition, same /nf:debug prompt |
19+
| Debug context injection | Lines 877-886 | Lines 253-262 | Yes — same template |
20+
| Fail-open | Fallback to feature/0.0 | Fallback to feature/0.0 | Yes |
21+
22+
## Status: Verified
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"nf/quick-362-wire-debug-routing-into-execute-phase-md": {
3+
"task_id": 362,
4+
"task_description": "Wire debug routing (Loop 1 + task classification + autoresearch-refine + debug_context injection) into execute-phase.md — matching the quick.md Step 5.8 pattern",
5+
"approach": "Add phase-level task classification and debug routing to execute-phase.md's plan execution loop, dispatching bug-fix phases through /nf:debug before execution and injecting formal constraints into executor prompts, matching the quick.md Step 5.8 pattern.",
6+
"out_of_scope": [
7+
"Rewriting the /nf:debug skill itself — only phase-level routing and constraint injection are in scope",
8+
"Cross-phase bug-fix dependencies — phase classification is per-plan, not per-milestone",
9+
"Modifying quick.md — only execute-phase.md is in scope"
10+
],
11+
"classification": {
12+
"type": "feature",
13+
"confidence": 0.85,
14+
"routed_through_debug": false
15+
},
16+
"risk_level": "high",
17+
"risk_reason": "Workflow file modification (execute-phase.md) — guardrail-protected",
18+
"branches_affected": ["nf/quick-362-wire-debug-routing-into-execute-phase-md"],
19+
"created_at": "2026-03-27T12:46:04.416Z",
20+
"planner_model": "inherit",
21+
"created_by": "quick-orchestrator"
22+
}
23+
}
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
task_id: 363
3+
description: "Push Loop 2 and debug_context into execute-plan.md Pattern A spawn prompt"
4+
formal_artifacts: none
5+
---
6+
7+
# Plan: Push Loop 2 + debug_context into Pattern A
8+
9+
## Objective
10+
11+
Expand the Pattern A spawn prompt in `execute-plan.md` to include `<formal_coverage_auto_detection>` (Loop 2) and `<debug_context>` blocks, so the nested child nf-executor inherits both verification loops when committing.
12+
13+
## Must-Haves
14+
15+
1. Pattern A spawn prompt includes `<formal_coverage_auto_detection>` block with Loop 2 (solution-simulation-loop)
16+
2. Pattern A spawn prompt includes conditional `<debug_context>` passthrough from parent context
17+
3. Pattern B confirmed safe (orchestrator commits, not subagent) — no changes needed
18+
4. Fail-open preserved on all new blocks
19+
5. Sync repo source → installed copy
20+
21+
## Analysis
22+
23+
- **Pattern A** (line 121): Currently a one-liner prose description. Expand to include formal blocks in the prompt specification.
24+
- **Pattern B** (line 123): Segment subagents do NOT commit — orchestrator (main context) commits. Orchestrator has Loop 2. **No change needed.**
25+
- **Pattern C** (line 125): Executes in main context. Has Loop 2. **No change needed.**
26+
- **Pattern D** (lines 130+): Worktree executors with minimal prompts. Opt-in only (--parallel flag). **Defer to separate task.**
27+
28+
## Tasks
29+
30+
### Task 1: Expand Pattern A spawn description to include formal blocks
31+
32+
Replace the Pattern A one-liner at line 121 with an expanded prompt specification that includes:
33+
1. The existing instructions (execute plan, autonomous, all tasks, SUMMARY, commit, deviation/auth rules)
34+
2. `<formal_coverage_auto_detection>` block (same as execute-phase.md lines 217-251)
35+
3. `<debug_context>` passthrough: `${PARENT_DEBUG_CONTEXT || ''}` — the parent executor passes any debug_context it received from the orchestrator
36+
37+
Note: The parent nf-executor (spawned by execute-phase.md) receives `$DEBUG_CONSTRAINTS`, `$DEBUG_FORMAL_VERDICT`, `$DEBUG_REPRODUCING_MODEL` from the orchestrator's debug routing. When spawning the Pattern A child, the parent must forward these as a `<debug_context>` block in the child's prompt.
38+
39+
### Task 2: Sync to installed copy
40+
41+
```bash
42+
cp core/workflows/execute-plan.md ~/.claude/nf/workflows/execute-plan.md
43+
```
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Verification: Quick Task 363
2+
3+
## Must-Haves
4+
5+
| # | Requirement | Status | Evidence |
6+
|---|---|---|---|
7+
| 1 | Pattern A includes formal_coverage_auto_detection (Loop 2) | PASS | Lines 132-154 — full block with simulateSolutionLoop, gates, fail-open |
8+
| 2 | Pattern A includes debug_context passthrough | PASS | Line 156 — `${PARENT_DEBUG_CONTEXT || ''}` + line 161 passthrough docs |
9+
| 3 | Pattern B confirmed safe (orchestrator commits) | PASS | Line 123 — "Autonomous segments: NO SUMMARY/commit", orchestrator does final commit |
10+
| 4 | Fail-open preserved | PASS | Lines 140, 152, 153 — skip silently on errors/missing modules |
11+
| 5 | Sync repo → installed copy | PASS | `cp` verified via diff |
12+
13+
## End-to-End Trace
14+
15+
```
16+
User runs /nf:execute-phase
17+
→ execute-phase.md Step 1.5: Classify plan → route bug_fix through /nf:debug (Loop 1)
18+
→ execute-phase.md Step 2: Spawn nf-executor with <formal_coverage_auto_detection> + <debug_context>
19+
→ nf-executor reads execute-plan.md
20+
→ Pattern C: executes in main context → has Loop 2 + debug_context ✓
21+
→ Pattern A: spawns child nf-executor with Loop 2 + debug_context passthrough ✓ (NEW)
22+
→ Pattern B: segment subagents don't commit, orchestrator commits with Loop 2 ✓
23+
→ Pattern D: worktree executors — no loops (opt-in only, deferred)
24+
```
25+
26+
## Status: Verified
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"nf/quick-362-wire-debug-routing-into-execute-phase-md": {
3+
"task_id": 363,
4+
"task_description": "Push Loop 2 (formal_coverage_auto_detection + solution-simulation-loop) and debug_context into execute-plan.md Pattern A spawn prompt",
5+
"approach": "Inject formal_coverage_auto_detection, solution-simulation-loop, and debug_context constraint blocks into the Pattern A nf-executor spawn prompt in execute-plan.md so nested child executors inherit both verification loops.",
6+
"out_of_scope": [
7+
"Implementation of Loop modules (already exist)",
8+
"Changes to Pattern B, C, or D routing",
9+
"Loop 1 debug routing integration (already handled at orchestrator level)"
10+
],
11+
"classification": {
12+
"type": "feature",
13+
"confidence": 0.85,
14+
"routed_through_debug": false
15+
},
16+
"risk_level": "high",
17+
"risk_reason": "Workflow file modification (execute-plan.md) — guardrail-protected",
18+
"branches_affected": ["nf/quick-362-wire-debug-routing-into-execute-phase-md"],
19+
"created_at": "2026-03-27T13:46:18.360Z",
20+
"planner_model": "inherit",
21+
"created_by": "quick-orchestrator"
22+
}
23+
}

core/workflows/execute-phase.md

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,89 @@ node ~/.claude/nf/bin/gsd-tools.cjs activity-set \
101101
- Bad: "Executing terrain generation plan"
102102
- Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."
103103

104+
1.5. **Classify plan type and debug routing (ROUTE-02, ROUTE-03):**
105+
106+
For each plan, classify its objective and optionally route through `/nf:debug` before execution.
107+
108+
**1.5a. Classify plan type via Haiku subagent:**
109+
110+
Spawn a Haiku subagent to classify the plan's objective:
111+
112+
```
113+
Task(
114+
subagent_type="general-purpose",
115+
model="haiku",
116+
description="Classify plan type for debug routing",
117+
prompt="
118+
You are classifying a development plan into exactly one category.
119+
120+
## Plan Objective
121+
{plan_objective_text from <objective> tag}
122+
123+
## Categories
124+
- bug_fix: The plan fixes a bug, error, regression, crash, or broken behavior.
125+
- feature: The plan adds new functionality or capability.
126+
- refactor: The plan reorganizes, renames, cleans up, or simplifies existing code without changing behavior.
127+
128+
Respond with ONLY a JSON object:
129+
{
130+
\"type\": \"bug_fix\" | \"feature\" | \"refactor\",
131+
\"confidence\": 0.0-1.0
132+
}
133+
"
134+
)
135+
```
136+
137+
Parse response as JSON. Store as `$PLAN_CLASSIFICATION`.
138+
139+
**Fail-open:** If Haiku is unavailable or JSON parse fails, use `{ "type": "feature", "confidence": 0.0 }`.
140+
141+
Log: `"Plan classification: ${PLAN_CLASSIFICATION.type} (confidence: ${PLAN_CLASSIFICATION.confidence})"`
142+
143+
**1.5b. Debug routing:**
144+
145+
**Skip if:** `$PLAN_CLASSIFICATION.type` is NOT `bug_fix`, OR `$PLAN_CLASSIFICATION.confidence` < 0.7.
146+
147+
If skipped, log: `"Debug routing: skipped (type: ${PLAN_CLASSIFICATION.type}, confidence: ${PLAN_CLASSIFICATION.confidence})"`
148+
Set `$DEBUG_CONSTRAINTS = null`, `$DEBUG_FORMAL_VERDICT = null`, `$DEBUG_REPRODUCING_MODEL = null`.
149+
150+
**If routing:**
151+
152+
1. Log: `"Debug routing: bug_fix detected (confidence: ${PLAN_CLASSIFICATION.confidence}) — routing through /nf:debug"`
153+
154+
2. Spawn `/nf:debug` as a Task subagent:
155+
156+
```
157+
Task(
158+
prompt="
159+
Run /nf:debug with the following failure context.
160+
161+
## Plan Objective (from phase plan)
162+
{plan_objective_text}
163+
164+
## Instructions
165+
- Run the full debug pipeline (Steps A through A.8: collect context, discovery, reproduction, refinement, constraint extraction)
166+
- Return the debug output including:
167+
- \$CONSTRAINTS (extracted constraints from Loop 1, if any)
168+
- \$FORMAL_VERDICT (pass/fail/skip from formal model checking, if any)
169+
- \$REPRODUCING_MODEL (path to reproducing formal model, if any)
170+
- If any step fails or produces no output, continue with remaining steps (fail-open)
171+
- Do NOT fix the bug — only diagnose and extract constraints. The executor will apply the fix.
172+
",
173+
subagent_type="general-purpose",
174+
description="Debug routing for plan {plan_number}: {plan_objective_summary}"
175+
)
176+
```
177+
178+
3. Parse debug output. Extract and store:
179+
- `$DEBUG_CONSTRAINTS` — constraints from Loop 1 refinement (may be empty)
180+
- `$DEBUG_FORMAL_VERDICT` — formal model check result (may be "skipped")
181+
- `$DEBUG_REPRODUCING_MODEL` — path to reproducing model (may be null)
182+
183+
4. Log: `"Debug routing complete. Constraints: ${DEBUG_CONSTRAINTS ? 'found' : 'none'}, Verdict: ${DEBUG_FORMAL_VERDICT || 'skipped'}"`
184+
185+
**Fail-open:** If the debug subagent errors or times out, log a warning and proceed without debug context. Set all debug vars to null.
186+
104187
2. **Spawn executor agents:**
105188

106189
Pass paths only — executors read files themselves with their fresh 200k context.
@@ -167,6 +250,17 @@ node ~/.claude/nf/bin/gsd-tools.cjs activity-set \
167250
6. If step 2 found NO intersections: skip Loop 2 entirely (GATE-03) — silent, no log
168251
</formal_coverage_auto_detection>
169252
253+
${DEBUG_CONSTRAINTS || DEBUG_FORMAL_VERDICT || DEBUG_REPRODUCING_MODEL ?
254+
`<debug_context>
255+
This plan was routed through /nf:debug before execution. Use the following debug output as supplementary context for your implementation:
256+
257+
${DEBUG_CONSTRAINTS ? '**Constraints from formal model refinement:**\n' + DEBUG_CONSTRAINTS : ''}
258+
${DEBUG_FORMAL_VERDICT ? '**Formal verdict:** ' + DEBUG_FORMAL_VERDICT : ''}
259+
${DEBUG_REPRODUCING_MODEL ? '**Reproducing model:** ' + DEBUG_REPRODUCING_MODEL : ''}
260+
261+
These constraints inform the fix but do not gate it. If constraints conflict with the plan, follow the plan.
262+
</debug_context>` : ''}
263+
170264
<success_criteria>
171265
- [ ] All tasks executed
172266
- [ ] Each task committed individually

0 commit comments

Comments
 (0)