@simonren/quorum 0.9.1 → 0.11.0

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 (68) hide show
  1. package/README.md +91 -48
  2. package/commands/multi-consult.md +47 -72
  3. package/commands/multi-review.md +68 -99
  4. package/dist/adapters/base.d.ts +53 -70
  5. package/dist/adapters/base.js +21 -79
  6. package/dist/adapters/claude.d.ts +38 -17
  7. package/dist/adapters/claude.js +93 -185
  8. package/dist/adapters/cli-adapter.d.ts +78 -0
  9. package/dist/adapters/cli-adapter.js +217 -0
  10. package/dist/adapters/codex.d.ts +18 -13
  11. package/dist/adapters/codex.js +64 -200
  12. package/dist/adapters/gemini.d.ts +30 -21
  13. package/dist/adapters/gemini.js +55 -149
  14. package/dist/adapters/index.d.ts +8 -5
  15. package/dist/adapters/index.js +7 -8
  16. package/dist/config.d.ts +98 -28
  17. package/dist/config.js +44 -25
  18. package/dist/consult-prompt.d.ts +6 -5
  19. package/dist/consult-prompt.js +48 -23
  20. package/dist/decoders/claude.d.ts +6 -0
  21. package/dist/decoders/claude.js +10 -1
  22. package/dist/doctor.d.ts +20 -0
  23. package/dist/doctor.js +91 -0
  24. package/dist/executor.d.ts +58 -46
  25. package/dist/executor.js +218 -129
  26. package/dist/guards.d.ts +29 -0
  27. package/dist/guards.js +72 -0
  28. package/dist/handoff.d.ts +79 -229
  29. package/dist/handoff.js +411 -402
  30. package/dist/index.d.ts +8 -12
  31. package/dist/index.js +81 -106
  32. package/dist/integrity.d.ts +16 -0
  33. package/dist/integrity.js +49 -0
  34. package/dist/sections.d.ts +22 -0
  35. package/dist/sections.js +31 -0
  36. package/dist/server.d.ts +9 -0
  37. package/dist/server.js +36 -0
  38. package/dist/tools/consult.d.ts +17 -76
  39. package/dist/tools/consult.js +72 -188
  40. package/dist/tools/format.d.ts +35 -0
  41. package/dist/tools/format.js +85 -0
  42. package/dist/tools/review.d.ts +55 -0
  43. package/dist/tools/review.js +120 -0
  44. package/dist/types.d.ts +20 -103
  45. package/dist/types.js +18 -29
  46. package/package.json +7 -4
  47. package/dist/cli/check.d.ts +0 -20
  48. package/dist/cli/check.js +0 -78
  49. package/dist/cli/codex.d.ts +0 -11
  50. package/dist/cli/codex.js +0 -255
  51. package/dist/cli/gemini.d.ts +0 -12
  52. package/dist/cli/gemini.js +0 -253
  53. package/dist/context.d.ts +0 -1538
  54. package/dist/context.js +0 -383
  55. package/dist/decoders/gemini.d.ts +0 -33
  56. package/dist/decoders/gemini.js +0 -58
  57. package/dist/errors.d.ts +0 -46
  58. package/dist/errors.js +0 -198
  59. package/dist/pipeline.d.ts +0 -135
  60. package/dist/pipeline.js +0 -462
  61. package/dist/prompt-v2.d.ts +0 -38
  62. package/dist/prompt-v2.js +0 -391
  63. package/dist/prompt.d.ts +0 -71
  64. package/dist/prompt.js +0 -309
  65. package/dist/schema.d.ts +0 -660
  66. package/dist/schema.js +0 -536
  67. package/dist/tools/feedback.d.ts +0 -91
  68. package/dist/tools/feedback.js +0 -117
