Dots accreting into an image. No strokes, no documents — only the sum of marks. And a ledger in the tail.
Stipple is a long-horizon custodian of specifications. It holds requirements as immutable facts with sealed provenance, so that impact is computable and refinement is controlled — a spec that can answer questions about itself that no document can (which requirements were never refined? what breaks if this one changes? who cut this from scope, and when?).
The source of truth is not a document. It is an append-only transaction log. Everything you read — the current spec, the docs, the graph — is a projection of that log, regenerated by replay.
| Layer | Question | Where |
|---|---|---|
| Research programme | WHY | docs/00-working-notes.md, docs/01-supplement.md |
| Kernel | WITH WHAT | docs/03-revision-1-kernel.md (locked) |
| Product | THE THING | docs/04-product-mvp0.md |
| Methodology | HOW YOU WORK | (deliberately empty — written in arrears from dogfooding) |
docs/02-revision-0.md is the superseded kernel draft, kept as corpus.
docs/ the four design documents (+ superseded Rev 0)
corpus/ manifest of the first bootstrap corpus (the docs themselves)
features/ the behavioral specification — Gherkin scenarios (the contract)
features/steps/ step definitions — EMPTY by design; the implementer's job
src/ the kernel and MCP adapter — EMPTY by design; the implementer's job
Read AGENTS.md first. It is the operating manual: session startup
checklist, hard rules (the .feature files are read-only for agents; the log
is append-only; the kernel/adapter boundary is mechanically checked), the
development methodology with its failure-diagnosis taxonomy, and the quality
gates.
The features/ directory is the executable specification. Every named invariant
and core behavior from the kernel spec is a Gherkin scenario.
npm install
npm test # cucumber-js, --strict: all steps undefined → RED
npm run verify # full gate: typecheck + lint + knip + boundary + features + unit coverageTurn it green by implementing (1) the kernel in src/kernel/ and (2) the step
definitions in features/steps/. Green suite = MVP0 kernel done. The suite
is ratcheted: a scenario that has gone green may never go red again, and every
work slice reports the green count.
Philosophy, all the way down: the scenarios are the judgment/spec layer (human-owned); the kernel and step definitions are the mechanism layer. Same split the system itself makes — mechanism in code, judgment in prose.
- Kernel (TypeScript/Node):
append+ all seven guards,replay→ SQLite index, the query set,project→ MD. Implement untilfeatures/is green. - MCP adapter (thin): ~8 tools over the kernel; tool descriptions carry the judgment guidance; provenance stamped server-side.
- Prompt set (versioned): distillation, formalization shapes, triage.
- Bootstrap turn 1: point v0 at
corpus/manifest.md— ingest Stipple's own design documents as the first corpus, then build v1 through v0's tools.
- Truth: one JSONL file — one transaction per line, append-only,
hash-chained, line-versioned (
"v":1). - Index: SQLite, disposable —
rm cache.db && replay, never migrated. - Projection: a generated Markdown directory, read-only by convention.
The log is the only stateful artifact. Everything else is regenerated.
The seven invariants (one active revision per peg; non-empty provenance; resolvable internal refs; tamper-evident parentage; closure under compensation; intra-peg supersede; hash-chain integrity) live in code, on the write path. The model operating v0 must be physically unable to append an invalid transaction. Guards are mechanism; the rest is judgment.
These docs are the last artifacts written the old way. Once ingested, edits happen as transactions, not as file edits.