GSD-style fresh-context-per-task: worktree isolation for autonomous execution

[azalio]

Summary

map-framework has context compression/compaction but lacks per-task context isolation. On long autonomous sessions, accumulated context degrades LLM output quality. GSD solves this by giving every executor agent a completely fresh 200K-token Claude instance via isolation="worktree".

This is the second-largest structural gap after spec-driven pipeline.

What GSD does

Core mechanism: isolation="worktree"

• Orchestrator stays thin (~10-15% context for 200K models)
• Each plan spawns a fresh executor agent in an isolated git worktree:

  Agent(
    subagent_type="gsd-executor",
    isolation="worktree",
    prompt="...minimal instruction + file list to read from disk..."
  )
  

• Agent gets a clean 200K window (up to 1M for models supporting it)
• Files are READ from disk, NOT inlined into the prompt
• After wave completes: git merge --no-ff merges all worktree branches back

Wave-based parallelism with DAG

• Plans declare dependencies: depends_on: ["01"]
• Orchestrator groups into dependency-resolved waves:

  Wave 1: Plan 01, Plan 02  (no deps, parallel)
  Wave 2: Plan 03           (depends: 01,02)
  

• Intra-wave files_modified overlap detection → forces sequential if conflict
• Sequential Agent() dispatch with run_in_background: true avoids .git/config.lock

Safety guards

• Worktree path safety: Guards against HEAD on protected refs, cwd-drift, absolute paths outside worktree
• Post-wave merge gate: Runs full build+test suite after merge to catch cross-plan issues
• Deletion guard: Refuses bulk deletions outside .planning/
• Stall detection: Configurable surveillance intervals, heartbeat checkpoints

Context budget awareness

• Statusline hook: live context usage display
• Context monitor hook: agent-facing warnings at 35%/25% remaining
• Read depth scales with window: <500K = frontmatter only, >=500K = full body
• Adaptive prompt enrichment for 1M+ models vs thinning for sub-200K

Current map-framework state

• Compression/compaction: Exists but operates on a SINGLE session — all subtasks share accumulated context
• .map/ state: Branch-scoped checkpoint, but no isolation BETWEEN subtasks within a session
• No wave parallelism: Subtasks execute sequentially or at actor discretion, not as independent waves
• No per-subtask worktree: Everything runs in the same git working tree
• No context budget awareness in runtime: No statusline or warning hooks

Proposed design

Phase 1: Per-subtask worktree isolation (opt-in via config)

• .map/config.yaml key: worktree_isolation: true
• Actor spawns each independent subtask in its own worktree:

  Agent(
    subagent_type="map-actor",
    isolation="worktree",
    prompt="...subtask spec + file paths to read..."
  )
  

• Monitor + Evaluator run in orchestrator context after subtask completes
• Post-wave merge + full test suite run

Phase 2: Wave-based parallelism

• map-plan assigns dependency metadata to subtasks
• map-efficient groups independent subtasks into waves
• Parallel Agent() dispatch within waves, sequential across waves
• files_modified overlap detection between subtasks in same wave
• Post-wave merge gate: build + test

Phase 3: Context budget hooks

• hooks/context-monitor: Inject warnings at configurable thresholds
• Statusline: Show current context usage %
• Adaptive detail: less context → less detail in agent prompts

Safety invariants

• Worktree path safety (protected refs, cwd-drift, absolute paths)
• Bulk deletion detection on merge
• Post-merge verification gate
• Heartbeat checkpoints to prevent SSE timeouts
• Configurable stall detection

References

• GSD: workflows/execute-phase.md (lines 504-647), references/worktree-path-safety.md, references/context-budget.md, references/gates.md
• GSD Architecture: docs/ARCHITECTURE.md (lines 73-75, 317-357, 389-394)

Acceptance criteria

• .map/config.yaml key worktree.isolation
• Per-subtask worktree creation with isolation="worktree"
• Post-subtask merge with safety guards
• Wave-based parallelism for independent subtasks
• Context budget hook (warnings at thresholds)
• Heartbeat checkpoint on orchestrator SSE stream

[azalio]

Беру в работу.

Phase 1, Slice 1 (config-driven, opt-in, OFF by default) — per-subtask git worktree isolation: step-runner-owned lifecycle + safety guards, wired into map-efficient.

• worktree.isolation: true config key (dotted-YAML alias → snake_case dataclass worktree_isolation, по образцу sofa.enabled / review.cross_ai.*)
• step-runner subcommands (детерминированное тестируемое ядро на tmp-репо):
  • create_subtask_worktree — worktree off HEAD; guards: not-a-repo, protected-ref, idempotent re-use
  • merge_subtask_worktree — --no-ff merge-back + safety guards (bulk-deletion detection, conflict→abort+report) + пост-merge гейт через verification_checks
  • cleanup_subtask_worktree — идемпотентный git worktree remove/prune
  • worktree_isolation_status — отчёт; manifest stage worktree
• skill wiring в map-efficient: при включённом флаге Actor исполняется в worktree (isolation="worktree"), после Monitor/Evaluator → merge-back через runner
• тесты + make render-templates (4 generated trees) + docs (USAGE/ARCHITECTURE/CHANGELOG)

Дизайн сверяю с llm-council. PR пойдёт с Part of #284 — issue остаётся открытым.

Отложено в следующие слайсы: Phase 2 (wave/DAG-параллелизм + files_modified overlap), Phase 3 (context-budget hooks: statusline, warnings, heartbeat).

[azalio]

✅ Phase 1, Slice 1 landed via #296 (squash-merged to main).

Per-subtask git worktree isolation is live in /map-efficient (opt-in via worktree.isolation, OFF by default). Each subtask's Actor runs in a dedicated throwaway git worktree; the result is squash-merged back into the working branch only after verification_checks pass IN the worktree (pre-merge gate), and a rejected attempt is discarded so the working branch is never touched by a bad attempt.

Shipped (runner-owned; the step runner owns the lifecycle + every guard, structured {kind,message}):

• create_subtask_worktree — crash-safe remove-and-recreate; guards: not-a-repo, protected-ref, nested-worktree refusal, active-git-op, subtask_id ref/path sanitization, dirty-main (excludes MAP runtime state), submodule init
• merge_subtask_worktree — base-divergence, runtime-state-in-diff, bulk-deletion (worktree.max_deletions), submodule-pointer, detached-HEAD guards BEFORE touching the working branch; accept = git merge --squash + one runner-authored commit (never --no-ff)
• discard_subtask_worktree — atomic reject, idempotent, --save-patch
• worktree_isolation_status — reconcile recorded vs live worktrees
• worktrees stored OUT of the working tree (repo's git common dir); MAP state always resolves against the main checkout; new worktree manifest stage + .map/<branch>/worktrees.json

Design llm-council-reviewed (conv 461b92f9): runner-owned over harness-native isolation="worktree"; squash-merge over --no-ff; always-discard on reject; pre-merge verify + crash-safe retry + atomic reject folded in (so the slice is not a no-op); explicit state-root separation. make check green (ruff/mypy/pyright 0, 2910 tests, render check) and GitHub CI green (build + test matrix macos/ubuntu × 3.11/3.12).

Acceptance criteria

• .map/config.yaml key worktree.isolation
• Per-subtask worktree creation (runner-owned; Actor dispatched WITHOUT harness-native isolation)
• Post-subtask merge with safety guards (+ pre-merge verification)
• Wave-based parallelism for independent subtasks → Phase 2
• Context budget hook (warnings at thresholds) → Phase 3
• Heartbeat checkpoint on orchestrator SSE stream → Phase 3

Remaining (issue stays open):

• Phase 2 — wave/DAG parallelism + files_modified overlap detection (the map-wt/<slug>-<attempt> branch scheme + --attempt threading already support it without a schema change).
• Phase 3 — context-budget hooks (statusline, warnings at thresholds, heartbeat).

[azalio]

Беру в работу следующий срез.

Phase 2, Slice 1 — параллельное исполнение независимых subtask'ов волны в изолированных worktree'ах + runner-owned per-wave merge-back координатор (opt-in, worktree.isolation, OFF by default).

Что уже есть (встраиваюсь, не пишу с нуля):

• DAG-волны: dependency_graph.py (compute_waves + split_wave_by_file_conflicts) + оркестратор set_waves/get_wave_step/validate_wave_step/advance_wave/wave_monitor_failed; decomposer emits dependencies + affected_files; per-wave gates в skill.
• Phase 1 worktree-примитивы (create_/merge_/discard_subtask_worktree, --attempt, ветки map-wt/<slug>-<attempt>).

Реальный gap: wave-loop и worktree-изоляция не связаны — параллельная волна не запускает каждый subtask в своём worktree, нет per-wave merge-back координатора. merge_subtask_worktree к тому же имеет строгий BASE_DIVERGED guard (working_head == base_sha), который ломается при последовательном merge нескольких worktree'ов волны (первый merge двигает HEAD).

План среза:

• новый runner-subcommand merge_wave_worktrees — детерминированное тестируемое ядро: фиксирует wave_base_sha, отвергает внешний сдвиг HEAD, но разрешает sibling-дивергенцию внутри волны; squash-merge каждого принятого worktree в детерминированном порядке (3-way, disjoint → conflict-free; real-conflict → abort + структурный отчёт), сохраняя one-commit-per-subtask
• wiring wave-loop в map-efficient: при включённой изоляции каждый subtask параллельной волны исполняется в своём worktree, concurrent dispatch; на all-pass → merge_wave_worktrees → post-wave gate; на Monitor-fail → discard + retry
• тесты + make render-templates (4 generated trees) + docs (USAGE/ARCHITECTURE/CHANGELOG)

Дизайн координатора (merge-стратегия, атомарность отката, где гонять verification) сверяю с llm-council. PR пойдёт с Part of #284 — issue остаётся открытым.

Отложено в следующий срез: Phase 3 (context-budget hooks: statusline, warnings, heartbeat).

[azalio]

✅ Phase 2 (wave/DAG parallelism) — merge coordinator landed via #297 (squash-merged to main, 8323fe5).

The wave/DAG scheduler is now wired to per-subtask worktree isolation: a parallel wave of independent subtasks each runs in its own worktree and is accepted atomically by the new runner-owned merge_wave_worktrees. This closes the headline acceptance criterion Wave-based parallelism for independent subtasks.

Core problem solved: every worktree of a wave is cut off the same base, so they cannot be merged one at a time — the first merge_subtask_worktree advances HEAD and the next trips BASE_DIVERGED. The coordinator relaxes only that guard to a wave-scoped form (refuses EXTERNAL HEAD movement, allows in-wave sibling divergence).

Shipped (council-reviewed, conv c29d6fa9):

• dedicated coordinator (zero blast radius on the single-subtask path); shared _wt_freeze_and_verify primitive reused by both paths; wave_base_sha derived from the sidecar
• merge by frozen SHA in sorted id order, one runner commit per subtask
• all-or-nothing: any conflict / commit / post-wave-gate failure rolls the whole branch back to base (hard-reset + clean -fd, never merge --abort — squash has no MERGE_HEAD; MAP state excluded from clean) and leaves every worktree intact for retry
• one post-wave full gate inside the atomic transaction (catches cross-subtask semantic breaks)
• advisory flock (MERGE_IN_PROGRESS), attached/clean-target preconditions, conflict attribution, actual-overlap telemetry
• 12 new coordinator tests; make check green (ruff/mypy/pyright 0 src+tests, 2922 tests, render check). CI on the repo is down (billing) — local gate was the authority.

Acceptance criteria

• .map/config.yaml key worktree.isolation
• Per-subtask worktree creation (runner-owned)
• Post-subtask merge with safety guards (+ pre-merge verification)
• Wave-based parallelism for independent subtasks → landed (feat(map-efficient): parallel-wave worktree merge coordinator (Part of #284 Phase 2) #297)
• Context budget hook (warnings at thresholds) → Phase 3
• Heartbeat checkpoint on orchestrator SSE stream → Phase 3

Remaining (issue stays open):

• Phase 3 — context-budget hooks: live statusline context %, agent-facing warnings at thresholds, heartbeat checkpoints to prevent SSE timeouts.

[azalio]

Беру в работу Phase 3 (context-budget hooks).

Грунд-аудит показал, что одна из трёх AC уже закрыта в core:

• ✅ Threshold warnings — context-meter.py (UserPromptSubmit /compact nudge) + _emit_context_budget_warning в map_orchestrator.py уже шлют предупреждение при пересечении compression_threshold_tokens.

Реальный остаток Phase 3 — два gap'а:

• ❌ Statusline (live context %) — statusLine ключа в shipped settings.json нет вообще. Это чистый, тестируемый, in-scope срез.
• ❔ Heartbeat (SSE keepalive) — размытый/harness-adjacent: Claude Code сам держит SSE keepalive на длинных Task-диспатчах. Нужен scoping-вердикт (своя машинерия в MAP vs docs-recipe), как у Exploratory: scheduled/watchdog trigger model + 'report-delivery' exit-condition shape #259.

План: этим PR — Phase 3a: context-budget statusline (новый map-statusline.py, statusLine wiring, config-kill-switch, тесты, render 4 деревьев, docs). Дизайн (default on/off + heartbeat scope) сверяю с llm-council. PR пойдёт с Part of #284 — heartbeat (Phase 3b) остаётся открытым со scoping-вопросом.

[azalio]

✅ Phase 3 (context-budget hooks) shipped via #298.

Statusline (map-statusline.py) — a Claude Code statusLine render command: [Opus] MAP ctx 47% (94k/200k) · branch · ST-003 ACTOR. Reads the usage Claude Code pre-computes on stdin (no transcript parse), branch from .git/HEAD, subtask from step_state.json; never blank/crashes. Wired non-destructively into .claude/settings.local.json only when no statusLine exists in local/project/user scope (no managed-file drift; idempotent). Claude provider only.

Acceptance criteria — all addressed

• .map/config.yaml key worktree.isolation
• Per-subtask worktree creation (feat(map-efficient): per-subtask git worktree isolation (Part of #284) #296)
• Post-subtask merge with safety guards (feat(map-efficient): per-subtask git worktree isolation (Part of #284) #296)
• Wave-based parallelism (feat(map-efficient): parallel-wave worktree merge coordinator (Part of #284 Phase 2) #297)
• Context budget hook (warnings at thresholds) — already shipped via context-meter.py (/compact nudge) + orchestrator _emit_context_budget_warning; the live statusline (feat(map): context-budget statusline (completes #284 Phase 3) #298) completes the continuous-observability half
• Heartbeat checkpoint on SSE stream → dispositioned as harness-owned (not built): the orchestrator is prompt-driven and dispatches subagents through Claude Code's Task tool, which the harness keeps alive. llm-council unanimous (conv 585f773b). A real crash-resume need is a separate, evidence-gated durable-checkpointing epic — not a network keepalive.

Recommend closing this epic once #298 merges. The only remaining idea (durable checkpointing / stuck-detection) is genuinely orthogonal — happy to open it as a fresh "Reliability & Recovery" epic if you want it tracked.

[azalio]

Закрываю как реализованный. Все три фазы реализованы в PR-ах #296 (Phase 1: per-subtask worktree isolation), #297 (Phase 2: parallel-wave merge coordinator), #298 (Phase 3: context-budget statusline). ARCHITECTURE.md подтверждает: «Phase 3 (context-budget hooks) is the final slice of #284 and is now complete».

---

Generated by Claude Code