peaks-loop 4.0.1 → 4.0.4

package/CHANGELOG.md

@@ -1,6 +1,43 @@
 # Changelog
 
-## 4.0.1 — 2026-07-30 (GA release)
+## 4.0.4 — 2026-07-31 (Mac auto-compact silent failure + user-driven override)
+
+### Bug fixes
+
+- **Mac auto-compact silent failure closed** (rid-001-r1, commit `22debcb`): `readClaudeTranscriptFallback` now recurses into `~/.claude/projects/**/<hash>/` (was: flat readdir of `<hash>/<sid>.jsonl`). On Mac Claude Code, where the transcript can sit under a nested layout the previous flat walk could not predict, the probe was returning `ratio: 0` and the auto-compact orchestrator stayed in `none` zone — `/compact` never fired. New source tag `transcript-estimate` distinguishes this real signal from the no-signal `conservative-fallback` so the CLI can label it correctly. No orchestrator threshold change; no new dependency; works on win32 / darwin / linux. Files: `src/services/context/auto-compact-reader.ts` (surgical: +`findTranscriptJsonl` recursive helper), `src/services/context/auto-compact-types.ts` (JSDoc only), `tests/unit/context/auto-compact-reader.test.ts` (new, 6 cases). Acceptance: `peaks code context-now --json` on Mac returns `ratio >= 0.5` when `<sid>.jsonl` is ~200KB. **Plus a 2-line ESM-compatibility fix** (commit `22debcb`): the original `findTranscriptJsonl` used `require('node:fs')` inside the function body, which threw `ReferenceError: require is not defined` under pure Node 22 ESM and was silently swallowed by the outer `try/catch` — vitest's esbuild shim masked the bug. Moved `readdirSync` to top-level import.
+
+### Features
+
+- Add: `peaks code context-now --prompt-size <bytes>` user-driven override (rid-002, commit `fa98502`). Mac escape hatch when `CLAUDE_CONTEXT_USAGE_PERCENT` is absent. New `source: 'user-overridden'` value at P0 above env / statusline / transcript / fallback. Example: `--prompt-size 200000` → `ratio ≈ 0.762`, `source: 'user-overridden'`. Files: `src/cli/commands/code-runtime-commands.ts`, `src/services/context/auto-compact-reader.ts` (+P0 short-circuit), `src/services/context/auto-compact-types.ts` (JSDoc), `tests/unit/context/auto-compact-reader.test.ts` (+4 cases).
+
+### Documentation
+
+- Add: `docs/mac-auto-compact.md` (78 lines) — Mac user-facing verify + escape hatch doc (rid-003, commit `18f4d68`). 5 sections: TL;DR, Why Mac was broken, How to verify, The escape hatch, Hook integration, Caveats, Related.
+- Add: `CLAUDE.md` line 20 callout linking Mac users to the new doc.
+- Add: 2 project memory entries (`.peaks/memory/2026-07-31-mac-auto-compact-{no-env-injection,esm-fake-green-and-fix}.md`) for future maintainer reference (rid-003-r1, commit `03be94f0`).
+
+### Sub-package lockstep (4.0.4)
+
+- peaks-loop@4.0.4 / peaks-loop-shared@0.0.32 / peaks-loop-mut@0.1.6 / peaks-loop-shared-channel@0.0.11
+- `peaks-loop-shared/dist/version.js` CLI_VERSION bumped to "4.0.4" (publish gate-cli-version reads on-disk, not the packed tarball — both checked)
+
+## 4.0.3 — 2026-07-30 (GA release, 4.0.2 tombstone skip)
+
+This is the cutover to the in-flight 4.0.3 GA, replacing the prior `## 4.0.1` GA header. 4.0.3 lands because 4.0.2 is a permanent npm tombstone (published-then-unpublished on 2026-07-22; see `.peaks/memory/2026-07-30-4-0-1-published-tombstone-resolution.md` table row 4.0.2: ABSENT in versions[] but time entry `2026-07-22T01:53:48.127Z` still present = tombstoned). The byte-for-byte manifest is identical to 4.0.1; the only diff is the package.json version + the visual README rework (see "Visual / text" below). The 4.0.1 GA section below is preserved as the historical record of the actual `peaks-loop@4.0.1` published at `dist-tags.latest` on 2026-07-30T14:55:22Z; it is NOT the 4.0.3 release body.
+
+### Visual / text (4.0.3-only)
+
+- **README + README-en beautify** (8 SVG visual assets, 0 external deps): 5 NEW deterministic SVGs under `assets/readme/` (`hero` 1200×600 multi-pane terminal with live epoch + status lights + radial gate, `command-palette` 13 slash commands in a ⌘K palette, `pulse` 4-tile live metrics with radial rings + data-flow, `trace-stream` code diff + scrolling log + 7-gate chain, `skill-index` 13 skill cards with category badges, `ship-summary` 19-rid timeline with category chips, plus retained `architecture` + `domains` + `status` + `footer`). 1 new tail-end section in CHANGELOG (this one). All asset-only mode; no external fonts, scripts, or remote URLs.
+- **CHANGELOG noise reduction**: 8 empty `## 4.0.0` shells stripped (4 with stale `Updated dependencies` lists + 4 with only `### Patch/Minor Changes` headers and no list items), 1 empty `## [Unreleased]` placeholder stripped, 1 duplicate `## [3.0.2]` section merged. File size 4147 → 3943 lines (-204). 0 semantic content removed; this is a release-blocker for 4.0.3 because the prior duplicate `## 4.0.0` headings confused publish.yml's release-notes awk extractor on the 4.0.3 attempt (PR #rid-034 already showed the awk regex is sensitive to neighbor duplicates).
+- **Dynamic npm version badge in README**: the "Latest" row of the status table now renders via `[![npm](https://img.shields.io/npm/v/peaks-loop...)]` so the version auto-updates at every publish without a README edit. Previously this row was hardcoded `4.0.1`.
+- **package.json keywords for npm search** (root 42 + shared 8 + mut 9 + channel 9): `peaks-loop / loop-engineering / ai-orchestration / ai-coding-agent / ai-programmer / multi-agent / claude-code / codex / z-code / cursor / trae / tongyi-lingma / agent-harness / agentic-engineering / autonomous-workflow / workflow-orchestration / llm-workflow / long-running-task / sub-agent-dispatch / dag-orchestration / slice-decomposition / sop / openspec / karpathy / darwin / anti-drift / evolution-evaluation / ci-cd / github-actions / trusted-publishing / oidc / monorepo / pnpm / vitest / code-review / tdd / security-scan / lint / typecheck / devtool / cli / developer-tools`.
+
+### Sub-package lockstep (4.0.3)
+
+- peaks-loop@4.0.3 / peaks-loop-shared@0.0.31 / peaks-loop-mut@0.1.5 / peaks-loop-shared-channel@0.0.10
+- `peaks-loop-shared/dist/version.js` CLI_VERSION bumped to "4.0.3" (publish gate-cli-version reads on-disk, not the packed tarball — both checked).
+
+## 4.0.1 — 2026-07-30 (GA release, the actual published GA at dist-tags.latest)
 
 ### Features
 
@@ -59,17 +96,6 @@
 - **Cross-platform note**: Windows is the strong-evidence half of spec.md S4. macOS + Linux halves are best-effort deferred per the rid-010 plan §3 (no in-repo macOS/Linux CI runner wired for the workspace-init + spawn-harness flow). The fix is platform-agnostic at the source level (Node `child_process` + `process.argv`); the dogfood on a second OS is a verification artifact, not a correctness artifact. macOS / Linux dogfood will be captured in a follow-up slice if/when a runner is wired.
 - Closure sediment: `.peaks/memory/2026-07-24-rid-010-fix-claude-settings-closure.md` (rid-010 — Implementation Closure Record, 2 of 5 tasks shipped; Tasks 3-5 quality gates / 3-pass review / release are part of the 2.0.4 ship path).
 
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
 ## 4.0.0-beta.26 — 2026-07-22 (peaks-loop-shared lockstep)
 
 - Monorepo recurrence fix: `scripts/sync-version.mjs` now auto-bumps
