worclaude 2.7.1 → 2.9.0

package/templates/core/claude-md.md

@@ -10,6 +10,12 @@
 {tech_stack_filled_during_init}
 
 ## Commands
+
+<!-- references package.json (or equivalent for non-Node stacks) -->
+The verification commands below are filled during init from the project's
+package manager scripts. Reference them by script name; do not restate the
+underlying tool invocations.
+
 {commands_filled_during_init}
 
 ## Skills (read on demand, not upfront)
@@ -35,6 +41,7 @@ See `.claude/skills/` — load only what's relevant:
 **Feature branch:** /start → work → /verify → /commit-push-pr
 **After merging PRs:** git checkout develop → git pull → /conflict-resolver (if needed) → /sync
 **Mid-task stop:** /end (writes handoff file)
+**Trigger discipline:** /commit-push-pr and /sync execute only when the human types them. They do not run autonomously after work "feels done."
 
 ## Critical Rules
 1. SPEC.md is source of truth. Do not invent features.
@@ -49,6 +56,7 @@ See `.claude/skills/` — load only what's relevant:
 10. Surgical changes only — every changed line must trace to the request. Don't "improve" adjacent code, comments, or formatting.
 11. Push back when simpler approaches exist. Present alternatives, don't pick silently.
 12. Transform tasks to success criteria. "Fix the bug" → "Write a failing test, then make it pass."
+13. Commit, push, and PR only when the human explicitly invokes /commit-push-pr or /sync. Never run git commit, git push, or gh pr create on your own initiative, never invoke those slash commands without an explicit human trigger, and never auto-answer the Version bump: question — refuse to proceed without a human-selected option.
 
 ## Memory Architecture
 
@@ -58,6 +66,7 @@ See `.claude/skills/` — load only what's relevant:
 - Path-scoped rules: `.claude/rules/` with YAML frontmatter.
 - Session state: `.claude/sessions/` (gitignored).{memory_architecture_extras}
 - Do NOT write session learnings or auto-captured patterns here.
+- If your repository has the Claude Code GitHub Action installed (run `/install-github-action`), `@claude` mentions in PR comments will automatically propose CLAUDE.md updates.
 
 ## Learnings
 

package/templates/hooks/correction-detect.cjs

@@ -37,7 +37,7 @@ try {
       );
     } else if (correctionPatterns.some((p) => p.test(prompt))) {
       process.stdout.write(
-        '[Correction detected] Consider proposing a [LEARN] block if this is a generalizable rule.\n'
+        '[Correction detected — semi-auto] Draft a one-line generalizable rule, then prompt via AskUserQuestion: "Capture as team learning? yes / yes, let me edit / no". On yes or yes-edit, emit a [LEARN] block; the Stop hook will persist it.\n'
       );
     }
   }

package/templates/hooks/learn-capture.cjs

@@ -139,7 +139,6 @@ try {
         `created: ${today}`,
         `category: ${learning.category}`,
         `project: ${projectName}`,
-        'times_applied: 0',
         '---',
         '',
         `**Rule:** ${learning.rule}`,
@@ -163,7 +162,6 @@ try {
           file: filename,
           category: learning.category,
           created: today,
-          times_applied: 0,
         });
       }
     }

