feat(miner): design the ContributionProfile schema + caching shape

[luciferlive112116]

Summary

Defines the ContributionProfile shape AMS uses to represent what it has learned about a repo's contribution-eligibility rules, before any extraction (#6796), caching (#6797) or discover wiring (#6798) is built against it. Schema/design only — no extraction logic, no discover changes.

Deliverables (mirroring the miner-goal-spec precedent): a design doc under packages/loopover-miner/docs/, the TypeScript interfaces (.d.ts), a constants + pure-helpers module (.js), and a schema test.

Grounded in #6794, not the abstract

The issue is explicit that this must be "informed by #6794's actual findings, not assumed upfront." I wrote that inventory (#6948), and three of its findings drove decisions the abstract shape would have gotten wrong — each is cited inline in the doc and the .d.ts:

1. Eligibility labels are matchers over name and description, not a fixed name list. rust/deno/kubernetes use their own taxonomies, and rust encodes the "good first issue" meaning only in E-easy's description — a name-only match misses it.
2. Every rule is independently absent, with per-signal confidence — not a single repo-level score. Signal quality varies widely within one repo (rust: great label descriptions, no PR template; react: a PR template, almost no label descriptions). absent is first-class, distinct from unknown.
3. The linked-issue requirement is an optional slot, not a spine field — it is loopover-local (8 CONTRIBUTING.md mentions vs 0 for react/rust/kubernetes), so modelling it as core would encode our own norm as an ecosystem norm.

Plus: assignee-exclusion is modelled as a runtime check (ContributionAssigneeRuntimeCheck), not a cached rule, because #6794 found it isn't documented for most repos and is derivable from the issue's own assignees at query time.

completeness = weakest signal

completeness = weakestConfidence([...spine signals]), not the average — so one strong signal never masks an absent one, and discover treats a partial profile conservatively. The weakestConfidence helper is provided and fully tested.

Caching shape

Names the SQLite store table (miner_contribution_profile) and TTL (CONTRIBUTION_PROFILE_CACHE_TTL_MS = 7 days), mirroring policy-doc-cache.js, so #6797 and this schema agree on them rather than each inventing one.

Validation

• Patch coverage 100% on the codecov-gated .js (packages/loopover-miner/lib/**): 13/13 statements, 4/4 branches, 3/3 functions — measured. The .d.ts is type-only (no runtime) and the doc/test are outside the gate.
• 8/8 tests pass — constants pinned, both helpers covered (including the empty-set and unrecognized-value branches of weakestConfidence, and that emptyContributionProfile's three rules are independent objects), and a doc test asserting every field + the three cited findings are documented (so the schema stays traceable to evidence).
• npm run typecheck — 0 (after the standard engine rebuild; the one pre-existing buildGateDispositions error is on clean main too, from a stale dist, and CI builds fresh). eslint — 0/0 · prettier --check — clean · node --check — ok · check-miner-package — unchanged (same 1 pre-existing local failure, my file adds none) · rebased on latest main.

Scope & safety

• Five files, all new except one line added to the miner package's node --check build list. Wanted paths (packages/, test/).
• No hot files: does not touch src/api/routes.ts, src/mcp/server.ts, the MCP CLI bin, or the pinned stdio-tool count — by design, to avoid the base-conflict/count-pin contention.
• Design only — no extraction, no discover behavior change; the implementation sub-issues build on this. No secrets; no changelog/site//CNAME/lovable changes.

Closes #6795

[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.71%. Comparing base (4966070) to head (bf04bbc).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6970   +/-   ##
=======================================
  Coverage   93.71%   93.71%           
=======================================
  Files         686      687    +1     
  Lines       68392    68404   +12     
  Branches    18730    18730           
=======================================
+ Hits        64093    64105   +12     
  Misses       3302     3302           
  Partials      997      997           

Flag	Coverage Δ
shard-1	43.34% <0.00%> (-0.42%)	⬇️
shard-2	36.92% <0.00%> (-0.01%)	⬇️
shard-3	32.69% <0.00%> (-0.12%)	⬇️
shard-4	34.44% <0.00%> (+0.58%)	⬆️
shard-5	31.63% <100.00%> (-0.50%)	⬇️
shard-6	46.03% <0.00%> (+0.26%)	⬆️

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

Files with missing lines	Coverage Δ
...ackages/loopover-miner/lib/contribution-profile.js	100.00% <100.00%> (ø)

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-17 16:53:16 UTC}

5 files · 1 AI reviewer · no blockers · readiness 98/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a schema-and-docs-only PR that defines the ContributionProfile TypeScript shape, a matching JS constants/helpers module (emptyContributionProfile, weakestConfidence), a design doc, and a schema test — explicitly deferring extraction (#6796), caching (#6797), and discover wiring (#6798) to later issues. The weakestConfidence implementation correctly walks the confidence-order array and picks the highest index (weakest signal), matching its own test cases including the empty-set and unrecognized-value edge cases. It closes the linked issue #6795, is grounded in the cited #6794 findings, and the build script is correctly updated to `node --check` the new lib file.

Nits — 5 non-blocking

• packages/loopover-miner/lib/contribution-profile.d.ts declares `ContributionAssigneeRuntimeCheck` but nothing in this PR consumes it yet — fine for a design-only PR, but worth a one-line note in the doc that it's forward-declared for AMS contribution-profile: implement generic label/docs/agent-file extraction #6796/AMS contribution-profile: wire eligibility filtering into discover #6798.
• test/unit/contribution-profile-schema.test.ts's doc-content assertions (`expect(doc).toContain(...)`) are brittle to doc wording changes; consider testing structural invariants (field list, TTL value) rather than prose substrings where feasible.
• The `contains` matcher in `ContributionLabelMatcher` is documented as case-insensitive but there's no runtime helper enforcing that yet — leave a TODO pointer to AMS contribution-profile: implement generic label/docs/agent-file extraction #6796 so the extractor doesn't silently implement case-sensitive matching.
• When AMS contribution-profile: implement generic label/docs/agent-file extraction #6796 lands, add a helper (e.g. `matchesLabel(matcher, label)`) alongside `weakestConfidence` in contribution-profile.js so the case-insensitive contract is enforced in one place rather than reimplemented per extractor.
• Consider exporting a `CONTRIBUTION_PROFILE_SPINE_FIELDS` constant listing the three signals that feed `completeness`, so AMS contribution-profile: implement generic label/docs/agent-file extraction #6796/AMS contribution-profile: wire eligibility filtering into discover #6798 don't have to hardcode the array shown in the doc's formula.

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	#6795
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	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 172 registered-repo PR(s), 103 merged, 27 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	luciferlive112116; Gittensor profile; 172 PR(s), 27 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The PR delivers exactly the requested schema/design-only deliverables: a markdown doc under packages/loopover-miner/docs/ alongside miner-goal-spec precedent, TypeScript/JSDoc definitions covering eligibility labels, exclusion labels, assignee-exclusion (as a runtime check), PR-body linked-issue requirements, a completeness/confidence indicator, and source provenance, plus a SQLite-mirroring cachi

Review context

• Author: luciferlive112116
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, JavaScript, MDX, Rust, TypeScript
• Official Gittensor activity: 172 PR(s), 27 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

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.