docs+ci: close narrative and submission loop

LpcPaul · qwencoder · LpcPaul · commit 8534cfa15e1c · 2026-04-16T22:17:40.000+08:00
P0-1: README definition layer aligned to v2.1
- Replaced old 'task+journey_stage+problem_family' framing with
  evidence/inference/route-id-first model
- Tightened 'Human role vs AI role' — human = installer/host,
  AI = default operator and contributor
- Removed 'AI and you' / 'give answer to AI and you' language
- Added v2.1 two-layer case diagram
- Removed overclaim 'Based on 8 similar cases' from concrete example
- Added 'What changes after installation?' section

P0-2: ARCHITECTURE.md human role tightened
- Audience: 'Primary runtime consumer: AI agents' (not 'primary/secondary')
- 'Human role: installer, repository host, and occasional maintainer'
- Added: 'Installation is a human decision; operation is not.'
- Added parse_issue_form.py to Execution Scripts table

P0-3: Issue form -&gt; validation loop closed (Scheme A)
- New scripts/parse_issue_form.py: assembles v2.1 case JSON from
  GitHub issue form fields (evidence + inference)
- Workflow uses Python parser instead of inline JS for robustness
- Dual-path: extracts embedded JSON block first (backward compat),
  then falls back to form field assembly
- End-to-end tested: form -&gt; parse -&gt; validate_case.py -&gt; PASSED

Co-authored-by: Qwen-Coder &lt;qwen-coder@alibabacloud.com&gt;
diff --git a/.github/workflows/validate_case.yml b/.github/workflows/validate_case.yml
@@ -35,9 +35,7 @@ jobs:
         run: pip install pyyaml
 
       - name: Run CI self-test
-        id: self_test
-        run: |
-          python3 scripts/ci_self_test.py
+        run: python3 scripts/ci_self_test.py
 
   validate-issue-case:
     if: github.event_name == 'issues' && contains(github.event.issue.labels.*.name, 'case-report')
@@ -57,143 +55,35 @@ jobs:
       - name: Install dependencies
         run: pip install pyyaml
 
-      # Step A: Try to extract full JSON from issue body first (optional field)
-      - name: Extract JSON from issue body
-        id: extract_json
+      # Step 1: Write issue body to file for parsing
+      - name: Write issue body to file
         uses: actions/github-script@v7
         with:
           script: |
-            const body = context.payload.issue.body || '';
-            const jsonMatch = body.match(/```json\s*\n([\s\S]*?)\n```/);
-            if (jsonMatch) {
-              const fs = require('fs');
-              fs.writeFileSync('/tmp/case_from_issue.json', jsonMatch[1]);
-              core.setOutput('has_json', 'true');
-            } else {
-              core.setOutput('has_json', 'false');
-            }
+            const fs = require('fs');
+            fs.writeFileSync('/tmp/issue_body.txt', context.payload.issue.body || '');
 
-      # Step B: If no JSON block, assemble v2.1 case JSON from structured form fields
+      # Step 2: Try to extract full JSON block first (backward compat)
+      - name: Check for embedded JSON block
+        id: check_json
+        run: |
+          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
+          fi
+
+      # Step 3: If no JSON block, assemble from form fields
       - name: Assemble case JSON from form fields
+        if: steps.check_json.outputs.has_json != 'true'
         id: assemble
