SpecBridge v0.2: offline spec authoring and approval workflow

[HelloThisWorld]

What

Implements Phase E — the production-quality, offline-first spec authoring and approval workflow — on top of the v0.1 read-only runtime. No model, no API key, no network for any command.

New commands

Command	Behavior
spec new <name>	Kiro-compatible feature specs (requirements-first / design-first / quick) and bugfix specs from offline templates; --title, --description, --from-file, --dry-run, --json
spec analyze <name>	Deterministic structural/consistency analysis (--stage, --strict, --json); errors block approval, warnings never do
spec approve <name> --stage <s>	Prerequisite-gated approval recording the SHA-256 of the exact file bytes; --revoke cascades to dependent approvals
spec status <name>	Per-stage approval health with modified-after-approval detection

Extended commands

spec list (MODE/STATUS columns incl. STALE_APPROVAL / unmanaged), spec show (--state, --analysis, --status), doctor (sidecar validation, orphan/stale/invalid state — report-only, never repairs).

Why

Kiro-style specs are only useful if the approve-then-build loop works outside Kiro. v0.2 makes the workflow portable while keeping the v0.1 promise intact: .kiro stays the source of truth, generated files are plain Markdown with zero tool metadata, and workflow state lives entirely in .specbridge/ (versioned zod schema 1.0.0, SHA-256 approval hashes, origin tracking for existing-workspace adoption).

Design points for review

• New package @specbridge/workflow (cli → workflow → compat-kiro → core) keeps the compatibility layer read-only-pure.
• Approval is recorded, never inferred. A stage is approved only if sidecar state holds a hash of the exact bytes; file existence proves nothing.
• Stale detection is read-time and in-memory. Read-only commands report STALE_APPROVAL but never rewrite state; the explicit repair is re-approval, which also invalidates dependent approvals when content changed (they were approved against different bytes).
• Atomic creation. Files are staged under .specbridge/tmp/ and renamed into .kiro/specs/<name> in one step; a failed state write rolls the whole creation back (failure-injection tested). No --force, existing specs are never overwritten.
• Placeholders gate approval. Templates carry machine-recognizable placeholders (<role>, "Add … here.", TBD); detection is deliberately conservative so hand-written specs are never falsely blocked (covered by the v02-manually-edited fixture).
• Existing Kiro projects need no migration. Specs without state are unmanaged and fully usable; the first successful approval initializes state, inferring the workflow mode only when unambiguous.

Testing

• 245 tests, all passing (was 139) — covers all 55 scenarios required by the v0.2 spec: creation, name validation/path traversal, state lifecycle, approval ordering per workflow, revocation cascades, hash stability (CRLF/UTF-8), stale detection, analyzer checks, strict mode, and v0.1 regression guarantees (byte-identical round trip, read-only commands stay read-only).
• 13 new v02-* fixtures; approved-hash fixtures rely on .gitattributes byte protection.
• scripts/smoke.mjs extended with a full end-to-end authoring cycle against the built CLI (19/19 checks).
• pnpm lint, pnpm typecheck, pnpm build all clean; versions consistently bumped to 0.2.0 with a new CHANGELOG.md.

Reviewer notes

• The v0.1 example sidecar states (hand-authored, informal shape — v0.1 never wrote state) were migrated to schema 1.0.0 with real content hashes; pre-1.0.0 shapes now degrade to a SIDECAR_STATE_LEGACY warning.
• vitest.config.ts sets NO_COLOR=1 because picocolors force-enables ANSI on Windows, which broke exact-output assertions.
• spec run/sync/verify/export remain honest "(planned)" stubs (exit 2); runner-assisted generation is documented as a v0.3 candidate only.

🤖 Generated with Claude Code