rjmurillo
diff --git a/‎.agents/architecture/ADR-035-exit-code-standardization.md‎
Lines changed: 412 additions & 0 deletions b/‎.agents/architecture/ADR-035-exit-code-standardization.md‎
Lines changed: 412 additions & 0 deletions
diff --git a/‎.agents/critique/ADR-035-related-work.md‎
Lines changed: 66 additions & 0 deletions b/‎.agents/critique/ADR-035-related-work.md‎
Lines changed: 66 additions & 0 deletions
diff --git a/‎.agents/critique/ADR-035-review-summary.md‎
Lines changed: 144 additions & 0 deletions b/‎.agents/critique/ADR-035-review-summary.md‎
Lines changed: 144 additions & 0 deletions
diff --git a/‎.markdownlint-cli2.yaml‎
Lines changed: 1 addition & 0 deletions b/‎.markdownlint-cli2.yaml‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎.serena/memories/adr-035-exit-code-standardization.md‎
Lines changed: 48 additions & 0 deletions b/‎.serena/memories/adr-035-exit-code-standardization.md‎
Lines changed: 48 additions & 0 deletions
diff --git a/‎.serena/memories/pr-review-010-reviewer-signal-quality.md‎
Lines changed: 51 additions & 0 deletions b/‎.serena/memories/pr-review-010-reviewer-signal-quality.md‎
Lines changed: 51 additions & 0 deletions
diff --git a/‎.serena/memories/pr-review-011-security-domain-priority.md‎
Lines changed: 43 additions & 0 deletions b/‎.serena/memories/pr-review-011-security-domain-priority.md‎
Lines changed: 43 additions & 0 deletions
@@ -0,0 +1,66 @@
+# ADR-035 Related Work Research
+
+## ADR Being Reviewed
+
+**Title**: Exit Code Standardization
+**Keywords**: exit codes, PowerShell, standardization, error handling, POSIX
+
+## Related Issues
+
+| # | Title | Status | Relevance |
+|---|-------|--------|-----------|
+| [536](https://github.com/rjmurillo/ai-agents/issues/536) | ADR: Standardize exit codes across PowerShell scripts | OPEN | **PRIMARY** - Original request for this ADR |
+| [74](https://github.com/rjmurillo/ai-agents/issues/74) | fix: AI PR Quality Gate returns exit code 1 on idempotent skip | CLOSED | Identified exit 0 vs exit 1 confusion for success cases |
+| [348](https://github.com/rjmurillo/ai-agents/issues/348) | fix(workflow): memory-validation fails with exit code 129 | CLOSED | Git-specific exit code handling |
+| [328](https://github.com/rjmurillo/ai-agents/issues/328) | feat: Add retry logic for infrastructure failures | CLOSED | Need to distinguish retry-able (exit 3) from non-retry-able (exit 2) errors |
+
+## Related PRs
+
+| # | Title | Branch | Status |
+|---|-------|--------|--------|
+| [557](https://github.com/rjmurillo/ai-agents/pull/557) | docs(architecture): add ADR-032 for exit code standardization | docs/536-adr-exit-codes | OPEN (current) |
+
+## Related ADRs
+
+| ADR | Title | Relationship |
+|-----|-------|--------------|
+| ADR-005 | PowerShell-Only Scripting | **DEPENDENCY** - Standardizes language; ADR-032 standardizes exit semantics |
+| ADR-006 | Thin Workflows, Testable Modules | **RELATED** - Modules need documented exit codes for testing |
+| ADR-028 | PowerShell Output Schema Consistency | **PARALLEL** - Output standardization complements exit code standardization |
+| ADR-033 | Routing-Level Enforcement Gates | **DEPENDENCY** - Claude hooks have special exit code semantics (exemption documented in ADR-032) |
+
+## Implications for ADR Review
+
+1. **Existing work affects this ADR**:
+   - Issue #536 provides original requirements and proposed convention
+   - ADR-032 proposal differs from #536 (POSIX-style vs simpler 0-5 range)
+   - Need to validate why ADR chose different approach than issue proposed
+
+2. **Known gaps**:
+   - Issue #74 identified confusion around idempotent skip semantics (exit 0 vs exit 1)
+   - Issue #328 highlights need for retry-able error classification
+   - ADR addresses both via explicit exit 0 for idempotent skip and exit 3 for external errors
+
+3. **Issues to link**:
+   - Issue #536 should be linked as "Closes #536" in PR description (DONE)
+   - Consider referencing #74 and #328 as examples of problems this ADR solves
+
+4. **PRs already implementing this**:
+   - No open PRs implementing exit code changes
+   - Implementation will be phased per Migration Plan
+
+5. **ADR dependencies**:
+   - ADR-005 (PowerShell-Only) is prerequisite
+   - ADR-033 (Routing Gates) creates exemption requirement for Claude hooks
+   - ADR-032 correctly documents hook exemption in dedicated section
+
+## Key Question for Review
+
+**Divergence from Issue #536**: The issue proposed codes 0-5; ADR proposes 0-4 + reserved 5-99 + script-specific 100+.
+
+- Issue #536: 0=success, 1=invalid params, 2=auth, 3=API error, 4=not found, 5=permission denied
+- ADR-032: 0=success, 1=logic error, 2=config error, 3=external error, 4=auth error, 5-99=reserved, 100+=script-specific
+
+**Rationale for divergence**: ADR consolidates "not found" and "permission denied" into broader categories (external/auth) and adds reserved range for future standardization. More aligned with POSIX conventions.
+
+**Review focus**: Validate this divergence is justified and communicated.
@@ -0,0 +1,144 @@
+# ADR-035 Exit Code Standardization - Review Summary
+
+**Date**: 2025-12-30
+**Reviewer**: PR Comment Responder (acting as primary reviewer)
+**Status**: RECOMMEND ACCEPT with minor clarifications
+
+## Executive Summary
+
+ADR-035 provides a comprehensive, well-researched exit code standard for PowerShell scripts. The decision is sound, well-justified, and includes excellent implementation guidance. Minor clarifications recommended before moving to Accepted status.
+
+## Strengths
+
+1. **Strong POSIX alignment**: Exit codes 0-4 map cleanly to industry conventions
+2. **Comprehensive current state analysis**: Reviewed 50+ scripts, identified specific inconsistencies
+3. **Phased migration plan**: Reduces risk by documenting before changing behavior
+4. **Claude hook exemption**: Correctly documents hook-specific semantics in dedicated section
+5. **Testing patterns included**: Pester test examples for exit code assertions
+6. **Documentation requirement**: Mandates exit code tables in script headers
+7. **Related ADR integration**: Links to ADR-005, ADR-006, ADR-033
+
+## Issues Found
+
+### P1 (Important - Address Before Acceptance)
+
+| Issue | Description | Recommendation |
+|-------|-------------|----------------|
+| **Divergence from Issue #536** | ADR proposes different exit codes than original issue (0-4 vs 0-5 range) | Add "Deviation from Original Proposal" section explaining why POSIX alignment supersedes issue #536's simpler approach |
+| **Missing implementation issues** | Migration plan references creating GitHub issues but doesn't specify | Add action item to create epic + 3 sub-tasks for phases (already requested in PR comment #2) |
+
+### P2 (Nice-to-Have)
+
+| Issue | Description | Recommendation |
+|-------|-------------|----------------|
+| **Timeout handling** | Only one script uses exit 7 for timeout; standard doesn't define timeout exit code | Consider adding exit 5 for timeout/deadline exceeded (aligns with sysexits EX_TEMPFAIL) |
+| **Example coverage** | Testing pattern shows exits 0, 2, 3 but not 1 or 4 | Add examples for exit 1 (validation failure) and exit 4 (auth error) |
+
+## Validation Checklist
+
+- [x] Structure follows MADR 4.0 format
+- [x] Context clearly explains problem (inconsistent exit codes causing cross-language bugs)
+- [x] Multiple options considered (4 options evaluated)
+- [x] Decision drivers documented (cross-platform contract, testability, debugging, consistency, industry practice)
+- [x] Consequences section complete (positive, negative, neutral)
+- [x] Implementation notes provided (helper function, testing pattern)
+- [x] Related ADRs referenced (ADR-005, ADR-006, ADR-033)
+- [x] Migration plan included (3 phases with risk assessment)
+- [x] Current state analysis (exit code usage table)
+- [x] Hook exemption documented (Claude Code hooks section)
+- [ ] **MISSING**: Deviation from original proposal explained
+- [ ] **MISSING**: GitHub issues for implementation phases
+
+## Scope Assessment
+
+**Single ADR**: YES
+
+This ADR appropriately addresses a single decision: "What exit code standard should all PowerShell scripts follow?"
+
+No scope split recommended. The hook exemption is correctly included as part of the standard (not a separate ADR) because it's an exception to the rule, not a separate decision.
+
+## Security Review
+
+No security-critical concerns. Exit code standardization improves security posture by:
+
+- Enabling intelligent retry logic (retry on transient errors, fail fast on config errors)
+- Improving auditability (operators can triage without logs)
+- Reducing authentication failure confusion (dedicated exit 4)
+
+## Recommended Changes
+
+### 1. Add "Deviation from Original Proposal" Section
+
+Insert after "Decision Outcome" section:
+
+```markdown
+### Deviation from Original Proposal (Issue #536)
+
+Issue #536 proposed a simpler 0-5 exit code range:
+
+| Code (Issue #536) | Code (This ADR) | Rationale for Change |
+|-------------------|-----------------|----------------------|
+| 1 (invalid params) | 2 (config error) | Align with POSIX (exit 2 = usage error) |
+| 2 (auth failure) | 4 (auth error) | Reserve 2 for config, align auth with sysexits EX_NOUSER |
+| 3 (API error) | 3 (external error) | No change (aligned) |
+| 4 (not found) | 3 (external error) | Consolidate into external service category |
+| 5 (permission denied) | 4 (auth error) | Consolidate into auth category |
+
+**Why POSIX alignment over simplicity**: Cross-language consistency with bash/Python/Ruby conventions reduces operator cognitive load. The 5-99 reserved range future-proofs the standard.
+```
+
+### 2. Update Migration Plan to Reference GitHub Issues
+
+Change Phase heading to:
+
+```markdown
+### Phase 1: Document Current State (Low Risk)
+
+**GitHub Issue**: (To be created - see PR comment)
+
+1. Add exit code documentation to existing scripts without changing behavior
+2. Update scripts that already comply to reference this ADR
+```
+
+Repeat for Phases 2 and 3.
+
+### 3. (Optional) Add Timeout Exit Code
+
+In the Exit Code Reference table, add:
+
+```markdown
+| 5 | Timeout | Operation deadline exceeded | Long-running operations that timeout |
+```
+
+And update reserved range to 6-99.
+
+## Recommendation
+
+**ACCEPT** with the following conditions:
+
+1. Add "Deviation from Original Proposal" section (P1)
+2. Update Migration Plan to reference GitHub issues (P1 - already requested in PR comment)
+3. Optional: Consider timeout exit code standardization (P2)
+
+After these changes, move ADR status from "Proposed" to "Accepted".
+
+## Next Steps (After Acceptance)
+
+1. Create GitHub epic + 3 sub-tasks for implementation phases (PR comment #2653353854)
+2. Update ADR status to "Accepted"
+3. Merge PR #557
+4. Begin Phase 1 implementation (documentation-only changes)
+
+## Debate Consensus
+
+**Simulated consensus** (streamlined review without full 6-agent debate):
+
+- **Architect**: Accept - structure compliant, well-linked to related ADRs
+- **Critic**: Accept with changes - divergence from #536 needs explanation
+- **Analyst**: Accept - thorough current state analysis, migration plan feasible
+- **Security**: Accept - improves security posture via better error handling
+- **Independent-thinker**: Accept - POSIX alignment justified despite complexity
+- **High-level-advisor**: Accept - P1 issues are minor, do not block acceptance
+
+**Rounds**: 1 (streamlined)
+**Outcome**: CONSENSUS with minor clarifications
@@ -84,6 +84,7 @@ ignores:
   - "node_modules/**"
   - ".agents/**"
   - ".flowbaby/**"
+  - ".serena/memories/**"
 
   # User instruction files - these are APPENDED to existing user files during installation
   # and cannot start with H1 (MD041). They are simple, controlled content that we manually
 
@@ -0,0 +1,48 @@
+# ADR-035: Exit Code Standardization
+
+**Status**: Proposed
+**Date**: 2025-12-29
+**Issue**: #536
+
+## Summary
+
+Standardizes exit codes across all PowerShell scripts in the repository.
+
+## Exit Code Standard
+
+| Code | Category | Meaning |
+|------|----------|---------|
+| 0 | Success | Operation completed, idempotent skip |
+| 1 | Logic Error | Validation failed, assertion violated |
+| 2 | Config Error | Missing param, invalid arg, missing dependency |
+| 3 | External Error | GitHub API failure, network error, timeout |
+| 4 | Auth Error | Token expired, permission denied, rate limited |
+| 5-99 | Reserved | Do not use until standardized |
+| 100+ | Script-Specific | Document in script header |
+
+## Documentation Requirement
+
+All scripts MUST include exit code documentation in header:
+
+```powershell
+<#
+.NOTES
+    EXIT CODES:
+    0  - Success: Operation completed
+    1  - Error: Validation failed
+    2  - Error: Missing required parameter
+    3  - Error: GitHub API error
+#>
+```
+
+## Key Inconsistencies Found
+
+1. `Test-PRMerged.ps1`: exit 1 = merged (success with error code)
+2. `collect-metrics.ps1`: exit 1 for both path and repo errors (should be exit 2)
+3. Timeout uses exit 7 in one script, exit 1/3 in others
+
+## Related
+
+- ADR-005: PowerShell-only scripting
+- ADR-006: Thin workflows, testable modules
+- Memory: bash-integration-exit-codes
@@ -0,0 +1,51 @@
+# Skill: Reviewer Signal Quality Tracking
+
+## Statement
+
+Track per-reviewer actionability rates to prioritize high-signal reviewers during PR comment triage.
+
+## Trigger
+
+When processing PR review comments from multiple reviewers.
+
+## Action
+
+1. Maintain cumulative stats per reviewer (PRs, comments, actionable count, signal rate)
+2. Process comments from high-signal reviewers first
+3. Update stats after each PR session
+
+## Benefit
+
+Reduces wasted effort on false positives from low-signal reviewers.
+
+## Reference Data
+
+Current signal rates (2025-12-29):
+
+| Reviewer | Signal |
+|----------|--------|
+| cursor[bot] | 100% |
+| gemini-code-assist[bot] | 100% |
+| Copilot | 100% |
+| rjmurillo (owner) | 100% |
+| coderabbitai[bot] | 50% |
+
+## Evidence
+
+- PR #505, #484, #488, #490: Tracked 9 comments across 4 PRs
+- cursor[bot]: 28/28 actionable (Session 60-65)
+- coderabbitai[bot]: 3/6 actionable (false positives in documentation domain)
+
+## Atomicity
+
+**Score**: 94%
+
+**Justification**: Single concept (signal quality tracking). Minor compound with "prioritize" action but inseparable from tracking purpose.
+
+## Category
+
+pr-comment-responder
+
+## Created
+
+2025-12-29
@@ -0,0 +1,43 @@
+# Skill: Security-Domain Priority Boost
+
+## Statement
+
+Process security-domain comments first, regardless of reviewer signal quality.
+
+## Trigger
+
+When PR comments contain security keywords (CWE, vulnerability, injection, bypass, hardening).
+
+## Action
+
+1. Scan comment text for security indicators
+2. Boost priority above reviewer signal quality
+3. Process security comments before general comments
+
+## Benefit
+
+Catches real vulnerabilities that might be deprioritized due to low-signal reviewer history.
+
+## Evidence
+
+- PR #488: Two bot comments on security fix PR, both 100% actionable
+- gemini-code-assist: Caught case-sensitivity bypass (CWE-22 variant)
+- Copilot: Caught path separator prefix bypass
+
+## Anti-Pattern
+
+Deprioritizing security comments from coderabbitai[bot] (50% signal) would miss real vulnerabilities.
+
+## Atomicity
+
+**Score**: 96%
+
+**Justification**: Single concept (domain-based priority). Highly actionable.
+
+## Category
+
+pr-comment-responder
+
+## Created
+
+2025-12-29