SpecBridge v0.4: deterministic spec drift verification and GitHub Action

[HelloThisWorld]

What

v0.4 delivers the drift phase (roadmap Phases H + I): deterministic, offline spec-to-code drift verification and a production node20 GitHub Action. Kiro helps users write specs; SpecBridge now verifies whether the implementation still matches them — no model, no API key, no network access.

Verification engine (@specbridge/drift)

• Git comparison resolution: --diff base...head, --base/--head, --working-tree (default), --staged; -z parsing (UTF-8/spaces/renames/binary/untracked), ref-injection rejection, shallow-clone guidance, --relative so nested .kiro workspaces are scoped correctly.
• Explicit rule registry SBV001–SBV025 (stable IDs, documented in docs/verification-rules.md): approval drift, evidence freshness, requirement–task traceability, impact areas, protected paths, trusted-command outcomes. Heuristic rules are labelled and never default to error (test-enforced).
• Spec policies under .specbridge/policies/<spec>.json (versioned Zod schema, validated globs, advisory/strict modes, per-rule overrides; .git/** protection immutable).
• Affected-spec resolution via six deterministic signals; unmapped (SBV014) and ambiguous (SBV022) files are reported, never ignored.
• Trusted commands come only from .specbridge/config.json; --no-run-verification reuses passing results only from valid, fresh evidence at the exact current HEAD.

CLI

spec verify [name] | --changed | --all, spec affected, spec policy init/show/validate, verify rules/explain. Formats: terminal / versioned JSON (Zod-validated before writing) / Step-Summary-ready Markdown / self-contained HTML (no scripts, no external requests). Exit codes 0/1/2/3/4/5 documented in docs/ci-quality-gates.md.

GitHub Action (integrations/github-action)

node20, committed reproducible bundle (rebuild is byte-identical; CI diffs it), @actions/core only. PR/push/workflow_dispatch diff resolution, 11 validated inputs, 10 outputs, bounded rule-ID annotations, Step Summary. Never modifies tracked files. Consumers need no pnpm and no model.

Approval-hash semantics v2

Approving tasks.md now records a checkbox-normalized approvedPlanHash beside the exact approvedHash: [ ] → [x] progress keeps the approval effective, while task text/ID/hierarchy/reference edits still invalidate it. Requirements/design stay exact-byte. Pre-v0.4 sidecar state keeps validating (exact-byte fallback) and migrates on the next sanctioned write. New evidence records a specContext (approved hashes + checkbox-invariant task fingerprint) for exact freshness checks; v0.3 records fall back to recorded approval timestamps.

Why

Specs that nobody verifies drift silently. This closes the loop promised since v0.1: approved .kiro specs + git diff + task evidence + trusted commands → a reproducible quality gate, locally or in CI — while preserving every v0.1–v0.3 guarantee (byte-identical round trips, surgical checkbox edits, sidecar state outside .kiro).

Reviewer notes

• Verification is read-only. Its only writes are report artifacts (.specbridge/reports/<id>/ when commands execute) and explicit --output files — proven by tree-hash tests.
• SBV006 exemption design: the verified specs' own spec/state/policy files are exempt from protected-path errors (that's spec authoring, governed by the approval rules SBV002/003/023) and reported as info; other specs' .kiro files, steering, .specbridge/config.json, and .git/** error.
• integrations/github-action/dist/index.js is a committed bundle (~1.7 MB) — reviewed via its sources under src/; CI enforces that the bundle matches them.
• The stock existing-kiro-project example genuinely contains drift (task 2 checked, subtasks open); the smoke suite now asserts SBV010 catches it.
• Deferred (documented in the roadmap, not claimed): MCP server, additional runners, spec sync/spec export, SARIF.

Testing

• pnpm test: 520 tests / 42 files, all passing (baseline 362/30; no existing test weakened — two v0.1 assertions updated because spec verify is no longer "(planned)").
• pnpm lint, pnpm typecheck (strict, action sources included), pnpm build: clean.
• pnpm smoke: 28 checks against the built CLI and examples.
• Scenario battery on a live git fixture: SBV005 strict failure, SBV007/SBV009 traceability, checkbox-only progress vs. plan edits, verifier failure exit codes, protected paths, read-only tree hashing.
• Action tested process-level against fixture event payloads (PR/push/dispatch/zero-SHA/shallow, annotation limits, outputs, no tracked-file changes).

🤖 Generated with Claude Code