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
87

# Verification

## Required Gates

Run in a Rust toolchain environment:

```bash
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --locked
```

Equivalent local helper:

```bash
scripts/verify-asr.sh
```

Do not mark ASR complete if any required gate is skipped or replaced by a
static-only check.

For GitHub release preparation, also prove the release binary and package
metadata:

```bash
cargo build --release --locked --bin asr
cargo package --allow-dirty --locked
```

## Focused Tests

```bash
cargo test --test asr_registry_contract --locked
cargo test --test asr_search_contract --locked
cargo test --test asr_context_contract --locked
cargo test --test asr_read_diff_contract --locked
cargo test --test asr_deps_impact_contract --locked
cargo test --test asr_product_hardening_contract --locked
```

## Manual Product Path

```bash
ASR_HOME=$(mktemp -d)
cargo run --bin asr -- init --json
cargo run --bin asr -- repo add app /path/to/checkout --json
cargo run --bin asr -- repo status app --json
cargo run --bin asr -- repo index app --json
cargo run --bin asr -- search 'RetryPolicy' --repo app --top-k 8 --json
cargo run --bin asr -- context 'retry backoff policy' --repo app --budget 4000 --json
cargo run --bin asr -- read app src/retry.rs --lines 1:80 --json
cargo run --bin asr -- deps app src/retry.rs --json
cargo run --bin asr -- impact app src/retry.rs --json
cargo run --bin asr -- read app src/retry.rs --lines 1:20 --live --json
cargo run --bin asr -- diff app --base HEAD~1 --head HEAD --json
cargo run --bin asr -- verify app --json
```

## Required Proof

| Check | Required evidence |
| --- | --- |
| Context budget | `asr context` returns `estimated_tokens <= budget`. |
| State boundary | `ASR_HOME` inside a Git worktree fails with `asr_home_inside_git_repo`; repo inside `ASR_HOME` fails with `repo_inside_asr_home`. |
| Stale rejection | Source changes after indexing return `repo_index_stale` before search/context succeeds again. |
| Exact shard | `ASR_HOME/index/exact/<repo>/manifest.json`, `chunks.jsonl`, and `postings.tsv` exist after indexing, and `asr verify` reports it as a rebuildable cache backed by SQLite chunks. |
| Read/deps/impact freshness | Default `read`, `deps`, and `impact` outputs include `source_policy.snapshot_bound=true`; `--live` outputs include `source_policy.live=true`. |
| Read safety | Invalid paths and out-of-range line requests fail with `invalid_path` or `invalid_line_range`. |
| Diff safety | `asr diff` returns hunk metadata, not full patch content, and JSON marks `source_policy.mode=git_ref_diff`. |
| Forgejo editing invariant | The agent edits the same checkout that ASR indexed. |

## Forgejo Scenario Proof

For a Forgejo-backed repository, prove the actual operating path:

```txt
1. Register the checkout used for agent work.
2. Index it with ASR.
3. Run `asr context` for a real task.
4. Read only returned ranges.
5. Edit in that same checkout.
6. Re-run tests and `asr repo index`.
7. Commit, merge, and push back to Forgejo.
```

If ASR indexes a bare repository for read-only discovery, do not use that bare
path as the editing surface.