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.
Files changed (104) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +67 -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/core/skill-registry-commands.js +9 -4
  12. package/dist/cli/commands/dispatch-command-spec.js +1 -1
  13. package/dist/cli/commands/dispatch-isolation-lease.d.ts +1 -1
  14. package/dist/cli/commands/dispatch-isolation-lease.js +6 -53
  15. package/dist/cli/commands/dispatch-prompt-blocks.d.ts +1 -1
  16. package/dist/cli/commands/dispatch-prompt-composition.d.ts +1 -1
  17. package/dist/cli/commands/dispatch-record-write.d.ts +1 -1
  18. package/dist/cli/commands/dispatch-tool-call.d.ts +1 -1
  19. package/dist/cli/commands/openspec-command-shared.js +2 -2
  20. package/dist/cli/commands/request-transition-failures.js +31 -4
  21. package/dist/cli/commands/request-transition-preflight.js +1 -1
  22. package/dist/cli/commands/slice-decompose-artifacts.js +2 -1
  23. package/dist/cli/commands/verdict-aggregate-command.js +2 -1
  24. package/dist/cli/commands/workflow-gate-commands.js +4 -4
  25. package/dist/cli/program.js +0 -2
  26. package/dist/services/artifacts/artifact-contract-block.js +21 -2
  27. package/dist/services/artifacts/artifact-prerequisites.d.ts +1 -0
  28. package/dist/services/artifacts/artifact-prerequisites.js +11 -99
  29. package/dist/services/artifacts/backcompat-acceptance.d.ts +66 -0
  30. package/dist/services/artifacts/backcompat-acceptance.js +220 -0
  31. package/dist/services/artifacts/prerequisite-checks.d.ts +8 -0
  32. package/dist/services/artifacts/prerequisite-checks.js +7 -2
  33. package/dist/services/artifacts/prerequisite-path-resolver.d.ts +39 -0
  34. package/dist/services/artifacts/prerequisite-path-resolver.js +110 -0
  35. package/dist/services/artifacts/rd-transition-gates.d.ts +33 -0
  36. package/dist/services/artifacts/rd-transition-gates.js +71 -0
  37. package/dist/services/artifacts/request-artifact-service.js +22 -20
  38. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +9 -1
  39. package/dist/services/artifacts/request-artifact-state-helpers.js +6 -4
  40. package/dist/services/audit-independent/judged-declaration-check.d.ts +1 -0
  41. package/dist/services/audit-independent/judged-declaration-check.js +62 -1
  42. package/dist/services/context/build-dispatch-system-prompt.d.ts +5 -9
  43. package/dist/services/context/build-dispatch-system-prompt.js +11 -11
  44. package/dist/services/context/post-compact-reinjection.js +1 -1
  45. package/dist/services/dispatch/test-tool-detection.d.ts +17 -1
  46. package/dist/services/dispatch/test-tool-detection.js +12 -1
  47. package/dist/services/doctor/doctor-service/checks/backcompat-acceptance.d.ts +15 -0
  48. package/dist/services/doctor/doctor-service/checks/backcompat-acceptance.js +53 -0
  49. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +38 -0
  50. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +243 -0
  51. package/dist/services/doctor/doctor-service/plugin-registry.js +4 -0
  52. package/dist/services/doctor/doctor-service/types.d.ts +12 -0
  53. package/dist/services/evidence/evidence-generator.js +8 -4
  54. package/dist/services/openspec/coverage-evidence-reader.d.ts +9 -9
  55. package/dist/services/openspec/coverage-evidence-reader.js +8 -8
  56. package/dist/services/openspec/openspec-archive-service.d.ts +1 -1
  57. package/dist/services/openspec/openspec-archive-service.js +6 -6
  58. package/dist/services/scan/file-size-baseline.d.ts +13 -6
  59. package/dist/services/scan/file-size-baseline.js +54 -31
  60. package/dist/services/scan/file-size-scan.d.ts +7 -14
  61. package/dist/services/scan/file-size-scan.js +6 -1
  62. package/dist/services/scan/type-corroboration.d.ts +32 -0
  63. package/dist/services/scan/type-corroboration.js +51 -0
  64. package/dist/services/scan/type-sanity-service.d.ts +14 -0
  65. package/dist/services/scan/type-sanity-service.js +10 -19
  66. package/dist/services/security/safe-settings-path.d.ts +5 -0
  67. package/dist/services/security/safe-settings-path.js +64 -8
  68. package/dist/services/skill/resume-detector.js +8 -8
  69. package/dist/services/workflow/pipeline-verify-gate-support.d.ts +28 -9
  70. package/dist/services/workflow/pipeline-verify-gate-support.js +40 -117
  71. package/dist/services/workflow/pipeline-verify-qa-phase.d.ts +102 -0
  72. package/dist/services/workflow/pipeline-verify-qa-phase.js +176 -0
  73. package/dist/services/workflow/pipeline-verify-rd-phase.d.ts +67 -0
  74. package/dist/services/workflow/pipeline-verify-rd-phase.js +122 -0
  75. package/dist/services/workflow/pipeline-verify-service.js +42 -44
  76. package/dist/services/workflow/request-type-resolution.d.ts +99 -0
  77. package/dist/services/workflow/request-type-resolution.js +130 -0
  78. package/dist/services/workflow/workflow-skip-service.d.ts +1 -0
  79. package/dist/services/workflow/workflow-skip-service.js +19 -21
  80. package/dist/services/workflow/workflow-state-store.d.ts +9 -0
  81. package/dist/services/workflow/workflow-state-store.js +26 -1
  82. package/dist/services/workspace/workspace-service.js +4 -16
  83. package/dist/shared/incrementing-number.d.ts +23 -2
  84. package/dist/shared/incrementing-number.js +57 -15
  85. package/package.json +5 -7
  86. package/schemas/doctor-report.schema.json +2 -2
  87. package/skills/bee/peaks-prd/SKILL.md +3 -2
  88. package/skills/peaks-code/SKILL.md +32 -15
  89. package/dist/cli/commands/vm-command-shared.d.ts +0 -23
  90. package/dist/cli/commands/vm-command-shared.js +0 -23
  91. package/dist/cli/commands/vm-commands.d.ts +0 -3
  92. package/dist/cli/commands/vm-commands.js +0 -45
  93. package/dist/cli/commands/vm-hypervisor-probe.d.ts +0 -27
  94. package/dist/cli/commands/vm-hypervisor-probe.js +0 -78
  95. package/dist/cli/commands/vm-hypervisor-runtime.d.ts +0 -15
  96. package/dist/cli/commands/vm-hypervisor-runtime.js +0 -64
  97. package/dist/cli/commands/vm-release-command.d.ts +0 -5
  98. package/dist/cli/commands/vm-release-command.js +0 -101
  99. package/dist/cli/commands/vm-spawn-command.d.ts +0 -5
  100. package/dist/cli/commands/vm-spawn-command.js +0 -177
  101. package/dist/cli/commands/vm-status-command.d.ts +0 -3
  102. package/dist/cli/commands/vm-status-command.js +0 -50
  103. package/dist/services/vm/vm-lease.d.ts +0 -40
  104. package/dist/services/vm/vm-lease.js +0 -160
