peaks-loop 4.1.18 → 4.1.19

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 (168) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +126 -0
  3. package/README-en.md +6 -0
  4. package/README.md +5 -0
  5. package/contracts/test-style-contract.md +14 -5
  6. package/dist/cli/commands/audit-red-lines-runners.js +6 -1
  7. package/dist/cli/commands/best-practice-scan-collision.d.ts +42 -0
  8. package/dist/cli/commands/best-practice-scan-collision.js +115 -0
  9. package/dist/cli/commands/best-practice-scan-command.d.ts +5 -0
  10. package/dist/cli/commands/best-practice-scan-command.js +9 -18
  11. package/dist/cli/commands/best-practice-scan-helpers.d.ts +12 -6
  12. package/dist/cli/commands/best-practice-scan-helpers.js +37 -17
  13. package/dist/cli/commands/code-auto-compact-command.js +26 -18
  14. package/dist/cli/commands/core/skill-generated-config-notice.d.ts +5 -0
  15. package/dist/cli/commands/core/skill-generated-config-notice.js +42 -8
  16. package/dist/cli/commands/core/skill-presence-commands.js +42 -74
  17. package/dist/cli/commands/core/skill-presence-set-command.d.ts +11 -0
  18. package/dist/cli/commands/core/skill-presence-set-command.js +175 -0
  19. package/dist/cli/commands/core/standards-init-command.js +44 -8
  20. package/dist/cli/commands/core/standards-migrate-command.js +5 -4
  21. package/dist/cli/commands/dispatch-dag-runners.d.ts +1 -0
  22. package/dist/cli/commands/dispatch-dag-runners.js +11 -1
  23. package/dist/cli/commands/dispatch-detached-branch.js +19 -1
  24. package/dist/cli/commands/mut-commands-helpers.d.ts +72 -5
  25. package/dist/cli/commands/mut-commands-helpers.js +197 -4
  26. package/dist/cli/commands/mut-commands.d.ts +9 -1
  27. package/dist/cli/commands/mut-commands.js +82 -154
  28. package/dist/cli/commands/preferences-commands.js +27 -2
  29. package/dist/cli/commands/scan-scope-helpers.js +2 -2
  30. package/dist/services/24h-mode/auto-engage.d.ts +11 -3
  31. package/dist/services/24h-mode/auto-engage.js +14 -6
  32. package/dist/services/artifacts/artifact-templates.js +10 -0
  33. package/dist/services/artifacts/backcompat-acceptance.d.ts +8 -1
  34. package/dist/services/artifacts/backcompat-acceptance.js +8 -7
  35. package/dist/services/artifacts/rd-transition-gates.d.ts +32 -5
  36. package/dist/services/artifacts/rd-transition-gates.js +96 -19
  37. package/dist/services/artifacts/request-artifact-service.js +6 -6
  38. package/dist/services/audit/enforcers/lint-output-style.js +14 -2
  39. package/dist/services/audit/enforcers/root-scratch-artifacts.d.ts +46 -0
  40. package/dist/services/audit/enforcers/root-scratch-artifacts.js +97 -0
  41. package/dist/services/audit/static-service.js +4 -4
  42. package/dist/services/code/auto-compact-history.d.ts +6 -1
  43. package/dist/services/code/auto-compact-history.js +6 -1
  44. package/dist/services/code/auto-compact-modes.d.ts +60 -14
  45. package/dist/services/code/auto-compact-modes.js +75 -20
  46. package/dist/services/code/auto-compact-profile.d.ts +23 -0
  47. package/dist/services/code/auto-compact-profile.js +51 -0
  48. package/dist/services/compact-history/compact-history-service.d.ts +6 -1
  49. package/dist/services/compact-history/compact-history-service.js +5 -1
  50. package/dist/services/context/auto-compact-types.d.ts +7 -5
  51. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.d.ts +37 -0
  52. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.js +100 -0
  53. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +11 -3
  54. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +48 -29
  55. package/dist/services/doctor/doctor-service/plugin-registry.js +2 -0
  56. package/dist/services/hooks/hook-payload-cwd.d.ts +11 -4
  57. package/dist/services/hooks/hook-payload-cwd.js +11 -4
  58. package/dist/services/hooks/presence-marker-detector.d.ts +3 -0
  59. package/dist/services/hooks/presence-marker-detector.js +21 -19
  60. package/dist/services/ide/adapters/claude-code-adapter.js +6 -8
  61. package/dist/services/ide/adapters/codex-adapter.js +23 -7
  62. package/dist/services/ide/adapters/cursor-adapter.js +23 -7
  63. package/dist/services/mode/mode-status-service.d.ts +26 -27
  64. package/dist/services/mode/mode-status-service.js +36 -60
  65. package/dist/services/preferences/preferences-types.d.ts +30 -0
  66. package/dist/services/preferences/preferences-types.js +13 -0
  67. package/dist/services/scan/acceptance-coverage-service.d.ts +14 -11
  68. package/dist/services/scan/acceptance-coverage-service.js +157 -52
  69. package/dist/services/scan/rid-change-claims.d.ts +15 -0
  70. package/dist/services/scan/rid-change-claims.js +116 -0
  71. package/dist/services/skills/presence-caller-id.d.ts +51 -0
  72. package/dist/services/skills/presence-caller-id.js +43 -0
  73. package/dist/services/skills/presence-gate.d.ts +65 -0
  74. package/dist/services/skills/presence-gate.js +113 -0
  75. package/dist/services/skills/presence-lease-resolver.d.ts +63 -0
  76. package/dist/services/skills/presence-lease-resolver.js +114 -0
  77. package/dist/services/skills/presence-lease-selection.d.ts +91 -0
  78. package/dist/services/skills/presence-lease-selection.js +135 -0
  79. package/dist/services/skills/presence-lease-service.d.ts +3 -11
  80. package/dist/services/skills/presence-lease-service.js +34 -87
  81. package/dist/services/skills/presence-lease-store.d.ts +33 -0
  82. package/dist/services/skills/presence-lease-store.js +94 -0
  83. package/dist/services/skills/presence-lease-types.d.ts +31 -0
  84. package/dist/services/skills/presence-lease-types.js +27 -0
  85. package/dist/services/skills/presence-role.d.ts +35 -0
  86. package/dist/services/skills/presence-role.js +72 -0
  87. package/dist/services/skills/skill-presence-service.d.ts +39 -9
  88. package/dist/services/skills/skill-presence-service.js +143 -174
  89. package/dist/services/skills/skill-presence-write.d.ts +60 -0
  90. package/dist/services/skills/skill-presence-write.js +74 -0
  91. package/dist/services/skills/skill-statusline-service.js +7 -7
  92. package/dist/services/standards/ide-aware-standards-service.d.ts +35 -23
  93. package/dist/services/standards/ide-aware-standards-service.js +45 -20
  94. package/dist/services/standards/migrate-claude-rules-service.d.ts +6 -0
  95. package/dist/services/standards/migrate-claude-rules-service.js +18 -0
  96. package/dist/services/standards/migrate-service.d.ts +1 -1
  97. package/dist/services/standards/migrate-service.js +27 -7
  98. package/dist/services/standards/project-scripts.d.ts +25 -0
  99. package/dist/services/standards/project-scripts.js +116 -0
  100. package/dist/services/standards/project-standards-service.d.ts +23 -15
  101. package/dist/services/standards/project-standards-service.js +176 -243
  102. package/dist/services/standards/standards-constitution.d.ts +89 -0
  103. package/dist/services/standards/standards-constitution.js +199 -0
  104. package/dist/services/standards/standards-files.d.ts +37 -0
  105. package/dist/services/standards/standards-files.js +138 -0
  106. package/dist/services/standards/standards-pointer.d.ts +73 -0
  107. package/dist/services/standards/standards-pointer.js +98 -0
  108. package/dist/services/standards/standards-render-agents.d.ts +34 -0
  109. package/dist/services/standards/standards-render-agents.js +149 -0
  110. package/dist/services/standards/standards-render-common.d.ts +38 -1
  111. package/dist/services/standards/standards-render-common.js +44 -7
  112. package/dist/services/standards/standards-render.d.ts +1 -3
  113. package/dist/services/standards/standards-render.js +6 -87
  114. package/dist/services/workflow/workflow-graph-ensure.d.ts +77 -0
  115. package/dist/services/workflow/workflow-graph-ensure.js +97 -0
  116. package/dist/services/workflow/workflow-presence-lifecycle.js +21 -6
  117. package/dist/services/workspace/generated-artifacts-content.d.ts +46 -0
  118. package/dist/services/workspace/generated-artifacts-content.js +167 -0
  119. package/dist/services/workspace/generated-artifacts-stamp.d.ts +36 -13
  120. package/dist/services/workspace/generated-artifacts-stamp.js +37 -15
  121. package/dist/services/workspace/runtime-layout.d.ts +64 -0
  122. package/dist/services/workspace/runtime-layout.js +62 -0
  123. package/output-styles/peaks-skill-swarm.md +18 -2
  124. package/package.json +8 -9
  125. package/schemas/doctor-report.schema.json +1 -1
  126. package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
  127. package/skills/bee/peaks-prd/SKILL.md +5 -3
  128. package/skills/bee/peaks-qa/SKILL.md +4 -2
  129. package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
  130. package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
  131. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  132. package/skills/bee/peaks-rd/SKILL.md +4 -2
  133. package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
  134. package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
  135. package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
  136. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +4 -4
  137. package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
  138. package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
  139. package/skills/bee/peaks-reviewer/SKILL.md +3 -1
  140. package/skills/bee/peaks-sc/SKILL.md +4 -2
  141. package/skills/bee/peaks-security-audit/SKILL.md +3 -1
  142. package/skills/bee/peaks-txt/SKILL.md +5 -3
  143. package/skills/bee/peaks-ui/SKILL.md +6 -4
  144. package/skills/peaks-audit/SKILL.md +3 -1
  145. package/skills/peaks-code/SKILL.md +3 -1
  146. package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
  147. package/skills/peaks-code/references/completion-handoff.md +1 -1
  148. package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
  149. package/skills/peaks-code/references/micro-cycle.md +2 -2
  150. package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
  151. package/skills/peaks-code/references/runbook.md +4 -4
  152. package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
  153. package/skills/peaks-code/references/standards-preflight.md +7 -6
  154. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  155. package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
  156. package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
  157. package/skills/peaks-content/SKILL.md +3 -1
  158. package/skills/peaks-doctor/SKILL.md +3 -1
  159. package/skills/peaks-final-review/SKILL.md +3 -1
  160. package/skills/peaks-ide/SKILL.md +3 -1
  161. package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
  162. package/skills/peaks-race-code/SKILL.md +3 -1
  163. package/skills/peaks-resume/SKILL.md +3 -1
  164. package/skills/peaks-slice-decompose/SKILL.md +3 -1
  165. package/skills/peaks-solo/SKILL.md +3 -1
  166. package/skills/peaks-sop/SKILL.md +4 -2
  167. package/skills/peaks-status/SKILL.md +3 -1
  168. package/skills/peaks-test/SKILL.md +3 -1
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Content comparison for the artifacts `peaks workspace init` generates into a
3
+ * consumer project.
4
+ *
5
+ * WHY A SEPARATE MODULE. `generated-artifacts-stamp.ts` owns the stamp and the
6
+ * staleness verdict; this module owns ONE question — "do the bytes on disk still
7
+ * match what the current release renders?" — plus the per-artifact detail that
8
+ * answers it. Splitting them keeps both files inside the 300-line size cap.
9
+ *
10
+ * WHAT IS COMPARED. The rendered template (`buildClaudeSettingsLocalJson()`)
11
+ * against the content of each generated artifact. The predicate is
12
+ * `templateContentMatches` — the one the materializer uses to decide
13
+ * `already-current` — so the detector and the writer cannot disagree.
14
+ *
15
+ * WHY CONTAINMENT AND NOT BYTE EQUALITY. `templateContentMatches` asks whether
16
+ * every entry the template declares is PRESENT and ignores extra on-disk
17
+ * entries. `.claude/settings.local.json` has a second writer (the auto-compact
18
+ * installer appends a `Bash|Task` entry) and carries the user's own keys; a
19
+ * byte-equality rule would call every such project stale on every turn.
20
+ *
21
+ * A MISSING ARTIFACT IS NOT DRIFT. There is nothing on disk to compare, and the
22
+ * generator recreates it on the next init; the stamp's reason codes cover the
23
+ * "never initialized" and "not readable" cases.
24
+ */
25
+ /** One generated artifact that no longer matches the rendered template. */
26
+ export type GeneratedArtifactDrift = {
27
+ /**
28
+ * Project-root-relative path of the artifact, POSIX-separated so the warning
29
+ * names the same file on every platform.
30
+ */
31
+ readonly artifact: string;
32
+ /** What differs, in one clause a reader can act on. */
33
+ readonly detail: string;
34
+ };
35
+ /** The verdict, plus the detail behind it. */
36
+ export type GeneratedArtifactContentStatus = {
37
+ readonly drifted: boolean;
38
+ readonly drifts: ReadonlyArray<GeneratedArtifactDrift>;
39
+ };
40
+ /**
41
+ * Compare every generated artifact on disk against the current template.
42
+ *
43
+ * The verdict is `templateContentMatches` — the writer's own predicate — and
44
+ * the per-artifact detail is a best-effort localisation of WHAT differs.
45
+ */
46
+ export declare function compareGeneratedArtifactContent(projectRoot: string, artifactPaths: ReadonlyArray<string>): GeneratedArtifactContentStatus;
@@ -0,0 +1,167 @@
1
+ /**
2
+ * Content comparison for the artifacts `peaks workspace init` generates into a
3
+ * consumer project.
4
+ *
5
+ * WHY A SEPARATE MODULE. `generated-artifacts-stamp.ts` owns the stamp and the
6
+ * staleness verdict; this module owns ONE question — "do the bytes on disk still
7
+ * match what the current release renders?" — plus the per-artifact detail that
8
+ * answers it. Splitting them keeps both files inside the 300-line size cap.
9
+ *
10
+ * WHAT IS COMPARED. The rendered template (`buildClaudeSettingsLocalJson()`)
11
+ * against the content of each generated artifact. The predicate is
12
+ * `templateContentMatches` — the one the materializer uses to decide
13
+ * `already-current` — so the detector and the writer cannot disagree.
14
+ *
15
+ * WHY CONTAINMENT AND NOT BYTE EQUALITY. `templateContentMatches` asks whether
16
+ * every entry the template declares is PRESENT and ignores extra on-disk
17
+ * entries. `.claude/settings.local.json` has a second writer (the auto-compact
18
+ * installer appends a `Bash|Task` entry) and carries the user's own keys; a
19
+ * byte-equality rule would call every such project stale on every turn.
20
+ *
21
+ * A MISSING ARTIFACT IS NOT DRIFT. There is nothing on disk to compare, and the
22
+ * generator recreates it on the next init; the stamp's reason codes cover the
23
+ * "never initialized" and "not readable" cases.
24
+ */
25
+ import { existsSync, readFileSync } from 'node:fs';
26
+ import { join } from 'node:path';
27
+ import { normalizePath } from '../../shared/path-utils.js';
28
+ import { EXTERNAL_GATE_EXEMPT_ENV } from '../skills/hooks-codegate-superpowers.js';
29
+ import { buildClaudeSettingsLocalJson, templateContentMatches } from './claude-settings-template.js';
30
+ import { isPreToolUseEntry, isRetiredTemplateEntry } from './claude-settings-retirements.js';
31
+ /**
32
+ * Compare every generated artifact on disk against the current template.
33
+ *
34
+ * The verdict is `templateContentMatches` — the writer's own predicate — and
35
+ * the per-artifact detail is a best-effort localisation of WHAT differs.
36
+ */
37
+ export function compareGeneratedArtifactContent(projectRoot, artifactPaths) {
38
+ const template = buildClaudeSettingsLocalJson();
39
+ const rendered = JSON.stringify(template);
40
+ const drifts = [];
41
+ for (const artifact of artifactPaths) {
42
+ for (const detail of artifactDriftDetails(projectRoot, artifact, template, rendered)) {
43
+ drifts.push({ artifact: normalizePath(artifact), detail });
44
+ }
45
+ }
46
+ return { drifted: drifts.length > 0, drifts };
47
+ }
48
+ /** The details for ONE artifact. Empty when it matches or is absent. */
49
+ function artifactDriftDetails(projectRoot, artifact, template, rendered) {
50
+ const path = join(projectRoot, artifact);
51
+ if (!existsSync(path))
52
+ return [];
53
+ let content;
54
+ try {
55
+ content = readFileSync(path, 'utf8');
56
+ }
57
+ catch {
58
+ return ['the file could not be read'];
59
+ }
60
+ if (templateContentMatches(rendered, content))
61
+ return [];
62
+ return contentDiffDetails(template, content);
63
+ }
64
+ /** Name what differs between the rendered template and the on-disk content. */
65
+ function contentDiffDetails(template, content) {
66
+ const parsed = parseJsonObject(content);
67
+ if (!parsed.ok)
68
+ return [parsed.reason];
69
+ const details = [
70
+ ...missingEntryDetails(template.hooks.PreToolUse, parsed.value.hooks),
71
+ ...retiredEntryDetails(parsed.value.hooks),
72
+ ...missingExemptionDetails(parsed.value.env)
73
+ ];
74
+ return details.length > 0 ? details : ['the content differs from the current template'];
75
+ }
76
+ /**
77
+ * The parsed top-level object of a settings file, or the reason there is none —
78
+ * DISCRIMINATED: "not JSON" and "JSON but not an object" are different facts.
79
+ */
80
+ function parseJsonObject(content) {
81
+ try {
82
+ const parsed = JSON.parse(content);
83
+ if (!isPlainRecord(parsed))
84
+ return { ok: false, reason: 'the file is not a JSON object' };
85
+ return { ok: true, value: parsed };
86
+ }
87
+ catch {
88
+ return { ok: false, reason: 'the file is not valid JSON' };
89
+ }
90
+ }
91
+ /**
92
+ * The template entries the on-disk file does not carry. Matching is
93
+ * multiset-aware: the template declares TWO `Bash` entries and each needs its
94
+ * own counterpart, so a file holding one copy is still drift.
95
+ */
96
+ function missingEntryDetails(templateEntries, onDiskHooks) {
97
+ const onDiskEntries = preToolUseEntries(onDiskHooks);
98
+ if (onDiskEntries === undefined) {
99
+ return [
100
+ `hooks.PreToolUse is missing (the template declares ${templateEntries.length} entries)`
101
+ ];
102
+ }
103
+ const unmatched = [...onDiskEntries];
104
+ const details = [];
105
+ templateEntries.forEach((required, index) => {
106
+ const at = unmatched.findIndex((candidate) => sameEntry(required, candidate));
107
+ if (at === -1) {
108
+ details.push(`hooks.PreToolUse entry #${index + 1} (matcher "${required.matcher}") is missing or differs`);
109
+ return;
110
+ }
111
+ unmatched.splice(at, 1);
112
+ });
113
+ return details;
114
+ }
115
+ /** The on-disk `hooks.PreToolUse` entries, or `undefined` when there are none. */
116
+ function preToolUseEntries(hooks) {
117
+ if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks))
118
+ return undefined;
119
+ const entries = hooks.PreToolUse;
120
+ if (!Array.isArray(entries))
121
+ return undefined;
122
+ return entries.filter(isPreToolUseEntry);
123
+ }
124
+ /** Structural equality of two `PreToolUse` entries. */
125
+ function sameEntry(required, candidate) {
126
+ if (required.matcher !== candidate.matcher)
127
+ return false;
128
+ if (required.hooks.length !== candidate.hooks.length)
129
+ return false;
130
+ return required.hooks.every((handler, index) => {
131
+ const other = candidate.hooks[index];
132
+ if (other === undefined)
133
+ return false;
134
+ return (handler.type === other.type &&
135
+ handler.command === other.command &&
136
+ handler.shell === other.shell);
137
+ });
138
+ }
139
+ /** The retired entries the on-disk file still carries, if any. */
140
+ function retiredEntryDetails(onDiskHooks) {
141
+ const entries = preToolUseEntries(onDiskHooks);
142
+ if (entries === undefined)
143
+ return [];
144
+ const retired = entries.filter((entry) => isRetiredTemplateEntry(entry));
145
+ return retired.length === 0 ? [] : ['hooks.PreToolUse carries an entry this release retired'];
146
+ }
147
+ /** The gate exemptions the on-disk file does not declare. */
148
+ function missingExemptionDetails(onDiskEnv) {
149
+ const env = isPlainRecord(onDiskEnv) ? onDiskEnv : {};
150
+ const details = [];
151
+ for (const [key, glob] of Object.entries(EXTERNAL_GATE_EXEMPT_ENV)) {
152
+ const current = env[key];
153
+ const declared = typeof current === 'string' &&
154
+ current
155
+ .split(',')
156
+ .map((part) => part.trim())
157
+ .includes(glob);
158
+ if (!declared) {
159
+ details.push(`env.${key} does not declare "${glob}"`);
160
+ }
161
+ }
162
+ return details;
163
+ }
164
+ /** A JSON object, as opposed to a null / array / primitive. */
165
+ function isPlainRecord(value) {
166
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
167
+ }
@@ -28,18 +28,32 @@
28
28
  * machine-local bookkeeping (`session.json`, `.outer-session-cache.json`), so
