# World-Class Keep/Discard Ledger

Append one entry for every material experiment or implementation slice.

## Round baseline-v8.8.107 - Baseline - 2026-04-29

Hypothesis: v8.8.107 is a stabilization baseline, not a completed world-class release.
Baseline: npm latest 8.8.107; local gates passed before publish: npm run check, npm run build, 451 tests; fresh npx returned 8.8.107 (Clavue).
Change: Record the baseline and required evidence model before starting upgrade slices.
Commands: See docs/clavue-world-class-major-upgrade-plan-2026-04-29.md Current Baseline.
Result: Baseline preserved for comparison.
Decision: keep
Reason: Future workstreams need a fixed reference point and cannot rely on vague quality claims.
Follow-up: Add command-produced eval rows as each workstream lands.

## Round runtime-release-preflight-v8.8.107 - Runtime/release hardening - 2026-04-29

Hypothesis: Reusing the resolved Mao Codex runtime and adding an offline release preflight reduces runtime drift and release-risk surprises without blocking normal local release prep.
Baseline: Mao jobs previously re-resolved Codex command availability at job launch; release checks covered metadata but not local launcher shadowing, GitHub Actions/npm availability, or fresh npx install guidance.
Change: Pass `runtime.codex` into Mao foreground/background job execution, fail clearly for unavailable/non-exec Codex modes, add `release:preflight`, keep local launcher mismatch advisory by default with `--strict-local-launcher` opt-in, preserve process env for fresh npx cache checks, and add execute-now/parallel intent regression coverage.
Commands: `npm run rebuild:dist`; `node scripts/verify-dist.mjs`; `node --test tests/mao-runtime.test.mjs tests/mao-job-runner.test.mjs tests/user-turn-intent.test.mjs`; `node --test tests/release-pipeline.test.mjs`; `node scripts/release-preflight.mjs --tag v8.8.107 --skip-local-launcher`; `node scripts/validate-release.mjs --tag v8.8.107`; final spec/code-quality subagent review.
Result: Focused Mao/intent tests passed 28/28; release pipeline passed 21/21; verify-dist and release metadata/preflight checks passed; final reviewer reported no blocking issues.
Decision: keep
Reason: The slice closes a real runtime handoff gap and adds release preflight coverage while avoiding false release blockers from previous global launcher installs.
Follow-up: Run `npm run check` before publishing if disk headroom allows; run `node scripts/release-preflight.mjs --tag v8.8.107 --online --strict-local-launcher` only when intentionally validating the live release environment.

## Round task-board-truth-diagnostic-pivot-v8.8.107 - Task-board truth - 2026-04-30

Hypothesis: Diagnostic/debug pivots should preserve task-board truth by allowing stale planning, design, or implementation tasks to be updated or deleted while the turn remains inspect-first.
Baseline: Execute-now reminders already told agents to clear superseded task-board entries, but inspect-first diagnostic reminders only said to stay read-only and could leave stale task boards visible after a debug pivot.
Change: Add diagnostic-pivot task-board truth guidance to the inspect-first intent reminder and anchor it in product-truth plus user-turn intent regressions.
Commands: `node --test tests/user-turn-intent.test.mjs`; `node --test tests/product-truth-surfaces.test.mjs`; `npm run rebuild:dist`; `node scripts/verify-dist.mjs`; `node --test tests/user-turn-intent.test.mjs tests/product-truth-surfaces.test.mjs`.
Result: Focused user-turn tests passed 18/18; product-truth tests passed 34/34; combined focused suite passed 52/52; dist verification passed.
Decision: keep
Reason: The slice closes a misleading UI/model-guidance gap without weakening inspect-first diagnostics or starting implementation after a debug pivot.
Follow-up: Continue P0 workflow-continuity slices against real resumed-session behavior rather than adding broader TUI harnessing prematurely.

## Round stale-in-progress-task-detection-v8.8.107 - Task-board truth - 2026-04-30

Hypothesis: Idle task boards should distinguish stale `in_progress` tasks from actively running work so resumed or paused sessions do not imply execution is still happening.
Baseline: Idle standalone task boards renamed counts to "marked in progress" and said unfinished tasks needed continuation, but row styling and summary counts still treated all `in_progress` tasks as active unless the assistant manually corrected the task board.
Change: Detect stale idle `in_progress` tasks when no active teammate or activity is present, render them dim/unbold with neutral icons and a "marked in progress, not active" suffix, split active versus stale in-progress summary counts, and anchor the behavior in product-truth tests.
Commands: `node --test tests/product-truth-surfaces.test.mjs tests/session-workflow-continuity.test.mjs`; spec/code-quality subagent review; `npm run rebuild:dist`; `node scripts/verify-dist.mjs`.
Result: Focused product-truth and continuity tests passed 50/50; dist rebuilt and verified; final reviewer reported no blockers.
Decision: keep
Reason: The slice closes a misleading idle-session UI gap without changing task persistence semantics or active spinner rendering.
Follow-up: Add broader rendered task-board UI coverage later if a stable Ink harness becomes necessary; continue remaining P0 task-board truth items first.

