@specferret/cli@0.2.0 · 12 scenarios · 2 repos

Validation Matrix

Every release must pass all 12 scenarios against the live npm package in two external validation repositories before publish. Manifests are fetched live from GitHub at build time.

✓ spec-kit · Apr 10, 2026 → ✓ BMAD · Apr 9, 2026 →

clean exit 0

Main Baseline

Clean baseline: no drift expected

main

breaking exit 1

Breaking: Required Field Removed

Breaking: expiresAt removed from auth.jwt required fields. api.GET/search and event.user-action both import auth.jwt and are flagged at depth 1.

review required

scenario/breaking-required-field

breaking exit 1

Breaking: Type Change

Breaking: token field type changed from string to integer in auth.jwt. Type changes are always classified as breaking.

review required

scenario/breaking-type-change

clean exit 0

Non-breaking: Optional Field

Non-breaking: refreshToken optional field added to auth.jwt properties. Not in required list. ferret classifies as non-breaking — node stays stable, lint exits 0.

scenario/nonbreaking-optional-add

breaking exit 1

Transitive Impact Depth

Breaking with transitive depth: auth.jwt loses expiresAt (breaking). api.GET/search and event.user-action flagged at depth 1 (breaking count). api.GET/recommendations imports api.GET/search and is flagged at depth 2 (nonBreaking count).

review required max depth ≥2 direct ≥2 transitive ≥1

scenario/transitive-impact-depth

clean exit 0

Review Resolution Flow

Post-review clean state: repository includes explicit evidence artifacts for accept/update/reject decisions and asserts they are present during scenario checks.

3 proof artifacts

scenario/review-resolution-flow

clean exit 0

Code-First Extraction

Code-first extraction (0.1.4+): src/auth/jwt.ts uses a @ferret-contract source annotation instead of the legacy codeFile frontmatter field. ferret extract is driven by codeContracts.include in ferret.config.json. Scenario asserts extract determinism by running ferret extract twice and requiring byte-identical generated contracts.

extract determinism

scenario/code-first-extract

clean exit 0

Opinionated Layout

Opinionated layout validation: contracts follow the spec-kit folder structure (contracts/<domain>/<name>.contract.md). ferret.config.json uses the lint-first workflow. All contracts are stable and in sync with context.json. Lint exits 0.

scenario/specferret-opinionated-layout

clean exit 0

Agent Mode Init

Agent mode scaffolding (0.1.4+): ferret init --agent-targets claude,copilot,gemini creates canonical agent rules and adapter instruction packs. Scenario asserts clean lint after init and that all expected scaffolding files are present.

5 proof artifacts

scenario/agent-mode-init

breaking exit 1

Breaking: Required Field Added

Breaking: scope field added to auth.jwt required array. Adding a required field breaks existing consumers who do not provide it. Covers S04 breaking class: required field added. Expects auth.jwt flagged as trigger with downstream contracts at depth 1.

review required

scenario/breaking-required-field-added

clean exit 0

No-Op: Property Reorder (No Drift)

No-op formatting change: auth.jwt properties are reordered (expiresAt first). Zero semantic change. ferret hashSchema uses key-sorted canonical JSON so property ordering produces identical hashes. Asserts exit 0 and clean drift class — proves false-positive protection (S03 hash stability).

scenario/noop-no-drift

breaking exit 1

Depth-3 Transitive Chain

Breaking with depth-3 transitive chain: auth.jwt loses expiresAt (breaking). api.GET/search and event.user-action flagged at depth 1. api.GET/recommendations flagged at depth 2. api.GET/trending (imports api.GET/recommendations) flagged at depth 3. Proves BFS traversal does not truncate beyond depth 2.

review required max depth ≥3 direct ≥2 transitive ≥2

scenario/depth-3-chain