docs+ci: finalize AI-native positioning and close submission loop

P1-1: README concrete example updated to route-id-first
- Output now shows 'switch_to_alternative_tool_path' first, then detail
- Removed hardcoded '8 similar cases' overclaim
- Tightened pain point language (no longer 'AI and you' guessing together)

P0-2: CONTRIBUTING.md rewritten as AI-only protocol
- Removed generic OSS welcoming tone
- Human paths explicitly marked as 'fallback / maintainer paths'
- 'What makes a good contribution' uses v2.1 terminology throughout
- Added 'Inference is re-computable; evidence is durable' principle

P0-1: SKILL.md tightened
- Moved Core principles up right after Identity section
- Removed duplicate Core principles section at end
- Reinforces AI-only identity earlier in the document

P0-3: Workflow observability enhanced
- Added 'Detect validation source' step (raw JSON vs form fields)
- Warning when both sources detected
- Validation comment now shows which source was used
- Error categorization in failure comments (missing fields, route id, schema, parse)
- Issue form 'Attempted tool' renamed to 'Attempted path'
- Full case JSON field marked as 'optional fallback' with clear override behavior

P0-4: Scripts paths verified
- All scripts (validate_case.py, build_index.py, parse_issue_form.py, ci_self_test.py) exist and are referenced correctly
- parse_issue_form.py updated to handle both 'Attempted path' and legacy 'Attempted tool' field names

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

Author: LpcPaul

.github/ISSUE_TEMPLATE/case_report.yml

@@ -38,9 +38,9 @@ body:
       required: true
 
   - type: input
-    id: evidence_attempted_tool
+    id: evidence_attempted_path
     attributes:
-      label: Attempted tool
+      label: Attempted path
       description: "What tool or path was used?"
       placeholder: "e.g. browser-cdp"
     validations:
@@ -251,6 +251,6 @@ body:
   - type: textarea
     id: full_json
     attributes:
-      label: Full case JSON (optional)
-      description: "Paste a complete v2.1 case object if available."
+      label: Full case JSON (optional fallback)
+      description: "Paste a complete v2.1 case object to override form fields. This is a fallback path for maintainers or when the form cannot capture complex cases. If provided, this JSON takes priority over structured fields."
       render: json

.github/workflows/validate_case.yml

@@ -63,24 +63,43 @@ jobs:
             const fs = require('fs');
             fs.writeFileSync('/tmp/issue_body.txt', context.payload.issue.body || '');
 
-      # Step 2: Try to extract full JSON block first (backward compat)
-      - name: Check for embedded JSON block
-        id: check_json
+      # Step 2: Check for both raw JSON and form fields
+      - name: Detect validation source
+        id: detect_source
         run: |
+          HAS_JSON=false
+          HAS_FORM=false
+
           if grep -q '```json' /tmp/issue_body.txt; then
-            sed -n '/```json/,/```/p' /tmp/issue_body.txt | grep -v '```' > /tmp/case_from_issue.json
-            echo "has_json=true" >> $GITHUB_OUTPUT
-          else
-            echo "has_json=false" >> $GITHUB_OUTPUT
+            HAS_JSON=true
+          fi
+
+          # Check if structured form fields exist (Task, Symptom, Why current path failed, etc.)
+          if grep -q '^### Task$' /tmp/issue_body.txt && grep -q '^### Symptom$' /tmp/issue_body.txt; then
+            HAS_FORM=true
+          fi
+
+          echo "has_json=$HAS_JSON" >> $GITHUB_OUTPUT
+          echo "has_form=$HAS_FORM" >> $GITHUB_OUTPUT
+
+          if [ "$HAS_JSON" = "true" ] && [ "$HAS_FORM" = "true" ]; then
+            echo "::warning::Both raw JSON block and structured form fields detected. Using raw JSON for validation."
           fi
 
-      # Step 3: If no JSON block, assemble from form fields
+      # Step 3: Extract or assemble case JSON
+      - name: Extract raw JSON block
+        if: steps.detect_source.outputs.has_json == 'true'
+        id: extract_json
+        run: |
+          sed -n '/```json/,/```/p' /tmp/issue_body.txt | grep -v '```' > /tmp/case_from_issue.json
+          echo "validation_source=raw_json_block" >> $GITHUB_OUTPUT
+
       - name: Assemble case JSON from form fields
-        if: steps.check_json.outputs.has_json != 'true'
+        if: steps.detect_source.outputs.has_json != 'true'
         id: assemble
         run: |
           python3 scripts/parse_issue_form.py --body-file /tmp/issue_body.txt --output /tmp/case_from_issue.json
