agent-source-repository 0.1.0

Agent Source Repository local context registry for coding agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

# Forgejo Workflow

This document defines the operating contract between Forgejo, ASR, and coding
agents.

## Roles

| Role | Responsibility |
| --- | --- |
| Forgejo | Stores the canonical Git repositories. |
| ASR | Owns repository registration, checkout selection, indexing, freshness checks, and bounded source reads. |
| Agent | Reads and edits only the checkout that ASR indexed. |

## Canonical Flow

```txt
Forgejo bare repository
  -> task checkout selected for ASR
  -> ASR indexes that checkout
  -> agent uses ASR context/read/search
  -> agent edits the same checkout
  -> tests and verification run in that checkout
  -> commit, merge, and push back to Forgejo
  -> ASR re-indexes after the change
```

## Why Checkout Ownership Matters

ASR search results are only valid for the source tree it indexed. If ASR indexes
one directory and the agent edits another, line ranges, dependency hints, stale
checks, and diff evidence can refer to the wrong content.

The required invariant is:

```txt
ASR indexed path == agent editing path
```

If that invariant is false, the agent must stop before editing.

## Bare Repositories

Forgejo stores repositories as Git repositories and may store them as bare
repositories. ASR may register a bare repository for read-only discovery or for
building an index snapshot from Git objects.

A bare repository is not an editing surface. For any task that changes files,
there must be a checkout. That checkout is the path ASR indexes and the path the
agent edits.

## Merge Completion

After the agent finishes a task:

```txt
1. Run the relevant tests and ASR verification.
2. Commit the checkout changes.
3. Merge according to the repository's branch policy.
4. Push the result to Forgejo.
5. Re-run ASR indexing for the affected repository.
```

Do not treat the task as complete while ASR still points at an older checkout or
stale index.

## Current CLI Surface

Current ASR commands:

```bash
asr init --json
asr repo add <repo> <path> --json
asr repo list --json
asr repo status <repo> --json
asr repo index <repo> --json
asr search "<query>" --repo <repo> --top-k 8 --json
asr context "<task>" --repo <repo> --budget 4000 --json
asr read <repo> <path> --lines 1:80 --json
asr deps <repo> <path> --json
asr impact <repo> <path> --json
asr diff <repo> --base HEAD~1 --head HEAD --json
asr verify <repo> --json
```

Until a dedicated checkout-management command exists, operators must ensure the
registered path for editing tasks is the actual checkout used by the agent.