peaks-loop 4.0.23 → 4.0.25

package/schemas/context.schema.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
     "version": {
@@ -11,7 +12,8 @@
     },
     "generatedAt": {
       "type": "string",
-      "format": "date-time"
+      "format": "date-time",
+      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
     },
     "sha256": {
       "type": "string",
@@ -39,7 +41,8 @@
               },
               "lines": {
                 "type": "integer",
-                "minimum": 0
+                "minimum": 0,
+                "maximum": 9007199254740991
               },
               "hash": {
                 "type": "string"
@@ -105,6 +108,9 @@
         },
         "deps": {
           "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
           "additionalProperties": {
             "type": "object",
             "properties": {
@@ -166,7 +172,8 @@
               },
               "fetchedAt": {
                 "type": "string",
-                "format": "date-time"
+                "format": "date-time",
+                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
               },
               "contentHash": {
                 "type": "string"
@@ -181,7 +188,8 @@
                     },
                     "tokenEstimate": {
                       "type": "integer",
-                      "minimum": 0
+                      "minimum": 0,
+                      "maximum": 9007199254740991
                     },
                     "excerpt": {
                       "type": "string"
@@ -319,11 +327,13 @@
         },
         "renderedAt": {
           "type": "string",
-          "format": "date-time"
+          "format": "date-time",
+          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
         },
         "sizeBytes": {
           "type": "integer",
-          "minimum": 0
+          "minimum": 0,
+          "maximum": 9007199254740991
         },
         "truncated": {
           "type": "boolean"
@@ -355,6 +365,5 @@
     "tokenizer",
     "renderer"
   ],
-  "additionalProperties": false,
-  "$schema": "http://json-schema.org/draft-07/schema#"
+  "additionalProperties": false
 }

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

@@ -339,3 +339,20 @@ Verify the surface (no need to re-derive):
 1. `peaks audit red-lines --project .` reports `proseOnly: 0` for any shipped L2 surface.
 2. `peaks lease-metrics --rate` after a clean run reports `estimatedLeaked: 0`.
 3. `peaks worktree list` returns 0 active leases after a clean run.
+
+## Peaks-Loop Step 2.5 sub-step: best-practice scan handoff
+
+When peaks-prd's `businessGoal` artifact transitions to `complete` + the sub-step has not
+yet fired for this intent, peaks-prd MUST emit a sub-step handoff to Step 2.5 best-practice
+scan BEFORE transitioning to Step 3 RD.
+
+**Handoff contract:**
+- Input: `businessGoal` (natural language) + `.peaks/project-scan/project-scan.md` (auto-generated by `peaks workspace init`)
+- Output: best-practice scan artifact at `.peaks/_runtime/<sessionId>/best-practice/<requestId>.md`
+- Trigger CLI: `peaks best-practice-scan --project <repo> --intent "<businessGoal>" --json`
+- Status: `awaiting-user-ack` (3 valid user responses per spec §7: 接受 / 接受方案 N / 拒绝 + 原因)
+
+**State machine:** peak-prd's state machine refuses `--allow-incomplete` style bypass for
+this sub-step. Silent auto-accept is NOT allowed — user explicit ack is mandatory.
+
+**Reference:** See `skills/peaks-code/SKILL.md` §Step 2.5 for the full sub-step contract.

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/SKILL.md

@@ -189,7 +189,7 @@ See also: references/session-overload-signal-index.md for the 7-signal lookup ta
 | Drift ID | Step | Symptom | Fix | Inline location |
 |---|---|---|---|---|
 | **D-001** | 0.8 | `peaks code detect-job --is-job ...` rejected with `error: unknown option '--is-job'` | Use `peaks job init --job-id <jid> --slice-list <list> --main-loop-strategy <single\|rotating>` | §Step 0.8 first paragraph |
-| **D-002** | 2.5 | `peaks session title --session-id <sid> ...` rejected with `error: unknown option '--session-id'` (this is the bare `<sid>` anti-pattern) | sid is positional: `peaks session title <sessionId> "<title>" --json` | §Step 2.5 |
+| **D-002** | 2.5 | `peaks session title --session-id <sid> ...` rejected with `error: unknown option '--session-id'` (this is the bare `<sid>` anti-pattern) | sid is positional: `peaks session title <sessionId> "<title>" --json` | §Step 2.5a |
 | **D-003** | 0.8 | `JOB_SHAPE_NOT_DECIDED` exception expected but never thrown | Current behavior is `peaks job status` reports `done: 0` passively — treat as recoverable miss, not hard error | §Step 0.8 third paragraph |
 | **D-010** | 11c | `peaks memory extract` returns `extractedCount: 0` despite `<!-- peaks-memory:start -->` existing | Block requires YAML frontmatter (`title:` + `kind:` + `---`) + closing `<!-- peaks-memory:end -->`. Bare `peaks-memory:start` is parsed silently but produces no writes | §Step 11c + 11d |
 
@@ -213,6 +213,33 @@ Before handing off to `peaks-rd`, scan the project and record findings to `.peak
 
 When the project has no live backend (no swagger.json, no API server), Code must activate frontend-only mode. The CLI is authoritative — read `frontendOnly` and `frontendOnlyReason` from `peaks scan archetype --json`. → `references/frontend-only-mode.md`.
 
+## Peaks-Loop Step 2.5: Best-practice scan (BPS) (NEW 2026-08-12)
+
+Inserted between current Step 2 (PRD) and Step 3 (RD). Sub-step does a **business-aware,
+language-aware, LLM-recommended best-practice scan** before RD kicks off.
+
+**Trigger:** Fires at peak-prd exit when business-goal is non-empty + sub-step not yet
+triggered for this intent.
+
+**Action sequence:**
+1. Detect project language (TS / JS / Python / Go / Java) via `language-detector` (5-lang
+   priority chain).
+2. Query Context7 (`@upstash/context7-mcp@^4.0.2`, installed as peaks-loop production dep)
+   priority-1 with 30s timeout.
+3. WebSearch fallback when Context7 returns empty / errors.
+4. Synthesize 8-row markdown comparison table per `output-formatter`.
+5. LLM picks one recommendation (★ marker) with reasoning block.
+6. **Mandatory ⚠️ catch gate** — user explicitly acks / picks alt / rejects + reason.
+
+**Out of scope for this sub-step:**
+- ❌ No changes to RD dispatch Karpathy prose (Step 3 unchanged)
+- ❌ No changes to QA / SC / TXT skills
+- ❌ No new `peaks-best-practice` standalone skill (sub-step inside peaks-prd only)
+- ❌ No framework-knowledge persistent index (future slice)
+
+**Reference:** Spec at `.peaks/_runtime/<sessionId>/sc/spec-step-2-5-best-practice-scan.md`
+§4-7. Implementation: `src/cli/commands/best-practice-scan-command.ts` + `src/services/best-practice/`.
+
 ## Peaks-Loop Request type classification + Workflow order + Transition verification gates
 
 The 6-type table + 11-step order + 7 transition gates (A-G) live in `references/workflow-gates-and-types.md`. peaks-code narrative references Gate A-G — keep both files in lockstep.

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`.)

package/skills/peaks-code/references/skill-presence-and-title.md

@@ -1,6 +1,6 @@
-# Step 2 + 2.5 — Skill presence and session title
+# Step 2 + 2.5a — Skill presence and session title
 
-> Combined body for `### Peaks-Loop Step 2: Re-set skill presence with the chosen mode` and `### Peaks-Loop Step 2.5: Set session title`.
+> Combined body for `### Peaks-Loop Step 2: Re-set skill presence with the chosen mode` and `### Peaks-Loop Step 2.5a: Set session title`.
 
 ## Step 2 — Re-set skill presence
 
@@ -20,7 +20,7 @@ Then display the compact status header: `Peaks-Loop Skill: peaks-code | Peaks-Lo
 
 Update with `peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate <gate>` when gates change. The presence file persists across the full workflow lifecycle — clear is owned by workflow terminalize; follow-up workflows re-claim via new workflow init.
 
-## Step 2.5 — Set session title
+## Step 2.5a — Set session title
 
 Extract a short (8-20 Chinese characters, or 4-10 English words) descriptive title from the user's first request. The title should capture the core task — e.g. "修复登录页OAuth回调异常", "添加暗色模式开关", "搭建项目基础架构". Then run: