chore(ultraplan-local): bump v3.4.0 + autonomy chain + parallel hardenings + schema-drift seal
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
This commit is contained in:
parent
bc1333ec17
commit
6f3519c551
5 changed files with 123 additions and 9 deletions
|
|
@ -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"
|
||||
},
|
||||
|
|
|
|||
|
|
@ -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.<ext>` (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 —
|
||||
|
|
|
|||
|
|
@ -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 <dir> --local`, `--external --quick`.
|
||||
|
||||
|
|
@ -50,6 +52,7 @@ Flags combine: `--project <dir> --local`, `--external --quick`.
|
|||
| `--quick` | Plan directly (no agent swarm) |
|
||||
| `--export <pr\|issue\|markdown\|headless> <plan>` | Generate shareable output from existing plan |
|
||||
| `--decompose <plan>` | 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 <path>`)
|
||||
- `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).
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# ultraplan-local — Brief, Research, Plan, Execute, Review, Continue
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue