advisor: soft checkpoints + onboarding hint (#236)

[uta2000]

Summary

Integrates the Claude advisor tool (beta advisor-tool-2026-03-01) into feature-flow as a complement to codex-consultation (#235). Closes #236.

Two additive changes:

1. Four soft advisor-call hints in judgment-heavy skills (design-verification, verify-acceptance-criteria, and two in consult-codex). Non-blocking — Claude decides per-invocation whether to call advisor().
2. Onboarding/settings hint — new hooks/scripts/advisor-hint.js SessionStart script nudges Sonnet users (rate-limited to once/day, permanently dismissible) to enable the advisor beta header. Full docs at docs/advisor.md; one-paragraph pointer in README. New feature-flow:settings advisor [dismiss] sub-action.

Deferred: tiered stuck-mode machinery and per-call observability — advisor runs as a server-side sub-inference with no hook-visible surface today.

Design Doc

Issue #236 is the authoritative design. docs/plans/2026-04-17-advisor-integration.md is a thin pointer to it; docs/plans/2026-04-17-advisor-integration-plan.md is the 15-task implementation plan.

Scope

• 4 SKILL.md one-liner inserts (design-verification, verify-acceptance-criteria, consult-codex ×2)
• 2 new JS scripts (skills/settings/scripts/advisor-headers.js, skills/settings/scripts/check-advisor.js) + 1 new hook script (hooks/scripts/advisor-hint.js) + 2 colocated test suites
• 1 new third entry in the existing hooks/hooks.json SessionStart array (no new hook event type)
• 1 new `advisor` sub-action handler in `skills/settings/SKILL.md`
• 1 new docs/advisor.md (4 required sections: What it is / How to enable / When it's worth it / Relationship to codex-consultation)
• README "Optional Enhancements / Advisor Tool" section
• .feature-flow.yml commented defaults for `advisor.enabled` + `hints.advisor.dismissed`
• ## Relationship to advisor tool section appended to docs/plans/2026-04-14-codex-consultation.md

Review Iteration

An initial code-review pass (pr-review-toolkit) flagged four findings — all addressed in commit refactor(advisor): address code-review findings:

1. Critical — test hermeticity: test run() helpers now delete XDG_CONFIG_HOME and APPDATA to prevent the developer's real settings.json from bleeding through on Linux/Windows.
2. Important — Sonnet gate: advisor-hint.js now calls detectSonnet() as Condition 5. Fails open (eligible) when CLAUDE_MODEL unset; suppresses hint for non-Sonnet models.
3. Important — YAML regex over-capture: replaced unbounded regex with an indentation-aware line-by-line parser (parseHintsAdvisorDismissed) to prevent false matches from sibling hints.* blocks with a dismissed field.
4. Important — duplication: advisor-hint.js now imports detection helpers from check-advisor.js (~30 fewer lines duplicated).

Test Plan

• node hooks/scripts/advisor-hint.test.js — 13 passing (was 11; +2 Sonnet-gate tests)
• node skills/settings/scripts/check-advisor.test.js — 14 passing (was 12; +2 sibling-regex tests)
• node hooks/scripts/version-check.test.js — 29 passing (baseline unchanged)
• node hooks/scripts/verdict-gate.test.js — 10 passing (baseline unchanged)
• All 11 ACs from issue advisor: tiered stuck mode + soft checkpoints + settings hint #236 verified via grep/file checks (see plan Task 15)
• Manual smoke: enable advisor beta header in ~/.claude/settings.json, confirm hint disappears
• Manual smoke: run feature-flow:settings advisor dismiss, confirm hints.advisor.dismissed: true is written and next SessionStart produces no hint output
• Manual smoke: verify advisor-hint.js silently exits 0 when `~/.feature-flow/` can't be written (e.g. readonly HOME)

Acceptance Criteria Status

All 11 ACs PASS. See docs/plans/2026-04-17-advisor-integration-plan.md Task 15 for the verification script.

Closes #236

🤖 Generated with Claude Code

[uta2000]

Manual smoke tests executed (2026-04-17) — all three PASS:

1. advisor beta header suppresses hint ✅

   • Without header → hint shown
   • With ANTHROPIC_BETA containing advisor-tool-2026-03-01 → no output (stdout + stderr empty)

2. dismiss flow suppresses hint ✅

   • Before dismiss (advisor.enabled: true, no hints block) → hint shown
   • After setting hints.advisor.dismissed: true → no output
   • Bonus: rate-limiter state file NOT written when hint is suppressed by dismiss (the hook short-circuits before markShownToday)

3. readonly HOME → silent exit 0 ✅

   • Set HOME to a chmod 555 tmpdir where ~/.feature-flow/hint-state.json cannot be written
   • Hook exits 0
   • stderr is empty (no error traces, no 'hook error' messages)
   • Hint still fires on stdout (correct — rate-limiter write failure is designed to be silent)

All test-plan checkboxes can now be checked. No blockers for merge.