go-tool-base → rust-tool-base parity audit¶

Go Tool Base (GTB) has matured substantially since RTB's baseline — now v0.22.0 (~29 library packages, ~23 commands). This is the material record of a deliberate parity check: review GTB's library + CLI, identify drift and feature gaps in RTB, and decide which become RTB specs.

The audit is paradigm-aware: RTB is not a Go→Rust port (see docs/about/why-rtb.md). Some GTB surface is an intentional non-goal for RTB; the audit distinguishes those from real gaps. It runs in small phases (quota-bounded). Each confirmed gap becomes an APPROVED spec in specs/, with open questions resolved at draft time.

GTB repo (read-only reference): gitlab.com/phpboyscout/go-tool-base.

Status¶

Phase 1 — findings (2026-06-23)¶

Cross-cutting decisions¶

• MCP default polarity stays RTB's safer opt-in/hidden (a command is not an AI-callable tool unless the author chose it) — not GTB's default-exposed.
• enable/disable is one unified command family — feature toggling and per-command MCP exposure (enable/disable mcp <path>) share the surface, mirroring GTB.
• Custom templates are an explicit goal (why-rtb.md had been silent); to be delivered in phases.
• Feature toggling was briefly assessed an intentional non-goal, then reversed to a goal — implemented the RTB way (scaffolder verb rewriting the .features(...) builder marker region + manifest, not a runtime/config toggle, which would clash with the typed-config paradigm).

Orphaned drift closed¶

• rust-tool-base.md:410 documents an update.check_interval that was never implemented — the update-policy spec closes it.

Phase 2 — findings (2026-06-26)¶

