v0.4.1 — Plugin Version Fix

v0.4.1 — Plugin Version Fix + Multi-Runner Support

Fixes the plugin version detection issue that caused claude plugin install to always install v0.3.4.

How to Update

# 1. Clear stale cache
rm -rf ~/.claude/plugins/cache/quantum-loop

# 2. Reinstall (from home directory)
cd ~
claude plugin uninstall quantum-loop@quantum-loop --scope project 2>/dev/null
claude plugin install quantum-loop@quantum-loop

# 3. Verify
/plugin   # Should show Version: 0.4.1

What Was Fixed

Root cause: Claude Code reads version from .claude-plugin/plugin.json, which was stuck at 0.3.4. We had bumped plugin.json (root) and marketplace.json but missed the third version file. All three now match at 0.4.1.

File	Before	After
.claude-plugin/plugin.json	0.3.4	0.4.1
plugin.json	0.3.6	0.4.1
.claude-plugin/marketplace.json	0.4.0	0.4.1

All v0.4.0 Features Included

• 7 runner manifests: Claude (guaranteed), Codex (tested), Copilot/Cursor/Gemini/Amp/Aider (experimental)
• Runner adapter layer: --tool codex to switch runners via JSON manifests
• Signal heuristic fallback for non-Claude runners
• Security hardening: path traversal protection, metacharacter validation, hook containment
• 148 tests across 5 test suites, 2 rounds of 6-agent review
• Bug fixes: json_atomic_update defined, sequential mode status updates, heuristic false-positive filtering

Full Changelog: v0.4.0...v0.4.1

v0.4.0 — Multi-Runner Support

Multi-Runner Support — Universal CLI Orchestrator

Quantum-loop can now orchestrate any terminal-based coding agent CLI, not just Claude Code. Switch runners with --tool codex and add custom runners by dropping a JSON manifest in runners/.

Supported Runners

Runner	Binary	Tier	Install
Claude Code	claude	Guaranteed	npm i -g @anthropic-ai/claude-code
OpenAI Codex	codex	Tested	npm i -g @openai/codex
GitHub Copilot CLI	copilot	Experimental	npm i -g @github/copilot
Cursor Agent	agent	Experimental	cursor.sh
Google Gemini CLI	gemini	Experimental	npm i -g @google/gemini-cli
Amp (Sourcegraph)	amp	Experimental	npm i -g @sourcegraph/amp
Aider	aider	Experimental	pip install aider-chat

Usage

# Default (Claude Code — zero behavior change)
./quantum-loop.sh --max-iterations 20

# Run with Codex
./quantum-loop.sh --tool codex --max-iterations 20

# Run with Gemini
./quantum-loop.sh --tool gemini --max-iterations 10

# Windows PowerShell
.\quantum-loop.ps1 -Tool codex -MaxIterations 20

# Add a custom runner
cp runners/claude.json runners/my-runner.json  # edit fields
bash schemas/validate.sh runners/my-runner.json  # validate

What's New

