# alkgit Research Index

Phase 0 (exploration) research. Feeds phase 1 (architecture).

| Doc | Topic | Status |
|---|---|---|
| [vision.md](vision.md) | Vision, guiding principles, non-goals, phase-0 checklist | draft v2 (amended 2026-09-21) |
| [gitoxide.md](gitoxide.md) | gitoxide (gix) capability + version alignment | initial pass complete |
| [alk-stack.md](alk-stack.md) | alk stack fit, integration surface, gitea-lesson constraints | initial pass complete |
| [git-protocol.md](git-protocol.md) | Server-side git smart protocol inventory (what we own) | initial pass complete |
| [reference-policy.md](reference-policy.md) | Licenses, reference projects, reuse policy | complete |
| [pocs.md](pocs.md) | POC plan (what to validate before architecture commits) | planned |
| [poc-1-findings.md](poc-1-findings.md) | POC-1: pkt-line over alkcall BiStream (duplex producer) | complete — proceed |
| [poc2-findings.md](poc2-findings.md) | POC-2: server-side pack generation (streaming pipeline) | complete — proceed |
| [poc3-findings.md](poc3-findings.md) | POC-3: smart-http shape through alkhttp (stateless substrate) | complete — proceed |
| [push-captures.md](push-captures.md) | Normative receive-pack (push) wire record (real git captures) | complete — ADR-013 basis |
| [negotiation-captures.md](negotiation-captures.md) | Normative V2 negotiation record (real git captures + source) | complete — ADR-014 basis |

## Key findings so far

- gitoxide covers storage + pkt-line; the **server half of the smart
  protocol is ours to write** (gix-protocol/transport are client-side).
- Published gix 0.87.1 == local clone base; pin crates.io versions.
- alkcall `BiStream` is the natural substrate under pkt-line for both ssh
  and http paths.
- The incompatible-license prior art confirms feasibility but contributes
  nothing; policy in [reference-policy.md](reference-policy.md).
- `gix` with `default-features = false` requires an explicit hash feature;
  workspace pins `sha1` with a `sha256` passthrough feature everywhere.

## Convergence criteria (phase 0 → phase 1)

Phase 0 is done when POC-1..3 have results and a recommended-approach
summary is written here (append below). Then the Architect produces
`docs/architecture/` per sdd_process.

**Convergence (2026-09-21)**: phase 0 gates all pass (POC-1/2/3 proceed).
Phase 1 opened with `docs/architecture/`; the structural decision is
ADR-010 — pure protocol crate following the alktty/alktunnels template
(the v1 "monorepo + alkgitd binary" framing in these research docs was an
init-agent artifact, amended in vision.md v2). POC-1 maps to the producer
half, POC-2 to the gix backend implementation, POC-3 to the stateless
substrate consumed by alkhttp's future `git` feature.