A Bun-first CLI that detects contract drift before it breaks downstream consumers.
Turns markdown contracts into a dependency graph, classifies drift, and blocks unsafe changes in local dev and CI.

• 2026-05-04 🎉 Released v0.6.0 — ferret scan now auto-infers stable status when a contract's source resolves clean (NOOP upward drift). No manual status: active needed. See CHANGELOG.
• 2026-05-04 🎉 Released v0.5.0 — source field on defineContract() for cross-file upward drift (S63) and roadmap → pending status rename with context.json v3.0 (S62). See CHANGELOG.
• 2026-04-26 🐛 Released v0.4.2 — dogfooding bug fixes: zod@4 compatibility, tree-sitter native module dedup, ContractRef type for consumes/dependsOn, and defineContract now returns schema: ZodObject<T> for safe composition. See release notes.
• 2026-04-14 🎉 Released v0.4.0 — ferret watch, ferret audit, and exported watch/audit APIs in @specferret/core. See CHANGELOG.
• 2026-04-14 🎉 Released v0.3.0 — TypeScript-native .contract.ts format with defineContract(), Zod-based schemas, ferret status command, and automatic .contract.ts discovery. See CHANGELOG.
• 2026-04-14 🎉 Released v0.2.0 — bidirectional drift enforcement (code → spec), upward drift detection in ferret lint --ci, source: blocks, and guided resolution for code-origin drift. See CHANGELOG.
• 2026-04-09 🎉 Released v0.1.4 — agent mode scaffolding (--agent-targets), default tree-sitter TypeScript extraction (no annotations required), context schema versioning, diagnostics command, and perf budget hardening. See release notes.
• 2026-04-04 🎉 Released v0.1.3 — publish-safe Bun exports, smoke-fixture hardening, and npm packages refreshed. See release notes.
• 2026-03-15 🚀 Released v0.1.0 — initial public release. ferret init, ferret scan, ferret lint, ferret review. Full BMAD and spec-kit validation runs passing.

• Key Features
• Architecture
• Install
• Quick Start
• Your First Contract
• CLI Reference
• TypeScript-Native Contracts
• Contract Types
• Changelog
• How Drift Resolution Works
• CI Integration
• BMAD & spec-kit Integration
• Use Cases
• Project Structure
• Roadmap
• Validation Evidence
• Development
• Star History

🔍 Drift Detection — Parses .contract.md and .contract.ts files and detects shape changes automatically on every ferret lint.

💥 Breaking vs Non-Breaking Classification — Missing required fields and removed properties are BREAKING. Optional additions are NON-BREAKING. You know exactly what needs review.

🕸️ Dependency Graph — Contracts declare dependencies with imports (markdown) or consumes (TypeScript). SpecFerret computes the full direct and transitive impact graph so you know every consumer of a drifted contract.

⚡ Fast — ferret lint on a clean project completes in under 500ms. SQLite-backed, no external service.

🔒 Pre-commit Enforcement — ferret init installs a .git/hooks/pre-commit hook that blocks commits when breaking drift is detected.

🤖 CI Mode — ferret lint --ci exits non-zero on drift, with JSON output for downstream tooling and agents.

🛠️ TypeScript Extraction — ferret extract infers contracts from exported TypeScript declarations by default, with // @ferret-contract: available as an override for explicit id and type.

📜 TypeScript-Native Contracts — Define contracts as .contract.ts files using defineContract() and Zod schemas. Full type safety, runtime invariants, and zero markdown.

SpecFerret is built in five strict layers. No layer reaches into another layer's domain.

┌─────────────────────────────────────────────────┐
│  CLI                                            │
│  ferret.ts · init · scan · lint · review        │
│  extract · status · watch · audit               │
│  Reads config, calls core, prints, exits.       │
│  Max 50 lines per command file.                 │
├─────────────────────────────────────────────────┤
│  Reconciler                                     │
│  BFS traversal · flags dirty nodes · report     │
│  Never parses files. Never formats output.      │
├─────────────────────────────────────────────────┤
│  Validator                                      │
│  JSON Schema subset · breaking / non-breaking   │
│  Pure function. No side effects. No I/O.        │
├─────────────────────────────────────────────────┤
│  Extractor                                      │
│  .contract.md · .contract.ts · .ts (tree-sitter)│
│  Never talks to the store or the graph.         │
├─────────────────────────────────────────────────┤
│  Store                                          │
│  SQLite (default) · Postgres (roadmap)          │
│  Parameterised SQL only. No business logic.     │
└─────────────────────────────────────────────────┘

Global install (recommended)

bun install -g @specferret/cli

Verify

ferret --version

Install @specferret/core as a library

bun add @specferret/core
# or
npm install @specferret/core

Use @specferret/core directly when you want to integrate the extractor, validator, or reconciler into your own tooling or agent workflow.

1. Install

bun install -g @specferret/cli

2. Initialise your project

cd your-project
ferret init

This creates .ferret/ state, ferret.config.json, and installs a pre-commit hook.

3. Bootstrap contracts (choose one path)

Manual contract-first path:

mkdir -p contracts

Code-first TypeScript path:

ferret extract

ferret extract uses Tree-sitter to infer contracts from exported TypeScript declarations and scaffolds deterministic .contract.md files with no annotations required. @ferret-contract remains supported as a compatibility override for explicit id and type.

Example summary from inferred extraction:

ferret extract  created=7  updated=0  skipped=0  failed=0  inferred=12  annotated=2  143ms

4. Lint (default daily command)

ferret lint

ferret lint runs scan/reconcile checks and reports drift. Use ferret scan directly for advanced/manual graph refresh workflows.

Clean output:

✓ ferret  12 contracts  0 drift  9ms

Drift detected:

  ferret  3 contracts need review

  BREAKING  auth.jwt
  ├── contracts/search.contract.md          imports this directly
  ├── contracts/recommendations.contract.md imports this directly
  └── contracts/analytics.contract.md       imports this transitively (depth 2)

  NON-BREAKING  tables.document
  └── contracts/search.contract.md          optional field added — no action needed

  2 breaking  1 non-breaking

  → Run ferret review to resolve

5. Resolve

ferret review

Create a file under contracts/ with a ferret: frontmatter block:

---
ferret:
  id: api.GET/users
  type: api
  shape:
    type: array
    items:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
      required: [id, email]
---

# GET /users

Returns the list of registered users.

Then run:

ferret lint

Now change required: [id, email] to required: [id] — removing email from required — and run lint again to see breaking drift detected.

---
ferret:
  id: api.POST/search
  type: api
  imports:
    - auth.jwt
  shape:
    type: object
    properties:
      query:
        type: string
      results:
        type: array
    required: [query, results]
---

# POST /search

Authenticated search endpoint. Depends on the JWT auth contract.

// @ferret-contract: api.GET/users api
export interface GetUsersResponse {
  id: string;
  email: string;
}

ferret extract

ferret extract  created=5  updated=1  skipped=0  failed=0  inferred=5  annotated=1  87ms

ferret  checking staged files...

  BREAKING  auth.jwt shape changed
  └── 3 downstream contracts need review

  commit blocked  →  run ferret review

✓ ferret  12 contracts  0 drift  9ms

{
  "drift": true,
  "breaking": 2,
  "nonBreaking": 1,
  "diagnosticsSchemaVersion": "1.0.0",
  "diagnostics": [
    {
      "code": "FERRET_DRIFT_BREAKING",
      "severity": "error",
      "message": "auth.jwt impacts contracts/search/results.contract.md (direct, depth 1).",
      "location": {
        "contractId": "auth.jwt",
        "filePath": "contracts/search/results.contract.md",
        "depth": 1,
        "impact": "direct"
      },
      "remediation": "Run ferret review and resolve downstream drift before merge."
    }
  ],
  "contracts": [...]
}

Instead of markdown frontmatter, define contracts directly in TypeScript with full type safety:

// contracts/auth.contract.ts
import { z } from 'zod';
import { defineContract } from '@specferret/core';

export const jwtPayload = defineContract({
  id: 'auth.jwt',
  value: 'JWT authentication payload',
  output: {
    sub: z.string(),
    email: z.string().email(),
    role: z.enum(['admin', 'user', 'viewer']),
    iat: z.number(),
  },
  invariants: [(r) => r.role !== ''],
  status: 'active',
});

