merge: resolve conflicts with main in traceability intake

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rjmurillo-bot

.agents/AGENT-SYSTEM.md

@@ -36,7 +36,7 @@ Task(subagent_type="analyst", prompt="Investigate API latency issues")
 
 ### Agent Count
 
-This system includes **19 specialized agents** organized into 5 categories.
+This system includes **20 specialized agents** organized into 5 categories.
 
 ---
 
@@ -304,6 +304,40 @@ Create a threat model and identify required controls.
 
 ---
 
+#### merge-resolver
+
+**File**: `src/claude/merge-resolver.md`
+
+**Role**: Resolves git merge conflicts by analyzing commit history and code intent
+
+**Specialization**: Git conflict analysis, intent classification, heuristic-based resolution
+
+**Input**:
+- PR number or branch name with conflicts
+- Base and head branch references
+
+**Output**:
+- Resolved conflict files (staged)
+- Resolution report with confidence scores
+- Merge commit with rationale
+
+**Delegates To**: None (returns to orchestrator)
+
+**Called By**: orchestrator, implementer, qa
+
+**When to Use**:
+- PR has merge conflicts with base branch
+- Rebase failures need systematic resolution
+- Automated conflict resolution for known patterns
+
+**Example Invocation**:
+```text
+@merge-resolver Resolve conflicts on PR #123. The PR branch has diverged
+from main with conflicts in 3 source files.
+```
+
+---
+
 ### 2.3 Quality Agents
 
 #### critic

.agents/analysis/126-skillbook-deduplication-investigation.md

