@openplaybooks/converge 0.2.0

package/skills/converge-development/reference/framework-map.md

@@ -0,0 +1,294 @@
+# Framework map — where things live
+
+A subsystem→location→symptom cheat sheet for diagnosing framework bugs. Use it in step 5 of the dev loop.
+
+Repo root: `/Users/minh/Documents/converge`. All paths below are relative to root unless noted.
+
+## Monorepo layout
+
+```
+packages/
+  core/         framework engine (navigator, gap detection, journal, checkpoint, planning, …)
+  cli/          `converge` command — arg parsing, subcommands, output formatting
+  agentfn/      unified agent function — single callable across all AI providers
+  claudefn/     Claude provider — spawns `claude` CLI programmatically
+  acpfn/        ACP provider — wraps Anthropic Client Protocol SDK
+  kimifn/       Kimi provider
+  qwenfn/       Qwen provider
+  geminifn/     Gemini provider
+  openfn/       Opencode AI provider
+  navigator/    generic graph-driven state machine / convergence loop
+  codets/       code-generation utilities (fluent TS/JSX/MD emitter)
+  project-root/ canonical project-root resolver (finds nearest `.converge/`)
+  provider-benchmark/ deep journal analysis for comparing AI providers
+  swebench/     SWE-bench Lite evaluation runner
+  tbench/       terminal-bench evaluation runner
+  studio/       (reserved)
+```
+
+The CLI binary is `packages/cli/dist/index.js`. The runtime entry from the binary is `packages/cli/src/main.ts` → individual `commands-*.ts` files.
+
+## Subsystem → location → symptoms
+
+### Navigator (convergence engine)
+- **Source:** `packages/core/src/navigator/` — `core/navigator.ts`, `core/actions/`, `repair/strategies/`, `repair/agent-runner.ts`
+- **Key files:**
+  - `packages/core/src/navigator/repair/agent-runner.ts` — runs AI agents, resolves AI config, emits `AGENT_START/COMPLETE/FAILED` events
+  - `packages/core/src/navigator/repair/strategies/task-run.ts` — primary task execution strategy (builds prompt, calls `runAgent`)
+  - `packages/core/src/navigator/repair/strategies/seed-script-repair.ts` — seed script auto-repair
+  - `packages/core/src/navigator/repair/strategy-catalog.ts` — maps gap kinds to fix strategies
+- **Symptoms:**
+  - Node stuck in `buffered` / `executing` status across iterations
+  - Action phases fire out of order (preflight skipped, response duplicated)
+  - Stall detection misfires (declares stall when progress is visible, or fails to detect repeating failures)
+  - Navigate iterates without progress (gap unchanged across iterations)
+  - Per-task `agent:` field ignored — all tasks use default provider
+- **Reproduce against:** `tests/test-simple-run` (smallest), `tests/test-loop-detection` (stall), `tests/test-mixed-model` (provider routing)
+- **Watch:** stdout `🤖 AI Provider:` lines, per-task `events.jsonl`, per-attempt `logs/events.jsonl`
+
+### Task discovery & resolution (TASK.md → Unit → DAG)
+- **Source:** `packages/core/src/task/discovery/static-children.ts` (folder-scan for `\d{2,3}-` prefixed subdirectories), `packages/core/src/task/unit/factories.ts` (Unit.fromPath), `packages/core/src/task/unit/unit.ts` (Unit class)
+- **Also:** `packages/core/src/task/unit/resolve.ts` — `resolveAgent`, `resolvePrompt`, `resolveTaskAI`, `resolveSkill`
+- **Also:** `packages/core/src/task/unit/find-gaps.ts` — gap detection from Unit state; `packages/core/src/task/unit/fix-gaps.ts` — gap resolution
+- **Symptoms:**
+  - Children not discovered despite valid prefix subdirectories
+  - `ai:` block in TASK.md ignored (provider falls back to default)
+  - Sort order wrong (prefix parsing broken)
+  - Gaps double-counted or missing
+- **Reproduce against:** `tests/test-compile-discover` (child discovery), `tests/test-mixed-model` (ai: block), `tests/playbook-compile.test.ts` (compile suite)
+- **Watch:** compile output (`Compiled default: N nodes`), manifest.json `parent_map`
+
+### TASK.md parsing & schema
+- **Source:** `packages/core/src/config/task-md-definition.ts` — `parseTaskMd`, `parseTaskMdString`, `parseFrontmatterToTaskMdDef`, `mapTaskMdToTaskDefinition`, `RESERVED_KEYS`
+- **Also:** `packages/core/src/config/task-definition.ts` — `TaskDefinition` interface, `TaskAIConfig`, builder
+- **Also:** `packages/core/src/config/declarative-loader.ts` — playbook loading, `resolveTaskDef`, `loadTaskFile`
+- **Also:** `packages/core/src/task/playbook/loader.ts` — playbook check parsing and `scripts/`-path validation
+- **Symptoms:**
+  - Frontmatter field silently ignored (not in `RESERVED_KEYS`, falls through to `vars`)
+  - `ai:` block parsed but not mapped (missing from `mapTaskMdToTaskDefinition`)
+  - Legacy `type: test` or `.test.md` content still appears in a playbook and now fails hard
+- **Reproduce against:** `tests/test-mixed-model` (ai: block), `tests/playbook-compile.test.ts` (compile)
+- **Watch:** compile manifest `nodes[].agent` field, `parseTaskMdString` return shape
+
+### DAG & manifest
+- **Source:** `packages/core/src/dag/` — `dag-node.ts` (DagNode), `task-dag.ts` (TaskDag), `dag-tree.ts` (execution tree)
+- **Also:** `packages/core/src/manifest/` — `types.ts` (Manifest, ManifestNode, RunState), `writer.ts`, `reader.ts`
+- **Also:** `packages/cli/src/commands-compile.ts` — compile command, manifest/runstate writing
+- **Symptoms:**
+  - Wrong node count after compile
+  - Parent-child relationships incorrect in manifest
+  - Run fails with "No compiled manifest found"
+  - Frontier count wrong
+- **Reproduce against:** `tests/test-compile-discover`, `tests/playbook-dag.test.ts`
+- **Watch:** manifest.json (`nodes`, `parent_map`, `child_map`), runstate.json
+
+### AI config resolution
+- **Source:** `packages/core/src/ai/factory.ts` — `resolveAIConfig`, `listAIProviders`, `createAIFactory`, multi-provider config
+- **Symptoms:**
+  - `provider:` field in project.yaml ignored
+  - Multi-provider config falls back to default even when task specifies `agent:`
+  - `preferredProvider` not passed through from task metadata
+- **Reproduce against:** `tests/test-mixed-model`
+- **Watch:** stdout `🤖 AI Provider:` lines, `AI config type:`, `Providers:` debug lines
+
+### Executor (task execution within navigator)
+- **Source:** `packages/core/src/navigator/core/actions/execution/run-executor.ts`, `packages/core/src/navigator/core/actions/execution/`
+- **Symptoms:**
+  - Task spawn fails / process never starts
+  - Wrong exit code interpretation (success treated as failure or vice versa)
+  - Hangs after spawn (no event stream, no timeout)
+  - Execution skips seed-spawned children
+  - Skill symlink setup/teardown fails silently
+- **Reproduce against:** `examples/hello-world` for single-task path, any example with seed for parallel spawn
+- **Watch:** process spawn lines in stdout, per-attempt `logs/events.jsonl`
+
+### Journal
+- **Source:** `packages/core/src/journal/`
+- **Key file:** `packages/core/src/journal/structure.ts` (path layout and file-type mapping)
+- **Symptoms:**
+  - Materialized TASK.md missing or stale in journal
+  - Attempt log files not written
+  - `events.jsonl` truncated mid-write
+  - Status file (`status.json`) corrupted or stale
+  - Gap snapshot (`gaps.yml`) missing
+- **Reproduce against:** any example; `examples/hello-world` makes the file set easiest to inspect
+- **Watch:** `journal/<playbook>/tasks/<taskId>/` and `attempts/<n>/`
+
+### Checkpoint
+- **Source:** `packages/core/src/checkpoint/`
+- **Symptoms:**
+  - Resume fails after a clean kill
+  - Parent stays `seeded` while all children show complete
+  - Status flip-flops between iterations
+  - `progress.completedChildren` doesn't match disk reality
+  - Checkpoint write fails silently (partial write, missing fields)
+- **Reproduce against:** `examples/test-resume`, examples with seed children (e.g. `examples/test-seeding`)
+- **Watch:** `journal/<playbook>/runstate.json`, `journal/<playbook>/tasks/<taskId>/status.json`
+
+### Seed (dynamic child spawning)
+- **Source:** `packages/core/src/executor/seed-executor.ts` — `ctx.spawn()` implementation, script resolution, staged writes
+- **Also:** `packages/core/src/navigator/repair/strategies/seed-script-repair.ts` — auto-repair of broken seed scripts
+- **Symptoms:**
+  - Seed script runs but children don't appear in tree
+  - Children spawn but parent rollup never fires
+  - Seed spawns duplicate tasks across iterations
+  - Seed script not found (path resolution wrong)
+  - Seed repair fires on transient errors (429, 5xx)
+- **Reproduce against:** `tests/test-seeding` (basic), `tests/test-queue-pattern` (incremental do-while), `tests/test-financial-deep-research` (multi-level)
+- **Watch:** `converge list`, `journal/<playbook>/runstate.json`, and `inventory/<playbook>/tasks.jsonl`
+
+### Test infrastructure
+- **Source:** `tests/*.test.ts` (vitest, root-level integration tests), `tests/test-*/` (fixture directories), `packages/*/tests/` (per-package unit tests)
+- **Config:** `/vitest.config.ts` (root, `fileParallelism: false`), `packages/*/vitest.config.ts` (per-package)
+- **Key fixtures:**
+  - `tests/test-simple-run` — basic single-task run
+  - `tests/test-compile-discover` — compile + run separation, child discovery
+  - `tests/test-mixed-model` — multi-provider AI routing
+  - `tests/test-gap-blocked-input` — dependency backoff, input gaps
+  - `tests/test-gap-missing-output` — output gap detection
+  - `tests/test-buggy-check` — buggy check relaxation
+  - `tests/test-loop-detection` — tool-call loop detection
+  - `tests/test-multi-attempt` — multi-attempt convergence
+  - `tests/test-queue-pattern` — incremental do-while seed
+  - `tests/test-seeding` — recursive seed spawning
+  - `tests/test-financial-deep-research` — named non-default playbook
+- **Test patterns:**
+  1. **Compile tests** — `converge playbook validate <name>` or `converge run --playbook=<name> --dry`, verify structure and manifest shape
+  2. **DAG tests** — verify `depends_on`, `depended_on_by`, `child_map`, content hashes
+  3. **Integration tests** — `converge run --playbook=<name>`, check outputs on disk
+  4. **Structure tests** — verify TASK.md frontmatter, seed.js exports, playbook YAML
+- **Running:** `npx vitest run tests/` (all), `npx vitest run tests/<file>` (specific file), `npx vitest` (watch mode)
+- **Adding a test:** create a test fixture under `tests/test-<name>/` with `.converge/project.yaml` + `playbooks/default/` structure, then write a `.test.ts` file that compiles/runs and verifies expected outputs
+
+### Gap detection
+- **Source:** `packages/core/src/task/gap/`
+- **Key types:** `packages/core/src/task/gap/types.ts` (`GapKind`, `GapType`, `CompactGap`)
+- **Key logic:** `packages/core/src/task/gap/detector.ts` (`GapDetector`, `ConvergenceAnalyzer`)
+- **Gap kinds:** `plan`, `seed`, `seed-script`, `blocker`, `output`, `check-failed`, `corrupted`, `systemic`, `user-question`, `insufficient-evidence`, `contradictory-finding`, `untested-hypothesis`
+- **Symptoms:**
+  - Gap persists across waves despite valid outputs on disk
+  - Wrong gap kind assigned (e.g. `seed-script` gap on a hand-written task)
+  - Gap score doesn't improve between waves (stall trigger)
+  - `detect-gaps` action returns empty when gaps clearly exist
+  - Input gaps not traced to upstream task outputs
+- **Reproduce against:** `examples/test-buggy-check`, `examples/test-gap-blocked-input`, `examples/test-gap-missing-output`
+- **Watch:** per-task `gaps.yml`, per-attempt gap events in `logs/events.jsonl`
+
+### Validation / checks
+- **Source:** `packages/core/src/validation/`, `packages/core/src/task/checks/`
+- **Also:** `packages/core/src/task/playbook/loader.ts` — explicit `cmd` checks + `scripts/` reference extraction
+- **Symptoms:**
+  - Check passes when output is wrong / fails when output is right
+  - Check predicate evaluates against stale state
+  - Check error message uninformative
+  - check command points at a missing `scripts/...` helper
+  - legacy `type: test` / `.test.md` authoring still present
+- **Reproduce against:** `tests/test-buggy-check` (check behavior), `packages/core/tests/config/playbook-loader-checks.test.ts`
+- **Watch:** per-attempt `CHECK.md`, navigator `verify` action output
+
+### Planning / synthesis / orchestrator
+- **Source:** `packages/core/src/planning/`, `packages/core/src/synthesis/`, `packages/core/src/orchestrator/`
+- **Symptoms:**
+  - Wrong task chosen as next-task
+  - Phase transitions out of order
+  - Synthesis step produces empty / malformed output
+  - `plan` gap appears but re-planning produces invalid plan
+- **Reproduce against:** multi-phase examples
+- **Watch:** plan-related navigator actions in stdout, per-task `plan.md` in journal
+
+### Storage / artifacts
+- **Source:** `packages/core/src/storage/`, plus on-disk `.converge/artifacts/<playbook>/`
+- **Symptoms:**
+  - Artifact path mismatch (task writes to one path, reader expects another)
+  - Artifact missing despite task showing complete
+  - Artifact overwritten across iterations when it shouldn't be
+- **Watch:** `.converge/artifacts/<playbook>/...`
+
+### Hooks
+- **Source:** `packages/core/src/hooks/`
+- **Symptoms:**
+  - Lifecycle hook never fires
+  - Hook fires twice
+  - Hook exception silently swallowed
+- **Watch:** stdout for hook log lines, per-attempt `events.jsonl` for hook events
+
+### agentfn / AI providers
+- **Source:** `packages/agentfn/src/` (unified interface + skill management + compose)
+- **Also:** `packages/{claudefn,acpfn,kimifn,qwenfn,geminifn,openfn}/` (individual provider clients)
+- **Symptoms:**
+  - Provider throws on a valid response shape
+  - Retry loop doesn't kick in on `Overloaded` / 429 / 5xx
+  - Retry loop *over*-retries on a permanent error (400, 401, 403)
+  - Token / cost accounting wrong
+  - Skill symlinks land in wrong directory
+  - Provider selection (`provider:` field) ignored
+- **Reproduce against:** whichever example the user has the provider configured for (check `.converge/project.yaml`)
+- **Watch:** stdout for `Overloaded`, `API Error`, `429`, `5xx` retry messages; per-attempt `logs/events.jsonl` for provider call records
+
+### CLI
+- **Source:** `packages/cli/src/`
+  - `main.ts` — entry, arg parsing, command dispatch
+  - `commands-run.ts` — `run` command
+  - `commands-build.ts` — `build` command
+  - `commands-clean.ts` — `clean` command
+  - `commands-test.ts` — `test` command
+  - `commands-compile.ts` — `compile` command
+  - `commands-reset.ts` — `reset` command
+  - `commands-list.ts`, `commands-tree.ts` — list/status display
+  - `commands-inspect.ts` — task/session inspection
+  - `commands-metrics.ts` — cost metrics
+  - `commands-gantt.ts`, `commands-graph.ts`, `commands-journal.ts` — visualization
+  - `commands-validate.ts` — `verify` command
+  - `commands-seed.ts` — `seed` command
+  - `commands-playbook.ts` — playbook management
+  - `commands-deps.ts` — dependency management
+  - `autonomous-run.ts` — autonomous run loop
+  - `dag-run.ts` — DAG-based run
+  - `run-event-stream.ts` — event stream handling
+- **Symptoms:**
+  - Wrong arg parsing / unrecognized flag
+  - Path-form scoping picks wrong playbook
+  - Exit code wrong (0 on failure, non-zero on success)
+  - Output formatting broken
+  - `--select` expression doesn't match expected tasks
+  - `clean --select` deletes wrong or no tasks
+- **Reproduce against:** any example; pick the smallest that exposes the subcommand under test
+- **Watch:** the actual CLI command's output
+
+## How to use this map
+
+1. Match the symptom to a subsystem row above.
+2. Open the listed source files.
+3. Trace the call path from the symptom backwards.
+4. Cross-reference with `troubleshooting/playbook.md` — if the symptom is recorded, follow the recipe.
+5. If the diagnosis crosses subsystem rows (e.g. navigator ↔ seed, or gap detection ↔ agentfn), surface the hypothesis to the user before editing.
+
+## Test fixture → subsystem mapping
+
+Use these when picking a test bed (dev loop step 1). All paths under `tests/`:
+
+| Fixture | Exercises |
+|---------|-----------|
+| `test-simple-run` | Basic task execution, single-attempt convergence |
+| `test-compile-discover` | Compile/run separation, static child discovery, manifest+runtime |
+| `test-mixed-model` | Multi-provider AI routing, `ai:` block, agentfn dispatch |
+| `test-buggy-check` | Buggy-check relaxation, `BUGGY_CHECK.md`, check patching |
+| `test-gap-blocked-input` | DependencyBackoffStrategy, input gap detection, producer→consumer |
+| `test-gap-missing-output` | Output gap detection, TaskRunStrategy re-execution |
+| `test-loop-detection` | Tool-call loop detection, LEARN.md augmentation |
+| `test-multi-attempt` | Multi-attempt convergence, sequential check gates |
+| `test-resume` | Crash-safe resume, incremental file creation |
+| `test-seeding` | Recursive seed spawning (3 levels), `ctx.spawn()` |
+| `test-seed-repair` | SeedScriptRepairStrategy, broken seed auto-fix |
+| `test-queue-pattern` | Incremental do-while drain, discovery, convergence |
+| `test-financial-deep-research` | Named non-default playbook, multi-level seed structure |
+| `test-mixed-model` | Multi-provider `ai:` block, per-task provider/model config |
+
+## Self-improvement-loop playbook
+
+- **Run:** `converge run --playbook=self-improvement-loop --select improve+`
+- **Source:** `.converge/playbooks/self-improvement-loop/` (`README.md`, `tasks/improve/TASK.md`, `tasks/improve/seeds/epoch.seed.js`, `scripts/*.mjs`)
+- **Evidence:** `.converge/artifacts/self-improvement-loop/` (`journal.md`, `metrics.jsonl`, `backlog.jsonl`, `touched-files.jsonl`, `epochs/<NNN>/verify/result.json`)
+- **Gate failures:** dirty start → clean non-artifact diff; selection quality → `metrics.jsonl`/`touched-files.jsonl`; patch mismatch → manifest vs non-artifact `git diff`; weak verification → changed subsystem tests.
+
+Full examples (heavier, multi-phase) live under `examples/`:

