feat(miner-plan): soft-claim local-write action-spec builder (#2315)

[nickmopen]

Closes #2315.

A miner that wants to make its claim visible to a fleet (an optional, public "soft claim" comment — "a miner is working on this") needs a spec builder, not an actuator. This follows the existing src/mcp/local-write-tools.ts pattern exactly: gittensory supplies the content of a shell-safe command; the miner's own harness runs it with its own GitHub credentials. This module builds the spec only and never executes anything, so it's contributor-safe under the same LOCAL_WRITE_BOUNDARY reasoning local-write-tools.ts documents.

Deliverables

• src/miner/soft-claim.ts:
  • buildSoftClaimCommentBody({ minerId, claimedAt, expiresAt? }) — a pure, deterministic Markdown body (miner id, claimed-at timestamp, and an expiry note when expiresAt is given).
  • buildSoftClaimSpec(input) — composes that body and delegates to the existing buildPostEligibilityCommentSpec (src/mcp/local-write-tools.ts:54), reusing its single-quote shell-escaping (sq()) rather than duplicating command construction — so output stays deterministic and single-quote-shell-safe.
  • Module docstring cross-references LOCAL_WRITE_BOUNDARY (local-write-tools.ts:8) so the boundary language stays consistent.

Placed in the app src/ (not the isolated gittensory-engine package) precisely because it must reuse buildPostEligibilityCommentSpec from src/mcp/.

Validation

vitest (test/unit/soft-claim.test.ts) — 4/4 pass, tsc --noEmit clean:

• body with/without expiresAt;
• the delegated spec (action/boundary/command/inputs.body);
• shell-injection regression: a single quote in minerId is POSIX-escaped ('\'') so the command stays one safe --body argument (asserted the quotes balance).

Every line + both branches are exercised (100% of the new file), so codecov/patch stays satisfied.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.16%. Comparing base (d6daf68) to head (9065f4a).
⚠️ Report is 11 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2813      +/-   ##
==========================================
+ Coverage   96.13%   96.16%   +0.03%     
==========================================
  Files         248      249       +1     
  Lines       27572    27581       +9     
  Branches    10014    10015       +1     
==========================================
+ Hits        26506    26524      +18     
+ Misses        443      434       -9     
  Partials      623      623              

Files with missing lines	Coverage Δ
src/miner/soft-claim.ts	100.00% <100.00%> (ø)

... and 1 file 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 19:54:40 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
The change adds a small pure soft-claim comment body builder and composes it through the existing local-write comment spec builder, so command construction and boundary metadata stay centralized. The implementation is straightforward, covered for both expiry branches, and does not execute local writes itself. The most notable residual risk is that the Markdown body treats miner-provided text as display-ready while only the shell layer is escaped downstream.

Nits — 4 non-blocking

• src/miner/soft-claim.ts:17 should escape or normalize markdown-sensitive characters in minerId, because a backtick or newline can break the intended inline-code formatting of the public comment.
• test/unit/soft-claim.test.ts:43 verifies shell escaping via substring and quote-count parity, but it does not cover markdown-shaping input such as backticks or newlines in minerId.
• src/miner/soft-claim.ts:17 either constrain minerId to a documented safe identifier shape or add a tiny Markdown display escaping helper before embedding it in backticks.
• test/unit/soft-claim.test.ts:43 add one case for markdown-sensitive minerId input so the body contract is covered separately from shell escaping.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2315
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: 107 registered-repo PR(s), 67 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	nickmopen; Gittensor profile; 107 PR(s), 0 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: nickmopen
• 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: 107 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

[loopover-orb]

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