Capability Contracts

Infer draft outcome contracts from your codebase, then check whether critical capabilities still have test and observability proof.

Tests can pass while user outcomes drift. Capability Contracts gives local teams a small, deterministic way to find likely capabilities, draft reviewable contracts, and report when those contracts no longer have obvious proof.

The issue is not only whether code exists or tests pass. The issue is whether the declared user outcome still has visible proof.

Start Here

Your goal	Start with
Try the tool quickly	npm run example:all
See what it produces	Next.js auth report
Understand the example	Capability card
Understand the drift story	Worked Example: Outcome Drift
Use it on your own repo	Using your own repo
Understand contract format	Contract format
Understand proof markers	Proof markers

Who This Is For

This is for product engineering teams that already have routes, tests, and analytics or observability events, but do not have a lightweight way to connect those signals back to user-facing outcomes.

It is useful when you want to answer:

• Which capabilities does this repo appear to expose?
• Which outcomes have explicit proof in tests?
• Which outcomes emit observability events?
• Which contracts are missing visible proof after a code change?

What It Does

• scan discovers routes, tests, proof markers, events, and likely capabilities.
• draft writes YAML capability contracts from obvious local signals.
• check validates contracts against the current scan.
• report writes Markdown and JSON reports for humans and automation.

Workflow

routes + tests + events
  |
  v
local scan
  |
  v
likely capabilities
  |
  v
draft contracts
  |
  v
proof check
  |
  v
Markdown + JSON report

Try It In 10 Minutes

npm install
npm run example:all

The example intentionally reports auth.login as at_risk because auth.login.failed has an event but no matching test proof marker.

Start with the Next.js auth capability card, then read the committed Markdown report or JSON report.

What This Catches That Normal Checks Miss

A route can exist, tests can pass, and the code can still look reasonable while a user-facing outcome loses explicit proof.

The Next.js auth example includes three scenarios:

Scenario	Status	What changed
Healthy	pass	success and failure outcomes both have proof
Missing failure proof	at_risk	failure event exists, but test proof marker disappeared
Missing failure event	fail	test proof exists, but observability event disappeared

See Worked Example: Outcome Drift and the scenario suite.

Use It On Your Own Repo

npm run cli -- scan .
npm run cli -- draft .
npm run cli -- report .

Then review the generated contracts in capability-contracts/. Contracts are drafts. Edit the title, intent, outcomes, proof markers, and required observability events until they reflect the outcomes you actually care about.

Use --strict when at_risk contracts should fail automation:

npm run cli -- report . --strict

For a step-by-step adoption guide, see Using Capability Contracts On Your Own Repo.

What Counts As Proof?

A test existing is not the same as an outcome being protected.

An outcome is protected when a test explicitly declares proof with an outcome marker:

// outcome-proof: auth.login.succeeded

Observability events can also be declared as proof:

proof:
  observability:
    - event: auth.login.succeeded
      fields: [userId, sessionId]

If the event exists but the proof marker is missing, the contract is at_risk. If a declared route, entrypoint, or required event disappears, the contract is fail.

How It Works

The scanner uses simple static signals:

• Next.js route handlers in app/api/**/route.ts
• Express-style app.get() and router.post() calls
• test names from it() and test()
• outcome-proof: and capability-proof: comments
• event names from track(), analytics.track(), and emit()

Inference is deterministic and intentionally shallow. Contracts are drafts until a human accepts or edits them.

Relationship To Codebase Intel

Capability Contracts is a one-shot local inference and proof-checking tool.

Codebase Intel is the integrated product: continuous observation, richer evidence graph, runtime truth correlation, PR checks, contract governance, and agent-ready context.

Capability Contracts does not expose Codebase Intel's full evidence system, runtime truth model, governance layer, hosted workflows, or agent context. See docs/relationship-to-codebase-intel.md.

Non-Goals

• Full evidence graph
• Multi-language provider system
• Runtime truth ingestion
• GitHub App or SaaS dashboard
• Agent memory or orchestration
• LLM-generated contracts
• Deep semantic program analysis

Development

npm run typecheck
npm run test
npm run example:all
git diff --exit-code