peaks-loop 4.1.7 → 4.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +72 -0
  3. package/config/eslint/tsconfig.lint.json +1 -0
  4. package/dist/cli/commands/code-gate-step-08-command.js +21 -11
  5. package/dist/cli/commands/code-gate-step-08-remedy.d.ts +17 -0
  6. package/dist/cli/commands/code-gate-step-08-remedy.js +76 -0
  7. package/dist/cli/commands/code-job-shape-commands.js +21 -5
  8. package/dist/cli/commands/dispatch-from-dag.js +17 -0
  9. package/dist/cli/commands/job-commands.js +15 -5
  10. package/dist/cli/commands/job-init-status-commands.js +45 -5
  11. package/dist/cli/commands/lint-baseline-command.d.ts +15 -0
  12. package/dist/cli/commands/lint-baseline-command.js +64 -0
  13. package/dist/cli/commands/lint-commands.js +27 -51
  14. package/dist/cli/commands/request-command-options.d.ts +6 -0
  15. package/dist/cli/commands/request-commands.js +2 -0
  16. package/dist/cli/commands/request-mark-qa-initiated-command.d.ts +3 -0
  17. package/dist/cli/commands/request-mark-qa-initiated-command.js +80 -0
  18. package/dist/cli/commands/request-transition-failures.js +1 -0
  19. package/dist/cli/commands/reviewer-commands.d.ts +6 -6
  20. package/dist/cli/commands/reviewer-commands.js +154 -56
  21. package/dist/cli/commands/reviewer-config-commands.d.ts +9 -0
  22. package/dist/cli/commands/reviewer-config-commands.js +133 -0
  23. package/dist/services/artifacts/artifact-lint-service.js +102 -27
  24. package/dist/services/artifacts/artifact-prerequisites.d.ts +1 -0
  25. package/dist/services/artifacts/artifact-prerequisites.js +13 -13
  26. package/dist/services/artifacts/artifact-template-bodies.d.ts +7 -1
  27. package/dist/services/artifacts/artifact-template-bodies.js +14 -3
  28. package/dist/services/artifacts/artifact-templates.d.ts +6 -1
  29. package/dist/services/artifacts/artifact-templates.js +8 -5
  30. package/dist/services/artifacts/backcompat-acceptance.js +7 -5
  31. package/dist/services/artifacts/prerequisite-checks.d.ts +34 -9
  32. package/dist/services/artifacts/prerequisite-checks.js +28 -9
  33. package/dist/services/artifacts/qa-initiated-marker.d.ts +24 -0
  34. package/dist/services/artifacts/qa-initiated-marker.js +36 -0
  35. package/dist/services/artifacts/request-artifact-metadata.d.ts +9 -0
  36. package/dist/services/artifacts/request-artifact-metadata.js +9 -0
  37. package/dist/services/artifacts/request-artifact-service.js +6 -10
  38. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +2 -1
  39. package/dist/services/artifacts/request-artifact-state-helpers.js +6 -3
  40. package/dist/services/code/job-shape-provisional.d.ts +51 -0
  41. package/dist/services/code/job-shape-provisional.js +80 -0
  42. package/dist/services/code/step-08-gate.d.ts +24 -12
  43. package/dist/services/code/step-08-gate.js +54 -97
  44. package/dist/services/code/step-08-session-readers.d.ts +27 -0
  45. package/dist/services/code/step-08-session-readers.js +105 -0
  46. package/dist/services/dispatch/isolation-lease.d.ts +3 -2
  47. package/dist/services/dispatch/isolation-lease.js +15 -6
  48. package/dist/services/job/subagent-job-wrapper.d.ts +20 -7
  49. package/dist/services/job/subagent-job-wrapper.js +53 -5
  50. package/dist/services/lint/eslint-report.d.ts +19 -0
  51. package/dist/services/lint/eslint-report.js +60 -0
  52. package/dist/services/lint/eslint-runner-support.d.ts +18 -1
  53. package/dist/services/lint/eslint-runner-support.js +35 -2
  54. package/dist/services/lint/eslint-runner-types.d.ts +21 -1
  55. package/dist/services/lint/eslint-runner.js +43 -33
  56. package/dist/services/prd/gate-evidence-derivation.d.ts +2 -4
  57. package/dist/services/prd/gate-evidence-derivation.js +3 -1
  58. package/dist/services/qa/bdd-test-style-contract.d.ts +17 -0
  59. package/dist/services/qa/bdd-test-style-contract.js +41 -0
  60. package/dist/services/qa/bdd-test-style-verifier.d.ts +9 -6
  61. package/dist/services/qa/bdd-test-style-verifier.js +24 -37
  62. package/dist/services/rd/reviewer-dispatch-policy.d.ts +18 -14
  63. package/dist/services/rd/reviewer-dispatch-policy.js +14 -11
  64. package/dist/services/release/release-state.js +20 -5
  65. package/dist/services/reviewer/model-family.js +1 -1
  66. package/dist/services/reviewer/reviewer-artifacts.d.ts +12 -0
  67. package/dist/services/reviewer/reviewer-artifacts.js +67 -0
  68. package/dist/services/reviewer/reviewer-config-write.d.ts +18 -0
  69. package/dist/services/reviewer/reviewer-config-write.js +71 -0
  70. package/dist/services/reviewer/reviewer-config.d.ts +33 -5
  71. package/dist/services/reviewer/reviewer-config.js +102 -46
  72. package/dist/services/reviewer/reviewer-envelopes.d.ts +8 -0
  73. package/dist/services/reviewer/reviewer-envelopes.js +53 -0
  74. package/dist/services/reviewer/reviewer-service.d.ts +7 -4
  75. package/dist/services/reviewer/reviewer-service.js +46 -52
  76. package/dist/services/reviewer/reviewer-types.d.ts +9 -1
  77. package/dist/services/session/getSessionDir.js +16 -7
  78. package/dist/services/web/daemon-registry.d.ts +6 -4
  79. package/dist/services/web/daemon-registry.js +92 -17
  80. package/package.json +5 -5
  81. package/schemas/reviewer-envelope.schema.json +1 -1
  82. package/skills/bee/peaks-reviewer/SKILL.md +20 -4
  83. package/skills/bee/peaks-reviewer/references/reviewer-schema.md +12 -7
  84. package/skills/bee/peaks-security-audit/SKILL.md +20 -0
  85. package/skills/peaks-code/references/step-0-8-gate.md +2 -1
