peaks-loop 4.1.22 → 4.1.24

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 (118) hide show
  1. package/.claude-plugin/marketplace.json +12 -2
  2. package/CHANGELOG.md +184 -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 +23 -8
  8. package/dist/cli/commands/gate-commands-enforce.js +27 -12
  9. package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
  10. package/dist/cli/commands/observability-commands-hotspots.js +222 -0
  11. package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
  12. package/dist/cli/commands/observability-commands-near-miss.js +105 -0
  13. package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
  14. package/dist/cli/commands/observability-commands-queries.js +88 -47
  15. package/dist/cli/commands/observability-commands-session-row.d.ts +48 -0
  16. package/dist/cli/commands/observability-commands-session-row.js +201 -0
  17. package/dist/cli/commands/observability-commands.js +81 -20
  18. package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
  19. package/dist/services/artifacts/artifact-prerequisites.js +1 -1
  20. package/dist/services/artifacts/prerequisite-path-census.d.ts +47 -0
  21. package/dist/services/artifacts/prerequisite-path-census.js +100 -0
  22. package/dist/services/artifacts/prerequisite-path-resolver.js +32 -2
  23. package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
  24. package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
  25. package/dist/services/artifacts/rd-gate-event.js +211 -0
  26. package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
  27. package/dist/services/artifacts/rd-transition-gates.js +65 -24
  28. package/dist/services/hooks/output.d.ts +67 -1
  29. package/dist/services/hooks/output.js +74 -1
  30. package/dist/services/observability/aggregation-types.d.ts +21 -0
  31. package/dist/services/observability/aggregation.d.ts +12 -2
  32. package/dist/services/observability/aggregation.js +28 -3
  33. package/dist/services/observability/compliance-judge.d.ts +77 -0
  34. package/dist/services/observability/compliance-judge.js +143 -0
  35. package/dist/services/observability/compliance-spec.d.ts +96 -0
  36. package/dist/services/observability/compliance-spec.js +29 -0
  37. package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
  38. package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
  39. package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
  40. package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
  41. package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
  42. package/dist/services/observability/hotspot-attribution-summary.js +74 -0
  43. package/dist/services/observability/hotspot-rows.d.ts +47 -0
  44. package/dist/services/observability/hotspot-rows.js +89 -0
  45. package/dist/services/observability/hotspot-shared.d.ts +207 -0
  46. package/dist/services/observability/hotspot-shared.js +127 -0
  47. package/dist/services/observability/hotspot-sources.d.ts +55 -0
  48. package/dist/services/observability/hotspot-sources.js +142 -0
  49. package/dist/services/observability/hotspots.d.ts +47 -0
  50. package/dist/services/observability/hotspots.js +47 -0
  51. package/dist/services/observability/near-miss-attempts.d.ts +175 -0
  52. package/dist/services/observability/near-miss-attempts.js +223 -0
  53. package/dist/services/observability/near-miss-coverage.d.ts +109 -0
  54. package/dist/services/observability/near-miss-coverage.js +108 -0
  55. package/dist/services/observability/near-miss-denominator.d.ts +81 -0
  56. package/dist/services/observability/near-miss-denominator.js +75 -0
  57. package/dist/services/observability/near-miss-difference.d.ts +98 -0
  58. package/dist/services/observability/near-miss-difference.js +135 -0
  59. package/dist/services/observability/near-miss-facts.d.ts +165 -0
  60. package/dist/services/observability/near-miss-facts.js +101 -0
  61. package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
  62. package/dist/services/observability/near-miss-gate-events.js +106 -0
  63. package/dist/services/observability/near-miss-gates.d.ts +108 -0
  64. package/dist/services/observability/near-miss-gates.js +135 -0
  65. package/dist/services/observability/near-miss-records.d.ts +93 -0
  66. package/dist/services/observability/near-miss-records.js +87 -0
  67. package/dist/services/observability/near-miss.d.ts +148 -0
  68. package/dist/services/observability/near-miss.js +203 -0
  69. package/dist/services/observability/observability-schema.d.ts +17 -2
  70. package/dist/services/observability/observability-schema.js +21 -1
  71. package/dist/services/observability/owner-skill-map.d.ts +92 -0
  72. package/dist/services/observability/owner-skill-map.js +164 -0
  73. package/dist/services/observability/repair-cycle-metric.js +6 -3
  74. package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
  75. package/dist/services/observability/report-formatter-hotspots.js +76 -0
  76. package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
  77. package/dist/services/observability/report-formatter-near-miss.js +234 -0
  78. package/dist/services/observability/report-formatter.d.ts +49 -3
  79. package/dist/services/observability/report-formatter.js +55 -14
  80. package/dist/services/observability/retro-attribution.d.ts +129 -0
  81. package/dist/services/observability/retro-attribution.js +134 -0
  82. package/dist/services/observability/session-metric-rows.d.ts +153 -0
  83. package/dist/services/observability/session-metric-rows.js +184 -0
  84. package/dist/services/skills/presence-role.js +9 -2
  85. package/dist/services/standards/loop-engineering-readiness-lint.d.ts +15 -1
  86. package/dist/services/standards/loop-engineering-readiness-lint.js +27 -9
  87. package/dist/shared/incrementing-number.d.ts +57 -0
  88. package/dist/shared/incrementing-number.js +13 -0
  89. package/dist/skills/peaks-maker/index.js +43 -30
  90. package/output-styles/peaks-skill-swarm.md +2 -2
  91. package/package.json +5 -5
  92. package/scripts/install-skills-bundles.mjs +6 -1
  93. package/scripts/install-skills.mjs +10 -1
  94. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  95. package/skills/bee/peaks-prd/SKILL.md +1 -1
  96. package/skills/bee/peaks-qa/SKILL.md +1 -1
  97. package/skills/bee/peaks-rd/SKILL.md +1 -1
  98. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  99. package/skills/bee/peaks-sc/SKILL.md +1 -1
  100. package/skills/bee/peaks-security-audit/SKILL.md +1 -1
  101. package/skills/bee/peaks-txt/SKILL.md +1 -1
  102. package/skills/bee/peaks-ui/SKILL.md +1 -1
  103. package/skills/peaks-audit/SKILL.md +1 -1
  104. package/skills/peaks-code/SKILL.md +1 -1
  105. package/skills/peaks-content/SKILL.md +1 -1
  106. package/skills/peaks-doctor/SKILL.md +1 -1
  107. package/skills/peaks-final-review/SKILL.md +1 -1
  108. package/skills/peaks-ide/SKILL.md +1 -1
  109. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  110. package/skills/peaks-maker/SKILL.md +125 -0
  111. package/skills/peaks-mut/SKILL.md +297 -0
  112. package/skills/peaks-race-code/SKILL.md +1 -1
  113. package/skills/peaks-resume/SKILL.md +1 -1
  114. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  115. package/skills/peaks-solo/SKILL.md +1 -1
  116. package/skills/peaks-sop/SKILL.md +1 -1
  117. package/skills/peaks-status/SKILL.md +1 -1
  118. package/skills/peaks-test/SKILL.md +1 -1
