peaks-loop 4.1.23 → 4.1.25

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 (66) hide show
  1. package/.claude-plugin/marketplace.json +12 -2
  2. package/CHANGELOG.md +188 -0
  3. package/dist/cli/commands/code-auto-compact-command.js +19 -1
  4. package/dist/cli/commands/code-gate-step-08-command.js +103 -105
  5. package/dist/cli/commands/code-gate-step-08-remedy.d.ts +10 -2
  6. package/dist/cli/commands/code-gate-step-08-remedy.js +11 -3
  7. package/dist/cli/commands/gate-commands-enforce.d.ts +14 -8
  8. package/dist/cli/commands/gate-commands-enforce.js +31 -24
  9. package/dist/cli/commands/observability-commands-session-row.d.ts +48 -0
  10. package/dist/cli/commands/observability-commands-session-row.js +201 -0
  11. package/dist/cli/commands/observability-commands.js +2 -0
  12. package/dist/services/artifacts/prerequisite-path-census.d.ts +8 -3
  13. package/dist/services/artifacts/prerequisite-path-census.js +30 -9
  14. package/dist/services/artifacts/prerequisite-path-resolver.js +32 -2
  15. package/dist/services/hooks/output.d.ts +35 -1
  16. package/dist/services/hooks/output.js +39 -1
  17. package/dist/services/observability/aggregation.js +2 -1
  18. package/dist/services/observability/hotspot-shared.d.ts +7 -12
  19. package/dist/services/observability/hotspot-shared.js +18 -13
  20. package/dist/services/observability/near-miss-difference.js +4 -1
  21. package/dist/services/observability/near-miss.js +9 -2
  22. package/dist/services/observability/owner-skill-map.js +23 -3
  23. package/dist/services/observability/repair-cycle-metric.js +6 -3
  24. package/dist/services/skills/presence-role.js +9 -2
  25. package/dist/services/standards/loop-engineering-readiness-lint.d.ts +15 -1
  26. package/dist/services/standards/loop-engineering-readiness-lint.js +27 -9
  27. package/dist/shared/incrementing-number.d.ts +57 -0
  28. package/dist/shared/incrementing-number.js +13 -0
  29. package/dist/skills/peaks-maker/index.js +43 -30
  30. package/output-styles/peaks-skill-swarm.md +2 -2
  31. package/package.json +7 -6
  32. package/scripts/install-skills-bundles.mjs +6 -1
  33. package/scripts/install-skills.mjs +10 -1
  34. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  35. package/skills/bee/peaks-prd/SKILL.md +1 -1
  36. package/skills/bee/peaks-qa/SKILL.md +1 -1
  37. package/skills/bee/peaks-rd/SKILL.md +1 -1
  38. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  39. package/skills/bee/peaks-sc/SKILL.md +1 -1
  40. package/skills/bee/peaks-security-audit/SKILL.md +1 -1
  41. package/skills/bee/peaks-txt/SKILL.md +1 -1
  42. package/skills/bee/peaks-ui/SKILL.md +1 -1
  43. package/skills/peaks-audit/SKILL.md +1 -1
  44. package/skills/peaks-code/SKILL.md +1 -1
  45. package/skills/peaks-content/SKILL.md +1 -1
  46. package/skills/peaks-doctor/SKILL.md +1 -1
  47. package/skills/peaks-final-review/SKILL.md +1 -1
  48. package/skills/peaks-ide/SKILL.md +1 -1
  49. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  50. package/skills/peaks-maker/SKILL.md +125 -0
  51. package/skills/peaks-mut/SKILL.md +297 -0
  52. package/skills/peaks-race-code/SKILL.md +1 -1
  53. package/skills/peaks-resume/SKILL.md +1 -1
  54. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  55. package/skills/peaks-solo/SKILL.md +1 -1
  56. package/skills/peaks-sop/SKILL.md +1 -1
  57. package/skills/peaks-status/SKILL.md +1 -1
  58. package/skills/peaks-test/SKILL.md +1 -1
  59. package/skills/bee/peaks-prd/test-prompts.json +0 -12
  60. package/skills/bee/peaks-qa/test-prompts.json +0 -12
  61. package/skills/bee/peaks-rd/test-prompts.json +0 -12
  62. package/skills/bee/peaks-txt/test-prompts.json +0 -12
  63. package/skills/bee/peaks-ui/test-prompts.json +0 -12
  64. package/skills/peaks-code/test-prompts.json +0 -12
  65. package/skills/peaks-doctor/test_prompts.json +0 -17
  66. package/skills/peaks-sop/test-prompts.json +0 -17
@@ -27,6 +27,7 @@
27
27
  * Paths no template claims (a declaration key, a legacy location) keep their
28
28
  * own shape.
29
29
  */
30
+ import { sliceIdentity } from '../../shared/incrementing-number.js';
30
31
  import { allPrerequisitePaths } from '../artifacts/prerequisite-path-census.js';
31
32
  import { ownerSkillForPath, unownedPathReason } from './owner-skill-map.js';
