From 5a8ebfece7cfcb2c6b65aefa6ac774f369081aed Mon Sep 17 00:00:00 2001 From: hudsonaikins-crown Date: Sun, 4 Oct 2026 01:05:22 -0400 Subject: [PATCH 1/3] docs: revamp onboarding and repository harness Entire-Checkpoint: 4a06f28905d9 --- .buildkite/scripts/provenance-coverage.sh | 2 +- .github/ISSUE_TEMPLATE/bug.yml | 47 ++ .github/ISSUE_TEMPLATE/config.yml | 5 + .github/ISSUE_TEMPLATE/feature.yml | 43 ++ .github/pull_request_template.md | 43 ++ AGENTS.md | 79 ++- CONTRIBUTING.md | 165 +++--- README.md | 473 ++++-------------- SECURITY.md | 95 ++-- docs/README.md | 44 ++ docs/getting-started.md | 262 +++------- docs/harness.md | 61 +++ docs/historical/README.md | 24 + .../intb-261-p1b-execution-contract.md | 4 +- .../intb-261-p2-execution-contract.md | 4 +- .../intb-261-p3-execution-contract.md | 4 +- .../intb-261-p4-execution-contract.md | 4 +- .../intb-261-p5-execution-contract.md | 4 +- .../intb-261-p6-execution-contract.md | 4 +- .../intb-261-p7-execution-contract.md | 4 +- .../intb-261-p8-execution-contract.md | 0 .../intb-261-p9-execution-contract.md | 0 .../intb-261-pr28-thread-ledger.json | 0 .../intb-261-review-remediation-strategy.md | 4 +- .../intb-261-successor-finding-ledger.json | 0 .../intb-279-v060-execution-contract.md | 0 docs/operate-and-release.md | 124 +++++ docs/provenance.md | 129 +++++ docs/try-tabellio.md | 68 +++ package.json | 12 +- scripts/check-docs.mjs | 159 ++++++ tabellio.analytics-validator.validation.json | 2 +- tabellio.analytics.validation.json | 2 +- tabellio.baseline-integration.validation.json | 2 +- tabellio.buildkite-collector.validation.json | 2 +- tabellio.delivery-claims.validation.json | 2 +- tabellio.delivery-report.validation.json | 2 +- tabellio.deployment-receipt.validation.json | 2 +- tabellio.github-release.validation.json | 2 +- tabellio.plane-collector.validation.json | 2 +- templates/pull_request_template.md | 16 + tests/context-and-evidence.test.mjs | 11 +- tests/docs-check.test.mjs | 79 +++ 43 files changed, 1266 insertions(+), 725 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature.yml create mode 100644 .github/pull_request_template.md create mode 100644 docs/README.md create mode 100644 docs/harness.md create mode 100644 docs/historical/README.md rename docs/{ => historical}/intb-261-p1b-execution-contract.md (95%) rename docs/{ => historical}/intb-261-p2-execution-contract.md (95%) rename docs/{ => historical}/intb-261-p3-execution-contract.md (95%) rename docs/{ => historical}/intb-261-p4-execution-contract.md (96%) rename docs/{ => historical}/intb-261-p5-execution-contract.md (94%) rename docs/{ => historical}/intb-261-p6-execution-contract.md (95%) rename docs/{ => historical}/intb-261-p7-execution-contract.md (95%) rename docs/{ => historical}/intb-261-p8-execution-contract.md (100%) rename docs/{ => historical}/intb-261-p9-execution-contract.md (100%) rename docs/{ => historical}/intb-261-pr28-thread-ledger.json (100%) rename docs/{ => historical}/intb-261-review-remediation-strategy.md (98%) rename docs/{ => historical}/intb-261-successor-finding-ledger.json (100%) rename docs/{ => historical}/intb-279-v060-execution-contract.md (100%) create mode 100644 docs/operate-and-release.md create mode 100644 docs/provenance.md create mode 100644 docs/try-tabellio.md create mode 100644 scripts/check-docs.mjs create mode 100644 tests/docs-check.test.mjs diff --git a/.buildkite/scripts/provenance-coverage.sh b/.buildkite/scripts/provenance-coverage.sh index b71c8338..e22e512c 100644 --- a/.buildkite/scripts/provenance-coverage.sh +++ b/.buildkite/scripts/provenance-coverage.sh @@ -63,7 +63,7 @@ c8 --clean=false --exclude '**/node_modules/**' --reporter=json --reports-dir co # Include the policy benchmark and negative setup diagnostics without discarding # the integration demo coverage collected above. c8 --clean=false --exclude '**/node_modules/**' --reporter=json --reports-dir coverage \ - node --test --test-concurrency=1 tests/provenance-benchmark.test.mjs tests/demo-provenance.test.mjs tests/validation-checkpoints.test.mjs + node --test --test-concurrency=1 tests/provenance-benchmark.test.mjs tests/demo-provenance.test.mjs tests/validation-checkpoints.test.mjs tests/docs-check.test.mjs # Fallow 2.89 consumes function/statement coverage but rejects c8's unknown # branch-column sentinel (-1). Preserve the original report; omit only branch diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 00000000..cd182133 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,47 @@ +name: Bug report +description: Report a reproducible problem with current Tabellio behavior. +title: "[Bug]: " +body: + - type: markdown + attributes: + value: "For vulnerabilities, use https://github.com/IntelIP/Tabellio/security/advisories/new. Do not include credentials, private sessions, provider bodies, or account data." + - type: input + id: version + attributes: + label: Package version and source commit + description: Include tabellio-version output fields, not private machine paths. + placeholder: "0.7.0; source commit if known" + validations: + required: true + - type: input + id: environment + attributes: + label: Operating system and relevant tool versions + description: Include Node.js, Git, PostgreSQL, or Entire versions used by this workflow. + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Reproduction steps + description: Give minimal commands and safe sample inputs. Label synthetic fixtures. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: Include the safe error or receipt status and what remained unfinished. + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Safe evidence references + description: Link sanitized receipts, existing validation/review artifacts, and the affected code version. Never attach private checkpoint bundles. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..6a821bdd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Private vulnerability report + url: https://github.com/IntelIP/Tabellio/security/advisories/new + about: Report security issues privately. Do not post vulnerability details in public issues. diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 00000000..5da33651 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,43 @@ +name: Feature request +description: Propose a bounded improvement for a user outcome. +title: "[Feature]: " +body: + - type: markdown + attributes: + value: "Keep evidence safe. Never include credentials, private transcripts, provider bodies, or account data." + - type: input + id: version + attributes: + label: Current package version and source commit + placeholder: "0.7.0; source commit if known" + validations: + required: true + - type: textarea + id: problem + attributes: + label: Who needs this and what problem they face + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Current workflow or reproduction + description: Show the current steps or a clearly labeled hypothetical example. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior and observable result + description: Describe completion and relevant failure cases without assumed performance gains. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Existing tools or alternatives considered + - type: textarea + id: evidence + attributes: + label: Safe evidence references and constraints + description: Link sanitized examples or existing records; identify access and approval dependencies. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..6ae3c938 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,43 @@ +## Objective and behavior + +Who benefits, what problem this solves, and the observable before/after behavior. +List changed files, scope limits, and any unfinished work. + +## Tabellio Evidence + +- [ ] Evidence envelope generated +- [ ] Evidence envelope validated +- [ ] Required commands listed with pass/fail/skipped status +- [ ] Changed files listed +- [ ] External action policy present +- [ ] No deploy, migration, infrastructure, DNS, hosting, billing, live-money, credentialed provider read, secret-value read, or destructive workspace action attempted without explicit approval + +Evidence summary: + +```json +{ + "schemaVersion": "tabellio-evidence/v0.1", + "runId": "", + "baseRef": "", + "headRef": "", + "changedFileCount": 0, + "commandsRun": [], + "checks": [], + "externalActionsAttempted": false +} +``` + +Code version: repository, branch, full head commit, and base. +Verification: commands with pass/fail/blocked/skipped results. +Evidence references: existing manifest, exact-head validation, and durable review records. +External-action authority: source of explicit approval, or no protected action attempted. + +## Review Notes + +Use this section for human review context, known gaps, and follow-up work. Keep agent claims tied to evidence artifacts or command output. + +Blockers and decisions: + +Next step and responsible role: + +Passing checks and this note do not grant merge, release, publication, or deployment approval. diff --git a/AGENTS.md b/AGENTS.md index c8112c35..4ad20336 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,77 @@ -# Code cleanup +# Agent entry point -- Run `npm run quality:dead-code` after JavaScript removals. Run `npm run quality:changed-code` before opening a pull request. -- For cross-file removals, refresh Graphify and inspect callers before deleting. Verify current source and framework registrations. +Tabellio helps teams review AI-assisted code with evidence tied to the exact code +version. Serve teams trying and connecting Tabellio before adding operator detail. + +## Find the right guide + +- [README](README.md): product, published demo, limits, and help. +- [Documentation home](docs/README.md): try, connect, contribute, or operate. +- [Contributing](CONTRIBUTING.md): setup, verification, work-plan and handoff format. +- [Harness workflow](docs/harness.md): task state, failure routes, and lesson mapping. +- `scripts/` and `scripts/lib/`: CLIs and shared implementation. +- `schemas/`, `migrations/`, `examples/`: contracts, storage changes, and fixtures. +- Root `tabellio.*.validation.json` and `.tabellio/`: acceptance and validator authority. +- `reports/`: bounded evidence; `docs/historical/`: previous plans and review snapshots. +- `.github/` and `.buildkite/`: hosted checks using shared scripts. + +## Initialize before implementation + +1. Read the request, nearest instructions, and the relevant current guide. +2. Inspect status, branch, remotes, worktrees, and diff names. Preserve existing edits. +3. Use one isolated task branch when the current checkout contains unrelated work. +4. Use Node.js 20+, npm, Git 2.38+, and Entire 0.7.7+. CI uses Node.js 22.23.1. +5. Check `node scripts/tabellio-preflight.mjs --profile agent` and `npm run check`. +6. Establish the passing baseline or save the specific missing-access blocker. + +PostgreSQL client/server tools are needed for provenance integration checks. +Use the pinned scanner setup in [Contributing](CONTRIBUTING.md). git-spice 0.18+ +is needed for stack work. Preflight is read-only; `entire doctor` requires explicit +operator repair approval. Trust Codex hooks through `/hooks` when preflight directs it. + +## Select one task + +Follow initialize → select one task → implement → verify → review → human decision. +Write its objective, allowed files/behavior, completion criteria, and required checks +using the contributor format. Keep one active task; finish or hand it off before +starting another. Avoid runtime, schema, migration, or manifest changes for docs-only work. + +## Verify the change + +| Change | Required checks | +| --- | --- | +| All changes | `npm run check`; `npm run quality:changed-code`; `npm pack --dry-run` | +| Docs, entry files, templates | `npm run docs:check`; inspect commands and rendered Markdown | +| Installation or first-use instructions | Clean consumer install and documented demo | +| JavaScript changes | Focused behavior tests and `node --check` on changed scripts | +| JavaScript removals | `npm run quality:dead-code`; inspect callers and registrations | +| Cross-file removals | Refresh Graphify for relationships, then verify current source | +| Product or acceptance changes | Committed exact-head validation and required hosted checks | +| Provenance/security changes | Existing PostgreSQL and pinned scanner checks; see current guides | + +Failed checks return to the relevant fix. Never call skipped or blocked checks passed. +Use existing manifests, validation refs, and durable review records as the authority. +New code, base movement, or changed inputs can invalidate a previous passing result. + +## Authority and data + +Keep public `origin` limited to code branches and approved tags. Keep private +checkpoints, transcripts, validation, and review state on customer-owned storage. +Do not retain credentials, raw prompts, provider bodies, or private account data +in notes, packets, issues, logs, or PRs. Follow [data boundaries](tabellio.data-boundary.json). +Merge, publication, releases, deployment, migrations, infrastructure, DNS, hosting, +billing, live-money, credentialed reads, secret-value reads, and destructive actions +need explicit authority. Checks and notes grant no approval. Never bypass gates. +Plane is a legacy import capability. IntelIP uses AgentShift; no adapter is included. + +## Recover and hand off + +Resume from the task's saved code version, decisions, check artifacts, blockers, +and next step. Compare them with current Git and provider state before reusing readiness. +Reuse [agent-run state](docs/agent-run-lifecycle.md), [review records](docs/review-loop.md), +and [validation results](docs/validation-runner.md); notes are navigation, not approval. +Save missing access immediately. After three consecutive failed attempts without +material progress, stop retries and hand off the cause, attempted fixes, and next decision. +Remove only task-owned temporary files. Never reset others' changes or delete +private checkpoint history. Leave a clean scoped commit or an explicit unfinished-work +handoff using [Contributing](CONTRIBUTING.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 866760df..d3562b34 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,25 +1,52 @@ # Contributing -## Principles +Help teams try Tabellio, connect one repository, and review code with clear evidence. +Keep changes Git-native, agent-agnostic, dependency-light, deterministic before +AI-assisted, and default-deny for protected external actions. -Keep the workflow: +## Source-checkout setup -- agent-agnostic -- Git-native -- dependency-light -- deterministic before AI-assisted -- default-deny for external side effects -- clear about evidence versus claims +Use Node.js 20 or later, npm, Git 2.38 or later, and Entire 0.7.7 or later. +CI uses Node.js 22.23.1. PostgreSQL client/server binaries are required for the +provenance integration suite; git-spice 0.18 or later is needed for stack work. +The package has no runtime npm dependencies. Named npm scripts below belong to +this checkout; installed users start at [Try Tabellio](docs/try-tabellio.md). -## Local Checks +```bash +git clone https://github.com/IntelIP/Tabellio.git +cd Tabellio +entire enable --agent codex --project --skip-push-sessions +node scripts/tabellio-preflight.mjs --profile agent +``` + +Preflight is read-only. Review missing Codex hook trust through `/hooks`. +Run `entire doctor` only with explicit operator approval for repair. +Preserve any existing edits and use an isolated task branch when needed. -Run the full local check: +## Establish a baseline and verify + +Use the same pinned scanner setup and shared checks as CI: ```bash +. .buildkite/scripts/security-tools.sh +npm run docs:check npm run check +npm run quality:changed-code +npm pack --dry-run ``` -Generate and validate a fresh evidence packet: +The scanner installer verifies its download and uses a temporary tool directory. +`quality:changed-code` includes real PostgreSQL coverage; put `psql`, `initdb`, +and `pg_ctl` on `PATH`. Run focused tests for changed behavior and `node --check` +on changed JavaScript. After JavaScript removals, run `npm run quality:dead-code`. +For cross-file removals, refresh Graphify, inspect callers, and verify registrations. + +`docs:check` checks local links, required entry documents, current installation +versions, entry-file limits, and identical native/packaged PR templates. It does +not contact websites or score prose. Historical release versions remain valid. +Both GitHub Actions and Buildkite enforce it through `npm run check`. + +Generate safe review evidence when applicable: ```bash node scripts/write-tabellio-evidence-envelope.mjs --out /tmp/tabellio-pr-evidence.json @@ -27,79 +54,59 @@ node scripts/check-tabellio-evidence-envelope.mjs --evidence /tmp/tabellio-pr-ev node scripts/check-tabellio-external-actions.mjs --evidence /tmp/tabellio-pr-evidence.json ``` -Check script syntax: - -```bash -node --check scripts/check-tabellio-evidence-envelope.mjs -node --check scripts/check-tabellio-external-actions.mjs -node --check scripts/check-tabellio-run.mjs -node --check scripts/tabellio-run.mjs -node --check scripts/write-tabellio-evidence-envelope.mjs -``` - -Validate the canonical platform and exact-commit manifest before release: - -```bash -npm run tabellio:platform:check -node scripts/check-tabellio-validation.mjs --manifest tabellio.validation.json +The [validation manifest](tabellio.validation.json), validation refs, and +[durable review cycle](docs/review-loop.md) decide passing state for an exact code +version. Command output or a handoff note does not replace those records. +Before review, run the committed [exact-head validation](docs/validation-runner.md) +and confirm the required hosted checks. Fresh hosted workers need +[genuine private checkpoint proof](docs/checkpoint-proof-handoff.md). + +## One work-plan and handoff format + +Follow **initialize → select one task → implement → verify → review → human decision**. +Keep one active task. Save the plan beside the task's existing acceptance or review +record, using safe repository-relative paths or authorized private artifact references. +Update the same note when handing off; do not create a second approval system. + +```markdown +Objective: Who benefits and what problem this solves. +Scope: Allowed behavior and files; exclusions and dependencies. +Expected behavior: Observable completion criteria, including failure cases. +Verification commands: Required commands and pass/fail/blocked/skipped results. +Code version: Repository, branch, full commit ID, base, and dirty state. +Evidence references: Existing manifest, validation/review record, and safe artifacts. +Blockers: Missing access or unresolved failures; attempts and their results. +Decisions: Tradeoffs and the source of any explicit authority. +Next step: One action, responsible person/role, and human decision if required. ``` -## Pull Requests - -Each PR should include: - -- evidence envelope path or artifact -- commands run -- check result summary -- external-action policy summary -- skipped-check notes, if any - -Do not include: - -- secret values -- private session logs -- local machine paths -- provider account data -- unredacted credentials - -## Sensitive Changes - -Ask for extra review when changing: - -- required evidence fields -- required action classes -- default-deny behavior -- approval handling -- control-ref allow lists and approval checks -- forge credentials or validation worker isolation - -## Documentation Style - -Prefer: - -- short sections -- tables for comparisons -- code blocks for commands -- direct current-state wording +If a check fails, return to the relevant implementation, setup, or scope fix. +If access is missing, save the exact blocker and hand off the access decision. +After three consecutive failed attempts without material progress, stop blind +retries and hand off the cause, attempted fixes, and next useful action. +A changed commit, moved base, or changed input requires fresh applicable evidence. +Remove only task-owned temporary files; preserve unrelated edits and private refs. -Avoid: +## Pull requests and review -- compliance claims not implemented by code -- long roadmap text in the README -- burying security boundaries in prose +Use the [native PR template](.github/pull_request_template.md); its +[packaged counterpart](templates/pull_request_template.md) serves adopting repositories. +State the expected behavior, changed files, commands, exact code version, evidence, +external-action authority, and remaining blockers. An agent's claim does not grant readiness. -## Release Prep +Request extra review for changes to evidence fields, action classes, default-deny +behavior, approvals, control-ref allow lists, credentials, or worker isolation. +Keep secrets, raw transcripts, private provider/account data, and local machine +paths out of public reports. Use [private security reporting](SECURITY.md) for vulnerabilities. +Review clearance and human approval remain separate from passing checks. -Before tagging a release: +## Documentation and release work -- run `node scripts/tabellio-preflight.mjs --profile release` -- run `tabellio-review gate` on the open exact-head pull request before merge -- keep preflight read-only; run `entire doctor` only as an explicit operator-approved repair step -- update `CHANGELOG.md` -- confirm README examples use the intended release tag -- run local checks -- run an exact-head `tabellio-validate` pass -- confirm the durable review cycle has exact-head `ready` evidence before merge -- tag from a clean `origin/main` commit +Use short current-state sections, comparisons where useful, and working commands. +Clearly label synthetic fixtures and unsupported claims. Keep operator procedures +out of the main README and completed ticket records in [history](docs/historical/README.md). -After the release PR is explicitly merged, use `tabellio-release plan` to run merged-head validation, synchronize the terminal review cycle, and bind exact publishable control refs. Review the generated intent, create a short-lived `tabellio-release-approval/v0.1`, then run `tabellio-release execute` once. The executor publishes control refs, the annotated tag, and the GitHub release. It never merges the pull request. +Release operators follow [Operate and release](docs/operate-and-release.md), the +[platform check](docs/github-code-storage-boundary.md), and +[product validation](docs/product-validation.md). Tag, publish, merge, and deployment +authority remain separate decisions. Keep Apache-2.0 unchanged. diff --git a/README.md b/README.md index 63207cc4..fbe8dcdf 100644 --- a/README.md +++ b/README.md @@ -1,395 +1,132 @@ # Tabellio -![Tabellio product overview](docs/assets/tabellio-hero.svg) - -[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/) -[![GitHub](https://img.shields.io/badge/GitHub-code%20storage-181717?logo=github)](https://github.com/) -[![JSON Schema](https://img.shields.io/badge/JSON%20Schema-evidence%20contract-0B6BFF)](https://json-schema.org/) -[![SARIF](https://img.shields.io/badge/SARIF-code%20scanning-2563EB)](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) -[![git-spice](https://img.shields.io/badge/git--spice-stacked%20review-B45309)](https://abhinav.github.io/git-spice/) -[![Entire](https://img.shields.io/badge/Entire-checkpoint%20ledger-111827)](https://entire.io/) -[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE) - -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 | 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 | - -## Native Git Foundation - -### Local provenance rebuild - -The incremental TAB-18–29 rebuild adds a local PostgreSQL evidence projection. -Its current foundation stores source-attributed observations, typed relationships, -and exact base/head/merge-base identities. Imports are atomic and idempotent; -replay preserves the same digest. Missing, stale, conflicting, inferred, or failed -evidence prevents a passed review result. Review packets omit source payloads and -facts belonging to another candidate. - -Run the sample on macOS or Linux with Node.js, Git, and PostgreSQL client/server binaries on `PATH`: - -```bash -npm run tabellio:provenance:demo -``` - -The demo creates a temporary Git repository and private local PostgreSQL cluster, -imports a synthetic provider journey, restarts the database server, deletes and -replays the derived record, builds a review packet, and proves that a moved base -blocks the old evidence. It stops its server and removes its temporary files. -Git and PostgreSQL operations are real; Plane, Entire, GitHub, Buildkite, and -security observations in this sample are explicitly synthetic. This is not a -live-provider or security-scanner certification. - -The demo receipt includes a failure matrix with expected and actual verdicts, -safe reasons, and lineage digests where available. It exercises missing, stale, -conflicting, tampered, secret, failed-validation, outage, and moved-base cases. -Source replay runs twice in a newly created local database, verifies the original -digest, and checks that source snapshots and Git refs remain unchanged. Cleanup -and local cost/time are recorded even when the demo fails. - -To replace the sample security observation with real bounded checks, install -Gitleaks 8.30.1 and ast-grep 0.45.1 on `PATH`, then run: - -```bash -node scripts/demo-provenance.mjs --verify-security-scanners true -``` - -On Apple Silicon macOS or x86-64 Linux, `. .buildkite/scripts/security-tools.sh` -installs the pinned tools into a temporary directory and exposes them on `PATH`. -Set `TABELLIO_SECURITY_TOOLS_DIR` to reuse a tool directory. The installer verifies -the Gitleaks archive checksum and does not run npm package install scripts. -Configured CI uses this setup before checks; the required security -validator fails when scanners are missing instead of skipping scanner fixtures. -Run the same required check locally with `npm run tabellio:provenance:security:check`. +Tabellio helps teams review AI-assisted code by collecting what changed, what was checked, and which actions were approved for the exact code version. -The scanner reads immutable Git blobs without running candidate code. It uses -Gitleaks defaults and explicit JavaScript/TypeScript rules for unverified JWT -decoding, unsigned JWT configuration, disabled TLS verification, and dynamic -`eval`. Candidate ignore files and suppression comments cannot grant a pass. -Insecure HTTP dependency references fail; other declared npm dependencies remain -blocked pending vulnerability evidence. These checks cover the listed rules; -they do not establish the absence of all authorization or dependency defects. - -`tabellio-provenance security --input --repo --now