feat(plugins): pre_commit_gate injection stage; rebind TEA gates to it

[pbean]

Problem

TEA's trace/nfr/review quality gates bind to post_review_result — a stage emitted only inside the orchestrator review loop. Under the default review.trigger="recommended" flow, a dev session that sets followup_review_recommended: false takes _skip_review_and_commit, the loop never runs, post_review_result never fires, the three gate sessions never run, and on_pre_commit fail-opens on the missing artifacts (by design). Net effect: trace_blocking/nfr_blocking/review_blocking = true were completely inert on most stories. Hit live by hey-dad, whose all-blocking gate config never enforced once.

Fix

Framework — new pre_commit_gate injection stage. Fires unconditionally at the top of _commit, i.e. on every path into a commit: review-converged, skip, and the review-budget rescue (that third path already passes through the pre_commit veto today, so gating it too is consistent). Placement is before advance(COMMITTING): the task is still DEV_VERIFY/REVIEW_VERIFY, both of which legally transition to DEFERRED, so a blocking gate workflow whose session doesn't complete defers cleanly — COMMITTING itself has no legal move to DEFERRED. Ordering is inherent: gate sessions write their artifacts, then the existing pre_commit bus hook reads them and enforces. Gate sessions evaluate the exact tree about to commit.

• WORKFLOW_STAGES += pre_commit_gate (plugins/model.py); manifest load-time validation and registry.workflow_stages() pick it up with no registry change.
• engine._commit: if self._run_workflows("pre_commit_gate", task, task.review_cycle): return (note: on the skip path review_cycle is still 0, so gate task_ids there end -0).

TEA — rebind the gates. [workflows.trace|nfr|review] → stage = "pre_commit_gate" (role stays review); td/atdd/automate stay at post_dev_phase. on_pre_commit enforcement is unchanged — it's stage-agnostic; comments/docs updated (plugin-authoring-guide stage reference + injection-stage list, tea-plugin-guide six-step table + blocking section).

Tests

• The hey-dad regression: dev_effect(followup_review=False) + NO review session → the three gate workflows still run, at pre_commit_gate, before story-done (review-skipped present in the journal).
• Enforcement on the skip path: seeded FAIL nfr artifact + nfr_blocking=true → summary.escalated == 1, done == 0, run paused, no story-done.
• Framework: a pre_commit_gate workflow injects before commit on the skip path; a blocking one whose session errors defers legally (deferred == 1).
• Updated the stage-pinned shape test; the ordering tests (test_runs_inject_six_tea_workflows_in_order, sweep-bundle variant) pass unchanged — on the review path the gates' temporal position is identical.

Companion to #44 (livelock fix); the two are independent.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@pbean, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 52 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a2eff4e2-1e25-45d9-a369-bd20a57270fc

📥 Commits

Reviewing files that changed from the base of the PR and between af81b6d and b836418.

📒 Files selected for processing (8)

• docs/plugin-authoring-guide.md
• docs/tea-plugin-guide.md
• src/automator/data/plugins/tea/plugin.toml
• src/automator/data/plugins/tea/tea_plugin.py
• src/automator/engine.py
• src/automator/plugins/model.py
• tests/test_plugin_tea.py
• tests/test_plugin_workflows.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/pre-commit-gate-stage

---

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

[augmentcode]

🤖 Augment PR Summary

Summary: This PR fixes TEA quality gates not running under the default review.trigger="recommended" skip-review path by introducing a new unconditional workflow injection stage.

Changes:

• Adds a new workflow stage pre_commit_gate to the allowed workflow injection stages.
• Runs pre_commit_gate workflows at the top of Engine._commit() (before entering COMMITTING) so blocking workflows can legally defer.
• Rebinds TEA’s gate workflows (trace/nfr/review) from post_review_result to pre_commit_gate, ensuring they execute on every path into commit.
• Updates TEA/plugin authoring docs to describe the new stage and the revised execution order.
• Adds regression and framework tests verifying gates run on the skip-review path and that blocking failures defer/escalate correctly.

Technical Notes: The new stage is stage-agnostic with respect to enforcement: workflows write artifacts first, then existing pre_commit hook logic reads/enforces them; skip-review stories use review_cycle=0 for gate session IDs.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. No suggestions at this time.

Comment augment review to trigger a new review at any time.