@@ -0,0 +1,122 @@
1
+ /**
2
+ * peaks-workflow — the RD evidence gates, derived from the type tables.
3
+ *
4
+ * WHY THIS IS A MODULE OF ITS OWN. The same measured budget as
5
+ * `pipeline-verify-qa-phase.ts`: the file-size census records gated excess by
6
+ * EQUALITY, and `pipeline-verify-gate-support` already carries its share of that
7
+ * sum. A file under its cap adds nothing to it, so the reasoning below is paid
8
+ * for here at zero census cost.
9
+ *
10
+ * WHY A DERIVATION AT ALL. `rdGatesForType` answered "which evidence does RD
11
+ * owe" with three hand-written type lists — `=== 'bugfix'`, `!== 'docs' &&
12
+ * !== 'chore' && !== 'config'`, and a four-name union — none of which read the
13
+ * `artifact-prerequisites.ts` table that `peaks request transition` enforces.
14
+ * The table is the authority: a type whose `rd:qa-handoff` row carries the
15
+ * prerequisite owes that evidence, and a type whose row does not owes none.
16
+ *
17
+ * WHY THE `relativePath`s ARE THE BARE NAMES. Each row's path is the probe name
18
+ * the contract accessor is asked about, and each is a path the contract accepts.
19
+ * `rd/security-review.md` is load-bearing: it is the legacy tier of BOTH the
20
+ * fanout `AUDIT_SECURITY` row (feature / bugfix / refactor) and the
21
+ * `SECURITY_REVIEW` row config uses. The canonical `audit/security-<rid>.md` is
22
+ * carried only by the former, so deriving off it would silently drop config's
23
+ * security gate — the six-type table in `pipeline-verify-rd-gates.test.ts` pins
24
+ * that.
25
+ */
26
+ // A LIVE-BINDING CYCLE: `pipeline-verify-gate-support` re-exports
27
+ // `rdGatesForType` from this module while this module reads its
28
+ // `contractEvidencePaths`. Both are function declarations, which ESM initialises
29
+ // during instantiation, so the binding is safe — but only while nothing here
30
+ // CALLS it at module load. The derivation is function-only and the default
31
+ // parameter below resolves per call. A leaf-module split would have to move
32
+ // `contractPrerequisite` / `contractBodyViolations` with the accessor and expand
33
+ // this diff, so the cycle stays bounded to these two files.
34
+ import { contractEvidencePaths } from './pipeline-verify-gate-support.js';
35
+ /**
36
+ * Every RD evidence gate the checker can build, each naming the contract path it
37
+ * stands for. The NAME and DESCRIPTION are the checker's own — `peaks workflow
38
+ * skip` takes gate names and the violation text prints the description — while
39
+ * the PATH is the contract's, and it is the half that makes a gate list
40
+ * derivable instead of restated beside the tables it is supposed to be read from.
41
+ */
42
+ export const RD_EVIDENCE_GATES = [
43
+ // The contract's design / scope record at `rd:qa-handoff`. The retired
44
+ // `rd/tech-doc.md` slot this gate replaced has no prerequisite in any table.
45
+ {
46
+ name: 'prd-handoff',
47
+ description: 'PRD handoff capsule (approved scope + non-goals)',
48
+ relativePath: 'prd/handoff.md'
49
+ },
50
+ {
51
+ name: 'bug-analysis',
52
+ description: 'Bug root-cause analysis',
53
+ relativePath: 'rd/bug-analysis.md'
54
+ },
55
+ { name: 'code-review', description: 'Code review evidence', relativePath: 'rd/code-review.md' },
56
+ {
57
+ name: 'security-review',
58
+ description: 'Security review evidence',
59
+ relativePath: 'rd/security-review.md'
60
+ },
61
+ // `AUDIT_PERF`'s legacy tier. Relocating the gate (rather than deleting it) is
62
+ // what keeps AC3's control meaningful: genuinely absent perf evidence fails.
63
+ {
64
+ name: 'perf-baseline',
65
+ description: 'Performance audit evidence',
66
+ relativePath: 'rd/perf-baseline.md'
67
+ }
68
+ ];
69
+ /**
70
+ * The RD gate list for one type: the request gate, then one gate per evidence
71
+ * row this type's table carries.
72
+ *
73
+ * `lookup` is a parameter rather than a direct call so an arm can drive the
74
+ * derivation with a contract of its own. That is the only way to show a null
75
+ * drops a gate: a check that only ever runs against the table it already agrees
76
+ * with cannot be observed to drop anything.
77
+ */
78
+ export function deriveRdGates(requestType, lookup) {
79
+ const gates = [
80
+ {
81
+ name: 'rd-request-exists',
82
+ description: 'RD request artifact created',
83
+ passed: false,
84
+ detail: ''
85
+ }
86
+ ];
87
+ for (const evidence of RD_EVIDENCE_GATES) {
88
+ if (lookup(requestType, evidence.relativePath) === null)
89
+ continue;
90
+ gates.push({
91
+ name: evidence.name,
92
+ description: evidence.description,
93
+ passed: false,
94
+ detail: ''
95
+ });
96
+ }
97
+ return gates;
98
+ }
99
+ /**
100
+ * The production binding: the type's own `rd:qa-handoff` table is the lookup.
101
+ *
102
+ * `lookup` is an optional overrides seam, not configuration: the arm drives this
103
+ * binding with a synthetic contract so a restatement inside the default cannot
104
+ * stay green. Production passes one argument and gets the real table.
105
+ */
106
+ export function rdGatesForType(requestType, lookup = (type, relativePath) => contractEvidencePaths('rd', 'qa-handoff', type, relativePath)) {
107
+ return deriveRdGates(requestType, lookup);
108
+ }
109
+ /**
110
+ * The contract path the gate named `gateName` stands for.
111
+ *
112
+ * `resolveRdEvidencePaths` iterates exactly the gate list this module built, so
113
+ * a miss would be a name invented outside the table; it refuses by name rather
114
+ * than dereferencing nothing.
115
+ */
116
+ export function rdEvidenceProbe(gateName) {
117
+ const gate = RD_EVIDENCE_GATES.find((entry) => entry.name === gateName);
118
+ if (gate === undefined) {
119
+ throw new Error(`pipeline-verify: "${gateName}" is not an RD evidence gate — expected one of ${RD_EVIDENCE_GATES.map((entry) => entry.name).join(', ')}`);
120
+ }
121
+ return gate.relativePath;
122
+ }
@@ -11,19 +11,22 @@
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';
18
+ import { checkExpiredBackCompatCommitGate } from '../artifacts/artifact-prerequisites.js';
17
19
  import { listPromotionExempt, listUnpromotedFeedback } from '../feedback/feedback-promotion-service.js';
