cc-reviewer 6.0.0 → 6.2.0

package/commands/multi-consult.md

@@ -34,6 +34,35 @@ If the question references the codebase, populate `relevantFiles` with the minim
 
 If the current working directory is `/etc`, `~`, `~/.ssh`, or any other clearly sensitive system path, **refuse**. Tell the user: "Please invoke `/multi-consult` from a project root — `<cwd>` looks sensitive." Do not call the tool.
 
+### 4. Extract criteria; clarify load-bearing assumptions BEFORE calling
+
+Pin what the question is being judged against. Once criteria are explicit, the panel's recommendation is anchored to them instead of floating — this is the fix for "ask twice, get a different answer." Stochastic re-runs converge much better against fixed criteria than against an under-specified question.
+
+**4a. Append a CRITERIA block to the end of `question`**, priority-ordered, each tagged `[stated]` or `[assumed]`:
+
+```
+CRITERIA (priority order):
+1. [stated] cost-per-request under $X / 1M ops
+2. [stated] team writes Go; minimize ops complexity
+3. [assumed] sustained ~10k QPS write rate
+4. [assumed] eventual consistency acceptable for analytics
+```
+
+- `[stated]` = explicit in the user's message or earlier conversation.
+- `[assumed]` = you needed to fix it to recommend; the user did NOT say.
+- Cap `[assumed]` at 3. If the top 3 don't fit, the question is too vague — bounce back to the user before calling.
+
+**4b. Pre-call clarification gate.** Scan your `[assumed]` criteria. If any is **load-bearing** (the recommendation would flip if the assumption is wrong), STOP and ask the user before invoking the tool:
+
+> "Before I consult the panel, I need to confirm: <restate assumption>. Is that right, or should I adjust to <plausible alternative>?"
+
+A burned panel call on a wrong assumed criterion costs more than the round-trip.
+
+**Skip the gate when:**
+- `[stated]` criteria fully pin the answer space (no assumptions needed).
+- The user told you to proceed without clarification.
+- Remaining assumptions are clearly incidental (would not flip the rec).
+
 ## Tool Invocation
 
 Call `multi_consult` with:

package/commands/multi-review.md

@@ -23,17 +23,27 @@ Use `/multi-review` when you want thorough parallel reviews from all available m
 
 ## Before Calling - PREPARE THE HANDOFF
 
-### 1. Summarize What You Did (Brief!)
+### 1. Summarize What You Did + State the Acceptance Bar
+
+Don't just say what you did — also state the bar the work needs to clear. The bar is what lets reviewers calibrate "material" vs "nice to have." Without it, reviewers default to general code-quality vibes, which produces drift across runs.
+
 ```
-"Implemented caching layer for the product catalog API using Redis.
-Added cache invalidation on product updates."
+"Implemented caching layer for the product catalog API using Redis with cache invalidation on product updates.
+Bar: safe under concurrent updates (no stale reads on the next request) AND p95 read latency under 50ms."
 ```
 
-### 2. List Your Uncertainties
+### 2. List Your Uncertainties — Tag Load-Bearing vs Incidental
+
+Tag each uncertainty:
+- `[load-bearing]` = if your assumption here is wrong, the work is NOT shipping-ready
+- `[incidental]` = nice to verify but won't block ship
+
+Reviewers prioritize accordingly, and your synthesis can elevate `[load-bearing]` items above stylistic findings.
+
 ```
 UNCERTAINTIES:
-- "Is the cache TTL appropriate for this data?"
-- "Does the invalidation handle all update scenarios?"
+- [load-bearing] "Is the cache invalidation race-free under concurrent updates?"
+- [incidental] "Is the TTL value optimal — could it be 60s instead of 30s?"
 ```
 
 ### 3. Ask Specific Questions
@@ -43,6 +53,16 @@ QUESTIONS:
 - "Is there a race condition in the invalidation logic?"
 ```
 
+### 4. Identify Decisions You Made
+
+If you chose between alternatives — caching strategy, retry policy, error-handling shape, schema design, etc. — list them with rationale. The handoff schema's `decisions[]` field gives the adversarial reviewer a concrete hook to attack the design choice rather than just hunt for bugs. Skip if the change is a straightforward bug fix with no design choice involved.
+
+```
+DECISIONS:
+1. Chose write-through cache over write-behind. Rationale: stronger read-after-write consistency at the cost of slightly slower writes; we prioritize correctness for catalog data.
+2. Chose 30s TTL with explicit invalidation on update. Rationale: TTL bounds staleness if invalidation misses; explicit invalidation catches the common path immediately.
+```
+
 ## Tool Invocation
 
 Call `multi_review` with:
@@ -67,14 +87,19 @@ Call `multi_review` with:
 ```
 SUMMARY:
 <what you did, 1-3 sentences>
