peaks-loop 4.1.5 → 4.1.6
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 +36 -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/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.js +7 -7
- 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/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 +24 -8
- package/dist/services/workflow/pipeline-verify-gate-support.js +32 -38
- 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-service.js +26 -27
- 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/shared/incrementing-number.d.ts +23 -2
- package/dist/shared/incrementing-number.js +57 -15
- package/package.json +5 -7
- 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,99 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which request type this rid declares — DERIVED, so no caller can get it wrong.
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS EXISTS. `verifyPipeline` took the request type as an option and fell
|
|
5
|
+
* back to `feature` when it was absent. The two callers that matter both left it
|
|
6
|
+
* absent — `peaks workflow verify-pipeline` passes it only when a human types
|
|
7
|
+
* `--type`, and `slice-check` never passes it — so the CHECKER read every rid as
|
|
8
|
+
* `feature` while the commit-time carrier read the rid's own `- type:` line and
|
|
9
|
+
* got it right. For a docs or chore request those two readers disagreed on the
|
|
10
|
+
* same tree: `verify-pipeline` reported three RD-evidence violations and
|
|
11
|
+
* `complete: false`, and the commit leg reported the contract satisfied.
|
|
12
|
+
*
|
|
13
|
+
* That is the same defect one layer up from the gate list: two layers answering
|
|
14
|
+
* one question, each with its own answer. So the answer is derived here, in ONE
|
|
15
|
+
* place, and every caller inherits it — `--type` stays as the explicit override.
|
|
16
|
+
*
|
|
17
|
+
* THE RULE IS THE CARRIER'S OWN, deliberately. `CARRIER_ROLES` is the order
|
|
18
|
+
* `.husky/pipeline/contract-verdict.mjs` enumerates a rid's carriers in
|
|
19
|
+
* (`CARRIER_DIRS`), and the first carrier that exists answers — including when its
|
|
20
|
+
* answer is the reader's substituted default, which is what that leg does with an
|
|
21
|
+
* unusable or absent `- type:` line.
|
|
22
|
+
*
|
|
23
|
+
* THE SCOPE IS THE CARRIER'S OWN TOO, AND THAT PART CAME SECOND. Matching the
|
|
24
|
+
* ORDER while scanning every directory under `.peaks/_runtime/` was a security
|
|
25
|
+
* defect, not a style question: a directory whose name sorted before the rid's
|
|
26
|
+
* session won, so anyone able to create one file under `.peaks/_runtime/` could
|
|
27
|
+
* choose ANY rid's gate table — silently, with the type looking like an ordinary
|
|
28
|
+
* derivation. Measured before the fix: a docs rid read as `feature`, `complete`
|
|
29
|
+
* true → false, with an empty 16-byte file in a directory beside it.
|
|
30
|
+
*
|
|
31
|
+
* So a carrier is read from a SESSION and never from a bare directory: the caller's
|
|
32
|
+
* session when it named one, else the canonical binding's, else the fail-closed
|
|
33
|
+
* default. Two further review rounds measured what the middle grounds cost — a
|
|
34
|
+
* session chosen by its directory NAME, then a directory named after the request
|
|
35
|
+
* itself, read as the EVIDENCE scope — and each is now shut off in the module that
|
|
36
|
+
* owns that axis. See `sessionsToRead` and, for the evidence half,
|
|
37
|
+
* `pipeline-verify-service.ts`'s empty-scope guard.
|
|
38
|
+
*
|
|
39
|
+
* WHAT "READS NOTHING" COVERS, STATED EXACTLY: the type (this module), the request
|
|
40
|
+
* artifact (`findRequestFile`, which answers null for a null scope), and the
|
|
41
|
+
* evidence (`resolveRdEvidencePaths` / `resolveQaEvidencePaths`, which are handed
|
|
42
|
+
* an empty gate list). All three axes, or the sentence is the kind of comment this
|
|
43
|
+
* slice exists to remove.
|
|
44
|
+
*/
|
|
45
|
+
import { type RequestType } from '../artifacts/artifact-prerequisites.js';
|
|
46
|
+
/**
|
|
47
|
+
* The rid's carriers, in the order the commit-time leg reads them: the RD request
|
|
48
|
+
* is the slice's own record, and a PRD- or QA-only rid still answers.
|
|
49
|
+
*
|
|
50
|
+
* EXPORTED FOR ITS PARITY ARM, and that is not decoration. These three roles and
|
|
51
|
+
* `.husky/pipeline/contract-verdict.mjs`'s `CARRIER_DIRS` are two literals held
|
|
52
|
+
* equal by a comment, which is the duplicate-derivation pattern this whole line of
|
|
53
|
+
* work exists to remove. They cannot be one literal without a layering inversion —
|
|
54
|
+
* the hook reads `src/` dynamically and lazily, and `src/` may not read `.husky/` —
|
|
55
|
+
* so an arm asserts the equality instead, and a reorder on either side reddens it.
|
|
56
|
+
*/
|
|
57
|
+
export declare const CARRIER_ROLES: readonly ["rd", "prd", "qa"];
|
|
58
|
+
/**
|
|
59
|
+
* Whether a skip may be HONOURED for a request of this type — the request-type
|
|
60
|
+
* rule, asserted again when a skip is READ.
|
|
61
|
+
*
|
|
62
|
+
* WHY THE READ RE-ASSERTS IT. `isWorkflowSkipState` validates field PRESENCE only;
|
|
63
|
+
* the three write-time rules (this allowlist, one-time, caller kind) live in
|
|
64
|
+
* `canSkipSlice`, so a hand-planted file satisfies the shape and none of the rules.
|
|
65
|
+
* Measured: a planted file flipped the commit leg from refusing a FEATURE rid with
|
|
66
|
+
* six missing artifacts to passing it. A reader that acts on the record is trusting
|
|
67
|
+
* a carrier, which is the thing this line of work exists to stop.
|
|
68
|
+
*
|
|
69
|
+
* It lives here, beside the request type, because the rule IS a statement about the
|
|
70
|
+
* request type; it reuses `SKIPPABLE_TYPES` rather than respelling the allowlist.
|
|
71
|
+
* WHAT IT CANNOT DO: for a type the allowlist permits the record IS the
|
|
72
|
+
* authorization, and a reader cannot tell a planted one from a written one — the
|
|
73
|
+
* measured axis is the forbidden one, and the residual is in the RD artifact.
|
|
74
|
+
*/
|
|
75
|
+
export declare function mayHonourSkip(requestType: RequestType): boolean;
|
|
76
|
+
/**
|
|
77
|
+
* What a caller is told when no scope resolves — the refusal names itself and
|
|
78
|
+
* names the remedy, rather than reporting a missing artifact nobody can act on.
|
|
79
|
+
*/
|
|
80
|
+
export declare const NO_SESSION_SCOPE = "No session scope resolved: name one with --session-id <id>, or run inside a tree that has a peaks session binding. Nothing is read without one \u2014 not a carrier from some other directory, and not evidence from a directory named after this request.";
|
|
81
|
+
/**
|
|
82
|
+
* The type of `rid`, or `request.requestType` when that is a request type.
|
|
83
|
+
*
|
|
84
|
+
* `request.requestType` is the caller's `--type`: an explicit, validated override.
|
|
85
|
+
* It is checked against the same membership rule the artifacts layer uses, so a
|
|
86
|
+
* typo falls through to the derivation rather than selecting a table by accident.
|
|
87
|
+
*
|
|
88
|
+
* The parameter is the request's own identity, which is what every caller already
|
|
89
|
+
* has to hand — so no caller has to remember a separate argument.
|
|
90
|
+
*/
|
|
91
|
+
export declare function resolveRequestType(request: {
|
|
92
|
+
projectRoot: string;
|
|
93
|
+
rid: string;
|
|
94
|
+
/** The caller's `--type`, when it passed one. */
|
|
95
|
+
requestType?: string;
|
|
96
|
+
/** The session the caller is working in, when it named one. `null` is a
|
|
97
|
+
* resolved answer too: it means no scope could be resolved. */
|
|
98
|
+
sessionId?: string | null | undefined;
|
|
99
|
+
}): Promise<RequestType>;
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which request type this rid declares — DERIVED, so no caller can get it wrong.
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS EXISTS. `verifyPipeline` took the request type as an option and fell
|
|
5
|
+
* back to `feature` when it was absent. The two callers that matter both left it
|
|
6
|
+
* absent — `peaks workflow verify-pipeline` passes it only when a human types
|
|
7
|
+
* `--type`, and `slice-check` never passes it — so the CHECKER read every rid as
|
|
8
|
+
* `feature` while the commit-time carrier read the rid's own `- type:` line and
|
|
9
|
+
* got it right. For a docs or chore request those two readers disagreed on the
|
|
10
|
+
* same tree: `verify-pipeline` reported three RD-evidence violations and
|
|
11
|
+
* `complete: false`, and the commit leg reported the contract satisfied.
|
|
12
|
+
*
|
|
13
|
+
* That is the same defect one layer up from the gate list: two layers answering
|
|
14
|
+
* one question, each with its own answer. So the answer is derived here, in ONE
|
|
15
|
+
* place, and every caller inherits it — `--type` stays as the explicit override.
|
|
16
|
+
*
|
|
17
|
+
* THE RULE IS THE CARRIER'S OWN, deliberately. `CARRIER_ROLES` is the order
|
|
18
|
+
* `.husky/pipeline/contract-verdict.mjs` enumerates a rid's carriers in
|
|
19
|
+
* (`CARRIER_DIRS`), and the first carrier that exists answers — including when its
|
|
20
|
+
* answer is the reader's substituted default, which is what that leg does with an
|
|
21
|
+
* unusable or absent `- type:` line.
|
|
22
|
+
*
|
|
23
|
+
* THE SCOPE IS THE CARRIER'S OWN TOO, AND THAT PART CAME SECOND. Matching the
|
|
24
|
+
* ORDER while scanning every directory under `.peaks/_runtime/` was a security
|
|
25
|
+
* defect, not a style question: a directory whose name sorted before the rid's
|
|
26
|
+
* session won, so anyone able to create one file under `.peaks/_runtime/` could
|
|
27
|
+
* choose ANY rid's gate table — silently, with the type looking like an ordinary
|
|
28
|
+
* derivation. Measured before the fix: a docs rid read as `feature`, `complete`
|
|
29
|
+
* true → false, with an empty 16-byte file in a directory beside it.
|
|
30
|
+
*
|
|
31
|
+
* So a carrier is read from a SESSION and never from a bare directory: the caller's
|
|
32
|
+
* session when it named one, else the canonical binding's, else the fail-closed
|
|
33
|
+
* default. Two further review rounds measured what the middle grounds cost — a
|
|
34
|
+
* session chosen by its directory NAME, then a directory named after the request
|
|
35
|
+
* itself, read as the EVIDENCE scope — and each is now shut off in the module that
|
|
36
|
+
* owns that axis. See `sessionsToRead` and, for the evidence half,
|
|
37
|
+
* `pipeline-verify-service.ts`'s empty-scope guard.
|
|
38
|
+
*
|
|
39
|
+
* WHAT "READS NOTHING" COVERS, STATED EXACTLY: the type (this module), the request
|
|
40
|
+
* artifact (`findRequestFile`, which answers null for a null scope), and the
|
|
41
|
+
* evidence (`resolveRdEvidencePaths` / `resolveQaEvidencePaths`, which are handed
|
|
42
|
+
* an empty gate list). All three axes, or the sentence is the kind of comment this
|
|
43
|
+
* slice exists to remove.
|
|
44
|
+
*/
|
|
45
|
+
import { DEFAULT_REQUEST_TYPE, isRequestType } from '../artifacts/artifact-prerequisites.js';
|
|
46
|
+
import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
|
|
47
|
+
import { getSessionIdCanonical } from '../session/session-manager.js';
|
|
48
|
+
import { SKIPPABLE_TYPES } from './workflow-skip-service.js';
|
|
49
|
+
/**
|
|
50
|
+
* The rid's carriers, in the order the commit-time leg reads them: the RD request
|
|
51
|
+
* is the slice's own record, and a PRD- or QA-only rid still answers.
|
|
52
|
+
*
|
|
53
|
+
* EXPORTED FOR ITS PARITY ARM, and that is not decoration. These three roles and
|
|
54
|
+
* `.husky/pipeline/contract-verdict.mjs`'s `CARRIER_DIRS` are two literals held
|
|
55
|
+
* equal by a comment, which is the duplicate-derivation pattern this whole line of
|
|
56
|
+
* work exists to remove. They cannot be one literal without a layering inversion —
|
|
57
|
+
* the hook reads `src/` dynamically and lazily, and `src/` may not read `.husky/` —
|
|
58
|
+
* so an arm asserts the equality instead, and a reorder on either side reddens it.
|
|
59
|
+
*/
|
|
60
|
+
export const CARRIER_ROLES = ['rd', 'prd', 'qa'];
|
|
61
|
+
/**
|
|
62
|
+
* Whether a skip may be HONOURED for a request of this type — the request-type
|
|
63
|
+
* rule, asserted again when a skip is READ.
|
|
64
|
+
*
|
|
65
|
+
* WHY THE READ RE-ASSERTS IT. `isWorkflowSkipState` validates field PRESENCE only;
|
|
66
|
+
* the three write-time rules (this allowlist, one-time, caller kind) live in
|
|
67
|
+
* `canSkipSlice`, so a hand-planted file satisfies the shape and none of the rules.
|
|
68
|
+
* Measured: a planted file flipped the commit leg from refusing a FEATURE rid with
|
|
69
|
+
* six missing artifacts to passing it. A reader that acts on the record is trusting
|
|
70
|
+
* a carrier, which is the thing this line of work exists to stop.
|
|
71
|
+
*
|
|
72
|
+
* It lives here, beside the request type, because the rule IS a statement about the
|
|
73
|
+
* request type; it reuses `SKIPPABLE_TYPES` rather than respelling the allowlist.
|
|
74
|
+
* WHAT IT CANNOT DO: for a type the allowlist permits the record IS the
|
|
75
|
+
* authorization, and a reader cannot tell a planted one from a written one — the
|
|
76
|
+
* measured axis is the forbidden one, and the residual is in the RD artifact.
|
|
77
|
+
*/
|
|
78
|
+
export function mayHonourSkip(requestType) {
|
|
79
|
+
return SKIPPABLE_TYPES.includes(requestType);
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* What a caller is told when no scope resolves — the refusal names itself and
|
|
83
|
+
* names the remedy, rather than reporting a missing artifact nobody can act on.
|
|
84
|
+
*/
|
|
85
|
+
export const NO_SESSION_SCOPE = 'No session scope resolved: name one with --session-id <id>, or run inside a tree that has a peaks session binding. Nothing is read without one — not a carrier from some other directory, and not evidence from a directory named after this request.';
|
|
86
|
+
/**
|
|
87
|
+
* The one session this rid's carriers may be read from: the caller's, or the
|
|
88
|
+
* canonical binding's. NOTHING when neither resolves.
|
|
89
|
+
*
|
|
90
|
+
* WHY NOTHING, AND NOT A LIST OF "RECOGNISED" SESSIONS. An earlier version fell
|
|
91
|
+
* back to `discoverSessions` when no session resolved — and "recognised" is a
|
|
92
|
+
* DIRECTORY NAME (`/^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/`) sorted ascending, so
|
|
93
|
+
* a writer-chosen name decided the gate table on any tree where no session
|
|
94
|
+
* resolved; measured through the CLI, that turned a refused rid into
|
|
95
|
+
* `complete: true` with no violations. A name is not a proof of which session is
|
|
96
|
+
* being verified, and an unbound tree cannot say — so the answer is the
|
|
97
|
+
* fail-closed default, and the caller names the session when it knows one.
|
|
98
|
+
*/
|
|
99
|
+
function sessionsToRead(request) {
|
|
100
|
+
const named = request.sessionId ?? getSessionIdCanonical(request.projectRoot);
|
|
101
|
+
return named === null ? [] : [named];
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* The type of `rid`, or `request.requestType` when that is a request type.
|
|
105
|
+
*
|
|
106
|
+
* `request.requestType` is the caller's `--type`: an explicit, validated override.
|
|
107
|
+
* It is checked against the same membership rule the artifacts layer uses, so a
|
|
108
|
+
* typo falls through to the derivation rather than selecting a table by accident.
|
|
109
|
+
*
|
|
110
|
+
* The parameter is the request's own identity, which is what every caller already
|
|
111
|
+
* has to hand — so no caller has to remember a separate argument.
|
|
112
|
+
*/
|
|
113
|
+
export async function resolveRequestType(request) {
|
|
114
|
+
if (isRequestType(request.requestType ?? ''))
|
|
115
|
+
return request.requestType;
|
|
116
|
+
for (const sessionId of sessionsToRead(request)) {
|
|
117
|
+
for (const role of CARRIER_ROLES) {
|
|
118
|
+
const artifact = await showRequestArtifact({
|
|
119
|
+
projectRoot: request.projectRoot,
|
|
120
|
+
role,
|
|
121
|
+
requestId: request.rid,
|
|
122
|
+
sessionId
|
|
123
|
+
});
|
|
124
|
+
if (artifact === null)
|
|
125
|
+
continue;
|
|
126
|
+
return artifact.requestType;
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
return DEFAULT_REQUEST_TYPE;
|
|
130
|
+
}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { type WorkflowSkipState } from './workflow-state-store.js';
|
|
2
2
|
import type { RequestType } from '../artifacts/artifact-prerequisites.js';
|
|
3
|
+
export declare const SKIPPABLE_TYPES: ReadonlyArray<RequestType>;
|
|
3
4
|
export type SkipArgs = {
|
|
4
5
|
/** Request id this skip applies to. */
|
|
5
6
|
rid: string;
|
|
@@ -1,28 +1,26 @@
|
|
|
1
1
|
/**
|
|
2
2
|
*
|
|
3
3
|
* Pure-function classifier (`canSkipSlice`) + side-effecting applicator
|
|
4
|
-
* (`applySkip`). Both are testable without filesystem mocks
|
|
5
|
-
*
|
|
6
|
-
* pair so the unit tests use in-memory fakes; the production caller
|
|
7
|
-
* passes the real store from `workflow-state-store.ts`).
|
|
4
|
+
* (`applySkip`). Both are testable without filesystem mocks: injected
|
|
5
|
+
* read/write state functions, the real store in production.
|
|
8
6
|
*
|
|
9
7
|
* Three rules (per RD §Why + Tech Doc §2-4):
|
|
10
8
|
* - Rule 1 (slice type allowlist): `bugfix` / `feature` / `refactor`
|
|
11
|
-
* can never skip QA
|
|
12
|
-
* `
|
|
13
|
-
* - Rule 2 (one-time semantics):
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
* with `reason: "rid already has a different skip applied"`.
|
|
9
|
+
* can never skip QA. The allowlist is DERIVED from the pipeline's
|
|
10
|
+
* QA-free set (`QA_FREE_TYPES`); today that is `docs` / `chore`.
|
|
11
|
+
* - Rule 2 (one-time semantics): the same skip on the same rid is an
|
|
12
|
+
* idempotent no-op (`applied: false`); a different one is denied with
|
|
13
|
+
* `reason: "rid already has a different skip applied"`.
|
|
17
14
|
* - Rule 3 (role-based authorization): scripts (caller kind derived
|
|
18
15
|
* from `$PEAKS_CALLER_ID` env var) MUST pass `--i-have-reviewed`
|
|
19
16
|
* in addition to `--reason`.
|
|
20
17
|
*/
|
|
21
18
|
import { execFileSync } from 'node:child_process';
|
|
22
19
|
import { userInfo } from 'node:os';
|
|
23
|
-
import { readSkipState, writeSkipState } from './workflow-state-store.js';
|
|
20
|
+
import { hasControlChars, readSkipState, writeSkipState } from './workflow-state-store.js';
|
|
24
21
|
import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
|
|
25
|
-
|
|
22
|
+
import { QA_FREE_TYPES } from './pipeline-verify-qa-phase.js';
|
|
23
|
+
export const SKIPPABLE_TYPES = QA_FREE_TYPES;
|
|
26
24
|
const SCRIPT_CALLER_IDS = ['ci', 'postinstall', 'cron'];
|
|
27
25
|
/** Parse the `--gates` CLI arg (e.g. "QA,slice-check") into string[]. */
|
|
28
26
|
export function parseGatesList(raw) {
|
|
@@ -55,17 +53,17 @@ export function detectCallerKind(envCallerId) {
|
|
|
55
53
|
*/
|
|
56
54
|
export async function canSkipSlice(projectRoot, sessionId, args, currentState) {
|
|
57
55
|
// Argument validation (no filesystem).
|
|
58
|
-
if (args.reason.trim().length === 0) {
|
|
56
|
+
if (args.reason.trim().length === 0 || hasControlChars(args.reason)) {
|
|
59
57
|
return {
|
|
60
58
|
allowed: false,
|
|
61
|
-
reason: 'skip requires --reason; what is the user-visible justification for this QA bypass?'
|
|
59
|
+
reason: 'skip requires a single-line --reason; what is the user-visible justification for this QA bypass?'
|
|
62
60
|
};
|
|
63
61
|
}
|
|
64
62
|
const gates = parseGatesList(args.gatesRaw);
|
|
65
|
-
if (gates.length === 0) {
|
|
63
|
+
if (gates.length === 0 || gates.some(hasControlChars)) {
|
|
66
64
|
return {
|
|
67
65
|
allowed: false,
|
|
68
|
-
reason: '--gates must list at least one gate name (e.g. "QA" or "QA,slice-check")'
|
|
66
|
+
reason: '--gates must list at least one single-line gate name (e.g. "QA" or "QA,slice-check")'
|
|
69
67
|
};
|
|
70
68
|
}
|
|
71
69
|
// Resolve caller kind.
|
|
@@ -96,7 +94,7 @@ export async function canSkipSlice(projectRoot, sessionId, args, currentState) {
|
|
|
96
94
|
if (!SKIPPABLE_TYPES.includes(sliceType)) {
|
|
97
95
|
return {
|
|
98
96
|
allowed: false,
|
|
99
|
-
reason: `slice type "${sliceType}" cannot skip QA (
|
|
97
|
+
reason: `slice type "${sliceType}" cannot skip QA (QA-free types: ${SKIPPABLE_TYPES.join(', ')})`,
|
|
100
98
|
sliceType
|
|
101
99
|
};
|
|
102
100
|
}
|
|
@@ -188,8 +186,8 @@ function pathFromStateFile(projectRoot, sessionId, rid) {
|
|
|
188
186
|
return `${projectRoot}/.peaks/_runtime/${sessionId}/workflow-state/${rid}.json`;
|
|
189
187
|
}
|
|
190
188
|
/** Resolve the author of the skip. Reads `git config --global user.name`
|
|
191
|
-
* synchronously
|
|
192
|
-
*
|
|
189
|
+
* synchronously, falling back to the OS user and then 'unknown'. A value
|
|
190
|
+
* carrying a control character is not written (the reader would refuse it). */
|
|
193
191
|
function resolveSkipAppliedBy() {
|
|
194
192
|
try {
|
|
195
193
|
const out = execFileSync('git', ['config', '--global', 'user.name'], {
|
|
@@ -199,7 +197,7 @@ function resolveSkipAppliedBy() {
|
|
|
199
197
|
});
|
|
200
198
|
const trimmed = out.trim();
|
|
201
199
|
if (trimmed.length > 0) {
|
|
202
|
-
return trimmed;
|
|
200
|
+
return hasControlChars(trimmed) ? 'unknown' : trimmed;
|
|
203
201
|
}
|
|
204
202
|
}
|
|
205
203
|
catch {
|
|
@@ -208,7 +206,7 @@ function resolveSkipAppliedBy() {
|
|
|
208
206
|
}
|
|
209
207
|
try {
|
|
210
208
|
const info = userInfo();
|
|
211
|
-
return info.username;
|
|
209
|
+
return hasControlChars(info.username) ? 'unknown' : info.username;
|
|
212
210
|
}
|
|
213
211
|
catch {
|
|
214
212
|
return 'unknown';
|
|
@@ -6,10 +6,19 @@ export type WorkflowSkipState = {
|
|
|
6
6
|
skipAppliedBy: string;
|
|
7
7
|
callerKind: 'human' | 'llm' | 'script';
|
|
8
8
|
};
|
|
9
|
+
/** C0/C1 controls and DEL. A newline or escape in a printed field is a spoofed line. */
|
|
10
|
+
export declare function hasControlChars(value: string): boolean;
|
|
9
11
|
/**
|
|
10
12
|
* Read the skip-state for a rid, or `null` if no state file exists or
|
|
11
13
|
* the file is malformed. The caller is expected to treat `null` as
|
|
12
14
|
* "no skip applied; evaluate all gates normally".
|
|
15
|
+
*
|
|
16
|
+
* A NULL IS SILENCE, AND SILENCE MEANS "NO SKIP HONOURED". The shape check refuses
|
|
17
|
+
* a record the write path could not have produced — an empty reason, or no gate
|
|
18
|
+
* named — so a hand-planted file that satisfies field PRESENCE but not the write
|
|
19
|
+
* rules lands here as `null` and the gates are evaluated. That is the safe
|
|
20
|
+
* direction: the cost is a skip that stops applying, stated in the RD artifact,
|
|
21
|
+
* not a bypass that starts applying.
|
|
13
22
|
*/
|
|
14
23
|
export declare function readSkipState(projectRoot: string, sessionId: string, rid: string): WorkflowSkipState | null;
|
|
15
24
|
/**
|
|
@@ -21,6 +21,14 @@
|
|
|
21
21
|
import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
22
22
|
import { dirname, join } from 'node:path';
|
|
23
23
|
const STATE_FILE_NAME = 'workflow-state.json';
|
|
24
|
+
/** C0/C1 controls and DEL. A newline or escape in a printed field is a spoofed line. */
|
|
25
|
+
export function hasControlChars(value) {
|
|
26
|
+
for (const char of value) {
|
|
27
|
+
if (char < ' ' || char === '\u007f' || (char >= '\u0080' && char <= '\u009f'))
|
|
28
|
+
return true;
|
|
29
|
+
}
|
|
30
|
+
return false;
|
|
31
|
+
}
|
|
24
32
|
function stateFilePath(projectRoot, sessionId, rid) {
|
|
25
33
|
return join(projectRoot, '.peaks', '_runtime', sessionId, 'workflow-state', `${rid}.json`);
|
|
26
34
|
}
|
|
@@ -28,6 +36,13 @@ function stateFilePath(projectRoot, sessionId, rid) {
|
|
|
28
36
|
* Read the skip-state for a rid, or `null` if no state file exists or
|
|
29
37
|
* the file is malformed. The caller is expected to treat `null` as
|
|
30
38
|
* "no skip applied; evaluate all gates normally".
|
|
39
|
+
*
|
|
40
|
+
* A NULL IS SILENCE, AND SILENCE MEANS "NO SKIP HONOURED". The shape check refuses
|
|
41
|
+
* a record the write path could not have produced — an empty reason, or no gate
|
|
42
|
+
* named — so a hand-planted file that satisfies field PRESENCE but not the write
|
|
43
|
+
* rules lands here as `null` and the gates are evaluated. That is the safe
|
|
44
|
+
* direction: the cost is a skip that stops applying, stated in the RD artifact,
|
|
45
|
+
* not a bypass that starts applying.
|
|
31
46
|
*/
|
|
32
47
|
export function readSkipState(projectRoot, sessionId, rid) {
|
|
33
48
|
const path = stateFilePath(projectRoot, sessionId, rid);
|
|
@@ -81,14 +96,24 @@ function isWorkflowSkipState(value) {
|
|
|
81
96
|
return false;
|
|
82
97
|
if (!Array.isArray(v.skippedGates))
|
|
83
98
|
return false;
|
|
84
|
-
if (
|
|
99
|
+
if (v.skippedGates.length === 0)
|
|
100
|
+
return false;
|
|
101
|
+
if (!v.skippedGates.every((g) => typeof g === 'string' && g.trim().length > 0 && g === g.trim() && !hasControlChars(g)))
|
|
85
102
|
return false;
|
|
86
103
|
if (typeof v.skipReason !== 'string')
|
|
87
104
|
return false;
|
|
105
|
+
if (v.skipReason.trim().length === 0)
|
|
106
|
+
return false;
|
|
107
|
+
if (hasControlChars(v.skipReason))
|
|
108
|
+
return false;
|
|
88
109
|
if (typeof v.skipAppliedAt !== 'string')
|
|
89
110
|
return false;
|
|
111
|
+
if (hasControlChars(v.skipAppliedAt))
|
|
112
|
+
return false;
|
|
90
113
|
if (typeof v.skipAppliedBy !== 'string')
|
|
91
114
|
return false;
|
|
115
|
+
if (hasControlChars(v.skipAppliedBy))
|
|
116
|
+
return false;
|
|
92
117
|
if (v.callerKind !== 'human' && v.callerKind !== 'llm' && v.callerKind !== 'script')
|
|
93
118
|
return false;
|
|
94
119
|
return true;
|
|
@@ -2,10 +2,27 @@
|
|
|
2
2
|
* Utilities for generating incrementing numbered filenames.
|
|
3
3
|
* Used by session-based artifact storage to create files like 001-feature.md.
|
|
4
4
|
*/
|
|
5
|
+
/**
|
|
6
|
+
* The `<NNN>-` prefix family: EXACTLY three digits, anchored at the start. The one
|
|
7
|
+
* definition the counting side (`getNextNumber`), the writing side
|
|
8
|
+
* (`buildNumberedFilename`) and the stripping side (`requestIdFromFileName`) all
|
|
9
|
+
* read, so neither side can widen the family without the others.
|
|
10
|
+
*
|
|
11
|
+
* Three digits is what the writer pads to for every number it can hand out, and a
|
|
12
|
+
* WIDER pattern on the counting side is the whole defect this constant closes: with
|
|
13
|
+
* `^(\d+)-` the leading YEAR of a bare date-shaped name (`2026-10-15-<slug>`) reads
|
|
14
|
+
* as a file number. Four digits is out of family by construction — `\d{3}` is
|
|
15
|
+
* followed by `-`, and `2026-` has a digit there.
|
|
16
|
+
*/
|
|
17
|
+
export declare const NUMBERED_PREFIX_RE: RegExp;
|
|
5
18
|
/**
|
|
6
19
|
* Get the next available number in a directory.
|
|
7
|
-
* Scans existing .md files and finds the highest numeric prefix.
|
|
8
|
-
* Returns 1 if directory is empty or
|
|
20
|
+
* Scans existing .md files and finds the highest IN-FAMILY numeric prefix.
|
|
21
|
+
* Returns 1 if the directory is empty, missing, or holds no in-family name.
|
|
22
|
+
*
|
|
23
|
+
* A name whose leading digits are not a whole prefix in the family — a bare
|
|
24
|
+
* date-shaped name, whose leading digits are a year — is ignored rather than
|
|
25
|
+
* counted, so it can never move the answer.
|
|
9
26
|
*
|
|
10
27
|
* @param dirPath - Directory to scan for numbered files
|
|
11
28
|
* @returns Next available number (1, 2, 3, ...)
|
|
@@ -27,6 +44,10 @@ export declare function buildNumberedFilename(number: number, description: strin
|
|
|
27
44
|
* markdown artifact at all. The READ side of `buildNumberedFilename`, in the same
|
|
28
45
|
* module, so writer and reader cannot drift apart from each other.
|
|
29
46
|
*
|
|
47
|
+
* The prefix it strips is `NUMBERED_PREFIX_RE` — the same family `getNextNumber`
|
|
48
|
+
* counts — so a name the writer produced always reads back as the id it was given.
|
|
49
|
+
* A bare date-shaped stem carries no in-family prefix and is returned verbatim.
|
|
50
|
+
*
|
|
30
51
|
* The returned stem is not yet checked against the id pattern the artifact service
|
|
31
52
|
* owns; a caller that needs a legal request id applies that there rather than the
|
|
32
53
|
* pattern being imported here.
|
|
@@ -4,10 +4,27 @@
|
|
|
4
4
|
*/
|
|
5
5
|
import { existsSync, readdirSync } from 'node:fs';
|
|
6
6
|
import { join } from 'node:path';
|
|
7
|
+
/**
|
|
8
|
+
* The `<NNN>-` prefix family: EXACTLY three digits, anchored at the start. The one
|
|
9
|
+
* definition the counting side (`getNextNumber`), the writing side
|
|
10
|
+
* (`buildNumberedFilename`) and the stripping side (`requestIdFromFileName`) all
|
|
11
|
+
* read, so neither side can widen the family without the others.
|
|
12
|
+
*
|
|
13
|
+
* Three digits is what the writer pads to for every number it can hand out, and a
|
|
14
|
+
* WIDER pattern on the counting side is the whole defect this constant closes: with
|
|
15
|
+
* `^(\d+)-` the leading YEAR of a bare date-shaped name (`2026-10-15-<slug>`) reads
|
|
16
|
+
* as a file number. Four digits is out of family by construction — `\d{3}` is
|
|
17
|
+
* followed by `-`, and `2026-` has a digit there.
|
|
18
|
+
*/
|
|
19
|
+
export const NUMBERED_PREFIX_RE = /^(\d{3})-/;
|
|
7
20
|
/**
|
|
8
21
|
* Get the next available number in a directory.
|
|
9
|
-
* Scans existing .md files and finds the highest numeric prefix.
|
|
10
|
-
* Returns 1 if directory is empty or
|
|
22
|
+
* Scans existing .md files and finds the highest IN-FAMILY numeric prefix.
|
|
23
|
+
* Returns 1 if the directory is empty, missing, or holds no in-family name.
|
|
24
|
+
*
|
|
25
|
+
* A name whose leading digits are not a whole prefix in the family — a bare
|
|
26
|
+
* date-shaped name, whose leading digits are a year — is ignored rather than
|
|
27
|
+
* counted, so it can never move the answer.
|
|
11
28
|
*
|
|
12
29
|
* @param dirPath - Directory to scan for numbered files
|
|
13
30
|
* @returns Next available number (1, 2, 3, ...)
|
|
@@ -20,7 +37,7 @@ export function getNextNumber(dirPath) {
|
|
|
20
37
|
return 1;
|
|
21
38
|
const numbers = files
|
|
22
39
|
.map((f) => {
|
|
23
|
-
const match =
|
|
40
|
+
const match = NUMBERED_PREFIX_RE.exec(f);
|
|
24
41
|
return match && match[1] ? parseInt(match[1], 10) : NaN;
|
|
25
42
|
})
|
|
26
43
|
.filter((n) => !isNaN(n));
|
|
@@ -35,17 +52,29 @@ export function getNextNumber(dirPath) {
|
|
|
35
52
|
* @returns Formatted filename like "001-feature-name.md"
|
|
36
53
|
*/
|
|
37
54
|
/**
|
|
38
|
-
* The `<NNN>` prefix in a numbered filename is COSMETIC
|
|
39
|
-
* the
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
* number
|
|
45
|
-
* and
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
55
|
+
* The `<NNN>` prefix in a numbered filename is COSMETIC — but that is a claim about
|
|
56
|
+
* the NUMBER, not about the prefix's WIDTH. The width is `NUMBERED_PREFIX_RE`:
|
|
57
|
+
* exactly three digits, the one family the counting, writing and stripping sides all
|
|
58
|
+
* read. `getNextNumber` scans the directory's highest in-family prefix and adds one,
|
|
59
|
+
* and nothing claims a number in between — so two writers running at once can both
|
|
60
|
+
* read the same maximum and both stamp the same number. That is harmless only
|
|
61
|
+
* because the number is not an identity: what names an artifact is the slug (the
|
|
62
|
+
* request id), and every reader strips a prefix in the family. Measured 2026-10-12:
|
|
63
|
+
* the sole consumers of the number are this module's writer path (`getNextNumber` ->
|
|
64
|
+
* `buildNumberedFilename`) and the read side (`requestIdFromFileName`, which
|
|
65
|
+
* discards it); the artifact service's duplicate check and lookup both key on the
|
|
66
|
+
* slug. Read that as a constraint: give the number a meaning and you must claim it
|
|
67
|
+
* atomically first, rather than assume this scan hands out unique values.
|
|
68
|
+
*
|
|
69
|
+
* WHY THE FAMILY IS STATED RATHER THAN ASSUMED — the defect this replaced. The
|
|
70
|
+
* counting side once matched `^(\d+)-` while the stripping side knew only `^0\d{2}-`.
|
|
71
|
+
* Two patterns on one naming rule disagree from the day they are written, and a
|
|
72
|
+
* directory of nothing but bare date-shaped names is where it showed: the count
|
|
73
|
+
* answered 2027 (the year 2026, plus one), the writer stamped `2027-` onto a fresh
|
|
74
|
+
* artifact, and the stripping side handed back an id carrying a prefix the state
|
|
75
|
+
* machine had never been given. A four-digit prefix is out of family, so
|
|
76
|
+
* `buildNumberedFilename` refuses to write one instead of letting the writer walk
|
|
77
|
+
* past the reader.
|
|
49
78
|
*/
|
|
50
79
|
// Windows supports up to 255 chars per filename component (and 260 for the
|
|
51
80
|
// full path). Pre-#015 the slug was silently truncated to 50 chars, which
|
|
@@ -75,6 +104,15 @@ export function slugifyDescription(description) {
|
|
|
75
104
|
}
|
|
76
105
|
export function buildNumberedFilename(number, description) {
|
|
77
106
|
const padded = String(number).padStart(3, '0');
|
|
107
|
+
// The writer is held to the reader's own family. A number with no three-digit
|
|
108
|
+
// spelling (1000 and up) would produce a prefix `requestIdFromFileName` does not
|
|
109
|
+
// strip, and the artifact's id would then disagree with the id it was given —
|
|
110
|
+
// the counting/stripping disagreement on a second axis. Refuse rather than widen
|
|
111
|
+
// the reader: a four-digit prefix on a filename is a year to every reader.
|
|
112
|
+
if (!NUMBERED_PREFIX_RE.test(`${padded}-`)) {
|
|
113
|
+
throw new Error(`Cannot number a file ${number}: the prefix family is exactly three digits, and ${padded}- is ` +
|
|
114
|
+
'outside it. A directory that has filled the family needs a second directory, not a fourth digit.');
|
|
115
|
+
}
|
|
78
116
|
const slug = slugifyDescription(description);
|
|
79
117
|
return `${padded}-${slug}.md`;
|
|
80
118
|
}
|
|
@@ -83,6 +121,10 @@ export function buildNumberedFilename(number, description) {
|
|
|
83
121
|
* markdown artifact at all. The READ side of `buildNumberedFilename`, in the same
|
|
84
122
|
* module, so writer and reader cannot drift apart from each other.
|
|
85
123
|
*
|
|
124
|
+
* The prefix it strips is `NUMBERED_PREFIX_RE` — the same family `getNextNumber`
|
|
125
|
+
* counts — so a name the writer produced always reads back as the id it was given.
|
|
126
|
+
* A bare date-shaped stem carries no in-family prefix and is returned verbatim.
|
|
127
|
+
*
|
|
86
128
|
* The returned stem is not yet checked against the id pattern the artifact service
|
|
87
129
|
* owns; a caller that needs a legal request id applies that there rather than the
|
|
88
130
|
* pattern being imported here.
|
|
@@ -90,7 +132,7 @@ export function buildNumberedFilename(number, description) {
|
|
|
90
132
|
export function requestIdFromFileName(fileName) {
|
|
91
133
|
if (!fileName.endsWith('.md'))
|
|
92
134
|
return null;
|
|
93
|
-
return fileName.replace(
|
|
135
|
+
return fileName.replace(NUMBERED_PREFIX_RE, '').replace(/\.md$/, '');
|
|
94
136
|
}
|
|
95
137
|
/**
|
|
96
138
|
* Get the next numbered file path in a directory.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "peaks-loop",
|
|
3
|
-
"version": "4.1.
|
|
3
|
+
"version": "4.1.6",
|
|
4
4
|
"description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
|
|
5
5
|
"author": "SquabbyZ",
|
|
6
6
|
"keywords": [
|
|
@@ -129,10 +129,10 @@
|
|
|
129
129
|
"picomatch": "4.0.4",
|
|
130
130
|
"yaml": "^2.9.0",
|
|
131
131
|
"zod": "^4.4.3",
|
|
132
|
-
"peaks-loop-internal-runtime": "0.0.
|
|
133
|
-
"peaks-loop-
|
|
134
|
-
"peaks-loop-
|
|
135
|
-
"peaks-loop-shared": "0.0.
|
|
132
|
+
"peaks-loop-internal-runtime": "0.0.46",
|
|
133
|
+
"peaks-loop-mut": "0.1.60",
|
|
134
|
+
"peaks-loop-shared": "0.0.95",
|
|
135
|
+
"peaks-loop-shared-channel": "0.0.63"
|
|
136
136
|
},
|
|
137
137
|
"devDependencies": {
|
|
138
138
|
"@changesets/cli": "2.31.1",
|
|
@@ -185,8 +185,6 @@
|
|
|
185
185
|
"test:race": "vitest run --no-file-parallelism packages/peaks-loop-shared-channel/tests/shared-channel.test.ts tests/unit/services/dispatch/dispatch-record-writer.test.ts",
|
|
186
186
|
"test:replay": "node scripts/fixture-capture-setup.mjs && vitest run tests/unit/services/dispatch/conflict-replay.test.ts tests/unit/services/dispatch/e2e-fixtures.test.ts",
|
|
187
187
|
"fixture:capture-setup": "node scripts/fixture-capture-setup.mjs",
|
|
188
|
-
"test:coverage": "node ./scripts/coverage-c8.mjs",
|
|
189
|
-
"test:coverage:c8": "node ./scripts/coverage-c8.mjs",
|
|
190
188
|
"test:coverage:vitest": "vitest run --coverage",
|
|
191
189
|
"test:coverage:workflow": "vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",
|
|
192
190
|
"schema:generate": "node scripts/generate-context-schema.mjs",
|
|
@@ -383,8 +383,9 @@ scan BEFORE transitioning to Step 3 RD.
|
|
|
383
383
|
|
|
384
384
|
**Handoff contract:**
|
|
385
385
|
- Input: `businessGoal` (natural language) + `.peaks/project-scan/project-scan.md` (auto-generated by `peaks workspace init`)
|
|
386
|
-
-
|
|
387
|
-
-
|
|
386
|
+
- Lookup (LLM-side, and required for a real scan): query Context7 priority-1 → WebSearch priority-2 with your own tools, then write the results to `.peaks/_runtime/<sessionId>/best-practice/lookup-results.json` as `{ "intent": "<businessGoal>", "context7": { "ok", "results": [{ "title", "url", "snippet" }] }, "websearch": { … } }`. A lookup that returned nothing is `"ok": false, "results": []`, and **if every seam you supply returns nothing the scan refuses with `BEST_PRACTICE_SCAN_NO_FRAGMENTS` and writes no artifact** — zero fragments never renders. Each fragment carries `title`/`url`/`snippet` and no other key, and the `url` is one you construct: Context7 returns no URL, only a library ID.
|
|
387
|
+
- Output: best-practice scan artifact at `<repo>/best-practice/<date>-<slug>.md` (gitignored; `<slug>` is a 32-char slice of the goal). A refusal never overwrites it — it is recorded beside it at `<repo>/best-practice/skipped/<date>-<slug>.md`, so a real recommendation survives the auto-triggered scan that shares its intent.
|
|
388
|
+
- Trigger CLI: `peaks best-practice-scan --project <repo> --intent "<businessGoal>" --lookup-results .peaks/_runtime/<sessionId>/best-practice/lookup-results.json --json`
|
|
388
389
|
- Status: `awaiting-user-ack` (3 valid user responses per spec §7: 接受 / 接受方案 N / 拒绝 + 原因)
|
|
389
390
|
|
|
390
391
|
**State machine:** peak-prd's state machine refuses `--allow-incomplete` style bypass for
|