package/skills/converge-development/reference/observability.md

@@ -0,0 +1,132 @@
+# Observability — what to read on disk during a run
+
+The stdout event stream tells you *what* the framework is doing. The journal and inventory tell you *why*. When debugging the framework itself, you need both.
+
+All paths are relative to the example directory (e.g. `/Users/minh/Documents/converge/examples/hello-world`).
+
+## Top-level layout (per playbook run)
+
+```
+.converge/
+├── project.yaml                              project + provider config
+├── playbooks/<playbook>/                     playbook source
+│   ├── playbook.yml
+│   └── tasks/<task>/TASK.md
+├── journal/<playbook>/                       runtime state — read this for diagnosis
+│   ├── manifest.json                         compiled DAG (nodes, parent_map, child_map)
+│   ├── runstate.json                         execution state (node status, attempts, fingerprints)
+│   ├── events.jsonl                          playbook-level event stream
+│   └── tasks/<taskId>/
+│       ├── status.json                       task status (pending → in_progress → complete/failed)
+│       ├── gaps.yml                          current gap snapshot
+│       ├── summary.md                        human-readable status
+│       ├── plan.md                           plan output (for containers)
+│       ├── seed.json                         seed spawn record (for seed tasks)
+│       ├── FEEDBACK.md                       latest attempt feedback
+│       ├── LEARN.md                          accumulated learning across attempts
+│       └── attempts/<n>/
+│           ├── TASK.md                       materialized snapshot at attempt time
+│           ├── CHECK.md                      check predicate output
+│           └── logs/
+│               ├── events.jsonl              per-attempt event log (most detailed)
+│               └── log.log                   raw AI session transcript
+├── inventory/<playbook>/                     runtime ledger for spawned tasks
+│   ├── tasks.jsonl                           flat task inventory
+│   └── spawned/<taskId>/TASK.md              rendered spawned task definitions
+└── artifacts/<playbook>/                     task outputs (the actual work product)
+```
+
+## What each file tells you
+
+### `journal/<playbook>/tasks/<taskId>/status.json`
+Lightweight task status file. Faster to read than checkpoint for quick status checks. Contains status enum and timestamps.
+
+### `journal/<playbook>/tasks/<taskId>/gaps.yml`
+Current gap snapshot for this task. Lists all unresolved gaps with kind, type, severity, and description. Compare across waves to see if gaps are resolving.
+
+### `journal/<playbook>/tasks/<taskId>/attempts/<n>/TASK.md`
+Snapshot of TASK.md as the runner saw it at attempt n. **If this differs from the source `playbooks/<playbook>/tasks/<task>/TASK.md`, the runner is using a stale materialized copy** — known failure mode. Compare:
+
+```bash
+diff .converge/playbooks/<playbook>/tasks/<task>/TASK.md \
+     .converge/journal/<playbook>/tasks/<taskId>/attempts/<n>/TASK.md
+```
+
+### `journal/<playbook>/tasks/<taskId>/attempts/<n>/CHECK.md`
+What the check predicate evaluated. Use to see the gap between expected and actual output.
+
+### `journal/<playbook>/tasks/<taskId>/attempts/<n>/logs/events.jsonl`
+The most detailed per-attempt event stream. Includes: spawn, hook fires, agentfn provider calls, check evaluation, gap detection, repair attempts. **Primary diagnostic source for navigator and provider bugs.**
+
+```bash
+# pretty-print one attempt's events
+jq -c . .converge/journal/<playbook>/tasks/<taskId>/attempts/<n>/logs/events.jsonl | less
+```
+
+### `artifacts/<playbook>/...`
+What the task actually produced. **Always cross-check checkpoint status against artifacts on disk** — checkpoint can lie; the artifact is ground truth.
+
+## Useful tail commands during a run
+
+```bash
+# All task checkpoints + event streams, side by side
+tail -f .converge/journal/<playbook>/events.jsonl &
+find .converge/journal/<playbook>/tasks -path '*/logs/events.jsonl' -exec tail -f {} +
+
+# Latest attempt's detailed events for a specific task
+TASK_DIR=".converge/journal/<playbook>/tasks/<taskId>"
+LATEST=$(ls -t "$TASK_DIR/attempts/" 2>/dev/null | head -1)
+tail -f "$TASK_DIR/attempts/$LATEST/logs/events.jsonl"
+
+# Quick status scan across all tasks
+find .converge/journal/<playbook>/tasks -name "status.json" -exec sh -c 'echo "{} -> $(jq -r .status {})"' \;
+```
+
+## CLI introspection commands
+
+These are also disk readers, just packaged. Use them as a faster path than reading raw JSON:
+
+```bash
+CLI="node /Users/minh/Documents/converge/packages/cli/dist/index.js"
+
+# Task list with status
+$CLI list --playbook <name>
+
+# Dependency graph
+$CLI show graph --playbook <name>
+
+# Inspect a specific task
+$CLI inspect --playbook <name> --task <task-id>
+
+# Show cost metrics
+$CLI show metrics --playbook <name>
+
+# Verify config and structure
+$CLI playbook validate <name>
+
+# Show journal for a playbook
+$CLI show journal --playbook <name>
+```
+
+## Self-improvement-loop artifacts
+
+Read `.converge/artifacts/self-improvement-loop/` as the autonomous loop's evidence trail: `journal.md`, `metrics.jsonl`, `backlog.jsonl`, `touched-files.jsonl`, `convergence.md`, and `epochs/<NNN>/verify/result.json`.
+
+```bash
+latest=$(ls -1 .converge/artifacts/self-improvement-loop/epochs | sort -n | tail -1)
+jq . .converge/artifacts/self-improvement-loop/epochs/$latest/verify/result.json
+jq -c . .converge/artifacts/self-improvement-loop/metrics.jsonl
+jq -r .file .converge/artifacts/self-improvement-loop/touched-files.jsonl | sort | uniq -c | sort -rn
+```
+
+If a gate fails, read the matching script in `.converge/playbooks/self-improvement-loop/scripts/`; do not weaken checks or hand-edit evidence to pass.
+
+## Adding temporary diagnostic logging
+
+When the on-disk surface isn't enough, add `console.log` in the relevant `packages/core/src/<subsystem>/` file. Then:
+
+1. `pnpm --filter @openplaybooks/converge-core build` (faster than full `pnpm build`).
+2. `rm -rf .converge/journal/<playbook> .converge/inventory/<playbook>` to clear runtime state.
+3. Re-run the example.
+
+**Remove the `console.log` before declaring the fix done.** Don't ship debugging output. If the module already has a real logger, prefer that over raw `console.log`.

