@chllming/wave-orchestration 0.9.9 → 0.9.11

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.9.11 - 2026-04-07
+
+### Fixed
+- **Verdict parsing: first-match-wins** — `parseVerdictFromText()` now returns the **first** regex match instead of the last. In append-only cont-QA report files, stale `Verdict: BLOCKED` entries from earlier attempts would linger at the bottom of the file while newer `Verdict: PASS` entries were written above them. The last-match-wins behavior caused the cont-QA gate to read the stale blocked verdict, creating an infinite retry loop. This was the root cause of 17 blocked waves in React Word Editor (DOCX W20+).
+- **Log verdict priority over report verdict** — `buildAgentExecutionSummary()` now prefers the log-based `[wave-verdict]` marker over the report file `Verdict:` line. The log is authoritative for the current run, while report files may accumulate conflicting entries across retry attempts.
+- **Integration steward closure is now sticky** — When the integration steward (A8) explicitly reports `state=ready-for-doc-closure` with zero blockers, synthesized proof gaps and doc gaps from implementation agent validation are cleared from the integration summary. Previously, `buildWaveIntegrationSummary()` would re-inject gaps derived from agent summaries on every `refreshDerivedState()` call, overriding the steward's explicit sign-off and causing unnecessary retry cycles (observed as 15+ loops in DOCX W20).
+
+### Added
+- Test suite for `parseVerdictFromText` covering first-match behavior, null/empty inputs, multi-verdict report files, and `[wave-verdict]` marker parsing.
+
+## 0.9.10 - 2026-04-07
+
+### Fixed
+- **Run-state history bloat**: The `run-state.json` history array grew unbounded, reaching 500MB+ in long-running repos. Each reconciliation cycle appended entries with full evidence objects (file hashes, status paths) that were never pruned. Fixed with:
+  - History cap: max 200 total entries, max 20 per wave. Older entries are pruned on every write.
+  - Evidence stripping: only the most recent history entry per wave retains its full evidence object; older entries have evidence set to null.
+  - Improved dedup: the transition dedup check now ignores `completedAt` timestamps in status file evidence, preventing identical reconciliation cycles from creating duplicate entries.
+
+
 ## 0.9.9 - 2026-04-07
 
 ### Fixed

package/docs/README.md

@@ -56,9 +56,11 @@ The useful path is journey-first:
 - Want the practical `0.9.3` operating stance:
   Read [guides/recommendations-0.9.7
 - [0.9.8 Operating Recommendations](guides/recommendations-0.9.8.md
-- [0.9.9 Recommendations](guides/recommendations-0.9.9.md)).md](./guides/recommendations-0.9.7
+- [0.9.9 Recommendations](guides/recommendations-0.9.9.md
+- [0.9.10 Recommendations](guides/recommendations-0.9.10.md))).md](./guides/recommendations-0.9.7
 - [0.9.8 Operating Recommendations](guides/recommendations-0.9.8.md
-- [0.9.9 Recommendations](guides/recommendations-0.9.9.md)).md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
+- [0.9.9 Recommendations](guides/recommendations-0.9.9.md
+- [0.9.10 Recommendations](guides/recommendations-0.9.10.md))).md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
 - Want the concrete runtime module map:
   Read [plans/end-state-architecture.md](./plans/end-state-architecture.md) for the engine-by-engine architecture and artifact ownership model.
 - Want the CLI surface map:

package/docs/guides/recommendations-0.9.10.md