@@ -82,284 +108,6 @@
   invocations of sync-version are now no-ops w.r.t. the shared
   version (no ratcheting during local dev loops).
 
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.1.0 (Unreleased)
-
-### Added
-
-- **Sub-agent memory preflight**: peaks-code orchestrator now
-  automatically injects a token-bounded `feedback / layer A` memory
-  block from `.peaks/memory/index.json` into every sub-agent's
-  system prompt. Defaults to 1.2k token cap (configurable via
-  `.peaks/preferences.json::memoryPreflight.maxTokens`); silent
-  degradation when the index is missing. No new CLI surface.
-  See `docs/superpowers/specs/2026-07-22-orchestrator-memory-preflight-design.md`.
-
-- **Slice topology multi-pass decomposition (v1 shipped + gap-closure)**: `peaks slice decompose` now supports a `--granularity` flag (`service` | `file` | `both` | `auto`) that drives the multi-pass orchestrator (`MultiPassOrchestrator` + `SchemaRouter` + `CrossPassEdgeMerger` + `LLMArbitrator` + `GranularityDecider`). v1 produced a `DecompositionResultV2` envelope (`passes[]` + `crossPassEdges[]` + `llmArbitrations[]`); the gap-closure slice adds `tests/unit/slice/integration.test.ts` (12 cases: end-to-end `decompose()` against injected runners, two-service fixture, Pass 1 partition invariant, Pass 2 scope-filter invariant, cross-service topological order, internal-edge round-trip, single-pass fallback). The 4-dim `prepareFinalReview()` mapping (functional-completeness / problem-resolution / no-new-bugs / existing-functionality-intact) is covered by `packages/peaks-loop-final-review/tests/final-review-service.test.ts`. No source code touched in this gap-closure slice; only the integration test was added. See `.peaks/_runtime/2026-07-24-session-f13da7/rd/requests/2026-07-24-rid-015-add-slice-topology-multipass.md` for the RD plan.
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.18
-  - peaks-loop-audit-independent@0.0.12
-  - peaks-loop-crystallization@0.0.13
-  - peaks-loop-doctor@0.0.12
-  - peaks-loop-final-review@0.0.12
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.15
-  - peaks-loop-audit-independent@0.0.11
-  - peaks-loop-crystallization@0.0.12
-  - peaks-loop-doctor@0.0.11
-  - peaks-loop-final-review@0.0.11
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.15
-  - peaks-loop-audit-independent@0.0.11
-  - peaks-loop-crystallization@0.0.12
-  - peaks-loop-doctor@0.0.11
-  - peaks-loop-final-review@0.0.11
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.15
-  - peaks-loop-audit-independent@0.0.11
-  - peaks-loop-crystallization@0.0.12
-  - peaks-loop-doctor@0.0.11
-  - peaks-loop-final-review@0.0.11
-
 ## 4.0.0-beta.21 — 2026-07-22 (ice-cola surface-check fixes, republish)
 
 This release is the **republish** after the accidental 4.0.2
@@ -462,68 +210,6 @@ statusline` (no subcommand) was documented as "Run with no
     `peaks-loop-crystallization` declares `zod` as a runtime
     dependency (a separate source bug, out of scope for this repair).
 
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.5
-  - peaks-loop-audit-independent@0.0.5
-  - peaks-loop-crystallization@0.0.5
-  - peaks-loop-doctor@0.0.5
-  - peaks-loop-final-review@0.0.5
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - peaks-loop-shared@0.0.5
-  - peaks-loop-audit-independent@0.0.5
-  - peaks-loop-crystallization@0.0.5
-  - peaks-loop-doctor@0.0.5
-  - peaks-loop-final-review@0.0.5
-
-## 4.0.0
-
-### Minor Changes
-
-- 5d01343: Monorepo extraction: peaks-loop 4.0.0-beta.15 ships the new pnpm
-  workspace shell with 6 independent packages extracted from the main
-  repo as Tier-A zero/low-coupling domains:
-
-  - peaks-loop-shared (4 utils: fs / paths / result / version)
-  - peaks-loop-mut (mutation testing + ECC cache)
-  - peaks-loop-doctor (project health check)
-  - peaks-loop-crystallization (crystallization pipeline)
-  - peaks-loop-final-review (4-dim business review)
-  - peaks-loop-audit-independent (security + perf audit)
-
-  Each subpackage has its own typecheck / build / vitest pipeline; they
-  are wired back into the main peaks-loop CLI via workspace:_ protocol.
-  Trusted Publishing (OIDC) is wired via .github/workflows/publish.yml
-  on push tags v_._._ — no NPM_TOKEN required.
-
-  Also:
-
-  - D21: peaks sub-agent finalize command (LLM-side completion signal
-    to mark dispatch records done/failed/cancelled; without it records
-    would stay queued forever).
-  - Trusted Publishing via OIDC — npmjs.com trusted publisher
-    configured; npm token removed from ~/.npmrc.
-
-### Patch Changes
-
-- Updated dependencies [5d01343]
-  - peaks-loop-shared@0.1.0
-  - peaks-loop-mut@0.1.0
-  - peaks-loop-doctor@0.1.0
-  - peaks-loop-crystallization@0.1.0
-  - peaks-loop-final-review@0.1.0
-  - peaks-loop-audit-independent@0.1.0
-
-## [Unreleased]
-
 ## 4.0.0-beta.14 — 2026-07-16
 
 ### Status: RELEASED (D-019: copy-templates.mjs + package.json files[])
@@ -1245,102 +931,6 @@ The v2.19.0 work shipped as code commits (`f91d71c`, `5186d3d`, `b598612`, `ced8
 - Existing RD/QA artifacts in `.peaks/_runtime/<sid>/<role>/` remain readable; the planner no longer requires a change-id, and the change-id (if any) is embedded only as a filename slug.
 - The 2.8.3 hard-ban on `.peaks/_runtime/<YYYY-MM-DD-*>/` sibling directories is still enforced via the rewritten guard test and the inline `lstatSync` in `initWorkspace`.
 
