v1.12.0: Version pinning, security hardening, git worktrees, plugin docs, zsh default

Author: AnExiledDev

.devcontainer/.gitignore

@@ -1,6 +1,7 @@
 # Explicitly ignored (safety net on top of root .* rule)
 .review
 .secrets
+.build-cache/
 
 # Un-ignore dotfiles that should be tracked (overrides root .* pattern)
 !.env.example

.devcontainer/CHANGELOG.md

@@ -1,5 +1,74 @@
 # CodeForge Devcontainer Changelog
 
+## [v1.12.0] - 2026-02-18
+
+### Added
+
+#### Plugin README Documentation
+- **9 new README files** for all marketplace plugins: auto-formatter, auto-linter, code-directive, codeforge-lsp, dangerous-command-blocker, notify-hook, protected-files-guard, ticket-workflow, workspace-scope-guard. Each documents purpose, hook lifecycle, protected patterns, and plugin structure
+
+#### Protected Files Guard: Bash Hook
+- **`guard-protected-bash.py`** — new PreToolUse/Bash hook blocking bash commands that write to protected file paths (companion to existing Edit/Write guard). Covers `>`, `>>`, `tee`, `cp`, `mv`, `sed -i` targeting `.env`, lock files, `.git`, certificates, and credentials
+
+#### Devcontainer Secrets Declaration
+- **`secrets` block** in devcontainer.json declaring `GH_TOKEN`, `NPM_TOKEN`, `GH_USERNAME`, `GH_EMAIL` with documentation URLs for VS Code Codespaces/devcontainer secret management
+
+#### Post-Start Hook System
+- **`run_poststart_hooks()`** in setup.sh — runs executable `.sh` scripts from `/usr/local/devcontainer-poststart.d/`; controlled by `SETUP_POSTSTART` env flag (default: true)
+
+#### Git Worktree Support
+- **System prompt `<git_worktrees>` section** — layout convention, creation commands, project detection, and safety rules
+- **CLAUDE.md documentation** — full worktree section with layout, creation, detection, and compatibility details
+- **setup-projects.sh** — `.worktrees/` explicit scanning at depth 3, `.git` file detection via `gitdir:` check, `"worktree"` tag in Project Manager
+- **protected-files-guard** — `.git` regex updated from `\.git/` to `\.git(/|$)` to cover worktree `.git` pointer files
+
+#### Other
+- **`CLAUDECODE=null` env var** — unsets the detection flag in `remoteEnv` to allow nested Claude Code sessions (claude-in-claude)
+- **Go runtime option** — commented-out `ghcr.io/devcontainers/features/go:1` entry in devcontainer.json for easy opt-in
+
+### Changed
+
+#### Feature Version Pinning
+- All local features pinned from `"latest"` to explicit versions: agent-browser `0.11.1`, ast-grep `0.40.5`, biome `2.4.2`, ruff `0.15.1`, pyright `1.1.408`, typescript-language-server `5.1.3`, TypeScript `5.9.3`
+- External features pinned to minor versions: node `1.6`, github-cli `1.0`, docker-outside-of-docker `1.7`, uv `1.0`, rust `1.4`, claude-code `1.1`
+
+#### Default Shell: bash → zsh
+- VS Code terminal default profile changed from bash to zsh
+- Explicit `zsh` profile added to terminal profile list
+- Claude Teams tmux profile shell changed from bash to zsh
+
+#### Security Hardening
+- **dangerous-command-blocker** — 7 new blocked patterns: Docker container escape (`--privileged`, host root mount), destructive Docker ops (`stop/rm/kill/rmi`), bare force push (no branch specified), `find -exec rm`, `find -delete`, `git clean -f`, `rm -rf ../`. JSON parse failures now fail closed (exit 2 instead of 0)
+- **protected-files-guard** — JSON parse failures fail closed (exit 2 instead of 0)
+
+#### Build & Setup
+- **ccms build cache** — install.sh checks `.build-cache/bin/ccms` before cargo building; caches binary after first build for faster rebuilds; pinned to commit `f90d259a4476`
+- **setup.sh** — `setup-update-claude.sh` now runs in background (non-blocking container start); script failure output displayed for diagnostics; new `background` status indicator in summary
+- **inotify-tools moved to build time** — tmux feature installs inotify-tools via apt at build; setup-projects.sh no longer attempts runtime apt-get install
+- **Container memory** — recommended from 4GB/8GB to 6GB/12GB in troubleshooting docs
+
+#### Writing System Prompt
+- New **Emotional Architecture** section — cognitive-emotional loop, controlled emotion principle, autism framing for POV characters
+- Expanded metaphor guidance — secondary sources beyond primary domain, "would he think this?" test
+- Refined show-don't-tell rules — naming emotion permitted when it adds weight, brief internal processing after major events required
+- Character profile additions — emotional architecture and trigger fields
+
+#### Other
+- **connect-external-terminal.ps1** — tmux session directory respects `WORKSPACE_ROOT` env var with fallback
+- **setup-projects.sh** — inotifywait exclude pattern narrowed from `\.git/` to `\.git` for worktree compatibility
+- **README.md** — 5 new badges (changelog, last commit, npm downloads, Node.js, issues), updated tool/feature/skill counts, added Rust/Bun/ccw, changelog section
+- **CLAUDE.md** — expanded ccw description, fixed Bun registry reference, documented setup-auth.sh/check-setup.sh, added CLAUDECODE/env flags/experimental vars/git worktrees/rules system sections, skill count 17→28
+- **Documentation** — `SETUP_TERMINAL`/`SETUP_POSTSTART` in configuration reference, `CLAUDECODE=null` env var, workspace-scope-guard in plugins.md
+- **Agent definitions** — minor path/prompt fixes across 8 agents (claude-guide, debug-logs, dependency-analyst, explorer, generalist, git-archaeologist, researcher, security-auditor)
+- **.gitignore** — added `.build-cache/` exclusion
+
+### Removed
+
+- **mcp-reasoner feature** — entire feature directory deleted (README, devcontainer-feature.json, install.sh, poststart-hook.sh)
+- **splitrail feature** — entire feature directory deleted (README, devcontainer-feature.json, install.sh)
+
+---
+
 ## [v1.11.0] - 2026-02-17
 
 ### Added

.devcontainer/CLAUDE.md

@@ -49,7 +49,7 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 | `claude` | Run Claude Code with auto-configuration (prefers native binary at `~/.local/bin/claude`) |
 | `cc` | Shorthand for `claude` with config |
 | `ccraw` | Vanilla Claude Code without any config (bypasses function override) |
-| `ccw` | Shorthand for `claude` with writing system prompt |
+| `ccw` | Claude Code with the writing system prompt — uses `writing-system-prompt.md` instead of `main-system-prompt.md`, optimized for creative and technical writing tasks |
 | `ccusage` | Analyze token usage history |
 | `ccburn` | Real-time token burn rate visualization |
 | `agent-browser` | Headless Chromium for browser automation (Playwright-based) |
@@ -113,7 +113,7 @@ ast-grep, biome, ccms, ccstatusline, claude-monitor, dprint, hadolint, lsp-serve
 `ghcr.io/devcontainers/features/node`, `ghcr.io/devcontainers/features/github-cli`, `ghcr.io/devcontainers/features/docker-outside-of-docker`, `ghcr.io/devcontainers/features/go` (all official Microsoft features)
 
 **External features without `version: "none"` support:**
-`ghcr.io/devcontainers-extra/features/uv`, `ghcr.io/anthropics/devcontainer-features/claude-code`, `ghcr.io/nickmccurdy/bun`
+`ghcr.io/devcontainers-extra/features/uv`, `ghcr.io/anthropics/devcontainer-features/claude-code`, `ghcr.io/rails/devcontainer/features/bun`
 
 **External features with `version: "none"` support (Rust):**
 `ghcr.io/devcontainers/features/rust` (official Microsoft feature)
@@ -139,6 +139,8 @@ Scripts in `./scripts/` run via `postStartCommand`:
 | `setup-update-claude.sh` | Installs native Claude Code binary on first run; background auto-updates on subsequent starts |
 | `setup-terminal.sh` | Configures VS Code Shift+Enter keybinding for Claude Code multi-line input |
 | `setup-projects.sh` | Auto-detects projects for VS Code Project Manager |
+| `setup-auth.sh` | Configures Git and NPM auth from `.secrets` file or environment variables |
+| `check-setup.sh` | Verifies CodeForge setup health (binary paths, config files, features) |
 | `setup-symlink-claude.sh` | Symlinks ~/.claude for third-party tool compatibility |
 
 ### External Terminal
