Tabellio

GitHub-native context and evidence for agentic development.

Tabellio gives coding agents a deterministic Git foundation: standard Git repositories, isolated worktrees, immutable commit IDs, merge previews, compare-and-swap ref updates, and context packets tied to the exact diff. GitHub stores code and provides a thin pull-request shell. Tabellio keeps agent transcripts, review state, validation results, and control refs outside that public code-storage boundary.

What It Adds

Tabellio attaches a structured evidence packet to a pull request. The packet is small enough to inspect in review and strict enough to validate in CI.

Area	Evidence
Task	Source request, issue, ticket, or manual prompt summary
Git	Repository, base branch, head branch, commit SHA, and PR metadata
Runtime	Human, CI, or agent runtime that produced the change
Diff	Changed files
Validation	Commands run and check results
Approvals	Required, granted, denied, or skipped approvals
Side effects	Deployment, migration, infra, billing, secret, provider, and destructive-action policy
Artifacts	Evidence files generated by the run

Native Git Foundation

The native engine runs through the installed git executable. It never constructs shell commands.

Component	Role
GitProcess	Executes argument arrays with prompts disabled and typed failures
RepositoryStore	Repository contract for Tabellio's GitHub-backed workflow
NativeGitStore	Reads commits and diffs, manages worktrees, previews merges, and updates refs safely
WorkspaceManager	Gives each agent run a contained worktree path
Context packet	Binds task, actor, exact commits, changed files, checkpoints, and merge status
Agent-run CLI	Orchestrates start, checkpoint, validation, status, and safe promotion

Review Questions

AI-assisted pull requests should not depend on reviewer trust alone. Tabellio gives reviewers a repeatable answer to:

• What changed?
• Why did it change?
• What commands ran?
• What failed or was skipped?
• Did the workflow try to deploy, migrate, read secrets, touch billing, or mutate infrastructure?
• Where is the machine-readable audit packet?

Workflow Stack

Layer	Tooling	Role
Runtime	Node.js 20+	Runs the local writer and validators
Validation	tabellio-validate on any trusted worker	Runs an exact committed command manifest and stores results on a Git ref
Evidence contract	JSON Schema	Validates the evidence envelope and external-action policy
Code storage	GitHub	Stores code refs and tags; provides a thin pull-request shell
Stacked review	git-spice	Stack engine for small dependent GitHub pull requests
Checkpoint ledger	Entire and Entire CLI	Required default for agent session and checkpoint context
Git substrate	Standard Git CLI, bare repositories, and worktrees	Stores repositories, branches, commits, patches, and agent-created code state
Agent review	OpenAI Codex	Produces findings imported into the durable GitHub review ledger
Prior art	SLSA and in-toto	Inspiration for provenance and supply-chain evidence, without a compliance claim

origin is the canonical GitHub code remote. Entire is the required checkpoint ledger; git-spice manages stacks; Tabellio owns validation and durable review state. Private control refs are external state and are rejected when their destination is origin.

Core Files

Path	Purpose
tabellio.platform.json	Code-storage boundary, stack, ledger, validation, review, and control-ref contract
schemas/	Evidence and external-action JSON schemas
scripts/providers/native-git-store.mjs	Standard Git storage provider
scripts/providers/git-spice-stack-manager.mjs	Read-only git-spice stack adapter
scripts/providers/git-spice-operations.mjs	Approval-gated git-spice submit, update, sync, restack, and merge adapter
scripts/providers/entire-ledger-provider.mjs	Metadata-only Entire checkpoint adapter
scripts/providers/github-provider.mjs	Read-only GitHub pull-request, review, comment, status, and check adapter
scripts/lib/git-json-ledger.mjs	Versioned, compare-and-swap JSON state on standard Git refs
scripts/lib/review-cycle.mjs	Durable GitHub and agent review/fix state machine
scripts/lib/validation-runner.mjs	Exact-commit, shell-free validation with bounded evidence logs
scripts/lib/control-ref-transport.mjs	Approval-gated, fast-forward-only sharing of review, validation, and Entire refs
scripts/tabellio-preflight.mjs	Fail-closed GitHub, Entire, hook-trust, and release-main readiness checks
scripts/tabellio-release.mjs	Integrity-bound post-merge control-ref, tag, and GitHub release orchestration
scripts/lib/	Git process, repository contract, worktree, and context primitives
scripts/	Dependency-free capture, writer, and validators
examples/	Minimal valid context, evidence, review, validation, stack, and ledger fixtures
templates/	Pull request checklist for evidence-backed review
docs/	Setup, schema, workflow model, Codex review, tooling stack, and research grounding

Quick Start

Enable the required ledger, initialize stacks, and validate the canonical platform contract:

entire enable --agent codex --project
git-spice repo init
npm run tabellio:platform:check
node scripts/tabellio-validate.mjs run --repo . --commit HEAD --manifest tabellio.validation.json

Keep origin limited to ordinary code branches and tags. Configure a separate private GitHub repository under another remote name before publishing control refs. The transport refuses to target origin.

Before agent or release work, run:

node scripts/tabellio-preflight.mjs --profile agent
node scripts/tabellio-preflight.mjs --profile release

Hook trust failures identify the exact Codex /hooks action required. Release profile additionally requires clean main equal to origin/main.

Validate the bundled fixture:

node scripts/check-tabellio-evidence-envelope.mjs --evidence examples/tabellio-evidence/minimal-evidence.json
node scripts/check-tabellio-external-actions.mjs --evidence examples/tabellio-evidence/minimal-evidence.json

Generate evidence from the current Git state:

node scripts/write-tabellio-evidence-envelope.mjs --out tabellio-pr-evidence.json
node scripts/check-tabellio-evidence-envelope.mjs --evidence tabellio-pr-evidence.json
node scripts/check-tabellio-external-actions.mjs --evidence tabellio-pr-evidence.json

Capture GitHub-bound context first, then bind evidence to it:

node scripts/capture-tabellio-context.mjs \
  --repo . \
  --repo-id IntelIP/Tabellio \
  --base main \
  --head HEAD \
  --out tabellio-context.json
node scripts/check-tabellio-context.mjs --context tabellio-context.json
node scripts/write-tabellio-evidence-envelope.mjs \
  --context tabellio-context.json \
  --out tabellio-pr-evidence.json

Context capture requires an Entire checkpoint by default. For legacy Git-note repositories during migration, pass --ledger git-note explicitly.

Run the local agent lifecycle:

node scripts/tabellio-run.mjs start \
  --run-id run-42 \
  --repo . \
  --base main \
  --task-summary "Add deterministic import validation"

# Edit and commit inside the returned workspace path, then:
node scripts/tabellio-run.mjs checkpoint --run-id run-42 --repo . --summary "Implementation committed"
node scripts/tabellio-run.mjs finish --run-id run-42 --repo . -- npm test
node scripts/tabellio-run.mjs promote --run-id run-42 --repo .

See Agent run lifecycle for state and failure behavior.

Package scripts:

npm run check
npm run tabellio:run -- status --run-id run-42
npm run tabellio:run:example:check
npm run tabellio:stack -- --repo . --repo-id IntelIP/Tabellio --out tabellio-stack.json
npm run tabellio:stack:check
npm run tabellio:stack:operation:example:check
npm run tabellio:review:example:check
npm run tabellio:validate:example:check
npm run tabellio:ledger -- --repo . --repo-id IntelIP/Tabellio --base main --head HEAD --out tabellio-ledger.json
npm run tabellio:ledger:check
npm run tabellio:context:capture
npm run tabellio:context:check
npm run tabellio:evidence:write
npm run tabellio:evidence:check
npm run tabellio:external-actions:check

Protected Action Classes

These actions require explicit approval before attempted execution:

• deployment
• database migration
• infrastructure change
• DNS or hosting change
• billing or live-money action
• credentialed provider read
• secret-value read
• destructive workspace action

The external-action checker fails when an action is marked attempted: true without approved: true.

Docs

• Getting started
• Agentic tooling stack
• GitHub code-storage boundary
• Agent run lifecycle
• Approved stack operations
• Durable review and fix loop
• Exact-commit validation
• Operations hardening
• Workflow model
• Native Git foundation
• Evidence schema
• Codex review
• Research grounding
• Brand system
• Security policy
• Contributing
• Changelog

License

Apache-2.0. See LICENSE and NOTICE.