-        if: steps.extract_json.outputs.has_json != 'true'
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const body = context.payload.issue.body || '';
-            const fs = require('fs');
-
-            function getField(label) {
-              const regex = new RegExp(`^### ${label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\n([\\s\\S]*?)(?=\\n### |$)`, 'm');
-              const match = body.match(regex);
-              if (match) {
-                let val = match[1].trim();
-                // Remove "_No response_" placeholder
-                if (val === '_No response_') return '';
-                return val;
-              }
-              return '';
-            }
-
-            function getDropdown(label) {
-              const val = getField(label);
-              // Clean up markdown list formatting
-              return val.replace(/^-\s*/, '').trim();
-            }
-
-            function getMultiLine(label) {
-              const val = getField(label);
-              // Split by lines, remove empty lines and "- " prefix
-              return val.split('\n')
-                .map(l => l.replace(/^-\s*/, '').trim())
-                .filter(l => l.length > 0);
-            }
-
-            const evidenceTask = getField('Task') || '';
-            const evidenceDesiredOutcome = getField('Desired outcome') || '';
-            const evidenceAttemptedTool = getField('Attempted tool') || '';
-            const evidenceToolType = getDropdown('Tool type') || 'unknown';
-            const evidenceSymptom = getField('Symptom') || '';
-            const evidenceReproductionSteps = getMultiLine('Reproduction steps');
-            const evidenceContext = getField('Context (optional)') || '';
-            const evidenceEnvironmentNotes = getField('Environment notes (optional)') || '';
-            const evidenceFailedStep = getField('Failed step (optional)') || '';
-            const evidenceArtifactsUsed = getMultiLine('Artifacts used (optional)');
-
-            const inferenceJourneyStage = getDropdown('Journey stage') || 'unknown';
-            const inferenceProblemFamily = getDropdown('Problem family') || 'unknown';
-            const inferenceWhyCurrentPathFailed = getField('Why current path failed') || '';
-            const inferenceBestCandidateRouteId = getDropdown('Best candidate route id') || '';
-            const inferenceBestCandidateRouteDetail = getField('Route detail (optional)') || '';
-            const inferencePrerequisitesForSwitch = getMultiLine('Prerequisites for switch (optional)');
-            const inferenceConfidence = getDropdown('Confidence') || 'medium';
-
-            const resolutionOutcome = getDropdown('Outcome') || 'unknown';
-            const resolutionFollowUpNotes = getField('Follow-up notes (optional)') || '';
-
-            const metadataSource = getDropdown('Source') || 'user-reported';
-            const metadataTags = (getField('Tags') || '').split(',').map(t => t.trim()).filter(t => t.length > 0);
-
-            // Parse environment notes for platform and constraints
-            const environment = { platform: 'other' };
-            if (evidenceEnvironmentNotes) {
-              const platformMatch = evidenceEnvironmentNotes.match(/[Pp]latform:\s*(\S+)/);
-              if (platformMatch) environment.platform = platformMatch[1];
-              if (evidenceEnvironmentNotes.includes('dynamic render')) environment.requires_dynamic_render = true;
-              if (evidenceEnvironmentNotes.includes('network')) environment.requires_network = true;
-              if (evidenceEnvironmentNotes.includes('login')) environment.requires_login = true;
-              if (evidenceEnvironmentNotes.includes('filesystem')) environment.requires_local_filesystem = true;
-              if (evidenceEnvironmentNotes.includes('deterministic')) environment.requires_deterministic_execution = true;
-              environment.notes = evidenceEnvironmentNotes;
-            }
-
-            const caseData = {
-              schema_version: "2.1",
-              id: `${new Date().toISOString().slice(0, 10)}-${evidenceTask.replace(/\s+/g, '-').toLowerCase().slice(0, 20)}-${String(Math.floor(Math.random() * 9999)).padStart(4, '0')}`,
-              title: `${evidenceTask} ${inferenceJourneyStage} ${inferenceProblemFamily}`,
-              summary: inferenceWhyCurrentPathFailed,
-              created_at: new Date().toISOString(),
-              tags: metadataTags,
-              evidence: {
-                task: evidenceTask,
-                desired_outcome: evidenceDesiredOutcome,
-                attempted_path: {
-                  tool: evidenceAttemptedTool,
-                  tool_type: evidenceToolType
-                },
-                symptom: evidenceSymptom,
-                reproduction_steps: evidenceReproductionSteps.length > 0 ? evidenceReproductionSteps : undefined
-              },
-              inference: {
-                journey_stage: inferenceJourneyStage,
-                problem_family: inferenceProblemFamily,
-                why_current_path_failed: inferenceWhyCurrentPathFailed,
-                best_candidate_route_id: inferenceBestCandidateRouteId,
-                best_candidate_route_detail: inferenceBestCandidateRouteDetail || undefined,
-                prerequisites_for_switch: inferencePrerequisitesForSwitch.length > 0 ? inferencePrerequisitesForSwitch : undefined,
-                confidence: inferenceConfidence
-              },
-              resolution: {
-                outcome: resolutionOutcome,
-                follow_up_notes: resolutionFollowUpNotes || undefined
-              },
-              source: metadataSource,
-              verified: false,
-              related_cases: []
-            };
-
-            // Add optional fields only if they have content
-            if (evidenceContext) caseData.evidence.context = evidenceContext;
-            if (Object.keys(environment).length > 1) caseData.evidence.environment = environment;
-            if (evidenceFailedStep) caseData.evidence.failed_step = evidenceFailedStep;
-            if (evidenceArtifactsUsed.length > 0) caseData.evidence.artifacts_used = evidenceArtifactsUsed;
-
-            fs.writeFileSync('/tmp/case_from_issue.json', JSON.stringify(caseData, null, 2));
-            core.setOutput('has_json', 'true');
-            core.setOutput('assembled', 'true');
+        run: |
+          python3 scripts/parse_issue_form.py --body-file /tmp/issue_body.txt --output /tmp/case_from_issue.json
+          echo "assembled=true" >> $GITHUB_OUTPUT
 