@@ -148,6 +150,8 @@ Scripts in `./scripts/` run via `postStartCommand`:
 .devcontainer/connect-external-terminal.sh
 ```
 
+On Windows, use `connect-external-terminal.ps1` (PowerShell equivalent).
+
 ## Installed Plugins
 
 Plugins are declared in `config/defaults/settings.json` under `enabledPlugins` and auto-activated on container start:
@@ -163,7 +167,7 @@ Plugins are declared in `config/defaults/settings.json` under `enabledPlugins` a
 - `protected-files-guard@devs-marketplace` — Blocks edits to secrets/lock files
 - `auto-formatter@devs-marketplace` — Batch-formats edited files at Stop (Ruff for Python, Biome for JS/TS/CSS/JSON/GraphQL/HTML; also supports shfmt, dprint, gofmt, rustfmt when installed)
 - `auto-linter@devs-marketplace` — Auto-lints edited files at Stop (Pyright + Ruff for Python, Biome for JS/TS/CSS/GraphQL; also supports ShellCheck, hadolint, go vet, clippy when installed)
-- `code-directive@devs-marketplace` — 17 custom agents, 17 skills, syntax validation, skill suggestions, agent redirect hook
+- `code-directive@devs-marketplace` — 17 custom agents, 28 skills, syntax validation, skill suggestions, agent redirect hook
 - `workspace-scope-guard@devs-marketplace` — Blocks writes and warns on reads outside the working directory
 
 ### Local Marketplace
@@ -223,6 +227,64 @@ Key environment variables set in the container:
 | `GH_CONFIG_DIR` | `/workspaces/.gh` |
 | `ANTHROPIC_MODEL` | `claude-opus-4-6` |
 | `TMPDIR` | `/workspaces/.tmp` |
+| `CLAUDECODE` | `null` (unset) |
+
+Setting `"CLAUDECODE": null` in `remoteEnv` unsets this variable inside the container, which allows nested Claude Code sessions (claude-in-claude) that would otherwise be blocked by the outer session's detection flag.
+
+All setup steps are controlled by boolean flags in `.devcontainer/.env`. Set any to `false` to disable:
+`SETUP_CONFIG`, `SETUP_ALIASES`, `SETUP_AUTH`, `SETUP_PLUGINS`, `SETUP_UPDATE_CLAUDE`, `SETUP_TERMINAL`, `SETUP_PROJECTS`, `SETUP_POSTSTART`.
+
+### Experimental Environment Variables
+
+These are set in `config/defaults/settings.json` under `env` and control Claude Code experimental features:
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | `1` | Enables Agent Teams (multi-agent orchestration) |
+| `CLAUDE_CODE_EFFORT_LEVEL` | `high` | Sets reasoning effort level |
+| `CLAUDE_CODE_ENABLE_TASKS` | `true` | Enables the task/todo system |
+| `CLAUDE_CODE_PLAN_MODE_INTERVIEW_PHASE` | `true` | Enables interview phase before plan execution |
+| `CLAUDE_CODE_PLAN_V2_AGENT_COUNT` | `3` | Number of agents in Plan V2 orchestration |
+| `CLAUDE_CODE_PLAN_MODE_REQUIRED` | `true` | Forces plan mode for teammate agents |
+| `ENABLE_CLAUDE_CODE_SM_COMPACT` | `1` | Enables smart compaction for context management |
+| `CLAUDE_CODE_FORCE_GLOBAL_CACHE` | `1` | Forces global prompt caching |
+| `FORCE_AUTOUPDATE_PLUGINS` | `1` | Auto-updates plugins on every session start |
+
+## Git Worktrees
+
+CodeForge supports git worktrees for working on multiple branches simultaneously.
+
+### Layout
+
+Worktrees live in a `.worktrees/` directory alongside the main repo:
+
+```
+/workspaces/projects/
+├── CodeForge/           # main repo (.git directory)
+└── .worktrees/          # worktree container
+    ├── feature-a/       # worktree checkout (.git file)
+    └── bugfix-b/        # worktree checkout (.git file)
+```
+
+### Creating Compatible Worktrees
+
+```bash
+cd /workspaces/projects/CodeForge
+mkdir -p /workspaces/projects/.worktrees
+git worktree add /workspaces/projects/.worktrees/my-branch my-branch
+```
+
+### Project Detection
+
+- `setup-projects.sh` scans `.worktrees/` directories at depth 3 (inside container dirs like `projects/`)
+- Worktrees are detected by their `.git` file (containing `gitdir:`) and tagged with both `"git"` and `"worktree"` in Project Manager
+- Each worktree appears as an independent project in VS Code Project Manager
+
+### Compatibility
+
+- `workspace-scope-guard` resolves worktree paths correctly via `os.path.realpath()`
+- `protected-files-guard` protects both `.git/` directories and `.git` files (worktree pointers)
+- Read-only agents (e.g., git-archaeologist) can use `git worktree list` but cannot add/remove worktrees
 
 ## Modifying Behavior
 
@@ -232,3 +294,11 @@ Key environment variables set in the container:
 4. **Add a custom config file**: Add an entry to `config/file-manifest.json` with `src`, `dest`, and optional `overwrite`/`destFilename`
 5. **Add features**: Add to `"features"` in `devcontainer.json`
 6. **Disable auto-setup**: Set variables to `false` in `.env`
+
+## Rules System
+
+Rules live in `config/defaults/rules/` and are copied to `.claude/rules/` by the file manifest (`config/file-manifest.json`) on every container start. Unlike CLAUDE.md (which loads on demand when entering a project), rules load automatically on every Claude Code session.
+
+**Current rules**: `spec-workflow.md`, `workspace-scope.md`, `session-search.md`
+
+**Adding custom rules**: Create a `.md` file in `config/defaults/rules/`, then add a manifest entry in `config/file-manifest.json` pointing to `${CLAUDE_CONFIG_DIR}/rules` as the destination. The rule will be deployed on the next container start.

.devcontainer/README.md

@@ -144,7 +144,8 @@ claude --resume               # Resume previous session
 | Python 3.14 | Base language runtime |
 | Node.js LTS | JavaScript runtime |
 | TypeScript | Via Node.js |
-| Go | Latest stable via devcontainer feature |
+| Go | Optional — uncomment Go feature in `devcontainer.json` to enable |
+| Rust | Latest stable via devcontainer feature |
 | Bun | Fast JavaScript runtime and toolkit |
 
 ### Package Managers
@@ -203,7 +204,9 @@ Copy `.devcontainer/.env.example` to `.devcontainer/.env` and customize:
 | `SETUP_AUTH` | `true` | Configure Git/NPM auth from `.secrets` |
 | `SETUP_PLUGINS` | `true` | Install official plugins + register marketplace |
 | `SETUP_UPDATE_CLAUDE` | `true` | Auto-update Claude Code on container start |
+| `SETUP_TERMINAL` | `true` | Configure VS Code Shift+Enter keybinding for Claude Code terminal |
 | `SETUP_PROJECTS` | `true` | Auto-detect projects for VS Code Project Manager |
+| `SETUP_POSTSTART` | `true` | Run post-start hooks from `/usr/local/devcontainer-poststart.d/` |
 | `PLUGIN_BLACKLIST` | `""` | Comma-separated plugin names to skip |
 
 ### Claude Code Settings
@@ -247,7 +250,7 @@ The default system prompt is in `.devcontainer/config/defaults/main-system-promp
 
 ## Custom Features
 
