feat: add repo hygiene proactive agent

[khaliqgant]

Summary

• add a repo-hygiene proactive agent for PR-opened and PR-synchronized events
• diagnose duplicated/dead code, divergent paths, stale skills/rules/docs, and code smells in read-only mode
• post GitHub comments, write Notion journal pages, optionally post Slack summaries, and save memory for future runs

Validation

• npm run typecheck
• npx agentworkforce persona compile ./repo-hygiene/persona.ts

Notes

• First slice is intentionally read-only; fix mode should be added later behind explicit labels such as agent-hygiene:fix.

---

Summary by cubic

Adds a repo-hygiene proactive agent that reviews opened/updated PRs in read-only mode to flag duplicated/dead code, divergent paths, stale docs/skills, and code smells. It posts a concise PR comment, journals the run to Notion with hardened error handling (non-blocking), optionally sends a Slack summary, and saves memory for trend tracking.

• New Features

  • Triggers on GitHub pull_request.opened and pull_request.synchronize.
  • Runs a bounded-diff diagnosis (MAX_DIFF_CHARS).
  • Outputs: PR comment (summary, findings, follow-ups, confidence), Notion journal, optional Slack summary, and workspace memory.
  • Adds persona (persona.ts/persona.json) and handler (agent.ts) with a read-only sandbox.

• Migration

  • Set NOTION_DATABASE_ID (required); optionally SLACK_CHANNEL; tune MAX_DIFF_CHARS.
  • Deploy the persona (launch link in repo-hygiene/README.md).
  • Read-only by design; fix mode will be gated behind labels later.

^{Written for commit 6abf6e0. Summary will update on new commits.}

Review in cubic

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces the Repo Hygiene Agent, a new automated agent that runs on GitHub PR events, performs read-only code-quality analysis via AI, and reports findings to PR comments, Notion journals, workspace memory, and optional Slack channels.

Changes

Repo Hygiene Agent

Layer / File(s)	Summary
Persona & Configuration repo-hygiene/persona.json, repo-hygiene/persona.ts	Agent metadata, GitHub PR triggers (opened/synchronize), Notion and Slack integrations, environment configuration (Notion database ID, Slack channel, max diff size), Codex harness/model and system prompt, workspace-scoped memory, and handler entry point.
Data Contracts & Main Handler repo-hygiene/agent.ts (lines 1–60)	Data shapes for PR reference, findings, and hygiene reports; main exported handler that validates integrations, orchestrates PR reading → diagnosis → PR comment → Notion page → memory save → optional Slack posting.
Diagnosis & Analysis Pipeline repo-hygiene/agent.ts (lines 62–201)	PR metadata and diff extraction, sandbox repository hints collection (file discovery, workflow/doc patterns, ripgrep for keywords), prior memory recall, prompt construction and model execution, and report normalization with fallback error handling.
Output & Persistence repo-hygiene/agent.ts (lines 203–328)	Markdown PR comment rendering with findings and recommendations, Notion journal page creation with dated title and chunked rich-text blocks, workspace memory persistence with run snapshot and tags, and optional Slack summary with severity labels.
Documentation & Registration repo-hygiene/README.md, README.md	Agent README describes read-only workflow, configuration, operational safety boundary, and future phases; top-level README adds repo-hygiene to the agents table with trigger and responsibility descriptions.

Sequence Diagram

sequenceDiagram
  participant GitHub as GitHub (PR Event)
  participant Handler as Repo Hygiene Handler
  participant Analysis as Diagnosis Pipeline
  participant Model as AI Model
  participant PR_Comment as GitHub (Comment)
  participant Notion as Notion (Journal)
  participant Memory as Workspace Memory
  participant Slack as Slack (Optional)
  
  GitHub->>Handler: pull_request.opened/synchronize
  Handler->>Analysis: readPr() + diagnose()
  Analysis->>Model: run(prompt with diff & hints & memory)
  Model-->>Analysis: JSON hygiene report
  Analysis-->>Handler: parsed HygieneReport
  Handler->>PR_Comment: renderPrComment()
  Handler->>Notion: writeNotionJournal()
  Handler->>Memory: rememberRun()
  Handler->>Slack: renderSlackSummary()

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A hygiene agent hops into view,
Sniffing PR diffs and code that's askew,
Comments on GitHub, journals in Notion,
Remembers each finding with digital devotion,
Sandboxed and safe, it leaps without committing—
Clean repos ahead, no commits are permitted! 🎯

🚥 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
Title check	✅ Passed	The title clearly summarizes the main change: adding a new repo hygiene proactive agent to the codebase.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description clearly documents the new repo-hygiene agent, its purpose, triggers, outputs, and intentional read-only scope with future plans.

_{✏️ 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 feat/repo-hygiene-agent

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@repo-hygiene/agent.ts`:
- Around line 52-55: After posting the PR comment with ctx.github.comment, make
the Notion journaling calls best-effort so failures there don't cause the
handler to throw and trigger a retry that would duplicate the comment: wrap
calls to writeNotionJournal and rememberRun in a try/catch (referencing
writeNotionJournal(ctx, pr, event, report, body) and rememberRun(ctx, pr, event,
report, notionPage.url)), catch and log the error (including the error object)
and return/continue without rethrowing; ensure any downstream code can handle a
missing notionPage.url (e.g., treat it as null) so the handler completes
successfully even if Notion fails.
- Around line 98-99: The code treats MAX_DIFF_CHARS as a minimum (Math.max(4000,
diffBudget)) instead of a true maximum, so small configured values are ignored;
change the logic around diffBudget/boundedDiff to respect a user-specified
maximum while still enforcing an upper cap (e.g., 40000). Specifically, update
how diffBudget is applied in boundedDiff (the boundedDiff variable and the
diffBudget derived from input(ctx, 'MAX_DIFF_CHARS')) so that when diffBudget is
finite you slice using Math.min(40000, Math.max(0, diffBudget)) and otherwise
default to 40000.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3b5873f4-ac40-49bf-9d3f-58424d4dd8aa

📥 Commits

Reviewing files that changed from the base of the PR and between 59cd069 and 40fb356.

📒 Files selected for processing (5)

• README.md
• repo-hygiene/README.md
• repo-hygiene/agent.ts
• repo-hygiene/persona.json
• repo-hygiene/persona.ts

[cubic-dev-ai]

2 issues found across 5 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[khaliqgant]

Addressed the two review findings:

• Made Notion/memory journaling best-effort after the GitHub PR comment is posted, so a Notion failure no longer retries and duplicates the PR comment.
• Changed MAX_DIFF_CHARS to act as a real cap, bounded at 40000, instead of a 4000-character minimum.

Validation:

• npm run typecheck
• npx agentworkforce persona compile ./repo-hygiene/persona.ts