Core Concepts · 5.5

Verification

Where the evidence that a story works comes from, how CI results reach each story, and how IntentDocs tells you how far to trust a "done".

An agent saying it's finished is a claim. Verification is the evidence behind it: which criteria pass, which tests prove them, and whether those results are newer than the code. IntentDocs keeps that evidence on each story, so when you review it you can see what was checked and by whom.

Where evidence comes from

Source	How it arrives	Recorded as
The agent	`report_criteria` after it builds and checks each criterion.	Reported by the agent.
A person	`npx intentdocs check --report`, or confirming a `founder_confirm` criterion.	Reported by a person.
Tests	The agent saves each test with `save_tests`, linked to the criteria it proves. Its result comes from the agent's report, or from CI.	A result on the test, and on the criteria it proves.

Each criterion keeps its latest result, the evidence, any caveat, and the attempt number. See Acceptance criteria.

Tests linked to criteria

A test proves one or more criteria. When an agent saves it with save_tests, it passes the ids of those criteria. An id that isn't one of the story's criteria is refused, with the valid ids listed.

On the story page, the Tests tab tags every test with the criteria it proves, for example AC 02 · pass, and names any criterion with no test. On the Spec tab, each criterion says how many tests prove it, or No test.

Test results from CI

With CI reporting on, your test suite reports results itself, with no agent involved.

Run npx intentdocs ci in the repository. It creates a CI key, adds a GitHub Actions workflow, and stores the key as the INTENTDOCS_CI_KEY repo secret.
Your test runner writes a JUnit XML report. The workflow posts it to IntentDocs.
IntentDocs matches each result to a saved test by its file and full_name, and records it against the commit.

The test card then reads "passed on" or "failed on" that commit. Two rules decide what counts:

Only runs on the project's default branch are applied. Results from other branches are accepted and ignored.
A result reaches a story only if a saved test has the same file and full_name, exactly as the runner prints them. npx intentdocs ci --status shows how many results matched.

For a CI system other than GitHub Actions, post the report yourself:

curl -X POST "https://www.intentdocs.com/api/ci/$PROJECT_ID/report" \
  -H "Authorization: Bearer $CI_KEY" \
  -H "X-Commit-SHA: $GITHUB_SHA" \
  -H "X-Branch: $GITHUB_REF_NAME" \
  -H "Content-Type: application/xml" \
  --data-binary @test-results.xml

Keys are listed, and can be revoked, in Project settings → Test reporting.

How far to trust a "done"

Every story that's dev complete or approved carries a trust word on Validate:

Word	Means
verified	Every `must` criterion has a passing result.
evidenced	Some results are in, but not every `must` criterion passes.
asserted	Marked done with no reported evidence at all.

When evidence goes stale

Evidence only counts if it's about the code as it is now. IntentDocs watches for four ways it stops being true:

Tests older than the code. The latest result is older than the latest recorded commit to the story's pull request. Review says so under the verdict.
Spec changed since built. The user story or criteria changed after the story was built. The story page shows what changed. Choose Send for rework… so the code follows, or No code change needed to make the new text the spec it was built against.
Regressed. A criterion that passed is failing now.
Code changed. With the GitHub App installed, a merged pull request touched a built story's code, and its tests hadn't passed on that branch.

On Validate, a built story with criteria that were never verified against it appears under Worth a look.

Approving in bulk

You can approve many stories at once when a machine has vouched for every part of them. A dev-complete story qualifies only when all four hold:

Every criterion passed, checked by a machine: not reported by a person, and not a founder_confirm criterion.
No result carries a caveat.
Its test results are newer than its last recorded commit.
Its pull request is linked and merged.

Every other story needs reading, and Validate says why. See The Validate tab.

Note: agents never approve. However strong the evidence, approved is a person's decision.