peaks-loop 4.1.22 → 4.1.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/.claude-plugin/marketplace.json +12 -2
  2. package/CHANGELOG.md +184 -0
  3. package/dist/cli/commands/code-auto-compact-command.js +19 -1
  4. package/dist/cli/commands/code-gate-step-08-command.js +103 -105
  5. package/dist/cli/commands/code-gate-step-08-remedy.d.ts +10 -2
  6. package/dist/cli/commands/code-gate-step-08-remedy.js +11 -3
  7. package/dist/cli/commands/gate-commands-enforce.d.ts +23 -8
  8. package/dist/cli/commands/gate-commands-enforce.js +27 -12
  9. package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
  10. package/dist/cli/commands/observability-commands-hotspots.js +222 -0
  11. package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
  12. package/dist/cli/commands/observability-commands-near-miss.js +105 -0
  13. package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
  14. package/dist/cli/commands/observability-commands-queries.js +88 -47
  15. package/dist/cli/commands/observability-commands-session-row.d.ts +48 -0
  16. package/dist/cli/commands/observability-commands-session-row.js +201 -0
  17. package/dist/cli/commands/observability-commands.js +81 -20
  18. package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
  19. package/dist/services/artifacts/artifact-prerequisites.js +1 -1
  20. package/dist/services/artifacts/prerequisite-path-census.d.ts +47 -0
  21. package/dist/services/artifacts/prerequisite-path-census.js +100 -0
  22. package/dist/services/artifacts/prerequisite-path-resolver.js +32 -2
  23. package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
  24. package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
  25. package/dist/services/artifacts/rd-gate-event.js +211 -0
  26. package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
  27. package/dist/services/artifacts/rd-transition-gates.js +65 -24
  28. package/dist/services/hooks/output.d.ts +67 -1
  29. package/dist/services/hooks/output.js +74 -1
  30. package/dist/services/observability/aggregation-types.d.ts +21 -0
  31. package/dist/services/observability/aggregation.d.ts +12 -2
  32. package/dist/services/observability/aggregation.js +28 -3
  33. package/dist/services/observability/compliance-judge.d.ts +77 -0
  34. package/dist/services/observability/compliance-judge.js +143 -0
  35. package/dist/services/observability/compliance-spec.d.ts +96 -0
  36. package/dist/services/observability/compliance-spec.js +29 -0
  37. package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
  38. package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
  39. package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
  40. package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
  41. package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
  42. package/dist/services/observability/hotspot-attribution-summary.js +74 -0
  43. package/dist/services/observability/hotspot-rows.d.ts +47 -0
  44. package/dist/services/observability/hotspot-rows.js +89 -0
  45. package/dist/services/observability/hotspot-shared.d.ts +207 -0
  46. package/dist/services/observability/hotspot-shared.js +127 -0
  47. package/dist/services/observability/hotspot-sources.d.ts +55 -0
  48. package/dist/services/observability/hotspot-sources.js +142 -0
  49. package/dist/services/observability/hotspots.d.ts +47 -0
  50. package/dist/services/observability/hotspots.js +47 -0
  51. package/dist/services/observability/near-miss-attempts.d.ts +175 -0
  52. package/dist/services/observability/near-miss-attempts.js +223 -0
  53. package/dist/services/observability/near-miss-coverage.d.ts +109 -0
  54. package/dist/services/observability/near-miss-coverage.js +108 -0
  55. package/dist/services/observability/near-miss-denominator.d.ts +81 -0
  56. package/dist/services/observability/near-miss-denominator.js +75 -0
  57. package/dist/services/observability/near-miss-difference.d.ts +98 -0
  58. package/dist/services/observability/near-miss-difference.js +135 -0
  59. package/dist/services/observability/near-miss-facts.d.ts +165 -0
  60. package/dist/services/observability/near-miss-facts.js +101 -0
  61. package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
  62. package/dist/services/observability/near-miss-gate-events.js +106 -0
  63. package/dist/services/observability/near-miss-gates.d.ts +108 -0
  64. package/dist/services/observability/near-miss-gates.js +135 -0
  65. package/dist/services/observability/near-miss-records.d.ts +93 -0
  66. package/dist/services/observability/near-miss-records.js +87 -0
  67. package/dist/services/observability/near-miss.d.ts +148 -0
  68. package/dist/services/observability/near-miss.js +203 -0
  69. package/dist/services/observability/observability-schema.d.ts +17 -2
  70. package/dist/services/observability/observability-schema.js +21 -1
  71. package/dist/services/observability/owner-skill-map.d.ts +92 -0
  72. package/dist/services/observability/owner-skill-map.js +164 -0
  73. package/dist/services/observability/repair-cycle-metric.js +6 -3
  74. package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
  75. package/dist/services/observability/report-formatter-hotspots.js +76 -0
  76. package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
  77. package/dist/services/observability/report-formatter-near-miss.js +234 -0
  78. package/dist/services/observability/report-formatter.d.ts +49 -3
  79. package/dist/services/observability/report-formatter.js +55 -14
  80. package/dist/services/observability/retro-attribution.d.ts +129 -0
  81. package/dist/services/observability/retro-attribution.js +134 -0
  82. package/dist/services/observability/session-metric-rows.d.ts +153 -0
  83. package/dist/services/observability/session-metric-rows.js +184 -0
  84. package/dist/services/skills/presence-role.js +9 -2
  85. package/dist/services/standards/loop-engineering-readiness-lint.d.ts +15 -1
  86. package/dist/services/standards/loop-engineering-readiness-lint.js +27 -9
  87. package/dist/shared/incrementing-number.d.ts +57 -0
  88. package/dist/shared/incrementing-number.js +13 -0
  89. package/dist/skills/peaks-maker/index.js +43 -30
  90. package/output-styles/peaks-skill-swarm.md +2 -2
  91. package/package.json +5 -5
  92. package/scripts/install-skills-bundles.mjs +6 -1
  93. package/scripts/install-skills.mjs +10 -1
  94. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  95. package/skills/bee/peaks-prd/SKILL.md +1 -1
  96. package/skills/bee/peaks-qa/SKILL.md +1 -1
  97. package/skills/bee/peaks-rd/SKILL.md +1 -1
  98. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  99. package/skills/bee/peaks-sc/SKILL.md +1 -1
  100. package/skills/bee/peaks-security-audit/SKILL.md +1 -1
  101. package/skills/bee/peaks-txt/SKILL.md +1 -1
  102. package/skills/bee/peaks-ui/SKILL.md +1 -1
  103. package/skills/peaks-audit/SKILL.md +1 -1
  104. package/skills/peaks-code/SKILL.md +1 -1
  105. package/skills/peaks-content/SKILL.md +1 -1
  106. package/skills/peaks-doctor/SKILL.md +1 -1
  107. package/skills/peaks-final-review/SKILL.md +1 -1
  108. package/skills/peaks-ide/SKILL.md +1 -1
  109. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  110. package/skills/peaks-maker/SKILL.md +125 -0
  111. package/skills/peaks-mut/SKILL.md +297 -0
  112. package/skills/peaks-race-code/SKILL.md +1 -1
  113. package/skills/peaks-resume/SKILL.md +1 -1
  114. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  115. package/skills/peaks-solo/SKILL.md +1 -1
  116. package/skills/peaks-sop/SKILL.md +1 -1
  117. package/skills/peaks-status/SKILL.md +1 -1
  118. package/skills/peaks-test/SKILL.md +1 -1