• Runner adapter layer (lib/runner.sh) — runner_load(), runner_build_cmd(), runner_ensure_instructions(), runner_inject_preamble(), runner_parse_output()
• JSON manifest system (runners/*.json) — Declarative config per runner: binary, flags, prompt delivery method, instruction file, signal protocol settings
• Signal heuristic fallback (lib/signal-heuristics.sh) — Infers pass/fail from git commits and test output when non-Claude runners don't emit quantum signals
• Preamble injection (runners/preamble.md) — Teaches non-Claude runners the signal protocol
• Hook system (runners/hooks/*.sh) — Optional per-runner shell overrides (Codex sandbox warning, Copilot autopilot flags)
• JSON Schema (schemas/runner.schema.json) — Formal schema with validation script
• Full platform parity — quantum-loop.sh, quantum-loop.ps1, templates/quantum-loop.sh all support --tool

Security Hardening

• Tool name validation (^[A-Za-z0-9_-]+$) prevents path traversal
• Binary name and manifest flag metacharacter rejection
• Hook file path containment checks
• printf '%q' prompt escaping
• Test command allowlist with array execution (no eval)
• Template manifest loading via fs.readFileSync + process.argv (no require() injection)

Testing

• 148 tests across 5 test suites, all passing
• 2 rounds of 6-agent code review (risk, correctness, security, test-quality, cross-file-impact, consistency)
• Codex CLI 22-assertion end-to-end test
• Claude command regression gate

Bug Fixes

• json_atomic_update() was called but never defined — added to lib/json-atomic.sh
• Sequential mode now correctly updates story .status and retry counters
• Heuristic error detection no longer false-positives on "0 errors" output
• Windows line endings fixed in lib/json-atomic.sh

Closes #19

Full Changelog: v0.3.7...v0.4.0

v0.3.7 — Hardening Layer v2

Hardening Layer v2

Comprehensive post-mortem fixes addressing 7 systemic issues found during the 19-story parallel execution run.

New modules

• lib/init-guard.sh — Pre-flight environment detection (OneDrive/long-path warnings, worktree cleanup, stale ref pruning, forceSequential when temp dir not writable)
• lib/resilience.sh — WIP commits after each task, squash-on-merge for clean history, crash recovery with resume detection (supersedes crash-recovery.sh)
• lib/merge-semantic.sh — AST-aware 3-way merge via ts-morph (TypeScript), libcst (Python), and diff3 fallback

Modified modules

• lib/merge-strategy.sh — quantum.json backup/restore + stash exclusion, semantic merge delegation before ours/theirs
• lib/materialize.sh — Smart threshold: materialize contract types in fileConflicts even with single consumer
• lib/monitor.sh — Delegates to squash_and_merge() as primary merge path
• lib/spawn.sh — build_agent_prompt() accepts completed_tasks for WIP resume

Agent prompt updates

• orchestrator.md — init-guard/resilience integration, scoped git add, new quantum.json field docs
• implementer.md — WIP commit instructions
• type-auditor.md — Scoped git add

Test coverage

• 9 unit test suites, 4 integration tests — 487 assertions total
• Integration tests cover: init-to-merge flow, semantic merge conflict, crash recovery WIP, stash isolation

Issues addressed

1. Windows/OneDrive long-path failures → init-guard.sh detects and warns at init
2. quantum.json corruption during git stash/pop → backup/restore + :(exclude) pathspec
3. Lossy ours/theirs merge resolution → AST-aware semantic merge before fallback
4. Lost agent progress on session restart → WIP commits + detect_resumable_work()
5. git index.lock contention from git add -A → scoped git add on main branch
6. Worktree accumulation from previous sessions → cleanup_orphan_dirs() at init
7. Duplicate types across parallel stories → materialize on fileConflicts too

Full Changelog: v0.3.6...v0.3.7

v0.3.6 - Modular Merge Hardening

Modular Merge Hardening

7 independent modules for automated merge conflict resolution in parallel execution mode. Eliminates manual merge intervention by auto-resolving conflicts based on file category.

New Modules

• barrel-regen — Auto-regenerate barrel/index files (TS/JS/Python/Rust) after merge
• dep-manifest — Protect dependency manifests with --ours + re-install
• merge-strategy — Category-based conflict resolution with 5 configurable rules
• known-failures — Track known test failures across waves, distinguish regressions from pre-existing
• worktree lifecycle — Register, cleanup stale/merged, pre-spawn slot checking

Integrations

• monitor.sh delegates to merge-strategy with graceful fallback
• orchestrator.md hooks all modules at correct lifecycle points (pre-wave, spawn, post-merge, post-wave)
• ql-plan documents contractBreaking and fixes fields for interface cascade prevention
• quantum.json.example schema extended with knownFailures, worktreeTracking, mergeStrategy

Stats

• 23 files changed, +9,762 / -796 lines
• 570 test assertions across 14 test suites (8 unit + 6 integration)
• 0 shellcheck warnings
• 17 stories executed in 5 parallel waves, all first-attempt passes

v0.3.5 — DAG Intelligence

What's New

DAG Intelligence — Post-generation validation system for ql-plan that detects and fixes planning defects before execution.

New Agents

• dag-validator — Coordinator that spawns 3 parallel specialists, merges reports, applies restructuring with cycle detection, creates stub stories, and produces a DAG Health Report
• bottleneck-analyzer — Detects linear chains > 2, single-story waves, and fan-out blockers (5+ downstream); auto-extracts types-only stubs
• duplication-detector — Hybrid keyword pre-filter (Jaccard similarity) + LLM semantic verification; extracts shared utility stubs
• conflict-auditor — Auto-computes fileConflicts from filePaths intersections with severity classification (high/medium/low)

New Schema Fields

• storyType on stories (types-only, logic, config, test) — enables safe restructuring decisions
• dagValidation block — traceability for bottlenecks, duplication risks, computed conflicts, and stubs
• severity on fileConflicts entries — high-severity conflicts get synthetic dependsOn edges preventing co-scheduling

New Reference Doc

• skills/ql-plan/references/dag-validation.md — configurable stop-words, Jaccard threshold, bottleneck heuristics, severity rules, barrel file patterns, plan size thresholds

ql-plan Integration

• Story Type Tagging — planner auto-tags every story with storyType
• Step 7: DAG Validation — automatic post-generation validation with stub flesh-out, revert-on-failure, and Health Report output
• Idempotency — re-running on an unchanged plan skips validation

Context Window Optimization

• Agent prompts reduced 29% (1,156 → 825 lines) following skill-creator principles
• Removed redundant JSON examples, algorithm explanations Claude already knows, and repetitive Rules sections

Bug Fixes (from PR review)

• Blocker story now correctly receives dependsOn edge to its own stub
• Missing waveAssignment on stubs defaults to "unknown"/low severity (was wave 0 causing false medium)
• Synthetic dependency injection sorts by wave order then priority (was priority only)
• Re-run Kahn's after stub creation before conflict auditing
• quantum.json.example schema aligned with actual agent output formats

Triggered by: 2026-03-24 post-mortem — issues #5 (sequential bottleneck), #8 (duplicate implementation), #9 (incomplete fileConflicts)

Full PR: #20

v0.3.4 — Progressive Materialization

What's New

Progressive Materialization — 5-layer defense system against type divergence in parallel worktree execution.

Layers

• L1: Structural contracts with shapes and definitions in ql-plan
• L2: Selective contract materialization before each wave (lib/materialize.sh)
• L3: Escalate-on-conflict merge strategy (lib/monitor.sh)
• L4: Post-merge typecheck gate with baseline comparison (lib/monitor.sh)
• L5: Wave-end type audit with feedback loop (lib/type-audit.sh)

New Files

• lib/materialize.sh — contract materialization with language detection (TS/Python/Go)
• lib/type-audit.sh — wave-end duplicate type detection
• agents/type-auditor.md — short-lived agent for type consolidation
• skills/ql-plan/references/contract-shapes.md — language-specific shape examples

Schema Changes

• Enhanced contracts.shared_types with shape, definition, owner, consumers, definitionFile
• typecheckCommand field with auto-detection
• execution.materializedContracts and execution.discoveredContracts

Full design: docs/plans/2026-03-18-worktree-isolation-fix-design.md

v0.3.3 — Parallel Execution Hardening

Parallel Execution Hardening

Field-tested fixes from a 14-story parallel execution run (ql/image-mode feature). Addresses all critical issues discovered during real-world parallel agent orchestration.

Fixed

• File-conflict-aware DAG scheduling — filter_file_conflicts() prevents spawning parallel agents that share files. Wired into both dispatch sites in quantum-loop.sh.
• Worktree nesting prevention — _resolve_repo_root() resolves nested paths to top-level repo, preventing .ql-wt/ inside .ql-wt/ path explosion.
• Windows long-path fallback — Paths > 200 chars fall back to repo-namespaced temp directory. Emergency /tmp last resort.
• Editable install race — PYTHONPATH injection replaces pip install -e . in parallel worktrees (src-layout + flat-layout).
• Worktree cleanup retry — 3 attempts with 2s delay for Windows file locks; rm -rf only as fallback.
• Cross-wave conflict detection — filter_file_conflicts seeds with in_progress stories' files.

Added

• Inline review gate (Step 3B.4) — Spec compliance + code quality after each parallel merge.
• Full-feature code review (Step 4B) — Holistic review of entire branch diff for cross-story consistency, architecture coherence, and security.
• 14 new tests — 79 total (35 DAG + 15 worktree + 29 spawn), all passing.

Upgrade

/plugin marketplace update quantum-loop

Or pull latest and restart Claude Code.

Full changelog: CHANGELOG.md

v0.3.2 — Enforce Worktree Isolation

Fixed

• Mandatory worktree isolation — isolation: "worktree" is now documented as MANDATORY for parallel execution, with specific failure modes listed (bash contention, file conflicts, quantum.json races)
• Correct tool naming — orchestrator now references "Agent tool" (not "Task tool") with exact parameter names
• Atomic quantum.json updates — new Step 3B.1 batches all in_progress status writes into a single atomic update before spawning agents
• Monitor loop — changed from polling to waiting for Claude Code completion notifications
• State management discipline — only the orchestrator writes quantum.json; Edit tool banned (use Python/jq); multi-story updates batched into one write
• Implementer parallel mode — implementer agents in worktrees no longer edit quantum.json (stale copy); report via output message instead
• Anti-rationalization guards — 2 new entries blocking "skip worktree" and "worktrees won't work on this OS" excuses

Full changelog: https://github.com/andyzengmath/quantum-loop/blob/master/CHANGELOG.md#032---2026-03-10

v0.3.1 — Post-Mortem Fixes

What's New

Closes all 7 issues from the Math Research Agent post-mortem — the first real-world 34-story parallel execution. Delivered in 3 layers: schema, agent protocols, and runtime enforcement.

New Schema Fields

• contracts — cross-story agreements for shared values (secret keys, env vars, types). Implementers enforce exact values; propose-and-wait on disagreements.
• wiring_verification — grep-based mechanical check on tasks that create modules. Spec-reviewer verifies: missing string = fail, present = pass.
• consumedBy — declares cross-story consumption. Implementers import existing components instead of inlining duplicates.
• coverageThreshold — configurable test coverage gate. Quality-reviewer runs coverage tool and fails stories below threshold.
• staleThresholdMinutes + startedAt — stale story detection with configurable timeout (default 20min, CLI-overridable).

Agent Protocol Improvements

• Coding standards enforcement — quality-reviewer reads CLAUDE.md, .claude/rules/, and codebasePatterns; violations are CRITICAL severity
• Coverage gate — quality-reviewer detects coverage tool (c8/nyc/pytest-cov/go test/JaCoCo) and enforces threshold
• Contract reading — implementer reads contracts before implementing; propose-and-wait if disagreeing
• Lifecycle awareness — ql-brainstorm question #7 (LIFECYCLE) and ql-spec Pre-Save lifecycle checklist
• testFirst mandate — ql-plan defaults testFirst: true for all tasks; exempt tasks require justification

Runtime Enforcement

• Stale story detection in orchestrator, quantum-loop.sh, quantum-loop.ps1, and templates
• Final verification sweep — full test suite before COMPLETE; failure blocks completion
• Execution observations — auto-generated post-mortem doc after every run; optional GitHub issue filing
• CLAUDE.md defensive check — warns and skips stories in_progress by other agents

Bug Fixes

• Atomic in_progress + startedAt write prevents crash window
• startedAt cleared on all exit paths (BLOCKED, timeout, merge conflict, unrecognized signal)
• Null-guard failureLog in observations jq
• startedAt cleared in crash recovery

Tests

• 4 new shell test files (14 tests): stale detection, startedAt lifecycle, final sweep, observations

Full Changelog: v0.3.0...v0.3.1

v0.3.0 - Cross-Story Integration Layer

Informed by real-world field data: 14-story implementation where 100% of bugs were cross-story integration issues, 0% caught by per-story review gates.

Added

• Cross-story integration review (ql-review Stage 3) — traces call chains across story boundaries using LSP (grep fallback). Runs after dependency chains complete and as final gate before COMPLETE.
• Final integration gate — orchestrator runs import smoke test, full test suite, and dead code scan before declaring COMPLETE
• File-touch conflict detection — ql-plan flags parallel stories modifying same file, adds reconciliation tasks, stores conflicts in quantum.json metadata (fileConflicts)
• Consumer verification pattern — wiring acceptance criteria belong on the consumer story, not the creator
• Edge case test requirements — boundary values, type variations, collision scenarios, scale tests required for all testFirst tasks
• Edge case reference doc (references/edge-cases.md) — Python, JS, Go, Rust testing gotchas. Implementer reads it at the start of every testFirst task.
• Import chain verification — ql-verify requires integration evidence for multi-story features
• Cursor marketplace manifest (.cursor-plugin/plugin.json)

Changed

• Orchestrator Step 4 split into Final Integration Gate + Completion
• Implementer always reads references/edge-cases.md for testFirst tasks
• All versions bumped to 0.3.0 (plugin.json, marketplace.json, cursor plugin.json)