Gcc

Git Context Controller (GCC)

Overview

GCC transforms agent memory from a passive token stream into a structured, versioned file system under .GCC/. Inspired by Git, it provides four operations — COMMIT, BRANCH, MERGE, CONTEXT — to persist milestones, explore alternatives in isolation, synthesize results, and recover historical context efficiently.

Initialization

On first use, check if .GCC/ exists in the project root. If not, run scripts/gcc_init.sh to create the directory structure:

.GCC/
├── main.md          # Global roadmap and objectives
├── metadata.yaml    # Infrastructure state (branches, file tree, config)
├── commit.md        # Commit history for main branch
├── log.md           # OTA execution log for main branch
└── branches/        # Isolated workspaces for experiments
    └── <branch-name>/
        ├── commit.md
        ├── log.md
        └── summary.md

For detailed file format specifications, read references/file_formats.md.

Configuration

GCC behavior is controlled via metadata.yaml:

• proactive_commits: true — Automatically suggest commits after completing coherent sub-tasks
• proactive_commits: false — Only commit when explicitly requested

Toggle with: "enable/disable proactive commits" or by editing metadata.yaml.

Commands

COMMIT

Persist a milestone on the current branch.

Triggers: /gcc commit <summary>, "commit this progress", "save this milestone", "checkpoint"

Procedure: 1. Read the current branch's commit.md to determine the next commit number 2. Append a new entry to commit.md with:

• Sequential ID (e.g., [C004])
• Date (UTC ISO 8601)
• Current branch name
• Branch purpose (from summary.md if on a branch, or from main.md)
• Previous progress summary (1-2 sentences from last commit)
• This commit's contribution (detailed technical description with files touched)

3. Append an OTA entry to log.md recording the commit action 4. Update metadata.yaml file tree if files were created/modified 5. If on main branch, update milestones section in main.md

Proactive behavior: When proactive_commits: true, suggest a commit after:

• Completing a function, module, or coherent unit of work
• Fixing a bug and verifying the fix
• Finishing a research/exploration phase with conclusions
• Any point where losing context would mean re-doing significant work

BRANCH

Create an isolated workspace for exploring an alternative approach.

Triggers: /gcc branch <name>, "branch to try...", "explore alternative...", "experiment with..."

Procedure: 1. Create .GCC/branches/<branch-name>/ directory 2. Create summary.md with: purpose, parent branch, creation date, key hypotheses 3. Create empty commit.md and log.md for the branch 4. Update metadata.yaml to register the new branch 5. Update main.md Active Branches section 6. Log the branch creation in the parent branch's log.md

From this point, all COMMITs and OTA logs go to the branch-specific files until a MERGE or explicit branch switch.

MERGE

Integrate a completed branch back into the main flow.

Triggers: /gcc merge <branch>, "merge results from...", "integrate the experiment", "branch X is done"

Procedure: 1. Read the branch's summary.md and commit.md to understand outcomes 2. Append a synthesis commit to main's commit.md summarizing:

• What was tried
• What was learned
• What is being integrated (or why the branch is being abandoned)

3. Update main.md:

• Add milestone entry with branch results
• Remove from Active Branches
• Update objectives if applicable

4. Update metadata.yaml: set branch status to merged or abandoned 5. Log the merge in main's log.md

CONTEXT

Retrieve historical memory at different resolution levels.

Triggers: /gcc context <flag>, "what did we do on...", "recover context", "show me the history", "where were we"

Flags:

• --branch [name] — Read summary.md and latest commits for a specific branch (or current branch if no name). Provides high-level understanding of what happened and why.

• --log [n] — Read last N entries (default 20) from the current branch's log.md. Provides fine-grained OTA traces for debugging or resuming interrupted work.

• --metadata — Read metadata.yaml to recover project structure: file tree, dependencies, active branches, configuration.

• --full — Read main.md for the complete project roadmap, all milestones, and active branches. Use for cross-session recovery or handoff to another agent.

When no flag is specified, default to --branch for the current active branch.