32
33
  /** The templates a path can be recognised as, with the rid slot filled. */
@@ -34,23 +35,27 @@ const PREREQ_TEMPLATES = allPrerequisitePaths().filter((path) => path.includes('
34
35
  /**
35
36
  * The artifact path with the `<rid>` placeholder left in place.
36
37
  *
37
- * The template is recognised by re-filling the slot with the rid and
38
- * comparing, which is exact. The template is then returned AS IT IS: the
39
- * placeholder is part of the artifact's name, and stripping it produced paths
40
- * that name no real file.
38
+ * The template is recognised by splitting it at its slot and comparing the
39
+ * path's head, tail and the id it carries between them — by LOGICAL id, since
40
+ * `rd/code-review-004-<rid>.md` and `rd/code-review-<rid>.md` name the SAME
41
+ * artifact and one file must not become two rows. The template is returned AS
42
+ * IT IS: the placeholder is part of its name, and stripping it named no file.
41
43
  *
42
- * WHY A `<rid>`-LESS PATH IS RETURNED AS IT IS. The templates matched here
43
- * are the ones that CARRY a slot, so a path that came from a template
44
- * without one — `qa/.initiated` is a real artifact — never matches and is
45
- * returned unchanged. That asymmetry is DELIBERATE: there is nothing to
46
- * canonicalise, because the path already names the artifact it is. Do not
47
- * "fix" it by widening the template list — a template with no slot would
48
- * match EVERY path it happened to equal, and the comparison is only exact
49
- * for the form that carries the substituted id.
44
+ * A `<rid>`-less path is returned unchanged — there is nothing to canonicalise.
45
+ * Do not widen the template list: a slotless template matches every path.
50
46
  */
51
47
  export function canonicalArtifact(path, rid) {
48
+ const logical = sliceIdentity(rid).logical;
52
49
  for (const template of PREREQ_TEMPLATES) {
53
- if (template.replace('<rid>', rid) === path)
50
+ const at = template.indexOf('<rid>');
51
+ if (at < 0)
52
+ continue;
53
+ const head = template.slice(0, at);
54
+ const tail = template.slice(at + '<rid>'.length);
55
+ if (!path.startsWith(head) || !path.endsWith(tail))
56
+ continue;
57
+ const carried = path.slice(head.length, path.length - tail.length);
58
+ if (sliceIdentity(carried).logical === logical)
54
59
  return template;
55
60
  }
56
61
  return path;
@@ -31,6 +31,7 @@
31
31
  */
32
32
  import { collectAttempts, passMomentOf, unreadableVerdictOf, VERDICT_STATE } from './near-miss-attempts.js';
33
33
  import { getPrerequisitesFor } from '../artifacts/artifact-prerequisites.js';
34
+ import { sliceIdentity } from '../../shared/incrementing-number.js';
34
35
  /**
35
36
  * Whether a request type's prerequisite table has a row for the verdict
36
37
  * transition.
@@ -59,7 +60,9 @@ export function countDifferences(events, rollups, requestTypes) {
59
60
  const types = new Set();
60
61
  const slices = [];
61
62
  for (const rollup of rollups) {
62
- const sliceEvents = events.filter((event) => event.category === 'slice-transition' && event.sliceRid === rollup.sliceRid);
63
+ const sliceEvents = events.filter((event) => event.category === 'slice-transition' &&
64
+ event.sliceRid !== undefined &&
65
+ sliceIdentity(event.sliceRid).logical === rollup.sliceRid);
63
66
  const attempts = collectAttempts(sliceEvents);
64
67
  const hasPassMoment = passMomentOf(attempts) !== null;
65
68
  if (rollup.success && !hasPassMoment) {
@@ -91,11 +91,17 @@ import { sliceFacts } from './near-miss-facts.js';
91
91
  import { evidenceFor, reasonsFor, unmeasuredReason } from './near-miss-records.js';
92
92
  import { computeCoverage, unobservableReasons } from './near-miss-coverage.js';
93
93
  import { describeDenominator } from './near-miss-denominator.js';
94
+ import { sliceIdentity } from '../../shared/incrementing-number.js';
94
95
  /**
95
96
  * The events of one slice, grouped by the slice they belong to.
96
97
  *
97
98
  * An event with no slice rid belongs to no slice, so it is not in any of the
98
99
  * populations — it is not a slice's evidence of anything.
100
+ *
101
+ * The group is keyed by the LOGICAL request id
102
+ * (`src/shared/incrementing-number.ts`): a slice whose events were written
103
+ * under both spellings is ONE slice, so its attempts are judged together
104
+ * rather than as two halves of a slice.
99
105
  */
100
106
  function groupBySlice(events) {
101
107
  const bySlice = new Map();
@@ -103,9 +109,10 @@ function groupBySlice(events) {
103
109
  const sliceRid = event.sliceRid;
104
110
  if (sliceRid === undefined)
105
111
  continue;
106
- const bucket = bySlice.get(sliceRid);
112
+ const logical = sliceIdentity(sliceRid).logical;
113
+ const bucket = bySlice.get(logical);
107
114
  if (bucket === undefined)
108
- bySlice.set(sliceRid, [event]);
115
+ bySlice.set(logical, [event]);
109
116
  else
110
117
  bucket.push(event);
111
118
  }
@@ -58,9 +58,11 @@ export const OWNER_SKILL_ENTRIES = [
58
58
  // The security review evidence. For the fanout types the key declares
59
59
  // `audit/security-<rid>.md`, which the independent security audit writes;
60
60
  // for the `config` type it declares the config-specific
61
- // `rd/security-review-<rid>.md`, which is an RD artifact. One key, one
62
- // answer — the row names the skill that owns the security review as a
63
- // concept, which is the audit skill for every type that reaches it.
61
+ // `rd/security-review-<rid>.md`, which the same audit skill writes — the
62
+ // `config` type demands the security review and nothing else, and the
63
+ // review itself is still the audit skill's work. One key, one answer — the
64
+ // row names the skill that owns the security review as a concept, which is
65
+ // the audit skill for every type that reaches it.
64
66
  { prefix: 'gateEvidence.securityReview', skill: 'peaks-security-audit' },
65
67
  { prefix: 'audit/security-', skill: 'peaks-security-audit' },
66
68
  // The bare security audit location — the one that predates the request id
@@ -84,6 +86,24 @@ export const OWNER_SKILL_ENTRIES = [
84
86
  // claim, so without this row it over-claimed this file and named the wrong
85
87
  // skill to fix.
86
88
  { prefix: 'rd/third-party-review-', skill: 'peaks-reviewer' },
89
+ // The security review is the AUDIT skill's artifact, not RD's: the
90
+ // judged-declaration check resolves the security audit artifact through
91
+ // `securityArtifactTiers`, and that list names these two files as the
92
+ // tiers the audit writes at. The `gateEvidence.securityReview` declaration
93
+ // key already names that skill, so the key side and the path side said
94
+ // different things about one file. The `rd/` row above is a DIRECTORY
95
+ // claim, so without these rows it over-claimed this file and pointed a
96
+ // reader at the wrong skill — the same shape the `rd/third-party-review-`
97
+ // row fixes.
98
+ //
99
+ // TWO ROWS, BECAUSE THE TWO LOCATIONS HAVE TWO SHAPES. The file that
100
+ // carries the request id in its name is a PREFIX claim, exactly like the
101
+ // third-party review above it. The legacy tier is the bare file name with
102
+ // no request id in it, so it is EXACT — the same reason `audit/security.md`
103
+ // above is EXACT: a prefix claim on that name would also claim every file
104
+ // whose name merely starts with it.
105
+ { prefix: 'rd/security-review-', skill: 'peaks-security-audit' },
106
+ { prefix: 'rd/security-review.md', skill: 'peaks-security-audit', exact: true },
87
107
  { prefix: 'qa/', skill: 'peaks-qa' },
88
108
  { prefix: 'sc/', skill: 'peaks-sc' },
89
109
  { prefix: 'mut/', skill: 'peaks-mut' }
@@ -37,6 +37,7 @@
37
37
  */
38
38
  import { artifactRole, isSliceTransition, transitionTo } from './aggregation-helpers.js';
39
39
  import { REPAIR_CYCLE_CAP } from './aggregation-types.js';
40
+ import { sliceIdentity } from '../../shared/incrementing-number.js';
40
41
  /**
41
42
  * Version 1 was never versioned — it silently counted qa-role events.
42
43
  * Version 2 is the repair-cycle count. A consumer that reads
@@ -77,9 +78,10 @@ function sliceSteps(events) {
77
78
  for (const event of events) {
78
79
  if (!isSliceTransition(event))
79
80
  continue;
80
- const bucket = bySlice.get(event.sliceRid);
81
+ const rid = sliceIdentity(event.sliceRid).logical;
82
+ const bucket = bySlice.get(rid);
81
83
  if (bucket === undefined)
82
- bySlice.set(event.sliceRid, [event]);
84
+ bySlice.set(rid, [event]);
83
85
  else
84
86
  bucket.push(event);
85
87
  }
@@ -150,7 +152,8 @@ function legacyQaEventCounts(events) {
150
152
  continue;
151
153
  if (artifactRole(event) !== 'qa')
152
154
  continue;
153
- counts.set(event.sliceRid, (counts.get(event.sliceRid) ?? 0) + 1);
155
+ const rid = sliceIdentity(event.sliceRid).logical;
156
+ counts.set(rid, (counts.get(rid) ?? 0) + 1);
154
157
  }
155
158
  return counts;
156
159
  }
@@ -32,7 +32,11 @@ export const ORCHESTRATOR_ROLE_SKILLS = [
32
32
  // accepted here, before any PRD or RD skill may run. Nothing dispatches it.
33
33
  'peaks-audit',
34
34
  // The fast lane — a user-facing entry the user picks instead of the full workflow.
35
- 'peaks-race-code'
35
+ 'peaks-race-code',
36
+ // The always-loaded entry that writes the skill pool and the local SkillHub:
37
+ // the user reaches it by describing what they want, and it is never
38
+ // dispatched by another skill.
39
+ 'peaks-maker'
36
40
  ];
37
41
  /** The 1-level sub-roles an orchestrator dispatches. */
38
42
  export const BEE_ROLE_SKILLS = [
@@ -53,7 +57,10 @@ export const BEE_ROLE_SKILLS = [
53
57
  // One dimension audited, decoupled from the RD fan-out: one envelope,
54
58
  // written for the caller that asked for the audit.
55
59
  'peaks-perf-audit',
56
- 'peaks-security-audit'
60
+ 'peaks-security-audit',
61
+ // One stage of a larger flow: peaks-code and peaks-rd dispatch it after the
62
+ // TACT chain exists, and it writes one measurement report back.
63
+ 'peaks-mut'
57
64
  ];
58
65
  /** The two lists as ONE lookup, so a skill's tier is decided in one place. */
59
66
  const ROLE_TIERS = new Map([
@@ -8,7 +8,8 @@
8
8
  * { ok: false, findings: string[] }.
9
9
  *
10
10
  * The lint asserts three structural properties the spec binds every
11
- * Loop-Engineering-participating peaks-* skill to:
11
+ * Loop-Engineering-participating peaks-* skill to. All three see the skill's
12
+ * OWN text: the shared loop-hygiene insert is blanked first.
12
13
  *
13
14
  * 1. The skill references the shared guideline file
14
15
  * `.peaks/standards/loop-engineering-guidelines.md` (or its
@@ -49,6 +50,9 @@
49
50
  * that rule at the textual layer.
50
51
  */
51
52
  export type LintFinding = string;
53
+ /** Loop-hygiene block delimiters — a shared, non-per-skill insert; skip it. */
54
+ export declare const HYGIENE_BLOCK_OPEN_MARKER = "<!-- peaks:loop-hygiene";
55
+ export declare const HYGIENE_BLOCK_CLOSE_MARKER = "<!-- /peaks:loop-hygiene -->";
52
56
  export type ReadinessLintResult = {
53
57
  ok: true;
54
58
  findings: [];
@@ -101,9 +105,19 @@ export declare const JSON_HAND_AUTHORING_PHRASES: ReadonlyArray<string>;
101
105
  * verb targeting the user.
102
106
  */
103
107
  export declare const JSON_REFERENCE_ALLOWLIST: ReadonlyArray<string>;
108
+ /**
109
+ * Blank the shared loop-hygiene block so the readiness checks skip it: only text
110
+ * BETWEEN two paired markers goes. The region is blanked, not deleted, so a
111
+ * later finding keeps its ORIGINAL line number. A malformed region (one marker
112
+ * with no pair) strips nothing — a lint that one deleted line can switch off is
113
+ * worse than the false positive this exemption exists to fix.
114
+ */
115
+ export declare function stripHygieneBlock(text: string): string;
104
116
  /**
105
117
  * Lint a SKILL.md text for Loop Engineering readiness.
106
118
  *
119
+ * Checks run on {@link stripHygieneBlock}(input); see the helper for why.
120
+ *
107
121
  * @param skillMdText raw markdown text of a peaks-* SKILL.md
108
122
  * @returns a ReadinessLintResult
109
123
  */
@@ -8,7 +8,8 @@
8
8
  * { ok: false, findings: string[] }.
9
9
  *
10
10
  * The lint asserts three structural properties the spec binds every
11
- * Loop-Engineering-participating peaks-* skill to:
11
+ * Loop-Engineering-participating peaks-* skill to. All three see the skill's
12
+ * OWN text: the shared loop-hygiene insert is blanked first.
12
13
  *
13
14
  * 1. The skill references the shared guideline file
14
15
  * `.peaks/standards/loop-engineering-guidelines.md` (or its
@@ -48,6 +49,9 @@
48
49
  * This lint is what stops a future peaks-* skill from regressing
49
50
  * that rule at the textual layer.
50
51
  */
52
+ /** Loop-hygiene block delimiters — a shared, non-per-skill insert; skip it. */
53
+ export const HYGIENE_BLOCK_OPEN_MARKER = '<!-- peaks:loop-hygiene';
54
+ export const HYGIENE_BLOCK_CLOSE_MARKER = '<!-- /peaks:loop-hygiene -->';
51
55
  /**
52
56
  * The shared guideline file that every Loop-Engineering-participating
53
57
  * peaks-* skill must reference. Both the canonical path and the
@@ -166,9 +170,26 @@ export const JSON_REFERENCE_ALLOWLIST = [
166
170
  // ---------------------------------------------------------------------------
167
171
  // Pure function
168
172
  // ---------------------------------------------------------------------------
173
+ /**
174
+ * Blank the shared loop-hygiene block so the readiness checks skip it: only text
175
+ * BETWEEN two paired markers goes. The region is blanked, not deleted, so a
176
+ * later finding keeps its ORIGINAL line number. A malformed region (one marker
177
+ * with no pair) strips nothing — a lint that one deleted line can switch off is
178
+ * worse than the false positive this exemption exists to fix.
179
+ */
180
+ export function stripHygieneBlock(text) {
181
+ const start = text.indexOf(HYGIENE_BLOCK_OPEN_MARKER);
182
+ const closeAt = start === -1 ? -1 : text.indexOf(HYGIENE_BLOCK_CLOSE_MARKER, start);
183
+ if (start === -1 || closeAt === -1)
184
+ return text;
185
+ const end = closeAt + HYGIENE_BLOCK_CLOSE_MARKER.length;
186
+ return text.slice(0, start) + text.slice(start, end).replace(/[^\r\n]/g, '') + text.slice(end);
187
+ }
169
188
  /**
170
189
  * Lint a SKILL.md text for Loop Engineering readiness.
171
190
  *
191
+ * Checks run on {@link stripHygieneBlock}(input); see the helper for why.
192
+ *
172
193
  * @param skillMdText raw markdown text of a peaks-* SKILL.md
173
194
  * @returns a ReadinessLintResult
174
195
  */
@@ -180,9 +201,10 @@ export function lintSkillLoopEngineeringReadiness(skillMdText) {
180
201
  findings: ['skill-md-empty: SKILL.md text is empty or missing']
181
202
  };
182
203
  }
183
- checkGuidelineReference(skillMdText, findings);
184
- checkCliVerbBypass(skillMdText, findings);
185
- checkJsonHandAuthoring(skillMdText, findings);
204
+ const checkedText = stripHygieneBlock(skillMdText);
205
+ checkGuidelineReference(checkedText, findings);
206
+ checkCliVerbBypass(checkedText, findings);
207
+ checkJsonHandAuthoring(checkedText, findings);
186
208
  if (findings.length > 0) {
187
209
  return { ok: false, findings };
188
210
  }
@@ -192,12 +214,8 @@ export function lintSkillLoopEngineeringReadiness(skillMdText) {
192
214
  // Individual checks
193
215
  // ---------------------------------------------------------------------------
194
216
  function checkGuidelineReference(text, findings) {
195
- // Strip code fences before checking — references inside ``` blocks
196
- // are still valid references (the lint accepts them), but we strip
197
- // so the substring match is unambiguous.
198
- const stripped = text;
199
217
  for (const ref of LOOP_ENGINEERING_GUIDELINE_PATHS) {
200
- if (stripped.includes(ref)) {
218
+ if (text.includes(ref)) {
201
219
  return;
202
220
  }
203
221
  }
@@ -1,6 +1,9 @@
1
1
  /**
2
2
  * Utilities for generating incrementing numbered filenames.
3
3
  * Used by session-based artifact storage to create files like 001-feature.md.
4
+ *
5
+ * It also holds the READ side of the numbered-prefix family for a request id
6
+ * that is not a filename: `sliceIdentity` below.
4
7
  */
5
8
  /**
6
9
  * The `<NNN>-` prefix family: EXACTLY three digits, anchored at the start. The one
@@ -53,6 +56,60 @@ export declare function buildNumberedFilename(number: number, description: strin
53
56
  * pattern being imported here.
54
57
  */
55
58
  export declare function requestIdFromFileName(fileName: string): string | null;
59
+ /**
60
+ * The two facts ONE recorded request id carries about the numbered prefix.
61
+ *
62
+ * WHY A REQUEST ID HAS TWO SPELLINGS. A request is written two ways: the
63
+ * LOGICAL id (`2026-10-28-22-4-census-judged-tiers`) and the NUMBERED id the
64
+ * request writer stamps on the artifact it writes
65
+ * (`004-2026-10-28-22-4-census-judged-tiers`). `NUMBERED_PREFIX_RE` — the
66
+ * family `buildNumberedFilename` writes and `requestIdFromFileName` strips — is
67
+ * the repository's own statement that the number is COSMETIC: one request, two
68
+ * spellings of it. This module is the READ side of that statement for a request
69
+ * id that is not a filename.
70
+ *
71
+ * WHY THE NUMBER IS COSMETIC FOR IDENTITY. The number says which request
72
+ * artifact of its session this is; it is not part of the request's identity. So
73
+ * the same request reads as `004-…` under one artifact's name and as `…` under
74
+ * another's, and a reader that groups by the raw string counts one slice twice —
75
+ * under two names, with two scores.
76
+ *
77
+ * WHY THE NUMBER IS NOT COSMETIC FOR RESOLUTION. The artifacts a slice leaves
78
+ * behind are named after the NUMBERED spelling
79
+ * (`rd/code-review-004-<rid>.md`), so a reader that resolves a file must ask
80
+ * under the spelling the files were written with. THAT is why this answers two
81
+ * questions and not one: `logical` is what a reader GROUPS by, and `numbered`
82
+ * is the spelling the files carry.
83
+ *
84
+ * WHY THE TWO ANSWERS LIVE TOGETHER. A reader that collapses them — that
85
+ * groups by the spelling it resolves with — trades a false accusation for a
86
+ * false "evidence missing" report. The two spellings are one rule with two
87
+ * faces, and this module is where both faces are read.
88
+ */
89
+ export type SliceIdentity = {
90
+ /**
91
+ * The ONE id of the request: the request id with its cosmetic number prefix
92
+ * removed.
93
+ *
94
+ * An id that does not carry the prefix is returned unchanged — the bare
95
+ * spelling IS the logical id — so this is the identity function on it. That
96
+ * is what makes the function safe to apply to every spelling of the same
97
+ * request: both spellings read as ONE id.
98
+ */
99
+ readonly logical: string;
100
+ /**
101
+ * The spelling that names this request's artifacts on disk, when the
102
+ * recorded spelling carried the number; null when it did not.
103
+ */
104
+ readonly numbered: string | null;
105
+ };
106
+ /**
107
+ * The identity of the request a recorded request id names.
108
+ *
109
+ * @param sliceRid - the request id as it was written, in either spelling
110
+ * @returns the logical id, and the numbered spelling when the id carried one
111
+ */
112
+ export declare function sliceIdentity(sliceRid: string): SliceIdentity;
56
113
  /**
57
114
  * Get the next numbered file path in a directory.
58
115
  * Combines getNextNumber() and buildNumberedFilename().
@@ -1,6 +1,9 @@
1
1
  /**
2
2
  * Utilities for generating incrementing numbered filenames.
3
3
  * Used by session-based artifact storage to create files like 001-feature.md.
4
+ *
5
+ * It also holds the READ side of the numbered-prefix family for a request id
6
+ * that is not a filename: `sliceIdentity` below.
4
7
  */
5
8
  import { existsSync, readdirSync } from 'node:fs';
6
9
  import { join } from 'node:path';
@@ -134,6 +137,16 @@ export function requestIdFromFileName(fileName) {
134
137
  return null;
135
138
  return fileName.replace(NUMBERED_PREFIX_RE, '').replace(/\.md$/, '');
136
139
  }
140
+ /**
141
+ * The identity of the request a recorded request id names.
142
+ *
143
+ * @param sliceRid - the request id as it was written, in either spelling
144
+ * @returns the logical id, and the numbered spelling when the id carried one
145
+ */
146
+ export function sliceIdentity(sliceRid) {
147
+ const logical = sliceRid.replace(NUMBERED_PREFIX_RE, '');
148
+ return { logical, numbered: logical === sliceRid ? null : sliceRid };
149
+ }
137
150
  /**
138
151
  * Get the next numbered file path in a directory.
139
152
  * Combines getNextNumber() and buildNumberedFilename().
@@ -1,32 +1,45 @@
1
1
  // src/skills/peaks-maker/index.ts
2
+ //
3
+ // The manifest of the peaks-maker skill: the name and description its
4
+ // frontmatter carries, and the body of the document.
5
+ //
6
+ // WHERE THE DOCUMENT LIVES. `peaks-maker` is a DISTRIBUTED skill: its
7
+ // document is `skills/peaks-maker/SKILL.md`, in the same root `skills/` tree
8
+ // every other shipped skill lives in — the one directory the installer
9
+ // reads (`scripts/install-skills-bundles.mjs`) and the one the registry
10
+ // loads (`skillsDir` in `src/services/skills/skill-registry.ts`). It used to
11
+ // be a sibling of this file, which is why this module resolved it relative
12
+ // to `import.meta.url`.
13
+ //
14
+ // That relative resolution was what made the published module throw. The
15
+ // build compiles `src/**` into `dist/**` but never copies a SKILL.md
16
+ // alongside it, so `dist/skills/peaks-maker/index.js` read a file that the
17
+ // tarball does not contain and died with ENOENT on import. Resolving through
18
+ // `skillsDir` fixes that: the root package ships `skills/**`, so the same
19
+ // lookup finds the document in a checkout and in an installed package.
20
+ //
21
+ // THE FRONTMATTER IS PARSED BY THE REPOSITORY'S PARSER. The copy that lived
22
+ // here was a second, line-based frontmatter parser. It could not read the
23
+ // block scalar the description now uses (`description: |` plus the indented
24
+ // text), so it reported the description as the single character `|` — a
25
+ // manifest that validated nothing. `parseFrontmatter` is the parser the
26
+ // registry, the plugin manifest and the doctor all use, so the manifest and
27
+ // the registry can no longer disagree about what the document says.
2
28
  import { readFileSync } from 'node:fs';
3
- import { fileURLToPath } from 'node:url';
4
- import { dirname, join } from 'node:path';
5
- function parseFrontmatter(md) {
6
- const m = md.match(/^---\n([\s\S]+?)\n---\n([\s\S]*)$/);
7
- if (!m)
8
- throw new Error('peaks-maker SKILL.md is missing YAML frontmatter');
9
- const fm = {};
10
- for (const line of m[1].split('\n')) {
11
- const i = line.indexOf(':');
12
- if (i > 0)
13
- fm[line.slice(0, i).trim()] = line.slice(i + 1).trim();
14
- }
15
- // The non-null assertions below were unsafe: if `name:` or `description:`
16
- // was absent from the frontmatter, `fm[name]` would be `undefined`, which
17
- // violates the declared return type and silently leaks a malformed
18
- // manifest to every consumer of `peaksMakerManifest`. Validate explicitly
19
- // so a missing/empty key surfaces as a clear error at module-load time.
20
- const name = fm.name;
21
- const description = fm.description;
22
- if (typeof name !== 'string' || name.length === 0) {
23
- throw new Error('peaks-maker SKILL.md is missing name or description in frontmatter');
24
- }
25
- if (typeof description !== 'string' || description.length === 0) {
26
- throw new Error('peaks-maker SKILL.md is missing name or description in frontmatter');
27
- }
28
- return { name, description, body: m[2] };
29
- }
30
- const here = dirname(fileURLToPath(import.meta.url));
31
- const md = readFileSync(join(here, 'SKILL.md'), 'utf-8');
32
- export const peaksMakerManifest = parseFrontmatter(md);
29
+ import { join } from 'node:path';
30
+ import { skillsDir } from 'peaks-loop-shared/paths';
31
+ import { parseFrontmatter } from '../../shared/frontmatter.js';
32
+ /** The maker skill's document, in the distributed skill tree. */
33
+ const SKILL_MD = join(skillsDir, 'peaks-maker', 'SKILL.md');
34
+ const md = readFileSync(SKILL_MD, 'utf-8');
35
+ // The body is everything after the frontmatter. The parser above reads the
36
+ // frontmatter; this reads the document it wraps.
37
+ const BODY = /^---\r?\n[\s\S]*?\r?\n---\r?\n([\s\S]*)$/.exec(md)?.[1] ?? '';
38
+ // `parseFrontmatter` throws when `name` or `description` is missing or
39
+ // empty, so a malformed document is refused here rather than published.
40
+ const metadata = parseFrontmatter(md);
41
+ export const peaksMakerManifest = {
42
+ name: metadata.name,
43
+ description: metadata.description,
44
+ body: BODY
45
+ };
@@ -53,8 +53,8 @@ Peaks-Loop Skill: <skill-name> | Peaks-Loop Role: <tier> | Peaks-Loop Gate: <cur
53
53
 
54
54
  `<skill-name>` is the value returned by `peaks skill presence --json`'s `data.skill`. The `Role` line surfaces the two-layer Peaks-Loop family so the user always knows which layer is active:
55
55
 
56
- - **orchestrator** (1-level) — `peaks-code`, `peaks-content`, `peaks-doctor`, `peaks-issue-fix-orchestrator`, `peaks-solo`, `peaks-ide`, `peaks-sop`, `peaks-audit`, `peaks-race-code`. These are user-facing workflows that own gate transitions.
57
- - **bee** (1-level sub-role) — `peaks-prd`, `peaks-rd`, `peaks-qa`, `peaks-ui`, `peaks-sc`, `peaks-txt`, `peaks-final-review`, `peaks-resume`, `peaks-status`, `peaks-test`, `peaks-reviewer`, `peaks-slice-decompose`, `peaks-perf-audit`, `peaks-security-audit`. These are dispatched by an orchestrator and own one stage.
56
+ - **orchestrator** (1-level) — `peaks-code`, `peaks-content`, `peaks-doctor`, `peaks-issue-fix-orchestrator`, `peaks-solo`, `peaks-ide`, `peaks-sop`, `peaks-audit`, `peaks-race-code`, `peaks-maker`. These are user-facing workflows that own gate transitions.
57
+ - **bee** (1-level sub-role) — `peaks-prd`, `peaks-rd`, `peaks-qa`, `peaks-ui`, `peaks-sc`, `peaks-txt`, `peaks-final-review`, `peaks-resume`, `peaks-status`, `peaks-test`, `peaks-reviewer`, `peaks-slice-decompose`, `peaks-perf-audit`, `peaks-security-audit`, `peaks-mut`. These are dispatched by an orchestrator and own one stage.
58
58
 
59
59
  **Both layers must always appear in the header regardless of which skill is currently active**, so the user sees the full Peaks-Loop family on every turn. When the active skill is a bee (e.g. `peaks-rd`), the orchestrator is implicit and you MAY add a parenthetical: `peaks-rd (under peaks-code)`. When the active skill is an orchestrator, no parent is implied.
60
60
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.23",
3
+ "version": "4.1.25",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -90,8 +90,9 @@
90
90
  "scripts/canonical-store-report.mjs",
91
91
  "scripts/watch.mjs",
92
92
  "scripts/watch-tree.mjs",
93
- "skills/**",
93
+ "skills/**/!(*test[-_]prompts*).*",
94
94
  "!skills/**/test-prompts.json",
95
+ "!skills/**/test_prompts.json",
95
96
  "!skills/**/.DS_Store",
96
97
  "output-styles/**",
97
98
  "agents/**",
@@ -132,10 +133,10 @@
132
133
  "picomatch": "4.0.7",
133
134
  "yaml": "^2.9.1",
134
135
  "zod": "^4.6.7",
135
- "peaks-loop-internal-runtime": "0.0.63",
136
- "peaks-loop-mut": "0.1.77",
137
- "peaks-loop-shared": "0.0.112",
138
- "peaks-loop-shared-channel": "0.0.80"
136
+ "peaks-loop-internal-runtime": "0.0.65",
137
+ "peaks-loop-shared-channel": "0.0.82",
138
+ "peaks-loop-shared": "0.0.114",
139
+ "peaks-loop-mut": "0.1.79"
139
140
  },
140
141
  "devDependencies": {
141
142
  "@changesets/cli": "2.31.1",
@@ -42,8 +42,13 @@ import { resolveBundleTargetRoot } from './install-skills-ide.mjs';
42
42
  *
43
43
  * @param {string} skillsRoot
44
44
  * @returns {Array<{ skillName: string, sourcePath: string }>}
45
+ *
46
+ * EXPORTED so a test can assert on the ENUMERATION itself — the names this
47
+ * installer would reconcile — instead of on a file happening to exist on
48
+ * disk. The two are different claims: a document under `skills/` that this
49
+ * function does not enumerate is installed by nothing.
45
50
  */
46
- function collectSkillCandidates(skillsRoot) {
51
+ export function collectSkillCandidates(skillsRoot) {
47
52
  const beeRoot = join(skillsRoot, 'bee');
48
53
  /** @type {Array<{ skillName: string, sourcePath: string }>} */
49
54
  const candidates = [];
@@ -18,7 +18,11 @@ import { homedir } from 'node:os';
18
18
  import { join, resolve } from 'node:path';
19
19
  import { pathToFileURL } from 'node:url';
20
20
 
21
- import { installBundledAgents, installBundledSkills } from './install-skills-bundles.mjs';
21
+ import {
22
+ collectSkillCandidates,
23
+ installBundledAgents,
24
+ installBundledSkills
25
+ } from './install-skills-bundles.mjs';
22
26
  import {
23
27
  IDE_SKILL_INSTALL_PROFILES,
24
28
  isPlatformPresent,
@@ -34,6 +38,11 @@ import { createConfigResult, installUserConfig } from './install-skills-user-con
34
38
  export { IDE_DETECTION_DIRS } from './install-skills-ide.mjs';
35
39
  export { IDE_SKILL_INSTALL_PROFILES };
36
40
  export { installBundledSkills, installBundledAgents };
41
+ // The candidate enumeration, on the public surface for the same reason the
42
+ // installers are: what the installer WOULD reconcile is a fact about the
43
+ // package, and a test that has to reach past the entry point to see it will
44
+ // keep asserting on the wrong thing.
45
+ export { collectSkillCandidates };
37
46
  export { installUserConfig };
38
47
  export { installBundledOutputStyles, installBundledOutputStyleDefault };
39
48
 
@@ -12,7 +12,7 @@ metadata:
12
12
  - schema: .peaks/project-scan/audit-output-schema.md
13
13
  ---
14
14
 
15
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
15
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 25. -->
16
16
 
17
17
  ## Loop hygiene (every turn — MANDATORY)
18
18
 
@@ -8,7 +8,7 @@ description: |
8
8
  visibility: internal
9
9
  ---
10
10
 
11
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
11
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 25. -->
12
12
 
13
13
  ## Loop hygiene (every turn — MANDATORY)
14
14
 
@@ -8,7 +8,7 @@ description: |
8
8
  visibility: internal
9
9
  ---
10
10
 
11
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
11
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 25. -->
12
12
 
13
13
  ## Loop hygiene (every turn — MANDATORY)
14
14
 
@@ -9,7 +9,7 @@ description: |
9
9
  visibility: internal
10
10
  ---
11
11
 
12
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
12
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 25. -->
13
13
 
14
14
  ## Loop hygiene (every turn — MANDATORY)
15
15
 
@@ -4,7 +4,7 @@ visibility: internal
4
4
  description: Third-party independent code-review skill for Peaks. Use as a parallel reviewer to karpathy-reviewer when a workflow needs an out-of-band (non-RD-model) review pass to mitigate single-LLM self-dogfood blind spots. Emits a schema-validated ReviewerEnvelope (no free-form LLM JSON). v2.14.0 G4.
5
5
  ---
6
6
 
7
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
7
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 25. -->
8
8
 
9
9
  ## Loop hygiene (every turn — MANDATORY)
10
10
 
@@ -8,7 +8,7 @@ description: |
8
8
  visibility: internal
9
9
  ---
10
10
 
11
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
11
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 25. -->
12
12
 
13
13
  ## Loop hygiene (every turn — MANDATORY)
14
14