Output GH issues to /dist/issues folder

Author: noelsaw1

CHANGELOG.md

@@ -25,6 +25,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - **README.md**: Added GitHub Issue Creator to tools table and usage documentation
 - **Template Support**: Templates now support optional `GITHUB_REPO` field for automated issue creation
+- **GitHub Issue Footer**: Changed from broken relative links to local file paths in code blocks for better usability
+- **GitHub Issue Creator**: Made `GITHUB_REPO` truly optional - script will generate issue body without creating the issue if no repo is specified
+- **Issue Persistence**: When no GitHub repo is specified, issue bodies are now saved to `dist/issues/GH-issue-{SCAN_ID}.md` for manual copy/paste to GitHub or project management apps
+- **AI Instructions**: Updated `dist/TEMPLATES/_AI_INSTRUCTIONS.md` with complete Phase 3 (GitHub Issue Creation) workflow documentation
 
 ## [1.3.1] - 2026-01-12
 

PROJECT/3-COMPLETED/GITHUB-ISSUE-CREATION-FEATURE.md

@@ -40,14 +40,15 @@ Implemented automated GitHub issue creation from scan results with AI triage dat
 
 ## Features
 
-✅ **Auto-formatted Issues** - Clean, actionable GitHub issues with checkboxes  
-✅ **AI Triage Integration** - Shows confirmed issues vs. needs review  
-✅ **Template Integration** - Reads GitHub repo from project templates  
-✅ **Interactive Preview** - Review before creating the issue  
-✅ **Confidence Levels** - Shows AI confidence for each finding  
-✅ **File Path Cleanup** - Removes local paths for cleaner display  
-✅ **Timezone Conversion** - Converts UTC timestamps to local time  
-✅ **Report Links** - Includes links to full HTML and JSON reports
+✅ **Auto-formatted Issues** - Clean, actionable GitHub issues with checkboxes
+✅ **AI Triage Integration** - Shows confirmed issues vs. needs review
+✅ **Template Integration** - Reads GitHub repo from project templates (optional)
+✅ **Interactive Preview** - Review before creating the issue
+✅ **Confidence Levels** - Shows AI confidence for each finding
+✅ **File Path Cleanup** - Removes local paths for cleaner display
+✅ **Timezone Conversion** - Converts UTC timestamps to local time
+✅ **Local File Paths** - Shows local report paths instead of broken links
+✅ **Graceful Degradation** - Works without GitHub repo, saves to `dist/issues/` for manual use
 
 ## Usage
 
@@ -79,12 +80,17 @@ The script generates issues with:
 
 ## Testing
 
-✅ Tested with Elementor v3.34.1 scan (200 AI-triaged findings)  
-✅ Created test issue #67 in Hypercart-Dev-Tools/WP-Code-Check  
-✅ Verified issue format and content  
-✅ Verified file path cleanup  
-✅ Verified timezone conversion  
+✅ Tested with Elementor v3.34.1 scan (200 AI-triaged findings)
+✅ Tested with Hypercart Helper v1.1.4 scan (4 AI-triaged findings)
+✅ Created test issue #67 in Hypercart-Dev-Tools/WP-Code-Check
+✅ Created production issue #7 in NeochromeTeam/hypercart-helper
+✅ Verified issue format and content
+✅ Verified file path cleanup
+✅ Verified timezone conversion
 ✅ Verified interactive preview
+✅ Verified local file paths in footer (no broken links)
+✅ Verified graceful degradation without GitHub repo
+✅ Verified persistent issue files saved to `dist/issues/`
 
 ## Integration
 

README.md

@@ -171,23 +171,30 @@ See [TEMPLATES/_AI_INSTRUCTIONS.md](dist/TEMPLATES/_AI_INSTRUCTIONS.md) for deta
 Automatically create GitHub issues from scan results with AI triage data:
 
 ```bash
-# Create issue from latest scan
+# Create issue from latest scan (specify repo)
 ./dist/bin/create-github-issue.sh \
   --scan-id 2026-01-12-155649-UTC \
   --repo owner/repo
 
-# Or use template's GitHub repo
+# Or use template's GitHub repo (if GITHUB_REPO is set in template)
 ./dist/bin/create-github-issue.sh --scan-id 2026-01-12-155649-UTC
+
+# Generate issue body without creating (no repo needed)
+# Useful for manual issue creation or when repo is not specified
+./dist/bin/create-github-issue.sh --scan-id 2026-01-12-155649-UTC
+# → Saves to dist/issues/GH-issue-2026-01-12-155649-UTC.md
 ```
 
 **Features:**
 - ✅ **Auto-formatted Issues** - Clean, actionable GitHub issues with checkboxes
 - ✅ **AI Triage Integration** - Shows confirmed issues vs. needs review
-- ✅ **Template Integration** - Reads GitHub repo from project templates
+- ✅ **Template Integration** - Reads GitHub repo from project templates (optional)
 - ✅ **Interactive Preview** - Review before creating the issue
