open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

chore(ultraplan-local): bump v3.4.0 + autonomy chain + parallel hardenings + schema-drift seal

Browse source 
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:
Kjell Tore Guttormsen 2026-05-04 08:52:55 +02:00
commit 6f3519c551
5 changed files with 123 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

40
plugins/ultraplan-local/CLAUDE.md
View file

@ -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).