From 1486368a2bb11470506968c171201834a8e4712b Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Fri, 1 May 2026 06:31:42 +0200 Subject: [PATCH] chore(release): ultraplan-local v3.1.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Quality program release. Spor 0+1+2+3 all delivered. - 109 zero-dep tests gate fork-readiness - 5 validators wired into 4 commands as CLI shims - HANDOVER-CONTRACTS.md: single source of truth for 5 pipeline handovers - PreCompact-hook (P0) closes progress.json drift; --resume now works - Semantic plan-critic catches paraphrased deferred decisions - examples/01-add-verbose-flag/: hand-calibrated end-to-end pipeline demo - 4 hooks total (pre-bash, pre-write, session-title, post-bash-stats, pre-compact-flush) - SECURITY.md + Extending-the-plugin docs CC v2.1.x feature adoption: F8 (MCP_CONNECTION_NONBLOCKING), F9 (sessionTitle), F3 (duration_ms), F12 (disableSkillShellExecution). F2 (hook 'if'-field) deferred — universal protection wins. Pre-flight verification: - npm test → 109 pass - plan-validator --strict templates/plan-template.md → READY - plan-validator --strict tests/fixtures/plan-fase-narrative.md → FAIL (expected) - grep smallCodebase|mediumCodebase|largeCodebase → 0 hits Version bumped: package.json, plugin.json, README badge, root README, root CLAUDE.md. Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 2 +- README.md | 2 +- .../.claude-plugin/plugin.json | 2 +- plugins/ultraplan-local/CHANGELOG.md | 88 +++++++++++++++++++ plugins/ultraplan-local/README.md | 2 +- plugins/ultraplan-local/package.json | 2 +- .../tests/fixtures/plan-fase-narrative.md | 25 ++++++ 7 files changed, 118 insertions(+), 5 deletions(-) create mode 100644 plugins/ultraplan-local/tests/fixtures/plan-fase-narrative.md diff --git a/CLAUDE.md b/CLAUDE.md index 87bce2c..a201c2a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,7 +13,7 @@ plugins/ llm-security/ v6.0.0 — Security scanning, auditing, threat modeling ms-ai-architect/ v1.8.0 — Microsoft AI architecture (Cosmo Skyberg persona) okr/ v1.0.0 — OKR guidance for Norwegian public sector - ultraplan-local/ v3.0.0 — Brief, research, plan, execute (four-command universal pipeline) + ultraplan-local/ v3.1.0 — Brief, research, plan, execute (four-command universal pipeline) ultra-cc-architect/ v0.1.0 — Claude-Code-specific architecture matching + skill-factory (extracted from ultraplan-local in v3.0.0) ``` diff --git a/README.md b/README.md index cc96f6e..669cbd5 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ Key commands: `/config-audit posture`, `/config-audit feature-gap`, `/config-aud --- -### [Ultra {brief | research | plan | execute} - local](plugins/ultraplan-local/) `v3.0.0` +### [Ultra {brief | research | plan | execute} - local](plugins/ultraplan-local/) `v3.1.0` Deep requirements gathering, research, implementation planning, and self-verifying execution with specialized agent swarms, adversarial review, and failure recovery. diff --git a/plugins/ultraplan-local/.claude-plugin/plugin.json b/plugins/ultraplan-local/.claude-plugin/plugin.json index b1a7180..4f8e2fd 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": "Four-command context-engineering pipeline (brief → research → plan → execute) with project folders, specialized agent swarms, external research triangulation, adversarial review, session decomposition, and headless execution. CC-feature matching extracted to the separate ultra-cc-architect plugin in v3.0.0.", - "version": "3.0.0", + "version": "3.1.0", "author": { "name": "Kjell Tore Guttormsen" }, diff --git a/plugins/ultraplan-local/CHANGELOG.md b/plugins/ultraplan-local/CHANGELOG.md index 9c7aa43..2cd26ff 100644 --- a/plugins/ultraplan-local/CHANGELOG.md +++ b/plugins/ultraplan-local/CHANGELOG.md @@ -4,6 +4,94 @@ 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.1.0] - 2026-05-01 + +Quality program: pure quality lift, no scope creep. Built around the +fork-er onramp — anyone cloning this plugin should get value out of +the box. 109 zero-dep tests gate readiness. + +### Added — testing & validation infrastructure (Spor 0+1) + +- `package.json` with `node:test` runner and zero npm dependencies (`engines.node>=18`) +- `lib/util/{result,frontmatter}.mjs` — Result-shape helpers and a hand-rolled YAML subset parser supporting list-of-dicts (the form used by `must_contain` in real plans) +- `lib/parsers/{plan-schema,manifest-yaml,project-discovery,arg-parser,bash-normalize}.mjs` — primitive parsers +- `lib/validators/{brief,research,plan,progress}-validator.mjs` and `lib/validators/architecture-discovery.mjs` — wrappers over parsers, each with a CLI shim (`if (import.meta.url === ...)`) so they can be invoked from Bash via `node ${CLAUDE_PLUGIN_ROOT}/lib/validators/X.mjs` +- `tests/lib/*` + `tests/validators/*` — 109 tests +- `tests/lib/doc-consistency.test.mjs` — pins agent-table count, command-table coverage, plan_version invariant, and settings.json scope cleanliness; first-red surfaces drift between docs and code + +### Changed — wiring (Spor 1) + +| Site | Was | Is | +|------|-----|-----| +| `/ultrabrief-local` Phase 4g | implicit trust | `node lib/validators/brief-validator.mjs --json` | +| `/ultraplan-local` Phase 1 | inline frontmatter parse + `test -f` | brief-validator `--soft` + research-validator `--dir` + architecture-discovery | +| `agents/planning-orchestrator.md` Phase 5.5 | three `grep -cE` calls | single `node lib/validators/plan-validator.mjs --strict --json` | +| `/ultraexecute-local` Phase 2.3 (`--validate`) | inline regex | `plan-validator --strict` + `progress-validator` | + +Validators default to `strict: false`. Only `--validate` mode and Phase 5.5 use `--strict`. Existing in-flight projects under `.claude/projects/` continue to work. + +### Added — handover contracts (Spor 2) + +- `docs/HANDOVER-CONTRACTS.md` (~310 lines) — single source of truth for the 5 pipeline handovers (brief→research, research→plan, architecture→plan EXTERNAL, plan→execute, progress.json resume). Per-handover sections: Producer / Consumer / Path conventions / Frontmatter schema / Body invariants / Validation strategy / Versioning / Failure modes. Architecture handover is explicitly an external contract — drift-WARN never drift-FAIL. + +### Added — PreCompact resume integrity (Spor 2, P0 fix) + +- `hooks/scripts/pre-compact-flush.mjs` — PreCompact-event hook (CC v2.1.105+) that reconciles `progress.json` with git history before context compaction. Atomic write (tmp + rename), monotonic only (current_step never decreases), fail-open (always exit 0). Closes the documented progress.json drift bug from `docs/ultraexecute-v2-observations-from-config-audit-v4.md` — `--resume` now works after long conversations. +- `hooks/hooks.json` registers the PreCompact entry. + +### Added — examples (Spor 3) + +- `examples/01-add-verbose-flag/` — calibrated end-to-end pipeline demo for a small realistic task (add `--verbose` to a CLI parser). Includes `brief.md`, `research/01-cli-parser-conventions.md`, `plan.md` (7 steps with full manifest YAML), and `progress.json`. All four artifacts pass their respective validators. Hand-calibrated, not LLM-generated, so the example stays reviewable. +- `examples/REGENERATED.md` per example documents calibration date and regeneration triggers. +- `examples/README.md` walks fork-ers through what to study first. + +### Changed — plan-critic semantic rubric (Spor 3, P0 fix) + +`agents/plan-critic.md` rule #7 split into two parts: + +1. **Literal blockers** (exact-string): `TBD`, `TODO`, `FIXME`, `XXX` always fire. +2. **Semantic rubric** (instruction-shaped): 8 deferred-decision tests covering vague modifiers, imperatives without targets, forward references without expansion, volume/quality without spec, edge-cases delegated, production-readiness delegated, path mismatch, and over-stuffed steps. + +Calibrated against 5-phrase corpus the v3.0 exact-string blacklist missed: "implement as needed", "wire it up", "make it production-ready", "add tests where appropriate", "handle edge cases" — all five now flagged with rule citations. + +### Added — CC v2.1.x feature adoption (Spor 3) + +- **F8** — `MCP_CONNECTION_NONBLOCKING=true` documented under "Headless multi-session tuning" in README (CC v2.1.89+) for parallel `claude -p` sessions +- **F9** — `hooks/scripts/session-title.mjs` (UserPromptSubmit, CC v2.1.94+) sets `ultra::` titles for ultra invocations +- **F3** — `hooks/scripts/post-bash-stats.mjs` (PostToolUse, CC v2.1.97+) appends `duration_ms` per Bash call to `${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl` +- **F12** — `disableSkillShellExecution: true` recommended in README "Security hardening" + `SECURITY.md` (CC v2.1.91+) for fork-ers handling untrusted plans + +**Deferred:** F2 (hook `if`-field scoping). The plan called for scoping pre-bash-executor / pre-write-executor to ultraexecute sessions to "reduce false-positives in brief/plan" — but brief/plan don't issue Bash commands that match the destructive denylist, so the rationale doesn't hold. Universal protection wins. + +### Added — security & extension docs (Spor 3) + +- `SECURITY.md` — Forgejo private-issue reporting, supported = current minor only, scope (4 hooks + denylist), hardening recommendations +- `docs/architect-bridge-test.md` — manual smoke checklist for the ultraplan ↔ ultra-cc-architect bridge (1 paragraph, intentionally not CI) +- `README.md` — new "Extending the plugin" section: how to add an agent, switch the planning model, disable external research, find the data contract, disable the architect bridge + +### Removed — vestigial config (Spor 0) + +- `settings.json` `exploration` and `agentTeam` blocks (read by zero code; verified via grep before deletion) +- `docs/ultra-suite-brief_2.md` archived as `_archive-` (was paste from another plugin's work) + +### Tests + +109 tests, all green. `npm test` is the fork-readiness gate. + +### Hook table (after v3.1.0) + +| Hook | Event | CC version | Purpose | +|------|-------|-----------|---------| +| pre-bash-executor.mjs | PreToolUse(Bash) | 2.0+ | Block destructive shell commands | +| pre-write-executor.mjs | PreToolUse(Write) | 2.0+ | Block writes to sensitive paths | +| session-title.mjs | UserPromptSubmit | 2.1.94+ | Set `ultra::` titles | +| post-bash-stats.mjs | PostToolUse(Bash) | 2.1.97+ | Log Bash `duration_ms` to JSONL | +| pre-compact-flush.mjs | PreCompact | 2.1.105+ | Reconcile progress.json with git history | + +### Files changed + +This release is plugin-internal — no breaking changes to artifact formats or CLI surface. Forkers should `npm test` after pulling to confirm readiness. + ## [3.0.0] - 2026-04-30 ### Architect extracted to its own plugin diff --git a/plugins/ultraplan-local/README.md b/plugins/ultraplan-local/README.md index 1da3d4a..34b3ccf 100644 --- a/plugins/ultraplan-local/README.md +++ b/plugins/ultraplan-local/README.md @@ -1,6 +1,6 @@ # ultraplan-local — Brief, Research, Plan, Execute -![Version](https://img.shields.io/badge/version-3.0.0-blue) +![Version](https://img.shields.io/badge/version-3.1.0-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple) diff --git a/plugins/ultraplan-local/package.json b/plugins/ultraplan-local/package.json index 046c5e4..42bdaa3 100644 --- a/plugins/ultraplan-local/package.json +++ b/plugins/ultraplan-local/package.json @@ -1,6 +1,6 @@ { "name": "ultraplan-local", - "version": "3.0.0", + "version": "3.1.0", "description": "Four-command context-engineering pipeline (brief → research → plan → execute) for Claude Code.", "type": "module", "engines": { diff --git a/plugins/ultraplan-local/tests/fixtures/plan-fase-narrative.md b/plugins/ultraplan-local/tests/fixtures/plan-fase-narrative.md new file mode 100644 index 0000000..5f76e86 --- /dev/null +++ b/plugins/ultraplan-local/tests/fixtures/plan-fase-narrative.md @@ -0,0 +1,25 @@ +# Bad plan — narrative drift fixture + +plan_version: 1.7 + +This fixture exists ONLY to verify that `plan-validator --strict` +rejects Opus 4.7-style narrative drift (Fase / Phase / Stage / Steg +headings instead of `### Step N:`). It MUST FAIL strict validation. + +## Context + +This is what an LLM might produce when it ignores the literal-step +schema and falls back to narrative phasing. The validator should +catch this and refuse. + +### Fase 1: Forberedelse + +Vi må først forstå koden. Les filene under src/. + +### Fase 2: Implementering + +Skriv ny kode i nye filer. + +### Fase 3: Verifisering + +Kjør testene og fiks eventuelle feil.