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.
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 | Exact-head commands plus structural, semantic, workflow, visual, operational, and security 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 |
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 |
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?
| Layer | Tooling | Role |
|---|---|---|
| Runtime | Node.js 20+ | Runs the local writer and validators |
| Validation | tabellio-validate on any trusted worker | Runs exact committed command or typed product validators 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.
| 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/tabellio-merge-ready.mjs | Approval-gated publication of one exact-validation commit status |
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 |
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.jsonConfigure Entire's supported strategy_options.checkpoint_remote in .entire/settings.json to target the private GitHub control repository, and keep strategy_options.push_sessions false. Tabellio preflight fails closed when the effective checkpoint remote differs from the platform control remote or automatic checkpoint pushing could bypass release approval.
Use gate in CI. It persists the same exact-head result but exits non-zero unless the final decision is passed:
tabellio-validate gate --repo . --repo-id github.com/owner/repository --base main --commit HEAD --manifest tabellio.validation.jsonPlan an integrity-bound Tabellio / exact-head-validation status from that exact validation:
tabellio-merge-ready plan \
--repo . \
--commit HEAD \
--out /secure/operator/status-intent.jsonPublishing requires a separate short-lived approval and scoped GitHub credential. The status proves only that the committed validation manifest passed for that head; review clearance, other checks, policy, and merge authority remain separate. See Exact-head validation status.
Validation worktrees and isolated home directories use private system-temporary sessions. --workspace-root /absolute/external/path may select another external parent; repository-internal and .git/** paths are rejected.
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 releaseHook trust failures identify the exact Codex /hooks action required. Release profile additionally requires clean main equal to origin/main.
Before merging a release-capable pull request, synchronize the durable review cycle and require exact-head readiness:
tabellio-review gate \
--repo . \
--repo-id github.com/owner/repository \
--owner owner \
--remote-repo repository \
--number 42 \
--token-file /secure/path/github-token \
--actor pre-merge-gateThe gate exits non-zero for untriaged feedback, unpublished fixes, failed or pending checks, missing exact-head validation, or a pull request that is already merged or closed. Merge approval remains a separate human action.
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.jsonGenerate 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.jsonCapture 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.jsonContext 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. See Product validation for acceptance contracts, typed evidence, cost gates, and repository adapters.
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:checkThese 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.
- Getting started
- Agentic tooling stack
- GitHub code-storage boundary
- Agent run lifecycle
- Approved stack operations
- Durable review and fix loop
- Exact-commit validation
- Exact-head validation status
- Operations hardening
- Workflow model
- Native Git foundation
- Evidence schema
- Codex review
- Research grounding
- Brand system
- Security policy
- Contributing
- Changelog