@simonren/quorum 0.12.2 → 0.14.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.
package/README.md CHANGED
@@ -83,13 +83,13 @@ You have a question → /multi-consult → question + criteria → Codex, Gemi
83
83
 
84
84
  **Key principles:**
85
85
  - **Claude Code is primary.** External models assist; Claude Code verifies and decides.
86
- - **Working-directory strategy.** Claude Code passes the cwd and a small brief; reviewers read the files themselves. Read-only by contract: Codex runs with `--sandbox read-only`; Claude runs in default permission mode with prompts disabled, write and agent tools removed, and only read-only `git` allowed in Bash; agy runs with `--sandbox`, which covers only its terminal, and agy lets the model rerun a command outside it unless agy's `toolPermission` is `proceed-in-sandbox` (`doctor` warns on `always-proceed`). agy cannot make its file tools read-only, so quorum fingerprints the working tree (`git status`) before and after every run and flags any change at the top of the result.
86
+ - **Working-directory strategy.** Claude Code passes the cwd and a small brief; reviewers read the files themselves. Read-only by contract: Codex runs with `--sandbox read-only`; Claude runs in default permission mode with prompts disabled and holds only the Read, Grep, Glob and Bash tools, with Bash limited to read-only commands; agy runs with `--sandbox`, which covers only its terminal, and agy lets the model rerun a command outside it unless agy's `toolPermission` is `proceed-in-sandbox` (`doctor` warns on `always-proceed`). agy cannot make its file tools read-only, so quorum fingerprints the working tree (`git status`, plus the size and mtime of every file it lists) before and after every run and flags any change at the top of the result. Ignored files and `.git/` are outside that check.
87
87
  - **Structured, verifiable answers.** Reviewers respond with `Verdict` / `Findings` (severity, location, evidence, impact, fix, confidence) / `Answers` / `Decisions`; drift from the contract is flagged so Claude Code can discount it.
88
88
  - **Synthesis, not passthrough.** Raw model output never reaches you unless you ask for it; the provenance footer always does.
89
89
 
90
90
  ## Configuration
91
91
 
92
- `~/.config/quorum/config.json` is created with defaults on first launch and hot-reloaded when edited. Every key is optional.
92
+ `~/.config/quorum/config.json` is created empty on first launch and hot-reloaded when edited. Every key is optional, and a key you leave out follows the current release's default.
93
93
 
94
94
  ```json
95
95
  {
@@ -71,16 +71,16 @@ The call takes minutes. Do not call it twice for the same work.
71
71
 
72
72
  ## Step 3 — Verify, then judge
73
73
 
74
- The result is a `# Multi-Model Review` header followed by `## Standard review` and `## Adversarial review`, each holding one `<review model=… pass=… status=…>` block per model. Each block is a reviewer's raw response in the shape `## Verdict` / `## Findings` (`[S1|S2|S3]` with Location, Evidence, Impact, Fix, Confidence) / `## Answers` / `## Decisions`. A block may carry `status="failed"` or a `⚠️ Format drift` line.
74
+ The result is a `# Multi-Model Review` header followed by `## Standard review` and `## Adversarial review`, each holding one `<review model=… pass=… status=…>` block per model. Each block is a reviewer's raw response in the shape `## Verdict` / `## Findings` (`[S1|S2]` with Location, Evidence, Impact, Fix, Confidence; `[S3]` as one-liners) / `## Answers` / `## Decisions`. Answer and decision lines start with an id — `U1`, `Q1`, `D1` — that numbers your brief's uncertainties, questions and decisions in the order you wrote them, the same in every block. A block may carry `status="failed"` or a `⚠️ Format drift` line.
75
75
 
76
76
  1. **Read every block.** Note which model/pass failed and why; that goes in your report.
77
77
  2. **Merge findings** into one deduplicated list across models and passes. Record who raised each. Agreement raises priority but does not replace verification.
78
- 3. **Verify each finding yourself.** Open the file at the cited location, trace the failure path, and mark it:
78
+ 3. **Verify the findings that decide the verdict, once each:** every S1/S2, and any finding that would change your verdict. Read only the cited ranges, batching several locations into one tool call; trace the failure path and mark it:
79
79
  - ✓✓ verified — you confirmed the failure path in the code
80
80
  - ✓ plausible — consistent with the code, not fully traced
81
- - ✗ rejected — say why in one line
82
- Adversarial-only findings are speculative by design: verify before acting. A finding with no location or evidence is unverified, not accepted.
83
- 4. **Resolve your own uncertainties** from the Answers sections, load-bearing first. Do the same for your questions and decisions; note where reviewers disagree with each other.
81
+ - ✗ rejected — say why in one line, citing the `path:line` that refutes it. A failure no real caller or input can produce is rejected, not fixed.
82
+ S3 findings are listed as `? unverified` unless you verify them because you are about to fix them; a security, authorization or data-loss finding is verified whatever its severity. Adversarial-only findings are speculative by design: verify before acting. A finding with no location or evidence is unverified, not accepted.
83
+ 4. **Resolve your own uncertainties** from the Answers sections, matching by id, load-bearing first. Do the same for your questions and decisions; note where reviewers disagree with each other.
84
84
  5. **Decide.** Your verdict, judged against your bar, not a tally of the panel's.
85
85
 
86
86
  ## Step 4 — Report
@@ -91,7 +91,7 @@ Use this shape:
91
91
  **Verdict:** SHIP | SHIP WITH FIXES | DO NOT SHIP — <one sentence against the bar>
