# Canonical Completion Gate

**Authority**: This document defines the single source of truth for marking issues as `done`. All skills must reference this document rather than duplicating partial rules.

## Completion Gate Checklist

An issue **CANNOT** be marked `done` until ALL applicable checks pass:

### 1. Validation Passed
- [ ] Linting passes with no new errors
- [ ] Type checking passes (if applicable)
- [ ] Formatting is applied
- [ ] Tests pass (no regressions)

### 2. Baseline Comparison (if baseline exists)
- [ ] Baseline comparison completed
- [ ] No new errors introduced
- [ ] No new warnings introduced (or documented as accepted)
- [ ] Test coverage not decreased

### 3. Review Completed
- [ ] Code review performed at appropriate depth
- [ ] No blocking findings remain unaddressed
- [ ] Security considerations reviewed (if applicable)

### 4. Archival to history.md
- [ ] Issue moved from priority file to `history.md`
- [ ] Completion date recorded
- [ ] Brief "Delivered:" summary included

---

## Confidence-Aware Requirements

### LOW Confidence Issues (MANDATORY ADDITIONAL CHECKS)

When `confidence: low`, the following are **non-negotiable**:

1. **Baseline MUST exist** — If `.agent/ops/baseline.md` is missing, create it BEFORE implementation
2. **Tier 2+ Validation ONLY** — Cannot use Tier 1 (quick) validation; must run full checks
3. **Human Review REQUIRED** — Cannot auto-close; must explicitly ask user permission to mark done
4. **Explicit Baseline Comparison** — Must document baseline comparison results in issue log

**Low-confidence completion format:**
```markdown
**{ID}** — {title}  
status: done | completed: YYYY-MM-DD | confidence: low  
Delivered: {what was done}  
Baseline: {comparison result — pass/fail/accepted-with-risk}  
Human Review: Approved by user on YYYY-MM-DD
```

### NORMAL Confidence Issues

Standard checks apply. Human review recommended but not mandatory for non-critical paths.

**Normal-confidence completion format:**
```markdown
**{ID}** — {title}  
status: done | completed: YYYY-MM-DD  
Delivered: {what was done}
```

### HIGH Confidence Issues

Soft gates only. Can bundle multiple issues. Human review optional for truly trivial changes.

---

## Accepted Risk Documentation

If an issue is closed with **known limitations or residual risk**, document explicitly:

```markdown
**{ID}** — {title}  
status: done | completed: YYYY-MM-DD | confidence: {level}  
Delivered: {what was done}  
Accepted Risk:
- {Risk 1}: {Reason accepted}
- {Risk 2}: {Reason accepted}
```

This creates an audit trail and allows future review of decisions.

---

## history.md Conventions

### Archive Entry Format

```markdown
**{TYPE}-{NUMBER}@{HASH}** — {title}  
status: done | completed: YYYY-MM-DD  
Delivered: {one-line summary of what was delivered}
```

With confidence (for low-confidence issues):
```markdown
**{TYPE}-{NUMBER}@{HASH}** — {title}  
status: done | completed: YYYY-MM-DD | confidence: low  
Delivered: {summary}  
Baseline: Pass (no regressions)  
Human Review: Approved on YYYY-MM-DD
```

### Archive Entry Rules

1. **Date stamp required** — Always include `completed: YYYY-MM-DD`
2. **Brief delivery summary** — What was actually delivered (not just "done")
3. **Confidence context** — Include confidence level for low-confidence work
4. **Baseline result** — Include for low-confidence or when baseline exists
5. **No duplicate entries** — Each issue archived exactly once
6. **Chronological order** — Most recent at top of Archived section

### Anti-Patterns (FORBIDDEN)

- ❌ Marking done without moving to history.md
- ❌ Closing low-confidence without human review
- ❌ Skipping baseline comparison when baseline exists
- ❌ No delivery summary (just "done")
- ❌ Missing date stamp
- ❌ Closing with failing tests/lint

---

## Skills Referencing This Document

The following skills MUST reference this document instead of duplicating completion rules:

- `ao-implementation` — completion gate at end of implementation
- `ao-task` — when marking issues done
- `ao-validation` — ensuring all gates pass before completion
- `ao-housekeeping` — archival conventions

**Reference link**: `.ao/reference/completion-gate.md`

---

*Last updated: 2026-01-25*
