IntentBond

IntentBond connects intent and specifications to code, tests, and verification evidence. Follow explicit links to find what a change affects and keep the related artifacts consistent as software changes.

It checks links across Git versions, runs your tests, and saves results tied to the source checked. Optional Alloy and Z3 checks add formal verification for selected properties.

How it works

Capture user outcomes and rationale in intent.md, and concrete requirements and design in spec.md. These are suggested document roles; existing filenames such as requirements.md work too. Give intent and requirements stable IDs, and link requirements to the intent they refine. IntentBond's own intent and specification demonstrate the full chain.

Keep requirements in Markdown and reference them from code and tests using OpenFastTrace (OFT) IDs:

### Session expiration
`req~session-expiration~1`

Sessions expire after 30 minutes of inactivity.

Needs: impl, utest

# [impl->req~session-expiration~1]  # Beside the implementation
# [utest->req~session-expiration~1] # Beside the test assertion

1 is the requirement revision. OFT checks that the required links exist and reference that revision. IntentBond runs the tests and reports changes against a Git baseline. Review determines whether the linked code and checks satisfy the requirement.

Separate files and intermediate design items are optional. See the authoring guidance for intent links and conversation decisions, the session example for a minimal requirement, and artifact meanings for interpreting the chain.

Install

Requires Python 3.11+, Git, and Java 17+ on Linux or macOS. Install intentbond from this checkout in a Python virtual environment:

python3 -m pip install .
ib install-oft

The OFT installer downloads and checksum-verifies the pinned release. For an existing JAR, set INTENTBOND_OFT_JAR or pass --oft-jar to ib check.

Add traceability to an existing project

Start with one feature. Use its documentation, code, and tests to propose requirements and links. Flag inferred intent and missing tests for review.

Give a coding agent the existing-project skill, or start manually from a clean project checkout:

ib recover

This saves the original source and prepares citation records. Add requirements, code/test references, and a scope.json following the recovery guide, then run:

ib recover-check

Exit 4 means checks passed and review is pending. Read recovery-review.md, resolve open questions, and commit the accepted requirements, links, and scope. Recovery creates review records in .intentbond/recovery/ and keeps full bundles under local Git metadata. The records need not stay in the working tree after adoption; the retention guidance explains how to preserve provenance in Git history or artifact storage.

Check a change

1. Configure the project

Copy scope.json and adapt its paths, coverage rules, and test command. Commit it at the project root with the starting requirements and references.

Checks use the baseline's scope, so candidate edits cannot change their own checking rules. A caller can instead supply a trusted external scope with --scope. Tests run on captured source; their dependencies must be available in the checking environment.

2. Validate the starting commit

From the project's checkout:

ib check --base HEAD --candidate HEAD

3. Make changes and check them

ib check

By default, this compares your working tree with the branch's merge base against the default branch, or HEAD on the default branch. Use --base COMMIT to choose another baseline. Each run saves results in a fresh temporary directory; use --out /path/to/check-1 to choose a new directory outside the project.

See the command reference for defaults and source-capture details.

Understand and review the result

Open summary.md in the reported evidence directory for changed requirements, test results, and pending review.

For long checks, use ib check --progress to follow the retained test log on stderr. The final CLI summary separates recorded trace-command and test durations; it does not include all source-capture overhead or measure agent effort.

Exit from ib check	Meaning
0	Automated checks passed; no selected changes triggered the semantic review gate.
4	Automated checks passed; selected changes need semantic review.
1, 2, 3	Validation failed, could not run, or had an empty scope.

Review the full diff. review.patch contains changes selected by specification paths, test paths and optional review_paths; passing checks do not approve them.

Inspect a requirement and its links in saved evidence:

ib explain 'req~session-expiration~1' --evidence /path/to/check/evidence.json

Match a later commit to the source already checked:

ib verify --candidate HEAD --evidence /path/to/check/evidence.json

Use the original baseline and scope. For exit-4 evidence, --allow-pending-review allows matching while review remains pending. verify does not rerun tests. See evidence semantics for what each result establishes.

Work with an agent

Give your agent the development skill to maintain requirements, code, tests, and links during changes. Configure CI separately to enforce checks on pull requests.

IntentBond also works manually and in CI. The IntentMade integration is optional.

Optional assurance assessment combines existing check evidence, review, and required decisions without another test or model run. Manual tools, CI, and factories can use the same contract and optional SDLC process profile.

Add property tests

Use the property-testing guide to express selected requirements as assertions over generated inputs. Tests use your existing runner; examples cover Hypothesis, fast-check, and QuickCheck.

Optional execution links associate individual test results with requirement coverage and can require selected tests to run and pass.

Check selected properties with Alloy or Z3

Formal checks are optional. The model-checking guide covers authoring models, reviewing assumptions, replaying traces against code, and retaining results. Committed checks run without an LLM.

Run the Alloy example:

ib install-alloy
ib alloy-check --root examples/model-checking --manifest checks.json --out /tmp/alloy-check-1

Or install Z3 and run the SMT example:

pip install 'intentbond[smt]'
ib smt-check --root examples/smt-checking --manifest checks.json --out /tmp/smt-check-1

ib chc-check uses Z3 Spacer to check safety over arbitrary numbers of modeled transitions. See the CHC example.

These runners work standalone or alongside tests in ib check. Results concern the model under recorded assumptions and bounds; review and implementation replay assess its correspondence to real code.

Inspect requirement evolution

ib impact --evidence /path/to/check/evidence.json

Compare requirement declarations, links, and source changes. The granularity guide explains how to give independently changing promises their own IDs.

Impact also shows changed files with no imported artifacts, native coverage and required execution gaps, and highly connected artifacts. These observations guide review without establishing completeness. Optional ib review worklists preserve notes and deferred items against the exact checked source. See development review for policy selection and resumable review.

Documentation and contributing

See the documentation index for guides, examples, and the command reference. IntentBond's own intent and specification are maintained with its code and tests. Contributions are welcome; start with CONTRIBUTING.md. Report vulnerabilities through SECURITY.md.

License

MIT. Dependencies and optional tools retain their own licenses.