v3.0.0 — Behavior Governance

dotforge v3.0.0 — Behavior Governance

dotforge v3 ships a runtime behavior governance layer on top of the v2.9 configuration layer. Behaviors are declarative policies on tool calls, compiled to `PreToolUse` hooks that share a session-scoped state file. Opt-in and non-breaking — v2.9 projects run unchanged.

What's new

• Behavior catalogue (`behaviors/`): `no-destructive-git`, `search-first`, `verify-before-done`, `respect-todo-state` (core, on by default) + `plan-before-code`, `objection-format` (opinionated, opt-in)
• Declarative DSL: `behavior.yaml` with closed field/operator set, 5-level escalation (silent → nudge → warning → soft_block → hard_block), flag-based temporal gating, template rendering
• Compiler: YAML → bash hooks + `settings.json` snippet. Conditions enforced at runtime via `regex_match`, `contains`, `starts_with`, …
• Runtime: mkdir-based locking, TTL 24h, counters, flags, pending_block reinvocation detection for override audit
• CLI: `/forge behavior list | describe | status | on | off | strict | relaxed` with project and session scopes
• Audit dimension 14: `/forge audit` now scores v3 behavior coverage (0-1)
• 33 tests green across runtime, compiler, CLI, and per-behavior scenarios

Example

```
Bash(git push origin main --force)
PreToolUse:Bash hook returned blocking error
PreToolUse:Bash says: Destructive git operation blocked: force push,
hard reset, clean -f, and forced branch delete
are not allowed.
Error: Hook PreToolUse:Bash denied this tool
```

Spec of record

• `docs/v3/SPEC.md` — evaluation algorithm, level table
• `docs/v3/SCHEMA.md` — `behavior.yaml v1`
• `docs/v3/RUNTIME.md` — state.json, locking, TTL, flags
• `docs/v3/MIGRATION.md` — v2.9 → v3 upgrade path
• `docs/changelog.md` — full release notes

Breaking changes

None. v3 is purely additive. A v2.9.1 project upgraded to v3.0.0 continues to work with zero changes until the user explicitly creates `behaviors/` and wires compiled hooks into `settings.json`.

Test suite

• runtime: 8
• compiler: 1
• CLI: 5
• search-first: 5
• no-destructive-git: 2
• verify-before-done: 3
• respect-todo-state: 2
• plan-before-code: 3
• objection-format: 2

Total: 33 tests green (up from 18 in v3.0.0-alpha.1).

v2.9.0 — Hardening + Portability + Upstream Alignment

Hardening + Portability + Upstream Alignment — E2E Validated

Verdict: SHIP — 28/28 checklist items passed

Reliability Fixes (Codex Review)

• score.sh --json: sanitized heredoc + True/False Python
• check-updates.sh: manifest path corrected
• detect-stack-drift.sh: schema + react/vite message fixed
• hookify: project-relative paths
• test-config.sh: injection scan false positive fixed
• Manifest schema: stacks array added

Portability (macOS + Linux + WSL + Git Bash)

• timeout → gtimeout → skip fallback
• _hash() POSIX: md5sum → md5 → cksum
• Shebangs normalized to #!/usr/bin/env bash
• New: install.sh one-liner with platform detection

Upstream Alignment (Claude Code v2.1.84–v2.1.92)

• 26 hook events (Setup removed), if conditional, defer decision
• 6 permission modes (auto, dontAsk added)
• 1M context GA for Opus 4.6 / Sonnet 4.6
• MCP 500K result override, paths: YAML list syntax
• Claude 3 Haiku deprecated (Apr 19, 2026)

Quick Install

curl -fsSL https://raw.githubusercontent.com/luiseiman/dotforge/main/install.sh | bash

E2E Validation

• Bootstrap on clean project: 20 files, react-vite-ts detected
• Audit: 8.87/10 (text + JSON valid)
• Status: 12 projects, avg 9.8/10
• Sync: no destruction of customizations

Full changelog: https://github.com/luiseiman/dotforge/blob/main/docs/changelog.md

v2.8.1 — Source-Verified Corrections + Cleanup

