docs(engine): add TSDoc to goal-model.ts

[davion-knight]

Closes #5819.

Adds documentation to packages/loopover-engine/src/goal-model.ts, which had zero doc comments despite computeLaneFit being referenced by name in the package README.

Comment-only — +38 lines, all TSDoc/comments, zero executable lines changed or removed. No new lines/branches, so it does not add to Codecov's src/** patch-coverage surface; behavior is unchanged.

Deliverable

• Module header — describes the pure lane-fit scorer that MinerGoalSpec path/label preferences compile down to, consumed by miner-goal-lane-fit.ts and opportunity-metadata.ts's computeMetadataLaneFit.
• GoalModelInput — TSDoc on each field.
• computeLaneFit — spells out the exact precedence: blockedPaths/blockedLabels hard-veto → 0; no wantedPaths/preferredLabels configured → neutral 0.5; configured but no match → 0; otherwise matchedDimensions / activeDimensions partial credit (incl. the note that 0.5 is reachable two ways).
• compileGlobMatcher — documents supported glob tokens (*, **, **+/, ?) and unsupported ones (character classes, brace expansion), plus its case-insensitive / backslash-normalized matching.

Validation

• Confirmed comment-only: the diff has zero deletions and no non-comment additions.
• Ran the module through tsx against the current source: the documented rules were verified against actual output (neutral 0.5, veto 0, both-match 1, one-of-two 0.5, no-match 0).
• The module parses and behaves identically; test/goal-model.test.ts imports the built dist/ (comments are stripped at build), so runtime behavior is unaffected.

[superagent-security]

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

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-15 05:45:38 UTC}

1 file · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a pure documentation PR adding TSDoc comments to goal-model.ts's module header, GoalModelInput type, compileGlobMatcher, and computeLaneFit — zero executable lines are added or removed, confirmed by the +38/-0 diff shape touching only comment lines. The documentation is accurate and detailed, correctly describing the veto/neutral/no-match/partial-credit precedence in computeLaneFit and the supported/unsupported glob tokens in compileGlobMatcher, matching the referenced test behavior in the existing code context. No test changes are needed since this doesn't touch executable code, and the PR closes issue #5819 as stated.

Nits — 5 non-blocking

• The computeLaneFit doc comment (goal-model.ts) is quite long for a TSDoc block — consider trimming the parenthetical aside about '0.5 reachable two ways' since it's somewhat redundant with rules 2 and 4 stated just above it.
• The module header doc references `miner-goal-lane-fit.ts` and `opportunity-metadata.ts` by file name rather than using `{@​link}` tags consistently with how `computeLaneFit` is linked elsewhere in the same comment — consider using `{@​link}` for those too if the tooling resolves cross-file links.
• Consider adding a short doc-comment example (e.g., a one-line sample input/output) to computeLaneFit given how much precedence logic it now documents, though this is optional given the exhaustive prose already present.
• If the package README's reference to computeLaneFit predates this doc, consider linking back to this TSDoc from the README or vice versa for discoverability.
• Code changes lack test evidence — Add focused regression tests or explain why existing coverage is sufficient.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#5819
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: 143 registered-repo PR(s), 95 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	davion-knight; Gittensor profile; 143 PR(s), 0 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	ℹ️ None detected	risk: low · value: none · LLM: minor

Linked issue satisfaction

Addressed
The diff adds a module header explaining goal-model.ts's role and its consumers, full TSDoc on GoalModelInput's fields, a precedence-and-scoring TSDoc block on computeLaneFit matching the hard-veto/neutral-default/partial-credit rules described in the issue, and a doc comment on compileGlobMatcher listing supported (*, **, **/, ?) and unsupported (character classes, brace expansion) glob syntax.

Review context

• Author: davion-knight
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 143 PR(s), 0 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://gittensory.aethereal.dev/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.