## Round stale-global-launcher-detection-v8.8.107 - Upgrade UX - 2026-04-30

Hypothesis: Doctor/update should warn when a stale PATH/global `clavue` launcher shadows the current runtime, without blocking update flows or creating false warnings for same/newer launchers.
Baseline: Fresh npx could return 8.8.107 while a local global launcher returned stale 8.8.106; Doctor/update had install warnings but no runtime PATH launcher version comparison.
Change: Add warning-only PATH launcher detection to Doctor diagnostics using the Clavue executable/package constants, resolve the PATH launcher and current runtime paths conservatively, run the PATH launcher with `--version`, warn only when it reports an older version than `APP_UPDATE_VERSION`, and reuse existing `DiagnosticInfo.warnings` so update prints the same repair guidance.
Commands: `node --test tests/product-truth-surfaces.test.mjs`; spec/code-quality subagent review; `npm run rebuild:dist`; `node scripts/verify-dist.mjs`; `node --test tests/product-truth-surfaces.test.mjs tests/release-pipeline.test.mjs`.
Result: Product-truth tests passed 34/34; focused product-truth plus release pipeline tests passed 55/55; dist rebuilt and verified; final code-quality reviewer reported no blockers after the spec blocker was fixed.
Decision: keep
Reason: The slice closes a real upgrade trust gap by surfacing stale PATH launchers in both Doctor and update while keeping diagnostics warning-only and avoiding broader installer refactors.
Follow-up: Add executable fixture coverage later if Doctor diagnostics gain a stable unit-test harness for mocked PATH launchers.

## Round init-fixture-matrix-v8.8.107 - Onboarding - 2026-04-30

Hypothesis: `/init` fixture coverage should verify non-Node project guidance across Python, Go, Makefile, and docs-only repositories without changing runtime behavior.
Baseline: `/init` tests covered Node, Cargo workspace, nested project targeting, ambiguous nested project diagnostics, docs-only child folders, legacy guidance, and onboarding completion, but lacked explicit Python, Go, Makefile, and root docs-only fixture assertions.
Change: Add table-driven fixture coverage for Python `pyproject.toml`, Go `go.mod`, Makefile, and docs-only root repositories, verifying generated `clavue.md` project facts and inferred command guidance.
Commands: `node --test tests/init-command.test.mjs`.
Result: Focused init command tests passed 9/9.
Decision: keep
Reason: The slice expands the required `/init` fixture matrix and locks existing runtime behavior without overlapping active worker scopes or changing shipped runtime code.
Follow-up: Continue remaining `/init` failure-path coverage for unwritable target and malformed manifests when it does not conflict with worker changes.

## Round companion-workflow-contract-v8.8.107 - Companion workflows - 2026-04-30

Hypothesis: Companion role commands should expose explicit workflow contracts before wiring the `/mao` execution bridge, so users can request recap/diagnose/fix/review intent without accidental rename fallback or hidden execution.
Baseline: Companion commands had role policy, guide, memory, provider, and card surfaces, but bare workflow verbs were treated as rename input and no stable inert workflow response contract existed.
Change: Parse `recap`, `diagnose`, `fix`, and `review` before rename fallback, preserve optional prompts, return a stable workflow contract through `createCompanionCall()` without `/mao` execution, and advertise the verbs in help/card text.
Commands: `node --test tests/companion-actions.test.mjs`; `npm run rebuild:dist`; `node scripts/verify-dist.mjs`; final spec/code-quality subagent review.
Result: Companion action tests passed 2/2; dist rebuilt and verified; final spec and code-quality reviewers reported no blockers.
Decision: keep
Reason: The slice closes an intent-routing and discoverability gap while keeping the workflow bridge explicitly inert until `/mao` execution integration is designed.
Follow-up: Wire the `/mao` execution bridge in a later slice with separate execution, permission, and no-recursion tests.

## Round clean-ripgrep-vendoring-v8.8.107 - Release packaging - 2026-04-30

Hypothesis: Ripgrep vendoring should derive Codex platform package mappings from `package-lock.json` when installed `node_modules` are absent, so clean worktrees and release-prep environments do not fail before using lockfile metadata.
Baseline: `scripts/vendor-ripgrep.mjs` always read `node_modules/@openai/codex/bin/codex.js` to discover platform packages, which made lockfile-driven vendoring brittle in clean worktrees without installed Codex packages.
Change: Preserve installed-entrypoint parsing when available, add package-lock optionalDependency fallback mapping for every ripgrep target, and add a clean temp-worktree regression that runs the vendoring script without `node_modules`.
Commands: `node --test tests/ripgrep.test.mjs`; `node --test tests/ripgrep.test.mjs tests/mao-job-runner.test.mjs tests/mao-runtime.test.mjs tests/companion-actions.test.mjs`; `npm run rebuild:dist`; `node scripts/verify-dist.mjs`; focused suite rerun after dist rebuild.
Result: Ripgrep tests passed 2/4 with 2 system-rg skips; focused integration suite passed 16/18 with 2 system-rg skips before and after dist rebuild; dist rebuilt and verified.
Decision: keep
Reason: The slice closes a release/build robustness gap for clean checkout workflows while preserving the existing installed-package source of truth when present.
Follow-up: Run full `npm run check` before publish if disk and runtime budget allow.

