[andreatnvidia]

Summary

Daily audits can produce repeated one-line fixes to the same document, as in #1049 and #1090. Select a complete, bounded maintenance task instead, and keep isolated cosmetic findings in the backlog.

Related Issue

N/A (maintainer change). Extends the batching introduced in #632 and #787.

Changes

• Group documentation findings by subsystem or API migration across links, docstrings, and source-backed reference updates, including explicit deprecated aliases. Finish the selected scope before proposing a fix.
• Treat confidence as an eligibility requirement, then prioritize impact and completeness. Require concrete breakage or at least two related eligible findings; deferrals do not count as failed attempts.
• Gate docs fix invocations on completed audit scopes. Allow 10 files / 200 changed lines for docs while retaining 3 files / 50 changed lines for code, and align the workflow allowlist with Fern.
• Add workflow tests for scope boundaries, allowed paths, legacy backlog entries, and incomplete scopes.

Testing

• 30 focused workflow and attempted-fix tests passed.
• Changed Python file passed Ruff lint and formatting; workflow YAML, all 17 shell steps, license headers, and diff whitespace checks passed.
• Used the existing repository environment: make install-dev is blocked locally by uv 0.12.9 versus the required >=0.13.4.
• Repository-wide Ruff reports a pre-existing import-order issue in docs/colab_notebooks/8-generating-word-documents.ipynb. The notebook is untouched.
• Full package and E2E suites were not run; this changes CI policy and workflow gates.

Checklist

• Follows commit message conventions
• Commits are signed off (DCO)
• External-contributor issue requirement: N/A
• Architecture docs: N/A (CI policy only)

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; both previous test failures are addressed.

Summary

The PR changes agentic CI to finish bounded maintenance tasks instead of opening isolated cosmetic fixes.

• Docs audits now group related findings into complete maintenance tasks.
• The daily workflow gates docs fixes on completed task scopes.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Restore and initialize state] --> B[Clear cached docs completion]
  B --> C[Refresh recorded PR states]
  C --> D[Audit one bounded docs task]
  D --> E{Completed findings available?}
  E -->|No| F[Keep report and backlog]
  E -->|Yes| G[Recheck every task member]
  G --> H[Apply complete eligible task]
  H --> I[Check paths, file count, and changed lines]
  I --> J[Keep or reject proposed PR]

Loading

_{Reviews (5) · Last reviewed commit: "Merge branch 'main' into andreatnvidia/f..." · Reviewed by Greptile}

[greptile-apps]

Tests fail with macOS Bash

If bash resolves to macOS's default Bash 3.2, all 18 cases in test_suite_scope_limits fail. The test sets DIFF_REF=HEAD, so the extracted fragment reaches mapfile, which Bash 3.2 does not support. With -e, the shell exits before checking the limits. Use a compatible fragment or explicitly provide a newer Bash for these tests.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/data-designer/tests/test_agentic_ci_daily_workflow.py
Line: 73-74

Comment:
**Tests fail with macOS Bash**

If `bash` resolves to macOS's default Bash 3.2, all 18 cases in `test_suite_scope_limits` fail. The test sets `DIFF_REF=HEAD`, so the extracted fragment reaches `mapfile`, which Bash 3.2 does not support. With `-e`, the shell exits before checking the limits. Use a compatible fragment or explicitly provide a newer Bash for these tests.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Tests need an undeclared tool

If a developer has not separately installed jq, four cases in test_fix_phase_requires_completed_docs_scope fail after following the documented setup. The invoked script calls jq and falls back to size=0 when it is missing, but these cases expect size=1. Provide this dependency through the test setup or run these checks in an environment that explicitly installs it.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/data-designer/tests/test_agentic_ci_daily_workflow.py
Line: 101-105

Comment:
**Tests need an undeclared tool**

If a developer has not separately installed `jq`, four cases in `test_fix_phase_requires_completed_docs_scope` fail after following the documented setup. The invoked script calls `jq` and falls back to `size=0` when it is missing, but these cases expect `size=1`. Provide this dependency through the test setup or run these checks in an environment that explicitly installs it.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[nabinchha]

Thanks for putting this together, @andreatnvidia!

Summary

The PR groups related documentation findings into complete maintenance tasks, raises the docs scope limits, and gates fixes on current audit completion. This matches the stated intent, but the new selection rules can prevent PR-state reconciliation and strand retryable findings.

Findings

Warnings — Worth addressing

.agents/recipes/docs-and-references/recipe.md:49 — [P2] Reconcile PR state before excluding recorded-open findings

• What: The audit now excludes findings whose latest recorded attempt is open, before any PR-state reconciliation occurs. _fix-policy.md performs that reconciliation only at the start of the fix phase. After reset_docs_scope clears completion, a backlog containing only these findings produces size=0, so the workflow skips the fix invocation that could update their status.
• Why: If a maintainer closes a docs PR without merging it, the cached attempt remains open and the still-valid findings cannot receive their permitted retry. Repeated runs keep excluding them unless another task independently triggers the fix phase; otherwise backlog expiry can eventually discard them. The old backlog gate admitted these entries and allowed reconciliation to run.
• Suggestion: Reconcile recorded open PRs before the audit chooses its scope, or run reconciliation independently of the completed-scope gate. Add a lifecycle test where a cached open attempt refers to a now-closed PR and verify its findings can be audited and retried without an unrelated task.

What Looks Good

• Cached audit completion is explicitly invalidated, preventing old completion flags from admitting unaudited fixes.
• Workflow tests cover scope boundaries, forbidden paths, malformed backlog data, and corrupt cached state.
• Docs tasks preserve related findings and blockers instead of silently producing partial maintenance PRs.

Residual Risk

All 53 focused workflow and attempted-fix tests passed. The changed Python file passed Ruff lint and formatting; diff whitespace and all daily-workflow shell syntax checks passed. A local reproduction confirmed that a recorded-open finding excluded by the audit yields size=0 and skips reconciliation. Full package suites and live Claude/GitHub workflow execution were not run; task grouping remains prompt-driven.

Verdict

Needs changes — move PR-state reconciliation ahead of audit selection so closed PRs do not strand retryable docs findings.

---

This review was generated by an AI assistant.

[andreatnvidia]

Thanks for the review, @nabinchha! Fixed in 6c33c5a7. Recorded PR states now reconcile before docs audit selection, independently of the completed-scope gate. Added a lifecycle test confirming that a cached-open finding whose PR was closed can be audited and retried without another task triggering reconciliation.

[nabinchha]

Thanks for addressing the review, @andreatnvidia!

Summary

Reviewed the follow-up fix in 6c33c5a7. Recorded open PRs are now reconciled before docs audit selection, independently of the completed-scope gate. Closed PRs can therefore be reconsidered without another maintenance task triggering reconciliation.

Findings

No remaining actionable findings. The previously reported P2 is resolved.

What Looks Good

• Reconciliation runs before audit selection and preserves state if a PR query fails.
• The lifecycle regression test covers a cached-open finding whose PR has closed, through scope reset, reconciliation, and admission after audit completion.

Residual Risk

All 58 focused workflow and attempted-fix tests passed. Ruff lint and formatting passed for the updated Python files. Full package suites and live Claude/GitHub workflow execution were not run.

Verdict

Ship it — the original finding is resolved.

---

This review was generated by an AI assistant using the repository's review-code skill.