29
29
  * the stamp lives beside them and needs no new `.gitignore` line.
30
30
  *
31
- * WHAT IS COMPARED. Two versions, because they move independently and a
32
- * mismatch of either means the same thing to the user (regenerate):
33
- * - `packageVersion` — the installed peaks-loop release. Moves on `npm i -g`.
34
- * - `templateVersion` — `TEMPLATE_VERSION`, the shape of the hooks tree this
35
- * release emits. Can move without a release the user would notice.
31
+ * WHAT IS COMPARED. The CONTENT of the generated artifacts, against the
32
+ * current release's rendered template — not the release number that wrote them.
33
+ * A release bump is not a change to the bytes: `packageVersion` moves on every
34
+ * publish, so a version comparison reports "behind" on every project that
35
+ * upgraded without re-running init, forever. Such a warning carries no action,
36
+ * and a warning that carries no action is noise the reader learns to ignore —
37
+ * which is the state this detector was built to end.
38
+ *
39
+ * So the verdict is a content verdict:
40
+ * - the rendered template (`buildClaudeSettingsLocalJson()`) is compared
41
+ * against `.claude/settings.local.json` and the offline template copy by
42
+ * `templateContentMatches` — the same predicate the materializer uses to
43
+ * decide `already-current`, so the detector and the writer cannot disagree
44
+ * about what "current" means;
45
+ * - `templateVersion` still decides on its own: a different template shape
46
+ * means the artifacts were written by a release whose hooks tree this one
47
+ * does not carry, which is staleness whatever the bytes look like;
48
+ * - `packageVersion` is reported as INFORMATION (which release wrote the
49
+ * artifacts on disk) and does not make a project stale on its own.
36
50
  *
