alkgit/AGENTS.md

AGENTS.md

Operating instructions for opencode agents working in this repo. opencode auto-loads this file as instructions, overriding the built-in defaults for this project. Custom agents in .opencode/agents/ inherit these rules unless their own prompts say otherwise.

Git Workflow

Commit and push when reasonable. When a change is complete and verified (build + lint + tests pass), commit and push to origin/main without asking. This overrides the built-in default of "only commit when explicitly asked."

Commit in small, focused units — one commit per unit of work (a fix, a feature, a doc change), not one large commit covering many topics. Push regularly so work is never stranded locally.

The workflow:

1. Make the change
2. Verify: cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check, cargo doc --no-deps if docs changed
3. Inspect git status and git diff before staging — stage only the intended files, never secrets
4. Write a concise commit message in conventional commits style: <type>(<scope>): <summary> — types are feat, fix, docs, chore, refactor, test, perf, build, ci; the scope is optional. For multi-point changes, use a summary line plus a body with bullet points and a verification block.
5. git push origin main
6. Report the commit hash and the verification summary

Exceptions — do not commit or push without asking:

• The change is exploratory / speculative (you're not sure the user wants it kept)
• The user is actively reviewing the diff and may ask for changes
• The change touches published wire formats or semver-relevant public API (crates will be published to crates.io once architecture lands; see the ADRs in docs/architecture/decisions/ for the stable-contract list once it exists)
• You'd be force-pushing, amending a published commit, creating an empty commit, or skipping hooks

Never commit secrets, keys, or credentials. If a commit fails or hooks reject it, fix the issue and create a new commit — do not amend the failed one.

Git identity is preconfigured (glm-5.3-flash <glm-5.3-flash@alk.dev>). Do not change git config, skip hooks, or use git commit -i.

Project Conventions (Rust / protocol crate)

This is alkgit — a pure protocol crate (ADR-010, the alktty/alktunnels template): the git smart protocol as producer/consumer halves on alkcall channels (the alk/git ALPN), backend traits with a feature-gated gitoxide (gix) implementation, no binary, no front doors (doors — alkhttp git feature, alkssh — are family infrastructure; see docs/architecture/doors.md). Single crate at the repo root (src/, tests/). The conventions below apply to all work in src/ and tests/. They mirror .opencode/agents/implementation-specialist.md §Project Conventions and are repeated here so they apply to every session, not just spawned implementation agents.

1. No comments in code unless the user explicitly asks. This is a project-wide convention. Doc comments (///, //!) are fine and expected on public API. Inline // comments only when the user asks or when a non-obvious safety/correctness constraint would otherwise be missed (e.g., "ACL must run before the first advertised ref line — ref names leak repository existence").

2. Error handling — thiserror for library error types. No panics in library code. No unwrap() or expect() outside tests. If you reach for unwrap, the error path wasn't specified — stop and decide what should actually happen. For poisoned RwLock/Mutex, use unwrap_or_else(|e| e.into_inner()) so a panic in one operation does not cascade to other operations.

3. tokio is the async runtime — all I/O is async. Git protocol sessions are long-lived streaming conversations; do not introduce blocking I/O on the async path. Use tokio::sync primitives (oneshot, mpsc) for correlation; parking_lot for short-held internal locks.

4. No secret material on the wire or in plaintext at rest — the git protocol, the call protocol payloads, and the metadata store carry no private keys, API keys, tokens, or decrypted credentials. Stored credential material lives in alkvault; metadata holds vault references. Outbound credentials flow through Capabilities injected at the assembly layer → OperationContext.capabilities → handler. See the no-env-vars invariant below and the alkcall ADRs (ADR-010, ADR-017).

5. No-env-vars invariant — no handler reads outbound credentials from any source other than OperationContext.capabilities. The credential injection path is vault → assembly layer → Capabilities → handler. This is a spec-level invariant, not a runtime convention.

6. Visible-surface = authorized-surface — the reason this project exists (a self-hosted gitea got pwned via an internal API reachable over the internet). Every operation exposed on the wire is gated by alkcall's AccessControl::check(peer_identity); ops with Visibility::Internal are never wire-callable; no endpoint exists that a caller cannot see themselves authorized for. There is no unauthenticated endpoint unless a repo is explicitly public, and push is always authenticated. This is a spec-level invariant.

7. gitoxide for git primitives, no shelling out — storage and pkt-line come from the gix crates (pinned in the crate manifest). The serving path never spawns the git binary (no GPL dependency, no process-injection surface). The server half of the smart protocol is ours; see docs/research/git-protocol.md for the inventory.

8. License hygiene — this project is MIT OR Apache-2.0. Never copy or derive code from MPL-2.0-licensed reference projects; reading gitoxide (MIT OR Apache-2.0) is fine. The policy and the rationale live in docs/research/reference-policy.md — do not name the incompatible-licensed project in docs, README, or commit messages.

9. Wire formats are stable one-way doors — once a wire surface is published (the git smart protocol is defined upstream and not ours to change; the one existing piece of alkgit-specific framing — the native session preamble, ADR-016 — is pinned and in the OQ-03 freeze inventory), its shape must not change. Protocol capability advertisement is honest: never advertise what we don't serve.

10. Feature flags — optional surface is feature-gated: gix (default-on; the backend implementations) and sha256 (hash algorithm passthrough; sha1 is the default and pinned in the crate manifest). The wire layer compiles without gix (default-features = false). Verify both cargo test (default) and cargo test --all-features pass if features are added.

11. Bounded resources — every protocol session carries wall-clock, size, and round limits (max negotiation rounds, max receive-pack size, session timeout). Git servers are internet-facing; unbounded loops and unbounded buffers are bugs.

12. Repo identity is registry-resolved — repo names arriving on the wire are IDs resolved against a server-side registry to configured storage roots. Wire-supplied names are never used as filesystem paths directly (path traversal is a protocol-level input, not a config value).

13. Naming — Rust standard: snake_case for functions/variables/ modules, PascalCase for types/traits, SCREAMING_SNAKE_CASE for constants.

14. Module structure — one module per file under src/, re-exported from src/lib.rs (the alktty crate-root pattern). Public API surface is lib.rs re-exports. Single crate at the repo root (ADR-010); the gix backend implementation lives under the default-on gix feature; default-features = false gives the wire/protocol layer only.

15. Composability boundary ("ALPN as a service") — alkgit is front-door-blind: it consumes (identity, repo id, duplex stream, limits) and depends on alkcall types only, never on alkhttp/alkssh, and carries no http/channel-specific types below the stream. Doors (alkhttp git feature, alkssh) are family infrastructure; a downstream app embeds alkgit and brings its own doors. v1 is the reduction to wire layer + backend traits + one gix implementation.

Verification Commands

Run these before committing. All must pass.

cargo test                                    # full suite
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo doc --no-deps                           # if docs changed
cargo publish --dry-run --allow-dirty         # before a release (per crate)

If feature flags are added, also run cargo test --all-features and cargo clippy --all-features --all-targets -- -D warnings.

Lifecycle Status

The project is in SDD phase 1 (architecture committed, implementation not yet begun). Phase 0 research is in docs/research/; the committed architecture is docs/architecture/ (ADR-010 is the structural decision: pure protocol crate, alk/git ALPN, backend traits, no binary/doors). POC code never merges to main — two modes: branch mode (POC builds on repo code; git branch, findings merged into research docs, branch dropped) or standalone mode (POC independent of repo code; scratch project at /workspace/<poc-name>). POCs have relaxed constraints (comments/unwrap acceptable) — they are exploration tools, not production code. Open architecture questions live in docs/architecture/open-questions.md (the active set: OQ-03 — partially resolved, the publish freeze inventory — and OQ-05 — sha256 policy, deferred on ecosystem need; OQ-16 — grant-key identity namespace, deferred on the distributed phase. OQ-04 receive-pack, OQ-06 registry backing, and OQ-08 identity model are resolved: ADR-013, ADR-012, ADR-011). Both gate reviews (001 pre-decomposition, 002 post-remediation) are complete and all their findings are resolved (resolutions: ADR-015/016/017/018); the specs are in reviewed status and decomposition into implementation tasks may begin.

Architecture Context

• docs/research/ — phase 0 research (current source of truth for design direction):
  • vision.md — vision, guiding principles, non-goals
  • gitoxide.md — gix capability/version alignment (sha1 feature pinning is mandatory; default-features = false without a hash feature does not compile)
  • alk-stack.md — alkcall/alkhttp/alktls/alkvault integration surface
  • git-protocol.md — server-side smart-protocol inventory (what we own: advertisement, ls-refs, fetch negotiation, receive-pack)
  • reference-policy.md — license/reuse policy (MPL-2.0 prior art: facts only, never code)
  • pocs.md — POC-1..3 plan gating phase 0 completion
• Sibling crates (published, MIT OR Apache-2.0): alkcall 0.8 (call + channels RPC with ACL; BiStream is the git-session substrate), alkhttp 0.5 (HTTP serving + call adapters), alktls 0.1 (rustls + ACME), alkvault 0.1 (secret encryption). Their architecture docs live in their own repos; alkcall ADRs referenced above are at /workspace/@alkdev/alkcall/docs/architecture/decisions/.
• gitoxide reference clone: /workspace/gitoxide (matches published 0.87.1 plus a few unreleased commits — pin crates.io versions; treat the clone as a reading aid only, never a path dependency).