docs(claude): the tenant guard shipped — stop saying nothing catches it (#1355)

[alfredo1996]

What

CLAUDE.md:131 still read:

a forgotten filter is a cross-tenant leak that nothing catches. Adding a guard is tracked in #1226.

The guard shipped in #1351.

That's worse than an ordinary stale doc, because CLAUDE.md is loaded as ground truth by every agent session — and the claim is false in a direction that changes behaviour. An agent reading it either duplicates the guard or reasons more defensively than the code requires.

What I deliberately did NOT do

Soften the mandate. The first two clauses stay verbatim: there is genuinely no ORM- or middleware-level enforcement, and the filter must still be written per query, in the route.

The ratchet is a test-time safety net, not runtime enforcement. Rewriting this to imply the problem is solved would be worse than leaving it stale — an agent that believes the ORM scopes queries will write an unscoped one. The new wording says both things explicitly.

The guard

Pinned by path, not by phrasing, in the existing docs-accuracy.test.ts (the suite that already guards CLAUDE.md, from #1235). So a future rewrite is free to reword but not to drop the pointer — and it asserts the path exists, so renaming the test without updating the doc fails too.

It also pins the two load-bearing phrases, which is the less obvious half: the risk here isn't only that the reference goes stale, it's that someone "tidies" the caveat away.

Proven in both directions:

drop the path reference             -> FAIL
soften "not runtime enforcement"    -> FAIL
baseline                            -> 8 passed

Closes #1355

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Updated multi-tenancy guidance to reference test-time tenant-scope enforcement.
  • Clarified that tenant filtering remains required for each database query and is not enforced at runtime.

• Tests

  • Added documentation-accuracy checks to verify the tenant-scope test reference, file existence, and required guidance wording.

[coderabbitai]

Walkthrough

Updates multi-tenancy guidance to reference the shipped tenant-scope test and adds documentation-accuracy checks for its path, existence, and required wording.

Changes

Tenant documentation accuracy

Layer / File(s)	Summary
Tenant guidance and accuracy validation CLAUDE.md, app/src/lib/__tests__/docs-accuracy.test.ts	Multi-tenancy guidance now describes the test-time ratchet, while tests validate the canonical tenant-scope test path and required per-query and non-runtime-enforcement phrasing.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• alfredo1996/neoboard#1238: Updates related multi-tenancy documentation and documentation-drift validation.

Suggested labels: documentation

Suggested reviewers: alfredorubin96

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	❓ Inconclusive	The summary conflicts on whether CLAUDE.md still references #1226, so full compliance can't be verified.	Confirm the doc removes the #1226 tracking claim while keeping per-query filtering and non-runtime-enforcement wording.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Concise and specific; it clearly states the tenant-guard docs update.
Out of Scope Changes check	✅ Passed	Changes stay within documentation and its accuracy test; no unrelated edits are evident.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/issue-1355-tenant-guard-ref

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 install timed out. The project may have too many dependencies for the sandbox.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{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 `@app/src/lib/__tests__/docs-accuracy.test.ts`:
- Around line 114-123: Update the documentation accuracy test around the
existing CLAUDE.md assertions to explicitly verify that the stale “tracked in
`#1226`” wording is absent, while preserving the current path and caveat checks.

🪄 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: eef091e5-56a9-44ab-8e79-b7e7a2bd4cce

📥 Commits

Reviewing files that changed from the base of the PR and between 3ead032 and 8598a8e.

📒 Files selected for processing (2)

• CLAUDE.md
• app/src/lib/__tests__/docs-accuracy.test.ts

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Assert that the stale tracking claim stays removed.

The PR objective explicitly removes the “tracked in #1226” wording, but this test only checks that the new path and caveats exist. Reintroducing the stale claim would therefore pass CI.

Proposed assertion

     expect(doc).toMatch(/per query, in the route/);
     expect(doc).toMatch(/not runtime enforcement/);
+    expect(doc).not.toMatch(/tracked in `#1226/i`);

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	const doc = readDoc("CLAUDE.md");
	const guardPath = "app/src/lib/db/__tests__/tenant-scope.test.ts";
	expect(doc).toContain(guardPath);
	expect(existsSync(resolve(REPO_ROOT, guardPath))).toBe(true);
	// The mandate itself is load-bearing and must survive any rewording: the
	// ratchet is a test-time safety net, NOT runtime enforcement. An agent
	// that believes the ORM scopes queries will write an unscoped one.
	expect(doc).toMatch(/per query, in the route/);
	expect(doc).toMatch(/not runtime enforcement/);
	const doc = readDoc("CLAUDE.md");
	const guardPath = "app/src/lib/db/__tests__/tenant-scope.test.ts";
	expect(doc).toContain(guardPath);
	expect(existsSync(resolve(REPO_ROOT, guardPath))).toBe(true);
	// The mandate itself is load-bearing and must survive any rewording: the
	// ratchet is a test-time safety net, NOT runtime enforcement. An agent
	// that believes the ORM scopes queries will write an unscoped one.
	expect(doc).toMatch(/per query, in the route/);
	expect(doc).toMatch(/not runtime enforcement/);
	expect(doc).not.toMatch(/tracked in `#1226/i`);

🤖 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 `@app/src/lib/__tests__/docs-accuracy.test.ts` around lines 114 - 123, Update
the documentation accuracy test around the existing CLAUDE.md assertions to
explicitly verify that the stale “tracked in `#1226`” wording is absent, while
preserving the current path and caveat checks.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud