refactor(engine): move local-write action specs into the shared engine package

[JSONbored]

Summary

Advances #2337.

src/mcp/local-write-tools.ts had zero root-specific dependencies (only a generic JSON-value type) despite living in root src/ — it builds pure, deterministic LocalWriteActionSpecs with no DB/env/Cloudflare-binding access, so it always belonged in the shared "brain" layer alongside the rest of the portable engine, not root-only.

This is a prerequisite for packages/gittensory-miner's own real driving-loop entrypoint (in progress, separate PR) to construct the exact same open_pr command gittensory's MCP server would return via gittensory_open_pr, with zero network round-trip and zero duplicated/drifting logic — both consumers now import the same functions from one place, resolving the architectural fork between "duplicate the command-construction logic" and "build new MCP-client infrastructure."

• packages/gittensory-engine/src/miner/local-write-tools.ts — the moved implementation, byte-identical logic, JsonValue inlined as a local LocalWriteJsonValue type (no new cross-package type dependency).
• src/mcp/local-write-tools.ts — now a thin re-export, preserving every existing import path (src/mcp/server.ts, src/review/fix-handoff-render.ts, src/miner/soft-claim.ts) unchanged.
• Root gains @jsonbored/gittensory-engine as an explicit dependency (the workspace symlink already resolved it at runtime, but it was never declared in package.json).
• test/unit/local-write-tools.test.ts adds the vi.mock source-redirect this session's own established pattern uses whenever a root test exercises logic that now lives behind a package-specifier re-export — without it, v8 coverage cannot attribute hits back to the engine's .ts source (it resolves through dist/ instead), which would have silently failed codecov/patch on the new engine file despite every test passing.

Scope

• Conventional Commit title (refactor(engine): ...).
• Focused: pure move + re-export + one dependency declaration + the coverage-redirect fix on the existing test.
• Follows CONTRIBUTING.md.
• Linked issue: Advances maintainer: wire the submission-gate trigger into the harness driving loop #2337 (this is a prerequisite for the real entrypoint, not the entrypoint itself).

Validation

• npm run build --workspace @jsonbored/gittensory-engine then npm run typecheck — clean.
• npx vitest run test/unit/local-write-tools.test.ts — 19/19 passing, 100% stmts/branches/funcs/lines on both src/mcp/local-write-tools.ts and packages/gittensory-engine/src/miner/local-write-tools.ts (verified via --coverage.include on both paths — confirmed 0% before adding the vi.mock redirect, 100% after, so this isn't assumed).
• All 3 existing call sites' own test suites still pass unchanged: test/unit/discovery-soft-claim.test.ts (9), test/unit/soft-claim.test.ts (4), test/unit/fix-handoff-render.test.ts (12) — 25/25.
• npm audit --audit-level=moderate — no new external dependencies (workspace-internal only).

Safety

• No secrets/wallets/hotkeys/trust-scores exposed.
• No behavior change — byte-identical logic, only its module location and export path moved.
• Not an API/OpenAPI/MCP protocol change (the MCP tool registrations in src/mcp/server.ts are unchanged; only their import source moved).

[superagent-security]

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

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	8714892	Commit Preview URL Branch Preview URL	Jul 11 2026, 03:37 PM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.21%. Comparing base (01b37d0) to head (8714892).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5117   +/-   ##
=======================================
  Coverage   94.21%   94.21%           
=======================================
  Files         470      470           
  Lines       39743    39743           
  Branches    14506    14506           
=======================================
  Hits        37442    37442           
  Misses       1645     1645           
  Partials      656      656           

Flag	Coverage Δ
shard-1	46.42% <7.89%> (ø)
shard-2	33.86% <7.89%> (ø)
shard-3	32.14% <100.00%> (ø)
shard-4	31.81% <7.89%> (ø)
shard-5	33.53% <7.89%> (ø)
shard-6	44.83% <7.89%> (-0.07%)	⬇️

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

Files with missing lines	Coverage Δ
...s/gittensory-engine/src/miner/local-write-tools.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]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-11 15:40:57 UTC}

5 files · 1 AI reviewer · 2 blockers · readiness 93/100 · CI green · unstable

⏸️ Suggested Action - Manual Review

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.

Review summary
This is a clean move-and-re-export refactor: the local-write-tools implementation is relocated byte-identical into packages/gittensory-engine/src/miner/local-write-tools.ts with JsonValue inlined as a local LocalWriteJsonValue type, root's src/mcp/local-write-tools.ts becomes a thin re-export preserving all existing import paths, the engine barrel and package.json dependency are updated accordingly, and the test file adds a vi.mock source-redirect so coverage attributes to the .ts source instead of dist/. The diff is internally consistent, CI is fully green including codecov/patch, and the test assertions themselves are untouched (same behavior, same coverage), so this is a low-risk, well-scoped mechanical move.

Nits — 5 non-blocking

• The moved file's JSDoc for buildFollowUpIssueSpec still says 'gittensor:bug' as an example label (packages/gittensory-engine/src/miner/local-write-tools.ts) — pre-existing wording carried over verbatim, not introduced by this diff, so purely cosmetic.
• package.json pins @​jsonbored/gittensory-engine as "*" rather than a workspace protocol like "workspace:*"; verify this is the established convention for other intra-monorepo deps in this package.json rather than a copy-paste choice specific to this PR.
• Confirm other root package.json workspace dependencies (if any) use the same "*" version convention so this isn't an outlier.
• Since maintainer: wire the submission-gate trigger into the harness driving loop #2337 anticipates further moves into the engine package, consider whether the vi.mock source-redirect pattern used here is worth extracting into a shared test helper to avoid copy-pasting it per re-export file going forward.
• nit: packages/gittensory-engine/src/miner/local-write-tools.ts:1 and src/mcp/local-write-tools.ts:1 carry a lot of PR-rationale prose in source comments; trim this to the stable module boundary and leave the migration narrative in the PR or issue.

Concerns raised — review before merging

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.

Signal	Result	Evidence
Code review	❌ 2 blockers	1 reviewer
Linked issue	⚠️ Missing	No linked issue or no-issue rationale found.
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 (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 46 registered-repo PR(s), 38 merged, 416 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 46 PR(s), 416 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 46 PR(s), 416 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Explain no-issue PR.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

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.

[BETA] Chat with Gittensory

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

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

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 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