@@ -0,0 +1,137 @@
+---
+title: "0.9.10 Recommendations"
+summary: "How to use 0.9.10's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
+---
+
+# 0.9.10 Recommendations
+
+Use this guide when you are adopting `0.9.10` and want one practical operating stance for the softer blocker states, advisory turn-budget behavior, and targeted recovery flow that the current package line ships.
+
+## Recommended Default
+
+For most repos, the safest `0.9.10` default is:
+
+- bound work with `budget.minutes`
+- leave generic `budget.turns` as advisory metadata
+- author non-proof follow-up as `soft`, `stale`, or `advisory` instead of silently treating every open record as a hard blocker
+- use `resolve-policy` when the answer already exists in repo policy or shipped docs
+- prefer targeted rerun or resume after timeout, max-turn, rate-limit, or missing-status outcomes instead of relaunching the whole wave
+- in short-lived sandboxes, prefer `wave submit`, `wave supervise`, `wave status`, and `wave wait` instead of binding the full run to one client shell
+- when a wave-gate dimension has a documented gap that is not an actionable blocker, use `gap` instead of `pass` or `blocked` — the runtime treats it as a conditional pass
+
+That recommendation matches the runtime:
+
+- executor launch metadata only emits hard turn-limit flags from `claude.maxTurns` or `opencode.steps`
+- open `stale` and `advisory` coordination records stay visible without reopening the active blocking edge
+- recoverable launcher failures queue targeted retry state instead of immediately escalating to broad terminal wave failure
+
+## 1. Budgets
+
+Treat the two budget knobs differently:
+
+- `budget.minutes` is the primary attempt budget
+- generic `budget.turns` is only a planning hint
+- `claude.maxTurns` or `opencode.steps` are the hard runtime ceilings when you actually want deterministic turn stopping
+
+Recommended pattern for synthesis-heavy implementation or closure work:
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "implementation-default": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "minutes": 35,
+          "turns": 12
+        }
+      }
+    }
+  }
+}
+```
+
+In that pattern, `35` minutes is real policy. `12` turns is only guidance for planning and preview metadata.
+
+Only set a hard runtime ceiling when you deliberately want the runtime itself to stop:
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "bounded-closure": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "minutes": 20
+        },
+        "claude": {
+          "maxTurns": 6
+        }
+      }
+    }
+  }
+}
+```
+
+## 2. Softer Coordination States
+
+`0.9.2` keeps “still visible” separate from “still blocking”.
+
+Use these states intentionally:
+
+| State | Use it for | What the runtime does |
+| --- | --- | --- |
+| `soft` | follow-up that still matters but should not be treated like proof failure | remains visible and may still drive repair or retry targeting |
+| `stale` | outdated clarification or blocker context kept for history | visible in control state, but does not reopen blocking by itself |
+| `advisory` | known issue, note, or human context that should stay visible without blocking closure | visible in control state, but does not own the active blocking edge |
+
+Practical command paths:
+
+```bash
+pnpm exec wave control task act defer --lane main --wave 10 --id blocker-doc-follow-up
+pnpm exec wave control task act mark-stale --lane main --wave 10 --id clarify-a7-rollout
+pnpm exec wave control task act mark-advisory --lane main --wave 10 --id request-clarify-a7-rollout
+pnpm exec wave control task act resolve-policy --lane main --wave 10 --id clarify-a7-rollout --detail "Policy already covered in the rollout guide."
+```
+
+Use them when the repo already knows the answer, the remaining item is informational, or the follow-up should stay visible for the next wave without holding the current wave hostage.
+
+## 3. What Should Stay Hard
+
+Do not relax everything.
+
+Keep these hard or closure-critical unless you are intentionally changing wave policy:
+
+- missing proof or required deliverables
+- failed integration, documentation, or cont-QA closure gates
+- real human-feedback or escalation requirements that block safe continuation
+- requests or clarifications that still represent unresolved ownership or policy ambiguity for the current wave
+
+Use `gap` in wave-gate markers when a dimension has a documented gap that is not actionable in the current wave. For example, `live=gap` is appropriate when an infrastructure topology constraint prevents full live validation but the constraint is known, documented, and does not represent a regression. Do not use `gap` to hide actual failures or unreviewed work.
+
+If the current wave cannot truthfully close without the answer, keep it blocking.
+
+## 4. Recovery Recommendation
+
+My recommendation after reviewing the current `0.9.10` code path is:
+
+- let timeout, max-turn, rate-limit, and missing-status failures go through the built-in targeted recovery path first
+- inspect the queued rerun or resume request before manually relaunching the whole wave
+- preserve reusable proof from successful sibling owners whenever the reducer already identified it as reusable
+
+That is the shape the launcher now prefers. It only broadens failure when the remaining blockers are still proof-critical or otherwise non-recoverable.
+
+## 5. Suggested Operator Policy
+
+For most repo-owned runbooks:
+
+- teach authors to use `budget.minutes` first
+- teach operators to downgrade only non-proof follow-up
+- treat `resolve-policy` as the preferred path when the answer already exists in docs or repo policy
+- escalate to a full-wave rerun only after targeted recovery proves insufficient
+
+If you want a single sentence policy:
+
+> Keep proof and closure strict, keep generic turns advisory, and keep non-proof context visible without letting it accidentally own wave closure.

package/docs/guides/recommendations-0.9.11.md

