> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Spec Completion Tracking System

> Version: 1.1.0 Last Updated: 2026-02-24 Status: Active

**Version:** 1.1.0\
**Last Updated:** 2026-02-24\
**Status:** Active

This guide explains how to use the spec completion tracking system to monitor implementation progress, track deferred phases, and generate completion reports.

There are no separate commands for audit, status update, or complete-feature; use **`spec-complete`** with the flags below.

**Single command:** All completion operations are performed via **`spec-complete`** (`.cursor/commands/specs/spec-complete.md`). The workflow names below (audit, status update, complete-with-deferred) describe *what you are doing*; they are implemented as **sub-operations of `spec-complete`** using the flags in the table. There are no separate `audit-spec-completion`, `update-spec-status`, or `complete-feature` command files—only `spec-complete` with the flags above.

| Workflow (conceptual)                   | Use this                                                                                  |
| --------------------------------------- | ----------------------------------------------------------------------------------------- |
| Comprehensive completion audit          | `spec-complete --spec {CORE-##} --completion-report [--include-deferred] [--output path]` |
| Quick status update / update log        | `spec-complete --spec {CORE-##} [--notes "…"]` (updates implementation log and status)    |
| Complete feature with deferred checking | `spec-complete --spec {CORE-##} --check-deferred [--update-deferred-summary]`             |
| Update status registry                  | `spec-complete --spec {CORE-##} --completion-report --update-registry`                    |

***

## Overview

The spec completion tracking system provides:

* **Automated Auditing:** Comprehensive completion status checks for all specifications (via `spec-complete --completion-report`)
* **Deferred Phase Tracking:** Monitor status of deferred phases and enhancements (`spec-complete --check-deferred`, `--update-deferred-summary`)
* **Status Registry:** Centralized view of completion across all cores (`spec-complete --update-registry`)
* **Completion Reports:** Detailed reports with recommendations and missing items (`spec-complete --completion-report --output path`)
* **Quick Status Updates:** Fast status updates via `spec-complete` (updates implementation log and metadata)

***

## Key Components

### Command

**`spec-complete`** is the only completion command. Use the flags above to perform audits, status updates, and deferred checks.

### Files

1. **`specs/SPEC_STATUS_REGISTRY.md`** - Centralized completion status
2. **`specs/{core}/IMPLEMENTATION_LOG.md`** - Detailed completion history
3. **`specs/{core}/summaries/DEFERRED-PHASES-SUMMARY.md`** - Deferred work tracking

**Board and assignment tracking:** For GitHub Project setup and when to update the board (whats-next, spec-complete, start work), see [GITHUB\_PROJECT\_SPEC\_TRACKING\_PLAN.md](GITHUB_PROJECT_SPEC_TRACKING_PLAN.md).

***

## Common Workflows

### 1. Audit a Single Spec

**Use Case:** Check completion status of a specific specification

```bash theme={null}
# Basic audit (completion report)
spec-complete --spec HR-02 --completion-report

# Include deferred phases
spec-complete --spec HR-02 --completion-report --include-deferred

# Generate detailed report to file
spec-complete --spec HR-02 --completion-report --include-deferred --output reports/hr-02-completion.md
```

**What It Does:**

* Reads spec file and implementation log
* Checks code implementation (tables, hooks, components)
* Validates test coverage
* Checks deferred phases status
* Generates completion report

**Output:**

* Completion percentage breakdown
* Phase-by-phase status
* Missing items checklist
* Recommendations

### 2. Quick Status Update

**Use Case:** Update status after completing a phase

```bash theme={null}
# Update implementation log and spec status (with notes)
spec-complete --spec HR-02 --notes "Complete (Base + Enhancements 1-3)"

# Add completion notes
spec-complete --spec HR-02 --notes "Completed credential renewal workflow"
```

*Note: Phase-level and percentage updates are reflected in the implementation log and spec metadata when you run `spec-complete`. For read-only status, use `spec-status --spec HR-02 --detailed`.*

**What It Updates:**

