tooling: maintainer CLI to expand a loose issue prompt into a gate-ready contributor issue

[JSONbored]

Problem

Contributor issues in this repo must be extremely explicit — real file paths, exact patterns to mirror, explicit anti-patterns, complete test requirements — because the gate only enforces what's written and Gittensor miners run PR work through AI harnesses with no room for inferred intent (see this repo's own .claude/skills/contributor-pipeline-gardening/reference.md, "The gate only enforces what the issue explicitly says"). Authoring an issue to that bar is real, repeated maintainer work: #8082's own 8 sub-issues each required grepping the live codebase for exact precedent files/functions, verifying assumptions against the current checkout rather than memory, and writing a complete, unambiguous heavy-template body before anything could be published. This is a large share of the maintainer's own per-issue time cost today, and it's the actual gap between "loose intent" and "a real, filed, gate-ready issue."

⚠️ Required shape. ORB does not yet have a maintainer-facing GUI to surface this in (the frontends are still in design). Build this as a pure, adapter-agnostic core module, not a script with the logic embedded in it — mirrors scripts/export-d1-core.ts's pure-core/thin-IO split and the calibration module's pure-core/host-adapter split (packages/loopover-engine/src/calibration/signal-tracking.ts + src/review/signal-tracking-wire.ts). A CLI wrapper is the first thin consumer of that core, not the whole feature — so that once an ORB maintainer dashboard exists, an API route can become a second thin consumer of the exact same core with no rewrite. A PR that puts the actual grounding/drafting logic directly inside a scripts/*.ts file, with no separately importable core, does NOT satisfy this issue.

Area

A new pure core module (e.g. packages/loopover-engine/src/issue-drafting/ or src/services/issue-drafting.ts — pick whichever matches the existing convention for cross-consumer pure logic in this repo, same call packages/loopover-engine/src/calibration/signal-tracking.ts's own header comment already made for that module) plus a thin CLI wrapper under scripts/. Not part of the scored gate, not miner-facing, not wired into any CI check.

Proposal

• Input: a loose, one-line-to-short-paragraph description of an intended change — the same shape as prompting an LLM directly, not a fully-specified issue.
• The core module searches the actual current codebase for real precedent (existing files/functions/patterns the new work should cite or mirror) — the same grounding process used by hand for Epic: verifiable pre-merge backtest for ORB/AMS deterministic rules #8082's own sub-issues: exact file paths, exact function signatures, exact existing conventions, verified against the live checkout, never invented or assumed.
• Output: a draft issue body in this repo's existing heavy template (Context / Requirements / Deliverables / Test Coverage Requirements / Expected Outcome / Links & Resources — see .claude/skills/contributor-pipeline-gardening/reference.md). The CLI wrapper writes this to a local file for the maintainer to read, edit, and only then publish. Never auto-published. The maintainer stays the one who sets labels, milestone, contributor-vs-maintainer-only status, and issue relationships — this tool drafts body text only.
• When the core cannot ground part of the loose input in real precedent (no matching existing file/pattern found), the draft must say so explicitly at that point in the body, not silently invent a plausible-sounding but unverified requirement. A maintainer reading the draft needs to know exactly which parts still need a human decision before publishing.
• The core's public entrypoint must not assume a CLI-shaped caller (no process.argv reads, no direct file writes inside the core) — it takes a plain string/options object and returns a plain string (the drafted body) or a structured result, so a future API-route consumer can call it identically to how the CLI wrapper does.

Deliverables

• The pure core module (grounding search + draft assembly), with a public function signature that takes the loose prompt (+ any options, e.g. which directories to search) and returns the drafted body as a string/structured result — no IO beyond read-only codebase search.
• A thin CLI wrapper under scripts/ that reads the prompt (argv or a file), calls the core, and writes the result to a local file — mirrors scripts/export-d1-data.ts's own thin-wrapper role relative to export-d1-core.ts.
• A short internal note on how it performs against a handful of real recent issues (e.g., how close it gets to Epic: verifiable pre-merge backtest for ORB/AMS deterministic rules #8082's own actual sub-issue bodies starting from just a one-line prompt) — this comparison is the real acceptance bar, not a subjective "looks good."

Resources

• .claude/skills/contributor-pipeline-gardening/reference.md (the existing template and the "gate only enforces explicit text" discipline the output must be consistent with)
• Epic: verifiable pre-merge backtest for ORB/AMS deterministic rules #8082 and its sub-issues, as a real worked example of loose-intent → grounded, gate-ready spec
• scripts/export-d1-core.ts / scripts/export-d1-data.ts and packages/loopover-engine/src/calibration/signal-tracking.ts / src/review/signal-tracking-wire.ts (the pure-core/thin-adapter pattern this must follow)

Boundaries

Never auto-publishes an issue. Never sets contributor-vs-maintainer-only status, labels, or milestone on its own — those stay a maintainer decision on every issue, no exceptions, given the documented cost of a wrongly-unlocked issue (see contributor-pipeline-gardening/reference.md's "Never unlock an existing maintainer-only issue" section). Not a substitute for the maintainer's own judgment on scope or safety — a drafting-speed tool only, not a decision-maker. No API route or GUI wiring in this issue — the core must simply not preclude one later.

maintainer-only — internal tooling for issue authoring, not a build task for contributors.

[linear-code]

JSO-5590