Five-agent paradigm-aware sweep across the un-audited surface. Verdicts classify each item REAL GAP (RTB needs it), DRIFT (RTB's equivalent has fallen behind), ALREADY-PRESENT (parity, different shape), or NON-GOAL (intentional — Rust ecosystem or paradigm supersedes). The headline result: most of GTB's growth is server/RPC/PGP surface that is set aside for now — partly a permanent paradigm non-goal, partly deferred pending parity (§C splits the two) — and the real gaps are concentrated in the scaffolder, rtb-ai, and a cluster of RTB's own documented-but-unimplemented contracts that the sweep surfaced incidentally.

A. Real gaps (paradigm-aligned — RTB should close these)¶

B. RTB's own documented-but-unimplemented contracts (surfaced by the sweep)¶

These are not GTB-parity items — they are places where an RTB spec or CLAUDE.md asserts an API that does not exist in the code. Several are security-relevant and one blocks an already-approved spec. Verified by direct grep (2026-06-26).

C. Not-now surface — two tiers¶

GTB surface RTB does not pursue today splits into two materially different categories (decision 2026-06-26, MC). The distinction matters: one tier is permanent, the other is parked and revisited.

C1. Paradigm non-goals (permanent — nothing to "reach parity" on)¶

Rust's ecosystem/idiom already covers these differently or for free; RTB will never grow its own version, so they are not "deferred work."

• Plumbing Rust gives for free: pkg/logger (→ tracing), pkg/utils (→ which/IsTerminal), pkg/tls (→ rustls safe defaults), pkg/osinfo (→ os_info/env::consts; RTB already derives OS/arch in rtb-update/src/asset.rs:55), pkg/workspace (→ Path::ancestors()), internal/circuitbreaker / internal/ratelimit (→ tower/governor if a server ever exists — RTB won't hand-roll them either way).
• Build-time changelog generation: pkg/changelog → release-plz owns it. (The runtime changelog command is a separate real gap — §B.)
• Telemetry vendor backends: PostHog/Datadog → OTLP is the universal path.
• man pages: rtb-docs spec line 430 declares this a non-goal.

C2. Deferred pending parity (parked — revisit once core parity lands)¶

These are real capabilities, not rejected — they hinge on a product decision that is premature until the core gaps (§A) are closed and the feature shape is understood. Treat as intentionally deferred goals, not non-goals. Reassess at the end of the parity programme.

• Server / serve transport story: pkg/http server + SecurityHeadersMiddleware, pkg/grpc, pkg/gateway, pkg/openapi, pkg/authn (server-side API-key / JWT-OIDC-discovery / mTLS verification), pkg/controls (lifecycle + liveness/readiness health). All exist to serve GTB's HTTP/gRPC servers. RTB ships only loopback docs serve today — but why-rtb.md:44 already gestures at integrating axum for a tool serve subcommand. If RTB commits to that serve story, this whole cluster becomes in-scope at once (and pulls in the C1 resilience bits via tower/governor). Deferred until that product call. (Open: does RTB want a first-class serve? — resolve before declaring done.)
• Author-side signing / PGP trust: pkg/signing (KMS/PEM signers), pkg/openpgpkey (WKD), internal/trustkeys, sign/keys commands. RTB today verifies (Ed25519/minisign in rtb-update) and delegates release-artefact signing to release-plz + cargo-dist; the trust anchor is ToolMetadata::update_public_keys (compile-time-embedded), not WKD. But if downstream tools need to sign their own artefacts (not RTB releases), an author-side signing surface could become a goal. Deferred until the downstream need is concrete. (Open: what would a downstream tool actually need to sign, and is cargo-dist insufficient?)

D. ALREADY-PRESENT (parity confirmed, no action)¶

pkg/forms→rtb-tui Wizard; pkg/docs→rtb-docs (modulo the open_url gap); pkg/config→rtb-config (hot-reload at parity); pkg/credentials→ rtb-credentials (RTB has more backends); pkg/vcs→rtb-vcs (RTB's git/ module exceeds GTB — adds blame/walk; GitLab nested groups + all 6 release providers present; GitHub-App auth absent in both — not a gap); pkg/version→VersionInfo; --shorthand for flags; regenerate non-destructive marker-merge (RTB's is arguably stronger).

Cross-impact on the Phase-1 specs (the reason for Phase 2)¶

The user's premise — finish the audit before implementing, because findings may reshape the specs — was correct. Net: no Phase-1 spec is invalidated, but three need adjustment and one needs a sequencing dependency.

1. scaffolder-custom-template-overlays — SEQUENCING DEPENDENCY. The spec names gitlab-ci (.gitlab-ci.yml) as a suppressible component (§6:96) and a protected path (§7:107) — but RTB ships no .gitlab-ci.yml today (gap A1). The CI-scaffolding gap should land before or with this spec, else the suppressible component suppresses nothing. Also: Phase-B git fetch of third-party templates trusts a commit SHA-pin only (no signature/allowlist) — acceptable (cargo's git-dep model), flagged for a future template-provenance decision.
2. scaffolder-feature-toggle — ADJUST. Mechanically compatible (RTB's generic merge_marker_regions handles the new // rtb:features-* region with zero changes; manifest extension is additive). But Feature::Changelog is toggleable with no backing command (§B) — toggling it "on" yields a dead flag. The spec needs a feature-has-backing-command invariant (implement changelog, or mark it backing-less).
3. mcp-command-exposure-gating — MINOR ADJUST. Same root cause: the resolver must not assume every Feature/command pair has a registered command (the changelog flag is the counterexample). Add an explicit rule for flag-without-command.
4. rtb-update-policy-v0.1 — SOUND AS WRITTEN. The sweep validated it: Enabled mode calls Updater::run(), which unconditionally enforces Ed25519 verification (no --no-verify), so auto-update inherits mandatory signature verification — no signing work is gated by the policy. Throttle uses a persisted last-check timestamp, not ratelimit/circuitbreaker (confirmed non-goals). OS/arch asset selection already lives in rtb-update/src/asset.rs:55 (not blocked by osinfo). No change needed.

Manifest-schema collision check: the additive blocks (features:, templates:, a future git:/CI block) are independently keyed — safe so long as each uses #[serde(default, skip_serializing_if)] to preserve deny_unknown_fields round-tripping.

Impact assessment — what "achieving parity" actually costs¶

• The not-now share is large and reassuring — but split it (see §C). Roughly half of GTB's package growth is set aside, in two tiers: a permanent paradigm non-goal tier (§C1 — Rust idiom supersedes; nothing to port) and a deferred-pending-parity tier (§C2 — the server/serve story + author-side signing; parked, not rejected, revisit once §A is closed). Parity does not mean porting either tier now — but the §C2 cluster is a deliberate deferral with open product questions, not a closed door. why-rtb.md's paradigm holds up under audit.
• The real work clusters into three buckets, in recommended order:
• Close RTB's own unimplemented contracts (§B) first — these are security/correctness debt independent of GTB, cheap, and one (browser::open_url) already blocks a shipped spec. compile_bounded
  • browser::open_url are the priorities.
• Scaffolder parity — CI-scaffolding (unblocks the overlay spec) → git-push → command-metadata → keyword rejection. This is where downstream tool authors feel the gap most.
• rtb-ai modernisation — token usage, tool-use loop, fallback, model refresh. Largest single subsystem; can be staged.
• Phase-1 specs are safe to implement after the three adjustments above are folded in. rtb-update-policy remains the cleanest first implementation (no changes needed); but compile_bounded / browser::open_url arguably outrank it as they are security contracts already promised.

Recommended new specs (Phase-2 output, priority order)¶

Drafting status as of 2026-06-26 (✅ = drafted APPROVED).

1. ✅ 2026-06-26-rtb-app-regex-util-compile-bounded (S) — documented security contract.
2. ✅ 2026-06-26-rtb-cli-browser-open-url (S) — scheme allowlist; unblocks rtb-docs.
3. ✅ 2026-06-26-scaffolder-ci-pipeline-scaffolding (L) — unblocks the overlay spec; GitLab (Phase A) + GitHub Actions (Phase B); default-on/cli-preset/full-pipeline.
4. ✅ 2026-06-26-rtb-cli-changelog-subcommand (M) — backs Feature::Changelog.
5. ⬜ rtb-ai-v0.4-usage-accumulation-and-toolloop (L; can split) + model-default refresh — pending user decisions (tool-loop scope, fallback shape).
6. ✅ 2026-06-26-scaffolder-generate-project-git-push (M).
7. ✅ 2026-06-26-scaffolder-command-authoring-parity (S) — command metadata (--short/--aliases/--parent/--args) + Rust-keyword rejection (combined).
8. ✅ 2026-06-26-rtb-error-exit-code-attachment (S). ⬜ rtb-telemetry-spill-and-deletion (M); ⬜ rtb-cli-output-format-breadth (M) — lower priority, not yet drafted.
9. ✅ 2026-06-26-doc-corrections-parity — soften why-rtb.md:44 serve; reconcile CLAUDE.md:244 HTTP-middleware claim.
10. ⬜ (deferred, product call) rtb-ai-agentic-scaffold-verify-loop (L) — only if AI-assisted scaffolding parity is wanted.

Spec-amendments (applied 2026-06-26): ✅ feature-toggle §9 + MCP-gating §10 "feature-has-backing-command" invariant; update-policy needs none.

Implementation progress (dependency-ordered waves)¶

Specs are implemented in waves ordered by dependency, not by drafting order (rationale + full dependency graph: the cross-impact analysis above). rtb-ai is intentionally last — it is an independent island (blocks nothing, blocked by nothing) and the largest single effort.

Carried follow-ups (future-dated / cross-wave)¶

• cli-preset template → run_and_exit: the cli main.rs.j2 still uses run() with an adoption note — it pins a published rust-tool-base, so it switches to run_and_exit only once the release that ships the API is out (next release-plz run after Wave 0). Tracked in 2026-06-26-rtb-error-exit-code-attachment.md.
• update-policy: full Feature::Update gating (App doesn't carry the runtime Features) + the mock-release-server assert_cmd e2e + scaffolder threading + runtime config override. Tracked in 2026-06-23-rtb-update-policy-v0.1.md.
• Local disk pressure: the dev box (and likely the homelab CI runner) sits at ~91% disk; heavy rtb-cli-bin links have hit ENOSPC. Mitigations: clear target/{debug/incremental,doc}, cap CARGO_BUILD_JOBS.

How to resume¶

Analysis is complete; specs are drafted. Implementation is mid-flight — Waves 0–1 are merged to main. Next is Wave 2 (scaffolder polish): it is independent of the rest and needs no design decisions, so it can run straight through (command-authoring-parity + generate-project git push, TDD). After that, follow the wave order above. The three Phase-1 spec adjustments (custom-template CI sequencing, feature-toggle + MCP backing-command invariant) are folded into Waves 3–4. rtb-ai (Wave 5) still needs its open questions resolved before drafting.