# Ground File Management

> Reference for: Common Ground
> Load when: Storage operations, project identification, file format

---

## Directory Structure

Ground files are stored in the user's Claude home directory:

```
~/.claude/common-ground/
├── index.md                              # Global registry of all projects
└── {project-id}/
    ├── COMMON-GROUND.md                         # Human-readable assumptions
    ├── ground.index.json                 # Machine-readable index
    └── archive/
        └── {timestamp}-{reason}.md       # Archived versions (future)
```

---

## Project Identification

### Primary Method: Git Remote

```bash
git remote get-url origin 2>/dev/null
```

**Example outputs:**
- `https://github.com/user/repo.git` -> project_id: `github.com/user/repo`
- `git@github.com:user/repo.git` -> project_id: `github.com/user/repo`

**Normalization rules:**
1. Remove protocol prefix (`https://`, `git@`)
2. Remove `.git` suffix
3. Replace `:` with `/` for SSH URLs
4. Use as directory name (URL-safe characters)

### Fallback Method: Path-Based

If no git remote found:

```bash
pwd
```

**Example:**
- `/home/user/projects/my-app` -> project_id: `local/home-user-projects-my-app`

**Normalization rules:**
1. Prefix with `local/`
2. Replace `/` with `-`
3. Remove leading slash

---

## Global Index (index.md)

Located at: `~/.claude/common-ground/index.md`

### Template

```markdown
# Common Ground: Project Registry

Last Updated: {timestamp}

## Tracked Projects

| Project | ID | Assumptions | Last Check |
|---------|----|-----------:|------------|
| {name} | {project_id} | {count} | {date} |

---

*Auto-generated by /common-ground command*
```

### Update Rules

- Add new project when first ground file created
- Update counts and dates on each /common-ground run
- Remove projects when ground file deleted (future --reset)

---

## Ground File (COMMON-GROUND.md)

Located at: `~/.claude/common-ground/{project_id}/COMMON-GROUND.md`

### Template

```markdown
# Project Common Ground

**Project:** {project_name}
**Project ID:** {project_id}
**Created:** {created_timestamp}
**Last Updated:** {updated_timestamp}

---

## ESTABLISHED

High confidence assumptions. Treat as premises.

### {id}: {title}

- **Type:** {stated|inferred|assumed}
- **Assumption:** {description}
- **Source:** {evidence or citation}
- **Validated:** {date}
- **Context:** {when this applies}

---

## WORKING

Medium confidence. Use but flag if contradicted.

### {id}: {title}

- **Type:** {stated|inferred|assumed}
- **Assumption:** {description}
- **Source:** {evidence or citation}
- **Validated:** {date}
- **Context:** {when this applies}

---

## OPEN

Low confidence. Ask before assuming.

### {id}: {title}

- **Type:** {stated|inferred|assumed|uncertain}
- **Assumption:** {description}
- **Source:** {evidence or citation}
- **Validated:** {date}
- **Context:** {when this applies}

---

## History

| Date | Action | ID | Details |
|------|--------|------|---------|
| {date} | {Created/Promoted/Demoted/Archived} | {id} | {details} |

---

*Managed by /common-ground command*
```

### Assumption ID Format

Format: `A{number}` (e.g., A001, A002, A003)

- Sequential within project
- Never reused (even after archival)
- Track highest ID in index.json

---

## Machine Index (ground.index.json)

Located at: `~/.claude/common-ground/{project_id}/ground.index.json`

### Schema

```json
{
  "version": "1.0",
  "project_id": "{project_id}",
  "project_name": "{human_readable_name}",
  "created": "{ISO_timestamp}",
  "last_updated": "{ISO_timestamp}",
  "next_id": 4,
  "assumptions": [
    {
      "id": "A001",
      "title": "{short_title}",
      "type": "stated|inferred|assumed|uncertain",
      "tier": "ESTABLISHED|WORKING|OPEN",
      "assumption": "{full_description}",
      "source": "{evidence}",
      "validated": "{ISO_date}",
      "context": "{when_applies}",
      "created": "{ISO_timestamp}",
      "history": [
        {
          "date": "{ISO_timestamp}",
          "action": "created|promoted|demoted",
          "from_tier": null,
          "to_tier": "WORKING",
          "reason": "{optional}"
        }
      ]
    }
  ],
  "archived": []
}
```

### Field Definitions

| Field | Type | Description |
|-------|------|-------------|
| `version` | string | Schema version for migrations |
| `project_id` | string | Unique project identifier |
| `project_name` | string | Human-readable project name |
| `next_id` | number | Next assumption ID to assign |
| `assumptions` | array | Active assumptions |
| `archived` | array | Archived assumptions (future) |

---

## File Operations

### Create New Ground File

1. Check if `~/.claude/common-ground/` exists, create if not
2. Create `{project_id}/` directory
3. Write `COMMON-GROUND.md` from template
4. Write `ground.index.json` with empty assumptions
5. Update global `index.md`

### Update Existing Ground File

1. Read `ground.index.json`
2. Apply changes (add/promote/demote)
3. Update `last_updated` timestamp
4. Regenerate `COMMON-GROUND.md` from index.json
5. Update global `index.md` counts

### Read Ground File

1. Check if `{project_id}/ground.index.json` exists
2. If exists, parse JSON and return
3. If not exists, return null (trigger fresh start)

---

## Writing Best Practices

### Human-Readable (COMMON-GROUND.md)

- Use consistent markdown formatting
- Include horizontal rules between tiers
- Keep assumptions readable without JSON
- Include history table for audit trail

### Machine-Readable (ground.index.json)

- Always valid JSON
- Include all fields (no omissions)
- Use ISO 8601 timestamps
- Preserve history array for audit

### Sync Rules

- `ground.index.json` is source of truth
- `COMMON-GROUND.md` is generated from index.json
- Always update both on any change
- Never manually edit COMMON-GROUND.md (regenerate instead)

---

## Error Handling

| Scenario | Action |
|----------|--------|
| No home directory access | Warn user, suggest alternate path |
| Corrupted index.json | Backup and regenerate from COMMON-GROUND.md |
| Missing project directory | Create fresh on next run |
| Permission denied | Report error with path |