From 84c180ab660dc36d41dc545b0e5ef347b8301845 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Wed, 26 Nov 2025 09:37:14 +0800 Subject: [PATCH] refactor: Simplify and streamline agent documentation and output schemas for clarity and consistency --- .claude/commands/workflow/review-fix.md | 48 --- .../commands/workflow/review-module-cycle.md | 81 +--- .../commands/workflow/review-session-cycle.md | 89 +---- .../review-deep-dive-results-schema.json | 355 ++++-------------- .../review-dimension-results-schema.json | 322 +++------------- 5 files changed, 139 insertions(+), 756 deletions(-) diff --git a/.claude/commands/workflow/review-fix.md b/.claude/commands/workflow/review-fix.md index 94878d48..77296bf1 100644 --- a/.claude/commands/workflow/review-fix.md +++ b/.claude/commands/workflow/review-fix.md @@ -224,55 +224,7 @@ if (result.passRate < 100%) { - TodoWrite completion: Mark all phases done - Output summary to user with dashboard link -### Planning Agent (@cli-planning-agent) -**Role**: Analyze findings, create execution strategy, initialize progress tracking - -**Orchestrator Provides**: -- Review findings data (id, title, severity, file, description, recommendations) -- Project context (structure, test framework, git status) -- Output directory and template paths - -**Agent Outputs**: -- fix-plan.json (groups, timeline, execution strategy) -- fix-progress-{N}.json (one per group, initial state) - -### Execution Agent (@cli-execute-agent) - -**Role**: Execute fixes for assigned group, update progress in real-time - -**Orchestrator Provides**: -- Group assignment (from fix-plan.json) -- Fix strategy and risk assessment (from fix-plan.json) -- Progress file path (fix-progress-{N}.json) - -**Agent Responsibilities**: -- Read/update assigned progress file -- Apply fixes with flow control tracking -- Run tests and verify -- Commit successful fixes to git - -## Reference - -### CLI Tool Configuration - -**Planning Agent**: -```javascript -{ - subagent_type: "cli-planning-agent", - timeout: 300000, // 5 minutes for planning - description: "Generate fix plan for N code review findings" -} -``` - -**Execution Agent**: -```javascript -{ - subagent_type: "cli-execute-agent", - timeout: 3600000, // 60 minutes per group (adjustable) - description: "Fix M issues: {group_name}" -} -``` ### Output File Structure diff --git a/.claude/commands/workflow/review-module-cycle.md b/.claude/commands/workflow/review-module-cycle.md index 6b7c2e8c..e3d5eb32 100644 --- a/.claude/commands/workflow/review-module-cycle.md +++ b/.claude/commands/workflow/review-module-cycle.md @@ -263,73 +263,7 @@ echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html" - TodoWrite completion: Mark all tasks done - Output: Dashboard path and REVIEW-SUMMARY.md path to user -### Review Agent (@cli-explore-agent) -**Analysis Mode**: Deep Scan (Phase 1: Bash structural + Phase 2: Gemini semantic + Phase 3: Synthesis) - -**Context Provided by Orchestrator**: -```javascript -{ - dimension: "security|architecture|quality|...", - review_type: "module", - target_files: ["src/auth/service.ts", "src/auth/validator.ts", ...], - output_paths: { - json: "{output-dir}/dimensions/{dimension}.json", - report: "{output-dir}/reports/{dimension}-analysis.md", - cli_output: "{output-dir}/reports/{dimension}-cli-output.txt" - }, - cli_config: { - tool: "gemini", - template: "~/.claude/workflows/cli-templates/prompts/analysis/xxx.txt", - timeout: 3600000, - mode: "analysis" - } -} -``` - -**Deliverables**: -1. Dimension JSON with findings array (see JSON Schema below) -2. Analysis markdown report with summary and recommendations -3. CLI output log for debugging - -### Deep-Dive Agent (@cli-explore-agent) - -**Analysis Mode**: Dependency Map + Deep Scan (for root cause analysis with architectural context) - -**Context Provided**: -```javascript -{ - finding_id: "uuid", - original_finding: {...}, - iteration: 1, - output_paths: { - json: "{output-dir}/iterations/iteration-1-finding-{uuid}.json", - report: "{output-dir}/reports/deep-dive-1-{uuid}.md" - }, - cli_config: { - tool: "gemini", - template: "01-diagnose-bug-root-cause.txt", - timeout: 2400000 - } -} -``` - -**Deliverables**: -1. Deep-dive JSON with root cause, remediation plan, impact assessment -2. Analysis report with detailed recommendations - -## Reference - -### CLI Tool Configuration - -**Fallback Chain**: Gemini → Qwen → Codex (same as test-cycle-execute) - -**Tool Details**: -1. **Gemini** (primary): `gemini-2.5-pro` - 60min timeout -2. **Qwen** (fallback): `coder-model` - 60min timeout -3. **Codex** (fallback): `gpt-5.1-codex` - 60min timeout - -**When to Fallback**: HTTP 429, timeout, invalid JSON output, confidence < 0.4 ### Output File Structure @@ -494,15 +428,17 @@ Task( ## CLI Configuration - Tool Priority: gemini → qwen → codex (fallback chain) - - Template: ~/.claude/workflows/cli-templates/prompts/analysis/${dimensionTemplate} - Custom Focus: ${customFocus || 'Standard dimension analysis'} - - Timeout: ${timeout}ms - Mode: analysis (READ-ONLY) - Context Pattern: ${targetFiles.map(f => `@${f}`).join(' ')} ## Expected Deliverables + **MANDATORY**: Before generating any JSON output, read the template example first: + - Read: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json + - Follow the exact structure and field naming from the example + 1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json - - MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json + - MUST follow example template: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json - MUST include: findings array with severity, file, line, description, recommendation - MUST include: summary statistics (total findings, severity distribution) - MUST include: cross_references to related findings @@ -568,12 +504,15 @@ Task( ## CLI Configuration - Tool Priority: gemini → qwen → codex - Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt - - Timeout: 2400000ms (40 minutes) - Mode: analysis (READ-ONLY) ## Expected Deliverables + **MANDATORY**: Before generating any JSON output, read the template example first: + - Read: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json + - Follow the exact structure and field naming from the example + 1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json - - MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json + - MUST follow example template: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json - MUST include: root_cause with summary, details, affected_scope, similar_patterns - MUST include: remediation_plan with approach, steps[], estimated_effort, risk_level - MUST include: impact_assessment with files_affected, tests_required, breaking_changes diff --git a/.claude/commands/workflow/review-session-cycle.md b/.claude/commands/workflow/review-session-cycle.md index 46467858..85f973da 100644 --- a/.claude/commands/workflow/review-session-cycle.md +++ b/.claude/commands/workflow/review-session-cycle.md @@ -249,84 +249,7 @@ echo "📊 Dashboard: file://${absolutePath}/.review/dashboard.html" - TodoWrite completion: Mark all tasks done - Output: Dashboard path and REVIEW-SUMMARY.md path to user -### Review Agent (@cli-explore-agent) -**Analysis Mode**: Deep Scan (Phase 1: Bash structural + Phase 2: Gemini semantic + Phase 3: Synthesis) - -**Context Provided by Orchestrator**: -```javascript -{ - dimension: "security|architecture|quality|...", - session_id: "WFS-xxx", - session_metadata_path: ".workflow/active/WFS-xxx/workflow-session.json", - summaries_dir: ".workflow/active/WFS-xxx/.summaries/", - output_paths: { - json: ".review-cycle/dimensions/{dimension}.json", - report: ".review-cycle/reports/{dimension}-analysis.md", - cli_output: ".review-cycle/reports/{dimension}-cli-output.txt" - }, - cli_config: { - tool: "gemini", - template: "~/.claude/workflows/cli-templates/prompts/analysis/xxx.txt", - timeout: 3600000, - mode: "analysis" - } -} -``` - -**Deliverables**: -1. Dimension JSON with findings array (see JSON Schema below) -2. Analysis markdown report with summary and recommendations -3. CLI output log for debugging - -### Deep-Dive Agent (@cli-explore-agent) - -**Analysis Mode**: Dependency Map + Deep Scan (for root cause analysis with architectural context) - -**Context Provided**: -```javascript -{ - finding_id: "uuid", - original_finding: {...}, - iteration: 1, - output_paths: { - json: ".review-cycle/iterations/iteration-1-finding-{uuid}.json", - report: ".review-cycle/reports/deep-dive-1-{uuid}.md" - }, - cli_config: { - tool: "gemini", - template: "01-diagnose-bug-root-cause.txt", - timeout: 2400000 - } -} -``` - -**Deliverables**: -1. Deep-dive JSON with root cause, remediation plan, impact assessment -2. Analysis report with detailed recommendations - - -### Features Summary - -- **Real-time Progress**: Phase indicator, progress bar, agent status (auto-refresh 5s) -- **Interactive Findings**: Severity/dimension filtering, search, sort, detail drawer -- **Export**: Generate markdown report -- **Dark Mode**: Toggle with localStorage persistence - -**Usage Details**: See `~/.claude/workflows/DASHBOARD-QUICKSTART.md` - -## Reference - -### CLI Tool Configuration - -**Fallback Chain**: Gemini → Qwen → Codex (same as test-cycle-execute) - -**Tool Details**: -1. **Gemini** (primary): `gemini-2.5-pro` - 60min timeout -2. **Qwen** (fallback): `coder-model` - 60min timeout -3. **Codex** (fallback): `gpt-5.1-codex` - 60min timeout - -**When to Fallback**: HTTP 429, timeout, invalid JSON output, confidence < 0.4 ### Session File Structure @@ -520,8 +443,12 @@ Task( - Mode: analysis (READ-ONLY) ## Expected Deliverables + **MANDATORY**: Before generating any JSON output, read the template example first: + - Read: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json + - Follow the exact structure and field naming from the example + 1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json - - MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json + - MUST follow example template: ~/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json - MUST include: findings array with severity, file, line, description, recommendation - MUST include: summary statistics (total findings, severity distribution) - MUST include: cross_references to related findings @@ -591,8 +518,12 @@ Task( - Mode: analysis (READ-ONLY) ## Expected Deliverables + **MANDATORY**: Before generating any JSON output, read the template example first: + - Read: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json + - Follow the exact structure and field naming from the example + 1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json - - MUST follow schema: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json + - MUST follow example template: ~/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json - MUST include: root_cause with summary, details, affected_scope, similar_patterns - MUST include: remediation_plan with approach, steps[], estimated_effort, risk_level - MUST include: impact_assessment with files_affected, tests_required, breaking_changes diff --git a/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json b/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json index 8ddd69cb..4d7e8792 100644 --- a/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json +++ b/.claude/workflows/cli-templates/schemas/review-deep-dive-results-schema.json @@ -1,291 +1,82 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "Review Deep-Dive Results Schema", - "description": "Output schema for cli-explore-agent deep-dive iteration analysis. Contains root cause analysis, remediation plan, and impact assessment for critical findings.", - "type": "object", - "required": [ - "finding_id", - "original_dimension", - "iteration", - "analysis_timestamp", - "cli_tool_used", - "root_cause", - "remediation_plan", - "impact_assessment", - "reassessed_severity", - "confidence_score", - "status" - ], - "properties": { - "finding_id": { - "type": "string", - "description": "Original finding ID from dimension analysis", - "example": "sec-001-a1b2c3d4" - }, - "original_dimension": { - "type": "string", - "enum": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"], - "description": "Dimension where finding was originally discovered" - }, - "iteration": { - "type": "integer", - "minimum": 1, - "description": "Deep-dive iteration number" - }, - "analysis_timestamp": { - "type": "string", - "format": "date-time", - "description": "ISO8601 timestamp when deep-dive completed" - }, - "cli_tool_used": { - "type": "string", - "enum": ["gemini", "qwen", "codex"], - "description": "CLI tool used for deep-dive analysis" - }, +[ + { + "finding_id": "sec-001-a1b2c3d4", + "original_dimension": "security", + "iteration": 1, + "analysis_timestamp": "2025-01-25T14:40:15Z", + "cli_tool_used": "gemini", "root_cause": { - "type": "object", - "required": ["summary", "details", "affected_scope"], - "properties": { - "summary": { - "type": "string", - "description": "One-sentence root cause summary" - }, - "details": { - "type": "string", - "description": "Detailed explanation with history and context" - }, - "affected_scope": { - "type": "string", - "description": "Full scope of affected code" - }, - "similar_patterns": { - "type": "array", - "items": { - "type": "string" - }, - "description": "List of file:function where similar issue exists" - } - } + "summary": "Legacy code from v1 migration, pre-ORM implementation", + "details": "Query builder was ported from old codebase without security review. Team unaware of injection risks in string concatenation pattern. Code review at migration time focused on functionality, not security.", + "affected_scope": "All query-builder.ts methods using string template literals (15 methods total)", + "similar_patterns": [ + "src/database/user-queries.ts:buildEmailQuery", + "src/database/order-queries.ts:buildOrderSearch" + ] }, "remediation_plan": { - "type": "object", - "required": ["approach", "priority", "estimated_effort", "risk_level", "steps"], - "properties": { - "approach": { - "type": "string", - "description": "High-level fix strategy" + "approach": "Migrate to ORM prepared statements with input validation layer", + "priority": "P0 - Critical (security vulnerability)", + "estimated_effort": "4 hours development + 2 hours testing", + "risk_level": "low", + "steps": [ + { + "step": 1, + "action": "Replace direct string concatenation with ORM query builder", + "files": ["src/database/query-builder.ts:buildUserQuery:140-150"], + "commands": [ + "Replace: const query = `SELECT * FROM users WHERE id = ${userId}`;", + "With: return db('users').where('id', userId).first();" + ], + "rationale": "ORM automatically parameterizes queries, eliminating injection risk", + "validation": "Run: npm test -- src/database/query-builder.test.ts" }, - "priority": { - "type": "string", - "pattern": "^P[0-2] - ", - "description": "Priority level with severity label", - "examples": ["P0 - Critical (security vulnerability)", "P1 - High (performance bottleneck)"] + { + "step": 2, + "action": "Add input validation layer before ORM", + "files": ["src/database/validators.ts:validateUserId:NEW"], + "commands": [ + "Create validator: export function validateUserId(id: unknown): number { ... }", + "Add schema: z.number().positive().int()" + ], + "rationale": "Defense in depth - validate types and ranges before database layer", + "validation": "Run: npm test -- src/database/validators.test.ts" }, - "estimated_effort": { - "type": "string", - "description": "Estimated time for development and testing", - "example": "4 hours development + 2 hours testing" - }, - "risk_level": { - "type": "string", - "enum": ["low", "medium", "high"], - "description": "Risk level of implementing the fix" - }, - "steps": { - "type": "array", - "minItems": 1, - "items": { - "type": "object", - "required": ["step", "action", "files", "commands", "rationale", "validation"], - "properties": { - "step": { - "type": "integer", - "minimum": 1, - "description": "Step sequence number" - }, - "action": { - "type": "string", - "description": "What to do in this step" - }, - "files": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Files to modify with function:lines format", - "examples": ["src/database/query-builder.ts:buildUserQuery:140-150"] - }, - "commands": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Specific code changes or commands to execute" - }, - "rationale": { - "type": "string", - "description": "Why this step is needed" - }, - "validation": { - "type": "string", - "description": "How to verify step completion (test command)", - "example": "Run: npm test -- src/database/query-builder.test.ts" - } - } - } - }, - "rollback_strategy": { - "type": "string", - "description": "How to safely revert changes if needed" + { + "step": 3, + "action": "Apply pattern to all 15 similar methods", + "files": ["src/database/query-builder.ts:ALL_METHODS"], + "commands": ["Bulk replace string templates with ORM syntax"], + "rationale": "Prevent similar vulnerabilities in other query methods", + "validation": "Run: npm test -- src/database/" } - } + ], + "rollback_strategy": "Git commit before each step, revert if tests fail. Staged rollout: dev → staging → production with monitoring." }, "impact_assessment": { - "type": "object", - "required": ["files_affected", "tests_required", "breaking_changes"], - "properties": { - "files_affected": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Files affected with action type", - "examples": ["src/database/query-builder.ts (modify)", "src/database/validators.ts (new)"] - }, - "tests_required": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Test files required with action type", - "examples": ["src/database/query-builder.test.ts (update existing)", "src/database/validators.test.ts (new)"] - }, - "breaking_changes": { - "type": "boolean", - "description": "Whether this fix introduces breaking changes" - }, - "dependencies_updated": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Dependencies that need updating", - "examples": ["knex@2.5.1 (ORM library)"] - }, - "deployment_notes": { - "type": "string", - "description": "Special deployment considerations" - } - } - }, - "reassessed_severity": { - "type": "string", - "enum": ["critical", "high", "medium", "low"], - "description": "Updated severity after deep analysis" - }, - "severity_change_reason": { - "type": "string", - "description": "Justification for severity change (or 'No change')" - }, - "confidence_score": { - "type": "number", - "minimum": 0.0, - "maximum": 1.0, - "description": "Confidence level of analysis (0.0-1.0)" - }, - "references": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Project-specific and external documentation references" - }, - "status": { - "type": "string", - "enum": ["remediation_plan_ready", "resolved"], - "description": "Status after deep-dive analysis" - } - }, - "examples": [ - { - "finding_id": "sec-001-a1b2c3d4", - "original_dimension": "security", - "iteration": 1, - "analysis_timestamp": "2025-01-25T14:40:15Z", - "cli_tool_used": "gemini", - "root_cause": { - "summary": "Legacy code from v1 migration, pre-ORM implementation", - "details": "Query builder was ported from old codebase without security review. Team unaware of injection risks in string concatenation pattern. Code review at migration time focused on functionality, not security.", - "affected_scope": "All query-builder.ts methods using string template literals (15 methods total)", - "similar_patterns": [ - "src/database/user-queries.ts:buildEmailQuery", - "src/database/order-queries.ts:buildOrderSearch" - ] - }, - "remediation_plan": { - "approach": "Migrate to ORM prepared statements with input validation layer", - "priority": "P0 - Critical (security vulnerability)", - "estimated_effort": "4 hours development + 2 hours testing", - "risk_level": "low", - "steps": [ - { - "step": 1, - "action": "Replace direct string concatenation with ORM query builder", - "files": ["src/database/query-builder.ts:buildUserQuery:140-150"], - "commands": [ - "Replace: const query = `SELECT * FROM users WHERE id = ${userId}`;", - "With: return db('users').where('id', userId).first();" - ], - "rationale": "ORM automatically parameterizes queries, eliminating injection risk", - "validation": "Run: npm test -- src/database/query-builder.test.ts" - }, - { - "step": 2, - "action": "Add input validation layer before ORM", - "files": ["src/database/validators.ts:validateUserId:NEW"], - "commands": [ - "Create validator: export function validateUserId(id: unknown): number { ... }", - "Add schema: z.number().positive().int()" - ], - "rationale": "Defense in depth - validate types and ranges before database layer", - "validation": "Run: npm test -- src/database/validators.test.ts" - }, - { - "step": 3, - "action": "Apply pattern to all 15 similar methods", - "files": ["src/database/query-builder.ts:ALL_METHODS"], - "commands": ["Bulk replace string templates with ORM syntax"], - "rationale": "Prevent similar vulnerabilities in other query methods", - "validation": "Run: npm test -- src/database/" - } - ], - "rollback_strategy": "Git commit before each step, revert if tests fail. Staged rollout: dev → staging → production with monitoring." - }, - "impact_assessment": { - "files_affected": [ - "src/database/query-builder.ts (modify)", - "src/database/validators.ts (new)", - "src/database/user-queries.ts (modify)", - "src/database/order-queries.ts (modify)" - ], - "tests_required": [ - "src/database/query-builder.test.ts (update existing)", - "src/database/validators.test.ts (new)", - "integration/security/sql-injection.test.ts (new)" - ], - "breaking_changes": false, - "dependencies_updated": ["knex@2.5.1 (ORM library)"], - "deployment_notes": "No downtime required. Database migrations not needed." - }, - "reassessed_severity": "high", - "severity_change_reason": "Found existing WAF rules partially mitigate risk in production. Input validation at API gateway layer provides additional defense. Downgrade from critical to high, but still requires immediate fix.", - "confidence_score": 0.95, - "references": [ - "Project ORM migration guide: docs/architecture/orm-guide.md", - "Knex.js parameterization: https://knexjs.org/guide/query-builder.html#where", - "Similar incident: TICKET-1234 (previous SQL injection fix)" + "files_affected": [ + "src/database/query-builder.ts (modify)", + "src/database/validators.ts (new)", + "src/database/user-queries.ts (modify)", + "src/database/order-queries.ts (modify)" ], - "status": "remediation_plan_ready" - } - ] -} + "tests_required": [ + "src/database/query-builder.test.ts (update existing)", + "src/database/validators.test.ts (new)", + "integration/security/sql-injection.test.ts (new)" + ], + "breaking_changes": false, + "dependencies_updated": ["knex@2.5.1 (ORM library)"], + "deployment_notes": "No downtime required. Database migrations not needed." + }, + "reassessed_severity": "high", + "severity_change_reason": "Found existing WAF rules partially mitigate risk in production. Input validation at API gateway layer provides additional defense. Downgrade from critical to high, but still requires immediate fix.", + "confidence_score": 0.95, + "references": [ + "Project ORM migration guide: docs/architecture/orm-guide.md", + "Knex.js parameterization: https://knexjs.org/guide/query-builder.html#where", + "Similar incident: TICKET-1234 (previous SQL injection fix)" + ], + "status": "remediation_plan_ready" + } +] diff --git a/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json b/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json index caa5e7c0..d7165146 100644 --- a/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json +++ b/.claude/workflows/cli-templates/schemas/review-dimension-results-schema.json @@ -1,281 +1,51 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "Review Dimension Results Schema", - "description": "Output schema for cli-explore-agent dimension analysis results. Contains structured findings from security, architecture, quality, action-items, performance, maintainability, and best-practices reviews.", - "type": "object", - "required": ["dimension", "review_id", "analysis_timestamp", "cli_tool_used", "summary", "findings"], - "properties": { - "dimension": { - "type": "string", - "enum": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"], - "description": "Review dimension being analyzed" - }, - "review_id": { - "type": "string", - "pattern": "^review-\\d{8}-\\d{6}$", - "description": "Unique review cycle identifier", - "example": "review-20250125-143022" - }, - "analysis_timestamp": { - "type": "string", - "format": "date-time", - "description": "ISO8601 timestamp when analysis completed" - }, - "cli_tool_used": { - "type": "string", - "enum": ["gemini", "qwen", "codex"], - "description": "CLI tool used for analysis (fallback chain: gemini → qwen → codex)" - }, - "model": { - "type": "string", - "description": "Model name/version used by CLI tool", - "examples": ["gemini-2.5-pro", "coder-model", "gpt-5.1-codex"] - }, - "analysis_duration_ms": { - "type": "integer", - "minimum": 0, - "description": "Analysis duration in milliseconds" - }, +[ + { + "dimension": "security", + "review_id": "review-20250125-143022", + "analysis_timestamp": "2025-01-25T14:30:22Z", + "cli_tool_used": "gemini", + "model": "gemini-2.5-pro", + "analysis_duration_ms": 2145000, "summary": { - "type": "object", - "required": ["total_findings", "critical", "high", "medium", "low", "files_analyzed", "lines_reviewed"], - "properties": { - "total_findings": { - "type": "integer", - "minimum": 0, - "description": "Total number of findings across all severities" - }, - "critical": { - "type": "integer", - "minimum": 0, - "description": "Count of critical severity findings" - }, - "high": { - "type": "integer", - "minimum": 0, - "description": "Count of high severity findings" - }, - "medium": { - "type": "integer", - "minimum": 0, - "description": "Count of medium severity findings" - }, - "low": { - "type": "integer", - "minimum": 0, - "description": "Count of low severity findings" - }, - "files_analyzed": { - "type": "integer", - "minimum": 0, - "description": "Total number of files analyzed" - }, - "lines_reviewed": { - "type": "integer", - "minimum": 0, - "description": "Total lines of code reviewed" - } - } + "total_findings": 15, + "critical": 2, + "high": 4, + "medium": 6, + "low": 3, + "files_analyzed": 47, + "lines_reviewed": 8932 }, - "findings": { - "type": "array", - "description": "Array of findings discovered during analysis", - "items": { - "$ref": "#/definitions/unifiedFinding" - } - }, - "cross_references": { - "type": "array", - "description": "Cross-references to findings in other dimensions", - "items": { - "type": "object", - "required": ["finding_id", "related_dimensions", "reason"], - "properties": { - "finding_id": { - "type": "string", - "description": "Finding ID that appears in multiple dimensions" - }, - "related_dimensions": { - "type": "array", - "items": { - "type": "string" - }, - "description": "List of dimensions where this finding appears" - }, - "reason": { - "type": "string", - "description": "Explanation of cross-reference relationship" - } - } - } - } - }, - "definitions": { - "unifiedFinding": { - "type": "object", - "title": "Unified Finding Schema", - "description": "Standardized finding structure applicable to all review dimensions", - "required": ["id", "title", "severity", "category", "description", "file", "line", "snippet", "recommendation", "impact", "iteration", "status"], - "properties": { - "id": { - "type": "string", - "format": "uuid", - "description": "Unique finding identifier (UUID v4)", - "example": "sec-001-a1b2c3d4" - }, - "title": { - "type": "string", - "minLength": 10, - "maxLength": 100, - "description": "Short descriptive title (50-100 chars)" - }, - "severity": { - "type": "string", - "enum": ["critical", "high", "medium", "low"], - "description": "Severity level based on impact and risk" - }, - "category": { - "type": "string", - "description": "Dimension-specific category (see CATEGORIES in review-cycle.md)", - "examples": ["injection", "coupling", "code-smell", "n-plus-one"] - }, - "description": { - "type": "string", - "minLength": 50, - "description": "Detailed description with context (200-500 words)" - }, - "file": { - "type": "string", - "description": "Relative path to affected file", - "example": "src/database/query-builder.ts" - }, - "line": { - "type": "integer", - "minimum": 1, - "description": "Line number where issue occurs" - }, - "snippet": { - "type": "string", - "description": "Code context (5-10 lines around the issue)" - }, - "recommendation": { - "type": "string", - "description": "Actionable fix recommendation with code examples" - }, - "impact": { - "type": "string", - "description": "Potential impact description (business + technical)" - }, - "references": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Documentation URLs and standard references", - "examples": [ - "OWASP Top 10 - A03:2021 Injection", - "https://owasp.org/www-community/attacks/SQL_Injection" - ] - }, + "findings": [ + { + "id": "sec-001-a1b2c3d4", + "title": "SQL Injection vulnerability in user query", + "severity": "critical", + "category": "injection", + "description": "Direct string concatenation in SQL query allows injection attacks. User input is not sanitized before query execution.", + "file": "src/database/query-builder.ts", + "line": 145, + "snippet": "const query = `SELECT * FROM users WHERE id = ${userId}`;", + "recommendation": "Use parameterized queries: db.query('SELECT * FROM users WHERE id = ?', [userId])", + "references": [ + "OWASP Top 10 - A03:2021 Injection", + "https://owasp.org/www-community/attacks/SQL_Injection" + ], + "impact": "Potential data breach, unauthorized access to user records, data manipulation", "metadata": { - "type": "object", - "description": "Dimension-specific metadata", - "properties": { - "cwe_id": { - "type": "string", - "description": "CWE identifier (for security findings)", - "example": "CWE-89" - }, - "owasp_category": { - "type": "string", - "description": "OWASP category (for security findings)", - "example": "A03:2021-Injection" - }, - "pattern_type": { - "type": "string", - "description": "Pattern type (for quality findings)", - "examples": ["anti-pattern", "code-smell"] - }, - "complexity_score": { - "type": "number", - "description": "Cyclomatic complexity score (for quality findings)" - } - } + "cwe_id": "CWE-89", + "owasp_category": "A03:2021-Injection" }, - "iteration": { - "type": "integer", - "minimum": 0, - "description": "Iteration number when finding was discovered (0 = initial parallel phase)" - }, - "status": { - "type": "string", - "enum": ["pending_remediation", "remediation_plan_ready", "resolved"], - "description": "Current status of finding" - }, - "cross_references": { - "type": "array", - "items": { - "type": "string" - }, - "description": "List of dimensions where this finding also appears" - }, - "reassessed_severity": { - "type": "string", - "enum": ["critical", "high", "medium", "low"], - "description": "Updated severity if changed in deep-dive iteration" - } + "iteration": 0, + "status": "pending_remediation", + "cross_references": [] } - } - }, - "examples": [ - { - "dimension": "security", - "review_id": "review-20250125-143022", - "analysis_timestamp": "2025-01-25T14:30:22Z", - "cli_tool_used": "gemini", - "model": "gemini-2.5-pro", - "analysis_duration_ms": 2145000, - "summary": { - "total_findings": 15, - "critical": 2, - "high": 4, - "medium": 6, - "low": 3, - "files_analyzed": 47, - "lines_reviewed": 8932 - }, - "findings": [ - { - "id": "sec-001-a1b2c3d4", - "title": "SQL Injection vulnerability in user query", - "severity": "critical", - "category": "injection", - "description": "Direct string concatenation in SQL query allows injection attacks. User input is not sanitized before query execution.", - "file": "src/database/query-builder.ts", - "line": 145, - "snippet": "const query = `SELECT * FROM users WHERE id = ${userId}`;", - "recommendation": "Use parameterized queries: db.query('SELECT * FROM users WHERE id = ?', [userId])", - "references": [ - "OWASP Top 10 - A03:2021 Injection", - "https://owasp.org/www-community/attacks/SQL_Injection" - ], - "impact": "Potential data breach, unauthorized access to user records, data manipulation", - "metadata": { - "cwe_id": "CWE-89", - "owasp_category": "A03:2021-Injection" - }, - "iteration": 0, - "status": "pending_remediation", - "cross_references": [] - } - ], - "cross_references": [ - { - "finding_id": "sec-001-a1b2c3d4", - "related_dimensions": ["quality", "architecture"], - "reason": "Same file flagged in multiple dimensions" - } - ] - } - ] -} + ], + "cross_references": [ + { + "finding_id": "sec-001-a1b2c3d4", + "related_dimensions": ["quality", "architecture"], + "reason": "Same file flagged in multiple dimensions" + } + ] + } +]