package/dist/handoff.d.ts CHANGED
@@ -1,188 +1,64 @@
1
1
  /**
2
- * Review Handoff Protocol
3
- *
4
- * Defines the minimal, targeted information that should flow from CC to reviewers.
2
+ * Review handoff protocol — what flows from Claude Code (CC) to a reviewer,
3
+ * and the prompts built from it.
5
4
  *
6
5
  * Philosophy:
7
- * - Reviewers have filesystem access - don't duplicate what they can discover
8
- * - Pass ONLY what CC uniquely knows: uncertainties, decisions, questions
9
- * - Let reviewer use their tools (file reading) for actual code
10
- * - Do NOT assume git — working directory may not be a git repo
11
- */
12
- import { z } from 'zod';
13
- import { FocusArea } from './types.js';
14
- export { FocusArea } from './types.js';
15
- /**
16
- * Uncertainty that CC has - things the reviewer should verify
6
+ * - Reviewers have the filesystem; CC has the conversation. The brief carries
7
+ * only what CC uniquely knows: what it did, the bar it must clear, its
8
+ * uncertainties, questions, decisions, and acknowledged gaps.
9
+ * - Reviewers verify against the code, they do not trust the brief.
10
+ * - Reviewer output goes back to CC for verification and synthesis, so it is
11
+ * asked for in a fixed markdown structure that CC can cross-reference across
12
+ * models and passes.
17
13
  */
18
- export declare const UncertaintySchema: z.ZodObject<{
19
- topic: z.ZodString;
20
- question: z.ZodString;
21
- ccAssumption: z.ZodOptional<z.ZodString>;
22
- relevantFiles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
23
- severity: z.ZodOptional<z.ZodEnum<["critical", "important", "minor"]>>;
24
- }, "strip", z.ZodTypeAny, {
25
- question: string;
14
+ import { FocusArea, OutputType } from './types.js';
15
+ import type { ReviewRequest } from './adapters/base.js';
16
+ export type { FocusArea } from './types.js';
17
+ export type UncertaintyWeight = 'load-bearing' | 'incidental';
18
+ export interface Uncertainty {
19
+ /** Short label (first clause of the question). */
26
20
  topic: string;
27
- relevantFiles?: string[] | undefined;
28
- severity?: "critical" | "important" | "minor" | undefined;
29
- ccAssumption?: string | undefined;
30
- }, {
21
+ /** The full uncertainty as CC stated it. */
31
22
  question: string;
32
- topic: string;
33
- relevantFiles?: string[] | undefined;
34
- severity?: "critical" | "important" | "minor" | undefined;
35
- ccAssumption?: string | undefined;
36
- }>;
37
- export type Uncertainty = z.infer<typeof UncertaintySchema>;
38
- /**
39
- * Decision CC made - for reviewer to evaluate
40
- */
41
- export declare const DecisionSchema: z.ZodObject<{
42
- decision: z.ZodString;
43
- rationale: z.ZodString;
44
- alternatives: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
45
- tradeoffs: z.ZodOptional<z.ZodString>;
46
- }, "strip", z.ZodTypeAny, {
47
- decision: string;
48
- rationale: string;
49
- alternatives?: string[] | undefined;
50
- tradeoffs?: string | undefined;
51
- }, {
23
+ /** What CC assumed or did — the reviewer should verify it. */
24
+ ccAssumption?: string;
25
+ /** Files related to this uncertainty. */
26
+ relevantFiles?: string[];
27
+ /** load-bearing: if wrong, the work is not shippable. incidental: nice to check. */
28
+ weight?: UncertaintyWeight;
29
+ }
30
+ export interface Decision {
52
31
  decision: string;
53
- rationale: string;
54
- alternatives?: string[] | undefined;
55
- tradeoffs?: string | undefined;
56
- }>;
57
- export type Decision = z.infer<typeof DecisionSchema>;
58
- /**
59
- * Question CC wants the reviewer to answer
60
- */
61
- export declare const QuestionSchema: z.ZodObject<{
62
- question: z.ZodString;
63
- context: z.ZodOptional<z.ZodString>;
64
- ccGuess: z.ZodOptional<z.ZodString>;
65
- }, "strip", z.ZodTypeAny, {
66
- question: string;
67
- context?: string | undefined;
68
- ccGuess?: string | undefined;
69
- }, {
32
+ rationale?: string;
33
+ alternatives?: string[];
34
+ }
35
+ export interface Question {
70
36
  question: string;
71
- context?: string | undefined;
72
- ccGuess?: string | undefined;
73
- }>;
74
- export type Question = z.infer<typeof QuestionSchema>;
75
- /**
76
- * The complete handoff from CC to reviewer
77
- * Intentionally minimal - only what CC uniquely knows
78
- */
79
- export declare const HandoffSchema: z.ZodObject<{
80
- workingDir: z.ZodString;
81
- summary: z.ZodString;
82
- uncertainties: z.ZodOptional<z.ZodArray<z.ZodObject<{
83
- topic: z.ZodString;
84
- question: z.ZodString;
85
- ccAssumption: z.ZodOptional<z.ZodString>;
86
- relevantFiles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
87
- severity: z.ZodOptional<z.ZodEnum<["critical", "important", "minor"]>>;
88
- }, "strip", z.ZodTypeAny, {
89
- question: string;
90
- topic: string;
91
- relevantFiles?: string[] | undefined;
92
- severity?: "critical" | "important" | "minor" | undefined;
93
- ccAssumption?: string | undefined;
94
- }, {
95
- question: string;
96
- topic: string;
97
- relevantFiles?: string[] | undefined;
98
- severity?: "critical" | "important" | "minor" | undefined;
99
- ccAssumption?: string | undefined;
100
- }>, "many">>;
101
- decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
102
- decision: z.ZodString;
103
- rationale: z.ZodString;
104
- alternatives: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
105
- tradeoffs: z.ZodOptional<z.ZodString>;
106
- }, "strip", z.ZodTypeAny, {
107
- decision: string;
108
- rationale: string;
109
- alternatives?: string[] | undefined;
110
- tradeoffs?: string | undefined;
111
- }, {
112
- decision: string;
113
- rationale: string;
114
- alternatives?: string[] | undefined;
115
- tradeoffs?: string | undefined;
116
- }>, "many">>;
117
- questions: z.ZodOptional<z.ZodArray<z.ZodObject<{
118
- question: z.ZodString;
119
- context: z.ZodOptional<z.ZodString>;
120
- ccGuess: z.ZodOptional<z.ZodString>;
121
- }, "strip", z.ZodTypeAny, {
122
- question: string;
123
- context?: string | undefined;
124
- ccGuess?: string | undefined;
125
- }, {
126
- question: string;
127
- context?: string | undefined;
128
- ccGuess?: string | undefined;
129
- }>, "many">>;
130
- priorityFiles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
131
- focusAreas: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
132
- confidence: z.ZodOptional<z.ZodNumber>;
133
- customInstructions: z.ZodOptional<z.ZodString>;
134
- }, "strip", z.ZodTypeAny, {
135
- workingDir: string;
136
- summary: string;
137
- confidence?: number | undefined;
138
- uncertainties?: {
139
- question: string;
140
- topic: string;
141
- relevantFiles?: string[] | undefined;
142
- severity?: "critical" | "important" | "minor" | undefined;
143
- ccAssumption?: string | undefined;
144
- }[] | undefined;
145
- decisions?: {
146
- decision: string;
147
- rationale: string;
148
- alternatives?: string[] | undefined;
149
- tradeoffs?: string | undefined;
150
- }[] | undefined;
151
- questions?: {
152
- question: string;
153
- context?: string | undefined;
154
- ccGuess?: string | undefined;
155
- }[] | undefined;
156
- focusAreas?: string[] | undefined;
157
- customInstructions?: string | undefined;
158
- priorityFiles?: string[] | undefined;
159
- }, {
37
+ context?: string;
38
+ ccGuess?: string;
39
+ }
40
+ /** The complete brief from CC to a reviewer. Intentionally minimal. */
41
+ export interface Handoff {
160
42
  workingDir: string;
43
+ /** What kind of work the brief describes. */
44
+ outputType?: OutputType;
45
+ /** Git ref the change is relative to when the tree is clean (a checked-out PR). */
46
+ baseRef?: string;
47
+ /** What CC did and why (1–3 sentences). */
161
48
  summary: string;
162
- confidence?: number | undefined;
163
- uncertainties?: {
164
- question: string;
165
- topic: string;
166
- relevantFiles?: string[] | undefined;
167
- severity?: "critical" | "important" | "minor" | undefined;
168
- ccAssumption?: string | undefined;
169
- }[] | undefined;
170
- decisions?: {
171
- decision: string;
172
- rationale: string;
173
- alternatives?: string[] | undefined;
174
- tradeoffs?: string | undefined;
175
- }[] | undefined;
176
- questions?: {
177
- question: string;
178
- context?: string | undefined;
179
- ccGuess?: string | undefined;
180
- }[] | undefined;
181
- focusAreas?: string[] | undefined;
182
- customInstructions?: string | undefined;
183
- priorityFiles?: string[] | undefined;
184
- }>;
185
- export type Handoff = z.infer<typeof HandoffSchema>;
49
+ /** What "shipping-ready" means here — reviewers judge "material" against it. */
50
+ bar?: string;
51
+ uncertainties?: Uncertainty[];
52
+ questions?: Question[];
53
+ decisions?: Decision[];
54
+ /** Gaps CC deliberately left — reviewers should not re-report them. */
55
+ knownGaps?: string[];
56
+ /** Files to read first (CC's changed files + anything it flagged). */
57
+ priorityFiles?: string[];
58
+ focusAreas?: FocusArea[];
59
+ /** Free-form steering from the user. */
60
+ customInstructions?: string;
61
+ }
186
62
  export interface ReviewerRole {
187
63
  id: string;
188
64
  name: string;
@@ -191,80 +67,54 @@ export interface ReviewerRole {
191
67
  applicableFocusAreas: FocusArea[];
192
68
  systemPrompt: string;
193
69
  }
194
- /**
195
- * Strong generic role - when no specific focus is given
196
- * This is NOT a weak fallback - it's a comprehensive reviewer
197
- */
70
+ /** Strong generic role when no focus is given — a comprehensive reviewer, not a weak fallback. */
198
71
  export declare const COMPREHENSIVE_REVIEWER: ReviewerRole;
199
- /**
200
- * Change-focused reviewer - specifically for reviewing diffs
201
- */
72
+ /** Change-focused reviewer — used when the requested focus areas map to no specialist. */
202
73
  export declare const CHANGE_FOCUSED_REVIEWER: ReviewerRole;
203
- /**
204
- * Specialized roles - when specific focus is requested
205
- */
206
74
  export declare const SECURITY_REVIEWER: ReviewerRole;
207
75
  export declare const PERFORMANCE_REVIEWER: ReviewerRole;
208
76
  export declare const ARCHITECTURE_REVIEWER: ReviewerRole;
209
77
  export declare const CORRECTNESS_REVIEWER: ReviewerRole;
78
+ export declare const ADVERSARIAL_REVIEWER: ReviewerRole;
210
79
  export declare const ROLES: Record<string, ReviewerRole>;
211
80
  /**
212
- * Select and compose roles based on focus areas.
213
- *
214
- * When multiple focus areas map to different roles (e.g. security + performance),
215
- * composes them into a single role with merged prompts instead of picking one winner.
81
+ * Select and compose roles from focus areas. Multiple areas mapping to
82
+ * different specialists compose into one role with merged prompts.
216
83
  */
217
84
  export declare function selectRole(focusAreas?: FocusArea[]): ReviewerRole;
218
- export declare const ADVERSARIAL_REVIEWER: ReviewerRole;
219
- /**
220
- * Build an adversarial handoff prompt with challenge-mode stance sections.
221
- *
222
- * Block structure ported from openai/codex-plugin-cc's adversarial-review
223
- * prompt: tagged XML blocks (operating_stance, attack_surface, review_method,
224
- * finding_bar, calibration_rules, grounding_rules, final_check) so the prompt
225
- * has stable internal structure the reviewer can lean on. CC's handoff
226
- * sections (uncertainties / decisions / questions / focus / files / focus
227
- * instructions) are layered on after as our differentiator.
228
- */
229
- export declare function buildAdversarialHandoffPrompt(options: PromptOptions): string;
85
+ /** Section headers the reviewer must emit, in order. */
86
+ export declare const REVIEW_RESPONSE_SECTIONS: readonly ["Verdict", "Findings", "Answers", "Decisions"];
87
+ /** The subset whose absence marks a response as drifted. */
88
+ export declare const REQUIRED_REVIEW_SECTIONS: readonly ["Verdict", "Findings"];
230
89
  export interface PromptOptions {
231
90
  handoff: Handoff;
232
91
  role?: ReviewerRole;
233
92
  }
234
- /**
235
- * Build the review prompt using minimal, targeted context.
236
- * No output format constraints — reviewer responds naturally, CC interprets.
237
- */
93
+ /** Standard review pass: find bugs and gaps, judge against the bar. */
238
94
  export declare function buildHandoffPrompt(options: PromptOptions): string;
239
95
  /**
240
- * Parse structured ccOutput into Handoff fields.
241
- *
242
- * The slash commands tell CC to format its output as:
243
- * SUMMARY:
244
- * <text>
245
- *
246
- * UNCERTAINTIES (verify these):
247
- * 1. <text>
96
+ * Adversarial pass: break confidence in the change.
248
97
  *
249
- * QUESTIONS:
250
- * 1. <text>
251
- *
252
- * PRIORITY FILES:
253
- * - <file>
254
- *
255
- * If no sections detected, returns { summary: ccOutput } (graceful fallback).
98
+ * The tagged blocks (operating_stance, attack_surface, review_method,
99
+ * finding_bar, calibration_rules, grounding_rules, final_check) are ported
100
+ * from openai/codex-plugin-cc's adversarial-review prompt so the reviewer has
101
+ * a stable operating contract; CC's brief is layered on after.
256
102
  */
257
- export declare function parseStructuredCcOutput(ccOutput: string): Pick<Handoff, 'summary'> & Partial<Handoff>;
103
+ export declare function buildAdversarialHandoffPrompt(options: PromptOptions): string;
104
+ /** Build the prompt for a ReviewRequest, selecting the pass from `reviewMode`. */
105
+ export declare function buildReviewPrompt(request: ReviewRequest): string;
258
106
  /**
259
- * Build a handoff from MCP tool inputs.
107
+ * Parse CC's structured brief into Handoff fields.
260
108
  *
261
- * Parses structured sections (SUMMARY, UNCERTAINTIES, QUESTIONS, PRIORITY FILES)
262
- * from ccOutput when present, populating typed Handoff fields so reviewers
263
- * receive machine-usable context instead of a single summary blob.
109
+ * The slash command tells CC to format its output as ALL-CAPS section headers
110
+ * (`SUMMARY:`, `UNCERTAINTIES (verify these):`, ...). Headers are matched
111
+ * case-sensitively at the start of a line so prose such as "Questions: none"
112
+ * inside a section cannot open a new one. Unstructured input falls back to
113
+ * `{ summary: ccOutput }`.
264
114
  */
265
- export declare function buildSimpleHandoff(workingDir: string, ccOutput: string, analyzedFiles?: string[], focusAreas?: string[], customPrompt?: string): Handoff;
115
+ export declare function parseStructuredCcOutput(ccOutput: string): Pick<Handoff, 'summary'> & Partial<Handoff>;
266
116
  /**
267
- * Enhance a simple handoff with uncertainties/questions
268
- * CC should call this to add its specific concerns
117
+ * Build a handoff from MCP tool inputs. Structured sections in ccOutput are
118
+ * parsed into typed fields; `analyzedFiles` are merged into priorityFiles.
269
119
  */
270
- export declare function enhanceHandoff(handoff: Handoff, uncertainties?: Uncertainty[], questions?: Question[], decisions?: Decision[]): Handoff;
120
+ export declare function buildSimpleHandoff(workingDir: string, ccOutput: string, analyzedFiles?: string[], focusAreas?: FocusArea[], customPrompt?: string, outputType?: OutputType, baseRef?: string): Handoff;