@sebastianandreasson/pi-autonomous-agents 0.9.1 → 0.11.0

package/README.md

@@ -89,6 +89,7 @@ pi-harness report
 pi-harness clear-history
 pi-harness visual-once
 pi-harness visualize
+pi-harness debug-live
 pi-harness visual-review-worker
 ```
 
@@ -319,4 +320,35 @@ npm run check
 npm test
 ```
 
+For local visualizer iteration against fake live SDK agent:
+
+```bash
+npm run debug:live-ui
+```
+
+Scenario variants:
+
+```bash
+node src/cli.mjs debug-live --reset --scenario noisy --task-count 24
+node src/cli.mjs debug-live --reset --scenario retry
+```
+
+For React/Vite visualizer UI dev loop:
+
+```bash
+npm run dev:visualizer:ui
+```
+
+For production visualizer UI build:
+
+```bash
+npm run build:visualizer:ui
+```
+
+Publish now auto-runs check, tests, and UI build via `prepublishOnly`.
+
+This seeds `.pi-debug/live-ui/`, runs harness there with streaming fake SDK fixture, hosts visualizer, and gives stable local repro loop for UI work. React app lives in `visualizer-ui/`. Visualizer server now serves built assets from `visualizer-ui/dist/` and falls back to build-instructions page if build artifacts are missing.
+
+See `docs/VISUALIZER_UI_PLAN.md` for migration plan.
+
 The package requires Node `>=20`.

package/docs/PI_SUPERVISOR.md

@@ -35,8 +35,10 @@ Main package files:
 - `src/pi-prompts.mjs`: default prompt builders
 - `src/pi-visual-review.mjs`: multimodal visual-review worker
 - `src/pi-visual-once.mjs`: one-shot manual visual review runner
-- `src/pi-visualizer.mjs`: local web UI for orchestration flow and active stage
+- `src/pi-visualizer.mjs`: local web UI entrypoint
+- `src/pi-visualizer-server.mjs`: shared visualizer server/runtime
 - `src/pi-visualizer-shared.mjs`: flow-state helpers for visualizer
+- `src/pi-debug-live.mjs`: local fake-live sandbox runner for visualizer debugging
 - `src/pi-report.mjs`: telemetry summary report
 - `templates/DEVELOPER.md`: default developer-role instructions template
 - `templates/TESTER.md`: default tester-role instructions template
@@ -49,6 +51,7 @@ pi-harness run
 pi-harness report
 pi-harness visual-once
 pi-harness visualize
