peaks-loop 4.0.24 → 4.0.25

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 4.0.25 — 2026-09-01 (codegraph hint fix + post-slice re-index + frontend ACL)
+
+**1 atomic commit from session 2026-09-01-session-fdd7aa** (user feedback batch):
+
+- `70184e1f` feat(peaks-code): apply feedback batch — codegraph hint fix + post-slice re-index + frontend ACL + headroom sediment
+
+**Highlights**:
+
+1. **codegraph 提示泄漏修复** — `peaks codegraph <subcommand>` 透传上游 stdout/stderr 前，新增 `rewriteBareCodegraphHints` 纯函数，把上游裸 `codegraph <sub>` 提示改写为 `peaks codegraph <sub>`（上游 binary 是嵌套传递依赖、不在 PATH，裸命令提示会误导 LLM 敲 "command not found"）。8 个 vitest 用例：quoted/backtick hint、7 子命令全量、幂等、`@colbymchenry/codegraph` 包名不误伤。
+
+2. **codegraph post-slice 增量刷新** — peaks-code 编排规范：每个 slice/task 完成后主动 `peaks codegraph index`，让下一 slice 的 affected/query/context 基于最新代码图，而不是过期的 pre-slice 图。
+
+3. **前端防腐层 ACL 标准** — peaks-rd 新增硬约束：前端内部模型不被外部/API 形状污染；DTO ↔ ViewModel 映射（外部字段 → 内部字段）；Mapper 聚合单文件（如 `mappers/user.mapper.ts`），不散落各页面。QA / code-review 校验。
+
+4. **headroom-ai 半成品 finding sediment** — 记录 headroom proxy 后端（N-7）未接、当前 0 token 节省；省 token 主杠杆是 G7 metadata-only + auto-compact + cache 对齐。
+
 ## 4.0.24 — 2026-08-12 (zod v4 + Context7 + Step 2.5 best-practice scan)
 
 **6 atomic commits from session 2026-08-12-session-4aaf2b** (5 functional + 1 sediment):

package/dist/cli/commands/codegraph-commands.d.ts

@@ -1,3 +1,13 @@
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
+/**
+ * Rewrites bare upstream `codegraph <subcommand>` hints to the peaks-loop
+ * equivalent (`peaks codegraph <subcommand>`). The upstream binary is a
+ * nested transitive dependency and is NOT on PATH, so an LLM that follows
+ * a bare hint like `Run "codegraph init" to initialize` would hit
+ * "command not found". Already-prefixed `peaks codegraph ...` hints and
+ * other `codegraph` references (e.g. `@colbymchenry/codegraph`) are left
+ * untouched.
+ */
+export declare function rewriteBareCodegraphHints(text: string): string;
 export declare function registerCodegraphCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/codegraph-commands.js

@@ -24,6 +24,18 @@ function printCodegraphFailure(io, command, error, asJson, exitCode = 1) {
     printResult(io, fail(command, 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(getErrorMessage(error)), {}, ['Check the codegraph command options and project path before retrying']), asJson);
     process.exitCode = exitCode;
 }
