Skip to content

Commit f1ac8e1

Browse files
SuperInstanceSuperInstance
committed
[FLEET] Dockside exam checklist + tender protocol
1 parent ad3eb90 commit f1ac8e1

1 file changed

Lines changed: 201 additions & 0 deletions

File tree

‎DOCKSIDE-EXAM.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Coast Guard Dockside Exam — Fleet Certification Checklist
2+
3+
**Every repo in the Cocapn fleet must pass this exam.**
4+
**A lighthouse-keeper won't let you on the water without it.**
5+
6+
---
7+
8+
## What This Is
9+
10+
When a keeper sees your vessel on its waters, it checks: is this ship seaworthy? Can it operate independently? Can it report back? Can it be rescued if something goes wrong?
11+
12+
This checklist is the dockside exam. Every repo — every agent, every library, every tool — should be able to tick every box that applies to it.
13+
14+
---
15+
16+
## Section 1: GitHub Hygiene
17+
18+
- [ ] **README.md exists** — Anyone who lands here knows what this is in 10 seconds
19+
- [ ] **Description set** — GitHub repo description is filled in (shows in search)
20+
- [ ] **Topics tagged** — At least 3 GitHub topics for discoverability
21+
- [ ] **License file** — MIT, Apache-2.0, or documented why proprietary
22+
- [ ] **.gitignore** — No secrets, no node_modules, no build artifacts committed
23+
- [ ] **No secrets in git history** — API keys, tokens, passwords are in .env or environment
24+
- [ ] **Default branch is `main`** — Not `master` (fleet standard)
25+
- [ ] **Branch protection** — At least on main for critical repos
26+
- [ ] **Clean commit history** — No "fix", "wip", "asdf" commits on main
27+
- [ ] **Commit convention** — `[AGENT-NAME] description` format for attribution
28+
29+
## Section 2: CI/CD Pipeline
30+
31+
- [ ] **GitHub Actions** — `.github/workflows/ci.yml` exists and passes
32+
- [ ] **Tests run on push** — Every push to PR/main triggers tests
33+
- [ ] **Lint/format check** — Code style is validated automatically
34+
- [ ] **Build check** — Project builds successfully (compile, bundle, etc.)
35+
- [ ] **Release tags** — Version tags for stable releases
36+
- [ ] **Changelog** — CHANGELOG.md or release notes exist
37+
- [ ] **Badges in README** — Build status, coverage, version visible at a glance
38+
39+
## Section 3: Package/Registry Readiness
40+
41+
**For crates (Rust):**
42+
- [ ] `Cargo.toml` has name, version, description, license, repository
43+
- [ ] `cargo publish --dry-run` succeeds
44+
- [ ] Published to crates.io (if public library)
45+
46+
**For npm (JavaScript/TypeScript):**
47+
- [ ] `package.json` has name, version, description, main/types
48+
- [ ] `npm publish --dry-run` succeeds
49+
- [ ] Published to npm (if public library)
50+
51+
**For PyPI (Python):**
52+
- [ ] `pyproject.toml` or `setup.py` with name, version, description
53+
- [ ] `python -m build` succeeds
54+
- [ ] Published to PyPI (if public library)
55+
56+
**For Go:**
57+
- [ ] `go.mod` has module path matching repo URL
58+
- [ ] `go test ./...` passes
59+
- [ ] Tagged with semver for `go get` compatibility
60+
61+
**For C/C++:**
62+
- [ ] `Makefile` or `CMakeLists.txt` that builds cleanly
63+
- [ ] `make install` target works
64+
- [ ] Header files are self-documenting
65+
66+
## Section 4: Agent Vessel Certification
67+
68+
**If this repo IS an agent (git-agent standard):**
69+
70+
- [ ] **CHARTER.md** — Purpose, contracts, constraints
71+
- [ ] **ABSTRACTION.md** — Primary plane, reads/writes, compilers
72+
- [ ] **STATE.md** — Current health, last active, blockers
73+
- [ ] **TASK-BOARD.md** — Prioritized work items
74+
- [ ] **SKILLS.md** — What this agent can do
75+
- [ ] **IDENTITY.md** — Name, model, vibe, emoji
76+
- [ ] **DIARY/** — Learning journal, at least one entry
77+
- [ ] **for-fleet/** — Bottle directory for outbound messages
78+
- [ ] **from-fleet/** — Bottle directory for inbound messages
79+
- [ ] **GIT-AGENT-STANDARD.md** — The fleet standard (read and followed)
80+
81+
## Section 5: Documentation
82+
83+
- [ ] **Usage instructions** — How to run/use this thing
84+
- [ ] **API documentation** — If it exposes an API, it's documented
85+
- [ ] **Examples** — At least one working example
86+
- [ ] **Architecture overview** — How the pieces fit together
87+
- [ ] **Contributing guide** — How others (agents or humans) can contribute
88+
89+
## Section 6: Operational Readiness
90+
91+
- [ ] **Health check endpoint** — If it's a service, `/health` responds
92+
- [ ] **Graceful shutdown** — Handles SIGTERM cleanly
93+
- [ ] **Configuration** — All config via env vars or config files, not hardcoded
94+
- [ ] **Logging** — Structured logs, not just print statements
95+
- [ ] **Error handling** — Errors are caught, reported, don't crash the service
96+
- [ ] **Resource limits** — Memory/CPU limits documented if running as a service
97+
98+
## Section 7: Tender Compatibility
99+
100+
**Can a tender vessel service this repo in the wild?**
101+
102+
- [ ] **Works offline** — Can run without internet (for edge/tender scenarios)
103+
- [ ] **Clone depth 1 works** — Can boot from shallow clone
104+
- [ ] **Dependencies documented** — All requirements listed and versioned
105+
- [ ] **State is portable** — Agent state can be exported/imported
106+
- [ ] **Commits are self-contained** — Each commit tells a complete story
107+
- [ ] **Can rewind** — `git checkout` to any prior commit produces a working state
108+
109+
---
110+
111+
## Scoring
112+
113+
| Category | Max Score | Passing |
114+
|----------|-----------|---------|
115+
| GitHub Hygiene | 10 | 7 |
116+
| CI/CD | 7 | 4 |
117+
| Package Registry | 3-4 | 2 |
118+
| Agent Vessel | 10 | 7 (if agent) |
119+
| Documentation | 5 | 3 |
120+
| Operational | 6 | 4 |
121+
| Tender Compat | 6 | 3 |
122+
| **Total** | **~47** | **~30** |
123+
124+
A repo that scores below 30 needs work before it goes to sea.
125+
126+
---
127+
128+
## Who Checks This
129+
130+
- **Lighthouse Keeper** — Checks on every heartbeat for vessels in its waters
131+
- **Tender** — Checks when it visits a remote agent in the wild
132+
- **Fleet Mechanic** — Can be dispatched to fix failing repos
133+
- **Self-check** — Any agent can run this against its own repo
134+
135+
---
136+
137+
## The Tender Protocol
138+
139+
### What Is a Tender?
140+
141+
A tender is a mobile agent that visits remote/edge agents. It:
142+
- Carries updates (new code, new locks, new standards)
143+
- Collects work (commits, diary entries, bottles)
144+
- Thinks alongside the edge agent on local changes
145+
- Syncs with GitHub when back in range
146+
147+
### How Tenders Work
148+
149+
```
150+
TENDER APPROACHES → DOCKSIDE EXAM → EXCHANGE → DEPART
151+
↑ |
152+
└──────── returns to lighthouse ──────────┘
153+
```
154+
155+
**1. Approach**
156+
- Tender detects agent via local network, bluetooth, or scheduled visit
157+
- No internet required — this is local-only communication
158+
159+
**2. Dockside Exam**
160+
- Tender runs this checklist against the agent's repo
161+
- Agent shows its STATE.md, TASK-BOARD.md, recent commits
162+
- If passing, proceed to exchange. If not, tender can help fix issues
163+
164+
**3. Exchange**
165+
- **Tender gives:** Updates from fleet (pull from master), new standards, lock libraries, firmware
166+
- **Agent gives:** Commits since last visit, diary entries, bottles for fleet, test results
167+
- **Both think:** If agent needs changes, tender can iterate locally — run tests, make commits
168+
- **Tender carries the diff:** When back in range, tender pushes agent's work to GitHub master
169+
170+
**4. Depart**
171+
- Agent's local clone is now current
172+
- Tender carries outbound commits/bottles
173+
- Next visit scheduled or on-demand
174+
175+
### The Clone Is The Agent
176+
177+
The GitHub repo is the master copy. When a tender clones it to an edge device:
178+
- That clone IS the agent running in the wild
179+
- Commits made locally are carried back by the tender
180+
- The master can rewind to any prior state via git history
181+
- A new model can bootcamp from any commit — that commit IS a training snapshot
182+
183+
### Rewind and Bootcamp
184+
185+
```
186+
git log --oneline # see all previous states of this agent
187+
git checkout abc123 # rewind to a specific state
188+
# Bootcamp: feed this state to a new model as context
189+
# Fine-tune: the commit history IS the training data
190+
```
191+
192+
Every commit is a snapshot of the agent's capability at that moment.
193+
A dojo can replay the commits to train any model to become that agent.
194+
The diary entries are the human-readable training notes.
195+
The code changes are the skill acquisitions.
196+
The bottles are the social learning.
197+
198+
---
199+
200+
*This document is part of the Git-Agent Standard v2.0*
201+
*Deployed to every fleet repo. Maintained by the Lighthouse Keeper.*

0 commit comments

Comments
 (0)