+      # Step 4: Validate the case (works for both paths)
       - name: Validate case
-        if: steps.extract_json.outputs.has_json == 'true' || steps.assemble.outputs.has_json == 'true'
         id: validate
         run: |
           RESULT=$(python3 scripts/validate_case.py --input /tmp/case_from_issue.json 2>&1) || EXIT_CODE=$?
@@ -202,8 +92,8 @@ jobs:
           echo "EOF" >> $GITHUB_OUTPUT
           echo "exit_code=${EXIT_CODE:-0}" >> $GITHUB_OUTPUT
 
+      # Step 5: Post comment with results
       - name: Post validation comment
-        if: steps.extract_json.outputs.has_json == 'true' || steps.assemble.outputs.has_json == 'true'
         uses: actions/github-script@v7
         with:
           script: |
diff --git a/README.md b/README.md
@@ -47,22 +47,17 @@ This is what AgentRX does: turns a stuck state into a structured next-step decis
 
 **AgentRX is installed by humans, but operated by AI.**
 
-Once installed, the human is not the primary user. The primary user is the AI agent itself:
-- it **diagnoses** stuck states
-- it **searches** the case library
-- it **chooses** a better route
-- it **contributes** new cases back
-
-You don't run AgentRX. Your AI does.
+Once installed, the human is not the primary user. The primary runtime user is the AI agent itself.
+The default contributor is also AI.
 
 ### Human role vs AI role
 
 | | What they do |
 |---|---|
-| **Human** | Install the skill. Expose the repository / index / rules. Optionally review schema or approve maintenance changes. |
-| **AI** | Detect stuck state. Structure evidence. Derive inference. Retrieve similar cases. Choose next action. Optionally contribute a new case. |
+| **Human** | Install the skill. Host the repository. Optionally review schema or approve maintenance changes. |
+| **AI** | Detect stuck state. Collect evidence. Derive inference. Retrieve similar cases. Choose a route. Optionally contribute a new case. |
 
-**The human is the installer and host. The AI is the default operator.**
+**The human is the installer and host. The AI is the default operator and contributor.**
 
 ### The AI self-evolution loop
 
@@ -86,7 +81,42 @@ Each case contributed by an AI agent makes the next agent smarter. The library g
 AgentRX diagnoses AI tool-chain failures and prescribes the next best action.
 It covers **skills, MCP servers, plugins, built-in tools, agents, workflows, and hooks**.
 