+Bar: <what counts as shipping-ready — concrete acceptance criteria>
 
 UNCERTAINTIES (verify these):
-1. <uncertainty>
-2. <uncertainty>
+1. [load-bearing|incidental] <uncertainty>
+2. [load-bearing|incidental] <uncertainty>
 
 QUESTIONS:
 1. <question>
 
+DECISIONS:
+1. <choice>. Rationale: <why this over alternatives>
+2. <choice>. Rationale: <why this over alternatives>
+
 PRIORITY FILES:
 - <file>
 ```

package/dist/handoff.d.ts

@@ -218,8 +218,13 @@ export declare function selectRole(focusAreas?: FocusArea[]): ReviewerRole;
 export declare const ADVERSARIAL_REVIEWER: ReviewerRole;
 /**
  * Build an adversarial handoff prompt with challenge-mode stance sections.
- * Same structure as buildHandoffPrompt but adds adversarial XML sections
- * and uses the ADVERSARIAL_REVIEWER role.
+ *
+ * Block structure ported from openai/codex-plugin-cc's adversarial-review
+ * prompt: tagged XML blocks (operating_stance, attack_surface, review_method,
+ * finding_bar, calibration_rules, grounding_rules, final_check) so the prompt
+ * has stable internal structure the reviewer can lean on. CC's handoff
+ * sections (uncertainties / decisions / questions / focus / files / focus
+ * instructions) are layered on after as our differentiator.
  */
 export declare function buildAdversarialHandoffPrompt(options: PromptOptions): string;
 export interface PromptOptions {

package/dist/handoff.js

@@ -186,8 +186,13 @@ export const ADVERSARIAL_REVIEWER = {
 };
 /**
  * Build an adversarial handoff prompt with challenge-mode stance sections.
- * Same structure as buildHandoffPrompt but adds adversarial XML sections
- * and uses the ADVERSARIAL_REVIEWER role.
+ *
+ * Block structure ported from openai/codex-plugin-cc's adversarial-review
+ * prompt: tagged XML blocks (operating_stance, attack_surface, review_method,
+ * finding_bar, calibration_rules, grounding_rules, final_check) so the prompt
+ * has stable internal structure the reviewer can lean on. CC's handoff
+ * sections (uncertainties / decisions / questions / focus / files / focus
+ * instructions) are layered on after as our differentiator.
  */
 export function buildAdversarialHandoffPrompt(options) {
     const { handoff } = options;
@@ -195,34 +200,36 @@ export function buildAdversarialHandoffPrompt(options) {
     const sections = [];
     // SECTION 1: ROLE
     sections.push(`# ROLE: ${role.name}\n\n${role.systemPrompt}`);