package/templates/hooks/obs-agent-events.cjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+'use strict';
+
+// SubagentStart and SubagentStop hook: records each agent event to
+// .claude/observability/agent-events.jsonl. The aggregator
+// (worclaude observability) pairs start+stop on session+agent to
+// compute durations — keeping the hook stateless.
+//
+// Single hook serves both events; the input.event field tells which
+// fired. Always exits 0.
+
+const { readFileSync, appendFileSync, mkdirSync, existsSync } = require('fs');
+const { join } = require('path');
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return;
+  }
+
+  const cwd = process.env.CLAUDE_PROJECT_DIR || input.cwd || process.cwd();
+  const obsDir = join(cwd, '.claude', 'observability');
+  if (!existsSync(obsDir)) {
+    try {
+      mkdirSync(obsDir, { recursive: true });
+    } catch {
+      return;
+    }
+  }
+
+  const event = input.event || input.hook_event_name || 'unknown';
+  const phase = /stop$/i.test(event) ? 'stop' : 'start';
+
+  const entry = {
+    ts: new Date().toISOString(),
+    event: phase,
+    agent: input.agent_name || input.subagent_type || input.agent || 'unknown',
+  };
+  if (input.session_id) entry.session = input.session_id;
+  if (phase === 'stop' && input.exit_status) entry.exit = input.exit_status;
+
+  try {
+    appendFileSync(join(obsDir, 'agent-events.jsonl'), JSON.stringify(entry) + '\n');
+  } catch {
+    // Non-critical
+  }
+}
+
+try {
+  main();
+} catch {
+  // Never block session
+}

package/templates/hooks/obs-command-invocations.cjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+'use strict';
+
+// UserPromptSubmit hook: records slash-command invocations to
+// .claude/observability/command-invocations.jsonl. Reads JSON from stdin
+// per Claude Code hook contract. Skips non-slash prompts (filter is
+// `/^/`). Always exits 0.
+
+const { readFileSync, appendFileSync, mkdirSync, existsSync } = require('fs');
+const { join } = require('path');
+
+const SLASH_RE = /^\s*\/([\w-]+)/;
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return;
+  }
+
+  const prompt = input.prompt || input.user_prompt || input.text || '';
+  const match = SLASH_RE.exec(prompt);
+  if (!match) return;
+
+  const cwd = process.env.CLAUDE_PROJECT_DIR || input.cwd || process.cwd();
+  const obsDir = join(cwd, '.claude', 'observability');
+  if (!existsSync(obsDir)) {
+    try {
+      mkdirSync(obsDir, { recursive: true });
+    } catch {
+      return;
+    }
+  }
+
+  const entry = {
+    ts: new Date().toISOString(),
+    command: '/' + match[1],
+  };
+  if (input.session_id) entry.session = input.session_id;
+
+  try {
+    appendFileSync(join(obsDir, 'command-invocations.jsonl'), JSON.stringify(entry) + '\n');
+  } catch {
+    // Non-critical
+  }
+}
+
+try {
+  main();
+} catch {
+  // Never block session
+}

package/templates/hooks/obs-skill-loads.cjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+'use strict';
+
+// InstructionsLoaded hook: records each skill load to
+// .claude/observability/skill-loads.jsonl. Reads JSON from stdin per Claude
+// Code hook contract. Always exits 0 — never blocks the session.
+
+const { readFileSync, appendFileSync, mkdirSync, existsSync } = require('fs');
+const { join } = require('path');
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return;
+  }
+
+  const cwd = process.env.CLAUDE_PROJECT_DIR || input.cwd || process.cwd();
+  const obsDir = join(cwd, '.claude', 'observability');
+  if (!existsSync(obsDir)) {
+    try {
+      mkdirSync(obsDir, { recursive: true });
+    } catch {
+      return;
+    }
+  }
+
+  const skill =
+    input.skill_name ||
+    input.skill ||
+    input.instructions_name ||
+    (input.path && String(input.path).split('/').filter(Boolean).slice(-2, -1)[0]) ||
+    'unknown';
+  const trigger = input.trigger || input.reason || 'unknown';
+
+  const entry = {
+    ts: new Date().toISOString(),
+    skill,
+    trigger,
+  };
+
+  try {
+    appendFileSync(join(obsDir, 'skill-loads.jsonl'), JSON.stringify(entry) + '\n');
+  } catch {
+    // Non-critical
+  }
+}
+
+try {
+  main();
+} catch {
+  // Never block session
+}

package/templates/hooks/skill-hint.cjs

@@ -2,7 +2,11 @@
 'use strict';
 
 // UserPromptSubmit hook: hints at relevant skills based on user prompt keywords.
