Automatic Issue Creation from Failed Patrol and Hygiene Scans

[github-actions]

Strategic Improvement

Close the self-improvement loop by automatically filing GitHub issues when patrol or hygiene scans detect actionable problems. If code-review finds SOLID violations, adversarial-review finds edge cases, or hygiene finds technical debt, create labeled issues for the daemon to process. Makes platform health monitoring actionable, not just informational.

Acceptance Criteria

• --auto-issue flag for patrol commands (code-review, security-audit, hygiene, adversarial)
• Scan output analyzed for actionable findings (severity threshold configurable)
• Create GitHub issue with label shipwright-auto + severity label (P0-P6)
• Issue body includes: finding description, affected files, suggested fix, scan evidence
• Deduplication: don't create duplicate issues for same finding
• shipwright patrol-meta --auto-issue runs all patrols and files issues
• Daemon automatically picks up shipwright-auto labeled issues
• Test suite validates issue creation, deduplication, and label assignment

Context

• Priority: P6
• Complexity: fast
• Generated by: Strategic Intelligence Agent
• Strategy alignment: P6: Platform Self-Improvement (AGI-Level Readiness)

[github-actions]

⚓ Shipwright Pipeline Starting

Field	Value
Template	standard
Complexity	standard
Max Iterations	20
Triage	Closes self-improvement loop by auto-filing issues from patrol scans; requires enhancing 4 patrol commands, adding deduplication logic, and integrating with GitHub issues API.
Runner	ubuntu-latest
Risk Level	unknown
Workflow	23411464120

The autonomous pipeline is processing this issue. Updates will be posted as stages complete.

[github-actions]

[github-actions]

[github-actions]

📋 Implementation Plan

Click to expand full plan (224 lines)

Here is the complete implementation plan:

---

Plan: Automatic Issue Creation from Failed Patrol and Hygiene Scans

Socratic Design Analysis

Requirements Clarity

Minimum viable change: A shared library scripts/lib/auto-issue.sh with auto_issue_create(), auto_issue_dedup(), and auto_issue_from_findings(), plus --auto-issue flag wiring into 4 patrol commands and patrol-meta.

Implicit requirements:

• Must respect NO_GITHUB guard (codebase convention)
• Must respect rate limiting (AUTO_ISSUE_MAX, default 5)
• Must emit events via emit_event for observability
• Must integrate with decision engine signal mode when DECISION_ENGINE_ENABLED=true

Design Alternatives Considered

Alternative A: Centralized library (CHOSEN) — New scripts/lib/auto-issue.sh sourced by each patrol command. Single dedup logic, consistent format, easy to test. Blast radius: 5 existing scripts get ~15 lines each; 1 new lib; 1 new test.

Alternative B: Each command creates its own issues — Rejected: duplicated dedup logic, inconsistent formats, violates DRY.

Alternative C: Pipe to separate issue-creation command — Rejected: over-engineering; not all commands produce structured JSON. The --auto-issue flag is simpler and matches codebase conventions.

---

Component Diagram

┌──────────────────────────────────────────────────────────┐
│                    CLI Layer                              │
│  sw-code-review.sh  sw-security-audit.sh  sw-hygiene.sh │
│  sw-adversarial.sh  sw-patrol-meta.sh                    │
│         │                │              │                │
│         └───── --auto-issue flag ───────┘                │
└──────────────────────┬───────────────────────────────────┘
                       │ calls
┌──────────────────────▼───────────────────────────────────┐
│              scripts/lib/auto-issue.sh                    │
│                                                          │
│  auto_issue_create(title, body, severity, files, scan)   │
│  auto_issue_dedup(title) → bool                          │
│  auto_issue_from_findings(json_file, scan_type)          │
│  auto_issue_severity_to_priority(sev) → "P0".."P6"      │
│  auto_issue_body(desc, files, fix, evidence) → markdown  │
└──────────┬──────────────────────┬────────────────────────┘
           │                      │
    ┌──────▼──────┐    ┌─────────▼─────────┐

</details>

