> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotready.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Flags and Claim Gates: Controlling Coding Readiness

> Flags are attention records attached to primitive branches that control when a coding agent may claim implementation work and what proof removes the flag.

Flags are not primitives and not tickets. They are attention records attached to primitive branches — lightweight signals that tell agents, reviewers, and tools where work is needed and whether that work is ready to be claimed. By separating flags from primitives, the product tree keeps coding lifecycle state out of product truth while still giving coding agents a precise, machine-readable gate to check before starting any implementation.

## Flag types

Eight flag types cover every category of product attention:

<CardGroup cols={2}>
  <Card title="discovery" icon="magnifying-glass">
    Premise or product discovery work that must happen before intent work is ready. Signals that more research or validation is needed upstream.
  </Card>

  <Card title="seed" icon="seedling">
    Implementation work for a proposed or missing intent. This is the primary gate for new coding work.
  </Card>

  <Card title="delta" icon="code-compare">
    Implementation work needed after an approved intent changes. Triggered whenever a committed intent is amended in a way that affects the existing implementation.
  </Card>

  <Card title="coverage_gap" icon="triangle-exclamation">
    Missing primitive coverage — a part of the product that should have a primitive but does not yet.
  </Card>

  <Card title="blocker" icon="ban">
    A claim, proof, service, authority, or environment blocker that prevents progress on an otherwise ready flag.
  </Card>

  <Card title="drift" icon="arrows-rotate">
    Detected divergence between product truth and the current implementation. Signals that the code no longer matches the committed intent or standard.
  </Card>

  <Card title="proof_gap" icon="file-circle-question">
    Missing proof detail on a seed or delta flag. The flag exists but its Completion Proof is incomplete or absent.
  </Card>

  <Card title="question" icon="circle-question">
    A lightweight attention marker that does not yet warrant a full question card. Use it to note uncertainty without blocking other work.
  </Card>
</CardGroup>

## The claim gate

A coding agent may only claim work when **all five conditions** are true on the flag:

```yaml theme={null}
flag_type: "seed"   # or "delta"
status: "ready"
blocked_by: []
claimable: true
completion_proof_state: "ready"
```

<Warning>
  The workspace **Coding work switch** must also be enabled. A flag that satisfies all five YAML conditions above is still not claimable if the workspace switch is off. Both gates must be open.
</Warning>

### Field meanings

| Field                    | Required value    | What it checks                                                                          |
| ------------------------ | ----------------- | --------------------------------------------------------------------------------------- |
| `flag_type`              | `seed` or `delta` | Only implementation flags are claimable — not discovery, blocker, drift, or others.     |
| `status`                 | `ready`           | The product and design work shaping this flag is complete.                              |
| `blocked_by`             | `[]` (empty list) | No unresolved blockers remain.                                                          |
| `claimable`              | `true`            | Explicitly unlocked for coding claim.                                                   |
| `completion_proof_state` | `ready`           | The Completion Proof describing what evidence removes the flag is present and complete. |

## Ready but blocked

A seed or delta flag may reach `status: ready` while a service, authority decision, environment constraint, or upstream flag still prevents implementation. In that case, set `claimable: false` and list the blockers:

```yaml theme={null}
flag_type: "seed"
status: "ready"
claimable: false
blocked_by:
  - "SV-003"
completion_proof_state: "ready"
```

<Note>
  This state is useful when the product branch and Completion Proof are well-specified and you want to signal readiness without opening the work to claim. Resolve each item in `blocked_by` to unlock the flag.
</Note>

## Completion Proof

Every ready seed and delta flag must carry Completion Proof. Completion Proof describes **what evidence removes the flag** — passing tests, a confirmed deployment, a reviewed artifact, or a measurable outcome. It does not prescribe which files to edit or how to structure the implementation.

<Tip>
  Write Completion Proof from the perspective of the reviewer, not the coder. "All integration tests pass and the intent's operating envelope is verified in staging" is good Completion Proof. "Edit `src/api/auth.ts` to add the header" is not.
</Tip>

## Open flags

An open discovery, seed, or delta flag may be sparse at creation time. It only needs to:

1. Point to the primitive branch that needs attention.
2. Preserve the trigger context — why the flag was raised.

Open seed and delta flags are product and design responsibility. Coding agents do not act on them until the claim gate is fully open.

```yaml theme={null}
flag_type: "seed"
status: "open"
primitive_ref: "I-007"
trigger: "New intent I-007 approved in M1 review — no implementation exists yet."
blocked_by: []
claimable: false
completion_proof_state: "missing"
```