@@ -0,0 +1,128 @@
+# Investigation: Skillbook Deduplication in Retrospective Workflow
+
+**Issue**: #126
+**Date**: 2026-02-24
+**Status**: Complete
+
+## Context
+
+The 2025-12-16 Phase 4 retrospective (`2025-12-16-phase4-handoff-validation.md`)
+noted: "Skillbook deduplication check referenced but unclear if functioning."
+This investigation traces the retrospective-to-skillbook pipeline and documents
+gaps in the deduplication mechanism.
+
+## Findings
+
+### 1. Skillbook Deduplication Logic
+
+**Location**: `src/claude/skillbook.md`, lines 97-124
+
+The skillbook agent defines a Pre-ADD Checklist with three steps:
+
+1. Read `memory-index.md` for domain routing
+2. Read the relevant domain index (`skills-*-index.md`)
+3. Search activation vocabulary for similar keywords
+
+**Similarity threshold**: 70%. Below 70% triggers ADD. Above 70% triggers UPDATE.
+Exact match triggers REJECT.
+
+**Implementation**: Prompt-based only. The agent prompt instructs the LLM to
+perform deduplication, but no automated tool enforces it. The prompt references
+`Search-Memory.ps1` for lexical search, but that script does not exist in the
+repository.
+
+**Memory router** (`memory_core/memory_router.py`): Provides SHA-256 hash-based
+deduplication for merging search results across Serena and Forgetful backends.
+This deduplicates identical content across sources. It does not compute semantic
+similarity between skills.
+
+### 2. Retrospective to Skillbook Handoff
+
+**Location**: `src/claude/retrospective.md`, Phases 4-5
+
+The retrospective agent defines a structured pipeline:
+
+- **Phase 4** (line 645): Extract learnings with atomicity scoring
+- **Phase 5** (line 889): Recursive learning extraction with skillbook delegation
+- **Structured Handoff** (line 1270): Mandatory output format with skill
+  candidates, memory updates, and git operations
+
+The handoff format is well-specified. It includes skill ID, statement, atomicity
+score, operation type, and target file. The retrospective agent recommends
+routing to the skillbook agent, which the orchestrator handles.
+
+**Enforcement**: None. The handoff relies on agent compliance with prompt
+instructions. No validation script, CI check, or gate verifies that the
+skillbook agent ran deduplication before persisting a skill.
+
+### 3. Evidence from 2025-12-16 Retrospective
+
+The retrospective that triggered this issue confirms the gap:
+
+> "Deduplication Check: Placeholder for now (no existing skills to compare)"
+> "Need actual skillbook integration to make this meaningful"
+> "Compare Against Skillbook: Once skills are stored, test deduplication check
+> with real data"
+
+At the time, the skillbook contained no skills to deduplicate against. The
+deduplication table in the retrospective template was empty.
+
+### 4. Current State of Skill Storage
+
+Skills are stored as atomic markdown files in `.serena/memories/` with domain
+indexes (`skills-*-index.md`). The memory-index hierarchy (L1 -> L2 -> L3)
+provides keyword-based routing. This supports manual deduplication via keyword
+overlap checking, but does not automate similarity scoring.
+
+## Gap Summary
+
+| Component | Specified | Implemented | Gap |
+|-----------|-----------|-------------|-----|
+| Deduplication logic | Yes (prompt) | Prompt-only | No automated enforcement |
+| Similarity threshold (70%) | Yes (prompt) | No tooling | LLM judgment only |
+| `Search-Memory.ps1` | Referenced | Does not exist | Missing script |
+| Memory router dedup | SHA-256 hash | Yes | Exact-match only, no semantic similarity |
+| Handoff format | Yes (structured) | Prompt-only | No validation gate |
+| Retrospective -> skillbook routing | Yes (orchestrator) | Manual | No automated trigger |
+
+## Remediation Plan
+
+### Short-term (P2, low effort)
+
+1. **Remove `Search-Memory.ps1` references** from `skillbook.md`. Replace with
+   the actual available tool: `memory_router.py` CLI or Serena `read_memory`
+   tool for keyword search.
+
+2. **Add deduplication verification to retrospective template**. The
+   "Deduplication Check" table (retrospective.md line 782) should include a
+   column for "Tool Used" to make it auditable.
+
+### Medium-term (P1, moderate effort)
+
+3. **Add keyword overlap scoring to memory router**. Extend `memory_router.py`
+   with a function that computes Jaccard similarity between activation keywords
+   of existing skills and a proposed skill. This replaces LLM-based similarity
+   judgment with a deterministic metric.
+
+4. **Create a `check_skill_duplicate.py` script**. Accept a proposed skill
+   statement and keywords. Search existing skills. Return similarity score and
+   most similar match. Exit code 0 if novel, 1 if duplicate.
+
+### Long-term (P2, higher effort)
+
+5. **Add CI validation for skill uniqueness**. Run the duplicate check script
+   on any PR that adds files to `.serena/memories/`. Block merge if similarity
+   exceeds threshold without explicit override.
+
+6. **Automate retrospective -> skillbook routing**. When a retrospective
+   artifact contains a Handoff Summary with skill candidates, trigger the
+   skillbook agent automatically.
+
+## Related Files
+
+| File | Role |
+|------|------|
+| `src/claude/skillbook.md` | Skillbook agent prompt with dedup checklist |
+| `src/claude/retrospective.md` | Retrospective agent prompt with handoff format |
+| `.claude/skills/memory/memory_core/memory_router.py` | Memory router with hash-based dedup |
+| `.agents/retrospective/2025-12-16-phase4-handoff-validation.md` | Original retrospective citing the gap |

.agents/analysis/spec-generator-evaluation.md