Cross-file upward drift with source (v0.5.0)

Add a source field to point upward drift tracking at a named TypeScript type in your src/ directory. SpecFerret will compare the Zod output schema against the live implementation type via tree-sitter on every ferret lint:

// contracts/keywords.contract.ts
export const apiGetKeywords = defineContract({
  id: 'api.getKeywords',
  value: 'Keywords endpoint',
  output: {
    keywords: z.array(z.object({ keyword: z.string(), created_at: z.string() })),
    limit: z.number(),
    remaining: z.number(),
  },
  source: { file: 'src/routes/keywords.ts', symbol: 'KeywordsResponse' },
});

// src/routes/keywords.ts
export type KeywordsResponse = {
  keywords: Array<{ keyword: string; created_at: string }>;
  limit: number;
  remaining: number;
};

Now ferret lint detects drift between the Zod contract and the actual KeywordsResponse type — two representations, one enforcement check, no markdown spec needed.

**Why `.contract.ts`?**

- **`tsc` enforces your contract** — shape errors are compile errors, not runtime surprises
- **Zod schemas** — converted to JSON Schema automatically via `zod-to-json-schema`
- **Runtime invariants** — typed functions, not text descriptions
- **`consumes` references** — object references, not string IDs. Upstream shape changes break downstream contracts at compile time
- **`contract.schema`** — `defineContract` returns a `ZodObject<T>` on every contract. Use it for composition: `z.array(jwtPayload.schema)`, `z.object({ token: jwtPayload.schema })`. Do not compose with `contract.output` — that is the raw shape, not a schema.

> [!NOTE]
> v0.4.2 requires **zod@4**. If your project is on zod@3, upgrade: `bun add zod@4`.

**Using it:**

