Skip to content

Commit 6fa0610

Browse files
shreyas-lyzrshreyas-lyzr
committed
docs: add OpenGAP (GitAgentProtocol) research paper
Add paper/ directory with: - open-gap.tex: arXiv-ready LaTeX master (~981 lines) - open-gap.md: detailed Markdown mirror (~862 lines) - bibliography.bib: 22 references (MCP, A2A, FINRA/SEC/SR 11-7, Karpathy LLM Wiki, GitClose, TLA+/Alloy, EU AI Act, ISO 42001) - Makefile: pdflatex + bibtex build - tables/fidelity-matrix.csv: regenerable adapter fidelity data - README.md: build instructions and citation Covers: design lineage (Unix → GitOps → agents), protocol spec with formal 10-tuple definition, 15-adapter portability model with fidelity function, 14 lifecycle patterns grouped into 4 meta-patterns, compliance mapping (FINRA/SEC/SR 11-7/CFPB/EU AI Act/ISO 42001), hook-based enforcement, structural SOD theorem, three case studies, threat model, conformance levels.
1 parent 26d2aaf commit 6fa0610

6 files changed

Lines changed: 2066 additions & 0 deletions

File tree

‎paper/Makefile‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
MAIN := open-gap
2+
LATEX := pdflatex
3+
BIBTEX := bibtex
4+
OUT := $(MAIN).pdf
5+
6+
.PHONY: pdf clean distclean watch
7+
8+
pdf: $(OUT)
9+
10+
$(OUT): $(MAIN).tex bibliography.bib
11+
$(LATEX) -interaction=nonstopmode $(MAIN).tex
12+
$(BIBTEX) $(MAIN)
13+
$(LATEX) -interaction=nonstopmode $(MAIN).tex
14+
$(LATEX) -interaction=nonstopmode $(MAIN).tex
15+
16+
clean:
17+
rm -f $(MAIN).aux $(MAIN).log $(MAIN).bbl $(MAIN).blg $(MAIN).out $(MAIN).toc
18+
19+
distclean: clean
20+
rm -f $(OUT)
21+
22+
watch:
23+
@echo "Rebuilding on change. Requires fswatch (brew install fswatch)."
24+
@fswatch -o $(MAIN).tex bibliography.bib | xargs -n1 -I{} make pdf

‎paper/README.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# OpenGAP Paper
2+
3+
This directory contains the canonical research paper for **OpenGAP** — the GitAgentProtocol — in arXiv-ready LaTeX and a Markdown mirror.
4+
5+
## Files
6+
7+
- `open-gap.tex` — the paper (master source of truth)
8+
- `bibliography.bib` — BibTeX references
9+
- `Makefile` — build rules
10+
- `figures/` — image assets (patterns diagrams, logo, etc.)
11+
- `tables/` — CSV data backing tables that are regenerable from code (e.g., fidelity matrix)
12+
13+
## Build
14+
15+
Requires a TeX distribution with `pdflatex` and `bibtex` (TeX Live, MiKTeX, or MacTeX).
16+
17+
```bash
18+
make pdf # produces open-gap.pdf
19+
make clean # removes LaTeX aux files
20+
make distclean # also removes the PDF
21+
make watch # rebuild on change (requires fswatch)
22+
```
23+
24+
The paper uses only arXiv-compatible packages (`amsmath`, `amssymb`, `graphicx`, `hyperref`, `listings`, `booktabs`, `xcolor`, `geometry`, `authblk`, `microtype`, `caption`), so the same source compiles locally and on arXiv.
25+
26+
## Citing
27+
28+
Preferred BibTeX entry (update year and arXiv id once posted):
29+
30+
```bibtex
31+
@misc{opengap2026,
32+
author = {Shreyas Kapale and {OpenGAP Working Group}},
33+
title = {{OpenGAP: GitAgentProtocol — A Git-Native Protocol for the AI Agent Lifecycle}},
34+
year = {2026},
35+
eprint = {XXXX.XXXXX},
36+
archivePrefix= {arXiv},
37+
primaryClass = {cs.SE},
38+
url = {https://gitagent.sh/paper}
39+
}
40+
```
41+
42+
## Regenerating the fidelity matrix
43+
44+
The fidelity matrix in Appendix B should be regenerated against the current adapters before each submission. The procedure:
45+
46+
1. Run `gapman export --format <adapter> -o /tmp/export-<adapter>` for each of the 15 adapters, against both `examples/standard/` and `examples/full/`.
47+
2. For each adapter output, check whether each of the nine GAP elements (SOUL, RULES, DUTIES, skills, tools, hooks, memory, sub-agents, compliance) is (F) fully preserved, (P) partially preserved, or (-) absent.
48+
3. Commit the result to `tables/fidelity-matrix.csv`.
49+
4. Update the tabular block in `open-gap.tex`, Appendix B, from the CSV.
50+
51+
## Contributing
52+
53+
The paper is maintained alongside the specification. Pull requests that change the spec should also update the paper (or explicitly note why not). Pull requests that improve the paper without changing the spec are equally welcome.

