fix(prompt): skip duplicate gentle-ai orchestration blocks from ancestor AGENTS.md (#1722)

[carlosmoradev]

Fixes #1722

Problem

When a ~/AGENTS.md (or any ancestor AGENTS.md) written by gentle-ai exists, a gentle-shell session started in any project under $HOME loads the orchestration rules twice:

1. From gentle-shell's own injected harness (appendSystemPrompt in extensions/gentle-ai.ts containing ## el Gentleman Identity and Harness and # el Gentleman Orchestrator).
2. From ancestor AGENTS.md loaded into Pi's systemPromptOptions.contextFiles (~59 KB containing gentle-ai:orchestrator, gentle-ai:agent-routing, gentle-ai:sdd-orchestrator, gentle-ai:sdd-model-assignments, gentle-ai:engram-protocol, gentle-ai:remote-authorization, and gentle-ai:codegraph-guidance).

This results in:

• ~15,000 extra input tokens on every request, defeating the 8,192 B core prompt budget gentle-pi enforces for its own core.
• Potential prompt divergence between old gentle-ai orchestration rules and gentle-pi's injected canon.

Change

• In lib/child-context-files.ts:
  • Generalize filterManagedBlocks to accept a custom block-removal predicate while preserving byte-for-byte all unmanaged project text, code fences, and structure.
  • Export isAncestorContextFile(filePath, cwd, home) to detect when a context file is $HOME/AGENTS.md, $HOME/CLAUDE.md, or located in an ancestor directory above cwd.
  • Export filterSessionContextFiles(options, cwd, home):
    • For ancestor context files (such as ~/AGENTS.md), strip all duplicate gentle-ai managed blocks (orchestrator, sdd-orchestrator, sdd-model-assignments, agent-routing, engram-protocol, remote-authorization, codegraph-guidance, persona, strict-tdd-mode), while keeping unmanaged user/workspace instructions byte-for-byte. If an ancestor file becomes entirely blank after filtering, omit it from contextFiles to prevent rendering empty instruction blocks.
    • For project-local context files, strip ORCHESTRATOR_ONLY_MANAGED_BLOCKS (orchestrator, sdd-orchestrator, sdd-model-assignments, agent-routing) to prevent stale prompt overrides, while keeping project-local tools and non-orchestrator guidance.
• In extensions/gentle-ai.ts:
  • Wire filterSessionContextFiles into before_agent_start for primary sessions before the orchestrator prompt is appended, ensuring exactly one canonical copy of orchestration rules reaches the model.
• Add comprehensive unit and integration tests:
  • In tests/child-context-files.test.ts: test isAncestorContextFile edge cases (home, parent, cwd, subfolder, unrelated) and filterSessionContextFiles stripping / omitting.
  • In tests/append-system-prompt-route.test.ts: test primary session before_agent_start filtering ancestor context files while appending gentlePrompt.

Verification

• Strict TDD RED: SyntaxError / missing export and assertion failures reproduced.
• Strict TDD GREEN:
  • 22/22 passed in tests/child-context-files.test.ts
  • 5/5 passed in tests/append-system-prompt-route.test.ts
  • 33/33 passed in tests/orchestrator-budget.test.ts
  • 78/78 passed across related prompt and context test suites
• Typecheck: node scripts/check-types.mjs clean (186 recorded diagnostics, 0 regressions).
• Runtime modules check: node scripts/build-runtime-modules.mjs --check matches TypeScript sources.
• Provider contract mirror check: passed.

Summary by CodeRabbit

• Bug Fixes
  • Primary sessions now omit managed orchestration instructions inherited from parent and home-directory context files, reducing repeated instructions in the session context.
  • Context files left empty after filtering are omitted; remaining user-written text is preserved.
  • Project-local context files retain other managed instructions and user-written text.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: cb397e17-d5bb-4ba1-8de4-d0d892dc189c

📥 Commits

Reviewing files that changed from the base of the PR and between 653dad9 and 49a8062.

📒 Files selected for processing (5)

• extensions/gentle-ai.ts
• lib/child-context-files.ts
• odd/tasks/fix-1722-deduplicate-orchestration-rules.md
• tests/append-system-prompt-route.test.ts
• tests/child-context-files.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

Primary sessions now filter system-prompt context files before prompt construction. The filter removes all managed blocks from ancestor context files and orchestrator-only blocks from project-local files. Empty ancestor files are omitted. Named-agent and child sessions skip this filtering.

Changes

Primary-session context filtering

Layer / File(s)	Summary
Context-file filtering behavior lib/child-context-files.ts	Managed-block filtering now accepts a removal predicate. New session filtering removes all managed blocks from ancestor files, removes orchestrator-only blocks from project-local files, and omits ancestor files left empty.
Primary-session wiring and validation extensions/gentle-ai.ts, tests/child-context-files.test.ts, tests/append-system-prompt-route.test.ts, odd/tasks/fix-1722-deduplicate-orchestration-rules.md	The primary-session hook filters context files using the session working directory before prompt construction. Tests cover ancestor detection, block removal, omitted files, and hook integration. The task document records the objective and verification checks.

Priority: ➖ Normal

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

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant gentleAiExtension
  participant filterSessionContextFiles
  participant systemPromptOptions
  participant promptConstruction
  gentleAiExtension->>filterSessionContextFiles: Pass context options and session working directory
  filterSessionContextFiles->>systemPromptOptions: Remove selected managed blocks and omit empty ancestor files
  gentleAiExtension->>promptConstruction: Build prompt with filtered context options

Loading

Suggested reviewers: alan-thegentleman

Merge Risk: ⚪ Minimal · up to 49a80

The identified comments do not require changes before merge; normal checks remain appropriate.

Architecture Summary

Architecture risk: 🟡 Medium · up to 49a80

The change affects 4 systems.

Changed systems: lib, extensions, tests, odd

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — lib (service) was modified; 1 changed file maps to changed impact.
• observed — extensions (service) was modified; 1 changed file maps to changed impact.
• observed — tests (service) was modified; 2 changed files map to changed impact.
• observed — odd (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in extensions/gentle-ai.ts: Imports filterSessionContextFiles for use in primary-session context setup.
• observed — Modified behavior in extensions/gentle-ai.ts: Before prompt construction, primary sessions filter event.systemPromptOptions using ctx.cwd, falling back to process.cwd(). The added comments describe skipping duplicate Gentle AI orchestration blocks from ancestor AGENTS.md files and retaining unmanaged text and non-orchestrator guidance.
• observed — Modified behavior in lib/child-context-files.ts: The module comments now describe filtering ancestor context files for primary sessions, and imports add home-directory and path utilities.
• observed — Modified behavior in lib/child-context-files.ts: The former filterOrchestratorOnlyBlocks implementation is generalized as exported filterManagedBlocks, with a predicate parameter defaulting to the existing orchestrator-only managed-block set.

Reliability and maintainability

• inferred — Risk-relevant change factors for lib: blast_radius_1; direct_dependents_1

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 4 files. (1 skipped: 1…	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 describes the main change: filtering duplicate gentle-ai orchestration blocks from ancestor AGENTS.md files.
Linked Issues check	✅ Passed	[#1722] The primary-session before_agent_start handler filters context files before appending the orchestrator prompt. filterSessionContextFiles removes gentle-ai managed blocks from ancestor file…
Out of Scope Changes check	✅ Passed	The context-file filtering, primary-session hook, and related tests implement [#1722]. Project-local filtering also prevents stale orchestrator instructions from conflicting with the canonical prompt.…

Full details: Docstring Coverage

Explanation

Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 4 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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