package/skills/converge-development/troubleshooting/playbook.md

@@ -0,0 +1,213 @@
+# Framework troubleshooting playbook
+
+Symptom → root cause → fix recipes for **framework bugs** (under `packages/`). Distinct from `converge-control`'s playbook, which covers user-playbook bugs.
+
+**This file grows.** Append new entries each time the dev loop fixes a novel framework bug (step 8 of `SKILL.md`). Never delete an entry unless the bug class no longer applies (e.g. the subsystem was rewritten and the symptom is impossible).
+
+## Entry format
+
+Each entry follows this structure. Copy it when adding a new one:
+
+```markdown
+## <symptom in one sentence, as the user / operator would describe it>
+
+**Symptom**
+- What you observe in stdout / journal / checkpoint / artifacts
+- Exact log lines if available
+
+**Root cause**
+- The actual code-level reason. Cite file paths.
+
+**Fix**
+- The patch applied. Cite file paths and what changed (one or two sentences, not a diff).
+
+**Verification**
+- Exact commands run after the fix to confirm
+- What you expected to see in the output
+
+**Files touched**
+- List of `packages/**` files modified
+```
+
+---
+
+## Skill symlinks land in the monorepo root's `.claude/skills/` instead of the example's
+
+**Symptom**
+- After running an example like `examples/autonomous-pentest`, the example's skills appear as symlinks under `<repo-root>/.claude/skills/` instead of `examples/<name>/.claude/skills/`.
+- Console line during the run: `🔗 Creating skill junctions in: /Users/.../converge/.claude/skills`. The path is the monorepo root, not the example dir.
+- Symlinks point to `../../examples/<name>/.converge/skills/<skill>` — clearly the framework knew about the example's skills but resolved the install location to the wrong root.
+- Symlinks persist after the run (cleanup also runs against the wrong dir).
+
+**Root cause**
+The framework had **six** `findProjectRoot` implementations across packages, each using a different heuristic. The buggy ones either:
+1. Walked up looking for `.claude/` first (`agentfn.ts:36`, `compose.ts:26`) — climbed past the example to the monorepo root if the example had `.converge/` but no `.claude/`.
+2. Walked up looking for `pnpm-workspace.yaml`/`package.json` (`agentfn/skills.ts:417`, `kimifn/skills.ts:19`, `geminifn/skills.ts:19`, `qwenfn/skills.ts:19`) — every example lacks both files but the monorepo root has them, so the walk always landed at the monorepo root.
+
+In `agentfn.ts`, the `agentfn()` function computed the *correct* `symlinkTarget` on line 183, then the legacy-skills branch at line 218–222 silently *overwrote* it using the bad `_findProjectRoot` from `agentfn/skills.ts`.
+
+**Fix**
+Established a single canonical rule: **project root = nearest ancestor (or self) containing `.converge/`**. Period. No `.claude/` preference. No workspace markers. No `process.cwd()` escape hatches.
+
+Implemented as a small `findConvergeRoot(startDir)` helper inlined into each fn package that needs it. Migrated every call site:
+
+- `agentfn/agentfn.ts` — deleted local `findProjectRoot`, imported `findConvergeRoot`. Rewrote the legacy-skills branch to reuse the already-computed `projectRoot` instead of re-resolving.
+- `agentfn/compose.ts` — same treatment.
+- `agentfn/skills.ts` — deleted `_findProjectRoot`. `_getConvergeDir`, `listSkills`, and `legacyGetSkillPath` now use `findConvergeRoot`.
+- `kimifn/src/skills.ts`, `geminifn/src/skills.ts`, `qwenfn/src/skills.ts` — deleted local `findProjectRoot`, imported `findConvergeRoot`. `getSkillsDir` and `getAgentsDir` retain the `<root>/skills/` and `<root>/agents/` path shape; only the root-finding logic changed.
+- `core/src/client/converge-client.ts` — removed the `process.env.CONVERGE_PROJECT_DIR ?? process.cwd()` fallback. The SDK now hard-fails with a clear error if `CONVERGE_PROJECT_DIR` (or `parsed.projectDir` from `CONVERGE_CONTEXT_JSON`) is missing. No silent guesses.
+
+**Verification**
+1. New package's own tests pass:
+   ```bash
+   cd /Users/minh/Documents/converge/packages/project-root && pnpm test
+   # → 9 passed
+   ```
+2. Full monorepo build clean:
+   ```bash
+   cd /Users/minh/Documents/converge && pnpm build
+   ```
+3. End-to-end check of the resolved path with a synthetic monorepo + nested example:
+   ```bash
+   # Tempdir with .converge/ at outer level AND inside examples/demo/.
+   # findConvergeRoot from inside examples/demo/tasks/recon must return
+   # examples/demo, NOT the outer monorepo root. Verified.
+   ```
+4. Per-package test counts unchanged from baseline (zero regressions).
+5. Manual: re-run any example that has `.converge/skills/`. Watch the `🔗 Creating skill junctions in:` line — path must end in `examples/<name>/.claude/skills`, not `<monorepo>/.claude/skills`.
+
+**Files touched**
+- `packages/project-root/` (new package: `package.json`, `tsconfig.json`, `vitest.config.ts`, `src/index.ts`, `tests/find-converge-root.test.ts`)
+- `packages/agentfn/package.json` (added dep)
+- `packages/agentfn/vitest.config.ts` (added alias)
+- `packages/agentfn/src/agentfn.ts`
+- `packages/agentfn/src/compose.ts`
+- `packages/agentfn/src/skills.ts`
+- `packages/kimifn/package.json` (added dep)
+- `packages/kimifn/src/skills.ts`
+- `packages/geminifn/package.json` (added dep)
+- `packages/geminifn/src/skills.ts`
+- `packages/qwenfn/package.json` (added dep)
+- `packages/qwenfn/src/skills.ts`
+- `packages/core/src/client/converge-client.ts`
+
+---
+
+## Shared seed script path not found despite file existing at project root
+
+*(Historical note: originally diagnosed for the WBS subsystem, which has since been replaced by the seed/navigator architecture. The path-resolution pattern is still relevant.)*
+
+**Symptom**
+- A TASK.md or seed template references a shared script at the project root.
+- Run fails with a "script not found" error.
+- The script exists at `<projectDir>/scripts/foo.js` but the runner only looks under the journal task directory.
+- Error shows a resolved path inside `journal/<playbook>/tasks/...` instead of the project root.
+
+**Root cause**
+- The seed script executor resolved the script path only against the task materialization directory. That works for co-located scripts (e.g. `./seeds/index.js` next to the TASK.md) but breaks for shared scripts at the project root.
+
+**Fix**
+- Two-step resolution in the seed executor:
+  1. Try task-dir-relative first (preserves the co-located convention).
+  2. If that doesn't exist, fall back to project-dir-relative.
+  3. The "not found" error message now lists *both* candidate paths so debugging is unambiguous.
+- Mirror the same project-dir fallback in the repair path (`core/src/navigator/core/actions/repair/strategy-seed-script-repair.ts`) so the repair pipeline can also locate shared scripts.
+
+**Verification**
+```bash
+cd /Users/minh/Documents/converge
+pnpm --filter @openplaybooks/converge-core build && pnpm --filter @openplaybooks/converge build
+cd examples/test-seeding
+node /Users/minh/Documents/converge/packages/cli/dist/index.js clean --select '*'
+node /Users/minh/Documents/converge/packages/cli/dist/index.js run
+# expect: seed script found and executed, no "script not found" errors
+```
+
+**Files touched**
+- `packages/core/src/navigator/core/actions/resolution/resolve-seed.ts` (seed script resolution)
+- `packages/core/src/navigator/core/actions/repair/strategy-seed-script-repair.ts` (repair path)
+
+---
+
+## Transient remote errors (429, 5xx, network) trigger seed script repair, wasting tokens
+
+**Symptom**
+- A seed script runs, hits a transient downstream failure (rate limit, quota exhausted, 5xx, network reset), and exits non-zero. Stdout shows the error, e.g.:
+  ```
+  google.genai.errors.ClientError: 429 RESOURCE_EXHAUSTED. {'error': {'message': 'Your prepayment credits are depleted...'}}
+  ```
+- Runner classifies this as a script bug and triggers repair, calling AI to "fix" the script:
+  ```
+  → Strategy: seed script error - triggering AI repair
+  [seed-script-repair] Calling AI to fix script (attempt 1)...
+  ```
+- AI rewrites a script that wasn't broken, costing tokens for no benefit. Even if the rewrite is syntactically valid, the next run hits the same 429.
+
+**Root cause**
+- The seed repair path had no precondition to detect transient/remote failures. Every non-success exit path fed into AI repair.
+
+**Fix**
+- Added a transient-error precondition:
+  - `TRANSIENT_REMOTE_PATTERNS` regex list matches 429, 5xx (502/503/504), `RESOURCE_EXHAUSTED`, `quota`, `rate-limit`, `Overloaded`, `ECONNRESET`/`ECONNREFUSED`/`ETIMEDOUT`/`ENOTFOUND`, "credits depleted", etc.
+  - `isTransientRemoteError(error)` checks `error.name + message + stack` against those patterns.
+  - Before the AI-repair branch, the executor logs a `skip-transient` fact and returns early when transient. The script's normal retry loop (1/2, 2/2) still applies; we just don't rewrite the script.
+
+**Verification**
+```bash
+cd /Users/minh/Documents/converge
+pnpm --filter @openplaybooks/converge-core build && pnpm --filter @openplaybooks/converge build
+cd examples/test-seeding
+# Use a depleted/invalid API key to deterministically force a 429
+GEMINI_API_KEY=invalid node /Users/minh/Documents/converge/packages/cli/dist/index.js clean --select '*'
+GEMINI_API_KEY=invalid node /Users/minh/Documents/converge/packages/cli/dist/index.js run
+# expect: log line showing transient error detected and AI repair skipped
+# expect: NO "[seed-script-repair] Calling AI to fix script" line
+```
+
+**Files touched**
+- `packages/core/src/navigator/core/actions/repair/strategy-seed-script-repair.ts` (transient error pre-filter)
+
+---
+
+## `seedConfigGap is not defined` crash in resolve-seed action
+
+**Symptom**
+- Running a playbook with a seed task that has a seed gap.
+- Crash with `ReferenceError: seedConfigGap is not defined` at `resolveSeed`.
+- Stack trace points to `resolve-seed.ts` (or the bundled `dist/index.js` equivalent).
+
+**Root cause**
+- `packages/core/src/navigator/core/actions/resolution/resolve-seed.ts` line 37 references `seedConfigGap.id` but the variable captured from the gap search (line 19) is named `seedGap`. The variable name `seedConfigGap` was never declared — a simple typo.
+
+**Fix**
+- Rename `seedConfigGap` → `seedGap` on the `gapId:` line in `resolve-seed.ts`.
+
+**Verification**
+- Run `examples/test-seed-repair`. Should not crash with `seedConfigGap is not defined`. Instead it should proceed to seed execution and (if the seed has a deliberate error) trigger repair.
+
+**Files touched**
+- `packages/core/src/navigator/core/actions/resolution/resolve-seed.ts`
+
+---
+
+## SeedScriptRepairStrategy can't find the seed file because `scriptPath` points to the task directory, not the script
+
+**Symptom**
+- Seed script execution fails with a runtime error (e.g., `ReferenceError`).
+- Self-healing triggers seed-script-repair.
+- Repair strategy fails: `Seed script not found at <task-dir>` (non-retryable).
+- The seed script exists at `<seeds-dir>/<name>.seed.js` but the repair strategy only looks under the task directory.
+
+**Root cause**
+- `packages/core/src/executor/seed-executor.ts` "Strategy 4" (general seed error handler, ~line 1096) sets `scriptPath: this.taskFilePath` without trying to extract the actual script path from the error.
+- The `extractSeedScriptPathFromError` method already knows how to parse the error format `"Seed script import failed: <path>\n<cause>"`, but it was only called in Strategy 2 (missing file), not Strategy 4 (general error).
+- `packages/core/src/navigator/repair/strategies/seed-script-repair.ts` then searches for `seed.js`/`seedData.ts`/`seed/index.js` under the task directory, which doesn't contain the script (it's in `../seeds/`).
+
+**Fix**
+- In the Strategy 4 gap creation block, call `this.extractSeedScriptPathFromError(error)` first and use that as `scriptPath`, falling back to `this.taskFilePath` if extraction fails.
+
+**Verification**
+- Run `examples/test-seed-repair`. The repair strategy should find the seed script, call AI to fix it, self-test should pass, and the fixed script should re-run successfully.
+
+**Files touched**
+- `packages/core/src/executor/seed-executor.ts`