fix(engine): floor percentComplete at 0 so it stays in its documented 0-100 range (#6773)

[shin-core]

Summary

• packages/loopover-engine/src/loop-progress.ts documents percentComplete as "0-100, or null when the budget is unknown", but buildProgressSnapshot clamped only the upper bound (Math.min(100, ...)).
• LoopProgressState.iteration is a plain, unvalidated number, so a negative iteration (from an upstream bookkeeping bug) produced a negative percentComplete — outside the documented range, on a customer-facing progress surface.
• Clamp both ends: Math.max(0, Math.min(100, ...)). No other behavior changes (the null-budget path and the upper clamp are untouched).

Closes #6773

Test plan

• Regression test: a negative iteration (-1 and -100) floors percentComplete to 0.
• The existing upper-bound (100), exact-percent, and null-budget cases still pass unchanged — test/unit/loop-progress.test.ts green (13 tests).
• Coverage on the changed file: 100% statements (16/16), 100% branches (21/21).
• npm run typecheck clean.

[superagent-security]

🚨 Contributor flagged. Click here for more info: Superagent Dashboard

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.63%. Comparing base (61bfd47) to head (84543ed).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6799   +/-   ##
=======================================
  Coverage   93.63%   93.63%           
=======================================
  Files         683      683           
  Lines       68148    68148           
  Branches    18703    18703           
=======================================
  Hits        63812    63812           
  Misses       3350     3350           
  Partials      986      986           

Flag	Coverage Δ
shard-1	43.63% <0.00%> (ø)
shard-2	36.85% <0.00%> (+0.12%)	⬆️
shard-3	32.80% <100.00%> (+0.05%)	⬆️
shard-4	34.67% <0.00%> (+0.46%)	⬆️
shard-5	31.00% <100.00%> (-0.57%)	⬇️
shard-6	45.67% <0.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/loopover-engine/src/loop-progress.ts	100.00% <100.00%> (ø)

[loopover-orb]

Warning

⏸️ LoopOver review result - manual review recommended

_{Review updated: 2026-07-17 07:18:44 UTC}

2 files · 1 AI reviewer · no blockers · CI green · unstable

⏸️ Suggested Action - Manual Review

Review summary
This PR adds a lower-bound clamp (`Math.max(0, ...)`) to `percentComplete` in `buildProgressSnapshot`, fixing a real gap where the previous code only clamped the upper bound with `Math.min(100, ...)` and left negative `iteration` values producing negative percentages. The fix is at the correct layer — the documented contract is on `percentComplete` itself, not on validating `iteration` upstream (which is explicitly typed as a plain unvalidated number) — and the regression test directly exercises the reachable case via the public `LoopProgressState.iteration` field. Scope is tight: one function, one clamp, matching tests, no unrelated changes.

Nits — 2 non-blocking

• The inline comment above the clamp restates the doc comment on `percentComplete` almost verbatim; could be trimmed to just the 'why negative iteration is possible' part.
• Consider also asserting in the test that `iteration: 0, maxIterations: 5` still yields `percentComplete: 0` (already implied by rounding, but would round out the boundary coverage alongside the new negative-floor test).

Flagged checks (non-blocking)

• Contributor trust — Contributor flagged for review

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#6773
Related work	⚠️ 2 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 44 registered-repo PR(s), 25 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	shin-core; Gittensor profile; 44 PR(s), 0 issue(s).
Improvement	✅ Minor	risk: clean · value: minor

Review context

• Author: shin-core
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript, JavaScript, Solidity, Dart, Python, CSS, PHP, Rust
• Official Gittensor activity: 44 PR(s), 0 issue(s).
• Related work: Items reference the same linked issue ams-policy-spec.ts's normalizeNonNegativeInteger doc comment claims a floor it doesn't enforce #6775. (issue #6775, PR #6800)
• Related work: Open PR work references issue ams-policy-spec.ts's normalizeNonNegativeInteger doc comment claims a floor it doesn't enforce #6775. (issue #6775, PR #6800)

Contributor next steps

• Start here: Review top overlaps.
• Then work through the remaining 2 steps in the Signals table above.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

LoopOver approves — the gate is satisfied and CI is green.