rein-aharness/docs/repository-grant.md

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

{
  "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.

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.