peaks-loop 4.1.5 → 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 +67 -0
- package/README-en.md +47 -183
- package/README.md +24 -188
- package/dist/cli/commands/best-practice-scan-command.d.ts +11 -6
- package/dist/cli/commands/best-practice-scan-command.js +35 -20
- package/dist/cli/commands/best-practice-scan-helpers.d.ts +47 -0
- package/dist/cli/commands/best-practice-scan-helpers.js +88 -5
- package/dist/cli/commands/best-practice-scan-lookup-results.d.ts +13 -0
- package/dist/cli/commands/best-practice-scan-lookup-results.js +237 -0
- package/dist/cli/commands/core/skill-registry-commands.js +9 -4
- package/dist/cli/commands/dispatch-command-spec.js +1 -1
- package/dist/cli/commands/dispatch-isolation-lease.d.ts +1 -1
- package/dist/cli/commands/dispatch-isolation-lease.js +6 -53
- package/dist/cli/commands/dispatch-prompt-blocks.d.ts +1 -1
- package/dist/cli/commands/dispatch-prompt-composition.d.ts +1 -1
- package/dist/cli/commands/dispatch-record-write.d.ts +1 -1
- package/dist/cli/commands/dispatch-tool-call.d.ts +1 -1
- package/dist/cli/commands/openspec-command-shared.js +2 -2
- package/dist/cli/commands/request-transition-failures.js +31 -4
- package/dist/cli/commands/request-transition-preflight.js +1 -1
- package/dist/cli/commands/slice-decompose-artifacts.js +2 -1
- package/dist/cli/commands/verdict-aggregate-command.js +2 -1
- package/dist/cli/commands/workflow-gate-commands.js +4 -4
- package/dist/cli/program.js +0 -2
- package/dist/services/artifacts/artifact-contract-block.js +21 -2
- package/dist/services/artifacts/artifact-prerequisites.d.ts +1 -0
- package/dist/services/artifacts/artifact-prerequisites.js +11 -99
- 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/artifacts/rd-transition-gates.d.ts +33 -0
- package/dist/services/artifacts/rd-transition-gates.js +71 -0
- package/dist/services/artifacts/request-artifact-service.js +22 -20
- package/dist/services/artifacts/request-artifact-state-helpers.d.ts +9 -1
- package/dist/services/artifacts/request-artifact-state-helpers.js +6 -4
- package/dist/services/audit-independent/judged-declaration-check.d.ts +1 -0
- package/dist/services/audit-independent/judged-declaration-check.js +62 -1
- package/dist/services/context/build-dispatch-system-prompt.d.ts +5 -9
- package/dist/services/context/build-dispatch-system-prompt.js +11 -11
- package/dist/services/context/post-compact-reinjection.js +1 -1
- package/dist/services/dispatch/test-tool-detection.d.ts +17 -1
- package/dist/services/dispatch/test-tool-detection.js +12 -1
- 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/evidence/evidence-generator.js +8 -4
- package/dist/services/openspec/coverage-evidence-reader.d.ts +9 -9
- package/dist/services/openspec/coverage-evidence-reader.js +8 -8
- package/dist/services/openspec/openspec-archive-service.d.ts +1 -1
- package/dist/services/openspec/openspec-archive-service.js +6 -6
- package/dist/services/scan/file-size-baseline.d.ts +13 -6
- package/dist/services/scan/file-size-baseline.js +54 -31
- package/dist/services/scan/file-size-scan.d.ts +7 -14
- package/dist/services/scan/file-size-scan.js +6 -1
- package/dist/services/scan/type-corroboration.d.ts +32 -0
- package/dist/services/scan/type-corroboration.js +51 -0
- package/dist/services/scan/type-sanity-service.d.ts +14 -0
- package/dist/services/scan/type-sanity-service.js +10 -19
- package/dist/services/security/safe-settings-path.d.ts +5 -0
- package/dist/services/security/safe-settings-path.js +64 -8
- package/dist/services/skill/resume-detector.js +8 -8
- package/dist/services/workflow/pipeline-verify-gate-support.d.ts +28 -9
- package/dist/services/workflow/pipeline-verify-gate-support.js +40 -117
- package/dist/services/workflow/pipeline-verify-qa-phase.d.ts +102 -0
- package/dist/services/workflow/pipeline-verify-qa-phase.js +176 -0
- 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 +42 -44
- package/dist/services/workflow/request-type-resolution.d.ts +99 -0
- package/dist/services/workflow/request-type-resolution.js +130 -0
- package/dist/services/workflow/workflow-skip-service.d.ts +1 -0
- package/dist/services/workflow/workflow-skip-service.js +19 -21
- package/dist/services/workflow/workflow-state-store.d.ts +9 -0
- package/dist/services/workflow/workflow-state-store.js +26 -1
- package/dist/services/workspace/workspace-service.js +4 -16
- package/dist/shared/incrementing-number.d.ts +23 -2
- package/dist/shared/incrementing-number.js +57 -15
- package/package.json +5 -7
- package/schemas/doctor-report.schema.json +2 -2
- package/skills/bee/peaks-prd/SKILL.md +3 -2
- package/skills/peaks-code/SKILL.md +32 -15
- package/dist/cli/commands/vm-command-shared.d.ts +0 -23
- package/dist/cli/commands/vm-command-shared.js +0 -23
- package/dist/cli/commands/vm-commands.d.ts +0 -3
- package/dist/cli/commands/vm-commands.js +0 -45
- package/dist/cli/commands/vm-hypervisor-probe.d.ts +0 -27
- package/dist/cli/commands/vm-hypervisor-probe.js +0 -78
- package/dist/cli/commands/vm-hypervisor-runtime.d.ts +0 -15
- package/dist/cli/commands/vm-hypervisor-runtime.js +0 -64
- package/dist/cli/commands/vm-release-command.d.ts +0 -5
- package/dist/cli/commands/vm-release-command.js +0 -101
- package/dist/cli/commands/vm-spawn-command.d.ts +0 -5
- package/dist/cli/commands/vm-spawn-command.js +0 -177
- package/dist/cli/commands/vm-status-command.d.ts +0 -3
- package/dist/cli/commands/vm-status-command.js +0 -50
- package/dist/services/vm/vm-lease.d.ts +0 -40
- package/dist/services/vm/vm-lease.js +0 -160
|
@@ -108,6 +108,15 @@ const BODY_RULE = 'The gate matches each marker below as a case-insensitive subs
|
|
|
108
108
|
*/
|
|
109
109
|
const SCOPE_BASE = 'This block is generated from the prerequisite table alone, so the rows below are necessary and are ' +
|
|
110
110
|
'not a complete contract.';
|
|
111
|
+
/**
|
|
112
|
+
* The body-lint gate, named in EVERY non-empty block because it runs for every role
|
|
113
|
+
* and every type: the transition OUT of `draft` lints the artifact and refuses on
|
|
114
|
+
* any placeholder the template still carries. The block said nothing about it, so a
|
|
115
|
+
* producer that satisfied every row below still met a refusal the carrier had never
|
|
116
|
+
* mentioned — the same defect as a row whose marker the producer was not shown.
|
|
117
|
+
*/
|
|
118
|
+
const SCOPE_LINT = ' Separately from the rows above: leaving `draft` runs the body lint over this artifact, and it ' +
|
|
119
|
+
'refuses on a placeholder the template still carries — an unfilled `<...>` token or a `- ...` stub.';
|
|
111
120
|
/**
|
|
112
121
|
* The addendum for a state the gate really does guard with more than the table.
|
|
113
122
|
* Measured on a probe project and again on this slice's own rid: an artifact set
|
|
@@ -115,9 +124,19 @@ const SCOPE_BASE = 'This block is generated from the prerequisite table alone, s
|
|
|
115
124
|
* outside the table. The earlier wording said a gate "may also check something
|
|
116
125
|
* the table does not carry", which under-claims a systematic gap at exactly the
|
|
117
126
|
* state this block guides a producer to.
|
|
127
|
+
*
|
|
128
|
+
* The declaration is named because naming it is the whole fix: the refusal used to
|
|
129
|
+
* report the artifact as absent when the artifact was there and only its
|
|
130
|
+
* declaration was unmet, so a producer that read this far-first ended one refusal
|
|
131
|
+
* later than it needed to.
|
|
132
|
+
* NO PRODUCER IS NAMED: the same declaration is required of whichever security
|
|
133
|
+
* artifact the rows above demand — a `config` slice's is `rd/security-review-<rid>.md`
|
|
134
|
+
* — and more than one in-repo producer writes a valid one.
|
|
118
135
|
*/
|
|
119
136
|
const SCOPE_HANDOFF = ' At `rd:qa-handoff` the gate also runs checks that are not rows of this table, so satisfying every ' +
|
|
120
|
-
'row below does not by itself open that transition.'
|
|
137
|
+
'row below does not by itself open that transition. One is the judged declaration: the security ' +
|
|
138
|
+
'artifact the rows above name must also carry a `## Judged content` block, and a body written ' +
|
|
139
|
+
'without one satisfies the row and is still refused.';
|
|
121
140
|
const ARTIFACT_CONTRACT_HEADING = '## Artifact contract (generated from the prerequisite table)';
|
|
122
141
|
/**
|
|
123
142
|
* The block, or `''` when this role has nothing gated to say under this type.
|
|
@@ -139,7 +158,7 @@ export function buildArtifactContractBlock(input) {
|
|
|
139
158
|
return (`\n${ARTIFACT_CONTRACT_HEADING}\n` +
|
|
140
159
|
`Role \`${input.role}\`, ${typeLine}.\n` +
|
|
141
160
|
`${BODY_RULE}\n` +
|
|
142
|
-
`${SCOPE_BASE}${guardedHandoff ? SCOPE_HANDOFF : ''}\n` +
|
|
161
|
+
`${SCOPE_BASE}${guardedHandoff ? SCOPE_HANDOFF : ''}${SCOPE_LINT}\n` +
|
|
143
162
|
rows.map((row) => row.text).join('') +
|
|
144
163
|
'\n');
|
|
145
164
|
}
|
|
@@ -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,9 +1,11 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { readFile, readdir } from 'node:fs/promises';
|
|
3
|
-
import { pathExists } from 'peaks-loop-shared/fs';
|
|
1
|
+
import { readFile } from 'node:fs/promises';
|
|
4
2
|
import { emitPrereqTransitionEvent } from './prerequisite-transition-event.js';
|
|
5
3
|
import { isUnsafePathInput } from '../../shared/path-safety.js';
|
|
6
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';
|
|
7
9
|
export const VALID_REQUEST_TYPES = [
|
|
8
10
|
'feature',
|
|
9
11
|
'bugfix',
|
|
@@ -337,40 +339,6 @@ export function getPrerequisitesFor(role, newState, requestType) {
|
|
|
337
339
|
const table = PREREQUISITES_BY_TYPE[requestType];
|
|
338
340
|
return table[`${role}:${newState}`] ?? [];
|
|
339
341
|
}
|
|
340
|
-
function resolvePrerequisitePath(prerequisite, requestId) {
|
|
341
|
-
return prerequisite.relativePath.replace('<rid>', requestId);
|
|
342
|
-
}
|
|
343
|
-
/**
|
|
344
|
-
* Resolve a prerequisite to an on-disk path, tolerating the numbered filename
|
|
345
|
-
* prefix that `request init` writes (e.g. `001-<rid>.md`). When the prerequisite
|
|
346
|
-
* path contains `<rid>`, we accept either the legacy bare `<rid>.md` form or any
|
|
347
|
-
* `NNN-<rid>.md` numbered form — mirroring the matcher in request-artifact-service.
|
|
348
|
-
* Returns the matched absolute path, or null when nothing matches.
|
|
349
|
-
*/
|
|
350
|
-
async function resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, requestId) {
|
|
351
|
-
const relative = resolvePrerequisitePath(prerequisite, requestId);
|
|
352
|
-
const exact = join(sessionRoot, relative);
|
|
353
|
-
if (await pathExists(exact)) {
|
|
354
|
-
return exact;
|
|
355
|
-
}
|
|
356
|
-
// Only `<rid>`-templated prerequisites can carry a numbered prefix; fixed paths
|
|
357
|
-
// (e.g. rd/tech-doc.md) are matched exactly above.
|
|
358
|
-
if (!prerequisite.relativePath.includes('<rid>')) {
|
|
359
|
-
return null;
|
|
360
|
-
}
|
|
361
|
-
const dir = dirname(exact);
|
|
362
|
-
const targetSuffix = `-${basename(exact)}`;
|
|
363
|
-
let entries;
|
|
364
|
-
try {
|
|
365
|
-
entries = await readdir(dir);
|
|
366
|
-
}
|
|
367
|
-
catch {
|
|
368
|
-
// TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
|
|
369
|
-
return null;
|
|
370
|
-
}
|
|
371
|
-
const match = entries.find((name) => /^\d+-/.test(name) && name.endsWith(targetSuffix));
|
|
372
|
-
return match ? join(dir, match) : null;
|
|
373
|
-
}
|
|
374
342
|
export async function checkPrerequisites(options) {
|
|
375
343
|
const requirements = getPrerequisitesFor(options.role, options.newState, options.requestType);
|
|
376
344
|
if (requirements.length === 0) {
|
|
@@ -393,15 +361,14 @@ export async function checkPrerequisites(options) {
|
|
|
393
361
|
// back-compat).
|
|
394
362
|
// The sessionId is preserved in the artifact body's frontmatter for
|
|
395
363
|
// human navigation; it is no longer a filesystem path key.
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
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);
|
|
400
367
|
const missing = [];
|
|
401
368
|
const warnings = [];
|
|
402
369
|
for (const prerequisite of requirements) {
|
|
403
370
|
const relative = resolvePrerequisitePath(prerequisite, options.requestId);
|
|
404
|
-
const absolute = await resolvePrerequisiteAbsolutePathWithFallback(
|
|
371
|
+
const absolute = await resolvePrerequisiteAbsolutePathWithFallback(roots.canonical, roots.legacy, prerequisite, options.requestId);
|
|
405
372
|
if (absolute === null) {
|
|
406
373
|
// A `backCompat` prerequisite downgrades a missing file to a warning, NOT
|
|
407
374
|
// a hard failure; v2.14.0/v2.15.0 re-elevate it. The decision and the
|
|
@@ -456,16 +423,13 @@ export async function checkPrerequisites(options) {
|
|
|
456
423
|
// re-hashes them, so a repair after the audit is refused by name. An
|
|
457
424
|
// artifact with no declaration is refused here, not waved through — a
|
|
458
425
|
// deleted section is the shed this arm exists to close.
|
|
459
|
-
const { verifyJudgedDeclaration } = await import('../audit-independent/judged-declaration-check.js');
|
|
426
|
+
const { describeJudgedRefusal, verifyJudgedDeclaration } = await import('../audit-independent/judged-declaration-check.js');
|
|
460
427
|
for (const refusal of verifyJudgedDeclaration({
|
|
461
428
|
projectRoot: options.projectRoot,
|
|
462
429
|
sessionId: options.sessionId,
|
|
463
430
|
requestId: options.requestId
|
|
464
431
|
}).refusals) {
|
|
465
|
-
missing.push({
|
|
466
|
-
path: refusal.artifact,
|
|
467
|
-
description: `Judged declaration ${refusal.code} at ${refusal.path}`
|
|
468
|
-
});
|
|
432
|
+
missing.push({ path: refusal.artifact, description: describeJudgedRefusal(refusal) });
|
|
469
433
|
}
|
|
470
434
|
}
|
|
471
435
|
const result = { ok: missing.length === 0, missing, warnings };
|
|
@@ -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>;
|