37
51
  * The stamp records what the generator LAST WROTE. It is not a promise that
38
52
  * the on-disk artifacts still match it — a user may have hand-edited
39
- * `.claude/settings.local.json` since. That question is the existing
40
- * `templateContentMatches` comparator's, and it is asked on the next init,
41
- * which is what this detector tells the user to trigger.
53
+ * `.claude/settings.local.json` since, and that is drift the content
54
+ * comparison now detects.
42
55
  */
56
+ import { type GeneratedArtifactDrift } from './generated-artifacts-content.js';
43
57
  /**
44
58
  * Where the stamp lives, relative to the project root.
45
59
  *
@@ -62,12 +76,15 @@ export type GeneratedArtifactsStamp = {
62
76
  readonly writtenAt: string;
63
77
  };
64
78
  export type GeneratedArtifactsStaleness = {
65
- /** `true` only when a generated artifact exists AND its stamp is behind. */
79
+ /** `true` only when a generated artifact's CONTENT no longer matches the current template. */
66
80
  readonly stale: boolean;
67
81
  /**
68
- * Machine-readable reason codes, empty when `stale` is false:
69
- * - `package-upgraded` — on-disk stamp names an older peaks-loop release
70
- * - `template-changed` — on-disk stamp names an older template shape
82
+ * Machine-readable reason codes. `package-upgraded` is INFORMATION — which
83
+ * release wrote the artifacts — and does not by itself make `stale` true;
84
+ * every other code does.
85
+ * - `package-upgraded` — on-disk stamp names a different peaks-loop release
86
+ * - `template-changed` — on-disk stamp names a different template shape
87
+ * - `content-drift` — a generated artifact no longer matches the rendered template
71
88
  * - `unstamped` — artifacts exist but predate this stamp
72
89
  * - `stamp-unreadable` — a stamp file exists but is not parseable
73
90
  */
@@ -77,6 +94,8 @@ export type GeneratedArtifactsStaleness = {
77
94
  readonly packageVersion: string;
78
95
  readonly templateVersion: string;
79
96
  };
97
+ /** What differs, per artifact, for a `content-drift` verdict. Empty otherwise. */
98
+ readonly drift: ReadonlyArray<GeneratedArtifactDrift>;
80
99
  };
81
100
  export declare function generatedArtifactsStampPath(projectRoot: string): string;
82
101
  /**
@@ -110,7 +129,11 @@ export declare function writeGeneratedArtifactsStamp(projectRoot: string, option
110
129
  * Returns `stale: false` — with no reasons — for the two cases that are NOT
111
130
  * staleness:
112
131
  * - the project has no generated artifact at all (never initialized), and
113
- * - the stamp matches both expected versions.
132
+ * - the artifacts' CONTENT still matches the current template.
133
+ *
134
+ * A `packageVersion` that differs from the installed release is reported in
135
+ * `reasons` as information and does NOT make the project stale: a release bump
136
+ * moves that number on every publish, while the generated bytes stand still.
114
137
  *
115
138
  * `unstamped` is reported only when an artifact EXISTS and no stamp does:
116
139
  * those are projects initialized by a release that predates this module, and
@@ -28,23 +28,37 @@
28
28
  * machine-local bookkeeping (`session.json`, `.outer-session-cache.json`), so
29
29
  * the stamp lives beside them and needs no new `.gitignore` line.
30
30
  *
31
- * WHAT IS COMPARED. Two versions, because they move independently and a
32
- * mismatch of either means the same thing to the user (regenerate):
33
- * - `packageVersion` — the installed peaks-loop release. Moves on `npm i -g`.
34
- * - `templateVersion` — `TEMPLATE_VERSION`, the shape of the hooks tree this
35
- * release emits. Can move without a release the user would notice.
31
+ * WHAT IS COMPARED. The CONTENT of the generated artifacts, against the
32
+ * current release's rendered template — not the release number that wrote them.
33
+ * A release bump is not a change to the bytes: `packageVersion` moves on every
34
+ * publish, so a version comparison reports "behind" on every project that
35
+ * upgraded without re-running init, forever. Such a warning carries no action,
36
+ * and a warning that carries no action is noise the reader learns to ignore —
37
+ * which is the state this detector was built to end.
38
+ *
39
+ * So the verdict is a content verdict:
40
+ * - the rendered template (`buildClaudeSettingsLocalJson()`) is compared
41
+ * against `.claude/settings.local.json` and the offline template copy by
42
+ * `templateContentMatches` — the same predicate the materializer uses to
43
+ * decide `already-current`, so the detector and the writer cannot disagree
44
+ * about what "current" means;
45
+ * - `templateVersion` still decides on its own: a different template shape
46
+ * means the artifacts were written by a release whose hooks tree this one
47
+ * does not carry, which is staleness whatever the bytes look like;
48
+ * - `packageVersion` is reported as INFORMATION (which release wrote the
49
+ * artifacts on disk) and does not make a project stale on its own.
36
50
  *
37
51
  * The stamp records what the generator LAST WROTE. It is not a promise that
38
52
  * the on-disk artifacts still match it — a user may have hand-edited
39
- * `.claude/settings.local.json` since. That question is the existing
40
- * `templateContentMatches` comparator's, and it is asked on the next init,
41
- * which is what this detector tells the user to trigger.
53
+ * `.claude/settings.local.json` since, and that is drift the content
54
+ * comparison now detects.
42
55
  */
