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
@@ -1,7 +1,19 @@
1
1
  import { FileSizeViolationError } from './request-artifact-state-helpers.js';
2
2
  import { readGitChangeSet } from '../scan/file-size-baseline.js';
3
3
  import { scanFileSize } from '../scan/file-size-scan.js';
4
- import { corroborateDeclaredType, diffUnavailableVerdict, isToolingOnlyDeclaredType } from '../scan/type-corroboration.js';
4
+ import { corroborateDeclaredType, diffUnavailableVerdict, isProductSourcePath, isToolingOnlyDeclaredType } from '../scan/type-corroboration.js';
5
+ import { isArtifactWorkspaceFile } from '../scan/type-sanity-service.js';
6
+ import { listSessionRdArtifactIds, readRidChangeClaims } from '../scan/rid-change-claims.js';
7
+ import { slugifyDescription } from '../../shared/incrementing-number.js';
8
+ import { normalizePath } from '../../shared/path-utils.js';
9
+ /**
10
+ * True for the three states the RD gates judge. A type PREDICATE, so a caller
11
+ * that filters on it keeps the narrowed state — the old inline `||` chain did
12
+ * the same narrowing, and losing it would make the phase un-assignable.
13
+ */
14
+ export function isRdGatePhase(state) {
15
+ return state === 'implemented' || state === 'qa-handoff' || state === 'handed-off';
16
+ }
5
17
  export class TypeCorroborationViolationError extends Error {
6
18
  code = 'TYPE_CORROBORATION_VIOLATION';
7
19
  declaredType;
@@ -31,6 +43,74 @@ function readOrRefuse(projectRoot, declaredType) {
31
43
  throw new TypeCorroborationViolationError(declaredType, diffUnavailableVerdict(declaredType));
32
44
  }
33
45
  }
46
+ /** The note written when the anti-lie fallback could not run. */
47
+ function fallbackDisabledNote(sessionId, missing, total) {
48
+ return (`认领表不完整,反撒谎兜底未启用:session '${sessionId}' 的 ${total} 个 RD artifact 中有 ` +
49
+ `${missing} 个未带 "## Changed paths" 段,无法证明工作树里没有无人认领的产品源文件改动 ` +
50
+ '(the anti-lie fallback is disabled while the session claim table is incomplete).');
51
+ }
52
+ /** The refusal for product-source changes that NO rid claimed. */
53
+ function unclaimedMessage(declaredType, paths) {
54
+ return (`Unclaimed product source changes cannot ride a '${declaredType}' request: ${paths.join(', ')} — ` +
55
+ 'these paths are changed in the working tree and no request artifact in this session claimed ' +
56
+ 'them in a "## Changed paths" section. A docs/chore/config request selects a reduced ' +
57
+ 'prerequisite table, so it may not carry src/** or packages/<name>/src/** changes: declare ' +
58
+ 'feature, bugfix or refactor (which carry the full QA evidence), have the owning rid claim ' +
59
+ 'the path, or move the change out of product source.');
60
+ }
61
+ /** The product-source paths in the working tree that no rid claimed. */
62
+ function unclaimedSourcePaths(worktreePaths, claims) {
63
+ const claimed = new Set();
64
+ for (const paths of claims.values()) {
65
+ for (const path of paths)
66
+ claimed.add(normalizePath(path));
67
+ }
68
+ return worktreePaths.filter((file) => !isArtifactWorkspaceFile(file) &&
69
+ isProductSourcePath(file) &&
70
+ !claimed.has(normalizePath(file)));
71
+ }
72
+ /**
73
+ * The declared type judged against the RID's own paths, with the anti-lie
74
+ * fallback beside it.
75
+ */
76
+ function judgeDeclaredType(options) {
77
+ const claims = readRidChangeClaims(options.projectRoot, options.sessionId);
78
+ const artifactIds = listSessionRdArtifactIds(options.projectRoot, options.sessionId);
79
+ const own = claims.get(options.requestId) ?? claims.get(slugifyDescription(options.requestId));
80
+ // (A) The anti-lie fallback — only when EVERY rid artifact in the session
81
+ // declares its paths. An incomplete table cannot prove "nobody claimed it".
82
+ const missing = artifactIds.filter((rid) => !claims.has(rid));
83
+ const tableComplete = artifactIds.length > 0 && missing.length === 0;
84
+ let note = null;
85
+ if (tableComplete) {
86
+ const unclaimed = unclaimedSourcePaths(options.worktreePaths, claims);
87
+ if (unclaimed.length > 0) {
88
+ return {
89
+ ok: false,
90
+ kind: 'source-unclaimed',
91
+ message: unclaimedMessage(options.declaredType, unclaimed)
92
+ };
93
+ }
94
+ }
95
+ else {
96
+ note = fallbackDisabledNote(options.sessionId, missing.length, artifactIds.length);
97
+ }
98
+ // (B) The rid's own declaration; the whole working tree when it declared none.
99
+ const scope = own ?? options.worktreePaths;
100
+ const verdict = corroborateDeclaredType({
101
+ projectRoot: options.projectRoot,
102
+ declaredType: options.declaredType,
103
+ changedPaths: scope
104
+ });
105
+ if (!verdict.ok) {
106
+ // The refusal carries the same statement the passing note does: when the
107
+ // anti-lie fallback stood down, a reader of the refusal alone must not be
108
+ // left thinking it was in force.
109
+ const message = note === null ? verdict.message : `${verdict.message} ${note}`;
110
+ return { ok: false, kind: verdict.kind, message };
111
+ }
112
+ return { ok: true, note };
113
+ }
34
114
  export function runRdTransitionGates(options) {
35
115
  const judged = isToolingOnlyDeclaredType(options.declaredType);
36
116
  if (options.allowIncomplete)
@@ -44,28 +124,25 @@ export function runRdTransitionGates(options) {
44
124
  }
45
125
  return null;
46
126
  }
