# Repository grant contract

Status: **v1 enabled for local `TaskSpec` files and profiled Activity Core
rows**.

`repository_grant` is the explicit authority envelope for a bounded local Git
mutation. It is separate from task prose, labels, organizational attribution,
tool profiles, and repository path resolution. None of those inputs may be
interpreted as repository authority.

## Version 1

```json
{
  "repository_grant": {
    "version": "1",
    "allowed_paths": ["docs/", "README.md"],
    "commit_count": {"min": 1, "max": 1},
    "publish": false
  }
}
```

All four fields are required and unknown fields are rejected.

- `version` is the string `"1"`.
- `allowed_paths` is a non-empty array of unique, repository-relative POSIX
  patterns. An exact path grants that path; a trailing `/` grants that directory
  subtree; `*` is confined to one path segment; and `**` may span segments.
  Absolute paths, parent traversal, backslashes, and `.git` grants are rejected.
- `commit_count.min` and `.max` are positive integers satisfying
  `1 <= min <= max <= 32`.
- `publish` must be `false`. Version 1 grants local commits only. Publication
  needs a future separately reviewed contract with remote/ref and outcome
  evidence; it cannot be enabled by a label or tool profile.

The parser canonicalizes path order and exposes a stable grant id plus bounded
evidence containing only the path count and digest, not the raw grant patterns.
The repository acceptance validator converts the grant into the policy used to
check descendant commits, changed paths, clean post-state, protected Git
metadata, and local remote-tracking refs.

## Current execution posture

`TaskSpec.from_file` parses this contract and `run_task` executes it under the
canonical repository transaction. A successful adapter result is accepted only
when the commit ancestry/count, changed paths, clean post-state, protected Git
metadata, and remote-tracking refs satisfy the exact grant. The result carries
bounded grant, baseline, policy, commit, and path evidence without raw grant
paths, prompts, or provider output.

Granted runs require durable external metrics and refuse `--no-metrics`. Their
metrics are written outside the checkout only after acceptance, so a successful
run remains clean. See [external-metrics.md](external-metrics.md).

Activity Core revision `b63131e` added strict definition admission and separate
queue carriage. The claim client parses that exact v1 field, refuses malformed
authority, and requires `harness_profile_ref` whenever a queued grant is
present. Profiled success applies the same repository acceptance policy and
external metrics contract as a local granted run.

Before sending a profiled terminal result, the worker durably records the exact
run, transaction, worker, action, and bounded result. Response-lost closes are
replayed without repeating workload code and Activity Core distinguishes exact
reconciliation from terminal, evidence, owner, state, and lease conflicts.
Grant-absent compatibility runs retain their legacy result behavior during
migration.

Task descriptions, labels, `execution_refs`, consuming-repo defaults, and
profile absence must never synthesize a grant.