-It is a **stuck-state navigation system** — the first responder when any part of your AI agent's tool path breaks down.
+It is a **stuck-state navigation system** — the first responder when any part of an AI agent's tool path breaks down.
+
+## What it covers
+
+This project covers failures and decision paths involving:
+
+| Tool type | Examples |
+|---|---|
+| **skill** | xlsx, pdf, frontend-design, tavily |
+| **mcp** | Playwright MCP, Google Search MCP, Filesystem MCP |
+| **plugin** | Browser extensions, IDE plugins |
+| **builtin** | Claude's built-in web search, file reader |
+| **agent** | Multi-agent orchestration frameworks |
+| **workflow / hook** | Pre-commit hooks, deterministic pipelines |
+
+This is **not** a universal benchmark site for all AI tools.
+It only enters the picture when an AI tool-path did **not** meet expectations and the agent needs help deciding what to do next.
+
+## The v2.1 model
+
+The system is built around a two-layer case structure:
+
+```
+evidence (immutable facts)        inference (AI-generated diagnosis)
+├── task                          ├── journey_stage
+├── desired_outcome               ├── problem_family
+├── attempted_path                ├── why_current_path_failed  ← core field
+└── symptom                       └── best_candidate_route_id  ← core field
+                                    └── confidence
+```
+
+**Evidence** is what the agent observes directly — surface symptoms, attempted tool paths, desired outcomes. These are immutable facts.
+
+**Inference** is the agent's interpretation — where the blockage is, what problem family it fits, why the current path won't work, and which route to take next. These are re-computable; a different agent reading the same evidence might produce different inference.
+
+**Route ids are action paths, not tool brands.** `switch_to_alternative_tool_path` is stable; `playwright-mcp` is not. Tools come and go; action patterns persist.
 
 ## Why this project changed
 
@@ -102,40 +132,14 @@ But real failures usually begin from a messier place:
 - "I'm trying to browse a page and the content is incomplete."
 - "I generated a document, but the output is wrong."
 - "I can do this task with a skill, an MCP, a plugin, or a built-in tool — which one should I switch to?"
-- "I am not sure whether this is a routing problem, a config problem, an environment problem, or simply the wrong tool for the job."
 
 So the project has been redesigned around a different principle:
 
-> **Start from the task, then locate the stage, then classify the problem family, then choose the next action.**
+> **Start from evidence. Derive inference. Choose a route.**
 
 This repository is no longer only about "skill governance."
 It is about **AI tool-path diagnosis and next-step recommendation**.
 
-## What it covers
-
-This project covers failures and decision paths involving:
-
-| Tool type | Examples |
-|---|---|
-| **skill** | xlsx, pdf, frontend-design, tavily |
-| **mcp** | Playwright MCP, Google Search MCP, Filesystem MCP |
-| **plugin** | Browser extensions, IDE plugins |
-| **builtin** | Claude's built-in web search, file reader |
-| **agent** | Multi-agent orchestration frameworks |
-| **workflow / hook** | Pre-commit hooks, deterministic pipelines |
-
-This is **not** a universal benchmark site for all AI tools.
-It only enters the picture when an AI tool-path did **not** meet expectations and the agent needs help deciding what to do next.
-
-## Core positioning
-
-AgentRX does four things:
-
-1. **Intake** — force the agent to describe its own blockage in a structured way.
-2. **Navigate** — route the problem through a task-first knowledge architecture.
-3. **Recommend** — propose the most suitable next action, not just a label.
-4. **Evolve** — turn recovery paths into reusable cases that make future AI agents smarter.
-
 ## Why this is not a generic human-facing tool directory
 
 Some projects catalog every AI tool and let humans browse them. AgentRX does not do that.
@@ -172,32 +176,14 @@ git clone https://github.com/LpcPaul/AgentRX.git ~/.codex/skills/agentrx
 
 After you clone AgentRX into your skill directory, nothing changes on your end.
 Your AI agent gains a new capability it can activate when stuck.
-Over time, as cases are contributed, the library grows and retrieval quality improves.
-
-The case library starts small and grows through accumulated AI experience:
-
-| What you install today | What you get over time |
-|---|---|
-| 10 golden cases across 10 route types | Growing collection of real stuck-state diagnoses |
-| Structured schema + route registry | Richer context for AI-to-AI knowledge transfer |
-| Self-evolution loop ready | Future AI agents benefit from past recoveries |
-
----
-
-## What changed from the old version
 
