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.
- package/.claude-plugin/marketplace.json +12 -2
- package/CHANGELOG.md +184 -0
- package/dist/cli/commands/code-auto-compact-command.js +19 -1
- package/dist/cli/commands/code-gate-step-08-command.js +103 -105
- package/dist/cli/commands/code-gate-step-08-remedy.d.ts +10 -2
- package/dist/cli/commands/code-gate-step-08-remedy.js +11 -3
- package/dist/cli/commands/gate-commands-enforce.d.ts +23 -8
- package/dist/cli/commands/gate-commands-enforce.js +27 -12
- package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
- package/dist/cli/commands/observability-commands-hotspots.js +222 -0
- package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
- package/dist/cli/commands/observability-commands-near-miss.js +105 -0
- package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
- package/dist/cli/commands/observability-commands-queries.js +88 -47
- package/dist/cli/commands/observability-commands-session-row.d.ts +48 -0
- package/dist/cli/commands/observability-commands-session-row.js +201 -0
- package/dist/cli/commands/observability-commands.js +81 -20
- package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
- package/dist/services/artifacts/artifact-prerequisites.js +1 -1
- package/dist/services/artifacts/prerequisite-path-census.d.ts +47 -0
- package/dist/services/artifacts/prerequisite-path-census.js +100 -0
- package/dist/services/artifacts/prerequisite-path-resolver.js +32 -2
- package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
- package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
- package/dist/services/artifacts/rd-gate-event.js +211 -0
- package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
- package/dist/services/artifacts/rd-transition-gates.js +65 -24
- package/dist/services/hooks/output.d.ts +67 -1
- package/dist/services/hooks/output.js +74 -1
- package/dist/services/observability/aggregation-types.d.ts +21 -0
- package/dist/services/observability/aggregation.d.ts +12 -2
- package/dist/services/observability/aggregation.js +28 -3
- package/dist/services/observability/compliance-judge.d.ts +77 -0
- package/dist/services/observability/compliance-judge.js +143 -0
- package/dist/services/observability/compliance-spec.d.ts +96 -0
- package/dist/services/observability/compliance-spec.js +29 -0
- package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
- package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
- package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
- package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
- package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
- package/dist/services/observability/hotspot-attribution-summary.js +74 -0
- package/dist/services/observability/hotspot-rows.d.ts +47 -0
- package/dist/services/observability/hotspot-rows.js +89 -0
- package/dist/services/observability/hotspot-shared.d.ts +207 -0
- package/dist/services/observability/hotspot-shared.js +127 -0
- package/dist/services/observability/hotspot-sources.d.ts +55 -0
- package/dist/services/observability/hotspot-sources.js +142 -0
- package/dist/services/observability/hotspots.d.ts +47 -0
- package/dist/services/observability/hotspots.js +47 -0
- package/dist/services/observability/near-miss-attempts.d.ts +175 -0
- package/dist/services/observability/near-miss-attempts.js +223 -0
- package/dist/services/observability/near-miss-coverage.d.ts +109 -0
- package/dist/services/observability/near-miss-coverage.js +108 -0
- package/dist/services/observability/near-miss-denominator.d.ts +81 -0
- package/dist/services/observability/near-miss-denominator.js +75 -0
- package/dist/services/observability/near-miss-difference.d.ts +98 -0
- package/dist/services/observability/near-miss-difference.js +135 -0
- package/dist/services/observability/near-miss-facts.d.ts +165 -0
- package/dist/services/observability/near-miss-facts.js +101 -0
- package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
- package/dist/services/observability/near-miss-gate-events.js +106 -0
- package/dist/services/observability/near-miss-gates.d.ts +108 -0
- package/dist/services/observability/near-miss-gates.js +135 -0
- package/dist/services/observability/near-miss-records.d.ts +93 -0
- package/dist/services/observability/near-miss-records.js +87 -0
- package/dist/services/observability/near-miss.d.ts +148 -0
- package/dist/services/observability/near-miss.js +203 -0
- package/dist/services/observability/observability-schema.d.ts +17 -2
- package/dist/services/observability/observability-schema.js +21 -1
- package/dist/services/observability/owner-skill-map.d.ts +92 -0
- package/dist/services/observability/owner-skill-map.js +164 -0
- package/dist/services/observability/repair-cycle-metric.js +6 -3
- package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
- package/dist/services/observability/report-formatter-hotspots.js +76 -0
- package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
- package/dist/services/observability/report-formatter-near-miss.js +234 -0
- package/dist/services/observability/report-formatter.d.ts +49 -3
- package/dist/services/observability/report-formatter.js +55 -14
- package/dist/services/observability/retro-attribution.d.ts +129 -0
- package/dist/services/observability/retro-attribution.js +134 -0
- package/dist/services/observability/session-metric-rows.d.ts +153 -0
- package/dist/services/observability/session-metric-rows.js +184 -0
- package/dist/services/skills/presence-role.js +9 -2
- package/dist/services/standards/loop-engineering-readiness-lint.d.ts +15 -1
- package/dist/services/standards/loop-engineering-readiness-lint.js +27 -9
- package/dist/shared/incrementing-number.d.ts +57 -0
- package/dist/shared/incrementing-number.js +13 -0
- package/dist/skills/peaks-maker/index.js +43 -30
- package/output-styles/peaks-skill-swarm.md +2 -2
- package/package.json +5 -5
- package/scripts/install-skills-bundles.mjs +6 -1
- package/scripts/install-skills.mjs +10 -1
- package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
- package/skills/bee/peaks-prd/SKILL.md +1 -1
- package/skills/bee/peaks-qa/SKILL.md +1 -1
- package/skills/bee/peaks-rd/SKILL.md +1 -1
- package/skills/bee/peaks-reviewer/SKILL.md +1 -1
- package/skills/bee/peaks-sc/SKILL.md +1 -1
- package/skills/bee/peaks-security-audit/SKILL.md +1 -1
- package/skills/bee/peaks-txt/SKILL.md +1 -1
- package/skills/bee/peaks-ui/SKILL.md +1 -1
- package/skills/peaks-audit/SKILL.md +1 -1
- package/skills/peaks-code/SKILL.md +1 -1
- package/skills/peaks-content/SKILL.md +1 -1
- package/skills/peaks-doctor/SKILL.md +1 -1
- package/skills/peaks-final-review/SKILL.md +1 -1
- package/skills/peaks-ide/SKILL.md +1 -1
- package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
- package/skills/peaks-maker/SKILL.md +125 -0
- package/skills/peaks-mut/SKILL.md +297 -0
- package/skills/peaks-race-code/SKILL.md +1 -1
- package/skills/peaks-resume/SKILL.md +1 -1
- package/skills/peaks-slice-decompose/SKILL.md +1 -1
- package/skills/peaks-solo/SKILL.md +1 -1
- package/skills/peaks-sop/SKILL.md +1 -1
- package/skills/peaks-status/SKILL.md +1 -1
- 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
|
|
32
|
-
|
|
33
|
-
|
|
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
|
-
|
|
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
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
-
|
|
84
|
-
|
|
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;
|