* Spec file metadata
* Implementation log entry
* Status registry (if exists)

### 3. Complete Feature with Deferred Checking

**Use Case:** Mark feature complete and check deferred phases

```bash theme={null}
# Complete with deferred checking
spec-complete --spec HR-02 --check-deferred

# Update deferred summary
spec-complete --spec HR-02 --update-deferred-summary

# Full completion with report
spec-complete --spec HR-02 --check-deferred --completion-report
```

**What It Does:**

* Validates spec completion
* Checks test coverage
* Validates documentation
* Checks deferred phases (if `--check-deferred`)
* Updates implementation log
* Generates report (if `--completion-report`)

### 4. Audit All Specs

**Use Case:** Get overview of all specs across all cores

```bash theme={null}
# Audit all specs
spec-complete --completion-report --all --include-deferred

# Update status registry
spec-complete --completion-report --all --update-registry

# Generate reports for all
spec-complete --completion-report --all --include-deferred --output reports/all-specs-completion.md
```

**What It Does:**

* Audits all specs in all cores
* Calculates completion percentages
* Updates status registry
* Generates summary statistics

### 5. Audit Core-Specific Specs

**Use Case:** Focus on a specific core module

```bash theme={null}
# Audit all HR specs
spec-complete --completion-report --core hr --include-deferred

# Update registry for HR core
spec-complete --completion-report --core hr --update-registry

# Re-verify LO and update registry only (script)
node scripts/audit/audit-spec-completion.js --core=lo --include-deferred --update-registry
```

***

## Understanding Completion Status

### Status Symbols

* ✅ **Complete** - Fully implemented and tested
* 🚧 **In Progress** - Currently being implemented
* 📋 **Specification** - Spec written, not started
* 📋 **Deferred** - Specified but not implemented
* ⏳ **In Progress (Deferred)** - Deferred phase being implemented

### Completion Percentage Calculation

The system calculates two completion metrics:

#### Scope Completion (Primary Metric)

What percentage of the *current planned scope* is done. **Does NOT include deferred phases.**

* **Base Implementation:** 60% weight
* **Enhancements:** 40% weight

**Example:**

* Base: 100% complete
* Enhancements: 2 of 3 complete (67%)
* **Scope Completion:** (100% × 0.6) + (67% × 0.4) = **87%**

#### Full Completion (Secondary Metric)

What percentage of *all specified work* (including deferred) is done.

* **Scope Completion:** 70% weight
* **Deferred Phases:** 30% weight

**Example:**

* Scope Completion: 87%
* Deferred Phases: 0 of 2 complete (0%)
* **Full Completion:** (87% × 0.7) + (0% × 0.3) = **61%**

> **Interpretation:** A spec with 100% Scope Completion is "done for now" even if deferred phases haven't started. Full Completion shows overall progress toward complete feature parity.

***

## Status Registry

The status registry (`specs/SPEC_STATUS_REGISTRY.md`) provides a centralized view of all specs.

### Viewing the Registry

```bash theme={null}
# Open the registry file
cat specs/SPEC_STATUS_REGISTRY.md

# Or view in your editor
```

### Updating the Registry

```bash theme={null}
# Auto-update after auditing
spec-complete --completion-report --all --update-registry

# Update specific core
spec-complete --completion-report --core hr --update-registry
```

### Registry Structure

The registry includes:

* Summary statistics by core
* Table for each core with:
  * Spec ID and name
  * Base status
  * Enhancements status
  * Deferred phases count
  * Overall completion percentage
  * Last audited date

***

## Completion Reports

### Report Structure

Completion reports include:

1. **Summary Section**
   * Overall status
   * Completion percentage
   * Last audited date

2. **Base Implementation**
   * Status and completion date
   * Implementation log link
   * Test coverage summary

3. **Enhancements**
   * Status of each enhancement
   * Completion dates

4. **Deferred Phases**
   * Status of each deferred phase
   * Expansion spec links
   * Implementation status
   * Estimated effort

5. **Missing Items**
   * Checklist of incomplete items
   * Test coverage gaps
   * Documentation gaps

