feat(P02): opencode integration layer (#2)

18 CI agents, 11 workflows, 11 commands, 5 references, 3 contexts. Zero learnship dependencies.
2026-05-29 13:27:29 +00:00
parent eedcdd4282
commit 2f738c33b7
50 changed files with 3113 additions and 0 deletions
@@ -0,0 +1,97 @@
+<git_context_loading>
+
+How CI agents load project context. The git log IS the project memory — a CI agent's first impulse to gather context is `git log` + `git branch`, not file reads.
+
+---
+
+## Core Principle
+
+**Read the log first, files second.**
+
+The git log contains every decision, escalation, lesson, and compound learning through structured `---ci---` YAML blocks. Files in `.ci/` are long-lived reference documents (PROJECT.md, ARCHITECTURE.md, ROADMAP.md, REQUIREMENTS.md, config.json) that change infrequently.
+
+## Context Loading Sequence
+
+1. **Branch scan** — `GitContext.getBranches()` to discover phase and milestone structure
+2. **State reconstruction** — `GitContext.reconstructState()` to get current phase, milestone, stage
+3. **Decision scan** — `GitContext.getDecisions()` for all project decisions
+4. **Escalation check** — `GitContext.getEscalations()` for any pending escalations
+5. **Requirements coverage** — `GitContext.getRequirementsCoverage()` for covered/partial
+6. **Lessons scan** — `GitContext.getLessons()` for all learned lessons
+7. **Compound learnings** — `GitContext.getCompounds()` for cross-phase patterns
+8. **File reads** — Only now read `.ci/` files (PROJECT.md, ARCHITECTURE.md, etc.)
+
+## GitContext API
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `isGitRepo()` | boolean | Check if inside a git repo |
+| `getCurrentBranch()` | string | Current branch name |
+| `getRecentCommits(count)` | ParsedCiCommit[] | Recent commits with parsed `---ci---` blocks |
+| `getLatestCiCommit()` | ParsedCiCommit \| null | Most recent CI commit |
+| `getBranches()` | BranchInfo[] | All branches with type and merge status |
+| `getPhaseBranches()` | BranchInfo[] | Phase branches only |
+| `getMilestoneBranches()` | BranchInfo[] | Milestone branches only |
+| `reconstructState()` | ProjectState | Full project state from git log |
+| `getDecisions(phase?)` | CommitDecision[] | Decisions, optionally filtered by phase |
+| `getLessons(phase?)` | string[] | Learned lessons |
+| `getCompounds(category?)` | CompoundInfo[] | Compound learnings |
+| `getEscalations()` | EscalationInfo[] | All escalations |
+| `getRequirementsCoverage()` | { covered, partial } | Requirement traceability |
+| `getCommitsForPhase(phase)` | ParsedCiCommit[] | All commits for a phase |
+| `getCommitsForBranch(branch)` | ParsedCiCommit[] | All commits on a branch |
+
+## ProjectState
+
+The `reconstructState()` method returns:
+
+```typescript
+interface ProjectState {
+  currentPhase: number;
+  currentMilestone: string;
+  currentStage: PipelineStage;
+  phasesCompleted: number[];
+  phaseBranches: BranchInfo[];
+  milestoneBranches: string[];
+  lastCommit: ParsedCiCommit | null;
+}
+```
+
+Derived entirely from git data — no file reads required.
+
+## ParsedCiCommit
+
+Every commit returned by `getRecentCommits()` is parsed into:
+
+```typescript
+interface ParsedCiCommit {
+  hash: string;
+  type: CommitType;
+  scope: string;
+  subject: string;
+  ci: CiMetadata | null;    // null if no ---ci--- block
+  body: string;
+}
+```
+
+Commits without `---ci---` blocks have `ci: null` — these are treated as non-CI commits (e.g., manual edits by the developer).
+
+## Context Budget Strategy
+
+When context is limited:
+
+1. `reconstructState()` — always (cheap, single call)
+2. `getDecisions(currentPhase)` — current phase decisions only
+3. `getRequirementsCoverage()` — aggregate view
+4. Skip lessons/compounds unless specifically needed
+5. Read `.ci/ROADMAP.md` instead of scanning all phase branches
+
+## What NOT to Do
+
+- Never read `.ci/` files before checking the git log
+- Never parse commit messages manually — use `CommitParser.parseCommitMessage()`
+- Never assume the latest commit reflects the current state — check branches
+- Never reconstruct state from files when git data is available
+- Never skip the branch scan — merged branches indicate completed phases
+
+</git_context_loading>