t1434: make quality-debt cap and worker pool configurable

[marcusquinn]

Summary

• adds two orchestration config keys with safe defaults that preserve current behavior: orchestration.quality_debt_cap_pct (30) and orchestration.max_workers_cap (8)
• wires new env overrides in config-helper.sh and consumes the keys in pulse-wrapper.sh
• updates pulse pre-fetched state + pulse guidance so quality-debt cap is driven by runtime config instead of a hardcoded 30%

Verification

• bash -n .agents/scripts/pulse-wrapper.sh && bash -n .agents/scripts/config-helper.sh
• python3 -m json.tool .agents/configs/aidevops-config.schema.json >/dev/null
• JSONC_DEFAULTS=.agents/configs/aidevops.defaults.jsonc JSONC_SCHEMA=.agents/configs/aidevops-config.schema.json .agents/scripts/config-helper.sh get orchestration.quality_debt_cap_pct
• JSONC_DEFAULTS=.agents/configs/aidevops.defaults.jsonc JSONC_SCHEMA=.agents/configs/aidevops-config.schema.json .agents/scripts/config-helper.sh get orchestration.max_workers_cap

Summary by CodeRabbit

• New Features
  • Added configurable worker pool size cap (default: 8 workers)
  • Made quality-debt work allocation percentage tunable (default: 30% of worker pool)
  • Environment variable support for both settings enables flexible deployment configuration
  • Quality-debt task scheduling now respects configured allocation limits to prevent overallocation

[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!

[github-actions]

Missing issue link. This PR references issue #4122, but the PR body doesn't contain a closing keyword.

Add Closes #4122 to the PR description so GitHub auto-links and auto-closes the issue on merge.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 448fac0f-c023-4bc2-9ca1-ac25d91dd675

📥 Commits

Reviewing files that changed from the base of the PR and between afd9190 and 8c99c46.

📒 Files selected for processing (5)

• .agents/configs/aidevops-config.schema.json
• .agents/configs/aidevops.defaults.jsonc
• .agents/scripts/commands/pulse.md
• .agents/scripts/config-helper.sh
• .agents/scripts/pulse-wrapper.sh

---

Walkthrough

This PR introduces configurable caps for worker pool sizing and quality-debt allocation in the pulse orchestration system by adding max_workers_cap and quality_debt_cap_pct parameters to the configuration schema, defaults, and pulse-wrapper logic.

Changes

Cohort / File(s)	Summary
Configuration Schema & Defaults .agents/configs/aidevops-config.schema.json, .agents/configs/aidevops.defaults.jsonc	Adds JSON schema definitions and default values for max_workers_cap (default 8) and quality_debt_cap_pct (default 30) under the orchestration configuration block, with corresponding environment variable overrides.
Configuration Mapping .agents/scripts/config-helper.sh	Maps the new configuration parameters to environment variables AIDEVOPS_MAX_WORKERS_CAP and AIDEVOPS_QUALITY_DEBT_CAP_PCT for consumption by orchestration scripts.
Pulse Orchestration Logic .agents/scripts/pulse-wrapper.sh	Reads QUALITY_DEBT_CAP_PCT from configuration with validation/clamping logic, threads it through priority allocation calculations, writes it to allocation state file, and includes it in debug/summary output for visibility.
Pulse Dispatch Rules .agents/scripts/commands/pulse.md	Replaces hard-coded 30% quality-debt concurrency cap with configurable QUALITY_DEBT_CAP_PCT from pre-fetched state, adjusts max calculation formula, and adds conditional logic to skip quality-debt dispatch when capacity is reached.

Sequence Diagram

sequenceDiagram
    participant Config as Configuration Layer
    participant Wrapper as pulse-wrapper.sh
    participant Allocator as Priority Allocator
    participant State as State File
    participant Pulse as pulse.md (Dispatcher)

    Config->>Wrapper: Provide max_workers_cap & quality_debt_cap_pct
    Wrapper->>Wrapper: Validate & clamp QUALITY_DEBT_CAP_PCT (max 100)
    Wrapper->>Allocator: Calculate priority allocations<br/>with capped quality-debt %
    Allocator->>Allocator: Compute max quality-debt slots<br/>= floor(MAX_WORKERS * CAP_PCT / 100)
    Allocator->>State: Write QUALITY_DEBT_CAP_PCT<br/>to allocation state
    State->>Pulse: Provide pre-fetched state with cap value
    Pulse->>Pulse: Check if QUALITY_DEBT_CURRENT<br/>>= QUALITY_DEBT_MAX
    alt Capacity Available
        Pulse->>Pulse: Dispatch quality-debt work
    else Capacity Exceeded
        Pulse->>Pulse: Skip quality-debt dispatch
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• refactor: simplify pulse.md — 622 to 127 lines, trust intelligence over deterministic rules #2465: Modifies pulse.md dispatch logic and quality-debt handling, directly affected by the new configurable cap mechanism introduced here.
• t1429: Separate stats from pulse to prevent rate-limit blocking #4094: Updates pulse-wrapper.sh priority allocation flow, shares orchestration logic patterns with this PR's allocation threading.
• GH#3821: Add daily PR creation cap to prevent CodeRabbit quota exhaustion #3822: Adds configurable caps to pulse-wrapper.sh to control prefetch/dispatch behavior, parallels the capping/validation pattern introduced here.

Suggested labels

refactor

Poem

🎯 Worker caps now dance with grace,
Quality-debt finds its rightful place,
Config flows through script and state,
Orchestration perfected—no more hard-coded fate! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: making quality-debt cap and worker pool configurable, which aligns directly with the PR objectives and all file modifications.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch bugfix/t1434-quality-debt-cap

---

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

[github-actions]

🔍 Code Quality Report

�[0;35m[MONITOR]�[0m Code Review Monitoring Report

�[0;34m[INFO]�[0m Latest Quality Status:
SonarCloud: 0 bugs, 0 vulnerabilities, 397 code smells

�[0;34m[INFO]�[0m Recent monitoring activity:
Wed Mar 11 04:12:48 UTC 2026: Code review monitoring started
Wed Mar 11 04:12:49 UTC 2026: SonarCloud - Bugs: 0, Vulnerabilities: 0, Code Smells: 397

📈 Current Quality Metrics

• BUGS: 0
• CODE SMELLS: 397
• VULNERABILITIES: 0

Generated on: Wed Mar 11 04:12:51 UTC 2026

---

Generated by AI DevOps Framework Code Review Monitoring

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud