tdwhere123 · tdwhere123 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -8,7 +8,7 @@
     {
       "name": "do-it",
       "description": "Workflow discipline plugin: skills auto-trigger via hooks; no slash commands required.",
-      "version": "0.10.0",
+      "version": "0.11.0",
       "source": "./",
       "author": {
         "name": "tdwhere123"

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "do-it",
   "description": "Workflow discipline plugin for Claude Code: tier routing, premise grilling, verification gates. Skills auto-trigger via hooks—no slash commands required.",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "author": {
     "name": "tdwhere123"
   },

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,47 @@
 
 - No unreleased changes.
 
+## 0.11.0
+
+### Fixed
+
+- macOS CI: the `anti-patterns-lint` hook is now BSD-portable. The no-consumer
+  check uses git grep's own `-w` word match instead of a GNU `\b` regex, and
+  file paths are canonicalized with `pwd -P` before repo-relative stripping so
+  the `/var`→`/private/var` symlink no longer breaks self-exclusion. The macOS
+  hook-test job was failing on these for three releases.
+
+### Changed
+
+- Handbook slimmed from 12 templates to 7 project-truth files. The five process
+  docs that duplicated skills were removed: the task-card layout now lives in
+  `do-it-planning`, the review protocol in `do-it-review-loop`, the dispatch
+  contract in `do-it-subagent-orchestration`, the execution pipeline in
+  `do-it-router`, and the handbook maintenance rules in the `do-it-handbook`
+  skill.
+- Three low-utilization skills consolidated (23 → 20): `do-it-grill-log` folded
+  into `do-it-grill` (Grill Log Artifact), `do-it-domain-language` into
+  `do-it-context` (Domain Glossary Mode), and the optional `do-it-visual-planning`
+  into `do-it-planning` (Visual Aids); the visual companion (local browser
+  server + render templates) moves under `do-it-planning` and its templates were
+  visually redesigned. Existing installs remove the deprecated skills on upgrade.
+- `do-it-router` gains a § Restraint principle: advisory over blocking, reuse
+  over add, no unbounded libraries, check git intent before deleting, and
+  capabilities that auto-fire instead of requiring a `/command`.
+- `do-it-context` gives `CLAUDE.md` a formal role in the source-of-truth
+  hierarchy, draws the `CLAUDE.md` / `CONTEXT.md` / handbook boundary, and can
+  scaffold a lean `CLAUDE.md` on demand (additive, never auto-write).
+
+### Added
+
+- Advisory nudges (one-shot, never block): after grill on durable-plan work with
+  no plan card, a reminder to land the plan card before implementation drifts
+  ahead; on established projects (`.do-it/CONTEXT.md` or handbook present) or
+  port/restore prompts, a reminder to read existing structure / grep current
+  code first.
+- `comments-lint` now flags `phase N`, `wave N`, and `BL-NNN` stage markers as
+  `task-ref` comments.
+
 ## 0.10.0
 
 ### Added

diff --git a/README.md b/README.md
@@ -112,8 +112,7 @@ CODEX_HOME=/tmp/do-it-plugin-test codex plugin marketplace add /path/to/do-it
 ```
 
 The Codex plugin bundle lives at `plugins/do-it/` and is generated from
-`manifest.json`. It includes 23 skills and 23 agents, including optional
-`do-it-visual-planning`.
+`manifest.json`. It includes 20 skills and 23 agents.
 
 For v1, pair plugin installation with `do-it setup` when you need enforced
 automatic hooks. Local `codex features list` currently reports
@@ -137,9 +136,8 @@ do-it doctor --target=claude
 ```
 
 The Claude target installs to `~/.claude/` by default; override with
-`CLAUDE_PLUGIN_ROOT_OVERRIDE`. Optional skills such as
-`do-it-visual-planning` are excluded by default; opt in with
-`--with-optional`.
+`CLAUDE_PLUGIN_ROOT_OVERRIDE`. The `--with-optional` flag installs any manifest
+skills marked optional (none are marked optional in 0.11.0).
 
 ## What It Installs
 
@@ -322,8 +320,7 @@ emitting valid JSON without `jq`. Stale session directories are pruned after 7
 days. `do-it-router` gains an `Integrity` section — a failure is a clue to
 trace, not a symptom to hide — referenced by `do-it-debugging`,
 `do-it-fix-loop`, `do-it-verification-gate`, and the subagent dispatch
-contract. `do-it-visual-planning` ships `plan-card` / `review-report` scenario
-templates, and the CI test job now also runs on macOS. If a machine has a
+contract. The CI test job now also runs on macOS. If a machine has a
 cached `0.8.0` plugin, reinstall or refresh so the host loads the new hook and
 skill files.
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -102,7 +102,7 @@ CODEX_HOME=/tmp/do-it-plugin-test codex plugin marketplace add /path/to/do-it
 ```
 
 Codex plugin bundle 位于 `plugins/do-it/`，由 `manifest.json` 生成。
-它包含 23 个 skill 和 23 个 agent，包括可选的 `do-it-visual-planning`。
+它包含 20 个 skill 和 23 个 agent。
 
 v1 阶段，如果你需要强制自动 hooks，请把 plugin 安装和 `do-it setup` 配套使用。
 当前本机 `codex features list` 显示 `codex_hooks=true`、`plugins=true`、
@@ -125,7 +125,7 @@ do-it doctor --target=claude
 ```
 
 Claude target 默认装到 `~/.claude/`；用 `CLAUDE_PLUGIN_ROOT_OVERRIDE` 改根目录。
-可选 skill（如 `do-it-visual-planning`）默认不装，加 `--with-optional` 才装。
+`--with-optional` 会安装 manifest 中标记为 optional 的 skill（0.11.0 没有 optional skill）。
 
 ## 它会安装什么
 
@@ -287,8 +287,7 @@ reasoning-effort 字段，Claude 生成的 agent 默认继承当前宿主模型
 `do_it_emit_context` 在没有 `jq` 时仍能输出合法 JSON。陈旧 session 目录会在
 7 天后清理。`do-it-router` 新增 `Integrity` 段 —— 失败是要追根因的线索,
 不是要掩盖的症状 —— 被 `do-it-debugging`、`do-it-fix-loop`、
-`do-it-verification-gate` 和子智能体派发合约引用。`do-it-visual-planning`
-新增 `plan-card` / `review-report` 场景模板,CI 测试任务现在也跑 macOS。
+`do-it-verification-gate` 和子智能体派发合约引用。CI 测试任务现在也跑 macOS。
 若某台机器缓存了 `0.8.0` 插件,请重装或刷新,让宿主加载新的 hook 和 skill。
 
 ## 升级到 0.8.0

diff --git a/commands/do-it-handbook.md b/commands/do-it-handbook.md
@@ -1,5 +1,5 @@
 ---
-description: 在当前项目里铺一份 .do-it/handbook/ 骨架（invariants / architecture / code-map / glossary / backlog / runtime-status / maintenance / task-card-template + 三个 workflow 文件），仅补齐缺失文件，不覆盖已有内容。
+description: 在当前项目里铺一份 .do-it/handbook/ 骨架（invariants / architecture / code-map / glossary / backlog / runtime-status），仅补齐缺失文件，不覆盖已有内容。
 ---
 
 # /do-it-handbook

diff --git a/docs/maintenance.md b/docs/maintenance.md
@@ -110,8 +110,8 @@ When a skill changes, decide which kind of update it is:
 - do-it rewrite
 - do-it compatibility adapter that preserves a workflow idea while changing the
   installed name and wording
-- optional auxiliary support, such as visual planning, that is installed but not
-  part of the default tier flow
+- optional auxiliary support that is installed but not part of the default tier
+  flow (no skills are marked optional in 0.11.0)
 
 For either kind:
 
@@ -259,8 +259,7 @@ surface generated from the same maintained manifest:
   `do-it` at `./plugins/do-it`.
 - `plugins/do-it/.codex-plugin/plugin.json` — plugin metadata with version
   parity to `package.json`.
-- `plugins/do-it/skills/` — generated from every `manifest.skills[]` entry,
-  including optional `do-it-visual-planning`.
+- `plugins/do-it/skills/` — generated from every `manifest.skills[]` entry.
 - `plugins/do-it/agents/` — generated from every `manifest.agents[]` entry.
 - `scripts/build-codex-plugin.mjs` — the only supported way to refresh the
   generated plugin bundle.

diff --git a/docs/routing-matrix.md b/docs/routing-matrix.md
@@ -130,16 +130,16 @@ rebuilds it from each `skills/do-it/<name>/SKILL.md` frontmatter and
 - `do-it-context`: maintains the project's canonical `.do-it/CONTEXT.md` —
   one-line definitions for terms, invariants, and relationships that
   downstream skills (grill, planning, review) read before debating semantics.
-- `do-it-grill-log`: writes the per-task `.do-it/grill/<task>.md` artifact
-  (`kind`, falsifier, status, evidence). Read by `do-it-planning` and
+  Its § Domain Glossary Mode stabilizes domain terms and catches contradictions
+  between user language, docs, and code.
+- `do-it-grill` § Grill Log Artifact: writes the per-task `.do-it/grill/<task>.md`
+  artifact (`kind`, falsifier, status, evidence). Read by `do-it-planning` and
   `do-it-verification-gate` so unresolved facts or execution-blocking
   decisions block closeout.
 - `do-it-architecture-scan`: checks ownership, dependency direction, coupling,
   migration path, rollout risk, and failure isolation.
 - `do-it-interface-drill`: checks API, type, schema, CLI, docs, protocol, and
   adapter contracts at the producer/consumer boundary.
-- `do-it-domain-language`: stabilizes domain terms and catches contradictions
-  between user language, docs, and code.
 - `do-it-tdd`, `do-it-debugging`, `do-it-review-loop`,
   `do-it-fix-loop`, and `do-it-verification-gate`: focused quality loops used
   when behavior, root cause, review findings, or completion claims require
@@ -148,8 +148,6 @@ rebuilds it from each `skills/do-it/<name>/SKILL.md` frontmatter and
   slices, ownership boundaries, and return schemas.
 - `do-it-worktree-isolation` and `do-it-branch-closeout`: optional support for
   isolated work and final integration.
-- `do-it-visual-planning`: optional local visual companion for planning
-  artifacts; it is not part of the default delivery route.
 
 The do-it roles absorb the useful discipline from the previous workflow family:
 mandatory truth checks, failure-mode forecasting, explicit planning, isolated
@@ -183,16 +181,16 @@ class: task` for a delegated slice, or `tier: Heavy, class: wave` for the parent
 coordinator. Do not use `wave` or `phase` as substitutes for `Standard` or
 `Heavy`.
 
-`do-it-domain-language`, `do-it-worktree-isolation`, `do-it-skill-authoring`,
-and `do-it-visual-planning` are routed by need rather than by tier:
+`do-it-worktree-isolation` and `do-it-skill-authoring` are routed by need rather
+than by tier:
 
-- use `do-it-domain-language` when overloaded terms, product concepts, or
-  business rules affect the plan or review;
 - use `do-it-worktree-isolation` when current workspace state, parallel lanes,
   or rollback risk requires isolation;
-- use `do-it-skill-authoring` when creating or updating skills;
-- use `do-it-visual-planning` only when a local visual planning companion would
-  improve a planning discussion.
+- use `do-it-skill-authoring` when creating or updating skills.
+
+Vocabulary work (overloaded terms, product concepts, business rules) routes to
+`do-it-context` § Domain Glossary Mode; visual comparison routes to
+`do-it-planning` § Visual Aids.
 
 ## Planning Rules
 
@@ -276,7 +274,7 @@ Use for `Heavy` work:
 2. Use `do-it-grill` to challenge the decision tree, failure-mode forecast, and path map before implementation.
 3. Use `do-it-slicing` to define lanes and shared-file ownership.
 4. Run `do-it-interface-drill`, `do-it-architecture-scan`, and
-   `do-it-domain-language` only where their evidence will change the plan.
+   `do-it-context` § Domain Glossary Mode only where their evidence will change the plan.
 5. Delegate Standard slices unless a child is explicitly assigned Heavy work.
 6. Run expanded review, fix-loop, re-review, and branch closeout.
 

diff --git a/docs/upstream-map.md b/docs/upstream-map.md
@@ -18,7 +18,7 @@ runtime-specific assumptions do not leak into new Codex installs.
 | `do-it-brainstorm` | requirement-shape discovery before grill | Absorbs multi-perspective divergence into a product + architecture core flow: product boundary, core goal, option tradeoffs, architecture foundation, extension modules, and explicit grill handoff. |
 | `do-it-architecture-scan` | architecture risk and opportunity scan | Absorbs codebase-improvement heuristics while keeping opportunities non-blocking unless correctness or delivery risk is real. |
 | `do-it-interface-drill` | interface and boundary design | Absorbs interface-design drills for APIs, schemas, CLIs, events, UI contracts, and agent handoffs. |
-| `do-it-domain-language` | canonical term and model alignment | Absorbs ubiquitous-language and domain-model discipline for overloaded terms, glossary updates, and contradictions between code/docs/user language. |
+| `do-it-context` § Domain Glossary Mode | canonical term and model alignment | Absorbs ubiquitous-language and domain-model discipline for overloaded terms, glossary updates, and contradictions between code/docs/user language. (Folded in from the former `do-it-domain-language` skill.) |
 | `do-it-tdd` | behavior-first RED/GREEN loop | Absorbs behavior-via-public-interface testing and one-test-at-a-time tracer-bullet TDD. |
 | `do-it-debugging` | root-cause investigation | Absorbs systematic debugging and issue triage: reproduce, trace, find root cause, then plan durable RED/GREEN fixes. |
 | `do-it-subagent-orchestration` | delegated slice protocol | Absorbs parallel-agent dispatch and subagent-driven development, but defaults child agents to Standard slices instead of inheriting Heavy parent flows. |
@@ -27,7 +27,7 @@ runtime-specific assumptions do not leak into new Codex installs.
 | `do-it-verification-gate` | evidence-before-claims closeout | Absorbs legacy verification discipline and makes success claims depend on fresh commands or explicit evidence. |
 | `do-it-worktree-isolation` | workspace isolation | Absorbs git-worktree setup and current-worktree safety into a do-it support skill. |
 | `do-it-branch-closeout` | branch/PR/merge finish | Absorbs development-branch finish checks, commit/PR evidence, and cleanup choices. |
-| `do-it-visual-planning` | optional planning companion | Absorbs the older visual brainstorming helper as an optional `.do-it/visual` support path, not a core workflow gate. Marked `optional: true` in `manifest.json` from 0.4.0; install with `--with-optional`. |
+| `do-it-planning` § Visual Aids | optional planning companion | Absorbs the older visual brainstorming helper as an optional `.do-it/visual` support path, not a core workflow gate. (Folded in from the former `do-it-visual-planning` skill; the browser companion was retired.) |
 | `do-it-skill-authoring` | skill creation and maintenance | Absorbs progressive-disclosure skill writing and repo-managed skill validation. |
 
 ## External Idea Map
@@ -45,8 +45,8 @@ The do-it skills are rewrites, not vendored copies. Useful ideas from
 | `improve-codebase-architecture` | `do-it-architecture-scan` | Friction-led exploration, shallow-module detection, deep-module candidates, coupling and testability impact. |
 | `tdd` | `do-it-tdd` | Public-interface behavior tests and one RED/GREEN vertical slice at a time. |
 | `triage-issue` | `do-it-debugging` | Manifestation, code path, root cause, minimal fix, and TDD fix plan. |
-| `qa` | `do-it-review-loop`, `do-it-domain-language` | User-facing durable issues, concise reproduction, and project domain language. |
-| `ubiquitous-language`, `domain-model` | `do-it-domain-language` | Canonical glossary, ambiguity flags, code/docs contradiction checks, and lightweight ADR triggers. |
+| `qa` | `do-it-review-loop`, `do-it-context` | User-facing durable issues, concise reproduction, and project domain language. |
+| `ubiquitous-language`, `domain-model` | `do-it-context` § Domain Glossary Mode | Canonical glossary, ambiguity flags, code/docs contradiction checks, and lightweight ADR triggers. |
 | `write-a-skill` | `do-it-skill-authoring` | Concise SKILL.md, progressive disclosure, optional resources, and validation. |
 
 Excluded or adapter-only ideas remain outside the core install flow unless a

diff --git a/hooks/anti-patterns-lint.sh b/hooks/anti-patterns-lint.sh
@@ -82,6 +82,14 @@ if ! command -v git >/dev/null 2>&1; then
 fi
 
 FILE_DIR="$(dirname "$FILE_PATH")"
+# Canonicalize the directory so it matches git's symlink-resolved
+# --show-toplevel output. On macOS the temp/working tree can sit under
+# /var -> /private/var (or /tmp -> /private/tmp); without this the REPO_ROOT
+# prefix strip below would fail, leaving REL_FILE absolute and REL_DIR collapsed
+# to ".", which breaks both the diff pathspec and the self-exclusion. pwd -P is
+# POSIX-portable; readlink -f is not (BSD lacks it).
+FILE_DIR="$(cd "$FILE_DIR" 2>/dev/null && pwd -P || printf '%s' "$FILE_DIR")"
+FILE_PATH="$FILE_DIR/$(basename "$FILE_PATH")"
 REPO_ROOT="$(git -C "$FILE_DIR" rev-parse --show-toplevel 2>/dev/null)"
 if [[ -z "$REPO_ROOT" ]]; then
   do_it_debug anti-patterns-lint "decision=skip reason=not-a-git-repo"
@@ -187,9 +195,11 @@ case "$FILE_PATH" in
       NO_CONSUMER_NAMES=""
       while IFS= read -r name; do
         [[ -z "$name" ]] && continue
-        # Search for any reference to `name` in other JS/TS files. Use a basic
-        # word-boundary regex; this catches `Name(`, `Name.`, ` Name `, etc.
-        REFS="$(_doit_timeout 5s git -C "$REPO_ROOT" grep -lE "\\b${name}\\b" \
+        # Search for any reference to `name` in other JS/TS files. Use git
+        # grep's own `-w` word match with `-F` fixed string — portable to BSD
+        # (macOS), unlike a GNU `\b` regex which BSD regcomp does not support.
+        # This still catches `Name(`, `Name.`, ` Name `, etc. at word boundaries.
+        REFS="$(_doit_timeout 5s git -C "$REPO_ROOT" grep -lwF -e "$name" \
           -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.mjs' '*.cjs' 2>/dev/null || true)"
         # Drop the current file from the result.
         REL_FILE="${FILE_PATH#"${REPO_ROOT}/"}"
@@ -305,6 +315,9 @@ fi
 
 PROJECT_ROOT="$(do_it_project_root "$CWD")"
 PROJECT_ROOT="${PROJECT_ROOT%/}"
+# FILE_PATH was symlink-resolved with pwd -P above; resolve PROJECT_ROOT the same
+# way so the display strip still works when CWD is a symlinked path (macOS).
+PROJECT_ROOT="$(cd "$PROJECT_ROOT" 2>/dev/null && pwd -P || printf '%s' "$PROJECT_ROOT")"
 case "$FILE_PATH" in
   "$PROJECT_ROOT"/*) DISPLAY_PATH="${FILE_PATH#"$PROJECT_ROOT"/}" ;;
   *) DISPLAY_PATH="$FILE_PATH" ;;

diff --git a/hooks/comments-lint.sh b/hooks/comments-lint.sh
@@ -253,9 +253,10 @@ if [[ "${FIX_HITS:-0}" -gt 0 ]]; then
   _record_family "fix-narrative"
 fi
 
-# 3. Task references
+# 3. Task references — external trackers plus do-it stage markers (phase /
+#    wave / backlog IDs) that rot a release or two after they are written.
 TASKREF_HITS=$(printf '%s\n' "$FILTERED" \
-  | grep -ciE 'issue #|pr #|ticket #|jira-' \
+  | grep -ciE 'issue #|pr #|ticket #|jira-|\bBL-[0-9]|\bphase[ -][0-9]|\bwave[ -][0-9]' \
   || true)
 if [[ "${TASKREF_HITS:-0}" -gt 0 ]]; then
   HITS=$((HITS + TASKREF_HITS))