92
92
 
93
93
  **Must fix** (S1/S2, ✓✓ or ✓): `path:line` — what is wrong → what you will do
94
- **Worth fixing** (S3): …
94
+ **Worth fixing** (S3, `? unverified` unless marked): …
95
95
  **Rejected:** <finding> — <why>, one line each
96
96
  **Uncertainties resolved:** <load-bearing items: verified / refuted / still open>
97
97
 
@@ -13,8 +13,21 @@
13
13
  * Code's planning workflow (write a plan file,
14
14
  * spawn Explore agents, end with ExitPlanMode)
15
15
  * which fights the review brief.
16
- * 2. --disallowed-tools write tools and agent/plan tools removed
17
- * 3. --allowed-tools only read-only git commands may run in Bash
16
+ * 2. --tools the session holds only Read, Grep, Glob and
17
+ * Bash. An allowlist, not a denylist: each
18
+ * Claude Code release adds built-in tools,
19
+ * and one that needs no permission runs
20
+ * whatever layer 1 says — EnterWorktree
21
+ * created a branch and a worktree in the
22
+ * repository under review
23
+ * 3. no --allowed-tools Bash runs only what Claude Code itself
24
+ * judges read-only, which covers the git a
25
+ * review needs (status, diff, log, show,
26
+ * blame, grep, ls-files). An allow rule such
27
+ * as `Bash(git diff *)` must not come back:
28
+ * it bypassed that judgement, so
29
+ * `git diff --output=<file>` wrote the file
30
+ * and `git grep -O<cmd>` ran the command
18
31
  * 4. --strict-mcp-config none of the user's MCP servers are started
19
32
  * 5. --setting-sources '' no user/project/local settings, hooks or
20
33
  * plugins from settings files
@@ -27,10 +40,8 @@
27
40
  */
28
41
  import { ReviewerCapabilities } from './base.js';
29
42
  import { CliAdapter, CliOutcome, RunContext, RunLimits } from './cli-adapter.js';
30
- /** Write tools plus the agent/plan tools a review has no business calling. */
31
- export declare const DISALLOWED_TOOLS = "Edit Write NotebookEdit Agent Task ExitPlanMode AskUserQuestion Workflow";
32
- /** The only shell commands the reviewer may run: read-only git, as the prompt's ground rules promise. */
33
- export declare const ALLOWED_TOOLS: string;
43
+ /** Every tool the reviewer session has. Grep and Glob need no permission, so a search can never be refused. */
44
+ export declare const REVIEWER_TOOLS = "Read,Grep,Glob,Bash";
34
45
  export declare class ClaudeAdapter extends CliAdapter {
35
46
  readonly id = "claude";
36
47
  protected readonly binary = "claude";
@@ -13,8 +13,21 @@
13
13
  * Code's planning workflow (write a plan file,
14
14
  * spawn Explore agents, end with ExitPlanMode)
15
15
  * which fights the review brief.
16
- * 2. --disallowed-tools write tools and agent/plan tools removed
17
- * 3. --allowed-tools only read-only git commands may run in Bash
16
+ * 2. --tools the session holds only Read, Grep, Glob and
17
+ * Bash. An allowlist, not a denylist: each
18
+ * Claude Code release adds built-in tools,
19
+ * and one that needs no permission runs
20
+ * whatever layer 1 says — EnterWorktree
21
+ * created a branch and a worktree in the
22
+ * repository under review
23
+ * 3. no --allowed-tools Bash runs only what Claude Code itself
24
+ * judges read-only, which covers the git a
25
+ * review needs (status, diff, log, show,
26
+ * blame, grep, ls-files). An allow rule such
27
+ * as `Bash(git diff *)` must not come back:
28
+ * it bypassed that judgement, so
29
+ * `git diff --output=<file>` wrote the file
30
+ * and `git grep -O<cmd>` ran the command
18
31
  * 4. --strict-mcp-config none of the user's MCP servers are started
19
32
  * 5. --setting-sources '' no user/project/local settings, hooks or
20
33
  * plugins from settings files
@@ -30,12 +43,8 @@ import { CliAdapter } from './cli-adapter.js';
30
43
  import { CliExecutor } from '../executor.js';
31
44
  import { ClaudeEventDecoder } from '../decoders/index.js';
32
45
  import { getConfig } from '../config.js';
33
- /** Write tools plus the agent/plan tools a review has no business calling. */
34
- export const DISALLOWED_TOOLS = 'Edit Write NotebookEdit Agent Task ExitPlanMode AskUserQuestion Workflow';
35
- /** The only shell commands the reviewer may run: read-only git, as the prompt's ground rules promise. */
36
- export const ALLOWED_TOOLS = [
37
- 'git status', 'git diff', 'git log', 'git show', 'git blame', 'git ls-files', 'git grep', 'git rev-parse', 'git merge-base',
38
- ].flatMap((cmd) => [`Bash(${cmd})`, `Bash(${cmd} *)`]).join(' ');
46
+ /** Every tool the reviewer session has. Grep and Glob need no permission, so a search can never be refused. */
47
+ export const REVIEWER_TOOLS = 'Read,Grep,Glob,Bash';
39
48
  export class ClaudeAdapter extends CliAdapter {
40
49
  id = 'claude';
41
50
  binary = 'claude';
@@ -73,8 +82,7 @@ export class ClaudeAdapter extends CliAdapter {
73
82
  '--output-format', 'stream-json',
74
83
  '--no-session-persistence', // ephemeral — leaves no session on disk
75
84
  '--disable-slash-commands', // no skills — minimal startup
76
- '--disallowed-tools', DISALLOWED_TOOLS, // write + agent tools removed (layer 2)
77
- '--allowed-tools', ALLOWED_TOOLS, // read-only git in Bash (layer 3)
85
+ '--tools', REVIEWER_TOOLS, // nothing but read tools exists in the session (layer 2)
78
86
  ];
79
87
  }