## ✅ Task Checklist
- [ ] Task 1: Create `scripts/lib/auto-issue.sh` with core functions
- [ ] Task 2: Create `scripts/sw-auto-issue-test.sh` with 15 test cases
- [ ] Task 3: Add `--auto-issue` to `scripts/sw-code-review.sh`
- [ ] Task 4: Add `--auto-issue` to `scripts/sw-security-audit.sh`
- [ ] Task 5: Add `--auto-issue` to `scripts/sw-hygiene.sh`
- [ ] Task 6: Add `--auto-issue` to `scripts/sw-adversarial.sh`
- [ ] Task 7: Add `--auto-issue` to `scripts/sw-patrol-meta.sh`
- [ ] Task 8: Register test in `package.json`
- [ ] Task 9: Run test suite and fix any failures

---
_Generated by `shipwright pipeline` at 2026-03-22T20:26:12Z_

[github-actions]

[github-actions]

📐 Architecture Decision Record

Click to expand ADR (1059 lines)

Architecture Decision Record: Automatic Issue Creation from Failed Patrol and Hygiene Scans

Context

Problem: Shipwright's patrol commands (code-review, security-audit, hygiene, adversarial, patrol-meta) detect quality issues but require manual triage to create actionable GitHub issues. This creates friction: findings sit in JSON reports, requiring engineers to manually file issues, leading to lost signal and duplicate effort.

Requirements:

• Automatically create GitHub issues from patrol findings
• Prevent duplicate issues (race conditions, GitHub indexing lag)
• Respect NO_GITHUB guard (offline/dry-run mode)
• Support configurable severity thresholds
• Integrate cleanly with existing 5 patrol commands without breaking changes
• Observable (emit events, rate-limit warnings, dry-run logs)

Constraints from Codebase:

• Bash 3.2 compatible (set -euo pipefail, no associative arrays)
• All patrol commands use same test harness (test-helpers.sh)
• GitHub integration via gh CLI (already in use for PR creation, checks, deployments)
• Event emission via emit_event "type" "key=val" (observability baseline)
• Issue labels for categorization (shipwright-auto, P0–P6 priority scale)
• Existing patrol output: JSON findings files with structured schema (severity, description, affected_files)

---

Decision

Chosen: Centralized shared library (scripts/lib/auto-issue.sh) with standardized functions for dedup, creation, formatting, and severity mapping. Each patrol command sources the library, normalizes its findings to a canonical JSON schema, and calls auto_issue_from_findings().

Rationale:

• Single source of truth for dedup logic, preventing duplicates across commands
• Consistency — all auto-created issues follow same format, labels, and metadata
• Maintainability — changes to dedup strategy or label format happen in one place
• Testability — 100% of logic covered by focused unit tests in one test suite
• Non-invasive — existing patrol commands change minimally (~15 lines each); no breaking changes to their APIs or output

Design Decisions

1. Deduplication Strategy: Local Cache + GitHub Search (Staged)

Check local cache (fast, ~100µs)
  ↓ (on miss)
Call gh issue list --search (slower, but authoritative)
  ↓ (on miss)
Create issue + record in local cache

Context: GitHub's search index can lag 30–60s after issue creation. Without dedup, two parallel patrol runs could create identical issues.

Decision: Two-tier dedup:

1. Local cache (~/.shipwright/auto-issue-dedup.json, 24h TTL, atomic writes with flock) — fast check, prevents same-session duplicates
2. GitHub search (gh issue list --state open --label shipwright-auto --search "exact title") — catches cross-session duplicates, tolerates indexing lag

Alternatives:

• A: GitHub search only — Pros: single source of truth / Cons: indexing lag leads to duplicates, slower per-issue (~2s per check), fails offline
• B: Exact issue ID tracking — Pros: zero dupes / Cons: requires database, breaks with issue deletion, too heavyweight

Consequences:

• Local cache must be garbage-collected (24h TTL prevents unbounded growth)
• Atomic writes with flock add ~5ms per check (acceptable)
• Offline mode (NO_GITHUB) skips GitHub search but still uses local cache

---

Generated by shipwright pipeline design stage at 2026-03-22T20:29:44Z

[github-actions]

[github-actions]

🔨 Build started — shipwright loop with 20 max iterations, 1 agent(s), model: haiku

[github-actions]

[github-actions]

[github-actions]