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.
Files changed (86) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +36 -0
  3. package/README-en.md +47 -183
  4. package/README.md +24 -188
  5. package/dist/cli/commands/best-practice-scan-command.d.ts +11 -6
  6. package/dist/cli/commands/best-practice-scan-command.js +35 -20
  7. package/dist/cli/commands/best-practice-scan-helpers.d.ts +47 -0
  8. package/dist/cli/commands/best-practice-scan-helpers.js +88 -5
  9. package/dist/cli/commands/best-practice-scan-lookup-results.d.ts +13 -0
  10. package/dist/cli/commands/best-practice-scan-lookup-results.js +237 -0
  11. package/dist/cli/commands/dispatch-command-spec.js +1 -1
  12. package/dist/cli/commands/dispatch-isolation-lease.d.ts +1 -1
  13. package/dist/cli/commands/dispatch-isolation-lease.js +6 -53
  14. package/dist/cli/commands/dispatch-prompt-blocks.d.ts +1 -1
  15. package/dist/cli/commands/dispatch-prompt-composition.d.ts +1 -1
  16. package/dist/cli/commands/dispatch-record-write.d.ts +1 -1
  17. package/dist/cli/commands/dispatch-tool-call.d.ts +1 -1
  18. package/dist/cli/commands/openspec-command-shared.js +2 -2
  19. package/dist/cli/commands/request-transition-failures.js +31 -4
  20. package/dist/cli/commands/request-transition-preflight.js +1 -1
  21. package/dist/cli/commands/slice-decompose-artifacts.js +2 -1
  22. package/dist/cli/commands/verdict-aggregate-command.js +2 -1
  23. package/dist/cli/commands/workflow-gate-commands.js +4 -4
  24. package/dist/cli/program.js +0 -2
  25. package/dist/services/artifacts/artifact-contract-block.js +21 -2
  26. package/dist/services/artifacts/artifact-prerequisites.js +7 -7
  27. package/dist/services/artifacts/rd-transition-gates.d.ts +33 -0
  28. package/dist/services/artifacts/rd-transition-gates.js +71 -0
  29. package/dist/services/artifacts/request-artifact-service.js +22 -20
  30. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +9 -1
  31. package/dist/services/artifacts/request-artifact-state-helpers.js +6 -4
  32. package/dist/services/audit-independent/judged-declaration-check.d.ts +1 -0
  33. package/dist/services/audit-independent/judged-declaration-check.js +62 -1
  34. package/dist/services/context/build-dispatch-system-prompt.d.ts +5 -9
  35. package/dist/services/context/build-dispatch-system-prompt.js +11 -11
  36. package/dist/services/context/post-compact-reinjection.js +1 -1
  37. package/dist/services/dispatch/test-tool-detection.d.ts +17 -1
  38. package/dist/services/dispatch/test-tool-detection.js +12 -1
  39. package/dist/services/evidence/evidence-generator.js +8 -4
  40. package/dist/services/openspec/coverage-evidence-reader.d.ts +9 -9
  41. package/dist/services/openspec/coverage-evidence-reader.js +8 -8
  42. package/dist/services/openspec/openspec-archive-service.d.ts +1 -1
  43. package/dist/services/openspec/openspec-archive-service.js +6 -6
  44. package/dist/services/scan/file-size-baseline.d.ts +13 -6
  45. package/dist/services/scan/file-size-baseline.js +54 -31
  46. package/dist/services/scan/file-size-scan.d.ts +7 -14
  47. package/dist/services/scan/file-size-scan.js +6 -1
  48. package/dist/services/scan/type-corroboration.d.ts +32 -0
  49. package/dist/services/scan/type-corroboration.js +51 -0
  50. package/dist/services/scan/type-sanity-service.d.ts +14 -0
  51. package/dist/services/scan/type-sanity-service.js +10 -19
  52. package/dist/services/security/safe-settings-path.d.ts +5 -0
  53. package/dist/services/security/safe-settings-path.js +64 -8
  54. package/dist/services/skill/resume-detector.js +8 -8
  55. package/dist/services/workflow/pipeline-verify-gate-support.d.ts +24 -8
  56. package/dist/services/workflow/pipeline-verify-gate-support.js +32 -38
  57. package/dist/services/workflow/pipeline-verify-qa-phase.d.ts +102 -0
  58. package/dist/services/workflow/pipeline-verify-qa-phase.js +176 -0
  59. package/dist/services/workflow/pipeline-verify-service.js +26 -27
  60. package/dist/services/workflow/request-type-resolution.d.ts +99 -0
  61. package/dist/services/workflow/request-type-resolution.js +130 -0
  62. package/dist/services/workflow/workflow-skip-service.d.ts +1 -0
  63. package/dist/services/workflow/workflow-skip-service.js +19 -21
  64. package/dist/services/workflow/workflow-state-store.d.ts +9 -0
  65. package/dist/services/workflow/workflow-state-store.js +26 -1
  66. package/dist/shared/incrementing-number.d.ts +23 -2
  67. package/dist/shared/incrementing-number.js +57 -15
  68. package/package.json +5 -7
  69. package/skills/bee/peaks-prd/SKILL.md +3 -2
  70. package/skills/peaks-code/SKILL.md +32 -15
  71. package/dist/cli/commands/vm-command-shared.d.ts +0 -23
  72. package/dist/cli/commands/vm-command-shared.js +0 -23
  73. package/dist/cli/commands/vm-commands.d.ts +0 -3
  74. package/dist/cli/commands/vm-commands.js +0 -45
  75. package/dist/cli/commands/vm-hypervisor-probe.d.ts +0 -27
  76. package/dist/cli/commands/vm-hypervisor-probe.js +0 -78
  77. package/dist/cli/commands/vm-hypervisor-runtime.d.ts +0 -15
  78. package/dist/cli/commands/vm-hypervisor-runtime.js +0 -64
  79. package/dist/cli/commands/vm-release-command.d.ts +0 -5
  80. package/dist/cli/commands/vm-release-command.js +0 -101
  81. package/dist/cli/commands/vm-spawn-command.d.ts +0 -5
  82. package/dist/cli/commands/vm-spawn-command.js +0 -177
  83. package/dist/cli/commands/vm-status-command.d.ts +0 -3
  84. package/dist/cli/commands/vm-status-command.js +0 -50
  85. package/dist/services/vm/vm-lease.d.ts +0 -40
  86. package/dist/services/vm/vm-lease.js +0 -160
@@ -10,14 +10,11 @@ import { type ArtifactPrerequisite, type RequestType } from '../artifacts/artifa
10
10
  import type { RequestArtifactRole, RequestArtifactState } from '../artifacts/request-artifact-service.js';
11
11
  import type { PipelineGate } from './pipeline-verify-types.js';
12
12
  export declare function extractState(markdown: string): string;
13
- /**
14
- * scope is the change-id (the `.peaks/_runtime/<sessionId>/` dir the file lives
15
- * in), NOT the session-id. We resolve the on-disk location via
16
- * `showRequestArtifact` (which scans all top-level dirs and returns the
17
- * actual dir the file was found in) instead of assuming
18
- * `.peaks/_runtime/<sessionId>/<role>/requests/`.
19
- */
20
- export declare function findRequestFile(projectRoot: string, role: string, rid: string): Promise<{
13
+ /** The rid's artifact file, read from ONE session: `sessionId` is required, and
14
+ * `null` — no resolvable scope — means NO CARRIER, never a scan (that branch
15
+ * reads every directory under `.peaks/_runtime/` and takes the first name that
16
+ * sorts). The dir the file was FOUND in comes back as `sessionId`. */
17
+ export declare function findRequestFile(projectRoot: string, role: string, rid: string, sessionId: string | null): Promise<{
21
18
  path: string;
22
19
  content: string;
23
20
  sessionId: string;
@@ -54,6 +51,25 @@ export declare function findRequestFile(projectRoot: string, role: string, rid:
54
51
  export declare function contractPrerequisite(role: RequestArtifactRole, state: RequestArtifactState, requestType: RequestType, probeName: string): ArtifactPrerequisite | null;
55
52
  export declare function contractEvidencePaths(role: RequestArtifactRole, state: RequestArtifactState, requestType: RequestType, probeName: string): string[] | null;
56
53
  export declare function rdGatesForType(requestType: RequestType): PipelineGate[];
54
+ /**
55
+ * The QA phase's gate list for one type.
56
+ *
57
+ * Both halves are read off the type's own table. WHICH EVIDENCE the phase owes is
58
+ * the type's `qa:` row, resolved through the same contract accessor
59
+ * `rdGatesForType` uses — a row the contract carries builds its gate, a row it
60
+ * does not carry builds none. WHETHER the phase exists at all is
61
+ * `typeRequiresQaPhase`, the same call the checker makes, which is the part that
62
+ * used to be a list of three request types named here. The derivation and the
63
+ * arming that keeps it total are `pipeline-verify-qa-phase.ts`.
64
+ *
65
+ * Two of the six types are why this reads the table instead of naming its
66
+ * members. The minimal table — docs and chore — carries no `qa:` row, so those
67
+ * types owe no QA evidence and get an empty list; that is how both the checker
68
+ * and the commit-time carrier learn there is no phase to report. Config carries
69
+ * exactly one QA row instead: a test report, and no test cases. The member list
70
+ * was wrong about both, in opposite directions: one type was asked for a phase it
71
+ * does not owe, and the other never for the evidence its transition requires.
72
+ */
57
73
  export declare function qaGatesForType(requestType: RequestType): PipelineGate[];
58
74
  export declare const RD_QA_HANDOFF_STATES: Set<string>;
59
75
  export declare const QA_COMPLETE_STATES: Set<string>;
@@ -9,24 +9,25 @@
9
9
  import { existsSync, readFileSync } from 'node:fs';
10
10
  import { join } from 'node:path';
11
11
  import { getPrerequisitesFor } from '../artifacts/artifact-prerequisites.js';
12
+ import * as qaPhase from './pipeline-verify-qa-phase.js';
12
13
  import { prerequisiteBodyViolations } from '../artifacts/prerequisite-checks.js';
13
14
  import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
14
15
  import { readArtifactState } from '../artifacts/request-artifact-state-helpers.js';
15
16
  export function extractState(markdown) {
16
17
  return readArtifactState(markdown) ?? 'unknown';
17
18
  }
18
- /**
19
- * scope is the change-id (the `.peaks/_runtime/<sessionId>/` dir the file lives
20
- * in), NOT the session-id. We resolve the on-disk location via
21
- * `showRequestArtifact` (which scans all top-level dirs and returns the
22
- * actual dir the file was found in) instead of assuming
23
- * `.peaks/_runtime/<sessionId>/<role>/requests/`.
24
- */
25
- export async function findRequestFile(projectRoot, role, rid) {
19
+ /** The rid's artifact file, read from ONE session: `sessionId` is required, and
20
+ * `null` — no resolvable scope — means NO CARRIER, never a scan (that branch
21
+ * reads every directory under `.peaks/_runtime/` and takes the first name that
22
+ * sorts). The dir the file was FOUND in comes back as `sessionId`. */
23
+ export async function findRequestFile(projectRoot, role, rid, sessionId) {
24
+ if (sessionId === null)
25
+ return null;
26
26
  const artifact = await showRequestArtifact({
27
27
  projectRoot,
28
28
  role: role,
29
- requestId: rid
29
+ requestId: rid,
30
+ sessionId
30
31
  });
31
32
  if (artifact === null)
32
33
  return null;
@@ -177,32 +178,27 @@ export function rdGatesForType(requestType) {
177
178
  }
178
179
  return gates;
179
180
  }
181
+ /**
182
+ * The QA phase's gate list for one type.
183
+ *
184
+ * Both halves are read off the type's own table. WHICH EVIDENCE the phase owes is
185
+ * the type's `qa:` row, resolved through the same contract accessor
186
+ * `rdGatesForType` uses — a row the contract carries builds its gate, a row it
187
+ * does not carry builds none. WHETHER the phase exists at all is
188
+ * `typeRequiresQaPhase`, the same call the checker makes, which is the part that
189
+ * used to be a list of three request types named here. The derivation and the
190
+ * arming that keeps it total are `pipeline-verify-qa-phase.ts`.
191
+ *
192
+ * Two of the six types are why this reads the table instead of naming its
193
+ * members. The minimal table — docs and chore — carries no `qa:` row, so those
194
+ * types owe no QA evidence and get an empty list; that is how both the checker
195
+ * and the commit-time carrier learn there is no phase to report. Config carries
196
+ * exactly one QA row instead: a test report, and no test cases. The member list
197
+ * was wrong about both, in opposite directions: one type was asked for a phase it
198
+ * does not owe, and the other never for the evidence its transition requires.
199
+ */
180
200
  export function qaGatesForType(requestType) {
181
- const gates = [
182
- {
183
- name: 'qa-request-exists',
184
- description: 'QA request artifact created',
185
- passed: false,
186
- detail: ''
187
- }
188
- ];
189
- if (requestType === 'feature' || requestType === 'refactor' || requestType === 'bugfix') {
190
- gates.push({ name: 'test-cases', description: 'QA test cases', passed: false, detail: '' });
191
- gates.push({
192
- name: 'test-report',
193
- description: 'QA test report with execution results',
194
- passed: false,
195
- detail: ''
196
- });
197
- }
198
- // The `security-findings` / `performance-findings` gates were removed here
199
- // security review or performance review — `peaks-qa/SKILL.md` says so, and
200
- // the v2.11.0 D1/D4 trim dropped both from every `qa:verdict-issued` table.
201
- // The evidence they used to demand is now checked on the RD side, at the
202
- // paths the contract actually names (`audit/security-<rid>.md`,
203
- // `audit/perf.md` and `rd/security-review.md` / `rd/perf-baseline.md` as the
204
- // declared legacy tiers behind them).
205
- return gates;
201
+ return qaPhase.qaPhaseGates(qaPhase.typeRequiresQaPhase(requestType), qaPhase.QA_EVIDENCE_GATES.filter((gate) => qaPhase.QA_STATES.some((state) => contractEvidencePaths('qa', state, requestType, gate.relativePath) !== null)));
206
202
  }
207
203
  export const RD_QA_HANDOFF_STATES = new Set(['qa-handoff', 'handed-off', 'implemented']);
208
204
  export const QA_COMPLETE_STATES = new Set(['verdict-issued']);
@@ -293,10 +289,8 @@ export function resolveRdEvidencePaths(gates, rdEvidenceDir, projectRoot, rid, r
293
289
  * at the contract's own paths (`audit/security-<rid>.md`,
294
290
  * `audit/perf-<rid>.md`). */
295
291
  export function resolveQaEvidencePaths(gates, projectRoot, rdEvidenceDir, requestType, rid, violations, nextActions, tracker) {
296
- const QA_EVIDENCE_PROBE = {
297
- 'test-cases': 'qa/test-cases/<rid>.md',
298
- 'test-report': 'qa/test-reports/<rid>.md'
299
- };
292
+ // Derived from the declared gates — a restatement could resolve a renamed path.
293
+ const QA_EVIDENCE_PROBE = Object.fromEntries(qaPhase.QA_EVIDENCE_GATES.map((gate) => [gate.name, gate.relativePath]));
300
294
  let anyEvidenceResolved = tracker.anyEvidenceResolved;
301
295
  let allResolvedPathsCanonical = tracker.allResolvedPathsCanonical;
302
296
  for (const gate of gates.slice(1)) {
@@ -0,0 +1,102 @@
1
+ /**
2
+ * peaks-workflow — the QA phase, derived from the type tables.
3
+ *
4
+ * WHY THIS IS A MODULE OF ITS OWN. A measured budget, not taste: the file-size
5
+ * census records the gated excess by EQUALITY, and `pipeline-verify-gate-support`
6
+ * already carries its share of that sum. A file under its cap adds nothing to it,
7
+ * so the reasoning below — which a contributor has to be able to find — is paid
8
+ * for here, at zero census cost.
9
+ *
10
+ * WHY A DERIVATION AT ALL. Two layers answered one question — *does this request
11
+ * need a QA phase?* — and gave different answers, because neither read the answer
12
+ * off the type tables that define the contract. One named three request types;
13
+ * the other asked unconditionally. A request whose table carries no QA row at all
14
+ * therefore satisfied every prerequisite its own contract lists and was then
15
+ * refused at commit time for a phase that contract never asked for.
16
+ *
17
+ * The tables are the authority. `MINIMAL_TABLE` carries no `qa:` row, which is
18
+ * what "these types have no QA phase" has always meant, and what
19
+ * `request transition --role qa --state verdict-issued` has always enforced
20
+ * against the same table.
21
+ *
22
+ * WHY IT IS ARMED. A derivation nobody checks is a restatement with better
23
+ * manners. A table row can name a QA artifact no gate stands for, and that row
24
+ * would then build no gate and say nothing about it — the same drift, one layer
25
+ * down. So the declared gate list is reconciled against every type's QA rows once
26
+ * per process, and a mismatch THROWS. The cost is deliberate and wider than it
27
+ * looks: the CLI registers every command eagerly, so an unrepresentable row does
28
+ * not merely fail `verify-pipeline` — it fails EVERY `peaks` invocation that
29
+ * reaches this module, the commit leg and `workflow verdict-aggregate` included.
30
+ * That is the fail-closed
31
+ * direction, and naming the row keeps the repair one line.
32
+ */
33
+ import { type RequestType } from '../artifacts/artifact-prerequisites.js';
34
+ import type { PipelineGate } from './pipeline-verify-types.js';
35
+ /**
36
+ * Every state the QA role can be in, taken from the repository's own state model
37
+ * rather than restated here.
38
+ *
39
+ * WHY IT IS NOT JUST `verdict-issued`. The terminal state is the one the phase's
40
+ * evidence is resolved at, so an earlier version keyed both the derivation and the
41
+ * reconciliation to it alone — which left the `qa:running` row a feature's table
42
+ * already carries outside the arming. A row at any other state would have been
43
+ * silently unrepresentable. The arming is total over the state axis instead.
44
+ */
45
+ export declare const QA_STATES: readonly import("../artifacts/request-artifact-state-helpers.js").RequestArtifactState[];
46
+ /**
47
+ * Every QA evidence gate the checker can build, each naming the contract path it
48
+ * stands for. The NAME is the checker's own — `peaks workflow skip` takes gate
49
+ * names and the violation text prints the description — while the PATH is the
50
+ * contract's, and it is the half that makes a gate list derivable instead of
51
+ * restated beside the tables it is supposed to be read from.
52
+ */
53
+ export declare const QA_EVIDENCE_GATES: ReadonlyArray<{
54
+ name: string;
55
+ description: string;
56
+ relativePath: string;
57
+ }>;
58
+ /**
59
+ * Does this type's table carry a QA phase?
60
+ *
61
+ * One derivation, so the gate list and the checker's verdict cannot disagree: the
62
+ * phase exists for a type exactly when its table carries a QA prerequisite —
63
+ * counted across every QA state, so a type whose only QA row sits at a
64
+ * non-terminal state is not read as having no phase at all.
65
+ */
66
+ export declare function typeRequiresQaPhase(requestType: RequestType): boolean;
67
+ /**
68
+ * The request types whose table carries NO QA phase — the set a skip may cover.
69
+ *
70
+ * DERIVED, not listed. The skip allowlist used to spell `['docs', 'config', 'chore']`,
71
+ * and `config` carries a QA phase (its table demands `SECURITY_REVIEW` and
72
+ * `TEST_REPORT`), so a plantable record could bypass a phase the contract requires.
73
+ * Reading the answer off the same derivation the pipeline uses means a table change
74
+ * moves the allowlist with it — in both directions, without anyone remembering.
75
+ */
76
+ export declare const QA_FREE_TYPES: ReadonlyArray<RequestType>;
77
+ /**
78
+ * Fill in the QA request gate for a phase that HAS one.
79
+ *
80
+ * A type whose table carries no QA row has no QA gate to fill, and that is not a
81
+ * special case to handle at the call site: the artifact is still honoured — its
82
+ * state and its location are read either way — so a tree that ran QA for a type
83
+ * whose table does not demand it keeps passing.
84
+ */
85
+ export declare function markQaRequestGate(gates: PipelineGate[], artifactPath: string): void;
86
+ /**
87
+ * The QA phase's gate list for one type: the phase gate when the phase exists,
88
+ * then one gate per piece of evidence the caller resolved from the contract. An
89
+ * empty list IS the answer for a type with no QA phase.
90
+ *
91
+ * The `security-findings` / `performance-findings` gates were removed here
92
+ * security review or performance review — `peaks-qa/SKILL.md` says so, and the
93
+ * v2.11.0 D1/D4 trim dropped both from every `qa:verdict-issued` table. The
94
+ * evidence they used to demand is now checked on the RD side, at the paths the
95
+ * contract actually names (`audit/security-<rid>.md`, `audit/perf.md` and
96
+ * `rd/security-review.md` / `rd/perf-baseline.md` as the declared legacy tiers
97
+ * behind them).
98
+ */
99
+ export declare function qaPhaseGates(required: boolean, evidence: ReadonlyArray<{
100
+ name: string;
101
+ description: string;
102
+ }>): PipelineGate[];
@@ -0,0 +1,176 @@
1
+ /**
2
+ * peaks-workflow — the QA phase, derived from the type tables.
3
+ *
4
+ * WHY THIS IS A MODULE OF ITS OWN. A measured budget, not taste: the file-size
5
+ * census records the gated excess by EQUALITY, and `pipeline-verify-gate-support`
6
+ * already carries its share of that sum. A file under its cap adds nothing to it,
7
+ * so the reasoning below — which a contributor has to be able to find — is paid
8
+ * for here, at zero census cost.
9
+ *
10
+ * WHY A DERIVATION AT ALL. Two layers answered one question — *does this request
11
+ * need a QA phase?* — and gave different answers, because neither read the answer
12
+ * off the type tables that define the contract. One named three request types;
13
+ * the other asked unconditionally. A request whose table carries no QA row at all
14
+ * therefore satisfied every prerequisite its own contract lists and was then
15
+ * refused at commit time for a phase that contract never asked for.
16
+ *
17
+ * The tables are the authority. `MINIMAL_TABLE` carries no `qa:` row, which is
18
+ * what "these types have no QA phase" has always meant, and what
19
+ * `request transition --role qa --state verdict-issued` has always enforced
20
+ * against the same table.
21
+ *
22
+ * WHY IT IS ARMED. A derivation nobody checks is a restatement with better
23
+ * manners. A table row can name a QA artifact no gate stands for, and that row
24
+ * would then build no gate and say nothing about it — the same drift, one layer
25
+ * down. So the declared gate list is reconciled against every type's QA rows once
26
+ * per process, and a mismatch THROWS. The cost is deliberate and wider than it
27
+ * looks: the CLI registers every command eagerly, so an unrepresentable row does
28
+ * not merely fail `verify-pipeline` — it fails EVERY `peaks` invocation that
29
+ * reaches this module, the commit leg and `workflow verdict-aggregate` included.
30
+ * That is the fail-closed
31
+ * direction, and naming the row keeps the repair one line.
32
+ */
33
+ import { getPrerequisitesFor, VALID_REQUEST_TYPES } from '../artifacts/artifact-prerequisites.js';
34
+ import { allowedStatesForRole } from '../artifacts/request-artifact-state-helpers.js';
35
+ /**
36
+ * Every state the QA role can be in, taken from the repository's own state model
37
+ * rather than restated here.
38
+ *
39
+ * WHY IT IS NOT JUST `verdict-issued`. The terminal state is the one the phase's
40
+ * evidence is resolved at, so an earlier version keyed both the derivation and the
41
+ * reconciliation to it alone — which left the `qa:running` row a feature's table
42
+ * already carries outside the arming. A row at any other state would have been
43
+ * silently unrepresentable. The arming is total over the state axis instead.
44
+ */
45
+ export const QA_STATES = allowedStatesForRole('qa');
46
+ /**
47
+ * Every QA evidence gate the checker can build, each naming the contract path it
48
+ * stands for. The NAME is the checker's own — `peaks workflow skip` takes gate
49
+ * names and the violation text prints the description — while the PATH is the
50
+ * contract's, and it is the half that makes a gate list derivable instead of
51
+ * restated beside the tables it is supposed to be read from.
52
+ */
53
+ export const QA_EVIDENCE_GATES = [
54
+ { name: 'test-cases', description: 'QA test cases', relativePath: 'qa/test-cases/<rid>.md' },
55
+ {
56
+ name: 'test-report',
57
+ description: 'QA test report with execution results',
58
+ relativePath: 'qa/test-reports/<rid>.md'
59
+ }
60
+ ];
61
+ /**
62
+ * Every QA prerequisite this type's table carries, at any state the QA role can
63
+ * be in.
64
+ *
65
+ * THE REFUSAL IS NAMED ON PURPOSE. `getPrerequisitesFor` reads a record keyed by
66
+ * type, so a non-member reaches `undefined` and throws a bare `TypeError` — before
67
+ * the derivation existed, a list of names answered such a caller with a gate list
68
+ * instead. A value that no longer works must say what it wanted, which value it
69
+ * got, and what the alternatives are.
70
+ */
71
+ function qaPrerequisitesOfType(requestType) {
72
+ if (!VALID_REQUEST_TYPES.includes(requestType)) {
73
+ throw new Error(`pipeline-verify: "${String(requestType)}" is not a request type — expected one of ${VALID_REQUEST_TYPES.join(', ')}`);
74
+ }
75
+ return QA_STATES.flatMap((state) => getPrerequisitesFor('qa', state, requestType));
76
+ }
77
+ /**
78
+ * Does this type's table carry a QA phase?
79
+ *
80
+ * One derivation, so the gate list and the checker's verdict cannot disagree: the
81
+ * phase exists for a type exactly when its table carries a QA prerequisite —
82
+ * counted across every QA state, so a type whose only QA row sits at a
83
+ * non-terminal state is not read as having no phase at all.
84
+ */
85
+ export function typeRequiresQaPhase(requestType) {
86
+ return qaPrerequisitesOfType(requestType).length > 0;
87
+ }
88
+ /**
89
+ * The request types whose table carries NO QA phase — the set a skip may cover.
90
+ *
91
+ * DERIVED, not listed. The skip allowlist used to spell `['docs', 'config', 'chore']`,
92
+ * and `config` carries a QA phase (its table demands `SECURITY_REVIEW` and
93
+ * `TEST_REPORT`), so a plantable record could bypass a phase the contract requires.
94
+ * Reading the answer off the same derivation the pipeline uses means a table change
95
+ * moves the allowlist with it — in both directions, without anyone remembering.
96
+ */
97
+ export const QA_FREE_TYPES = Object.freeze(VALID_REQUEST_TYPES.filter((requestType) => !typeRequiresQaPhase(requestType)));
98
+ /**
99
+ * Fill in the QA request gate for a phase that HAS one.
100
+ *
101
+ * A type whose table carries no QA row has no QA gate to fill, and that is not a
102
+ * special case to handle at the call site: the artifact is still honoured — its
103
+ * state and its location are read either way — so a tree that ran QA for a type
104
+ * whose table does not demand it keeps passing.
105
+ */
106
+ export function markQaRequestGate(gates, artifactPath) {
107
+ const requestGate = gates[0];
108
+ if (requestGate === undefined)
109
+ return;
110
+ requestGate.passed = true;
111
+ requestGate.detail = `found at ${artifactPath}`;
112
+ }
113
+ /**
114
+ * The QA phase's gate list for one type: the phase gate when the phase exists,
115
+ * then one gate per piece of evidence the caller resolved from the contract. An
116
+ * empty list IS the answer for a type with no QA phase.
117
+ *
118
+ * The `security-findings` / `performance-findings` gates were removed here
119
+ * security review or performance review — `peaks-qa/SKILL.md` says so, and the
120
+ * v2.11.0 D1/D4 trim dropped both from every `qa:verdict-issued` table. The
121
+ * evidence they used to demand is now checked on the RD side, at the paths the
122
+ * contract actually names (`audit/security-<rid>.md`, `audit/perf.md` and
123
+ * `rd/security-review.md` / `rd/perf-baseline.md` as the declared legacy tiers
124
+ * behind them).
125
+ */
126
+ export function qaPhaseGates(required, evidence) {
127
+ if (!required)
128
+ return [];
129
+ const gates = [
130
+ {
131
+ name: 'qa-request-exists',
132
+ description: 'QA request artifact created',
133
+ passed: false,
134
+ detail: ''
135
+ }
136
+ ];
137
+ for (const gate of evidence) {
138
+ gates.push({ name: gate.name, description: gate.description, passed: false, detail: '' });
139
+ }
140
+ return gates;
141
+ }
142
+ /**
143
+ * THE ARM — the reconciliation behind the load-time refusal below.
144
+ *
145
+ * `prerequisitesOfType` is a parameter rather than a direct call so an arm can
146
+ * drive this with a table of its own. That is the only way to show the refusal is
147
+ * reachable: a check that can only ever run against the table it already agrees
148
+ * with cannot be observed to fail.
149
+ *
150
+ * It is handed EVERY QA state's rows — `qaPrerequisitesOfType` above, whose
151
+ * `QA_STATES` is the repository's own model — so a `qa:` row at a state the phase
152
+ * does not end in is armed too. Keying only the terminal state is how the
153
+ * `qa:running` row went unarmed.
154
+ */
155
+ function qaGateReconciliationFailures(types, prerequisitesOfType) {
156
+ const failures = [];
157
+ for (const requestType of types) {
158
+ for (const prerequisite of prerequisitesOfType(requestType)) {
159
+ // The same path set the contract resolver matches on, so a row accepted
160
+ // through a legacy tier is covered by the gate that tier stands behind.
161
+ const contractPaths = [
162
+ prerequisite.relativePath,
163
+ ...(prerequisite.legacyRelativePath !== undefined ? [prerequisite.legacyRelativePath] : []),
164
+ ...(prerequisite.legacyRelativePaths ?? [])
165
+ ];
166
+ if (QA_EVIDENCE_GATES.some((gate) => contractPaths.includes(gate.relativePath)))
167
+ continue;
168
+ failures.push(`the "${requestType}" table carries the QA prerequisite ${prerequisite.relativePath} and no gate in QA_EVIDENCE_GATES stands for it`);
169
+ }
170
+ }
171
+ return failures;
172
+ }
173
+ const QA_GATE_RECONCILIATION_FAILURES = qaGateReconciliationFailures(VALID_REQUEST_TYPES, qaPrerequisitesOfType);
174
+ if (QA_GATE_RECONCILIATION_FAILURES.length > 0) {
175
+ throw new Error(`pipeline-verify: the QA gate list does not follow the type tables — ${QA_GATE_RECONCILIATION_FAILURES.join('; ')}`);
176
+ }
@@ -11,19 +11,21 @@
11
11
  * paths compile unchanged.
12
12
  *
13
13
  */
14
- import { isRequestType } from '../artifacts/artifact-prerequisites.js';
14
+ import { markQaRequestGate, typeRequiresQaPhase } from './pipeline-verify-qa-phase.js';
15
+ import { NO_SESSION_SCOPE, mayHonourSkip, resolveRequestType } from './request-type-resolution.js';
15
16
  import { readSkipState } from './workflow-state-store.js';
16
17
  import { getSessionIdCanonical } from '../session/session-manager.js';
17
18
  import { listPromotionExempt, listUnpromotedFeedback } from '../feedback/feedback-promotion-service.js';
18
19
  import { QA_COMPLETE_STATES, RD_QA_HANDOFF_STATES, extractState, findRequestFile, qaGatesForType, rdGatesForType, resolveQaEvidencePaths, resolveRdEvidencePaths } from './pipeline-verify-gate-support.js';
19
20
  export async function verifyPipeline(options) {
20
- const requestType = isRequestType(options.requestType ?? '')
21
- ? options.requestType
22
- : 'feature';
23
- const violations = [];
21
+ // ONE scope for every read: the session, or NONE — never a scan.
22
+ const sessionId = options.sessionId ?? getSessionIdCanonical(options.projectRoot);
23
+ const requestType = await resolveRequestType({ ...options, sessionId });
24
+ const violations = sessionId === null ? [NO_SESSION_SCOPE] : [];
24
25
  const nextActions = [];
25
26
  const rdGates = rdGatesForType(requestType);
26
27
  const qaGates = qaGatesForType(requestType);
28
+ const qaPhaseRequired = typeRequiresQaPhase(requestType);
27
29
  // and pre-mark matching gates as `status: 'skipped'`. We do this
28
30
  // BEFORE evaluating evidence files, so a skipped gate never
29
31
  // emits a "missing evidence" violation. The boolean `passed` is
@@ -31,7 +33,7 @@ export async function verifyPipeline(options) {
31
33
  // treat skipped gates as satisfied; the new `status` field
32
34
  // distinguishes the bypass from an actual pass.
33
35
  const skippedGateNames = new Set();
34
- if (options.sessionId !== undefined) {
36
+ if (options.sessionId !== undefined && mayHonourSkip(requestType)) {
35
37
  const skipState = readSkipState(options.projectRoot, options.sessionId, options.rid);
36
38
  if (skipState !== null) {
37
39
  for (const gateName of skipState.skippedGates) {
@@ -47,7 +49,7 @@ export async function verifyPipeline(options) {
47
49
  skippedGateNames.add(gateName);
48
50
  }
49
51
  }
50
- nextActions.push(`Skipped gates (via peaks workflow skip): [${skipState.skippedGates.join(', ')}] — reason: ${skipState.skipReason}`);
52
+ nextActions.push(`Skipped gates (via peaks workflow skip): [${skipState.skippedGates.join(', ')}] — reason: ${skipState.skipReason} (record says applied by ${skipState.skipAppliedBy} at ${skipState.skipAppliedAt}, caller: ${skipState.callerKind})`);
51
53
  }
52
54
  }
53
55
  function markIfSkipped(gate) {
@@ -59,7 +61,7 @@ export async function verifyPipeline(options) {
59
61
  }
60
62
  // Resolve RD + QA on-disk locations via showRequestArtifact (the change-id
61
63
  // is whatever dir the file actually lives in, not the caller's session-id).
62
- const rdFile = await findRequestFile(options.projectRoot, 'rd', options.rid);
64
+ const rdFile = await findRequestFile(options.projectRoot, 'rd', options.rid, sessionId);
63
65
  let rdInvoked = false;
64
66
  let rdState = 'missing';
65
67
  // The resolved change-id is the on-disk location the file actually
@@ -89,33 +91,31 @@ export async function verifyPipeline(options) {
89
91
  // detail / nextActions surface the `DEPRECATION_LEGACY_PATH_USED`
90
92
  // warning so QA / TXT can nudge users to migrate via
91
93
  // `peaks workspace migrate`.
92
- // v2.18.1 bug #5 fix: when `resolvedChangeId` is empty (no RD/QA
93
- // artifact on disk yet), the canonical session id from the
94
- // binding-store is the preferred filesystem scope; falling through
95
- // to `options.rid` would make every missing-evidence path look like
96
- // a per-rid scope dir.
97
- const rdEvidenceDir = resolvedChangeId ||
98
- options.sessionId ||
99
- getSessionIdCanonical(options.projectRoot) ||
100
- options.rid;
101
- const rdTracker = resolveRdEvidencePaths(rdGates, rdEvidenceDir, options.projectRoot, options.rid, requestType, violations, nextActions, { anyEvidenceResolved: false, allResolvedPathsCanonical: true });
94
+ // v2.18.1 bug #5 fix: when `resolvedChangeId` is empty (no RD/QA artifact on
95
+ // disk yet), the canonical session id from the binding-store is the scope.
96
+ //
97
+ // THE RID IS NOT A SCOPE: this chain used to end at `options.rid`, reading
98
+ // EVIDENCE out of a directory named after the rid. An empty scope reads none.
99
+ const rdEvidenceDir = resolvedChangeId || options.sessionId || getSessionIdCanonical(options.projectRoot) || '';
100
+ // An empty gate list IS "no evidence read": the resolver walks the gates it is
101
+ // handed, so no second branch has to be kept in step with this one.
102
+ const rdTracker = resolveRdEvidencePaths(rdEvidenceDir === '' ? [] : rdGates, rdEvidenceDir, options.projectRoot, options.rid, requestType, violations, nextActions, { anyEvidenceResolved: false, allResolvedPathsCanonical: true });
102
103
  // Check if RD reached qa-handoff
103
104
  if (rdInvoked && !RD_QA_HANDOFF_STATES.has(rdState)) {
104
105
  violations.push(`RD not ready for QA: state is "${rdState}" — must reach "qa-handoff" (unit tests, karpathy-guidelines §1 Think / §2 Simplicity / §3 Surgical / §4 Goal-Driven, code review, security review complete)`);
105
106
  nextActions.push(`Complete RD gates → peaks request transition ${options.rid} --role rd --state qa-handoff`);
106
107
  }
107
108
  // Check QA phase
108
- const qaFile = await findRequestFile(options.projectRoot, 'qa', options.rid);
109
+ const qaFile = await findRequestFile(options.projectRoot, 'qa', options.rid, sessionId);
109
110
  let qaInvoked = false;
110
111
  let qaState = 'missing';
111
112
  if (qaFile) {
112
113
  qaInvoked = true;
113
114
  qaState = extractState(qaFile.content);
114
- qaGates[0].passed = true;
115
- qaGates[0].detail = `found at ${qaFile.path}`;
115
+ markQaRequestGate(qaGates, qaFile.path);
116
116
  resolvedChangeId = qaFile.sessionId || resolvedChangeId;
117
117
  }
118
- else {
118
+ else if (qaPhaseRequired) {
119
119
  violations.push('QA phase skipped: peaks-qa was never invoked for this request (no QA request artifact found)');
120
120
  nextActions.push('Invoke Skill(skill="peaks-qa") with the request-id for functional/performance/security testing');
121
121
  qaGates[0].detail = 'not found';
@@ -123,7 +123,7 @@ export async function verifyPipeline(options) {
123
123
  // Check QA evidence files. (The v2.18.1 bug #5 `changeIdForResolver`
124
124
  // fallback — current session id when no RD/QA artifact is on disk yet —
125
125
  // the security/perf findings branch that was its only consumer.)
126
- const qaTracker = resolveQaEvidencePaths(qaGates, options.projectRoot, rdEvidenceDir, requestType, options.rid, violations, nextActions, rdTracker);
126
+ const qaTracker = resolveQaEvidencePaths(rdEvidenceDir === '' ? [] : qaGates, options.projectRoot, rdEvidenceDir, requestType, options.rid, violations, nextActions, rdTracker);
127
127
  const anyEvidenceResolved = qaTracker.anyEvidenceResolved;
128
128
  const allResolvedPathsCanonical = qaTracker.allResolvedPathsCanonical;
129
129
  // Check if QA reached verdict-issued
@@ -167,7 +167,7 @@ export async function verifyPipeline(options) {
167
167
  // Resolve the "RD invoked without QA" check now that markIfSkipped
168
168
  // has run. The check is suppressed when every QA gate is skipped
169
169
  // to skip the QA phase).
170
- if (rdInvokedWithoutQaRaw) {
170
+ if (rdInvokedWithoutQaRaw && qaPhaseRequired) {
171
171
  const allQaSkipped = qaGates.every((g) => g.status === 'skipped');
172
172
  if (!allQaSkipped) {
173
173
  violations.push('CRITICAL: peaks-rd was invoked but peaks-qa was NOT — QA functional/performance/security testing is mandatory after all RD work');
@@ -226,12 +226,11 @@ export async function verifyPipeline(options) {
226
226
  const allRdGatesPassed = rdGates.every((g) => g.passed);
227
227
  const allQaGatesPassed = qaGates.every((g) => g.passed);
228
228
  const complete = rdInvoked &&
229
- qaInvoked &&
229
+ (qaInvoked ? QA_COMPLETE_STATES.has(qaState) : !qaPhaseRequired) &&
230
230
  allRdGatesPassed &&
231
231
  allQaGatesPassed &&
232
232
  allFeedbackGatesPassed &&
233
- RD_QA_HANDOFF_STATES.has(rdState) &&
234
- QA_COMPLETE_STATES.has(qaState);
233
+ RD_QA_HANDOFF_STATES.has(rdState);
235
234
  // 'suffixed' when the contract's current path served the file and 'legacy'
236
235
  // when the deprecated fallback did; 'none' if neither gate passed.
237
236
  //