## Round publish-surface-secret-scan-v8.8.107 - Release security - 2026-04-30

Hypothesis: Release validation should catch accidental credential leaks across publishable text surfaces without blocking documented placeholders.
Baseline: `scripts/validate-release.mjs` checked release metadata, package whitelists, required files, ignore rules, and tracked artifacts, but did not scan README, install script, package metadata, docs, or dist text sidecars for token-like secrets before npm publishing.
Change: Add a bounded publish-surface secret scan for `README.md`, `install.sh`, `package.json`, docs except `docs/superpowers`, and text-like dist sidecars, covering private key blocks plus GitHub, npm, AWS, and provider API-key assignment patterns while allowing example/placeholder values and code variable assignments.
Commands: `node scripts/validate-release.mjs --tag v8.8.107`; `node --test tests/release-pipeline.test.mjs`.
Result: Release validation passed; release pipeline tests passed 22/22 with the new validation contract assertion.
Decision: keep
Reason: The slice closes a high-impact publish-surface privacy gap with a focused warning-free release gate and no broad secret-scanning dependency.
Follow-up: Re-run `npm run rebuild:dist`, `node scripts/verify-dist.mjs`, and broader gates after integrating worker outputs.

## Round parallel-worker-recursion-guard-v8.8.107 - Parallel development - 2026-04-30

Hypothesis: Generated `/parallel` coordinator followups and worker prompts should not be reclassified as fresh high-concurrency user intent, while legitimate user-authored parallel prompts should still route normally.
Baseline: Coordinator followups had generated markers, but worker prompts could include phrases like `concurrent Clavue workers`, `Coordination rules:`, and user goals containing `火力全开` or `多线程`, creating a recursion risk after launch; `/team check` integration also needed a single provider profile resolution before runtime capability reporting.
Change: Reuse the resolved provider profile in `/team check`, add generated-worker prompt marker gating that requires the worker signature rather than a single generic phrase, keep `/parallel --team` worker specs in shared-workspace mode, and add regression coverage for generated worker prompt suppression plus legitimate `Coordination rules:` user intent.
Commands: `node --test tests/team-command.test.mjs tests/parallel-development.test.mjs`; final spec/code-quality subagent review.
Result: Focused team and parallel tests passed 18/18 after the marker-boundary fix; final reviewer reported no blockers.
Decision: keep
Reason: The slice closes a recursive worker-launch risk and a provider capability integration defect without suppressing legitimate user high-concurrency requests or advertising worktree isolation in team mode.
Follow-up: Rebuild and verify `dist`, then run the broader local gates.

## Round init-malformed-manifest-v8.8.107 - Onboarding - 2026-04-30

Hypothesis: `/init` should surface malformed package manifests as explicit project facts without blocking guidance creation, so users know setup files need repair while onboarding can still proceed.
Baseline: `/init` caught `package.json` parse errors but collapsed them to `Node package manifest`, hiding malformed JSON from generated `clavue.md` guidance.
Change: Return `Malformed JSON package manifest` for invalid `package.json` content and add focused fixture coverage that creates malformed JSON, runs `/init`, and checks the generated guidance.
Commands: `node --test tests/init-command.test.mjs` red baseline failed 9/10 on the malformed manifest assertion; `npm run rebuild:dist && node --test tests/init-command.test.mjs`; `node scripts/verify-dist.mjs`.
Result: Focused init command tests passed 10/10 after the fix; dist rebuilt and verified.
Decision: keep
Reason: The slice closes a trust gap for first-run project inspection without adding prompts, blocking guidance creation, or changing onboarding success semantics.
Follow-up: Continue remaining `/init` failure coverage for unwritable write/onboarding-state rollback and mixed monorepo fixture behavior.

## Round parallel-full-firepower-launch-v8.8.107 - Parallel development - 2026-04-30

Hypothesis: High-concurrency natural-language `/parallel` requests should launch the full-firepower worker shape by default while preserving explicit worker-count overrides and real launch accounting.
Baseline: `/parallel` had launch-contract and recursion protections, but full-firepower prompts still needed durable max-worker defaulting and concrete coverage for concurrent AgentTool launches.
Change: Full-firepower/high-concurrency prompt parsing now defaults to 8 workers, explicit `--agents N` and leading numeric counts still override, `/parallel` launches effective worker specs through `Promise.allSettled(effectiveSpecs.map(...))`, and regression tests lock the Chinese prompt shape plus launch wiring.
Commands: `node --test tests/team-command.test.mjs tests/parallel-development.test.mjs tests/user-turn-intent.test.mjs`; `npm run rebuild:dist && node scripts/verify-dist.mjs`.
Result: Focused parallel/team/user-turn tests passed 37/37; dist rebuilt and verified after the source changes.
Decision: keep
Reason: The slice makes user-authored “火力全开” / high-concurrency requests materially execute with max bounded workers instead of merely sounding parallel, while retaining safe overrides and accounting.
Follow-up: Run broader `npm run check` or `npm run build` before claiming the full upgrade round is release-ready.
