peaks-loop 4.1.6 → 4.1.8

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 (90) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +78 -0
  3. package/config/eslint/tsconfig.lint.json +1 -0
  4. package/dist/cli/commands/core/skill-registry-commands.js +9 -4
  5. package/dist/cli/commands/dispatch-from-dag.js +17 -0
  6. package/dist/cli/commands/job-commands.js +15 -5
  7. package/dist/cli/commands/lint-baseline-command.d.ts +15 -0
  8. package/dist/cli/commands/lint-baseline-command.js +64 -0
  9. package/dist/cli/commands/lint-commands.js +27 -51
  10. package/dist/cli/commands/request-command-options.d.ts +6 -0
  11. package/dist/cli/commands/request-commands.js +2 -0
  12. package/dist/cli/commands/request-mark-qa-initiated-command.d.ts +3 -0
  13. package/dist/cli/commands/request-mark-qa-initiated-command.js +80 -0
  14. package/dist/cli/commands/request-transition-failures.js +1 -0
  15. package/dist/cli/commands/reviewer-commands.d.ts +6 -6
  16. package/dist/cli/commands/reviewer-commands.js +154 -56
  17. package/dist/cli/commands/reviewer-config-commands.d.ts +9 -0
  18. package/dist/cli/commands/reviewer-config-commands.js +133 -0
  19. package/dist/services/artifacts/artifact-lint-service.js +102 -27
  20. package/dist/services/artifacts/artifact-prerequisites.d.ts +2 -0
  21. package/dist/services/artifacts/artifact-prerequisites.js +22 -110
  22. package/dist/services/artifacts/artifact-template-bodies.d.ts +7 -1
  23. package/dist/services/artifacts/artifact-template-bodies.js +14 -3
  24. package/dist/services/artifacts/artifact-templates.d.ts +6 -1
  25. package/dist/services/artifacts/artifact-templates.js +8 -5
  26. package/dist/services/artifacts/backcompat-acceptance.d.ts +66 -0
  27. package/dist/services/artifacts/backcompat-acceptance.js +222 -0
  28. package/dist/services/artifacts/prerequisite-checks.d.ts +42 -9
  29. package/dist/services/artifacts/prerequisite-checks.js +35 -11
  30. package/dist/services/artifacts/prerequisite-path-resolver.d.ts +39 -0
  31. package/dist/services/artifacts/prerequisite-path-resolver.js +110 -0
  32. package/dist/services/artifacts/qa-initiated-marker.d.ts +24 -0
  33. package/dist/services/artifacts/qa-initiated-marker.js +36 -0
  34. package/dist/services/artifacts/request-artifact-metadata.d.ts +9 -0
  35. package/dist/services/artifacts/request-artifact-metadata.js +9 -0
  36. package/dist/services/artifacts/request-artifact-service.js +6 -10
  37. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +2 -1
  38. package/dist/services/artifacts/request-artifact-state-helpers.js +6 -3
  39. package/dist/services/dispatch/isolation-lease.d.ts +3 -2
  40. package/dist/services/dispatch/isolation-lease.js +15 -6
  41. package/dist/services/doctor/doctor-service/checks/backcompat-acceptance.d.ts +15 -0
  42. package/dist/services/doctor/doctor-service/checks/backcompat-acceptance.js +53 -0
  43. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +38 -0
  44. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +243 -0
  45. package/dist/services/doctor/doctor-service/plugin-registry.js +4 -0
  46. package/dist/services/doctor/doctor-service/types.d.ts +12 -0
  47. package/dist/services/job/subagent-job-wrapper.d.ts +20 -7
  48. package/dist/services/job/subagent-job-wrapper.js +53 -5
  49. package/dist/services/lint/eslint-report.d.ts +19 -0
  50. package/dist/services/lint/eslint-report.js +60 -0
  51. package/dist/services/lint/eslint-runner-support.d.ts +18 -1
  52. package/dist/services/lint/eslint-runner-support.js +35 -2
  53. package/dist/services/lint/eslint-runner-types.d.ts +21 -1
  54. package/dist/services/lint/eslint-runner.js +43 -33
  55. package/dist/services/prd/gate-evidence-derivation.d.ts +2 -4
  56. package/dist/services/prd/gate-evidence-derivation.js +3 -1
  57. package/dist/services/qa/bdd-test-style-contract.d.ts +17 -0
  58. package/dist/services/qa/bdd-test-style-contract.js +41 -0
  59. package/dist/services/qa/bdd-test-style-verifier.d.ts +9 -6
  60. package/dist/services/qa/bdd-test-style-verifier.js +24 -37
  61. package/dist/services/rd/reviewer-dispatch-policy.d.ts +18 -14
  62. package/dist/services/rd/reviewer-dispatch-policy.js +14 -11
  63. package/dist/services/release/release-state.js +20 -5
  64. package/dist/services/reviewer/model-family.js +1 -1
  65. package/dist/services/reviewer/reviewer-artifacts.d.ts +12 -0
  66. package/dist/services/reviewer/reviewer-artifacts.js +67 -0
  67. package/dist/services/reviewer/reviewer-config-write.d.ts +18 -0
  68. package/dist/services/reviewer/reviewer-config-write.js +71 -0
  69. package/dist/services/reviewer/reviewer-config.d.ts +33 -5
  70. package/dist/services/reviewer/reviewer-config.js +102 -46
  71. package/dist/services/reviewer/reviewer-envelopes.d.ts +8 -0
  72. package/dist/services/reviewer/reviewer-envelopes.js +53 -0
  73. package/dist/services/reviewer/reviewer-service.d.ts +7 -4
  74. package/dist/services/reviewer/reviewer-service.js +46 -52
  75. package/dist/services/reviewer/reviewer-types.d.ts +9 -1
  76. package/dist/services/session/getSessionDir.js +16 -7
  77. package/dist/services/web/daemon-registry.d.ts +6 -4
  78. package/dist/services/web/daemon-registry.js +92 -17
  79. package/dist/services/workflow/pipeline-verify-gate-support.d.ts +4 -1
  80. package/dist/services/workflow/pipeline-verify-gate-support.js +8 -79
  81. package/dist/services/workflow/pipeline-verify-rd-phase.d.ts +67 -0
  82. package/dist/services/workflow/pipeline-verify-rd-phase.js +122 -0
  83. package/dist/services/workflow/pipeline-verify-service.js +16 -17
  84. package/dist/services/workspace/workspace-service.js +4 -16
  85. package/package.json +5 -5
  86. package/schemas/doctor-report.schema.json +2 -2
  87. package/schemas/reviewer-envelope.schema.json +1 -1
  88. package/skills/bee/peaks-reviewer/SKILL.md +20 -4
  89. package/skills/bee/peaks-reviewer/references/reviewer-schema.md +12 -7
  90. package/skills/bee/peaks-security-audit/SKILL.md +20 -0