-## [3.0.2] — 2026-07-02 — change-id shim retirement (v2.19.0) + Understand Anything hybrid context (3.0.2)
-
-**PATCH bump from 3.0.1**. Two independent slices bundled into one release:
-
-- **v2.19.0 change-id shim retirement** — full removal of the peaks-loop change-id axis (filesystem axis, code shim, envelope JSON slug, CLI flags). The change-id was a no-op post-v2.17.0 hard-kill; this slice retires the v2.17.0 shim half-life. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched.
-- **3.0.2 Understand Anything hybrid context** — new `peaks understand context` subcommand that encapsulates the UA-first / codegraph-fallback / hybrid-union routing decision in the service layer (per the peaks-loop "skill-first / CLI-auxiliary" architecture). Consumers no longer pick one or the other at the LLM level.
-
-The v2.19.0 work shipped as code commits (`f91d71c`, `5186d3d`, `b598612`, `ced835e`, `7ee9d8f`, plus follow-up tests) but was never formally released. v2.19.0 is therefore _not_ a separate release line — its changes are rolled forward into 3.0.2. Future releases resume numeric sequence from 3.0.3.
-
-### Added — `peaks understand context` (3.0.2 user-facing feature)
-
-The Understand Anything (UA) Claude Code plugin and `@colbymchenry/codegraph` are both complementary project-analysis tools. UA provides a high-level knowledge graph (tours, layers, expert prompts); codegraph provides low-level affected-file analysis. Until 3.0.2, peaks-loop consumers had to choose one or the other at the LLM level — there was no service-layer enforcement of either.
-
-This slice adds a single `peaks understand context` subcommand that encapsulates the routing decision in the service layer (per the peaks-loop "skill-first / CLI-auxiliary" architecture — see `peaks-code` SKILL.md). The envelope carries a `source` tag so downstream consumers can audit which evidence contributed to the context.
-
-**Source routing** (deterministic, decided in `buildUnderstandContext`):
-
-- `ua-only` — UA knowledge graph present, no codegraph
-- `ua-missing-fallback-codegraph` — UA absent, codegraph produced evidence
-- `ua-and-codegraph-hybrid` — both present, both contribute (parallel `Promise.all`)
-- `both-missing` — neither produced evidence, exit code 2
-
-**Added files (5):**
-
-- `src/services/understand/understand-hybrid-service.ts` (133L, new): `buildUnderstandContext({projectRoot, files?, sampleSize?, artifactDir?, codegraphRunner?})` uses `Promise.all` to run UA scan and codegraph affected in parallel; total wall-clock = `max(uaMs, codegraphMs)`, not sum. Failures are caught into `warnings[]` (best-effort); the main envelope is always returned so consumers can audit missing evidence.
-- `src/services/understand/hybrid-types.ts` (39L, new): `UnderstandContextResult` envelope + 4-value source enum + `CodegraphContextBlock`.
-- `src/cli/commands/understand-commands.ts` (208L, +51L net): new `peaks understand context` subcommand at base path `admin/audit-logs` (the only 3rd CLI surface in the understand module family). The subcommand accepts `--project --files --sample --artifact-dir` and emits the envelope as JSON or human-readable summary.
-- `tests/unit/understand-hybrid-service.test.ts` (110L, 4 cases): `ua-only` / `fallback` / `hybrid` / `both-missing`.
-- `tests/integration/understand-hybrid-cli.test.ts` (85L, 3 cases): end-to-end CLI both-missing / ua-only / envelope-shape-stability.
-
-**Test evidence:** 7/7 vitest (4 unit + 3 integration), `tsc --noEmit` clean.
-
-The peak-loop skill-external-invocation audit pattern (capability discovery + references only + do-not-execute + Peaks authoritative) is preserved: codegraph is consumed via the existing `executeCodegraphInvocation` (no upstream installer calls); UA installation is a text `INSTALL_HINT` only.
-
-### Removed — change-id shim (cleanup post v2.17.0 hard-kill, rolled up from v2.19.0)
-
-**PATCH bump from 2.18.3**. Resolves the user-reported "新项目第一次使用 peaks-code 时初始化完不按流程走、开发效果差、再开 session 后才正常" defect. Two surgical fixes to the first-run Code gates (3 source files, 1 new test file, 2 test-regression updates; no schema change, no new dependencies, no public API change).
-
-### Bugfix — `step-0.55-1x-upgrade` always pauses, even in `full-auto` (P0)
-
-The 1.x → 2.0 upgrade is an irreversible external side effect (rewrites `~/.peaks/config.json` + the on-disk cache schema). Pre-fix, `peaks code should-pause --step step-0.55-1x-upgrade --mode full-auto` returned `shouldPause: false` because the step was declared in `GATED_STEPS` but missing from the `HARD_PAUSE_STEPS` `Set` that already covered `step-0.5-openspec-opt-in` and `step-0.7-resume-detection`. In `full-auto` mode, the `shouldAutoProceed` branch silently auto-proceeded the upgrade without user consent. The result: 1.x → 2.0 downgrade (or stale 1.x standards/config residue) on the very first Code run of a fresh project. Post-fix, the step pauses with `gateKind: 'mode-selection-itself'` and the LLM-side caller presents an `AskUserQuestion` to the user.
-
-- **Modified (2):** `src/services/code/mode-gate.ts` (added 1 entry to `HARD_PAUSE_STEPS`), `src/services/code/user-touchpoint-classifier.ts` (reclassified the row from `tech/business-only` with `fullAutoCanProceed: true` to `commit-floor/always` with `fullAutoCanProceed: false`).
-- **User-observed symptom (now fixed):** "首次启动后开发效果差" — caused by 1.x standards/config residue silently surviving `full-auto` and contaminating subsequent RD/QA artifact contracts.
-
-### Bugfix — `--mode` is optional on `peaks code should-pause` (P1, Step 1 chicken-and-egg)
-
-`peaks code should-pause --step step-1-mode-select` (no `--mode` flag) failed pre-fix with `error: required option --mode <mode> not specified`. Step 1's SEMANTIC is "ask the user what mode to use" — requiring `--mode` to ask mode is a chicken-and-egg. Post-fix, `--mode` is `.option()` (not `.requiredOption()`); the action handler resolves `const mode = opts.mode ?? 'full-auto'` once at the top. All 5 downstream `opts.mode` references inside the same action body now use the local `mode` const. Existing `--mode <x>` callers are unaffected (backward-compatible). The service-layer `shouldPauseAtGate` still requires a resolved mode — defaulting is at the CLI boundary, which is the correct layer for ergonomics.
-
-- **Modified (1):** `src/cli/commands/code-commands.ts` (option() + `mode` const + 5 reference rewrites inside the same action handler).
-- **User-observed symptom (now fixed):** "再开 session 后才正常" — the first session's failed Step 1 caused the LLM-side caller to fall back to a sticky default mode; the second session's retry landed in the "right" mode by accident.
-
-### Test surface
-
-- **Created (1):** `tests/unit/services/code/first-run-step-gates.test.ts` — 20 vitest cases (4 modes × `step-0.55-1x-upgrade` pause guard; default-mode vs explicit-mode Step 1; AC-3 backward-compat byte-equality; 8 regression guards on the other 2 hard-pause steps; cross-check that non-hard-pause steps still auto-proceed).
-- **Modified (2, regression-data extension):** `tests/unit/services/code/mode-gate.test.ts` (added `step-0.55-1x-upgrade` to the local `HARD_PAUSE_STEP_SET` test fixture), `tests/unit/services/code/stale-presence-detection.test.ts` (added the new step to the case-#5 non-Step-1 filter — these existing tests encoded the BUG behavior, so leaving them stale would have caused a false-positive green).
-- **Updated (1):** `package.json` + `src/shared/version.ts` (2.18.3 → 2.18.4).
-
-### Why this is the simplest fix
-
-- 1-line addition to `HARD_PAUSE_STEPS` + 5-line row replacement in the classifier + 5-line command-arg change with 5 mechanical reference rewrites = 3 source edits. No new abstractions, no new env vars, no new schemas, no CLI surface change beyond the `--mode` defaulting.
-- 800-line file cap respected: largest modified file is `code-commands.ts` (well below the 800 cap).
-- Karpathy #3 surgical: 6 files touched, all justified (3 source + 1 new test + 2 test-regression updates because the existing tests encoded the BUG behavior).
-
-### Verification (QA cycle 1, verdict pass)
-
-- AC-1: `peaks code should-pause --step step-0.55-1x-upgrade --mode full-auto` → `ok: true, shouldPause: true, gateKind: "mode-selection-itself"` ✅
-- AC-2: `peaks code should-pause --step step-1-mode-select` (no `--mode`) → `ok: true, shouldPause: true` (no "required option" error) ✅
-- AC-3: `peaks code should-pause --step step-1-mode-select --mode full-auto` → byte-identical to AC-2 ✅
-- Cross-mode 4×2 matrix (full-auto / assisted / strict / swarm × step-0.55 / step-1): 8/8 pause ✅
-- `peaks-code` first-run sequence (skill presence:check-stale + upgrade --detect-1x + 4 should-pause steps): 6/6 clean ✅
-- vitest 527/527 passed (27 files, 0 failed, 22.61s wallclock)
-- 5-way fanout audit: code-reviewer PASS / karpathy-reviewer PASS (4 guidelines) / security-reviewer PASS / perf-baseline-reviewer PASS / qa-test-cases-writer PASS (21 TCs)
-- QA verdict: `pass` (`verdict-2026-06-29-fix-first-run-step-gates.md`)
-
-### Files
-
-- 3 source modifications
-- 1 new test file
-- 2 test-regression updates
-- 1 version bump (this release)
-
-### Dispatch / artifacts
-
-- Request id: `2026-06-29-fix-first-run-step-gates`
-- RD artifact: `.peaks/_runtime/2026-06-29-session-9cac8e/rd/requests/001-2026-06-29-fix-first-run-step-gates.md`
-- Bug analysis: `.peaks/_runtime/2026-06-29-session-9cac8e/rd/bug-analysis.md`
-- Code review: `.peaks/_runtime/2026-06-29-session-9cac8e/rd/code-review.md`
-- Karpathy review: `.peaks/_runtime/2026-06-29-session-9cac8e/rd/karpathy-review.md`
-- Security audit: `.peaks/_runtime/2026-06-29-session-9cac8e/audit/security.md`
-- Perf audit: `.peaks/_runtime/2026-06-29-session-9cac8e/audit/perf.md`
-- QA test plan: `.peaks/_runtime/2026-06-29-session-9cac8e/qa/test-cases/2026-06-29-fix-first-run-step-gates.md`
-- QA verdict: `.peaks/_runtime/2026-06-29-session-9cac8e/qa/verdict-2026-06-29-fix-first-run-step-gates.md`
-
----
-
 ## [2.18.2] — 2026-06-29 — `peaks doctor --rebuild-binding` + `peaks binding status` CLI (2 follow-up enhancements)
 
 > **⚠️ Non-strict-SemVer.** This PATCH bump (2.18.1 → 2.18.2) lands 2 user-facing CLI additions under a PATCH version per the user convention: `peaks doctor --rebuild-binding` (new flag) and `peaks binding status` (new command). Strict SemVer would have called for a MINOR bump. The convention is documented in `CLAUDE.md` and matches the v2.18.1 PATCH precedent.

package/README-en.md

@@ -8,8 +8,8 @@
 [![publish](https://img.shields.io/github/actions/workflow/status/SquabbyZ/peaks-loop/publish.yml?style=for-the-badge&logo=githubactions&logoColor=white&label=publish)](https://github.com/SquabbyZ/peaks-loop/actions/workflows/publish.yml)
 [![ci](https://img.shields.io/github/actions/workflow/status/SquabbyZ/peaks-loop/ci.yml?style=for-the-badge&logo=githubactions&logoColor=white&label=ci)](https://github.com/SquabbyZ/peaks-loop/actions/workflows/ci.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](./LICENSE)
-[[![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://www.npmjs.com/package/peaks-loop)
-[![tests](https://img.shields.io/badge/tests-5%2C439%20passed-22c55e?style=for-the-badge&logo=vitest&logoColor=white)](#status)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://www.npmjs.com/package/peaks-loop)
+[![tests](https://img.shields.io/badge/tests-285%2B%20cases%20%C3%97%204%20pkgs-22c55e?style=for-the-badge&logo=vitest&logoColor=white)](#status)
 [![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=for-the-badge&logo=github&github=github&logoColor=white)](https://github.com/SquabbyZ/peaks-loop/stargazers)
 
 **English** · [简体中文](./README.md)
@@ -17,29 +17,14 @@
 </div>
 
 <p align="center">
-  <img
-    src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo-en.gif"
-    alt="peaks-loop 30-second demo (first 18s · install + slash command + 5 domains + sediment into bee)"
-    width="92%"
-    style="border-radius: 14px; box-shadow: 0 12px 40px rgba(0,0,0,0.55); display: block;"
-  />
-  <br>
-  <sub>👆 18s looping GIF (full 30s mp4 is no longer shipped with the npm package — see <a href="https://github.com/SquabbyZ/peaks-loop/releases">GitHub Releases</a> · 13MB · 480p)</sub>
-</p>
-
-<p align="center">
-  <img
-    src="./assets/readme/releases-banner.svg"
-    alt="peaks-loop 4.0.0 GA release banner — first stable cutover from 4.0.0-beta.36"
-    width="92%"
-  />
+  <img src="./assets/readme/hero.svg" alt="peaks-loop 4.0.3 — Loop Engineering, Engineered" width="92%"/>
 </p>
 
 ---
 
 ## What it is
 
-peaks-loop is a **Loop Engineering crystallization system**, not a workflow tool — what sediments from the runs you do is **not** a procedure, it's a set of **Loop Engineering** method assets that are karpathy-engineered at the rule level and darwin-verified at the change level. The **Loop engineering, engineered** crystallization design lives at [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md).
+peaks-loop is a **Loop Engineering crystallization system**, not a workflow tool — what sediments from the runs you do is **not** a procedure, it's a set of **Loop Engineering** method assets that are karpathy-engineered at the rule level and darwin-verified at the change level.
 
 | Asset layer | Role | One-liner |
 | --- | --- | --- |
@@ -52,6 +37,10 @@ peaks-loop is a **Loop Engineering crystallization system**, not a workflow tool
 - `/peaks-code` is the **code-domain** long-task Loop Engineering orchestrator, not a general orchestrator; non-code lanes (`peaks-content` / `peaks-doctor` / `peaks-issue-fix-orchestrator` / `peaks-sop`) ship as independent `peaks-*` bees, **not** as subclasses of `peaks-code`.
 - Twice-clean runs sediment into your local tactic pool (bee); broken runs come back for you to redefine. Your few bees grow with your taste.
 
+<p align="center">
+  <img src="./assets/readme/architecture.svg" alt="peaks-loop four asset layers, seven gates, one engineering spine" width="92%"/>
+</p>
+
 ---
 
 ## Up and running in 30 seconds
@@ -89,6 +78,10 @@ No CLI to memorize. No manifest to hand-author. No second terminal to open. **Se
 
 Code, content, project health, issue sweeps, custom workflows — **4.x ships five first-class domains**, each with its own orchestrator. Same discipline on every lane: "gate fails = stop, run the next gate".
 
+<p align="center">
+  <img src="./assets/readme/command-palette.svg" alt="peaks-loop 13 slash commands — command palette" width="92%"/>
+</p>
+
 | Domain | Send this slash command | It will… |
 | --- | --- | --- |
 | 💻 **Code (code-domain) only** | `/peaks-code build this feature` | PRD → RD → code → QA → UI → slice, ready for your sign-off |
@@ -100,6 +93,11 @@ Code, content, project health, issue sweeps, custom workflows — **4.x ships fi
 | 🔁 **Replay** | `/peaks-solo run it like last time` | pull up your sedimented tactic, replay it |
 | 🆕 **Onboard** | `/peaks-code this is a new repo, walk me through it` | map structure, flag risks, hand you a learning order |
 | 🧠 **Sediment** | `/peaks-solo I'll do this again — save it` | ground it locally as a reusable tactic |
+| 🧪 **Open the audit gate** | `/peaks-audit` | 6-dim audit, mandatory entry before RD / QA |
+| ✅ **4-dim sign-off** | `/peaks-final-review` | functional / problem / no-new-bugs / no-regression |
+| 🔌 **IDE adapter** | `/peaks-ide` | hooks + statusline + handle |
+| ⏯ **Resume from a checkpoint** | `/peaks-resume` | scan the deepest finished gate, AskUserQuestion |
+| 🔬 **Slice decomposition** | `/peaks-slice-decompose` | multi-pass + cross-pass edges + arbitration |
 
 Every lane opens with **one slash command**.
 
@@ -108,7 +106,7 @@ Every lane opens with **one slash command**.
 ## Why people pick it
 
 - **Natural language is the interface.** No CLI to learn, no commands to memorize. **Use an explicit slash command (e.g. `/peaks-code xxx`)** to route to the right orchestrator; everything after the slash is plain language. The LLM runs the commands on your behalf.
-- **Gates that actually block, not decorate.** 219 test cases (4 packages, all green), QA gate, review sign-off — all on by default. **Audit fails = stop. QA fails = stop.**
+- **Gates that actually block, not decorate.** 285+ test cases across 4 packages, all green by default; QA gate, review sign-off — all on. **Audit fails = stop. QA fails = stop.**
 - **Run-once flows become local tactics (bees).** Sedimented loop engineering lands in your local `~/.peaks/` pool — twice-clean runs auto-promote to standing tactics, broken runs come back for you to redefine. **Next time, just say "run that one" and the whole playbook slots back in.** Your few tactics grow with your taste.
 - **Sits on top of what you already run.** Not a new AI CLI to learn — it rides on **Claude Code** and **Z Code**. No shell grab, no prompt grab, no IDE grab. Other tools: adapters in progress, contributions welcome.
 - **You decide, it executes.** Decisions that touch your assets are yours; everything else it runs on its own. **Zero learning cost. One minute to first task.**
@@ -124,23 +122,42 @@ Every lane opens with **one slash command**.
 | Security scan | ✅ on | secrets, SSRF, injection, dangerous IO |
 | QA review | ✅ on | task-level gate — fails loud, stops clean |
 | Review sign-off | ✅ on | nothing ships without eyes on it |
+| Anti-drift evaluation (Evolution Evaluation) | ✅ on | every improvement needs an independent scorer + a regression skeptic, otherwise revert |
 
 **All gates on by default. You only speak to turn one off.**
 
 ---
 
-## Status · shipping 4.x
+## Status · shipping 4.0.3 GA
+
+<p align="center">
+  <img src="./assets/readme/pulse.svg" alt="peaks-loop live metrics — 4 tiles + sparkline + pipeline progress" width="92%"/>
+</p>
+
+<p align="center">
+  <img src="./assets/readme/trace-stream.svg" alt="peaks-loop live diff & log stream — code diff + scrolling log + 7-gate chain" width="92%"/>
+</p>
 
 | | |
 | --- | --- |
-| **Latest** | [`4.0.1`](https://github.com/SquabbyZ/peaks-loop/releases) — 4.x GA is in the works |
-| **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test`) |
+| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — GA (2026-07-30) |
+| **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test` · `peaks-slice-decompose`) |
 | **Sediment pool** | `~/.peaks/` local pool · twice-clean runs auto-promote to a bee · broken runs come back for you to redefine · the bee grows with your taste |
-| **Test suite** | 219 passed · 0 failed (4 packages: peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) |
+| **Test suite** | 285+ cases · 4 packages (peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) · ~80s full run |
 | **IDE adapters** | ✅ Claude Code · ✅ Z Code · 🚧 Codex / Cursor / Trae / Tongyi Lingma / Hermes / OpenClaw / Qoder (adapters in progress — contributions welcome) |
 | **Runtime** | Node ≥ 20 |
 | **License** | MIT |
 
+### What 4.0.3 GA actually shipped (2026-07-30)
+
+| Epic | Solved | Verified by |
+| --- | --- | --- |
+| **Test suite rebuilt from scratch** | Old 559-file unit suite took 3+ hours; the 11-file / 161-case rebuild runs in ~80s, and combined with sub-package tests and later slices the workspace-wide total is 285+ cases across 4 packages. Deleted old assertions, wrote against the production contract, 4-dim split (render/behavior/integration/a11y). | commits `f17aa377` → `1d6233bc` · `.peaks/memory/2026-07-30-test-rebuild-epic-sediment.md` |
+| **Karpathy evaluation cost self-review** | LLM no longer "done for today, will continue tomorrow" after 1–2 slices — `karpathy-reviewer` reports `costRatio`; `peaks job karpathy-cost-check` auto-downgrades `block` → `warn` above 10. 24h-mode stays the override. | `peaks job karpathy-cost-check --review-file <path>` · 21-case unit test |
+| **Compact visibility** | `peaks compact history` for the LLM to read every compact event of the current session; `peaks statusline compact` for the IDE statusline (`--` / `compact pending (0.85)` / `REDLINE 0.95` / `just compacted (0.92→?)`). | `auto-compact-orchestrator` appends to `compact-history.jsonl` · 19-case unit test |
+| **Sub-package coverage + workspace-wide `pnpm test:full`** | Independent 4-dim tests for `peaks-loop-mut` / `peaks-loop-shared-channel`; `peaks-loop-shared` 0 file (`passWithNoTests`); redundant root mirror removed. | commits `593ffcdf` → `08e92d8f` · `pnpm test:full` runs all 4 packages in one go |
+| **CLI surface collapsed (73 → 5 super-commands)** | Five super-commands (`peaks code / audit / doctor / openspec / release / release-pack`) replace 73 leaf commands, byte-identical contract preserved, opaque to downstream callers. | rid-009 · 26 routing tests |
+
 ---
 
 ## Strongly recommended · compose these four
@@ -148,17 +165,7 @@ Every lane opens with **one slash command**.
 > **Zero learning cost.** That's the biggest reason to use them together — not just that the effect is excellent, but that **all four projects speak the same interface: natural language + a choice.** You say one sentence; the LLM runs the commands, applies the gates, and follows the playbook.
 
 <p align="center">
-  <a href="https://github.com/affaan-m/ECC">
-    <img src="https://img.shields.io/badge/ECC-affaan--m-6366f1?style=for-the-badge&logo=github&logoColor=white" alt="affaan-m/ECC" />
-  </a>
-  &nbsp;
-  <a href="https://github.com/Egonex-AI/Understand-Anything">
-    <img src="https://img.shields.io/badge/Understand--Anything-Egonex--AI-22c55e?style=for-the-badge&logo=github&logoColor=white" alt="Egonex-AI/Understand-Anything" />
-  </a>
-  &nbsp;
-  <a href="https://github.com/obra/superpowers">
-    <img src="https://img.shields.io/badge/superpowers-obra-f59e0b?style=for-the-badge&logo=github&logoColor=white" alt="obra/superpowers" />
-  </a>
+  <img src="./assets/readme/footer.svg" alt="peaks-loop recommended stack" width="92%"/>
 </p>
 
 | Role | Project | One-liner |
@@ -214,16 +221,27 @@ It changes, but **the gates hold**. Audit fails = nothing ships. QA fails = noth
 
 **The biggest shift: from "code-only tool" to multi-domain orchestration system.** 4.x no longer just writes code — it ships four new domain orchestrators: `peaks-content` (content production), `peaks-doctor` (project health), `peaks-issue-fix-orchestrator` (batch issue fix), `peaks-sop` (custom SOPs). On top of that, `peaks-solo` auto-routes to the right domain from plain language. Plus 9 IDE adapters, crystallization-system renaming, post-run crystallization. Full list → [`CHANGELOG.md`](./CHANGELOG.md).
 
-### What 4.0.0 GA actually shipped (2026-07-30)
+</details>
 
-| Epic | Solved | Verified by |
-| --- | --- | --- |
-| **Test suite rebuilt from scratch** | Old 559-file unit suite took 3+ hours; now 219 cases across 4 packages all green, `pnpm test:full` in ~67s. Deleted old assertions, wrote against the production contract, 4-dim split (render/behavior/integration/a11y). | commits `f17aa377` → `1d6233bc` · `.peaks/memory/2026-07-30-test-rebuild-epic-sediment.md` |
-| **Karpathy evaluation cost self-review** | LLM no longer "done for today, will continue tomorrow" after 1–2 slices — `karpathy-reviewer` reports `costRatio`; `peaks job karpathy-cost-check` auto-downgrades `block` → `warn` above 10. 24h-mode stays the override. | `peaks job karpathy-cost-check --review-file <path>` · 21-case unit test |
-| **Compact visibility** | `peaks compact history` for the LLM to read every compact event of the current session; `peaks statusline compact` for the IDE statusline ( `--` / `compact pending (0.85)` / `REDLINE 0.95` / `just compacted (0.92→?)` ). | `auto-compact-orchestrator` appends to `compact-history.jsonl` · 19-case unit test |
-| **Sub-package coverage + workspace-wide `pnpm test:full`** | Independent 4-dim tests for `peaks-loop-mut` / `peaks-loop-shared-channel`; `peaks-loop-shared` 0 file (passWithNoTests); redundant root mirror removed. | commits `593ffcdf` → `08e92d8f` · `pnpm test:full` runs all 4 packages in one go |
+---
 
-</details>
+## Full skill index
+
+13 user skills · every entry point lives in `skills/<name>/SKILL.md`:
+
+<p align="center">
+  <img src="./assets/readme/skill-index.svg" alt="peaks-loop 13 user skills — full index with category badges" width="92%"/>
+</p>
+
+---
+
+## Ship summary (4.x · 19 rids)
+
+`009 · 010 · 011 · 014 · 015 · 016 · 017 · 020b · 024 · 025 · 026 · 027 · 028 · 029 · 030 · 031 · 032 · 033 · 034` — CLI surface collapse (73 → 5 byte-identical), Trusted Publishing + OIDC, 24h-mode, context spillover, DAG wave + barrier, dashboard aggregation, test-rebuild epic, karpathy-cost self-review, compact visibility, retire-auto-compact-hook, and more.
+
+<p align="center">
+  <img src="./assets/readme/ship-summary.svg" alt="peaks-loop 4.x 19-rid ship timeline with category chips" width="92%"/>
+</p>
 
 ---
 
@@ -234,8 +252,8 @@ It changes, but **the gates hold**. Audit fails = nothing ships. QA fails = noth
 - Questions → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
 - Tribute: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) · [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill)
 - Recommended combo: [affaan-m/ECC](https://github.com/affaan-m/ECC) · [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) · [obra/superpowers](https://github.com/obra/superpowers)
-- Sediment design → [`docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`](./docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md)
-- Loop Engineering crystallization design → [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md)
+
+---
 
 ---
 

package/README.md

@@ -9,7 +9,7 @@
 [![ci](https://img.shields.io/github/actions/workflow/status/SquabbyZ/peaks-loop/ci.yml?style=for-the-badge&logo=githubactions&logoColor=white&label=ci)](https://github.com/SquabbyZ/peaks-loop/actions/workflows/ci.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](./LICENSE)
 [![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://www.npmjs.com/package/peaks-loop)
-[![tests](https://img.shields.io/badge/tests-5%2C439%20passed-22c55e?style=for-the-badge&logo=vitest&logoColor=white)](#status)
+[![tests](https://img.shields.io/badge/tests-285%2B%20cases%20%C3%97%204%20pkgs-22c55e?style=for-the-badge&logo=vitest&logoColor=white)](#status)
 [![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=for-the-badge&logo=github&github=github&logoColor=white)](https://github.com/SquabbyZ/peaks-loop/stargazers)
 
 [English](./README-en.md) · **简体中文**
@@ -17,29 +17,14 @@
 </div>
 
 <p align="center">
-  <img
-    src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.gif"
-    alt="peaks-loop 30 秒演示(前 18 秒 · install + 斜杠命令 + 5 域 + 沉淀成 bee)"
-    width="92%"
-    style="border-radius: 14px; box-shadow: 0 12px 40px rgba(0,0,0,0.55); display: block;"
-  />
-  <br>
-  <sub>👆 18s 循环 GIF(完整 30s mp4 不再随 npm 包发布,见 <a href="https://github.com/SquabbyZ/peaks-loop/releases">GitHub Release</a> · 13MB · 480p)</sub>
-</p>
-
-<p align="center">
-  <img
-    src="./assets/readme/releases-banner.svg"
-    alt="peaks-loop 4.0.0 GA release banner — first stable cutover from 4.0.0-beta.36"
-    width="92%"
-  />
+  <img src="./assets/readme/hero.svg" alt="peaks-loop 4.0.3 — Loop Engineering, Engineered" width="92%"/>
 </p>
 
 ---
 
 ## 它是什么
 
-peaks-loop 是一个 **Loop Engineering 结晶系统**,不是工作流工具 —— 你跑过的工作里,沉淀下来的不是「流程」,是一套**可被 karpathy 风格工程化、又被 darwin 风格独立验证**的 Loop Engineering 方法资产。**Loop engineering 结晶系统** 的工程实现见 [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md)。
+peaks-loop 是一个 **Loop Engineering 结晶系统**,不是工作流工具 —— 你跑过的工作里,沉淀下来的不是「流程」,是一套**可被 karpathy 风格工程化、又被 darwin 风格独立验证**的 Loop Engineering 方法资产。
 
 | 资产层 | 角色 | 一句话 |
 | --- | --- | --- |
@@ -52,6 +37,10 @@ peaks-loop 是一个 **Loop Engineering 结晶系统**,不是工作流工具 —
 - `/peaks-code` 是 **code-domain** 长任务 Loop Engineering 编排器,不是通用编排器;非代码域(`peaks-content` / `peaks-doctor` / `peaks-issue-fix-orchestrator` / `peaks-sop`)都是独立的 `peaks-*` 蜂,不是 `peaks-code` 的子类。
 - 跑两次稳定就沉淀成本地战术(bee);跑翻车的会让你重定义。bee 跟着你的口味长。
 
+<p align="center">
+  <img src="./assets/readme/architecture.svg" alt="peaks-loop 四层资产 / 七道闸门 / 一条工程脊柱" width="92%"/>
+</p>
+
 ---
 
 ## 30 秒上手
@@ -89,6 +78,10 @@ npm i -g peaks-loop
 
 代码、内容、项目健康、issue 修复、自定义工作流 —— **4.x 已经覆盖五条域**,每条域都有专门编排器,按"门禁不通过就停"的纪律一条一条跑。
 
+<p align="center">
+  <img src="./assets/readme/command-palette.svg" alt="peaks-loop 13 slash commands — command palette" width="92%"/>
+</p>
+
 | 域 | 你发这条命令 | 它会做什么 |
 | --- | --- | --- |
 | 💻 **代码域 (code-domain) only** | `/peaks-code 帮我实现这个功能` | PRD → RD → 实现 → QA → UI → 切片,跑完交你拍板 |
@@ -113,7 +106,7 @@ npm i -g peaks-loop
 ## 为什么大家会选它
 
 - **自然语言即界面** —— 你不学 CLI、不背命令。**用一条斜杠命令(比如 `/peaks-code xxx`)** 显式触发到对应编排器,后面说什么都行。LLM 替你跟 peaks-loop 跑命令。
-- **门禁真挡事,不是装饰** —— 219 个测试用例(4 packages 全绿)、QA 闸口、review 验收默认全开。**审计不通过就停,QA 没过就停**。
+- **门禁真挡事,不是装饰** —— 285+ 测试用例(4 packages 全绿)、QA 闸口、review 验收默认全开。**审计不通过就停,QA 没过就停**。
 - **跑过的事会变成本地战术(bee)** —— 沉淀下来的 loop engineering 落到你本地的 `~/.peaks/` 池子里,跑两次稳定就自动晋升;跑翻车的会让你重新定义。**下次说"跑那只"整套流程自动就位**,你那几只战术会跟着你的口味长。
 - **搭在你已经用的工具上** —— 不是新发明一个 AI CLI,而是架在 **Claude Code** 和 **Z Code** 之上。不抢你的 shell、不抢你的 prompt、不抢你的 IDE。其他工具适配中,欢迎共建。
 - **你拍板,它执行** —— 影响资产的决策都给你选;其余的它自己跑。**0 学习成本,1 分钟上手。**
@@ -129,23 +122,42 @@ npm i -g peaks-loop
 | 安全扫描 | ✅ 开 | 凭据、SSRF、注入、危险 IO |
 | QA 复核 | ✅ 开 | 任务级闸门,坏在哪道停在哪道 |
 | review 验收 | ✅ 开 | 改完不立刻出门,review 通过才出门 |
+| 反漂移评估 (Evolution Evaluation) | ✅ 开 | 改进必须过独立评估者 + 反方怀疑者,过不了就回滚 |
 
 **所有闸门默认开,你想关哪一道才需要单独说。**
 
 ---
 
-## 当前状态 · 4.x 正式版
+## 当前状态 · 4.0.3 GA
+
+<p align="center">
+  <img src="./assets/readme/pulse.svg" alt="peaks-loop live metrics — 4 tiles + sparkline + pipeline progress" width="92%"/>
+</p>
+
+<p align="center">
+  <img src="./assets/readme/trace-stream.svg" alt="peaks-loop 实时 diff & log stream — code diff + 滚动日志 + 7-gate 链路" width="92%"/>
+</p>
 
 | | |
 | --- | --- |
-| **最新版本** | [`4.0.1`](https://github.com/SquabbyZ/peaks-loop/releases) — 4.x 正式版筹备中 |
-| **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测) |
+| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — GA(2026-07-30) |
+| **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测 / `peaks-slice-decompose` 切片) |
 | **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
-| **测试套件** | 219 passed · 0 failed (4 packages: peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) |
+| **测试套件** | 285+ cases · 4 packages (peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) · 80s 全量 |
 | **适配 IDE** | ✅ Claude Code · ✅ Z Code · 🚧 Codex / Cursor / Trae / Tongyi Lingma / Hermes / OpenClaw / Qoder(适配中,欢迎共建) |
 | **依赖运行时** | Node ≥ 20 |
 | **License** | MIT |
 
+### 4.0.3 GA 这一波实打实修了什么(2026-07-30)
+
+| Epic | 解决的事 | 怎么验 |
+| --- | --- | --- |
+| **测试体系从零重建** | 旧 559 文件单测卡 3 小时跑不完;现 11 test files / 161 cases 单测已上线,加上子包测试与新增切片,全量 4 packages 285+ cases 全绿,`pnpm test:full` ~80s。删旧断言、写生产合约、4 维分拆(render/behavior/integration/a11y)。 | commit `f17aa377` → `1d6233bc` · `.peaks/memory/2026-07-30-test-rebuild-epic-sediment.md` |
+| **Karpathy 评估成本自审** | LLM 在 1-2 个 slice 后不再"今天差不多了明天继续"——`karpathy-reviewer` 报 `costRatio`,>10 时 `peaks job karpathy-cost-check` 自动降级 `block`→`warn`。24h-mode 仍是 override。 | `peaks job karpathy-cost-check --review-file <path>` · 21 cases 单测 |
+| **Compact 显性可见** | `peaks compact history` 给 LLM 看本次会话所有 compact 事件;`peaks statusline compact` 单行指示给 IDE 状态栏( `--` / `compact pending (0.85)` / `REDLINE 0.95` / `just compacted (0.92→?)`)。 | `auto-compact-orchestrator` append 到 `compact-history.jsonl` · 19 cases 单测 |
+| **子包独立单测 + `pnpm test:full` 覆盖全 workspace** | `peaks-loop-mut` / `peaks-loop-shared-channel` 各自 4 维单测;`peaks-loop-shared` 0 file (passWithNoTests);root 镜像冗余删除。 | commit `593ffcdf` → `08e92d8f` · `pnpm test:full` 一次跑完 4 packages |
+| **CLI surface 收敛(73 → 5 super-commands)** | 5 个 super-command(`peaks code / audit / doctor / openspec / release / release-pack`)替换 73 个 leaf command,byte-identical 契约保留,改动对外透明。 | rid-009 · 26 routing test |
+
 ---
 
 ## 强烈推荐 · 四个项目组合起来用
@@ -153,17 +165,7 @@ npm i -g peaks-loop
 > **0 学习成本。** 这是组合起来用最大的好处 —— 不只是效果俱佳,更是因为这四个项目的**接口对齐到了"自然语言"**,你只需要说一句话,谁替你跑命令、按什么闸门、按什么战术手册,完全不用你记。
 
 <p align="center">
-  <a href="https://github.com/affaan-m/ECC">
-    <img src="https://img.shields.io/badge/ECC-affaan--m-6366f1?style=for-the-badge&logo=github&logoColor=white" alt="affaan-m/ECC" />
-  </a>
-  &nbsp;
-  <a href="https://github.com/Egonex-AI/Understand-Anything">
-    <img src="https://img.shields.io/badge/Understand--Anything-Egonex--AI-22c55e?style=for-the-badge&logo=github&logoColor=white" alt="Egonex-AI/Understand-Anything" />
-  </a>
-  &nbsp;
-  <a href="https://github.com/obra/superpowers">
-    <img src="https://img.shields.io/badge/superpowers-obra-f59e0b?style=for-the-badge&logo=github&logoColor=white" alt="obra/superpowers" />
-  </a>
+  <img src="./assets/readme/footer.svg" alt="peaks-loop 推荐组合" width="92%"/>
 </p>
 
 | 角色 | 项目 | 一句话 |
@@ -219,15 +221,6 @@ peaks-loop 的两条工程脊柱直接来自这两个项目:
 
 **最大的不同:从"代码专用"扩成"多域编排系统"。** 4.x 不再只是写代码 —— 新增了 `peaks-content`(内容生产)、`peaks-doctor`(项目健康)、`peaks-issue-fix-orchestrator`(批量修 issue)、`peaks-sop`(自定义 SOP)四条域编排链,加上 `peaks-solo` 分诊员按你说话自动判断该走哪一域。再加 9 个 IDE 适配、结晶系统重命名、post-run crystallization 机制。完整变更 → [`CHANGELOG.md`](./CHANGELOG.md)。
 
-### 4.0.0 GA 这一波实打实修了什么(2026-07-30)
-
-| Epic | 解决的事 | 怎么验 |
-| --- | --- | --- |
-| **测试体系从零重建** | 旧 559 文件单测卡 3 小时跑不完;现 219 cases 4 packages 全绿,`pnpm test:full` ~67s。删旧断言、写生产合约、4 维分拆(render/behavior/integration/a11y)。 | commit `f17aa377` → `1d6233bc` · `.peaks/memory/2026-07-30-test-rebuild-epic-sediment.md` |
-| **Karpathy 评估成本自审** | LLM 在 1-2 个 slice 后不再"今天差不多了明天继续"——`karpathy-reviewer` 报 `costRatio`,>10 时 `peaks job karpathy-cost-check` 自动降级 `block`→`warn`。24h-mode 仍是 override。 | `peaks job karpathy-cost-check --review-file <path>` · 21 cases 单测 |
-| **Compact 显性可见** | `peaks compact history` 给 LLM 看本次会话所有 compact 事件;`peaks statusline compact` 单行指示给 IDE 状态栏( `--` / `compact pending (0.85)` / `REDLINE 0.95` / `just compacted (0.92→?)`)。 | `auto-compact-orchestrator` append 到 `compact-history.jsonl` · 19 cases 单测 |
-| **子包独立单测 + `pnpm test:full` 覆盖全 workspace** | `peaks-loop-mut` / `peaks-loop-shared-channel` 各自 4 维单测;`peaks-loop-shared` 0 file (passWithNoTests);root 镜像冗余删除。 | commit `593ffcdf` → `08e92d8f` · `pnpm test:full` 一次跑完 4 packages |
-
 </details>
 
 ---
@@ -236,13 +229,19 @@ peaks-loop 的两条工程脊柱直接来自这两个项目:
 
 13 个 user skill · 全部入口都在 `skills/<name>/SKILL.md`:
 
-`/peaks-code` · `/peaks-content` · `/peaks-doctor` · `/peaks-audit` · `/peaks-final-review` · `/peaks-ide` · `/peaks-issue-fix-orchestrator` · `/peaks-sop` · `/peaks-solo` · `/peaks-resume` · `/peaks-status` · `/peaks-test` · `/peaks-slice-decompose`
+<p align="center">
+  <img src="./assets/readme/skill-index.svg" alt="peaks-loop 13 user skills 索引卡" width="92%"/>
+</p>
 
 ---
 
-## Ship 摘要(4.x · 14 rid)
+## Ship 摘要(4.x · 19 rid)
 
-`020b · 024 · 025 · 026 · 027 · 028 · 029 · 030 · 031 · 032 · 033 · 034 · GA(4.0.0) · retire-auto-compact-hook` — 涵盖 code-run、24h-mode、spillover、DAG fan-out、dashboard 聚合、CLI surface 收敛(73→9 byte-identical)等。详见 [`CHANGELOG.md`](./CHANGELOG.md)。
+`009 · 010 · 011 · 014 · 015 · 016 · 017 · 020b · 024 · 025 · 026 · 027 · 028 · 029 · 030 · 031 · 032 · 033 · 034` — 涵盖 CLI surface 收敛(73→5 byte-identical)、Trusted Publishing + OIDC、24h-mode、context spillover、DAG wave+barrier、dashboard aggregation、test-rebuild epic、karpathy-cost self-review、compact visibility、retire-auto-compact-hook 等。
+
+<p align="center">
+  <img src="./assets/readme/ship-summary.svg" alt="peaks-loop 4.x 19 rid 历程表" width="92%"/>
+</p>
 
 ---
 
@@ -253,40 +252,9 @@ peaks-loop 的两条工程脊柱直接来自这两个项目:
 - 提问 → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
 - 致敬: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) · [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill)
 - 组合推荐: [affaan-m/ECC](https://github.com/affaan-m/ECC) · [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) · [obra/superpowers](https://github.com/obra/superpowers)
-- 沉淀设计 → [`docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`](./docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md)
-- Loop Engineering 结晶设计 → [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md)
 
 ---
 
-## 发布(Trusted Publishing · OIDC)
-
-本仓库发布链路**不**使用 npm token,改用 **Trusted Publishing + OIDC**:
-
-- 维护者**不需要**也不会持有 `NPM_TOKEN` —— `~/.npmrc` 已被清理,npmjs.com 已把 Publishing access 切到 disallow tokens。
-- 触发方式 1:`git tag vX.Y.Z && git push --tags`(走 `.github/workflows/publish.yml` 的 `push: tags: v*.*.*` 触发器)。
-- 触发方式 2:GitHub UI → Actions → publish → Run workflow(手动兜底,可用于 dry-run / 补发)。
-- 每次发布跑完整链路:`install → typecheck → build → vitest → changesets version → changesets publish`,全部通过才会真正落到 npm。
-- 维护者的本地动作只有两步:`pnpm changeset` 写变更说明 + 合并 PR(剩下的 CI 自动跑)。
-
-**npmjs 侧一次性配置**(本 slice 完成后由人工做一次):
-
-1. 登录 https://www.npmjs.com → Settings → Trusted Publishers → Add GitHub Action。
-2. Owner / Org:`SquabbyZ` · Repository:`peaks-loop` · Workflow filename:`publish.yml` · Environment name:留空。
-3. 保存。
-
-**撤销** = npmjs 端删 trusted publisher,**无需** rotate token。
-
-**常见故障**:
-
-| 现象 | 原因 | 修法 |
-|------|------|------|
-| publish 步骤报 `Cannot get JWT` | 缺 `id-token: write` | 检查 `.github/workflows/publish.yml#permissions` |
-| publish 步骤报 `ENEEDAUTH` 或 `404 from registry.npmjs.org` | npmjs 端没配 trusted publisher | 走上面的 3 步配置 |
-| `changeset version` 把 `package.json` 改了我没想要 | 漏掉了手动 version | 提交前先本地 `pnpm changeset version`,CI 端为 no-op |
-| tag 推了但 CI 没跑 | tag 格式不符 `v*.*.*` | 检查 `git tag` 输出 |
-
-详细 RD 文档见 [`docs/superpowers/slices/slice-s1-trusted-publish.md`](./docs/superpowers/slices/slice-s1-trusted-publish.md)。
-
 ---
 
 <div align="center">

package/dist/cli/commands/code-runtime-commands.js

@@ -115,9 +115,20 @@ export function registerCodeRuntimeCommands(code, io) {
         '≥0.95 emits action=red-line (forced hook fires next turn).')
         .requiredOption('--project <path>', 'target project root')
         .option('--session-id <sid>', 'override session id (default: read from active presence)')
-        .option('--enforce-job-mode', 'v3.1.2: treat ≥0.85 as MANDATORY auto-compact (not advisory). Auto-enabled when job-shape.json says isJob=true.')).action(async (opts) => {
+        .option('--enforce-job-mode', 'v3.1.2: treat ≥0.85 as MANDATORY auto-compact (not advisory). Auto-enabled when job-shape.json says isJob=true.')
+        .option('--prompt-size <bytes>', 'override the bytes-from-env path; takes priority over env / statusline / transcript. Useful when CLAUDE_CONTEXT_USAGE_PERCENT is absent (e.g. Mac Claude Code).')).action(async (opts) => {
         try {
             const { readContextPercent } = await import('../../services/context/auto-compact-reader.js');
+            // rid-002: parse --prompt-size <bytes> defensively. CLI-layer
+            // guard rejects non-finite / negative values; only finite
+            // non-negative numbers reach the reader. Undefined → no override.
+            let promptSizeBytes;
+            if (opts.promptSize !== undefined) {
+                const parsed = Number(opts.promptSize);
+                if (Number.isFinite(parsed) && parsed >= 0) {
+                    promptSizeBytes = parsed;
+                }
+            }
             // v3.1.2: detect Job mode from job-shape.json when --enforce-job-mode
             // is not explicitly passed. The LLM is the source of truth for
             // whether the request is Job-shaped; the recorded decision is.
@@ -140,7 +151,8 @@ export function registerCodeRuntimeCommands(code, io) {
             const probe = readContextPercent({
                 projectRoot: opts.project,
                 sessionId: opts.sessionId ?? readActiveSid(opts.project) ?? 'unknown',
-                env: process.env
+                env: process.env,
+                promptSizeBytes
             });
             const ratioPct = (probe.ratio * 100).toFixed(1);
             let action = 'ok';
@@ -179,6 +191,7 @@ export function registerCodeRuntimeCommands(code, io) {
                 ide: probe.ide,
                 capacityBytes: probe.capacityBytes,
                 rawBytes: probe.rawBytes ?? null,
+                bytesPrompt: promptSizeBytes ?? null,
                 capturedAt: probe.capturedAt
             }, [], [
                 action === 'red-line'

package/dist/services/context/auto-compact-reader.d.ts

@@ -3,6 +3,16 @@ export interface ReadContextPercentInput {
     readonly projectRoot: string;
     readonly sessionId: string;
     readonly env?: NodeJS.ProcessEnv | undefined;
+    /**
+     * Slice 2026-07-31-rid-002: explicit byte count from `--prompt-size <bytes>`.
+     * When set to a finite non-negative number, short-circuits the entire
+     * env / statusline / transcript chain with `source: 'user-overridden'`.
+     * Mac escape hatch — Claude Code Mac does NOT inject
+     * `CLAUDE_CONTEXT_USAGE_PERCENT` into PreToolUse sub-shells, so the
+     * user (or a hook wrapper) can inject the bytes they observed themselves.
+     * Priority P0 — above everything else.
+     */
+    readonly promptSizeBytes?: number | undefined;
 }
 /**
  * Read env-var-based context percentage. Returns `null` when the env
@@ -19,12 +29,30 @@ declare function readEnvPercent(env: NodeJS.ProcessEnv, varName: string): number
  */
 declare function readClaudeStatuslinePercent(): number | null;
 /**
- * Conservative transcript-size fallback. Walks
- * `~/.claude/projects/<hash>/<sid>.jsonl` and estimates
+ * Recursive search for `<sessionId>.jsonl` under `projectsDir`. Used by
+ * `readClaudeTranscriptFallback` and exported via `_internal` so unit
+ * tests can drive it without monkey-patching `os.homedir` (which is
+ * non-configurable in ESM module namespaces).
+ *
+ * The Mac layout encodes the cwd as a single hash directory; on Mac
+ * Claude Code nests the transcript under that hash with an extra level
+ * of subdirectory we cannot predict ahead of time. A flat readdir misses
+ * that branch and returns null — the silent-failure mode that this fix
+ * closes.
+ */
+declare function findTranscriptJsonl(projectsDir: string, sessionId: string): {
+    path: string;
+    bytes: number;
+} | null;
+/**
+ * Conservative transcript-size fallback. Recursively searches
+ * `~/.claude/projects/<hash>/<sid-or-nested>.jsonl` (Mac may nest
+ *  the jsonl under an
+ * extra directory we cannot predict ahead of time) and estimates
  * `ratio = bytesUsed / 256K`. Returns the bytes seen so the
  * orchestrator can show "estimated from 124KB of 256KB transcript"
- * in the envelope. Tagged `'conservative-fallback'` so callers
- * know NOT to treat this as a hard gate.
+ * in the envelope. Tagged `'transcript-estimate'` (v2.14.0) so callers
+ * know it is a real signal, NOT a hard gate.
  */
 declare function readClaudeTranscriptFallback(sessionId: string): {
     ratio: number;
@@ -47,5 +75,6 @@ export declare const _internal: {
     readEnvPercent: typeof readEnvPercent;
     readClaudeStatuslinePercent: typeof readClaudeStatuslinePercent;
     readClaudeTranscriptFallback: typeof readClaudeTranscriptFallback;
+    findTranscriptJsonl: typeof findTranscriptJsonl;
 };
 export {};

package/dist/services/context/auto-compact-reader.js

@@ -22,7 +22,7 @@
  *   3. `ratio: 0` with `source: 'conservative-fallback'` — the
  *      orchestrator MUST NOT auto-fire compact on this signal.
  */
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { detectIdeFromEnv } from './ide-detect.js';
@@ -70,25 +70,36 @@ function readClaudeStatuslinePercent() {
     return null;
 }
 /**
- * Conservative transcript-size fallback. Walks
- * `~/.claude/projects/<hash>/<sid>.jsonl` and estimates
- * `ratio = bytesUsed / 256K`. Returns the bytes seen so the
- * orchestrator can show "estimated from 124KB of 256KB transcript"
- * in the envelope. Tagged `'conservative-fallback'` so callers
- * know NOT to treat this as a hard gate.
+ * Recursive search for `<sessionId>.jsonl` under `projectsDir`. Used by
+ * `readClaudeTranscriptFallback` and exported via `_internal` so unit
+ * tests can drive it without monkey-patching `os.homedir` (which is
+ * non-configurable in ESM module namespaces).
+ *
+ * The Mac layout encodes the cwd as a single hash directory; on Mac
+ * Claude Code nests the transcript under that hash with an extra level
+ * of subdirectory we cannot predict ahead of time. A flat readdir misses
+ * that branch and returns null — the silent-failure mode that this fix
+ * closes.
  */
-function readClaudeTranscriptFallback(sessionId) {
-    const projectsDir = join(homedir(), '.claude', 'projects');
+function findTranscriptJsonl(projectsDir, sessionId) {
     if (!existsSync(projectsDir))
         return null;
     try {
-        const { readdirSync } = require('node:fs');
-        for (const hashDir of readdirSync(projectsDir)) {
-            const candidate = join(projectsDir, hashDir, `${sessionId}.jsonl`);
-            if (existsSync(candidate)) {
-                const bytes = statSync(candidate).size;
-                const ratio = Math.min(1, bytes / (256 * 1024));
-                return { ratio, bytes };
+        const stack = [projectsDir];
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            if (dir === undefined)
+                break;
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const full = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(full);
+                }
+                else if (entry.isFile() && entry.name === `${sessionId}.jsonl`) {
+                    const bytes = statSync(full).size;
+                    return { path: full, bytes };
+                }
             }
         }
     }
@@ -97,6 +108,24 @@ function readClaudeTranscriptFallback(sessionId) {
     }
     return null;
 }
+/**
+ * Conservative transcript-size fallback. Recursively searches
+ * `~/.claude/projects/<hash>/<sid-or-nested>.jsonl` (Mac may nest
+ *  the jsonl under an
+ * extra directory we cannot predict ahead of time) and estimates
+ * `ratio = bytesUsed / 256K`. Returns the bytes seen so the
+ * orchestrator can show "estimated from 124KB of 256KB transcript"
+ * in the envelope. Tagged `'transcript-estimate'` (v2.14.0) so callers
+ * know it is a real signal, NOT a hard gate.
+ */
+function readClaudeTranscriptFallback(sessionId) {
+    const projectsDir = join(homedir(), '.claude', 'projects');
+    const hit = findTranscriptJsonl(projectsDir, sessionId);
+    if (hit === null)
+        return null;
+    const ratio = Math.min(1, hit.bytes / (256 * 1024));
+    return { ratio, bytes: hit.bytes };
+}
 /**
  * Probe the current AI CLI's context-fill ratio. Adapter-driven:
  * looks up the registered `IdeAdapter.compact` profile via
@@ -121,6 +150,24 @@ export function readContextPercent(input) {
     // through `unknown` to IdeId's wider 8-element set.
     const ideId = (detected === 'unknown' ? 'claude-code' : detected);
     const adapter = getAdapter(ideId);
+    // P0 user-overridden takes priority over env / statusline / transcript.
+    // Mac escape hatch: when the CLI/helper passes `--prompt-size <bytes>`,
+    // honor that number directly. Do NOT read env, statusline, or transcript
+    // — user intent always wins. Negative / non-finite values are ignored
+    // here (CLI layer validates >= 0); they fall through to the chain below.
+    if (input.promptSizeBytes !== undefined &&
+        Number.isFinite(input.promptSizeBytes) &&
+        input.promptSizeBytes >= 0) {
+        const ratio = Math.min(1, input.promptSizeBytes / capacityBytes);
+        return {
+            ratio,
+            source: 'user-overridden',
+            rawBytes: input.promptSizeBytes,
+            capacityBytes,
+            ide: ideId,
+            capturedAt
+        };
+    }
     // Primary: read the adapter-declared env-var (no hard-coded IDE names).
     if (adapter.compact) {
         const primary = readEnvPercent(env, adapter.compact.envVarForContextPercent);
@@ -147,7 +194,7 @@ export function readContextPercent(input) {
         if (fallback !== null) {
             return {
                 ratio: fallback.ratio,
-                source: 'conservative-fallback',
+                source: 'transcript-estimate',
                 rawBytes: fallback.bytes,
                 capacityBytes,
                 ide: ideId,
@@ -161,4 +208,4 @@ export function readContextPercent(input) {
     return { ratio: 0, source: 'conservative-fallback', capacityBytes, ide: ideId, capturedAt };
 }
 /** Re-export the env-var probe for unit tests. */
-export const _internal = { readEnvPercent, readClaudeStatuslinePercent, readClaudeTranscriptFallback };
+export const _internal = { readEnvPercent, readClaudeStatuslinePercent, readClaudeTranscriptFallback, findTranscriptJsonl };

package/dist/services/context/auto-compact-types.d.ts

@@ -152,10 +152,18 @@ export interface ContextPercentProbe {
     readonly ratio: number;
     /**
      * Adapter-driven source tag. Fixed values:
+     *   - `user-overridden`         (v2.14.0 rid-002: explicit `--prompt-size
+     *                                <bytes>` from the CLI / hook wrapper —
+     *                                takes priority P0 over EVERY other source.
+     *                                Mac escape hatch.)
      *   - `${ideId}-env`            (e.g. `claude-code-env`)
      *   - `statusline-poll`         (Claude Code MVP fallback)
-     *   - `conservative-fallback`   (transcript size estimate OR
-     *                                no signal available — caller
+     *   - `transcript-estimate`     (v2.14.0 Mac-aware: recursive
+     *                                readdir under ~/.claude/projects/
+     *                                finds <sid>.jsonl and reports
+     *                                bytes/256K; a real signal, NOT
+     *                                a hard gate)
+     *   - `conservative-fallback`   (no signal available — caller
      *                                MUST NOT treat as hard gate)
      * Future IDEs may add per-ide sources; the type accepts any
      * string to keep the schema forward-compatible.

package/package.json

@@ -1,8 +1,52 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.1",
+  "version": "4.0.4",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
+  "keywords": [
+    "peaks-loop",
+    "loop-engineering",
+    "ai-orchestration",
+    "ai-coding-agent",
+    "ai-programmer",
+    "multi-agent",
+    "claude-code",
+    "codex",
+    "z-code",
+    "cursor",
+    "trae",
+    "tongyi-lingma",
+    "agent-harness",
+    "agentic-engineering",
+    "autonomous-workflow",
+    "workflow-orchestration",
+    "llm-workflow",
+    "long-running-task",
+    "sub-agent-dispatch",
+    "dag-orchestration",
+    "slice-decomposition",
+    "sop",
+    "openspec",
+    "karpathy",
+    "darwin",
+    "anti-drift",
+    "evolution-evaluation",
+    "ci-cd",
+    "github-actions",
+    "trusted-publishing",
+    "oidc",
+    "monorepo",
+    "pnpm",
+    "vitest",
+    "code-review",
+    "tdd",
+    "security-scan",
+    "lint",
+    "typecheck",
+    "devtool",
+    "cli",
+    "developer-tools"
+  ],
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -54,9 +98,9 @@
     "headroom-ai": "0.22.4",
     "yaml": "^2.9.0",
     "zod": "^3.25.76",
-    "peaks-loop-mut": "0.1.3",
-    "peaks-loop-shared": "0.0.29",
-    "peaks-loop-shared-channel": "0.0.8"
+    "peaks-loop-mut": "0.1.7",
+    "peaks-loop-shared": "0.0.33",
+    "peaks-loop-shared-channel": "0.0.12"
   },
   "peerDependencies": {
     "@alibaba-group/open-code-review": "1.3.1"