80
88
  async runCli(prompt, workingDir, ctx) {
@@ -158,16 +158,17 @@ export class CliAdapter {
158
158
  }
159
159
  const rateLimit = [
160
160
  'rate limit', 'rate_limit', 'too many requests', 'quota exceeded', 'insufficient_quota', 'exceeded your current quota',
161
- 'overloaded', ...this.extraRateLimitPatterns,
161
+ 'overloaded', 'usage limit', 'spend limit', 'at capacity', ...this.extraRateLimitPatterns,
162
162
  ];
163
- if (has(rateLimit) || httpStatus('429')) {
163
+ // "You've hit your session limit · resets 5:40pm" is how Claude Code reports a subscription cap.
164
+ if (has(rateLimit) || httpStatus('429') || /hit your [\w ]{0,20}limit/i.test(stderr)) {
164
165
  return { type: 'rate_limit', message: `${this.getCapabilities().name} rate limit or quota: ${excerpt}` };
165
166
  }
166
167
  return { type: 'cli_error', message: excerpt || 'Unknown error' };
167
168
  }
168
169
  getSuggestion(error) {
169
170
  switch (error.type) {
170
- case 'rate_limit': return 'Wait a minute and retry; if it persists, check the plan limits for this CLI';
171
+ case 'rate_limit': return `Wait and retry (the message may name a reset time). If it persists, check the plan limits for this CLI or set ${this.id}.model to another model in ~/.config/quorum/config.json`;
171
172
  case 'auth_error': return this.authHint;
172
173
  case 'cli_not_found': return this.installHint;
173
174
  case 'timeout': return `Narrow the scope or raise ${this.id}.inactivityTimeoutMs in ~/.config/quorum/config.json`;
@@ -13,7 +13,6 @@ export declare class CodexAdapter extends CliAdapter {
13
13
  protected readonly binary = "codex";
14
14
  protected readonly installHint = "Install with: npm install -g @openai/codex-cli, then run `codex login`";
15
15
  protected readonly authHint = "Run `codex login` to authenticate";
16
- protected extraRateLimitPatterns: string[];
17
16
  getCapabilities(): ReviewerCapabilities;
18
17
  protected getLimits(ctx: RunContext): RunLimits;
19
18
  /** Request value > per-kind config default. */
@@ -17,7 +17,6 @@ export class CodexAdapter extends CliAdapter {
17
17
  binary = 'codex';
18
18
  installHint = 'Install with: npm install -g @openai/codex-cli, then run `codex login`';
19
19
  authHint = 'Run `codex login` to authenticate';
20
- extraRateLimitPatterns = ['usage limit', 'insufficient_quota'];
21
20
  getCapabilities() {
22
21
  return {
23
22
  name: 'Codex',
@@ -63,6 +62,12 @@ export class CodexAdapter extends CliAdapter {
63
62
  if (effectiveTier !== 'default') {
64
63
  args.push('-c', `service_tier=${effectiveTier}`);
65
64
  }
65
+ // A code review's evidence is the working tree; web fetches only add
66
+ // turns (38% of review runs made them). Consult keeps web for questions
67
+ // that depend on current library or service behaviour.
68
+ if (ctx.kind === 'review') {
69
+ args.push('-c', 'web_search="disabled"');
70
+ }
66
71
  const decoder = new CodexEventDecoder();
67
72
  const cliStartTime = Date.now();
68
73
  const tierLabel = effectiveTier !== 'default' ? ` [${effectiveTier}]` : '';
package/dist/config.d.ts CHANGED
@@ -7,7 +7,9 @@
7
7
  * - Lazy, cached load with mtime-based hot reload. `getConfig()` returns the
8
8
  * cached config or re-reads when the file changed on disk.
9
9
  * - Missing file → defaults in memory (no write). `initConfig()` (server
10
- * start-up) creates the file with defaults on first launch.
10
+ * start-up) creates an empty `{}` on first launch. It never writes the
11
+ * defaults: a default pinned on disk would shadow every later release's
12
+ * default for that user (a fixed default model would not reach them).
11
13
  * - Invalid JSON → defaults, warn on stderr. A schema violation resets only
12
14
  * the offending fields; the rest of that section and the others survive.
13
15
  * - Partial user configs are deep-merged against defaults via Zod `.default()`.
@@ -349,7 +351,7 @@ export declare const DEFAULT_CONFIG: Config;
349
351
  export declare function getConfigPath(): string;
350
352
  export declare function getConfig(): Config;
351
353
  /**
352
- * Create the config file with defaults if it does not exist. Uses the
354
+ * Create an empty config file if none exists. Uses the
353
355
  * exclusive `wx` flag for atomic creation — safe against TOCTOU races when
354
356
  * multiple server instances start concurrently. Refreshes the cache so
355
357
  * subsequent `getConfig()` calls see disk state.
package/dist/config.js CHANGED
@@ -7,7 +7,9 @@
7
7
  * - Lazy, cached load with mtime-based hot reload. `getConfig()` returns the
8
8
  * cached config or re-reads when the file changed on disk.
9
9
  * - Missing file → defaults in memory (no write). `initConfig()` (server
10
- * start-up) creates the file with defaults on first launch.
10
+ * start-up) creates an empty `{}` on first launch. It never writes the
11
+ * defaults: a default pinned on disk would shadow every later release's
12
+ * default for that user (a fixed default model would not reach them).
11
13
  * - Invalid JSON → defaults, warn on stderr. A schema violation resets only
12
14
  * the offending fields; the rest of that section and the others survive.
13
15
  * - Partial user configs are deep-merged against defaults via Zod `.default()`.
@@ -146,7 +148,7 @@ export function getConfig() {
146
148
  return _cached;
147
149
  }
148
150
  /**
149
- * Create the config file with defaults if it does not exist. Uses the
151
+ * Create an empty config file if none exists. Uses the
150
152
  * exclusive `wx` flag for atomic creation — safe against TOCTOU races when
151
153
  * multiple server instances start concurrently. Refreshes the cache so
152
154
  * subsequent `getConfig()` calls see disk state.
@@ -155,7 +157,7 @@ export function initConfig() {
155
157
  const path = _configPath;
156
158
  mkdirSync(dirname(path), { recursive: true });
157
159
  try {
158
- writeFileSync(path, JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n', { encoding: 'utf-8', flag: 'wx' });
160
+ writeFileSync(path, '{}\n', { encoding: 'utf-8', flag: 'wx' });
159
161
  _cached = DEFAULT_CONFIG;
160
162
  _cachedMtimeMs = statSync(path).mtimeMs;
161
163
  return { path, created: true };
@@ -30,7 +30,7 @@ export function buildConsultPrompt(request) {
30
30
  sections.push([
31
31
  'GROUND RULES — READ-ONLY:',
32
32
  '- Do not create, modify, or delete files.',
33
- '- Do not run git commands or anything else that changes state.',
33
+ '- Do not run anything that changes state: no git commit/checkout/stash/reset/push, no installs, no formatters.',
34
34
  '- Do not read files outside WORKING DIRECTORY.',
35
35
  ].join('\n'));
36
36
  sections.push(`WORKING DIRECTORY: ${workingDir}`);
@@ -66,7 +66,7 @@ export function buildConsultPrompt(request) {
66
66
  ' one and say what would flip you to the other.',
67
67
  '- Be concrete: name the specific technology, pattern, or code change.',
68
68
  ' Cite file:line when referencing code.',
69
- '- Aim for 300–700 words. Go longer only if the question needs it.',
69
+ '- Hard limit: 700 words in total.',
70
70
  ].join('\n'));
71
71
  sections.push([
72
72
  'Respond in this exact structure with these exact ## headers in this',
package/dist/handoff.d.ts CHANGED
@@ -104,13 +104,9 @@ export declare function buildAdversarialHandoffPrompt(options: PromptOptions): s
104
104
  /** Build the prompt for a ReviewRequest, selecting the pass from `reviewMode`. */
105
105
  export declare function buildReviewPrompt(request: ReviewRequest): string;
106
106
  /**
107
- * Parse CC's structured brief into Handoff fields.
108
- *
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 }`.
107
+ * Parse CC's structured brief into Handoff fields. A brief is in the colon
108
+ * form if it has a `SUMMARY:` line, else in the markdown form if it has a
109
+ * `## SUMMARY` heading, else unstructured: `{ summary: ccOutput }`.
114
110
  */
115
111
  export declare function parseStructuredCcOutput(ccOutput: string): Pick<Handoff, 'summary'> & Partial<Handoff>;
116
112
  /**
package/dist/handoff.js CHANGED
@@ -189,7 +189,7 @@ export const REQUIRED_REVIEW_SECTIONS = ['Verdict', 'Findings'];
189
189
  function renderTask(handoff) {
190
190
  const kind = TASK_BY_OUTPUT_TYPE[handoff.outputType ?? 'implementation'];
191
191
  const base = handoff.baseRef
192
- ? `\n\nThe working tree is clean; the change is \`git diff ${handoff.baseRef}...HEAD\` (\`--stat\` first, then the files).`
192
+ ? `\n\nThe change is committed: \`git diff ${handoff.baseRef}...HEAD\` (\`--stat\` first, then the files). Anything \`git status\` shows as uncommitted is part of it too.`
193
193
  : '';
194
194
  return `## WHAT YOU ARE REVIEWING
195
195
 
@@ -207,6 +207,9 @@ function renderGroundRules() {
207
207
  return `## GROUND RULES
208
208
 
209
209
  - Read-only. Do not create, modify, or delete files. Do not run anything that changes state: no git commit/checkout/stash/reset/push, no installs, no formatters, no test runs that write.
210
+ - Stay inside the working directory: do not read, list, or search paths outside it — no hunting parent or sibling directories for AGENTS.md or CLAUDE.md.
211
+ - No web access: do not fetch URLs or search the web. The code in the working directory is the evidence.
212
+ - Read what you need: search for the symbol first, then read the line range around it rather than a whole large file. Aim for about 12 tool calls; go beyond that only to confirm a finding that would change the verdict.
210
213
  - If the directory is a git repository, \`git status\`, \`git diff\`, \`git diff --cached\` and \`git log -3 --stat\` are the fastest way to find the change; when the brief names a base ref, \`git diff <base>...HEAD\` is the change. If it is not a repository, or the tree is clean and no base ref is given, work from PRIORITY FILES and the brief.
211
214
  - Verify before you report. Open the file, quote the line. A finding without a location and evidence is not a finding.
212
215
  - Stay in scope: the change and the code it touches. Report a pre-existing problem elsewhere only if the change activates it or the bar depends on it, and label it "pre-existing".
@@ -220,8 +223,8 @@ function renderUncertainties(handoff) {
220
223
  // When the topic is just the question minus its punctuation, one line is enough.
221
224
  const topicIsQuestion = u.question.startsWith(u.topic) && u.question.length - u.topic.length <= 1;
222
225
  const lines = topicIsQuestion
223
- ? [`### ${i + 1}. ${u.question}${tag}`]
224
- : [`### ${i + 1}. ${u.topic}${tag}`, `- Question: ${u.question}`];
226
+ ? [`### U${i + 1}. ${u.question}${tag}`]
227
+ : [`### U${i + 1}. ${u.topic}${tag}`, `- Question: ${u.question}`];
225
228
  if (u.ccAssumption)
226
229
  lines.push(`- The agent assumed: ${u.ccAssumption}`);
227
230
  if (u.relevantFiles && u.relevantFiles.length > 0)
@@ -238,7 +241,7 @@ function renderQuestions(handoff) {
238
241
  if (!handoff.questions || handoff.questions.length === 0)
239
242
  return null;
240
243
  const items = handoff.questions.map((q, i) => {
241
- const lines = [`${i + 1}. **${q.question}**`];
244
+ const lines = [`Q${i + 1}. **${q.question}**`];
242
245
  if (q.context)
243
246
  lines.push(` Context: ${q.context}`);
244
247
  if (q.ccGuess)
@@ -253,7 +256,7 @@ function renderDecisions(handoff, mode) {
253
256
  if (!handoff.decisions || handoff.decisions.length === 0)
254
257
  return null;
255
258
  const items = handoff.decisions.map((d, i) => {
256
- const lines = [`${i + 1}. **${d.decision}**`];
259
+ const lines = [`D${i + 1}. **${d.decision}**`];
257
260
  if (d.rationale)
258
261
  lines.push(` Rationale: ${d.rationale}`);
259
262
  if (d.alternatives && d.alternatives.length > 0)
@@ -304,27 +307,29 @@ function renderResponseFormat(mode) {
304
307
  : 'Judge against the acceptance bar.';
305
308
  return `## RESPONSE FORMAT
306
309
 
307
- Use exactly these \`##\` headers, in this order, and nothing before the first one.
310
+ Use exactly these \`##\` headers, in this order, and nothing before the first one. Hard limit: 900 words in total. Prefer one strong finding over several weak ones.
308
311
 
309
312
  ## Verdict
310
313
  One line: \`SHIP\`, \`SHIP WITH FIXES\`, or \`DO NOT SHIP\`, then one sentence of justification. ${verdictNote}
311
314
 
312
315
  ## Findings
313
- Ordered by severity, most severe first. Write \`None.\` if there are no material findings. For each:
314
- ### [S1|S2|S3] <short title>
316
+ Ordered by severity, most severe first. Write \`None.\` if there are no material findings. For each S1 or S2 finding:
317
+ ### [S1|S2] <short title>
315
318
  - Location: \`path:line\`
316
319
  - Evidence: what in the code shows it — quote the line or trace the path
317
320
  - Impact: what goes wrong, and under what conditions
318
321
  - Fix: the concrete change
319
322
  - Confidence: high | medium | low — say so if the finding rests on an inference you could not verify
320
323
 
324
+ After them, at most 5 S3 findings, one line each: \`- [S3] <short title> — path:line — <fix>\`.
325
+
321
326
  Severity: S1 = blocks the bar (data loss, security, wrong results, crash on a common path). S2 = real bug or gap; ship only after fixing. S3 = worth fixing, not blocking.
322
327
 
323
328
  ## Answers
324
- Numbered to match the agent's uncertainties, then its questions. Each: \`verified\` / \`refuted\` / \`could not verify\`, plus the evidence in one or two sentences. Write \`None asked.\` if the brief had neither.
329
+ One line per uncertainty and question in the brief, each starting with its id: \`- U1: verified — <evidence>\`. Use \`verified\` / \`refuted\` / \`could not verify\`, plus the evidence in one or two sentences. Write \`None asked.\` if the brief had neither.
325
330
 
326
331
  ## Decisions
327
- One line per decision in the brief: \`agree\`, or \`disagree — <better alternative and why>\`. Write \`None listed.\` if the brief listed none.`;
332
+ One line per decision in the brief, each starting with its id: \`- D1: agree\`, or \`- D1: disagree — <better alternative and why>\`. Write \`None listed.\` if the brief listed none.`;
328
333
  }
329
334
  function joinSections(sections) {
330
335
  return sections.filter((s) => typeof s === 'string' && s.length > 0).join('\n\n');
@@ -452,26 +457,20 @@ export function buildReviewPrompt(request) {
452
457
  // =============================================================================
453
458
  const KNOWN_HEADERS = ['SUMMARY', 'UNCERTAINTIES', 'QUESTIONS', 'DECISIONS', 'KNOWN GAPS', 'PRIORITY FILES'];
454
459
  /**
455
- * Parse CC's structured brief into Handoff fields.
456
- *
457
- * The slash command tells CC to format its output as ALL-CAPS section headers
458
- * (`SUMMARY:`, `UNCERTAINTIES (verify these):`, ...). Headers are matched
459
- * case-sensitively at the start of a line so prose such as "Questions: none"
460
- * inside a section cannot open a new one. Unstructured input falls back to
461
- * `{ summary: ccOutput }`.
460
+ * The slash command's form: `SUMMARY:`, `UNCERTAINTIES (verify these):`, ...
461
+ * Names are matched case-sensitively at the start of a line so prose such as
462
+ * "Questions: none" inside a section cannot open a new one. A markdown heading
463
+ * is ordinary text here, so a quoted `## SUMMARY` example stays where it is.
462
464
  */
463
- export function parseStructuredCcOutput(ccOutput) {
464
- if (!/^SUMMARY[^:\n]*:/m.test(ccOutput)) {
465
- return { summary: ccOutput };
466
- }
465
+ function splitColonBrief(ccOutput) {
467
466
  const headerPattern = new RegExp(`^(${KNOWN_HEADERS.join('|')})[^:\\n]*:[ \\t]*`, 'gm');
468
467
  const found = [];
469
468
  let match;
470
469
  while ((match = headerPattern.exec(ccOutput)) !== null) {
471
470
  found.push({ name: match[1], start: match.index, contentStart: match.index + match[0].length });
472
471
  }
473
- if (found.length === 0)
474
- return { summary: ccOutput };
472
+ if (!found.some((header) => header.name === 'SUMMARY'))
473
+ return null;
475
474
  const sections = new Map();
476
475
  for (let i = 0; i < found.length; i++) {
477
476
  const end = i + 1 < found.length ? found[i + 1].start : ccOutput.length;
@@ -480,33 +479,83 @@ export function parseStructuredCcOutput(ccOutput) {
480
479
  if (!sections.has(found[i].name))
481
480
  sections.set(found[i].name, body);
482
481
  }
482
+ return { sections, lead: [ccOutput.slice(0, found[0].start).trim()], extra: [] };
483
+ }
484
+ /**
485
+ * The markdown form a third of real briefs use: `## SUMMARY`,
486
+ * `## KNOWN GAPS (do not report again)`. Every heading outside a code fence
487
+ * ends the section above it. A heading that is not one of the six, or repeats
488
+ * one, is kept with the summary instead of being glued onto the last list item
489
+ * of the section above, so nothing the agent wrote is lost.
490
+ */
491
+ function splitMarkdownBrief(ccOutput) {
492
+ const fences = [...ccOutput.matchAll(/^```[\s\S]*?^```/gm)].map((m) => [m.index, m.index + m[0].length]);
493
+ const headings = [...ccOutput.matchAll(/^#{1,6}[ \t]+([^\n]*)$/gm)]
494
+ .filter((m) => !fences.some(([from, to]) => m.index > from && m.index < to));
495
+ const knownName = (text) => KNOWN_HEADERS.find((name) => new RegExp(`^${name}\\b`).test(text));
496
+ if (!headings.some((m) => knownName(m[1]) === 'SUMMARY'))
497
+ return null;
498
+ const sections = new Map();
499
+ const lead = [ccOutput.slice(0, headings[0].index).trim()];
500
+ const extra = [];
501
+ headings.forEach((heading, i) => {
502
+ const text = heading[1].trim();
503
+ const end = i + 1 < headings.length ? headings[i + 1].index : ccOutput.length;
504
+ const below = ccOutput.slice(heading.index + heading[0].length, end);
505
+ const name = knownName(text);
506
+ if (name && !sections.has(name)) {
507
+ // `## SUMMARY: did X` carries content on the heading line; `(…)` decoration is dropped.
508
+ const colon = text.indexOf(':');
509
+ sections.set(name, `${colon === -1 ? '' : text.slice(colon + 1)}\n${below}`.trim());
510
+ }
511
+ else {
512
+ (sections.has('SUMMARY') ? extra : lead).push(`${text}\n${below.trim()}`.trim());
513
+ }
514
+ });
515
+ return { sections, lead, extra };
516
+ }
517
+ /**
518
+ * Parse CC's structured brief into Handoff fields. A brief is in the colon
519
+ * form if it has a `SUMMARY:` line, else in the markdown form if it has a
520
+ * `## SUMMARY` heading, else unstructured: `{ summary: ccOutput }`.
521
+ */
522
+ export function parseStructuredCcOutput(ccOutput) {
523
+ const brief = splitColonBrief(ccOutput) ?? splitMarkdownBrief(ccOutput);
524
+ if (!brief)
525
+ return { summary: ccOutput };
526
+ const { sections } = brief;
483
527
  const result = { summary: ccOutput };
484
528
  const rawSummary = sections.get('SUMMARY');
485
529
  if (rawSummary && rawSummary.length > 0) {
486
530
  const { summary, bar } = splitBar(rawSummary);
487
- result.summary = summary.length > 0 ? summary : ccOutput;
531
+ result.summary = summary.length > 0 ? [...brief.lead, summary, ...brief.extra].filter(Boolean).join('\n\n') : ccOutput;
488
532
  if (bar)
489
533
  result.bar = bar;
490
534
  }
491
- const uncertainties = parseListItems(sections.get('UNCERTAINTIES') ?? '');
535
+ const uncertainties = parseListOrProse(sections.get('UNCERTAINTIES') ?? '');
492
536
  if (uncertainties.length > 0) {
493
537
  result.uncertainties = uncertainties.map((item) => {
494
538
  const { weight, text } = splitWeightTag(item);
495
539
  return { topic: extractTopic(text), question: text, weight };
496
540
  });
497
541
  }
498
- const questions = parseListItems(sections.get('QUESTIONS') ?? '');
542
+ const questions = parseListOrProse(sections.get('QUESTIONS') ?? '');
499
543
  if (questions.length > 0) {
500
544
  result.questions = questions.map((question) => ({ question }));
501
545
  }
502
- const decisions = parseListItems(sections.get('DECISIONS') ?? '');
546
+ const decisions = parseListOrProse(sections.get('DECISIONS') ?? '');
503
547
  if (decisions.length > 0) {
504
548
  result.decisions = decisions.map((item) => splitRationale(item));
505
549
  }
506
- const gaps = parseListItems(sections.get('KNOWN GAPS') ?? '');
550
+ const gaps = parseListOrProse(sections.get('KNOWN GAPS') ?? '');
507
551
  if (gaps.length > 0)
508
552
  result.knownGaps = gaps;
509
- const files = parseListItems(sections.get('PRIORITY FILES') ?? '').map(stripBackticks);
553
+ const fileSection = sections.get('PRIORITY FILES') ?? '';
554
+ const fileItems = parseListItems(fileSection);
555
+ const files = fileItems.length > 0
556
+ ? fileItems.flatMap(splitInlineFiles)
557
+ // No list at all: take what looks like a path from `a.ts, b.ts`, and nothing from a sentence.
558
+ : fileSection.split(/[,\n]/).map((part) => stripBackticks(part.trim())).filter((part) => part.length > 0 && !/\s/.test(part));
510
559
  if (files.length > 0)
511
560
  result.priorityFiles = files;
512
561
  return result;
@@ -545,6 +594,17 @@ function splitRationale(item) {
545
594
  function stripBackticks(s) {
546
595
  return s.replace(/^`+|`+$/g, '').trim();
547
596
  }
597
+ /**
598
+ * `src/a.ts, src/b.ts` in one list item is several files. An item whose
599
+ * pieces contain spaces is one annotated file (`src/a.ts — the parser, the
600
+ * tests`), and a single backtick-quoted path keeps its own commas.
601
+ */
602
+ function splitInlineFiles(item) {
603
+ if (/^`[^`]*`$/.test(item))
604
+ return [stripBackticks(item)];
605
+ const parts = item.replace(/,\s*$/, '').split(/,\s+/).map(stripBackticks);
606
+ return parts.length > 1 && parts.every((part) => part.length > 0 && !/\s/.test(part)) ? parts : [stripBackticks(item)];
607
+ }
548
608
  /**
549
609
  * Short topic from an item — the first clause, up to 60 chars. Clause
550
610
  * boundaries are punctuation followed by whitespace (or a trailing `?`/`.`),
@@ -580,6 +640,20 @@ function parseListItems(text) {
580
640
  items.push(current.trim());
581
641
  return items;
582
642
  }
643
+ /**
644
+ * A section with no list markers at all was written as prose: keep it, one
645
+ * item per paragraph, rather than drop what the agent wrote. A paragraph that
646
+ * only says there is nothing ("None known.", "Nothing material.") is no item.
647
+ */
648
+ function parseListOrProse(text) {
649
+ const items = parseListItems(text);
650
+ if (items.length > 0)
651
+ return items;
652
+ return text
653
+ .split(/\n\s*\n/)
654
+ .map((paragraph) => paragraph.replace(/\s*\n\s*/g, ' ').trim())
655
+ .filter((paragraph) => paragraph.length > 0 && !/^(none|nothing|n\/a)\b(?! of\b)/i.test(paragraph));
656
+ }
583
657
  // =============================================================================
584
658
  // HANDOFF FROM TOOL INPUTS
585
659
  // =============================================================================
@@ -8,9 +8,18 @@
8
8
  * silently trusted. Best-effort: outside a git repository there is nothing to
9
9
  * compare and the check is skipped.
10
10
  */
11
- /** `git status --porcelain` for `dir`, or null when it is not a git repository (or git is missing). */
12
- export declare function snapshotWorkingTree(dir: string): string | null;
13
- /** Paths whose status entry differs between two snapshots (added, modified, deleted, renamed). */
14
- export declare function changedPaths(before: string | null, after: string | null): string[];
11
+ /**
12
+ * One string per `git status --porcelain` entry, each followed by a tab and
13
+ * the file's size and mtime; null when `dir` is not a git repository (or git
14
+ * is missing). Ignored files and `.git/` are outside what git status lists,
15
+ * so a write there is not seen.
16
+ *
17
+ * The status code alone cannot show a second edit: a file under review is
18
+ * already ` M` (or `??`) before the panel starts and still is after a reviewer
19
+ * rewrites it, and those are the files a reviewer is most likely to touch.
20
+ */
21
+ export declare function snapshotWorkingTree(dir: string): string[] | null;
22
+ /** Paths whose status entry or content stamp differs between two snapshots (added, modified, deleted, renamed, edited again). */
23
+ export declare function changedPaths(before: string[] | null, after: string[] | null): string[];
15
24
  /** Tool-result warning for a working tree that changed while reviewers ran. */
16
25
  export declare function tamperWarning(paths: string[]): string;
package/dist/integrity.js CHANGED
@@ -9,32 +9,67 @@
9
9
  * compare and the check is skipped.
10
10
  */
11
11
  import { execFileSync } from 'child_process';
12
- /** `git status --porcelain` for `dir`, or null when it is not a git repository (or git is missing). */
12
+ import { lstatSync } from 'fs';
13
+ import { join } from 'path';
14
+ /**
15
+ * One string per `git status --porcelain` entry, each followed by a tab and
16
+ * the file's size and mtime; null when `dir` is not a git repository (or git
17
+ * is missing). Ignored files and `.git/` are outside what git status lists,
18
+ * so a write there is not seen.
19
+ *
20
+ * The status code alone cannot show a second edit: a file under review is
21
+ * already ` M` (or `??`) before the panel starts and still is after a reviewer
22
+ * rewrites it, and those are the files a reviewer is most likely to touch.
23
+ */
13
24
  export function snapshotWorkingTree(dir) {
14
25
  try {
15
- return execFileSync('git', ['-C', dir, 'status', '--porcelain', '--untracked-files=all'], {
16
- encoding: 'utf-8',
17
- timeout: 15_000,
18
- stdio: ['ignore', 'pipe', 'ignore'],
19
- });
26
+ const git = (args) => execFileSync('git', ['-C', dir, ...args], { encoding: 'utf-8', timeout: 15_000, stdio: ['ignore', 'pipe', 'ignore'] });
27
+ // Porcelain paths are relative to the repository root, not to `dir`.
28
+ const root = git(['rev-parse', '--show-toplevel']).trim();
29
+ const entries = git(['status', '--porcelain', '-z', '--untracked-files=all']).split('\0');
30
+ const lines = [];
31
+ for (let i = 0; i < entries.length; i++) {
32
+ const entry = entries[i];
33
+ if (entry.length < 4)
34
+ continue;
35
+ // A rename or copy is followed by its source path as an entry of its own.
36
+ if ('RC'.includes(entry[0]) || 'RC'.includes(entry[1]))
37
+ i++;
38
+ lines.push(`${entry}\t${fileStamp(join(root, entry.slice(3)))}`);
39
+ }
40
+ return lines;
20
41
  }
21
42
  catch {
22
43
  return null;
23
44
  }
24
45
  }
25
- /** Paths whose status entry differs between two snapshots (added, modified, deleted, renamed). */
46
+ // ponytail: size+mtime, not a content hash. A rewrite with identical bytes is
47
+ // reported, and a same-size write that restores the old mtime (`touch -r`,
48
+ // `cp -p`) is missed. Hash the file here if either matters.
49
+ function fileStamp(path) {
50
+ try {
51
+ // lstat: a symlink's own size and mtime change when it is retargeted.
52
+ const stat = lstatSync(path);
53
+ return `${stat.size}:${stat.mtimeMs}`;
54
+ }
55
+ catch {
56
+ return 'gone';
57
+ }
58
+ }
59
+ /** Paths whose status entry or content stamp differs between two snapshots (added, modified, deleted, renamed, edited again). */
26
60
  export function changedPaths(before, after) {
27
61
  if (before === null || after === null)
28
62
  return [];
29
- const a = new Set(before.split('\n').filter(Boolean));
30
- const b = new Set(after.split('\n').filter(Boolean));
63
+ const a = new Set(before);
64
+ const b = new Set(after);
65
+ const path = (line) => line.slice(3, line.lastIndexOf('\t'));
31
66
  const changed = new Set();
32
67
  for (const line of a)
33
68
  if (!b.has(line))
34
- changed.add(line.slice(3));
69
+ changed.add(path(line));
35
70
  for (const line of b)
36
71
  if (!a.has(line))
37
- changed.add(line.slice(3));
72
+ changed.add(path(line));
38
73
  return [...changed].sort();
39
74
  }
40
75
  /** Tool-result warning for a working tree that changed while reviewers ran. */
@@ -8,8 +8,12 @@
8
8
  * delimiters.
9
9
  */
10
10
  import { ReviewFailure, ReviewResult } from '../adapters/base.js';
11
- /** Per-model output cap so one runaway reviewer cannot crowd out the others. */
12
- export declare const MAX_OUTPUT_CHARS = 60000;
11
+ /**
12
+ * Per-model output cap so one runaway reviewer cannot crowd out the others.
13
+ * The prompts cap a review at 900 words and a consult answer at 700 (~6K
14
+ * chars), so this only bites when a model ignores its length limit.
15
+ */
16
+ export declare const MAX_OUTPUT_CHARS = 20000;
13
17
  export declare const NO_CLIS_TEXT: string;
14
18
  export interface ToolText {
15
19
  [key: string]: unknown;
@@ -7,8 +7,12 @@
7
7
  * because the raw output is free markdown and cannot be relied on for
8
8
  * delimiters.
9
9
  */
10
- /** Per-model output cap so one runaway reviewer cannot crowd out the others. */
11
- export const MAX_OUTPUT_CHARS = 60_000;
10
+ /**
11
+ * Per-model output cap so one runaway reviewer cannot crowd out the others.
12
+ * The prompts cap a review at 900 words and a consult answer at 700 (~6K
13
+ * chars), so this only bites when a model ignores its length limit.
14
+ */
15
+ export const MAX_OUTPUT_CHARS = 20_000;
12
16
  const ERROR_EMOJI = {
13
17
  cli_not_found: '❌',
14
18
  timeout: '⏱️',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@simonren/quorum",
3
- "version": "0.12.2",
3
+ "version": "0.14.0",
4
4
  "description": "MCP server for Claude Code — a quorum of AI models (Codex, Gemini, Claude Fable with fresh context) for standard + adversarial review and consultation, synthesized by Claude Code",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",