+pi-harness debug-live
 ```
 
 The package reads `PI_CONFIG_FILE` if provided. Otherwise it falls back to the bundled generic `pi.config.json`.
@@ -59,6 +62,8 @@ The package reads `PI_CONFIG_FILE` if provided. Otherwise it falls back to the b
 
 Visualizer reads active-run lock, TODO file, per-run state, per-run iteration summary, per-run last output snapshot, live feed JSONL, and telemetry to show current stage plus historical runs.
 
+For local UI iteration in this package repo, use `pi-harness debug-live` to run against seeded fake live SDK sandbox. Useful variants: `--scenario noisy`, `--scenario retry`, `--task-count 24`.
+
 ## Config Contract
 
 Projects typically provide their own `pi.config.json` with fields such as:

package/docs/VISUALIZER_UI_PLAN.md

@@ -0,0 +1,117 @@
+# Visualizer UI migration plan
+
+## Goal
+
+Replace inline browser JS/HTML in `src/pi-visualizer-server.mjs` with maintainable React frontend, while keeping Node visualizer server as API + SSE + static asset host.
+
+## Chosen stack
+
+- React
+- Vite
+- TypeScript
+- Zustand
+- Plain CSS
+
+## Repo layout
+
+```text
+src/
+  pi-visualizer-server.mjs   # API, SSE, static asset host
+visualizer-ui/
+  package.json
+  tsconfig.json
+  vite.config.ts
+  index.html
+  src/
+    main.tsx
+    App.tsx
+    api.ts
+    store.ts
+    types.ts
+    styles.css
+    components/
+      TodoList.tsx
+      FlowStrip.tsx
+      LiveFeed.tsx
+      CurrentEdits.tsx
+      DiagnosticsPanel.tsx
+```
+
+## State model
+
+Zustand store owns:
+
+- latest snapshot
+- selected run
+- selected todo
+- selected event
+- feed toggles
+- SSE lifecycle
+- initial load status / error
+
+## API contract
+
+Current server routes:
+
+- `GET /api/state` → full snapshot
+- `GET /api/stream` → SSE full snapshots
+
+Short term: React app consumes current full-snapshot SSE.
+
+Next improvement:
+
+- add monotonic `seq` to live feed entries
+- optionally move SSE from full snapshots to patch events
+- add snapshot version to ignore stale payloads
+
+## Migration phases
+
+### Phase 1
+- scaffold `visualizer-ui/`
+- keep current inline HTML as fallback
+- add built asset serving from `visualizer-ui/dist`
+- add `/api/state` alias
+
+### Phase 2
+- port current layout into React components
+- use Zustand store + initial snapshot fetch
+- use SSE reconnect from frontend
+
+### Phase 3
+- move feed/timeline ordering to stable `seq`
+- reduce full rerenders
+- preserve scroll behavior inside components
+
+### Phase 4
+- remove inline browser app from server once built UI covers current features
+- keep server only as API/static host
+
+## Dev workflow
+
+Backend + fake live harness:
+
+```bash
+npm run debug:live-ui
+```
+
+Frontend dev server:
+
+```bash
+npm run dev:visualizer:ui
+```
+
+Frontend build:
+
+```bash
+npm run build:visualizer:ui
+```
+
+## Notes
+
+Current state:
+
+- React/Vite/Zustand UI scaffold added
+- built assets generated under `visualizer-ui/dist/`
+- server serves built UI directly
+- legacy inline browser app removed
+- fallback page only shows build instructions when dist missing

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sebastianandreasson/pi-autonomous-agents",
   "private": false,
-  "version": "0.9.1",
+  "version": "0.11.0",
   "type": "module",
   "description": "Portable unattended PI harness for developer/tester/visual-review loops.",
   "license": "MIT",
@@ -19,13 +19,18 @@
     "@mariozechner/pi-coding-agent": "^0.66.1"
   },
   "scripts": {
-    "check": "node --check src/cli.mjs && node --check src/pi-clear-history.mjs && node --check src/pi-client.mjs && node --check src/pi-config.mjs && node --check src/pi-flow.mjs && node --check src/pi-heartbeat.mjs && node --check src/pi-history.mjs && node --check src/pi-preflight.mjs && node --check src/pi-prompts.mjs && node --check src/pi-repo.mjs && node --check src/pi-report.mjs && node --check src/pi-sdk-turn.mjs && node --check src/pi-supervisor.mjs && node --check src/pi-telemetry.mjs && node --check src/pi-visual-once.mjs && node --check src/pi-visual-review.mjs && node --check src/pi-visualizer.mjs && node --check src/pi-visualizer-server.mjs && node --check src/pi-visualizer-shared.mjs && node --check src/index.mjs && node --check test/pi-heartbeat.test.mjs && node --check test/pi-lifecycle.test.mjs && node --check test/pi-role-models.test.mjs && node --check test/pi-flow.test.mjs && node --check test/pi-history.test.mjs && node --check test/pi-prompts.test.mjs && node --check test/pi-preflight.test.mjs && node --check test/pi-repo.test.mjs && node --check test/pi-sdk-supervisor.test.mjs && node --check test/pi-sdk-turn.test.mjs && node --check test/pi-telemetry.test.mjs && node --check test/pi-visualizer-shared.test.mjs && node --check test/fixtures/fake-pi.mjs && node --check test/fixtures/fake-pi-sdk.mjs",
-    "test": "node --test test/pi-heartbeat.test.mjs test/pi-lifecycle.test.mjs test/pi-role-models.test.mjs test/pi-flow.test.mjs test/pi-history.test.mjs test/pi-prompts.test.mjs test/pi-preflight.test.mjs test/pi-repo.test.mjs test/pi-sdk-supervisor.test.mjs test/pi-sdk-turn.test.mjs test/pi-telemetry.test.mjs test/pi-visualizer-shared.test.mjs"
+    "check": "node --check src/cli.mjs && node --check src/pi-clear-history.mjs && node --check src/pi-client.mjs && node --check src/pi-config.mjs && node --check src/pi-debug-live.mjs && node --check src/pi-flow.mjs && node --check src/pi-heartbeat.mjs && node --check src/pi-history.mjs && node --check src/pi-preflight.mjs && node --check src/pi-prompts.mjs && node --check src/pi-repo.mjs && node --check src/pi-report.mjs && node --check src/pi-sdk-turn.mjs && node --check src/pi-supervisor.mjs && node --check src/pi-telemetry.mjs && node --check src/pi-visual-once.mjs && node --check src/pi-visual-review.mjs && node --check src/pi-visualizer.mjs && node --check src/pi-visualizer-server.mjs && node --check src/pi-visualizer-shared.mjs && node --check src/index.mjs && node --check test/pi-heartbeat.test.mjs && node --check test/pi-lifecycle.test.mjs && node --check test/pi-role-models.test.mjs && node --check test/pi-flow.test.mjs && node --check test/pi-history.test.mjs && node --check test/pi-prompts.test.mjs && node --check test/pi-preflight.test.mjs && node --check test/pi-repo.test.mjs && node --check test/pi-sdk-supervisor.test.mjs && node --check test/pi-sdk-turn.test.mjs && node --check test/pi-telemetry.test.mjs && node --check test/pi-visualizer-shared.test.mjs && node --check test/fixtures/fake-pi.mjs && node --check test/fixtures/fake-pi-sdk.mjs && node --check test/fixtures/fake-live-pi-sdk.mjs",
+    "test": "node --test test/pi-heartbeat.test.mjs test/pi-lifecycle.test.mjs test/pi-role-models.test.mjs test/pi-flow.test.mjs test/pi-history.test.mjs test/pi-prompts.test.mjs test/pi-preflight.test.mjs test/pi-repo.test.mjs test/pi-sdk-supervisor.test.mjs test/pi-sdk-turn.test.mjs test/pi-telemetry.test.mjs test/pi-visualizer-shared.test.mjs",
+    "debug:live-ui": "node src/cli.mjs debug-live --reset",
+    "dev:visualizer:ui": "npm --prefix visualizer-ui run dev",
+    "build:visualizer:ui": "npm --prefix visualizer-ui run build",
+    "prepublishOnly": "npm run check && npm test && npm run build:visualizer:ui"
   },
   "files": [
     "src",
     "templates",
     "docs",
+    "visualizer-ui/dist",
     "pi.config.json",
     "SETUP.md",
     "README.md"

package/src/cli.mjs

@@ -19,6 +19,7 @@ const COMMANDS = new Map([
   ['clear-history', 'pi-clear-history.mjs'],
   ['visual-once', 'pi-visual-once.mjs'],
   ['visualize', 'pi-visualizer.mjs'],
+  ['debug-live', 'pi-debug-live.mjs'],
   ['visual-review-worker', 'pi-visual-review.mjs'],
 ])
 

package/src/pi-client.mjs

@@ -3,6 +3,9 @@ import path from 'node:path'
 import { randomUUID } from 'node:crypto'
 
 const liveFeedWriteQueues = new Map()
+const liveFeedSequences = new Map()
+const MAX_LIVE_FEED_TEXT = 2000
+const MAX_LIVE_FEED_SUMMARY = 600
 import {
   appendLog,
   writeTextFile,
@@ -41,6 +44,63 @@ async function writeAgentOutputSnapshot(config, content) {
   }
 }
 
+function truncateText(value, maxChars) {
+  const text = String(value ?? '')
+  if (text.length <= maxChars) {
+    return text
+  }
+  return `${text.slice(0, maxChars - 16)}\n... [truncated]`
+}
+
+function summarizeValue(value, maxChars = MAX_LIVE_FEED_SUMMARY) {
+  if (value === null || value === undefined) {
+    return ''
+  }
+  if (typeof value === 'string') {
+    return truncateText(value, maxChars)
+  }
+  try {
+    return truncateText(JSON.stringify(value), maxChars)
+  } catch {
+    return truncateText(String(value), maxChars)
+  }
+}
+
+function sanitizeLiveFeedEvent(filePath, event) {
+  const nextSeq = (liveFeedSequences.get(filePath) ?? 0) + 1
+  liveFeedSequences.set(filePath, nextSeq)
+
+  const normalized = {
+    seq: nextSeq,
+    timestamp: String(event?.timestamp ?? new Date().toISOString()),
+    iteration: Number(event?.iteration ?? 0),
+    retryCount: Number(event?.retryCount ?? 0),
+    reason: String(event?.reason ?? ''),
+    phase: String(event?.phase ?? ''),
+    role: String(event?.role ?? ''),
+    kind: String(event?.kind ?? ''),
+    type: String(event?.type ?? 'event'),
+    toolName: String(event?.toolName ?? ''),
+    isError: event?.isError === true,
+    text: truncateText(event?.text ?? '', MAX_LIVE_FEED_TEXT),
+  }
+
+  const argsSummary = summarizeValue(event?.args)
+  const partialSummary = summarizeValue(event?.partialResult)
+  const resultSummary = summarizeValue(event?.result)
+  if (argsSummary !== '') {
+    normalized.argsSummary = argsSummary
+  }
+  if (partialSummary !== '') {
+    normalized.partialSummary = partialSummary
+  }
+  if (resultSummary !== '') {
+    normalized.resultSummary = resultSummary
+  }
+
+  return normalized
+}
+
 async function appendLiveFeedEvent(config, event) {
   if (!config.runLiveFeedFile) {
     return
@@ -51,8 +111,9 @@ async function appendLiveFeedEvent(config, event) {
   const next = previous
     .catch(() => {})
     .then(async () => {
+      const sanitized = sanitizeLiveFeedEvent(filePath, event)
       await fs.mkdir(path.dirname(filePath), { recursive: true })
-      await fs.appendFile(filePath, `${JSON.stringify(event)}\n`, 'utf8')
+      await fs.appendFile(filePath, `${JSON.stringify(sanitized)}\n`, 'utf8')
     })
 
   liveFeedWriteQueues.set(filePath, next)

package/src/pi-debug-live.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+import { spawn, execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const packageRoot = path.resolve(scriptDir, '..')
+const cliFile = path.join(scriptDir, 'cli.mjs')
+const fakePiFile = path.join(packageRoot, 'test', 'fixtures', 'fake-pi.mjs')
+const fakeLiveSdkFile = path.join(packageRoot, 'test', 'fixtures', 'fake-live-pi-sdk.mjs')
+const sandboxDir = path.join(packageRoot, '.pi-debug', 'live-ui')
+const DEFAULT_TASK_COUNT = 12
+
+function shellQuote(value) {
+  return JSON.stringify(String(value))
+}
+
+function readFlagValue(flag) {
+  const index = process.argv.indexOf(flag)
+  if (index === -1) {
+    return ''
+  }
+  return String(process.argv[index + 1] ?? '').trim()
+}
+
+function readScenario() {
+  const value = readFlagValue('--scenario') || process.env.PI_FAKE_LIVE_SCENARIO || 'default'
+  return String(value).trim() || 'default'
+}
+
+function readTaskCount() {
+  const raw = Number.parseInt(readFlagValue('--task-count') || process.env.PI_DEBUG_TASK_COUNT || `${DEFAULT_TASK_COUNT}`, 10)
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TASK_COUNT
+}
+
+function buildTodoLines(taskCount) {
+  const lines = []
+  for (let index = 1; index <= taskCount; index += 1) {
+    const phase = index <= Math.ceil(taskCount / 3)
+      ? 'Phase 1'
+      : index <= Math.ceil((taskCount * 2) / 3)
+        ? 'Phase 2'
+        : 'Phase 3'
+    const label = `Fake live task ${index}`
+    if (lines.length === 0 || lines[lines.length - 1] !== `## ${phase}`) {
+      if (lines.length > 0) {
+        lines.push('')
+      }
+      lines.push(`## ${phase}`)
+      lines.push('')
+    }
+    lines.push(`- [ ] ${label}`)
+  }
+  return `${lines.join('\n')}\n`
+}
+
+async function ensureRepo(cwd) {
+  try {
+    execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd, stdio: 'ignore' })
+  } catch {
+    execFileSync('git', ['init'], { cwd, stdio: 'ignore' })
+    execFileSync('git', ['config', 'user.name', 'PI Harness Debug'], { cwd, stdio: 'ignore' })
+    execFileSync('git', ['config', 'user.email', 'pi-harness-debug@example.com'], { cwd, stdio: 'ignore' })
+  }
+}
+
+async function seedFiles(cwd, { taskCount, scenario }) {
+  await fs.mkdir(path.join(cwd, 'pi'), { recursive: true })
+  await fs.writeFile(path.join(cwd, 'TODOS.md'), buildTodoLines(taskCount), 'utf8')
+  await fs.writeFile(path.join(cwd, 'DEVELOPER.md'), `Developer instructions for local visualizer debugging.\nScenario: ${scenario}\n`, 'utf8')
+  await fs.writeFile(path.join(cwd, 'TESTER.md'), `Tester instructions for local visualizer debugging.\nScenario: ${scenario}\n`, 'utf8')
+  await fs.writeFile(path.join(cwd, 'pi.config.json'), `${JSON.stringify({
+    transport: 'sdk',
+    taskFile: 'TODOS.md',
+    developerInstructionsFile: 'DEVELOPER.md',
+    testerInstructionsFile: 'TESTER.md',
+    piCli: fakePiFile,
+    piModel: 'fake-model',
+    roleModels: {
+      developer: 'fake-model',
+      developerRetry: 'fake-model',
+      developerFix: 'fake-model',
+      tester: 'fake-model',
+      testerCommit: 'fake-model',
+    },
+    testCommand: `${shellQuote(process.execPath)} -e ${shellQuote('setTimeout(()=>process.exit(0), 250)')}`,
+    streamTerminal: true,
+    continueAfterSeconds: 3600,
+    noEventTimeoutSeconds: 3600,
+    toolContinueAfterSeconds: 3600,
+    toolNoEventTimeoutSeconds: 3600,
+    sleepBetweenSeconds: 1,
+    maxIterations: Math.max(taskCount * 3, 20),
+  }, null, 2)}\n`, 'utf8')
+}
+
+async function ensureInitialCommit(cwd) {
+  try {
+    execFileSync('git', ['rev-parse', 'HEAD'], { cwd, stdio: 'ignore' })
+  } catch {
+    execFileSync('git', ['add', '.'], { cwd, stdio: 'ignore' })
+    execFileSync('git', ['commit', '-m', 'chore(debug): seed fake live sandbox'], { cwd, stdio: 'ignore' })
+  }
+}
+
+async function main() {
+  const reset = process.argv.includes('--reset')
+  const scenario = readScenario()
+  const taskCount = readTaskCount()
+
+  if (reset) {
+    await fs.rm(sandboxDir, { recursive: true, force: true })
+  }
+
+  await fs.mkdir(sandboxDir, { recursive: true })
+  await ensureRepo(sandboxDir)
+  await seedFiles(sandboxDir, { taskCount, scenario })
+  await ensureInitialCommit(sandboxDir)
+
+  process.stdout.write(`PI debug sandbox: ${sandboxDir}\n`)
+  process.stdout.write(`Using fake live SDK fixture: ${fakeLiveSdkFile}\n`)
+  process.stdout.write(`Scenario: ${scenario}\n`)
+  process.stdout.write(`Task count: ${taskCount}\n`)
+
+  const child = spawn(process.execPath, [cliFile, 'run'], {
+    cwd: sandboxDir,
+    env: {
+      ...process.env,
+      PI_CONFIG_FILE: 'pi.config.json',
+      PI_SDK_MODULE: fakeLiveSdkFile,
+      PI_FAKE_LIVE_SCENARIO: scenario,
+      PI_VISUALIZER_HOST: process.env.PI_VISUALIZER_HOST || '127.0.0.1',
+      PI_VISUALIZER_PORT: process.env.PI_VISUALIZER_PORT || '4317',
+    },
+    stdio: 'inherit',
+  })
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.exitCode = 128
+      return
+    }
+    process.exitCode = code ?? 1
+  })
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.stack ?? error.message : String(error))
+  process.exitCode = 1
+})