@@ -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.22",
3
+ "version": "4.1.24",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -132,10 +132,10 @@
132
132
  "picomatch": "4.0.7",
133
133
  "yaml": "^2.9.1",
134
134
  "zod": "^4.6.7",
135
- "peaks-loop-internal-runtime": "0.0.62",
136
- "peaks-loop-mut": "0.1.76",
137
- "peaks-loop-shared": "0.0.111",
138
- "peaks-loop-shared-channel": "0.0.79"
135
+ "peaks-loop-internal-runtime": "0.0.64",
136
+ "peaks-loop-mut": "0.1.78",
137
+ "peaks-loop-shared": "0.0.113",
138
+ "peaks-loop-shared-channel": "0.0.81"
139
139
  },
140
140
  "devDependencies": {
141
141
  "@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
 
@@ -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
 
@@ -3,7 +3,7 @@ name: peaks-audit
3
3
  description: Gate autonomous LLM work on a 6-dimension audit + user-accepted goal. Use IMMEDIATELY after a need is expressed, BEFORE any PRD/RD/QA work starts.
4
4
  ---
5
5
 
6
- <!-- 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. -->
6
+ <!-- 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. -->
7
7
 
8
8
  ## Loop hygiene (every turn — MANDATORY)
9
9
 
@@ -3,7 +3,7 @@ name: peaks-code
3
3
  description: Code-domain loop engineering orchestrator for the Peaks-Loop skill family. Use when the user asks Peaks-Loop to handle a code-repo workflow end-to-end (端到端/全流程/需求开发), especially from a product document (PRD/飞书文档/Feishu doc) through implementation and validation. Coordinates peaks-prd, peaks-rd, peaks-qa, peaks-ui, peaks-sc, and peaks-txt while preserving user confirmation gates. Triggers on `/peaks-code`, "peaks code", "全流程开发", "端到端迭代". General primitives (peaks-resume / peaks-status / peaks-test) are sibling skills, not children.
4
4
  ---
5
5
 
6
- <!-- 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. -->
6
+ <!-- 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. -->
7
7
 
8
8
  ## Loop hygiene (every turn — MANDATORY)
9
9
 
@@ -3,7 +3,7 @@ name: peaks-content
3
3
  description: Non-code orchestrator for content workflows (draft / edit / publish / archive). Use when a user wants to drive an end-to-end content-production loop (blog post, newsletter, marketing copy, social thread, doc page) where the LLM must coordinate draft / edit / tone / publish / archive stages with explicit gates between them, and where the user only wants to speak natural language and pick options. NOT for free-form chatting; NOT for code review. Reuses the peaks-loop Loop Engineering primitives (Loop Engineering Asset, Bee Asset, Workflow Trace, Evolution Evaluation) but does NOT import peaks-code internals. Triggers on `/peaks-content`, "peaks content", "content workflow", "publish this to <channel>", "edit the draft", "archive the previous version".
4
4
  ---
5
5
 
6
- <!-- 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. -->
6
+ <!-- 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. -->
7
7
 
8
8
  ## Loop hygiene (every turn — MANDATORY)
9
9
 
@@ -4,7 +4,7 @@ description: Orchestrate peaks-loop's L3 doctor (peaks audit + peaks doctor + pe
4
4
  visibility: internal
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
 
@@ -3,7 +3,7 @@ name: peaks-final-review
3
3
  description: Final-review skill for Peaks. Use when a workflow needs to assemble 4-dimension business-review evidence (functional-completeness, problem-resolution, no-new-bugs, existing-functionality-intact) for human acceptance at the end of an autonomous slice. Triggers on "/peaks-final-review", "prepare final review", "4-dim review", or peaks-code end-of-workflow handoff.
4
4
  ---
5
5
 
6
- <!-- 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. -->
6
+ <!-- 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. -->
7
7
 
8
8
  ## Loop hygiene (every turn — MANDATORY)
9
9
 
@@ -4,7 +4,7 @@ description: Orchestrate peaks-loop's IDE-aware behavior (hooks + statusline + h
4
4
  visibility: internal
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
 
@@ -3,7 +3,7 @@ name: peaks-issue-fix-orchestrator
3
3
  description: 'End-to-end orchestrator that surveys open issues in a target repo, classifies them by difficulty, mines reference merged-PRs, fixes each issue with real commits (with Repository + AI-modified declaration), writes normalized PR description files, and emits a one-line submit script. Use when the user wants to drive a "fix N open issues and prepare PRs" run on an upstream repo (any language; primarily Python + TypeScript). Reuses Loop Engineering primitives: 4-layer asset model, Darwin ratchet, karpathy-engineered red lines, Human-NL-Choice-Only. Triggers on `/peaks-issue-fix-orchestrator`, "fix 30 issues", "dogfood on <repo>", "open-issue sweep on <repo>".'
4
4
  ---
5
5
 
6
- <!-- 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. -->
6
+ <!-- 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. -->
7
7
 
8
8
  ## Loop hygiene (every turn — MANDATORY)
9
9
 
@@ -0,0 +1,125 @@
1
+ ---
2
+ name: peaks-maker
3
+ description: |
4
+ Sediment and SkillHub author. Use when the user describes — in natural language — intent to (a) capture a workflow as a reusable skill, (b) refine or clone an existing bee, (c) export / import a skill bundle, (d) retain a release for the local SkillHub, or (e) dispose a previous release. Intent-based, never keyword-based: "调一下", "改改", "下次复用" all map to the same concrete `peaks skill sediment …` verb. User never types CLI; peaks-maker runs it on the user's behalf.
5
+ ---
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 25. -->
8
+
9
+ ## Loop hygiene (every turn — MANDATORY)
10
+
11
+ **Skill header.** While this skill is active, open every turn with
12
+ `Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`.
13
+ Every turn, not only the first — it is how the user knows which skill is driving.
14
+ `Role` and `Context` are machine facts: copy them from `peaks skill presence --json`
15
+ (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them.
16
+
17
+ **Context is this skill's own business.** Run `peaks skill presence --json` every turn and
18
+ read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
19
+ run `peaks code auto-compact --project .` **yourself**, then continue. Tell the user the
20
+ ratio in one line if it helps, but never hand them the compaction step: asking the user to
21
+ run `/compact` is the regression the zero-pause contract forbids. This holds in **every
22
+ mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
23
+
24
+ **Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
25
+ it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
26
+ config); `.peaks/**` writes are exempt.
27
+
28
+ **Expect one denial per file anyway — and do NOT pre-empt it.** A `PreToolUse` gate (ECC's
29
+ "Fact-Forcing Gate") denies the FIRST edit a session makes to any given path, once, by
30
+ design. Reading does NOT prevent it: the gate keys on the path's first touch, not on whether
31
+ you read it. **Do not recite its four questions before every edit** — it asks when it wants
32
+ them, and reciting unprompted burns a round-trip per file for nothing. Answer only when a
33
+ denial actually arrives.
34
+
35
+ **When one does arrive:** a denial is not a failure and the tool is not broken — your edit
36
+ was NOT applied. State the facts it asks for (importers, affected API, data schemas if any,
37
+ the user's verbatim instruction), then retry the SAME operation. The retry is allowed. Do not
38
+ switch tools, do not give up, do not retry blindly. One more thing worth knowing: an idle gap
39
+ of ~30 minutes clears the gate's "already passed" list, so a file you cleared earlier can be
40
+ denied again after a long pause. That is the gate resetting, not you regressing.
41
+ <!-- /peaks:loop-hygiene -->
42
+
43
+ # Peaks-Maker
44
+
45
+ peaks-maker is the user-facing skill that turns natural-language intent into `peaks skill sediment …` CLI calls. It is always-loaded. It is the only entry that writes the pool and the local SkillHub.
46
+
47
+ ## What peaks-maker does
48
+
49
+ 1. Reads the user's intent (NL — never a CLI verb list).
50
+ 2. Disambiguates only when genuinely ambiguous (via `AskUserQuestion` multi-choice).
51
+ 3. Runs the right `peaks skill sediment …` subcommand on the user's behalf.
52
+ 4. Reports back in NL.
53
+
54
+ ## What peaks-maker must NOT do
55
+
56
+ - Never require the user to type a CLI verb, JSON, or path.
57
+ - Never bypass `AskUserQuestion` for genuine ambiguity.
58
+ - Never write to `.system/` (the soft-protection guard refuses).
59
+ - Never run `sqlite3` directly against `~/.peaks/skills/state.db` — only via the `peaks skill sediment …` surface.
60
+ - Never auto-promote. Always ask the user in NL.
61
+ - Never invent a CLI verb. The fixed set is `add-segment`, `add-bee`, `refine-bee`, `clone-bee`, `promote`, `retire`, `dispose`, `releases`, `release-show`, `release-diff`, `export`, `import`, `gc-blobs`, `list`, `show`, `search`, `recent`, `rebuild-index`. The blessed 18 are defined in `src/services/standards/loop-engineering-readiness-lint.ts`. Adding/removing verbs requires updating that allowlist and the CLI surface together.
62
+
63
+ ## Loop Engineering role
64
+
65
+ peaks-loop's first-class product is the user's **Loop Engineering** —
66
+ the user's reusable method systems, not the user's ad-hoc workflows.
67
+ peaks-maker participates in Loop Engineering as three coordinated
68
+ roles, replacing the older "bee sediment gatekeeper" framing
69
+ (spec §7.5 / §10 RL-8):
70
+
71
+ 1. **Loop crystallizer.** Reads a completed run's evidence (brief,
72
+ trace pointers, evaluator verdicts) and drives the user through a
73
+ single `AskUserQuestion` choice among
74
+ `create_new_loop | update_existing_loop | trace_only`. The LLM
75
+ then invokes `peaks asset crystallize` on the user's behalf. The
76
+ crystallization prompt is gated to completed-task evidence only
77
+ (RL-2 — Post-run crystallization).
78
+ 2. **Bee creator.** Writes the executable body that runs the loop
79
+ (main bee + supporting bees) using `peaks skill sediment add-bee`
80
+ and `peaks skill sediment refine-bee`. Bees are created or
81
+ updated only in the same transaction as their owning loop
82
+ (RL-3 — Loop + Bee dual-asset).
83
+ 3. **Evolution gatekeeper.** Honors the Darwin-style ratchet
84
+ (RL-4 / RL-5 / RL-6) when the user wants to evolve a loop or
85
+ bee: enforces a single editable asset, a single optimization
86
+ dimension, an independent-context evaluator (≠ author), and a
87
+ regression skeptic. Promotion requires the user to confirm in
88
+ natural language; LLM runs `peaks evolution propose / evaluate /
89
+ mark-keep / revert` on the user's behalf.
90
+
91
+ ### Reference
92
+
93
+ - The shared karpathy-engineered red lines that govern every
94
+ Loop-Engineering-participating peaks-* skill live at
95
+ `.peaks/standards/loop-engineering-guidelines.md`. peaks-maker
96
+ imports that file (not a copy) and is bound by RL-0..RL-9.
97
+ - The post-run crystallization prompt is surfaced by
98
+ `peaks asset crystallize` (M5 umbrella verb; spec §7.4).
99
+ - The Darwin-style ratchet is enforced by
100
+ `peaks evolution propose / evaluate / mark-keep / revert`
101
+ (M4 ratchet CLI surface; spec §6).
102
+
103
+ ### Readiness gate
104
+
105
+ Any new peaks-* skill that participates in Loop Engineering must
106
+ pass the readiness lint:
107
+
108
+ ```text
109
+ peaks skill lint --category loop-engineering-readiness --path <skill-dir>
110
+ ```
111
+
112
+ The lint asserts three things (see
113
+ `src/services/standards/loop-engineering-readiness-lint.ts`):
114
+
115
+ 1. the SKILL.md references
116
+ `.peaks/standards/loop-engineering-guidelines.md`;
117
+ 2. the SKILL.md does not introduce a CLI verb the user is meant to
118
+ type (only LLM-coordinated verbs from the sediment / asset /
119
+ evolution surface are allowed; RL-1);
120
+ 3. the SKILL.md does not introduce a JSON / manifest
121
+ hand-authoring surface (RL-1).
122
+
123
+ peaks-maker itself passes this lint today; the linter is what stops
124
+ a future peaks-* skill from regressing the two-forms-only / NL-only
125
+ rule at the textual layer.