Sourcebound

Sourcebound is a documentation engine and CLI for maintainers who need code and prose to change together. It binds selected claims to their defining sources, so drifted documentation fails locally and in CI instead of reaching readers.

Install the stable release and catch your first stale claim.

The final sourcebound verify command prints a sourcebound.outcome.v2 receipt with "ok": true.

Before adoption, audit reports bounded repository-neutral advisories. A manifest turns integrity checks into gates; policy markers opt compatible writing rules into specific documents. Neither authorizes Sourcebound to flatten repository-native forms.

Why Sourcebound exists

A stale sentence does not fail loudly. It keeps a straight face after the code has moved on, and reviewers have no mechanical way to identify the false claim. Sourcebound gives each protected fact a source, then checks that relationship again in CI.

Declared sources own the protected facts. A packaged policy enforces the deterministic form floor; authored judgment still owns motivation, pedagogy, and voice. Static adapters read common code and schema formats, while declared commands run under explicit process controls. The engine can repair bound regions, rank static count and column candidates, enforce accepted source-claim relationships, and project canonical text and visual records into purpose-built human and agent surfaces with local receipts.

Human review can improve a sentence. It cannot make the sentence fail when its defining source changes. The deterministic seam explains how Sourcebound separates source evidence, optional phrasing, and gate authority.

Install in the repository you want to protect

From that repository, download the latest stable wheel, install it in an isolated environment, and run the manifest-free audit:

release_dir="$(mktemp -d)"
gh release download --repo owieschon/sourcebound \
  --pattern 'sourcebound-*-py3-none-any.whl' --dir "$release_dir"
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "$release_dir"/sourcebound-*.whl
sourcebound audit

After reviewing the assessment, inspect the files that init proposes before accepting its gate:

sourcebound init --no-model
git diff -- .sourcebound.yml .sourcebound/repository-surface.md README.md llms.txt
sourcebound check
sourcebound verify

An established, unregistered README stays byte-for-byte authored. Init writes its detected catalog to .sourcebound/repository-surface.md; a new README or one that adopted the register may own that region directly.

After a bound source changes, run check, then use drive for a declared repair. Run project when a declared projection depends on the repaired document, then run verify. The tutorial shows the failure before the repair; the support guide covers mature-repository adoption.

How the pieces fit

Three inputs stay separate before the deterministic core:

• Authored intent records why a surface matters. Sourcebound preserves that purpose; it does not infer its priority or turn judgment into gate authority.
• Repository contract declares sources, binding mechanisms, process limits, and projections. Policy markers scope compatible form checks; they do not certify voice.
• Change state combines base and head refs with that contract to produce an immutable impact plan. Static adapters and bounded commands produce typed evidence. Each mechanism proves only its declared relationship; accepted source-claim checks are separate, and unbound prose stays visibly unknown.

The core exposes four job-specific exits:

1. Repair bounded prose. drive writes only planned regions. project runs separately when a declared output depends on changed documentation.
2. Reject stale changes. check and verdict are read-only. The verdict names changed, bound, unbound, and skipped surfaces.
3. Publish agent context. project writes declared outputs such as llms.txt and context bundles.
4. Record local state. verify emits its own outcome receipt.

verdict and verify produce independent receipts. Neither certifies unbound or judgment prose. The product contract defines each authority boundary.

Current boundaries

• Catalog coverage detects source additions, removals, and replacements; it does not validate prose.
• Source-claim discovery ranks static count and identifier-set candidates. A candidate remains advisory until the repository accepts its exact document and source relationship.
• Declared processes use time, I/O, and environment controls. The host owns network isolation; see the security model.
• The manifest decides what Sourcebound evaluates. Authored purpose records goals; Sourcebound does not infer or certify them.
• Feedback is off by default. Enabled runs queue bounded local envelopes; only an explicit feedback flush contacts the configured sink, and delivery cannot change a gate result.

Use the learning path for examples. The product contract owns parser, write-boundary, and exit-code details.