+/**
+ * Rewrites bare upstream `codegraph <subcommand>` hints to the peaks-loop
+ * equivalent (`peaks codegraph <subcommand>`). The upstream binary is a
+ * nested transitive dependency and is NOT on PATH, so an LLM that follows
+ * a bare hint like `Run "codegraph init" to initialize` would hit
+ * "command not found". Already-prefixed `peaks codegraph ...` hints and
+ * other `codegraph` references (e.g. `@colbymchenry/codegraph`) are left
+ * untouched.
+ */
+export function rewriteBareCodegraphHints(text) {
+    return text.replace(/(?<![\w-])(?<!peaks\s)codegraph(?=\s+(?:status|init|index|query|files|context|affected)\b)/g, 'peaks codegraph');
+}
 async function runCodegraphCommand(io, command, options, asJson) {
     try {
         const invocation = createCodegraphInvocation(options);
@@ -33,11 +45,13 @@ async function runCodegraphCommand(io, command, options, asJson) {
             return;
         }
         const didFail = result.exitCode !== null && result.exitCode !== 0;
-        if (result.stdout.length > 0) {
-            io.stdout((didFail ? redactSensitiveErrorMessage(result.stdout) : result.stdout).trimEnd());
+        const stdout = rewriteBareCodegraphHints(result.stdout);
+        const stderr = rewriteBareCodegraphHints(result.stderr);
+        if (stdout.length > 0) {
+            io.stdout((didFail ? redactSensitiveErrorMessage(stdout) : stdout).trimEnd());
         }
-        if (result.stderr.length > 0) {
-            io.stderr((didFail ? redactSensitiveErrorMessage(result.stderr) : result.stderr).trimEnd());
+        if (stderr.length > 0) {
+            io.stderr((didFail ? redactSensitiveErrorMessage(stderr) : stderr).trimEnd());
         }
         if (didFail) {
             process.exitCode = result.exitCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.24",
+  "version": "4.0.25",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -102,10 +102,10 @@
     "headroom-ai": "0.22.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.9",
-    "peaks-loop-mut": "0.1.22",
-    "peaks-loop-shared": "0.0.58",
-    "peaks-loop-shared-channel": "0.0.26"
+    "peaks-loop-internal-runtime": "0.0.10",
+    "peaks-loop-mut": "0.1.23",
+    "peaks-loop-shared-channel": "0.0.27",
+    "peaks-loop-shared": "0.0.59"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

package/skills/bee/peaks-rd/SKILL.md

@@ -189,6 +189,12 @@ When RD work creates a frontend application and the user has not specified a tec
 
 → see `references/frontend-project-generation.md` for the scaffold protocol.
 
+## Frontend anti-corruption layer (ACL)
+
+When RD work touches the frontend (pure frontend or full-stack), enforce the ACL discipline: the frontend's internal model is never polluted by external / API shapes. DTO ↔ ViewModel mapping converts external fields to internal fields at the boundary, and all conversion logic lives in one mapper file per domain (e.g. `mappers/user.mapper.ts`) — never scattered across pages. Hard constraint, verified by QA / code-review.
+
+→ see `references/frontend-acl-mapper.md` for the three rules + reference shape + verification.
+
 ## Artifact and standards output
 
 When project identification or scanning produces reports, matrices, maps, plans, or validation files, write them under the configured Peaks-Loop artifact workspace (default: `.peaks/_runtime/<sessionId>/rd/`). Do not default to a git-backed artifact repository or external artifact sync. Route standards mutations through `peaks standards init/update`; do not hand-write. Do not update user-global `~/.claude/rules/**` from this workflow.
@@ -267,6 +273,7 @@ Index of every `references/` file in this skill. Read on demand.
 | `references/compact-handoff.md` | RD compact handoff capsule. |
 | `references/external-references.md` | External 3rd-party inventory. |
 | `references/frontend-project-generation.md` | React + Vite + shadcn/ui default. |
+| `references/frontend-acl-mapper.md` | 前端防腐层 ACL + DTO↔VM 映射 + Mapper 聚合硬约束. |
 | `references/library-version-awareness.md` | Breaking-change gate + freshness check. |
 | `references/mandatory-perf-baseline.md` | RD-side perf baseline + `peaks perf baseline` workflow. |
 | `references/matt-pocock-integration.md` | Matt Pocock skills as references. |

package/skills/bee/peaks-rd/references/frontend-acl-mapper.md

@@ -0,0 +1,29 @@
+# Frontend anti-corruption layer (ACL) + Mapper aggregation (RD)
+
+> Body of `## Frontend anti-corruption layer (ACL)`. When RD work touches the frontend (pure frontend OR full-stack), the frontend's internal model MUST NOT be polluted by external / API data shapes. Enforce the anti-corruption layer (ACL) discipline on every frontend slice.
+
+## Three hard rules (BLOCKING)
+
+1. **ACL — protect the frontend internals.** The frontend never consumes backend / API DTOs directly in components, pages, hooks, or stores. An anti-corruption layer translates every external shape into an internal one at the boundary.
+
+2. **DTO ↔ ViewModel mapping — external fields → internal fields.** API / DTO field names and nesting are external concerns. Map them to internal ViewModel fields at the boundary. Backend field/schema drift must not leak past the mapper.
+
+3. **Mapper aggregation — one file per domain.** All conversion logic for a domain lives in exactly one mapper file (e.g. `mappers/user.mapper.ts`), never scattered across pages / components. A page or component imports the mapper; it does not inline a mapping.
+
+## Reference shape
+
+```ts
+// mappers/user.mapper.ts — the ONLY place user DTO ↔ ViewModel mapping lives
+import type { UserDTO } from '@/api/types';        // external
+import type { UserViewModel } from '@/models/user'; // internal
+
+export function toUserViewModel(dto: UserDTO): UserViewModel {
+  return { id: dto.user_id, name: dto.display_name, avatar: dto.avatar_url };
+}
+```
+
+Components / hooks import `toUserViewModel`; they never destructure `dto.user_id` directly.
+
+## Verification
+
+QA / code-review must flag: (a) any component / hook / store consuming a `*DTO` or a raw API response field directly, (b) any `*.mapper.ts` duplication across pages. The mapper is the single translation seam between external DTOs and the internal ViewModel.

package/skills/peaks-code/references/codegraph-orchestration.md

@@ -2,4 +2,10 @@
 
 > Body of `## Codegraph orchestration context`. Code treats `peaks codegraph affected --project <path> <changed-files...> --json` as an optional project-analysis enhancement that informs the role handoff between PRD, RD, and QA. The output is untrusted supporting evidence — Code must not treat codegraph output as approval for scope, design, or QA verdict.
 
-Do not run upstream installer flows, mutate agent settings, or commit `.codegraph/` artifacts into git. Peaks-Loop gates remain authoritative; codegraph context is a hint, never a substitute for role-skill output.
+Do not run upstream installer flows, mutate agent settings, or commit `.codegraph/` artifacts into git. Peaks-Loop gates remain authoritative; codegraph context is a hint, never a substitute for role-skill output.
+
+## Post-slice incremental re-index (slice 2026-09-01-feedback)
+
+After each slice / task completes (RD done → QA done), the orchestrator MUST proactively run `peaks codegraph index --project <path>` to refresh the codegraph so the next slice's `affected` / `query` / `context` reflect the latest code — never a stale pre-slice graph. `index` is an incremental refresh; `peaks codegraph init` runs once per project, `index` runs after every slice.
+
+The upstream bare `codegraph <subcommand>` binary is NOT on PATH — always route through `peaks codegraph <subcommand>`. (Upstream's own `status` output prints `Run "codegraph init" to initialize`; that bare-command hint is misleading in the peaks-loop context. A separate fix slice rewrites it to `peaks codegraph init`.)