Conversational Bleed Guard¶

The Conversational Bleed Guard is Codaris's automated code hygiene and linting defense system. It detects and prevents conversational chat residue, prompt phrasing, author notes, and AI watermark markers from inadvertently entering production code, docstrings, system prompts, or configuration files.

What is Conversational Residue / Chat Bleed?¶

When developing software using LLM assistants, autonomous agents, and multi-turn interactive REPLs, conversational artifacts from the dialogue layer can inadvertently leak into the codebase. This phenomenon is known as conversational residue or chat bleed.

Common examples include: - Conversational turn markers and acknowledgments: "as requested", "per your request", "as discussed", "say so if". - Author/human identifiers and personal notes: "the owner said", "the owner's", "bod:". - Assistant self-attributions and watermarks: "🤖 Generated with...", "robot generated".

Why Chat Bleed is Harmful¶

Codebase Hygiene and Professionalism: Source code should be declarative and self-documenting. Conversational chatter in comments, commit messages, and docstrings degrades software engineering standards.
Privacy and Information Leakage: Residue can leak private developer identities, internal conversational transcripts, organizational usernames, and confidential prompts into public git repositories.
Agent "Mode Bleed" and Token Waste: In autonomous, multi-turn LLM agent architectures (such as Codaris's compiler and Autopilot engines), system prompts and source comments are fed back into language models during downstream turns. Conversational residue in code can mislead downstream models into assuming a conversational rather than deterministic execution mode, leading to token waste, hallucinated instructions, or failed policy enforcement.

The Linter: `scripts/lint_conversational_bleed.py`¶

Codaris enforces a zero-tolerance policy against chat bleed using scripts/lint_conversational_bleed.py. The linter inspects Python and TypeScript/TSX source trees, reporting exact file locations and line numbers for all violations.

Scanned Scope and Targets¶

By default, the linter scans: - backend/app/ (.py) — Backend engine, agents, and API service. - src/ (.py) — Core CLI and shared compiler libraries. - frontend/src/ (.ts, .tsx) — Next.js and React web studio code.

Excluded Directories¶

Standard build caches and environment directories are automatically excluded from scanning: - .git/ - .venv/ and venv/ - __pycache__/ - node_modules/ - dist/, build/, .next/, .turbo/

Allowlisted Paths¶

Vendored reference files, benchmark datasets, and documentation of third-party specifications that intentionally reference author notes are allowlisted: - backend/app/skills/references/

Inline Suppression Markers¶

When a pattern must appear intentionally (for example, in a test asserting that the linter correctly detects a pattern), developers can add an inline suppression comment:

Python: # noqa: bleed, # bleed: ignore, or # conversational-bleed: allow
TypeScript / JavaScript: // noqa: bleed, // bleed: ignore, or // conversational-bleed: allow

Rules and Regex Patterns¶

The linter evaluates code against three primary regex pattern sets:

1. Author and User Chat References¶

re.compile(r"\b(?:the\s+owner|owner's)\b|\bbod:", re.IGNORECASE)

- Rationale: Detects references to specific repository authors or conversational phrases like "the owner said" or dialogue speaker prefixes like "bod:". - Target Replacement: Generic policy or user references (e.g., "the user", "the user's", "Policy:").

2. Conversational Filler Phrasing¶

re.compile(r"\b(?:say\s+so\s+if|as\s+requested|as\s+discussed|per\s+your\s+request)\b", re.IGNORECASE)

- Rationale: Identifies conversational pleasantries and back-and-forth chat dialogue left behind by AI assistants when responding to requests. - Target Replacement: Remove conversational preamble and document the technical invariant directly.

3. Generator Badges and AI Watermarks¶

re.compile(r"(?:🤖\s*Generated\s+with|robot\s+generated)", re.IGNORECASE)

- Rationale: Flags automated bot signatures, emoji watermarks, or machine-generated tags that clutter headers and markdown comments. - Target Replacement: Stripped completely.

CLI Usage¶

The linter is a standalone script that requires only the Python standard library.

# Scan default targets (backend/app, src, frontend/src)
python3 scripts/lint_conversational_bleed.py

# Verbose output showing scanned counts
python3 scripts/lint_conversational_bleed.py -v

# Scan a specific file or directory
python3 scripts/lint_conversational_bleed.py backend/app/engine/autopilot.py

# Automatically fix common patterns in-place
python3 scripts/lint_conversational_bleed.py --fix

Exit Codes¶

Code	Meaning
`0`	Clean — No violations detected across all scanned files.
`1`	Violations detected — One or more files contain conversational bleed patterns.
`2`	Execution error — Invalid arguments or unreadable paths.

Output Example (Failing)¶

backend/app/engine/sample.py:42: error: conversational bleed detected ['the owner\'s' - owner or author chat reference ('the owner', 'owner\'s', 'bod:')]
     42 | # Per the owner's instruction, use 4 threads
frontend/src/components/Header.tsx:18: error: conversational bleed detected ['🤖 Generated with' - generator artifact tag ('🤖 Generated with', 'robot generated')]
     18 | /* 🤖 Generated with Claude Code */

conversational_bleed_linter: FAILED (2 violation(s) across 2 file(s))

Automated Remediation (`--fix`)¶

Passing --fix safely transforms standard violations: - bod: $\to$ Policy: - the owner's $\to$ the user's - the owner $\to$ the user - owner's $\to$ user's - Strips trailing 🤖 Generated with... and robot generated comments.

CI Enforcement¶

Conversational Bleed linting is enforced at multiple stages of the development and landing lifecycle:

flowchart LR
    Dev[Developer Workstation] --> Local[Landing Gate<br/>scripts/test_gate.sh]
    Local --> PR[Pull Request]
    PR --> GHA[GitHub Actions CI<br/>.github/workflows/structure.yml]
    GHA --> Merge[Merge to main]

1. GitHub Actions CI (`structure.yml`)¶

The structure gate workflow runs on every push to main and on all pull requests:

- name: Conversational bleed lint
  run: python3 scripts/lint_conversational_bleed.py

If any violation exists in the pull request diff or modified files, the CI check fails immediately, preventing merge.

2. Local Landing Gate (`scripts/test_gate.sh`)¶

Before landing commits locally, developers run scripts/test_gate.sh. The test gate executes scripts/lint_conversational_bleed.py alongside structure ratchets and unit suites:

./scripts/test_gate.sh

3. Unit Test Verification¶

The linter's own pattern matching and remediation behavior is covered by backend/tests/test_conversational_bleed_linter.py, ensuring: - All regex patterns reliably flag violations across Python and TypeScript comments and strings. - Suppression markers (# noqa: bleed, // noqa: bleed) correctly allow legitimate uses. - Allowlisted directories are respected. - Automatic --fix modifications produce valid, syntactically clean output.