43
56
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
44
57
  import { dirname, join } from 'node:path';
45
58
  import { CLI_VERSION } from 'peaks-loop-shared/version';
46
59
  import { isExpectedFsMiss } from '../../shared/fs-utils.js';
47
60
  import { TEMPLATE_VERSION } from './claude-settings-template.js';
61
+ import { compareGeneratedArtifactContent } from './generated-artifacts-content.js';
48
62
  /**
49
63
  * Where the stamp lives, relative to the project root.
50
64
  *
@@ -139,7 +153,11 @@ export function writeGeneratedArtifactsStamp(projectRoot, options = {}) {
139
153
  * Returns `stale: false` — with no reasons — for the two cases that are NOT
140
154
  * staleness:
141
155
  * - the project has no generated artifact at all (never initialized), and
142
- * - the stamp matches both expected versions.
156
+ * - the artifacts' CONTENT still matches the current template.
157
+ *
158
+ * A `packageVersion` that differs from the installed release is reported in
159
+ * `reasons` as information and does NOT make the project stale: a release bump
160
+ * moves that number on every publish, while the generated bytes stand still.
143
161
  *
144
162
  * `unstamped` is reported only when an artifact EXISTS and no stamp does:
145
163
  * those are projects initialized by a release that predates this module, and
@@ -150,18 +168,22 @@ export function detectStaleGeneratedArtifacts(projectRoot) {
150
168
  const onDisk = readGeneratedArtifactsStamp(projectRoot);
151
169
  const artifactsPresent = hasGeneratedArtifact(projectRoot);
152
170
  if (!artifactsPresent) {
153
- return { stale: false, reasons: [], onDisk, expected };
171
+ return { stale: false, reasons: [], onDisk, expected, drift: [] };
154
172
  }
155
173
  if (existsSync(generatedArtifactsStampPath(projectRoot)) && onDisk === null) {
156
- return { stale: true, reasons: ['stamp-unreadable'], onDisk, expected };
174
+ return { stale: true, reasons: ['stamp-unreadable'], onDisk, expected, drift: [] };
157
175
  }
158
176
  if (onDisk === null) {
159
- return { stale: true, reasons: ['unstamped'], onDisk, expected };
177
+ return { stale: true, reasons: ['unstamped'], onDisk, expected, drift: [] };
160
178
  }
179
+ const content = compareGeneratedArtifactContent(projectRoot, GENERATED_ARTIFACT_RELATIVE_PATHS);
161
180
  const reasons = [];
162
- if (onDisk.packageVersion !== expected.packageVersion)
163
- reasons.push('package-upgraded');
164
181
  if (onDisk.templateVersion !== expected.templateVersion)
165
182
  reasons.push('template-changed');
166
- return { stale: reasons.length > 0, reasons, onDisk, expected };
183
+ if (onDisk.packageVersion !== expected.packageVersion)
184
+ reasons.push('package-upgraded');
185
+ if (content.drifted)
186
+ reasons.push('content-drift');
187
+ const stale = reasons.includes('template-changed') || reasons.includes('content-drift');
188
+ return { stale, reasons, onDisk, expected, drift: content.drifts };
167
189
  }
@@ -89,3 +89,67 @@ export declare const RUNTIME_SYSTEM_ENTRIES: readonly RuntimeSystemEntry[];
89
89
  * above so the check and the census cannot disagree about the same name.
90
90
  */
