fix: close round-2 plan-vs-implementation gaps (A, B, C)

Gap A — SessionStart Tier 1 missing PROJECT-TOC.md content
  hooks/session-start now extracts the ## Files section of PROJECT-TOC.md and
  injects it as a <project-toc> block between the <harness-anchor-state>
  block and the meta-skill body. Per plan §1, this restores the original
  Progressive Disclosure design: agents see a project index at session start
  without needing an explicit Read.

  Token budget rebalanced: banner kept full, then TOC truncated first if
  needed, then skill body. 200-char buffer reserved for truncation markers.
  Final safety cap re-applied. Verified: cmake fixture session yields a
  4018-char banner with TOC entries visible, well under 8000-char cap.

Gap B — Context7/WebSearch callouts missing from 9/11 skills
  Added a "Looking up …" subsection to each skill (cpp-build-systems,
  cpp-static-analysis, cpp-sanitizers, cpp-formatting, init-verification,
  anti-hallucination-gates, project-indexing, feature-state-keeper,
  context-budget-discipline) directing agents to Context7 first, WebSearch
  as fallback, for unfamiliar tool errors / check names / API references.
  using-harness-anchor adds a meta rule: "When stuck, search docs first."

Gap C — Skill descriptions exceeded plan §7 attention-table ≤150-char ideal
  Rewrote all 11 frontmatter descriptions, front-loading trigger keywords
  per learn-harness gotchas #12 (skill listing budget). Lengths now 129-150
  chars (was 181-281). validate-anchor.sh ≤500 check still passes.

Verification:
  validate-anchor.sh: 51/51 pass
  post-edit-warn contract test: 5/5 pass
  description length ≤150: all 11 OK
  Context7 coverage: 11/11 HAS
  SessionStart on CMake fixture: <project-toc> block present, entries visible

Skipped Gap D (.harness-anchor/last-error.log for index-builder crashes) —
rare failure path; stderr already captures errors; old TOC naturally preserved
when index-builder exits before write.

Author: Redtropig

hooks/session-start

@@ -134,34 +134,77 @@ banner="${banner}
 
 "
 
-# ---- 6. Read meta-skill body ----
+# ---- 6. Read PROJECT-TOC.md "## Files" section (Tier 1 navigation index) ----
+# Per plan §1: Tier 1 should include "PROJECT-TOC.md 前 N 行（每文件一行，N 动态调整使总和 < 上限）"
+toc_block=""
+toc_files_section=""
+if [ -f "$toc_file" ]; then
+    # Extract lines between "## Files" header and the next "## " header (or EOF).
+    toc_files_section=$(awk '/^## Files/{flag=1; next} /^## /{flag=0} flag' "$toc_file" 2>/dev/null || true)
+    # Strip leading/trailing blank lines
+    toc_files_section=$(printf '%s' "$toc_files_section" | awk 'NF{p=1} p' | awk 'BEGIN{lines=""} {lines=lines $0 "\n"} END{sub(/\n+$/, "", lines); print lines}')
+    if [ -n "$toc_files_section" ]; then
+        toc_block="<project-toc>
+${toc_files_section}
+</project-toc>
+
+"
+    fi
+fi
+
+# ---- 7. Read meta-skill body ----
 skill_content=""
 if [ -f "$SKILL_FILE" ]; then
     skill_content="$(cat "$SKILL_FILE")"
 else
     skill_content="(using-harness-anchor SKILL.md missing — plugin install incomplete)"
 fi
 
-# ---- 7. Combine + token budget hard cap (≤ ~2000 tokens ≈ 8000 chars) ----
-combined="${banner}${skill_content}"
+# ---- 8. Combine + token budget hard cap (≤ ~2000 tokens ≈ 8000 chars) ----
+# Priority for truncation: banner (always full) → skill body → toc head (drop first).
 MAX_CHARS=8000