@@ -6,6 +6,7 @@ import { isArtifactWorkspaceFile } from '../scan/type-sanity-service.js';
6
6
  import { listSessionRdArtifactIds, readRidChangeClaims } from '../scan/rid-change-claims.js';
7
7
  import { slugifyDescription } from '../../shared/incrementing-number.js';
8
8
  import { normalizePath } from '../../shared/path-utils.js';
9
+ import { bypassReason, claimTableReason, gateLabel, liveGateIds, notedGateIds, rdGateRecorder } from './rd-gate-event.js';
9
10
  /**
10
11
  * True for the three states the RD gates judge. A type PREDICATE, so a caller
11
12
  * that filters on it keeps the narrowed state — the old inline `||` chain did
@@ -28,19 +29,36 @@ export class TypeCorroborationViolationError extends Error {
28
29
  /** Written into the artifact when `--allow-incomplete` skips a gate that COULD
29
30
  * have judged this type: a silent bypass is indistinguishable from a pass. */
30
31
  export function rdGatesBypassNote(phase) {
31
- const gates = phase === 'implemented'
32
- ? 'file-size ratchet, declared-type corroboration'
33
- : 'declared-type corroboration';
32
+ const gates = notedGateIds(phase)
33
+ .map((gateId) => gateLabel(gateId))
34
+ .join(', ');
34
35
  return (`bypassed the rd ${phase} gates (${gates}) via --allow-incomplete; ` +
35
36
  'none of them was evaluated');
36
37
  }
38
+ /** The gates a bypassed transition skipped, each with its own event: every
39
+ * gate that was LIVE for the transition and did not run. The live set is not
40
+ * the note's list — see `liveGateIds`. */
41
+ function reportBypass(record, phase, judged) {
42
+ for (const gateId of liveGateIds(phase, judged)) {
43
+ record(gateId, 'bypass', { reason: bypassReason(gateId, phase) });
44
+ }
45
+ return judged ? rdGatesBypassNote(phase) : null;
46
+ }
37
47
  /** The shared read, or the fail-closed verdict built from the same message. */
