dotforge

dotforge
**Behavior governance for Claude Code.** Declare runtime policies on tool calls — "search before writing", "no destructive git", "verify before shipping" — and enforce them via compiled PreToolUse hooks that share a session-scoped state file. Escalates silently → nudge → warning → soft_block → hard_block.
Other tools stop at configuration. dotforge governs behavior — and keeps auditing, syncing, and evolving your .claude/ setup across every repo you manage.
For people and teams managing more than one Claude Code project.
v4.0 — what's new (2026-06-03)
Audit two-dimension model + override loop retired (v4.0.x)
- **Override capture loop — shipped in v4.0.0, retired after validation.** A portfolio scan found **0 overrides across all 12 projects in ~7 weeks** (production included; only 4/12 adopted behaviors at all). The auditable override trail + capture loop (process-override-log.sh, overrides.log, SessionStart wiring) were removed as dead weight. The graduated escalation engine (soft_block) — which IS exercised; the happy path is "verify", not "override" — stays. See .claude/rules/domain/native-vs-dotforge-boundary.md.
- **scripts/migrate-v3-to-v4.sh** — safe migration script with mandatory --dry-run, atomic backup, --rollback. See docs/v4/MIGRATION-V3-TO-V4.md.
- **Audit two-dimension model** — **Native Health** (0-10: native Claude Code usage + security) + **dotforge Adoption** (0-4: informational, does not affect the score). Behaviors / workflows moved to the non-penalizing Adoption dimension — native-first projects no longer lose points for skipping dotforge machinery. New Native-Health items: auto-memory hygiene, permission cascade, attribution.
- **domain/workflow-economics.md** (new domain rule) — documents v4 PoC cost-quality findings. Decision matrix: when workflow vs skill. Token economy principles. **TL;DR: workflows are 4-25x more expensive than bash skills for recurring work — use only as on-demand escalation, not as default refactor.**
- **workflows/watch.js** ships as REFERENCE implementation, NOT promoted to /forge watch default. The bash skill remains the production tool.
What v4 is NOT
The original v4 thesis ("workflow-native everywhere") was REJECTED in Phase 0 PoC. 4 smoke tests measured workflows/watch.js at $5-25 per run vs $0.75-1.00 baseline. /forge sync-all, /forge audit, /forge update, /forge watch stay as bash skills. Full PoC findings in docs/v4/SPEC.md.
v3.13 — what's new (2026-06-03)
Workflow security boundary + ultracode runtime layer (v3.13.0)
- **Workflow subagents bypass session permission mode** — workflow-spawned subagents always run in acceptEdits regardless of session mode (including plan). File edits auto-approved. Documented in domain/workflow-automation.md, domain/workflow-and-ultracode-policy.md, domain/permission-model.md. Reinforces that permissions.deny is the only kernel-level backstop for production-tier projects using workflows.
- **/effort ultracode runtime activator** — xhigh reasoning + automatic workflow orchestration per substantive task. Closes the loop with dotforge's tier-based ultracode policy: production/heavy tier → activate via /effort ultracode at session start. session-startup.sh now emits actionable hint.
- **/deep-research bundled workflow** — Claude Code ships built-in workflow that fans out web searches, cross-checks sources, returns cited report.
- **v2.1.160 acceptEdits security prompts** — shell rc files (.zshenv/.zlogin/.bash_login/~/.config/git/) always prompt; build-tool config (.npmrc/.yarnrc*/bunfig.toml/.bazelrc/.pre-commit-config.yaml/.devcontainer/) prompts in acceptEdits. Defense-in-depth pattern with sandbox.filesystem.denyWrite.
- **v2.1.160 keyword rename workflow → ultracode** — the trigger keyword changed. Setting key workflowKeywordTriggerEnabled unchanged. Anti-confusion guidance for dotforge ultracode-tier semantics in CLAUDE.md.
- **v2.1.161 PostToolBatch failure isolation** — failed Bash no longer cancels other parallel calls in the batch. Hook logic must inspect per-tool success.
- **Small additions**: Mantle as new enterprise provider (Bedrock/Vertex/Foundry/Mantle), CLAUDE_CODE_ENABLE_AUTO_MODE=1 opt-in for third-party platforms, claude mcp ${VAR} no longer expanded in CLI output (security fix), single-file grep satisfies read-before-edit, OTEL OTEL_RESOURCE_ATTRIBUTES as metric labels + tool_decision.tool_parameters with OTEL_LOG_TOOL_DETAILS=1, claude agents shows done/total.