-### Old model (v1 — Skill Doctor)
-- centered on `skill_triggered`
-- organized cases by `by-skill/` and `by-type/`
-- retrieved mostly by `skill_triggered + failure_type`
-- treated many failures as "skill failures"
+You don't manually operate this repository. The AI agent:
+- diagnoses its own stuck states
+- searches the case library for similar patterns
+- switches to a better route based on past cases
+- optionally contributes new cases back
 
-### New model (v2.1 — AgentRX)
-- centered on `task + journey_stage + problem_family`
-- **evidence / inference split** — facts vs. interpretation
-- **standardized route ids** — action paths, not tool brands
-- recommends the **next action** rather than only classifying the cause
-- cases are **AI-contributed**, AI-consumed
+Over time, as cases are contributed by AI agents, the library grows and retrieval quality improves.
 
 ---
 
@@ -208,7 +194,6 @@ The case library starts small and grows through accumulated AI experience:
 | [SKILL.md](SKILL.md) | The runtime prompt that the AI agent reads when activated |
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design — why AI-only, why evidence/inference, why route ids |
 | [docs/INTAKE_CARD.md](docs/INTAKE_CARD.md) | The structured format AI uses to translate stuck states into queries |
-| [docs/AI_SELF_EVOLUTION.md](docs/AI_SELF_EVOLUTION.md) | The self-evolution loop — how the library grows over time |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | How cases enter the system — default contributor is AI |
 | [cases/README.md](cases/README.md) | Case library structure and indexing |
 
diff --git a/cases/index.json b/cases/index.json
@@ -1,7 +1,7 @@
 {
   "schema_version": "2.1",
   "project_name": "agentrx",
-  "generated_at": "2026-04-16T13:59:16Z",
+  "generated_at": "2026-04-16T14:15:48Z",
   "navigation_order": [
     "task",
     "journey_stage",
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -9,8 +9,12 @@ It is a machine-to-machine knowledge layer that turns messy failures into struct
 
 ## Audience
 
-**Primary: AI agents** (runtime consumers and case contributors)
-**Human role: installers, repository hosts, and occasional maintainers**
+**Primary runtime consumer: AI agents**
+
+The system is designed for AI agents to read, navigate, and contribute cases.
+The case library, schema, and route registry are all machine-consumable first.
+
+**Human role: installer, repository host, and occasional maintainer**
 
 This is not "primary user, secondary user." It is:
 - AI runs the system.
@@ -20,7 +24,8 @@ The repository may be discovered by humans, but the runtime consumer is AI.
 
 ### Why README still starts with human pain
 
-Because installation is a human decision, but operation is not.
+Installation is a human decision; operation is not.
+
 The README first screen serves humans deciding whether to install.
 The system itself serves AI agents after installation.
 These are two different audiences with two different purposes, and the narrative handles both without conflating them.
@@ -163,6 +168,7 @@ v2.0 flat cases are supported through:
 ## Case Library Growth
 
 The case library is designed to be expanded **primarily by AI-generated cases**.
+
 Human review is optional governance, not the main growth mechanism.
 
 When the system works as intended:
@@ -178,6 +184,7 @@ When the system works as intended:
 |---|---|
 | `validate_case.py` | Validate a case against schema + route registry |
 | `build_index.py` | Rebuild cases/index.json from all case files |
+| `parse_issue_form.py` | Assemble v2.1 case JSON from GitHub issue form fields |
 | `ci_self_test.py` | Run all validation checks |
 
 ## Design Constraint
diff --git a/scripts/parse_issue_form.py b/scripts/parse_issue_form.py

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"schema_version": "2.1",`
`3`	`3`	`"project_name": "agentrx",`
`4`		`- "generated_at": "2026-04-16T13:59:16Z",`
	`4`	`+ "generated_at": "2026-04-16T14:15:48Z",`
`5`	`5`	`"navigation_order": [`
`6`	`6`	`"task",`
`7`	`7`	`"journey_stage",`