peaks-loop 4.1.6 → 4.1.7
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.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +31 -0
- package/dist/cli/commands/core/skill-registry-commands.js +9 -4
- package/dist/services/artifacts/artifact-prerequisites.d.ts +1 -0
- package/dist/services/artifacts/artifact-prerequisites.js +9 -97
- package/dist/services/artifacts/backcompat-acceptance.d.ts +66 -0
- package/dist/services/artifacts/backcompat-acceptance.js +220 -0
- package/dist/services/artifacts/prerequisite-checks.d.ts +8 -0
- package/dist/services/artifacts/prerequisite-checks.js +7 -2
- package/dist/services/artifacts/prerequisite-path-resolver.d.ts +39 -0
- package/dist/services/artifacts/prerequisite-path-resolver.js +110 -0
- package/dist/services/doctor/doctor-service/checks/backcompat-acceptance.d.ts +15 -0
- package/dist/services/doctor/doctor-service/checks/backcompat-acceptance.js +53 -0
- package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +38 -0
- package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +243 -0
- package/dist/services/doctor/doctor-service/plugin-registry.js +4 -0
- package/dist/services/doctor/doctor-service/types.d.ts +12 -0
- package/dist/services/workflow/pipeline-verify-gate-support.d.ts +4 -1
- package/dist/services/workflow/pipeline-verify-gate-support.js +8 -79
- package/dist/services/workflow/pipeline-verify-rd-phase.d.ts +67 -0
- package/dist/services/workflow/pipeline-verify-rd-phase.js +122 -0
- package/dist/services/workflow/pipeline-verify-service.js +16 -17
- package/dist/services/workspace/workspace-service.js +4 -16
- package/package.json +5 -5
- package/schemas/doctor-report.schema.json +2 -2
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"metadata": {
|
|
3
3
|
"pluginRoot": ".",
|
|
4
|
-
"version": "4.1.
|
|
4
|
+
"version": "4.1.7"
|
|
5
5
|
},
|
|
6
6
|
"plugins": [
|
|
7
7
|
{
|
|
8
8
|
"name": "peaks-loop",
|
|
9
9
|
"description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
|
|
10
|
-
"version": "4.1.
|
|
10
|
+
"version": "4.1.7",
|
|
11
11
|
"author": {
|
|
12
12
|
"name": "SquabbyZ"
|
|
13
13
|
},
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,36 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 4.1.7 — 2026-10-18(提交腿硬门、契约表派生、过期债棘轮,以及 canonical store 与 IDE skill 树的漂移检查)
|
|
4
|
+
|
|
5
|
+
**版本级别**: 未发布区间 `v4.1.6..HEAD` 共 **5 个 commit**(**1 feat / 2 refactor / 1 chore / 1 docs**)。取 **patch**,依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。
|
|
6
|
+
|
|
7
|
+
### 1. `backCompatUntil` 在提交腿真正关闭(`0cfc25c0`)
|
|
8
|
+
|
|
9
|
+
`prerequisite-checks.ts` 早就算出 `expiredWindow` 并把它写进软 warning,但没有任何边界把它变成失败;到 4.1.6 为止,`mut/mut-report.json` 与 `rd/third-party-review.md` 已在声明窗口之后约二十个 minor 仍然软通过。现在 `peaks workflow verify-pipeline` 在"过期 + 缺 artifact + 无当前接受"时返回 `complete:false`;`peaks request transition` 仍保持软 warning。接受清单在 `.peaks/lint/backcompat-expired-acceptance.json`,每条带 reason 与 `reviewBy`(上限 installed + 2 minor);`initWorkspace` 幂等播种,`reviewBy` 在播种时推导;缺失清单 fail-closed,doctor 以 `error` 报告。路径解析抽到 leaf 模块,transition 与 commit gate 共用。
|
|
10
|
+
|
|
11
|
+
### 2. `rdGatesForType` 从契约表派生(`98f5ed60`)
|
|
12
|
+
|
|
13
|
+
三个手写的请求类型列表(`bugfix`、`!docs/chore/config`、`feature|refactor|bugfix|config`)被一张 `RD_EVIDENCE_GATES` 表和 `contractEvidencePaths` 取代;重复的 `RD_EVIDENCE_PROBE` 映射删除,`pipeline-verify-gate-support.ts` 净减 75 行。六种类型的 gate 列表逐项不变,由表驱动测试钉住;一个 lookup seam 与两个 binding 用例证明生产函数确实走契约,而不是另一份列表。
|
|
14
|
+
|
|
15
|
+
### 3. 过期 grace 标记的只减不增棘轮(`f02c6be6`)
|
|
16
|
+
|
|
17
|
+
129 个 `grace: 1 minor release (v2.14.0)` 标记分布在 83 个已跟踪的 `src/**` 文件里,宽限期早已过去而没有机制执行。新增 `expired-grace-ratchet.test.ts` + `_expired-grace-scan.ts`,以 `git ls-files` 为人口、以 `.peaks/lint/expired-grace-baseline.json` 为基线:新未登记标记、计数变化或陈旧条目都会变红。控制臂与两次真实控制(删一条基线、加一条假条目)都按预期失败。**129 个 catch 没有逐个改写**——棘轮记录债务并禁止增长。
|
|
18
|
+
|
|
19
|
+
### 4. canonical store 与 IDE skill 树的漂移检查(`f1525621`)
|
|
20
|
+
|
|
21
|
+
新增只读 doctor 检查 `skills:reference-parity`:比较 `$PEAKS_HOME`(或 `~/.peaks`)下的 canonical skill store 与每个已存在的 IDE skill 根,点名"一侧有、另一侧没有"的文件,并提示 **"Ask the LLM to run `peaks skill sync`"**。junction 比较相等;realpath visited set 防 symlink 环;store 不可读时报告 warning。schema 增加加法式 `skills:<topic>:<ide>:<skill>` id 形状。顺带修复 `peaks skill doctor` 忽略 `severity` 的问题:warning 现在只展示,不再把 exit code 置 1。
|
|
22
|
+
|
|
23
|
+
### 5. backlog 重测(`2e6fd7e9`)
|
|
24
|
+
|
|
25
|
+
§14.5 的 `--rid` 穿越在 HEAD 上已由 request-id 校验拒绝,重测记录在案;§14.8 关闭;新增 §16 记录本轮两个切片与两个 `backCompatUntil` 软门。
|
|
26
|
+
|
|
27
|
+
### 用户可见行为
|
|
28
|
+
|
|
29
|
+
- `peaks workflow verify-pipeline` 新增一个提交腿硬失败;`peaks request transition` 保持软。
|
|
30
|
+
- `peaks doctor` 新增 `skills:reference-parity` 检查。
|
|
31
|
+
- `peaks skill doctor` 的 warning 不再导致 exit 1。
|
|
32
|
+
- 无破坏性变更;4.1.6 的行为除上述三点外保持不变。
|
|
33
|
+
|
|
3
34
|
## 4.1.6 — 2026-10-18(三类闸规则收紧:配置路径的 reader、skip 允许列表、声明类型;两个 refactor 切片被自己新增的规则抓住)
|
|
4
35
|
|
|
5
36
|
**版本级别**: 未发布区间 `v4.1.5..HEAD` 共 **38 个 commit**(**2 feat / 11 fix / 3 refactor / 7 chore / 8 docs / 4 test+style**)。取 **patch**,依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。**本版含两处用户可见的行为收紧**,按 4.1.5 的先例明写:声明为 `docs`/`chore`/`config` 的请求不能再携带产品源码;`config` 不再能通过 skip 记录跳过它的 QA 阶段。
|
|
@@ -50,16 +50,21 @@ function runSkillList(options, io) {
|
|
|
50
50
|
function runSkillDoctor(options, io) {
|
|
51
51
|
return runDoctor().then((report) => {
|
|
52
52
|
const skillChecks = report.checks.filter((check) => check.id.startsWith('skill'));
|
|
53
|
-
|
|
53
|
+
// A `severity: 'warning'` finding is displayed but does not fail the
|
|
54
|
+
// command: the severity contract in `doctor-service/types.ts` says a
|
|
55
|
+
// warning must not escalate an exit code (the parity check is one).
|
|
56
|
+
const failed = skillChecks.filter((check) => !check.ok && check.severity !== 'warning').length;
|
|
57
|
+
const warned = skillChecks.filter((check) => !check.ok && check.severity === 'warning').length;
|
|
54
58
|
if (options.json === true) {
|
|
55
|
-
printResult(io, ok('skill.doctor', { checks: skillChecks, ok: failed === 0 }), true);
|
|
59
|
+
printResult(io, ok('skill.doctor', { checks: skillChecks, ok: failed === 0, warnings: warned }), true);
|
|
56
60
|
}
|
|
57
61
|
else {
|
|
58
62
|
for (const check of skillChecks) {
|
|
59
|
-
const icon = check.ok ? '+' : '×';
|
|
63
|
+
const icon = check.ok ? '+' : check.severity === 'warning' ? '!' : '×';
|
|
60
64
|
io.stdout(` ${icon} ${check.message}`);
|
|
61
65
|
}
|
|
62
|
-
|
|
66
|
+
const warningSuffix = warned > 0 ? `, ${warned} warning(s)` : '';
|
|
67
|
+
io.stdout(`\n ${skillChecks.length - failed - warned} passed, ${failed} failed${warningSuffix}`);
|
|
63
68
|
if (failed > 0) {
|
|
64
69
|
io.stderr('\nOne or more skill checks failed.');
|
|
65
70
|
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { RequestArtifactRole, RequestArtifactState } from './request-artifact-service.js';
|
|
2
|
+
export { checkExpiredBackCompatCommitGate, type ExpiredBackCompatCommitGateOptions } from './backcompat-acceptance.js';
|
|
2
3
|
export type RequestType = 'feature' | 'bugfix' | 'refactor' | 'docs' | 'config' | 'chore';
|
|
3
4
|
export declare const VALID_REQUEST_TYPES: ReadonlyArray<RequestType>;
|
|
4
5
|
export declare const DEFAULT_REQUEST_TYPE: RequestType;
|
|
@@ -1,10 +1,11 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { readFile, readdir } from 'node:fs/promises';
|
|
3
|
-
import { pathExists } from 'peaks-loop-shared/fs';
|
|
4
|
-
import { NUMBERED_PREFIX_RE, slugifyDescription } from '../../shared/incrementing-number.js';
|
|
1
|
+
import { readFile } from 'node:fs/promises';
|
|
5
2
|
import { emitPrereqTransitionEvent } from './prerequisite-transition-event.js';
|
|
6
3
|
import { isUnsafePathInput } from '../../shared/path-safety.js';
|
|
7
4
|
import { bodyViolationsIfDeclared, missingPrerequisiteWarning } from './prerequisite-checks.js';
|
|
5
|
+
import { resolvePrerequisiteAbsolutePathWithFallback, resolvePrerequisitePath, sessionRootsFor } from './prerequisite-path-resolver.js';
|
|
6
|
+
// The commit-leg expiry gate lives in its own module because this file is over
|
|
7
|
+
// the file-size cap; re-exported here so every caller keeps one import site.
|
|
8
|
+
export { checkExpiredBackCompatCommitGate } from './backcompat-acceptance.js';
|
|
8
9
|
export const VALID_REQUEST_TYPES = [
|
|
9
10
|
'feature',
|
|
10
11
|
'bugfix',
|
|
@@ -338,42 +339,6 @@ export function getPrerequisitesFor(role, newState, requestType) {
|
|
|
338
339
|
const table = PREREQUISITES_BY_TYPE[requestType];
|
|
339
340
|
return table[`${role}:${newState}`] ?? [];
|
|
340
341
|
}
|
|
341
|
-
function resolvePrerequisitePath(prerequisite, requestId) {
|
|
342
|
-
return prerequisite.relativePath.replace('<rid>', requestId);
|
|
343
|
-
}
|
|
344
|
-
/**
|
|
345
|
-
* Resolve a prerequisite to an on-disk path, tolerating the numbered filename
|
|
346
|
-
* prefix that `request init` writes (e.g. `001-<rid>.md`). When the prerequisite
|
|
347
|
-
* path contains `<rid>`, we accept either the legacy bare `<rid>.md` form or any
|
|
348
|
-
* `NNN-<rid>.md` numbered form — mirroring the matcher in request-artifact-service.
|
|
349
|
-
* Returns the matched absolute path, or null when nothing matches.
|
|
350
|
-
*/
|
|
351
|
-
async function resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, requestId) {
|
|
352
|
-
const relative = resolvePrerequisitePath(prerequisite, requestId);
|
|
353
|
-
const exact = join(sessionRoot, relative);
|
|
354
|
-
if (await pathExists(exact)) {
|
|
355
|
-
return exact;
|
|
356
|
-
}
|
|
357
|
-
// Only `<rid>`-templated prerequisites can carry a numbered prefix; fixed paths
|
|
358
|
-
// (e.g. rd/tech-doc.md) are matched exactly above.
|
|
359
|
-
if (!prerequisite.relativePath.includes('<rid>')) {
|
|
360
|
-
return null;
|
|
361
|
-
}
|
|
362
|
-
const dir = dirname(exact);
|
|
363
|
-
// The on-disk suffix is the SLUG of this basename — the writer lowercases the
|
|
364
|
-
// rid — so a mixed-case rid used to be reported absent with the file on disk.
|
|
365
|
-
const suffix = `-${slugifyDescription(basename(exact).replace(/\.md$/, ''))}.md`;
|
|
366
|
-
let entries;
|
|
367
|
-
try {
|
|
368
|
-
entries = await readdir(dir);
|
|
369
|
-
}
|
|
370
|
-
catch {
|
|
371
|
-
// TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
|
|
372
|
-
return null;
|
|
373
|
-
}
|
|
374
|
-
const match = entries.find((name) => NUMBERED_PREFIX_RE.test(name) && name.endsWith(suffix));
|
|
375
|
-
return match ? join(dir, match) : null;
|
|
376
|
-
}
|
|
377
342
|
export async function checkPrerequisites(options) {
|
|
378
343
|
const requirements = getPrerequisitesFor(options.role, options.newState, options.requestType);
|
|
379
344
|
if (requirements.length === 0) {
|
|
@@ -396,15 +361,14 @@ export async function checkPrerequisites(options) {
|
|
|
396
361
|
// back-compat).
|
|
397
362
|
// The sessionId is preserved in the artifact body's frontmatter for
|
|
398
363
|
// human navigation; it is no longer a filesystem path key.
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
const legacySessionRoot = options.sessionId !== undefined ? join(options.projectRoot, '.peaks', options.sessionId) : null;
|
|
364
|
+
// The two tiers are built by the resolver module, so the commit gate and this
|
|
365
|
+
// transition probe the same directories.
|
|
366
|
+
const roots = sessionRootsFor(options.projectRoot, options.sessionId);
|
|
403
367
|
const missing = [];
|
|
404
368
|
const warnings = [];
|
|
405
369
|
for (const prerequisite of requirements) {
|
|
406
370
|
const relative = resolvePrerequisitePath(prerequisite, options.requestId);
|
|
407
|
-
const absolute = await resolvePrerequisiteAbsolutePathWithFallback(
|
|
371
|
+
const absolute = await resolvePrerequisiteAbsolutePathWithFallback(roots.canonical, roots.legacy, prerequisite, options.requestId);
|
|
408
372
|
if (absolute === null) {
|
|
409
373
|
// A `backCompat` prerequisite downgrades a missing file to a warning, NOT
|
|
410
374
|
// a hard failure; v2.14.0/v2.15.0 re-elevate it. The decision and the
|
|
@@ -481,55 +445,3 @@ export async function checkPrerequisites(options) {
|
|
|
481
445
|
});
|
|
482
446
|
return result;
|
|
483
447
|
}
|
|
484
|
-
/**
|
|
485
|
-
* Resolve a prerequisite to an on-disk path, with a 2-tier fallback
|
|
486
|
-
* dirs are no longer created):
|
|
487
|
-
* 1. `<canonicalSessionRoot>/<relative>` (post-F3 canonical session
|
|
488
|
-
* home, when `canonicalSessionRoot` is provided).
|
|
489
|
-
* 2. `<legacySessionRoot>/<relative>` (pre-F3 legacy session home,
|
|
490
|
-
* when `legacySessionRoot` is provided).
|
|
491
|
-
* Tolerates the numbered filename prefix that `request init` writes
|
|
492
|
-
* (e.g. `001-<rid>.md`) at every tier. Returns the matched absolute
|
|
493
|
-
* path, or null when nothing matches.
|
|
494
|
-
*
|
|
495
|
-
* Back-compat: once neither primary session-root tier resolved, the
|
|
496
|
-
* resolver walks `prerequisite.legacyRelativePaths` in declared order
|
|
497
|
-
* and tries each at BOTH session roots before declaring the prereq
|
|
498
|
-
* missing. This covers both artifacts that moved location
|
|
499
|
-
* (`rd/security-review.md` → `audit/security.md`) and ones that later
|
|
500
|
-
* gained a rid in the filename (`audit/security.md` →
|
|
501
|
-
*/
|
|
502
|
-
async function resolvePrerequisiteAbsolutePathWithFallback(canonicalSessionRoot, legacySessionRoot, prerequisite, requestId) {
|
|
503
|
-
const roots = [canonicalSessionRoot, legacySessionRoot];
|
|
504
|
-
// First pass: try the primary relativePath at every root.
|
|
505
|
-
for (const root of roots) {
|
|
506
|
-
if (root === null)
|
|
507
|
-
continue;
|
|
508
|
-
const found = await resolvePrerequisiteAbsolutePath(root, prerequisite, requestId);
|
|
509
|
-
if (found !== null)
|
|
510
|
-
return found;
|
|
511
|
-
}
|
|
512
|
-
// Second pass: the single previous location, then any further older
|
|
513
|
-
// ones, at every root — newest first, so a session that somehow holds
|
|
514
|
-
// both a pre-rid and a v2.11.x file resolves to the newer shape.
|
|
515
|
-
// Only the relativePath is swapped — the same numbered-prefix
|
|
516
|
-
// tolerance applies via the shared resolver.
|
|
517
|
-
const legacyTiers = [
|
|
518
|
-
...(prerequisite.legacyRelativePath !== undefined ? [prerequisite.legacyRelativePath] : []),
|
|
519
|
-
...(prerequisite.legacyRelativePaths ?? [])
|
|
520
|
-
];
|
|
521
|
-
for (const legacy of legacyTiers) {
|
|
522
|
-
const legacyPrereq = {
|
|
523
|
-
...prerequisite,
|
|
524
|
-
relativePath: legacy
|
|
525
|
-
};
|
|
526
|
-
for (const root of roots) {
|
|
527
|
-
if (root === null)
|
|
528
|
-
continue;
|
|
529
|
-
const found = await resolvePrerequisiteAbsolutePath(root, legacyPrereq, requestId);
|
|
530
|
-
if (found !== null)
|
|
531
|
-
return found;
|
|
532
|
-
}
|
|
533
|
-
}
|
|
534
|
-
return null;
|
|
535
|
-
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The commit-leg gate for back-compat windows that have CLOSED.
|
|
3
|
+
*
|
|
4
|
+
* `peaks request transition` stays soft on purpose: `missingPrerequisiteWarning`
|
|
5
|
+
* reports a closed window as a warning so the workflow can still reach
|
|
6
|
+
* `qa-handoff` and record the skip. This module is the other boundary. It
|
|
7
|
+
* refuses a closed, missing window unless the tracked acceptance list carries a
|
|
8
|
+
* current entry for that exact `path` + `until` pair.
|
|
9
|
+
*
|
|
10
|
+
* A MISSING LIST IS A FAILURE, NOT AN OPT-OUT. The commit leg is the hard
|
|
11
|
+
* boundary the product asked for, so absence is reported like any other
|
|
12
|
+
* malformed list. The remediation names the seeding path — `peaks workspace
|
|
13
|
+
* init` writes the tracked list — and the LLM performs it; the user speaks or
|
|
14
|
+
* picks, and never hand-authors JSON.
|
|
15
|
+
*
|
|
16
|
+
* WHO EDITS THE LIST. The LLM does, on the user's behalf: the user speaks or
|
|
17
|
+
* picks, and the tracked JSON is a reviewed diff the LLM authors. No message
|
|
18
|
+
* here asks a human to hand-author JSON.
|
|
19
|
+
*
|
|
20
|
+
* WHY THE GATE LIVES HERE AND NOT IN `artifact-prerequisites.ts`. That file is
|
|
21
|
+
* over the file-size cap and a change may only shrink it, so this is the same
|
|
22
|
+
* split its `prerequisite-checks.ts` sibling took. The public name is still
|
|
23
|
+
* exported from `artifact-prerequisites.ts`; that module re-exports it, so
|
|
24
|
+
* every caller keeps one import site.
|
|
25
|
+
*
|
|
26
|
+
* ONE RESOLVER, ONE COMPARATOR. Path resolution and the session-root tiers are
|
|
27
|
+
* the ones the transition uses, and window comparison is
|
|
28
|
+
* `compareReleaseVersions`, so the two legs cannot disagree about whether an
|
|
29
|
+
* artifact exists or where a boundary sits.
|
|
30
|
+
*/
|
|
31
|
+
import type { RequestType } from './artifact-prerequisites.js';
|
|
32
|
+
/** The seeded list a new project receives, and the reason each window is
|
|
33
|
+
* accepted. `reviewBy` is DERIVED at seed time from the installed release, so a
|
|
34
|
+
* project initialized on a release boundary receives a current list rather
|
|
35
|
+
* than an already-expired one; it is bounded by the same two-minor cap the gate
|
|
36
|
+
* enforces. */
|
|
37
|
+
export declare function backcompatAcceptanceSeed(installedVersion?: string): string;
|
|
38
|
+
/**
|
|
39
|
+
* Seed the tracked acceptance list for a project that has none. Idempotent: an
|
|
40
|
+
* existing file is never overwritten, so a project's reviewed entries survive
|
|
41
|
+
* every `peaks workspace init`. Called by `initWorkspace`.
|
|
42
|
+
*/
|
|
43
|
+
export declare function seedBackCompatAcceptance(projectRoot: string): void;
|
|
44
|
+
export type ExpiredBackCompatCommitGateOptions = {
|
|
45
|
+
projectRoot: string;
|
|
46
|
+
/** The evidence scope. Without one no artifact resolves, so every closed
|
|
47
|
+
* window is judged missing — the fail-closed answer. */
|
|
48
|
+
sessionId?: string | undefined;
|
|
49
|
+
requestType: RequestType;
|
|
50
|
+
requestId: string;
|
|
51
|
+
/** Injected so a caller can drive both sides of a window boundary; defaults
|
|
52
|
+
* to the release this build ships. */
|
|
53
|
+
installedVersion?: string | undefined;
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* The COMMIT-LEG verdict on back-compat windows that have closed.
|
|
57
|
+
*
|
|
58
|
+
* The table is read through the same accessor the transition uses, and the
|
|
59
|
+
* import is dynamic because `artifact-prerequisites.ts` re-exports this module:
|
|
60
|
+
* a static edge back would close a runtime import cycle. Same idiom, same
|
|
61
|
+
* reason, as the lazy producer imports in `request-commands.ts`.
|
|
62
|
+
*/
|
|
63
|
+
export declare function checkExpiredBackCompatCommitGate(options: ExpiredBackCompatCommitGateOptions): Promise<{
|
|
64
|
+
violations: string[];
|
|
65
|
+
warnings: string[];
|
|
66
|
+
}>;
|
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The commit-leg gate for back-compat windows that have CLOSED.
|
|
3
|
+
*
|
|
4
|
+
* `peaks request transition` stays soft on purpose: `missingPrerequisiteWarning`
|
|
5
|
+
* reports a closed window as a warning so the workflow can still reach
|
|
6
|
+
* `qa-handoff` and record the skip. This module is the other boundary. It
|
|
7
|
+
* refuses a closed, missing window unless the tracked acceptance list carries a
|
|
8
|
+
* current entry for that exact `path` + `until` pair.
|
|
9
|
+
*
|
|
10
|
+
* A MISSING LIST IS A FAILURE, NOT AN OPT-OUT. The commit leg is the hard
|
|
11
|
+
* boundary the product asked for, so absence is reported like any other
|
|
12
|
+
* malformed list. The remediation names the seeding path — `peaks workspace
|
|
13
|
+
* init` writes the tracked list — and the LLM performs it; the user speaks or
|
|
14
|
+
* picks, and never hand-authors JSON.
|
|
15
|
+
*
|
|
16
|
+
* WHO EDITS THE LIST. The LLM does, on the user's behalf: the user speaks or
|
|
17
|
+
* picks, and the tracked JSON is a reviewed diff the LLM authors. No message
|
|
18
|
+
* here asks a human to hand-author JSON.
|
|
19
|
+
*
|
|
20
|
+
* WHY THE GATE LIVES HERE AND NOT IN `artifact-prerequisites.ts`. That file is
|
|
21
|
+
* over the file-size cap and a change may only shrink it, so this is the same
|
|
22
|
+
* split its `prerequisite-checks.ts` sibling took. The public name is still
|
|
23
|
+
* exported from `artifact-prerequisites.ts`; that module re-exports it, so
|
|
24
|
+
* every caller keeps one import site.
|
|
25
|
+
*
|
|
26
|
+
* ONE RESOLVER, ONE COMPARATOR. Path resolution and the session-root tiers are
|
|
27
|
+
* the ones the transition uses, and window comparison is
|
|
28
|
+
* `compareReleaseVersions`, so the two legs cannot disagree about whether an
|
|
29
|
+
* artifact exists or where a boundary sits.
|
|
30
|
+
*/
|
|
31
|
+
import { dirname, join } from 'node:path';
|
|
32
|
+
import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
|
|
33
|
+
import { readFile } from 'node:fs/promises';
|
|
34
|
+
import { pathExists } from 'peaks-loop-shared/fs';
|
|
35
|
+
import { CLI_VERSION } from 'peaks-loop-shared/version';
|
|
36
|
+
import { isUnsafePathInput } from '../../shared/path-safety.js';
|
|
37
|
+
import { compareReleaseVersions, missingPrerequisiteWarning } from './prerequisite-checks.js';
|
|
38
|
+
import { resolvePrerequisiteAbsolutePathWithFallback, resolvePrerequisitePath, sessionRootsFor } from './prerequisite-path-resolver.js';
|
|
39
|
+
/** The one tracked acceptance list. Adding an entry is a reviewed diff the LLM
|
|
40
|
+
* authors on the user's behalf; no source file keeps a second copy. */
|
|
41
|
+
const BACKCOMPAT_ACCEPTANCE_PATH = '.peaks/lint/backcompat-expired-acceptance.json';
|
|
42
|
+
/** Every field an entry must carry, non-empty. `reviewBy` is the one that makes
|
|
43
|
+
* the list expire, so an entry without it is malformed rather than permissive. */
|
|
44
|
+
const REQUIRED_ACCEPTANCE_FIELDS = ['path', 'until', 'reason', 'reviewBy'];
|
|
45
|
+
/** How many minor releases ahead of the installed build a `reviewBy` may sit.
|
|
46
|
+
* A list entry that jumps years ahead accepts without a near-term review, which
|
|
47
|
+
* is the same "forever" defect in a new field. */
|
|
48
|
+
const REVIEW_CAP_MINORS = 2;
|
|
49
|
+
/** The seeded list a new project receives, and the reason each window is
|
|
50
|
+
* accepted. `reviewBy` is DERIVED at seed time from the installed release, so a
|
|
51
|
+
* project initialized on a release boundary receives a current list rather
|
|
52
|
+
* than an already-expired one; it is bounded by the same two-minor cap the gate
|
|
53
|
+
* enforces. */
|
|
54
|
+
export function backcompatAcceptanceSeed(installedVersion = CLI_VERSION) {
|
|
55
|
+
const reviewBy = reviewCapFor(installedVersion);
|
|
56
|
+
return JSON.stringify({
|
|
57
|
+
version: 1,
|
|
58
|
+
note: "Expired backCompat windows accepted for the commit leg. The LLM edits this file on the user's behalf (the user only speaks or picks); adding an entry is a reviewed diff and reviewBy is enforced against a two-minor cap.",
|
|
59
|
+
accepted: [
|
|
60
|
+
{
|
|
61
|
+
path: 'mut/mut-report.json',
|
|
62
|
+
until: 'v2.14.0',
|
|
63
|
+
reason: 'No producer in this build: peaks mut * requires --input-sig (TACT.sig), and peaks tact read is not a registered command (backlog §9.2).',
|
|
64
|
+
reviewBy
|
|
65
|
+
},
|
|
66
|
+
{
|
|
67
|
+
path: 'rd/third-party-review.md',
|
|
68
|
+
until: 'v2.15.0',
|
|
69
|
+
reason: 'No reviewer configured: peaks reviewer status reports no-reviewer-config, and the prerequisite table soft-skips this artifact in that state. Documented deviation: this commit-leg gate does not re-evaluate the reviewer.providers conditional, so the window is accepted here regardless of that config.',
|
|
70
|
+
reviewBy
|
|
71
|
+
}
|
|
72
|
+
]
|
|
73
|
+
}, null, 2);
|
|
74
|
+
}
|
|
75
|
+
function isBackCompatAcceptance(value) {
|
|
76
|
+
if (value === null || typeof value !== 'object' || Array.isArray(value))
|
|
77
|
+
return false;
|
|
78
|
+
const entry = value;
|
|
79
|
+
return REQUIRED_ACCEPTANCE_FIELDS.every((field) => typeof entry[field] === 'string' && entry[field] !== '');
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* The tracked acceptances, or why they cannot be read.
|
|
83
|
+
*
|
|
84
|
+
* ABSENT is a problem, not an opt-out: the commit leg is the hard boundary, so
|
|
85
|
+
* a project that lacks the list is told to seed it. The remediation names the
|
|
86
|
+
* LLM as the actor — `peaks workspace init` seeds the file, and the user never
|
|
87
|
+
* hand-authors JSON.
|
|
88
|
+
*/
|
|
89
|
+
async function loadBackCompatAcceptances(projectRoot) {
|
|
90
|
+
const absolute = join(projectRoot, '.peaks', 'lint', 'backcompat-expired-acceptance.json');
|
|
91
|
+
if (!(await pathExists(absolute))) {
|
|
92
|
+
return {
|
|
93
|
+
accepted: [],
|
|
94
|
+
problem: `${BACKCOMPAT_ACCEPTANCE_PATH} is absent. Ask the LLM to run \`peaks workspace init\` to seed the tracked list (the LLM edits it on the user's behalf), or to produce the missing artifacts`
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
const unreadable = (why) => ({
|
|
98
|
+
accepted: [],
|
|
99
|
+
problem: `${BACKCOMPAT_ACCEPTANCE_PATH} ${why}, so expired back-compat windows cannot be judged`
|
|
100
|
+
});
|
|
101
|
+
let raw;
|
|
102
|
+
try {
|
|
103
|
+
raw = await readFile(absolute, 'utf8');
|
|
104
|
+
}
|
|
105
|
+
catch {
|
|
106
|
+
return unreadable('cannot be read');
|
|
107
|
+
}
|
|
108
|
+
let parsed;
|
|
109
|
+
try {
|
|
110
|
+
parsed = JSON.parse(raw);
|
|
111
|
+
}
|
|
112
|
+
catch {
|
|
113
|
+
return unreadable('is not valid JSON');
|
|
114
|
+
}
|
|
115
|
+
if (parsed === null || typeof parsed !== 'object') {
|
|
116
|
+
return unreadable('is not a JSON object');
|
|
117
|
+
}
|
|
118
|
+
const accepted = parsed.accepted;
|
|
119
|
+
if (!Array.isArray(accepted) || !accepted.every(isBackCompatAcceptance)) {
|
|
120
|
+
return unreadable('does not carry an "accepted" array of path/until/reason/reviewBy entries');
|
|
121
|
+
}
|
|
122
|
+
return { accepted, problem: null };
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Seed the tracked acceptance list for a project that has none. Idempotent: an
|
|
126
|
+
* existing file is never overwritten, so a project's reviewed entries survive
|
|
127
|
+
* every `peaks workspace init`. Called by `initWorkspace`.
|
|
128
|
+
*/
|
|
129
|
+
export function seedBackCompatAcceptance(projectRoot) {
|
|
130
|
+
const absolute = join(projectRoot, '.peaks', 'lint', 'backcompat-expired-acceptance.json');
|
|
131
|
+
if (existsSync(absolute))
|
|
132
|
+
return;
|
|
133
|
+
mkdirSync(dirname(absolute), { recursive: true });
|
|
134
|
+
writeFileSync(absolute, `${backcompatAcceptanceSeed()}\n`, 'utf8');
|
|
135
|
+
}
|
|
136
|
+
/** Every `backCompat` requirement whose window has closed while its artifact is
|
|
137
|
+
* absent. A present artifact is excluded: its body checks belong to the
|
|
138
|
+
* transition, and an artifact that exists needs no acceptance. */
|
|
139
|
+
async function closedBackCompatWindows(requirements, installedVersion, requestId, roots) {
|
|
140
|
+
const closed = [];
|
|
141
|
+
for (const prerequisite of requirements) {
|
|
142
|
+
const until = prerequisite.backCompatUntil;
|
|
143
|
+
const relative = resolvePrerequisitePath(prerequisite, requestId);
|
|
144
|
+
const softWarning = missingPrerequisiteWarning(prerequisite, relative, installedVersion);
|
|
145
|
+
if (until === undefined || softWarning?.expiredWindow === undefined)
|
|
146
|
+
continue;
|
|
147
|
+
const absolute = await resolvePrerequisiteAbsolutePathWithFallback(roots.canonical, roots.legacy, prerequisite, requestId);
|
|
148
|
+
if (absolute === null)
|
|
149
|
+
closed.push({ path: relative, until });
|
|
150
|
+
}
|
|
151
|
+
return closed;
|
|
152
|
+
}
|
|
153
|
+
/** The furthest `reviewBy` this build accepts, as a release string. */
|
|
154
|
+
function reviewCapFor(installedVersion) {
|
|
155
|
+
const [major, minor] = installedVersion.replace(/^v/i, '').split(/[.-]/);
|
|
156
|
+
const minorNumber = Number.parseInt(minor ?? '0', 10);
|
|
157
|
+
return `v${major ?? '0'}.${(Number.isNaN(minorNumber) ? 0 : minorNumber) + REVIEW_CAP_MINORS}.0`;
|
|
158
|
+
}
|
|
159
|
+
/** The accepted entry that covers `window`, or the violation saying why none
|
|
160
|
+
* does.
|
|
161
|
+
*
|
|
162
|
+
* `reviewBy` is exclusive (an entry reviewed for this release has reached its
|
|
163
|
+
* target) and capped (`reviewBy` may sit at most two minors ahead), so a list
|
|
164
|
+
* that only grows or that jumps far ahead cannot keep accepting. */
|
|
165
|
+
function judgeClosedWindow(list, window, installedVersion) {
|
|
166
|
+
const entry = list.accepted.find((candidate) => candidate.path === window.path && candidate.until === window.until);
|
|
167
|
+
if (entry === undefined) {
|
|
168
|
+
return {
|
|
169
|
+
violation: `expired back-compat window and no current acceptance: ${window.path} — ${window.until} (installed ${installedVersion}); ask the LLM to add an entry to ${BACKCOMPAT_ACCEPTANCE_PATH} with a reason and a future reviewBy (the LLM edits the tracked file on the user's behalf), or produce the artifact`
|
|
170
|
+
};
|
|
171
|
+
}
|
|
172
|
+
if (compareReleaseVersions(installedVersion, entry.reviewBy) >= 0) {
|
|
173
|
+
return {
|
|
174
|
+
violation: `expired back-compat window and no current acceptance: ${window.path} — ${window.until} (installed ${installedVersion}); reviewBy ${entry.reviewBy} has been reached — ask the LLM to renew it with a future reviewBy or produce the artifact`
|
|
175
|
+
};
|
|
176
|
+
}
|
|
177
|
+
const cap = reviewCapFor(installedVersion);
|
|
178
|
+
if (compareReleaseVersions(entry.reviewBy, cap) > 0) {
|
|
179
|
+
return {
|
|
180
|
+
violation: `back-compat acceptance reviewBy is beyond the review cap: ${window.path} — ${window.until}; reviewBy ${entry.reviewBy} is more than ${REVIEW_CAP_MINORS} minor releases ahead of installed ${installedVersion} (cap ${cap}) — ask the LLM to lower reviewBy to ${cap} or earlier`
|
|
181
|
+
};
|
|
182
|
+
}
|
|
183
|
+
return { accepted: entry };
|
|
184
|
+
}
|
|
185
|
+
/**
|
|
186
|
+
* The COMMIT-LEG verdict on back-compat windows that have closed.
|
|
187
|
+
*
|
|
188
|
+
* The table is read through the same accessor the transition uses, and the
|
|
189
|
+
* import is dynamic because `artifact-prerequisites.ts` re-exports this module:
|
|
190
|
+
* a static edge back would close a runtime import cycle. Same idiom, same
|
|
191
|
+
* reason, as the lazy producer imports in `request-commands.ts`.
|
|
192
|
+
*/
|
|
193
|
+
export async function checkExpiredBackCompatCommitGate(options) {
|
|
194
|
+
const { getPrerequisitesFor } = await import('./artifact-prerequisites.js');
|
|
195
|
+
const installedVersion = options.installedVersion ?? CLI_VERSION;
|
|
196
|
+
const softRequirements = getPrerequisitesFor('rd', 'qa-handoff', options.requestType).filter((prerequisite) => prerequisite.backCompat === true);
|
|
197
|
+
if (softRequirements.length === 0)
|
|
198
|
+
return { violations: [], warnings: [] };
|
|
199
|
+
// Same sink guard as `checkPrerequisites`: the session id is joined into both
|
|
200
|
+
// roots below, so an unsafe value is refused where it would be used.
|
|
201
|
+
if (options.sessionId !== undefined && isUnsafePathInput(options.sessionId)) {
|
|
202
|
+
throw new Error(`Invalid session id: ${options.sessionId} (must be a single path segment)`);
|
|
203
|
+
}
|
|
204
|
+
const roots = sessionRootsFor(options.projectRoot, options.sessionId);
|
|
205
|
+
const closed = await closedBackCompatWindows(softRequirements, installedVersion, options.requestId, roots);
|
|
206
|
+
if (closed.length === 0)
|
|
207
|
+
return { violations: [], warnings: [] };
|
|
208
|
+
const list = await loadBackCompatAcceptances(options.projectRoot);
|
|
209
|
+
const violations = list.problem === null ? [] : [list.problem];
|
|
210
|
+
const warnings = [];
|
|
211
|
+
for (const window of closed) {
|
|
212
|
+
const decision = judgeClosedWindow(list, window, installedVersion);
|
|
213
|
+
if ('accepted' in decision) {
|
|
214
|
+
warnings.push(`accepted expired back-compat window: ${window.path} until ${window.until} (installed ${installedVersion}); reviewBy ${decision.accepted.reviewBy} — ${decision.accepted.reason}`);
|
|
215
|
+
continue;
|
|
216
|
+
}
|
|
217
|
+
violations.push(decision.violation);
|
|
218
|
+
}
|
|
219
|
+
return { violations, warnings };
|
|
220
|
+
}
|
|
@@ -42,6 +42,14 @@ import type { ArtifactPrerequisite } from './artifact-prerequisites.js';
|
|
|
42
42
|
* `rd/third-party-review.md`) differs by stem as well as by directory.
|
|
43
43
|
*/
|
|
44
44
|
export declare function backCompatWarningCode(prerequisite: ArtifactPrerequisite): string;
|
|
45
|
+
/** Negative when `a` predates `b`, positive when it follows, 0 when their
|
|
46
|
+
* release triples are equal.
|
|
47
|
+
*
|
|
48
|
+
* Exported because the commit-leg expiry gate makes the same comparison the
|
|
49
|
+
* soft warning makes: an acceptance entry is current only while its `reviewBy`
|
|
50
|
+
* is still ahead of the installed release. One comparator, so the two legs
|
|
51
|
+
* cannot disagree about where a window boundary sits. */
|
|
52
|
+
export declare function compareReleaseVersions(a: string, b: string): number;
|
|
45
53
|
/**
|
|
46
54
|
* The soft-pass warning for a missing `prerequisite`, or `null` when a missing
|
|
47
55
|
* file is a HARD failure and belongs in `missing` instead.
|
|
@@ -73,8 +73,13 @@ function releaseTriple(version) {
|
|
|
73
73
|
return triple;
|
|
74
74
|
}
|
|
75
75
|
/** Negative when `a` predates `b`, positive when it follows, 0 when their
|
|
76
|
-
* release triples are equal.
|
|
77
|
-
|
|
76
|
+
* release triples are equal.
|
|
77
|
+
*
|
|
78
|
+
* Exported because the commit-leg expiry gate makes the same comparison the
|
|
79
|
+
* soft warning makes: an acceptance entry is current only while its `reviewBy`
|
|
80
|
+
* is still ahead of the installed release. One comparator, so the two legs
|
|
81
|
+
* cannot disagree about where a window boundary sits. */
|
|
82
|
+
export function compareReleaseVersions(a, b) {
|
|
78
83
|
const left = releaseTriple(a);
|
|
79
84
|
const right = releaseTriple(b);
|
|
80
85
|
for (let index = 0; index < RELEASE_SEGMENTS; index += 1) {
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where a prerequisite resolves on disk: its declared path, the numbered
|
|
3
|
+
* filename prefix `request init` writes, and the historical session-root tiers.
|
|
4
|
+
*
|
|
5
|
+
* THE ONE RESOLVER. The transition (`checkPrerequisites`) and the commit gate
|
|
6
|
+
* (`checkExpiredBackCompatCommitGate`) both ask this module, so a numbered
|
|
7
|
+
* prefix or a legacy root that one honours cannot be misread by the other.
|
|
8
|
+
* It lives here, rather than in `artifact-prerequisites.ts`, because that file
|
|
9
|
+
* is over the file-size cap and a change may only shrink it.
|
|
10
|
+
*/
|
|
11
|
+
import type { ArtifactPrerequisite } from './artifact-prerequisites.js';
|
|
12
|
+
export declare function resolvePrerequisitePath(prerequisite: ArtifactPrerequisite, requestId: string): string;
|
|
13
|
+
/** The two session-root tiers the resolver probes: the canonical session home
|
|
14
|
+
* and the pre-F3 legacy one. ONE constructor, so the transition and the commit
|
|
15
|
+
* gate cannot disagree about where a session's evidence lives. */
|
|
16
|
+
export type SessionRoots = {
|
|
17
|
+
canonical: string | null;
|
|
18
|
+
legacy: string | null;
|
|
19
|
+
};
|
|
20
|
+
export declare function sessionRootsFor(projectRoot: string, sessionId: string | undefined): SessionRoots;
|
|
21
|
+
/**
|
|
22
|
+
* Resolve a prerequisite to an on-disk path, with a 2-tier fallback
|
|
23
|
+
* dirs are no longer created):
|
|
24
|
+
* 1. `<canonicalSessionRoot>/<relative>` (post-F3 canonical session
|
|
25
|
+
* home, when `canonicalSessionRoot` is provided).
|
|
26
|
+
* 2. `<legacySessionRoot>/<relative>` (pre-F3 legacy session home,
|
|
27
|
+
* when `legacySessionRoot` is provided).
|
|
28
|
+
* Tolerates the numbered filename prefix that `request init` writes
|
|
29
|
+
* (e.g. `001-<rid>.md`) at every tier. Returns the matched absolute
|
|
30
|
+
* path, or null when nothing matches.
|
|
31
|
+
*
|
|
32
|
+
* Back-compat: once neither primary session-root tier resolved, the
|
|
33
|
+
* resolver walks `prerequisite.legacyRelativePaths` in declared order
|
|
34
|
+
* and tries each at BOTH session roots before declaring the prereq
|
|
35
|
+
* missing. This covers both artifacts that moved location
|
|
36
|
+
* (`rd/security-review.md` → `audit/security.md`) and ones that later
|
|
37
|
+
* gained a rid in the filename (`audit/security.md` →
|
|
38
|
+
*/
|
|
39
|
+
export declare function resolvePrerequisiteAbsolutePathWithFallback(canonicalSessionRoot: string | null, legacySessionRoot: string | null, prerequisite: ArtifactPrerequisite, requestId: string): Promise<string | null>;
|