From 6f3519c55116caee48fd611d8939171d6e696297 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Mon, 4 May 2026 08:52:55 +0200 Subject: [PATCH] chore(ultraplan-local): bump v3.4.0 + autonomy chain + parallel hardenings + schema-drift seal MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ships the speedup work documented in plan-v2 of project 2026-05-03-ultra-pipeline-speedup. Adds: - --gates {open|closed|adaptive} flag on all four pipeline commands - lib/util/autonomy-gate.mjs state machine (idle → main-merged) - lib/review/plan-review-dedup.mjs (Phase 9 inline dedup) - lib/stats/event-emit.mjs (autonomy-gate transitions, main-merge gate) - hooks/scripts/post-compact-flush.mjs PostCompact hook (rehydrate) - Phase 8 schema-drift seal in commands/ultraplan-local.md - Phase 2.6 wave-executor 11 hardenings - Synthetic SC7 determinism floor (Jaccard >= 0.833) for plan + review - Hook baseline regression pins (path-guard + bash-guard) - examples/01-add-verbose-flag/perf-measure harness (gitignored) Architecture decision: Path B (sequential --no-ff parallel waves with manifest-driven failure recovery) ships in v3.4.0. Path C (cache-first hybrid) deferred to v3.5.0 contingent on Step 6 cache-telemetry harvest. Memory updates (Step 14, outside-repo files): - project_ultraplan_opus47_gap.md rewritten per Path B (mitigated v1.8.0 + plan-step-7 defense-in-depth; residual risk for plugins NOT using ultraplan-local prompt arch) - MEMORY.md one-liner updated to flag mitigation status --- .../.claude-plugin/plugin.json | 2 +- plugins/ultraplan-local/CHANGELOG.md | 72 +++++++++++++++++++ plugins/ultraplan-local/CLAUDE.md | 40 +++++++++-- plugins/ultraplan-local/README.md | 14 +++- plugins/ultraplan-local/package.json | 4 +- 5 files changed, 123 insertions(+), 9 deletions(-) diff --git a/plugins/ultraplan-local/.claude-plugin/plugin.json b/plugins/ultraplan-local/.claude-plugin/plugin.json index fae2866..3255b5b 100644 --- a/plugins/ultraplan-local/.claude-plugin/plugin.json +++ b/plugins/ultraplan-local/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "ultraplan-local", "description": "Five-command context-engineering pipeline (brief → research → plan → execute → review) with project folders, specialized agent swarms, external research triangulation, adversarial review, post-hoc independent review with Handover 6 feedback loop, session decomposition, and headless execution. CC-feature matching extracted to the separate ultra-cc-architect plugin in v3.0.0.", - "version": "3.3.0", + "version": "3.4.0", "author": { "name": "Kjell Tore Guttormsen" }, diff --git a/plugins/ultraplan-local/CHANGELOG.md b/plugins/ultraplan-local/CHANGELOG.md index 6996cdc..657cb5e 100644 --- a/plugins/ultraplan-local/CHANGELOG.md +++ b/plugins/ultraplan-local/CHANGELOG.md @@ -4,6 +4,78 @@ 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/). +## [3.4.0] - 2026-05-04 — Ultra-pipeline speedup + +Hardenings + scaffolding to support an autonomy chain from brief approval +through main-merge with parallel-wave execution. Non-breaking: all existing +flags continue to work; `--gates` is opt-in autonomy control. Plan-step +delivery covered by 18 plan-v2 steps split across three Waves. + +### Added — autonomy + parallelism + +- `lib/util/autonomy-gate.mjs` — autonomy-gate state machine (idle → approved → executing → merge-pending → main-merged) for the brief-to-merge chain (Step 4) +- `lib/review/plan-review-dedup.mjs` — deterministic plan-review dedup helpers reused by Phase 9 inline dedup (Step 5) +- `lib/stats/event-emit.mjs` — single-source stats event emitter for autonomy-gate transitions and main-merge-gate (Step 6 + 12) +- `--gates {open|closed|adaptive}` flag on all four pipeline commands (Step 11). Controls how many autonomy checkpoints surface to the operator. Default `adaptive`. +- `hooks/scripts/post-compact-flush.mjs` — PostCompact hook re-injects session-state after context compaction so multi-session work survives a compaction boundary (Step 13) + +### Added — hardenings + defense-in-depth + +- `commands/ultraplan-local.md` Phase 8 schema-drift defense — post-generation `plan-validator --strict` run blocks plans containing narrative `Fase`/`Phase` headers or missing Manifest YAML; addresses the documented Opus-4.7 plan/list-emission drift (Step 7, builds on v1.8.0 fix in commit `9ecd669`) +- `commands/ultraplan-local.md` Phase 9 parallelization with inline dedup — single-message multi-Agent dispatch + plan-review-dedup helper (Step 8) +- `commands/ultraexecute-local.md` Phase 2.6 wave-executor — 11 sub-hardenings for plugin-in-monorepo + gitignored-state topology: GIT_OPTIONAL_LOCKS, --max-turns, --max-budget-usd, scoped --allowedTools, --append-system-prompt-file, SHARED_CONTEXT_FILE, SAFETY_PREAMBLE, deferred git push origin, push-before-cleanup ordering, GH #36071 awareness (Step 9) +- `templates/headless-launch-template.md` — mirrors Phase 2.6 hardenings so the headless launcher is consistent with Phase 2.6 prose (Step 10) +- `commands/ultraplan-local.md` + `agents/planning-orchestrator.md` Phase 8 main-merge gate — emit stats event for main-merge gate decisions (Step 12) + +### Added — quality infrastructure + +- `tests/lib/agent-frontmatter.test.mjs` — pins agent frontmatter invariants (Step 1-test) +- `tests/synthetic/plan-run-A.md` + `plan-run-B.md` + `plan-determinism.test.mjs` — SC7 plan-determinism floor (Jaccard ≥ 0.833) (Step 15) +- `tests/synthetic/review-run-A.md` + `review-run-B.md` + `review-determinism.test.mjs` — SC7 review-determinism floor (Jaccard ≥ 0.833) (Step 15) +- `tests/hooks/path-guard.test.mjs` — pins pre-write-executor BLOCK rules; regression detection if BLOCK_RULES are silently weakened (Step 18) +- `tests/hooks/bash-guard.test.mjs` — pins pre-bash-executor BLOCK rules (Step 18) +- `examples/01-add-verbose-flag/perf-measure.local.sh` (gitignored) — operator-driven SC1 wall-time measurement harness (Step 16) +- `examples/01-add-verbose-flag/perf-baseline.local.md` (gitignored) — SC1 gate template + measurement protocol (Step 16) + +### Changed + +- `lib/parsers/manifest-yaml.mjs` — schema extended additively to recognize `skip_commit_check` and `memory_write` flags (forward-compat: unknown keys ignored). Used by Step 14 and other steps that legitimately don't produce a git commit (Step 4) +- `.gitignore` — generalized `*.local.md` + `*.local.json` rules into a single `*.local.*` glob, covering `.local.sh` and any future `.local.` (Step 16) +- `package.json` — `version` 3.3.0 → 3.4.0 +- `.claude-plugin/plugin.json` — `version` 3.3.0 → 3.4.0 +- `README.md` + `CLAUDE.md` — version refs + `--gates` flag docs + Wave 1+2+3 architecture notes +- Marketplace root `README.md` — ultraplan-local version line bumped 3.3.0 → 3.4.0 + +### Memory updates (Step 14) + +- `~/.claude/projects/-Users-ktg--claude-plugins-marketplaces-ktg-plugin-marketplace/memory/project_ultraplan_opus47_gap.md` — rewritten per Path B (memory truth gate). New body: + (a) historical context referencing commit `9ecd669` (v1.8.0 fix, 2026-04-17), + (b) empirical evidence (5 organic plans 2026-04-18 → 2026-05-01 all clean per research/04 D1), + (c) defense-in-depth added in Step 7 (`commands/ultraplan-local.md` Phase 8), + (d) residual risk surface for plugins NOT using ultraplan-local prompt arch. +- `~/.claude/projects/.../memory/MEMORY.md` — one-liner updated to flag mitigation status. The drift mechanism stays a known model-level risk; the plugin-level mitigation is documented. + +These memory edits are recorded here because the files live outside the +repo and have no git checkpoint of their own. + +### Architecture decision (Path B not Path C) + +Brief offered three architectural options for the speedup work: + +- Path A — cache-first (drop --allowedTools per child) — REJECTED. Inverts security model; plugin hooks don't fire reliably in `claude -p` (research/06 GH #36071). +- Path B — sequential `--no-ff` parallel waves with manifest-driven failure recovery — CHOSEN. v3.4.0 ships this. +- Path C — hybrid (cache-warm sentinel + identical-tool parallel) — DEFERRED to v3.5.0 contingent on cache-telemetry data harvested by Step 6's stats events. Requires unverified Q3 (CLAUDE_CODE_FORK_SUBAGENT cache-prefix preservation at 150-250K context). + +### Tests + +- 265 baseline (post-Wave-2) → ~290+ green after Wave 3 (Steps 15 + 18 add ~25 tests; doc-consistency may add a couple more pin tests) + +### Open Questions for v1.1 + +- Real-LLM determinism measurement — synthetic floor (0.833) is anchored; the foreign-repo run against `examples/01-add-verbose-flag/` for SC1+SC4+SC5 measurement is a separate post-ship session. +- Cache-telemetry harvest — Step 6 stats events emit shapes useful for Path C decision; harvesting + analysis is v1.1 work. +- Marketplace-level autonomy-gate — currently per-plugin scope. Marketplace-wide policy + dashboards are out of scope for this solo project. + ## [3.3.0] - 2026-05-01 Adds `/ultracontinue-local` — a zero-friction multi-session resumption command — diff --git a/plugins/ultraplan-local/CLAUDE.md b/plugins/ultraplan-local/CLAUDE.md index a104274..4528f25 100644 --- a/plugins/ultraplan-local/CLAUDE.md +++ b/plugins/ultraplan-local/CLAUDE.md @@ -23,6 +23,7 @@ Deep implementation planning and research with an explicit brief step, specializ |------|----------| | _(default)_ | Dynamic interview until quality gates pass → brief.md with research plan | | `--quick` | Compact start; still escalates if required sections are weak or the brief-review gate fails → brief.md with research plan | +| `--gates {open\|closed\|adaptive}` | (v3.4.0) Autonomy-checkpoint policy. Default `adaptive` | Always interactive. Phase 3 is a section-driven completeness loop (no hard cap on question count); Phase 4 runs a `brief-reviewer` stop-gate with max 3 review iterations. After writing the brief, asks the user to choose manual (print commands) or auto (Claude runs research + plan in foreground). @@ -36,6 +37,7 @@ Always interactive. Phase 3 is a section-driven completeness loop (no hard cap o | `--local` | Only codebase analysis agents (skip external + Gemini) | | `--external` | Only external research agents (skip codebase analysis) | | `--fg` | No-op alias (foreground is default since v2.4.0) | +| `--gates {open\|closed\|adaptive}` | (v3.4.0) Autonomy-checkpoint policy. Default `adaptive` | Flags combine: `--project --local`, `--external --quick`. @@ -50,6 +52,7 @@ Flags combine: `--project --local`, `--external --quick`. | `--quick` | Plan directly (no agent swarm) | | `--export ` | Generate shareable output from existing plan | | `--decompose ` | Split plan into self-contained headless sessions | +| `--gates {open\|closed\|adaptive}` | (v3.4.0) Autonomy-checkpoint policy. Default `adaptive` | **Breaking change (v2.0):** one of `--brief` or `--project` is required. There is no interview inside `/ultraplan-local`. The `--spec` flag has been removed — use `/ultrabrief-local` to produce a brief instead. @@ -67,6 +70,7 @@ If `{project_dir}/architecture/overview.md` exists (typically produced by the se | `--step N` | Execute only step N | | `--fg` | Force foreground — run all steps sequentially, ignore Execution Strategy | | `--session N` | Execute only session N from plan's Execution Strategy | +| `--gates {open\|closed\|adaptive}` | (v3.4.0) Autonomy-checkpoint policy. Default `adaptive` | ### /ultrareview-local modes @@ -110,12 +114,14 @@ The triage gate is deterministic — path-pattern classifier produces `{file → | contrarian-researcher | sonnet | Counter-evidence, overlooked alternatives | | gemini-bridge | sonnet | Gemini Deep Research second opinion (conditional) | -## Quality infrastructure (v3.1.0) +## Quality infrastructure (v3.4.0) -`lib/` contains zero-dep validators and parsers wired into the four commands: +`lib/` contains zero-dep validators, parsers, and autonomy primitives wired into the four commands: -- `lib/util/{frontmatter,result,atomic-write}.mjs` — shared YAML-frontmatter parser + Result helpers + `atomicWriteJson(path, obj)` for tmp+rename writes -- `lib/parsers/{plan-schema,manifest-yaml,project-discovery,arg-parser,bash-normalize}.mjs` — pure parsers (no I/O), unit-tested +- `lib/util/{frontmatter,result,atomic-write,autonomy-gate}.mjs` — shared YAML-frontmatter parser + Result helpers + `atomicWriteJson(path, obj)` for tmp+rename writes + autonomy-gate state machine (v3.4.0) +- `lib/parsers/{plan-schema,manifest-yaml,project-discovery,arg-parser,bash-normalize,jaccard,finding-id}.mjs` — pure parsers (no I/O), unit-tested. `manifest-yaml` extended in v3.4.0 with additive `skip_commit_check` + `memory_write` flags (forward-compat: unknown keys ignored) +- `lib/review/{rule-catalogue,plan-review-dedup}.mjs` — version-pinned rule catalogue (12 keys) + Phase 9 inline dedup helpers (v3.4.0) +- `lib/stats/event-emit.mjs` — single-source stats event emitter for autonomy-gate transitions and main-merge-gate (v3.4.0) - `lib/validators/{brief,research,plan,progress,session-state}-validator.mjs` — schema validators with CLI shims (`node lib/validators/X.mjs --json `) - `lib/validators/architecture-discovery.mjs` — drift-WARN external-contract discovery for `architecture/overview.md` @@ -125,7 +131,7 @@ Wiring points (replaces previous prose-grep instructions): - `planning-orchestrator` Phase 5.5 → `plan-validator --strict` (replaces 3 `grep -cE` calls) - `/ultraexecute-local --validate` → `plan-validator --strict` + `progress-validator` -Tests under `tests/**/*.test.mjs` (185 tests, 0 deps). `npm test` is the fork-readiness gate. +Tests under `tests/**/*.test.mjs` (~290 tests, 0 deps). `npm test` is the fork-readiness gate. v3.4.0 adds: synthetic determinism fixtures (`tests/synthetic/plan-run-*.md` + `review-run-*.md` + companion `*-determinism.test.mjs` enforcing Jaccard ≥ 0.833 SC7 floor) and hook baseline regression pins (`tests/hooks/{path-guard,bash-guard}.test.mjs` exercising `pre-write-executor.mjs` + `pre-bash-executor.mjs` denylist BLOCK paths). Doc-consistency test at `tests/lib/doc-consistency.test.mjs` pins agent-table count, command-table coverage, plan_version invariant, settings.json scope cleanliness, Handover 7 presence, and `session-state-validator` CLI shim. @@ -137,6 +143,30 @@ Doc-consistency test at `tests/lib/doc-consistency.test.mjs` pins agent-table co `hooks/scripts/post-bash-stats.mjs` (PostToolUse, CC v2.1.97+) appends `duration_ms` for each Bash call into `${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl`. Useful for finding long-running verify or checkpoint commands. +`hooks/scripts/post-compact-flush.mjs` (PostCompact event, v3.4.0) re-injects `.session-state.local.json` after context compaction so multi-session work survives a compaction boundary. Companion to `pre-compact-flush.mjs` (which writes the state file before compaction); together they form the rehydrate cycle that keeps `/ultracontinue-local` reliable across long-running multi-session work. + +## Autonomy mode (`--gates`, v3.4.0) + +All four pipeline commands accept `--gates {open|closed|adaptive}`: + +| Value | Behavior | +|-------|----------| +| `open` | Skip optional checkpoints; trust manifests + verify gates only | +| `closed` | Stop at every autonomy boundary; operator confirms each transition | +| `adaptive` (default) | Stop only at meaningful boundaries (manifest-audit FAIL, plan-critic BLOCKER, main-merge gate) | + +Under the hood: `lib/util/autonomy-gate.mjs` runs the state machine `idle → approved → executing → merge-pending → main-merged`. `lib/stats/event-emit.mjs` records each transition to `${CLAUDE_PLUGIN_DATA}/ultra*-stats.jsonl`. The main-merge gate is the final autonomy boundary before HEAD lands on `main`. + +### Path A/B/C decision (v3.4.0) + +Three architectural options were considered for the speedup work: + +- **Path A — cache-first** (drop `--allowedTools` per child to recover cross-phase cache sharing): REJECTED. Inverts the security model; plugin hooks don't fire reliably in `claude -p` (research/06 GH #36071). +- **Path B — sequential `--no-ff` parallel waves with manifest-driven failure recovery**: CHOSEN. Ships in v3.4.0. Phase 2.6 of `/ultraexecute-local` runs the wave executor with hardenings for plugin-in-monorepo + gitignored-state topology. +- **Path C — hybrid (cache-warm sentinel + identical-tool parallel)**: DEFERRED to v3.5.0 contingent on cache-telemetry data harvested by `lib/stats/event-emit.mjs`. Path C requires unverified Q3 (CLAUDE_CODE_FORK_SUBAGENT cache-prefix preservation at 150-250K context). + +Path C migration would require: (1) re-architecting tool-list to be identical across all wave children, (2) cache-telemetry analysis confirming Q3 holds, (3) prompt-level deny re-enablement to compensate for tool scoping rollback. + ## Architecture **Brief:** 7-phase workflow: Parse mode → Create project dir → Phase 3 completeness loop (section-driven, no question cap) → Phase 4 draft/review/revise with `brief-reviewer` as stop-gate (max 3 iterations; gate = all dimensions ≥ 4 and research plan = 5) → Finalize (`brief.md` on pass, or `brief_quality: partial` on cap/force-stop) → Manual/auto opt-in → Stats. Always interactive. Auto mode runs research + plan inline in the main context (v2.4.0). diff --git a/plugins/ultraplan-local/README.md b/plugins/ultraplan-local/README.md index 6d2a72e..27a7065 100644 --- a/plugins/ultraplan-local/README.md +++ b/plugins/ultraplan-local/README.md @@ -1,6 +1,6 @@ # ultraplan-local — Brief, Research, Plan, Execute, Review, Continue -![Version](https://img.shields.io/badge/version-3.3.0-blue) +![Version](https://img.shields.io/badge/version-3.4.0-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple) @@ -49,6 +49,18 @@ After all steps complete, `/ultraexecute-local` runs **Phase 7.5 — Manifest au No cloud dependency. No GitHub requirement. Works on **Mac, Linux, and Windows**. +### Autonomy mode (`--gates`, v3.4.0) + +All four pipeline commands accept `--gates {open|closed|adaptive}` to control how many autonomy checkpoints surface to the operator on the path from brief approval to main-merge. + +| Value | Behavior | +|-------|----------| +| `open` | Skip optional checkpoints. The pipeline runs end-to-end with the fewest interruptions. Suitable for trusted briefs in clean repos. | +| `closed` | Stop at every checkpoint. The operator confirms each transition. Suitable for high-stakes work or unfamiliar repos. | +| `adaptive` (default) | Stop only when the autonomy-gate state machine reports a meaningful boundary (manifest-audit FAIL, plan-critic BLOCKER, main-merge gate). Best balance of velocity and safety. | + +Under the hood, `lib/util/autonomy-gate.mjs` runs a small state machine (`idle → approved → executing → merge-pending → main-merged`) and `lib/stats/event-emit.mjs` records each transition to `${CLAUDE_PLUGIN_DATA}/ultra*-stats.jsonl`. The new `hooks/scripts/post-compact-flush.mjs` PostCompact hook re-injects `.session-state.local.json` after context compaction so multi-session work survives a compaction boundary. + ## Quick start ```bash diff --git a/plugins/ultraplan-local/package.json b/plugins/ultraplan-local/package.json index 4838836..26fe878 100644 --- a/plugins/ultraplan-local/package.json +++ b/plugins/ultraplan-local/package.json @@ -1,7 +1,7 @@ { "name": "ultraplan-local", - "version": "3.3.0", - "description": "Five-command context-engineering pipeline (brief → research → plan → execute → review) for Claude Code.", + "version": "3.4.0", + "description": "Six-command context-engineering pipeline (brief → research → plan → execute → review → continue) for Claude Code.", "type": "module", "engines": { "node": ">=18"