+banner_len=${#banner}
+skill_len=${#skill_content}
+
+# Compute budget for TOC = remaining after banner + skill + 200-char buffer for markers
+toc_budget=$((MAX_CHARS - banner_len - skill_len - 200))
+
+if [ -n "$toc_block" ]; then
+    if [ "$toc_budget" -lt 250 ]; then
+        # Not enough room for meaningful TOC head; drop it.
+        toc_block=""
+    elif [ "${#toc_block}" -gt "$toc_budget" ]; then
+        # Truncate TOC content to fit budget; preserve block wrapper + add pointer.
+        truncated_files="${toc_files_section:0:$toc_budget}"
+        # Trim to last complete line so we don't cut mid-entry
+        truncated_files="${truncated_files%$'\n'*}"
+        toc_block="<project-toc>
+${truncated_files}
+<see PROJECT-TOC.md for full index>
+</project-toc>
+
+"
+    fi
+fi
+
+combined="${banner}${toc_block}${skill_content}"
+
+# Final safety: if skill body itself is enormous, truncate it.
 if [ "${#combined}" -gt "$MAX_CHARS" ]; then
-    # Banner is small and authoritative; truncate the skill body to fit.
-    banner_len=${#banner}
     marker="
 
 <truncated — see ${SKILL_FILE} for full content>"
     marker_len=${#marker}
-    skill_budget=$((MAX_CHARS - banner_len - marker_len))
-    if [ "$skill_budget" -lt 0 ]; then
-        # Banner alone exceeds budget — emit it raw, drop skill body.
-        combined="${combined:0:$MAX_CHARS}"
+    skill_budget=$((MAX_CHARS - banner_len - ${#toc_block} - marker_len))
+    if [ "$skill_budget" -gt 0 ]; then
+        combined="${banner}${toc_block}${skill_content:0:$skill_budget}${marker}"
     else
-        combined="${banner}${skill_content:0:$skill_budget}${marker}"
+        # Worst-case: even banner+TOC alone exceeds cap. Emit raw cap.
+        combined="${combined:0:$MAX_CHARS}"
     fi
 fi
 
-# ---- 8. JSON-escape (pure bash, no jq dependency) ----
+# ---- 9. JSON-escape (pure bash, no jq dependency) ----
 escape_for_json() {
     local s="$1"
     s="${s//\\/\\\\}"
@@ -174,7 +217,7 @@ escape_for_json() {
 
 context="$(escape_for_json "$combined")"
 
-# ---- 9. Emit Claude Code SessionStart JSON (silently injected as additionalContext) ----
+# ---- 10. Emit Claude Code SessionStart JSON (silently injected as additionalContext) ----
 printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$context"
 
 exit 0

skills/anti-hallucination-gates/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: anti-hallucination-gates
-description: Use before claiming a feature/fix/task is "done", "fixed", "complete", "working", "passing". Enforces Default-FAIL contract — every done criterion needs concrete evidence path. Express calibrated uncertainty when evidence is missing.
+description: Use before claiming "done", "fixed", "complete", "passing". Default-FAIL contract — every criterion needs evidence; express uncertainty if missing.
 ---
 
 # Anti-Hallucination Gates
@@ -104,6 +104,15 @@ If any box is unchecked: state uncertainty explicitly, do NOT flip status to `pa
 - You're about to say "the fix should work"
 - The PostToolUse hook injected warnings — do NOT silently ignore them; surface and address per `self-correction-loop`
 
+## Looking up evidence commands for unfamiliar frameworks
+
+When the project uses a test/lint framework you don't have committed to memory (Catch2, doctest, ruff, deno test, etc.):
+
+- **Context7** — fetch the framework's canonical CLI reference
+- **WebSearch** — "framework + test runner output format" usually surfaces what counts as evidence
+
+Bluffing the command and not actually running it is the anti-pattern this skill exists to prevent.
+
 ## Related
 
 - `feature-state-keeper` — actual writes to feature_list.json

skills/context-budget-discipline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: context-budget-discipline
-description: Use when sessions run long, when adding subagents, when the agent fetches large files, or when planning context-heavy work. Applies SELECT / WRITE / COMPRESS / ISOLATE operations from 2026 context engineering practice. Prevents lost-in-the-middle and reduces token cost.
+description: Use when sessions run long, adding subagents, fetching large files, or planning context-heavy work. SELECT/WRITE/COMPRESS/ISOLATE discipline.
 ---
 
 # Context Budget Discipline
@@ -88,6 +88,15 @@ You can roughly estimate context use by:
 
 When the user asks "how much room do we have?", be honest about the estimate.
 
+## Looking up context engineering research
+
+For specific patterns (e.g., compaction algorithms, attention windowing, RAG indexing strategies):
+
+- **Context7** — Anthropic / OpenAI engineering blog references on harnesses
+- **WebSearch** — "context engineering 2026" surfaces recent practitioner reports
+
+Pattern names evolve fast in this area; don't rely on memory.
+
 ## Related
 
 - `using-harness-anchor` — Tier 1 injection budget reference

skills/cpp-build-systems/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cpp-build-systems
-description: Use in C/C++ projects when configuring builds, fixing build/configure errors, generating compile_commands.json, or selecting CMake/Meson/Make/Bazel commands. Always export compile_commands.json — it's required for static analysis and language tooling.
+description: Use in C/C++ projects for build configure/errors, compile_commands.json generation, or selecting CMake/Meson/Make/Bazel commands.
 ---
 
 # C/C++ Build Systems
@@ -111,3 +111,12 @@ Run `bash ${CLAUDE_PLUGIN_ROOT}/scripts/cpp-detect.sh --target .` to get a JSON
 If you propose a build fix you haven't verified by running the build:
 
 > "I believe the fix is `<change>`. Please run `cmake -S . -B .build && cmake --build .build` and share the output before we mark this resolved."
+
+## Looking up tool errors
+
+Unfamiliar CMake/Meson/Bazel error or missing-package message? Don't guess:
+
+- **Context7** — query `cmake docs`, `meson docs`, `bazel docs` for canonical reference (structured, reliable)
+- **WebSearch** — the exact error string often surfaces a Stack Overflow / GitHub issue with the fix (fallback)
+
+Prefer Context7 first; only fall back to WebSearch for recent ecosystem changes.

skills/cpp-formatting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cpp-formatting
-description: Use in C/C++ projects to apply clang-format consistently. Run on changed lines only, never reformat unchanged code mid-feature. Use .clang-format from project root or LLVM baseline.
+description: Use in C/C++ projects for clang-format. Changed-lines-only; never reformat unchanged code mid-feature. .clang-format from root or LLVM baseline.
 ---
 
 # C/C++ Formatting (clang-format)
@@ -74,3 +74,12 @@ git diff --stat   # should show only changed lines' format
 ```
 
 If clang-format touched files you didn't change, your `.clang-format` may have drifted between machines (different versions produce different output). Pin clang-format major version in CI.
+
+## Looking up clang-format options
+
+For an unfamiliar `.clang-format` key (e.g. `PenaltyExcessCharacter`, `BreakInheritanceList`):
+
+- **Context7** — fetch the official clang-format options reference
+- **WebSearch** — search "clang-format <option-name>" for usage examples
+
+Prefer Context7 for canonical documentation.

skills/cpp-sanitizers/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cpp-sanitizers
-description: Use in C/C++ projects when debugging crashes, hangs, undefined behavior, data races, or memory errors. ASan/UBSan/TSan are runtime checkers — they catch what static analysis misses. Build sanitizer config separately; don't mix with release config.
+description: Use in C/C++ projects for crashes, hangs, UB, data races, memory errors. ASan/UBSan/TSan runtime checks. Build sanitizer config separately.
 ---
 
 # C/C++ Sanitizers — Runtime Bug Catchers
@@ -104,3 +104,12 @@ Run: `ASAN_OPTIONS=suppressions=asan-suppressions.txt ./your_test`
 - Before any release / merge to main → run full ASan+UBSan suite
 
 ## See `ub-failure-patterns.md` for common UBSan signatures and their fixes.
+
+## Looking up unfamiliar signatures
+
+When a sanitizer report uses an error class outside `ub-failure-patterns.md`:
+
+- **Context7** — query `clang sanitizers` or `address sanitizer` for canonical docs
+- **WebSearch** — search the exact error string for community reports
+
+Prefer Context7; WebSearch is best for recent regressions or platform-specific issues.

skills/cpp-static-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cpp-static-analysis
-description: Use in C/C++ projects when reviewing changed code, before claiming a feature done, or when investigating bugs. Runs clang-tidy / cppcheck / include-what-you-use (IWYU). Requires compile_commands.json. Surface warnings on changed lines only — don't dump the world.
+description: Use in C/C++ projects when reviewing changes or hunting bugs. Runs clang-tidy/cppcheck/IWYU. Needs compile_commands.json. Changed lines only.
 ---
 
 # C/C++ Static Analysis
@@ -100,6 +100,15 @@ If a warning is wrong (false positive), file a one-line `// NOLINT(check-name) 
 
 If a warning is in code you didn't change (legacy area) and not a regression risk, defer it: note in `progress.md`, don't fix in this session. Scope discipline.
 
+## Looking up unfamiliar checks
+
+When you encounter a clang-tidy check name you don't recognize (e.g. `bugprone-suspicious-enum-usage`, `cert-err58-cpp`):
+
+- **Context7** — fetch canonical clang-tidy check documentation
+- **WebSearch** — search "clang-tidy <check-name>" for discussions on false positives / edge cases
+
+Same for cppcheck IDs and IWYU pragmas. Prefer Context7; WebSearch as fallback.
+
 ## Templates
 
 - `.clang-tidy` baseline config: `templates/cpp/.clang-tidy.tpl` (copied by `/cpp-init`)

skills/feature-state-keeper/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feature-state-keeper
-description: Use when starting, advancing, finishing, or blocking a feature. Manages feature_list.json scope record and progress.md/session-handoff.md state files. Enforces Default-FAIL: status='pass' requires non-null evidence.
+description: Use when starting, advancing, finishing, or blocking a feature. Manages feature_list.json + progress.md + session-handoff.md. Default-FAIL enforced.
 ---
 
 # Feature State Keeper
@@ -112,6 +112,15 @@ Aim for ≤ 300 words. The next session should be able to resume from this alone
 
 If the schema file is present, an external validator (e.g. `ajv-cli`) can verify. The agent need not run it — write valid JSON the first time by following the shape above.
 
+## Looking up JSON Schema constraints
+
+For non-trivial schema constructs (`allOf`, `oneOf`, `if/then`, regex patterns):
+
+- **Context7** — `json schema` for the canonical draft-07 / draft-2020-12 spec
+- **WebSearch** — specific keyword + "json schema" for examples
+
+Don't guess schema syntax — `feature_list.schema.json` validation must stay correct.
+
 ## Related
 
 - For evidence-gathering procedure → `anti-hallucination-gates` skill

skills/init-verification/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: init-verification
-description: Use at the start of work in a project, after any environment change (deps, branch switch, OS update), or when something "used to work" stops working. Runs init.sh health check; treats failures as blocking. Implements Anthropic's "verify environment before agent does work" pattern.
+description: Use at start of work, after env changes (deps/branch/OS), or when something stops working. Runs init.sh health check; treats failures as blocking.
 ---
 
 # Init Verification
@@ -77,6 +77,15 @@ When it fails, list the specific failed step, not "init failed" alone.
 - Inside a subagent that was already given verified-healthy context
 - For trivial single-file edits where build/test aren't needed (rare; usually init still cheap enough to run)
 
+## Looking up toolchain errors
+
+When `init.sh` fails with a cryptic toolchain message (e.g., CMake "could not find compiler", npm `ENOENT`, cargo "linker not found"):
+
+- **Context7** — fetch the tool's canonical docs (`cmake docs`, `npm docs`, `cargo book`)
+- **WebSearch** — the exact error string usually surfaces a known fix
+
+Prefer Context7 for stable behavior; WebSearch for recent platform-specific changes.
+
 ## Related
 
 - `/anchor` — scaffolds the initial `init.sh`

skills/project-indexing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-indexing
-description: Use when locating files, understanding project structure, or before reaching for Glob/find. Consults PROJECT-TOC.md (one-line index of every git-tracked file). Detects staleness via git commit anchor.
+description: Use when locating files or understanding structure. Consults PROJECT-TOC.md (one-line index per file). Staleness via git commit anchor.
 ---
 
 # Project Indexing
@@ -73,6 +73,15 @@ The `## Decisions` section is human-edited (long-lived architectural notes). The
 
 `PROJECT-TOC.md` typically fits within a few thousand tokens even for medium projects. The SessionStart hook injects **only the first N lines** that fit the Tier 1 budget; the rest is read on demand. Don't ask the user to load the full TOC unless the budget allows.
 
+## Looking up indexing techniques
+
+For deeper context-engineering / progressive-disclosure indexing approaches not covered here:
+
+- **Context7** — search "progressive disclosure llm agent" for harness research
+- **WebSearch** — recent agent harness blog posts and patterns
+
+The current TOC algorithm is intentionally minimal; refinements (semantic chunks, embeddings) belong in a separate skill.
+
 ## Related
 
 - `using-harness-anchor` — overall navigation, points here when files are sought