-CodeForge includes several custom devcontainer features:
+CodeForge includes custom devcontainer features. Any feature can be disabled by setting `"version": "none"` in `devcontainer.json` — the entry stays in place for easy re-enabling. Each feature's README documents its options and dependencies.
 
 | Feature | Description |
 |---------|-------------|
@@ -261,9 +264,14 @@ CodeForge includes several custom devcontainer features:
 | `tree-sitter` | Parser with JS/TS/Python grammars |
 | `lsp-servers` | Pyright and TypeScript language servers |
 | `biome` | Fast JS/TS/JSON/CSS formatter (global install) |
+| `ruff` | Fast Python linter and formatter |
+| `shfmt` | Shell script formatter (disabled by default) |
+| `shellcheck` | Static analysis for shell scripts (disabled by default) |
+| `hadolint` | Dockerfile linter (disabled by default) |
+| `dprint` | Pluggable formatter for Markdown/YAML/TOML (disabled by default) |
+| `ccms` | Claude Code session history search |
 | `notify-hook` | Desktop notifications on Claude completion |
 | `mcp-qdrant` | Qdrant vector database MCP server (optional) |
-| `mcp-reasoner` | Enhanced AI reasoning MCP server (optional) |
 
 ## Safety Plugins
 
@@ -273,9 +281,27 @@ CodeForge includes several custom devcontainer features:
 | `protected-files-guard` | Blocks modifications to .env, lock files, .git/, and credentials |
 | `workspace-scope-guard` | Enforces working directory scope — blocks writes and warns on reads outside the project |
 