Source-Verified Corrections + Cleanup

• Fix: compaction threshold corrected to effectiveContextWindow - 13K tokens (~93.5% for 200K)
• Fix: MEMORY.md index dual cap: 200 lines AND 25KB
• Fix: auto-mode permission stripping is reversible (restored on exit)
• Fix: complete dangerous patterns list documented
• Fix: hook events count 25 → 27
• Fix: PostCompact dual interface documented
• New: tool result size limits (50K/tool, 200K/turn, 30K bash)
• New: tool concurrency & safety classification table
• New: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80 in template settings
• Cleanup: go-api, python-fastapi, _common.md split

Full changelog: https://github.com/luiseiman/dotforge/blob/main/docs/changelog.md

v2.8.0 — P1 Internals Alignment

P1 Internals Alignment

Based on cross-repository reverse engineering of Claude Code internals (5 repos analyzed).

Fixes

• node-express glob narrowed to backend paths (avoids react overlap)
• data-analysis glob removed .py (avoids python-fastapi overlap)
• Auto-mode safe permissions: replaced python3/node/npm/aws/gcloud with specific tool commands in 6 stacks

New

• System prompt override patterns in python-fastapi, java-spring, go-api
• ToolSearch Step 0 in watch-upstream + scout-repos
• SessionEnd timeout env var (5000ms default)
• Async hooks documentation in hookify
• test-runner model: haiku → sonnet
• 5K token output budget in all agents
• context: fork on 5 heavy skills
• 3 internal analysis docs (internals, improvement plan, feature flags)

Docs

• best-practices: async hooks, @include directive, auto-mode stripping
• security-checklist: YOLO mode safety
• usage-guide: skill context:fork
• 36-item improvement plan (P0+P1 done, P2-P3 pending)

Full changelog: https://github.com/luiseiman/claude-kit/blob/main/docs/changelog.md

v2.7.1 — Hook Architecture Corrections

• PreCompact confirmed non-blocking
• PostCompact payload verified (compact_summary + trigger)
• Hook types http, prompt, agent documented
• 4 new hook events: PermissionRequest, SubagentStart, CwdChanged, StopFailure
• globs: vs paths: documentation corrected

v2.7.0 — Domain Knowledge Layer + Context Continuity

• Domain learning rule (globs:**/*)
• /forge domain extract|sync-vault|list
• PostCompact hook → writes compact_summary to last-compact.md
• SessionStart hook → re-injects context after compaction
• /forge audit shows domain knowledge section
• /forge sync skips .claude/rules/domain/

v2.6.1 — Docs + Rule Loading

• Documentation updated with eager vs lazy rule loading
• guia-uso.md synchronized to v2.7.1
• audit/score.sh standalone for CI

v2.6.0 — CI/CD, Stack Drift, MCP UX

• audit/score.sh standalone scorer for GitHub Actions
• detect-stack-drift.sh PostToolUse hook
• /forge mcp add command
• MCP version pinning + update-versions.sh
• Model IDs table in model-routing.md
• session-report.sh wired in standard/full profiles

v2.5.0 — Capture, MCP Templates, Model Routing

• /forge capture with auto-context detection
• /cap shorthand alias
• MCP server templates: github, postgres, supabase, redis, slack
• Model routing rules: haiku/sonnet/opus by task type
• 7 agents with explicit model assignments

v2.4.0 — Init, Unregister, Auto-update

What's new

• /forge init — Quick-start setup: auto-detects stack, asks 3 questions (what it does/doesn't, built with what, how you work), generates personalized config. Detects user language.
• /forge unregister — Remove a project from the registry without deleting its .claude/ config
• /forge global sync auto-updates — Now runs git pull --ff-only on claude-kit before syncing ~/.claude/. No more manual cd && git pull.
• Privacy fix — Registry ships empty (projects: []). Local data in gitignored projects.local.yml. No more private paths in the public repo.
• 15 skills, 7 agents (added session-reviewer)

Quick start

git clone --depth 1 https://github.com/luiseiman/claude-kit.git
cd claude-kit && ./global/sync.sh

Then in any project:

/forge init