+- ✅ **Graceful Degradation** - Works without GitHub repo (generates issue body only)
+- ✅ **Persistent Issue Files** - Saves to `dist/issues/` with matching filename pattern for easy manual copy/paste
 
 **Requirements:**
-- GitHub CLI (`gh`) installed and authenticated
+- GitHub CLI (`gh`) installed and authenticated (only for creating issues)
 - Scan with AI triage data (`--ai-triage` flag)
 
 ---
@@ -218,6 +225,24 @@ WP Code Check is a **complete code quality suite** with multiple specialized too
 - **Deep Review**: Quick Scanner + Golden Rules (experimental)
 - **Legacy Audit**: Quick Scanner + Baseline + Golden Rules (experimental)
 
+### Output Directories
+
+All scan outputs are organized in the `dist/` directory:
+
+| Directory | Contents | Git Tracked | Purpose |
+|-----------|----------|-------------|---------|
+| `dist/logs/` | JSON scan results (`*.json`) | ❌ No | Machine-readable scan data |
+| `dist/reports/` | HTML reports (`*.html`) | ❌ No | Human-readable scan reports |
+| `dist/issues/` | GitHub issue bodies (`GH-issue-*.md`) | ❌ No | Manual copy/paste to GitHub or project management apps |
+| `dist/TEMPLATES/` | Project templates (`*.txt`) | ✅ Yes | Reusable scan configurations |
+
+**Filename Pattern:** All outputs use matching UTC timestamps for easy correlation:
+```
+dist/logs/2026-01-13-031719-UTC.json
+dist/reports/2026-01-13-031719-UTC.html
+dist/issues/GH-issue-2026-01-13-031719-UTC.md
+```
+
 ---
 
 ## CI/CD Integration