@@ -4,7 +4,7 @@
4
4
  * WRITE goes through `assertUnder` first — the slice-wide guard against an
5
5
  * artifact escaping `<root>/.peaks/_runtime/<sid>/web/` (AC1).
6
6
  */
7
- import { existsSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
7
+ import { constants, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
8
8
  import { dirname } from 'node:path';
9
9
  import { assertUnder, webDaemonDir, webDaemonInfoPath, webSpawnLockPath } from './web-artifact-paths.js';
10
10
  import { parseDaemonInfo } from './web-protocol.js';
@@ -115,38 +115,111 @@ export function isProcessAlive(pid) {
115
115
  return error.code === 'EPERM';
116
116
  }
117
117
  }
118
+ const SPAWN_LOCK_ATTEMPTS = 3;
118
119
  /**
119
- * Take the cold-start lock (O_EXCL create). Returns `false` when another
120
- * process holds a live lock, and reclaims a STALE one — owner pid dead, or
121
- * older than `SPAWN_LOCK_STALE_MS` — before retrying once (tech-doc §1.4).
120
+ * Take the cold-start lock. Returns `false` when another process holds a live
121
+ * lock; reclaims a STALE one by renaming it to a per-call quarantine. Unlink-
122
+ * then-create is not atomic (two callers could both return true), so the
123
+ * replacement is created and identity-verified, and a moved fresh lock is
124
+ * restored rather than replaced.
122
125
  */
123
126
  export function acquireSpawnLock(projectRoot, sessionId) {
124
127
  const target = webSpawnLockPath(projectRoot, sessionId);
125
128
  assertUnder(target, webDaemonDir(projectRoot, sessionId));
126
129
  mkdirSync(dirname(target), { recursive: true, mode: DAEMON_DIR_MODE });
127
- if (tryCreateSpawnLock(target)) {
128
- return true;
130
+ let mine = null;
131
+ for (let attempt = 0; attempt < SPAWN_LOCK_ATTEMPTS; attempt += 1) {
132
+ const created = tryCreateSpawnLock(target);
133
+ if (created !== null) {
134
+ mine = created;
135
+ if (ownsLockFile(target, created))
136
+ return true;
137
+ continue;
138
+ }
139
+ const existing = readSpawnLock(target);
140
+ if (isOwnLock(existing, mine))
141
+ return true;
142
+ if (isSpawnLockHeld(target, existing))
143
+ return false;
144
+ return reclaimSpawnLock(target, existing);
129
145
  }
130
- const existing = readSpawnLock(target);
131
- const ageMs = existing === null ? Number.NaN : Date.now() - Date.parse(existing.startedAt);
132
- if (existing !== null && isProcessAlive(existing.pid) && ageMs <= SPAWN_LOCK_STALE_MS) {
146
+ return false;
147
+ }
148
+ function isOwnLock(existing, mine) {
149
+ return (existing !== null &&
150
+ mine !== null &&
151
+ existing.pid === mine.pid &&
152
+ existing.startedAt === mine.startedAt);
153
+ }
154
+ /** Unreadable is held while young; readable is held while its owner is alive and young. */
155
+ function isSpawnLockHeld(target, existing) {
156
+ if (existing === null) {
157
+ return lockFileAgeMs(target) <= SPAWN_LOCK_STALE_MS;
158
+ }
159
+ return (isProcessAlive(existing.pid) &&
160
+ Date.now() - Date.parse(existing.startedAt) <= SPAWN_LOCK_STALE_MS);
161
+ }
162
+ /** True only when `target` still holds the exact body this call created. */
163
+ function ownsLockFile(target, created) {
164
+ const now = readSpawnLock(target);
165
+ return now !== null && now.pid === created.pid && now.startedAt === created.startedAt;
166
+ }
167
+ let reclaimSerial = 0; // one quarantine per call, so reclaimers never share a path
168
+ /**
169
+ * Take a stale lock by renaming it to this call's quarantine; true only when
170
+ * the verified replacement was created.
171
+ */
172
+ function reclaimSpawnLock(target, existing) {
173
+ reclaimSerial += 1;
174
+ const quarantine = `${target}.reclaim-${String(process.pid)}-${String(reclaimSerial)}`;
175
+ try {
176
+ renameSync(target, quarantine);
177
+ }
178
+ catch {
133
179
  return false;
134
180
  }
181
+ const moved = readSpawnLock(quarantine);
182
+ const movedIsStale = existing === null
183
+ ? moved === null && lockFileAgeMs(quarantine) > SPAWN_LOCK_STALE_MS
184
+ : moved !== null && moved.pid === existing.pid && moved.startedAt === existing.startedAt;
185
+ if (!movedIsStale) {
186
+ restoreQuarantinedLock(quarantine, target);
187
+ return false;
188
+ }
189
+ rmSync(quarantine, { force: true });
190
+ const created = tryCreateSpawnLock(target);
191
+ return created !== null && ownsLockFile(target, created);
192
+ }
193
+ /** Put a freshly-moved lock back without ever replacing a lock that now owns the path. */
194
+ function restoreQuarantinedLock(quarantine, target) {
135
195
  try {
136
- unlinkSync(target);
196
+ copyFileSync(quarantine, target, constants.COPYFILE_EXCL);
197
+ rmSync(quarantine, { force: true });
198
+ }
199
+ catch (error) {
200
+ if (error.code !== 'EEXIST')
201
+ throw error;
202
+ rmSync(quarantine, { force: true });
203
+ }
204
+ }
205
+ /** File age, used only when the body cannot be read; `Infinity` when it vanished. */
206
+ function lockFileAgeMs(target) {
207
+ try {
208
+ return Date.now() - statSync(target).mtimeMs;
137
209
  }
138
210
  catch {
139
- // Racers: whoever wins the unlink still has to win the O_EXCL create below.
211
+ return Number.POSITIVE_INFINITY;
140
212
  }
141
- return tryCreateSpawnLock(target);
142
213
  }
143
- /** Release the spawn lock, but only when this process is its owner. */
214
+ /** Release the spawn lock, but only when this process provably owns it. */
144
215
  export function releaseSpawnLock(projectRoot, sessionId) {
145
216
  const target = webSpawnLockPath(projectRoot, sessionId);
146
217
  const existing = readSpawnLock(target);
147
- if (existing !== null && existing.pid !== process.pid) {
218
+ if (existing !== null && existing.pid !== process.pid)
219
+ return;
220
+ // A young unreadable body may be a live creator mid-write; do not unlink it.
221
+ if (existing === null && lockFileAgeMs(target) <= SPAWN_LOCK_STALE_MS)
148
222
  return;
149
- }
150
223
  try {
151
224
  unlinkSync(target);
152
225
  }
@@ -166,15 +239,17 @@ export function listSessionDaemons(projectRoot, sessionId) {
166
239
  }
167
240
  function tryCreateSpawnLock(target) {
168
241
  const body = { pid: process.pid, startedAt: new Date().toISOString() };
242
+ let created;
169
243
  try {
170
244
  writeFileSync(target, JSON.stringify(body), { flag: 'wx', encoding: 'utf8' });
171
- return true;
245
+ created = true;
172
246
  }
173
247
  catch {
174
248
  // `EEXIST` (held) and any other write failure both mean "not acquired".
175
249
  // The caller either waits for the holder or surfaces a readiness timeout.
176
- return false;
250
+ created = false;
177
251
  }
252
+ return created ? body : null;
178
253
  }
179
254
  function readSpawnLock(target) {
180
255
  try {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.7",
3
+ "version": "4.1.9",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -129,10 +129,10 @@
129
129
  "picomatch": "4.0.4",
130
130
  "yaml": "^2.9.0",
131
131
  "zod": "^4.4.3",
132
- "peaks-loop-internal-runtime": "0.0.47",
133
- "peaks-loop-mut": "0.1.61",
134
- "peaks-loop-shared": "0.0.96",
135
- "peaks-loop-shared-channel": "0.0.64"
132
+ "peaks-loop-internal-runtime": "0.0.49",
133
+ "peaks-loop-mut": "0.1.63",
134
+ "peaks-loop-shared": "0.0.98",
135
+ "peaks-loop-shared-channel": "0.0.66"
136
136
  },
137
137
  "devDependencies": {
138
138
  "@changesets/cli": "2.31.1",
@@ -32,7 +32,7 @@
32
32
  },
33
33
  "passed": {
34
34
  "type": "boolean",
35
- "description": "True when reviewer found no blocking violations."
35
+ "description": "True only when a review RAN and found no blocking violations. False when it found violations, and also false on every skip path (no config, provider error, non-conforming JSON) — a review that never produced a verdict is never a pass."
36
36
  },
37
37
  "violations": {
38
38
  "type": "array",
@@ -72,11 +72,23 @@ If the distinctness check fails, the CI gate fails. See `references/reviewer-sch
72
72
  ## CLI surface
73
73
 
74
74
  ```
75
- peaks reviewer run --rid <rid> [--json]
75
+ peaks reviewer config --provider <name:model> --provider <name:model> [options]
76
+ peaks reviewer run --rid <rid> [--write] [--session-id <id>] [--json]
76
77
  peaks reviewer status [--json]
77
78
  ```
78
79
 
79
- `run` produces `rd/third-party-review.json` (and a human-readable `rd/third-party-review.md`) under `.peaks/_runtime/<sessionId>/`. `status` shows whether the reviewer is configured and which selection mode is active.
80
+ `config` writes the `reviewer` section to `~/.peaks/config.json` — the LLM
81
+ runs it on the user's behalf; nobody hand-authors JSON. It refuses a section
82
+ with fewer than two dispatchable providers (`ollama` / `anthropic` / `openai`).
83
+
84
+ `run --write` produces `rd/third-party-review-<rid>.json` (the validated envelope)
85
+ and the human-readable `rd/third-party-review-<rid>.md` under
86
+ `.peaks/_runtime/<sessionId>/rd/`. It writes **nothing** on a skip and
87
+ reports why: a skip is `passed: false` + `gateAction: 'warn'`, never a pass.
88
+
89
+ `status` reports one of three states — `no-section`, `insufficient-providers`
90
+ (naming the count and the >=2 requirement), or `configured` — and carries the
91
+ fix command in `nextActions`.
80
92
 
81
93
  ## Configuration (`~/.peaks/config.json`)
82
94
 
@@ -97,7 +109,11 @@ peaks reviewer status [--json]
97
109
  }
98
110
  ```
99
111
 
100
- Missing section: reviewer is skipped (transition still passes; envelope records `skipped: no-reviewer-config`). Per A4.1, the CLI flag `--reviewer-model` is REMOVED — users edit the config file.
112
+ Missing section: reviewer is skipped. The skip envelope records
113
+ `passed: false` + `gateAction: 'warn'` plus `skipped: no-reviewer-config` in
114
+ `reason` — it is never reported as a pass. Per A4.1, the CLI flag
115
+ `--reviewer-model` is REMOVED; configuration goes through
116
+ `peaks reviewer config`.
101
117
 
102
118
  ## Hard prohibitions
103
119
 
@@ -108,7 +124,7 @@ Missing section: reviewer is skipped (transition still passes; envelope records
108
124
 
109
125
  ## Sub-agent dispatch (when launched by peaks-code swarm)
110
126
 
111
- When this skill runs as a sub-agent dispatched by peaks-code, the sub-agent receives the parent session id and change-id via envelope. It MUST write its output to `.peaks/_runtime/<sessionId>/rd/third-party-review.json` + `.md` and return a compact JSON envelope.
127
+ When this skill runs as a sub-agent dispatched by peaks-code, the sub-agent receives the parent session id and change-id via envelope. It MUST write its output to `.peaks/_runtime/<sessionId>/rd/third-party-review-<rid>.json` + `.md` and return a compact JSON envelope.
112
128
 
113
129
  ## L2 surface reference (post rid-l2-extended)
114
130
 
@@ -10,9 +10,9 @@
10
10
  | `reviewerId` | string | yes | Stable id (`third-party-reviewer-v2.14.0`). |
11
11
  | `modelId` | string | yes | Concrete model id (overwritten server-side from the provider we called). |
12
12
  | `modelFamily`| string | yes | Family bucket (overwritten server-side via `deriveModelFamily(modelId)`). |
13
- | `passed` | bool | yes | True when no blocking violations. |
13
+ | `passed` | bool | yes | True only when a review RAN and found no blocking violations. False on every skip path. |
14
14
  | `violations` | array | yes | `[{kind, file, line, hint}]`. Empty when none. |
15
- | `gateAction` | enum | yes | `block` | `allow` | `warn`. |
15
+ | `gateAction` | enum | yes | `block` | `allow` | `warn`. A skip is `warn`, never `allow`. |
16
16
  | `reason` | string | yes | One-sentence rationale. |
17
17
 
18
18
  ## Violation kinds (closed enum)
@@ -28,22 +28,27 @@
28
28
 
29
29
  ## Distinctness gate (AC-4.4)
30
30
 
31
- `third-party-review.json.modelFamily` MUST differ from `karpathy-review.json.modelFamily`. Equality fails the build. The reviewer service stamps `modelFamily` from the actual `modelId` (the LLM cannot self-report a different family).
31
+ `third-party-review-<rid>.json.modelFamily` MUST differ from `karpathy-review.json.modelFamily`. Equality fails the build. The reviewer service stamps `modelFamily` from the actual `modelId` (the LLM cannot self-report a different family).
32
32
 
33
33
  ## Skipped envelope
34
34
 
35
- When `~/.peaks/config.json` lacks the `reviewer` section, the reviewer returns:
35
+ When `~/.peaks/config.json` lacks the `reviewer` section (or has fewer than
36
+ two usable providers), the reviewer returns:
36
37
 
37
38
  ```json
38
39
  {
39
40
  "reviewerId": "third-party-reviewer-v2.14.0",
40
41
  "modelId": "skipped",
41
42
  "modelFamily": "skipped",
42
- "passed": true,
43
+ "passed": false,
43
44
  "violations": [],
44
- "gateAction": "allow",
45
+ "gateAction": "warn",
45
46
  "reason": "skipped: no-reviewer-config (fallbackOnError=skip)"
46
47
  }
47
48
  ```
48
49
 
49
- The transition still passes; the THIRD_PARTY_REVIEW prereq records the skip in `prerequisites.warnings`.
50
+ A skip is not a pass: `passed` is `false` and `gateAction` is `warn`, so no
51
+ consumer reading those two fields sees green. `peaks reviewer run --write`
52
+ refuses to write `rd/third-party-review-<rid>.md` / `.json` from a skipped
53
+ envelope — the artifact exists only when a review actually ran. The
54
+ THIRD_PARTY_REVIEW prereq records the skip in `prerequisites.warnings`.
@@ -155,6 +155,26 @@ hash in the artifact, and `rd:qa-handoff` re-hashes them, so a declared path edi
155
155
  refuses that transition. **Declare what you judged, not what you touched** — the check can tell
156
156
  that a declared path moved, and it cannot tell that an undeclared one did.
157
157
 
158
+ #### Where the audit loop terminates (BLOCKING discipline)
159
+
160
+ The content-hash binding is intentional: **any** later edit to a judged path — including a
161
+ comment-only edit — invalidates the audit, and the transition refuses until the audit is re-run.
162
+ That is the correct behaviour, and it is also an unbounded loop if the audit's own findings are
163
+ fixed after it runs: fixing a finding edits a judged path, which invalidates the audit, whose
164
+ re-run can surface the next finding. Nothing in the CLI can bound this; the skill must:
165
+
166
+ 1. **Freeze `src/` before the audit.** The audit is the **last** producer step, not a mid-slice
167
+ reviewer. Do not run it, then edit code, then run it again by default.
168
+ 2. **A re-run is required, never optional.** After a post-audit edit, the artifact is stale — the
169
+ transition will refuse, and no hand-editing of `## Judged content` is a substitute (the
170
+ declaration is written by `run`, and hand-authoring it fails §11.1).
171
+ 3. **Record the remaining findings as accepted residuals.** A finding that survives the frozen
172
+ diff is a decision, not a blocker: put it in the backlog / handoff residuals with the reason it
173
+ was accepted. Do not spend a second audit on comment text.
174
+ 4. **If a finding must be fixed, fix everything the re-run will judge in one pass,** then run the
175
+ audit exactly once more. Two audits are the normal ceiling for a slice; a third means the
176
+ freeze step was skipped.
177
+
158
178
  The artifact body has the required sections per `.peaks/project-scan/audit-output-schema.md`:
159
179
 
160
180
  - `## Summary` — 1-paragraph narrative
@@ -16,7 +16,8 @@ The CLI does NOT judge whether the request is Job-shaped — that is the LLM's j
16
16
  ### Action sequence
17
17
 
18
18
  1. LLM reads the user prompt and applies judgement → `isJob: boolean + rationale + suggestedJobId + suggestedStrategy + confidence`.
19
- 2. LLM calls `peaks code detect-job --is-job <bool> --rationale <text> --suggested-job-id <jid> --suggested-strategy <single|rotating> --confidence <high|medium|low> [--force]`.
19
+ 2. LLM calls `peaks code detect-job --is-job <bool> --rationale <text> [--suggested-job-id <jid>] --suggested-strategy <single|rotating> --confidence <high|medium|low> [--force]`.
20
+ `--suggested-job-id` is required when `--is-job true` and optional when `--is-job false`, where it defaults to `single-task`.
20
21
  3. CLI records to `.peaks/_runtime/<sessionId>/job-shape.json`.
21
22
  4. If `isJob: true` → `peaks job init --job-id <jid> --slice-list <...> --main-loop-strategy <strategy> --rotate-every 3` (BEFORE Step 1).
22
23
  5. Downstream steps (Step 1, Step 0.81, etc.) call `read-job-shape` to refuse if missing.