47
- if (options.phase !== 'implemented') {
48
- const verdict = corroborateDeclaredType({
49
- projectRoot: options.projectRoot,
50
- declaredType: options.declaredType
51
- });
52
- if (!verdict.ok)
53
- throw new TypeCorroborationViolationError(options.declaredType, verdict);
54
- return null;
55
- }
127
+ // ONE enumeration for the whole transition: the type rule judges the rid's own
128
+ // paths against the same working-tree read the size ratchet measures.
56
129
  const changeSet = readOrRefuse(options.projectRoot, options.declaredType);
57
- const verdict = corroborateDeclaredType({
130
+ const verdict = judgeDeclaredType({
58
131
  projectRoot: options.projectRoot,
59
132
  declaredType: options.declaredType,
60
- changedPaths: changeSet.changedPaths
133
+ requestId: options.requestId,
134
+ sessionId: options.sessionId,
135
+ worktreePaths: changeSet.changedPaths
61
136
  });
62
137
  if (!verdict.ok)
63
138
  throw new TypeCorroborationViolationError(options.declaredType, verdict);
64
- const size = scanFileSize({
65
- projectRoot: options.projectRoot,
66
- changedFiles: changeSet.changedFiles
67
- });
68
- if (!size.ok)
69
- throw new FileSizeViolationError(size.violations);
70
- return null;
139
+ if (options.phase === 'implemented') {
140
+ const size = scanFileSize({
141
+ projectRoot: options.projectRoot,
142
+ changedFiles: changeSet.changedFiles
143
+ });
144
+ if (!size.ok)
145
+ throw new FileSizeViolationError(size.violations);
146
+ }
147
+ return verdict.note;
71
148
  }
@@ -15,7 +15,7 @@ import { isUnsafePathInput } from '../../shared/path-safety.js';
15
15
  import { guardRuntimeSegment, runtimeRoot } from '../../shared/runtime-root.js';
16
16
  import { checkTypeSanity } from '../scan/type-sanity-service.js';
17
17
  import { requireUserConfirmation } from '../mode/mode-enforcement.js';
18
- import { runRdTransitionGates } from './rd-transition-gates.js';
18
+ import { isRdGatePhase, runRdTransitionGates } from './rd-transition-gates.js';
19
19
  import { emitObservabilityEvent } from '../observability/observability-service.js';
20
20
  export { VALID_REQUEST_TYPES, DEFAULT_REQUEST_TYPE, isRequestType };
21
21
  // Re-export the pure-function template surface so external callers (CLI,
@@ -403,15 +403,15 @@ export async function transitionRequestArtifact(options) {
403
403
  }
404
404
  }
405
405
  }
406
- const gateBypassNote = options.role === 'rd' &&
407
- (options.newState === 'implemented' ||
408
- options.newState === 'qa-handoff' ||
409
- options.newState === 'handed-off')
406
+ // The phase test is a predicate, so the narrowed state reaches the gate.
407
+ const gateBypassNote = options.role === 'rd' && isRdGatePhase(options.newState)
410
408
  ? runRdTransitionGates({
411
409
  projectRoot: options.projectRoot,
412
410
  declaredType: existing.requestType,
413
411
  allowIncomplete: options.allowIncomplete === true,
414
- phase: options.newState
412
+ phase: options.newState,
413
+ requestId: options.requestId,
414
+ sessionId: existing.sessionId
415
415
  })
