feat: strengthen Company Brain context bridge

[100yenadmin]

Summary

• resolves configured Company Brain account IDs through the account-list path instead of fabricating local context
• skips context injection when account resolution does not match the configured stable ID
• surfaces open follow-ups in the distinct <company-brain-context> block
• preserves citations, insufficient-evidence states, approval metadata, readiness, verification status, and visibility scope
• keeps Company Brain separate from generic memory injection

Validation

• npm test
• npm run build

Closes #31
Refs electricsheephq/electric-sheep#2029

Summary by CodeRabbit

• Documentation

  • Clarified Company Brain behavior: account resolution follows Company Brain path when auto-mode is enabled
  • Updated context injection documentation with account scoping details
  • Refined context formatting documentation including follow-ups and Action safety sections

• New Features

  • Company Brain context now surfaces open follow-ups in a dedicated section

• Tests

  • Added coverage for account resolution verification

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR enhances Company Brain account resolution and context formatting by exporting a reusable account-resolution function, refactoring the context resolver to use it, and extending context formatting to include aggregated follow-up records. Documentation and tests validate the new behavior.

Changes

Company Brain Account Resolution and Context Formatting

Layer / File(s)	Summary
Account Resolution Type and New Function src/index.ts	Export CompanyBrainResolvedAccount interface and introduce resolveCompanyBrainAccountFromAccountsList(...) to resolve a single unambiguous account from Company Brain accounts-list results, returning null when zero or ambiguous candidates are found.
Context Resolver Refactoring and Follow-ups Integration src/index.ts	Refactor resolveCompanyBrainAccountForContext to delegate account resolution to the new helper and change the resolution payload structure. Add helper functions to collect and aggregate follow-up records from brief, actionReadiness, and sections; update appendJsonSection to skip empty arrays.
Unit Test Coverage for Account Resolution and Format src/__tests__/company-brain-context-format.test.ts	Import the new resolution function, add unit tests verifying successful and failed account resolution cases, and update formatCompanyBrainContext output assertions to require the new "Open follow-ups:" section.
Documentation of Account Resolution and Context Formatting README.md, docs/company-brain-tools.md	Clarify that account resolution follows the Company Brain path even when a stable account ID is configured. Document the accounts-list-based resolution, follow-ups section rendering, and action-safety summaries in the injected context block.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• electricsheephq/evaos-cortex-plugin#29: Both PRs involve Company Brain context injection safety and account-resolution logic in src/index.ts, particularly the ambiguity handling and approval-gated action rendering as read-only "action safety" sections with follow-up context.

Poem

🐰 A rabbit hops through Company Brain,
Resolving accounts down the clear lane,
Follow-ups gathered, context precise,
Account safety checks—let's roll the dice!
One path, one truth, approval gated right. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main feature: strengthening the Company Brain context bridge by resolving accounts via account-list path and properly surfacing follow-ups.
Linked Issues check	✅ Passed	The PR successfully implements all coding requirements from issue #31: resolves accounts via account-list path, injects distinct company-brain-context block, preserves citations/metadata/follow-ups, and avoids flattening into generic memory.
Out of Scope Changes check	✅ Passed	All changes align with the stated objectives: documentation clarifications, exported types/functions for account resolution, test coverage for new logic, and context formatting enhancements are all directly within scope.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 codex/company-brain-customer-zero

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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

[coderabbitai]

🧹 Nitpick comments (1)

src/__tests__/company-brain-context-format.test.ts (1)

26-62: ⚡ Quick win

Consider adding a test case for multiple matching accounts.

The stack outline specifies that the function "returns a resolved account object only when exactly one unambiguous candidate exists; returns null otherwise." The current tests cover successful single-match resolution and not-found scenarios, but don't verify the ambiguous case where multiple accounts could match.

✅ Suggested test case for multiple matches

Add a test block after line 62:

{
  const resolved = resolveCompanyBrainAccountFromAccountsList(
    {
      accounts: [
        { id: "acct_acme", name: "Acme Clinic", visibility_scope: "account" },
        { id: "acct_acme_2", name: "Acme Clinic East", visibility_scope: "account" },
      ],
      total: 2,
    },
    {
      configuredAccountId: "acct_acme",
      search: "acct_acme",
    },
  );

  assert.equal(resolved, null, "Should return null when multiple candidates exist");
}

🤖 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/__tests__/company-brain-context-format.test.ts` around lines 26 - 62, Add
a test that verifies resolveCompanyBrainAccountFromAccountsList returns null
when more than one account matches the search (ambiguous case): call
resolveCompanyBrainAccountFromAccountsList with an accounts array containing two
matching entries (e.g., "acct_acme" and "acct_acme_2" both with visibility_scope
"account"), keep configuredAccountId/search set to "acct_acme", and assert the
result is null to ensure the function treats multiple candidates as ambiguous.

🤖 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.

Nitpick comments:
In `@src/__tests__/company-brain-context-format.test.ts`:
- Around line 26-62: Add a test that verifies
resolveCompanyBrainAccountFromAccountsList returns null when more than one
account matches the search (ambiguous case): call
resolveCompanyBrainAccountFromAccountsList with an accounts array containing two
matching entries (e.g., "acct_acme" and "acct_acme_2" both with visibility_scope
"account"), keep configuredAccountId/search set to "acct_acme", and assert the
result is null to ensure the function treats multiple candidates as ambiguous.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9248a979-e529-41a1-8291-75f884160dd1

📥 Commits

Reviewing files that changed from the base of the PR and between 77a59a0 and 2753143.

⛔ Files ignored due to path filters (6)

• dist/__tests__/company-brain-context-format.test.js is excluded by !**/dist/**
• dist/__tests__/company-brain-context-format.test.js.map is excluded by !**/dist/**, !**/*.map
• dist/index.d.ts is excluded by !**/dist/**
• dist/index.d.ts.map is excluded by !**/dist/**, !**/*.map
• dist/index.js is excluded by !**/dist/**
• dist/index.js.map is excluded by !**/dist/**, !**/*.map

📒 Files selected for processing (4)

• README.md
• docs/company-brain-tools.md
• src/__tests__/company-brain-context-format.test.ts
• src/index.ts