diff --git a/README.md b/README.md index 5b45f60..c4f1bf9 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ practice makes claude perfect | [**Voice Mode**](https://x.com/trq212/status/2028628570692890800) ![beta](!/tags/beta.svg) | `/voice` | [![Best Practice](!/tags/best-practice.svg)](https://x.com/trq212/status/2028628570692890800) speak to prompt - /voice to activate| | [**Simplify & Batch**](https://x.com/bcherny/status/2027534984534544489) | `/simplify`, `/batch` | [![Best Practice](!/tags/best-practice.svg)](https://x.com/bcherny/status/2027534984534544489) Built-in skills for code quality and bulk operations — simplify refactors for reuse and efficiency, batch runs commands across files | | [**Agent Teams**](https://code.claude.com/docs/en/agent-teams) ![beta](!/tags/beta.svg) | built-in (env var) | [![Best Practice](!/tags/best-practice.svg)](https://x.com/bcherny/status/2019472394696683904) [![Implemented](!/tags/implemented.svg)](implementation/claude-agent-teams-implementation.md) Multiple agents working in parallel on the same codebase with shared task coordination | -| [**Remote Control**](https://code.claude.com/docs/en/remote-control) | `/remote-control`, `/rc` | [![Best Practice](!/tags/best-practice.svg)](https://code.claude.com/docs/en/remote-control) Continue local sessions from any device — phone, tablet, or browser · [Headless Mode](https://code.claude.com/docs/en/headless) | +| [**Remote Control**](https://code.claude.com/docs/en/remote-control) | `/remote-control`, `/rc` | [![Best Practice](!/tags/best-practice.svg)](https://x.com/noahzweben/status/2032533699116355819) Continue local sessions from any device — phone, tablet, or browser · [Headless Mode](https://code.claude.com/docs/en/headless) | | [**Git Worktrees**](https://code.claude.com/docs/en/common-workflows) | built-in | [![Best Practice](!/tags/best-practice.svg)](https://x.com/bcherny/status/2025007393290272904) Isolated git branches for parallel development — each agent gets its own working copy | | [**Ralph Wiggum Loop**](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum) | plugin | [![Best Practice](!/tags/best-practice.svg)](https://github.com/ghuntley/how-to-ralph-wiggum) [![Implemented](!/tags/implemented.svg)](https://github.com/shanraisshan/novel-llm-26) Autonomous development loop for long-running tasks — iterates until completion | diff --git a/best-practice/claude-settings.md b/best-practice/claude-settings.md index fd310e9..3612edf 100644 --- a/best-practice/claude-settings.md +++ b/best-practice/claude-settings.md @@ -1,8 +1,8 @@ # Claude Code Settings Reference -![Last Updated](https://img.shields.io/badge/Last_Updated-Mar%2015%2C%202026%2012%3A52%20PM%20PKT-white?style=flat&labelColor=555) ![Version](https://img.shields.io/badge/Claude_Code-v2.1.76-blue?style=flat&labelColor=555) +![Last Updated](https://img.shields.io/badge/Last_Updated-Mar%2015%2C%202026%201%3A10%20PM%20PKT-white?style=flat&labelColor=555) ![Version](https://img.shields.io/badge/Claude_Code-v2.1.76-blue?style=flat&labelColor=555) -A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of v2.1.76, Claude Code exposes **55+ settings** and **140+ environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts). +A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of v2.1.76, Claude Code exposes **60+ settings** and **160+ environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts). @@ -67,7 +67,7 @@ Within the managed tier, precedence is: server-managed > MDM/OS-level policies > | `model` | string | `"default"` | Override default model. Accepts aliases (`sonnet`, `opus`, `haiku`) or full model IDs | | `agent` | string | - | Set the default agent for the main conversation. Value is the agent name from `.claude/agents/`. Also available via `--agent` CLI flag | | `language` | string | `"english"` | Claude's preferred response language | -| `cleanupPeriodDays` | number | `30` | Sessions inactive longer than this are deleted at startup. Setting to `0` deletes all existing transcripts and disables session persistence entirely (no `.jsonl` files written, `/resume` shows no conversations) | +| `cleanupPeriodDays` | number | `30` | Sessions inactive longer than this are deleted at startup. Setting to `0` deletes all existing transcripts and disables session persistence entirely (no `.jsonl` files written, `/resume` shows no conversations, hooks receive an empty `transcript_path`) | | `autoUpdatesChannel` | string | `"latest"` | Release channel: `"stable"` or `"latest"` | | `alwaysThinkingEnabled` | boolean | `false` | Enable extended thinking by default for all sessions | | `skipWebFetchPreflight` | boolean | `false` | Skip WebFetch blocklist check before fetching URLs | @@ -75,6 +75,7 @@ Within the managed tier, precedence is: server-managed > MDM/OS-level policies > | `fastModePerSessionOptIn` | boolean | `false` | Require users to opt in to fast mode each session | | `teammateMode` | string | `"auto"` | Agent team display mode: `"auto"` (split panes in tmux/iTerm2, in-process otherwise), `"in-process"`, or `"tmux"` | | `includeGitInstructions` | boolean | `true` | Include git-related instructions in system prompt | +| `feedbackSurveyRate` | number | - | Probability (0–1) that the session quality survey appears when eligible. Enterprise admins can control how often the survey is shown. Example: `0.05` = 5% of eligible sessions | **Example:** ```json @@ -106,6 +107,25 @@ Store plan and auto-memory files in custom locations. **Use Case:** Useful for organizing planning artifacts separately from Claude's internal files, or for keeping plans in a shared team location. +### Worktree Settings + +Configure how `--worktree` creates and manages git worktrees. Useful for reducing disk usage and startup time in large monorepos. + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| `worktree.symlinkDirectories` | array | `[]` | Directories to symlink from the main repository into each worktree to avoid duplicating large directories on disk | +| `worktree.sparsePaths` | array | `[]` | Directories to check out in each worktree via git sparse-checkout (cone mode). Only the listed paths are written to disk | + +**Example:** +```json +{ + "worktree": { + "symlinkDirectories": ["node_modules", ".cache"], + "sparsePaths": ["packages/my-app", "shared/utils"] + } +} +``` + ### Attribution Settings Customize attribution messages for git commits and pull requests. @@ -230,10 +250,21 @@ Control what tools and operations Claude can perform. **Evaluation order:** Rules are evaluated in order: deny rules first, then ask, then allow. The first matching rule wins. +**Read/Edit path patterns:** Permission rules for `Read`, `Edit`, and `Write` support gitignore-style patterns with four prefix types: + +| Prefix | Meaning | Example | +|--------|---------|---------| +| `//` | Absolute path from filesystem root | `Read(//Users/alice/file)` | +| `~/` | Relative to home directory | `Read(~/.zshrc)` | +| `/` | Relative to project root | `Edit(/src/**)` | +| `./` or none | Relative path (current directory) | `Read(.env)`, `Read(*.ts)` | + **Bash wildcard notes:** - `*` can appear at **any position**: prefix (`Bash(* install)`), suffix (`Bash(npm *)`), or middle (`Bash(git * main)`) +- **Word boundary:** `Bash(ls *)` (space before `*`) matches `ls -la` but NOT `lsof`; `Bash(ls*)` (no space) matches both - `Bash(*)` is treated as equivalent to `Bash` (matches all bash commands) - Permission rules support output redirections: `Bash(python:*)` matches `python script.py > output.txt` +- The legacy `:*` suffix syntax (e.g., `Bash(npm:*)`) is equivalent to ` *` but is deprecated **Example:** ```json @@ -425,6 +456,7 @@ Map Anthropic model IDs to provider-specific model IDs for Bedrock, Vertex, or F | Key | Type | Default | Description | |-----|------|---------|-------------| +| `effortLevel` | string | - | Persist the effort level across sessions. Accepts `"low"`, `"medium"`, or `"high"`. Written automatically when you run `/effort low`, `/effort medium`, or `/effort high`. Supported on Opus 4.6 and Sonnet 4.6 | | `modelOverrides` | object | - | Map model picker entries to provider-specific IDs (e.g., Bedrock inference profile ARNs). Each key is a model picker entry name, each value is the provider model ID | **Example:** @@ -448,10 +480,9 @@ The `/model` command exposes an **effort level** control that adjusts how much r | Low | Minimal reasoning, fastest responses | **How to use:** -1. Run `/model` in Claude Code -2. Select **Default (recommended)** — Opus 4.6 -3. Use **← →** arrow keys to adjust the effort level -4. The setting applies to the current session and future sessions +1. Run `/effort low`, `/effort medium`, or `/effort high` to set directly (v2.1.76+) +2. Or run `/model` → select a model → use **← →** arrow keys to adjust +3. The setting persists via the `effortLevel` key in `settings.json` **Note:** Effort level is available for Opus 4.6 and Sonnet 4.6 on Max and Team plans. The default was changed from High to Medium in v2.1.68. As of v2.1.75, 1M context window for Opus 4.6 is available by default on Max, Team, and Enterprise plans. @@ -634,12 +665,12 @@ Set environment variables for all Claude Code sessions. | `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Disable git-related system prompt instructions | | `ENABLE_CLAUDEAI_MCP_SERVERS` | Enable Claude.ai MCP servers | | `CLAUDE_CODE_EFFORT_LEVEL` | Set effort level: `high`, `medium`, or `low` | -| `CLAUDE_CODE_MAX_TURNS` | Maximum agentic turns before stopping | +| `CLAUDE_CODE_MAX_TURNS` | Maximum agentic turns before stopping *(not in official docs — unverified)* | | `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Disable non-essential network traffic | -| `CLAUDE_CODE_SKIP_SETTINGS_SETUP` | Skip first-run settings setup flow | -| `CLAUDE_CODE_PROMPT_CACHING_ENABLED` | Override prompt caching behavior | -| `CLAUDE_CODE_DISABLE_TOOLS` | Comma-separated list of tools to disable | -| `CLAUDE_CODE_DISABLE_MCP` | Disable all MCP servers (`1` to disable) | +| `CLAUDE_CODE_SKIP_SETTINGS_SETUP` | Skip first-run settings setup flow *(not in official docs — unverified)* | +| `CLAUDE_CODE_PROMPT_CACHING_ENABLED` | Override prompt caching behavior *(not in official docs — unverified)* | +| `CLAUDE_CODE_DISABLE_TOOLS` | Comma-separated list of tools to disable *(not in official docs — unverified)* | +| `CLAUDE_CODE_DISABLE_MCP` | Disable all MCP servers (`1` to disable) *(not in official docs — unverified)* | | `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Max output tokens per response (default: 32000, max: 64000) | | `CLAUDE_CODE_DISABLE_FAST_MODE` | Disable fast mode entirely (`1` to disable) | | `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Disable auto memory (`1` to disable) | @@ -664,11 +695,11 @@ Set environment variables for all Claude Code sessions. | `CLAUDE_CODE_CLIENT_KEY` | Client private key path for mTLS | | `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted mTLS key | | `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | Plugin marketplace git clone timeout in ms (default: 120000) | -| `CLAUDE_CODE_HIDE_ACCOUNT_INFO` | Hide email/org info from UI | +| `CLAUDE_CODE_HIDE_ACCOUNT_INFO` | Hide email/org info from UI *(not in official docs — unverified)* | | `CLAUDE_CODE_DISABLE_CRON` | Disable scheduled/cron tasks (`1` to disable) | | `DISABLE_INSTALLATION_CHECKS` | Disable installation warnings | | `DISABLE_BUG_COMMAND` | Disable the `/bug` command | -| `DISABLE_NON_ESSENTIAL_MODEL_CALLS` | Disable flavor text and non-essential model calls | +| `DISABLE_NON_ESSENTIAL_MODEL_CALLS` | Disable flavor text and non-essential model calls *(not in official docs — unverified)* | | `DISABLE_COST_WARNINGS` | Disable cost warning messages | | `CLAUDE_CODE_SUBAGENT_MODEL` | Override model for subagents (e.g., `haiku`, `sonnet`) | | `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | SessionEnd hook timeout in ms (replaces hard 1.5s limit) | @@ -676,6 +707,29 @@ Set environment variables for all Claude Code sessions. | `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Disable terminal title updates (`1` to disable) | | `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip automatic IDE extension installation (`1` to skip) | | `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Debounce interval in ms for OTel headers helper script | +| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Override Opus model alias (e.g., `claude-opus-4-6[1m]`) | +| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Override Sonnet model alias (e.g., `claude-sonnet-4-6`) | +| `MAX_THINKING_TOKENS` | Maximum extended thinking tokens per response | +| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Auto-compact window behavior configuration | +| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Enable prompt suggestions | +| `CLAUDE_CODE_PLAN_MODE_REQUIRED` | Require plan mode for sessions | +| `CLAUDE_CODE_TEAM_NAME` | Team name for agent teams | +| `CLAUDE_CODE_TASK_LIST_ID` | Task list ID for task integration | +| `CLAUDE_ENV_FILE` | Custom environment file path | +| `FORCE_AUTOUPDATE_PLUGINS` | Force plugin auto-updates (`1` to enable) | +| `HTTP_PROXY` | HTTP proxy URL for network requests | +| `HTTPS_PROXY` | HTTPS proxy URL for network requests | +| `NO_PROXY` | Comma-separated list of hosts that bypass proxy | +| `MCP_TOOL_TIMEOUT` | MCP tool execution timeout in ms | +| `MCP_CLIENT_SECRET` | MCP OAuth client secret | +| `MCP_OAUTH_CALLBACK_PORT` | MCP OAuth callback port | +| `IS_DEMO` | Enable demo mode | +| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Character budget for slash command tool output | +| `VERTEX_REGION_CLAUDE_3_5_HAIKU` | Vertex AI region override for Claude 3.5 Haiku | +| `VERTEX_REGION_CLAUDE_3_7_SONNET` | Vertex AI region override for Claude 3.7 Sonnet | +| `VERTEX_REGION_CLAUDE_4_0_OPUS` | Vertex AI region override for Claude 4.0 Opus | +| `VERTEX_REGION_CLAUDE_4_0_SONNET` | Vertex AI region override for Claude 4.0 Sonnet | +| `VERTEX_REGION_CLAUDE_4_1_OPUS` | Vertex AI region override for Claude 4.1 Opus | --- @@ -684,6 +738,7 @@ Set environment variables for all Claude Code sessions. | Command | Description | |---------|-------------| | `/model` | Switch models and adjust Opus 4.6 effort level | +| `/effort` | Set effort level directly: `low`, `medium`, `high` (v2.1.76+) | | `/config` | Interactive configuration UI | | `/memory` | View/edit all memory files | | `/agents` | Manage subagents | @@ -711,6 +766,12 @@ Set environment variables for all Claude Code sessions. "alwaysThinkingEnabled": true, "includeGitInstructions": true, "plansDirectory": "./plans", + "effortLevel": "medium", + + "worktree": { + "symlinkDirectories": ["node_modules"], + "sparsePaths": ["packages/my-app", "shared/utils"] + }, "modelOverrides": { "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789:inference-profile/anthropic.claude-opus-4-6-v1:0" @@ -780,3 +841,5 @@ Set environment variables for all Claude Code sessions. - [Claude Code GitHub Settings Examples](https://github.com/feiskyer/claude-code-settings) - [Eesel AI - Developer's Guide to settings.json](https://www.eesel.ai/blog/settings-json-claude-code) - [Shipyard - Claude Code CLI Cheatsheet](https://shipyard.build/blog/claude-code-cheat-sheet/) +- [Claude Code Environment Variables Reference](https://code.claude.com/docs/en/env-vars) +- [Claude Code Permissions Reference](https://code.claude.com/docs/en/permissions) diff --git a/changelog/best-practice/claude-settings/changelog.md b/changelog/best-practice/claude-settings/changelog.md index baef95e..1c13c67 100644 --- a/changelog/best-practice/claude-settings/changelog.md +++ b/changelog/best-practice/claude-settings/changelog.md @@ -100,3 +100,22 @@ | 10 | MED | Example Update | Update Quick Reference example to include `effortLevel` and `worktree` settings | ✋ ON HOLD (awaiting user approval) | | 11 | LOW | Suspect Keys | `sandbox.ignoreViolations`, `sandbox.network.deniedDomains` still not in official docs sandbox table | ✋ ON HOLD (kept in report pending verification — recurring from 2026-03-05) | | 12 | LOW | Suspect Keys | `skipWebFetchPreflight`, `skippedMarketplaces`, `skippedPlugins`, `pluginConfigs` — still in JSON schema but not on official settings page | ✋ ON HOLD (kept in report — valid per schema, recurring from 2026-03-05) | + +--- + +## [2026-03-15 01:10 PM PKT] Claude Code v2.1.76 + +| # | Priority | Type | Action | Status | +|---|----------|------|--------|--------| +| 1 | HIGH | New Setting | Add `effortLevel` to Model Configuration — persists effort level across sessions (`"low"`, `"medium"`, `"high"`). Also added `/effort` command to Useful Commands and updated Effort Level how-to section | ✅ COMPLETE (added to Model Overrides table, updated how-to, added /effort command) | +| 2 | HIGH | New Settings | Add Worktree Settings section with `worktree.sparsePaths` (array, sparse-checkout cone mode) and `worktree.symlinkDirectories` (array, symlink dirs to avoid duplication) | ✅ COMPLETE (new Worktree Settings subsection in Core Configuration with table and example) | +| 3 | HIGH | New Setting | Add `feedbackSurveyRate` to General Settings — probability (0-1) for session quality survey | ✅ COMPLETE (added to General Settings table) | +| 4 | HIGH | Missing Env Vars | Add 23 missing env vars to table (20 genuinely new + 3 from code-block-only) | ✅ COMPLETE (added all 23 env vars to Common Environment Variables table) | +| 5 | HIGH | Broken Link | Previous run flagged `https://claudelog.com/configuration/` as ECONNREFUSED — now loads successfully | ✅ COMPLETE (link restored, no action needed) | +| 6 | MED | Permission Syntax | Add Read/Edit gitignore-style path patterns (`//path`, `~/path`, `/path`, `./path`), word-boundary wildcard detail, and legacy `:*` deprecation note | ✅ COMPLETE (added path patterns table, word-boundary note, and `:*` deprecation) | +| 7 | MED | Changed Description | Update `cleanupPeriodDays` to add "hooks receive an empty `transcript_path`" when set to 0 | ✅ COMPLETE (added to description) | +| 8 | MED | Unverified Env Vars | Mark 7 env vars not in official docs as unverified | ✅ COMPLETE (added "not in official docs — unverified" markers) | +| 9 | MED | New Source | Add `https://code.claude.com/docs/en/env-vars` and `https://code.claude.com/docs/en/permissions` to Sources section | ✅ COMPLETE (added both URLs) | +| 10 | MED | Example Update | Update Quick Reference example to include `effortLevel` and `worktree` settings | ✅ COMPLETE (added effortLevel and worktree block to example) | +| 11 | LOW | Suspect Keys | `sandbox.ignoreViolations`, `sandbox.network.deniedDomains` still not in official docs sandbox table | ✋ ON HOLD (kept in report pending verification — recurring from 2026-03-05) | +| 12 | LOW | Suspect Keys | `skipWebFetchPreflight`, `skippedMarketplaces`, `skippedPlugins`, `pluginConfigs` — still in JSON schema but not on official settings page | ✋ ON HOLD (kept in report — valid per schema, recurring from 2026-03-05) | diff --git a/changelog/best-practice/claude-settings/verification-checklist.md b/changelog/best-practice/claude-settings/verification-checklist.md index a5efeb1..ff60f21 100644 --- a/changelog/best-practice/claude-settings/verification-checklist.md +++ b/changelog/best-practice/claude-settings/verification-checklist.md @@ -24,6 +24,9 @@ Rules that verify settings key tables against official docs. | 1B | Key Types | For each key in the tables, verify the Type column matches official docs | content-match | settings documentation page | 2026-03-05 | Initial checklist — type mismatches cause user confusion | | 1C | Key Defaults | For each key with a default, verify the Default column matches official docs | content-match | settings documentation page | 2026-03-05 | Initial checklist — wrong defaults cause unexpected behavior | | 1D | Key Descriptions | For each key, verify the Description column accurately reflects official docs behavior | content-match | settings documentation page | 2026-03-05 | Initial checklist — stale descriptions mislead users | +| 1E | Scope Column | For each key that has a Scope column (MCP, Plugin, Permission tables), verify the scope value matches official docs (e.g., "Managed only", "Any", "Project") | content-match | settings documentation page | 2026-03-15 | v2.1.71 caught `extraKnownMarketplaces` scope wrong ("Any" → "Project"), v2.1.75 caught `autoMemoryDirectory` scope restriction. No rule existed to systematically verify scope columns | +| 1F | Inverse Completeness | For each key in the report tables, verify it exists in official docs OR is explicitly marked as "not in official docs — unverified". Keys with no official backing must be annotated | field-level | settings documentation page + JSON schema | 2026-03-15 | Suspect keys (`sandbox.ignoreViolations`, `skipWebFetchPreflight`, etc.) stayed ON HOLD for 6 runs because no rule checked the reverse direction — items in report that shouldn't be there | +| 1G | Edge-Case Semantics | For settings with special behavior at boundary values (e.g., `0`, empty string, `null`), verify the boundary behavior is documented and matches official docs | content-match | settings documentation page | 2026-03-15 | v2.1.75 caught `cleanupPeriodDays` zero-value behavior late; v2.1.76 added "hooks receive empty transcript_path" detail. Edge cases were under-verified | --- @@ -35,6 +38,8 @@ Rules that verify the settings hierarchy table. |---|----------|-------|-------|-----------------|-------|--------| | 2A | Priority Levels | Verify all priority levels in the hierarchy table match official docs (5-level chain + managed policy) | field-level | settings documentation page | 2026-03-05 | Initial checklist — wrong priority causes override confusion | | 2B | File Locations | For each priority level, verify the file location path matches official docs | content-match | settings documentation page | 2026-03-05 | Initial checklist — wrong paths cause settings to be ignored | +| 2C | Merge Semantics | Verify the array/object merge behavior description (e.g., "concatenated and deduplicated") matches official docs wording exactly | content-match | settings documentation page | 2026-03-15 | v2.1.75 caught "merged" → "concatenated and deduplicated" change. No rule existed to check merge behavior wording | +| 2D | Managed Internals | Verify managed-tier delivery methods (server-managed, MDM, registry, file) and internal precedence order match official docs. Verify platform-specific file paths and deprecation notes | field-level | settings documentation page | 2026-03-15 | v2.1.75 restructured managed tier with internal precedence and Windows path deprecation. These sub-details had no dedicated rule | --- @@ -46,6 +51,8 @@ Rules that verify permission configuration accuracy. |---|----------|-------|-------|-----------------|-------|--------| | 3A | Permission Modes | Verify all permission modes in the table match official docs | field-level | settings documentation page | 2026-03-05 | Initial checklist — missing modes limit user options | | 3B | Tool Syntax Patterns | Verify all tool permission syntax patterns and examples match official docs | content-match | settings documentation page | 2026-03-05 | Initial checklist — wrong syntax causes permission failures | +| 3C | Bidirectional Mode Check | Verify every permission mode in the report exists in official docs, AND every mode in official docs exists in the report. Modes in report but not in docs must be marked "unverified" | field-level | settings + permissions documentation pages | 2026-03-15 | v2.1.74 caught `askEdits`/`viewOnly` in report but not in official docs — they had been unverified since run 1. Unidirectional check (docs→report) missed this for 3 runs | +| 3D | Evaluation Semantics | Verify permission evaluation order (deny-first), remote-environment restrictions, and path-prefix resolution meanings (`//`, `~/`, `/`, `./`) are documented and match official docs | content-match | permissions documentation page | 2026-03-15 | v2.1.75 caught missing evaluation order; v2.1.76 caught missing path-prefix patterns. Semantic behavior rules had no dedicated check | --- @@ -67,6 +74,8 @@ Rules that verify environment variable completeness and ownership. |---|----------|-------|-------|-----------------|-------|--------| | 5A | Env Var Completeness | Verify all `env`-configurable environment variables from official docs appear in the report | field-level | settings documentation page | 2026-03-05 | Initial checklist — missing env vars limit user configuration options | | 5B | Ownership Boundary | Verify no env vars from `best-practice/claude-cli-startup-flags.md` are duplicated in the settings report, and vice versa | cross-file | claude-cli-startup-flags.md vs settings report | 2026-03-05 | Initial checklist — env var refactoring split vars across two files, must prevent re-duplication | +| 5C | Env Var Descriptions | For each env var in the table, verify the description (format, values, behavior) matches official /en/env-vars page | content-match | env-vars documentation page | 2026-03-15 | v2.1.74 caught `ANTHROPIC_CUSTOM_HEADERS` described as "JSON string" instead of "Name: Value format, newline-separated". Rule 5A only checked presence, not description accuracy | +| 5D | Inverse Env Var Check | For each env var in the report table, verify it exists on the official /en/env-vars page OR is explicitly marked "not in official docs — unverified" | field-level | env-vars documentation page | 2026-03-15 | v2.1.76 found 7 env vars in report with no official backing. Without inverse checking, undocumented vars accumulate silently | --- @@ -77,6 +86,7 @@ Rules that verify example accuracy. | # | Category | Check | Depth | Compare Against | Added | Origin | |---|----------|-------|-------|-----------------|-------|--------| | 6A | Quick Reference Example | Verify the Quick Reference complete example uses valid current settings with correct syntax and realistic values | content-match | settings documentation page | 2026-03-05 | Initial checklist — example must demonstrate current best practices | +| 6B | Example URL Validation | Verify any URLs embedded in JSON example blocks (e.g., `$schema`, API endpoints) resolve correctly and use current domains | exists | HTTP response | 2026-03-15 | v2.1.74 caught `$schema` URL using wrong domain (`www.schemastore.org` vs `json.schemastore.org`). URLs inside code blocks were not covered by rule 9B which only checks markdown links | --- @@ -100,6 +110,18 @@ Meta-rules about the workflow verification process itself. --- +## 10. Version Metadata & Suspect Key Lifecycle + +Meta-rules that verify report metadata accuracy and prevent indefinite accumulation of unresolved items. + +| # | Category | Check | Depth | Compare Against | Added | Origin | +|---|----------|-------|-------|-----------------|-------|--------| +| 10A | Version Metadata | Verify the report's version badge, header settings count, and env var count reflect the actual audited version and current table row counts | content-match | report file internal consistency | 2026-03-15 | v2.1.71 caught version badge mismatch; v2.1.69 caught header counts wrong. No rule existed to verify these meta-fields | +| 10B | Suspect Key Escalation | After 5 consecutive runs ON HOLD, suspect keys must be resolved: either (a) confirmed via JSON schema and annotated with "in JSON schema, not on official page", or (b) removed from the report. Report the run count for each suspect key | exists | changelog history | 2026-03-15 | Suspect keys (`sandbox.ignoreViolations`, `skipWebFetchPreflight`, etc.) stayed ON HOLD across 6 runs with no resolution mechanism. Indefinite accumulation provides no value | +| 10C | Bidirectional Completeness | General meta-rule: every settings key, permission mode, and env var in the report must be traceable to an official source or explicitly marked "unverified". This is the inverse of rules 1A/3A/5A. Superset of 1F, 3C, 5D | field-level | official docs vs report | 2026-03-15 | Cross-cutting rule synthesized from research: 6 items were caught late because only docs→report checking existed. The reverse direction (report→docs) catches orphaned entries | + +--- + ## 9. Hyperlinks Rules that verify all hyperlinks in the report are valid.