416
416
  : null;
417
417
  const clock = options.clock ?? defaultClock;
@@ -2,7 +2,8 @@
2
2
  * P2-a Theme C — output style enforcers.
3
3
  *
4
4
  * The peaks-loop dogfood rule: every skill response carries a status
5
- * header (`Peaks-Loop Skill: <name> | Peaks-Loop Gate: <gate> | Next:
5
+ * header (`Peaks-Loop Skill: <name> | Peaks-Loop Role: <tier> |
6
+ * Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next:
6
7
  * <action>`), the SKILL.md body has no greeting/closing-prompt
7
8
  * flattery, and the status header is detectable in the recent
8
9
  * session transcript (test-only fixture).
@@ -32,7 +33,18 @@ const CLOSING_PROMPTS = [
32
33
  /\b随时(欢迎)?(联系|提问)/i,
33
34
  /\b随时 (欢迎 )?(联系|提问)/i
34
35
  ];
35
- const STATUS_HEADER_PATTERN = /Peaks-Loop Skill:\s*peaks-[a-z0-9-]+\s*\|\s*Peaks-Loop Gate:\s*[A-Za-z0-9_.-]+\s*\|\s*Next:\s*\S/;
36
+ /**
37
+ * The status-header shape check. It answers ONE question — "does this
38
+ * response carry a Peaks-Loop status header at all?" — and not "is the
39
+ * header's shape right?".
40
+ *
41
+ * The header is published in several shapes: three segments, four with a
42
+ * Role cell, five with Role and Context. The Role and Context cells are
43
+ * therefore OPTIONAL here: a header that omits them is still a header, and a
44
+ * linter that reddened the three-segment examples still carried by the skill
45
+ * documentation would be measuring something other than its own duty.
46
+ */
47
+ const STATUS_HEADER_PATTERN = /Peaks-Loop Skill:\s*peaks-[a-z0-9-]+\s*\|\s*(?:Peaks-Loop Role:\s*[^|\n]*\s*\|\s*)?Peaks-Loop Gate:\s*[A-Za-z0-9_.-]+\s*(?:\|\s*Peaks-Loop Context:\s*[^|\n]*)?\|\s*Next:\s*\S/;
36
48
  export function lintNoFluff(skill) {
37
49
  const hits = [];
38
50
  for (const pattern of FLUFF_GREETINGS) {
@@ -0,0 +1,46 @@
1
+ import type { EnforcerFinding, RedLineAudit } from '../types.js';
2
+ /** The suffix a stderr capture carries: the `2> name.err` redirect. */
3
+ export declare const ROOT_SCRATCH_CAPTURE_SUFFIX = ".err";
4
+ /** Which shape a root file matched. */
5
+ export type RootScratchShape = 'stderr-capture' | 'zero-byte';
6
+ /** One scratch artifact found at the project root. */
7
+ export interface RootScratchArtifact {
8
+ /** The file name, as it sits at the root. */
9
+ readonly name: string;
10
+ /** The shape it matched. */
11
+ readonly shape: RootScratchShape;
12
+ /** The size in bytes; `0` for the zero-byte shape, `-1` when it could not be read. */
13
+ readonly size: number;
14
+ }
15
+ /**
16
+ * Every scratch artifact at the project root.
17
+ *
18
+ * A root that cannot be read THROWS: a sweep that cannot look must not report
19
+ * "clean", which is the one answer it is not entitled to give.
20
+ */
21
+ export declare function findRootScratchArtifacts(input: {
22
+ readonly projectRoot: string;
23
+ }): readonly RootScratchArtifact[];
24
+ /** The catalog id the audit reports a root capture under. */
25
+ export declare const ROOT_SCRATCH_FINDING_ID = "rl-root-scratch-artifacts-001";
26
+ /** The rule text the audit reports a root capture under. */
27
+ export declare const ROOT_SCRATCH_RULE = "Root Scratch Artifacts: No Capture At The Project Root";
28
+ /**
29
+ * The audit findings for the root sweep.
30
+ *
31
+ * One `fail` finding per artifact. A root that cannot be swept THROWS: the
32
+ * audit reports a scanner failure rather than a clean sweep, because "clean"
33
+ * is the one answer a sweep that could not look is not entitled to give.
34
+ */
35
+ export declare function rootScratchFindings(input: {
36
+ readonly projectRoot: string;
37
+ }): readonly EnforcerFinding[];
38
+ /**
39
+ * The audit envelope with the root sweep folded in.
40
+ *
41
+ * The sweep is merged where a command assembles its envelope, not inside
42
+ * `runRedLinesAudit`: that module is at the repository's file-size ceiling, and
43
+ * a line added there moves a ratcheted total UP. Both audit commands call this
44
+ * one helper, so the two surfaces cannot drift apart.
45
+ */
46
+ export declare function withRootScratchFindings(audit: RedLineAudit, projectRoot: string): RedLineAudit;
@@ -0,0 +1,97 @@
1
+ /**
2
+ * The root scratch sweep: a scratch capture must not sit at the project root.
3
+ *
4
+ * WHAT IT CHECKS. Two shapes, both at the TOP level of the project root:
5
+ *
6
+ * - `stderr-capture` — a file whose name ends in `.err`. That is the shape a
7
+ * `2> name.err` redirect of a per-file test run produces, and it is the
8
+ * shape of the five captures that reached a repository root and were
9
+ * committed. A tracked file leaves `git status` clean, the file-size census
10
+ * does not read `.err`, and eslint does not lint it.
11
+ * - `zero-byte` — a file of zero bytes: a redirect that produced no output at
12
+ * all. `.gitkeep` is exempt, because an empty placeholder is what it is
13
+ * for.
14
+ *
15
+ * WHY IT READS THE DISK. A capture that is not tracked yet is still a capture
16
+ * at the root, and it is exactly the one a `git status` sweep cannot see.
17
+ *
18
+ * WHAT IT DOES NOT SEE. A capture inside a subdirectory, and a symlink at the
19
+ * root. The shape this sweep exists for is a regular file next to the
20
+ * manifest.
21
+ */
22
+ import { readdirSync, statSync } from 'node:fs';
23
+ import { join } from 'node:path';
24
+ /** The suffix a stderr capture carries: the `2> name.err` redirect. */
25
+ export const ROOT_SCRATCH_CAPTURE_SUFFIX = '.err';
26
+ /** Root files that are empty on purpose. */
27
+ const LEGITIMATELY_EMPTY_ROOT_FILES = new Set(['.gitkeep']);
28
+ /** The size of a file, or `-1` when it cannot be read. */
29
+ function fileSize(path) {
30
+ try {
31
+ return statSync(path).size;
32
+ }
33
+ catch {
34
+ return -1;
35
+ }
36
+ }
37
+ /**
38
+ * Every scratch artifact at the project root.
39
+ *
40
+ * A root that cannot be read THROWS: a sweep that cannot look must not report
41
+ * "clean", which is the one answer it is not entitled to give.
42
+ */
43
+ export function findRootScratchArtifacts(input) {
44
+ const artifacts = [];
45
+ const entries = readdirSync(input.projectRoot, { withFileTypes: true });
46
+ for (const entry of entries) {
47
+ if (!entry.isFile())
48
+ continue;
49
+ const name = entry.name;
50
+ const size = fileSize(join(input.projectRoot, name));
51
+ if (name.endsWith(ROOT_SCRATCH_CAPTURE_SUFFIX)) {
52
+ artifacts.push({ name, shape: 'stderr-capture', size });
53
+ continue;
54
+ }
55
+ if (LEGITIMATELY_EMPTY_ROOT_FILES.has(name))
56
+ continue;
57
+ if (size === 0)
58
+ artifacts.push({ name, shape: 'zero-byte', size });
59
+ }
60
+ return artifacts;
61
+ }
62
+ /** The catalog id the audit reports a root capture under. */
63
+ export const ROOT_SCRATCH_FINDING_ID = 'rl-root-scratch-artifacts-001';
64
+ /** The rule text the audit reports a root capture under. */
65
+ export const ROOT_SCRATCH_RULE = 'Root Scratch Artifacts: No Capture At The Project Root';
66
+ /**
67
+ * The audit findings for the root sweep.
68
+ *
69
+ * One `fail` finding per artifact. A root that cannot be swept THROWS: the
70
+ * audit reports a scanner failure rather than a clean sweep, because "clean"
71
+ * is the one answer a sweep that could not look is not entitled to give.
72
+ */
73
+ export function rootScratchFindings(input) {
74
+ return findRootScratchArtifacts({ projectRoot: input.projectRoot }).map((artifact) => ({
75
+ enforcerId: ROOT_SCRATCH_FINDING_ID,
76
+ rule: ROOT_SCRATCH_RULE,
77
+ severity: 'fail',
78
+ file: artifact.name,
79
+ detail: artifact.shape === 'stderr-capture'
80
+ ? `stderr capture at the project root (${artifact.size} bytes); write scratch under the session runtime dir`
81
+ : 'zero-byte file at the project root; write scratch under the session runtime dir'
82
+ }));
83
+ }
84
+ /**
85
+ * The audit envelope with the root sweep folded in.
86
+ *
87
+ * The sweep is merged where a command assembles its envelope, not inside
88
+ * `runRedLinesAudit`: that module is at the repository's file-size ceiling, and
89
+ * a line added there moves a ratcheted total UP. Both audit commands call this
90
+ * one helper, so the two surfaces cannot drift apart.
91
+ */
92
+ export function withRootScratchFindings(audit, projectRoot) {
93
+ return {
94
+ ...audit,
95
+ enforcerFindings: [...audit.enforcerFindings, ...rootScratchFindings({ projectRoot })]
96
+ };
97
+ }
@@ -21,6 +21,7 @@
21
21
  * mock it; the runner itself is never invoked from production code.
22
22
  */
23
23
  import { runRedLinesAudit } from './red-lines-service.js';
24
+ import { withRootScratchFindings } from './enforcers/root-scratch-artifacts.js';
24
25
  import { loadPreferences } from '../preferences/preferences-service.js';
25
26
  import { computeProseRatio } from './prose-ratio-calculator.js';
26
27
  export function runStaticAudit(input) {
@@ -31,10 +32,9 @@ export function runStaticAudit(input) {
31
32
  loadPreferences(input.projectRoot);
32
33
  // Always run the peaks-loop lint layer; no ECC findings merged.
33
34
  const peaksResult = runRedLinesAudit({ projectRoot: input.projectRoot });
34
- const mergedAudit = {
35
- ...peaksResult.audit,
36
- enforcerFindings: [...peaksResult.audit.enforcerFindings]
37
- };
35
+ // The root scratch sweep rides in this envelope too, so the two audit
36
+ // surfaces report the same findings.
37
+ const mergedAudit = withRootScratchFindings(peaksResult.audit, input.projectRoot);
38
38
  const state = {
39
39
  spawned: false,
40
40
  installed: false,
@@ -8,7 +8,12 @@ export interface CompactHistoryEvent {
8
8
  readonly schemaVersion: 1;
9
9
  readonly ts: string;
10
10
  readonly target: 'main' | 'sub-agent' | 'worker';
11
- readonly mode: 'standard' | 'partial' | 'aggressive';
11
+ /**
12
+ * The profile the run used. `eager` is the canonical name of the
13
+ * earlier-firing profile; `partial` is its legacy alias and is still
14
+ * accepted so an old row can be read; `aggressive` predates both.
15
+ */
16
+ readonly mode: 'standard' | 'partial' | 'aggressive' | 'eager';
12
17
  readonly ide: string;
13
18
  readonly pathway: string;
14
19
  readonly beforeRatio: number;
@@ -8,10 +8,15 @@
8
8
  import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
9
9
  import { join } from 'node:path';
10
10
  import { getSessionDir } from '../session/getSessionDir.js';
11
+ import { normalizeAutoCompactMode } from './auto-compact-modes.js';
11
12
  export function appendCompactHistoryEvent(input) {
12
13
  const dir = getSessionDir(input.projectRoot, input.sessionId);
13
14
  if (!existsSync(dir))
14
15
  mkdirSync(dir, { recursive: true });
15
16
  const path = join(dir, 'compact-history.jsonl');
16
- appendFileSync(path, JSON.stringify(input.event) + '\n', 'utf8');
17
+ // The row carries the CANONICAL profile name. The legacy alias is
18
+ // normalized at the one storage choke point, so an old row and a new row
19
+ // can be compared — and the alias never reaches the runtime state.
20
+ const mode = normalizeAutoCompactMode(input.event.mode) ?? input.event.mode;
21
+ appendFileSync(path, JSON.stringify({ ...input.event, mode }) + '\n', 'utf8');
17
22
  }
@@ -1,31 +1,71 @@
1
1
  /**
2
+ * The PUBLIC auto-compact profiles.
2
3
  *
3
- * The default `'standard'` mode preserves the v2.13.0 zero-pause contract
4
- * thresholds (autoFire=0.80, preCompact=0.85, redLine=0.95). The `'partial'`
5
- * mode fires earlier for 24h long-run scenarios where the user has explicitly
6
- * opted into higher compaction cadence via `peaks session 24h-mode`.
4
+ * Two profiles, and BOTH are public: any project, in any mode, can pick
5
+ * either one. Nothing here belongs to the 24h long-run mode any more — a
6
+ * profile is a THRESHOLD choice, not a mode.
7
+ *
8
+ * `'standard'` keeps the v2.13.0 zero-pause contract thresholds
9
+ * (autoFire=0.80, preCompact=0.85, redLine=0.95).
10
+ *
11
+ * `'eager'` fires EARLIER (autoFire=0.65, preCompact=0.70, redLine=0.85).
12
+ *
13
+ * WHY THE NAME CHANGED. The profile used to be called `'partial'`, and that
14
+ * name promised a behaviour this product does not have: there is NO
15
+ * partial-compaction pathway — the profile only moves the THRESHOLDS at
16
+ * which the orchestrator fires. A public name that promises behaviour the
17
+ * product does not implement is a lie in the CLI surface, so the profile is
18
+ * named after what it actually does: it fires earlier. `'partial'` stays
19
+ * ACCEPTED as a compatibility alias — `--mode partial` is a published CLI
20
+ * surface, and dropping it would break existing callers harder than a
21
+ * no-op — and `normalizeAutoCompactMode` is the ONE place that maps it onto
22
+ * `'eager'`.
7
23
  *
8
24
  * `autoFire` tier is added between soft-warn and preCompact. peaks-loop
9
25
  * preempts and runs `peaks code auto-compact` itself when
10
26
  * context crosses `autoFire`; the LLM is NOT asked to "decide"
11
27
  * (the LLM-judged 0.85–0.95 zone was the source of false-positive
12
28
  * "context too low" reports at 60%+ free — the LLM was guessing).
29
+ */
30
+ /** The canonical profile names. */
31
+ export type AutoCompactProfile = 'standard' | 'eager';
32
+ /**
33
+ * Every mode name this build ACCEPTS.
13
34
  *
14
- * The mode only changes the THRESHOLDS at which the orchestrator fires.
15
- * The actual partial-compaction behaviour (dropping low-priority context
16
- * layers) is a follow-up slice; for now `partial` mode is logged +
17
- * decision-emitted, no separate compaction pathway.
35
+ * `'partial'` is the legacy alias of `'eager'`. It stays in the type so a
36
+ * caller that still passes it keeps compiling, and it is collapsed to
37
+ * `'eager'` by `normalizeAutoCompactMode` before anything is stored or
38
+ * reported — the alias is a spelling, never a second profile.
18
39
  */
19
- export type AutoCompactMode = 'standard' | 'partial';
20
- export declare const AUTO_COMPACT_THRESHOLDS: Readonly<Record<AutoCompactMode, {
40
+ export type AutoCompactMode = AutoCompactProfile | 'partial';
41
+ /** The canonical profile names, in the order the CLI lists them. */
42
+ export declare const AUTO_COMPACT_PROFILES: readonly AutoCompactProfile[];
43
+ export interface AutoCompactThresholds {
21
44
  readonly autoFire: number;
22
45
  readonly preCompact: number;
23
46
  readonly redLine: number;
24
- }>>;
25
- export declare function thresholdFor(mode: AutoCompactMode, kind: 'autoFire' | 'preCompact' | 'redLine'): number;
47
+ }
48
+ /**
49
+ * The threshold table. `partial` is the legacy alias and points at the SAME
50
+ * row as `eager` — the numbers are written once, so the alias cannot drift
51
+ * away from the profile it names.
52
+ */
53
+ export declare const AUTO_COMPACT_THRESHOLDS: Readonly<Record<AutoCompactMode, AutoCompactThresholds>>;
54
+ /**
55
+ * Normalize a mode name to its canonical profile, or `null` when the name is
56
+ * not a mode this build knows.
57
+ *
58
+ * This is the single entry point for the alias mapping: `'partial'` in,
59
+ * `'eager'` out, and every caller that needs the canonical name goes
60
+ * through here.
61
+ */
62
+ export declare function normalizeAutoCompactMode(value: string): AutoCompactProfile | null;
63
+ /** True when `value` names a mode this build accepts (a canonical name or the legacy alias). */
26
64
  export declare function isValidMode(value: string): value is AutoCompactMode;
65
+ /** The threshold a mode fires at. */
66
+ export declare function thresholdFor(mode: AutoCompactMode, kind: 'autoFire' | 'preCompact' | 'redLine'): number;
27
67
  /**
28
- * Human-readable form of a mode's threshold row.
68
+ * Human-readable form of a profile's threshold row.
29
69
  *
30
70
  * Derived from `AUTO_COMPACT_THRESHOLDS` rather than hand-written. Diagnosis
31
71
  * 2026-09-15 (C1) found this string advertising `0.85/0.95` for `standard`
@@ -35,4 +75,10 @@ export declare function isValidMode(value: string): value is AutoCompactMode;
35
75
  * numbers out of the table makes that drift unrepresentable.
36
76
  */
37
77
  export declare function describeMode(mode: AutoCompactMode): string;
38
- export declare function isPartialModeEligible(contextPercent: number): boolean;
78
+ /** True when the context percentage has reached the `eager` profile's pre-compact line. */
79
+ export declare function isEagerModeEligible(contextPercent: number): boolean;
80
+ /**
81
+ * @deprecated The profile was renamed; `eager` is the canonical name. Kept
82
+ * so an existing caller keeps working — it now means the same thing.
83
+ */
84
+ export declare const isPartialModeEligible: typeof isEagerModeEligible;
@@ -1,36 +1,84 @@
1
1
  /**
2
+ * The PUBLIC auto-compact profiles.
2
3
  *
3
- * The default `'standard'` mode preserves the v2.13.0 zero-pause contract
4
- * thresholds (autoFire=0.80, preCompact=0.85, redLine=0.95). The `'partial'`
5
- * mode fires earlier for 24h long-run scenarios where the user has explicitly
6
- * opted into higher compaction cadence via `peaks session 24h-mode`.
4
+ * Two profiles, and BOTH are public: any project, in any mode, can pick
5
+ * either one. Nothing here belongs to the 24h long-run mode any more — a
6
+ * profile is a THRESHOLD choice, not a mode.
7
+ *
8
+ * `'standard'` keeps the v2.13.0 zero-pause contract thresholds
9
+ * (autoFire=0.80, preCompact=0.85, redLine=0.95).
10
+ *
11
+ * `'eager'` fires EARLIER (autoFire=0.65, preCompact=0.70, redLine=0.85).
12
+ *
13
+ * WHY THE NAME CHANGED. The profile used to be called `'partial'`, and that
14
+ * name promised a behaviour this product does not have: there is NO
15
+ * partial-compaction pathway — the profile only moves the THRESHOLDS at
16
+ * which the orchestrator fires. A public name that promises behaviour the
17
+ * product does not implement is a lie in the CLI surface, so the profile is
18
+ * named after what it actually does: it fires earlier. `'partial'` stays
19
+ * ACCEPTED as a compatibility alias — `--mode partial` is a published CLI
20
+ * surface, and dropping it would break existing callers harder than a
21
+ * no-op — and `normalizeAutoCompactMode` is the ONE place that maps it onto
22
+ * `'eager'`.
7
23
  *
8
24
  * `autoFire` tier is added between soft-warn and preCompact. peaks-loop
9
25
  * preempts and runs `peaks code auto-compact` itself when
10
26
  * context crosses `autoFire`; the LLM is NOT asked to "decide"
11
27
  * (the LLM-judged 0.85–0.95 zone was the source of false-positive
12
28
  * "context too low" reports at 60%+ free — the LLM was guessing).
13
- *
14
- * The mode only changes the THRESHOLDS at which the orchestrator fires.
15
- * The actual partial-compaction behaviour (dropping low-priority context
16
- * layers) is a follow-up slice; for now `partial` mode is logged +
17
- * decision-emitted, no separate compaction pathway.
18
29
  */
19
- export const AUTO_COMPACT_THRESHOLDS = {
30
+ /** The canonical profile names, in the order the CLI lists them. */
31
+ export const AUTO_COMPACT_PROFILES = ['standard', 'eager'];
32
+ /**
33
+ * The ONE alias table: a legacy mode name → the canonical profile it means.
34
+ * `normalizeAutoCompactMode` is its only reader, so the mapping cannot be
35
+ * restated — and therefore cannot drift — anywhere else.
36
+ */
37
+ const LEGACY_MODE_ALIASES = { partial: 'eager' };
38
+ const EAGER_THRESHOLDS = { autoFire: 0.65, preCompact: 0.7, redLine: 0.85 };
39
+ const PROFILE_THRESHOLDS = {
20
40
  standard: { autoFire: 0.8, preCompact: 0.85, redLine: 0.95 },
21
- partial: { autoFire: 0.65, preCompact: 0.7, redLine: 0.85 }
41
+ eager: EAGER_THRESHOLDS
22
42
  };
23
- export function thresholdFor(mode, kind) {
24
- return AUTO_COMPACT_THRESHOLDS[mode][kind];
43
+ /**
44
+ * The threshold table. `partial` is the legacy alias and points at the SAME
45
+ * row as `eager` — the numbers are written once, so the alias cannot drift
46
+ * away from the profile it names.
47
+ */
48
+ export const AUTO_COMPACT_THRESHOLDS = {
49
+ ...PROFILE_THRESHOLDS,
50
+ partial: EAGER_THRESHOLDS
51
+ };
52
+ /**
53
+ * Normalize a mode name to its canonical profile, or `null` when the name is
54
+ * not a mode this build knows.
55
+ *
56
+ * This is the single entry point for the alias mapping: `'partial'` in,
57
+ * `'eager'` out, and every caller that needs the canonical name goes
58
+ * through here.
59
+ */
60
+ export function normalizeAutoCompactMode(value) {
61
+ if (value === 'standard' || value === 'eager')
62
+ return value;
63
+ const alias = LEGACY_MODE_ALIASES[value];
64
+ return alias ?? null;
25
65
  }
66
+ /** True when `value` names a mode this build accepts (a canonical name or the legacy alias). */
26
67
  export function isValidMode(value) {
27
- return value === 'standard' || value === 'partial';
68
+ return normalizeAutoCompactMode(value) !== null;
69
+ }
70
+ /** The threshold a mode fires at. */
71
+ export function thresholdFor(mode, kind) {
72
+ // `mode` is typed, so the canonical name is always resolvable; the
73
+ // fallback keeps the function total for an untyped caller.
74
+ const canonical = normalizeAutoCompactMode(mode) ?? 'standard';
75
+ return AUTO_COMPACT_THRESHOLDS[canonical][kind];
28
76
  }
29
77
  function pct(ratio) {
30
78
  return `${(ratio * 100).toFixed(0)}%`;
31
79
  }
32
80
  /**
33
- * Human-readable form of a mode's threshold row.
81
+ * Human-readable form of a profile's threshold row.
34
82
  *
35
83
  * Derived from `AUTO_COMPACT_THRESHOLDS` rather than hand-written. Diagnosis
36
84
  * 2026-09-15 (C1) found this string advertising `0.85/0.95` for `standard`
@@ -40,12 +88,19 @@ function pct(ratio) {
40
88
  * numbers out of the table makes that drift unrepresentable.
41
89
  */
42
90
  export function describeMode(mode) {
43
- const { autoFire, preCompact, redLine } = AUTO_COMPACT_THRESHOLDS[mode];
91
+ const canonical = normalizeAutoCompactMode(mode) ?? 'standard';
92
+ const { autoFire, preCompact, redLine } = AUTO_COMPACT_THRESHOLDS[canonical];
44
93
  const bands = `auto-fire ${pct(autoFire)} / pre-compact ${pct(preCompact)} / red-line ${pct(redLine)}`;
45
- return mode === 'standard'
94
+ return canonical === 'standard'
46
95
  ? `standard (${bands} — v2.13.0 zero-pause contract)`
47
- : `partial (${bands} — 24h long-run mode)`;
96
+ : `eager (${bands} — fires earlier than standard)`;
48
97
  }
49
- export function isPartialModeEligible(contextPercent) {
50
- return contextPercent >= AUTO_COMPACT_THRESHOLDS.partial.preCompact;
98
+ /** True when the context percentage has reached the `eager` profile's pre-compact line. */
99
+ export function isEagerModeEligible(contextPercent) {
100
+ return contextPercent >= EAGER_THRESHOLDS.preCompact;
51
101
  }
102
+ /**
103
+ * @deprecated The profile was renamed; `eager` is the canonical name. Kept
104
+ * so an existing caller keeps working — it now means the same thing.
105
+ */
106
+ export const isPartialModeEligible = isEagerModeEligible;
@@ -0,0 +1,23 @@
1
+ import { type AutoCompactProfile } from './auto-compact-modes.js';
2
+ /** Which of the three sources answered the profile question. */
3
+ export type AutoCompactProfileSource = 'cli' | 'preference' | 'default';
4
+ export interface ResolvedAutoCompactProfile {
5
+ readonly profile: AutoCompactProfile;
6
+ /** Where it came from: `'cli'`, `'preference'` or `'default'`. */
7
+ readonly source: AutoCompactProfileSource;
8
+ }
9
+ /**
10
+ * The profile the project pinned, or `null` when it pinned nothing: no key in
11
+ * the file, an unknown value, or the default `'standard'`. A file this build
12
+ * CANNOT READ answers `null` too, leaving the compaction path unbroken.
13
+ */
14
+ export declare function readAutoCompactProfilePreference(projectRoot: string): AutoCompactProfile | null;
15
+ /**
16
+ * Resolve the profile in force for one invocation — THE resolution order lives
17
+ * here, in one place, so it cannot drift between the CLI and the services.
18
+ */
19
+ export declare function resolveAutoCompactProfile(input: {
20
+ readonly projectRoot: string;
21
+ /** The normalized `--mode` value, when the caller named one. */
22
+ readonly cliMode?: AutoCompactProfile | null | undefined;
23
+ }): ResolvedAutoCompactProfile;