OTA Logging

Throughout all work (not just during explicit commands), maintain the OTA execution log:

1. Observation: What was noticed or discovered 2. Thought: Reasoning about what to do next 3. Action: What action was taken

Append entries to the active branch's log.md. Keep a maximum of 50 entries; when exceeding, remove the oldest entries. Each entry includes a sequential ID, timestamp, and branch name.

Log OTA entries at meaningful decision points — not every single action, but significant observations, strategy changes, and outcomes.

Cross-Session Recovery

When starting a new session on an existing project with .GCC/:

1. Read metadata.yaml to understand project state and active branches 2. Read main.md for the global roadmap and objectives 3. Read the active branch's latest commits and log entries 4. Resume work with full context of what was accomplished and what remains

Natural Language Mapping

GCC File Format Reference

main.md

The global roadmap. Updated on every MERGE and periodically on significant COMMITs.

# Project Roadmap

## Objectives
- [ ] Objective 1
- [x] Objective 2 (completed)

## Milestones
### M1: Feature X implemented
- Branch: feature-x
- Commits: 3
- Status: merged

### M2: Bug fix Y
- Branch: fix-y
- Commits: 1
- Status: active

## Active Branches
- `experiment-z`: Testing alternative approach for caching

commit.md

Each commit entry captures the full reasoning context, not just a diff summary.

## [C003] Implement retry logic for API calls
- **Date**: 2025-01-15T10:30:00Z
- **Branch**: feature-resilience
- **Branch Purpose**: Add fault tolerance to external API integrations
- **Previous Progress**: Identified failure patterns in logs; designed retry strategy with exponential backoff
- **This Commit's Contribution**: Implemented `retry_with_backoff(fn, max_retries=3)` in `utils/http.py`. Added unit tests covering timeout, 5xx, and network error scenarios. Validated against staging API.
- **Files touched**: utils/http.py, tests/test_http.py

log.md

Fine-grained OTA (Observation-Thought-Action) trace entries. Keep the last 50 entries maximum.

---
**[OTA-042]** 2025-01-15T10:15:00Z | Branch: feature-resilience
- **Observation**: API calls to /users endpoint failing with 503 errors intermittently
- **Thought**: Need exponential backoff rather than fixed delay; should cap at 3 retries to avoid infinite loops
- **Action**: Implementing retry_with_backoff() in utils/http.py

---
**[OTA-043]** 2025-01-15T10:28:00Z | Branch: feature-resilience
- **Observation**: Tests passing for timeout and 5xx scenarios
- **Thought**: Ready to commit this milestone - retry logic is complete and validated
- **Action**: COMMIT with summary of retry implementation

metadata.yaml

Structured infrastructure state. Updated on every operation.

version: 1
created: "2025-01-10T08:00:00Z"
proactive_commits: true
branches:
  - name: main
    status: active
    created: "2025-01-10T08:00:00Z"
  - name: feature-resilience
    status: active
    created: "2025-01-15T09:00:00Z"
    parent: main
  - name: experiment-cache
    status: abandoned
    created: "2025-01-12T14:00:00Z"
    reason: "Redis dependency too heavy for this use case"
file_tree:
  - src/main.py
  - src/utils/http.py
  - tests/test_http.py
dependencies:
  - requests>=2.28
  - pytest>=7.0
config:
  language: python
  framework: fastapi

Branch Directory Structure

Each branch under .GCC/branches/<branch-name>/ contains:

.GCC/branches/feature-resilience/
├── commit.md    # Commits specific to this branch
├── log.md       # OTA traces for this branch
└── summary.md   # Branch purpose and current status

summary.md (per-branch)

# Branch: feature-resilience

## Purpose
Add fault tolerance to external API integrations to handle intermittent 503 errors.

## Status: active
## Parent: main
## Created: 2025-01-15T09:00:00Z

## Key Decisions
- Using exponential backoff (not fixed delay)
- Max 3 retries to prevent cascade failures
- Logging all retry attempts for observability