peaks-loop 4.1.6 → 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 (25) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +31 -0
  3. package/dist/cli/commands/core/skill-registry-commands.js +9 -4
  4. package/dist/services/artifacts/artifact-prerequisites.d.ts +1 -0
  5. package/dist/services/artifacts/artifact-prerequisites.js +9 -97
  6. package/dist/services/artifacts/backcompat-acceptance.d.ts +66 -0
  7. package/dist/services/artifacts/backcompat-acceptance.js +220 -0
  8. package/dist/services/artifacts/prerequisite-checks.d.ts +8 -0
  9. package/dist/services/artifacts/prerequisite-checks.js +7 -2
  10. package/dist/services/artifacts/prerequisite-path-resolver.d.ts +39 -0
  11. package/dist/services/artifacts/prerequisite-path-resolver.js +110 -0
  12. package/dist/services/doctor/doctor-service/checks/backcompat-acceptance.d.ts +15 -0
  13. package/dist/services/doctor/doctor-service/checks/backcompat-acceptance.js +53 -0
  14. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +38 -0
  15. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +243 -0
  16. package/dist/services/doctor/doctor-service/plugin-registry.js +4 -0
  17. package/dist/services/doctor/doctor-service/types.d.ts +12 -0
  18. package/dist/services/workflow/pipeline-verify-gate-support.d.ts +4 -1
  19. package/dist/services/workflow/pipeline-verify-gate-support.js +8 -79
  20. package/dist/services/workflow/pipeline-verify-rd-phase.d.ts +67 -0
  21. package/dist/services/workflow/pipeline-verify-rd-phase.js +122 -0
  22. package/dist/services/workflow/pipeline-verify-service.js +16 -17
  23. package/dist/services/workspace/workspace-service.js +4 -16
  24. package/package.json +5 -5
  25. package/schemas/doctor-report.schema.json +2 -2
@@ -0,0 +1,67 @@
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
+ import type { RequestType } from '../artifacts/artifact-prerequisites.js';
27
+ import type { PipelineGate } from './pipeline-verify-types.js';
28
+ /**
29
+ * Every RD evidence gate the checker can build, each naming the contract path it
30
+ * stands for. The NAME and DESCRIPTION are the checker's own — `peaks workflow
31
+ * skip` takes gate names and the violation text prints the description — while
32
+ * the PATH is the contract's, and it is the half that makes a gate list
33
+ * derivable instead of restated beside the tables it is supposed to be read from.
34
+ */
35
+ export declare const RD_EVIDENCE_GATES: ReadonlyArray<{
36
+ name: string;
37
+ description: string;
38
+ relativePath: string;
39
+ }>;
40
+ /** What a type's table carries for one probe name, or null when it carries none. */
41
+ export type RdEvidenceLookup = (requestType: RequestType, relativePath: string) => readonly string[] | null;
42
+ /**
43
+ * The RD gate list for one type: the request gate, then one gate per evidence
44
+ * row this type's table carries.
45
+ *
46
+ * `lookup` is a parameter rather than a direct call so an arm can drive the
47
+ * derivation with a contract of its own. That is the only way to show a null
48
+ * drops a gate: a check that only ever runs against the table it already agrees
49
+ * with cannot be observed to drop anything.
50
+ */
51
+ export declare function deriveRdGates(requestType: RequestType, lookup: RdEvidenceLookup): PipelineGate[];
52
+ /**
53
+ * The production binding: the type's own `rd:qa-handoff` table is the lookup.
54
+ *
55
+ * `lookup` is an optional overrides seam, not configuration: the arm drives this
56
+ * binding with a synthetic contract so a restatement inside the default cannot
57
+ * stay green. Production passes one argument and gets the real table.
58
+ */
59
+ export declare function rdGatesForType(requestType: RequestType, lookup?: RdEvidenceLookup): PipelineGate[];
60
+ /**
61
+ * The contract path the gate named `gateName` stands for.
62
+ *
63
+ * `resolveRdEvidencePaths` iterates exactly the gate list this module built, so
64
+ * a miss would be a name invented outside the table; it refuses by name rather
65
+ * than dereferencing nothing.
66
+ */
67
+ export declare function rdEvidenceProbe(gateName: string): string;
@@ -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
+ }
@@ -15,6 +15,7 @@ import { markQaRequestGate, typeRequiresQaPhase } from './pipeline-verify-qa-pha
15
15
  import { NO_SESSION_SCOPE, mayHonourSkip, resolveRequestType } from './request-type-resolution.js';
16
16
  import { readSkipState } from './workflow-state-store.js';
17
17
  import { getSessionIdCanonical } from '../session/session-manager.js';
18
+ import { checkExpiredBackCompatCommitGate } from '../artifacts/artifact-prerequisites.js';
18
19
  import { listPromotionExempt, listUnpromotedFeedback } from '../feedback/feedback-promotion-service.js';
19
20
  import { QA_COMPLETE_STATES, RD_QA_HANDOFF_STATES, extractState, findRequestFile, qaGatesForType, rdGatesForType, resolveQaEvidencePaths, resolveRdEvidencePaths } from './pipeline-verify-gate-support.js';
