peaks-loop 4.0.21 → 4.0.24

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/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/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: