Specs¶
Specs live in the project wiki, not in this repository.
A spec is a point-in-time decision record, written once, true of a moment, read
later for its conclusions. Keeping them here buried the living documentation they
sat beside, so they moved. Contributor guides, engineering standards and testing
conventions stay in docs/, because those change with the code.
| Spec | Title | Status |
|---|---|---|
| 0001 | CockroachDB Errors Migration Specification | IMPLEMENTED |
| 0002 | Deep Cobra Integration for ErrorHandler Specification | IMPLEMENTED |
| 0003 | pkg/chat Open-Source Readiness Specification | IMPLEMENTED |
| 0004 | Generator Pipeline Refactor Specification | IMPLEMENTED |
| 0005 | Assets Resource Leak Fix Specification | IMPLEMENTED |
| 0006 | ChatClient Interface Improvements Specification | IMPLEMENTED |
| 0007 | Chat Provider Deduplication Specification | IMPLEMENTED |
| 0008 | Controllable Interface Narrowing Specification | IMPLEMENTED |
| 0009 | Controller State Race Fix Specification | IMPLEMENTED |
| 0010 | Generate Dry-Run Specification | IMPLEMENTED |
| 0011 | Operational Tooling Specification | IMPLEMENTED |
| 0012 | Opt-in Telemetry Specification | IMPLEMENTED |
| 0013 | Plugin Extension System Specification | REJECTED |
| 0014 | Props Interface Narrowing Specification | IMPLEMENTED |
| 0015 | Root Command Hardening Specification | IMPLEMENTED |
| 0016 | Security Hardening Specification | IMPLEMENTED |
| 0017 | Streaming Chat Responses Specification | IMPLEMENTED |
| 0018 | Test Coverage Gaps Specification | IMPLEMENTED |
| 0019 | Trivial Code Improvements Specification | IMPLEMENTED |
| 0020 | Parallel Tool Execution in ReAct Loop | IMPLEMENTED |
| 0021 | Module and Repository Rename (gtb to go-tool-base) | IMPLEMENTED |
| 0022 | Unified Logger Abstraction Specification | IMPLEMENTED |
| 0023 | Code Quality Hardening Specification | IMPLEMENTED |
| 0024 | Command Middleware System Specification | IMPLEMENTED |
| 0025 | Controls Package Health Check Integration | IMPLEMENTED |
| 0026 | Controls Package Liveness and Readiness Probes | IMPLEMENTED |
| 0027 | Controls Package Self-Healing and Automatic Restarts | IMPLEMENTED |
| 0028 | Documentation Gaps Specification | IMPLEMENTED |
| 0029 | Programmatic Config Access | IMPLEMENTED |
| 0030 | Secure HTTP Client Specification | IMPLEMENTED |
| 0031 | Security & Server Hardening Specification | IMPLEMENTED |
| 0032 | SPEC 8: Structured Output Extension | IMPLEMENTED |
| 0033 | Test Coverage Follow-Up Specification | IMPLEMENTED |
| 0034 | Post-Gemini Implementation Review | IMPLEMENTED |
| 0035 | VCS Repo Thread-Safety Wrapper | IMPLEMENTED |
| 0036 | Chat Conversation Persistence Specification | IMPLEMENTED |
| 0037 | Config Schema Validation Specification | IMPLEMENTED |
| 0038 | Health Check Extensibility Specification | IMPLEMENTED |
| 0039 | HTTP Retry with Exponential Backoff Specification | IMPLEMENTED |
| 0040 | Offline Update Support Specification | IMPLEMENTED |
| 0041 | Output Table Formatter Specification | IMPLEMENTED |
| 0042 | Structured Changelog Diffing Specification | IMPLEMENTED |
| 0043 | Transport Middleware and Logging Specification | IMPLEMENTED |
| 0044 | Godog BDD Strategy: Evaluation & Phased Rollout | IMPLEMENTED |
| 0045 | Extended Release Sources Specification | IMPLEMENTED |
| 0046 | Telemetry Vendor Backends: Datadog & PostHog | IMPLEMENTED |
| 0047 | Embedded Changelog Command | IMPLEMENTED |
| 0048 | Generator Ignore File | IMPLEMENTED |
| 0049 | HTTP Client Middleware Chain | IMPLEMENTED |
| 0050 | Progress & Spinner Output Helpers | IMPLEMENTED |
| 0051 | Workspace / Project Detection | IMPLEMENTED |
| 0052 | Go-Native Changelog Generator Tool | IMPLEMENTED |
| 0053 | Config Environment Variable Prefix | IMPLEMENTED |
| 0054 | Credential Storage Hardening | IMPLEMENTED |
| 0055 | Generator Template Escaping for Non-Code Locations | IMPLEMENTED |
| 0056 | Remote Update Integrity: Checksums + GPG Signatures | IMPLEMENTED |
| 0057 | URL Scheme Validation Specification | IMPLEMENTED |
| 0058 | Test Race Remediation: Restoring t.Parallel() Across the Codebase | IMPLEMENTED |
| 0059 | Chat Provider BaseURL Validation | IMPLEMENTED |
| 0060 | Post-Audit Hardening Bundle | IMPLEMENTED |
| 0061 | Regex Hardening Against ReDoS | IMPLEMENTED |
| 0062 | Snapshot Identifier Validation | IMPLEMENTED |
| 0063 | Telemetry Redaction for Errors and Headers | IMPLEMENTED |
| 0064 | Generic Config Validation Helper Specification | IMPLEMENTED |
| 0065 | Command Composition: setup.Command wrapper with Register | IMPLEMENTED |
| 0066 | OpenTelemetry Observability Specification | IMPLEMENTED |
| 0067 | gtb keys mint: pluggable OpenPGP-from-HSM minter |
IMPLEMENTED |
| 0068 | Functional Options for HTTP and gRPC Server Construction | IMPLEMENTED |
| 0069 | gtb keys wkd: generate the Web Key Directory tree from one or more public keys |
IMPLEMENTED |
| 0070 | gtb sign: detached OpenPGP signing via a pluggable backend |
IMPLEMENTED |
| 0071 | Generator signing support: gtb enable signing, scaffold internal/trustkeys, wire props.Signing |
IMPLEMENTED |
| 0072 | Generator release-signing pipeline: gtb enable signing writes the GoReleaser signs: block |
IMPLEMENTED |
| 0073 | Framework bootstrap vs child PersistentPreRunE: stop downstream hooks silently disabling setup | IMPLEMENTED |
| 0074 | Config hot-reload rework: a container-owned watcher that actually reloads merged config | IMPLEMENTED |
| 0075 | Controls supervisor & lifecycle hardening: idempotent start, real restart semantics, no busy-spin | IMPLEMENTED |
| 0076 | Flag-to-config binding: implement the documented flags precedence layer | IMPLEMENTED |
| 0077 | Generator validation perimeter: close the manifest/signing/AI-tool input gaps | IMPLEMENTED |
| 0078 | Provider-aware repository auth: stop hard-coding GitHub for clone/push credentials | IMPLEMENTED |
| 0079 | Signal-aware execution context: flow Ctrl-C through cmd.Context() and the cleanup path | IMPLEMENTED |
| 0080 | Generator custom/extensible template overlays (local folder or git repo, ref-pinned, manifest-tracked) | IMPLEMENTED |
| 0081 | Generator git initialisation & initial commit (opt-out), optional remote push | IMPLEMENTED |
| 0082 | Refresh the generator's GitLab CI to the phpboyscout/cicd component model | IMPLEMENTED |
| 0083 | Improve the generated project's default README.md | IMPLEMENTED |
| 0084 | Provider-interface adoption: make GTB eat its own dogfood | IMPLEMENTED |
| 0085 | RepoLike role-interface split: break the 23-method kitchen sink into focused roles | IMPLEMENTED |
| 0086 | gtb enable/disable <feature>: manifest-driven feature toggles that survive regeneration |
IMPLEMENTED |
| 0087 | Opt-in ForcedUpdate: three-state self-update gating with a configurable interval | IMPLEMENTED |
| 0088 | Injectable Release Source: a parallel-safe DI seam and reusable test double for self-update | IMPLEMENTED |
| 0089 | Per-command MCP exposure gating (build-time, default-on, explicitly excluded) | IMPLEMENTED |
| 0090 | Coverage gap closure: the remaining sub-90% packages | IMPLEMENTED |
| 0091 | Desktop-gated integration tests: keychain, WKD, live VCS, live chat | APPROVED |
| 0092 | doctor report: redacted support-bundle subcommand |
IMPLEMENTED |
| 0093 | Cross-Provider Fallback & Routing for the Chat Client | IMPLEMENTED |
| 0094 | config edit / config path / config unset: rounding out the config command surface (B3) |
IMPLEMENTED |
| 0095 | Credential Hardening Phase 3: OAuth Display-Once Closeout & SSH-Key Keychain Storage | DRAFT |
| 0096 | GCP KMS & Azure Key Vault signing backends (item C1) | DRAFT |
| 0097 | Linux package signing & packaging: GPG-signed .deb/.rpm via nfpm and signed repository metadata | DRAFT |
| 0098 | Man-page generation from the Cobra command tree (roff via cobra/doc) | IMPLEMENTED |
| 0099 | Resilience Middleware: Server-Side Rate Limiting and Client-Side Circuit Breaking | IMPLEMENTED |
| 0100 | Server-Side Authentication & Authorization Middleware | IMPLEMENTED |
| 0101 | Emergency signing-key rotation (A5) | DRAFT |
| 0102 | Sigstore/Rekor Transparency-Log Signing: additive keyless verification path (Phase 3) | DRAFT |
| 0103 | SLSA Build Provenance: signed in-toto attestation per release artifact | DRAFT |
| 0104 | Update Channels (stable/beta/canary) + Rollback / Pin: opt-in release-channel selection with safe downgrades | DRAFT |
| 0105 | Windows Authenticode code-signing for release binaries | DRAFT |
| 0106 | config coverage hardening via huh accessible-mode form tests | IMPLEMENTED |
| 0107 | Afero view of a vcs/repo worktree (safe billy→afero adapter) | IMPLEMENTED |
| 0108 | Diátaxis-Structured Documentation Generation | IMPLEMENTED |
| 0109 | Tool-calling for ProviderClaudeLocal via a local MCP server | DRAFT |
| 0110 | Standalone signing & verification module (dependency-inverted, reusable by non-GTB projects) | IMPLEMENTED |
| 0111 | Per-provider signing backend modules (signing-aws-kms first; GCP/Azure/Vault to follow) | IMPLEMENTED |
| 0112 | Extract pkg/chat into a standalone module with per-provider SDK modules | IMPLEMENTED |
| 0113 | Multimodal Input for pkg/chat Specification | DRAFT |
| 0114 | Bootstrap auto-initialise and per-command config-check relaxation | IMPLEMENTED |
| 0115 | Typed config section adapters for module extraction | IMPLEMENTED |
| 0116 | Slog-first logging and config adapter seams for module extraction | IMPLEMENTED |
| 0117 | Decouple root pkg/telemetry from pkg/props | IMPLEMENTED |
| 0118 | Complete manifest reconstruction from source | IMPLEMENTED |
| 0119 | Go module extraction playbook & naming convention | APPROVED |
| 0120 | Local development CA with automatic trust-store installation | DRAFT |
| 0121 | Split product analytics from observability in pkg/telemetry | DRAFT |
| 0122 | Extract pkg/controls into a standalone go/controls module | IMPLEMENTED |
| 0123 | Transport stack & foundations: extraction sequence plan | IMPLEMENTED |
| 0124 | Extract the OTel observability group into a standalone go/observability module | IMPLEMENTED |
| 0125 | Extract pkg/tls into a standalone go/tls module | IMPLEMENTED |
| 0126 | Extract the shared transport middleware & resilience into go/transit | IMPLEMENTED |
| 0127 | Extract the transport client factories into go/httpclient and go/grpcclient | IMPLEMENTED |
| 0128 | Remove the extraction facade re-export surfaces (clean break) | IMPLEMENTED |
| 0129 | Extract the transport server stack into go/transport | IMPLEMENTED |
| 0130 | Extract pkg/config into a standalone go/config module | IMPLEMENTED |
| 0131 | Extract pkg/credentials into a standalone go/credentials module | IMPLEMENTED |
| 0132 | Extract pkg/errorhandling into a standalone go/errorhandling module | IMPLEMENTED |
| 0133 | Extract the forge/release layer into go/forge and per-provider modules | IMPLEMENTED |
| 0134 | VCS stack extraction plan: go/repo, go/forge and the forge providers | IN PROGRESS |
| 0135 | Change scope: the configuration chain | IMPLEMENTED |
| 0136 | Migrate GTB to go/config v0.3.x | IMPLEMENTED |
| 0137 | Config write batching and provenance follow-ups | IMPLEMENTED |
| 0138 | Segregated default configuration via props.Assets | IMPLEMENTED |
| 0139 | Delete pkg/forms and rewrite the generator wizards on native huh v2 | IMPLEMENTED |
| 0140 | Extract pkg/workspace and pkg/changelog into standalone leaf modules | IMPLEMENTED |
| 0141 | Extract and redesign pkg/output into the standalone go/output module | IMPLEMENTED |
| 0142 | Forge-aware setup: migrate in-use GitHub auth + SSH operations into the forge providers | IMPLEMENTED |
| 0143 | transport-metrics: a comprehensive Prometheus instrumentation module for the toolkit | DRAFT |
| 0144 | Extract pkg/openapi into the transport-openapi companion module | IMPLEMENTED |
| 0145 | Bootstrap exemptions for auxiliary commands: help, completion, __complete, and the init subtree | IMPLEMENTED |
| 0146 | changelog: parse and generate against real-world release history, not just our own output | IMPLEMENTED |
| 0147 | changelog, yamldoc, workspace: medium/low follow-ups from the architectural review | IMPLEMENTED |
| 0148 | chat-gemini: preserve the typed SDK error chain so cross-provider failover works | IMPLEMENTED |
| 0149 | chat-openai: isolate per-call request params so call kinds stop bleeding state | IMPLEMENTED |
| 0150 | chat family: provider-conformance suite and batched contract fixes | DRAFT |
| 0151 | config: Apply must tolerate absent sibling sources in rebuild | IMPLEMENTED |
| 0152 | config family: medium/low follow-ups from the architectural review | IMPLEMENTED |
| 0153 | Config family version re-pin: bring GTB and all 19 adapters to config head, and stop the drift recurring | IMPLEMENTED |
| 0154 | controls: bound Wait() against context-ignoring StartFuncs | IMPLEMENTED |
| 0155 | controls: medium/low follow-ups from the architectural review | IMPLEMENTED |
| 0156 | Ecosystem fleet maintenance: CI pin coherence, version-coupling mechanism, fan-out discipline, and docs alignment | IMPLEMENTED |
| 0157 | forge-bitbucket: resolve the contradictory downloads self-link contract (auth host-pin vs URL-shape parsing) | IMPLEMENTED |
| 0158 | forge-gitlab: stop forwarding PRIVATE-TOKEN across cross-host redirects (plus a reusable httpclient guard) | IMPLEMENTED |
| 0159 | Forge/repo/setup follow-ups: batched MEDIUM/LOW findings from the architectural review | IMPLEMENTED |
| 0160 | Generator: batched MEDIUM/LOW follow-ups from the architectural review | IMPLEMENTED |
| 0161 | Generator: close the manifest-validation gaps behind CI-executed and code-generating sinks | IMPLEMENTED |
| 0162 | GTB framework core follow-ups: project-local config trust, bootstrap robustness, Props contract, and cleanups | IMPLEMENTED |
| 0163 | Leaf-module contract fixes: errorhandling, credentials, output, authn | IMPLEMENTED |
| 0164 | Observability & telemetry follow-ups: endpoint parsing, fallback options, spill-cap contract | IMPLEMENTED |
| 0165 | TTY-guard the interactive prompts in the root pre-run (telemetry consent, update prompt) | IMPLEMENTED |
| 0166 | redact: scheme-agnostic URL userinfo stripping | IMPLEMENTED |
| 0167 | Self-update downgrade guard: refuse to install an older 'latest' release without --force | IMPLEMENTED |
| 0168 | Setup credential stage: scope the keychain timeout to keychain operations, not the whole interactive flow | IMPLEMENTED |
| 0169 | Transit resilience: half-open trial deadline, stream-trial semantics, and panic-safe done callbacks | IMPLEMENTED |
| 0170 | Transport gateway: apply the middleware chain exactly once on the Register path | IMPLEMENTED |
| 0171 | Transport servers: honour a supplied server TLS config so mTLS is reachable on the managed path | IMPLEMENTED |
| 0172 | Transport stack follow-ups: bind addresses, option safety, retry semantics, and hardening batch | IMPLEMENTED |
| 0173 | version command: degrade gracefully when the release source is unreachable | IMPLEMENTED |
| 0174 | yamldoc: preserve anchors on Set, and make Bytes() validation resolve aliases | IMPLEMENTED |
| 0175 | chat: a stateless one-shot mode so batch work stops paying quadratic history costs | IMPLEMENTED |
| 0176 | Ed25519 + cargo-bin signing / standalone signing tool | DRAFT |
| 0177 | enable/disable signing must respect .gtb/ignore and never clobber a customised .goreleaser.yaml | IMPLEMENTED |
| 0178 | generate docs: frontmatter-first output and non-model authorship | IMPLEMENTED |
| 0179 | Conflict detection for the generate subcommands and non-interactive conflict resolution | IMPLEMENTED |
| 0180 | Keep the project generator's baked-in version pins current via Renovate | IMPLEMENTED |
| 0181 | gtb ignore command group and .gtb/ignore discoverability |
IMPLEMENTED |
| 0182 | External Command Attachment Specification | IMPLEMENTED |
Reports (audits and reviews) moved with them: see the reports index.
Referring to a spec¶
By number and name ("0020, the explainable-cull spec") never by date. The number is a stable handle; a date is not something anyone remembers.
Writing a new one¶
Claim the next number first, then draft against the canonical shape. See the
spec-driven-development skill in the phpboyscout marketplace.