# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [1.7.0] - 2026-04-12

### The self-verifying plan chain

Wave 1 of a parallel 6-session build revealed three failure modes: (1) a
session reported `status=completed` after only 2/5 steps — last tool call
was an arbitrary file review, not a completion check; (2) 3/6 sessions
had push blocked inside the sub-agent bash sandbox *after* all work was
done; (3) plans and blueprints were prose, so the orchestrator had no
machine-readable way to verify completion. v1.7.0 closes all three by
making the plan itself an executable contract.

### Added

- **Per-step verification manifest** in plan format (`plan_version: 1.7`).
  Every step now ends with a YAML `manifest:` block declaring
  `expected_paths`, `min_file_count`, `commit_message_pattern`,
  `bash_syntax_check`, `forbidden_paths`, `must_contain`. The manifest is
  the objective completion predicate — the Verify command is necessary but
  not sufficient.
- **Plan-critic dimension 10 — Manifest quality (hard gate).** Missing
  or invalid manifest (unparseable regex, path contradiction, missing
  block) is a `major` finding. v1.6 plans get a legacy-mode warning
  instead of a block.
- **Session Manifest aggregate** in session specs — synthesized by
  `session-decomposer` as the union of per-step manifests. Gives
  `ultraexecute-local` a single YAML block per session to audit against.
- **Step 0: Sandbox pre-flight** — obligatory first step in every
  generated session spec. Runs `git push --dry-run origin HEAD`; exit 77
  = sandbox cannot push, session status becomes `blocked` (not `failed`),
  no real work attempted. Escape hatch: `ULTRAEXECUTE_SKIP_PREFLIGHT=1`.
- **Launch script pre-flight** — `headless-launch-template.md` adds a
  `git push --dry-run` check outside the sandbox, before any session
  spawns, catching credential issues at the earliest possible point.
- **Phase 7.5 — Manifest audit (independent).** After all steps complete,
  `ultraexecute-local` re-verifies expected paths, commit count, commit
  message patterns, bash syntax, and forbidden-path untouched-ness from
  git log and filesystem. Agent's own bookkeeping is ignored. Disagreement
  with progress file → status overridden to `partial`.
- **Phase 7.6 — Recovery dispatch (bounded).** When Phase 7.5 detects
  drift in multi-session parent context, synthesize a temp session spec
  containing only missing steps and dispatch via existing
  `claude -p "/ultraexecute-local --session N"`. `recovery_depth ≤ 2`
  hard cap — third drift escalates to user.
- **Hard Rule 17: Manifest is the completion predicate.** A step may
  not be marked passed if its manifest does not verify, regardless of
  Verify's exit code.
- **Hard Rule 18: Last-activity rule.** Executor's final tool call
  before Phase 8 must be a manifest check, never an arbitrary file
  review. Prevents hallucinated completion.

### Changed

- **Plan template (`templates/plan-template.md`)** — adds
  `plan_version: 1.7` metadata line, `Manifest:` field on every step,
  "Manifest — objective completion predicate" section.
- **Plan-critic scoring** rebalanced: Headless readiness 0.15 → 0.10,
  Manifest quality 0.05 added. Legacy v1.6 plans skip the Manifest
  dimension and keep Headless readiness at 0.15.
- **Planning-orchestrator Phase 5** adds "Manifest generation rules
  (REQUIRED for every step)" with mechanical derivation from `Files:`
  and Checkpoint. Validates regex compilation and path existence before
  handoff to plan-critic.
- **Session-decomposer** parses plan manifests and propagates them
  verbatim into session specs. For v1.7+ plans with missing manifests:
  abort with pointer to failing step. For legacy v1.6 plans: synthesize
  minimal manifests and flag `legacy_synthesis: true`.
- **ultraexecute-local Phase 2** parses manifest YAML. Ugyldig YAML =
  abort with pointer to step. v<1.7 plans: synthesize + log
  `legacy_plan: true`.
- **ultraexecute-local Phase 6** — sub-step D renamed to D1 "Command
  verification"; new D2 "Manifest verification" runs after D1 with 5
  checks. F "Checkpoint" adds `checkpoint_drift` logging when HEAD
  message doesn't match `commit_message_pattern` (non-fatal).
- **Phase 8 report** — table gets Manifest column; JSON summary adds
  `plan_version`, `manifest_audit`, `drift_details`, `recovery_dispatched`,
  `recovery_depth`, `legacy_plan`. Result vocabulary strict:
  `completed | partial | blocked | failed | stopped`.
- **Division of labor clarified** in README — `/ultraresearch-local`
  gathers context (no decisions), `/ultraplan-local` transforms intent
  into an executable contract (manifests, plan-critic gate),
  `/ultraexecute-local` executes the contract disciplined (does NOT
  compensate for weak plans — escalates).

## [1.6.0] - 2026-04-08

### Added

- **`/ultraresearch-local` command** — deep research combining local codebase analysis
  with external knowledge. Produces structured research briefs with triangulation,
  confidence ratings, and source quality assessment. Supports modes: default (background),
  `--quick` (inline), `--local` (codebase only), `--external` (web only), `--fg` (foreground).
- **6 new agents** for the research pipeline:
  - `research-orchestrator` (opus) — runs full research pipeline as background task
  - `docs-researcher` (sonnet) — official documentation via Tavily, WebSearch, Microsoft Learn
  - `community-researcher` (sonnet) — real-world experience from issues, blogs, discussions
  - `security-researcher` (sonnet) — CVEs, audit history, supply chain risks
  - `contrarian-researcher` (sonnet) — counter-evidence and overlooked alternatives
  - `gemini-bridge` (sonnet) — independent second opinion via Gemini Deep Research MCP
- **Research brief template** (`templates/research-brief-template.md`) — structured format
  with dimensions, confidence ratings, triangulation, and source quality assessment.
- **`--research` flag for `/ultraplan-local`** — accepts up to 3 research brief paths.
  Enriches the interview (focuses on decisions, not facts) and injects brief context into
  exploration agents. Research-scout skips already-covered technologies.
- **Research-aware planning orchestrator** — `planning-orchestrator.md` now accepts research
  briefs, injects summaries into sub-agent prompts, and cross-references brief findings
  during synthesis.
- **Research settings** in `settings.json` — configurable Gemini bridge (enabled/timeout),
  interview depth, dimension limits, and stats tracking.

### Changed

- Plugin description and keywords updated to reflect research capabilities.
- CLAUDE.md expanded with ultraresearch command, modes, agents, architecture, and state.

## [1.5.0] - 2026-04-07

### Fixed

- **CRITICAL: Parallel session data loss** — Phase 2.6 ran parallel `claude -p` sessions
  in the same working directory, causing git race conditions and repository corruption.
  Each parallel session now runs in its own git worktree with isolated branch, index,
  and working files. Branches are merged back sequentially after each wave completes.

### Added

- **Phase 2.55 (Pre-flight safety checks)** — validates clean working tree, committed
  plan file, no scope fence overlaps between parallel sessions, and no stale worktrees
  before launching parallel execution.
- **Git worktree isolation** for all parallel sessions — one branch per session
  (`ultraplan/{slug}/session-{N}`), merged with `--no-ff` after wave completion.
- **Merge conflict detection** — if merging a session branch produces conflicts, the merge
  is aborted and conflicting files are reported. No silent data loss.
- **Unconditional worktree cleanup** — worktrees and session branches are always removed,
  even on failure. Manual cleanup commands are reported if automated cleanup fails.
- **Hard rules 11-13** — worktree isolation mandatory, cleanup unconditional, merge
  sequentially with conflict abort.
- **Session-scoped progress file naming** — `--session N` uses
  `.ultraexecute-progress-{slug}-session-{N}.json` to prevent merge conflicts.

### Changed

- Headless launch template uses git worktrees with `cleanup_worktrees` trap on EXIT,
  clean-tree pre-flight check, and sequential merge after each wave.
- Phase 2.6 rewritten with 5-step worktree lifecycle: create → launch → wait → merge → cleanup.

## [1.4.0] - 2026-04-06

### Renamed

- **`/ultraexecute` → `/ultraexecute-local`** — renamed for namespace consistency with `/ultraplan-local` and future-proofing against potential Anthropic naming. File: `commands/ultraexecute.md` → `commands/ultraexecute-local.md`. Note: `ultraexecute_summary` JSON key and `ultraexecute-stats.jsonl` filename are unchanged for backward compatibility.

### Added

- **`convention-scanner` agent** (sonnet) — dedicated agent for discovering coding conventions: naming, directory layout, import style, error handling, test patterns, git commit style, documentation patterns. Replaces inline Explore agent prompt for medium+ codebases.
- **Success Criteria section** in spec template — falsifiable "definition of done" conditions that the spec-reviewer validates and ultraexecute-local uses for verification.
- **Dry-run multi-session preview** — `--dry-run` now shows session groupings, wave structure, billing status, and `claude -p` commands when plan has an Execution Strategy.
- **External verification rule** in headless launch template — wave verification must run commands independently, never parse session logs as proof.
- **Billing preamble** in headless launch template — `unset ANTHROPIC_API_KEY` prevents accidental API billing.
- **Phase mapping comment** in planning-orchestrator — documents how orchestrator phases 1-7 map to command phases 4-10.

### Fixed

- **`git add -A` in escalation** — replaced with targeted staging of only files from completed steps. Prevents staging secrets, binaries, or unrelated work.
- **False `background: true` claim** — command documentation incorrectly stated the orchestrator has `background: true` in its frontmatter. Corrected to explain `run_in_background` on the Agent tool.

### Changed

- Execution Strategy reconciliation in session-decomposer — respects existing `## Execution Strategy` as input instead of re-analyzing from scratch. Warns on file-overlap conflicts.
- Headless launch template uses `--dangerously-skip-permissions` instead of `--allowedTools` for more robust headless execution.
- Session-decomposer updated with `--dangerously-skip-permissions` and `unset ANTHROPIC_API_KEY` for generated scripts.
- Convention Scanner references in command and orchestrator updated to use dedicated plugin agent.
- ROADMAP.md translated from Norwegian to English.
- plugin.json: added homepage, repository, license, keywords. Version bumped to 1.4.0.
- README badge updated to v1.4.0.

## [1.3.0] - 2026-04-06

### Added

- **Session-aware parallel execution** — `/ultraexecute` auto-detects `## Execution Strategy` in plans and orchestrates multi-session parallel execution via `claude -p`. No manual `bash launch.sh` required.
  - **`--fg` flag** — force foreground sequential execution, ignoring Execution Strategy
  - **`--session N` flag** — execute only session N from the plan's Execution Strategy (used by child processes)
  - **Phase 2.5 (Execution strategy decision)** — determines single-session vs multi-session mode
  - **Phase 2.6 (Multi-session orchestration)** — launches parallel `claude -p` sessions per wave, waits for completion, aggregates results
- **Execution Strategy in plan template** — new `## Execution Strategy` section with sessions, waves, scope fences, and execution order. Generated by planning-orchestrator for plans with > 5 steps.
- **Execution Strategy generation in planning-orchestrator** — Phase 5 analyzes step file-overlap to build dependency graph, groups connected components into sessions of 3–5 steps, and organizes sessions into parallel waves.

### Changed

- planning-orchestrator Phase 5 extended with Execution Strategy generation logic
- ultraplan-local Phase 8 now lists Execution Strategy as 10th required plan section
- Plan template includes `## Execution Strategy` section template with grouping rules
- CLAUDE.md updated with new ultraexecute modes and architecture
- plugin.json version bumped to 1.3.0

## [1.2.0] - 2026-04-06

### Added

- **`/ultraexecute` command** — disciplined plan executor with 9-phase workflow. Reads an ultraplan or session spec, executes steps sequentially with strict failure recovery, tracks progress for resume, and reports results in machine-parseable JSON.
  - 4 modes: default (execute), `--resume` (continue from checkpoint), `--dry-run` (validate without executing), `--step N` (single step)
  - Per-step protocol: implement → verify → on-failure handling → checkpoint
  - Failure recovery from plan's On failure clauses (revert/retry/skip/escalate)
  - 3-attempt retry cap per step (initial + 2 retries)
  - Progress file (`.ultraexecute-progress-{slug}.json`) for crash recovery and resume
  - Entry/exit condition checking for session specs
  - Scope fence enforcement for session specs (never-touch file protection)
  - JSON summary block in output for headless log parsing
  - Stats tracking to `ultraexecute-stats.jsonl`

### Changed

- CLAUDE.md restructured with two commands table (plan + execute)
- plugin.json version bumped to 1.2.0

## [1.1.0] - 2026-04-06

### Added

- **`--decompose` mode** — splits an existing plan into self-contained headless sessions. Analyzes step dependencies, groups steps into sessions of 3–5 steps each, identifies parallel execution waves, and generates session specs + dependency graph + launch script.
- **`--export headless` format** — shortcut for `--decompose`. Produces the same session decomposition output.
- **session-decomposer agent** (sonnet) — dedicated agent for plan decomposition. Parses step dependencies, builds dependency graph, groups steps into sessions, generates session specs with scope fences and failure handling.
- **Session spec template** (`templates/session-spec-template.md`) — defines the format for individual session specs: context, scope fence, steps, entry/exit conditions, failure handling, handoff state.
- **Headless launch template** (`templates/headless-launch-template.md`) — template for generating bash launch scripts that execute sessions in parallel waves using `claude -p`.
- **Failure recovery per step** — plan template now includes `On failure:` (revert/retry/skip/escalate) and `Checkpoint:` (git commit) fields for every implementation step.
- **Headless readiness dimension** in plan-critic — new 9th review dimension checking for On failure clauses, Checkpoint fields, and circuit breakers. Weighted at 0.15 in the quality score.

### Changed

- Plan-critic scoring rebalanced: 6 dimensions (was 5), weights adjusted to accommodate headless readiness
- Plan template step format extended with On failure and Checkpoint fields
- Planning-orchestrator Phase 5 updated with failure recovery generation requirements
- CLAUDE.md updated with new agent, modes, and state paths

## [1.0.0] - 2026-04-06

### Added

- **`--quick` mode** — skips exploration agent swarm. Runs interview → lightweight Glob/Grep scan → planning → adversarial review. For when the developer knows the codebase and needs structure, not cartography.
- **`--export` mode** — generates shareable output from an existing plan file. Three formats: `pr` (PR description), `issue` (issue comment), `markdown` (clean plan without internal metadata).
- **task-finder three-tier categorization** — findings categorized as Must-change (must be modified), Must-respect (contract that must not break), or Reference (context/reuse). Replaces flat file list.
- **Adaptive interview depth** — interview adapts to answer quality. Detailed answers trigger fewer, more targeted questions. Short/uncertain answers trigger simpler questions with offered alternatives.
- **Complete `plugin.json` metadata** — author, homepage, repository, license, keywords added.
- **README badges** — version, license, and platform badges.
- **Known limitations section in README** — IaC projects (Terraform, Helm, Pulumi, CDK) get reduced value from exploration agents.
- **Forgejo issue templates** — bug report and feature request YAML templates.
- **CONTRIBUTING.md** — rewritten for honest solo-project model.

### Changed

- plugin.json version bumped to 1.0.0
- Command header updated to Ultraplan Local v1.0
- Orchestrator accepts `mode: quick` in prompt for lightweight scanning path

## [0.4.0] - 2026-04-06

### Added

- **3 new agents** for information-complete planning:
  - `task-finder` — dedicated agent for finding task-relevant files, functions, types, and reuse candidates. Replaces inline Explore agent.
  - `git-historian` — analyzes git log, blame, active branches, code ownership, and hot files for planning context.
  - `spec-reviewer` — reviews spec quality (completeness, consistency, testability, scope clarity) before exploration begins. New Phase 1b/4b.
- **Plan scoring** — plan-critic produces a quantitative quality score (0–100) across 5 weighted dimensions with letter grades (A–D) and verdicts (APPROVE/REVISE/REPLAN).
- **No-placeholder rule** — plan-critic flags TBD, TODO, vague instructions, and underspecified steps as unconditional blockers. 3+ blockers = REPLAN regardless of score.
- **`[ASSUMPTION]` marking** — planning-orchestrator marks all unverifiable claims and warns when >3 assumptions exist.

### Changed

- **All agents run for all codebase sizes.** Small codebases get the same 6 core agents as large ones. Agent turns scale down for small codebases instead of dropping agents entirely.
- Phase 4b (spec review) added before exploration in both command and orchestrator.
- Orchestrator Phase 2 agent table expanded: 6 always + 1 conditional + 1 medium-only.
- Plan-critic review checklist expanded with no-placeholder checks (section 7) and scoring output.
- Orchestrator rules updated with assumption-marking and no-placeholder requirements.

## [0.3.0] - 2026-04-05

### Added

- **planning-orchestrator agent** — dedicated background agent (`background: true`) that handles Phases 4–10 autonomously. Replaces generic background agent spawning with a purpose-built orchestrator running on Opus with `maxTurns: 50`.
- **`effort` and `maxTurns` on all agents** — fine-grained cost and depth control:
  - Exploration agents: `effort: medium`, `maxTurns: 15–20`
  - Review agents (plan-critic, scope-guardian): `effort: high`, `maxTurns: 10`
  - Research-scout: `effort: medium`, `maxTurns: 10`
- **Plugin `settings.json`** — default configuration for mode, research, agent counts, interview limits, and team settings. Users can override in their own settings.
- **Worktree isolation for Agent Teams** — team members use `isolation: "worktree"` to prevent file conflicts during parallel implementation
- **Session tracking** (Phase 12) — writes JSONL records to `${CLAUDE_PLUGIN_DATA}/ultraplan-stats.jsonl` with task metadata, agent counts, review verdicts, and outcomes

### Changed

- Phase 3 now launches the `planning-orchestrator` agent instead of a generic background agent
- Agent Team implementation uses worktree isolation by default

## [0.2.0] - 2026-04-05

### Added

- **Interview phase** — iterative requirements gathering with AskUserQuestion before exploration. Produces a spec file that feeds into planning.
- **7 specialized agents** in `agents/` directory:
  - `architecture-mapper` — deep architecture analysis, anti-patterns, smell detection
  - `dependency-tracer` — import-chain following, data-flow analysis, side-effect catching
  - `test-strategist` — test strategy design based on existing patterns
  - `risk-assessor` — threat modeling, edge cases, failure modes
  - `plan-critic` — dedicated adversarial reviewer with hardcoded critical perspective
  - `scope-guardian` — scope creep and scope gap detection
  - `research-scout` — external research via WebSearch/Tavily for unfamiliar technologies
- **External research capability** — research-scout agent searches documentation, known issues, and best practices when the task involves external/unfamiliar technology
- **Background mode** — default mode runs interview in foreground, then plans in background. User is notified when done.
- **Spec-driven mode** (`--spec`) — skip interview, provide a pre-written spec file, plan entirely in background
- **Foreground mode** (`--fg`) — all phases in foreground, blocks session (v0.1.0 behavior)
- **Agent Team support** — when plan has 3+ independent steps, offers parallel implementation via Agent Teams
- **Spec template** in `templates/spec-template.md`
- **Research Sources section** in plan template for citing external research
- **Dual adversarial review** — plan-critic and scope-guardian run in parallel

### Changed

- Exploration agents replaced with named specialized agents from `agents/` directory
- Agent count scales with codebase: 3 (small), 5 (medium), 7 (large)
- Plan template extended with Research Sources and external tech fields
- Handoff phase supports "execute with team" option
- Command workflow expanded from 9 to 11 phases

## [0.1.0] - 2026-04-05

### Added

- Initial release
- `/ultraplan` slash command with 6-phase workflow
- Parallel Sonnet exploration (3 agents: architecture, task-relevant, conventions)
- Opus-driven plan generation from structured template
- Plan refinement loop with execute/save handoff
- Plan template with context, analysis, steps, alternatives, risks, verification
- Cross-platform support (Mac, Linux, Windows) — pure markdown, no scripts