@@ -0,0 +1,44 @@
+# Recommendations for 0.9.11
+
+## Upgrade
+
+```bash
+wave self-update
+# or: npm install -g @chllming/wave-orchestration@0.9.11
+```
+
+## What changed
+
+### Verdict parsing (P0 fix)
+
+The `parseVerdictFromText()` function now returns the **first** regex match instead of the last. This fixes a critical bug where append-only cont-QA report files accumulated `Verdict:` lines across retries, and the stale `Verdict: BLOCKED` at the bottom would override newer `Verdict: PASS` entries above it.
+
+**If you have waves stuck in cont-QA retry loops**, upgrading to 0.9.11 should unblock them on the next attempt. No manual intervention needed — the runner will re-evaluate the gate with the fixed parser.
+
+**For ongoing work**: the log-based `[wave-verdict]` marker is now preferred over the report file `Verdict:` line. Both still work, but if both are present, the log marker wins. This is more reliable because the log is per-run while report files persist across attempts.
+
+### Log verdict priority
+
+`buildAgentExecutionSummary()` now reads verdicts in this order:
+1. `[wave-verdict]` from the agent's log (authoritative per-run)
+2. `Verdict:` from the cont-QA report file (fallback)
+
+Previously the report file took priority. If your cont-QA role prompt instructs the agent to write `Verdict: PASS/BLOCKED` in the report, that still works — it just won't override a contradicting `[wave-verdict]` marker in the same run's log.
+
+### Integration steward sticky closure
+
+When A8 (integration steward) explicitly reports `state=ready-for-doc-closure` with zero blockers, the orchestrator no longer re-injects synthesized proof/doc gaps on the next `refreshDerivedState()` cycle. This prevents the pattern where:
+
+1. A8 closes all gaps → integration summary says "ready-for-doc-closure"
+2. Launcher calls `refreshDerivedState()` on next attempt
+3. `buildIntegrationEvidence()` re-derives gaps from agent summaries
+4. Integration summary regresses to "needs-more-work"
+5. Retry → goto 1
+
+**No action required** — the fix is automatic. If your waves were stuck in integration retry loops, they should resolve on the next attempt.
+
+## Recommendations
+
+- **Stuck cont-QA waves**: Just upgrade and let the runner retry. The fixed verdict parser will read the correct verdict.
+- **Stuck integration loops**: Same — upgrade and let the runner retry.
+- **Report file hygiene**: Consider having your cont-QA role prompt write verdicts with a clear section header (e.g., `## Final Verdict`) to make the file structure unambiguous. The first-match-wins behavior rewards putting the definitive verdict early in the file.

package/docs/plans/migration.md

@@ -1,6 +1,6 @@
 # Migration
 
-This page is the practical repo-upgrade guide for the current `0.9.9` surface.
+This page is the practical repo-upgrade guide for the current `0.9.10` surface.
 
 Use it when you are:
 
@@ -24,7 +24,7 @@ The `0.9.4` surface adds laddered gate modes and fixes the steward threshold enf
 
 ## What `0.9.4` Changes
 
-The current `0.9.9` surface keeps everything from `0.9.2` and adds two focused improvements with no breaking changes.
+The current `0.9.10` surface keeps everything from `0.9.2` and adds two focused improvements with no breaking changes.
 
 The practical changes are:
 
@@ -182,7 +182,7 @@ Use `pnpm exec wave dashboard --lane <lane> --attach current` or `--attach globa
 
 ## `0.9.4` Release Model
 
-The current `0.9.9` surface combines these strands:
+The current `0.9.10` surface combines these strands:
 
 - the gap-value wave-gate fix and first-time setup UX improvements released in `0.9.4`
 - the detached process-runner and sandbox supervisor hardening released in `0.9.2`
@@ -367,11 +367,15 @@ If your repo copied starter config defaults, also sync the `designRolePromptPath
 - hybrid design stewards rejoin implementation when they explicitly own code
 - long-running prompts receive signal-state and ack paths when the repo uses the new waiting model
 
+## Upgrading From `0.9.9` To `0.9.10`
+
+Run-state history is now capped at 200 entries (20 per wave). Existing bloated run-state files will be automatically pruned on the next write. No config changes needed.
+
 ## Upgrading From `0.9.8` To `0.9.9`
 
 Helper assignment barriers are now advisory in bootstrap gate mode. No config changes needed.
 
-## Upgrading From `0.8.3` To `0.9.9`
+## Upgrading From `0.8.3` To `0.9.10`
 
 Treat this as one move to the current `0.9.2` surface.
 
@@ -406,7 +410,7 @@ If your repo copied starter docs or skills, sync:
 - dry-run one design-steward wave if the repo wants the new authored surface
 - if the repo uses long-running watcher agents or shell automation, validate `scripts/wave-status.sh` and `scripts/wave-watch.sh` against a live or staged lane
 
