feat: enforce mandatory rationale and role in explore/diagnosis schema output

- Remove oneOf string option from relevant_files/affected_files, require structured objects
- Add required fields: rationale (minLength 10), role/change_type enum
- Add optional fields: discovery_source, key_symbols
- Update all caller commands with new format instructions and success criteria
- Fix consumer code: Map-based dedup, getPath() helper, path extraction
- Fix frontend: f.rationale || f.reason backward-compatible fallback
This commit is contained in:
catlog22
2026-02-13 10:42:37 +08:00
parent 78f1d81516
commit e485f1d69b
16 changed files with 679 additions and 373 deletions

View File

@@ -83,26 +83,45 @@
},
"affected_files": {
"type": "array",
"minItems": 1,
"items": {
"oneOf": [
{"type": "string"},
{
"type": "object",
"required": ["path", "relevance"],
"properties": {
"path": {"type": "string", "description": "File path relative to project root"},
"relevance": {"type": "number", "minimum": 0, "maximum": 1, "description": "Relevance score 0.0-1.0 (0.7+ high, 0.5-0.7 medium, <0.5 low)"},
"rationale": {"type": "string", "description": "Brief explanation of why this file is affected from this diagnosis angle"},
"change_type": {
"type": "string",
"enum": ["fix_target", "needs_update", "test_coverage", "reference_only"],
"description": "Type of change needed for this file"
}
}
"type": "object",
"required": ["path", "relevance", "rationale", "change_type"],
"properties": {
"path": {
"type": "string",
"description": "File path relative to project root"
},
"relevance": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Relevance score 0.0-1.0 (0.7+ high, 0.5-0.7 medium, <0.5 low)"
},
"rationale": {
"type": "string",
"minLength": 10,
"description": "REQUIRED: Selection rationale explaining why this file is affected. Must be specific. Example: 'Contains handleLogin() at line 45 where null check is missing for token response' rather than 'Related to bug'"
},
"change_type": {
"type": "string",
"enum": ["fix_target", "needs_update", "test_coverage", "reference_only"],
"description": "Type of change needed: fix_target=contains the bug, needs_update=requires changes due to fix, test_coverage=tests to add/update, reference_only=understanding context"
},
"discovery_source": {
"type": "string",
"enum": ["bash-scan", "cli-analysis", "ace-search", "dependency-trace", "stack-trace", "manual"],
"description": "How the file was identified as affected"
},
"key_symbols": {
"type": "array",
"items": {"type": "string"},
"description": "Key symbols (functions, classes) in this file related to the bug"
}
]
},
"additionalProperties": false
},
"description": "Files affected by the bug. Prefer object format with relevance scores for synthesis prioritization."
"description": "Files affected by the bug. Every file MUST have structured rationale explaining why it is affected and what change is needed."
},
"reproduction_steps": {
"type": "array",

View File

@@ -1,7 +1,7 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Exploration Context Schema",
"description": "Code exploration results from cli-explore-agent for task context gathering",
"description": "Code exploration results from cli-explore-agent for task context gathering. Every file MUST include selection rationale.",
"type": "object",
"required": [
"project_structure",
@@ -20,21 +20,54 @@
},
"relevant_files": {
"type": "array",
"minItems": 1,
"items": {
"oneOf": [
{"type": "string"},
{
"type": "object",
"required": ["path", "relevance"],
"properties": {
"path": {"type": "string", "description": "File path relative to project root"},
"relevance": {"type": "number", "minimum": 0, "maximum": 1, "description": "Relevance score 0.0-1.0 (0.7+ high, 0.5-0.7 medium, <0.5 low)"},
"rationale": {"type": "string", "description": "Brief explanation of why this file is relevant from this exploration angle"}
}
"type": "object",
"required": ["path", "relevance", "rationale", "role"],
"properties": {
"path": {
"type": "string",
"description": "File path relative to project root"
},
"relevance": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Relevance score 0.0-1.0 (0.7+ high, 0.5-0.7 medium, <0.5 low)"
},
"rationale": {
"type": "string",
"minLength": 10,
"description": "REQUIRED: Selection rationale explaining why this file is relevant to the exploration topic. Must be specific (not generic). Example: 'Contains AuthService.login() which is the entry point for JWT token generation' rather than 'Related to auth'"
},
"role": {
"type": "string",
"enum": [
"modify_target",
"dependency",
"pattern_reference",
"test_target",
"type_definition",
"integration_point",
"config",
"context_only"
],
"description": "File's role relative to the task: modify_target=needs changes, dependency=imported by targets, pattern_reference=demonstrates patterns to follow, test_target=tests needing update, type_definition=types/interfaces used, integration_point=where new code connects, config=configuration, context_only=understanding only"
},
"discovery_source": {
"type": "string",
"enum": ["bash-scan", "cli-analysis", "ace-search", "dependency-trace", "manual"],
"description": "How the file was discovered: bash-scan=structural scan (rg/find/tree), cli-analysis=Gemini/Qwen semantic analysis, ace-search=ACE context engine, dependency-trace=import/export graph traversal, manual=directly specified in task"
},
"key_symbols": {
"type": "array",
"items": {"type": "string"},
"description": "Key symbols (functions, classes, types) in this file relevant to the task. Example: ['AuthService', 'login', 'TokenPayload']"
}
]
},
"additionalProperties": false
},
"description": "File paths to be modified or referenced for the task. Prefer object format with relevance scores for synthesis prioritization."
"description": "Files relevant to the task. Every file MUST have structured rationale explaining its selection basis and role classification."
},
"patterns": {
"type": "string",