-          echo "assembled=true" >> $GITHUB_OUTPUT
+          echo "validation_source=parsed_issue_form" >> $GITHUB_OUTPUT
 
       # Step 4: Validate the case (works for both paths)
       - name: Validate case
@@ -99,18 +118,37 @@ jobs:
           script: |
             const validateResult = `${{ steps.validate.outputs.result }}`;
             const validateExit = '${{ steps.validate.outputs.exit_code }}';
-            const wasAssembled = '${{ steps.assemble.outputs.assembled }}' === 'true';
+            const validationSource = '${{ steps.extract_json.outputs.validation_source || steps.assemble.outputs.validation_source }}';
+            const hasBothSources = '${{ steps.detect_source.outputs.has_json }}' === 'true' && '${{ steps.detect_source.outputs.has_form }}' === 'true';
 
             let comment = '## AgentRX — Case Validation (v2.1)\n\n';
 
-            if (wasAssembled) {
-              comment += '📋 Case JSON was assembled from form fields.\n\n';
+            // Source info
+            if (hasBothSources) {
+              comment += '⚠️ Both raw JSON and form fields detected. Using raw JSON.\n\n';
+            }
+            if (validationSource === 'raw_json_block') {
+              comment += '📋 Validation source: raw JSON block from issue body.\n\n';
+            } else if (validationSource === 'parsed_issue_form') {
+              comment += '📋 Validation source: assembled from structured form fields.\n\n';
             }
 
+            // Result
             if (validateExit === '0') {
               comment += '✅ Case passed v2.1 schema validation.\n\n';
             } else {
               comment += '❌ Case validation failed:\n\n```\n' + validateResult + '\n```\n\n';
+
+              // Categorize errors
+              if (validateResult.includes('Missing required field')) {
+                comment += '**Error type:** Missing required fields. Check evidence and inference sections.\n\n';
+              } else if (validateResult.includes('route id') || validateResult.includes('best_candidate_route_id')) {
+                comment += '**Error type:** Invalid route id. Must be from rules/routes.yaml.\n\n';
+              } else if (validateResult.includes('schema') || validateResult.includes('not in allowed values')) {
+                comment += '**Error type:** Schema violation. Check field types and enum values.\n\n';
+              } else if (validateResult.includes('parse') || validateResult.includes('JSON')) {
+                comment += '**Error type:** JSON parse error. Ensure valid JSON format.\n\n';
+              }
             }
 
             comment += 'Review checklist:\n';

.gitignore

@@ -0,0 +1 @@
+__pycache__/

CONTRIBUTING.md

@@ -16,7 +16,7 @@ Human contributions are not the main growth mechanism of the library.
 
 ---
 
-## AI contribution path
+## AI contribution path (default)
 
 When an AI agent decides to contribute a case:
 
@@ -32,26 +32,40 @@ The case must follow `schema/case.schema.json` (v2.1). Key requirements:
 
 ---
 
-## Human contribution paths
+## Human contribution paths (fallback)
 
-Humans may submit cases through:
-- GitHub Issue using the case report template (fallback path)
-- Direct PR adding a JSON file to `cases/` (maintainer path)
-- Schema / taxonomy / validation improvements (maintenance path)
+The following are **fallback / maintainer paths**, not the default:
 
-These are **exception paths**, not the default. The system is designed for AI-generated structured case submission at scale.
+### Fallback: structured issue form
+- Use the case report template in GitHub Issues
+- Fill out evidence and inference fields
+- The workflow will assemble and validate the case JSON automatically
+
+### Maintainer override: direct PR
+- Add a JSON case file directly to `cases/`
+- Rebuild index with `python3 scripts/build_index.py`
+- Only for maintainers who need to add exceptional cases
+
+### Maintainer: schema and taxonomy edits
+- Edit `schema/case.schema.json`, `rules/routes.yaml`, or rules files
+- Run `python3 scripts/ci_self_test.py` to verify consistency
+
+These paths exist for maintenance and exceptional cases.
+They are **not** the default contribution mechanism.
+The system is designed for AI-generated structured case submission at scale.
 
 ---
 
 ## What makes a good contribution
 
-A good contribution — whether from AI or human — preserves the real AI journey:
+A good contribution preserves the real AI journey:
 
-- **Preserve the stuck journey.** What task was being attempted, which tool path was taken, what symptom appeared.
-- **Evidence first, diagnosis second.** Do not collapse symptom into diagnosis too early. The evidence layer must be fillable from observable facts alone.
-- **Route id over tool brand.** Recommend `switch_to_alternative_tool_path`, not "use playwright-mcp". Route ids are stable; tool names are not.
+- **Preserve evidence before diagnosis.** What task was being attempted, which tool path was taken, what symptom appeared.
+- **Preserve symptom before interpretation.** Do not collapse observable facts into diagnosis too early. The evidence layer must be fillable from observable facts alone.
+- **Route id over tool brand.** Use `switch_to_alternative_tool_path`, not "use playwright-mcp". Route ids are stable; tool names are not.
 - **Explain the mismatch, not the failure.** `why_current_path_failed` should describe why the tool-path-task combination doesn't work, not blame the tool.
 - **Under-specify rather than invent.** If evidence is insufficient for an inference, leave optional inference fields empty. Polluted inference is worse than missing inference.
+- **Inference is re-computable; evidence is durable.** A different agent reading the same evidence might produce different inference. That is by design.
 
 ---
 

README.md

@@ -8,7 +8,7 @@
 
 > You've installed a pile of tools — skills, MCP servers, plugins — but every time something goes wrong, your AI bounces between them forever trying, switching, retrying. Time wasted. Tokens burned.
 
-> You've got three tools that all claim to make slide decks. But which one is better? Which one fits this particular presentation? Every time, both you and your AI are stuck guessing.
+> You've got three tools that all claim to make slide decks. But which one is better? Which one fits this particular presentation? Every time, the AI has to guess, and you shouldn't have to be its fallback decision-maker.
 
 > A tool call fails, and the AI turns around and asks you what to do. But the whole reason you installed tools was so you wouldn't have to think about this stuff — and you don't know either.
 
@@ -27,16 +27,16 @@ AI: [tries browser-cdp skill]
 
 [AgentRX activates]
 
-AgentRX: You hit a `capability_mismatch` at the execute-task stage.
+AgentRX: Route: switch_to_alternative_tool_path
 
-         Two alternatives exist in your current environment:
+         Why: current tool captures static HTML only; page requires
+         JavaScript rendering.
 
-         1. web-access skill  — handles post-render DOM, best for this task
-         2. Playwright MCP    — better if you also need interaction
-                                (clicks, scrolls, form fills)
+         Detail: switch to a browser-capable route. playwright-mcp can
+         render the page and extract the full DOM. web_fetch is a
+         lighter option for static pages.
 
-         Prescription: switch to web-access.
-         Confidence: high.
+         Confidence: high
 ```
 
 This is what AgentRX does: turns a stuck state into a structured next-step decision.

SKILL.md

@@ -20,6 +20,13 @@ tags: [meta, diagnosis, governance, task-routing, tool-selection, recovery]
 You are a **task-first diagnosis and action-navigation layer** for AI agents.
 Your purpose is to complete the diagnosis-retrieval-recommendation loop within the system, not to escalate back to human judgment.
 
+### Core principles
+
+1. **Evidence first, inference second.** Facts before interpretation.
+2. **Route id over tool name.** Action paths are stable; tool brands are not.
+3. **Self-diagnosis before escalation.** Complete the loop within this system before asking the human.
+4. **Human is not the default decision-maker.** The system exists so AI can resolve stuck states autonomously.
+
 ## When to activate
 
 Activate when ANY of these is true:
@@ -102,15 +109,6 @@ See `docs/ARCHITECTURE.md` for the system design.
 
 ---
 
-## Core principles
-
-1. **Evidence first, inference second.** Facts before interpretation.
-2. **Route id over tool name.** Action paths are stable; tool brands are not.
-3. **Self-diagnosis before escalation.** Complete the loop within this system before asking the human.
-4. **Human is not the default decision-maker.** The system exists so AI can resolve stuck states autonomously.
-
----
-
 ## Case Contribution
 
 If the user agrees to contribute this case:

cases/index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "2.1",
   "project_name": "agentrx",
-  "generated_at": "2026-04-16T14:15:48Z",
+  "generated_at": "2026-04-16T14:54:32Z",
   "navigation_order": [
     "task",
     "journey_stage",

scripts/parse_issue_form.py

@@ -78,7 +78,7 @@ def assemble_case(body: str) -> dict:
     # ── Evidence ──
     task = parse_markdown_field(body, 'Task')
     desired_outcome = parse_markdown_field(body, 'Desired outcome')
-    attempted_tool = parse_markdown_field(body, 'Attempted tool')
+    attempted_path_label = parse_markdown_field(body, 'Attempted path') or parse_markdown_field(body, 'Attempted tool')
     tool_type = parse_dropdown(body, 'Tool type') or 'unknown'
     symptom = parse_markdown_field(body, 'Symptom')
     reproduction_steps = parse_multiline(body, 'Reproduction steps')
@@ -113,7 +113,7 @@ def assemble_case(body: str) -> dict:
         'task': task,
         'desired_outcome': desired_outcome,
         'attempted_path': {
-            'tool': attempted_tool,
+            'tool': attempted_path_label,
             'tool_type': tool_type,
         },
         'symptom': symptom,