Research
The CLI team's working documents, published as written: measurements on real vaults, designs and the reviews that corrected them, decisions, security reviews and the bugs found in daily use. Each one takes one question as far as the evidence went on the day it was written. They are the record, so they are not edited here; where one was wrong, a later document says so, usually above the mistake.
Research is not the same as an article. An article makes one argument for a reader, in the newsroom's format, and is written to be read start to finish. A research document is the work itself: tables, open questions, the plan that was later superseded. When a research thread produces an argument, it becomes an article, and the topic page links both.
Topics
Each topic is one open question, with where it stands today: what is shipped, what is designed, what is absent.
Keys, members and who may write
Should the read key and the write key become key pairs, can a vault have members who join and leave by a file each, and can a vault enforce who writes where? What is built, what is designed, and what is still a question.
research topicHistory integrity and signatures
How sgit made a vault's history verifiable without a vault move: signed commits, a format gate, rewind detection, and the compatibility rule that a newer client must never break an older one still writing.
research topicBig vaults and many agents
What happens when a vault reaches 35,000 objects and ten agents use it every day: what a clone fetches, what each session costs, which fixes came from measuring it, and why the server can stay simple.
research topicHow a vault takes writes
One commit per change is right for documents and wrong for a stream, and many small objects cost a request each. Copy-on-write, a write-ahead append lane, a vault in one zip, and pack mode, a zip per push, shipped in 0.24.0: what sgit already does, and what is proposed.
research topicRunning a vault locally
How to run a working vault, UI and API, on your own machine: the research into the server's API, the decision to run the SG/Send container rather than re-implement it, and the runtimes sgit supports.
research topicReviewing sgit's security with tools and agents
A tool-assisted security review of the code the zero-knowledge guarantee lives in: which agent skills and threat-modelling tools were worth running, what each found, and a CI pipeline where an AI review can break the build.
research topicFound in daily use
The bugs that agents and people hit while using sgit every day, each traced to its cause in the code, with what was fixed and what is still open.
Every document, newest first
Pack mode, round 4: the fixes at c5b326f2
The fourth round: no release blockers left. Every finding of the four rounds re-checked, two compactions of the same head run at once on dev and both finish with the vault intact, and three nits.
workflowHow pack mode went from an article to a release, and the documents along the way
How pack mode went from a measured problem to a release in eight days: research before code, a spec reviewed before the build, tests on a counted host, a live trial, four verification rounds by a second agent, and the documents each step left behind.
referencePack mode — feature reference for 0.24.0
The CLI team's one-page reference for pack mode as released in sgit-ai 0.24.0: what it is and why, the commands, the host layout, compression, the numbers to quote, compatibility and the gate, the security model and the tests.
reviewPack mode, round 3: the fixes at 3f2c9bea
The third round: everything from round two fixed or accepted, both UX items fixed live, and one new data-loss path, caused by a round-two fix: an aborting compaction deleted a snapshot that another compaction had adopted. The fix was to delete two lines.
responseResponse to "Pack mode, round 3" (21 Oct 2026)
The answer to round three: the round-two clean-up was the bug, so an aborted compaction now leaves its snapshot; a 404 on an already archived pack is success; the gate exemption needs the hex form.
responseResponse to "Pack mode, verified again" (round 2, 21 Oct 2026)
The answer to round two: a clone chooses its snapshot by the branch head, a pack that names a member twice is refused whole, an aborted compaction takes its snapshot back, and the gate exemption checks every feature.
reviewPack mode, verified again: the fixes at 801b890c
The second round: six of the eight fixes hold, two are partial. An aborted compaction could still leave an older snapshot that fresh clones took as the newest, and two zip entries with the same name got past the new zip-bomb check. Checked live against sgit-ai 0.23.0 from PyPI.
responseResponse to "Pack mode, verified" (21 Oct 2026)
The CLI team's answer to the first verification round: all eight findings agreed and fixed with a test each, three more found in its own pass, and the how-to corrected.
reviewPack mode, verified: tests, a code review, and a live trial on dev
The first verification of pack mode, before release: the 4,511 tests, the tester's how-to run step by step on dev, a normal vault against a pack vault on the same server (a published 2,087-object vault cloned in 8.6 s against 28.6 s), and a code review with a reproducing script for each of eight findings, two of them data loss in compaction.
how-toHow to test pack mode (for an agent or a person, on a throwaway vault)
The CLI team's page for testing pack mode on throwaway vaults, step by step: create, push and pull between clones, compaction, the round trip, what to report and the known limits.
measurementPack mode: the round trip, built and measured
What was built for pack mode, how the round trip from a normal vault to a pack vault and back is tested, and every measurement: the synthetic request-count gates, the live trial with the comms vault's 33,000 objects (a 25 s clone against 3½ minutes), and the reviewer's numbers.
specSpec: pack mode for sgit (CLI-only, packs-only vaults, no server change)
The specification for pack mode: every push writes one zip pack, a snapshot pack compacts them, nothing is deleted, large packs go straight to S3 by presigned URL, and a gated packs-only vault needs no server change. Commands, layout, failure handling, tests and the four performance runs.
responseResponse to "Pack mode, round 4" (22 Oct 2026)
The answer to round four: no blockers, and the three nits done; "already gone" is decided by the status code, never by "404" inside a pack name.
briefBrief to the SG/Send team: append to a vault object on S3 without re-uploading it, and conditional completes
A brief to the SG/Send team: a presigned append route that grows a zip on S3 by UploadPartCopy, conditional completes with If-Match and If-None-Match, and size and ETag with the read URL. Written for a single appended zip; the pack-mode spec of the next day needs none of it for its first version.
coverage mapKeys the way git does them, PKI access to a vault, and copy-on-write: what is already published, and what is not
Before writing two articles, a map of what is already published on keys the way git does them, PKI access to a vault and copy-on-write: seven questions from the memo, where each stands, the facts the articles must not get wrong, and seven code questions for the thread.
reviewResponse to "Scion and sgit" (newsroom.sgit.ai, article No. 141, v1.0.0)
The CLI team's response to the newsroom's "Scion and sgit" article: what it gets right, the three factual errors, and the measurements from a 35k-object vault the article should have carried.
fixResponse to "sgit issues found on 14 October 2026", and the comms-vault performance report
The issues reported on 14 October, each traced to its cause in the code, with what was fixed in the same push and what was left open.
designSecurity CI: a dedicated pipeline, and an AI review that can break the build
A dedicated security pipeline on every pull request, and a keyless AI security review that can break the build on anything new: why, how it is wired, and what it costs per reviewed change.
findingAC-L-001 / TM-R36 — characters outside [a-zA-Z0-9/\_.- ] in paths: what really happens
Characters outside a narrow set in a path are silently rewritten, so one vault gets two roots and a false push conflict. What really happens, reproduced, and a fix that raises an alarm instead of rewriting.
decisionsgit serve: container first. Options map and spike results
The decision to run the SG/Send container image rather than re-implement the server: the runtimes supported (including Apple's container and Podman), the spike results, and phase 1 as built.
researchsgit serve: running a vault locally — research and plan
How to run a vault locally: the vault server's API inventory, the browser modes, when TLS is and is not needed, and how much plumbing sgit would need.
case studyCase study — a tool-assisted security review of sgit-ai 0.21.0 (round 1)
What each tool found in the round-1 security review of sgit-ai 0.21.0, with counts and cost: the skill vetting, the derived graph, 270 function records, 68 STRIDE threats and the insider overlay.
researchThreat-modeling tools for an agent-driven review — Matt Adams' stack, the classics, and the house method
Threat-modeling tools for an agent-driven review: Matt Adams' stack (STRIDE GPT, the insider-threat model), the classics, and the house method, with the agent itself named as an actor.
researchAgent skills for security review — what exists, what it would do here
Agent skills for security review, each checked at its source, ranked by whether it brings a method, a tool with deterministic output, or vets the other skills, against this code base.
planPlan — the next security review of sgit-ai, with skills, and the review graphs it produces
The plan for a tool-assisted, data-producing security review of one slice of sgit-ai: the code the zero-knowledge guarantee and the trust boundaries live in.
designSealed files — a second encryption layer on top of a vault
A second encryption layer on top of either vault mode: files sealed to named recipients with ECDH P-256, HKDF and AES-256-GCM, with the corrections from the sgit.ai agent's review.
designNative PKI vault mode — architecture map
An architecture map for a second vault mode built on key pairs from the start, revised twice after review: sequence-number pinning, frozen hosts, concurrent writers.
analysisRead and write keys as PKI — design analysis
Are the read key and the write key really a public and a private key? Half right: the write key should become a signing key, and the read key cannot become a public key. What that would take.
reviewBranches check, test performance, test quality — 8 Oct 2026
An end-to-end check found that branches did not work. What was fixed behind it, the tests that now cover it, and a review of the test suite's speed and quality.
roadmapPossible future features, after 0.21.0
The git-parity and security ideas that are not in 0.21.0, what each would take and what it could break, starting from the constraint that a new commit field breaks older clients' signature checks.
reviewReview: "Git security features → sgit: a one-way mapping
A review of the one-way map from git's security features to sgit, checked against the code: three corrections, one missing gap, and the four easy gaps closed for 0.21.0.
analysisCompatibility matrix: sgit CLI × vault web UI × SG/Send API, across the integrity roll-out
The CLI, the vault web UI and the SG/Send API across the integrity roll-out, step by step: what each version reads, writes and loses, under the rule that no client may break another still writing.
measurementHistory integrity: what the three fixes would cost, and how to ship them without a vault move
What signature verification, ref monotonicity and 128-bit ids would cost, measured on a real vault, and how to ship all three without a vault move.
designPartial clones — a folder scope and a history depth (6 Oct 2026)
Cloning just the folders an agent reads and writes, read and write, plus a shallow mode, without changing the full clone: the Merkle-spine idea and the measurements.
fixFix — sgit pull silently discarded uncommitted edits to tracked files
sgit pull silently discarded uncommitted edits to tracked files. The root cause, and the fix: git's rules for the working tree, applied before any write.
measurementClone performance — the tree walk re-fetched shared sub-trees once per parent
A clone stuck walking trees: the walk re-fetched shared sub-trees once per parent, 10,098 requests for 2,236 unique trees. The instrumented run and the fix.
Where these come from
The CLI repository, team/humans/dinis_cruz/claude-code-web/MM/DD/, written by the CLI team's agents (Claude Code sessions) for Dinis Cruz between 2 and 20 October 2026. admin/build/import_cli_research.py copies them here with a front matter and nothing else; each page names its source file, commit and branch. This import was taken from commit 5473571 on the CLI's working branch claude/charming-babbage-5hzcxq, which holds everything on dev plus the documents of 16 and 20 October that were not yet merged when they were published here.
This page as markdown · its source, admin/content/research/index.md