docs: v3.0 Phase 0 — behavior governance specifications

[luiseiman]

Summary

• SPEC.md — formal semantics of 5 enforcement levels (silent→nudge→warning→soft_block→hard_block), evaluation algorithm pseudocode, chain rules, output protocol with exact JSON shapes, override protocol, 9 edge cases
• SCHEMA.md — complete YAML shape for behavior.yaml v1, closed DSL specification (operators + fields), template variables, index.yaml format, validation rules, full examples (search-first + no-destructive-git)
• RUNTIME.md — state.json schema with concrete example, session lifecycle, counter mechanics, TTL purge protocol, POSIX-portable mkdir locking, concurrency scenarios, error recovery
• AUDIT.md — overrides.log pipe-delimited format, metrics for /forge audit and /forge behavior status, registry integration, session-report.sh integration, grep one-liners for analysis
• COMPILER.md — compilation pipeline (YAML→bash), generated hook structure, DSL-to-bash operator mapping, settings.json mutation, shared runtime library signatures, PermissionDenied override audit hook, test patterns
• DECISIONS.md — aligned warning channel (stderr→stdout JSON) and locking mechanism (flock→mkdir POSIX) with formal specs

Acceptance criterion: another engineer can implement Phase 1 without questions.

Test plan

• Review SPEC.md evaluation algorithm — verify all conditional branches have defined outcomes
• Review SCHEMA.md search-first example — verify it passes all validation rules in Section 6
• Review RUNTIME.md state.json example — verify it matches SPEC.md counter mechanics
• Review COMPILER.md PermissionDenied hook — verify it covers SPEC.md Section 6 override protocol
• Cross-reference check: every COMPILER.md reference to SPEC/SCHEMA/RUNTIME/AUDIT points to existing sections

🤖 Generated with Claude Code