6. **Recommendations**
   * Next steps
   * Priority items
   * Estimated effort

### Generating Reports

```bash theme={null}
# Generate report for specific spec
spec-complete --completion-report --spec HR-02 --include-deferred --output reports/hr-02-completion.md

# Generate report for all specs
spec-complete --completion-report --all --include-deferred --output reports/all-specs-completion-2026-01-03.md
```

***

## Best Practices

### 1. Regular Audits

**Frequency:**

* **Weekly:** For active development cores (HR, RH, FA)
* **Monthly:** For all cores to track overall progress
* **Before Planning:** Run before planning new work
* **After Major Completions:** Run after completing major features

```bash theme={null}
# Weekly audit for active core
spec-complete --completion-report --core hr --include-deferred --update-registry

# Monthly full audit
spec-complete --completion-report --all --include-deferred --update-registry
```

### 2. Incremental Status Updates

Update status as you complete phases, not just at the end:

```bash theme={null}
# After completing base implementation
spec-complete --spec HR-02 --notes "Complete (Base)" 

# After completing enhancements
spec-complete --spec HR-02 --notes "Complete (Base + Enhancements)"

# After completing deferred phases
spec-complete --spec HR-02 --notes "Complete"
```

### 3. Deferred Phase Tracking

Keep deferred phases up to date:

```bash theme={null}
# Check deferred phases when completing features
spec-complete --spec HR-02 --check-deferred

# Update deferred summary
spec-complete --spec HR-02 --update-deferred-summary
```

### 4. Report Generation

Save reports for historical tracking:

```bash theme={null}
# Generate dated reports
spec-complete --completion-report --spec HR-02 --output reports/hr-02-completion-$(date +%Y-%m-%d).md

# Generate quarterly reports
spec-complete --completion-report --all --output reports/q1-2026-completion.md
```

### 5. Status Registry Maintenance

Keep the registry current:

```bash theme={null}
# Update after major changes
spec-complete --completion-report --all --update-registry

# Update specific core regularly
spec-complete --completion-report --core hr --update-registry
```

***

## Integration with Other Commands

### With `validate-spec`

```bash theme={null}
# Validate spec structure first
validate-spec --spec HR-02

# Then audit completion
spec-complete --completion-report --spec HR-02
```

### With `check-coverage`

```bash theme={null}
# Check test coverage
check-coverage --module hr

# Audit completion (includes coverage check)
spec-complete --completion-report --spec HR-02
```

### With `spec-complete`

```bash theme={null}
# Complete feature with full validation
spec-complete --spec HR-02 --check-deferred --completion-report

# Combines deferred-phase check and full completion audit in one pass
```

***

## Troubleshooting

### Status Not Updating

**Problem:** Status updates not reflected in registry

**Solution:**

```bash theme={null}
# Manually update registry
spec-complete --completion-report --spec HR-02 --update-registry
```

### Missing Deferred Phases

**Problem:** Deferred phases not showing in audit

**Solution:**

```bash theme={null}
# Use --include-deferred flag
spec-complete --completion-report --spec HR-02 --include-deferred
```

### Incorrect Completion Percentage

**Problem:** Completion percentage seems wrong

**Solution:**

```bash theme={null}
# Run full audit to recalculate
spec-complete --completion-report --spec HR-02 --include-deferred

# Check implementation log for accuracy
cat specs/hr/IMPLEMENTATION_LOG.md
```

***

## Examples

### Example 1: New Feature Completion

```bash theme={null}
# 1. Implement feature
# ... implementation work ...

# 2. Update status after base implementation
spec-complete --spec HR-10 --notes "Complete (Base)"

# 3. Complete feature with validation
spec-complete --spec HR-10 --check-deferred

# 4. Generate final report
spec-complete --completion-report --spec HR-10 --include-deferred --output reports/hr-10-completion.md
```

### Example 2: Deferred Phase Implementation