@@ -0,0 +1,72 @@
+# Spec-Generator Evaluation: Skill vs No Action
+
+## Decision
+
+**No Action Needed** (Outcome A)
+
+The spec-generator agent already produces consistent EARS output when invoked. Format
+inconsistency originates from manual spec creation that bypasses the agent entirely.
+
+## Evidence
+
+### Compliance Analysis (10 spec files)
+
+| Metric | Count | Percentage |
+|--------|-------|------------|
+| EARS-compliant specs | 4 | 40% |
+| Non-compliant specs | 6 | 60% |
+| Duplicate IDs | 3 pairs | REQ-001, DESIGN-001, TASK-001 |
+
+### Agent-Generated vs Manual Specs
+
+| Origin | Files | EARS Compliant | Traceability |
+|--------|-------|----------------|--------------|
+| Agent-generated | REQ-001-pr-comment-handling, REQ-002-pr-comment-triage, DESIGN-001-pr-comment-processing, TASK-001/002/003-pr-* | Yes | Complete chain |
+| Manual | REQ-001, REQ-a01, DESIGN-001, TASK-001 | No | Broken or missing |
+
+### Evaluation Questions (from issue 617)
+
+| Question | Finding | Implication |
+|----------|---------|-------------|
+| Are specs currently inconsistent? | Yes, 60% non-compliant | Problem exists |
+| Is EARS format not being followed? | Only when agent is bypassed | Agent works correctly |
+| Is traceability chain broken? | Yes, for manual specs only | Usage problem, not capability |
+| Does spec-generator agent already produce consistent output? | Yes | No action needed on agent |
+
+## Root Cause
+
+The spec-generator agent prompt (`.claude/agents/spec-generator.md`) contains:
+
+- Complete EARS templates (WHEN/THE SYSTEM SHALL/SO THAT)
+- All five EARS patterns (Ubiquitous, Event-Driven, State-Driven, Optional, Unwanted)
+- YAML frontmatter schemas with validation rules
+- Traceability chain enforcement (REQ to DESIGN to TASK)
+- Anti-pattern checklist
+
+When invoked, the agent produces compliant output. The inconsistency comes from specs
+created without the agent.
+
+## Why a Skill Would Not Help
+
+| Factor | Assessment |
+|--------|------------|
+| Agent output quality | Already deterministic and consistent |
+| Skill duplication | Would replicate agent prompt content |
+| Real gap | Usage enforcement, not format capability |
+| Better fix | "Do Router" gate (ADR-033 Phase 4) to force spec-generator routing |
+
+## Recommendation
+
+1. **No skill creation**. The agent handles format consistency.
+2. **Phase 4 consideration**: A future "Do Router" gate could enforce spec-generator
+   routing when spec files are created. This belongs in ADR-033 Phase 4, not Phase 2.
+3. **Cleanup**: Resolve duplicate IDs and convert manual specs to EARS format as
+   separate maintenance work.
+
+## References
+
+- Issue: [#617](https://github.com/rjmurillo/ai-agents/issues/617)
+- Parent: [#615](https://github.com/rjmurillo/ai-agents/issues/615)
+- Agent prompt: `.claude/agents/spec-generator.md`
+- Spec schemas: `.agents/governance/spec-schemas.md`
+- ADR-033: `.agents/architecture/ADR-033-routing-level-enforcement-gates.md`

.agents/architecture/ADR-033-routing-level-enforcement-gates.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Proposed
+Accepted
 
 ## Date
 
@@ -136,6 +136,7 @@ Instead of exit code 2, hooks can output JSON with `decision: "deny"` and exit 0
 | **QA Validation** | `gh pr create` | `.agents/qa/` report exists | JSON deny |
 | **Critic Review** | `gh pr merge` | Critic agent invoked in transcript | JSON deny |
 | **ADR Existence** | `gh pr create --head feat/*` | ADR file exists for features | JSON deny |
+| **Retrospective** | `git push` | Retrospective evidence in session or file | Exit code 2 |
 
 ### Hook Configuration
 
@@ -380,6 +381,21 @@ SkillCreator enforces:
 2. Block PR merge without critic review evidence
 3. Consider prompt-based hook for intelligent detection
 
+### Phase 3.5: Retrospective Gate (Issue #618)
+
+Implemented `invoke_retrospective_gate.py` to enforce retrospective before push:
+
+1. **Trigger**: `git push` commands
+2. **Evidence Requirements** (any satisfies):
+   - Retrospective section in session log (`## Retrospective`)
+   - Retrospective file in `.agents/retrospective/` for today
+   - Reference to retrospective file in session log
+3. **Bypass Conditions**:
+   - Documentation-only changes (auto-detected)
+   - Trivial sessions (<10 minutes, single file change)
+   - `SKIP_RETROSPECTIVE_GATE=true` environment variable
+4. **Hook Configuration**: Added to `.claude/settings.json` under `Bash(git push*)` matcher
+
 ### Phase 4: "Do Router" Integration
 
 1. Add keyword-based mandatory routing
@@ -448,7 +464,7 @@ flowchart TB
 
 ---
 
-*ADR Version: 1.2*
+*ADR Version: 1.3*
 *Created: 2025-12-30*
-*Updated: 2025-12-30 - Added SkillCreator guidance for gate-related skill creation*
+*Updated: 2026-02-20 - Added Retrospective Gate implementation (Issue #618)*
 *Note: ADR-032 reserved for Exit Code Standardization (PR #557)*