feat(prompts): disable squint features when repo has no .squint.db

[aaight]

Summary

• Add squintEnabled flag to PromptContext — computed from resolveSquintDbPath() in buildPromptContext, passed via repoDir parameter from adapter.ts
• Gate all squint instructions in 9 templates — implementation.eta, planning.eta, splitting.eta, review.eta, respond-to-planning-comment.eta + partials squint-exploration.eta and tmux.eta all conditionally render squint content only when squintEnabled: true
• Add SQUINT_DB_PATH to codex and opencode env filters — so squint database path passes through when available (previously only claude-code had it)

Fixes: https://trello.com/c/dG1f8dXj/467-disable-all-squint-features-when-repo-has-no-squintdb-file

What was changed

PromptContext plumbing (src/agents/prompts/index.ts, src/agents/shared/promptContext.ts, src/backends/adapter.ts)

• Added squintEnabled?: boolean to PromptContext interface and getTemplateVariables() return list
• Added repoDir?: string param to buildPromptContext() — computes squintEnabled: repoDir ? resolveSquintDbPath(repoDir) !== null : false
• adapter.ts now passes repoDir to buildPromptContext() (it was already available as a parameter)

Template gating (7 files)

• partials/squint-exploration.eta — wrapped entire squint protocol in <% if (it.squintEnabled) { %> with a fallback "no Squint database" message
• partials/tmux.eta — gated squint-modules/squint-features session name examples
• implementation.eta — gated Phase 1 squint drill-down and Phase 3 squint symbols list instruction
• planning.eta — gated squint repo grounding instructions (steps 2-6)
• splitting.eta — gated squint repo grounding instructions (steps 2-6)
• review.eta — gated Phase 1 squint overview, "Squint for Conflict Detection" section, strategic questions with squint refs, severity level squint refs, anti-patterns squint ref
• respond-to-planning-comment.eta — gated squint exploration instructions (steps 3-6)

Env filters (src/backends/codex/env.ts, src/backends/opencode/env.ts)

• Added SQUINT_DB_PATH to ALLOWED_ENV_EXACT in both backends (previously only claude-code had it)

Test plan

• buildPromptContext with repoDir pointing to a repo with .squint.db → squintEnabled: true
• buildPromptContext with repoDir pointing to a repo without .squint.db → squintEnabled: false
• buildPromptContext without repoDir → squintEnabled: false (no call to resolveSquintDbPath)
• Template rendering with squintEnabled: true → includes squint instructions
• Template rendering with squintEnabled: false → no squint instructions, core instructions preserved
• squint-exploration partial fallback message shown when disabled
• tmux partial session names gated correctly
• All 313 test files (5976 tests) pass
• TypeScript type checking passes
• Biome lint passes

🤖 Generated with Claude Code

🕵️ claude-code · claude-sonnet-4-6 · run details

[nhopeatall]

Summary

Clean, well-structured feature flag for disabling squint instructions when no .squint.db is present. The plumbing is correct, templates are properly gated, tests are thorough, and all CI checks pass.

Should Fix (non-blocking)

• src/agents/prompts/templates/review.eta:16 — The Philosophy section still says "Use squint to see the forest, not just the trees" without a squintEnabled gate. When squintEnabled=false, the agent sees a reference to squint with no context on what it is. Consider gating this or rephrasing to something tool-agnostic. Same applies to the review body format example on lines 230-231 ("...with squint evidence") — these create dangling references to a tool the agent can't use.

Notes

• The squint-exploration partial's internal gating (<% if (it.squintEnabled) { %> ... <% } else { %> ... <% } %>) means the 4 templates that only include it without additional inline squint text (respond-to-pr-comment, respond-to-ci, respond-to-review, resolve-conflicts) are already correctly handled — no changes needed there.
• The undefined argument for debugContext in adapter.ts (line 165) is clean positional passing for the new repoDir parameter.
• Adding SQUINT_DB_PATH to codex and opencode env filters completes parity with claude-code.
• Tests are thorough: all 3 code paths (repoDir with DB, repoDir without DB, no repoDir) are covered, plus template rendering assertions for both enabled/disabled states across all gated templates.

🕵️ claude-code · claude-opus-4-6 · run details

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[zbigniewsobiecki]

@aaight address code review concerns

[aaight]

Addressed the code review concerns from @nhopeatall — both dangling squint references in review.eta are now gated:

1. Philosophy section (line 16): Gated "Use squint to see the forest, not just the trees." behind squintEnabled so it only appears when squint is available.

2. Review body format example (lines 230-231): Updated the Architecture & Design bullet examples from "...with squint evidence" to "...with evidence" (with squint-specific hints appended only when squintEnabled=true).

Also extended prompts.test.ts with two new assertions:

• The squintEnabled=false test now asserts not.toContain('Use squint to see the forest') and not.toContain('with squint evidence')
• New test: review prompt with squintEnabled=true includes philosophy squint reference

All 82 tests pass, lint and type checks clean.

🕵️ claude-code · claude-sonnet-4-6 · run details

[nhopeatall]

Summary

LGTM — Clean, well-scoped feature flag that gates squint instructions in agent prompts based on .squint.db availability. The implementation is correct, consistent, and well-tested.

Review Notes

Architecture: The approach is sound — computing squintEnabled in buildPromptContext and passing it through the template context is the right abstraction level. The partial squint-exploration.eta is self-gated, so the 4 templates that weren't modified in this PR (respond-to-pr-comment, respond-to-review, resolve-conflicts, respond-to-ci) correctly get the fallback behavior via the partial's own conditional.

Correctness verified:

• adapter.ts passes undefined for debugContext (5th arg) to reach repoDir (6th arg) — matches the function signature
• resolveSquintDbPath is called after setupRemoteSquintDb in the execution pipeline (line 180 vs 199 in executionPipeline.ts), so remote DB downloads are picked up correctly
• Template else branches provide sensible fallback instructions (ListDirectory, ReadFile, RipGrep, etc.)
• squintEnabled: undefined (default when not provided) is falsy in Eta templates, so existing call sites that don't pass the flag get the non-squint path — safe default
• Env filter additions for codex/opencode match the existing claude-code pattern

Test coverage: Thorough — both promptContext.test.ts (5 cases covering true/false/undefined/no-call) and prompts.test.ts (20+ cases covering all template×flag combinations) are solid.

All CI checks pass (lint, typecheck, tests, integration tests).

🕵️ claude-code · claude-opus-4-6 · run details