```bash theme={null}
# 1. Audit to see deferred phases
spec-complete --completion-report --spec HR-02 --include-deferred

# 2. Implement deferred phase
# ... implementation work ...

# 3. Update status
spec-complete --spec HR-02 --notes "Phase 2: External Verification complete"

# 4. Update deferred summary
spec-complete --spec HR-02 --update-deferred-summary

# 5. Re-audit
spec-complete --completion-report --spec HR-02 --include-deferred
```

### Example 3: Monthly Progress Review

```bash theme={null}
# 1. Audit all specs
spec-complete --completion-report --all --include-deferred --update-registry

# 2. Generate summary report
spec-complete --completion-report --all --include-deferred --output reports/monthly-progress-2026-01.md

# 3. Review status registry
cat specs/SPEC_STATUS_REGISTRY.md
```

***

## Related Documentation

* **Commands:** `.cursor/README.md` - All cursor commands
* **Status Registry:** `specs/SPEC_STATUS_REGISTRY.md` - Centralized completion tracking
* **Implementation Logs:** `specs/{core}/IMPLEMENTATION_LOG.md` - Detailed completion history
* **Deferred Phases:** `specs/{core}/summaries/DEFERRED-PHASES-SUMMARY.md` - Deferred work tracking
* **Spec Template:** `specs/_templates/SPEC_TEMPLATE.md` - Completion status format

***

## Quarterly Deferred Review Process

Every quarter, perform a comprehensive review of deferred phases to ensure specifications stay current and priorities are aligned.

### Quarterly Review Checklist

```bash theme={null}
# Step 1: Generate comprehensive report
spec-complete --completion-report --all --include-deferred --output reports/deferred-review-Q{Q}-{YYYY}.md

# Step 2: Sync all deferred summaries
spec deferred --sync

# Step 3: Update registry
spec-complete --completion-report --all --update-registry
```

### Review Questions

For each deferred phase, answer:

1. **Still Relevant?**
   * [ ] Business need still exists
   * [ ] Technical approach still valid
   * [ ] Not superseded by other features

2. **Dependencies Changed?**
   * [ ] Check all dependency statuses
   * [ ] Identify newly available dependencies
   * [ ] Update blocked/ready status

3. **Priority Adjustment?**
   * [ ] Review with stakeholders
   * [ ] Update priority if needed
   * [ ] Consider promoting to active scope

4. **Effort Estimate Valid?**
   * [ ] Technology changes may affect estimate
   * [ ] Team capacity changes
   * [ ] Update estimates if >20% different

### Actions After Review

| Finding                        | Action                                                               |
| ------------------------------ | -------------------------------------------------------------------- |
| Feature no longer needed       | Run `spec deferred --promote --spec X --feature Y` with cancellation |
| Dependencies now available     | Move to "Ready for Implementation"                                   |
| Priority increased             | Consider promoting to active scope                                   |
| Estimate significantly changed | Update expansion spec                                                |
| Specification outdated         | Update expansion spec or create new one                              |

### Review Schedule

| Quarter | Review Date           | Report Location                        |
| ------- | --------------------- | -------------------------------------- |
| Q1      | First week of January | `reports/deferred-review-Q1-{YYYY}.md` |
| Q2      | First week of April   | `reports/deferred-review-Q2-{YYYY}.md` |
| Q3      | First week of July    | `reports/deferred-review-Q3-{YYYY}.md` |
| Q4      | First week of October | `reports/deferred-review-Q4-{YYYY}.md` |

### Review Meeting Template

```markdown theme={null}
# Deferred Phases Quarterly Review - Q{Q} {YYYY}

**Date:** {date}
**Attendees:** {list}

## Summary
- Total deferred phases: {N}
- Ready for implementation: {N}
- Blocked: {N}
- Cancelled this quarter: {N}
- Promoted this quarter: {N}

## Actions
| Spec | Phase | Decision | Owner | Due |
|------|-------|----------|-------|-----|
| | | | | |

## Next Quarter Focus
- {Priority 1}
- {Priority 2}
```

***

**Last Updated:** 2026-01-03\
**Next Review:** After first month of usage