91
91
  export declare const RUNTIME_SYSTEM_SUBDIRS: ReadonlySet<string>;
92
+ /**
93
+ * Every registered top-level name — dirs AND files.
94
+ *
95
+ * Derived from the registry above so the census and the registry cannot
96
+ * disagree about what "registered" means.
97
+ */
98
+ export declare const RUNTIME_SYSTEM_ENTRY_NAMES: ReadonlySet<string>;
99
+ /** One top-level entry under the runtime root, as the census sees it. */
100
+ export interface RuntimeRootEntry {
101
+ /** The exact top-level name. */
102
+ readonly name: string;
103
+ /** `dir` for a directory, `file` for everything else. */
104
+ readonly kind: RuntimeEntryKind;
105
+ }
106
+ /** One top-level entry that is neither a session dir nor a registered system entry. */
107
+ export interface RuntimeRootViolation {
108
+ readonly name: string;
109
+ readonly kind: RuntimeEntryKind;
110
+ }
111
+ /**
112
+ * What a read of the runtime root produced.
113
+ *
114
+ * `unreadable` is a first-class outcome, not an exception: a sweep that cannot
115
+ * look must not report "clean" — the one answer it is not entitled to give
116
+ * (see `services/audit/enforcers/root-scratch-artifacts.ts`).
117
+ */
118
+ export type RuntimeRootRead = {
119
+ readonly status: 'read';
120
+ readonly entries: readonly RuntimeRootEntry[];
121
+ } | {
122
+ readonly status: 'unreadable';
123
+ readonly reason: string;
124
+ };
125
+ /**
126
+ * The census verdict. `clean` is reachable ONLY for a tree that was read.
127
+ */
128
+ export type RuntimeRootCensus = {
129
+ readonly status: 'clean';
130
+ readonly entryCount: number;
131
+ } | {
132
+ readonly status: 'violations';
133
+ readonly violations: readonly RuntimeRootViolation[];
134
+ } | {
135
+ readonly status: 'undetermined';
136
+ readonly reason: string;
137
+ };
138
+ /**
139
+ * The census: every top-level entry of the runtime root that is neither a
140
+ * session dir nor a registered system entry.
141
+ *
142
+ * Three classes, in this order:
143
+ *
144
+ * 1. a DIRECTORY whose name is a valid session id — legal. A FILE wearing a
145
+ * session-shaped name is NOT legal: only a directory can be a session
146
+ * home, so such a file is a stray.
147
+ * 2. a name in `RUNTIME_SYSTEM_ENTRIES` — legal, whatever its kind. The
148
+ * registry is the authority on which names may sit at the root.
149
+ * 3. everything else — a violation, reported with its name AND its kind.
150
+ */
151
+ export declare function censusRuntimeRoot(input: {
152
+ readonly read: RuntimeRootRead;
153
+ /** Defaults to the canonical validator; the doctor injects its own. */
154
+ readonly isValidSessionId?: (sid: string) => boolean;
155
+ }): RuntimeRootCensus;
@@ -47,6 +47,7 @@
47
47
  * walk. See `tests/unit/runtime/no-runtime-input-guard.test.ts` for the same
