feat(miner-plan): add analyze and prepare plan-DAG templates to the shared engine

[GildardoDev]

Summary

Adds a small library of reusable plan TEMPLATES to the shared engine as packages/gittensory-engine/src/plan-templates.ts, so a miner does not have to invent its step graph from scratch for each lifecycle stage. Each template is a pure, deterministic builder that returns raw steps in exactly the shape gittensory_build_plan accepts (rawPlanStepSchema in src/mcp/server.ts), so build_plan can normalize them into a validated DAG. Templates only describe steps and their ordering; they never actuate anything.

Closes #2317

Deliverables

• analyzePlanTemplate(context?) and preparePlanTemplate(context?) returning RawPlanStep[] in the { id, title, actionClass?, dependsOn?, maxAttempts? } shape gittensory_build_plan expects.
  • analyze: feasibility-check and rag-retrieval run independently, then prompt-packet depends on both.
  • prepare: a strict chain of branch-create then coding-agent (a placeholder step, no actuation) then local-test.
• PLAN_TEMPLATE_BUILDERS (a stage to builder registry) and buildPlanTemplate(stage, context?) so callers can enumerate or dispatch by stage.
• The optional context.subject is woven into every step title as a single clean line, whitespace-collapsed and length-bounded so a long subject can never push a title past the schema's 300-character limit.

Notes

• The RawPlanStep type mirrors rawPlanStepSchema so the engine package stays standalone and imports no app code. The unit tests import the ACTUAL rawPlanStepSchema (now exported from src/mcp/server.ts) and assert every template round-trips through it, so the templates can never drift from what gittensory_build_plan accepts.
• The only change outside the engine package is adding export to the existing rawPlanStepSchema so the drift-guard tests can reference the real schema.

Validation

• Unit tests cover: a builder exists for every stage, every template round-trips through the real rawPlanStepSchema, ids are unique with only in-plan acyclic dependencies, output is deterministic, the subject is woven as one clean line (and omitted when absent), an oversized subject stays within the 300-char title limit, and the analyze ordering (prompt-packet depends on both feasibility and retrieval).
• npm run build --workspace @jsonbored/gittensory-engine succeeds; npm run typecheck is clean; the new tests pass under Vitest.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.01%. Comparing base (459df50) to head (5b6ca30).
⚠️ Report is 15 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2718      +/-   ##
==========================================
- Coverage   96.11%   96.01%   -0.11%     
==========================================
  Files         241      245       +4     
  Lines       27057    27316     +259     
  Branches     9834     9922      +88     
==========================================
+ Hits        26006    26227     +221     
- Misses        433      462      +29     
- Partials      618      627       +9     

Files with missing lines	Coverage Δ
packages/gittensory-engine/src/plan-templates.ts	100.00% <100.00%> (ø)
src/mcp/server.ts	95.80% <100.00%> (ø)

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-03 08:18:50 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
The change adds a small, pure plan-template module for the analyze and prepare stages, exports it through the engine barrel, and exposes the existing raw plan-step schema so the new unit tests can validate drift against the real MCP contract. The templates match the described dependency graphs, keep titles within the schema limit, and CI confirms the exported schema/test wiring builds on this commit. I do not see a reachable correctness defect in the visible diff.

Nits — 4 non-blocking

• nit: packages/gittensory-engine/src/plan-templates.ts:36 only type-checks `context.subject` at compile time, so a plain JavaScript caller can still pass a non-string value and hit `.replace`; consider coercing or ignoring non-strings if runtime caller hardening is intentional.
• nit: test/unit/plan-templates.test.ts:12 derives `STAGES` from `PLAN_TEMPLATE_BUILDERS`, so the stage coverage test mostly reasserts the current registry keys; a literal stage list or exported stage tuple would make missing-registry coverage clearer if more stages are added.
• packages/gittensory-engine/src/plan-templates.ts:36 could harden `normalizeSubject` with `const value = typeof subject === "string" ? subject : "";` before whitespace normalization.
• test/unit/plan-templates.test.ts:12 could keep an explicit `const STAGES = ["analyze", "prepare"] satisfies PlanTemplateStage[];` and assert registry keys against it, so the test fails more directly when the stage union and registry drift.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2317
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low 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: 246 registered-repo PR(s), 175 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	GildardoDev; Gittensor profile; 246 PR(s), 0 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: GildardoDev
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 246 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Await review-lane availability.
• Refresh registry data or choose a registered active repo.

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