dist/PATTERN-LIBRARY.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0.0",
-  "generated": "2026-01-12T16:01:47Z",
+  "generated": "2026-01-13T03:17:30Z",
   "summary": {
     "total_patterns": 29,
     "enabled": 29,

dist/PATTERN-LIBRARY.md

@@ -1,7 +1,7 @@
 # Pattern Library Registry
 
 **Auto-generated by Pattern Library Manager**
-**Last Updated:** 2026-01-12 16:01:47 UTC
+**Last Updated:** 2026-01-13 03:17:30 UTC
 
 ---
 
@@ -117,6 +117,6 @@
 
 ---
 
-**Generated:** 2026-01-12 16:01:47 UTC
+**Generated:** 2026-01-13 03:17:30 UTC
 **Version:** 1.0.0
 **Tool:** Pattern Library Manager

dist/TEMPLATES/_AI_INSTRUCTIONS.md

@@ -4,40 +4,41 @@
 
 Complete end-to-end workflow:
 1. **Phase 1a**: Check for existing templates in `dist/TEMPLATES/`
-2. **Phase 1b**: Complete template if needed (extract metadata)
+2. **Phase 1b**: Complete template if needed (extract metadata + optional GitHub repo)
 3. **Phase 1c**: Run scan using template or direct path
 4. **Phase 2**: AI-assisted triage of findings
-   
-**IN PROGRESS - NOT READY YET:**
-5. **Phase 3**: Send AI confirmed issues into a single GitHub issue via GitHub CLI
-This will require users to setup GitHub CLI (separately from GH desktop app) and authenticate their GitHub account 
+5. **Phase 3**: Create GitHub issue (automated or manual)
 
 ### End-to-End Execution Mode
 
 When a user requests **"Run template [name] end to end"**, execute the complete automated pipeline:
 
 1. **Run scan** → Generate JSON log (Phase 1c)
 2. **AI triage** → Analyze findings and update JSON (Phase 2)
-3. **Generate HTML** → Create final report with AI summary
+3. **Generate HTML** → Create final report with AI summary (Phase 2)
+4. **Create GitHub issue** → Automated or manual (Phase 3)
 
 **No manual intervention required** - the AI agent handles all phases automatically.
 
 **Example user requests:**
 - "Run template gravityforms end to end"
 - "Execute woocommerce end to end"
 - "Run gravityforms complete workflow"
+- "Scan, triage, and create GitHub issue for hypercart-helper"
 
 **AI Agent Actions:**
 1. Execute scan: `dist/bin/run [template-name]` (wait for completion)
 2. Locate generated JSON: `dist/logs/[TIMESTAMP].json`
 3. Perform AI triage analysis (read JSON, analyze findings)
 4. Update JSON with `ai_triage` section
 5. Regenerate HTML: `python3 dist/bin/json-to-html.py [json] [html]`
-6. Report completion with final HTML report location
+6. Create GitHub issue: `dist/bin/create-github-issue.sh --scan-id [TIMESTAMP]`
+7. Report completion with final HTML report and GitHub issue URL (if created)
 
 **Error Handling:**
 - If scan fails → stop and report error
-- If triage fails → generate basic HTML without AI summary, report issue
+- If triage fails → generate basic HTML without AI summary, report issue to user
+- If GitHub issue creation fails → issue body saved to `dist/issues/` for manual use
 - Provide progress updates as each phase completes
 
 ---
@@ -310,6 +311,137 @@ The HTML report will now show:
 
 ---
 
+## Phase 3: GitHub Issue Creation
+
+After AI triage is complete, create a GitHub issue with the findings.
+
+### When to Use
+
+- **Automatically**: When user requests "end to end" execution with GitHub repo configured
+- **Manually**: User explicitly asks "Create GitHub issue for this scan"
+- User wants to track findings in their project management system
+- User needs to share findings with their team
+
+### Prerequisites
+
+- ✅ Scan completed with JSON log
+- ✅ AI triage performed (JSON has `ai_triage` section)
+- ⚠️ GitHub CLI (`gh`) installed and authenticated (only for automated creation)
+- ⚠️ GitHub repo specified (via `--repo` flag or `GITHUB_REPO` in template) - **OPTIONAL**
+
+### Workflow Steps
+
+**Step 1: Determine the scan ID**
+```bash
+# Scan ID is the timestamp from the JSON filename
+# Example: dist/logs/2026-01-13-031719-UTC.json
+# Scan ID: 2026-01-13-031719-UTC
+```
+
+**Step 2: Run the GitHub issue creator**
+
+**Option A: Automated (with GitHub repo)**
+```bash
+# If template has GITHUB_REPO field
+./dist/bin/create-github-issue.sh --scan-id 2026-01-13-031719-UTC
+
+# Or specify repo manually
+./dist/bin/create-github-issue.sh --scan-id 2026-01-13-031719-UTC --repo owner/repo
+```
+
+**Option B: Manual (without GitHub repo)**
+```bash
+# No repo specified - saves to dist/issues/ for manual copy/paste
+./dist/bin/create-github-issue.sh --scan-id 2026-01-13-031719-UTC
+# → Saves to: dist/issues/GH-issue-2026-01-13-031719-UTC.md
+```
+
+**Step 3: Handle the result**
+
+**If automated creation succeeds:**
+- GitHub issue URL will be displayed
+- Issue includes:
+  - Scan metadata (plugin/theme name, version, date)
+  - Summary counts (confirmed issues, needs review, false positives)
+  - Confirmed issues section with checkboxes
+  - Needs review section with confidence levels
+  - Local file paths to reports
+
+**If no GitHub repo specified:**
+- Issue body saved to `dist/issues/GH-issue-{SCAN_ID}.md`
+- User can manually copy/paste to:
+  - GitHub (create issue manually)
+  - Jira, Linear, Asana, Trello, Monday.com
+  - Internal documentation
+  - Email or Slack
+
+### Output Locations
+
+All outputs use matching UTC timestamps for easy correlation:
+
+```
+dist/logs/2026-01-13-031719-UTC.json          # Scan data with AI triage
+dist/reports/2026-01-13-031719-UTC.html       # HTML report with AI summary
+dist/issues/GH-issue-2026-01-13-031719-UTC.md # Issue body (if no repo)
+```
+
+### GitHub Issue Format
+
+The generated issue includes:
+
+```markdown
+# WP Code Check Review - {SCAN_ID}
+
+**Scanned:** {Date in local timezone}
+**Plugin/Theme:** {Name} v{Version}
+**Scanner Version:** {Version}
+
+**Summary:** {total} findings | {confirmed} confirmed issues | {needs_review} need review | {false_positives} false positives
+
+---
+
+## ✅ Confirmed by AI Triage
+- [ ] **{Rationale}...**
+  `{file}:{line}` | Rule: `{rule_id}`
+
+---
+
+## 🔍 Most Critical but Unconfirmed
+
+- [ ] **{Classification} ({confidence} confidence)**
+  `{file}:{line}` | Rule: `{rule_id}`
+
+---
+
+**Local Reports:**
+
+```
+HTML Report: dist/reports/{SCAN_ID}.html
+JSON Report: dist/logs/{SCAN_ID}.json
+```
+
+**Powered by:** [WPCodeCheck.com](https://wpCodeCheck.com)
+```
+
+### Error Handling
+
+| Scenario | Behavior | User Action |
+|----------|----------|-------------|
+| No GitHub repo specified | ✅ Saves to `dist/issues/` | Copy/paste manually to GitHub or PM app |
+| GitHub CLI not installed | ❌ Error message | Install `gh` CLI or use manual workflow |
+| GitHub CLI not authenticated | ❌ Error message | Run `gh auth login` |
+| No AI triage data | ⚠️ Warning | Run AI triage first (Phase 2) |
+| Invalid scan ID | ❌ Error message | Check scan ID matches JSON filename |
+
+### Best Practices
+
+1. **Always run AI triage first** - GitHub issues are more useful with confirmed/false positive classifications
+2. **Use templates with GITHUB_REPO** - Enables fully automated workflow
+3. **Review before creating** - Script shows preview and asks for confirmation
+4. **Keep issue bodies** - Files in `dist/issues/` are not tracked by Git, safe to keep for reference
+
+---
+
 ## Common False Positive Patterns
 
 | Rule ID | Common False Positive Reason |