38
- function readOrRefuse(projectRoot, declaredType) {
48
+ function readOrRefuse(record, projectRoot, declaredType) {
39
49
  try {
40
50
  return readGitChangeSet(projectRoot, 'HEAD');
41
51
  }
42
52
  catch {
43
- throw new TypeCorroborationViolationError(declaredType, diffUnavailableVerdict(declaredType));
53
+ const verdict = diffUnavailableVerdict(declaredType);
54
+ // BEFORE the throw: after it the event would never fire, and "the diff
55
+ // could not be read" is one of the facts this stream exists to keep. IT IS
56
+ // THE CLAIM TABLE'S BLOCK, because the criterion is which gate could not be
57
+ // EVALUATED: the working-tree diff is the precondition the claim table
58
+ // needs. The verdict function living in the type-corroboration module is
59
+ // incidental.
60
+ record('claim-table', 'block', { violationKind: 'diff-unavailable', reason: verdict.message });
61
+ throw new TypeCorroborationViolationError(declaredType, verdict);
44
62
  }
45
63
  }
46
64
  /** The note written when the anti-lie fallback could not run. */
@@ -85,15 +103,21 @@ function judgeDeclaredType(options) {
85
103
  if (tableComplete) {
86
104
  const unclaimed = unclaimedSourcePaths(options.worktreePaths, claims);
87
105
  if (unclaimed.length > 0) {
88
- return {
89
- ok: false,
90
- kind: 'source-unclaimed',
91
- message: unclaimedMessage(options.declaredType, unclaimed)
92
- };
106
+ const message = unclaimedMessage(options.declaredType, unclaimed);
107
+ options.record('claim-table', 'block', {
108
+ violationKind: 'source-unclaimed',
109
+ reason: message
110
+ });
111
+ return { ok: false, kind: 'source-unclaimed', message };
93
112
  }
113
+ options.record('claim-table', 'pass');
94
114
  }
95
115
  else {
96
116
  note = fallbackDisabledNote(options.sessionId, missing.length, artifactIds.length);
117
+ // The fallback STOOD DOWN — it did not pass. A bypass says so; a pass
118
+ // would claim a check that never ran, and the reason says WHICH stand-down.
119
+ const standDown = claimTableReason(artifactIds.length, missing.length);
120
+ options.record('claim-table', 'bypass', { reason: standDown });
97
121
  }
98
122
  // (B) The rid's own declaration; the whole working tree when it declared none.
99
123
  const scope = own ?? options.worktreePaths;
@@ -107,27 +131,49 @@ function judgeDeclaredType(options) {
107
131
  // anti-lie fallback stood down, a reader of the refusal alone must not be
108
132
  // left thinking it was in force.
109
133
  const message = note === null ? verdict.message : `${verdict.message} ${note}`;
134
+ const refusal = { violationKind: verdict.kind, reason: message };
135
+ options.record('declared-type-corroboration', 'block', refusal);
110
136
  return { ok: false, kind: verdict.kind, message };
111
137
  }
138
+ options.record('declared-type-corroboration', 'pass');
112
139
  return { ok: true, note };
113
140
  }
141
+ /** The size ratchet, and the event that records what it decided. The refusal
142
+ * is recorded BEFORE the throw — after it the event would never fire. */
143
+ function runSizeRatchet(record, projectRoot, changedFiles) {
144
+ const size = changedFiles === undefined
145
+ ? scanFileSize({ projectRoot })
146
+ : scanFileSize({ projectRoot, changedFiles });
147
+ if (!size.ok) {
148
+ const error = new FileSizeViolationError(size.violations);
149
+ record('file-size-ratchet', 'block', { reason: error.message });
150
+ throw error;
151
+ }
152
+ record('file-size-ratchet', 'pass');
153
+ }
114
154
  export function runRdTransitionGates(options) {
155
+ const record = rdGateRecorder({
156
+ projectRoot: options.projectRoot,
157
+ sessionId: options.sessionId,
158
+ sliceRid: options.requestId,
159
+ phase: options.phase,
160
+ declaredType: options.declaredType
161
+ });
115
162
  const judged = isToolingOnlyDeclaredType(options.declaredType);
116
- if (options.allowIncomplete)
117
- return judged ? rdGatesBypassNote(options.phase) : null;
163
+ if (options.allowIncomplete) {
164
+ return reportBypass(record, options.phase, judged);
165
+ }
118
166
  if (!judged) {
119
167
  // The size ratchet still runs at implemented; the type rule is a no-op here.
120
- if (options.phase === 'implemented') {
121
- const size = scanFileSize({ projectRoot: options.projectRoot });
122
- if (!size.ok)
123
- throw new FileSizeViolationError(size.violations);
124
- }
168
+ if (options.phase === 'implemented')
169
+ runSizeRatchet(record, options.projectRoot);
125
170
  return null;
126
171
  }
127
172
  // ONE enumeration for the whole transition: the type rule judges the rid's own
128
173
  // paths against the same working-tree read the size ratchet measures.
129
- const changeSet = readOrRefuse(options.projectRoot, options.declaredType);
174
+ const changeSet = readOrRefuse(record, options.projectRoot, options.declaredType);
130
175
  const verdict = judgeDeclaredType({
176
+ record,
131
177
  projectRoot: options.projectRoot,
132
178
  declaredType: options.declaredType,
133
179
  requestId: options.requestId,
@@ -137,12 +183,7 @@ export function runRdTransitionGates(options) {
137
183
  if (!verdict.ok)
138
184
  throw new TypeCorroborationViolationError(options.declaredType, verdict);
139
185
  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);
186
+ runSizeRatchet(record, options.projectRoot, changeSet.changedFiles);
146
187
  }
147
188
  return verdict.note;
148
189
  }
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * peaks hook output contract. See `.claude/HOOKS.md` for the canonical doc.
3
3
  *
4
- * Three helpers, one job: enforce the stdout/stderr/exit-code discipline
4
+ * Four helpers, one job: enforce the stdout/stderr/exit-code discipline
5
5
  * that every peaks-managed hook command MUST follow. Centralising the
6
6
  * contract here lets us:
7
7
  * 1. Pin the contract in cross-platform tests (tests/unit/hooks/contract.test.ts).
@@ -49,6 +49,15 @@
49
49
  * permissionDecision='deny' to block. Setting exit=2 on top
50
50
  * of the JSON would be double-signaling.
51
51
  *
52
+ * emitResultDocument(io, envelope)
53
+ * - Writes the command's result envelope to io.stdout as ONE JSON
54
+ * document and its action lines to io.stderr as `next: ...`.
55
+ * - Carries NO root `decision` and NO hookSpecificOutput: the host
56
+ * OWNS the root `decision` key and accepts only {approve, block},
57
+ * and a pass-through grant would bypass the user's own permission
58
+ * prompt. Exit 0 is the pass-through signal.
59
+ * - Does NOT set process.exitCode.
60
+ *
52
61
  * Platform notes:
53
62
  * - The contract is platform-independent. The helpers write to ProgramIO
54
63
  * (stdout / stderr) only; no path separators, no shell escaping, no
@@ -56,6 +65,7 @@
56
65
  * - On win32, Node's process.stdout and process.stderr are binary-safe
57
66
  * and UTF-8; do not introduce \r\n anywhere. The contract is LF.
58
67
  */
68
+ import type { ResultEnvelope } from 'peaks-loop-shared/result';
59
69
  import type { ProgramIO } from '../../cli/cli-helpers.js';
60
70
  /** Exit code the host treats as a hard block (Claude Code convention). */
61
71
  export declare const HOOK_BLOCK_EXIT_CODE = 2;
@@ -89,3 +99,59 @@ export declare function emitBlock(io: ProgramIO, reason: string): EmitBlockResul
89
99
  * be used for new code.
90
100
  */
91
101
  export declare function emitDecision(io: ProgramIO, decision: DecisionShape | string): string;
102
+ /**
103
+ * The `hookSpecificOutput` block this repository ships on its allow paths.
104
+ *
105
+ * Why this shape: the Claude Code PreToolUse validator (measured against
106
+ * 2.1.312) accepts a stdout document whose root carries `hookSpecificOutput`
107
+ * with `permissionDecision` in {allow, deny, ask, defer}. It ALSO rejects a
108
+ * ROOT-level `decision` key whose value is outside {approve, block} — that is
109
+ * the exact error this slice fixes.
110
+ *
111
+ * `permissionDecision: "allow"` is the host's "this hook approves the call"
112
+ * signal. Measured: it makes the host approve the tool use, bypassing the
113
+ * user's own permission prompt, while an explicit user `deny` rule still
114
+ * overrides it. So this is a real permission grant, and the callers that use
115
+ * it must mean it.
116
+ */
117
+ export declare const HOOK_ALLOW_DECISION: DecisionShape;
118
+ /**
119
+ * Merge a payload with the allow decision into ONE JSON document.
120
+ *
121
+ * The host parses stdout as a SINGLE JSON document, so the decision and the
122
+ * payload must travel together — two documents on stdout means the second one
123
+ * is unparseable and the whole hook output degrades to plain text.
124
+ *
125
+ * The payload's own fields are preserved verbatim, so a downstream consumer
126
+ * that reads `JSON.parse(stdout).data.decision` keeps reading exactly that.
127
+ * The return type keeps the payload's own type, so a caller that passes a
128
+ * `ResultEnvelope` still gets a `ResultEnvelope` and can hand it to
129
+ * `printResult` — the merge only ADDS a key, it does not erase the shape.
130
+ */
131
+ export declare function buildAllowDocument<T extends object>(payload: T): T & {
132
+ hookSpecificOutput: DecisionShape;
133
+ };
134
+ /**
135
+ * Result document — a command's result envelope as ONE JSON document on
136
+ * stdout, with its action lines on stderr.
137
+ *
138
+ * This is the hook-mode replacement for `printResult(io, envelope, false)`.
139
+ * That printer is written for a human at a terminal: it flattens `data` to the
140
+ * ROOT of stdout, then appends `next: ...` prose to the same stream. For a
141
+ * command whose stdout IS the hook's decision channel, both halves are wrong.
142
+ * A payload's own `decision` becomes a ROOT `decision` — a key the host OWNS,
143
+ * with vocabulary {approve, block} — which is the "decision: Invalid option"
144
+ * error the user saw on every Bash call; and the trailing prose makes stdout
145
+ * unparseable as one document.
146
+ *
147
+ * The document emitted here is the SAME envelope `--json` already prints, so a
148
+ * command has ONE machine shape in both modes and the shape cannot drift
149
+ * between them. The prose moves to stderr, where a hint belongs and where the
150
+ * host never reads a decision from.
151
+ *
152
+ * It deliberately does NOT carry a `hookSpecificOutput` allow decision: an
153
+ * allow is a real permission GRANT that bypasses the user's own permission
154
+ * prompt (see HOOK_ALLOW_DECISION), and a gate that passes a call through has
155
+ * no opinion to give. Exit 0 is the pass-through signal.
156
+ */
157
+ export declare function emitResultDocument<T>(io: ProgramIO, envelope: ResultEnvelope<T>): void;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * peaks hook output contract. See `.claude/HOOKS.md` for the canonical doc.
3
3
  *
4
- * Three helpers, one job: enforce the stdout/stderr/exit-code discipline
4
+ * Four helpers, one job: enforce the stdout/stderr/exit-code discipline
5
5
  * that every peaks-managed hook command MUST follow. Centralising the
6
6
  * contract here lets us:
7
7
  * 1. Pin the contract in cross-platform tests (tests/unit/hooks/contract.test.ts).
@@ -49,6 +49,15 @@
49
49
  * permissionDecision='deny' to block. Setting exit=2 on top
50
50
  * of the JSON would be double-signaling.
51
51
  *
52
+ * emitResultDocument(io, envelope)
53
+ * - Writes the command's result envelope to io.stdout as ONE JSON
54
+ * document and its action lines to io.stderr as `next: ...`.
55
+ * - Carries NO root `decision` and NO hookSpecificOutput: the host
56
+ * OWNS the root `decision` key and accepts only {approve, block},
57
+ * and a pass-through grant would bypass the user's own permission
58
+ * prompt. Exit 0 is the pass-through signal.
59
+ * - Does NOT set process.exitCode.
60
+ *
52
61
  * Platform notes:
53
62
  * - The contract is platform-independent. The helpers write to ProgramIO
54
63
  * (stdout / stderr) only; no path separators, no shell escaping, no
@@ -108,3 +117,67 @@ export function emitDecision(io, decision) {
108
117
  io.stdout('\n');
109
118
  return serialized;
110
119
  }
120
+ /**
121
+ * The `hookSpecificOutput` block this repository ships on its allow paths.
122
+ *
123
+ * Why this shape: the Claude Code PreToolUse validator (measured against
124
+ * 2.1.312) accepts a stdout document whose root carries `hookSpecificOutput`
125
+ * with `permissionDecision` in {allow, deny, ask, defer}. It ALSO rejects a
126
+ * ROOT-level `decision` key whose value is outside {approve, block} — that is
127
+ * the exact error this slice fixes.
128
+ *
129
+ * `permissionDecision: "allow"` is the host's "this hook approves the call"
130
+ * signal. Measured: it makes the host approve the tool use, bypassing the
131
+ * user's own permission prompt, while an explicit user `deny` rule still
132
+ * overrides it. So this is a real permission grant, and the callers that use
133
+ * it must mean it.
134
+ */
135
+ export const HOOK_ALLOW_DECISION = {
136
+ hookEventName: CLAUDE_CODE_HOOK_EVENT,
137
+ permissionDecision: 'allow'
138
+ };
139
+ /**
140
+ * Merge a payload with the allow decision into ONE JSON document.
141
+ *
142
+ * The host parses stdout as a SINGLE JSON document, so the decision and the
143
+ * payload must travel together — two documents on stdout means the second one
144
+ * is unparseable and the whole hook output degrades to plain text.
145
+ *
146
+ * The payload's own fields are preserved verbatim, so a downstream consumer
147
+ * that reads `JSON.parse(stdout).data.decision` keeps reading exactly that.
148
+ * The return type keeps the payload's own type, so a caller that passes a
149
+ * `ResultEnvelope` still gets a `ResultEnvelope` and can hand it to
150
+ * `printResult` — the merge only ADDS a key, it does not erase the shape.
151
+ */
152
+ export function buildAllowDocument(payload) {
153
+ return { ...payload, hookSpecificOutput: HOOK_ALLOW_DECISION };
154
+ }
155
+ /**
156
+ * Result document — a command's result envelope as ONE JSON document on
157
+ * stdout, with its action lines on stderr.
158
+ *
159
+ * This is the hook-mode replacement for `printResult(io, envelope, false)`.
160
+ * That printer is written for a human at a terminal: it flattens `data` to the
161
+ * ROOT of stdout, then appends `next: ...` prose to the same stream. For a
162
+ * command whose stdout IS the hook's decision channel, both halves are wrong.
163
+ * A payload's own `decision` becomes a ROOT `decision` — a key the host OWNS,
164
+ * with vocabulary {approve, block} — which is the "decision: Invalid option"
165
+ * error the user saw on every Bash call; and the trailing prose makes stdout
166
+ * unparseable as one document.
167
+ *
168
+ * The document emitted here is the SAME envelope `--json` already prints, so a
169
+ * command has ONE machine shape in both modes and the shape cannot drift
170
+ * between them. The prose moves to stderr, where a hint belongs and where the
171
+ * host never reads a decision from.
172
+ *
173
+ * It deliberately does NOT carry a `hookSpecificOutput` allow decision: an
174
+ * allow is a real permission GRANT that bypasses the user's own permission
175
+ * prompt (see HOOK_ALLOW_DECISION), and a gate that passes a call through has
176
+ * no opinion to give. Exit 0 is the pass-through signal.
177
+ */
178
+ export function emitResultDocument(io, envelope) {
179
+ io.stdout(JSON.stringify(envelope, null, 2));
180
+ for (const action of envelope.nextActions) {
181
+ emitHint(io, `next: ${action}`);
182
+ }
183
+ }
@@ -16,6 +16,16 @@ export type StatusAggregate = {
16
16
  totalSlices: number;
17
17
  successCount: number;
18
18
  failCount: number;
19
+ /**
20
+ * Slices that reached a state which is neither a success terminal state nor
21
+ * a terminal failure — the ones stuck mid-flight, e.g. at `qa-handoff`.
22
+ *
23
+ * The three outcome counts partition the slice set, so
24
+ * `successCount + failCount + stalledCount === totalSlices` holds for every
25
+ * event set. A slice whose transitions recorded no final state at all also
26
+ * lands here: it reached no terminal outcome either.
27
+ */
28
+ readonly stalledCount: number;
19
29
  repairCyclePeak: number;
20
30
  fanoutCostTotal: number;
21
31
  };
@@ -30,6 +40,17 @@ export type SliceRollup = {
30
40
  repairCycleCount: number;
31
41
  success: boolean;
32
42
  };
43
+ /**
44
+ * How one slice ended.
45
+ *
46
+ * The three outcomes PARTITION the slice set: a slice that reached a
47
+ * terminal success state, a slice that reached a terminal failure state, and
48
+ * a slice that reached NEITHER — it advanced partway and stopped (at
49
+ * `qa-handoff`, typically). `stalled` is not a failure: the work was never
50
+ * concluded, and the counts must say so rather than drop the slice from the
51
+ * accounting.
52
+ */
53
+ export type SliceOutcome = 'success' | 'failed' | 'stalled';
33
54
  export type FanoutBreakdown = {
34
55
  total: number;
35
56
  perRole: Record<ObservabilitySubagentRole, number>;
@@ -14,11 +14,21 @@
14
14
  * builds the read-side surface so Slice C is purely additive.
15
15
  */
16
16
  import { type ObservabilityEvent } from './observability-service.js';
17
- import { type DashboardMetrics, type FanoutBreakdown, type Period, type RepairCycleReport, type SliceRollup, type StatusAggregate } from './aggregation-types.js';
17
+ import { type DashboardMetrics, type FanoutBreakdown, type Period, type RepairCycleReport, type SliceOutcome, type SliceRollup, type StatusAggregate } from './aggregation-types.js';
18
18
  export { REPAIR_CYCLE_CAP } from './aggregation-types.js';
19
19
  export { REPAIR_CYCLE_METRIC_VERSION } from './repair-cycle-metric.js';
20
20
  export { readAllSessionEvents, readSessionEvents } from './aggregation-helpers.js';
21
- export type { DashboardMetrics, FanoutBreakdown, LegacyQaEventCount, Period, QaRoundSummary, RepairCycleReport, SliceRollup, StatusAggregate } from './aggregation-types.js';
21
+ export type { DashboardMetrics, FanoutBreakdown, LegacyQaEventCount, Period, QaRoundSummary, RepairCycleReport, SliceOutcome, SliceRollup, StatusAggregate } from './aggregation-types.js';
22
+ /**
23
+ * How one slice ended, from its rollup.
24
+ *
25
+ * ONE spelling of the three outcomes, shared by the status counts and by the
26
+ * report's slice table: a slice that reached a terminal success state, a slice
27
+ * that reached a terminal failure state, and a slice that reached NEITHER — it
28
+ * advanced partway and stopped (at `qa-handoff`, typically). The last is not a
29
+ * failure, so it is not counted as one and is not drawn as one.
30
+ */
31
+ export declare function sliceOutcome(rollup: SliceRollup): SliceOutcome;
22
32
  export declare function aggregateStatus(events: readonly ObservabilityEvent[]): StatusAggregate;
23
33
  export declare function aggregateSlices(events: readonly ObservabilityEvent[]): SliceRollup[];
24
34
  export declare function aggregateFanout(events: readonly ObservabilityEvent[]): FanoutBreakdown;
@@ -17,6 +17,7 @@ import { readObservabilityEvents } from './observability-service.js';
17
17
  import { TERMINAL_FAIL_STATES, TERMINAL_HAPPY_STATES, ZERO_FANOUT } from './aggregation-types.js';
18
18
  import { durationMsBetween, isSliceTransition, transitionTo } from './aggregation-helpers.js';
19
19
  import { buildRepairCycleReport, computeSliceRepairMetrics } from './repair-cycle-metric.js';
20
+ import { sliceIdentity } from '../../shared/incrementing-number.js';
20
21
  // The result shapes and their data (terminal states, repair-loop cap, zeroed
21
22
  // fan-out row) live in `aggregation-types.ts`; the event-detail readers and
22
23
  // the event-source helpers live in `aggregation-helpers.ts` (wave-3 file-size
@@ -34,7 +35,7 @@ function rollupSlices(events) {
34
35
  for (const event of events) {
35
36
  if (!isSliceTransition(event))
36
37
  continue;
37
- const rid = event.sliceRid;
38
+ const rid = sliceIdentity(event.sliceRid).logical;
38
39
  let rollup = bySlice.get(rid);
39
40
  if (rollup === undefined) {
40
41
  rollup = {
@@ -70,6 +71,22 @@ function rollupSlices(events) {
70
71
  return bySlice;
71
72
  }
72
73
  // ----- public aggregations -----
74
+ /**
75
+ * How one slice ended, from its rollup.
76
+ *
77
+ * ONE spelling of the three outcomes, shared by the status counts and by the
78
+ * report's slice table: a slice that reached a terminal success state, a slice
79
+ * that reached a terminal failure state, and a slice that reached NEITHER — it
80
+ * advanced partway and stopped (at `qa-handoff`, typically). The last is not a
81
+ * failure, so it is not counted as one and is not drawn as one.
82
+ */
83
+ export function sliceOutcome(rollup) {
84
+ if (rollup.success)
85
+ return 'success';
86
+ if (rollup.finalState !== null && TERMINAL_FAIL_STATES.has(rollup.finalState))
87
+ return 'failed';
88
+ return 'stalled';
89
+ }
73
90
  export function aggregateStatus(events) {
74
91
  const bySlice = rollupSlices(events);
75
92
  const metrics = computeSliceRepairMetrics(events);
@@ -80,14 +97,22 @@ export function aggregateStatus(events) {
80
97
  if (cycles > repairCyclePeak)
81
98
  repairCyclePeak = cycles;
82
99
  }
83
- const successCount = Array.from(bySlice.values()).filter((r) => r.success).length;
84
- const failCount = Array.from(bySlice.values()).filter((r) => r.finalState !== null && TERMINAL_FAIL_STATES.has(r.finalState)).length;
100
+ // The three outcome buckets come from the ONE outcome spelling above, so
101
+ // they partition the slice set: every slice lands in exactly one bucket and
102
+ // `successCount + failCount + stalledCount === totalSlices` holds for every
103
+ // event set. Before the third bucket existed, a slice stuck at `qa-handoff`
104
+ // was in NEITHER the success nor the fail count and the summary reported
105
+ // fewer outcomes than the slice table showed rows.
106
+ const successCount = Array.from(bySlice.values()).filter((r) => sliceOutcome(r) === 'success').length;
107
+ const failCount = Array.from(bySlice.values()).filter((r) => sliceOutcome(r) === 'failed').length;
108
+ const stalledCount = Array.from(bySlice.values()).filter((r) => sliceOutcome(r) === 'stalled').length;
85
109
  const fanoutCostTotal = events.filter((e) => e.category === 'dispatch').length;
86
110
  return {
87
111
  totalEvents: events.length,
88
112
  totalSlices: bySlice.size,
89
113
  successCount,
90
114
  failCount,
115
+ stalledCount,
91
116
  repairCyclePeak,
92
117
  fanoutCostTotal
93
118
  };
@@ -0,0 +1,77 @@
1
+ /**
2
+ * `src/services/observability/compliance-judge.ts`
3
+ *
4
+ * The judge: given a compliance spec and a way to ask whether an artifact
5
+ * exists, report which declared steps actually ran.
6
+ *
7
+ * WHY A JUDGE AND NOT A SCOREBOARD. A pass rate says "the slice passed"; a
8
+ * compliance rate says "the checks the skill PROMISED ran". The difference is
9
+ * the point of the campaign: a slice can pass its gate while a step the skill
10
+ * declared never happened, and only the second reading sees that.
11
+ *
12
+ * THE JUDGE IS PURE. It never touches a filesystem: whether an artifact exists
13
+ * is asked through the `exists` callback the caller supplies. That is what
14
+ * makes one spec judgeable against a real workspace, a fixture, or a
15
+ * hypothetical — and it is why the rules below are statements about RULES
16
+ * rather than about a machine's state.
17
+ *
18
+ * THE DEMOTION RULE, AND WHY IT IS A FIXPOINT. A step that declares
19
+ * `afterStep: X` cannot be credited on the strength of its own artifact when X
20
+ * did not run: the audit that exists without the handoff it read is not
21
+ * evidence of an audit. Demoting one step can invalidate whatever depended on
22
+ * it, so the demotion is applied repeatedly until nothing changes — and since
23
+ * demotion only ever removes a pass, the loop terminates.
24
+ *
25
+ * STEP IDS MUST BE UNIQUE INSIDE A SPEC, AND THE JUDGE ENFORCES IT. The
26
+ * demotion looks a prerequisite up by id, so two steps sharing one id would be
27
+ * judged against each other — and each would overwrite the other's presence
28
+ * in the judge's bookkeeping, so both would report the same verdict. That is
29
+ * a silently wrong compliance number, which is the exact failure this
30
+ * campaign exists to prevent, so a spec that declares one id twice is
31
+ * REJECTED with an error naming the id rather than scored.
32
+ */
33
+ import type { ComplianceSpec } from './compliance-spec.js';
34
+ /** What the judge concluded about one declared step. */
35
+ export type StepResult = {
36
+ /** The step's id, so a reader can find it in the spec. */
37
+ readonly stepId: string;
38
+ /** Whether the step's artifact was there. */
39
+ readonly executed: boolean;
40
+ /**
41
+ * Why the step did not execute. Present exactly when `executed` is false;
42
+ * absent when it is true, because a passing step has nothing to explain.
43
+ */
44
+ readonly failureReason?: string;
45
+ };
46
+ /** The verdict for one spec. */
47
+ export type ComplianceResult = {
48
+ /** The spec's id. */
49
+ readonly specId: string;
50
+ /** One entry per declared step, in the order the spec declares them. */
51
+ readonly steps: readonly StepResult[];
52
+ /**
53
+ * The share of REQUIRED steps that executed. A spec that declares no
54
+ * required step demonstrates no compliance, so the rate is 0 rather than a
55
+ * vacuous 1: the reading that lets a spec declaring nothing read as
56
+ * perfect compliance is the one this metric exists to refuse.
57
+ */
58
+ readonly complianceRate: number;
59
+ };
60
+ /**
61
+ * Judge one spec.
62
+ *
63
+ * @param spec the declared steps to judge.
64
+ * @param exists asked whether a session-relative artifact path is present.
65
+ * THE PATH ARRIVES WITH ITS `<rid>` PLACEHOLDER UNRESOLVED. The judge hands
66
+ * the declared path through verbatim; the CALLER substitutes the request id
67
+ * before probing the filesystem. A caller that probes the raw string gets
68
+ * the literal `<rid>` as a path, every step misses, and the rate reads 0
69
+ * without a single error — so the substitution is the caller's job, and it
70
+ * is stated here because that is where the callback is declared.
71
+ *
72
+ * @throws Error when two steps of the spec share one id. The judge's
73
+ * bookkeeping is keyed by step id, so a repeated id would make two steps
74
+ * overwrite each other's presence and report the same verdict — a silently
75
+ * wrong compliance number. A malformed spec is refused rather than scored.
76
+ */
77
+ export declare function judgeCompliance(spec: ComplianceSpec, exists: (artifactPath: string) => boolean): ComplianceResult;