48
48
  * decision made the same way.
49
49
  */
50
+ import { isValidSessionId as canonicalIsValidSessionId } from './sid-naming-guard.js';
50
51
  /**
51
52
  * Reserved top-level dir for session-less command output.
52
53
  *
@@ -139,6 +140,11 @@ export const RUNTIME_SYSTEM_ENTRIES = [
139
140
  name: '.rebuild-binding.lock',
140
141
  kind: 'file',
141
142
  purpose: 'binding-store rebuild lock (session/binding-store.ts)'
143
+ },
144
+ {
145
+ name: 'classify-audit.jsonl',
146
+ kind: 'file',
147
+ purpose: "append-only classify audit log at the runtime root (cli/commands/classify-signals.ts); the path is built dynamically, so the drift guard's AST scan never saw it as a child — the census is what catches it"
142
148
  }
143
149
  ];
144
150
  /**
@@ -146,3 +152,59 @@ export const RUNTIME_SYSTEM_ENTRIES = [
146
152
  * above so the check and the census cannot disagree about the same name.
147
153
  */
148
154
  export const RUNTIME_SYSTEM_SUBDIRS = new Set(RUNTIME_SYSTEM_ENTRIES.filter((entry) => entry.kind === 'dir').map((entry) => entry.name));
155
+ // ---------------------------------------------------------------------------
156
+ // THE CENSUS
157
+ // ---------------------------------------------------------------------------
158
+ //
159
+ // WHY THE REGISTRY WAS NOT ENOUGH. The registry is a list of NAMES the code
160
+ // writes at the runtime root. Until now, only ONE of the two guards could see
161
+ // the tree it governs:
162
+ //
163
+ // - `L3:l3-orphan-sessions` reads DIRECTORIES only. It could never see a
164
+ // stray FILE at the root, so unregistered files accumulated unbounded
165
+ // (204 of them on 2026-10-24) with no product check able to name them.
166
+ // - `tests/unit/workspace/runtime-layout-drift-guard.test.ts` walks `src/**`,
167
+ // not the working tree. It proved the CODE does not write an unregistered
168
+ // child — it said nothing about what is actually sitting on disk.
169
+ //
170
+ // The census below closes the gap: it reads the REAL tree, compares it with
171
+ // the registry above, and reports every top-level entry that is neither a
172
+ // session dir nor a registered system entry — files included.
173
+ //
174
+ // IT IS PURE ON PURPOSE. The caller reads the entries off disk and hands them
175
+ // in; this module does no IO. That is what makes the decision unit-testable
176
+ // without a filesystem, and it keeps the registry module a registry.
177
+ /**
178
+ * Every registered top-level name — dirs AND files.
179
+ *
180
+ * Derived from the registry above so the census and the registry cannot
181
+ * disagree about what "registered" means.
182
+ */
183
+ export const RUNTIME_SYSTEM_ENTRY_NAMES = new Set(RUNTIME_SYSTEM_ENTRIES.map((entry) => entry.name));
184
+ /**
185
+ * The census: every top-level entry of the runtime root that is neither a
186
+ * session dir nor a registered system entry.
187
+ *
188
+ * Three classes, in this order:
189
+ *
190
+ * 1. a DIRECTORY whose name is a valid session id — legal. A FILE wearing a
191
+ * session-shaped name is NOT legal: only a directory can be a session
192
+ * home, so such a file is a stray.
193
+ * 2. a name in `RUNTIME_SYSTEM_ENTRIES` — legal, whatever its kind. The
194
+ * registry is the authority on which names may sit at the root.
195
+ * 3. everything else — a violation, reported with its name AND its kind.
196
+ */
197
+ export function censusRuntimeRoot(input) {
198
+ if (input.read.status === 'unreadable') {
199
+ return { status: 'undetermined', reason: input.read.reason };
200
+ }
201
+ const isValidSessionId = input.isValidSessionId ?? canonicalIsValidSessionId;
202
+ const violations = input.read.entries
203
+ .filter((entry) => !RUNTIME_SYSTEM_ENTRY_NAMES.has(entry.name))
204
+ .filter((entry) => !(entry.kind === 'dir' && isValidSessionId(entry.name)))
205
+ .map((entry) => ({ name: entry.name, kind: entry.kind }));
206
+ if (violations.length > 0) {
207
+ return { status: 'violations', violations };
208
+ }
209
+ return { status: 'clean', entryCount: input.read.entries.length };
210
+ }
@@ -45,12 +45,28 @@ For final evidence, prefer this visual block:
45
45
  └──────────────────────────────────────────
