[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 remove managed instructions from ancestor and home-directory context files, and orchestrator-only instructions from project-local context files.
  • Ancestor context files that are empty after filtering are omitted. Files with remaining content keep their text and paths.
  • Project-local files retain other managed instructions and user-written text.
  • Named-agent and child sessions continue to skip this filtering.

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Repository UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 33755196-033b-49c8-8b5b-11eee1687bee

Commits

Reviewing files that changed from the base of the PR and between 06d386d and 4c40a71.

Files selected for processing: 1

• extensions/gentle-ai.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

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: Low · up to 4c40a

A malformed ancestor context file can retain duplicate orchestration rules, but this is a narrow follow-up risk and does not block normal sessions from completing.

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: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly describes the main change: preventing duplicate gentle-ai orchestration blocks in ancestor AGENTS.md files. It is concise and related to the changeset.
Linked Issues check		[#1722] The PR filters all listed gentle-ai managed blocks from ancestor context files before the primary-session prompt is built. It omits ancestor files that become blank and preserves unmanaged c…
Out of Scope Changes check		The changes stay within prompt deduplication for [#1722]. The parser generalization supports selective block removal. Project-local orchestrator filtering prevents stale orchestration rules from confl…
Docstring Coverage		Docstring coverage is inconclusive: files from earlier reviews still need to be rechecked within the check's analysis limits. Not blocking.

Full details: Linked Issues check

Explanation

[#1722] The PR filters all listed gentle-ai managed blocks from ancestor context files before the primary-session prompt is built. It omits ancestor files that become blank and preserves unmanaged content. The primary before_agent_start flow runs the filter before appending the canonical orchestrator prompt. Tests cover ancestor detection, filtering, preservation, omission, and prompt routing.

Full details: Out of Scope Changes check

Explanation

The changes stay within prompt deduplication for [#1722]. The parser generalization supports selective block removal. Project-local orchestrator filtering prevents stale orchestration rules from conflicting with the canonical prompt. Tests and task documentation support the implementation. No unrelated change is evident.

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

[github-actions]

The linked issue #1722 was closed after more than 21 days without activity, so this pull request is being closed with it.

Reopen it together with the issue if the work should continue.