-## Upgrading From `0.6.x` Or `0.7.x` To `0.9.9`
+## Upgrading From `0.6.x` Or `0.7.x` To `0.9.10`
 
 This is the main migration path for older adopted repos.
 
@@ -557,4 +561,4 @@ For repos that depend on replay parity, replay at least:
 
 ## Summary
 
-The current `0.9.9` surface keeps the same authority-set and phase-engine architecture, ships both the design-role starter surface and the signal-driven long-running-agent starter surface, keeps the `0.8.7` policy and routing hardening, and now also packages the practical operator recommendations guide inside the release line. For most repos already on `0.8.x`, the upgrade is package bump plus validation. For older adopted repos, the real work is syncing repo-owned prompts, skills, planner corpus, wrapper scripts, and runbooks so they describe the runtime the package now ships.
+The current `0.9.10` surface keeps the same authority-set and phase-engine architecture, ships both the design-role starter surface and the signal-driven long-running-agent starter surface, keeps the `0.8.7` policy and routing hardening, and now also packages the practical operator recommendations guide inside the release line. For most repos already on `0.8.x`, the upgrade is package bump plus validation. For older adopted repos, the real work is syncing repo-owned prompts, skills, planner corpus, wrapper scripts, and runbooks so they describe the runtime the package now ships.

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@chllming/wave-orchestration",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "license": "MIT",
   "description": "Generic wave-based multi-agent orchestration for repository work.",
+  "packageManager": "pnpm@10.23.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chllming/agent-wave-orchestrator.git"
@@ -31,12 +32,6 @@
     "wave-dashboard": "scripts/wave-dashboard.mjs",
     "wave-local-executor": "scripts/wave-local-executor.mjs"
   },
-  "devDependencies": {
-    "@mozilla/readability": "^0.6.0",
-    "jsdom": "^29.0.1",
-    "pdfjs-dist": "^5.5.207",
-    "vitest": "3.2.4"
-  },
   "scripts": {
     "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
     "research:import-agent-context": "node scripts/research/import-agent-context-archive.mjs scripts/research/manifests/agent-context-expanded-2026-03-22.mjs",
@@ -50,5 +45,11 @@
     "wave:feedback": "node scripts/wave-human-feedback.mjs",
     "wave:launch": "node scripts/wave-launcher.mjs",
     "wave:local": "node scripts/wave-local-executor.mjs"
+  },
+  "devDependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "jsdom": "^29.0.1",
+    "pdfjs-dist": "^5.5.207",
+    "vitest": "3.2.4"
   }
-}
+}

package/releases/manifest.json

