feat(engine): add resolvePlanOverallStatus plan DAG helper

[kiannidev]

Summary

• Add resolvePlanOverallStatus(plan) — returns coarse plan status (pending | running | completed | failed | blocked)
• Mirrors hosted planProgress's status field; exports PlanOverallStatus type from the barrel
• Unit tests cover every status branch including cyclic deadlock and dangling dependency ids

Closes #2298

Test plan

• npx vitest run test/unit/plan-overall-status.test.ts --coverage (100% patch via diff-cover)
• npm run build --workspace @jsonbored/gittensory-engine && npm run build:miner

Made with Cursor

[superagent-security]

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

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-05 17:30:56 UTC}

4 files · 1 AI reviewer · no blockers · readiness 62/100 · CI green · clean

⏸️ Suggested Action - Manual Review

Review summary
Adds a small pure helper `resolvePlanOverallStatus` that reduces a plan's step statuses into one coarse enum, mirroring the existing single-purpose predicates (isPlanBlocked, isPlanProgressComplete, etc.) already in the barrel. The precedence logic (completed > failed > running > blocked > pending) is correct and each branch is exercised by a dedicated test, including the cyclic-deadlock and dangling-dependency-id cases traced through `nextReadySteps`'s `statusById.get(dep) ?? "pending"` fallback. The change is additive, exported correctly from `index.ts`, and documented in the README with a one-line summary consistent with the existing catalogue style.

Nits — 6 non-blocking

• packages/gittensory-engine/src/plan-overall-status.ts: `resolvePlanOverallStatus` runs five separate `.filter()` passes over `plan.steps` where a single reduce/loop would do; harmless at the 100-step cap enforced by plan-store validation but worth tightening if this becomes a hot path.
• test/unit/plan-overall-status.test.ts imports `plan-overall-status` and `plan-export` without the `.js` extension used elsewhere in the same files (e.g. `plan-overall-status.ts`'s own `./plan-export.js` import) — confirm this matches the repo's existing test import convention rather than being an inconsistency.
• The PR claims this mirrors hosted `planProgress`'s `status` field but the hosted implementation isn't visible in this diff — worth a reviewer double-check that the precedence order here (completed > failed > running > blocked > pending) actually matches hosted behavior rather than just plausibly matching it.
• The linked issue docs(miner-foundation): gittensory-miner and gittensory-engine README + package docs #2298's other referenced work appears to be miner-foundation docs per the review brief; worth confirming docs(miner-foundation): gittensory-miner and gittensory-engine README + package docs #2298 is actually the right issue for this specific DAG-status helper rather than an incidental link.
• Consider a single-pass tally (e.g. one `reduce` building a status-count object) in plan-overall-status.ts to avoid the five redundant array scans, mirroring `computePlanStatus` in packages/gittensory-miner/lib/plan-store.js which does an equivalent job with fewer passes.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2298
Related work	⚠️ 1 scoped overlap	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	❌ 5/25	Preflight is holding this PR: the review lane is unavailable, so it is not ready for automated review.
Contributor workload	✅ 10/10	Author activity: 1433 registered-repo PR(s), 732 merged, 48 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	kiannidev; Gittensor profile; 1433 PR(s), 48 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: kiannidev
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: TypeScript, MDX, C++, HTML, Rust
• Official Gittensor activity: 1433 PR(s), 48 issue(s).
• Related work: Titles/paths share 8 meaningful terms. (issue #2278, issue #2297)

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Await review-lane availability.
• Refresh registry data or choose a registered active repo.
• Check active issues and PRs before submitting.

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.

_{🟩 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 Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.11%. Comparing base (15ace01) to head (1fa0680).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3567   +/-   ##
=======================================
  Coverage   93.11%   93.11%           
=======================================
  Files         305      306    +1     
  Lines       31532    31547   +15     
  Branches    11509    11513    +4     
=======================================
+ Hits        29361    29376   +15     
  Misses       1517     1517           
  Partials      654      654           

Files with missing lines	Coverage Δ
...kages/gittensory-engine/src/plan-overall-status.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

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