18
20
  import { QA_COMPLETE_STATES, RD_QA_HANDOFF_STATES, extractState, findRequestFile, qaGatesForType, rdGatesForType, resolveQaEvidencePaths, resolveRdEvidencePaths } from './pipeline-verify-gate-support.js';
19
21
  export async function verifyPipeline(options) {
20
- const requestType = isRequestType(options.requestType ?? '')
21
- ? options.requestType
22
- : 'feature';
23
- const violations = [];
22
+ // ONE scope for every read: the session, or NONE — never a scan.
23
+ const sessionId = options.sessionId ?? getSessionIdCanonical(options.projectRoot);
24
+ const requestType = await resolveRequestType({ ...options, sessionId });
25
+ const violations = sessionId === null ? [NO_SESSION_SCOPE] : [];
24
26
  const nextActions = [];
25
27
  const rdGates = rdGatesForType(requestType);
26
28
  const qaGates = qaGatesForType(requestType);
29
+ const qaPhaseRequired = typeRequiresQaPhase(requestType);
27
30
  // and pre-mark matching gates as `status: 'skipped'`. We do this
28
31
  // BEFORE evaluating evidence files, so a skipped gate never
29
32
  // emits a "missing evidence" violation. The boolean `passed` is
@@ -31,7 +34,7 @@ export async function verifyPipeline(options) {
31
34
  // treat skipped gates as satisfied; the new `status` field
32
35
  // distinguishes the bypass from an actual pass.
33
36
  const skippedGateNames = new Set();
34
- if (options.sessionId !== undefined) {
37
+ if (options.sessionId !== undefined && mayHonourSkip(requestType)) {
35
38
  const skipState = readSkipState(options.projectRoot, options.sessionId, options.rid);
36
39
  if (skipState !== null) {
37
40
  for (const gateName of skipState.skippedGates) {
@@ -47,7 +50,7 @@ export async function verifyPipeline(options) {
47
50
  skippedGateNames.add(gateName);
48
51
  }
49
52
  }
50
- nextActions.push(`Skipped gates (via peaks workflow skip): [${skipState.skippedGates.join(', ')}] — reason: ${skipState.skipReason}`);
53
+ 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
54
  }
52
55
  }
53
56
  function markIfSkipped(gate) {
@@ -59,7 +62,7 @@ export async function verifyPipeline(options) {
59
62
  }
60
63
  // Resolve RD + QA on-disk locations via showRequestArtifact (the change-id
61
64
  // is whatever dir the file actually lives in, not the caller's session-id).
62
- const rdFile = await findRequestFile(options.projectRoot, 'rd', options.rid);
65
+ const rdFile = await findRequestFile(options.projectRoot, 'rd', options.rid, sessionId);
63
66
  let rdInvoked = false;
64
67
  let rdState = 'missing';
65
68
  // The resolved change-id is the on-disk location the file actually
@@ -89,33 +92,31 @@ export async function verifyPipeline(options) {
89
92
  // detail / nextActions surface the `DEPRECATION_LEGACY_PATH_USED`
90
93
  // warning so QA / TXT can nudge users to migrate via
91
94
  // `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 });
95
+ // v2.18.1 bug #5 fix: when `resolvedChangeId` is empty (no RD/QA artifact on
96
+ // disk yet), the canonical session id from the binding-store is the scope.
97
+ //
98
+ // THE RID IS NOT A SCOPE: this chain used to end at `options.rid`, reading
99
+ // EVIDENCE out of a directory named after the rid. An empty scope reads none.
100
+ const rdEvidenceDir = resolvedChangeId || options.sessionId || getSessionIdCanonical(options.projectRoot) || '';
101
+ // An empty gate list IS "no evidence read": the resolver walks the gates it is
102
+ // handed, so no second branch has to be kept in step with this one.
103
+ const rdTracker = resolveRdEvidencePaths(rdEvidenceDir === '' ? [] : rdGates, rdEvidenceDir, options.projectRoot, options.rid, requestType, violations, nextActions, { anyEvidenceResolved: false, allResolvedPathsCanonical: true });
102
104
  // Check if RD reached qa-handoff
103
105
  if (rdInvoked && !RD_QA_HANDOFF_STATES.has(rdState)) {
104
106
  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
107
  nextActions.push(`Complete RD gates → peaks request transition ${options.rid} --role rd --state qa-handoff`);
106
108
  }
107
109
  // Check QA phase
108
- const qaFile = await findRequestFile(options.projectRoot, 'qa', options.rid);
110
+ const qaFile = await findRequestFile(options.projectRoot, 'qa', options.rid, sessionId);
109
111
  let qaInvoked = false;
110
112
  let qaState = 'missing';
111
113
  if (qaFile) {
112
114
  qaInvoked = true;
113
115
  qaState = extractState(qaFile.content);
114
- qaGates[0].passed = true;
115
- qaGates[0].detail = `found at ${qaFile.path}`;
116
+ markQaRequestGate(qaGates, qaFile.path);
116
117
  resolvedChangeId = qaFile.sessionId || resolvedChangeId;
117
118
  }
118
- else {
119
+ else if (qaPhaseRequired) {
119
120
  violations.push('QA phase skipped: peaks-qa was never invoked for this request (no QA request artifact found)');
120
121
  nextActions.push('Invoke Skill(skill="peaks-qa") with the request-id for functional/performance/security testing');
121
122
  qaGates[0].detail = 'not found';
@@ -123,9 +124,17 @@ export async function verifyPipeline(options) {
123
124
  // Check QA evidence files. (The v2.18.1 bug #5 `changeIdForResolver`
124
125
  // fallback — current session id when no RD/QA artifact is on disk yet —
125
126
  // the security/perf findings branch that was its only consumer.)
126
- const qaTracker = resolveQaEvidencePaths(qaGates, options.projectRoot, rdEvidenceDir, requestType, options.rid, violations, nextActions, rdTracker);
127
+ const qaTracker = resolveQaEvidencePaths(rdEvidenceDir === '' ? [] : qaGates, options.projectRoot, rdEvidenceDir, requestType, options.rid, violations, nextActions, rdTracker);
127
128
  const anyEvidenceResolved = qaTracker.anyEvidenceResolved;
128
129
  const allResolvedPathsCanonical = qaTracker.allResolvedPathsCanonical;
130
+ const backcompatExpiry = await checkExpiredBackCompatCommitGate({
131
+ projectRoot: options.projectRoot,
132
+ sessionId: rdEvidenceDir === '' ? undefined : rdEvidenceDir,
133
+ requestType,
134
+ requestId: options.rid
135
+ });
136
+ violations.push(...backcompatExpiry.violations);
137
+ nextActions.push(...backcompatExpiry.warnings);
129
138
  // Check if QA reached verdict-issued
130
139
  if (qaInvoked && !QA_COMPLETE_STATES.has(qaState)) {
131
140
  violations.push(`QA not complete: state is "${qaState}" — must reach "verdict-issued" (functional + performance + security checks done)`);
@@ -135,12 +144,9 @@ export async function verifyPipeline(options) {
135
144
  // values are only final after the post-process pass. We track the
136
145
  // decision with a placeholder here and resolve it below.
137
146
  const rdInvokedWithoutQaRaw = rdInvoked && !qaInvoked;
138
- // the user marked as skipped, override the evaluation result. The
139
- // boolean `passed` is set to true so the gate counts as satisfied;
140
- // the new `status: 'skipped'` field signals the bypass to
141
- // downstream consumers. Violations and nextActions pushed for
142
- // skipped gates are filtered out (the user explicitly chose to
143
- // skip — the missing-evidence message is no longer actionable).
147
+ // A skipped gate counts as satisfied (`passed = true`); its `status: 'skipped'`
148
+ // signals the bypass downstream, and its missing-evidence violations and
149
+ // nextActions are filtered out because the user chose the skip.
144
150
  for (const gate of [...rdGates, ...qaGates]) {
145
151
  if (skippedGateNames.has(gate.name)) {
146
152
  markIfSkipped(gate);
@@ -167,7 +173,7 @@ export async function verifyPipeline(options) {
167
173
  // Resolve the "RD invoked without QA" check now that markIfSkipped
168
174
  // has run. The check is suppressed when every QA gate is skipped
169
175
  // to skip the QA phase).
170
- if (rdInvokedWithoutQaRaw) {
176
+ if (rdInvokedWithoutQaRaw && qaPhaseRequired) {
171
177
  const allQaSkipped = qaGates.every((g) => g.status === 'skipped');
172
178
  if (!allQaSkipped) {
173
179
  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 +232,12 @@ export async function verifyPipeline(options) {
226
232
  const allRdGatesPassed = rdGates.every((g) => g.passed);
227
233
  const allQaGatesPassed = qaGates.every((g) => g.passed);
228
234
  const complete = rdInvoked &&
229
- qaInvoked &&
235
+ (qaInvoked ? QA_COMPLETE_STATES.has(qaState) : !qaPhaseRequired) &&
230
236
  allRdGatesPassed &&
231
237
  allQaGatesPassed &&
232
238
  allFeedbackGatesPassed &&
233
- RD_QA_HANDOFF_STATES.has(rdState) &&
234
- QA_COMPLETE_STATES.has(qaState);
239
+ backcompatExpiry.violations.length === 0 &&
240
+ RD_QA_HANDOFF_STATES.has(rdState);
235
241
  // 'suffixed' when the contract's current path served the file and 'legacy'
236
242
  // when the deprecated fallback did; 'none' if neither gate passed.
237
243
  //
@@ -252,17 +258,9 @@ export async function verifyPipeline(options) {
252
258
  : 'suffixed';
253
259
  const gateC = allQaGatesPassed ? 'pass' : 'fail';
254
260
  const gateH = allFeedbackGatesPassed ? 'pass' : 'fail';
255
- // every gate resolved on the canonical path; `false` when at least
256
- // one fell back to a legacy form. QA / TXT surface the value so the
257
- // user knows the legacy content must be moved into the canonical
258
- // location (the legacy `peaks workspace migrate-change-scope` helper
259
- // was removed in v2.19.0; use `peaks workspace migrate` to relocate
260
- // misplaced content).
261
- //
262
- // If NO evidence file resolved (e.g. all gates missing), the field is
263
- // `true` — there is nothing non-canonical to worry about. If every
264
- // resolved gate was skipped via `peaks workflow skip`, the field is
265
- // `true` — the user opted out of the canonical/legacy decision.
261
+ // `true` when every resolved gate used the canonical path (or nothing resolved,
262
+ // or every gate was skipped). `false` when one fell back to a legacy form; QA /
263
+ // TXT surface it so the user moves the content with `peaks workspace migrate`.
266
264
  const allGatesSkipped = [...rdGates, ...qaGates].every((g) => g.status === 'skipped');
267
265
  const usedCanonicalPath = !anyEvidenceResolved || allGatesSkipped || allResolvedPathsCanonical;
268
266
  return {
@@ -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 (the
5
- * applicator accepts an injected `readSkipState` / `writeSkipState`
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, regardless of `--reason`. The allowlist is
12
- * `['docs', 'config', 'chore']`.
13
- * - Rule 2 (one-time semantics): if a skip-marker already exists for
14
- * this rid AND the requested skip is the same → idempotent
15
- * no-op (`applied: false, idempotent: true`). If different → deny
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
- const SKIPPABLE_TYPES = ['docs', 'config', 'chore'];
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 (allowlist: docs, config, chore)`,
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; falls back to the OS user if git config is
192
- * unavailable. Never throws. */
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';