-// Reads .claude/skills/ directory, matches skill-name tokens against prompt tokens.
+// Reads .claude/skills/ directory and matches prompt tokens against skill
+// directory names AND each skill's `description:` frontmatter line. The
+// description fallback lets renames stay in sync with intent (e.g. a skill
+// named "compact-safe" still matches the prompt "session context budget"
+// because its description mentions "context" and "session").
 // Outputs at most one hint to stdout if a match is found; empty output otherwise.
 // Always exits 0.
 
@@ -24,6 +28,18 @@ function tokenize(text) {
     .filter((w) => w.length >= 4 && !STOPWORDS.has(w));
 }
 
+function readSkillDescription(skillsDir, slug) {
+  try {
+    const content = readFileSync(path.join(skillsDir, slug, 'SKILL.md'), 'utf8');
+    const fm = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fm) return '';
+    const desc = fm[1].match(/^description:\s*["']?(.+?)["']?\s*$/m);
+    return desc ? desc[1] : '';
+  } catch {
+    return '';
+  }
+}
+
 try {
   const data = JSON.parse(readFileSync(0, 'utf8'));
   const prompt = data.input?.prompt || '';
@@ -50,7 +66,11 @@ try {
 
     for (const slug of skills) {
       const slugTokens = tokenize(slug);
-      const hit = slugTokens.some((t) => promptTokens.has(t));
+      let hit = slugTokens.some((t) => promptTokens.has(t));
+      if (!hit) {
+        const descTokens = tokenize(readSkillDescription(skillsDir, slug));
+        hit = descTokens.some((t) => promptTokens.has(t));
+      }
       if (hit) {
         process.stdout.write(
           `[Skill hint] Consider loading skill: ${slug}/SKILL.md\n`

package/templates/scripts/start-drift.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Drift detection for /start. Invoke as a single command:
+#   bash .claude/scripts/start-drift.sh
+# Bundling this in a script avoids per-line permission prompts that fire on
+# multi-line bash with X=$(...) patterns (env-var-prefixed substitution
+# is not covered by Bash(cmd:*) allow rules).
+set -eu
+
+LAST_SESSION=$(ls -t .claude/sessions/*.md 2>/dev/null | head -1 || true)
+LAST_SHA=""
+if [ -n "$LAST_SESSION" ]; then
+  LAST_SHA=$(awk '/^sha:/ {print $2; exit}' "$LAST_SESSION" 2>/dev/null || true)
+fi
+
+if [ -n "$LAST_SHA" ] && git rev-parse --verify --quiet "$LAST_SHA" >/dev/null 2>&1; then
+  echo "Commits since last session SHA ($LAST_SHA):"
+  git log --oneline "$LAST_SHA"..HEAD 2>/dev/null | head -15
+elif [ -n "$LAST_SESSION" ]; then
+  SESSION_DATE=$(echo "$LAST_SESSION" | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' | head -1)
+  echo "Commits since last session ($SESSION_DATE):"
+  git log --oneline --since="$SESSION_DATE" 2>/dev/null | head -15
+else
+  echo "No previous session found. Recent commits:"
+  git log --oneline -10 2>/dev/null
+fi
+
+echo ""
+echo "Current branch:"
+git branch --show-current 2>/dev/null

package/templates/scripts/sync-release-scope.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Resolve the last release tag and its commit date (YYYY-MM-DD) for /sync.
+# Invoke as a single command:
+#   bash .claude/scripts/sync-release-scope.sh
+# Output: two key=value lines suitable for downstream parsing.
+#   last_tag=v1.2.3
+#   since=2026-04-01
+# When no tag exists, both values are empty and /sync should bootstrap one.
+set -eu
+
+LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+SINCE=""
+if [ -n "$LAST_TAG" ]; then
+  SINCE=$(git log -1 --format=%as "$LAST_TAG" 2>/dev/null || echo "")
+fi
+
+printf 'last_tag=%s\nsince=%s\n' "$LAST_TAG" "$SINCE"

package/templates/scripts/test-coverage-changed-files.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# List files changed since the last release tag (or last 10 commits if no tag).
+# Invoke as a single command:
+#   bash .claude/scripts/test-coverage-changed-files.sh
+# Output is one filename per line, sorted and de-duplicated.
+set -eu
+
+LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+
+if [ -n "$LAST_TAG" ]; then
+  git log "$LAST_TAG"..HEAD --name-only --pretty=format: 2>/dev/null | sort -u | grep -v '^$' || true
+else
+  git diff --name-only HEAD~10 2>/dev/null || true
+fi

package/templates/settings/base.json

@@ -19,6 +19,22 @@
       "Bash(worclaude scan:*)",
       "Bash(worclaude setup-state:*)",
 
+      "// -- Shell builtins for slash-command flow --",
+      "Bash(test:*)",
+      "Bash([:*)",
+      "Bash(bash:*)",
+
+      "// -- WebFetch (research targets) + built-in WebSearch --",
+      "WebFetch(domain:docs.anthropic.com)",
+      "WebFetch(domain:docs.claude.com)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:api.github.com)",
+      "WebSearch",
+
+      "// -- Built-in skills used by the workflow --",
+      "Skill(update-config)",
+      "Skill(fewer-permission-prompts)",
+
       "// -- Common Dev Tools --",
       "Bash(echo:*)", "Bash(mkdir:*)", "Bash(touch:*)",
       "Bash(cp:*)", "Bash(mv:*)",
@@ -40,6 +56,29 @@
       "Edit(README*)", "Edit(*.md)",
       "Edit(package.json)", "Edit(pyproject.toml)",
       "Edit(.github/**)"
+    ],
+    "deny": [
+      "// -- Secret files (Read/Edit — Claude's own tools) --",
+      "Read(./.env)", "Read(./.env.*)",
+      "Read(./secrets/**)",
+      "Edit(./.env)", "Edit(./.env.*)", "Edit(./secrets/**)",
+      "Read(./*.pem)", "Read(./*.key)",
+      "Read(./id_rsa)", "Read(./id_ed25519)",
+
+      "// -- SSH and cloud creds (home-relative) --",
+      "Read(~/.ssh/**)",
+      "Read(~/.aws/credentials)",
+      "Read(~/.config/gh/hosts.yml)",
+
+      "// -- Bash file-view commands targeting .env --",
+      "Bash(cat *.env*)", "Bash(head *.env*)", "Bash(tail *.env*)",
+      "Bash(less *.env*)", "Bash(more *.env*)", "Bash(grep *.env*)",
+
+      "// -- Catastrophic rm patterns (literal-match defense-in-depth) --",
+      "Bash(rm -rf /)", "Bash(rm -rf /*)",
+      "Bash(rm -fr /)", "Bash(rm -fr /*)",
+      "Bash(rm -rf ~)", "Bash(rm -rf ~/*)",
+      "Bash(rm -rf $HOME)", "Bash(rm -rf $HOME/*)"
     ]
   },
   "hooks": {
@@ -120,6 +159,40 @@
           "type": "command",
           "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; test -f .claude/hooks/skill-hint.cjs && node .claude/hooks/skill-hint.cjs || true"
         }]
+      },
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; test -f .claude/hooks/obs-command-invocations.cjs && node .claude/hooks/obs-command-invocations.cjs || true"
+        }]
+      }
+    ],
+    "InstructionsLoaded": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; test -f .claude/hooks/obs-skill-loads.cjs && node .claude/hooks/obs-skill-loads.cjs || true"
+        }]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; test -f .claude/hooks/obs-agent-events.cjs && node .claude/hooks/obs-agent-events.cjs || true"
+        }]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; test -f .claude/hooks/obs-agent-events.cjs && node .claude/hooks/obs-agent-events.cjs || true"
+        }]
       }
     ],
     "Notification": [

package/templates/skills/universal/claude-md-maintenance.md

@@ -21,11 +21,12 @@ The cycle:
 This is why the Gotchas section exists. It grows organically from real problems
 encountered during development.
 
-## The 50-Line Target
+## The 200-Line Target
 
-CLAUDE.md should stay under 50 lines of actual content (excluding blank lines and
-section headers). This is a target, not a hard limit, but exceeding it significantly
-means CLAUDE.md is trying to do too much.
+CLAUDE.md should stay under 200 lines of actual content. This is the official
+Claude Code guidance and matches `worclaude doctor`'s WARN threshold (150 lines /
+30,000 chars) and ERROR threshold (200 lines). It is a target, not a hard limit,
+but exceeding it significantly means CLAUDE.md is trying to do too much.
 
 Claude reads CLAUDE.md at the start of every session and after every /compact.
 Long CLAUDE.md files waste context on every single interaction.
@@ -78,7 +79,7 @@ Each gotcha should be:
 ## When to Prune
 
 Review CLAUDE.md when:
-- It exceeds 50 lines
+- It exceeds the 200-line target
 - You notice rules that no longer apply
 - A rule has been absorbed into a skill
 - Two rules say the same thing differently
@@ -102,25 +103,60 @@ Only add rules for recurring problems.
 
 ## The @include Directive
 
-When CLAUDE.md grows beyond the 50-line target, use `@include` to split content
-into separate files while keeping it loadable:
+When CLAUDE.md outgrows what one file can hold cleanly, use `@path/to/import`
+to split content into separate files that still load with CLAUDE.md:
 
 ```markdown
 # CLAUDE.md
 ## Key Files
-@./docs/conventions.md
-@./docs/api-standards.md
+@README
+@docs/git-instructions.md
+@~/.claude/my-project-instructions.md
 ```
 
-- `@./relative` — relative to the file containing the directive
-- `@~/path` — relative to home directory
-- `@/absolute` — absolute path
+Syntax (per official Claude Code docs):
+
+- `@path/to/import` — relative to the file containing the directive
+  (e.g., `@README`, `@docs/git-instructions.md`)
+- `@~/path` — home-directory relative
+  (e.g., `@~/.claude/my-project-instructions.md`)
 - Works in CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md, and CLAUDE.local.md
 - Does NOT work inside code blocks (only in leaf text nodes)
 - Non-existent files are silently ignored; circular references are prevented
 
-This is the recommended alternative to cramming everything into CLAUDE.md.
-Each included file still consumes context budget, so use judiciously.
+Behavior:
+
+- **Imports load at launch and consume context.** They help organization, not
+  context budget. Splitting CLAUDE.md into 5 files of 50 lines each produces
+  the same context cost as one 250-line file.
+- **Recursion is capped at 5 hops.** A imports B imports C... — Claude stops
+  resolving after 5 levels.
+- **External imports trigger an approval dialog on first use.** Importing a
+  path outside the project root (e.g., a system-wide config) prompts the user
+  to confirm before the import resolves. This is a one-time approval.
+
+### The `@~/.claude/...` worktree-share pattern
+
+Worktree agents (`isolation: worktree`) operate in a freshly-checked-out copy
+of the repo. Anything in `.claude/CLAUDE.local.md` or other gitignored files
+is not present in the worktree, so the agent loses your local rules.
+
+Workaround: store shared local rules in a home-directory file and import it
+from the project's CLAUDE.md:
+
+```markdown
+# CLAUDE.md
+@~/.claude/my-team-rules.md
+```
+
+The worktree agent re-reads `~/.claude/my-team-rules.md` at launch (it lives
+outside the repo, so no checkout is needed) and gets the same rules as your
+main session. The first run triggers an external-import approval; after that
+it loads silently.
+
+Reserve this pattern for rules that belong to *you* across all projects
+(coding style preferences, personal shortcuts). Team-shared rules should
+still live inside the repo.
 
 ## Gotchas
 

package/templates/skills/universal/git-conventions.md

@@ -6,6 +6,16 @@ version: "1.0.0"
 
 # Git Conventions
 
+## Invocation Boundary
+
+`git commit`, `git push`, and `gh pr create` are invoked only when the human
+explicitly types `/commit-push-pr` or `/sync` (or one of their listed Trigger
+Phrases). The slash commands themselves are not invoked autonomously — wait for
+the human trigger. The `Version bump:` AskUserQuestion in `/commit-push-pr` is
+non-skippable; refuse to proceed without an explicit human selection.
+
+See CLAUDE.md Critical Rule 13.
+
 ## Branch Naming
 
 Pattern: `{type}/{short-description}`
@@ -98,7 +108,7 @@ When using `git worktree` for parallel work:
 - Always clean up worktrees when done: `git worktree remove {path}`
 - Don't leave stale worktrees — they hold refs and can cause confusion
 
-Agents that use worktree isolation (code-simplifier, test-writer, ci-fixer, etc.)
+Agents that use worktree isolation (code-simplifier, test-writer, bug-fixer, etc.)
 create and clean up their own worktrees automatically.
 
 ## Shared-State Files

package/templates/skills/universal/memory-architecture.md

@@ -0,0 +1,115 @@
+---
+description: 'Five-layer memory architecture: where each fact lives, how layers interact, when to promote learnings'
+when_to_use: 'When deciding where a new fact, rule, or preference belongs. When triaging a [LEARN] capture. When promoting from learnings to CLAUDE.md.'
+version: '1.0.0'
+---
+
+# Memory Architecture
+
+Worclaude projects use **five distinct memory layers**. Each has a different
+scope, owner, and lifecycle. Routing a fact to the correct layer is a
+load-bearing decision — the wrong layer means the fact is invisible when
+needed, or noisy when not.
+
+## The Five Layers
+
+| Layer                     | Scope    | Owner                   | Lifecycle                        |
+| ------------------------- | -------- | ----------------------- | -------------------------------- |
+| `CLAUDE.md`               | Team     | Manual (humans + Claude via `/update-claude-md`) | Stable, lean (target ~200 lines) |
+| `.claude/rules/`          | Team     | Manual, topic-organized | Stable; optionally path-scoped (deferred — see BACKLOG) |
+| `.claude/learnings/`      | Team     | Hook-captured (`learn-capture.cjs`) | Append-only; transient inputs to promotion |
+| `CLAUDE.local.md`         | Personal | Manual; gitignored      | Per-machine sandbox; never shared |
+| Claude Code auto memory   | Personal | Autonomous (Claude)     | Active, self-pruning              |
+
+The line between team and personal is the most important boundary. Team
+layers are committed and shared with collaborators; personal layers stay
+on the local machine.
+
+## Routing Contract
+
+When a fact, rule, or pattern surfaces during a session, route it like this:
+
+| Source                                              | Destination                       |
+| --------------------------------------------------- | --------------------------------- |
+| A team-relevant rule the user wants enforced — typed `[LEARN]` block or `/learn` invocation | `.claude/learnings/<category>.md` (via hook) |
+| A personal preference (workflow, tone, naming whim) | Claude Code auto memory (Claude does this autonomously when noticed) |
+| A machine-local sandbox value (paths, secrets, dev URLs) | `CLAUDE.local.md` (manual; gitignored) |
+| A topic that has accreted multiple learnings AND is stable | Promote to `CLAUDE.md` via `/update-claude-md` |
+
+**Default rule:** if you cannot point to a specific reason a fact belongs in
+a different layer, it does not belong in `CLAUDE.md`. `CLAUDE.md` is the
+last layer to grow, not the first.
+
+## Layer Interactions
+
+- **`CLAUDE.md` is the read-on-every-session layer.** It is loaded into
+  context at session start and after every `/compact`. Long files waste
+  context on every interaction. Stay under ~200 lines of actual content.
+- **`.claude/learnings/` is the staging area.** Hooks write here on every
+  `[LEARN]` block. Same category = same file = appended block, so a file
+  that grows multiple `**Rule:**` entries signals recurrence. The
+  `index.json` `created` field is updated to the latest capture date —
+  use it as a "last touched" timestamp, not a fixed creation date.
+- **Auto memory runs in parallel.** Claude Code maintains
+  `~/.claude/projects/<project-slug>/memory/` autonomously. It is
+  per-machine and personal. Worclaude does not write to it and does not
+  read from it during `/update-claude-md` promotion (deliberate scope
+  boundary — see BACKLOG for the discussion).
+- **`CLAUDE.local.md` overrides `CLAUDE.md`** for the local machine. Use
+  it for facts that are genuinely user-specific within an otherwise shared
+  project. Do not commit it.
+- **`.claude/rules/` is reserved.** Claude Code's official docs recommend
+  it for topic-organized, optionally path-scoped team rules. Worclaude
+  defers scaffolding it until a usage signal exists; users can still
+  create the folder manually. Do not duplicate `CLAUDE.md` content into
+  `.claude/rules/` ad-hoc.
+
+## Promotion Path: Learnings → CLAUDE.md
+
+Promotion is the bridge from `.claude/learnings/` to `CLAUDE.md`. It is
+deliberately gated by `/update-claude-md` rather than automatic — promotion
+is a content decision, not a mechanical one.
+
+A learning is a **promotion candidate** when at least one of these holds:
+
+1. **Recurrence:** the learning's file in `.claude/learnings/` has 3 or
+   more `**Rule:**` blocks (i.e., the same category was captured at least
+   three times). Counted by scanning the file, not the index.
+2. **Recency cluster:** the index entry's `created` date is within the
+   last 14 days AND the same theme has shown up in another recent
+   learning. Recent + repeated > recent alone.
+3. **Drift:** the learning's content is structurally relevant to an
+   existing `CLAUDE.md` section (e.g., a new "always do X" pattern that
+   would naturally live in `## Critical Rules` or `## Gotchas`) but the
+   pattern is missing from the file.
+
+Even when a candidate qualifies, `/update-claude-md` confirms each
+proposed addition with the user via `AskUserQuestion`. No silent writes.
+
+## Don't / Do
+
+- **Don't** edit `.claude/learnings/` files by hand to "fix" them. They
+  are the raw capture surface. If a learning is wrong, fix the rule in
+  `CLAUDE.md` or remove the learning file.
+- **Don't** scaffold `.claude/rules/` content from old `CLAUDE.md`
+  sections "to make `CLAUDE.md` smaller." Splitting into sub-files just
+  fragments the single source of truth without saving context.
+- **Don't** mix personal preferences into team layers. If something
+  applies only to your local workflow, it belongs in `CLAUDE.local.md`
+  or Claude Code's auto memory — not in `CLAUDE.md`.
+- **Do** delete stale learnings. If a category was captured once eight
+  months ago and never recurred, it is noise.
+- **Do** prune `CLAUDE.md` when it crosses 200 lines. `worclaude doctor`
+  warns at 150 and errors at 200. Pruning is part of maintenance.
+- **Do** read the file before recommending an update. Memory across
+  sessions is not authoritative — current file content is.
+
+## Cross-References
+
+- `/learn` — captures a `[LEARN]` block to `.claude/learnings/`.
+- `/update-claude-md` — proposes promotions from learnings to
+  `CLAUDE.md`, with size + dedup gates.
+- `claude-md-maintenance` skill — what belongs in `CLAUDE.md`, format
+  discipline, the 200-line target.
+- `worclaude doctor` — surfaces drift between `CLAUDE.md` claims and
+  `package.json` reality (see Phase 3 T3.8).