```bash
# .contract.ts files are discovered automatically — no config needed
ferret lint

# Disable if needed:
# ferret.config.json → "contractParsers": { "typescript": false }

Both .contract.md and .contract.ts work in the same project. Mixed format is fully supported.

// contracts/search.contract.ts
import { z } from 'zod';
import { defineContract } from '@specferret/core';
import { jwtPayload } from './auth.contract.js';

export const searchResults = defineContract({
  value: 'Search results endpoint',
  output: {
    query: z.string(),
    results: z.array(z.object({ id: z.string(), title: z.string() })),
  },
  consumes: [jwtPayload],
});

ferret status

ferret status  12 contracts

  stable        10
  needs-review   2

  NEEDS REVIEW
  auth.jwt          breaking — 3 dependents
  tables.document   non-breaking — 1 dependent

Each type uses the same frontmatter convention. The type field is used for grouping and reporting.

Type semantics are strict at runtime:

• ferret.type must be exactly one of: api, table, type, event, flow, config
• Unknown values are rejected during extraction with an error that lists allowed values
• Custom type namespaces are not currently supported as runtime extensions

Extension model:

• If a contract does not fit one of the six core types, use the closest core type and open an issue for model expansion

Migration note for legacy repos:

• Replace legacy values like schema, service, or model with the closest supported core type before running ferret scan or ferret lint

See CHANGELOG.md for versioned changes and migration notes.

When ferret lint detects drift it classifies every violation:

The impact report shows:

• The drifting contract id and source file
• Every downstream contract that imports it — direct and transitive
• Depth of the transitive chain

Run ferret review to step through each breaking drift, choose an action (accept / update / reject), and write resolution notes back to the contract file.

ferret review --json

ferret lint --ci

Minimal GitHub Actions step (reusable action)

- name: SpecFerret CI
  uses: BenGardiner123/action@v1
  with:
    baseline-mode: committed

Full job example

jobs:
  ferret:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: SpecFerret CI
        uses: BenGardiner123/action@v1
        with:
          baseline-mode: committed
          artifact-name: ferret-lint-ci

Starter templates:

• docs/ci-templates/ferret-action-single-package.yml
• docs/ci-templates/ferret-action-monorepo.yml
• docs/ci-templates/ferret-action-pr-only.yml

Baseline modes

SpecFerret is not a planning tool. It enforces contract consistency downstream of planning tools.

If you use BMAD or spec-kit:

1. Produce PRD, architecture, and stories as usual
2. Capture concrete shapes in .contract.md files under contracts/
3. Run ferret lint to validate and enforce consistency across the team

Example repo layout

your-project/
  _bmad-output/
    PRD.md
    architecture.md
  contracts/
    auth/
      jwt.contract.md
    tables/
      user.contract.md
    api/
      get-users.contract.md
  .ferret/
    context.json
  ferret.config.json

specferret/
├── packages/
│   ├── core/               @specferret/core
│   │   └── src/
│   │       ├── store/      # DBStore interface · SQLite · Postgres · factory
│   │       ├── extractor/  # frontmatter.ts · typescript.ts · typescript-contract.ts · validator.ts · upward-classifier.ts · hash.ts
│   │       ├── reconciler/ # BFS engine — dirty node flagging
│   │       ├── context/    # context.json writer
│   │       ├── watch/      # file watcher
│   │       ├── audit/      # bidirectional audit report
│   │       ├── config.ts   # project config loader
│   │       └── index.ts    # public re-exports
│   └── cli/                @specferret/cli
│       └── bin/
│           ├── commands/   # init · scan · lint · review · extract · status · watch · audit
│           └── ferret.ts   # CLI entrypoint
├── apps/
│   └── site/               specferret.dev (Astro)
├── spec/                   Architecture, stories, contract schema
├── docs/                   Quickstart, demo runbook, images
└── scripts/                Build helpers

PRs welcome. The codebase is intentionally small and readable.

• Postgres store — production-grade persistence without SQLite
• ferret audit — bidirectional drift report across all contracts (shipped v0.4.0)
• roadmap → pending status rename — contract lifecycle uses pending everywhere; ferret lint shows ✓ only when pending count is zero; context.json v3.0 (shipped v0.5.0 / S62)
• source field on defineContract() — cross-file upward drift for .contract.ts projects without the three-representation trap (shipped v0.5.0 / S63)
• Auto-infer stable from source during ferret scan — contracts auto-promote from pending → stable when source resolves clean; no manual declaration needed (shipped v0.6.0)
• ferret upgrade — SQLite → Postgres migration command
• ferret place — AI-powered feature placement against the graph
• ferret benchmark — provider benchmarking for AI-assisted review
• GitHub Action adoption (Sprint 6) — one-line CI enforcement via uses: BenGardiner123/action@v1
• Upward code-to-spec drift (Sprint 7) — catch implementation drift when specs are not updated
• TypeScript-native contracts (Sprint 8) — .contract.ts with defineContract(), Zod schemas, ferret status
• Tree-sitter extraction — TypeScript shape extraction without annotations (shipped)
• Multi-language support — Go, Python, OpenAPI (post Phase 5)
• Hosted dashboard — team-wide contract health, analytics, SSO/RBAC
• Branch-matrix dogfooding (Sprint 5) — scenario branches across spec-kit and BMAD validation repos

See spec/ROADMAP.MD for the full plan.

Latest validated evidence (post explicit S40/S41/S42 assertions):

Release evidence (v0.1.3 publish window):

Sprint 5 expands this from a single smoke path to a branch matrix. Operational details live in spec/GA-VALIDATION-REPOS.MD and spec/GA-VALIDATION-RUNBOOK.MD.

bun install
bun test
bun run build

Performance benchmark guardrails

Use explicit performance budgets when validating contributor changes:

# Lint clean-run budget (project baseline target)
ferret lint --perf-budget-ms 500

# Extract runtime budget (tune per fixture/repo size in CI)
ferret extract --perf-budget-ms 1000

If a budget is exceeded, the command exits non-zero and prints an actionable diagnostic.

Documentation safety rule

• Never include PII or secrets in docs, contracts, runbooks, screenshots, logs, or release evidence.
• Always use synthetic placeholders (for example user@example.test, REDACTED_TOKEN).
• Redact sensitive values before commit.

Monorepo packages

Package	Path	npm
@specferret/core	packages/core
@specferret/cli	packages/cli
specferret.dev (Astro)	apps/site	—

Docs

• docs/QUICKSTART.md
• spec/MASTER-ARCHITECTURE.MD
• spec/CONTRACT-SCHEMA.MD
• spec/ROADMAP.MD

_{MIT License · specferret.dev · "SpecFerret keeps your specs honest."}