@@ -2,6 +2,19 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.9.10",
+      "date": "2026-04-07",
+      "summary": "Fix run-state history bloat that caused 500MB+ JSON files and V8 string length crashes.",
+      "features": [
+        "Run-state history capped at 200 entries (20 per wave) with automatic pruning.",
+        "Evidence objects stripped from older history entries to reduce size.",
+        "Improved transition dedup ignores completedAt timestamps in evidence.",
+        "planner-agentic bundle placeholder remains available for adopted repos."
+      ],
+      "manualSteps": [],
+      "breaking": false
+    },
     {
       "version": "0.9.9",
       "date": "2026-04-07",

package/scripts/wave-orchestrator/agent-state.mjs

@@ -509,7 +509,9 @@ export function buildAgentExecutionSummary({ agent, statusRecord, logPath, repor
         : "";
   const reportVerdict = parseVerdictFromText(reportText, REPORT_VERDICT_REGEX);
   const logVerdict = parseVerdictFromText(signalText, WAVE_VERDICT_REGEX);
-  const verdict = reportVerdict.verdict ? reportVerdict : logVerdict;
+  // Prefer log verdict (authoritative for the current run) over report verdict
+  // (may accumulate stale entries across retries in append-only report files).
+  const verdict = logVerdict.verdict ? logVerdict : reportVerdict;
   const termination = detectTermination(agent, logText, statusRecord);
   return {
     agentId: agent?.agentId || null,

package/scripts/wave-orchestrator/derived-state-engine.mjs

@@ -573,6 +573,11 @@ export function buildWaveIntegrationSummary({
     securitySummary,
   });
   if (explicitIntegration) {
+    // When the integration steward explicitly asserts ready-for-doc-closure,
+    // clear synthesized proof/doc gaps — the steward has signed off on them.
+    const stewardClearedGaps =
+      explicitIntegration.state === "ready-for-doc-closure" &&
+      (explicitIntegration.blockers || 0) === 0;
     return {
       wave: wave.wave,
       lane: lanePaths.lane,
@@ -595,8 +600,8 @@ export function buildWaveIntegrationSummary({
       ),
       changedInterfaces: evidence.changedInterfaces,
       crossComponentImpacts: evidence.crossComponentImpacts,
-      proofGaps: evidence.proofGaps,
-      docGaps: evidence.docGaps,
+      proofGaps: stewardClearedGaps ? [] : evidence.proofGaps,
+      docGaps: stewardClearedGaps ? [] : evidence.docGaps,
       deployRisks: evidence.deployRisks,
       securityState: evidence.securityState,
       securityFindings: evidence.securityFindings,

package/scripts/wave-orchestrator/shared.mjs

@@ -443,16 +443,16 @@ export function parseVerdictFromText(text, regex) {
   }
   regex.lastIndex = 0;
   let match = regex.exec(text);
-  let verdict = null;
-  let detail = "";
-  while (match !== null) {
-    verdict = normalizeWaveVerdict(match[1]);
-    detail = String(match[2] || "")
-      .trim()
-      .replace(/^detail=/i, "")
-      .trim();
-    match = regex.exec(text);
+  if (!match) {
+    return { verdict: null, detail: "" };
   }
+  // Use the first match — in append-only reports the latest verdict is written
+  // at the top of the newest section, while stale entries linger at the bottom.
+  const verdict = normalizeWaveVerdict(match[1]);
+  const detail = String(match[2] || "")
+    .trim()
+    .replace(/^detail=/i, "")
+    .trim();
   return { verdict, detail };
 }
 

package/scripts/wave-orchestrator/wave-files.mjs

@@ -2665,6 +2665,9 @@ export function writeRunState(runStatePath, state) {
   return payload;
 }
 
+const RUN_STATE_MAX_HISTORY = 200;
+const RUN_STATE_MAX_HISTORY_PER_WAVE = 20;
+
 function nextRunStateSequence(history) {
   return (history || []).reduce((max, entry) => Math.max(max, Number(entry?.seq) || 0), 0) + 1;
 }
@@ -2686,13 +2689,23 @@ function appendRunStateTransition(state, {
   const effectiveDetail = String(detail || "").trim();
   const effectiveEvidence =
     evidence && typeof evidence === "object" && !Array.isArray(evidence) ? evidence : null;
+  // Dedup: skip if the transition is identical (ignore timestamps in evidence)
+  const evidenceForCompare = (ev) => {
+    if (!ev || typeof ev !== "object") return null;
+    const { statusFiles, ...rest } = ev;
+    // Strip completedAt from status files for comparison (changes every cycle)
+    const normalizedFiles = Array.isArray(statusFiles)
+      ? statusFiles.map(({ completedAt, ...f }) => f)
+      : statusFiles;
+    return JSON.stringify({ ...rest, statusFiles: normalizedFiles });
+  };
   if (
     previousEntry &&
     currentState === toState &&
     previousEntry.lastSource === source &&
     previousEntry.lastReasonCode === reasonCode &&
     previousEntry.lastDetail === effectiveDetail &&
-    JSON.stringify(currentEvidence || null) === JSON.stringify(effectiveEvidence || null)
+    evidenceForCompare(currentEvidence) === evidenceForCompare(effectiveEvidence)
   ) {
     return nextState;
   }
@@ -2717,6 +2730,31 @@ function appendRunStateTransition(state, {
     lastEvidence: effectiveEvidence,
   };
   nextState.history = [...nextState.history, historyEntry];
+  // Cap history to prevent unbounded growth (run-state bloat fix)
+  if (nextState.history.length > RUN_STATE_MAX_HISTORY) {
+    // Keep the last N entries per wave, plus the most recent entries overall
+    const byWave = new Map();
+    for (const entry of nextState.history) {
+      const key = String(entry.wave ?? "");
+      if (!byWave.has(key)) byWave.set(key, []);
+      byWave.get(key).push(entry);
+    }
+    const kept = [];
+    for (const [, entries] of byWave) {
+      kept.push(...entries.slice(-RUN_STATE_MAX_HISTORY_PER_WAVE));
+    }
+    // Strip evidence from all but the last entry per wave to reduce size
+    const lastPerWave = new Set();
+    for (let i = kept.length - 1; i >= 0; i--) {
+      const key = String(kept[i].wave ?? "");
+      if (!lastPerWave.has(key)) {
+        lastPerWave.add(key);
+      } else {
+        kept[i] = { ...kept[i], evidence: null };
+      }
+    }
+    nextState.history = kept.sort((a, b) => (a.seq || 0) - (b.seq || 0));
+  }
   nextState.completedWaves = completedWavesFromStateEntries(nextState.waves);
   return nextState;
 }