@@ -1,10 +1,11 @@
1
- import { join, dirname, basename } from 'node:path';
2
- import { readFile, readdir } from 'node:fs/promises';
3
- import { pathExists } from 'peaks-loop-shared/fs';
4
- import { NUMBERED_PREFIX_RE, slugifyDescription } from '../../shared/incrementing-number.js';
1
+ import { readFile } from 'node:fs/promises';
5
2
  import { emitPrereqTransitionEvent } from './prerequisite-transition-event.js';
6
3
  import { isUnsafePathInput } from '../../shared/path-safety.js';
7
4
  import { bodyViolationsIfDeclared, missingPrerequisiteWarning } from './prerequisite-checks.js';
5
+ import { resolvePrerequisiteAbsolutePathWithFallback, resolvePrerequisitePath, sessionRootsFor } from './prerequisite-path-resolver.js';
6
+ // The commit-leg expiry gate lives in its own module because this file is over
7
+ // the file-size cap; re-exported here so every caller keeps one import site.
8
+ export { checkExpiredBackCompatCommitGate } from './backcompat-acceptance.js';
8
9
  export const VALID_REQUEST_TYPES = [
9
10
  'feature',
10
11
  'bugfix',
@@ -178,16 +179,16 @@ const KARPATHY_REVIEW = {
178
179
  // to KARPATHY_REVIEW. The body MUST carry the literal substring
179
180
  // `third-party-review` so a stub file with an empty envelope cannot
180
181
  // pass the gate. The full envelope lives at the JSON sibling path
181
- // (`rd/third-party-review.json`); this MD file is the human-readable
182
- // companion. The body is also expected to declare a `modelFamily`
183
- // gate diffs `rd/third-party-review.json.modelFamily` against
184
- // `rd/karpathy-review.md` parsed `modelFamily`); equality fails the
185
- // build. When `~/.peaks/config.json` lacks a `reviewer.providers`
186
- // section, the prereq is auto-marked `skipped: no-reviewer-config`
187
- // and the transition still passes (A4.3 fallbackOnError=skip).
182
+ // (`rd/third-party-review-<rid>.json`); this MD file is the human-readable
183
+ // companion. The body declares a `modelFamily` that the gate diffs against
184
+ // the karpathy review's: equality fails the build. When `~/.peaks/config.json`
185
+ // lacks a `reviewer.providers` section, the prereq is auto-marked `skipped:
186
+ // no-reviewer-config` and the transition still passes (A4.3 fallbackOnError=skip).
187
+ // The bare pre-rid path is the legacy tier, so sessions already on disk pass.
188
188
  const THIRD_PARTY_REVIEW = {
189
- relativePath: 'rd/third-party-review.md',
190
- description: 'v2.14.0 G4 third-party reviewer (peaks-reviewer skill) — must declare a `modelFamily` distinct from the karpathy-reviewer modelFamily (AC-4.4). Skipped when `~/.peaks/config.json` lacks `reviewer.providers` (>=2 entries); the prereq then resolves to a soft warning (`no-reviewer-config`) rather than a hard failure. The JSON sibling at `rd/third-party-review.json` carries the schema-validated ReviewerEnvelope (no free-form LLM JSON). v2.14.0 ships as a soft-warning prereq (1-minor-release back-compat window); v2.15.0 will hard-fail when the file is absent AND `reviewer.providers` is configured.',
189
+ relativePath: 'rd/third-party-review-<rid>.md',
190
+ legacyRelativePath: 'rd/third-party-review.md',
191
+ description: 'v2.14.0 G4 third-party reviewer (peaks-reviewer skill) — must declare a `modelFamily` distinct from the karpathy-reviewer modelFamily (AC-4.4). Skipped when `~/.peaks/config.json` lacks `reviewer.providers` (>=2 entries); the prereq then resolves to a soft warning (`no-reviewer-config`) rather than a hard failure. The JSON sibling at `rd/third-party-review-<rid>.json` carries the schema-validated ReviewerEnvelope (no free-form LLM JSON); the rid is part of both filenames so two slices in one session do not collide, and the bare location is accepted as the legacy tier. v2.14.0 ships as a soft-warning prereq (1-minor-release back-compat window); v2.15.0 will hard-fail when the file is absent AND `reviewer.providers` is configured.',
191
192
  mustContain: ['third-party-review', 'modelFamily'],
192
193
  backCompat: true,
193
194
  backCompatUntil: 'v2.15.0'
@@ -338,42 +339,6 @@ export function getPrerequisitesFor(role, newState, requestType) {
338
339
  const table = PREREQUISITES_BY_TYPE[requestType];
339
340
  return table[`${role}:${newState}`] ?? [];
340
341
  }
341
- function resolvePrerequisitePath(prerequisite, requestId) {
342
- return prerequisite.relativePath.replace('<rid>', requestId);
343
- }
344
- /**
345
- * Resolve a prerequisite to an on-disk path, tolerating the numbered filename
346
- * prefix that `request init` writes (e.g. `001-<rid>.md`). When the prerequisite
347
- * path contains `<rid>`, we accept either the legacy bare `<rid>.md` form or any
348
- * `NNN-<rid>.md` numbered form — mirroring the matcher in request-artifact-service.
349
- * Returns the matched absolute path, or null when nothing matches.
350
- */
351
- async function resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, requestId) {
352
- const relative = resolvePrerequisitePath(prerequisite, requestId);
353
- const exact = join(sessionRoot, relative);
354
- if (await pathExists(exact)) {
355
- return exact;
356
- }
357
- // Only `<rid>`-templated prerequisites can carry a numbered prefix; fixed paths
358
- // (e.g. rd/tech-doc.md) are matched exactly above.
359
- if (!prerequisite.relativePath.includes('<rid>')) {
360
- return null;
361
- }
362
- const dir = dirname(exact);
363
- // The on-disk suffix is the SLUG of this basename — the writer lowercases the
364
- // rid — so a mixed-case rid used to be reported absent with the file on disk.
365
- const suffix = `-${slugifyDescription(basename(exact).replace(/\.md$/, ''))}.md`;
366
- let entries;
367
- try {
368
- entries = await readdir(dir);
369
- }
370
- catch {
371
- // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
372
- return null;
373
- }
374
- const match = entries.find((name) => NUMBERED_PREFIX_RE.test(name) && name.endsWith(suffix));
375
- return match ? join(dir, match) : null;
376
- }
377
342
  export async function checkPrerequisites(options) {
378
343
  const requirements = getPrerequisitesFor(options.role, options.newState, options.requestType);
379
344
  if (requirements.length === 0) {
@@ -396,15 +361,14 @@ export async function checkPrerequisites(options) {
396
361
  // back-compat).
397
362
  // The sessionId is preserved in the artifact body's frontmatter for
398
363
  // human navigation; it is no longer a filesystem path key.
399
- const canonicalSessionRoot = options.sessionId !== undefined
400
- ? join(options.projectRoot, '.peaks', '_runtime', options.sessionId)
401
- : null;
402
- const legacySessionRoot = options.sessionId !== undefined ? join(options.projectRoot, '.peaks', options.sessionId) : null;
364
+ // The two tiers are built by the resolver module, so the commit gate and this
365
+ // transition probe the same directories.
366
+ const roots = sessionRootsFor(options.projectRoot, options.sessionId);
403
367
  const missing = [];
404
368
  const warnings = [];
405
369
  for (const prerequisite of requirements) {
406
370
  const relative = resolvePrerequisitePath(prerequisite, options.requestId);
407
- const absolute = await resolvePrerequisiteAbsolutePathWithFallback(canonicalSessionRoot, legacySessionRoot, prerequisite, options.requestId);
371
+ const absolute = await resolvePrerequisiteAbsolutePathWithFallback(roots.canonical, roots.legacy, prerequisite, options.requestId);
408
372
  if (absolute === null) {
409
373
  // A `backCompat` prerequisite downgrades a missing file to a warning, NOT
410
374
  // a hard failure; v2.14.0/v2.15.0 re-elevate it. The decision and the
@@ -414,13 +378,13 @@ export async function checkPrerequisites(options) {
414
378
  warnings.push(softWarning);
415
379
  continue;
416
380
  }
417
- missing.push({ path: relative, description: prerequisite.description });
381
+ missing.push({ kind: 'absent', path: relative, description: prerequisite.description });
418
382
  continue;
419
383
  }
420
384
  // Read handed over as a thunk: the no-body-contract guard lives with the check.
421
385
  const bodyViolations = await bodyViolationsIfDeclared(prerequisite, () => readFile(absolute, 'utf8'));
422
386
  for (const description of bodyViolations) {
423
- missing.push({ path: relative, description });
387
+ missing.push({ kind: 'body', path: relative, description });
424
388
  }
425
389
  }
426
390
  // own `gateEvidence` DECLARATION must be true — every path it names must
@@ -460,12 +424,12 @@ export async function checkPrerequisites(options) {
460
424
  // artifact with no declaration is refused here, not waved through — a
461
425
  // deleted section is the shed this arm exists to close.
462
426
  const { describeJudgedRefusal, verifyJudgedDeclaration } = await import('../audit-independent/judged-declaration-check.js');
463
- for (const refusal of verifyJudgedDeclaration({
427
+ for (const gap of verifyJudgedDeclaration({
464
428
  projectRoot: options.projectRoot,
465
429
  sessionId: options.sessionId,
466
430
  requestId: options.requestId
467
431
  }).refusals) {
468
- missing.push({ path: refusal.artifact, description: describeJudgedRefusal(refusal) });
432
+ missing.push({ kind: 'body', path: gap.artifact, description: describeJudgedRefusal(gap) });
469
433
  }
470
434
  }
471
435
  const result = { ok: missing.length === 0, missing, warnings };
@@ -481,55 +445,3 @@ export async function checkPrerequisites(options) {
481
445
  });
482
446
  return result;
483
447
  }
484
- /**
485
- * Resolve a prerequisite to an on-disk path, with a 2-tier fallback
486
- * dirs are no longer created):
487
- * 1. `<canonicalSessionRoot>/<relative>` (post-F3 canonical session
488
- * home, when `canonicalSessionRoot` is provided).
489
- * 2. `<legacySessionRoot>/<relative>` (pre-F3 legacy session home,
490
- * when `legacySessionRoot` is provided).
491
- * Tolerates the numbered filename prefix that `request init` writes
492
- * (e.g. `001-<rid>.md`) at every tier. Returns the matched absolute
493
- * path, or null when nothing matches.
494
- *
495
- * Back-compat: once neither primary session-root tier resolved, the
496
- * resolver walks `prerequisite.legacyRelativePaths` in declared order
497
- * and tries each at BOTH session roots before declaring the prereq
498
- * missing. This covers both artifacts that moved location
499
- * (`rd/security-review.md` → `audit/security.md`) and ones that later
500
- * gained a rid in the filename (`audit/security.md` →
501
- */
502
- async function resolvePrerequisiteAbsolutePathWithFallback(canonicalSessionRoot, legacySessionRoot, prerequisite, requestId) {
503
- const roots = [canonicalSessionRoot, legacySessionRoot];
504
- // First pass: try the primary relativePath at every root.
505
- for (const root of roots) {
506
- if (root === null)
507
- continue;
508
- const found = await resolvePrerequisiteAbsolutePath(root, prerequisite, requestId);
509
- if (found !== null)
510
- return found;
511
- }
512
- // Second pass: the single previous location, then any further older
513
- // ones, at every root — newest first, so a session that somehow holds
514
- // both a pre-rid and a v2.11.x file resolves to the newer shape.
515
- // Only the relativePath is swapped — the same numbered-prefix
516
- // tolerance applies via the shared resolver.
517
- const legacyTiers = [
518
- ...(prerequisite.legacyRelativePath !== undefined ? [prerequisite.legacyRelativePath] : []),
519
- ...(prerequisite.legacyRelativePaths ?? [])
520
- ];
521
- for (const legacy of legacyTiers) {
522
- const legacyPrereq = {
523
- ...prerequisite,
524
- relativePath: legacy
525
- };
526
- for (const root of roots) {
527
- if (root === null)
528
- continue;
529
- const found = await resolvePrerequisiteAbsolutePath(root, legacyPrereq, requestId);
530
- if (found !== null)
531
- return found;
532
- }
533
- }
534
- return null;
535
- }
@@ -8,5 +8,11 @@
8
8
  export declare const PRD_TEMPLATE_BODY = "## Goals\n\n- ...\n\n## Non-goals\n\n- ...\n\n## Preserved behavior\n\n- ...\n\n## Acceptance criteria\n\n- ... (browser-verifiable when frontend is in scope)\n\n## Frontend delta (only when target is frontend)\n\n- pages / routes / components / states / permissions / data deps / edge cases\n- \u5F85\u8054\u8C03\u6001: ...\n- API contracts pending: ...\n\n## Risks and open questions\n\n- ...\n\n";
9
9
  export declare const UI_TEMPLATE_BODY = "## Affected surfaces\n\n- pages / routes / components / modals / states (loading, empty, error, hover, focus, active, responsive)\n- explicit out-of-scope surfaces (do not modify)\n\n## UX flow and page states\n\n- entry points, primary flow, secondary flows, exit points\n- state machine per surface when state transitions matter\n\n## Visual constraints\n\n- typography pair: ...\n- palette: ...\n- density and motion intensity dials: ...\n- rejected generic patterns\n\n## Interaction constraints\n\n- keyboard, focus order, ARIA roles, gesture support, accessibility minima\n\n## UI regression seeds\n\n- list of visible regressions QA must check against the prior state\n\n## Browser evidence\n\n- sanitized observations only \u2014 no login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs with PII / SSO / MFA material\n\n";
10
10
  export declare const RD_TEMPLATE_BODY = "## Red-line scope\n\n- in-scope files / routes / API paths / data models\n- explicit out-of-scope surfaces (do not modify, mock, delete, or replace)\n\n## Standards preflight\n\n- peaks standards init/update --project <path> --dry-run output paths and status\n- planned application: apply | review-only | blocked\n\n## OpenSpec linkage (when openspec/ exists)\n\n- change-id: <openspec change id>\n- entry validate: peaks openspec validate <change-id> data.valid status\n- to-rd projection: peaks openspec to-rd <change-id> artifact path\n- exit validate (after implementation): status\n\n## Coverage status\n\n- current total UT coverage: <percent>\n- new/changed code coverage: <percent>\n- gate verdict: pass | legacy-accepted | blocked\n\n## Slice contract\n\n- slice id, functional boundary, pre-refactor behavior, target structure, unit-test requirements, acceptance checks, rollback plan, commit boundary\n\n## Implementation evidence\n\n- diff paths, test commands + outputs, code review findings + fixes, security review findings + fixes, dry-run output\n\n## MCP usage (when external docs lookup was used)\n\n- capabilityId / tool / sanitized args\n- artifact path of stored result\n- no secrets, no full network bodies\n\n";
11
- export declare const QA_TEMPLATE_BODY = "## Red-line boundary check\n\n- in-scope changes seen in the diff (match PRD + RD scope)\n- out-of-scope changes flagged (any extra file, route, mock, fixture, behavior)\n- verdict: clean | boundary-violation\n\n## OpenSpec exit gate (when openspec/ exists)\n\n- change-id: <id>\n- peaks openspec validate <id> data.valid: true | false\n- issues: ...\n\n## Acceptance checks\n\n- per-criterion: check method, result (pass | fail | blocked), evidence path\n\n## Mandatory validation gates\n\n- unit tests: command + pass/fail + coverage delta\n- API validation (when applicable): request paths exercised, evidence\n- browser E2E (when frontend): headed gstack/browse/dist/browse visible-browser confirmation, sanitized route/actions, console/network observations\n- browser-error feedback loop: page errors, console exceptions, broken network, hydration failures \u2192 return-to-RD evidence\n- security check: tool used, findings, fixes, unresolved risks\n- performance check: tool used, baseline vs after numbers when available\n- validation report path\n\n## Regression matrix\n\n- list of surfaces / API paths / browser flows checked\n- pass/fail per row\n\n## Browser evidence\n\n- sanitized observations only \u2014 no login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs with PII / SSO / MFA material\n\n## Verdict\n\n- overall: pass | return-to-rd | blocked\n\n";
11
+ /**
12
+ * QA body. The OpenSpec exit gate is conditional: when the target repository
13
+ * has no `openspec/changes/`, the prompt form's `<id>` tokens are unfillable
14
+ * and a pristine artifact fails lint before QA can start. The N/A form records
15
+ * the same fact without a placeholder. Every other section is unconditional.
16
+ */
17
+ export declare function renderQaTemplateBody(hasOpenspecChanges: boolean): string;
12
18
  export declare const SC_TEMPLATE_BODY = "## Change impact\n\n- modules / files / routes / data models touched\n- blast radius: local | cross-cutting | release-critical\n- rollback strategy\n\n## Commit boundaries\n\n- one commit per OpenSpec heading (when openspec/ exists)\n- otherwise: list of slice ids \u2192 commit message + scope\n\n## Artifact retention\n\n- prd artifact: ...\n- rd artifact: ...\n- qa artifact: ...\n- ui artifact: ... (when UI involved)\n- coverage evidence: ...\n- code review evidence: ...\n\n## Sync / authorization\n\n";
@@ -100,7 +100,14 @@ export const RD_TEMPLATE_BODY = `## Red-line scope
100
100
  - no secrets, no full network bodies
101
101
 
102
102
  `;
103
- export const QA_TEMPLATE_BODY = `## Red-line boundary check
103
+ /**
104
+ * QA body. The OpenSpec exit gate is conditional: when the target repository
105
+ * has no `openspec/changes/`, the prompt form's `<id>` tokens are unfillable
106
+ * and a pristine artifact fails lint before QA can start. The N/A form records
107
+ * the same fact without a placeholder. Every other section is unconditional.
108
+ */
109
+ export function renderQaTemplateBody(hasOpenspecChanges) {
110
+ return `## Red-line boundary check
104
111
 
105
112
  - in-scope changes seen in the diff (match PRD + RD scope)
106
113
  - out-of-scope changes flagged (any extra file, route, mock, fixture, behavior)
@@ -108,10 +115,13 @@ export const QA_TEMPLATE_BODY = `## Red-line boundary check
108
115
 
109
116
  ## OpenSpec exit gate (when openspec/ exists)
110
117
 
111
- - change-id: <id>
118
+ ${hasOpenspecChanges
119
+ ? `- change-id: <id>
112
120
  - peaks openspec validate <id> data.valid: true | false
113
121
  - issues: ...
114
-
122
+ `
123
+ : `- N/A — openspec/changes/ is absent; no validate run
124
+ `}
115
125
  ## Acceptance checks
116
126
 
117
127
  - per-criterion: check method, result (pass | fail | blocked), evidence path
@@ -140,6 +150,7 @@ export const QA_TEMPLATE_BODY = `## Red-line boundary check
140
150
  - overall: pass | return-to-rd | blocked
141
151
 
142
152
  `;
153
+ }
143
154
  export const SC_TEMPLATE_BODY = `## Change impact
144
155
 
145
156
  - modules / files / routes / data models touched
@@ -6,6 +6,11 @@ import type { RequestType } from './artifact-prerequisites.js';
6
6
  * back-compat with external callers.
7
7
  */
8
8
  export type RequestArtifactRole = 'prd' | 'ui' | 'rd' | 'qa' | 'sc';
9
+ /** What every role's render needs beyond the request's own identity. */
10
+ export type RenderTemplateContext = {
11
+ requestType: RequestType | null;
12
+ projectRoot: string;
13
+ };
9
14
  /**
10
15
  * Handoff path helpers.
11
16
  *
@@ -26,4 +31,4 @@ export declare function formatHandoffPath(sessionId: string, role: string, reque
26
31
  export declare function formatCommitBoundaryPath(sessionId: string, requestId: string): string;
27
32
  /** Canonical path for the txt skill-usage lessons log under a session scope. */
28
33
  export declare function formatSkillUsageLessonsPath(sessionId: string): string;
29
- export declare function renderTemplate(role: RequestArtifactRole, requestId: string, sessionId: string, changeSlug: string, timestamp: string, requestType: RequestType | null): string;
34
+ export declare function renderTemplate(role: RequestArtifactRole, requestId: string, sessionId: string, changeSlug: string, timestamp: string, context: RenderTemplateContext): string;
@@ -1,4 +1,6 @@
1
- import { PRD_TEMPLATE_BODY, UI_TEMPLATE_BODY, RD_TEMPLATE_BODY, QA_TEMPLATE_BODY, SC_TEMPLATE_BODY } from './artifact-template-bodies.js';
1
+ import { existsSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { PRD_TEMPLATE_BODY, UI_TEMPLATE_BODY, RD_TEMPLATE_BODY, renderQaTemplateBody, SC_TEMPLATE_BODY } from './artifact-template-bodies.js';
2
4
  /**
3
5
  * Handoff path helpers.
4
6
  *
@@ -102,7 +104,7 @@ ${renderTypeLine(requestType)}
102
104
  - state: draft
103
105
  `);
104
106
  }
105
- function renderQaTemplate(requestId, _sessionId, sessionId, timestamp, requestType) {
107
+ function renderQaTemplate(requestId, _sessionId, sessionId, timestamp, requestType, hasOpenspecChanges) {
106
108
  return (`# QA Request ${requestId}
107
109
 
108
110
  - session: ${sessionId}
@@ -111,7 +113,7 @@ function renderQaTemplate(requestId, _sessionId, sessionId, timestamp, requestTy
111
113
  - linked-ui: ${formatHandoffPath(sessionId, 'ui', requestId)} (when UI involved)
112
114
  ${renderTypeLine(requestType)}
113
115
  ` +
114
- QA_TEMPLATE_BODY +
116
+ renderQaTemplateBody(hasOpenspecChanges) +
115
117
  `## Status
116
118
 
117
119
  - created: ${timestamp}
@@ -150,7 +152,8 @@ ${renderTypeLine(requestType)}
150
152
  - state: draft
151
153
  `);
152
154
  }
153
- export function renderTemplate(role, requestId, sessionId, changeSlug, timestamp, requestType) {
155
+ export function renderTemplate(role, requestId, sessionId, changeSlug, timestamp, context) {
156
+ const { requestType } = context;
154
157
  switch (role) {
155
158
  case 'prd':
156
159
  return renderPrdTemplate(requestId, sessionId, changeSlug, timestamp, requestType);
@@ -159,7 +162,7 @@ export function renderTemplate(role, requestId, sessionId, changeSlug, timestamp
159
162
  case 'rd':
160
163
  return renderRdTemplate(requestId, sessionId, changeSlug, timestamp, requestType);
161
164
  case 'qa':
162
- return renderQaTemplate(requestId, sessionId, changeSlug, timestamp, requestType);
165
+ return renderQaTemplate(requestId, sessionId, changeSlug, timestamp, requestType, existsSync(join(context.projectRoot, 'openspec', 'changes')));
163
166
  case 'sc':
164
167
  return renderScTemplate(requestId, sessionId, changeSlug, timestamp, requestType);
165
168
  }
@@ -0,0 +1,66 @@
1
+ /**
2
+ * The commit-leg gate for back-compat windows that have CLOSED.
3
+ *
4
+ * `peaks request transition` stays soft on purpose: `missingPrerequisiteWarning`
5
+ * reports a closed window as a warning so the workflow can still reach
6
+ * `qa-handoff` and record the skip. This module is the other boundary. It
7
+ * refuses a closed, missing window unless the tracked acceptance list carries a
8
+ * current entry for that exact `path` + `until` pair.
9
+ *
10
+ * A MISSING LIST IS A FAILURE, NOT AN OPT-OUT. The commit leg is the hard
11
+ * boundary the product asked for, so absence is reported like any other
12
+ * malformed list. The remediation names the seeding path — `peaks workspace
13
+ * init` writes the tracked list — and the LLM performs it; the user speaks or
14
+ * picks, and never hand-authors JSON.
15
+ *
16
+ * WHO EDITS THE LIST. The LLM does, on the user's behalf: the user speaks or
17
+ * picks, and the tracked JSON is a reviewed diff the LLM authors. No message
18
+ * here asks a human to hand-author JSON.
19
+ *
20
+ * WHY THE GATE LIVES HERE AND NOT IN `artifact-prerequisites.ts`. That file is
21
+ * over the file-size cap and a change may only shrink it, so this is the same
22
+ * split its `prerequisite-checks.ts` sibling took. The public name is still
23
+ * exported from `artifact-prerequisites.ts`; that module re-exports it, so
24
+ * every caller keeps one import site.
25
+ *
26
+ * ONE RESOLVER, ONE COMPARATOR. Path resolution and the session-root tiers are
27
+ * the ones the transition uses, and window comparison is
28
+ * `compareReleaseVersions`, so the two legs cannot disagree about whether an
29
+ * artifact exists or where a boundary sits.
30
+ */
31
+ import type { RequestType } from './artifact-prerequisites.js';
32
+ /** The seeded list a new project receives, and the reason each window is
33
+ * accepted. `reviewBy` is DERIVED at seed time from the installed release, so a
34
+ * project initialized on a release boundary receives a current list rather
35
+ * than an already-expired one; it is bounded by the same two-minor cap the gate
36
+ * enforces. */
37
+ export declare function backcompatAcceptanceSeed(installedVersion?: string): string;
38
+ /**
39
+ * Seed the tracked acceptance list for a project that has none. Idempotent: an
40
+ * existing file is never overwritten, so a project's reviewed entries survive
41
+ * every `peaks workspace init`. Called by `initWorkspace`.
42
+ */
43
+ export declare function seedBackCompatAcceptance(projectRoot: string): void;
44
+ export type ExpiredBackCompatCommitGateOptions = {
45
+ projectRoot: string;
46
+ /** The evidence scope. Without one no artifact resolves, so every closed
47
+ * window is judged missing — the fail-closed answer. */
48
+ sessionId?: string | undefined;
49
+ requestType: RequestType;
50
+ requestId: string;
51
+ /** Injected so a caller can drive both sides of a window boundary; defaults
52
+ * to the release this build ships. */
53
+ installedVersion?: string | undefined;
54
+ };
55
+ /**
56
+ * The COMMIT-LEG verdict on back-compat windows that have closed.
57
+ *
58
+ * The table is read through the same accessor the transition uses, and the
59
+ * import is dynamic because `artifact-prerequisites.ts` re-exports this module:
60
+ * a static edge back would close a runtime import cycle. Same idiom, same
61
+ * reason, as the lazy producer imports in `request-commands.ts`.
62
+ */
63
+ export declare function checkExpiredBackCompatCommitGate(options: ExpiredBackCompatCommitGateOptions): Promise<{
64
+ violations: string[];
65
+ warnings: string[];
66
+ }>;
@@ -0,0 +1,222 @@
1
+ /**
2
+ * The commit-leg gate for back-compat windows that have CLOSED.
3
+ *
4
+ * `peaks request transition` stays soft on purpose: `missingPrerequisiteWarning`
5
+ * reports a closed window as a warning so the workflow can still reach
6
+ * `qa-handoff` and record the skip. This module is the other boundary. It
7
+ * refuses a closed, missing window unless the tracked acceptance list carries a
8
+ * current entry for that exact `path` + `until` pair.
9
+ *
10
+ * A MISSING LIST IS A FAILURE, NOT AN OPT-OUT. The commit leg is the hard
11
+ * boundary the product asked for, so absence is reported like any other
12
+ * malformed list. The remediation names the seeding path — `peaks workspace
13
+ * init` writes the tracked list — and the LLM performs it; the user speaks or
14
+ * picks, and never hand-authors JSON.
15
+ *
16
+ * WHO EDITS THE LIST. The LLM does, on the user's behalf: the user speaks or
17
+ * picks, and the tracked JSON is a reviewed diff the LLM authors. No message
18
+ * here asks a human to hand-author JSON.
19
+ *
20
+ * WHY THE GATE LIVES HERE AND NOT IN `artifact-prerequisites.ts`. That file is
21
+ * over the file-size cap and a change may only shrink it, so this is the same
22
+ * split its `prerequisite-checks.ts` sibling took. The public name is still
23
+ * exported from `artifact-prerequisites.ts`; that module re-exports it, so
24
+ * every caller keeps one import site.
25
+ *
26
+ * ONE RESOLVER, ONE COMPARATOR. Path resolution and the session-root tiers are
27
+ * the ones the transition uses, and window comparison is
28
+ * `compareReleaseVersions`, so the two legs cannot disagree about whether an
29
+ * artifact exists or where a boundary sits.
30
+ */
31
+ import { dirname, join } from 'node:path';
32
+ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
33
+ import { readFile } from 'node:fs/promises';
34
+ import { pathExists } from 'peaks-loop-shared/fs';
35
+ import { CLI_VERSION } from 'peaks-loop-shared/version';
36
+ import { isUnsafePathInput } from '../../shared/path-safety.js';
37
+ import { compareReleaseVersions, missingPrerequisiteWarning } from './prerequisite-checks.js';
38
+ import { resolvePrerequisiteAbsolutePathWithFallback, sessionRootsFor } from './prerequisite-path-resolver.js';
39
+ /** The one tracked acceptance list. Adding an entry is a reviewed diff the LLM
40
+ * authors on the user's behalf; no source file keeps a second copy. */
41
+ const BACKCOMPAT_ACCEPTANCE_PATH = '.peaks/lint/backcompat-expired-acceptance.json';
42
+ /** Every field an entry must carry, non-empty. `reviewBy` is the one that makes
43
+ * the list expire, so an entry without it is malformed rather than permissive. */
44
+ const REQUIRED_ACCEPTANCE_FIELDS = ['path', 'until', 'reason', 'reviewBy'];
45
+ /** How many minor releases ahead of the installed build a `reviewBy` may sit.
46
+ * A list entry that jumps years ahead accepts without a near-term review, which
47
+ * is the same "forever" defect in a new field. */
48
+ const REVIEW_CAP_MINORS = 2;
49
+ /** The seeded list a new project receives, and the reason each window is
50
+ * accepted. `reviewBy` is DERIVED at seed time from the installed release, so a
51
+ * project initialized on a release boundary receives a current list rather
52
+ * than an already-expired one; it is bounded by the same two-minor cap the gate
53
+ * enforces. */
54
+ export function backcompatAcceptanceSeed(installedVersion = CLI_VERSION) {
55
+ const reviewBy = reviewCapFor(installedVersion);
56
+ return JSON.stringify({
57
+ version: 1,
58
+ note: "Expired backCompat windows accepted for the commit leg. The LLM edits this file on the user's behalf (the user only speaks or picks); adding an entry is a reviewed diff and reviewBy is enforced against a two-minor cap.",
59
+ accepted: [
60
+ {
61
+ path: 'mut/mut-report.json',
62
+ until: 'v2.14.0',
63
+ reason: 'No producer in this build: peaks mut * requires --input-sig (TACT.sig), and peaks tact read is not a registered command (backlog §9.2).',
64
+ reviewBy
65
+ },
66
+ {
67
+ path: 'rd/third-party-review-<rid>.md',
68
+ until: 'v2.15.0',
69
+ reason: 'No reviewer configured: peaks reviewer status reports no-reviewer-config, and the prerequisite table soft-skips this artifact in that state. Documented deviation: this commit-leg gate does not re-evaluate the reviewer.providers conditional, so the window is accepted here regardless of that config.',
70
+ reviewBy
71
+ }
72
+ ]
73
+ }, null, 2);
74
+ }
75
+ function isBackCompatAcceptance(value) {
76
+ if (value === null || typeof value !== 'object' || Array.isArray(value))
77
+ return false;
78
+ const entry = value;
79
+ return REQUIRED_ACCEPTANCE_FIELDS.every((field) => typeof entry[field] === 'string' && entry[field] !== '');
80
+ }
81
+ /**
82
+ * The tracked acceptances, or why they cannot be read.
83
+ *
84
+ * ABSENT is a problem, not an opt-out: the commit leg is the hard boundary, so
85
+ * a project that lacks the list is told to seed it. The remediation names the
86
+ * LLM as the actor — `peaks workspace init` seeds the file, and the user never
87
+ * hand-authors JSON.
88
+ */
89
+ async function loadBackCompatAcceptances(projectRoot) {
90
+ const absolute = join(projectRoot, '.peaks', 'lint', 'backcompat-expired-acceptance.json');
91
+ if (!(await pathExists(absolute))) {
92
+ return {
93
+ accepted: [],
94
+ problem: `${BACKCOMPAT_ACCEPTANCE_PATH} is absent. Ask the LLM to run \`peaks workspace init\` to seed the tracked list (the LLM edits it on the user's behalf), or to produce the missing artifacts`
95
+ };
96
+ }
97
+ const unreadable = (why) => ({
98
+ accepted: [],
99
+ problem: `${BACKCOMPAT_ACCEPTANCE_PATH} ${why}, so expired back-compat windows cannot be judged`
100
+ });
101
+ let raw;
102
+ try {
103
+ raw = await readFile(absolute, 'utf8');
104
+ }
105
+ catch {
106
+ return unreadable('cannot be read');
107
+ }
108
+ let parsed;
109
+ try {
110
+ parsed = JSON.parse(raw);
111
+ }
112
+ catch {
113
+ return unreadable('is not valid JSON');
114
+ }
115
+ if (parsed === null || typeof parsed !== 'object') {
116
+ return unreadable('is not a JSON object');
117
+ }
118
+ const accepted = parsed.accepted;
119
+ if (!Array.isArray(accepted) || !accepted.every(isBackCompatAcceptance)) {
120
+ return unreadable('does not carry an "accepted" array of path/until/reason/reviewBy entries');
121
+ }
122
+ return { accepted, problem: null };
123
+ }
124
+ /**
125
+ * Seed the tracked acceptance list for a project that has none. Idempotent: an
126
+ * existing file is never overwritten, so a project's reviewed entries survive
127
+ * every `peaks workspace init`. Called by `initWorkspace`.
128
+ */
129
+ export function seedBackCompatAcceptance(projectRoot) {
130
+ const absolute = join(projectRoot, '.peaks', 'lint', 'backcompat-expired-acceptance.json');
131
+ if (existsSync(absolute))
132
+ return;
133
+ mkdirSync(dirname(absolute), { recursive: true });
134
+ writeFileSync(absolute, `${backcompatAcceptanceSeed()}\n`, 'utf8');
135
+ }
136
+ /** Every `backCompat` requirement whose window has closed while its artifact is
137
+ * absent. A present artifact is excluded: its body checks belong to the
138
+ * transition, and an artifact that exists needs no acceptance. */
139
+ async function closedBackCompatWindows(requirements, installedVersion, requestId, roots) {
140
+ const closed = [];
141
+ for (const prerequisite of requirements) {
142
+ const until = prerequisite.backCompatUntil;
143
+ const relative = prerequisite.relativePath;
144
+ const aliases = [prerequisite.legacyRelativePath, ...(prerequisite.legacyRelativePaths ?? [])];
145
+ const softWarning = missingPrerequisiteWarning(prerequisite, relative, installedVersion);
146
+ if (until === undefined || softWarning?.expiredWindow === undefined)
147
+ continue;
148
+ const absolute = await resolvePrerequisiteAbsolutePathWithFallback(roots.canonical, roots.legacy, prerequisite, requestId);
149
+ if (absolute === null)
150
+ closed.push({ path: relative, until, aliases });
151
+ }
152
+ return closed;
153
+ }
154
+ /** The furthest `reviewBy` this build accepts, as a release string. */
155
+ function reviewCapFor(installedVersion) {
156
+ const [major, minor] = installedVersion.replace(/^v/i, '').split(/[.-]/);
157
+ const minorNumber = Number.parseInt(minor ?? '0', 10);
158
+ return `v${major ?? '0'}.${(Number.isNaN(minorNumber) ? 0 : minorNumber) + REVIEW_CAP_MINORS}.0`;
159
+ }
160
+ /** The accepted entry that covers `window`, or the violation saying why none
161
+ * does.
162
+ *
163
+ * `reviewBy` is exclusive (an entry reviewed for this release has reached its
164
+ * target) and capped (`reviewBy` may sit at most two minors ahead), so a list
165
+ * that only grows or that jumps far ahead cannot keep accepting. */
166
+ function judgeClosedWindow(list, window, installedVersion) {
167
+ const paths = [window.path, ...window.aliases];
168
+ const entry = list.accepted.find((candidate) => paths.includes(candidate.path) && candidate.until === window.until);
169
+ if (entry === undefined) {
170
+ return {
171
+ violation: `expired back-compat window and no current acceptance: ${window.path} — ${window.until} (installed ${installedVersion}); ask the LLM to add an entry to ${BACKCOMPAT_ACCEPTANCE_PATH} with a reason and a future reviewBy (the LLM edits the tracked file on the user's behalf), or produce the artifact`
172
+ };
173
+ }
174
+ if (compareReleaseVersions(installedVersion, entry.reviewBy) >= 0) {
175
+ return {
176
+ violation: `expired back-compat window and no current acceptance: ${window.path} — ${window.until} (installed ${installedVersion}); reviewBy ${entry.reviewBy} has been reached — ask the LLM to renew it with a future reviewBy or produce the artifact`
177
+ };
178
+ }
179
+ const cap = reviewCapFor(installedVersion);
180
+ if (compareReleaseVersions(entry.reviewBy, cap) > 0) {
181
+ return {
182
+ violation: `back-compat acceptance reviewBy is beyond the review cap: ${window.path} — ${window.until}; reviewBy ${entry.reviewBy} is more than ${REVIEW_CAP_MINORS} minor releases ahead of installed ${installedVersion} (cap ${cap}) — ask the LLM to lower reviewBy to ${cap} or earlier`
183
+ };
184
+ }
185
+ return { accepted: entry };
186
+ }
187
+ /**
188
+ * The COMMIT-LEG verdict on back-compat windows that have closed.
189
+ *
190
+ * The table is read through the same accessor the transition uses, and the
191
+ * import is dynamic because `artifact-prerequisites.ts` re-exports this module:
192
+ * a static edge back would close a runtime import cycle. Same idiom, same
193
+ * reason, as the lazy producer imports in `request-commands.ts`.
194
+ */
195
+ export async function checkExpiredBackCompatCommitGate(options) {
196
+ const { getPrerequisitesFor } = await import('./artifact-prerequisites.js');
197
+ const installedVersion = options.installedVersion ?? CLI_VERSION;
198
+ const softRequirements = getPrerequisitesFor('rd', 'qa-handoff', options.requestType).filter((prerequisite) => prerequisite.backCompat === true);
199
+ if (softRequirements.length === 0)
200
+ return { violations: [], warnings: [] };
201
+ // Same sink guard as `checkPrerequisites`: the session id is joined into both
202
+ // roots below, so an unsafe value is refused where it would be used.
203
+ if (options.sessionId !== undefined && isUnsafePathInput(options.sessionId)) {
204
+ throw new Error(`Invalid session id: ${options.sessionId} (must be a single path segment)`);
205
+ }
206
+ const roots = sessionRootsFor(options.projectRoot, options.sessionId);
207
+ const closed = await closedBackCompatWindows(softRequirements, installedVersion, options.requestId, roots);
208
+ if (closed.length === 0)
209
+ return { violations: [], warnings: [] };
210
+ const list = await loadBackCompatAcceptances(options.projectRoot);
211
+ const violations = list.problem === null ? [] : [list.problem];
212
+ const warnings = [];
213
+ for (const window of closed) {
214
+ const decision = judgeClosedWindow(list, window, installedVersion);
215
+ if ('accepted' in decision) {
216
+ warnings.push(`accepted expired back-compat window: ${window.path} until ${window.until} (installed ${installedVersion}); reviewBy ${decision.accepted.reviewBy} — ${decision.accepted.reason}`);
217
+ continue;
218
+ }
219
+ violations.push(decision.violation);
220
+ }
221
+ return { violations, warnings };
222
+ }