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
|
@@ -0,0 +1,110 @@
|
|
|
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 { join, dirname, basename } from 'node:path';
|
|
12
|
+
import { readdir } from 'node:fs/promises';
|
|
13
|
+
import { pathExists } from 'peaks-loop-shared/fs';
|
|
14
|
+
import { NUMBERED_PREFIX_RE, slugifyDescription } from '../../shared/incrementing-number.js';
|
|
15
|
+
export function resolvePrerequisitePath(prerequisite, requestId) {
|
|
16
|
+
return prerequisite.relativePath.replace('<rid>', requestId);
|
|
17
|
+
}
|
|
18
|
+
export function sessionRootsFor(projectRoot, sessionId) {
|
|
19
|
+
if (sessionId === undefined)
|
|
20
|
+
return { canonical: null, legacy: null };
|
|
21
|
+
return {
|
|
22
|
+
canonical: join(projectRoot, '.peaks', '_runtime', sessionId),
|
|
23
|
+
legacy: join(projectRoot, '.peaks', sessionId)
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Resolve a prerequisite to an on-disk path, tolerating the numbered filename
|
|
28
|
+
* prefix that `request init` writes (e.g. `001-<rid>.md`). When the prerequisite
|
|
29
|
+
* path contains `<rid>`, we accept either the legacy bare `<rid>.md` form or any
|
|
30
|
+
* `NNN-<rid>.md` numbered form — mirroring the matcher in request-artifact-service.
|
|
31
|
+
* Returns the matched absolute path, or null when nothing matches.
|
|
32
|
+
*/
|
|
33
|
+
async function resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, requestId) {
|
|
34
|
+
const relative = resolvePrerequisitePath(prerequisite, requestId);
|
|
35
|
+
const exact = join(sessionRoot, relative);
|
|
36
|
+
if (await pathExists(exact)) {
|
|
37
|
+
return exact;
|
|
38
|
+
}
|
|
39
|
+
// Only `<rid>`-templated prerequisites can carry a numbered prefix; fixed paths
|
|
40
|
+
// (e.g. rd/tech-doc.md) are matched exactly above.
|
|
41
|
+
if (!prerequisite.relativePath.includes('<rid>')) {
|
|
42
|
+
return null;
|
|
43
|
+
}
|
|
44
|
+
const dir = dirname(exact);
|
|
45
|
+
// The on-disk suffix is the SLUG of this basename — the writer lowercases the
|
|
46
|
+
// rid — so a mixed-case rid used to be reported absent with the file on disk.
|
|
47
|
+
const suffix = `-${slugifyDescription(basename(exact).replace(/\.md$/, ''))}.md`;
|
|
48
|
+
let entries;
|
|
49
|
+
try {
|
|
50
|
+
entries = await readdir(dir);
|
|
51
|
+
}
|
|
52
|
+
catch {
|
|
53
|
+
// TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
|
|
54
|
+
return null;
|
|
55
|
+
}
|
|
56
|
+
const match = entries.find((name) => NUMBERED_PREFIX_RE.test(name) && name.endsWith(suffix));
|
|
57
|
+
return match ? join(dir, match) : null;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Resolve a prerequisite to an on-disk path, with a 2-tier fallback
|
|
61
|
+
* dirs are no longer created):
|
|
62
|
+
* 1. `<canonicalSessionRoot>/<relative>` (post-F3 canonical session
|
|
63
|
+
* home, when `canonicalSessionRoot` is provided).
|
|
64
|
+
* 2. `<legacySessionRoot>/<relative>` (pre-F3 legacy session home,
|
|
65
|
+
* when `legacySessionRoot` is provided).
|
|
66
|
+
* Tolerates the numbered filename prefix that `request init` writes
|
|
67
|
+
* (e.g. `001-<rid>.md`) at every tier. Returns the matched absolute
|
|
68
|
+
* path, or null when nothing matches.
|
|
69
|
+
*
|
|
70
|
+
* Back-compat: once neither primary session-root tier resolved, the
|
|
71
|
+
* resolver walks `prerequisite.legacyRelativePaths` in declared order
|
|
72
|
+
* and tries each at BOTH session roots before declaring the prereq
|
|
73
|
+
* missing. This covers both artifacts that moved location
|
|
74
|
+
* (`rd/security-review.md` → `audit/security.md`) and ones that later
|
|
75
|
+
* gained a rid in the filename (`audit/security.md` →
|
|
76
|
+
*/
|
|
77
|
+
export async function resolvePrerequisiteAbsolutePathWithFallback(canonicalSessionRoot, legacySessionRoot, prerequisite, requestId) {
|
|
78
|
+
const roots = [canonicalSessionRoot, legacySessionRoot];
|
|
79
|
+
// First pass: try the primary relativePath at every root.
|
|
80
|
+
for (const root of roots) {
|
|
81
|
+
if (root === null)
|
|
82
|
+
continue;
|
|
83
|
+
const found = await resolvePrerequisiteAbsolutePath(root, prerequisite, requestId);
|
|
84
|
+
if (found !== null)
|
|
85
|
+
return found;
|
|
86
|
+
}
|
|
87
|
+
// Second pass: the single previous location, then any further older
|
|
88
|
+
// ones, at every root — newest first, so a session that somehow holds
|
|
89
|
+
// both a pre-rid and a v2.11.x file resolves to the newer shape.
|
|
90
|
+
// Only the relativePath is swapped — the same numbered-prefix
|
|
91
|
+
// tolerance applies via the shared resolver.
|
|
92
|
+
const legacyTiers = [
|
|
93
|
+
...(prerequisite.legacyRelativePath !== undefined ? [prerequisite.legacyRelativePath] : []),
|
|
94
|
+
...(prerequisite.legacyRelativePaths ?? [])
|
|
95
|
+
];
|
|
96
|
+
for (const legacy of legacyTiers) {
|
|
97
|
+
const legacyPrereq = {
|
|
98
|
+
...prerequisite,
|
|
99
|
+
relativePath: legacy
|
|
100
|
+
};
|
|
101
|
+
for (const root of roots) {
|
|
102
|
+
if (root === null)
|
|
103
|
+
continue;
|
|
104
|
+
const found = await resolvePrerequisiteAbsolutePath(root, legacyPrereq, requestId);
|
|
105
|
+
if (found !== null)
|
|
106
|
+
return found;
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
return null;
|
|
110
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The gates `transitionRequestArtifact` applies on `rd → implemented`,
|
|
3
|
+
* `rd → qa-handoff` and `rd → handed-off`: the per-file size ratchet and the
|
|
4
|
+
* declared-type corroboration. Extracted so `request-artifact-service.ts`
|
|
5
|
+
* (already over its cap) grows by one call instead of two blocks, and so the
|
|
6
|
+
* checks run for EVERY caller — not only the CLI flag path.
|
|
7
|
+
*
|
|
8
|
+
* ONE ENUMERATION PER TRANSITION. At `implemented` the change set is read once
|
|
9
|
+
* and shared: the type rule judges every path (deletions included, rename
|
|
10
|
+
* sources included), while the size scan measures the A/M/R/untracked subset.
|
|
11
|
+
* `qa-handoff` / `handed-off` run only the type rule (two git spawns); the size
|
|
12
|
+
* ratchet keeps the single state it has always judged.
|
|
13
|
+
*/
|
|
14
|
+
import type { RequestType } from './artifact-prerequisites.js';
|
|
15
|
+
import { type TypeCorroboration } from '../scan/type-corroboration.js';
|
|
16
|
+
export type RdGatePhase = 'implemented' | 'qa-handoff' | 'handed-off';
|
|
17
|
+
export declare class TypeCorroborationViolationError extends Error {
|
|
18
|
+
readonly code = "TYPE_CORROBORATION_VIOLATION";
|
|
19
|
+
readonly declaredType: RequestType;
|
|
20
|
+
readonly kind: 'source-touched' | 'diff-unavailable';
|
|
21
|
+
constructor(declaredType: RequestType, verdict: Extract<TypeCorroboration, {
|
|
22
|
+
ok: false;
|
|
23
|
+
}>);
|
|
24
|
+
}
|
|
25
|
+
/** Written into the artifact when `--allow-incomplete` skips a gate that COULD
|
|
26
|
+
* have judged this type: a silent bypass is indistinguishable from a pass. */
|
|
27
|
+
export declare function rdGatesBypassNote(phase: RdGatePhase): string;
|
|
28
|
+
export declare function runRdTransitionGates(options: {
|
|
29
|
+
projectRoot: string;
|
|
30
|
+
declaredType: RequestType;
|
|
31
|
+
allowIncomplete: boolean;
|
|
32
|
+
phase: RdGatePhase;
|
|
33
|
+
}): string | null;
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
import { FileSizeViolationError } from './request-artifact-state-helpers.js';
|
|
2
|
+
import { readGitChangeSet } from '../scan/file-size-baseline.js';
|
|
3
|
+
import { scanFileSize } from '../scan/file-size-scan.js';
|
|
4
|
+
import { corroborateDeclaredType, diffUnavailableVerdict, isToolingOnlyDeclaredType } from '../scan/type-corroboration.js';
|
|
5
|
+
export class TypeCorroborationViolationError extends Error {
|
|
6
|
+
code = 'TYPE_CORROBORATION_VIOLATION';
|
|
7
|
+
declaredType;
|
|
8
|
+
kind;
|
|
9
|
+
constructor(declaredType, verdict) {
|
|
10
|
+
super(verdict.message);
|
|
11
|
+
this.name = 'TypeCorroborationViolationError';
|
|
12
|
+
this.declaredType = declaredType;
|
|
13
|
+
this.kind = verdict.kind;
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
/** Written into the artifact when `--allow-incomplete` skips a gate that COULD
|
|
17
|
+
* have judged this type: a silent bypass is indistinguishable from a pass. */
|
|
18
|
+
export function rdGatesBypassNote(phase) {
|
|
19
|
+
const gates = phase === 'implemented'
|
|
20
|
+
? 'file-size ratchet, declared-type corroboration'
|
|
21
|
+
: 'declared-type corroboration';
|
|
22
|
+
return (`bypassed the rd ${phase} gates (${gates}) via --allow-incomplete; ` +
|
|
23
|
+
'none of them was evaluated');
|
|
24
|
+
}
|
|
25
|
+
/** The shared read, or the fail-closed verdict built from the same message. */
|
|
26
|
+
function readOrRefuse(projectRoot, declaredType) {
|
|
27
|
+
try {
|
|
28
|
+
return readGitChangeSet(projectRoot, 'HEAD');
|
|
29
|
+
}
|
|
30
|
+
catch {
|
|
31
|
+
throw new TypeCorroborationViolationError(declaredType, diffUnavailableVerdict(declaredType));
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
export function runRdTransitionGates(options) {
|
|
35
|
+
const judged = isToolingOnlyDeclaredType(options.declaredType);
|
|
36
|
+
if (options.allowIncomplete)
|
|
37
|
+
return judged ? rdGatesBypassNote(options.phase) : null;
|
|
38
|
+
if (!judged) {
|
|
39
|
+
// The size ratchet still runs at implemented; the type rule is a no-op here.
|
|
40
|
+
if (options.phase === 'implemented') {
|
|
41
|
+
const size = scanFileSize({ projectRoot: options.projectRoot });
|
|
42
|
+
if (!size.ok)
|
|
43
|
+
throw new FileSizeViolationError(size.violations);
|
|
44
|
+
}
|
|
45
|
+
return null;
|
|
46
|
+
}
|
|
47
|
+
if (options.phase !== 'implemented') {
|
|
48
|
+
const verdict = corroborateDeclaredType({
|
|
49
|
+
projectRoot: options.projectRoot,
|
|
50
|
+
declaredType: options.declaredType
|
|
51
|
+
});
|
|
52
|
+
if (!verdict.ok)
|
|
53
|
+
throw new TypeCorroborationViolationError(options.declaredType, verdict);
|
|
54
|
+
return null;
|
|
55
|
+
}
|
|
56
|
+
const changeSet = readOrRefuse(options.projectRoot, options.declaredType);
|
|
57
|
+
const verdict = corroborateDeclaredType({
|
|
58
|
+
projectRoot: options.projectRoot,
|
|
59
|
+
declaredType: options.declaredType,
|
|
60
|
+
changedPaths: changeSet.changedPaths
|
|
61
|
+
});
|
|
62
|
+
if (!verdict.ok)
|
|
63
|
+
throw new TypeCorroborationViolationError(options.declaredType, verdict);
|
|
64
|
+
const size = scanFileSize({
|
|
65
|
+
projectRoot: options.projectRoot,
|
|
66
|
+
changedFiles: changeSet.changedFiles
|
|
67
|
+
});
|
|
68
|
+
if (!size.ok)
|
|
69
|
+
throw new FileSizeViolationError(size.violations);
|
|
70
|
+
return null;
|
|
71
|
+
}
|
|
@@ -15,7 +15,7 @@ import { isUnsafePathInput } from '../../shared/path-safety.js';
|
|
|
15
15
|
import { guardRuntimeSegment, runtimeRoot } from '../../shared/runtime-root.js';
|
|
16
16
|
import { checkTypeSanity } from '../scan/type-sanity-service.js';
|
|
17
17
|
import { requireUserConfirmation } from '../mode/mode-enforcement.js';
|
|
18
|
-
import {
|
|
18
|
+
import { runRdTransitionGates } from './rd-transition-gates.js';
|
|
19
19
|
import { emitObservabilityEvent } from '../observability/observability-service.js';
|
|
20
20
|
export { VALID_REQUEST_TYPES, DEFAULT_REQUEST_TYPE, isRequestType };
|
|
21
21
|
// Re-export the pure-function template surface so external callers (CLI,
|
|
@@ -127,13 +127,13 @@ export async function createRequestArtifact(options) {
|
|
|
127
127
|
if (await isDirectory(requestsDir)) {
|
|
128
128
|
const existingFiles = await listMarkdownFiles(requestsDir);
|
|
129
129
|
// The writer lowercases the request id into a kebab slug
|
|
130
|
-
// (`buildNumberedFilename`), so the duplicate
|
|
131
|
-
//
|
|
130
|
+
// (`buildNumberedFilename`), so the duplicate check compares against the SAME
|
|
131
|
+
// slug — read off each filename by the one reader that owns the naming rule.
|
|
132
132
|
const slug = slugifyDescription(options.requestId);
|
|
133
133
|
const alreadyExists = existingFiles.some((file) => {
|
|
134
134
|
if (file === `${options.requestId}.md`)
|
|
135
135
|
return true;
|
|
136
|
-
if (
|
|
136
|
+
if (requestIdFromFileName(file) === slug)
|
|
137
137
|
return true;
|
|
138
138
|
return false;
|
|
139
139
|
});
|
|
@@ -280,8 +280,8 @@ export async function showRequestArtifact(options) {
|
|
|
280
280
|
if (file === `${options.requestId}.md`) {
|
|
281
281
|
return { fileName: file, path: join(dir, file) };
|
|
282
282
|
}
|
|
283
|
-
// Match
|
|
284
|
-
if (
|
|
283
|
+
// Match the id this filename carries, by the ONE rule that owns it
|
|
284
|
+
if (requestIdFromFileName(file) === slug) {
|
|
285
285
|
return { fileName: file, path: join(dir, file) };
|
|
286
286
|
}
|
|
287
287
|
}
|
|
@@ -333,7 +333,7 @@ async function readRequestArtifact(dir, role, found, sessionId) {
|
|
|
333
333
|
// the sibling `request-artifact-state-helpers.ts` module — see
|
|
334
334
|
// v2.18.3 file-split for the rationale. Function signatures and
|
|
335
335
|
// behaviour are unchanged (verbatim move).
|
|
336
|
-
import { ALLOWED_STATES_PER_ROLE,
|
|
336
|
+
import { ALLOWED_STATES_PER_ROLE, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock } from './request-artifact-state-helpers.js';
|
|
337
337
|
import { assertLegalStateStep } from './request-state-order.js';
|
|
338
338
|
export { allowedStatesForRole, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock } from './request-artifact-state-helpers.js';
|
|
339
339
|
export async function transitionRequestArtifact(options) {
|
|
@@ -401,27 +401,29 @@ export async function transitionRequestArtifact(options) {
|
|
|
401
401
|
sessionId: existing.sessionId
|
|
402
402
|
});
|
|
403
403
|
if (lintReport !== null && !lintReport.ok) {
|
|
404
|
-
const
|
|
405
|
-
if (
|
|
406
|
-
throw new LintGateError(options.role, options.newState,
|
|
404
|
+
const errors = lintReport.findings.filter((f) => f.severity === 'error');
|
|
405
|
+
if (errors.length > 0) {
|
|
406
|
+
throw new LintGateError(options.role, options.newState, errors);
|
|
407
407
|
}
|
|
408
408
|
}
|
|
409
409
|
}
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
410
|
+
const gateBypassNote = options.role === 'rd' &&
|
|
411
|
+
(options.newState === 'implemented' ||
|
|
412
|
+
options.newState === 'qa-handoff' ||
|
|
413
|
+
options.newState === 'handed-off')
|
|
414
|
+
? runRdTransitionGates({
|
|
415
|
+
projectRoot: options.projectRoot,
|
|
416
|
+
declaredType: existing.requestType,
|
|
417
|
+
allowIncomplete: options.allowIncomplete === true,
|
|
418
|
+
phase: options.newState
|
|
419
|
+
})
|
|
420
|
+
: null;
|
|
419
421
|
const clock = options.clock ?? defaultClock;
|
|
420
422
|
const timestamp = clock();
|
|
421
423
|
const bypassNote = !prerequisiteResult.ok && options.allowIncomplete === true
|
|
422
424
|
? `bypassed prerequisites (${prerequisiteResult.missing.map((entry) => entry.path).join(', ')})`
|
|
423
425
|
: undefined;
|
|
424
|
-
const combinedReason = [options.reason, bypassNote]
|
|
426
|
+
const combinedReason = [options.reason, bypassNote, gateBypassNote ?? undefined]
|
|
425
427
|
.filter((part) => part !== undefined && part.length > 0)
|
|
426
428
|
.join(' | ');
|
|
427
429
|
const reasonForNote = combinedReason.length > 0 ? combinedReason : undefined;
|
|
@@ -18,12 +18,20 @@ export declare class PrerequisitesNotSatisfiedError extends Error {
|
|
|
18
18
|
readonly warnings: PrerequisiteCheckResult['warnings'];
|
|
19
19
|
constructor(role: RequestArtifactRole, newState: RequestArtifactState, sessionId: string, missing: PrerequisiteCheckResult['missing'], warnings?: PrerequisiteCheckResult['warnings']);
|
|
20
20
|
}
|
|
21
|
+
/** The diagnosis a lint refusal carries: the `line`, `text` and `reason` the linter
|
|
22
|
+
* computed for each finding and this error previously kept only a count of. */
|
|
23
|
+
export type LintGateFinding = {
|
|
24
|
+
line: number;
|
|
25
|
+
text: string;
|
|
26
|
+
reason: string;
|
|
27
|
+
};
|
|
21
28
|
export declare class LintGateError extends Error {
|
|
22
29
|
readonly code = "LINT_GATE_FAILED";
|
|
23
30
|
readonly role: RequestArtifactRole;
|
|
24
31
|
readonly newState: RequestArtifactState;
|
|
25
32
|
readonly errorCount: number;
|
|
26
|
-
|
|
33
|
+
readonly findings: ReadonlyArray<LintGateFinding>;
|
|
34
|
+
constructor(role: RequestArtifactRole, newState: RequestArtifactState, findings: ReadonlyArray<LintGateFinding>);
|
|
27
35
|
}
|
|
28
36
|
export declare class TypeSanityViolationError extends Error {
|
|
29
37
|
readonly code = "TYPE_SANITY_VIOLATION";
|
|
@@ -22,7 +22,7 @@ export class PrerequisitesNotSatisfiedError extends Error {
|
|
|
22
22
|
*/
|
|
23
23
|
warnings;
|
|
24
24
|
constructor(role, newState, sessionId, missing, warnings = []) {
|
|
25
|
-
super(`Cannot transition ${role} to ${newState}: ${missing.length}
|
|
25
|
+
super(`Cannot transition ${role} to ${newState}: ${missing.length} unmet requirement${missing.length === 1 ? '' : 's'} under .peaks/_runtime/${sessionId}/`);
|
|
26
26
|
this.name = 'PrerequisitesNotSatisfiedError';
|
|
27
27
|
this.role = role;
|
|
28
28
|
this.newState = newState;
|
|
@@ -36,13 +36,15 @@ export class LintGateError extends Error {
|
|
|
36
36
|
role;
|
|
37
37
|
newState;
|
|
38
38
|
errorCount;
|
|
39
|
-
|
|
40
|
-
|
|
39
|
+
findings;
|
|
40
|
+
constructor(role, newState, findings) {
|
|
41
|
+
super(`Cannot transition ${role} to ${newState}: ${findings.length} lint error(s) found in artifact. ` +
|
|
41
42
|
'Fix lint errors or use --allow-incomplete to bypass.');
|
|
42
43
|
this.name = 'LintGateError';
|
|
43
44
|
this.role = role;
|
|
44
45
|
this.newState = newState;
|
|
45
|
-
this.
|
|
46
|
+
this.findings = findings;
|
|
47
|
+
this.errorCount = findings.length;
|
|
46
48
|
}
|
|
47
49
|
}
|
|
48
50
|
export class TypeSanityViolationError extends Error {
|
|
@@ -23,6 +23,7 @@ export type JudgedRefusal = {
|
|
|
23
23
|
readonly artifact: string;
|
|
24
24
|
readonly path: string;
|
|
25
25
|
};
|
|
26
|
+
export declare function describeJudgedRefusal(refusal: JudgedRefusal): string;
|
|
26
27
|
export type JudgedCheckResult = {
|
|
27
28
|
readonly refusals: readonly JudgedRefusal[];
|
|
28
29
|
readonly checked: number;
|
|
@@ -20,7 +20,68 @@
|
|
|
20
20
|
import { existsSync, readFileSync } from 'node:fs';
|
|
21
21
|
import { execFileSync } from 'node:child_process';
|
|
22
22
|
import { join } from 'node:path';
|
|
23
|
-
import { parseJudgedDeclaration, sha256OfFile } from './judged-declaration.js';
|
|
23
|
+
import { JUDGED_HEADING, parseJudgedDeclaration, sha256OfFile } from './judged-declaration.js';
|
|
24
|
+
/**
|
|
25
|
+
* What a refusal means, partitioned by THE ONE QUESTION its codes answer:
|
|
26
|
+
* **did this check complete the observation its sentence would assert?** One
|
|
27
|
+
* sentence for all 17 told a producer to satisfy a declaration a `declared-path-*`
|
|
28
|
+
* refusal had already read — "name the requirement that is unmet" broken one level
|
|
29
|
+
* in, and the reason the arm has been split four times since. The partition below
|
|
30
|
+
* is stated so a reviewer checks it, rather than hunting members:
|
|
31
|
+
*
|
|
32
|
+
* A. `declaration-*` — **11 codes** (`missing`, `unfenced`, `unterminated`,
|
|
33
|
+
* `empty`, `schema`, `path`, `hash`, `duplicate`, `bare-root`, `escaped`,
|
|
34
|
+
* `unparsable`). No declaration was read at all, so the sentence is about the
|
|
35
|
+
* BLOCK and claims nothing about the tree.
|
|
36
|
+
* B. `artifact-unreadable` — **1**. The artifact was not read; nothing about its
|
|
37
|
+
* declaration is known.
|
|
38
|
+
* C. `declared-path-unreadable` — **1**. The path was reached and could not be
|
|
39
|
+
* read, so its hash is **UNKNOWN**, not mismatched. Its own arm because the
|
|
40
|
+
* remedy differs and "re-run the producer" cannot work: a re-run hashes the
|
|
41
|
+
* same unreadable path and refuses identically.
|
|
42
|
+
* D. `root-listing-failed` — **1**. A root was declared and could NOT be listed,
|
|
43
|
+
* so no file under it was compared. Its answer is "no observation", not
|
|
44
|
+
* "mismatch".
|
|
45
|
+
* E. `declared-path-gone`, `declared-path-modified`,
|
|
46
|
+
* `undeclared-path-under-root` — **3**. All three COMPLETED their observation:
|
|
47
|
+
* a declared path is absent or edited, or the listing succeeded and found a
|
|
48
|
+
* file under a declared root that the declaration does not name. Together they
|
|
49
|
+
* are the only codes that may say the tree and the declaration disagree — which
|
|
50
|
+
* is why they are a LIST and not the `else` arm.
|
|
51
|
+
* F. **0 codes today** — the fail-safe. Anything unrecognised gets a sentence that
|
|
52
|
+
* asserts only what is certain (it parsed and was read). Codes A–E are
|
|
53
|
+
* exhaustive over the 17 the two modules emit, so this arm is unreachable now;
|
|
54
|
+
* it exists so a NEW code cannot inherit an observation it did not make, which
|
|
55
|
+
* is the failure this comment records four times.
|
|
56
|
+
*
|
|
57
|
+
* A producer reads this in a refusal, so the classes are the ACTIONS, not the codes:
|
|
58
|
+
* write the block, make the path readable, or re-run the producer.
|
|
59
|
+
*/
|
|
60
|
+
/** The codes that completed a tree observation, and so may say the tree disagrees. */
|
|
61
|
+
const OBSERVED_DISAGREEMENT = new Set([
|
|
62
|
+
'declared-path-gone',
|
|
63
|
+
'declared-path-modified',
|
|
64
|
+
'undeclared-path-under-root'
|
|
65
|
+
]);
|
|
66
|
+
export function describeJudgedRefusal(refusal) {
|
|
67
|
+
const where = `Judged declaration ${refusal.code} at ${refusal.path}`;
|
|
68
|
+
if (refusal.code === 'artifact-unreadable') {
|
|
69
|
+
return `${where}: the artifact is present but could not be read, so its \`${JUDGED_HEADING}\` declaration is unverified`;
|
|
70
|
+
}
|
|
71
|
+
if (refusal.code === 'declared-path-unreadable') {
|
|
72
|
+
return `${where}: the declaration is present and parses, but a path it names is present and unreadable, so its hash is unknown — make that path readable; re-running the producer hashes the same path and refuses identically`;
|
|
73
|
+
}
|
|
74
|
+
if (refusal.code === 'root-listing-failed') {
|
|
75
|
+
return `${where}: the declaration is present and parses and names this as a root, but the root could not be listed, so no file under it was compared — re-run the producer, which declares no roots`;
|
|
76
|
+
}
|
|
77
|
+
if (refusal.code.startsWith('declaration-')) {
|
|
78
|
+
return `${where}: the artifact is present; what is unmet is its \`${JUDGED_HEADING}\` block, absent or not one this check can accept`;
|
|
79
|
+
}
|
|
80
|
+
if (OBSERVED_DISAGREEMENT.has(refusal.code)) {
|
|
81
|
+
return `${where}: the declaration was read and the tree compared against it, and the two do not agree — re-run the producer`;
|
|
82
|
+
}
|
|
83
|
+
return `${where}: the declaration is present and parses; this code records no comparison this check completed, so treat the tree as unverified and re-run the producer`;
|
|
84
|
+
}
|
|
24
85
|
/** Where the security audit artifact may live, newest tier first. */
|
|
25
86
|
export function securityArtifactTiers(rid) {
|
|
26
87
|
return [
|
|
@@ -208,15 +208,11 @@ export declare const CODEGRAPH_UNAVAILABLE_BLOCK: string;
|
|
|
208
208
|
/** Binding phrases every dispatch prompt must contain, for every role. */
|
|
209
209
|
export declare const BINDING_RULE_TOKENS: readonly string[];
|
|
210
210
|
/**
|
|
211
|
-
* The runner-direct-path tokens: the
|
|
212
|
-
*
|
|
213
|
-
*
|
|
214
|
-
*
|
|
215
|
-
*
|
|
216
|
-
* `peaks test <file>` because it resolves the local binary Windows-aware.
|
|
217
|
-
*
|
|
218
|
-
* so this set is asserted IDENTICALLY for every role. The runner EXAMPLES
|
|
219
|
-
* were removed as part of the unification — they were never rules.
|
|
211
|
+
* The runner-direct-path tokens: the scope requirement; the whole-tree tier by ALL THREE of its
|
|
212
|
+
* members (both guard directories and the root selector); the PRINCIPLE they are the mechanism
|
|
213
|
+
* for; the two direct paths the block names (`peaks test --json` to introspect, PB-5 = the
|
|
214
|
+
* repo-defined `test` / `test:*` scripts that are NOT gated); and the quality guidance that must
|
|
215
|
+
* survive compression — never assume a runner without asking; prefer `peaks test <file>`.
|
|
220
216
|
*/
|
|
221
217
|
export declare const TEST_RUNNER_RULE_TOKENS: readonly string[];
|
|
222
218
|
/**
|
|
@@ -334,25 +334,25 @@ export const BINDING_RULE_TOKENS = [
|
|
|
334
334
|
'do NOT invoke `npx <runner>`',
|
|
335
335
|
'## Test Scope (mandatory)',
|
|
336
336
|
'PEAKS_FULL_TEST=1',
|
|
337
|
-
'
|
|
337
|
+
'not permitted'
|
|
338
338
|
];
|
|
339
339
|
/**
|
|
340
|
-
* The runner-direct-path tokens: the
|
|
341
|
-
*
|
|
342
|
-
*
|
|
343
|
-
*
|
|
344
|
-
*
|
|
345
|
-
* `peaks test <file>` because it resolves the local binary Windows-aware.
|
|
346
|
-
*
|
|
347
|
-
* so this set is asserted IDENTICALLY for every role. The runner EXAMPLES
|
|
348
|
-
* were removed as part of the unification — they were never rules.
|
|
340
|
+
* The runner-direct-path tokens: the scope requirement; the whole-tree tier by ALL THREE of its
|
|
341
|
+
* members (both guard directories and the root selector); the PRINCIPLE they are the mechanism
|
|
342
|
+
* for; the two direct paths the block names (`peaks test --json` to introspect, PB-5 = the
|
|
343
|
+
* repo-defined `test` / `test:*` scripts that are NOT gated); and the quality guidance that must
|
|
344
|
+
* survive compression — never assume a runner without asking; prefer `peaks test <file>`.
|
|
349
345
|
*/
|
|
350
346
|
export const TEST_RUNNER_RULE_TOKENS = [
|
|
351
347
|
'`./node_modules/.bin/vitest run`',
|
|
352
348
|
'PB-5',
|
|
353
349
|
'`peaks test --json`',
|
|
354
350
|
'ask the user before assuming a runner',
|
|
355
|
-
'(Windows-aware)'
|
|
351
|
+
'(Windows-aware)',
|
|
352
|
+
'subject is the tree, not one file, is in scope for every slice',
|
|
353
|
+
'`tests/unit/standards`',
|
|
354
|
+
'`tests/unit/lint`',
|
|
355
|
+
'`tests/unit/*.test.ts`'
|
|
356
356
|
];
|
|
357
357
|
/**
|
|
358
358
|
* Return the subset of `tokens` that `text` does NOT contain. Pure; used by
|
|
@@ -108,7 +108,7 @@ export const POST_COMPACT_REINJECTION_BYTE_BUDGET = 3072;
|
|
|
108
108
|
*/
|
|
109
109
|
export const AGENT_RUNTIME_RULES = Object.freeze([
|
|
110
110
|
'CLI: run `node --import tsx src/cli/index.ts <cmd>`, never `pnpm exec tsx` — on Windows the latter truncates any argument at its first newline.',
|
|
111
|
-
'Test scope: one file or pattern per run; the full suite requires PEAKS_FULL_TEST=1.',
|
|
111
|
+
'Test scope: one file or pattern per run; the full suite requires PEAKS_FULL_TEST=1; a slice also runs the whole-tree tier tests/unit/standards + tests/unit/lint + the root of tests/unit/ (tests/unit/*.test.ts).',
|
|
112
112
|
"Exit codes: never read a test result through a pipe (`| tail` reports tail's status); read ${PIPESTATUS[0]}.",
|
|
113
113
|
'Never write `.claude/settings.local.json` from a slice — reproduce against a temp project copy via `--project <tmpdir>`.',
|
|
114
114
|
'Git: commit / push policy is per-dispatch and is NOT inherited from this card — re-read the dispatch record before any state-mutating git command.',
|
|
@@ -36,11 +36,20 @@
|
|
|
36
36
|
* examples. No role split remains, so every role receives a byte-identical
|
|
37
37
|
* block.
|
|
38
38
|
*/
|
|
39
|
-
export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nRead `package.json#scripts.test` for the project's framework and use the project-local runner \u2014 do NOT invoke `npx <runner>`. If unsure, run `peaks test --json` first. Only as a last resort, ask the user before assuming a runner. `peaks test <file>` already resolves the local binary for you (Windows-aware).\n\n## Test Scope (mandatory)\n\nAny test command MUST be **scoped** to a single file or pattern
|
|
39
|
+
export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nRead `package.json#scripts.test` for the project's framework and use the project-local runner \u2014 do NOT invoke `npx <runner>`. If unsure, run `peaks test --json` first. Only as a last resort, ask the user before assuming a runner. `peaks test <file>` already resolves the local binary for you (Windows-aware).\n\n## Test Scope (mandatory)\n\nAny test command MUST be **scoped** to a single file or pattern \u2014 a bare `./node_modules/.bin/vitest run` is **not permitted** without the explicit opt-in token `PEAKS_FULL_TEST=1` (CI / release verification only, never routine slice verification). Nothing inspects the command you run: this is a rule you follow, not a gate that fires.\n\nA suite whose subject is the tree, not one file, is in scope for every slice, whatever the slice changed \u2014 it can go red for a change outside its own subtree. This repo's tier is `tests/unit/standards`, `tests/unit/lint` and the root of `tests/unit/` (`tests/unit/*.test.ts`): add all three to a slice's run, once per slice rather than per reviewer pass.\n\nRepo-defined `test` / `test:*` scripts are the human/LLM direct path and are NOT gated by this scope rule (PB-5).";
|
|
40
40
|
/**
|
|
41
41
|
* Pure helper that returns the block. Exists as a function (not just an
|
|
42
42
|
* exported constant) so future variants can take a runtime parameter
|
|
43
43
|
* (e.g. projectRoot for context) without churning every call site.
|
|
44
|
+
*
|
|
45
|
+
* The whole-tree tier (2026-10-16) names `tests/unit/standards`, `tests/unit/lint`
|
|
46
|
+
* and the root of `tests/unit/` (`tests/unit/*.test.ts`). A file-scoped run cannot
|
|
47
|
+
* cover a suite whose subject is the tree: the push gate's area rule turns
|
|
48
|
+
* `src/<area>` into `tests/unit/<area>`, and no guard directory has an area of its
|
|
49
|
+
* own to be reached through. That gap is a HAND-run's alone — the classifier's
|
|
50
|
+
* `subset()` unions the whole tier into every subset verdict, so the gate reaches
|
|
51
|
+
* the tier on every diff it runs at all. The one diff it does NOT run is gate data
|
|
52
|
+
* alone whose content did not move: that verdict selects 0 tests, root tier included.
|
|
44
53
|
*/
|
|
45
54
|
export declare function formatTestToolDetection(): string;
|
|
46
55
|
/**
|
|
@@ -49,6 +58,13 @@ export declare function formatTestToolDetection(): string;
|
|
|
49
58
|
* whether the command is allowed, refused, or requires the explicit
|
|
50
59
|
* opt-in.
|
|
51
60
|
*
|
|
61
|
+
* NO CALLER YET, stated so the next reader does not look for one: nothing
|
|
62
|
+
* under `src/`, `tests/` or `scripts/` imports this. The dispatch block
|
|
63
|
+
* states the scope as a rule the agent follows, and does not claim a run is
|
|
64
|
+
* refused — wiring this into the `peaks test` CLI or a hook is a separate
|
|
65
|
+
* change with its own blast radius, and it is the owner's call, not a
|
|
66
|
+
* consequence of the rule text.
|
|
67
|
+
*
|
|
52
68
|
* - 'scoped' — the command names a file/pattern after `run`
|
|
53
69
|
* - 'opt-in' — the user/LLM set PEAKS_FULL_TEST=1 to override
|
|
54
70
|
* - 'refused' — bare `vitest run` with no path and no opt-in
|
|
@@ -42,13 +42,24 @@ Read \`package.json#scripts.test\` for the project's framework and use the proje
|
|
|
42
42
|
|
|
43
43
|
## Test Scope (mandatory)
|
|
44
44
|
|
|
45
|
-
Any test command MUST be **scoped** to a single file or pattern
|
|
45
|
+
Any test command MUST be **scoped** to a single file or pattern — a bare \`./node_modules/.bin/vitest run\` is **not permitted** without the explicit opt-in token \`PEAKS_FULL_TEST=1\` (CI / release verification only, never routine slice verification). Nothing inspects the command you run: this is a rule you follow, not a gate that fires.
|
|
46
|
+
|
|
47
|
+
A suite whose subject is the tree, not one file, is in scope for every slice, whatever the slice changed — it can go red for a change outside its own subtree. This repo's tier is \`tests/unit/standards\`, \`tests/unit/lint\` and the root of \`tests/unit/\` (\`tests/unit/*.test.ts\`): add all three to a slice's run, once per slice rather than per reviewer pass.
|
|
46
48
|
|
|
47
49
|
Repo-defined \`test\` / \`test:*\` scripts are the human/LLM direct path and are NOT gated by this scope rule (PB-5).`;
|
|
48
50
|
/**
|
|
49
51
|
* Pure helper that returns the block. Exists as a function (not just an
|
|
50
52
|
* exported constant) so future variants can take a runtime parameter
|
|
51
53
|
* (e.g. projectRoot for context) without churning every call site.
|
|
54
|
+
*
|
|
55
|
+
* The whole-tree tier (2026-10-16) names `tests/unit/standards`, `tests/unit/lint`
|
|
56
|
+
* and the root of `tests/unit/` (`tests/unit/*.test.ts`). A file-scoped run cannot
|
|
57
|
+
* cover a suite whose subject is the tree: the push gate's area rule turns
|
|
58
|
+
* `src/<area>` into `tests/unit/<area>`, and no guard directory has an area of its
|
|
59
|
+
* own to be reached through. That gap is a HAND-run's alone — the classifier's
|
|
60
|
+
* `subset()` unions the whole tier into every subset verdict, so the gate reaches
|
|
61
|
+
* the tier on every diff it runs at all. The one diff it does NOT run is gate data
|
|
62
|
+
* alone whose content did not move: that verdict selects 0 tests, root tier included.
|
|
52
63
|
*/
|
|
53
64
|
export function formatTestToolDetection() {
|
|
54
65
|
return TEST_TOOL_DETECTION_BLOCK;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Check: the project carries the commit-leg back-compat acceptance list
|
|
3
|
+
* (`config:backcompat-acceptance`).
|
|
4
|
+
*
|
|
5
|
+
* Absence is a FAILURE, not a skip: without the list the commit-leg expiry gate
|
|
6
|
+
* fails closed, so a feature / bugfix / refactor slice cannot complete. The
|
|
7
|
+
* doctor reports the same state (`severity: 'error'`) and names the seed the
|
|
8
|
+
* `peaks workspace init` command writes — the LLM runs it on the user's behalf.
|
|
9
|
+
*
|
|
10
|
+
* An uninitialized project (no `.peaks/`) is not this check's finding: the
|
|
11
|
+
* workspace-init check owns that state, and reporting here too would name the
|
|
12
|
+
* same root twice.
|
|
13
|
+
*/
|
|
14
|
+
import type { DoctorCheckPlugin } from '../types.js';
|
|
15
|
+
export declare const check: DoctorCheckPlugin;
|