20
21
  export async function verifyPipeline(options) {
@@ -126,6 +127,14 @@ export async function verifyPipeline(options) {
126
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);
@@ -230,6 +236,7 @@ export async function verifyPipeline(options) {
230
236
  allRdGatesPassed &&
231
237
  allQaGatesPassed &&
232
238
  allFeedbackGatesPassed &&
239
+ backcompatExpiry.violations.length === 0 &&
233
240
  RD_QA_HANDOFF_STATES.has(rdState);
234
241
  // 'suffixed' when the contract's current path served the file and 'legacy'
235
242
  // when the deprecated fallback did; 'none' if neither gate passed.
@@ -251,17 +258,9 @@ export async function verifyPipeline(options) {
251
258
  : 'suffixed';
252
259
  const gateC = allQaGatesPassed ? 'pass' : 'fail';
253
260
  const gateH = allFeedbackGatesPassed ? 'pass' : 'fail';
254
- // every gate resolved on the canonical path; `false` when at least
255
- // one fell back to a legacy form. QA / TXT surface the value so the
256
- // user knows the legacy content must be moved into the canonical
257
- // location (the legacy `peaks workspace migrate-change-scope` helper
258
- // was removed in v2.19.0; use `peaks workspace migrate` to relocate
259
- // misplaced content).
260
- //
261
- // If NO evidence file resolved (e.g. all gates missing), the field is
262
- // `true` — there is nothing non-canonical to worry about. If every
263
- // resolved gate was skipped via `peaks workflow skip`, the field is
264
- // `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`.
265
264
  const allGatesSkipped = [...rdGates, ...qaGates].every((g) => g.status === 'skipped');
266
265
  const usedCanonicalPath = !anyEvidenceResolved || allGatesSkipped || allResolvedPathsCanonical;
267
266
  return {
@@ -7,6 +7,7 @@ import { updateCallerBindingSessionId } from '../session/caller-binding-service.
7
7
  import { resolveCallerProjection } from '../session/resolve-caller-id.js';
8
8
  import { normalizePath } from '../../shared/path-utils.js';
9
9
  import { assertWritableProjectRoot } from '../config/config-safety.js';
10
+ import { seedBackCompatAcceptance } from '../artifacts/backcompat-acceptance.js';
10
11
  /**
11
12
  * calling process's own per-caller binding at the session id this init just
12
13
  * bound. `getSessionIdCanonical` reads `callers/<callerId>.json` FIRST, so a
@@ -46,22 +47,6 @@ function listPeaksRuntimeSiblings(projectRoot) {
46
47
  return [];
47
48
  }
48
49
  }
49
- /**
50
- * `.peaks/_runtime/` so the legacy sibling-dir guard can enumerate
51
- * date-stamped residue dirs at the runtime layer. Returns `[]` when
52
- * the `.peaks/_runtime/` dir does not exist.
53
- */
54
- function listRuntimeSiblings(projectRoot) {
55
- const runtimeDir = join(projectRoot, '.peaks', '_runtime');
56
- if (!existsSync(runtimeDir))
57
- return [];
58
- try {
59
- return readdirSync(runtimeDir);
60
- }
61
- catch {
62
- return [];
63
- }
64
- }
65
50
  /**
66
51
  * basename matches the auto-generated session-id shape
67
52
  * `YYYY-MM-DD-<slug>` (the v2.8.3 hard-ban target). Bare dates
@@ -365,6 +350,9 @@ export async function initWorkspace(options) {
365
350
  // last regenerate this project", not "when did the bytes change". See
366
351
  // `generated-artifacts-stamp.ts`.
367
352
  writeGeneratedArtifactsStamp(options.projectRoot);
353
+ // The commit-leg expiry gate is opt-in by the presence of this tracked list;
354
+ // seeding it here (idempotently) is how a project opts in.
355
+ seedBackCompatAcceptance(options.projectRoot);
368
356
  return {
369
357
  sessionId: options.sessionId,
370
358
  sessionRoot,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.6",
3
+ "version": "4.1.7",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -129,10 +129,10 @@
129
129
  "picomatch": "4.0.4",
130
130
  "yaml": "^2.9.0",
131
131
  "zod": "^4.4.3",
132
- "peaks-loop-internal-runtime": "0.0.46",
133
- "peaks-loop-mut": "0.1.60",
134
- "peaks-loop-shared": "0.0.95",
135
- "peaks-loop-shared-channel": "0.0.63"
132
+ "peaks-loop-internal-runtime": "0.0.47",
133
+ "peaks-loop-mut": "0.1.61",
134
+ "peaks-loop-shared": "0.0.96",
135
+ "peaks-loop-shared-channel": "0.0.64"
136
136
  },
137
137
  "devDependencies": {
138
138
  "@changesets/cli": "2.31.1",
@@ -13,8 +13,8 @@
13
13
  "properties": {
14
14
  "id": {
15
15
  "type": "string",
16
- "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability|build|integration|L3):[A-Za-z0-9][A-Za-z0-9._-]*$",
17
- "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness/workspace), statusline:<topic> (out-of-band Claude Code statusLine — install/runtime), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version), build:<topic> (build-hygiene checks — dist/source version consistency), integration:<name> (third-party integration probe — e.g. gateguard-fact-force PreToolUse hook conflict on .peaks/**)."
16
+ "pattern": "^(?:(?:skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability|build|integration|L3):[A-Za-z0-9][A-Za-z0-9._-]*|skills:[A-Za-z0-9][A-Za-z0-9._-]*(?::[A-Za-z0-9][A-Za-z0-9._-]*)+)$",
17
+ "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness/workspace), skills:<topic>:<ide>:<skill> (canonical-store vs IDE skill-tree parity — a file present on one side and absent on the other; topic store means the canonical store is absent), statusline:<topic> (out-of-band Claude Code statusLine — install/runtime), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version), build:<topic> (build-hygiene checks — dist/source version consistency), integration:<name> (third-party integration probe — e.g. gateguard-fact-force PreToolUse hook conflict on .peaks/**)."
18
18
  },
19
19
  "ok": { "type": "boolean" },
20
20
  "message": { "type": "string", "minLength": 1 }