ci/README.md

# CI — Continuous Intelligence

Fully autonomous, git-native AI-driven software engineering harness.

## Overview

CI (Continuous Intelligence) is an autonomous-first software engineering harness that eliminates human-in-the-loop overhead while preserving the rigor of guided development. It receives a specification, resolves ambiguities through a single Clarify phase, then executes the full pipeline — research, plan, execute, verify — autonomously.

**The git log IS the project memory.** Every decision, escalation, lesson learned, and verification result is encoded in commit messages using structured `---ci---` YAML blocks. An agent's first impulse to gather context is `git log`, not file reads. Another agent with access to only commit messages (no code, no diffs) can reconstruct the project state completely.

## Installation

From source (package not yet published to npm):

```bash
git clone https://git.cloudinit.dev/continuous-intelligence/ci.git
cd ci
npm install
npm run build
npm link
```

## Quick Start

```bash
# Initialize from inline specification
ci init "Build a REST API for task management"

# Initialize from a specification file
ci init --spec ./specs/my-project.md

# Run the full autonomous pipeline
ci run --all

# Run a specific phase
ci run research
ci run plan
ci run execute
ci run verify

# Execute an ad-hoc task
ci quick "Add authentication middleware"

# Check project status (reads from git log + branches)
ci status

# Review autonomous decisions (extracted from git log ---ci--- blocks)
ci audit
ci audit --verbose

# Debug an issue
ci debug "Tests failing on CI"

# Rollback a phase
ci rollback 1

# Ship a phase (verify, security, commit, tag)
ci ship 1
```

## Git-Native Architecture (v0.2.0)

### The Commit Schema

Every CI-generated commit contains a `---ci---` YAML block with structured metadata:

```
feat(P01-01-02): create user registration endpoint

---ci---
phase: 1
milestone: v1.0
plan: 01-01
task: 01-01-02
status: execute
decisions:
  - id: D-003
    decision: Use bcrypt with 12 rounds for password hashing
    rationale: Industry standard; argon2 not available in target env
    confidence: 0.88
    alternatives: [argon2, scrypt]
requirements:
  covered: [AUTH-01]
---/ci---

- POST /auth/register validates email and password
- Checks for duplicate users
- Returns JWT token on success
```

### What Lives Where

| Where | What | Why |
|-------|------|-----|
| `.ci/config.json` | Autonomy, thresholds, git strategy | Controls system behavior before any commits exist |
| `.ci/PROJECT.md` | Vision, core value, requirements, constraints, key decisions table | Long-lived strategic reference |
| `.ci/ARCHITECTURE.md` | System architecture, component boundaries, data flow | Long-lived technical reference |
| `.ci/ROADMAP.md` | Phase breakdown, milestone mapping, success criteria | Long-lived planning reference |
| `.ci/REQUIREMENTS.md` | v1/v2 requirements with REQ-IDs and traceability | Long-lived requirements reference |
| **Git commit bodies** | Decisions, escalations, lessons, compounds, verification results | Dynamic event stream — the audit trail |
| **Git branches** | Phase/milestone status | `phase/NN-slug` and `milestone/vX.X-slug` encode project structure |

### Branch Strategy

```
main
 └── milestone/v1.0-mvp
      ├── phase/01-authentication       # in progress if not merged
      ├── phase/02-task-management
      └── phase/03-realtime-notifications
```

- Branch exists + not merged = phase **in progress**
- Branch merged to milestone = phase **complete**
- Milestone branch merged to main = milestone **complete**

### Context Reconstruction Protocol

An agent starting a session gathers context in this order:

1. `git log --oneline -20` — recent activity
2. `git branch -a` — phase/milestone structure
3. `git log -1 --format="%b"` — latest `---ci---` block
4. `.ci/config.json` — autonomy + thresholds
5. `.ci/PROJECT.md` — vision + constraints (when needed)
6. `.ci/ROADMAP.md` — phase plan + success criteria (when needed)
7. `.ci/REQUIREMENTS.md` — REQ-IDs + traceability (when planning)
8. `.ci/ARCHITECTURE.md` — system structure (when researching)

Steps 1-3 take <1 second and provide 80% of the context needed.

### The Reconstruction Test

An agent with access to **only commit messages** (no code, no diffs, no `.ci/` files) can reconstruct:

| Reconstructable | How |
|---------------|-----|
| Project specification | Init commit body |
| Current phase | `---ci---.phase` field + branch status |
| Current milestone | Branch names + `---ci---.milestone` field |
| All decisions with rationale | `git log --grep="decisions:" --format="%b"` |
| Decision confidence | Each decision has `confidence: 0.XX` |
| Alternatives considered | Each decision has `alternatives: [...]` |
| Requirements coverage | `git log --grep="requirements:" --format="%b"` |
| Lessons learned | `git log --grep="lessons:" --format="%b"` |
| Compounded solutions | `git log --grep="compound:" --format="%b"` |
| Escalation history | `git log --grep="escalation:" --format="%b"` |

### Commit Types

In addition to conventional commit types, CI uses:

| Type | When Used |
|------|-----------|
| `decision` | Autonomous decision logged (no code change) |
| `compound` | Compounded solution captured |
| `escalation` | Escalation raised or resolved |
| `verify` | Verification pass/fail |
| `wip` | Work-in-progress checkpoint |

## Autonomy Levels

| Level | Behavior |
|-------|----------|
| `full` | No human interaction after Clarify. Escalate only irreversible decisions. |
| `supervised` | Escalate on every Escalation Gate plus verification failures. |
| `guided` | Escalate on every Decision Gate. |

## Configuration

CI uses `.ci/config.json` for project configuration:

```json
{
  "autonomy": {
    "level": "full",
    "escalation_hooks": ["deploy", "delete_data", "merge_to_main"],
    "clarify_budget": 10,
    "decision_confidence_threshold": 0.6,
    "max_revision_iterations": 3,
    "max_verification_retries": 2,
    "escalation_timeout_ms": 300000
  },
  "model_profile": "quality",
  "parallelization": {
    "enabled": true,
    "max_concurrent_agents": 5,
    "min_plans_for_parallel": 2
  },
  "verification": {
    "automated_only": true,
    "escalate_visual": true,
    "escalate_external_integration": true,
    "test_first": false
  },
  "security": {
    "auto_accept_low_severity": true,
    "auto_mitigate_medium_severity": true,
    "escalate_high_severity": true
  },
  "git": {
    "branching_strategy": "phase",
    "auto_commit": true,
    "auto_push": false
  }
}
```

## Architecture

### Pipeline

```
SPECIFY → CLARIFY → RESEARCH → PLAN → EXECUTE → VERIFY → COMPLETE
                ↕               ↕         ↕          ↕
           (questions)    (auto-decide) (auto-run) (auto-verify)
```

### Git-Native Core Modules

| Module | Purpose |
|--------|---------|
| `commit-parser` | `---ci---` YAML block extraction and parsing from commit messages |
| `commit-builder` | Structured commit message generation for all commit types |
| `git-context` | Project state reconstruction from `git log` + `git branch` |
| `git-branch` | Phase/milestone branch lifecycle management |
| `ci-files` | `.ci/` long-lived reference file management with update discipline |

### Decision Engine

Every autonomous decision is classified by confidence:
- **High (>0.85)**: Auto-decide, commit as `---ci---` block
- **Medium (0.60-0.85)**: Auto-decide with assumption logging, flag for review
- **Low (<0.60)**: Escalate to human

Decisions are committed to git as `decision` type commits. The audit trail is `git log --grep="decisions:"`.

### 18 Agents

| Agent | Role | CI Modification |
|-------|------|----------------|
| orchestrator | Pipeline controller | Git-first context loading, `---ci---` commit generation |
| planner | Plan creation | Never sets `autonomous: false` |
| executor | Task execution | Never pauses for checkpoints |
| verifier | Output verification | Generates automated tests, not human UAT |
| researcher | Domain research | Logs assumptions, never flags for human |
| challenger | Plan stress-testing | Binding verdicts, only escalates <0.60 |
| security-auditor | Security audit | Auto-dispositions threats |
| debugger | Bug fixing | Auto-fixes when confidence > threshold |
| Others | Various | Retained from Learnship |

### Verification Layers

1. **Structural**: File existence, import/export wiring, no stubs
2. **Behavioral**: Generated automated tests for must-haves
3. **Security**: STRIDE analysis with auto-disposition
4. **Code Quality**: Multi-persona review with P0 auto-fix

## Specification Format

```markdown
# Project: My Project

## Objective
Build a REST API for task management.

## Requirements
- User authentication (JWT-based)
- CRUD operations for tasks
- Real-time notifications

## Constraints
- Must use Node.js
- Must be production-ready

## Out of Scope
- Admin dashboard
- Mobile apps
```

## Escalation Protocol

When CI cannot proceed autonomously:

1. **Irreversible Action**: Deploy, delete, merge to protected branch
2. **Verification Failure**: Tests pass but functional verification fails
3. **Low Confidence Decision**: Critical decision below threshold
4. **Security Escalation**: High-severity threat detected
5. **Specification Ambiguity**: Multiple valid interpretations

Each escalation is committed as an `escalation` type commit. Resolved escalations produce a follow-up commit with the resolution. The full escalation history is available via `git log --grep="escalation:"`.

## Current Limitations

- **Agent implementations are stubs**: All 18 agents return success immediately. Real LLM-based agent implementations are needed for research, planning, execution, and verification.
- **Package not published to npm**: Install from source only until a publishing pipeline is configured.
- **Behavioral/Security/Quality verification layers**: Structural verification is fully implemented; behavioral, security, and quality layers are partially stubbed.

## Differences from Learnship

| Dimension | Learnship | CI |
|-----------|-----------|-----|
| Project memory | `.planning/` directory files | Git log + `---ci---` commit blocks |
| Audit trail | `.ci/audit/*.json` files | `git log --grep="decisions:"` |
| State management | `STATE.md` + `STATE.md.json` | Reconstructed from git on demand |
| Phase discovery | Read `.planning/phases/` directory | `git branch -a \| grep phase/` |
| Human Interactions | 19+/lifecycle | 1-2/lifecycle |
| Decision Making | Human decides, agent implements | Agent decides, human reviews post-hoc |
| Verification | Human UAT | Automated tests + escalation |
| Specification | Multi-round conversation | Single spec file |

## Repository

[git.cloudinit.dev/continuous-intelligence/ci](https://git.cloudinit.dev/continuous-intelligence/ci)

## License

MIT