package/src/pi-prompts.mjs

@@ -119,6 +119,36 @@ function repoInstructionsAuthorityLine(config, instructionsFile, usesBundledInst
   return `Repo-local instructions in ${displayPath(config, instructionsFile)} are the primary role contract. Follow them over package defaults when they differ.\n`
 }
 
+export function classifyTaskType(task) {
+  const text = String(task ?? '').trim().toLowerCase()
+  if (text === '') {
+    return 'general'
+  }
+
+  if (
+    /\b(write|add|create|implement|expand|improve|fix|update)\b.*\b(test|tests|coverage|regression test|spec|specs)\b/.test(text)
+    || /\b(test|tests|coverage|regression test|spec|specs)\b.*\b(write|add|create|implement|expand|improve|fix|update)\b/.test(text)
+  ) {
+    return 'test'
+  }
+
+  return 'general'
+}
+
+function formatTaskTypeGuidance(taskType) {
+  if (taskType !== 'test') {
+    return ''
+  }
+
+  return [
+    'Test-task guidance:',
+    '- This TODO is primarily test-focused. Do not fail solely because changes are mostly or entirely tests.',
+    '- PASS if the new or updated test adds meaningful behavioral or regression coverage and verification passes.',
+    '- FAIL if the test is brittle, redundant, weakly asserted, or not tied to real behavior.',
+    '- Prefer checking whether the test would have failed before the change, or whether developer notes justify why missing coverage mattered.',
+  ].join('\n')
+}
+
 function testerPassOwnershipRules(config) {
   if (config.commitMode === 'plan') {
     return {
@@ -353,6 +383,9 @@ export function buildTesterPrompt(config, {
     developerNotes || '(none provided)',
     configMaxLines(config, 'maxPromptNotesLines', 16),
   )
+  const taskType = classifyTaskType(task)
+  const taskTypeLabel = taskType === 'test' ? 'test-focused' : 'general'
+  const taskTypeGuidance = formatTaskTypeGuidance(taskType)
   const verificationCommand = config.testCommand.trim() === '' ? '(not configured)' : config.testCommand
   const visualCaptureNote = config.visualReviewEnabled
     ? `\n- Keep the screenshot capture flow working so the harness still produces current visual artifacts for review.`
@@ -364,6 +397,7 @@ export function buildTesterPrompt(config, {
   )
   const passOwnership = testerPassOwnershipRules(config)
   const largeFileRiskHint = formatLargeFileRiskHint(largeFileWarnings)
+  const taskTypeRuleBlock = taskTypeGuidance === '' ? '' : `${taskTypeGuidance}\n`
 
   if (!config.usingBundledTesterInstructions) {
     return `Read ${taskFile} and ${instructionsFile}.
@@ -375,6 +409,7 @@ You are the TESTER role. You are reviewing the most recent developer work from a
 
 Current phase: ${phase}
 Current task: ${task}
+Current task type: ${taskTypeLabel}
 Reason for this tester pass: ${reason}
 
 Developer notes:
@@ -391,7 +426,7 @@ Rules:
 - If a snippet seems incomplete, reread a smaller exact window with read instead of another large overlapping shell range.
 - If blocked or inconclusive, return VERDICT: BLOCKED.
 - Do not hide real bugs with brittle tests.
-- ${passOwnership.successRule.slice(2)}
+${taskTypeRuleBlock}- ${passOwnership.successRule.slice(2)}
 - ${passOwnership.isolationRule.slice(2)}
 - ${passOwnership.extraRule.slice(2)}${visualCaptureNote}
 
@@ -417,6 +452,7 @@ You are the TESTER role. You are reviewing the most recent developer work from a
 
 Current phase: ${phase}
 Current task: ${task}
+Current task type: ${taskTypeLabel}
 Reason for this tester pass: ${reason}
 
 Developer notes:
@@ -433,7 +469,7 @@ ${indentBlock(innerLoopValidationRules(verificationCommand), '\t')}
 	- Prefer one focused browser-driven review pass.
 	- If a snippet seems incomplete, reread a smaller exact window with read instead of another large overlapping shell range.
 	- Do not hide real bugs with brittle tests.
-	- If blocked or inconclusive, return VERDICT: BLOCKED.
+${taskTypeGuidance === '' ? '' : `${indentBlock(taskTypeGuidance, '\t')}\n`}	- If blocked or inconclusive, return VERDICT: BLOCKED.
 ${indentBlock(passOwnership.successRule, '\t')}
 ${indentBlock(passOwnership.isolationRule, '\t')}
 ${indentBlock(passOwnership.extraRule, '\t')}${visualCaptureNote}