46
46
  ```
47
47
 
48
- For continuing turns in the same Peaks-Loop workflow, use a compact status header instead of the full banner:
48
+ For continuing turns in the same Peaks-Loop workflow, use a compact status header that **always surfaces both skill layers** — the active skill AND its role tier — plus the live context pressure, even when only the active skill is set:
49
49
 
50
50
  ```markdown
51
- Peaks-Loop Skill: <skill-name> | Peaks-Loop Gate: <current gate> | Next: <one short action>
51
+ Peaks-Loop Skill: <skill-name> | Peaks-Loop Role: <tier> | Peaks-Loop Gate: <current gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>
52
52
  ```
53
53
 
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
+
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.
58
+
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
+
61
+ `<tier>`, `<current gate>`, `<ratio%>` and `<zone>` are all **machine facts** — copy them verbatim from the same `peaks skill presence --json` read, never estimate them:
62
+
63
+ - `data.role` → the tier above (`orchestrator` / `bee`; `null` for an unknown skill).
64
+ - `data.gate` → the current gate.
65
+ - `data.context.ratioPct` → the context fill, e.g. `42.3%`.
66
+ - `data.context.action` → the zone, one of `none` / `soft-warn` / `auto-fire` / `pre-compact` / `red-line`.
67
+
68
+ **Persistence rule:** The active Peaks-Loop skill name and gate are persisted to the session-scoped presence lease at `.peaks/_runtime/<session-id>/leases/presence-*.json` (the canonical path; the project-level single-slot `active-skill.json` files were removed in 4.0.11). Read the active marker via `peaks skill presence --json` at the start of EVERY response when a Peaks-Loop skill workflow is active — the CLI resolves the lease across the project's session trees, do not read those files directly. If the CLI returns a valid skill, always show the compact header — even if this is the first turn of a new conversation, even after context compaction, and without exception. Only omit the header when the CLI reports no active skill. This ensures users unfamiliar with Claude Code's skill system always see which Peaks-Loop skill is orchestrating their session.
69
+
54
70
  Structure active Peaks-Loop responses around:
55
71
 
56
72
  1. **Peaks-Loop Role** — name the active Peaks-Loop role or role chain, for example PRD → RD → QA → SC.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.18",
3
+ "version": "4.1.19",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -131,16 +131,15 @@
131
131
  "picomatch": "4.0.7",
132
132
  "yaml": "^2.9.1",
133
133
  "zod": "^4.6.7",
134
- "peaks-loop-internal-runtime": "0.0.58",
135
- "peaks-loop-mut": "0.1.72",
136
- "peaks-loop-shared": "0.0.107",
137
- "peaks-loop-shared-channel": "0.0.75"
134
+ "peaks-loop-internal-runtime": "0.0.59",
135
+ "peaks-loop-shared": "0.0.108",
136
+ "peaks-loop-shared-channel": "0.0.76",
137
+ "peaks-loop-mut": "0.1.73"
138
138
  },
139
139
  "devDependencies": {
140
140
  "@changesets/cli": "2.31.1",
141
141
  "@jridgewell/trace-mapping": "^0.3.31",
142
- "@stryker-mutator/core": "^8.7.1",
143
- "@stryker-mutator/typescript-checker": "^8.7.1",
142
+ "@stryker-mutator/core": "^9.6.1",
144
143
  "@stryker-mutator/vitest-runner": "^9.6.1",
145
144
  "@types/node": "^24.19.1",
146
145
  "@types/picomatch": "4.0.3",
@@ -191,8 +190,8 @@
191
190
  "test:coverage:workflow": "vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",
192
191
  "schema:generate": "node scripts/generate-context-schema.mjs",
193
192
  "typecheck": "tsc -p tsconfig.json --noEmit && vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",
194
- "mut:run": "peaks mut run --project . --out mut-report.json",
195
- "mut:scan": "peaks mut asserts --in mut-report.json",
193
+ "mut:run": "peaks mut run --project . --test-files tests/unit/cli/commands/verdict-aggregate-missing-evidence.test.ts --mutate src/cli/commands/verdict-aggregate-command.ts src/shared/path-safety.ts src/services/workflow/pipeline-verify-qa-phase.ts src/cli/cli-helpers.ts --input-sig 0000000000000000000000000000000000000000000000000000000000000000 --session-id 00000000000000000000000000000000 --out .peaks/_runtime/00000000000000000000000000000000/mut/mut-report.json --json",
194
+ "mut:scan": "peaks mut asserts --project . --test-files tests/unit/cli/commands/verdict-aggregate-missing-evidence.test.ts --input-sig 0000000000000000000000000000000000000000000000000000000000000000 --session-id 00000000000000000000000000000000 --out .peaks/_runtime/00000000000000000000000000000000/mut/mut-asserts-report.json --json",
196
195
  "audit:prose-ratio": "peaks audit prose-ratio --project .",
197
196
  "dogfood:sediment": "bash scripts/dogfood-sediment-cycle.sh",
198
197
  "lint": "node ./scripts/lint/run-lint.mjs",
@@ -14,7 +14,7 @@
14
14
  "id": {
15
15
  "type": "string",
16
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/**)."
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; the store target carries the store-level outcome — in parity, nothing to compare, absent, or unreadable), 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 }
@@ -17,8 +17,10 @@ metadata:
17
17
  ## Loop hygiene (every turn — MANDATORY)
18
18
 
19
19
  **Skill header.** While this skill is active, open every turn with
20
- `Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
20
+ `Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`.
21
21
  Every turn, not only the first — it is how the user knows which skill is driving.
22
+ `Role` and `Context` are machine facts: copy them from `peaks skill presence --json`
23
+ (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them.
22
24
 
23
25
  **Context is this skill's own business.** Run `peaks skill presence --json` every turn and
24
26
  read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,