‎paper/bibliography.bib‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
@misc{mcp2024,
2+
author = {{Anthropic}},
3+
title = {Model Context Protocol: Specification},
4+
year = {2024},
5+
howpublished = {\url{https://modelcontextprotocol.io/specification}},
6+
note = {Accessed 2026-04-20}
7+
}
8+
9+
@misc{a2a2024,
10+
author = {{Google}},
11+
title = {Agent-to-Agent (A2A) Protocol},
12+
year = {2024},
13+
howpublished = {\url{https://github.com/google/A2A}},
14+
note = {Accessed 2026-04-20}
15+
}
16+
17+
@misc{schema2020,
18+
author = {Austin Wright and Henry Andrews and Ben Hutton and Greg Dennis},
19+
title = {{JSON Schema: A Media Type for Describing JSON Documents}},
20+
howpublished = {Internet-Draft, IETF},
21+
year = {2020},
22+
url = {https://json-schema.org/draft/2020-12/json-schema-core}
23+
}
24+
25+
@misc{finra_3110,
26+
author = {{Financial Industry Regulatory Authority}},
27+
title = {{FINRA Rule 3110 — Supervision}},
28+
year = {2014},
29+
howpublished = {\url{https://www.finra.org/rules-guidance/rulebooks/finra-rules/3110}}
30+
}
31+
32+
@misc{finra_4511,
33+
author = {{Financial Industry Regulatory Authority}},
34+
title = {{FINRA Rule 4511 — General Requirements (Books and Records)}},
35+
year = {2011},
36+
howpublished = {\url{https://www.finra.org/rules-guidance/rulebooks/finra-rules/4511}}
37+
}
38+
39+
@misc{finra_2210,
40+
author = {{Financial Industry Regulatory Authority}},
41+
title = {{FINRA Rule 2210 — Communications with the Public}},
42+
year = {2013},
43+
howpublished = {\url{https://www.finra.org/rules-guidance/rulebooks/finra-rules/2210}}
44+
}
45+
46+
@misc{finra_2409,
47+
author = {{Financial Industry Regulatory Authority}},
48+
title = {{Regulatory Notice 24-09: FINRA Reminds Firms that FINRA Rules Apply to the Use of Generative AI and LLMs}},
49+
year = {2024},
50+
howpublished = {\url{https://www.finra.org/rules-guidance/notices/24-09}}
51+
}
52+
53+
@misc{sec_17a_4,
54+
author = {{U.S. Securities and Exchange Commission}},
55+
title = {{Rule 17a-4 — Electronic Storage and Records Retention}},
56+
year = {1997},
57+
howpublished = {\url{https://www.sec.gov/rules/final/34-38245.txt}}
58+
}
59+
60+
@misc{sec_reg_bi,
61+
author = {{U.S. Securities and Exchange Commission}},
62+
title = {{Regulation Best Interest (Reg BI)}},
63+
year = {2019},
64+
howpublished = {\url{https://www.sec.gov/regulation-best-interest}}
65+
}
66+
67+
@misc{sec_reg_sp,
68+
author = {{U.S. Securities and Exchange Commission}},
69+
title = {{Regulation S-P — Privacy of Consumer Financial Information}},
70+
year = {2000},
71+
howpublished = {\url{https://www.sec.gov/rules/final/34-42974.htm}}
72+
}
73+
74+
@misc{sr_11_7,
75+
author = {{Board of Governors of the Federal Reserve System}},
76+
title = {{SR 11-7: Guidance on Model Risk Management}},
77+
year = {2011},
78+
howpublished = {\url{https://www.federalreserve.gov/supervisionreg/srletters/sr1107.htm}}
79+
}
80+
81+
@misc{sr_23_4,
82+
author = {{Board of Governors of the Federal Reserve System}},
83+
title = {{SR 23-4: Interagency Guidance on Third-Party Relationships}},
84+
year = {2023},
85+
howpublished = {\url{https://www.federalreserve.gov/supervisionreg/srletters/SR2304.htm}}
86+
}
87+
88+
@misc{cfpb_2022_03,
89+
author = {{Consumer Financial Protection Bureau}},
90+
title = {{Circular 2022-03: Adverse Action Notification Requirements in Connection with Credit Decisions Based on Complex Algorithms}},
91+
year = {2022},
92+
howpublished = {\url{https://www.consumerfinance.gov/compliance/circulars/circular-2022-03-adverse-action-notification-requirements-in-connection-with-credit-decisions-based-on-complex-algorithms/}}
93+
}
94+
95+
@misc{karpathy_llmwiki,
96+
author = {Andrej Karpathy},
97+
title = {{LLM Wiki — a note on a pattern for LLM-managed knowledge bases}},
98+
year = {2025},
99+
howpublished = {GitHub Gist, \url{https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f}}
100+
}
101+
102+
@misc{gitclose,
103+
author = {Priyanshu Priyam},
104+
title = {{GitClose: A git-native reference implementation of the monthly financial close using OpenGAP}},
105+
year = {2026},
106+
howpublished = {\url{https://github.com/Priyanshu-Priyam/gitclose}}
107+
}
108+
109+
@misc{rfc_38,
110+
author = {{OpenGAP Working Group}},
111+
title = {{RFC \#38 — compliance.financial\_governance block (discussion thread)}},
112+
year = {2026},
113+
howpublished = {\url{https://github.com/open-gitagent/gitagent/issues/38}}
114+
}
115+
116+
@misc{opengap_spec,
117+
author = {{OpenGAP Working Group}},
118+
title = {{OpenGAP (GitAgentProtocol) Specification v0.1.0}},
119+
year = {2026},
120+
howpublished = {\url{https://github.com/open-gitagent/gitagent/blob/main/spec/SPECIFICATION.md}}
121+
}
122+
123+
@misc{gapman_npm,
124+
author = {{OpenGAP Working Group}},
125+
title = {{gapman (@open-gitagent/gapman) on npm}},
126+
year = {2026},
127+
howpublished = {\url{https://www.npmjs.com/package/@open-gitagent/gapman}}
128+
}

0 commit comments

Comments
 (0)