-    // SECTION 2: ADVERSARIAL STANCE
-    sections.push(`## ADVERSARIAL STANCE
-
-<operating_stance>
-Default to skepticism. Assume the change can fail in subtle, high-cost,
-or user-visible ways until the evidence says otherwise. Do not give credit
-for good intent, partial fixes, or likely follow-up work.
+    // SECTION 2: ADVERSARIAL STANCE — tagged blocks form the operating contract
+    sections.push(`<operating_stance>
+Default to skepticism.
+Assume the change can fail in subtle, high-cost, or user-visible ways until the evidence says otherwise.
+Do not give credit for good intent, partial fixes, or likely follow-up work.
+If something only works on the happy path, treat that as a real weakness.
 </operating_stance>
 
 <attack_surface>
-Prioritized failure categories:
-1. Auth/permissions bypass
-2. Data loss or corruption
-3. Rollback safety
-4. Race conditions / concurrency
-5. Empty-state / null / timeout handling
-6. Version skew / backwards compatibility
-7. Observability gaps (missing logs, metrics, alerts)
+Prioritize the kinds of failures that are expensive, dangerous, or hard to detect:
+- auth, permissions, tenant isolation, and trust boundaries
+- data loss, corruption, duplication, and irreversible state changes
+- rollback safety, retries, partial failure, and idempotency gaps
+- race conditions, ordering assumptions, stale state, and re-entrancy
+- empty-state, null, timeout, and degraded dependency behavior
+- version skew, schema drift, migration hazards, and compatibility regressions
+- observability gaps that would hide failure or make recovery harder
 </attack_surface>
 
 <review_method>
-Actively try to disprove the change. Look for violated invariants,
-missing guards, unhandled failure paths. If the user supplied a focus area,
-weight it heavily, but still report any other material issue you can defend.
+Actively try to disprove the change.
+Look for violated invariants, missing guards, unhandled failure paths, and assumptions that stop being true under stress.
+Trace how bad inputs, retries, concurrent actions, or partially completed operations move through the code.
+If the user supplied a focus area, weight it heavily, but still report any other material issue you can defend.
 </review_method>
 
 <finding_bar>
-Material findings only. Each must answer:
+Report only material findings.
+Do not include style feedback, naming feedback, low-value cleanup, or speculative concerns without evidence.
+Each finding must answer:
 1. What can go wrong?
 2. Why is this code path vulnerable?
 3. What is the likely impact?
@@ -230,15 +237,25 @@ Material findings only. Each must answer:
 </finding_bar>
 
 <calibration_rules>
-Prefer one strong finding over several weak ones. If you cannot defend
-a finding from the provided code, drop it.
+Prefer one strong finding over several weak ones.
+Do not dilute serious issues with filler.
+If the change looks safe, say so directly and return no findings.
 </calibration_rules>
 
 <grounding_rules>
-Be aggressive, but stay grounded. Every finding must be defensible from
-the repository context. No speculative findings. No "might be an issue"
-without concrete evidence from the code.
-</grounding_rules>`);
+Be aggressive, but stay grounded.
+Every finding must be defensible from the repository context or tool outputs.
+Do not invent files, lines, code paths, incidents, attack chains, or runtime behavior you cannot support.
+If a conclusion depends on an inference, state that explicitly in the finding body and keep the confidence honest.
+</grounding_rules>
+
+<final_check>
+Before finalizing, check that each finding is:
+- adversarial rather than stylistic
+- tied to a concrete code location
+- plausible under a real failure scenario
+- actionable for an engineer fixing the issue
+</final_check>`);
     // SECTION 3: TASK (same as standard)
     sections.push(`## YOUR TASK
 

package/dist/schema.d.ts

@@ -11,6 +11,15 @@ export declare const ConfidenceLevel: z.ZodEnum<["verified", "high", "medium", "
 export type ConfidenceLevel = z.infer<typeof ConfidenceLevel>;
 export declare const ConfidenceScore: z.ZodNumber;
 export type ConfidenceScore = z.infer<typeof ConfidenceScore>;
+/**
+ * Sentinel used when a reviewer omits `confidence` on a finding, agreement,
+ * or disagreement. Confidence is required by the Zod schema, but external
+ * CLIs occasionally drop the field — rather than reject the whole review,
+ * normalization fills it with this midpoint value. 0.5 reads as "the
+ * reviewer did not commit to a confidence" without skewing the result
+ * toward "confidently right" or "confidently wrong".
+ */
+export declare const DEFAULT_FINDING_CONFIDENCE = 0.5;
 export declare const CodeLocation: z.ZodObject<{
     file: z.ZodString;
     line_start: z.ZodOptional<z.ZodNumber>;

package/dist/schema.js

@@ -12,6 +12,15 @@ export const SeverityLevel = z.enum(['critical', 'high', 'medium', 'low', 'info'
 export const ConfidenceLevel = z.enum(['verified', 'high', 'medium', 'low', 'uncertain']);
 // Numeric confidence score (0-1)
 export const ConfidenceScore = z.number().min(0).max(1);
+/**
+ * Sentinel used when a reviewer omits `confidence` on a finding, agreement,
+ * or disagreement. Confidence is required by the Zod schema, but external
+ * CLIs occasionally drop the field — rather than reject the whole review,
+ * normalization fills it with this midpoint value. 0.5 reads as "the
+ * reviewer did not commit to a confidence" without skewing the result
+ * toward "confidently right" or "confidently wrong".
+ */
+export const DEFAULT_FINDING_CONFIDENCE = 0.5;
 // =============================================================================
 // CODE LOCATION
 // =============================================================================
@@ -40,7 +49,7 @@ export const ReviewFinding = z.object({
         'other'
     ]).describe('Primary category of the finding'),
     severity: SeverityLevel.describe('Impact severity level'),
-    confidence: ConfidenceScore.describe('Confidence in this finding (0-1)'),
+    confidence: ConfidenceScore.describe('Confidence in this finding (0-1). Required. If the reviewer omits this field, normalizeReviewOutput fills it with DEFAULT_FINDING_CONFIDENCE (0.5) so the whole review is not dropped.'),
     title: z.string().max(120).describe('Brief title summarizing the issue'),
     description: z.string().describe('Detailed explanation of the finding'),
     location: CodeLocation.optional().describe('Where in the code this applies'),
@@ -269,10 +278,28 @@ export function getReviewOutputJsonSchema() {
         }
     };
 }
+/**
+ * Fill `confidence` with the sentinel when an object-shaped item omits it.
+ * Leaves non-object items alone so downstream Zod validation still surfaces
+ * a useful error for genuinely malformed entries.
+ */
+function fillMissingConfidence(item) {
+    if (!item || typeof item !== 'object' || Array.isArray(item))
+        return item;
+    const obj = item;
+    if (typeof obj.confidence === 'number')
+        return obj;
+    return { ...obj, confidence: DEFAULT_FINDING_CONFIDENCE };
+}
 /**
  * Normalize reviewer output that deviates from the strict schema.
  * Handles common patterns from external CLIs (e.g. Gemini returning
  * agreements as strings instead of objects, missing required fields).
+ *
+ * Notably: `confidence` is required on findings/agreements/disagreements,
+ * but reviewers occasionally drop it. Rather than reject the whole review,
+ * we fill the missing field with DEFAULT_FINDING_CONFIDENCE so the rest of
+ * the review survives validation.
  */
 function normalizeReviewOutput(parsed) {
     const normalized = { ...parsed };
@@ -280,13 +307,13 @@ function normalizeReviewOutput(parsed) {
     if (!normalized.reviewer) {
         normalized.reviewer = 'external';
     }
-    // Normalize agreements: string[] -> Agreement[]
+    // Normalize agreements: string[] -> Agreement[], then fill missing confidence
     if (Array.isArray(normalized.agreements)) {
         normalized.agreements = normalized.agreements.map((a) => {
             if (typeof a === 'string') {
-                return { original_claim: a, assessment: 'correct', confidence: 0.7 };
+                return { original_claim: a, assessment: 'correct', confidence: DEFAULT_FINDING_CONFIDENCE };
             }
-            return a;
+            return fillMissingConfidence(a);
         });
     }
     else {
@@ -296,6 +323,14 @@ function normalizeReviewOutput(parsed) {
     normalized.disagreements = normalized.disagreements ?? [];
     normalized.alternatives = normalized.alternatives ?? [];
     normalized.findings = normalized.findings ?? [];
+    // Fill missing confidence on findings and disagreements (Zod requires it;
+    // dropping the whole review for one missing scalar is worse than a sentinel)
+    if (Array.isArray(normalized.findings)) {
+        normalized.findings = normalized.findings.map(fillMissingConfidence);
+    }
+    if (Array.isArray(normalized.disagreements)) {
+        normalized.disagreements = normalized.disagreements.map(fillMissingConfidence);
+    }
     // Normalize optional response arrays — drop non-array values
     if (normalized.uncertainty_responses !== undefined && !Array.isArray(normalized.uncertainty_responses)) {
         delete normalized.uncertainty_responses;
@@ -435,7 +470,7 @@ export function parseLegacyMarkdownOutput(markdown, reviewer) {
                     output.agreements.push({
                         original_claim: content.split(':')[0] || content,
                         assessment: 'correct',
-                        confidence: 0.7,
+                        confidence: DEFAULT_FINDING_CONFIDENCE,
                     });
                 }
             }
@@ -450,7 +485,7 @@ export function parseLegacyMarkdownOutput(markdown, reviewer) {
                     output.disagreements.push({
                         original_claim: content.split(':')[0] || content,
                         issue: 'incorrect',
-                        confidence: 0.7,
+                        confidence: DEFAULT_FINDING_CONFIDENCE,
                         reason: content,
                     });
                 }
@@ -469,7 +504,7 @@ export function parseLegacyMarkdownOutput(markdown, reviewer) {
                         id: `legacy-${idx++}`,
                         category: 'other',
                         severity: 'medium',
-                        confidence: 0.6,
+                        confidence: DEFAULT_FINDING_CONFIDENCE,
                         title: content.slice(0, 100),
                         description: content,
                         location: locationMatch ? {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-reviewer",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "MCP server for Claude Code - Get second-opinion feedback from Codex/Gemini CLIs",
   "type": "module",
   "main": "dist/index.js",