fix: engram rule text assumed a fixed access path

[getappz]

Summary

• rule_text::ENGRAM told agents to "use engram MCP tools" with no acknowledgment that engram can be reached two different ways depending on setup: as a native plugin (mcp__engram__*) or, when that's disabled to avoid duplicating agentflare's own gateway-registry, only via gateway_search(query) -> gateway_execute(server="engram", ...)
• This caused a real session to conclude engram was unavailable (searched for mcp__engram__* directly, found nothing, gave up) when it was actually reachable through the gateway the whole time
• Rewrote the rule text to teach intent-first discovery generally, not just for engram

Why the refresh path

• components.rs's rules component only ever writes a rule file when absent (never overwrites) — so machines that already installed the old engram.md would keep the stale, misleading text forever, even after this fix ships
• Added confirm_rule_refresh in init.rs, same consent pattern as the existing confirm_ponytail_migration: only offers to refresh a rule file whose on-disk content matches a known old version verbatim (via a new rule_text::superseded() lookup) — anything that diverges for any other reason is left alone, since that's most likely a user edit
• Wired into init::run() right after check_competing_plugins

Test plan

• cargo test — 213 passed, including 6 new tests covering is_stale_rule (superseded / current / user-edited / no-superseded-version cases) and confirm_rule_refresh (refreshes stale, leaves user edits alone)
• cargo build — clean, no new warnings

Summary by CodeRabbit

• New Features

  • Initialization now checks for outdated rule files and can refresh them to the latest version.
  • Rule guidance content has been expanded and reformatted for clearer reading.

• Bug Fixes

  • Preserves user-edited rule files instead of overwriting custom changes during setup.
  • Skips updating files that are already current, reducing unnecessary prompts and writes.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR replaces single-line rule text constants with multi-line versions and adds SUPERSEDED variants plus a superseded(filename) lookup function in rule_text.rs. rule_targets becomes crate-visible. init.rs gains stale-rule detection and a confirm/refresh step wired into the init flow, with new tests.

Changes

Rule text refresh on init

Layer / File(s)	Summary
Rule text constants and superseded lookup src/rule_text.rs	EXA, GIT, LEANCTX, and ENGRAM become multi-line raw strings; new *_SUPERSEDED arrays and a superseded(filename) function map rule filenames to prior wording.
Crate-visible rule targets src/components.rs	rule_targets visibility changes from private to pub(crate) so init.rs can use it.
Stale rule detection and refresh flow src/init.rs	Adds is_stale_rule, prompt_yes, and confirm_rule_refresh helpers to detect stale rule files, prompt for consent, and overwrite them; wired into run(agent, yes) after plugin conflict checks; includes new tests.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant InitRun as init::run
  participant RuleRefresh as confirm_rule_refresh
  participant RuleText as rule_text::superseded
  participant FileSystem

  User->>InitRun: agentflare init
  InitRun->>RuleRefresh: confirm_rule_refresh(agent, yes)
  RuleRefresh->>FileSystem: read rule file content
  RuleRefresh->>RuleText: superseded(filename)
  RuleText-->>RuleRefresh: superseded text array
  RuleRefresh->>RuleRefresh: is_stale_rule(content, superseded)
  RuleRefresh->>User: prompt Y/n (if not yes)
  User-->>RuleRefresh: confirm
  RuleRefresh->>FileSystem: overwrite rule file with current text
  RuleRefresh-->>InitRun: continue to component checks

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change to ENGRAM rule text.
Description check	✅ Passed	The description covers the summary, rationale, and test plan, but it omits the template's Notes for reviewers section.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/engram-rule-gateway-discovery

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/init.rs`:
- Around line 142-160: The prompt handling in prompt_yes currently writes
without flushing and treats stdin read errors as empty input, which can
incorrectly return true. Update prompt_yes to flush stdout immediately after
print!("{message}") by bringing std::io::Write into scope, and make the
read_line error path fail closed by returning false (with the skipped message)
instead of falling through to the "" match arm.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 5b56d23c-4df1-4259-b143-8a4193ced8de

📥 Commits

Reviewing files that changed from the base of the PR and between 53d3602 and 1f27027.

📒 Files selected for processing (3)

• src/components.rs
• src/init.rs
• src/rule_text.rs

[coderabbitai]

🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
rg -nP 'use\s+std::io' src/init.rs

Repository: getappz/agentflare

Length of output: 156

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '== src/init.rs outline ==\n'
ast-grep outline src/init.rs --view expanded || true

printf '\n== imports and prompt_yes region ==\n'
cat -n src/init.rs | sed -n '1,220p'

Repository: getappz/agentflare

Length of output: 11434

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '== flush usage in repo ==\n'
rg -n 'stdout\(\)\.flush|flush\(\)' src . || true

printf '\n== std::io::Write imports in repo ==\n'
rg -n 'use\s+std::io::Write|use\s+std::io::.*Write' src || true

printf '\n== prompt-like helpers around init.rs ==\n'
cat -n src/init.rs | sed -n '1,90p'

Repository: getappz/agentflare

Length of output: 4443

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

python3 - <<'PY'
from pathlib import Path
text = Path('src/init.rs').read_text()
start = text.index('fn prompt_yes')
end = text.index('fn confirm_rule_refresh')
snippet = text[start:end]
print(snippet)
print("HAS_STD_IO_WRITE_IMPORT:", 'use std::io::Write' in text or 'use std::io::{Write' in text)
print("HAS_FLUSH_CALL:", '.flush()' in text)
PY

Repository: getappz/agentflare

Length of output: 1159

---

Flush the prompt and fail closed on stdin errors print!("{message}") needs an explicit flush before read_line, and a read error should return false instead of falling through to the empty-input true branch. Add use std::io::Write; if you wire in flush().

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/init.rs` around lines 142 - 160, The prompt handling in prompt_yes
currently writes without flushing and treats stdin read errors as empty input,
which can incorrectly return true. Update prompt_yes to flush stdout immediately
after print!("{message}") by bringing std::io::Write into scope, and make the
read_line error path fail closed by returning false (with the skipped message)
instead of falling through to the "" match arm.