ci/opencode/ci/references/commit-schema.md

<commit_schema>

Canonical ---ci--- YAML block schema for CIAgent commits. Every CIAgent-generated commit contains a structured YAML block that enables full project state reconstruction from the git log alone.

---

Block Format

<type>(<scope>): <subject>

---ci---
project: <slug>          # required in multi-project mode
phase: <number>
milestone: <string>
plan: <string>           # optional
task: <string>           # optional
status: <pipeline_stage>
decisions:               # optional
  - id: D-001
    decision: <text>
    rationale: <text>
    confidence: <0.0-1.0>
    alternatives: [<alt1>, <alt2>]
escalations:             # optional
  - id: E-001
    type: <escalation_type>
    description: <text>
    resolution: pending|timeout|human|auto
requirements:            # optional
  covered: [REQ-01, REQ-02]
  partial: [REQ-03]
lessons:                 # optional
  - <text>
compound:                # optional
  category: <string>
  problem: <text>
  solution: <text>
---/ci---

The project field is required when in multi-project mode (.ciagent/config.json has projects[] with length > 0). In single-project mode, it is optional.

Example with project field:

feat(P01-01-01): implement JWT auth

---ci---
project: auth-service
phase: 1
milestone: v0.2
plan: 01-01
task: 01-01-01
status: execute
---/ci---

Commit Types

Type	Purpose	Scope
feat	New feature	P##-##-##
fix	Bug fix	P##-##-##
test	Test-only	P##-##-##
refactor	Code cleanup	P##-##-##
docs	Documentation	P##, init, milestone
chore	Config, deps, tooling	P##
perf	Performance	P##-##-##
wip	Paused state	P##
decision	Standalone decision record	P##
compound	Compound learning	P##
escalation	Escalation artifact	P##
verify	Verification result	P##
note	Contextual annotation	P##
todo	Future intent	P##

Scope Format

Context	Format	Example
Initialization	init	docs(init): initialize project (5 phases)
Milestone	milestone	docs(milestone): complete v1.0-mvp
Phase-level	P##	docs(P03): complete auth phase
Plan-level	P##-##	feat(P03-01): implement JWT
Task-level	P##-##-##	feat(P03-01-02): add refresh rotation

Phase numbers are zero-padded to 2 digits. Plan and task numbers are not zero-padded.

Builder Methods

The CommitBuilder class provides typed constructors:

Method	Input	Commit Type
buildInitCommit	InitCommitInput	docs(init)
buildTaskCommit	TaskCommitInput	any task type
buildPhaseCompletionCommit	PhaseCompletionInput	docs(P##)
buildDecisionCommit	DecisionCommitInput	decision(P##)
buildEscalationCommit	EscalationCommitInput	escalation(P##)
buildCompoundCommit	CompoundCommitInput	compound(P##)
buildVerifyCommit	VerifyCommitInput	verify(P##)
buildResearchCommit	phase, milestone, subject, findings	docs(P##)

Reconstruction Guarantee

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

1. Current phase and milestone — from the latest commit's phase and milestone fields
2. Pipeline stage — from the latest commit's status field
3. All decisions — by collecting decisions[] from commits where type: decision or any commit with a decisions block
4. All escalations — by collecting escalations[] from type: escalation commits
5. Requirements coverage — by aggregating requirements.covered and requirements.partial across all commits
6. Lessons learned — by collecting lessons[] across all commits
7. Compound learnings — by collecting compound objects across all commits
8. Phase completion status — from the branch state (merged = complete, active = in progress)

Anti-Patterns

• Never put CIAgent metadata in code comments — it belongs in commit messages
• Never omit the ---ci--- block from a CIAgent-generated commit
• Never store decisions, escalations, or lessons in files — commit them
• Never use a non-standard commit type — use the 14 types above
• Never put freeform text inside the YAML block — use the structured fields

</commit_schema>