+### auto-code-quality (Not Active by Default)
+
+A self-contained combined auto-formatter and auto-linter plugin available in the marketplace at `plugins/devs-marketplace/plugins/auto-code-quality/`. It bundles formatting and linting into a single plugin with a three-phase pipeline: collect edited files (PostToolUse), batch format (Stop), and batch lint (Stop). Supports the same languages as auto-formatter + auto-linter. **Do not enable alongside auto-formatter or auto-linter** — they overlap in functionality.
+
+## Alias Management
+
+Features create shell aliases during container build (e.g., `ccusage`, `ccburn`). Separately, `setup-aliases.sh` creates a managed block in `~/.bashrc` and `~/.zshrc` on every container start for `cc`, `claude`, `ccraw`, `ccw`, and `cc-tools`. Both coexist without conflict — feature aliases are installed at build time while setup aliases are refreshed at start time.
+
+## Credential Management
+
+Three methods for providing GitHub/NPM credentials, in order of precedence:
+
+1. **Environment variables** — Set `GH_TOKEN`, `GH_USERNAME`, `GH_EMAIL`, `NPM_TOKEN` as environment variables (e.g., via Codespaces secrets or `localEnv` in `devcontainer.json`)
+2. **`.secrets` file** — Create `.devcontainer/.secrets` with token values (see template at `.secrets.example`). Auto-configured by `setup-auth.sh` on container start
+3. **Interactive login** — Run `gh auth login` for GitHub CLI, then set git identity manually
+
+All methods persist across container rebuilds via the bind-mounted `/workspaces/.gh/` directory.
+
 ## Agents & Skills
 
-The `code-directive` plugin includes specialized agent definitions and coding reference skills.
+The `code-directive` plugin includes 17 custom agent definitions and 28 coding reference skills.
 
 ### Custom Agents (17)
 
@@ -301,11 +327,11 @@ Agent definitions in `plugins/devs-marketplace/plugins/code-directive/agents/` p
 | `statusline-config` | ccstatusline configuration |
 | `test-writer` | Test authoring with pass verification |
 
-### Skills (17)
+### Skills (28)
 
 Skills in `plugins/devs-marketplace/plugins/code-directive/skills/` provide domain-specific coding references:
 
-`claude-agent-sdk` · `claude-code-headless` · `debugging` · `docker` · `docker-py` · `fastapi` · `git-forensics` · `performance-profiling` · `pydantic-ai` · `refactoring-patterns` · `security-checklist` · `skill-building` · `spec-refine` · `specification-writing` · `sqlite` · `svelte5` · `testing`
+`api-design` · `ast-grep-patterns` · `claude-agent-sdk` · `claude-code-headless` · `debugging` · `dependency-management` · `docker` · `docker-py` · `documentation-patterns` · `fastapi` · `git-forensics` · `migration-patterns` · `performance-profiling` · `pydantic-ai` · `refactoring-patterns` · `security-checklist` · `skill-building` · `spec-build` · `spec-check` · `spec-init` · `spec-new` · `spec-refine` · `spec-review` · `spec-update` · `specification-writing` · `sqlite` · `svelte5` · `testing`
 
 ## Specification Workflow
 
@@ -400,7 +426,7 @@ Common issues and solutions. For detailed troubleshooting, see [docs/troubleshoo
 **CodeForge Documentation**:
 - [Configuration Reference](docs/configuration-reference.md) — all env vars and config options
 - [Plugin System](docs/plugins.md) — plugin architecture and per-plugin docs
-- [Optional Features](docs/optional-features.md) — mcp-qdrant, mcp-reasoner, splitrail
+- [Optional Features](docs/optional-features.md) — mcp-qdrant and other optional components
 - [Keybinding Customization](docs/keybindings.md) — resolving VS Code conflicts
 - [Troubleshooting](docs/troubleshooting.md) — common issues and solutions