Home

SAIPEN

Continuation protocol for AI coding agents. Project memory in plain markdown. Cold agent with zero history runs /saipen continue, reads STATE->BOARD->LOG tail, executes next_action, resumes in under a minute. Any vendor, any day.

v7.121.0 | MIT | Spec | RFC |

---

One command. Zero dependencies. Zero amnesia.

User  ->  /saipen continue
Agent ->  reads STATE.md (phase, task, next_action, mode, human_note)
Agent ->  reads BOARD.md (DOING / TODO / DONE / BLOCKED tickets)
Agent ->  reads active LOG.md tail (recent events)
Agent ->  executes next_action immediately
Agent ->  loads phase doc only when rules needed
Agent ->  Works.

12 commands, full surface

Command	Effect
saipen set / saipen init	Bootstrap .saipen/
saipen continue / bare saipen	Resume from STATE
saipen goal <text>	Pivot to objective, run to completion
saipen plan	Enter PLAN phase
saipen clean	Deep repo scrub
saipen translate	Isolated translation build
saipen markhunt	Dry exhaustive audit (record only)
saipen prepare	Package work for handoff
saipen ship	Version bump, tag, push
saipen validate	Run conformance checker
saipen status	Read-only board report
saipen stop	Checkpoint + halt

Two layers

Layer	Required	Purpose
Core	✅	Continue work safely
Maintenance	On top of Core	Evolve software with no tasking

Core state machine: INIT -> PLAN -> SCOUT -> BUILD -> VERIFY -> REVIEW -> SHIP -> DONE | BLOCKED

Autonomous evolution: Empty board at DONE -> auto HUNT -> ADD -> HUNT... until mature or capped (3 waves / 20 tickets).

Goal mode: saipen goal <objective> - autonomous run with safety valve. Auto-pivots, auto-ships, auto-hunts. Stops at maturity or caps.

Key features v7.121.0

• WAIT categories (v7.93.0): Closed 7-word vocabulary — manual-verify, destructive-op, first-publish, user brake, blocked, safety valve, init. Makes stopping mechanically distinguishable.
• Cross-document drift detector (v7.93.0): tools/validate.py parses 6 sets from RFC, FAILs on schema/validator/BOOT/CONFORMANCE disagreement.
• Portable floor (v7.94.0-97.0): validate.sh + validate.ps1 probe all 9 RFC SS1.2 fields, frozen against new checks. Audited by tools/audit_floor.py — 20 mutations, both halves proven red (v7.100.0).
• SubSaipen protocol (v7.91.0): OUTBOX validated (status/summary/critical), patch-with-evidence format, read-only workers. Sub liveness now machine-checked: never-run instances WARN, unreviewed findings WARN (v7.99.0).
• Determinism invariants (v7.86.0-92.0): fixed action priority, RECOVER/FINISH/START hierarchy, one-ticket-at-a-time.
• CI gates pushes (v7.98.0): validate.yml fires on push to main/master and pull_request, with concurrency group. Pre-commit hook remains the opt-in per-machine gate.
• Drift hunt validation (v7.98.0): validate.py expanded to subSaipen next_action, self-transition enum, adapter paths. Plus (v7.102.0): all 9 adapters now name BOOT.md — no cold agent pays 25x the necessary read.
• SubSaipen production ready (v7.98.0): 4 live instances running since v7.84.0.
• Validator linted (v7.99.0): 9 cp1251-mangled section signs found inside its own FAIL messages — valid UTF-8, invisible to its own U+FFFD check. Repaired; CI runs ruff. Push claims now verified against git — a next_action claiming "pushed" with local-only commits FAILs.
• Doc inventory (v7.100.0): 184 shipped documents accounted for. Every one under a check or exempt with a stated reason. No more orphan files at phantom paths.
• Citation resolution (v7.101.0): every SS N.N and phases/.md reference in a shipped doc must name something that exists. 103 docs scanned, zero dangling.
• KNOWLEDGE/ under checks (v7.101.0): traps.md and decisions.md both taught a WAIT-at-DONE rule superseded 9 releases earlier. No more blanketed exemptions for project data.
• Mojibake lint (v7.103.0): 5 cp1251 corruption sequences detected across every shipped doc, not a curated 4. Found a mangled arrow in traps.md — the very file documenting the corruption.
• Phantom version check (v7.104.0): cited versions must exist in release ledger (git tags + CHANGELOG), not merely sit below VERSION. Ledger halves compared.
• Release.yml fix (v7.105.0): fetch-depth: 0 in CI — no more shallow-clone blind spots. make_latest pinned to highest semver.
• Palette Vintage Golden (v7.106.0-107.0): UI palette named, 18 tokens defined, 46 files renamed. Guard survives its own rename.
• Nine unclaimed MUSTs (v7.108.0): 3 RFC sections with 9 MUSTs and zero CONFORMANCE rows. Workspace hygiene now enforced mechanically.
• Tag audit (v7.109.0): tools/audit_tags.py sweeps every tag against VERSION. Found 4 pre-existing mismatches.
• UTF-16 encoding crash (v7.110.0): validator died on first UTF-16 STATE.md. All 3 checkpoint files encoding-checked up front. schema_version future-WARN.
• read-only dual meaning (v7.111.0): Core vs subSaipen read-only clarified — 7 banned phases vs 4. HUNT->DONE legal for subSaipen. Sub STATE checked against Core rules.
• audit_order.py (v7.112.0): catches use-before-define NameErrors invisible to ruff. requires: and saipen_version now meaningfully checked.
• Hook generation stamp (v7.113.0): pre-commit hook carries stamp, validator compares. Fail-open path now prints repair command.
• BOOT.md language rule (v7.114.0): reply-language rule carried in BOOT.md itself. Ambient-signal ban covers repo contents. Estonian alias resolved.
• last_event + TEMPLATE check (v7.115.0): STATE freshness marker enforced. TEMPLATE placeholders cannot escape into live instances.
• claim_time validation (v7.116.0): claim_time checked as ISO-8601 UTC. Half-claim (owner without time) warns. warn() prints category on every line.
• review_passes + digest freshness (v7.117.0): review_passes cap enforced. Digest named v7.83.0 — 33 releases stale.
• MARKHUNT manifest (v7.118.0): closure manifest validated — shape, cursor, vector completeness. no-git head pair must be a pair.
• audit_checks.py (v7.119.0): 41-mutation harness proving validator checks still go red. Control run is precondition.
• Portable floor honest wording (v7.120.0): floor stopped claiming conformance in validator's words. tools/audit_parity.py guards baseline.
• bash vs sh trap (v7.121.0): find_bash() picks real bash, never sh. Control-failure names which tool and exit code.

Quick Start

git clone https://github.com/vacterro/saipen
cd saipen
powershell -ExecutionPolicy Bypass -File .\bootstrap\inject.ps1     # Windows
bash bootstrap/inject.sh                                            # macOS / Linux

Paste to any agent: Read <clone>/saipen/BOOT.md first (cold-start kernel), then <clone>/saipen/RFC.md + <clone>/saipen/STYLE.md

Windows users: inject.sh now converts paths via cygpath -w under git bash / MSYS / Cygwin — no more dead paths in CLAUDE.md that no Windows agent can open (v7.100.0).

ДED Voice

"Без SAIPEN: открываешь проект через неделю — 'кто тут? что за код? где я остановился?' С SAIPEN: 'привет, продолжай, T-42 в DOING, verify не было, чини.' Один чтение — и работаешь. Никакого 'расскажи что ты делал'. Никакого 'дай контекст'. Просто STATE.md открыл — и всё понял."

---

GitHub | 32 locale guides | Changelog