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.
Files changed (25) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +31 -0
  3. package/dist/cli/commands/core/skill-registry-commands.js +9 -4
  4. package/dist/services/artifacts/artifact-prerequisites.d.ts +1 -0
  5. package/dist/services/artifacts/artifact-prerequisites.js +9 -97
  6. package/dist/services/artifacts/backcompat-acceptance.d.ts +66 -0
  7. package/dist/services/artifacts/backcompat-acceptance.js +220 -0
  8. package/dist/services/artifacts/prerequisite-checks.d.ts +8 -0
  9. package/dist/services/artifacts/prerequisite-checks.js +7 -2
  10. package/dist/services/artifacts/prerequisite-path-resolver.d.ts +39 -0
  11. package/dist/services/artifacts/prerequisite-path-resolver.js +110 -0
  12. package/dist/services/doctor/doctor-service/checks/backcompat-acceptance.d.ts +15 -0
  13. package/dist/services/doctor/doctor-service/checks/backcompat-acceptance.js +53 -0
  14. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +38 -0
  15. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +243 -0
  16. package/dist/services/doctor/doctor-service/plugin-registry.js +4 -0
  17. package/dist/services/doctor/doctor-service/types.d.ts +12 -0
  18. package/dist/services/workflow/pipeline-verify-gate-support.d.ts +4 -1
  19. package/dist/services/workflow/pipeline-verify-gate-support.js +8 -79
  20. package/dist/services/workflow/pipeline-verify-rd-phase.d.ts +67 -0
  21. package/dist/services/workflow/pipeline-verify-rd-phase.js +122 -0
  22. package/dist/services/workflow/pipeline-verify-service.js +16 -17
  23. package/dist/services/workspace/workspace-service.js +4 -16
  24. package/package.json +5 -5
  25. package/schemas/doctor-report.schema.json +2 -2
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "metadata": {
3
3
  "pluginRoot": ".",
4
- "version": "4.1.6"
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.6",
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
- const failed = skillChecks.filter((check) => !check.ok).length;
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
- io.stdout(`\n ${skillChecks.length - failed} passed, ${failed} failed`);
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 { join, dirname, basename } from 'node:path';
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
- const canonicalSessionRoot = options.sessionId !== undefined
400
- ? join(options.projectRoot, '.peaks', '_runtime', options.sessionId)
401
- : null;
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(canonicalSessionRoot, legacySessionRoot, prerequisite, options.requestId);
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
- function compareReleaseVersions(a, b) {
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>;