# Phase 0 Configuration Reference

This document covers the `platform.phase_0` section of `.github/agdt-config.json`,
which defines the configuration structure and validation rules for Phase 0 sync-back
settings. The config is validated and normalised at load time; runtime execution of
sync-back behaviour is out of scope for this package.

## Schema

```json
{
  "platform": {
    "phase_0": {
      "enabled": true,
      "sync_back_on_merge": true,
      "sync_back_fields": ["comment", "label", "status"]
    }
  }
}
```

### Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | `boolean` | `false` | First gate flag. When `false`, unknown-field rejection for `sync_back_fields` is disabled regardless of other settings. |
| `sync_back_on_merge` | `boolean` | `false` | Second gate flag. When `false`, unknown-field rejection for `sync_back_fields` is disabled regardless of other settings. |
| `sync_back_fields` | `list[str]` | `["comment"]` | Which fields to sync back. When absent or `null`, defaults silently to `["comment"]` with no validation. When a non-null value is provided, type and element validation applies; unknown-field name rejection is only enforced when both gates are active. |

### Valid `sync_back_fields` Values

| Value | Description |
|-------|-------------|
| `comment` | Identifier for comment-type sync-back. This is the default when `sync_back_fields` is omitted or `null`. |
| `label` | Identifier for label-type sync-back. |
| `status` | Identifier for status-type sync-back. |

Field identifiers are **case-sensitive** — `"Comment"`, `"LABEL"`, or `"Status"` are
rejected as unknown. No case-folding or normalization is performed.

## Default Behavior

When `sync_back_fields` is absent or `null`, the resolved field list defaults to
`["comment"]` regardless of gate flag values.

When either `enabled` or `sync_back_on_merge` is `false`, unknown-field validation is
skipped regardless of what `sync_back_fields` contains.

## Configuration Examples

### Minimal (default comment sync-back)

```json
{
  "platform": {
    "phase_0": {
      "enabled": true,
      "sync_back_on_merge": true
    }
  }
}
```

This uses the default `["comment"]` after normalization.

### Full opt-in (comment + label + status)

```json
{
  "platform": {
    "phase_0": {
      "enabled": true,
      "sync_back_on_merge": true,
      "sync_back_fields": ["comment", "label", "status"]
    }
  }
}
```

All three field identifiers are accepted and preserved in order.

### Label-only (no comment)

```json
{
  "platform": {
    "phase_0": {
      "enabled": true,
      "sync_back_on_merge": true,
      "sync_back_fields": ["label"]
    }
  }
}
```

Only the `label` identifier is preserved — `"comment"` is NOT implicitly added when you
provide an explicit list.

### Disabled sync-back

```json
{
  "platform": {
    "phase_0": {
      "enabled": true,
      "sync_back_on_merge": false
    }
  }
}
```

Unknown-field rejection is not applied because `sync_back_on_merge` is `false`.

## Edge Cases

- **`sync_back_fields: null`** — Treated the same as absent; defaults to `["comment"]`
  silently (no warning).
- **Empty list `[]`** — Accepted without error and preserved as an empty list.
- **Duplicate entries** — Silently deduplicated preserving first-occurrence order
  (e.g., `["comment", "comment"]` → `["comment"]`).
- **Unknown fields** — When both `enabled` and `sync_back_on_merge` are `true`, unknown
  field names raise a `ValueError` listing all unrecognized entries and the valid options.
  When either gate is `false`, unknown fields are silently accepted.
- **Non-list types** — A non-list value (string, int, bool) triggers a warning and
  defaults to `["comment"]`.
- **Non-string elements** — A list containing non-string elements (e.g., `[1, true]`)
  triggers a warning and defaults to `["comment"]`.
- **Wrong case** — `"Comment"`, `"LABEL"`, `"Status"` are all rejected as unknown when
  gates are active. Field identifiers are case-sensitive.

## Validation Error Format

When unknown fields are detected with both gates active:

```text
Unknown sync_back_fields: "assignee", "foo". Valid options are: comment, label, status
```

The error names ALL unknown fields and lists valid options in canonical order.
