Skip to content

Strangler Stage 4: reach target thresholds #1080

Closed as not planned
Closed as not planned

Description

Strangler Stage 4: reach target thresholds

Labels: code-quality, refactor


Stage 4 -- reach target thresholds

Final stage: bring the entire codebase to industry-standard complexity thresholds. This represents the long-term aspiration.

Threshold changes

Metric Stage 3 Target Violations Files
max-statements 80 50 87 59
max-branches 25 15 92 62
max-complexity 20 10 194 102
max-args 8 5 154 77
max-returns 6 6 0 0
file-length 500 400 ~4 ~4

Notes

  • This is a significant codebase-wide effort (100+ files)
  • Best tackled incrementally as part of feature work (boy-scout rule)
  • max-returns already at target after Stage 3
  • Consider whether max-args=5 is realistic or if 6-7 is a better pragmatic target for a CLI tool
  • Re-evaluate target thresholds based on learnings from Stages 1-3

How to verify

# Update thresholds in pyproject.toml, then:
uv run ruff check src/ tests/

# Update MAX_LINES in .github/workflows/ci.yml, then check:
find src/ -name '*.py' | xargs wc -l | awk '$1 > 400'

Depends on

Activity

  1. github-actions commented on May 1, 2026

    @github-actions

    Triage Panel -- Issue #1080: Strangler Stage 4: reach target thresholds

    Panel composition: DevX UX Expert [mandatory] | Supply Chain Security Expert [mandatory] | Python Architect [conditional: ACTIVE] | OSS Growth Hacker [conditional: inactive] | Doc Writer [conditional: inactive] | APM CEO [arbiter]


    DevX UX Expert

    User surface identified: This issue targets contributor and maintainer DX -- the quality of the internal codebase directly determines how easy it is to understand, extend, and test APM. Tighter complexity thresholds (max-complexity 20->10, max-branches 25->15, max-statements 80->50) make individual functions smaller, more testable, and easier to review in PRs.

    README-anchored mapping: The APM README positions APM as a developer tool; maintainability of the CLI source is a first-class contributor concern. The staged threshold approach (Stages 1-4 in issues #1076-#1080) is well-scoped and traceable.

    Risk flag: max-args=5 is aggressive for a CLI tool where commands often carry many configuration knobs. The issue itself flags this as a calibration question. Recommend resolving the max-args target value (5 vs 6-7) before the threshold is enforced in CI -- otherwise implementors will hit blocking lint failures on legitimate CLI signatures.

    Verdict: Direction accepted. The boy-scout rule strategy is the right implementation pattern for a 100+ file effort.


    Supply Chain Security Expert

    Risk surfaces assessed: No lockfile, marketplace, MCP config, signing, or auth surfaces are touched by this issue. This is purely internal code quality metric tightening.

    Conclusion: No theme/security or theme/governance label warranted. Safe to proceed as pure refactoring. No supply-chain risk surface.


    Python Architect

    Activation trigger: Fast-path -- issue body contains "refactor" keyword and describes codebase-wide restructuring across 100+ files.

    Feasibility assessment:

    1. max-complexity 20->10 (194 violations, 102 files): A 50% reduction is significant. Most violations will require function decomposition or extraction of helper functions. This is tractable with the boy-scout rule but requires sustained discipline across multiple release cycles.

    2. max-branches 25->15 (92 violations, 62 files): Achievable via guard clauses, early returns, and strategy-pattern extractions. Lower effort than complexity.

    3. max-statements 80->50 (87 violations, 59 files): Closely correlated with complexity. Decomposing complex functions typically resolves both metrics together.

    4. max-args 8->5 (154 violations, 77 files): This is the highest violation count and the most architecturally impactful threshold. For a CLI codebase, the recommended pattern before enforcing max-args=5 is to introduce parameter dataclasses or TypedDict config objects for multi-arg functions. Without a documented pattern, implementors will produce inconsistent workarounds. Recommend: establish the parameter-object pattern as a repo convention before Stage 4 CI enforcement of max-args.

    5. Cross-cutting impact: Stage 4 depends on Stage 3 (Strangler Stage 3: broad refactoring pass #1079) being complete. No new module, schema, or primitive is introduced -- this is threshold tightening only. No status/needs-design required at the issue level; the max-args pattern question is an implementation note.

    Recommendation: Accept with priority/low. The architecture of the staged approach is sound. Flag the max-args pattern in the implementing work.


    OSS Growth Hacker

    Inactive reason: Author is a known COLLABORATOR filing a structured technical refactoring task; tone adjustment for new or low-interaction contributors is not warranted.


    Doc Writer

    Inactive reason: Pure code-quality refactoring with no user-facing CLI changes; no new documentation pages in docs/src/content/docs/ are required.


    APM CEO -- Final Arbitration

    Decision: accept

    Issue #1080 is the well-structured fourth stage of a clearly-scoped strangler refactoring plan (#1076 -> #1079 -> #1080). The dependency chain is explicit, the metrics are concrete, and the boy-scout implementation strategy is the right approach for a 100+ file effort. No design ambiguity blocks acceptance.

    Theme: None -- this is pure CLI codebase quality work with no product surface implication. Only area/cli and area/testing apply.

    Label set proposed:

    • area/cli -- primary area (CLI source code quality)
    • area/testing -- complexity reduction directly improves testability
    • type/refactor -- confirmed (already human-applied)
    • status/accepted -- direction is clear
    • priority/low -- long-term aspiration; no sprint deadline

    Milestone: None. This is an open-ended aspiration that proceeds via the boy-scout rule across multiple release cycles. No current milestone candidate is appropriate.

    Note on non-taxonomy labels: The existing code-quality label is not in the APM taxonomy allow-list and cannot be managed by the triage panel. It is preserved as-is and may be a candidate for the maintainer to retire or add to the taxonomy if desired.

    Tone: This is a clear, well-structured issue from an experienced collaborator. The panel endorses the approach and flags only the max-args=5 calibration as an item to resolve during implementation -- either by accepting 5 (and introducing parameter-object conventions) or adjusting the target to 6-7.

    Suggested next action: After Stage 3 (#1079) lands, open a brief discussion on the max-args target value before Stage 4 CI enforcement. Then proceed incrementally with the boy-scout rule.


    Triage status: agentic proposal pending human ratification.
    Silence is approval. Maintainers can:

    • Override any label or milestone above by editing it directly --
      human edits are authoritative and will not be reverted on
      subsequent runs.
    • Re-trigger triage by applying the status/needs-triage label, or
      by removing status/triaged to enroll the issue in the next
      daily sweep.

    Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

    Generated by Triage Panel for issue #1080 · ● 502.1K · ◷

  2. added
    area/cliCLI command surface, flags, help text (cross-cutting).
    area/testingTest infrastructure, fixtures, e2e harness, coverage.
    priority/lowHuman-set low priority; does not imply acceptance, implementation approval or a release target.
    status/acceptedHuman scope approval; verify the issue's approval record and review contact before work.
    status/triagedAutomated advice completed; deduplication only. Not human approval; silence is not approval.
    type/refactorInternal restructure, no behavior change.
    and removed
    status/needs-triageAwaiting a human scope decision, including after automated advice.
    on May 1, 2026
  3. moved this from Todo to In Progress in APM Roadmapon May 18, 2026
  4. 5 remaining items

  5. added 7 commits that reference this issue on May 19, 2026
    00f6cb7
    02ff5c6
    cfcd8d8
    6e70b74
    5c480be
    049206a
    04e27ae
  6. danielmeppiel commented on Sep 12, 2026

    @danielmeppiel
    Collaborator

    At the lead maintainer's direction, the current acceptance of this item is withdrawn as part of APM's roadmap and contribution reset. Previous acceptance labels or comments must not be treated as approval to start or continue substantive implementation for inclusion in APM.

    Thank you for the work and ideas already contributed. Our small maintainer team needs to agree supported scope and review capacity before inviting more implementation. This is not a rejection of the proposal or a judgment of your work, and it does not undo completed work or erase its history.

    Please follow the contribution rules: a responsible human maintainer needs to record the bounded scope, acceptance criteria and review contact on the issue before substantive work resumes. Existing issue discussion, assignments and contributions remain available for that decision. Trivial typo and broken-link corrections retain their standing preapproval.

  7. added
    triage/recommendedAutomated advice completed; not human scope approval.
    and removed
    status/acceptedHuman scope approval; verify the issue's approval record and review contact before work.
    refactorLegacy classification name; prefer type/refactor. Retained for history.
    status/triagedAutomated advice completed; deduplication only. Not human approval; silence is not approval.
    on Sep 12, 2026
  8. danielmeppiel commented on Nov 12, 2026

    @danielmeppiel
    Collaborator

    Closed as not planned (Daniel Meppiel (@danielmeppiel), 2026-11-12). The staged Strangler refactor program is replaced by a shrink-only complexity ratchet, tracked in #1076. New code meets the Stage 2 limits immediately, and existing hotspots are paid down as they are touched.


    Posted with AI assistance on behalf of Daniel Meppiel (@danielmeppiel).

  9. moved this from In Progress to Done in APM Roadmapon Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/cliCLI command surface, flags, help text (cross-cutting).area/testingTest infrastructure, fixtures, e2e harness, coverage.code-qualityCode quality, linting, and complexity guardrailspriority/lowHuman-set low priority; does not imply acceptance, implementation approval or a release target.triage/recommendedAutomated advice completed; not human scope approval.type/refactorInternal restructure, no behavior change.

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions